@raytio/types 7.1.0 → 7.3.0

package/src/raytio.ts

@@ -1,5 +1,5 @@
-import { Encrypted } from "./crypto";
-import { Colors, CustomFonts } from "./theme";
+import type { Encrypted } from "./crypto";
+import type { Colors, CustomFonts } from "./theme";
 
 /** @internal see Microsoft/TypeScript#202 */
 export type StringWithIdentity<T> = string & { $$typeof$$: T };
@@ -13,6 +13,8 @@ export type PId = StringWithIdentity<"PId">;
 export type IId = StringWithIdentity<"IId">;
 /** An `n_id` is the ID of a {@link ProfileObject} */
 export type NId = StringWithIdentity<"NId">;
+/** ⚠️ This ID duplicates the {@link NId} and should only be used in exceptional circumstances */
+export type NId2 = StringWithIdentity<"NId2">;
 /** A `g_id` is the ID of a group */
 export type GId = StringWithIdentity<"GId">;
 /** A `u_id` is the ID of a user */
@@ -25,8 +27,10 @@ export type OId = StringWithIdentity<"OId">;
 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;
+/** A `k_id` (also called a `aack_id` or a `publicKeyId`) is the ID of an AA's public key  */
+export type KId = StringWithIdentity<"KId">;
+/** A `SchemaName` is the ID of a {@link Schema} */
+export type SchemaName = StringWithIdentity<"SchemaName">;
 
 export type DataTypes =
   | "string"
@@ -47,8 +51,33 @@ export type SubmissionStatus =
   | "Received"
   | "Accepted";
 
+/**
+ * Every object in the new database has these fields. In the
+ * interest of type-safety, the `id` should be one of the
+ * well-known IDs that extend {@link StringWithIdentity} (e.g.
+ * {@link NId} or {@link AId}). If the ID is irrelevant, then
+ * use `CommonFields<never>` rather than `CommonFields<string>`.
+ * This will deliberately prevent you from utilising the `id`
+ * field until you define a special type for that ID.
+ *
+ * This is especially important with the new API where it is much
+ * easier to mix up the different types of IDs.
+ */
+export type CommonFields<
+  IdType extends StringWithIdentity<string>,
+  Metadata = unknown,
+> = {
+  id: IdType;
+  /** ISO Date */
+  start_date: string;
+  /** ISO Date */
+  end_date: string;
+  active: boolean;
+  metadata: Metadata | undefined;
+};
+
 /** You can supply an option type argument if you know exactly what the properties will be */
-export type ProfileObject<Properties = Json> = {
+export type ProfileObject<Properties = Json> = Partial<CommonFields<NId2>> & {
   n_id: NId;
   properties: Properties;
   labels: string[];
@@ -72,21 +101,10 @@ export type ProfileObjectForUpload<Properties = Json> = {
 
   // 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
+  schema?: SchemaName; // only if creating a new PO
   n_id?: NId; // only if editing an existing PO
 };
 
-/**
- * arbitrary key-values pairs stored on a Profile Object.
- * 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 = Json;
-
 export type UrnNodeType =
   | "user"
   | "profile_object"
@@ -96,7 +114,13 @@ export type UrnNodeType =
   | "document";
 
 /** e.g. "urn:user:..." */
-export type Urn = `urn:${UrnNodeType}:${AnyId}`;
+export type Urn =
+  | `urn:user:${UId}`
+  | `urn:profile_object:${NId}`
+  | `urn:instance:${IId}`
+  | `urn:temp_object:${LId}`
+  | `urn:schema:${SchemaName}`
+  | `urn:document:${NId}`;
 
 export type Relationship = {
   start: Urn;
@@ -108,6 +132,9 @@ export type Relationship = {
     name?: string;
     [fieldName: string]: unknown;
   };
+  start_date?: string;
+  end_date?: string;
+  active?: boolean;
 };
 
 export type Lookup = {
@@ -135,8 +162,9 @@ 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?: AATag[];
@@ -159,17 +187,24 @@ 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[];
 };
 
-export type Instance = {
-  /** Access application instance ID */
-  i_id: IId;
+export type InstanceWithoutData = CommonFields<IId, { message?: string }> & {
   /** ID of the access application this submission was made to */
-  a_id: AId;
-  /** name of the access application this submission was made to */
-  aa_name: string;
+  aa_id: AId;
+  /** ID of the public key for this AA */
+  aack_id: KId;
   /** Code that validates information has been shared */
   confirmation_code: string;
   /** reference provided by the user who shared the data */
@@ -177,37 +212,50 @@ export type Instance = {
   /** Email of user who shared the data */
   data_provider_email: string;
   thread: string;
-  /** Latest date in which the shared information was available */
-  end_date: string;
-  /** Earliest date on which the shared information was available */
-  start_date: string;
   /** The status of a submission */
   state: SubmissionStatus;
-  /** @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;
+  sub_service_provider_hash: string;
   /** Service provider ID */
-  service_provider_n_id?: NId;
-  /** data associated is access application's instance */
+  service_provider_n_id: NId;
+
+  /** added by the client once it calculates the score */
+  // 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;
+};
+
+/**
+ * The API used to store data in this format, but it no
+ * longer does :( so `@raytio/core` reconstructs this object.
+ */
+export type Instance = InstanceWithoutData & {
   profile_objects: ProfileObject[];
-  // TODO: (semver breaking) mark as optional since the get-shared-data API doesn't return keys
   keys: {
-    [nId: NId]: {
+    // this is no longer keyed by the nId,
+    [nId2: NId2]: {
       [fieldName: string]: {
         data: string;
-        n_id: NId;
       };
     };
   };
-  relationships?: Relationship[];
-
-  /** added by the client once it calculates the score */
-  // Defined as `unknown` instead of `ScoreResult` because it could be nonsense,
-  // or a deprected version of `ScoreResult`.
-  score?: unknown;
+  relationships: Relationship[];
 };
 
 /**
@@ -218,15 +266,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

@@ -1,5 +1,5 @@
-import { AA, DataTypes, Organization, Urn } from "./raytio";
-import { WizardConfig } from "./wizard";
+import type { AA, DataTypes, Organization, SchemaName, Urn } from "./raytio";
+import type { WizardConfig } from "./wizard";
 
 /** should be renamed since this applies to ConditionallyVerifiable */
 export type ConditionallyRequired = {
@@ -33,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
@@ -103,7 +104,7 @@ export type SchemaField = {
   };
 
   /** If this field refers to a sub-object */
-  $ref?: string;
+  $ref?: SchemaName;
 
   /**
    * @internal
@@ -164,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.
@@ -200,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;
@@ -214,9 +221,9 @@ export type CommonSchemaAttributes = {
     /** 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[];
+    oneOf?: (SchemaName | "instance")[];
     /** Specify `oneOf` XOR `anyOf` It's a list of schema names. */
-    anyOf?: string[];
+    anyOf?: SchemaName[];
 
     /** assume TRUE if not specified */
     multiple?: boolean;
@@ -252,7 +259,7 @@ export type CommonSchemaAttributes = {
   onboard_properties?: {
     /** Profile Objects that should be created */
     profile_objects?: {
-      schema_name: string;
+      schema_name: SchemaName;
       properties: Record<string, unknown>;
     }[];
 
@@ -292,6 +299,12 @@ export type CommonSchemaAttributes = {
  * of what the API returns.
  */
 export type Schema = CommonSchemaAttributes & {
+  /** added by the client, copied from {@link WrappedSchema} */
+  name: SchemaName;
+
+  /** added by client */
+  type?: DataTypes;
+
   /** the localized title of the `schema_group`. added by the client */
   group_title?: string;
 
@@ -336,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;
@@ -343,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: SchemaName;
+  schema_type: SchemaType;
+  schema_version: string;
+
   /** whether the \`version\` is the latest version */
   version_current: boolean;
   schema: CommonSchemaAttributes & {
@@ -355,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";
+import type { NId, ProfileObject, SchemaName } 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>;
+  schema?: SchemaName;
+  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 */
@@ -45,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";
     },
   ];
 }>;
@@ -95,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,4 +1,4 @@
-import { AId } from "./raytio";
+import type { AId, SchemaName } from "./raytio";
 
 export type WizardPageTag =
   // actions
@@ -9,7 +9,7 @@ export type WizardPage = {
   /** if undefined, the schema title will be used */
   name?: string | symbol;
   filter: "oneOf" | "anyOf";
-  schemas: string[];
+  schemas: SchemaName[];
 
   /** the fallback description, if there isn't one for the specific situation */
   description?: string;
@@ -110,9 +110,9 @@ export type WizardConfig = {
   /** number of days in the future */
   expiry_date?: number;
   /** if specified, a Wizard will be shown on the review page with this schema */
-  terms_schema?: string;
+  terms_schema?: SchemaName;
   /** if specified, a Wizard will be shown on the review page with this schema */
-  signature_schema?: string;
+  signature_schema?: SchemaName;
 
   // the following ones are generally not pre-configured, instead they
   // just come from the URL query params.
@@ -141,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 */
@@ -152,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")[];
 };