@spec build(String.t(), String.t()) :: {:ok, String.t()} | {:error, String.t()}

Builds a category purpose code from category and purpose components.

Examples

iex> QRNBU.Validators.CategoryPurpose.build("SALA", "REGU")
{:ok, "SALA/REGU"}

iex> QRNBU.Validators.CategoryPurpose.build("sala", "regu")
{:ok, "SALA/REGU"}

iex> QRNBU.Validators.CategoryPurpose.build("ABC", "REGU")
{:error, "Category must be exactly 4 characters"}

@spec common_categories() :: map()

Returns common category codes with descriptions.

Examples

iex> QRNBU.Validators.CategoryPurpose.common_categories()
%{
  "SALA" => "Salary payment",
  "PENS" => "Pension payment",
  ...
}

@spec common_purposes() :: map()

Returns common purpose codes with descriptions.

Examples

iex> QRNBU.Validators.CategoryPurpose.common_purposes()
%{
  "REGU" => "Regular payment",
  "PROM" => "Promotional payment",
  ...
}

@spec parse(String.t()) :: {:ok, map()} | {:error, String.t()}

Parses a category purpose code into its components.

Returns {:ok, %{category: String.t(), purpose: String.t()}} or {:error, reason}.

Examples

iex> QRNBU.Validators.CategoryPurpose.parse("SALA/REGU")
{:ok, %{category: "SALA", purpose: "REGU"}}

@spec suggest(String.t()) :: {:ok, String.t()} | {:error, :no_match}

Suggests a category purpose code based on keywords in the payment purpose text.

Returns {:ok, suggested_code} or {:error, :no_match}.

Examples

iex> QRNBU.Validators.CategoryPurpose.suggest("Salary payment for December")
{:ok, "SALA/REGU"}

iex> QRNBU.Validators.CategoryPurpose.suggest("Pension fund contribution")
{:ok, "PENS/REGU"}

iex> QRNBU.Validators.CategoryPurpose.suggest("Random payment")
{:error, :no_match}

@spec validate(
  String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, String.t()}

Validates an ISO 20022 category purpose code.

The code is automatically normalized (trimmed and uppercased) before validation.

Options

• :encoding - Character encoding (ignored for category purpose, ASCII only)

Returns {:ok, normalized_code} or {:error, reason}.

@spec validate_with_description(String.t()) ::
  {:ok, String.t(), String.t()} | {:error, String.t()}

Validates and provides description for a category purpose code.

Returns {:ok, code, description} or {:error, reason}.

Examples

iex> QRNBU.Validators.CategoryPurpose.validate_with_description("SALA/REGU")
{:ok, "SALA/REGU", "Salary payment - Regular payment"}