@raytio/types 5.0.0 → 6.0.0

package/src/raytio.ts

@@ -1,9 +1,12 @@
 import { Encrypted } from "./crypto";
-import { Colors } from "./theme";
+import { Colors, CustomFonts } from "./theme";
 
 /** @internal see Microsoft/TypeScript#202 */
 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 */
 export type PId = StringWithIdentity<"PId">;
 /** An `i_id` is the ID of an @see Instance */
@@ -17,7 +20,6 @@ export type UId = StringWithIdentity<"UId">;
 /** An `a_id` is the ID of an @see AA */
 export type AId = StringWithIdentity<"AId">;
 
-/** @internal */
 export type DataTypes =
   | "string"
   | "number"
@@ -27,7 +29,6 @@ export type DataTypes =
   | "array"
   | "null";
 
-/** @internal */
 export type SubmissionStatus =
   | "Submitted"
   | "Processing"
@@ -39,7 +40,7 @@ export type SubmissionStatus =
   | "Accepted";
 
 /** You can supply an option type argument if you know exactly what the properties will be */
-export type ProfileObject<Properties = any> = {
+export type ProfileObject<Properties = Json> = {
   n_id: NId;
   properties: Properties;
   labels: string[];
@@ -49,11 +50,11 @@ export type ProfileObject<Properties = any> = {
    * @internal the client adds this, if this PO doesn't actually belong to the current user,
    * i.e. it's actually from a submission. If truthy, it's the `[aId, iId]` of the submission.
    */
-  isFromSubmission?: [aId: string, iId: string]; // TODO: do NOT use nominal types here, see microsoft/TypeScript#42773
+  isFromSubmission?: [aId: AId, iId: IId];
 };
 
 /** @internal This is what we send the API */
-export type ProfileObjectForUpload<Properties = any> = {
+export type ProfileObjectForUpload<Properties = Json> = {
   properties: Properties;
   document?: {
     content?: string | Encrypted;
@@ -61,6 +62,7 @@ export type ProfileObjectForUpload<Properties = any> = {
   };
   labels?: string[];
 
+  // TODO: represent the below constraint in the typedef
   // `schema` XOR `n_id` depending on whether creating or updating
   schema?: string; // only if creating a new PO
   n_id?: NId; // only if editing an existing PO
@@ -81,7 +83,7 @@ export type UrnNodeType =
   | "user"
   | "profile_object"
   | "instance"
-  | "temp_object" // this will only be encountered in backend environments which lack access to an applicationDecryptor
+  | "temp_object" // this will only be encountered in backend environments which lack access to an applicationDecryptor, or from RapidShare
   | "document";
 
 /** e.g. "urn:user:..." */
@@ -106,6 +108,9 @@ export type Lookup = {
   label?: string | number;
   children?: Lookup[];
   description?: string;
+
+  /** used in AkahuDynamicSection only */
+  requires_2FA?: boolean;
 };
 
 export type AA = {
@@ -114,19 +119,27 @@ 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;
-  picture?: string;
+  picture?: Urn;
   /** Easy to use AA logo url for pasting inot emails */
   picture_url?: string;
   scopes?: string[];
   tags?: string[];
   callback_uri?: string[];
+  /** markdown or string help information including [phoneNumber || email] */
+  aa_help?: string;
   theme?: {
-    colors: Colors;
+    font?: CustomFonts;
+    colors?: Colors;
   };
   /** the n_id of the associated service provider */
   service_provider_n_id?: NId;
   /** the id of the associated organisation */
   org_id: string;
+
+  /** 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
+  ruleset?: unknown;
+
   /** @internal */
   _transitions?: unknown[];
 };
@@ -154,7 +167,7 @@ export type Instance = {
   /** @depreacted The status of a submission */
   _state?: SubmissionStatus;
   /** Previous status of the shared information */
-  previous_state: string;
+  previous_state: SubmissionStatus;
   /** Hash of the Service Provider ID */
   sub_service_provider_hash?: string;
   /** Service provider ID */
@@ -171,6 +184,7 @@ export type Instance = {
       };
     };
   };
+  relationships?: Relationship[];
 };
 
 /**
@@ -191,3 +205,20 @@ export type Organization = {
   };
   customer: Record<string, unknown>;
 };
+
+/** validation data returned by preVerify (part of the extract&map API) */
+export type Validation = {
+  score: number;
+  warning?: string[];
+  breakdown: {
+    [category: string]: {
+      passed: boolean;
+      /** only present if passed=false */
+      code?: number;
+      /** only present if passed=false */
+      reason?: string;
+      /** only present if passed=false */
+      severity?: "low" | "medium" | "high";
+    };
+  };
+};

package/src/schema.ts

@@ -1,6 +1,7 @@
-import { AA, DataTypes, Organization, Urn } from "./raytio";
+import { AA, DataTypes, NId, Organization, Urn } from "./raytio";
 import { WizardConfig } from "./wizard";
 
+/** should be renamed since this applies to ConditionallyVerifiable */
 export type ConditionallyRequired = {
   field: string;
   if: {
@@ -22,6 +23,8 @@ export type SchemaFieldTag =
   | "display:survey"
   | "display:quoting"
   | "display:customModal"
+  | "display:terms_conditions"
+  | "display:showOnWizard" // added by #837, TODO: document
   | `display:main_media:${string}` // property name to determine what image to display
   // other
   | "action:client_upload"
@@ -30,16 +33,17 @@ export type SchemaFieldTag =
   | "type:extract_required";
 
 export type SchemaTag =
-  // legacy (TODO: remove these)
-  | "type:provider_profile"
-  | "type:service_offer"
-  | "client_only"
-  | "globally_unique_field"
   // action
+  | "action:experimental_pass_object_store_id"
   | "action:verify"
-  | "action:experimental_pass_urn"
+  // camera
+  | "default_camera:rear"
+  | "default_camera:front"
+  // misc
+  | `link_to:${/* schemaName */ string}:${/* relationshipType */ string}`
   // type
   | "type:service_provider"
+  | "type:service_offer"
   | "type:marketplace"
   | "type:client_only"
   | "type:globally_unique_field";
@@ -48,21 +52,21 @@ export type SchemaField = {
   /** @deprecated don't use, it's inconsistent */
   $id?: string;
   title?: string;
+  title_plural?: string;
   description?: string;
   /** readOnly means the Wizard won't show this field */
   readOnly?: boolean;
   examples?: unknown[];
   tags?: SchemaFieldTag[];
   type?: DataTypes;
-  enum?: unknown[];
+  enum?: string[];
   maximum?: number;
   minimum?: number;
   /** @deprecated raytio's usage not documented */
   maxLength?: number;
   /** @deprecated raytio's usage not documented */
   minLength?: number;
-  /** @internal added by the client. It's the default value based on the existing values from subschema on their profile */
-  defaultValue?: unknown;
+  /** the default value */
   default?: unknown;
   pattern?: string;
   /** whether the field should be encrypted */
@@ -70,13 +74,17 @@ export type SchemaField = {
   format?: "date" | "date-time";
   contentMediaType?: string;
   contentEncoding?: "base64";
-  /** for nested JSON */
+  /** `items` is used for nested arrays, (while `properties` is used for nested objects) */
   items?: {
     type: DataTypes;
     properties: {
       [subFieldName: string]: SchemaField;
     };
   };
+  /** `properties` is used for nested objects, (while `items` is used for nested arrays) */
+  properties?: {
+    [subFieldName: string]: SchemaField;
+  };
 
   /** If this field refers to a sub-object */
   $ref?: string;
@@ -98,10 +106,10 @@ export type SchemaField = {
   /** URL to a JSON file in the `Lookup` format */
   lookup?: string;
   /** @internal the client adds this - it's the fieldName. */
-  $prop?: string;
+  $prop: string;
   priority?: number;
   /** @internal if supplied, it's the existing field values. Added by the client */
-  subObjectRef?: (string | number)[]; //
+  subObjectRef?: unknown[];
   /** specifies that the description is formatted in markdown */
   description_decorator?: "md";
   /** if a `pattern` is specified, this is the error message */
@@ -118,6 +126,8 @@ export type SchemaField = {
   };
   /** if this field is a table input, this determines the text to show on the "Add Row" btn */
   add_row_btn_label?: string;
+  /** if this field is a table input, this determines the text to show if the table is empty */
+  table_empty_message?: string;
 
   /**
    * used on fields that are a signature file picker, see !849
@@ -138,26 +148,32 @@ export type SchemaField = {
  * `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;
 
-  /** name will always exist on schema */
+  /** these fields will always exist on schema */
   name: string;
+  title: string;
+  description: string;
 
+  /** 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.
    */
   schema_group?: string;
-
-  title?: string;
-  description?: 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;
 
   tags?: SchemaTag[];
-  verified_fields?: string[];
+  /** originally `string[]`, the client modifies this */
+  verified_fields?: (string | ConditionallyRequired)[];
 
   wasExpandedByClient?: boolean;
   /** added by client */
@@ -172,13 +188,11 @@ export type Schema = {
     then?: Schema;
   }[];
 
-  /**
-   * this is deliberately an optional prop, there are cases where properties are
-   * undefined, e.g.
-   *  - from get-all-schema API
-   *  - if the schema is a sub-object
-   */
-  properties?: {
+  /** 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;
   };
 
@@ -187,9 +201,25 @@ export type Schema = {
     [locale: string]: {
       // @ts-expect-error I don't understand what's wrong
       $schema: Schema;
-      // not that for entries that start in "group:", only the title field will be used.
+      // not 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.
-      [fieldNameOrGroupName: string]: SchemaField & { title_plural?: string };
+
+      // see !1796 for where these are used
+      $loading_extract: { title: string };
+      $loading_verify: { title: string };
+      $loading_save: { title: string };
+      $loading_update: { title: string };
+      $loading_upload: { title: string };
+      $loading_create_sub_obj: { title: string };
+      $loading_permission: { title: string };
+      $loading_link_to_person: { title: string };
+      $loading_delete_pending_ver: { title: string };
+      $loading_pending_ver_resubmit: { title: string };
+
+      [fieldNameOrGroupName: string]: Omit<SchemaField, "$prop"> & {
+        title_plural?: string;
+      };
     };
   };
   /** @internal the client adds this after processing the i18n property */
@@ -202,13 +232,14 @@ export type Schema = {
    * the estimated loading times in seconds for various API calls. The client adds
    * this field after processing the schema tags.
    */
-  timing?: Record<"extract" | "verify" | "persist" | "persist_verify", number>;
+  timing?: Record<"extract" | "live_person" | "verify_pending_delay", number>;
 
   relationships?: {
     relationship_name: string;
     direction: "from";
     type: string;
-
+    /** if required_relationship then use will be alerted in relationship menu and won't be able to share PO unless filled out */
+    required_relationship?: boolean;
     /** Specify `oneOf` XOR `anyOf`. It's a list of schema names, or `"instance"` (see #784) */
     oneOf?: string[];
     /** Specify `oneOf` XOR `anyOf` It's a list of schema names. */
@@ -258,6 +289,15 @@ export type Schema = {
       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>;
+    }[];
+
     /**
      * Organizations that should be created. NOTE: if multiple are specified, when the wizard
      * completes, the _first one_ will be selected
@@ -274,5 +314,39 @@ export type Schema = {
         }[];
       }[];
     }[];
+
+    /** The relative path in the client to redirect to once finished. May include variables */
+    return_to?: string;
   };
 };
+
+/** 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"
+> & {
+  /**
+   * @deprecated this prop exists so that SchemaMetadata does not extend Schema.
+   * use `getSchema(schemaName)` to fetch the full schema
+   */
+  __typeof__: "You cannot supply SchemaMetadata to a function that expects Schema";
+
+  isProfileSchema: boolean;
+  isSpSchema: boolean;
+};
+
+/** @ignore */
+export type RelationDefinition = NonNullable<Schema["relationships"]>[number];

package/src/theme.ts

@@ -13,6 +13,7 @@ export type Colors = {
   /** only used by the fancy layout on the login screen */
   raytioOrangeShade: string;
   successGreen: string;
+  loadingYellow: string;
   errorRed: string;
   textLight: string;
   textMedium: string;
@@ -23,3 +24,5 @@ export type Colors = {
   blankBackground: string;
   blank: string;
 };
+
+export type CustomFonts = { header?: string; body?: string };

package/src/verification.ts

@@ -1,5 +1,34 @@
 import { NId, ProfileObject } from "./raytio";
 
+export type VerificationPayload<WithValue extends boolean> = {
+  // we deliberately haven't defined 'sub'
+  field: string;
+  schema?: string;
+  metadata?: Record<string, unknown>;
+  passed: boolean;
+  request_div: string;
+  /** @deprecated don't use this, it looks like the schema name but it's not */
+  source: string;
+  /** the n_id of the parent profile object that this ver belongs (NOT the n_id of the field) */
+  source_n_id?: NId;
+  /** like `source_n_id` */
+  source_hashed_n_id?: NId;
+  type?: null;
+  v_id: string;
+  verification_date: string;
+  verifier_id?: NId;
+  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,
+  // 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
+  // eslint-disable-next-line @typescript-eslint/ban-types
+} & (WithValue extends true ? { value: string | number } : {});
+
 /**
  * Different APIs inconsistently include the `value` prop. If you know it exists,
  * use `Verification<true>`, otherwise just `Verification`. Verifications from
@@ -17,27 +46,7 @@ export type Verification<WithValue extends boolean = false> = ProfileObject<{
   verifications: [
     {
       signature: string;
-      data: {
-        field: string;
-        metadata?: Record<string, unknown>;
-        passed: boolean;
-        request_div: string;
-        /** @deprecated don't use this, it looks like the schema name but it's not */
-        source: string;
-        /** the n_id of the parent profile object that this ver belongs (NOT the n_id of the field) */
-        source_n_id: NId;
-        v_id: string;
-        verification_date: string;
-        verifier_id?: NId;
-        verifier_source_id?: NId;
-        verifier_service_id?: NId;
-        verifier_div: string;
-        // we are disabling the eslint rule beacuse 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
-        // eslint-disable-next-line @typescript-eslint/ban-types
-      } & (WithValue extends true ? { value: string | number } : {});
+      data: VerificationPayload<WithValue>;
     },
   ];
 }>;
@@ -46,6 +55,8 @@ export type Verification<WithValue extends boolean = false> = ProfileObject<{
  * "Not Verified" means show no badge, cf. "Verified False" means the
  * verifier revealed that the data was wrong. So show a ❌
  */
+// We cannot change the enum values, since ScoreRules have been generated
+// with the enum values hardcoded. The enum value are also used to find the "best" or "worst" verification (lower=better)
 export enum FieldVerification {
   Verified = 60_001,
   NotVerified,
@@ -53,6 +64,8 @@ export enum FieldVerification {
   Expired,
 }
 
+// We cannot change the enum values, since ScoreRules have been generated
+// with the enum values hardcoded.
 export enum POVerification {
   FullyVerified = 70_001,
   PartiallyVerified,
@@ -75,7 +88,7 @@ export type VerificationProvider = {
 /** This is what @raytio/core exposes, which is more useable than @see Verification */
 export type RealVer = {
   fieldName: string;
-  value: string | number;
+  value: unknown;
   provider: VerificationProvider;
   signature: string;
   /**

package/src/wizard.ts

@@ -1,13 +1,18 @@
 import { AId } from "./raytio";
 
 /** configuration data for a single wizard page (@see WizardConfig) */
-export interface WizardPage {
+export type WizardPage = {
   /** if undefined, the schema title will be used */
-  name?: string;
+  name?: string | symbol;
   filter: "oneOf" | "anyOf";
   schemas: string[];
 
+  /** the fallback description, if there isn't one for the specific situation */
   description?: string;
+  description_select?: string;
+  description_create?: string;
+  description_update?: string;
+
   /** if explictly == false, then it's an AO (not a PO), in which case there can only be one schema */
   profile?: boolean;
   /** if true this page can be skipped. The PageResult wil be undefined */
@@ -28,13 +33,46 @@ export interface WizardPage {
   /** whether the field descriptions should be shown */
   display_field_description?: boolean;
 
-  /** if supplied, only the fields that are listed should be shared */
-  fields_to_share?: string[];
+  /** if supplied, only the fields that are listed should be shared (#520, #1024) */
+  field_list?: string[];
 
   /** custom text & header that's displayed on reverfication modal for expired PO */
   reverify_header?: string;
   reverify_text?: string;
-}
+
+  /** do not allow uploading in ImageDynamicSection if this is explictly false */
+  allow_upload?: boolean;
+
+  /** for ImageDynamicSection, the minimum score to be treated as a pass */
+  extract_threshold?: number;
+
+  /** for ImageDynamicSection, the action to take if pre-verify passes */
+  extract_threshold_pass_action?: "review" | "next_step";
+
+  /** for ImageDynamicSection, the action to take if pre-verify fails */
+  extract_threshold_fail_action?:
+    | "capture" // go back
+    | "capture_review" // prompt user to go back OR continue to review screen. If this option is chosen, licenses that do not meet the threshold can be submited
+    | "recapture_or_next_step" // prompt user to go back OR continue & skip the review page. If this option is chosen, licenses that do not meet the threshold can be submited
+    | "review" // continue to review page
+    | "next_step"; // continue & skip the review page
+
+  /** 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` */
+  verify_data?: boolean;
+
+  /** a list of fields that should not be required, even if the schema says they're required */
+  optional_fields?: string[];
+
+  /** the information to share. undefined implies both. */
+  // TODO: 'profile' is not supported yet
+  share?: "profile" | "verification" | "both";
+
+  /** 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";
+};
 
 /**
  * when a form link is generated, this is what gets saved on the API.
@@ -75,4 +113,26 @@ export type WizardConfig = {
 
   /** if specified, the email addresses that a submission should be sent to */
   emails?: string[];
+
+  /**
+   * whether the passwordless-signup process should be used if the user visits
+   * this form, and they are not logged in. If false, the standard sign-up
+   * process will be used
+   */
+  quick_onboard?: boolean;
+
+  /** the loading message to show next to the spinner after the review screen */
+  sharing_data_message?: string;
+
+  /** a list of relationships that should be created after the wizard completes (see #987) */
+  relationships?: {
+    /** schema name */
+    from: string;
+    /** schema name */
+    to: string;
+    /** relationship type */
+    type: string;
+    /** relationship properties */
+    properties?: Record<string, any>;
+  }[];
 };