Search documentation of phoenix_kit

# PhoenixKit.ReferralCodes (phoenix_kit v1.6.19)

View Source

Referral code system for PhoenixKit - complete management in a single module.

This module provides both the Ecto schema definition and business logic for managing referral codes. It includes code creation, validation, usage tracking, and system configuration.

## Schema Fields

- `code`: The referral code string (unique, required)
- `description`: Human-readable description of the code
- `status`: Boolean indicating if the code is active
- `number_of_uses`: Current number of times the code has been used
- `max_uses`: Maximum number of times the code can be used
- `created_by`: User ID of the admin who created the code
- `beneficiary`: User ID who benefits when this code is used (optional)
- `date_created`: When the code was created
- `expiration_date`: When the code expires

## Core Functions

### Code Management

- `list_codes/0` - Get all referral codes
- `get_code!/1` - Get a referral code by ID (raises if not found)
- `get_code_by_string/1` - Get a referral code by its string value
- `create_code/1` - Create a new referral code
- `update_code/2` - Update an existing referral code
- `delete_code/1` - Delete a referral code
- `generate_random_code/0` - Generate a random code string

### Usage Tracking

- `use_code/2` - Record usage of a referral code by a user
- `get_usage_stats/1` - Get usage statistics for a code
- `list_usage_for_code/1` - Get all usage records for a code
- `user_used_code?/2` - Check if user has used a specific code

### System Settings

- `enabled?/0` - Check if referral codes system is enabled
- `required?/0` - Check if referral codes are required for registration
- `enable_system/0` - Enable the referral codes system
- `disable_system/0` - Disable the referral codes system
- `set_required/1` - Set whether referral codes are required

## Usage Examples

    # Check if system is enabled
    if PhoenixKit.ReferralCodes.enabled?() do
      # System is active
    end

    # Create a new referral code
    {:ok, code} = PhoenixKit.ReferralCodes.create_code(%{
      code: "WELCOME2024",
      description: "Welcome promotion",
      max_uses: 100,
      created_by: admin_user.id,
      expiration_date: ~U[2024-12-31 23:59:59.000000Z]
    })

    # Use a referral code during registration
    case PhoenixKit.ReferralCodes.use_code("WELCOME2024", user.id) do
      {:ok, usage} -> # Code used successfully
      {:error, reason} -> # Handle error
    end

# Summary

## Functions

change_code(referral_code, attrs \\ %{})

Returns an `%Ecto.Changeset{}` for tracking referral code changes.

changeset(referral_code, attrs)

Creates a changeset for referral code creation and updates.

count_user_codes(user_id)

Counts the total number of referral codes created by a user.

create_code(attrs \\ %{})

Creates a referral code.

delete_code(referral_code)

Deletes a referral code.

disable_system()

Disables the referral codes system.

enable_system()

Enables the referral codes system.

enabled?()

Checks if the referral codes system is enabled.

expired?(code)

Checks if a referral code has expired.

generate_random_code()

Generates a random 5-character alphanumeric referral code.

get_code!(id)

Gets a single referral code by ID.

get_code_by_string(code_string)

Gets a single referral code by its string value.

get_config()

Gets the current referral codes system configuration.

get_max_codes_per_user()

Gets the maximum number of referral codes a single user can create.

get_max_uses_per_code()

Gets the maximum number of uses allowed per referral code.

get_system_stats()

Gets summary statistics for the referral codes system.

get_usage_stats(code_id)

Gets usage statistics for a referral code.

list_codes()

Returns the list of referral codes ordered by creation date.

list_usage_for_code(code_id)

Lists all usage records for a referral code.

list_valid_codes()

Gets codes that are currently valid for use.

required?()

Checks if referral codes are required for user registration.

set_max_codes_per_user(max_codes)

Sets the maximum number of referral codes a single user can create.

set_max_uses_per_code(max_uses)

Sets the maximum number of uses allowed per referral code.

set_required(required)

Sets whether referral codes are required for registration.

update_code(referral_code, attrs)

Updates a referral code.

usage_limit_reached?(code)

Checks if a referral code has reached its usage limit.

use_code(code_string, user_id)

Records usage of a referral code by a user.

user_used_code?(user_id, code_id)

Checks if a user has already used a specific referral code.

valid_for_use?(code)

Checks if a referral code is currently valid for use.

validate_user_code_limit(user_id)

Validates that a user hasn't exceeded their referral code creation limit.

# Functions

# change_code(referral_code, attrs \\ %{})

Returns an `%Ecto.Changeset{}` for tracking referral code changes.

## Examples

    iex> PhoenixKit.ReferralCodes.change_code(code)
    %Ecto.Changeset{data: %PhoenixKit.ReferralCodes{}}

# changeset(referral_code, attrs)

Creates a changeset for referral code creation and updates.

Validates that code is unique and all required fields are present. Automatically sets date_created on new records.

# count_user_codes(user_id)

Counts the total number of referral codes created by a user.

## Examples

    iex> PhoenixKit.ReferralCodes.count_user_codes(1)
    5

# create_code(attrs \\ %{})

Creates a referral code.

## Examples

    iex> PhoenixKit.ReferralCodes.create_code(%{code: "TEST123", max_uses: 10})
    {:ok, %PhoenixKit.ReferralCodes{}}

    iex> PhoenixKit.ReferralCodes.create_code(%{code: ""})
    {:error, %Ecto.Changeset{}}

# delete_code(referral_code)

Deletes a referral code.

## Examples

    iex> PhoenixKit.ReferralCodes.delete_code(code)
    {:ok, %PhoenixKit.ReferralCodes{}}

    iex> PhoenixKit.ReferralCodes.delete_code(code)
    {:error, %Ecto.Changeset{}}

# disable_system()

Disables the referral codes system.

Sets the "referral_codes_enabled" setting to false.

## Examples

    iex> PhoenixKit.ReferralCodes.disable_system()
    {:ok, %Setting{}}

# enable_system()

Enables the referral codes system.

Sets the "referral_codes_enabled" setting to true.

## Examples

    iex> PhoenixKit.ReferralCodes.enable_system()
    {:ok, %Setting{}}

# enabled?()

Checks if the referral codes system is enabled.

Returns true if the "referral_codes_enabled" setting is true.

## Examples

    iex> PhoenixKit.ReferralCodes.enabled?()
    false

# expired?(code)

Checks if a referral code has expired.

## Examples

    iex> PhoenixKit.ReferralCodes.expired?(code)
    false

# generate_random_code()

Generates a random 5-character alphanumeric referral code.

Returns a string with uppercase letters and numbers, excluding potentially confusing characters (0, O, I, 1).

## Examples

    iex> PhoenixKit.ReferralCodes.generate_random_code()
    "A7B2K"

# get_code!(id)

Gets a single referral code by ID.

Raises `Ecto.NoResultsError` if the code does not exist.

## Examples

    iex> PhoenixKit.ReferralCodes.get_code!(123)
    %PhoenixKit.ReferralCodes{}

    iex> PhoenixKit.ReferralCodes.get_code!(456)
    ** (Ecto.NoResultsError)

# get_code_by_string(code_string)

Gets a single referral code by its string value.

Returns the referral code if found, nil otherwise.

## Examples

    iex> PhoenixKit.ReferralCodes.get_code_by_string("WELCOME2024")
    %PhoenixKit.ReferralCodes{}

    iex> PhoenixKit.ReferralCodes.get_code_by_string("INVALID")
    nil

# get_config()

Gets the current referral codes system configuration.

Returns a map with the current settings.

## Examples

    iex> PhoenixKit.ReferralCodes.get_config()
    %{enabled: false, required: false}

# get_max_codes_per_user()

Gets the maximum number of referral codes a single user can create.

Returns the system-wide limit for referral code creation per user. Defaults to 10 if not set.

## Examples

    iex> PhoenixKit.ReferralCodes.get_max_codes_per_user()
    10

# get_max_uses_per_code()

Gets the maximum number of uses allowed per referral code.

Returns the system-wide limit for how many times a single referral code can be used. Defaults to 100 if not set.

## Examples

    iex> PhoenixKit.ReferralCodes.get_max_uses_per_code()
    100

# get_system_stats()

Gets summary statistics for the referral codes system.

Returns counts and metrics useful for admin dashboards.

## Examples

    iex> PhoenixKit.ReferralCodes.get_system_stats()
    %{total_codes: 10, active_codes: 8, total_usage: 150, codes_with_usage: 6}

# get_usage_stats(code_id)

Gets usage statistics for a referral code.

## Examples

    iex> PhoenixKit.ReferralCodes.get_usage_stats(code_id)
    %{total_uses: 5, unique_users: 3, last_used: ~U[...], recent_users: [...]}

# list_codes()

Returns the list of referral codes ordered by creation date.

## Examples

    iex> PhoenixKit.ReferralCodes.list_codes()
    [%PhoenixKit.ReferralCodes{}, ...]

# list_usage_for_code(code_id)

Lists all usage records for a referral code.

## Examples

    iex> PhoenixKit.ReferralCodes.list_usage_for_code(code_id)
    [%PhoenixKit.ReferralCodeUsage{}, ...]

# list_valid_codes()

Gets codes that are currently valid for use.

Returns codes that are active, not expired, and haven't reached usage limits.

## Examples

    iex> PhoenixKit.ReferralCodes.list_valid_codes()
    [%PhoenixKit.ReferralCodes{}, ...]

# required?()

Checks if referral codes are required for user registration.

Returns true if the "referral_codes_required" setting is true.

## Examples

    iex> PhoenixKit.ReferralCodes.required?()
    false

# set_max_codes_per_user(max_codes)

Sets the maximum number of referral codes a single user can create.

Updates the system-wide limit for referral code creation per user.

## Examples

    iex> PhoenixKit.ReferralCodes.set_max_codes_per_user(5)
    {:ok, %Setting{}}

# set_max_uses_per_code(max_uses)

Sets the maximum number of uses allowed per referral code.

Updates the system-wide limit for referral code usage.

## Examples

    iex> PhoenixKit.ReferralCodes.set_max_uses_per_code(50)
    {:ok, %Setting{}}

# set_required(required)

Sets whether referral codes are required for registration.

## Examples

    iex> PhoenixKit.ReferralCodes.set_required(true)
    {:ok, %Setting{}}

    iex> PhoenixKit.ReferralCodes.set_required(false)
    {:ok, %Setting{}}

# update_code(referral_code, attrs)

Updates a referral code.

## Examples

    iex> PhoenixKit.ReferralCodes.update_code(code, %{description: "Updated"})
    {:ok, %PhoenixKit.ReferralCodes{}}

    iex> PhoenixKit.ReferralCodes.update_code(code, %{code: ""})
    {:error, %Ecto.Changeset{}}

# usage_limit_reached?(code)

Checks if a referral code has reached its usage limit.

## Examples

    iex> PhoenixKit.ReferralCodes.usage_limit_reached?(code)
    false

# use_code(code_string, user_id)

Records usage of a referral code by a user.

Validates that the code is valid for use before recording the usage. Updates the code's number_of_uses counter.

## Examples

    iex> PhoenixKit.ReferralCodes.use_code("WELCOME2024", user_id)
    {:ok, %PhoenixKit.ReferralCodeUsage{}}

    iex> PhoenixKit.ReferralCodes.use_code("EXPIRED", user_id)
    {:error, :code_not_found}

# user_used_code?(user_id, code_id)

Checks if a user has already used a specific referral code.

## Examples

    iex> PhoenixKit.ReferralCodes.user_used_code?(user_id, code_id)
    false

# valid_for_use?(code)

Checks if a referral code is currently valid for use.

A code is valid if:

- It exists and is active (status: true)
- It has not exceeded its maximum uses
- It has not expired

## Examples

    iex> PhoenixKit.ReferralCodes.valid_for_use?(code)
    true

# validate_user_code_limit(user_id)

Validates that a user hasn't exceeded their referral code creation limit.

Checks the current number of codes created by the user against the system limit. Returns `{:ok, :valid}` if within limits, `{:error, reason}` if limit exceeded.

## Examples

    iex> PhoenixKit.ReferralCodes.validate_user_code_limit(1)
    {:ok, :valid}

    iex> PhoenixKit.ReferralCodes.validate_user_code_limit(1)
    {:error, "You have reached the maximum limit of 10 referral codes"}