@raytio/types 6.0.2 → 7.1.0

package/src/raytio.ts

@@ -7,22 +7,26 @@ export type StringWithIdentity<T> = string & { $$typeof$$: T };
 /** @internal */
 type Json = Record<string, any>; // TODO: (semver breaking) unknown
 
-/** A `p_id` is the ID of a @see Relationship */
+/** A `p_id` is the ID of a {@link Relationship} */
 export type PId = StringWithIdentity<"PId">;
-/** An `i_id` is the ID of an @see Instance */
+/** An `i_id` is the ID of an {@link Instance} */
 export type IId = StringWithIdentity<"IId">;
-/** An `n_id` is the ID of a @see ProfileObject */
+/** An `n_id` is the ID of a {@link ProfileObject} */
 export type NId = StringWithIdentity<"NId">;
 /** A `g_id` is the ID of a group */
 export type GId = StringWithIdentity<"GId">;
 /** A `u_id` is the ID of a user */
 export type UId = StringWithIdentity<"UId">;
-/** An `a_id` is the ID of an @see AA */
+/** An `a_id` is the ID of an {@link AA} */
 export type AId = StringWithIdentity<"AId">;
-/** An `o_id` is the ID of an @see Organization */
+/** An `o_id` is the ID of an {@link Organization} */
 export type OId = StringWithIdentity<"OId">;
-/** A `wi_id` is the ID of a @see Webhook */
+/** A `wi_id` is the ID of a {@link Webhook} */
 export type WId = StringWithIdentity<"WId">;
+/** An `l_id` is the ID of any data stored in the KV-Store */ // e.g. StoredWizardConfig and VerBundleMetadata
+export type LId = StringWithIdentity<"LId">;
+
+export type AnyId = PId | IId | NId | GId | UId | AId | OId | WId;
 
 export type DataTypes =
   | "string"
@@ -74,24 +78,25 @@ export type ProfileObjectForUpload<Properties = Json> = {
 
 /**
  * arbitrary key-values pairs stored on a Profile Object.
- * May contain nested JSON and @see Encrypted properties.
+ * May contain nested JSON and {@link Encrypted} properties.
  *
  * There are some limits to field names: they cannot be called
  * `__signature` nor can they include the character sequence `<=>`.
+ *
+ * @deprecated - use {@link Json}
  */
-export type Properties = {
-  [fieldName: string]: any; // TODO: (semver breaking) unknown
-};
+export type Properties = Json;
 
 export type UrnNodeType =
   | "user"
   | "profile_object"
   | "instance"
+  | "schema"
   | "temp_object" // this will only be encountered in backend environments which lack access to an applicationDecryptor, or from RapidShare
   | "document";
 
 /** e.g. "urn:user:..." */
-export type Urn = `urn:${UrnNodeType}:${string}`; // TODO: TS4.3 replace `string` with `IId | NId | GId | UId | AId`
+export type Urn = `urn:${UrnNodeType}:${AnyId}`;
 
 export type Relationship = {
   start: Urn;
@@ -117,6 +122,13 @@ export type Lookup = {
   requires_2FA?: boolean;
 };
 
+export type AATag =
+  | "type:client_only"
+  | "type:share_with_new_user"
+  // heritage
+  | `related_service_provider:n_id:${NId}`
+  | "ServiceProvider"; // TODO: document or delete
+
 export type AA = {
   a_id: AId;
   name: string;
@@ -127,7 +139,7 @@ export type AA = {
   /** Easy to use AA logo url for pasting inot emails */
   picture_url?: string;
   scopes?: string[];
-  tags?: string[];
+  tags?: AATag[];
   callback_uri?: string[];
   /** markdown or string help information including [phoneNumber || email] */
   aa_help?: string;
@@ -137,7 +149,7 @@ export type AA = {
   };
   /** the n_id of the associated service provider */
   service_provider_n_id?: NId;
-  /** the id of the associated organisation */
+  /** the id of the associated organization */
   org_id: OId;
 
   /** configuration for the submission rules */
@@ -148,7 +160,7 @@ export type AA = {
   auth_list_enabled?: boolean;
 
   /** @internal */
-  _transitions?: unknown[];
+  transitions?: unknown[];
 };
 
 export type Instance = {
@@ -171,7 +183,7 @@ export type Instance = {
   start_date: string;
   /** The status of a submission */
   state: SubmissionStatus;
-  /** @depreacted The status of a submission */
+  /** @deprecated The status of a submission */
   _state?: SubmissionStatus;
   /** Previous status of the shared information */
   previous_state: SubmissionStatus;
@@ -183,8 +195,7 @@ export type Instance = {
   profile_objects: ProfileObject[];
   // TODO: (semver breaking) mark as optional since the get-shared-data API doesn't return keys
   keys: {
-    // TODO: TS4.3 use `NId` instead of `string`
-    [nId: string]: {
+    [nId: NId]: {
       [fieldName: string]: {
         data: string;
         n_id: NId;
@@ -218,6 +229,16 @@ export type Organization = {
   customer: Record<string, unknown>;
 };
 
+/** @internal some APIs now return extra info */
+export type FullOrg = {
+  id: OId;
+  organization: Omit<Organization, "id">;
+  /** 🧙‍♂️ */
+  gandalf: unknown;
+  stripe: { customer: unknown };
+  centrix_credentials: unknown;
+};
+
 /** validation data returned by preVerify (part of the extract&map API) */
 export type Validation = {
   score: number;
@@ -235,11 +256,15 @@ 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;
-  status: unknown;
+  /** not sure what this is */
+  provider_webhook_subscription_id: NId;
+  status: WebhookStatus;
   /** ISO Date */
   date_created: string;
   /** ISO Date */
@@ -251,9 +276,19 @@ export type Webhook = {
     field_name: string;
   };
   webhook_action: { webhook_action_type: string }[];
-  provider_subscription_credentials: unknown;
   webhook_filter_source: string;
   webhook_field_mapping_schema: {
     [key: string]: string;
   };
+  webhook_processing_rules: unknown;
+
+  provider_subscription_credentials: unknown;
+  provider_signature_check_enabled: boolean;
+  provider_signature_credentials: unknown;
+
+  subscribe_log?: {
+    date: string;
+    response_status_code: number;
+    response_payload: Json;
+  }[];
 };

package/src/schema.ts

@@ -1,11 +1,12 @@
-import { AA, DataTypes, NId, Organization, Urn } from "./raytio";
+import { AA, DataTypes, Organization, Urn } from "./raytio";
 import { WizardConfig } from "./wizard";
 
 /** should be renamed since this applies to ConditionallyVerifiable */
 export type ConditionallyRequired = {
   field: string;
+  // see `isConditionMet` for how this syntax works
   if: {
-    [fieldName: string]: string[];
+    [fieldName: string]: (string | number | boolean)[];
   };
 };
 
@@ -23,8 +24,8 @@ export type SchemaFieldTag =
   | "display:survey"
   | "display:quoting"
   | "display:customModal"
+  | `display:replace:'${string}':'${string}'`
   | "display:terms_conditions"
-  | "display:showOnWizard" // added by #837, TODO: document
   | `display:main_media:${string}` // property name to determine what image to display
   // date picker components
   | "date_component:day"
@@ -48,6 +49,7 @@ export type SchemaTag =
   | `oauth2_component:name:${string}`
   | `oauth2_component:redirect_url:${string}`
   // misc
+  | `time:${/* type */ string}:${/* seconds */ number}`
   | `link_to:${/* schemaName */ string}:${/* relationshipType */ string}`
   // type
   | "type:service_provider"
@@ -67,9 +69,15 @@ export type SchemaField = {
   examples?: unknown[];
   tags?: SchemaFieldTag[];
   type?: DataTypes;
-  enum?: string[];
+  enum?: (string | number | boolean)[];
+  /** for number inputs, the maximum allowed value */
   maximum?: number;
+  /** for number inputs, the minimum allowed value */
   minimum?: number;
+  /** for number inputs, the step size used in the input or slider */
+  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 */
   maxLength?: number;
   /** @deprecated raytio's usage not documented */
@@ -107,7 +115,7 @@ export type SchemaField = {
     [fieldName: string]: string[];
   };
 
-  allOf?: [{ $ref: string }, SchemaField];
+  allOf?: [{ $ref: string }, ServerSchemaField];
 
   /** only checkbox uses this prop */
   content?: string;
@@ -151,15 +159,12 @@ export type SchemaField = {
   image_silhouette?: string;
 };
 
-/**
- * Raytio's variant of JSON Schema. All props marked as optional except
- * `name`. This type can be used for both the schema and for individual fields.
- */
-export type Schema = {
-  /** @deprecated don't use this */
-  $id?: string;
-  $schema?: string;
-  n_id?: NId;
+/** the only difference between the client & server's definition is that the client adds `$prop` */
+export type ServerSchemaField = Omit<SchemaField, "$prop">;
+
+/** not exported. Attributes that are identical in both client schema & server schema */
+export type CommonSchemaAttributes = {
+  type?: DataTypes;
 
   /** these fields will always exist on schema */
   name: string;
@@ -173,47 +178,14 @@ export type Schema = {
    * forms that accept different types of similar documents.
    */
   schema_group?: string;
-  /** the localized title of the `schema_group`. added by the client */
-  group_title?: string;
-
-  /** @deprecated not sure why a schema would have this, only fields should */
-  $ref?: string;
-
-  version?: string;
-  /** whether the `version` is the latest version */
-  version_current?: boolean;
 
   tags?: SchemaTag[];
-  /** originally `string[]`, the client modifies this */
-  verified_fields?: (string | ConditionallyRequired)[];
-
-  wasExpandedByClient?: boolean;
-  /** added by client */
-  required?: (string | ConditionallyRequired)[];
-
-  type?: DataTypes;
-  definitions?: Record<string, { $ref: Urn }>;
-  allOf?: {
-    $ref?: string;
-    if?: Schema;
-    // we don't suport else (yet)
-    then?: Schema;
-  }[];
-
-  /** If this tag exists, the schema is deprecated. ISO Date. */
-  end_date?: string;
-
-  /** 🚨 Note that there are cases where properties are undefined, e.g. if the schema is a sub-object */
-  properties: {
-    [fieldName: string]: SchemaField;
-  };
 
   /* any overrides can be specfied per field or for the whole schema */
   i18n?: {
     [locale: string]: {
-      // @ts-expect-error I don't understand what's wrong
-      $schema: Schema;
-      // not that for entries that start in "group:" or $loading_, only the title field will be used.
+      $schema: { title: string; title_plural?: string; description?: string };
+      // note that for entries that start in "group:" or $loading_, only the title field will be used.
       // ^ the exception is `group:{GROUP_NAME}:{SUB_GROUP}.field` which is used for the combined field title/desc
       // normal fields can specify any field attributes to override.
 
@@ -229,22 +201,11 @@ export type Schema = {
       $loading_delete_pending_ver: { title: string };
       $loading_pending_ver_resubmit: { title: string };
 
-      [fieldNameOrGroupName: string]: Omit<SchemaField, "$prop"> & {
+      [fieldNameOrGroupName: string]: ServerSchemaField & {
         title_plural?: string;
       };
     };
   };
-  /** @internal the client adds this after processing the i18n property */
-  groupNames?: Record<string, string>;
-  /** @internal added by the client to inform downstream components which locale from schema.i18n was used */
-  clientLocale?: string;
-
-  /**
-   * @internal
-   * the estimated loading times in seconds for various API calls. The client adds
-   * this field after processing the schema tags.
-   */
-  timing?: Record<"extract" | "live_person" | "verify_pending_delay", number>;
 
   relationships?: {
     relationship_name: string;
@@ -287,12 +248,6 @@ export type Schema = {
     expand?: { fields: string[]; label: string }[];
   };
 
-  /** @internal @deprecated do not use */
-  unexpanded_allOf?: never;
-
-  /** @internal @deprecated do not use */
-  unexpanded_properties?: never;
-
   /** only the schema used for the onboarding wizard have this property */
   onboard_properties?: {
     /** Profile Objects that should be created */
@@ -332,32 +287,88 @@ export type Schema = {
   };
 };
 
-/** Only certain properties from the schema */
-export type SchemaMetadata = Pick<
-  Schema,
-  // if you update this list, also update SCHEMA_METADATA_FIELDS
-  | "name"
-  | "title"
-  | "description"
-  | "schema_group"
-  | "end_date"
-  | "i18n"
-  | "display"
-  | "tags"
-  // added by the client
-  | "clientLocale"
-  | "groupNames"
-  | "title_plural"
-  | "group_title"
-> & {
+/**
+ * Raytio's variant of JSON Schema, as used by the client. It is a modified version
+ * of what the API returns.
+ */
+export type Schema = CommonSchemaAttributes & {
+  /** the localized title of the `schema_group`. added by the client */
+  group_title?: string;
+
+  /** originally `string[]`, the client modifies this */
+  verified_fields?: (string | ConditionallyRequired)[];
+
+  /** originally `string[]`, the client modifies this */
+  required?: (string | ConditionallyRequired)[];
+
+  /** added by client */
+  wasExpandedByClient?: boolean;
+
+  /** ISO Date. Copied from {@link WrappedSchema} */
+  start_date?: string;
+  /** ISO Date. Copied from {@link WrappedSchema} If this tag exists, the schema is deprecated */
+  end_date?: string;
+
+  /** 🚨 Note that there are cases where properties are undefined, e.g. if the schema is a sub-object */
+  properties: {
+    [fieldName: string]: SchemaField;
+  };
+
+  /** the client adds this after processing the i18n property */
+  groupNames?: Record<string, string>;
+
+  /** added by the client to inform downstream components which locale from schema.i18n was used */
+  clientLocale?: string;
+
+  /** added by the client, copied from {@link WrappedSchema} */
+  version: string;
+
   /**
-   * @deprecated this prop exists so that SchemaMetadata does not extend Schema.
-   * use `getSchema(schemaName)` to fetch the full schema
+   * the estimated loading times in seconds for various API calls. The client adds
+   * this field after processing the schema tags.
    */
-  __typeof__: "You cannot supply SchemaMetadata to a function that expects Schema";
+  timing?: Record<"extract" | "live_person" | "verify_pending_delay", number>;
 
-  isProfileSchema: boolean;
-  isSpSchema: boolean;
+  /** added by the client. If true, this should be shown to the client */
+  isProfileSchema?: boolean;
+
+  /** added by the client. If true, this schema somehow relates to legacy service providers */
+  isSpSchema?: boolean;
+};
+
+/** This is what's returned by the API */
+export type WrappedSchema = {
+  active: true;
+  /** ISO Date */
+  start_date: string;
+  /** ISO Date. If this tag exists, the schema is deprecated. */
+  end_date: string;
+  name: string;
+  type: "ss" | "ps" | "us";
+  version: string;
+  /** whether the \`version\` is the latest version */
+  version_current: boolean;
+  schema: CommonSchemaAttributes & {
+    /** @deprecated don't use this */
+    $id?: string;
+    /** @deprecated don't use this */
+    $schema?: string;
+
+    definitions?: Record<string, { $ref: Urn }>;
+    allOf?: {
+      $ref?: string;
+      if?: Partial<WrappedSchema["schema"]>;
+      // we don't suport else (yet)
+      then?: Partial<WrappedSchema["schema"]>;
+    }[];
+
+    properties: {
+      [fieldName: string]: ServerSchemaField;
+    };
+
+    required?: string[];
+    verified_fields?: string[];
+  };
 };
 
 /** @ignore */

package/src/theme.ts

@@ -10,7 +10,7 @@ export type Colors = {
   raytioOrangeText: string;
   raytioOrangeUi: string;
   raytioOrangeHover: string;
-  /** only used by the fancy layout on the login screen */
+  /** ✨ */
   raytioOrangeShade: string;
   successGreen: string;
   loadingYellow: string;

package/src/verification.ts

@@ -20,9 +20,7 @@ export type VerificationPayload<WithValue extends boolean> = {
   verifier_source_id?: NId;
   verifier_service_id?: NId;
   verifier_div: string;
-  /** ISO Date */
-  valid_until?: string;
-  // we are disabling the eslint rule beacuse even tho `{}` acts illogically in typescript,
+  // we are disabling the eslint rule because even tho `{}` acts illogically in typescript,
   // in this case it's working as expected in the intersection type, see
   // https://github.com/typescript-eslint/typescript-eslint/issues/2063#issuecomment-632833366
   // and https://github.com/typescript-eslint/typescript-eslint/issues/2063#issuecomment-645510515
@@ -85,7 +83,7 @@ export type VerificationProvider = {
   date?: Date;
 };
 
-/** This is what @raytio/core exposes, which is more useable than @see Verification */
+/** This is what @raytio/core exposes, which is more useable than {@link Verification} */
 export type RealVer = {
   fieldName: string;
   value: unknown;

package/src/wizard.ts

@@ -1,6 +1,10 @@
 import { AId } from "./raytio";
 
-/** configuration data for a single wizard page (@see WizardConfig) */
+export type WizardPageTag =
+  // actions
+  "action:require_chip";
+
+/** configuration data for a single wizard page ({@link WizardConfig}) */
 export type WizardPage = {
   /** if undefined, the schema title will be used */
   name?: string | symbol;
@@ -23,7 +27,7 @@ export type WizardPage = {
   service_provider_link?: boolean;
   /** custom text to display on the Create New button */
   create_new_text?: string;
-  /** a URL to a preset for configuing NestedSchemaSelect. @see DeepConfig */
+  /** a URL to a preset for configuing NestedSchemaSelect. {@link DeepConfig} */
   selection_hierarchy_json?: string;
 
   /** whether the schema description should be shown */
@@ -60,7 +64,12 @@ export type WizardPage = {
   /** for ImageDynamicSection, the action to take if the API returns no `validation: {}` object */
   extract_threshold_null_action?: WizardPage["extract_threshold_fail_action"];
 
-  /** if `false`, ProfileObjects created while completing the form will not be verified. `undefined` implies `true` */
+  /**
+   * if `false`, ProfileObjects created while completing the form will not be verified.
+   * if `true`, you can only select ProfileObjects that are partially or fully verified.
+   * `undefined` implies `true`.
+   * @default true
+   */
   verify_data?: boolean;
 
   /** a list of fields that should not be required, even if the schema says they're required */
@@ -72,11 +81,19 @@ export type WizardPage = {
 
   /** can you force the colour theme to change for just one page (#1066, #1074). At the moment this on pages that use WebcamImageCapture */
   display_mode?: "light" | "dark" | "default";
+
+  tags?: WizardPageTag[];
+
+  /**
+   * If specified, this is is a "Conditional Wizard Page", which is only shown
+   * if the rule passed. This field contains the ID (not name) of the rule.
+   */
+  branching_rule_name?: string;
 };
 
 /**
  * when a form link is generated, this is what gets saved on the API.
- * Each value can be overriden in the query parameters. If specified
+ * Each value can be overridden in the query parameters. If specified
  * in the query parameters, it needs to be base64 and/or url encoded.
  */
 export type WizardConfig = {