skapi-js 2.2.6-beta.2 → 2.2.6-beta.4

package/dist/skapi.d.ts

@@ -1,3 +1,14 @@
+declare class SkapiError extends Error {
+    code: string | number;
+    /** The underlying Error, or the flat TicketError body of a failed ticket consumption (consumeTicket). */
+    cause: Error | TicketError;
+    constructor(error: any, options?: {
+        name?: string;
+        code?: string;
+        cause?: Error | TicketError;
+    });
+}
+
 type Condition = 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | '>' | '>=' | '<' | '<=' | '=';
 type RTCReceiverParams = {
     ice?: string;
@@ -558,6 +569,48 @@ type ProgressCallback = (e: {
     failed?: File[];
     abort: () => void;
 }) => void;
+/** One file of an uploadFiles() call that storage did not accept. */
+type FileUploadError = {
+    /** The File as it was given: the same object that is listed in `failed`. */
+    file: File;
+    /** The file's name. */
+    name: string;
+    /**
+     * Why it was not stored. `code` is the storage error code ('AccessDenied', 'EntityTooLarge' ...),
+     * or 'NETWORK_ERROR', 'TIMEOUT' (see UploadFilesParams.timeout), 'ABORTED' (the progress callback's
+     * abort()), 'TOO_MANY_REQUESTS', or 'UPLOAD_FAILED' when storage gave no code. `cause` holds the raw
+     * response or rejection, when there was one.
+     */
+    error: SkapiError;
+};
+/** What uploadFiles() resolves with. */
+type UploadFilesResult = {
+    /** Files that are stored. */
+    completed: File[];
+    /** Files storage did not accept. */
+    failed: File[];
+    /** Why each file in `failed` was not stored, one entry per file in the same order. Empty when every file was stored. */
+    errors: FileUploadError[];
+    /** Endpoint of every file, in the order they were given, whether or not it was stored. */
+    bin_endpoints: string[];
+};
+type UploadFilesParams = {
+    /** Record ID of the record to attach the files to. */
+    record_id: string;
+    /** Callback for upload progress. Useful when building a progress bar. */
+    progress?: ProgressCallback;
+    /**
+     * Milliseconds one file's upload may take. A file that takes longer is aborted and counted as failed with
+     * the code 'TIMEOUT'; the next file is then uploaded. Every file gets the full time. Omitted or 0: no limit.
+     */
+    timeout?: number;
+    /**
+     * Reject at the first file storage does not accept, with that file's error (a SkapiError, see FileUploadError),
+     * instead of resolving with it listed in `failed` and `errors`. The files stored before it stay stored.
+     * Default false.
+     */
+    throwOnFileError?: boolean;
+};
 type FetchOptions = {
     /** Maximum number of records to fetch per call */
     limit?: number;
@@ -691,8 +744,9 @@ type Subscription = {
  */
 type TicketConditionOperator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
 /**
- * One row of a ticket condition list: `headers`, `data`, `params` or `user` of a ticket's
- * condition, or `headers`, `data` or `user` of a req action's response condition.
+ * One row of a ticket condition list: `headers`, `body`, `params` or `user` of a ticket's
+ * condition, the `response` rows of a cond action, or `headers`, `data` or `user` of the
+ * response condition Skapi's own rows carry.
  *
  * How a list decides:
  * - Rows on the same key are alternatives: the key passes when any one of them matches.
@@ -701,9 +755,14 @@ type TicketConditionOperator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'eq' | 'ne
  * - A field missing from the request is a mismatch for its key, '!=' included, not an error.
  *   The only rows that pass on a missing field are `= undefined` and `!= null`.
  * - Every row is read, in order. For each key the FIRST matching row wins: its `setValueWhenMatch`
- *   applies and its `placeholder` captures, and later rows on that key are skipped. A row that
- *   does not match captures nothing, so several rows on one key, each with its own
- *   `setValueWhenMatch`, followed by a catch-all row, work as a lookup table.
+ *   replaces the value (in the data itself where the field exists) and its `placeholder` captures
+ *   the result. The later match rows on that key are skipped without being evaluated, so nothing
+ *   is re-checked against the replaced value; a later row on another key whose path runs through
+ *   the replaced field reads the replacement. A row that does not match captures nothing, so
+ *   several rows on one key, each with its own `setValueWhenMatch`, followed by a catch-all row,
+ *   work as a lookup table. At the ticket's condition keys and values are literal: `${...}` inside
+ *   a row is plain text. In a cond action the key is literal but `value` and `setValueWhenMatch`
+ *   may hold `${response...}` and `${placeholder[NAME]}`, resolved before the comparison.
  * - A capture-only row (a `placeholder` and no `operator`) never counts toward passing. It
  *   captures whenever its field exists.
  * - Header names ignore case, and header values are always strings. Query string values are
@@ -711,7 +770,7 @@ type TicketConditionOperator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'eq' | 'ne
  *   `?code=LAUNCH24` the string "LAUNCH24". '=' is strict, so it compares the parsed value: a
  *   `params` row needs `value: 2`, not "2", to match `?qty=2`.
  *
- * null and undefined (`data` and `params` rows only, in a response condition too):
+ * null and undefined (`body` and `params` rows only, in a response condition too):
  * - `= null` passes when the field is present and null. `!= null` passes otherwise, a missing field included.
  * - `= undefined` passes when the field is missing. `!= undefined` passes when it is present, null included.
  * - '>', '>=', '<' and '<=' never pass with null or undefined.
@@ -721,7 +780,7 @@ type TicketConditionOperator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'eq' | 'ne
 type TicketConditionRow = {
     /**
      * Where the row looks, relative to its own list and written without `${ }`:
-     * - `data` rows: a path into the request body. "id" is the body's `id`, "order[id]" is `order.id`.
+     * - `body` rows: a path into the request body. "id" is the body's `id`, "order[id]" is `order.id`.
      * - `params` rows: a path into the query string, read the same way.
      * - `response` rows of a cond action: a path into the enclosing action's answer ("body[status]" is a response's body.status, "record_id" a posted record's id); "" is the whole answer as text.
      * - `headers` rows: the header name, matched case-insensitively.
@@ -735,13 +794,13 @@ type TicketConditionRow = {
     /**
      * A literal, never templated. A list is read as described in TicketConditionOperator.
      * null, a list containing null, and undefined (an `operator` with no `value` key) are for
-     * `data` and `params` rows only.
+     * `body` and `params` rows only.
      */
     value?: string | number | boolean | null | undefined | Array<string | number | boolean | null>;
-    /** `data` and `params` rows only. When this row is the first matching row of its key, the value at `key` in the request data is replaced by this before anything else reads it. null replaces nothing. */
+    /** `body` and `params` rows only. When this row is the first matching row of its key, the value at `key` in the request data is replaced by this before anything else reads it. null replaces nothing. */
     setValueWhenMatch?: any;
     /**
-     * `data` and `params` rows only. Remembers the value at `key` under this name, and the
+     * `body` and `params` rows only. Remembers the value at `key` under this name, and the
      * actions read it as `${placeholder[NAME]}`. A match row captures only when it is the first
      * matching row of its key. A field that is missing captures nothing. Must match
      * ^[A-Za-z_][A-Za-z0-9_]*$.
@@ -827,7 +886,8 @@ type TicketCondition = {
     /** Rows against the request headers. See TicketConditionRow. Every row compares with a value: null, or no `value`, is refused. */
     headers?: TicketConditionRow[];
     /** Rows against the request body. Refused when `method` is 'GET': a GET request has no body. */
-    data?: TicketConditionRow[];
+    /** Rows against the request body ("data" before 2026-10-09; registration still accepts that name and stores "body"). */
+    body?: TicketConditionRow[];
     /** Rows against the query string, read on GET and on POST. */
     params?: TicketConditionRow[];
     /**
@@ -848,9 +908,12 @@ type TicketCondition = {
  * Skapi's own billing rows only (the super master registers them): the response check a `req`
  * carried before 2026-10-09. Anyone else checks a response with a cond action in the req's
  * Then chain. `headers` rows read the response headers and `data` row keys are paths into the
- * parsed body; `user` and `record_access` check the consumer.
+ * parsed body (they keep that name here: the ticket's own body rows are `body`); `user` and
+ * `record_access` check the consumer.
  */
-type TicketResponseCondition = Pick<TicketCondition, 'headers' | 'data' | 'user' | 'record_access'>;
+type TicketResponseCondition = Pick<TicketCondition, 'headers' | 'user' | 'record_access'> & {
+    data?: TicketConditionRow[];
+};
 /**
  * One step of a ticket's action chain. Actions run in order. When an action fails its `err`
  * chain runs and the consumption stops. Nothing is rolled back.
@@ -863,7 +926,7 @@ type TicketResponseCondition = Pick<TicketCondition, 'headers' | 'data' | 'user'
  *
  * | Reference | Reads |
  * |---|---|
- * | `${data}`, `${data[key]}` | The incoming request body (a text body too), or one key of it: `${data[id]}` is the body's `id`, `${data[order][id]}` its `order.id`. Always the incoming body, also in nested actions. |
+ * | `${body}`, `${body[key]}` | The incoming request body (a text body too), or one key of it: `${body[id]}` is the body's `id`, `${body[order][id]}` its `order.id`. Always the incoming body, also in nested actions. |
  * | `${params}`, `${params[key]}` | The incoming query string, or one key of it. |
  * | `${headers[name]}` | An incoming header, name case-insensitive. Authorization and Cookie read "<redacted>". |
  * | `${placeholder[NAME]}` | A value a condition row captured with `placeholder`. |
@@ -878,7 +941,7 @@ type TicketResponseCondition = Pick<TicketCondition, 'headers' | 'data' | 'user'
  * Registration refuses anything else inside `${ }` (an unknown root such as `${id}`, keys under
  * a root that takes none such as `${ip[x]}`, `${placeholder}` or `${headers}` without a key,
  * broken brackets) with a message listing these forms, `${result}` (gone: an answer is read as
- * `${response}` in the action's Then chain, or captured there by a Condition action), and a reference written
+ * `${response}` in the action's Then chain, or captured there by a Check answer action), and a reference written
  * where it can never resolve (`${response}` outside a Then chain, `${error}` outside an `err`
  * chain, `${record_access}` when the condition names no record). When the action runs, a
  * reference that does not resolve fails it before it does anything: PATH_NOT_FOUND,
@@ -890,7 +953,9 @@ type TicketResponseCondition = Pick<TicketCondition, 'headers' | 'data' | 'user'
  * action in that chain checks the answer: its `response` rows read it whole (key "") or by key,
  * whatever its shape. `retry: true` on acsg, acsr, pstr, req, mail and nlsd tries a failure again,
  * up to 3 more times, 1, 2 and 4 seconds apart, while the time budget holds them; never for a
- * failure inside Then.
+ * failure inside Then, nor for a refusal waiting cannot change (a bad address, a missing template
+ * or newsletter, the month's e-mail sends used up). An e-mail or newsletter already queued is
+ * never sent twice: bookkeeping that fails afterwards is a `warning` on the log row, not a failure.
  */
 type TicketAction = {
     /** Set the access group of a user. Answers the SUCCESS text the grant returns. */
@@ -950,7 +1015,7 @@ type TicketAction = {
     act: 'req';
     exe: {
         /**
-         * http:// or https:// with a hostname, such as "https://api.example.com/orders/${data[id]}".
+         * http:// or https:// with a hostname, such as "https://api.example.com/orders/${body[id]}".
          * The scheme is always written out, so a URL that is one whole reference is refused.
          * No IP literal, no userinfo, never under the api domain. Redirects are not followed.
          * A value put into the URL with `${...}` is percent-encoded, so it cannot add path
@@ -1011,12 +1076,12 @@ type TicketAction = {
         };
         /** Legacy. Registration moves these rows to the end of `condition.data`. */
         match?: TicketConditionRow[];
-        /** Skapi's own billing rows only. A response check is a Condition action in `actions`, whose `response` rows read the answer. */
+        /** Skapi's own billing rows only. A response check is a Check answer action (cond) in `actions`, whose `response` rows read the answer. */
         condition?: TicketResponseCondition;
         /**
          * Nested chain, run on an answer below 300. It reads the response as `${response}`:
          * `${response[status]}`, `${response[headers][content-type]}` (header names in
-         * lowercase) and `${response[body][key]}`, while `${data}` is still the incoming
+         * lowercase) and `${response[body][key]}`, while `${body}` is still the incoming
          * request body. A cond in it checks the response. Any action can nest, including
          * another req with its own `secretName`.
          */
@@ -1035,10 +1100,10 @@ type TicketAction = {
     exe: {
         /** The template's ID, as the Custom tab and the upload reply show it. Literal; it must be stored when the ticket is registered. */
         template: string;
-        /** The recipient: one address, or a reference that gives one, such as "${user[email]}" or "${data[email]}". */
+        /** The recipient: one address, or a reference that gives one, such as "${user[email]}" or "${body[email]}". */
         to: string;
         /**
-         * Values for the placeholders the template carries, by name: { "order": "${data[order][id]}" } fills
+         * Values for the placeholders the template carries, by name: { "order": "${body[order][id]}" } fills
          * ${order}. Templated. "service_name" and "email" (the recipient) are filled by default and may be
          * overwritten here. Up to 30.
          */
@@ -1090,18 +1155,20 @@ type TicketAction = {
     err?: TicketAction[];
 } | {
     /**
-     * Condition: rows inside a chain, under the rules of the ticket's own condition. A part
-     * that fails fails the chain here with CONDITION_FAILED (the action's `err` chain runs).
-     * Answers nothing. `response` rows only inside a Then chain, `error` rows only inside an
-     * `err` chain, `placeholder` rows name placeholders (and may compare with null).
+     * Check answer: rows on the answer of the action whose Then chain this is, under the
+     * rules of the ticket's own condition rows. A key no row matches fails the chain here with
+     * CONDITION_FAILED (the enclosing action's `err` chain runs). Answers nothing. Inside a
+     * Then chain only.
      */
     act: 'cond';
     exe: {
         /**
          * Rows on the answer of the action whose Then chain this Condition is in, whatever its shape: a key is
          * a path in the answer ("record_id" on a posted record, "body[status]" or "headers[content-type]" on a
-         * response), "" the whole answer as text. A row that does not pass fails the chain here with
-         * CONDITION_FAILED. Inside a Then chain only; answers nothing.
+         * response), "" the whole answer as text. `value` and `setValueWhenMatch` may hold `${response...}` and
+         * `${placeholder[NAME]}`, resolved right before the comparison; any other reference is refused. A row's
+         * placeholder captures the replaced value when the row has one. A key no row matches fails the chain
+         * here with CONDITION_FAILED. Inside a Then chain only; answers nothing.
          */
         response: TicketConditionRow[];
     };
@@ -1198,6 +1265,7 @@ type Types_DelRecordQuery = DelRecordQuery;
 type Types_EncryptionOptions = EncryptionOptions;
 type Types_FetchOptions = FetchOptions;
 type Types_FileInfo = FileInfo;
+type Types_FileUploadError = FileUploadError;
 type Types_Form<T> = Form<T>;
 type Types_GetRecordQuery = GetRecordQuery;
 type Types_Index = Index;
@@ -1228,12 +1296,14 @@ type Types_TicketReceipt = TicketReceipt;
 type Types_TicketResponseCondition = TicketResponseCondition;
 type Types_TicketSignatureCondition = TicketSignatureCondition;
 type Types_UniqueId = UniqueId;
+type Types_UploadFilesParams = UploadFilesParams;
+type Types_UploadFilesResult = UploadFilesResult;
 type Types_UserAttributes = UserAttributes;
 type Types_UserProfile = UserProfile;
 type Types_UserPublic = UserPublic;
 type Types_WebSocketMessage = WebSocketMessage;
 declare namespace Types {
-  export type { Types_BinaryFile as BinaryFile, Types_Condition as Condition, Types_Connection as Connection, Types_ConnectionInfo as ConnectionInfo, Types_DatabaseResponse as DatabaseResponse, Types_DelRecordQuery as DelRecordQuery, Types_EncryptionOptions as EncryptionOptions, Types_FetchOptions as FetchOptions, Types_FileInfo as FileInfo, Types_Form as Form, Types_GetRecordQuery as GetRecordQuery, Types_Index as Index, Types_Newsletter as Newsletter, Types_NewsletterGroup as NewsletterGroup, Types_PostRecordConfig as PostRecordConfig, Types_ProgressCallback as ProgressCallback, Types_RTCConnector as RTCConnector, Types_RTCConnectorParams as RTCConnectorParams, Types_RTCEvent as RTCEvent, Types_RTCReceiverParams as RTCReceiverParams, Types_RTCResolved as RTCResolved, Types_RealtimeCallback as RealtimeCallback, Types_RecordData as RecordData, Types_RecordEncryptionInfo as RecordEncryptionInfo, Types_RequestHistory as RequestHistory, Types_Subscription as Subscription, Types_Table as Table, Types_Tag as Tag, Types_Ticket as Ticket, Types_TicketAction as TicketAction, Types_TicketCondition as TicketCondition, Types_TicketConditionOperator as TicketConditionOperator, Types_TicketConditionRow as TicketConditionRow, Types_TicketError as TicketError, Types_TicketErrorCode as TicketErrorCode, Types_TicketReceipt as TicketReceipt, Types_TicketResponseCondition as TicketResponseCondition, Types_TicketSignatureCondition as TicketSignatureCondition, Types_UniqueId as UniqueId, Types_UserAttributes as UserAttributes, Types_UserProfile as UserProfile, Types_UserPublic as UserPublic, Types_WebSocketMessage as WebSocketMessage };
+  export type { Types_BinaryFile as BinaryFile, Types_Condition as Condition, Types_Connection as Connection, Types_ConnectionInfo as ConnectionInfo, Types_DatabaseResponse as DatabaseResponse, Types_DelRecordQuery as DelRecordQuery, Types_EncryptionOptions as EncryptionOptions, Types_FetchOptions as FetchOptions, Types_FileInfo as FileInfo, Types_FileUploadError as FileUploadError, Types_Form as Form, Types_GetRecordQuery as GetRecordQuery, Types_Index as Index, Types_Newsletter as Newsletter, Types_NewsletterGroup as NewsletterGroup, Types_PostRecordConfig as PostRecordConfig, Types_ProgressCallback as ProgressCallback, Types_RTCConnector as RTCConnector, Types_RTCConnectorParams as RTCConnectorParams, Types_RTCEvent as RTCEvent, Types_RTCReceiverParams as RTCReceiverParams, Types_RTCResolved as RTCResolved, Types_RealtimeCallback as RealtimeCallback, Types_RecordData as RecordData, Types_RecordEncryptionInfo as RecordEncryptionInfo, Types_RequestHistory as RequestHistory, Types_Subscription as Subscription, Types_Table as Table, Types_Tag as Tag, Types_Ticket as Ticket, Types_TicketAction as TicketAction, Types_TicketCondition as TicketCondition, Types_TicketConditionOperator as TicketConditionOperator, Types_TicketConditionRow as TicketConditionRow, Types_TicketError as TicketError, Types_TicketErrorCode as TicketErrorCode, Types_TicketReceipt as TicketReceipt, Types_TicketResponseCondition as TicketResponseCondition, Types_TicketSignatureCondition as TicketSignatureCondition, Types_UniqueId as UniqueId, Types_UploadFilesParams as UploadFilesParams, Types_UploadFilesResult as UploadFilesResult, Types_UserAttributes as UserAttributes, Types_UserProfile as UserProfile, Types_UserPublic as UserPublic, Types_WebSocketMessage as WebSocketMessage };
 }
 
 declare function terminatePendingRequests(): void;
@@ -2867,19 +2937,14 @@ declare class Skapi {
         endpoints: string | string[];
     }): Promise<RecordData[]>;
     /**
-     * Uploads files to an existing record and returns completed and failed results.
+     * Uploads files to an existing record. Resolves with the files stored (`completed`), the files storage did not accept (`failed`) and why (`errors`, one entry per failed file with a SkapiError that carries the storage code).
+     * `timeout` (milliseconds) aborts a file that takes longer and counts it as failed with the code 'TIMEOUT'; by default a file has no time limit.
+     * `throwOnFileError` rejects at the first file that fails, with that file's error, instead of resolving; the files stored before it stay stored.
      * @param fileList Files or form event containing files.
      * @param params Request parameters.
-     * @returns A promise that resolves to Promise<{ completed: File[], failed: File[], bin_endpoints: string[] }>.
+     * @returns A promise that resolves to Promise<UploadFilesResult>.
      */
-    uploadFiles(fileList: FormData | HTMLFormElement | SubmitEvent, params: {
-        record_id: string;
-        progress?: ProgressCallback;
-    }): Promise<{
-        completed: File[];
-        failed: File[];
-        bin_endpoints: string[];
-    }>;
+    uploadFiles(fileList: FormData | HTMLFormElement | SubmitEvent, params: UploadFilesParams): Promise<UploadFilesResult>;
     /**
      * Calls the mock endpoint for testing request and error handling flows.
      * @param data Data payload for the request.
@@ -3145,15 +3210,4 @@ declare class Skapi {
     bulkPostRecords(config: PostRecordConfig[]): Promise<RecordData[]>;
 }
 
-declare class SkapiError extends Error {
-    code: string | number;
-    /** The underlying Error, or the flat TicketError body of a failed ticket consumption (consumeTicket). */
-    cause: Error | TicketError;
-    constructor(error: any, options?: {
-        name?: string;
-        code?: string;
-        cause?: Error | TicketError;
-    });
-}
-
-export { type BinaryFile, type Condition, type Connection, type ConnectionInfo, type DatabaseResponse, type DelRecordQuery, type FetchOptions, type FileInfo, type Form, type GetRecordQuery, type Index, type Newsletter, type NewsletterGroup, type PostRecordConfig, type ProgressCallback, type RTCConnector, type RTCConnectorParams, type RTCEvent, type RTCReceiverParams, type RTCResolved, type RealtimeCallback, type RecordData, Skapi, SkapiError, type Subscription, type Table, type Tag, type Ticket, type TicketAction, type TicketCondition, type TicketConditionOperator, type TicketConditionRow, type TicketError, type TicketErrorCode, type TicketReceipt, type TicketResponseCondition, type TicketSignatureCondition, Types, type UniqueId, type UserAttributes, type UserProfile, type UserPublic, type WebSocketMessage };
+export { type BinaryFile, type Condition, type Connection, type ConnectionInfo, type DatabaseResponse, type DelRecordQuery, type FetchOptions, type FileInfo, type FileUploadError, type Form, type GetRecordQuery, type Index, type Newsletter, type NewsletterGroup, type PostRecordConfig, type ProgressCallback, type RTCConnector, type RTCConnectorParams, type RTCEvent, type RTCReceiverParams, type RTCResolved, type RealtimeCallback, type RecordData, Skapi, SkapiError, type Subscription, type Table, type Tag, type Ticket, type TicketAction, type TicketCondition, type TicketConditionOperator, type TicketConditionRow, type TicketError, type TicketErrorCode, type TicketReceipt, type TicketResponseCondition, type TicketSignatureCondition, Types, type UniqueId, type UploadFilesParams, type UploadFilesResult, type UserAttributes, type UserProfile, type UserPublic, type WebSocketMessage };