@raytio/types 7.2.0 → 7.3.0

package/README.md

@@ -38,6 +38,7 @@ Hovering over the type in VSCode will display documentation and available proper
 - [AATag](#aatag)
 - [AId](#aid)
 - [Colors](#colors)
+- [CommonFields](#commonfields)
 - [CommonSchemaAttributes](#commonschemaattributes)
 - [ConditionallyRequired](#conditionallyrequired)
 - [ContactPoint](#contactpoint)
@@ -47,10 +48,13 @@ Hovering over the type in VSCode will display documentation and available proper
 - [GId](#gid)
 - [IId](#iid)
 - [Instance](#instance)
+- [InstanceWithoutData](#instancewithoutdata)
+- [KId](#kid)
 - [LId](#lid)
 - [Location](#location)
 - [Lookup](#lookup)
 - [NId](#nid)
+- [NId2](#nid2)
 - [OId](#oid)
 - [Organization](#organization)
 - [PId](#pid)
@@ -63,6 +67,7 @@ Hovering over the type in VSCode will display documentation and available proper
 - [Schema](#schema)
 - [SchemaField](#schemafield)
 - [SchemaFieldTag](#schemafieldtag)
+- [SchemaName](#schemaname)
 - [SchemaTag](#schematag)
 - [SchemaType](#schematype)
 - [ServerSchemaField](#serverschemafield)
@@ -113,7 +118,7 @@ Hovering over the type in VSCode will display documentation and available proper
 | `service_provider_n_id?` | [`NId`](#nid) | the n_id of the associated service provider |
 | `start_date?` | `Date` | Currently Unused Attributes |
 | `tags?` | [`AATag`](#aatag)[] | - |
-| `theme?` | { `colors?`: [`Colors`](#colors) ; `font?`: [`CustomFonts`](modules.md#customfonts)  } | - |
+| `theme?` | { `colors?`: [`Colors`](#colors) ; `font?`: [`CustomFonts`](#customfonts)  } | - |
 | `theme.colors?` | [`Colors`](#colors) | - |
 | `theme.font?` | [`CustomFonts`](#customfonts) | - |
 
@@ -166,6 +171,40 @@ ___
 
 ___
 
+### CommonFields
+
+Ƭ **CommonFields**<`IdType`, `Metadata`\>: `Object`
+
+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 StringWithIdentity (e.g.
+[NId](#nid) or [AId](#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.
+
+#### Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `IdType` | extends `StringWithIdentity`<`string`\> |
+| `Metadata` | `unknown` |
+
+#### Type declaration
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `active` | `boolean` | - |
+| `end_date` | `string` | ISO Date |
+| `id` | `IdType` | - |
+| `metadata` | `Metadata` \| `undefined` | - |
+| `start_date` | `string` | ISO Date |
+
+___
+
 ### CommonSchemaAttributes
 
 Ƭ **CommonSchemaAttributes**: `Object`
@@ -187,12 +226,12 @@ not exported. Attributes that are identical in both client schema & server schem
 | `display.head_sub.fields` | `string`[] | - |
 | `display.head_sub.format?` | `string` | - |
 | `i18n?` | { `[locale: string]`: { `[fieldNameOrGroupName: string]`: [`ServerSchemaField`](#serverschemafield) & { `title_plural?`: `string`  }; `$loading_create_sub_obj`: { `title`: `string`  } ; `$loading_delete_pending_ver`: { `title`: `string`  } ; `$loading_extract`: { `title`: `string`  } ; `$loading_link_to_person`: { `title`: `string`  } ; `$loading_long_verification_message`: { `description?`: `string` ; `title?`: `string`  } ; `$loading_pending_ver_resubmit`: { `title`: `string`  } ; `$loading_permission`: { `title`: `string`  } ; `$loading_save`: { `title`: `string`  } ; `$loading_update`: { `title`: `string`  } ; `$loading_upload`: { `title`: `string`  } ; `$loading_verify`: { `title`: `string`  } ; `$schema`: { `description?`: `string` ; `title`: `string` ; `title_plural?`: `string`  }  };  } | - |
-| `onboard_properties?` | { `organizations?`: { `access_applications?`: { `links?`: { `description`: `string` ; `wizardConfig`: `Omit`<[`WizardConfig`](#wizardconfig), ``"a_id"``\>  }[] ; `properties`: `Omit`<[`AA`](modules.md#aa), ``"org_id"``\>  }[] ; `properties`: [`Organization`](modules.md#organization)  }[] ; `profile_objects?`: { `properties`: `Record`<`string`, `unknown`\> ; `schema_name`: `string`  }[] ; `relationships?`: { `from`: `string` ; `properties?`: `Record`<`string`, `string`\> ; `to`: `string` ; `type`: `string`  }[] ; `return_to?`: `string`  } | only the schema used for the onboarding wizard have this property |
-| `onboard_properties.organizations?` | { `access_applications?`: { `links?`: { `description`: `string` ; `wizardConfig`: `Omit`<[`WizardConfig`](#wizardconfig), ``"a_id"``\>  }[] ; `properties`: `Omit`<[`AA`](modules.md#aa), ``"org_id"``\>  }[] ; `properties`: [`Organization`](modules.md#organization)  }[] | Organizations that should be created. NOTE: if multiple are specified, when the wizard completes, the _first one_ will be selected |
-| `onboard_properties.profile_objects?` | { `properties`: `Record`<`string`, `unknown`\> ; `schema_name`: `string`  }[] | Profile Objects that should be created |
+| `onboard_properties?` | { `organizations?`: { `access_applications?`: { `links?`: { `description`: `string` ; `wizardConfig`: `Omit`<[`WizardConfig`](#wizardconfig), ``"a_id"``\>  }[] ; `properties`: `Omit`<[`AA`](#aa), ``"org_id"``\>  }[] ; `properties`: [`Organization`](#organization)  }[] ; `profile_objects?`: { `properties`: `Record`<`string`, `unknown`\> ; `schema_name`: [`SchemaName`](#schemaname)  }[] ; `relationships?`: { `from`: `string` ; `properties?`: `Record`<`string`, `string`\> ; `to`: `string` ; `type`: `string`  }[] ; `return_to?`: `string`  } | only the schema used for the onboarding wizard have this property |
+| `onboard_properties.organizations?` | { `access_applications?`: { `links?`: { `description`: `string` ; `wizardConfig`: `Omit`<[`WizardConfig`](#wizardconfig), ``"a_id"``\>  }[] ; `properties`: `Omit`<[`AA`](#aa), ``"org_id"``\>  }[] ; `properties`: [`Organization`](#organization)  }[] | Organizations that should be created. NOTE: if multiple are specified, when the wizard completes, the _first one_ will be selected |
+| `onboard_properties.profile_objects?` | { `properties`: `Record`<`string`, `unknown`\> ; `schema_name`: [`SchemaName`](#schemaname)  }[] | Profile Objects that should be created |
 | `onboard_properties.relationships?` | { `from`: `string` ; `properties?`: `Record`<`string`, `string`\> ; `to`: `string` ; `type`: `string`  }[] | Relationships that should be created |
 | `onboard_properties.return_to?` | `string` | The relative path in the client to redirect to once finished. May include variables |
-| `relationships?` | { `anyOf?`: `string`[] ; `direction`: ``"from"`` ; `multiple?`: `boolean` ; `oneOf?`: `string`[] ; `properties?`: { `[fieldName: string]`: [`SchemaField`](#schemafield);  } ; `relationship_name`: `string` ; `required?`: `string`[] ; `required_relationship?`: `boolean` ; `type`: `string`  }[] | - |
+| `relationships?` | { `anyOf?`: [`SchemaName`](#schemaname)[] ; `direction`: ``"from"`` ; `multiple?`: `boolean` ; `oneOf?`: ([`SchemaName`](#schemaname) \| ``"instance"``)[] ; `properties?`: { `[fieldName: string]`: [`SchemaField`](#schemafield);  } ; `relationship_name`: `string` ; `required?`: `string`[] ; `required_relationship?`: `boolean` ; `type`: `string`  }[] | - |
 | `schema_group?` | `string` | the group that a schema belongs to, such as "passports". This is useful for forms that accept different types of similar documents. |
 | `schema_type?` | [`SchemaType`](#schematype) | - |
 | `tags?` | [`SchemaTag`](#schematag)[] | - |
@@ -305,39 +344,24 @@ ___
 
 ### Instance
 
-Ƭ **Instance**: `Object`
+Ƭ **Instance**: [`InstanceWithoutData`](#instancewithoutdata) & { `keys`: { `[nId2: NId2]`: { `[fieldName: string]`: { `data`: `string`  };  };  } ; `profile_objects`: [`ProfileObject`](#profileobject)[] ; `relationships`: [`Relationship`](#relationship)[]  }
 
-#### Type declaration
+The API used to store data in this format, but it no
+longer does :( so `@raytio/core` reconstructs this object.
 
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `_state?` | [`SubmissionStatus`](#submissionstatus) | **`Deprecated`** The status of a submission |
-| `a_id` | [`AId`](#aid) | ID of the access application this submission was made to |
-| `aa_name` | `string` | name of the access application this submission was made to |
-| `aack_id?` | `string` | Key (Can be used to retrieve instance) |
-| `active?` | `boolean` | Activity Status |
-| `confirmation_code` | `string` | Code that validates information has been shared |
-| `data_provider_email` | `string` | Email of user who shared the data |
-| `device_id?` | `unknown` | Device Id |
-| `end_date` | `string` | Latest date in which the shared information was available |
-| `i_id` | [`IId`](#iid) | Access application instance ID |
-| `instance_version?` | `unknown` | Instance Version |
-| `keys` | { `[nId: NId]`: { `[fieldName: string]`: { `data`: `string` ; `n_id`: [`NId`](#nid)  };  };  } | - |
-| `metadata?` | `unknown` | Metadata |
-| `platform_footer_html?` | `unknown` | Footer Html |
-| `previous_state?` | [`SubmissionStatus`](#submissionstatus) | Previous status of the shared information |
-| `profile_objects` | [`ProfileObject`](#profileobject)[] | data associated is access application's instance |
-| `reference` | `string` | reference provided by the user who shared the data |
-| `related_offers?` | `unknown` | Related Offers |
-| `related_service_types?` | `unknown` | Related Service Types |
-| `relationships?` | [`Relationship`](#relationship)[] | - |
-| `score?` | `unknown` | added by the client once it calculates the score |
-| `service_provider_n_id?` | [`NId`](#nid) | Service provider ID |
-| `source_ip?` | `unknown` | Source IP |
-| `start_date` | `string` | Earliest date on which the shared information was available |
-| `state` | [`SubmissionStatus`](#submissionstatus) | The status of a submission |
-| `sub_service_provider_hash?` | `string` | Hash of the Service Provider ID |
-| `thread` | `string` | - |
+___
+
+### InstanceWithoutData
+
+Ƭ **InstanceWithoutData**: [`CommonFields`](#commonfields)<[`IId`](#iid), { `message?`: `string`  }\> & { `aa_id`: [`AId`](#aid) ; `aack_id`: [`KId`](#kid) ; `confirmation_code`: `string` ; `data_provider_email`: `string` ; `device_id?`: `unknown` ; `instance_version?`: `unknown` ; `platform_footer_html?`: `unknown` ; `previous_state?`: [`SubmissionStatus`](#submissionstatus) ; `reference`: `string` ; `related_offers?`: `unknown` ; `related_service_types?`: `unknown` ; `score?`: `unknown` ; `service_provider_n_id`: [`NId`](#nid) ; `source_ip?`: `unknown` ; `state`: [`SubmissionStatus`](#submissionstatus) ; `sub_service_provider_hash`: `string` ; `thread`: `string`  }
+
+___
+
+### KId
+
+Ƭ **KId**: `StringWithIdentity`<``"KId"``\>
+
+A `k_id` (also called a `aack_id` or a `publicKeyId`) is the ID of an AA's public key
 
 ___
 
@@ -413,6 +437,14 @@ An `n_id` is the ID of a [ProfileObject](#profileobject)
 
 ___
 
+### NId2
+
+Ƭ **NId2**: `StringWithIdentity`<``"NId2"``\>
+
+⚠️ This ID duplicates the [NId](#nid) and should only be used in exceptional circumstances
+
+___
+
 ### OId
 
 Ƭ **OId**: `StringWithIdentity`<``"OId"``\>
@@ -514,7 +546,7 @@ ___
 
 ### ProfileObject
 
-Ƭ **ProfileObject**<`Properties`\>: `Object`
+Ƭ **ProfileObject**<`Properties`\>: `Partial`<[`CommonFields`](#commonfields)<[`NId2`](#nid2)\>\> & { `labels`: `string`[] ; `n_id`: [`NId`](#nid) ; `properties`: `Properties`  }
 
 You can supply an option type argument if you know exactly what the properties will be
 
@@ -524,14 +556,6 @@ You can supply an option type argument if you know exactly what the properties w
 | :------ | :------ |
 | `Properties` | `Json` |
 
-#### Type declaration
-
-| Name | Type |
-| :------ | :------ |
-| `labels` | `string`[] |
-| `n_id` | [`NId`](#nid) |
-| `properties` | `Properties` |
-
 ___
 
 ### RealVer
@@ -565,19 +589,22 @@ ___
 
 | Name | Type |
 | :------ | :------ |
+| `active?` | `boolean` |
 | `end` | [`Urn`](#urn) |
+| `end_date?` | `string` |
 | `p_id` | [`PId`](#pid) |
 | `properties?` | { `[fieldName: string]`: `unknown`; `name?`: `string` ; `p_id`: [`PId`](#pid)  } |
 | `properties.name?` | `string` |
 | `properties.p_id` | [`PId`](#pid) |
 | `start` | [`Urn`](#urn) |
+| `start_date?` | `string` |
 | `type` | `string` |
 
 ___
 
 ### Schema
 
-Ƭ **Schema**: [`CommonSchemaAttributes`](#commonschemaattributes) & { `clientLocale?`: `string` ; `end_date?`: `string` ; `groupNames?`: `Record`<`string`, `string`\> ; `group_title?`: `string` ; `isProfileSchema?`: `boolean` ; `isSpSchema?`: `boolean` ; `name`: `string` ; `properties`: { `[fieldName: string]`: [`SchemaField`](modules.md#schemafield);  } ; `required?`: (`string` \| [`ConditionallyRequired`](modules.md#conditionallyrequired))[] ; `start_date?`: `string` ; `timing?`: `Record`<``"extract"`` \| ``"live_person"`` \| ``"verify_pending_delay"``, `number`\> ; `type?`: [`DataTypes`](modules.md#datatypes) ; `verified_fields?`: (`string` \| [`ConditionallyRequired`](modules.md#conditionallyrequired))[] ; `version`: `string` ; `wasExpandedByClient?`: `boolean`  }
+Ƭ **Schema**: [`CommonSchemaAttributes`](#commonschemaattributes) & { `clientLocale?`: `string` ; `end_date?`: `string` ; `groupNames?`: `Record`<`string`, `string`\> ; `group_title?`: `string` ; `isProfileSchema?`: `boolean` ; `isSpSchema?`: `boolean` ; `name`: [`SchemaName`](#schemaname) ; `properties`: { `[fieldName: string]`: [`SchemaField`](#schemafield);  } ; `required?`: (`string` \| [`ConditionallyRequired`](#conditionallyrequired))[] ; `start_date?`: `string` ; `timing?`: `Record`<``"extract"`` \| ``"live_person"`` \| ``"verify_pending_delay"``, `number`\> ; `type?`: [`DataTypes`](#datatypes) ; `verified_fields?`: (`string` \| [`ConditionallyRequired`](#conditionallyrequired))[] ; `version`: `string` ; `wasExpandedByClient?`: `boolean`  }
 
 Raytio's variant of JSON Schema, as used by the client. It is a modified version
 of what the API returns.
@@ -593,7 +620,7 @@ ___
 | Name | Type | Description |
 | :------ | :------ | :------ |
 | `$id?` | `string` | **`Deprecated`** don't use, it's inconsistent |
-| `$ref?` | `string` | If this field refers to a sub-object |
+| `$ref?` | [`SchemaName`](#schemaname) | If this field refers to a sub-object |
 | `add_row_btn_label?` | `string` | if this field is a table input, this determines the text to show on the "Add Row" btn |
 | `allOf?` | [{ `$ref`: `string`  }, [`ServerSchemaField`](#serverschemafield)] | - |
 | `content?` | `string` | only checkbox uses this prop |
@@ -609,7 +636,7 @@ ___
 | `examples?` | `unknown`[] | - |
 | `format?` | ``"date"`` \| ``"date-time"`` \| ``"uri"`` | - |
 | `image_silhouette?` | `string` | If this schema requires a photo of a document, you can specify a URL to a silhouette image which will be overlaid on top of the camera. For best results, the image should have a transparent background + minimal white foreground |
-| `items?` | { `properties`: { `[subFieldName: string]`: [`SchemaField`](#schemafield);  } ; `type`: [`DataTypes`](modules.md#datatypes)  } | `items` is used for nested arrays, (while `properties` is used for nested objects) |
+| `items?` | { `properties`: { `[subFieldName: string]`: [`SchemaField`](#schemafield);  } ; `type`: [`DataTypes`](#datatypes)  } | `items` is used for nested arrays, (while `properties` is used for nested objects) |
 | `items.properties` | { `[subFieldName: string]`: [`SchemaField`](#schemafield);  } | - |
 | `items.type` | [`DataTypes`](#datatypes) | - |
 | `lookup?` | `string` | URL to a JSON file in the `Lookup` format |
@@ -640,6 +667,14 @@ ___
 
 ___
 
+### SchemaName
+
+Ƭ **SchemaName**: `StringWithIdentity`<``"SchemaName"``\>
+
+A `SchemaName` is the ID of a [Schema](#schema)
+
+___
+
 ### SchemaTag
 
 Ƭ **SchemaTag**: ``"action:experimental_pass_object_store_id"`` \| ``"action:verify"`` \| ``"default_camera:rear"`` \| ``"default_camera:front"`` \| \`oauth2\_component:name:${string}\` \| \`oauth2\_component:redirect\_url:${string}\` \| \`time:${string}:${number}\` \| \`link\_to:${string}:${string}\` \| ``"type:service_provider"`` \| ``"type:service_offer"`` \| ``"type:marketplace"`` \| ``"type:client_only"`` \| ``"type:globally_unique_field"``
@@ -678,7 +713,7 @@ ___
 
 ### Urn
 
-Ƭ **Urn**: \`urn:user:${UId}\` \| \`urn:profile\_object:${NId}\` \| \`urn:instance:${IId}\` \| \`urn:temp\_object:${LId}\` \| \`urn:schema:${string}\` \| \`urn:document:${NId}\`
+Ƭ **Urn**: \`urn:user:${UId}\` \| \`urn:profile\_object:${NId}\` \| \`urn:instance:${IId}\` \| \`urn:temp\_object:${LId}\` \| \`urn:schema:${SchemaName}\` \| \`urn:document:${NId}\`
 
 e.g. "urn:user:..."
 
@@ -708,7 +743,7 @@ ___
 
 ### Verification
 
-Ƭ **Verification**<`WithValue`\>: [`ProfileObject`](#profileobject)<{ `field`: `string` ; `n_id`: [`NId`](modules.md#nid) ; `valid_until?`: `string` ; `verifications`: [{ `data`: [`VerificationPayload`](modules.md#verificationpayload)<`WithValue`\> ; `hashing_algorithm?`: ``"SHA512"`` ; `key_id?`: `string` ; `key_urn?`: `string` ; `signature`: `string` ; `signing_algorithm?`: ``"RSASSA_PSS_SHA_512"``  }]  }\>
+Ƭ **Verification**<`WithValue`\>: [`ProfileObject`](#profileobject)<{ `field`: `string` ; `n_id`: [`NId`](#nid) ; `valid_until?`: `string` ; `verifications`: [{ `data`: [`VerificationPayload`](#verificationpayload)<`WithValue`\> ; `hashing_algorithm?`: ``"SHA512"`` ; `key_id?`: `string` ; `key_urn?`: `string` ; `signature`: `string` ; `signing_algorithm?`: ``"RSASSA_PSS_SHA_512"``  }]  }\>
 
 Different APIs inconsistently include the `value` prop. If you know it exists,
 use `Verification<true>`, otherwise just `Verification`. Verifications from
@@ -724,7 +759,7 @@ ___
 
 ### VerificationPayload
 
-Ƭ **VerificationPayload**<`WithValue`\>: { `field`: `string` ; `metadata?`: { `[otherAttributes: string]`: `unknown`; `pending_details?`: { `pending_time`: ``"short"`` \| ``"long"`` ; `pending_type`: ``"time"`` \| ``"user"``  } ; `safeHarbourScore?`: [`SafeHarbourCode`](enums/SafeHarbourCode.md) ; `status?`: ``"pending"``  } ; `passed`: `boolean` ; `request_div`: `string` ; `schema?`: `string` ; `source`: `string` ; `source_hashed_n_id?`: [`NId`](#nid) ; `source_n_id?`: [`NId`](modules.md#nid) ; `type?`: ``null`` ; `v_id`: `string` ; `verification_date`: `string` ; `verifier_div`: `string` ; `verifier_id?`: [`NId`](modules.md#nid) ; `verifier_service_id?`: [`NId`](modules.md#nid) ; `verifier_source_id?`: [`NId`](modules.md#nid)  } & `WithValue` extends ``true`` ? { `value`: `string` \| `number`  } : {}
+Ƭ **VerificationPayload**<`WithValue`\>: { `field`: `string` ; `metadata?`: { `[otherAttributes: string]`: `unknown`; `pending_details?`: { `pending_time`: ``"short"`` \| ``"long"`` ; `pending_type`: ``"time"`` \| ``"user"``  } ; `safeHarbourScore?`: [`SafeHarbourCode`](enums/SafeHarbourCode.md) ; `status?`: ``"pending"``  } ; `passed`: `boolean` ; `request_div`: `string` ; `schema?`: [`SchemaName`](#schemaname) ; `source`: `string` ; `source_hashed_n_id?`: [`NId`](#nid) ; `source_n_id?`: [`NId`](#nid) ; `type?`: ``null`` ; `v_id`: `string` ; `verification_date`: `string` ; `verifier_div`: `string` ; `verifier_id?`: [`NId`](#nid) ; `verifier_service_id?`: [`NId`](#nid) ; `verifier_source_id?`: [`NId`](#nid)  } & `WithValue` extends ``true`` ? { `value`: `string` \| `number`  } : {}
 
 #### Type parameters
 
@@ -817,10 +852,10 @@ in the query parameters, it needs to be base64 and/or url encoded.
 | `return_to?` | `string` | the callback url to redirect to once complete. Must be in the AA's list of authorized callback urls |
 | `review_text?` | `string` | the text on the WizardReview page |
 | `sharing_data_message?` | `string` | the loading message to show next to the spinner after the review screen |
-| `signature_schema?` | `string` | if specified, a Wizard will be shown on the review page with this schema |
+| `signature_schema?` | [`SchemaName`](#schemaname) | if specified, a Wizard will be shown on the review page with this schema |
 | `skip_share?` | `boolean` | **`Deprecated`** added in !244 but never used |
 | `submit_text?` | `string` | the submit button label |
-| `terms_schema?` | `string` | if specified, a Wizard will be shown on the review page with this schema |
+| `terms_schema?` | [`SchemaName`](#schemaname) | if specified, a Wizard will be shown on the review page with this schema |
 | `update_reference?` | `boolean` | whether the user can change the reference, if there is one in the QP |
 | `webauthn_type?` | (``"usb"`` \| ``"nfc"`` \| ``"ble"`` \| ``"internal"``)[] | if specified, the user must validate their WebAuthN credential before they can submit the form |
 
@@ -860,7 +895,7 @@ configuration data for a single wizard page ([WizardConfig](#wizardconfig))
 | `profile?` | `boolean` | if explictly == false, then it's an AO (not a PO), in which case there can only be one schema |
 | `reverify_header?` | `string` | custom text & header that's displayed on reverfication modal for expired PO |
 | `reverify_text?` | `string` | - |
-| `schemas` | `string`[] | - |
+| `schemas` | [`SchemaName`](#schemaname)[] | - |
 | `selection_hierarchy_json?` | `string` | a URL to a preset for configuing NestedSchemaSelect. DeepConfig |
 | `service_provider_link?` | `boolean` | see #463 |
 | `share?` | ``"profile"`` \| ``"verification"`` \| ``"both"`` | the information to share. undefined implies both. |
@@ -887,8 +922,8 @@ This is what's returned by the API
 | :------ | :------ | :------ |
 | `active` | ``true`` | - |
 | `end_date` | `string` | ISO Date. If this tag exists, the schema is deprecated. |
-| `schema` | [`CommonSchemaAttributes`](#commonschemaattributes) & { `$id?`: `string` ; `$schema?`: `string` ; `allOf?`: { `$ref?`: `string` ; `if?`: `Partial`<[`WrappedSchema`](modules.md#wrappedschema)[``"schema"``]\> ; `then?`: `Partial`<[`WrappedSchema`](modules.md#wrappedschema)[``"schema"``]\>  }[] ; `definitions?`: `Record`<`string`, { `$ref`: [`Urn`](modules.md#urn)  }\> ; `properties`: { `[fieldName: string]`: [`ServerSchemaField`](modules.md#serverschemafield);  } ; `required?`: `string`[] ; `verified_fields?`: `string`[]  } | - |
-| `schema_name` | `string` | Schema Name Type and Version Properties |
+| `schema` | [`CommonSchemaAttributes`](#commonschemaattributes) & { `$id?`: `string` ; `$schema?`: `string` ; `allOf?`: { `$ref?`: `string` ; `if?`: `Partial`<[`WrappedSchema`](#wrappedschema)[``"schema"``]\> ; `then?`: `Partial`<[`WrappedSchema`](#wrappedschema)[``"schema"``]\>  }[] ; `definitions?`: `Record`<`string`, { `$ref`: [`Urn`](#urn)  }\> ; `properties`: { `[fieldName: string]`: [`ServerSchemaField`](#serverschemafield);  } ; `required?`: `string`[] ; `verified_fields?`: `string`[]  } | - |
+| `schema_name` | [`SchemaName`](#schemaname) | Schema Name Type and Version Properties |
 | `schema_type` | [`SchemaType`](#schematype) | - |
 | `schema_version` | `string` | - |
 | `start_date` | `string` | ISO Date |

package/dist/raytio.d.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;
@@ -12,6 +12,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 */
@@ -23,10 +25,35 @@ export type OId = StringWithIdentity<"OId">;
 /** 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 */ export type LId = StringWithIdentity<"LId">;
+/** 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" | "number" | "boolean" | "object" | "integer" | "array" | "null";
 export type SubmissionStatus = "Submitted" | "Processing" | "Rejected" | "Expired" | "Completed" | "DataChanged" | "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[];
@@ -46,12 +73,12 @@ export type ProfileObjectForUpload<Properties = Json> = {
         type?: string;
     };
     labels?: string[];
-    schema?: string;
+    schema?: SchemaName;
     n_id?: NId;
 };
 export type UrnNodeType = "user" | "profile_object" | "instance" | "schema" | "temp_object" | "document";
 /** e.g. "urn:user:..." */
-export type Urn = `urn:user:${UId}` | `urn:profile_object:${NId}` | `urn:instance:${IId}` | `urn:temp_object:${LId}` | `urn:schema:${string}` | `urn:document:${NId}`;
+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;
     end: Urn;
@@ -62,6 +89,9 @@ export type Relationship = {
         name?: string;
         [fieldName: string]: unknown;
     };
+    start_date?: string;
+    end_date?: string;
+    active?: boolean;
 };
 export type Lookup = {
     key: string | number;
@@ -112,13 +142,13 @@ export type AA = {
     /** @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 */
@@ -126,29 +156,12 @@ 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;
     /** 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 */
-    profile_objects: ProfileObject[];
-    keys: {
-        [nId: NId]: {
-            [fieldName: string]: {
-                data: string;
-                n_id: NId;
-            };
-        };
-    };
-    relationships?: Relationship[];
+    service_provider_n_id: NId;
     /** added by the client once it calculates the score */
     score?: unknown;
     /** Previous status of the shared information */
@@ -165,12 +178,21 @@ export type Instance = {
     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;
+};
+/**
+ * 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[];
+    keys: {
+        [nId2: NId2]: {
+            [fieldName: string]: {
+                data: string;
+            };
+        };
+    };
+    relationships: Relationship[];
 };
 /**
  * An organization.

package/dist/schema.d.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 = {
     field: string;
@@ -53,7 +53,7 @@ export type SchemaField = {
         [subFieldName: string]: SchemaField;
     };
     /** If this field refers to a sub-object */
-    $ref?: string;
+    $ref?: SchemaName;
     /**
      * @internal
      * the client adds this for conditional properties, see #329
@@ -175,9 +175,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;
         /** these are arbitary fields on the relationship */
@@ -217,7 +217,7 @@ export type CommonSchemaAttributes = {
     onboard_properties?: {
         /** Profile Objects that should be created */
         profile_objects?: {
-            schema_name: string;
+            schema_name: SchemaName;
             properties: Record<string, unknown>;
         }[];
         /** Relationships that should be created */
@@ -254,7 +254,7 @@ export type CommonSchemaAttributes = {
  */
 export type Schema = CommonSchemaAttributes & {
     /** added by the client, copied from {@link WrappedSchema} */
-    name: string;
+    name: SchemaName;
     /** added by client */
     type?: DataTypes;
     /** the localized title of the `schema_group`. added by the client */
@@ -299,7 +299,7 @@ export type WrappedSchema = {
     /** ISO Date. If this tag exists, the schema is deprecated. */
     end_date: string;
     /** Schema Name Type and Version Properties */
-    schema_name: string;
+    schema_name: SchemaName;
     schema_type: SchemaType;
     schema_version: string;
     /** whether the \`version\` is the latest version */

package/dist/verification.d.ts

@@ -1,4 +1,4 @@
-import { NId, ProfileObject } from "./raytio";
+import type { NId, ProfileObject, SchemaName } from "./raytio";
 export declare enum SafeHarbourCode {
     /** “a match has been made on each the Full Name, Address and Date of Birth” */
     M1 = "M1",
@@ -9,7 +9,7 @@ export declare enum SafeHarbourCode {
 }
 export type VerificationPayload<WithValue extends boolean> = {
     field: string;
-    schema?: string;
+    schema?: SchemaName;
     metadata?: {
         safeHarbourScore?: SafeHarbourCode;
         status?: "pending";

package/dist/wizard.d.ts

@@ -1,11 +1,11 @@
-import { AId } from "./raytio";
+import type { AId, SchemaName } from "./raytio";
 export type WizardPageTag = "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;
     filter: "oneOf" | "anyOf";
-    schemas: string[];
+    schemas: SchemaName[];
     /** the fallback description, if there isn't one for the specific situation */
     description?: string;
     description_select?: string;
@@ -81,9 +81,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;
     reference?: string;
     /**
      * the callback url to redirect to once complete. Must be in the AA's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raytio/types",
-  "version": "7.2.0",
+  "version": "7.3.0",
   "license": "MIT",
   "main": "index",
   "types": "index",

package/src/__tests__/raytio.typetest.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
-import { Urn, UrnNodeType } from "..";
+import type { Urn, UrnNodeType } from "..";
 
 // test that the definition of `Urn` only uses valid `UrnNodeType`s
 const assertTrue: Urn extends `urn:${UrnNodeType}:${string}` ? true : false =

package/src/__tests__/schema.typetest.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
-import { Schema, SchemaField, WrappedSchema } from "..";
+import type { Schema, SchemaField, WrappedSchema } from "..";
 
 /**
  * this file is not run, it is just compiled by tsc

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,6 +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">;
+/** 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"
@@ -45,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[];
@@ -70,7 +101,7 @@ 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
 };
 
@@ -88,7 +119,7 @@ export type Urn =
   | `urn:profile_object:${NId}`
   | `urn:instance:${IId}`
   | `urn:temp_object:${LId}`
-  | `urn:schema:${/* schemaName */ string}`
+  | `urn:schema:${SchemaName}`
   | `urn:document:${NId}`;
 
 export type Relationship = {
@@ -101,6 +132,9 @@ export type Relationship = {
     name?: string;
     [fieldName: string]: unknown;
   };
+  start_date?: string;
+  end_date?: string;
+  active?: boolean;
 };
 
 export type Lookup = {
@@ -166,13 +200,11 @@ export type AA = {
   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 */
@@ -180,31 +212,12 @@ 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;
-
   /** 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 */
-  profile_objects: ProfileObject[];
-  // TODO: (semver breaking) mark as optional since the get-shared-data API doesn't return keys
-  keys: {
-    [nId: NId]: {
-      [fieldName: string]: {
-        data: string;
-        n_id: NId;
-      };
-    };
-  };
-  relationships?: Relationship[];
+  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,
@@ -226,12 +239,23 @@ export type Instance = {
   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;
+};
+
+/**
+ * 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[];
+  keys: {
+    // this is no longer keyed by the nId,
+    [nId2: NId2]: {
+      [fieldName: string]: {
+        data: string;
+      };
+    };
+  };
+  relationships: Relationship[];
 };
 
 /**

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 = {
@@ -104,7 +104,7 @@ export type SchemaField = {
   };
 
   /** If this field refers to a sub-object */
-  $ref?: string;
+  $ref?: SchemaName;
 
   /**
    * @internal
@@ -221,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;
@@ -259,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>;
     }[];
 
@@ -300,7 +300,7 @@ export type CommonSchemaAttributes = {
  */
 export type Schema = CommonSchemaAttributes & {
   /** added by the client, copied from {@link WrappedSchema} */
-  name: string; // Will always exist on schema
+  name: SchemaName;
 
   /** added by client */
   type?: DataTypes;
@@ -361,7 +361,7 @@ export type WrappedSchema = {
   end_date: string;
 
   /** Schema Name Type and Version Properties */
-  schema_name: string;
+  schema_name: SchemaName;
   schema_type: SchemaType;
   schema_version: string;
 

package/src/verification.ts

@@ -1,4 +1,4 @@
-import { NId, ProfileObject } from "./raytio";
+import type { NId, ProfileObject, SchemaName } from "./raytio";
 
 // see #659
 export enum SafeHarbourCode {
@@ -13,7 +13,7 @@ export enum SafeHarbourCode {
 export type VerificationPayload<WithValue extends boolean> = {
   // we deliberately haven't defined 'sub'
   field: string;
-  schema?: string;
+  schema?: SchemaName;
   metadata?: {
     safeHarbourScore?: SafeHarbourCode;
     status?: "pending";

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.