@raytio/types 7.0.0 → 7.2.0

package/src/orgs.ts

@@ -0,0 +1,86 @@
+/** Types Used for Organization Related API Responses */
+/** An Organisation */
+export type Party = {
+  id: string;
+  start_date: string;
+  end_date: string;
+  active: boolean;
+  party_name: string;
+  party_description: string;
+  party_type: string;
+  metadata: PartyMetadata;
+  party_number: number;
+};
+
+/** An Organizations credentials */
+export type PartyMetadata = {
+  gandalf: unknown;
+  stripe: { customer: unknown };
+  centrix_credentials: unknown;
+};
+
+/** An Organization Site */
+export type PartySite = {
+  id: string;
+  start_date: string;
+  end_date: string;
+  active: boolean;
+  party_id: string;
+  location_number: number;
+  party_site_name: string;
+  party_site_description: string | null;
+  party_site_number: string | null;
+  party_uses: string[];
+  party_use_primary: string;
+  metadata: unknown;
+};
+
+/** An Organization Location */
+export type Location = {
+  id: string;
+  start_date: string;
+  end_date: string;
+  active: boolean;
+  location_name: string;
+  location_description: string | null;
+  address_line_1: string | null;
+  address_line_2: string | null;
+  address_line_3: string | null;
+  address_line_4: string | null;
+  premise: string | null;
+  subpremise: string | null;
+  street_number: string | null;
+  administrative_area_level_1: string | null;
+  administrative_area_level_2: string | null;
+  administrative_area_level_3: string | null;
+  route: string | null;
+  locality: string | null;
+  postal_code: string;
+  postal_code_suffix: string | null;
+  city: string | null;
+  region: string | null;
+  country: string | null;
+  geolocation: string | null;
+  geolocation_outline: string | null;
+  metadata: unknown;
+};
+
+/** A Contact Point for an Organization */
+export type ContactPoint = {
+  id: string;
+  start_date: string;
+  end_date: string;
+  active: boolean;
+  to_table: string;
+  uuid: string | undefined;
+  contact_point_purpose: string;
+  contact_point_type: string;
+  e164: string | null;
+  e164_suffix: string | null;
+  e164_type: string | null;
+  url: string | null;
+  url_type: string | null;
+  email_address: string;
+  email_address_preferred_format: string;
+  metadata: unknown;
+};

package/src/raytio.ts

@@ -7,22 +7,24 @@ 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 DataTypes =
   | "string"
@@ -72,17 +74,6 @@ export type ProfileObjectForUpload<Properties = Json> = {
   n_id?: NId; // only if editing an existing PO
 };
 
-/**
- * arbitrary key-values pairs stored on a Profile Object.
- * May contain nested JSON and @see Encrypted properties.
- *
- * There are some limits to field names: they cannot be called
- * `__signature` nor can they include the character sequence `<=>`.
- */
-export type Properties = {
-  [fieldName: string]: any; // TODO: (semver breaking) unknown
-};
-
 export type UrnNodeType =
   | "user"
   | "profile_object"
@@ -92,7 +83,13 @@ export type UrnNodeType =
   | "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:user:${UId}`
+  | `urn:profile_object:${NId}`
+  | `urn:instance:${IId}`
+  | `urn:temp_object:${LId}`
+  | `urn:schema:${/* schemaName */ string}`
+  | `urn:document:${NId}`;
 
 export type Relationship = {
   start: Urn;
@@ -118,7 +115,7 @@ export type Lookup = {
   requires_2FA?: boolean;
 };
 
-export type AATags =
+export type AATag =
   | "type:client_only"
   | "type:share_with_new_user"
   // heritage
@@ -131,11 +128,12 @@ export type AA = {
   description?: string;
   /** If a user signs up while completing this form, this message will be sent in the sign up email.  */
   aa_introduction?: string;
+  /** @deprecated see !2101 */
   picture?: Urn;
-  /** Easy to use AA logo url for pasting inot emails */
+  /** Easy to use AA logo url for pasting into emails */
   picture_url?: string;
   scopes?: string[];
-  tags?: AATags[];
+  tags?: AATag[];
   callback_uri?: string[];
   /** markdown or string help information including [phoneNumber || email] */
   aa_help?: string;
@@ -155,6 +153,15 @@ export type AA = {
   /** if true, only specific email addresses can submit the form */
   auth_list_enabled?: boolean;
 
+  /** Currently Unused Attributes */
+  start_date?: Date;
+  end_date?: Date;
+  active?: boolean;
+  key?: string;
+  logout_uri?: string[];
+  metadata?: unknown;
+  secret?: unknown;
+
   /** @internal */
   transitions?: unknown[];
 };
@@ -179,10 +186,9 @@ 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;
+
   /** Hash of the Service Provider ID */
   sub_service_provider_hash?: string;
   /** Service provider ID */
@@ -191,8 +197,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;
@@ -205,6 +210,28 @@ export type Instance = {
   // Defined as `unknown` instead of `ScoreResult` because it could be nonsense,
   // or a deprected version of `ScoreResult`.
   score?: unknown;
+
+  // Currently Unused properties
+  /** Previous status of the shared information */
+  previous_state?: SubmissionStatus;
+  /** Device Id */
+  device_id?: unknown;
+  /** Source IP */
+  source_ip?: unknown;
+  /** Related Offers */
+  related_offers?: unknown;
+  /** Instance Version */
+  instance_version?: unknown;
+  /** Footer Html */
+  platform_footer_html?: unknown;
+  /** Related Service Types */
+  related_service_types?: unknown;
+  /** Activity Status */
+  active?: boolean;
+  /** Key (Can be used to retrieve instance) */
+  aack_id?: string;
+  /** Metadata */
+  metadata?: unknown;
 };
 
 /**
@@ -215,15 +242,8 @@ export type Organization = {
   id: OId;
   name: string;
   email: string;
-  address: {
-    locationType: string;
-    street1: string;
-    street2: string;
-    city: string;
-    region: string;
-    country: string;
-  };
-  customer: Record<string, unknown>;
+  address: unknown; // Waiting on Backend Progress Before being properly updated (as of #1361)
+  customer: unknown; // Waiting on Backend Progress Before being properly updated (as of #1361) (was previously Record<string, unknown>)
 };
 
 /** @internal some APIs now return extra info */

package/src/schema.ts

@@ -24,6 +24,7 @@ export type SchemaFieldTag =
   | "display:survey"
   | "display:quoting"
   | "display:customModal"
+  | `display:replace:'${string}':'${string}'`
   | "display:terms_conditions"
   | `display:main_media:${string}` // property name to determine what image to display
   // date picker components
@@ -32,6 +33,7 @@ export type SchemaFieldTag =
   | "date_component:year"
   // other
   | "action:client_upload"
+  | "action:require_webauthn"
   | "verify:show_if_pending"
   | "special:hide_select_behind_button"
   | "type:capture_geolocation" // triggers the wizard's GeoLocationInput field
@@ -48,6 +50,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"
@@ -68,8 +71,14 @@ export type SchemaField = {
   tags?: SchemaFieldTag[];
   type?: DataTypes;
   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 */
@@ -156,15 +165,17 @@ 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;
   title: string;
   description: string;
+  /** specifies that the description is formatted in markdown */
+  description_decorator?: "md";
+
+  schema_type?: SchemaType;
 
   /** plural version of the title */
   title_plural?: string;
+
   /**
    * the group that a schema belongs to, such as "passports". This is useful for
    * forms that accept different types of similar documents.
@@ -192,6 +203,10 @@ export type CommonSchemaAttributes = {
       $loading_link_to_person: { title: string };
       $loading_delete_pending_ver: { title: string };
       $loading_pending_ver_resubmit: { title: string };
+      $loading_long_verification_message: {
+        title?: string;
+        description?: string;
+      };
 
       [fieldNameOrGroupName: string]: ServerSchemaField & {
         title_plural?: string;
@@ -284,6 +299,12 @@ export type CommonSchemaAttributes = {
  * of what the API returns.
  */
 export type Schema = CommonSchemaAttributes & {
+  /** added by the client, copied from {@link WrappedSchema} */
+  name: string; // Will always exist on schema
+
+  /** added by client */
+  type?: DataTypes;
+
   /** the localized title of the `schema_group`. added by the client */
   group_title?: string;
 
@@ -296,9 +317,9 @@ export type Schema = CommonSchemaAttributes & {
   /** added by client */
   wasExpandedByClient?: boolean;
 
-  /** ISO Date. Copied from @see WrappedSchema */
+  /** ISO Date. Copied from {@link WrappedSchema} */
   start_date?: string;
-  /** ISO Date. Copied from @see WrappedSchema If this tag exists, the schema is deprecated */
+  /** 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 */
@@ -312,7 +333,7 @@ export type Schema = CommonSchemaAttributes & {
   /** added by the client to inform downstream components which locale from schema.i18n was used */
   clientLocale?: string;
 
-  /** added by the client, copied from @see WrappedSchema */
+  /** added by the client, copied from {@link WrappedSchema} */
   version: string;
 
   /**
@@ -328,6 +349,9 @@ export type Schema = CommonSchemaAttributes & {
   isSpSchema?: boolean;
 };
 
+/** Type Classification of a Schema returned by API */
+export type SchemaType = "ss" | "ps" | "us";
+
 /** This is what's returned by the API */
 export type WrappedSchema = {
   active: true;
@@ -335,9 +359,12 @@ export type WrappedSchema = {
   start_date: string;
   /** ISO Date. If this tag exists, the schema is deprecated. */
   end_date: string;
-  name: string;
-  type: "ss" | "ps" | "us";
-  version: string;
+
+  /** Schema Name Type and Version Properties */
+  schema_name: string;
+  schema_type: SchemaType;
+  schema_version: string;
+
   /** whether the \`version\` is the latest version */
   version_current: boolean;
   schema: CommonSchemaAttributes & {
@@ -347,6 +374,7 @@ export type WrappedSchema = {
     $schema?: string;
 
     definitions?: Record<string, { $ref: Urn }>;
+
     allOf?: {
       $ref?: string;
       if?: Partial<WrappedSchema["schema"]>;

package/src/verification.ts

@@ -1,10 +1,37 @@
 import { NId, ProfileObject } from "./raytio";
 
+// see #659
+export enum SafeHarbourCode {
+  /** “a match has been made on each the Full Name, Address and Date of Birth” */
+  M1 = "M1",
+  /** “a match has been made on both Full Name and Date of Birth (but not Address)” */
+  M2 = "M2",
+  /** “a match has been made on both Full Name and Address (but not Date of Birth)” */
+  N1 = "N1",
+}
+
 export type VerificationPayload<WithValue extends boolean> = {
   // we deliberately haven't defined 'sub'
   field: string;
   schema?: string;
-  metadata?: Record<string, unknown>;
+  metadata?: {
+    safeHarbourScore?: SafeHarbourCode;
+    status?: "pending";
+    pending_details?: {
+      /**
+       * for pending verifications - whether the verifier will complete fast enough that
+       * we can show a loading indicator. If not, the user has to come back another day.
+       */
+      pending_time: "short" | "long";
+      /**
+       * for pending verifications - whether further user interaction is required to
+       * complete the verification, or if it will complete silently in the background.
+       */
+      pending_type: "time" | "user";
+    };
+
+    [otherAttributes: string]: unknown;
+  };
   passed: boolean;
   request_div: string;
   /** @deprecated don't use this, it looks like the schema name but it's not */
@@ -20,9 +47,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
@@ -47,6 +72,15 @@ export type Verification<WithValue extends boolean = false> = ProfileObject<{
     {
       signature: string;
       data: VerificationPayload<WithValue>;
+
+      /** undefined for data created before July 2023 */
+      key_id?: string;
+      /** undefined for data created before July 2023 */
+      key_urn?: string;
+      /** undefined for data created before July 2023 */
+      signing_algorithm?: "RSASSA_PSS_SHA_512";
+      /** undefined for data created before July 2023 */
+      hashing_algorithm?: "SHA512";
     },
   ];
 }>;
@@ -85,7 +119,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;
@@ -97,7 +131,7 @@ export type RealVer = {
    */
   verified: boolean;
   /** arbitary metadata returned by the verifier */
-  metadata?: Record<string, unknown>;
+  metadata?: VerificationPayload<false>["metadata"];
   /** nId of the verification */
   nID: NId;
   /** nId of the PO that the verification belongs to. Could be undefined */

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,6 +81,14 @@ 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;
 };
 
 /**
@@ -124,6 +141,9 @@ export type WizardConfig = {
   /** the loading message to show next to the spinner after the review screen */
   sharing_data_message?: string;
 
+  /** If this value is true, the form will display some data sharing information before the form (WizardPreview) */
+  display_sharing_preview?: boolean;
+
   /** a list of relationships that should be created after the wizard completes (see #987) */
   relationships?: {
     /** schema name */
@@ -135,4 +155,7 @@ export type WizardConfig = {
     /** relationship properties */
     properties?: Record<string, any>;
   }[];
+
+  /** if specified, the user must validate their WebAuthN credential before they can submit the form */
+  webauthn_type?: ("usb" | "nfc" | "ble" | "internal")[];
 };