@artu-ai/shared

@artu-ai/shared

Shared validation schemas, types, enums, scopes, and validators for the Artu Compliance API.

This package is the type/contract layer that powers @artu-ai/compliance-sdk. Most users get it automatically as a dependency of the SDK, but you can also depend on it directly to share the same Zod schemas, enums, and validators in your own code (e.g. validating input before a call, or building UI from the schemas).

Installation

npm install @artu-ai/shared

It is installed automatically when you install @artu-ai/compliance-sdk.

Scopes

Scopes are the core data-partitioning concept — a jurisdiction + regulated-activity combination (e.g. "MX:AV:AVI" = Mexico · Actividad Vulnerable · Activos Virtuales).

type Scope = MexScope | "base";
type MexScope = "MX" | "MX:AV:AVI" | "MX:AV:JYS" | "MX:AV:MJR" | "MX:AV:TSC" | "MX:CNBV:TRANSMISOR";

The Scopes utility provides validation, labels, and conversions:

import { Scopes, MexScopes } from "@artu-ai/shared/scopes";

Scopes.codes;                    // ["base", "MX", "MX:AV:AVI", ...]
Scopes.is("MX:AV:AVI");          // true (type guard)
Scopes.schema();                 // Zod schema
Scopes.getLabel("MX:AV:AVI");    // "Mexico - Activos Virtuales"
Scopes.options;                  // [{ value, label }, ...] for UI dropdowns

// URL slug conversion
Scopes.toUrlSlug("MX:AV:AVI");   // "mx-av-avi"
Scopes.fromUrlSlug("mx-av-avi"); // "MX:AV:AVI"

// Data-path building for nested scope data
Scopes.path("MX:AV:AVI", "operationType");
// "scopeData.MX.actividadVulnerable.AVI.operationType"

Data is stored hierarchically under scopeData, so a record can carry multiple scopes:

{
  name: "Juan García",
  scopeData: {
    MX: {
      rfc: "GAJL850101ABC",
      actividadVulnerable: { AVI: { operationType: "compra" } },
      cnbv: { TRANSMISOR: { /* ... */ } },
    },
  },
}

Schemas

Zod schemas for every entity, organized in composable layers (base → jurisdiction → activity):

import { clientSchema, transactionSchema } from "@artu-ai/shared/schemas";

const result = clientSchema.safeParse(input);
if (!result.success) console.error(result.error.issues);

Scope-specific request/response types are exposed through the SDK's scoped entry points (e.g. @artu-ai/compliance-sdk/mx/av/avi), which is the recommended way to consume them.

Enums

Every enum ships with a consistent set of utilities (map, codes, options, schema, type guard):

import { ClientType, Currency } from "@artu-ai/shared/enums";

ClientType.Individual;            // "individual"
ClientType;                       // { Individual, Company, Trust }

// Scope-specific enums
import { TipoOperacion } from "@artu-ai/shared/enums/mx/av/avi";

Validators

Validators for Mexican identifiers, each exposing a Zod schema:

import { Curp, Rfc, Clabe } from "@artu-ai/shared/validators";

Rfc.schema();             // Zod schema for RFC (tax ID)
Curp.schema().optional(); // CURP (personal ID)
Clabe.schema();           // CLABE (bank account)

Registry

The registry exposes field metadata (filterable/sortable fields, create/update/filter schemas) for each resource and scope — useful for building dynamic UIs (filter bars, sort menus, forms):

import { registry } from "@artu-ai/shared/registry";

const entry = registry["MX:AV:AVI"][Resource.Client];
entry.create.schema;   // Zod schema for creation
entry.filter.fields;   // field metadata: key, path, label, type, values
entry.sort.fields;     // sortable field names

Documentation

Full guides and API reference are at docs.artu.ai.

License

MIT