squarefi-bff-api-module 1.36.96 → 1.36.97

package/dist/api/frontend.js

@@ -194,6 +194,7 @@ export const frontend = {
                 params,
                 paramsSerializer: KYC_FORMS_ARRAY_PARAMS,
             }),
+            // `accepted_terms`: all document ids of `form.terms` (`[]` if none); missing ones come back in `details.terms`.
             submit: ({ entity_id, rails, programs, wallet_id, locale, ...data }) => apiClientV1Frontend.postRequest(`/frontend/kyc/entities/${entity_id}/forms/submit`, { data, params: { rails, programs, wallet_id, locale }, paramsSerializer: KYC_FORMS_ARRAY_PARAMS }),
         },
         verification: {

package/dist/api/types/autogen/apiV1Frontend.types.d.ts

@@ -16421,7 +16421,7 @@ export interface paths {
         };
         /**
          * The form of an entity for a set of purposes
-         * @description Built on every call from the tenant's requirement profiles and the entity. Without `rails` and `programs` it is the base form. With one rail it is that rail's form: the base profile, the tenant's rail profile and the vendor's minimum merged: a field required by any of them is required, `review` wins over `auto`, and a field is shown when any of them shows it (one asking it without a condition — the vendor's minimum always — shows it always); profiles whose conditions read each other in a circle answer `409 KYC_FORM_CONDITIONS_CYCLE`. Sections are the groups to draw, `visible_when` the show logic, `required_by` the purposes a field is required for, the locks (`saved`, `from_document`, `pending`, `status`) what the client cannot change, `schema_version` what to echo back. Fields that come from the identity document (names, date of birth, citizenship, the document number and dates) are left out until the document is verified; the document itself is asked: its type `gov_id_type` (`PASSPORT`, `ID_CARD`, `RESIDENCE_PERMIT`, `DRIVERS` — the codes `…/owners/{owner_id}/document` takes as `type` too), issuing country `gov_id_country` and photos `gov_id_front` and `gov_id_back` (shown unless a passport) — saved, and no longer asked, once it is verified; `state: complete` on a rail form means nothing is left to ask and the client goes straight to the rail's terms. With one program and `wallet_id` it is the form before a card: the level the program's vendor demands (`minimal`: name, email, phone; `basic`: plus date of birth, citizenship, gender, identity document type and number, residential address; `declared` / `full`: plus the identity document and the face, verified after the form) merged with the tenant's binding for the program, without the base form; what the personal entity already holds is locked `saved`, so `state: complete` means the card can be asked for at once. Several rails and programs at once is the multi form: the base form, every rail and every program merged, each field once with `required_by` naming the purposes. Access: the owner of the entity, or an owner / admin of a wallet it is linked to.
+         * @description Built on every call from the tenant's requirement profiles and the entity. Without `rails` and `programs` it is the base form. With one rail it is that rail's form: the base profile, the tenant's rail profile and the vendor's minimum merged: a field required by any of them is required, `review` wins over `auto`, and a field is shown when any of them shows it (one asking it without a condition — the vendor's minimum always — shows it always); profiles whose conditions read each other in a circle answer `409 KYC_FORM_CONDITIONS_CYCLE`. Sections are the groups to draw, `visible_when` the show logic, `required_by` the purposes a field is required for, the locks (`saved`, `from_document`, `pending`, `status`) what the client cannot change, `schema_version` what to echo back. Fields that come from the identity document (names, date of birth, citizenship, the document number and dates) are left out until the document is verified; the document itself is asked: its type `gov_id_type` (`PASSPORT`, `ID_CARD`, `RESIDENCE_PERMIT`, `DRIVERS` — the codes `…/owners/{owner_id}/document` takes as `type` too), issuing country `gov_id_country` and photos `gov_id_front` and `gov_id_back` (shown unless a passport) — saved, and no longer asked, once it is verified; `state: complete` on a rail form means no field is left to ask. The terms of the form's rails — a rail it names and the rail of each of its card programs — come with the form in `terms`, to be accepted with the submission (`accepted_terms`). With one program and `wallet_id` it is the form before a card: the level the program's vendor demands (`minimal`: name, email, phone; `basic`: plus date of birth, citizenship, gender, identity document type and number, residential address; `declared` / `full`: plus the identity document and the face, verified after the form) merged with the tenant's binding for the program, without the base form; what the personal entity already holds is locked `saved`, so `state: complete` means the card can be asked for at once. Several rails and programs at once is the multi form: the base form, every rail and every program merged, each field once with `required_by` naming the purposes. Access: the owner of the entity, or an owner / admin of a wallet it is linked to.
          */
         get: {
             parameters: {
@@ -16497,7 +16497,7 @@ export interface paths {
         get?: never;
         /**
          * Save the draft of a form
-         * @description The form is the one `rails` and `programs` name, as for `GET …/forms`. Replaces the draft as a whole with the given values of open fields. Types are checked, rules and requiredness are not — except that owner shares over 100% in total and a value whose condition reads an empty required source are refused here too. Nothing is written to the KYC entity. The first draft of a business form moves the application to `PENDING`. The entity's owner, or an owner or admin of a linked wallet.
+         * @description The form is the one `rails` and `programs` name, as for `GET …/forms`. Replaces the draft as a whole with the given values of open fields. Types are checked, rules and requiredness are not — except that owner shares over 100% in total and a value whose condition reads an empty required source are refused here too. Nothing is written to the KYC entity. The terms of the form's rails (`form.terms` of `GET …/forms`) are accepted with the submission only: a draft takes no `accepted_terms` (a key of that name is ignored, nothing about the terms is stored) and its answer carries no `terms`. The first draft of a business form moves the application to `PENDING`. The entity's owner, or an owner or admin of a linked wallet.
          */
         put: {
             parameters: {
@@ -16548,7 +16548,7 @@ export interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                /** @description `FORM_LOCKED` — the form is read-only by the application status, or its last submission waits on the verification or the review; `FORM_OUTDATED` — `schema_version` is not the one the form has now, reload it (`GET …/forms`) and send again; `KYC_FORM_CONDITIONS_CYCLE` — the tenant's form settings show fields on conditions that read each other in a circle */
+                /** @description `FORM_LOCKED` — the form is read-only by the application status, or its last submission waits on the verification or the review; `FORM_OUTDATED` — `schema_version` is not the one the form has now (its fields or the terms documents of its rails changed), reload it (`GET …/forms`) and send again; `KYC_FORM_CONDITIONS_CYCLE` — the tenant's form settings show fields on conditions that read each other in a circle */
                 409: {
                     headers: {
                         [name: string]: unknown;
@@ -16762,7 +16762,7 @@ export interface paths {
         put?: never;
         /**
          * Send a form
-         * @description The form is the one `rails` and `programs` name. The full check of every open field (all errors in one `VALIDATION_ERROR`), then a submission: `awaiting_verification` when the identity document and face are still needed, `applied` when every profile of the form writes the answers into the KYC entity at once, `in_review` when compliance decides (any profile of the form in review mode). Answers `200` with the form in its new state. One submission of a form at a time. A form over rails or programs that brings nothing new — no value and no file, every required field already saved in the entity (not just waiting in another submission under review) — is `applied` at once whatever the review mode: there is nothing for compliance to decide. A rail form does not change the application status. A card form is `auto` unless a profile of it says otherwise and never changes the application status. A multi form moves the application like the base form it includes; once applied, every rail and program of the set is satisfied from the shared data. Once a rail, card or multi form is accepted (`applied`, or `approved` by compliance) and the wallet's KYC is `APPROVED` — whichever comes second — when the form was sent by an owner or admin of the wallet (the role those routes ask for), CORE submits the wallet itself: to each rail of the form the wallet has no application on yet — only for a form of the wallet's own KYC entity, a member's form never puts the wallet on a rail — (as `POST /frontend/wallets/{wallet_id}/kyc-rails/{rail_id}` would; it then shows in `GET …/kyc-rails`), and to each program the member has no cardholder in yet (as `POST /frontend/issuing/cardholders` with `user_data_id` and its submit would). The latest form sent for a rail or program decides: returned, rejected or still in review, nothing is submitted. A submission CORE could not make — refused by the rail or the vendor, a program at its limit, a form sent by a member without that role — is left for the client to make with those routes, as before. The entity's owner, or an owner or admin of a linked wallet.
+         * @description The form is the one `rails` and `programs` name. The full check of every open field (all errors in one `VALIDATION_ERROR`) and of the terms — a form with terms documents (`form.terms`) is sent only with every one of their ids in `accepted_terms` (`400 KYC_TERMS_NOT_ACCEPTED` otherwise, nothing written) — then a submission: `awaiting_verification` when the identity document and face are still needed, `applied` when every profile of the form writes the answers into the KYC entity at once, `in_review` when compliance decides (any profile of the form in review mode). Answers `200` with the form in its new state. One submission of a form at a time. A form over rails or programs that brings nothing new — no value and no file, every required field already saved in the entity (not just waiting in another submission under review) — is `applied` at once whatever the review mode: there is nothing for compliance to decide. A rail form does not change the application status. A card form is `auto` unless a profile of it says otherwise and never changes the application status. A multi form moves the application like the base form it includes; once applied, every rail and program of the set is satisfied from the shared data. Once a rail, card or multi form is accepted (`applied`, or `approved` by compliance) and the wallet's KYC is `APPROVED` — whichever comes second — when the form was sent by an owner or admin of the wallet (the role those routes ask for), CORE submits the wallet itself: to each rail of the form the wallet has no application on yet — only for a form of the wallet's own KYC entity, a member's form never puts the wallet on a rail — (as `POST /frontend/wallets/{wallet_id}/kyc-rails/{rail_id}` would; it then shows in `GET …/kyc-rails`), and to each program the member has no cardholder in yet (as `POST /frontend/issuing/cardholders` with `user_data_id` and its submit would). The latest form sent for a rail or program decides: returned, rejected or still in review, nothing is submitted. A rail opened so, or opened before with its terms unconfirmed — a rail of the form, or the rail of one of its programs — gets its terms confirmed (`terms_confirmed: true`) at the time the form was sent, when the form accepted every terms document the application holds; terms changed since the form was sent are left for the client to confirm with `POST …/kyc-rails/{rail_id}/terms-and-conditions`. A submission CORE could not make — refused by the rail or the vendor, a program at its limit, a form sent by a member without that role — is left for the client to make with those routes, as before. The entity's owner, or an owner or admin of a linked wallet.
          */
         post: {
             parameters: {
@@ -16788,7 +16788,7 @@ export interface paths {
             };
             requestBody: {
                 content: {
-                    "application/json": components["schemas"]["KycFormsAnswersRequest"];
+                    "application/json": components["schemas"]["KycFormsSubmitRequest"];
                 };
             };
             responses: {
@@ -16801,7 +16801,7 @@ export interface paths {
                         "application/json": components["schemas"]["KycFormsFormResponse"];
                     };
                 };
-                400: components["responses"]["KycFormsFieldErrors"];
+                400: components["responses"]["KycFormsSubmitErrors"];
                 401: components["responses"]["UnauthorizedError"];
                 403: components["responses"]["KycFormsAccessDenied"];
                 /** @description `NOT_FOUND` — the entity does not exist or belongs to another tenant, or a rail / program of the query does not exist for the tenant */
@@ -16813,7 +16813,7 @@ export interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                /** @description `FORM_LOCKED` — the form is read-only by the application status, or its last submission waits on the verification or the review; `FORM_OUTDATED` — `schema_version` is not the one the form has now, reload it (`GET …/forms`) and send again; `OPERATION_IN_PROGRESS` — a submission of this form is already running; `KYC_FORM_CONDITIONS_CYCLE` — the tenant's form settings show fields on conditions that read each other in a circle */
+                /** @description `FORM_LOCKED` — the form is read-only by the application status, or its last submission waits on the verification or the review; `FORM_OUTDATED` — `schema_version` is not the one the form has now (its fields or the terms documents of its rails changed), reload it (`GET …/forms`) and send again; `OPERATION_IN_PROGRESS` — a submission of this form is already running; `KYC_FORM_CONDITIONS_CYCLE` — the tenant's form settings show fields on conditions that read each other in a circle */
                 409: {
                     headers: {
                         [name: string]: unknown;
@@ -20594,6 +20594,23 @@ export interface components {
                 add_label: string;
             };
         };
+        /** @description The terms of one rail of the form: a rail the form names, or the rail of one of its card programs — one group per rail, the programs that go through it listed with it. Draw one checkbox per group that accepts all of its `items`; send their ids in `accepted_terms` of `POST …/forms/submit`. */
+        KycFormsTerms: {
+            /** Format: uuid */
+            rail_id: string;
+            /** @description The card programs of the form that go through this rail; empty when only the rail itself is named. */
+            program_ids: string[];
+            /** @description The rail's active terms documents in display order; empty when the rail has none — nothing to accept. */
+            items: {
+                /** Format: uuid */
+                id: string;
+                /** @example Cardholder Agreement */
+                title: string;
+                description: string | null;
+                /** @example https://example.com/terms.pdf */
+                link: string | null;
+            }[];
+        };
         KycFormsForm: {
             /**
              * @description What the form is for: the base form, a rail, a card program (`card`), or one form over several rails and programs (`multi`).
@@ -20617,7 +20634,7 @@ export interface components {
              */
             locale: string;
             /**
-             * @description Hash of the form composition (keys, requiredness, conditions, list item fields; not the texts); echo it back in the draft and the submission. It can change between the load and the send: `409 FORM_OUTDATED`.
+             * @description Hash of the form composition (keys, requiredness, conditions, list item fields, the ids of the terms documents in `terms`; not the texts); echo it back in the draft and the submission. It can change between the load and the send: `409 FORM_OUTDATED`.
              * @example b3f1c2a9
              */
             schema_version: string;
@@ -20646,6 +20663,31 @@ export interface components {
                 description: string | null;
                 fields: components["schemas"]["KycFormsField"][];
             }[];
+            /**
+             * @description The terms the client accepts with the form, one group per rail of the form: the rails named first, then the rail of each card program. Empty for the base form; a program without a rail adds none. The documents are those in force now: a change after the load answers the submission `409 FORM_OUTDATED`.
+             * @example [
+             *       {
+             *         "rail_id": "a38b9a0c-5d1e-4f2a-8b3c-4d5e6f708192",
+             *         "program_ids": [
+             *           "d94ef320-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
+             *         ],
+             *         "items": [
+             *           {
+             *             "id": "0c1d2e3f-4a5b-4c6d-8e7f-90a1b2c3d4e5",
+             *             "title": "Cardholder Agreement",
+             *             "description": null,
+             *             "link": "https://example.com/terms.pdf"
+             *           }
+             *         ]
+             *       },
+             *       {
+             *         "rail_id": "c1d7fac1-2b3c-4d5e-9f60-718293a4b5c6",
+             *         "program_ids": [],
+             *         "items": []
+             *       }
+             *     ]
+             */
+            terms: components["schemas"]["KycFormsTerms"][];
         };
         KycFormsFormResponse: {
             /** @example true */
@@ -20691,6 +20733,16 @@ export interface components {
                 [key: string]: components["schemas"]["KycFormsAnswerValue"];
             };
         };
+        KycFormsSubmitRequest: components["schemas"]["KycFormsAnswersRequest"] & {
+            /**
+             * @description The ids of every terms document of the form (`form.terms[].items[].id`) — the client ticked the checkbox of each group. Required in full when the form has any: one left out answers `400 KYC_TERMS_NOT_ACCEPTED`, an id that is not a uuid or not of this form `400 VALIDATION_ERROR`. A form without terms documents is sent without it. The terms are checked after the fields: while a field is wrong, only the `VALIDATION_ERROR` comes back.
+             * @default []
+             * @example [
+             *       "0c1d2e3f-4a5b-4c6d-8e7f-90a1b2c3d4e5"
+             *     ]
+             */
+            accepted_terms: string[];
+        };
         KycFormsDraftSaved: {
             /** @example true */
             success: boolean;
@@ -20998,11 +21050,18 @@ export interface components {
                 }[];
             };
         };
-        /** @description The structured payload of an error that carries one (absent otherwise — an invalid uuid or a malformed body is a message only). `VALIDATION_ERROR`: `fields` is a map from the field key to its messages (a list item field is `beneficial_owners[0].role`, the list as a whole `beneficial_owners`). `FORM_FIELD_NOT_ALLOWED`, `KYC_FORM_CONDITIONS_CYCLE`: `fields` is a list of keys. */
+        /** @description The structured payload of an error that carries one (absent otherwise — an invalid uuid or a malformed body is a message only). `VALIDATION_ERROR`: `fields` is a map from the field key to its messages (a list item field is `beneficial_owners[0].role`, the list as a whole `beneficial_owners`). `FORM_FIELD_NOT_ALLOWED`, `KYC_FORM_CONDITIONS_CYCLE`: `fields` is a list of keys. `KYC_TERMS_NOT_ACCEPTED`: `terms` — and no `fields`. */
         KycFormsErrorDetails: {
-            fields: {
+            fields?: {
                 [key: string]: string[];
             } | string[];
+            /**
+             * @description The ids of the terms documents of the form left out of `accepted_terms`.
+             * @example [
+             *       "0c1d2e3f-4a5b-4c6d-8e7f-90a1b2c3d4e5"
+             *     ]
+             */
+            terms?: string[];
         };
         /** @description The error envelope of the KYC forms: `ErrorResponse` with the `details` of the field errors spelled out. */
         KycFormsErrorResponse: components["schemas"]["ErrorResponse"] & {
@@ -21098,6 +21157,15 @@ export interface components {
                 "application/json": components["schemas"]["KycFormsErrorResponse"];
             };
         };
+        /** @description `VALIDATION_ERROR` — field errors in `details.fields[key] = [message]` (on a business form the owner list the KYC tables refuse, and owner shares adding up to more than 100%, come back under `beneficial_owners`; a value sent for a field whose condition reads a source left empty or wrong comes back as the error of the source, e.g. `beneficial_owners[0].role`), or a message only for a malformed body (`schema_version` missing or longer than 64, `values` not an object, `accepted_terms` not a list of at most 200 uuids), an id in `accepted_terms` that is not a terms document of this form, and a path id that is not a uuid; `KYC_TERMS_NOT_ACCEPTED` — `accepted_terms` leaves out a terms document of the form, `details.terms` lists the ids left out, nothing is written; `FORM_FIELD_NOT_ALLOWED` — a key the form does not accept (unknown, locked, hidden, a file field), `details.fields = [key]`, the whole request refused; `FORM_TARGET_UNSUPPORTED` — a card program named on a business entity; `INVALID_REQUEST` — `wallet_id` missing for a form over card programs; `KYC_FORM_WALLET_NOT_LINKED` — `wallet_id` of a form over rails is not a wallet of this entity; `KYC_BASE_BINDING_MISSING` — the tenant has no base form for this client type; `KYC_FORMS_NOT_ENABLED` — the tenant is not on the forms flow */
+        KycFormsSubmitErrors: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["KycFormsErrorResponse"];
+            };
+        };
         /** @description `KYC_FORM_CONDITIONS_CYCLE` — the tenant's form settings show fields on conditions that read each other in a circle (`details.fields` lists the keys); nothing the client can fix, report it to support */
         KycFormsConditionsCycle: {
             headers: {

package/dist/api/types/types.d.ts

@@ -919,6 +919,8 @@ export declare namespace API {
             export type Form = Schemas['KycFormsForm'];
             export type FormScope = Form['scope'];
             export type FormSection = Form['sections'][number];
+            export type Terms = Schemas['KycFormsTerms'];
+            export type TermsItem = Terms['items'][number];
             export type FormState = Schemas['KycFormsFormState'];
             export type Field = Schemas['KycFormsField'];
             export type FieldType = Field['type'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squarefi-bff-api-module",
-  "version": "1.36.96",
+  "version": "1.36.97",
   "description": "Squarefi BFF API client module",
   "type": "module",
   "main": "./dist/index.js",