@raytio/types 8.0.0 → 8.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raytio/types",
-  "version": "8.0.0",
+  "version": "8.2.0",
   "license": "MIT",
   "main": "index",
   "types": "index",
@@ -13,6 +13,6 @@
   "scripts": {
     "docs": "sh ../../scripts/generate-docs.sh",
     "test": "npm run build && yarn docs",
-    "build": "tsc && rm -rf dist/__tests__"
+    "build": "yarn run -T tsc && rm -rf dist/__tests__"
   }
 }

package/src/authz.ts

@@ -0,0 +1,13 @@
+/** Relation types used by the new authz tuple system */
+export type AuthzRelation = "viewer" | "editor" | "admin" | "owner" | "member";
+
+export type AuthzSubjectType = "user" | "group";
+
+export type AuthzObjectType =
+  | "dsm_node"
+  | "dsm_access_application"
+  | "dsm_access_application_instance"
+  | "dsm_link"
+  | "dsm_public_profile"
+  | "far_customer"
+  | "group";

package/src/index.ts

@@ -7,3 +7,5 @@ export * from "./wizard";
 export * from "./orgs";
 export * from "./subscription";
 export * from "./merchant";
+export * from "./tenant";
+export * from "./authz";

package/src/raytio.ts

@@ -21,6 +21,14 @@ export type GId = StringWithIdentity<"GId">;
 export type UId = StringWithIdentity<"UId">;
 /** An `a_id` is the ID of an {@link AA} */
 export type AId = StringWithIdentity<"AId">;
+/** An `ao_id` is the ID of an {@link AAObject} */
+export type AOId = StringWithIdentity<"AOId">;
+/** A `aain_id` is the ID of an Instance Node */
+export type AINId = StringWithIdentity<"AINId">;
+/** A `aaink_id` is the ID of an Instance Node Key */
+export type AINKId = StringWithIdentity<"AINKId">;
+/** A `tnt_id` is the ID of a Tenant */
+export type TNTId = StringWithIdentity<"TNTId">;
 /**
  * An `o_id` is the ID of an {@link Organization}
  *
@@ -67,6 +75,10 @@ export type PTId = StringWithIdentity<"PTId">;
 export type MId = StringWithIdentity<"MId">;
 /** A `gpm_id` is the ID of a Verification Type */
 export type GPMId = StringWithIdentity<"GPMId">;
+/** A `b_id` is the ID of a badge definition */
+export type BId = StringWithIdentity<"BId">;
+/** a `GroupName` is the unique name of a group, often used instead of {@link GId} */
+export type GroupName = StringWithIdentity<"GroupName">;
 
 export type DataTypes =
   | "string"
@@ -85,6 +97,7 @@ export type SubmissionStatus =
   | "Completed"
   | "DataChanged"
   | "Received"
+  | "Pending"
   | "Accepted";
 
 /**
@@ -189,17 +202,22 @@ export type Lookup = {
   label?: string | number;
   children?: Lookup[];
   description?: string;
+  /** Icon source in format `icon:{AntDesignIconName}` (e.g., `icon:CameraOutlined`) */
+  image_src?: string;
 
   /** used in AkahuDynamicSection only */
   requires_2FA?: boolean;
+
+  /** Sort order within a lookup set. NULL = unordered. */
+  display_order?: number;
+  /** Group heading for dropdown lists (e.g., "APAC", "EMEA"). NULL = ungrouped. */
+  lookup_group?: string;
 };
 
 export type AATag =
   | "type:client_only"
   | "type:share_with_new_user"
-  // heritage
-  | `related_service_provider:n_id:${NId}`
-  | "ServiceProvider"; // TODO: document or delete
+  | "Merchant"; // TODO: document or delete
 
 export type AA = {
   a_id: AId;
@@ -220,11 +238,13 @@ export type AA = {
     font?: CustomFonts;
     colors?: Colors;
   };
-  /** the n_id of the associated service provider */
+  /** @deprecated use merchant_id instead */
   service_provider_n_id?: NId;
   /** the id of the associated organization */
   org_id?: OId;
   customer_id: CId;
+  /** the id of the associated merchant (replaces service_provider_n_id) */
+  merchant_id?: MId;
 
   /** configuration for the submission rules */
   // we know the type should be `ScoreConfig`, but we can't rely that it's valid, or the right version
@@ -233,6 +253,9 @@ export type AA = {
   /** if true, only specific email addresses can submit the form */
   auth_list_enabled?: boolean;
 
+  /** Bot protection challenge type. If set, users must complete a challenge before accessing the wizard. */
+  client_challenge_type?: "turnstile" | null;
+
   /** Currently Unused Attributes */
   start_date?: Date;
   end_date?: Date;
@@ -246,6 +269,28 @@ export type AA = {
   transitions?: unknown[];
 };
 
+export type AAObject = CommonFields<AOId> & {
+  aa_id: AId;
+  aai_id: IId;
+  properties: Json;
+  labels: string[];
+};
+
+export type InstanceNode = CommonFields<AINId> & {
+  aa_id: AId;
+  /* The n_id of the shared PO */
+  n_id: NId;
+  field_list: string[];
+};
+
+export type InstanceNodeKey = CommonFields<AINKId> & {
+  aa_id: AId;
+  aai_id: IId;
+  aain_id: AINId;
+  field_name: string;
+  key_data: string;
+};
+
 export type InstanceWithoutData = CommonFields<IId, { message?: string }> & {
   /** ID of the access application this submission was made to */
   aa_id: AId;
@@ -260,10 +305,10 @@ export type InstanceWithoutData = CommonFields<IId, { message?: string }> & {
   thread: string;
   /** The status of a submission */
   state: SubmissionStatus;
-  /** Hash of the Service Provider ID */
-  sub_service_provider_hash: string;
-  /** Service provider ID */
-  service_provider_n_id: NId;
+  /** Hash of the Merchant ID */
+  sub_merchant_hash: string;
+  /** Merchant ID (replaces service_provider_n_id) */
+  merchant_id: MId;
 
   /** added by the client once it calculates the score */
   // Defined as `unknown` instead of `ScoreResult` because it could be nonsense,
@@ -321,41 +366,46 @@ export type Validation = {
   };
 };
 
-export type WebhookStatus = "subscribed" | "pending" | "unsubscribe_failed";
-
-export type Webhook = {
-  wi_id: WId;
-  /** n_id of "the webhook provider which can be set up against a service provider" */
-  provider_webhook_id: NId;
-  /** not sure what this is */
-  provider_webhook_subscription_id: NId;
-  status: WebhookStatus;
-  /** ISO Date */
-  date_created: string;
-  /** ISO Date */
-  date_updated: string;
+export type WebhookStatus =
+  | "PENDING"
+  | "SUBSCRIBED"
+  | "UNSUBSCRIBED"
+  | "UNSUBSCRIBE_FAILED"
+  | "ERROR"
+  | "ARCHIVED";
 
+export type Webhook = CommonFields<WId> & {
+  aa_id: AId;
+  webhook_processing_rules: unknown;
+  provider_subscription_credentials: unknown;
+  provider_signature_check_enabled: boolean;
+  provider_signature_credentials: unknown;
+  webhook_filter_source: string | null;
   webhook_filter_schema: {
     operator: string;
     field_value: string;
     field_name: string;
-  };
-  webhook_action: { webhook_action_type: string }[];
-  webhook_filter_source: string;
+  } | null;
+  webhook_action: { webhook_action_type: string }[] | null;
   webhook_field_mapping_schema: {
     [key: string]: string;
-  };
-  webhook_processing_rules: unknown;
-
-  provider_subscription_credentials: unknown;
-  provider_signature_check_enabled: boolean;
-  provider_signature_credentials: unknown;
+  } | null;
+  provider_webhook_id: string;
+  provider_webhook_subscription_id: string | null;
+  subscribe_log?:
+    | {
+        date: string;
+        response_status_code: number;
+        response_payload: Json;
+      }[]
+    | null;
+  status: WebhookStatus;
+  metadata: unknown;
 
-  subscribe_log?: {
-    date: string;
-    response_status_code: number;
-    response_payload: Json;
-  }[];
+  // Legacy compatibility - these will be computed from the new fields
+  wi_id?: WId; // mapped from id
+  date_created?: string; // mapped from start_date
+  date_updated?: string; // computed or mapped as needed
 };
 
 /**
@@ -371,3 +421,16 @@ export type Link = {
   details?: AA;
   isDefault?: boolean;
 };
+
+// Used in Permissions - Get for Node
+export type Permission = {
+  id: NId;
+  n_id: NId;
+  labels: string[];
+  properties: { permissions: string; provider_name: string };
+  user_permission_type: string | null;
+  group_permission_type: "VIEWS" | "EDITS" | null;
+  group_name: "ALL" | "Public" | `sharing|${UId}|${UId}` | GId;
+  is_owner: boolean;
+  permission_id: PId;
+};

package/src/schema.ts

@@ -1,5 +1,11 @@
-import type { AA, DataTypes, SchemaName, Urn } from "./raytio";
-import type { Organization } from "./orgs";
+import type {
+  AA,
+  CommonFields,
+  DataTypes,
+  Json,
+  SchemaName,
+  Urn,
+} from "./raytio";
 import type { WizardConfig } from "./wizard";
 
 /** should be renamed since this applies to ConditionallyVerifiable */
@@ -11,6 +17,15 @@ export type ConditionallyRequired = {
   };
 };
 
+/** Schema-level conditional tags, evaluated at runtime based on form values */
+export type ConditionalTags = {
+  tags: string[];
+  // see `isConditionMet` for how this syntax works
+  if: {
+    [fieldName: string]: (string | number | boolean)[];
+  };
+};
+
 export type SchemaFieldTag =
   // legacy (TODO: remove these)
   | "password"
@@ -29,6 +44,11 @@ export type SchemaFieldTag =
   | `display:replace:('${string}', '${string}')`
   | "display:terms_conditions"
   | `display:main_media:${string}` // property name to determine what image to display
+  // content block variants (see ContentBlockField)
+  | "display:content-block"
+  | "display:info"
+  | "display:warning"
+  | "display:error"
   // date picker components
   | "date_component:day"
   | "date_component:month"
@@ -41,6 +61,8 @@ export type SchemaFieldTag =
   | "action:hash" // creates hash containing specified information
   | "action:require_webauthn"
   | `action:generate_pepper:` // generates a pepper length 'n'
+  | `action:timeout:${number}` // for a lookup field. Signifies it should expire after 'n' seconds
+  | `action:server-search:${string}` // for a lookup field. Enables server-side search on the specified column(s)
   | "verify:show_if_pending"
   | "special:hide_select_behind_button"
   | "type:capture_geolocation" // triggers the wizard's GeoLocationInput field
@@ -51,6 +73,7 @@ export type SchemaTag =
   | "action:experimental_pass_object_store_id"
   | "action:verify"
   | `action:display_qr_code:${/* either extract or verify */ string}:${/* when to display QR */ string}`
+  | `action:display_global_idv_app_qr_code:${/* either extract or verify */ string}`
   // camera
   | "default_camera:rear"
   | "default_camera:front"
@@ -61,12 +84,15 @@ export type SchemaTag =
   | `time:${/* type */ string}:${/* seconds */ number}`
   | `link_to:${/* schemaName */ string}:${/* relationshipType */ string}`
   | "display:default_view:edit" // links profile POcard direct to edit menu
+  // bot protection
+  | "support_challenge"
   // type
-  | "type:service_provider"
+  | "type:merchant"
   | "type:service_offer"
   | "type:marketplace"
   | "type:client_only"
-  | "type:globally_unique_field";
+  | "type:globally_unique_field"
+  | "type:application_object";
 
 export type SchemaField = {
   /** @deprecated don't use, it's inconsistent */
@@ -88,9 +114,9 @@ export type SchemaField = {
   step?: number;
   /** if true, the user must have encryption enabled to save this data, see #1324 */
   encrypt_require?: boolean;
-  /** @deprecated raytio's usage not documented */
+  /** for string inputs, the maximum character length. Also used to determine textarea rendering (maxLength > 30 renders a textarea) */
   maxLength?: number;
-  /** @deprecated raytio's usage not documented */
+  /** for string inputs, the minimum character length. Not currently used anywhere in the client */
   minLength?: number;
   /** the default value */
   default?: unknown;
@@ -146,12 +172,40 @@ export type SchemaField = {
   content?: string;
   /** URL to a JSON file in the `Lookup` format */
   lookup?: string;
+  /**
+   * Transforms the lookup response into the expected `{ key, value }[]` format.
+   * Use when the API returns data in a different structure.
+   *
+   * Simple format (extract array from path, use values as both key and value):
+   * ```json
+   * "lookupTransform": "[0].scopes"
+   * ```
+   *
+   * Object format (specify key/value mapping):
+   * ```json
+   * "lookupTransform": {
+   *   "path": "[0].items",
+   *   "key": "id",
+   *   "value": "name"
+   * }
+   * ```
+   */
+  lookupTransform?:
+    | string
+    | {
+        /** JSON path to extract the array (e.g., "[0].scopes", "data.items") */
+        path: string;
+        /** Property name to use as the lookup key (if omitted, uses the value itself) */
+        key?: string;
+        /** Property name to use as the lookup value (if omitted, uses the value itself) */
+        value?: string;
+      };
   /** @internal the client adds this - it's the fieldName. */
   $prop: string;
   priority?: number;
   /** @internal if supplied, it's the existing field values. Added by the client */
   subObjectRef?: unknown[];
-  /** specifies that the description is formatted in markdown */
+  /** @deprecated Markdown is now rendered by default for all descriptions. This property is no longer needed. */
   description_decorator?: "md";
   /** if a `pattern` is specified, this is the error message */
   patternMessage?: string;
@@ -191,12 +245,25 @@ export type SchemaField = {
 /** the only difference between the client & server's definition is that the client adds `$prop` */
 export type ServerSchemaField = Omit<SchemaField, "$prop">;
 
+/** An i18n entry from the fnd_i18n_entries API endpoint */
+export type FndI18nEntry = CommonFields<never> & {
+  i18n_key: string;
+  category: string;
+  translations: {
+    [locale: string]: {
+      title: string;
+      description?: string;
+      title_plural?: string;
+    };
+  };
+};
+
 /** not exported. Attributes that are identical in both client schema & server schema */
 export type CommonSchemaAttributes = {
   /** these fields will always exist on schema */
   title: string;
   description: string;
-  /** specifies that the description is formatted in markdown */
+  /** @deprecated Markdown is now rendered by default for all descriptions. This property is no longer needed. */
   description_decorator?: "md";
 
   schema_type?: SchemaType;
@@ -207,11 +274,22 @@ export type CommonSchemaAttributes = {
   /**
    * the group that a schema belongs to, such as "passports". This is useful for
    * forms that accept different types of similar documents.
+   * Can be a single group (string) or multiple groups (string[]) to allow a schema
+   * to appear in multiple lists.
    */
-  schema_group?: string;
+  schema_group?: string | string[];
+
+  /** Additional search terms to help users find schemas (e.g., ["license", "passport", "drivers license"]) */
+  search_terms?: string[];
 
   tags?: SchemaTag[];
 
+  /** if specified, suggests this onboarding scenario after creating a PO of this schema type */
+  suggest_post_create?: SchemaName;
+
+  /** Array of 2-character country codes that this schema is available for */
+  schema_country_codes?: string[];
+
   /* any overrides can be specfied per field or for the whole schema */
   i18n?: {
     [locale: string]: {
@@ -294,41 +372,140 @@ export type CommonSchemaAttributes = {
      * view or deafult view
      */
     compact_table?: boolean;
+
+    /**
+     * Pre-defined filter presets provided by the schema author.
+     * These appear as "Default filters" in the admin table UI and
+     * cannot be deleted by users (unlike user-saved filters).
+     *
+     * Each token's `propertyKey` must match a key in `properties`.
+     * Valid operators: `=`, `!=`, `:`, `!:`, `>`, `<`, `>=`, `<=`
+     */
+    filters?: {
+      /** Display name for the filter preset */
+      name: string;
+      /** How tokens are combined: "and" = all must match, "or" = any must match */
+      operation: "and" | "or";
+      /** Filter conditions */
+      tokens: {
+        /** Must match a key in schema `properties` */
+        propertyKey: string;
+        /** Comparison operator */
+        operator: string;
+        /** Value to compare against */
+        value: string;
+      }[];
+    }[];
+
+    /** Kanban board configuration for admin dashboard */
+    kanban?: {
+      /** Field that determines which column a card belongs to */
+      column_field?: string;
+      /** Field displayed as the card title */
+      title_field?: string;
+      /** Additional fields displayed on each card */
+      card_fields?: string[];
+    };
   };
 
   /** only the schema used for the onboarding wizard have this property */
   onboard_properties?: {
-    /** Profile Objects that should be created */
-    profile_objects?: {
-      schema_name: SchemaName;
-      properties: Record<string, unknown>;
-    }[];
-
-    /** Relationships that should be created */
-    relationships?: {
-      /** will normally look like `"{n_id:profile_objects[0]}"` */
-      from: string;
-      to: string;
-      type: string;
-      properties?: Record<string, string>;
-    }[];
+    /**
+     * High-level actions for complex workflows.
+     * create_organization: Single object for creating one organization
+     * create_access_application_link: Array for creating multiple links
+     */
+    actions?: {
+      /** Creates a single organization. Use this instead of legacy 'organizations' array. */
+      create_organization?: Array<{
+        properties: Json;
+        store_as?: string; // alias used to reference the created organization
+      }>;
+      /** Creates access application links (can be multiple) */
+      create_access_application_link?: Array<{
+        properties: Record<string, unknown>;
+        store_as?: string;
+      }>;
+      /** Other actions can be defined as needed */
+      [key: string]: any;
+    };
+    /**
+     * Execution order for entity creation. If not specified, uses default order.
+     * Examples: ["actions.create_organization", "db.v1.xrm_merchants", "db.v1.dsm_nodes"]
+     */
+    execution_order?: string[];
 
     /**
-     * Organizations that should be created. NOTE: if multiple are specified, when the wizard
-     * completes, the _first one_ will be selected
+     * Generic API endpoints organized by namespace and version.
+     *
+     * Structure: `{namespace}.{version}.{endpoint_name}` → `POST /{namespace}/{version}/{endpoint_name}`
+     *
+     * Examples:
+     * - `db.v1.xrm_merchants` → `POST /db/v1/xrm_merchants`
+     * - `db.v2.something` → `POST /db/v2/something`
+     * - `persist.v2.endpoint` → `POST /persist/v2/endpoint`
+     *
+     * Any namespace can be used. The `db` namespace is shown below as the primary example.
      */
-    organizations?: {
-      properties: Organization;
-      /** Access Applications that should be created for this org */
-      access_applications?: {
-        properties: Omit<AA, "org_id">;
-        /** Links that should be created for this AA */
-        links?: {
-          description: string;
-          wizardConfig: Omit<WizardConfig, "a_id">;
-        }[];
-      }[];
-    }[];
+    db?: {
+      v1?: {
+        /** Profile objects - POST /db/v1/dsm_nodes */
+        dsm_nodes?: Array<{
+          labels?: string[];
+          properties: Record<string, unknown>;
+          schema_name?: SchemaName;
+        }>;
+
+        /** Merchants - POST /db/v1/xrm_merchants */
+        xrm_merchants?: Array<Record<string, unknown>>;
+
+        /** Access Applications - POST /db/v1/dsm_access_applications */
+        dsm_access_applications?: Array<
+          Omit<AA, "org_id" | "a_id"> & {
+            org_id?: string;
+            links?: {
+              description: string;
+              wizardConfig: Omit<WizardConfig, "a_id">;
+            }[];
+          }
+        >;
+
+        /** Relationships - POST /db/v1/dsm_node_relationships */
+        dsm_node_relationships?: Array<{
+          from: string;
+          to: string;
+          type: string;
+          properties?: Record<string, unknown>;
+        }>;
+
+        /** Extensible for any other endpoint */
+        [endpoint: string]: Array<Record<string, unknown>> | undefined;
+      };
+      v2?: {
+        [endpoint: string]: Array<Record<string, unknown>> | undefined;
+      };
+      [version: string]:
+        | {
+            [endpoint: string]: Array<Record<string, unknown>> | undefined;
+          }
+        | undefined;
+    };
+    /**
+     * Additional namespaces can be added following the same structure as `db`.
+     * Example: persist?: { v2?: { [endpoint: string]: Array<Record<string, unknown>> } }
+     */
+    [namespace: string]:
+      | {
+          [version: string]:
+            | {
+                [endpoint: string]: Array<Record<string, unknown>> | undefined;
+              }
+            | undefined;
+        }
+      | object // for actions
+      | string[] // for execution_order
+      | string // for return_to
+      | undefined;
 
     /** The relative path in the client to redirect to once finished. May include variables */
     return_to?: string;
@@ -346,6 +523,12 @@ export type Schema = CommonSchemaAttributes & {
   /** added by client */
   type?: DataTypes;
 
+  /**
+   * Schema-level conditional tags, pre-processed for runtime evaluation.
+   * When form values match the `if` condition, the tags are added to the schema.
+   */
+  conditionalTags?: ConditionalTags[];
+
   /** the localized title of the `schema_group`. added by the client */
   group_title?: string;
 
@@ -373,12 +556,47 @@ export type Schema = CommonSchemaAttributes & {
    * In this case, this attribute defines what database table we need to use
    * to fetch the corresponding data, and which field is the primary_key of that
    * table (e.g. `id`, `o_id` etc.)
+   *
+   * The `path` property specifies the complete API path to use. If not provided,
+   * defaults to `/db/v1/{table}`. When `path` is specified, it is used directly
+   * without appending the table name.
+   * Examples:
+   * - `path: "/db/v1/rpc/my_function"` for RPC endpoints
+   * - `path: "/api/v2/custom_endpoint"` for custom API paths
+   *
+   * The optional `select` parameter supports PostgREST select syntax for nested
+   * objects/arrays. For example:
+   * `select: "id,item_id,gpm_items(id,item_key)"`
+   * This will return nested objects in the response.
    */
-  database?: { table: string; primary_key: string };
+  database?: {
+    /** Table name (required when path is not specified to construct `/db/v1/{table}`) */
+    table?: string;
+    primary_key: string;
+    /** Complete API path. If specified, used directly instead of `/db/v1/{table}` */
+    path?: string;
+    select?: string;
+    /** Schema to redirect to after creating a record (for insert schemas) */
+    return_to?: SchemaName;
+    /** HTTP method override. If specified, uses this instead of the default (POST for create, PATCH for edit, DELETE for delete) */
+    method?: "POST" | "PATCH" | "DELETE";
+    /**
+     * PostgREST query parameters to include in requests.
+     * Supports variable substitution: {$context.organizationId}, {$context.userId}, {$context.tenantId}
+     * Example: "org_id=eq.{$context.organizationId}&active=eq.true"
+     * If this contains "select=", it takes precedence over the `select` property.
+     */
+    query_parameters?: string;
+  };
 
   /** the client adds this after processing the i18n property */
   groupNames?: Record<string, string>;
 
+  /** specifies the order in which groups should be displayed */
+  groups?: {
+    order?: string[];
+  };
+
   /** added by the client to inform downstream components which locale from schema.i18n was used */
   clientLocale?: string;
 
@@ -399,7 +617,7 @@ export type Schema = CommonSchemaAttributes & {
 };
 
 /** Type Classification of a Schema returned by API */
-export type SchemaType = "ss" | "ps" | "us";
+export type SchemaType = "ss" | "ps" | "us" | "ms";
 
 /** This is what's returned by the API */
 export type WrappedSchema = {
@@ -416,6 +634,10 @@ export type WrappedSchema = {
 
   /** whether the \`version\` is the latest version */
   version_current: boolean;
+
+  /** Country codes that this schema is available for */
+  schema_country_codes?: string[];
+
   schema: CommonSchemaAttributes & {
     /** @deprecated don't use this */
     $id?: string;