skapi-js 2.0.3 → 2.1.0

package/dist/skapi.d.mts

@@ -572,7 +572,9 @@ type RequestHistory = {
     compact?: boolean;
     poll?: (arg?: {
         latency?: number;
-        onResponse?: (res: any) => void;
+        onResponse?: (res: any, meta?: {
+            executed?: number;
+        }) => void;
         onError?: (err: any) => void;
         onStream?: (chunk: string, seq: number) => void;
     }) => Promise<any>;
@@ -658,6 +660,243 @@ type Subscription = {
     get_notified: boolean;
     get_email: boolean;
 };
+/** Comparison operator of a ticket condition row. The word forms are normalized to the symbols on registration. For a string value, '>=' means "starts with". */
+type TicketConditionOperator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
+/**
+ * One row of a ticket condition list (`headers`, `data`, `params`, `user`, `match`).
+ * Rows with the same key are alternatives (any one matching satisfies the key), rows with
+ * different keys must all match. A comparison between incompatible types is a mismatch.
+ */
+type TicketConditionRow = {
+    /**
+     * `data` and `params` rows: a path into the request, such as "data[object][id]" (the leading
+     * "data" there is the request's own key, not the row list). `headers` rows: the header name,
+     * matched case-insensitively. `user` rows: the consumer attribute name. Never templated.
+     */
+    key: string;
+    /** Absent, with no `value`, on a capture-only row: it never fails and only fills `placeholder`. */
+    operator?: TicketConditionOperator;
+    /** A literal, never templated. A list passes when any member matches. */
+    value?: any;
+    /** `data` and `params` rows only. When the row matches, the value at `key` in the request data is replaced by this before anything else reads it. */
+    setValueWhenMatch?: any;
+    /** `data` and `params` rows only. Remembers the value at `key` under this name for the actions ("placeholder[NAME]"). Must match ^[A-Za-z_][A-Za-z0-9_]*$. */
+    placeholder?: string;
+};
+/** An HTTP call whose response must match. `url`, `headers`, `data` and `params` are templated like an action's `exe`; `match` rows are not. */
+type TicketRequestCondition = {
+    /** http:// or https:// with a hostname. No IP literal, no userinfo, never under the api domain. */
+    url: string;
+    method?: 'GET' | 'POST';
+    headers?: {
+        [name: string]: string;
+    };
+    /** Sent as JSON when a content-type header says application/json, else form encoded. */
+    data?: any;
+    params?: {
+        [key: string]: any;
+    };
+    /** Rows matched against the response body. */
+    match?: TicketConditionRow[];
+};
+/**
+ * An HMAC signature over the request, computed with a secret shared with the sender. Verified
+ * before anything else runs: the `timestamp` (when set) must be an integer within `tolerance` of
+ * now, the bytes described by `signed` are signed with the stored secret (`secret_prefix` removed,
+ * then decoded per `secret_encoding`), and the result is compared in constant time against every
+ * `${signature}` captured from the header. Any failure is a plain mismatch.
+ *
+ * Templates (`signed`, `timestamp`) are literal text with these tokens: `${body}` (the raw request
+ * body exactly as received), `${method}` (the HTTP method, upper case), `${header:Name}` (a request
+ * header, case-insensitive; an absent header fails verification) and any capture from `parts` other
+ * than `${signature}`. An unknown token is refused at registration.
+ *
+ * Public-key signature schemes (RSA, ECDSA, Ed25519) are not supported.
+ */
+type TicketSignatureCondition = {
+    /** The name of a Secret Key of the project, never the secret itself. Must exist at registration. */
+    secret: string;
+    /** The request header carrying the signature. Case-insensitive. Up to 256 characters. */
+    header: string;
+    /** Default 'sha256'. */
+    algorithm?: 'sha256' | 'sha1' | 'sha512';
+    /** How the signature value in the header is encoded. Default 'hex'. */
+    encoding?: 'hex' | 'base64';
+    /** Splits the header value into items, each trimmed. 1 to 8 characters. Absent: the whole header value is one item. */
+    separator?: string;
+    /**
+     * Patterns matched against each header item, in order; the first whose literal text fits
+     * captures the rest. Each pattern is literal text with at most one `${name}` capture (letters,
+     * digits and _; not `body` or `method`). `${signature}` may be captured by several items (any one matching passes) and
+     * must appear in at least one pattern; any other name becomes a token for the templates (the
+     * first capture wins). Items that match no pattern are ignored. Up to 10 patterns of up to 256
+     * characters each. Default ["${signature}"].
+     */
+    parts?: string[];
+    /** Template of the signed bytes. Up to 512 characters. Default "${body}". */
+    signed?: string;
+    /** Template resolving to unix time, in seconds or in milliseconds (a value above 10^12). Up to 512 characters. Absent: no timestamp check. */
+    timestamp?: string;
+    /** Seconds the timestamp may be away from now, 1 to 86400. Only used with `timestamp`. Default 300. */
+    tolerance?: number;
+    /** How the stored secret becomes the HMAC key bytes. Default 'raw'. */
+    secret_encoding?: 'raw' | 'base64' | 'hex';
+    /** Removed from the start of the stored secret before decoding. Up to 64 characters. */
+    secret_prefix?: string;
+};
+/** What a consumption request must look like before the ticket's actions run. Evaluated in the order the keys are listed here; the first failure is the reported one. */
+type TicketCondition = {
+    /** Answer HTTP 200 even when the consumption fails. For webhooks that retry on errors. */
+    return200?: boolean;
+    /** Absent = both allowed. */
+    method?: 'GET' | 'POST';
+    /** Verified first, over the raw request body. See TicketSignatureCondition. */
+    signature?: TicketSignatureCondition;
+    ip?: {
+        operator: TicketConditionOperator;
+        value: string | string[];
+    };
+    user_agent?: {
+        operator: TicketConditionOperator;
+        value: string | string[];
+    };
+    headers?: TicketConditionRow[];
+    /** Rows against the POST body. On a GET the body root is {}. */
+    data?: TicketConditionRow[];
+    /** Rows against the GET query string. On a POST the query root is {}. */
+    params?: TicketConditionRow[];
+    /** Rows against the consumer's attributes (user_id, email, access_group, ...). Signed-in consumption only. */
+    user?: TicketConditionRow[];
+    /** Record ID the consumer must own or have been granted. Signed-in consumption only. */
+    record_access?: string;
+    request?: TicketRequestCondition;
+};
+/** The subset of a condition a `req` action can evaluate against its response. A response has no method, query string or status policy. */
+type TicketResponseCondition = Pick<TicketCondition, 'headers' | 'data' | 'user' | 'record_access' | 'request'>;
+/**
+ * One step of a ticket's action chain. Actions run in order; each one's result is readable by
+ * the next as "result[...]". `exe` is templated right before the action runs: a string that is
+ * a whole path ("data[object][id]", "placeholder[NAME]") keeps the value's type, "${...}" inside
+ * text becomes a string, bare words are literal. When an action fails its `err` chain runs
+ * (with "error[code]", "error[message]", ...) and the consumption stops. Nothing is rolled back.
+ */
+type TicketAction = {
+    /** Update a Skapi service. Internal: registration refuses it unless the caller is a Skapi super master. */
+    act: 'srvc';
+    exe: {
+        [key: string]: any;
+    };
+    err?: TicketAction[];
+} | {
+    /** Set the access group of a user. */
+    act: 'acsg';
+    exe: {
+        /** 1 ~ 99, or "admin". */
+        group: number | 'admin';
+        /** Blank = the consumer (signed-in consumption only). The project owner cannot be a target. */
+        user_id?: string;
+    };
+    err?: TicketAction[];
+} | {
+    /** Grant private access to a record. */
+    act: 'acsr';
+    exe: {
+        /** A record ID, not a unique ID. */
+        record_id: string;
+        /** Blank = the consumer. */
+        user_id?: string | string[];
+    };
+    err?: TicketAction[];
+} | {
+    /** Post a record. Everything but `user_id` is the payload postRecord() sends, so the same rules apply. A `unique_id` makes a retried webhook update the same record instead of adding one. */
+    act: 'pstr';
+    exe: {
+        table: string | {
+            name: string;
+            access_group?: number | 'public' | 'authorized' | 'admin' | 'private';
+            subscription?: NonNullable<PostRecordConfig['table']>['subscription'];
+        };
+        data?: any;
+        index?: {
+            name: string;
+            value: string | number | boolean;
+        };
+        tags?: string[];
+        unique_id?: string;
+        /** Update instead of create. */
+        record_id?: string;
+        reference?: string;
+        readonly?: boolean;
+        source?: PostRecordConfig['source'];
+        /** Post as this user instead of the project owner. */
+        user_id?: string;
+    };
+    err?: TicketAction[];
+} | {
+    /** HTTP request with its own response condition and nested chain. Result: the parsed response body. */
+    act: 'req';
+    exe: {
+        /** http:// or https:// with a hostname. No IP literal, no userinfo, never under the api domain. Redirects are not followed. */
+        url: string;
+        /** Default GET. */
+        method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+        headers?: {
+            [name: string]: string;
+        };
+        /** POST and PUT body. Sent as JSON when a content-type header says application/json, else form encoded. */
+        data?: any;
+        /** Query string. */
+        params?: {
+            [key: string]: any;
+        };
+        /** Legacy. Rows matched against the response body like `condition.data`. */
+        match?: TicketConditionRow[];
+        /** Evaluated against the response. Captures land in the shared placeholder pool. */
+        condition?: TicketResponseCondition;
+        /** Nested chain. Its paths read the response body. */
+        actions?: TicketAction[];
+    };
+    err?: TicketAction[];
+};
+/** An issued ticket as getTickets() and registerTicket() return it. */
+type Ticket = {
+    ticket_id: string;
+    description?: string;
+    /** Remaining consumptions. Absent = unlimited. */
+    count?: number;
+    /** Absolute expiry in ms since epoch. Absent = never. */
+    time_to_live?: number;
+    /** true = once per user, n = n times. Absent or 0 = unlimited. Only enforced for signed-in consumers. */
+    limit_per_user?: boolean | number;
+    /** Created at (ms). */
+    timestamp: number;
+    /** Last registered at (ms). */
+    updated?: number;
+    condition?: TicketCondition;
+    actions?: TicketAction[];
+};
+type TicketErrorCode = 'INVALID_SERVICE' | 'SERVICE_DISABLED' | 'TICKET_NOT_FOUND' | 'TICKET_EXPIRED' | 'TICKET_EXHAUSTED' | 'USER_LIMIT_REACHED' | 'ISSUER_CANNOT_CONSUME' | 'AUTH_REQUIRED' | 'METHOD_NOT_ALLOWED' | 'CONDITION_FAILED' | 'PATH_NOT_FOUND' | 'PLACEHOLDER_MISSING' | 'REQUEST_FAILED' | 'TIMEOUT' | 'ACTION_FAILED' | 'ACTION_FORBIDDEN' | 'INTERNAL_ERROR';
+/**
+ * The body a consume endpoint answers with when the consumption fails, and the `cause` of the
+ * SkapiError consumeTicket() rejects with. A success body never has `stage`; an error body
+ * always does, also when the ticket answers HTTP 200 (`return200`).
+ */
+type TicketError = {
+    code: TicketErrorCode;
+    /** Human readable, one sentence. */
+    message: string;
+    stage: 'ticket' | 'condition' | 'action';
+    /** Only when stage is "action": the action that failed and its place in the chain, such as "actions[1].err[0]". */
+    action?: {
+        act: TicketAction['act'];
+        path: string;
+    };
+    /** Code specific, JSON safe. For example { expired_at } on TICKET_EXPIRED, { field, keys } on CONDITION_FAILED, { status, body } on REQUEST_FAILED. */
+    detail?: {
+        [key: string]: any;
+    };
+    ticket_id: string;
+};
 
 type Types_BinaryFile = BinaryFile;
 type Types_Condition = Condition;
@@ -687,13 +926,23 @@ type Types_RequestHistory = RequestHistory;
 type Types_Subscription = Subscription;
 type Types_Table = Table;
 type Types_Tag = Tag;
+type Types_Ticket = Ticket;
+type Types_TicketAction = TicketAction;
+type Types_TicketCondition = TicketCondition;
+type Types_TicketConditionOperator = TicketConditionOperator;
+type Types_TicketConditionRow = TicketConditionRow;
+type Types_TicketError = TicketError;
+type Types_TicketErrorCode = TicketErrorCode;
+type Types_TicketRequestCondition = TicketRequestCondition;
+type Types_TicketResponseCondition = TicketResponseCondition;
+type Types_TicketSignatureCondition = TicketSignatureCondition;
 type Types_UniqueId = UniqueId;
 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_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_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_TicketRequestCondition as TicketRequestCondition, 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 };
 }
 
 declare function terminatePendingRequests(): void;
@@ -946,6 +1195,18 @@ declare class Skapi {
     }): Promise<string | void>;
     /**
      * Queries unique ID records by unique_id or condition filters.
+     *
+     * Refused to a signed out caller when the project's `require_login`
+     * setting is on: REQUIRE_LOGIN from the SDK, INVALID_REQUEST from the
+     * backend for a caller that skips it. A project that has never set the
+     * flag counts as ON. This listing used to be served to anyone who knew
+     * the project id, and called with no `unique_id` it enumerates every
+     * unique ID in the project.
+     *
+     * The listing is NOT filtered by access group: a row is keyed by the
+     * unique ID alone, so any caller who gets past the sign in check sees the
+     * IDs of records in every group, each with the record ID it maps to.
+     * Fetching those records still goes through the usual access checks.
      * @param params Request parameters.
      * @param fetchOptions Pagination and fetch behavior options.
      * @returns A promise that resolves to Promise<DatabaseResponse<UniqueId>>.
@@ -989,6 +1250,23 @@ declare class Skapi {
     openIdLogin(params: {
         token: string;
         id: string;
+        /**
+         * Merges this OpenID identity into the existing account whose ORIGINAL login
+         * ID (its username, or the e-mail it was created with when it has none) is
+         * this OpenID account's login ID. `true` merges; an array of OpenID attribute
+         * names also copies those attributes to the account. Merging replaces the
+         * account's password.
+         *
+         * Never merges through an e-mail login alias. openIdLogin() fails with EXISTS,
+         * with or without merge, when this OpenID account's login ID is the verified
+         * e-mail login of another account of the project (an account created with a
+         * username, or one whose e-mail was changed to it), and in the rare case the
+         * alias cannot be removed safely. Any other account holding that login ID as an
+         * e-mail login alias has not verified the e-mail, so it loses the alias instead
+         * and a new OpenID account is created for this login ID: the two accounts then
+         * share the e-mail address. The alias is removed before signup restrictions are
+         * checked, so it is gone even when the login is then refused for another reason.
+         */
         merge?: boolean | string[];
         template?: {
             /** message_id of the template to use for the welcome e-mail (sent the first time this OpenID user account is created). */
@@ -1033,9 +1311,12 @@ declare class Skapi {
         group: string;
     }>): Promise<string>;
     /**
+     * **Deprecated. Use `forwardRequest(form, options)` instead.**
+     *
      * Sends a secure outbound request using a Skapi client secret key.
      * @param params Request parameters.
      * @returns A promise that resolves to the final API response, or to a status object when the request is queued.
+     * @deprecated Use forwardRequest(form, options), which takes the form as its first argument and makes the client secret optional. This name keeps working unchanged, and both dispatch the same request through the same code.
      */
     clientSecretRequest(params: {
         url: string;
@@ -1068,6 +1349,8 @@ declare class Skapi {
         }) => Promise<any>;
     }>;
     /**
+     * **Deprecated. Use `forwardRequestHistory` instead, which is this same function.**
+     *
      * Retrieves the history of client secret requests for a given URL and method.
      *
      * Listing modifiers: `compact` returns lightweight label/marker stubs
@@ -1081,6 +1364,7 @@ declare class Skapi {
      * @param params Request parameters.
      * @param fetchOptions Pagination and fetch behavior options.
      * @returns A promise that resolves to a paginated list of request history items.
+     * @deprecated Use forwardRequestHistory, which is this same function. A request started under either name is listed by both.
      */
     clientSecretRequestHistory(params: {
         url: string;
@@ -1092,11 +1376,8 @@ declare class Skapi {
         queue_exclude?: string;
     }, fetchOptions?: FetchOptions): Promise<DatabaseResponse<RequestHistory[]>>;
     /**
-     * Cancels a pending client secret request and removes it from the client-side queue if applicable.
-     * @param params Request parameters.
-     * @returns A promise that resolves to a result object with removed status and message.
-     */
-    /**
+     * **Deprecated. Use `forwardRequestStream` instead, which is this same function.**
+     *
      * Reads a streamed clientSecretRequest that this call did not start: a page reload,
      * a second tab, or a turn from history that was never finalized.
      *
@@ -1115,6 +1396,7 @@ declare class Skapi {
      *     onStream: (chunk) => parser.feed(chunk)
      * });
      * ```
+     * @deprecated Use forwardRequestStream, which is this same function.
      */
     clientSecretRequestStream(requestId: string, options: {
         url?: string;
@@ -1128,6 +1410,8 @@ declare class Skapi {
         owner?: string;
     }): Promise<any>;
     /**
+     * **Deprecated. Use `forwardRequestFinalize` instead, which is this same function.**
+     *
      * Stores the version of a streamed response you want KEPT as history, and releases
      * the relayed chunks it was assembled from.
      *
@@ -1143,6 +1427,7 @@ declare class Skapi {
      *     method: 'POST'
      * });
      * ```
+     * @deprecated Use forwardRequestFinalize, which is this same function.
      */
     clientSecretRequestFinalize(requestId: string, data?: any, options?: {
         url?: string;
@@ -1153,6 +1438,14 @@ declare class Skapi {
         finalized: boolean;
         message: string;
     }>;
+    /**
+     * **Deprecated. Use `cancelForwardRequest` instead, which is this same function.**
+     *
+     * Cancels a pending client secret request and removes it from the client-side queue if applicable.
+     * @param params Request parameters.
+     * @returns A promise that resolves to a result object with removed status and message.
+     * @deprecated Use cancelForwardRequest, which is this same function.
+     */
     cancelClientSecretRequest(params: {
         url: string;
         method: 'GET' | 'POST' | 'DELETE' | 'PUT';
@@ -1163,6 +1456,8 @@ declare class Skapi {
         message: string;
     }>;
     /**
+     * **Deprecated. Use `stopForwardRequestPolling` instead, which is this same function.**
+     *
      * Stops live polling for client secret requests without cancelling the requests
      * themselves. The server-side work continues; only this client stops asking about it.
      *
@@ -1178,6 +1473,7 @@ declare class Skapi {
      *
      * @param params Which polls to stop.
      * @returns The number of polls stopped.
+     * @deprecated Use stopForwardRequestPolling, which is this same function.
      */
     stopClientSecretPolling(params?: {
         url?: string;
@@ -1188,14 +1484,18 @@ declare class Skapi {
         owner?: string;
     }): number;
     /**
-     * True if a poll result came from stopClientSecretPolling rather than the server.
+     * True if a poll result came from stopForwardRequestPolling (or its deprecated alias
+     * stopClientSecretPolling) rather than the server.
      * @param res A resolved poll result.
      */
     isPollStopped(res: any): boolean;
     /**
+     * **Deprecated. Use `forwardRequestQueueCount` instead, which is this same function.**
+     *
      * Returns the number of requests currently waiting in a named client secret request queue.
      * @param params Request parameters.
      * @returns A promise that resolves to queue count information.
+     * @deprecated Use forwardRequestQueueCount, which is this same function.
      */
     clientSecretRequestQueueCount(params: {
         queue: string;
@@ -1206,34 +1506,191 @@ declare class Skapi {
         in_queue: number;
     }>;
     /**
-     * Consumes a one-time ticket and executes the ticketed request payload.
+     * Lists forwarded requests for a given url and method, newest first.
+     *
+     * Listing modifiers: `compact` returns lightweight label/marker stubs
+     * (request_text, response_text, response_complete_marker) instead of the
+     * full request/response bodies, which stay on the server; `queue_exact`
+     * restricts a queue listing to exactly the named queue (the queue lookup is
+     * otherwise a prefix range, so queue "u1" would also match "u1-bg");
+     * `queue_exclude` drops one queue's rows from the listing. Both queue
+     * filters are applied server-side after the range read, so a page can come
+     * back short while more matches remain - keep paging by startKey/endOfList.
+     *
+     * The same function as the deprecated clientSecretRequestHistory, so a request
+     * sent under either name is listed here.
      * @param params Request parameters.
-     * @returns A promise that resolves to Promise<any>.
+     * @param fetchOptions Pagination and fetch behavior options.
+     * @returns A promise that resolves to a paginated list of request history items.
+     */
+    forwardRequestHistory(params: {
+        url: string;
+        method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+        queue?: string;
+        status?: 'pending' | 'running' | 'resolved' | 'failed';
+        compact?: boolean;
+        queue_exact?: boolean;
+        queue_exclude?: string;
+    }, fetchOptions?: FetchOptions): Promise<DatabaseResponse<RequestHistory[]>>;
+    /**
+     * Reads a streamed forwardRequest that this call did not start: a page reload,
+     * a second tab, or a turn from history that was never finalized.
+     *
+     * `onStream` receives the relayed text in order, exactly as the destination sent it.
+     * skapi does not parse it; whatever grammar those bytes are in belongs to the caller
+     * and its destination. Pass `since` to resume rather than re-read from the beginning.
+     *
+     * When the request is still running this polls until it settles. When it has already
+     * settled it reads every chunk once and resolves.
+     *
+     * ```js
+     * const parser = createMyParser();
+     * await skapi.forwardRequestStream(requestId, {
+     *     url: 'https://api.example.com/v1/chat',
+     *     method: 'POST',
+     *     onStream: (chunk) => parser.feed(chunk)
+     * });
+     * ```
+     */
+    forwardRequestStream(requestId: string, options: {
+        url?: string;
+        method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+        onStream?: (chunk: string, seq: number, via?: 'socket' | 'poll') => void;
+        since?: number;
+        poll?: number;
+        realtimeGroup?: string;
+        onResponse?: (res: any) => void;
+        onError?: (err: any) => void;
+        service?: string;
+        owner?: string;
+    }): Promise<any>;
+    /**
+     * Stores the version of a streamed response you want KEPT as history, and releases
+     * the relayed chunks it was assembled from.
+     *
+     * The content is entirely yours. skapi neither validates nor interprets it: it stores
+     * what you tell it to store. Only the caller who made the request may finalize it.
+     *
+     * Until you finalize, the chunks stay indefinitely and every read of that turn has to
+     * fetch and re-parse all of them, so finalize as soon as you have rendered the answer.
+     *
+     * ```js
+     * await skapi.forwardRequestFinalize(requestId, parser.result(), {
+     *     url: 'https://api.example.com/v1/chat',
+     *     method: 'POST'
+     * });
+     * ```
+     */
+    forwardRequestFinalize(requestId: string, data?: any, options?: {
+        url?: string;
+        method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+        service?: string;
+        owner?: string;
+    }): Promise<{
+        finalized: boolean;
+        message: string;
+    }>;
+    /**
+     * Cancels a queued forwarded request and removes it from the client-side queue if applicable.
+     * @param params Request parameters.
+     * @returns A promise that resolves to a result object with removed status and message.
+     */
+    cancelForwardRequest(params: {
+        url: string;
+        method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+        id: string;
+        queue?: string;
+    }): Promise<{
+        removed: boolean;
+        message: string;
+    }>;
+    /**
+     * Stops live polling of forwarded requests without cancelling the requests
+     * themselves. The server-side work continues; only this client stops asking about it.
+     *
+     * Use it to drop polling traffic while the user is not looking at the results (a
+     * hidden tab, a closed view), then simply poll again when they return. Polls run
+     * one-at-a-time per queue, so a poll for a request that never settles otherwise
+     * blocks every poll queued behind it.
+     *
+     * Pass `id` (with `url` and `method`) to stop one request, `queue` to stop a queue's
+     * polls, or neither to stop all of them. A stopped poll resolves with
+     * `{ id, status: 'stopped' }` rather than rejecting, and its `onResponse`/`onError`
+     * callbacks are not called.
+     *
+     * @param params Which polls to stop.
+     * @returns The number of polls stopped.
+     */
+    stopForwardRequestPolling(params?: {
+        url?: string;
+        method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+        id?: string;
+        queue?: string;
+        service?: string;
+        owner?: string;
+    }): number;
+    /**
+     * Returns the number of requests currently waiting in a named forward request queue.
+     * @param params Request parameters.
+     * @returns A promise that resolves to queue count information.
+     */
+    forwardRequestQueueCount(params: {
+        queue: string;
+        service?: string;
+        owner?: string;
+    }): Promise<{
+        queue_name: string;
+        in_queue: number;
+    }>;
+    /**
+     * Consumes a ticket: calls its endpoint with `data`, so the ticket's condition is checked and
+     * its actions run. An anonymous POST goes to `/tp/`, an anonymous GET to `/tg/` with `data`
+     * as the query string, and a signed-in consumption (`auth: true`) to `/tpa/`, which is POST only.
+     *
+     * A failed consumption rejects with a SkapiError: `err.code` is the ticket error code and
+     * `err.cause` the flat TicketError body (`err.cause.stage`, `err.cause.action`, `err.cause.detail`).
+     * This holds when the ticket answers HTTP 200 as well (`return200`): the body is inspected, not the status.
+     * @param params Request parameters.
+     * @returns A promise that resolves to Promise<{ ticket_id: string; consume_id: string; user_id: string; is_test: boolean; timestamp: number; hash: string; }>.
      */
     consumeTicket(params: {
+        /** ID of the ticket to consume. */
         ticket_id: string;
-        method: string;
+        /** "GET" or "POST". */
+        method: 'GET' | 'POST';
+        /** Consume as the signed-in user. POST only. */
         auth?: boolean;
+        /** The POST body, or the query string of a GET. */
         data?: {
             [key: string]: any;
         };
-    }): Promise<any>;
+    }): Promise<{
+        ticket_id: string;
+        consume_id: string;
+        user_id: string;
+        is_test: boolean;
+        timestamp: number;
+        hash: string;
+    }>;
     /**
-     * Lists consumed tickets with optional filters and pagination.
+     * Lists the tickets the signed-in user has consumed, with optional filters and pagination.
      * @param params Request parameters.
      * @param fetchOptions Pagination and fetch behavior options.
      * @returns A promise that resolves to Promise<DatabaseResponse<any>>.
      */
     getConsumedTickets(params: {
+        /** Only the consumptions of this ticket. */
         ticket_id?: string;
     }, fetchOptions?: FetchOptions): Promise<DatabaseResponse<any>>;
     /**
      * Lists issued tickets with optional filters and pagination.
+     * The project owner gets the full ticket (condition, actions, count, expiry, per-user limit); any other signed-in user gets `ticket_id`, `description`, `count`, `time_to_live` and `timestamp` only.
      * @param params Request parameters.
      * @param fetchOptions Pagination and fetch behavior options.
      * @returns A promise that resolves to Promise<DatabaseResponse<any>>.
      */
     getTickets(params: {
+        /** Absent = every ticket. "<id>" = that ticket. "#<id>#" = the consumption log of that ticket (project owner only). */
         ticket_id?: string;
     }, fetchOptions?: FetchOptions): Promise<DatabaseResponse<any>>;
     /**
@@ -1290,30 +1747,71 @@ declare class Skapi {
         user_id: string;
     }): Promise<'SUCCESS: Account has been deleted.'>;
     /**
-     * Invites a user by email with optional attributes and invitation email options.
-     * @param params Payload for the request.
-     * @param options Optional behavior configuration.
+     * Invites a user by e-mail. The invitation carries a temporary password and a
+     * link to accept, valid for 7 days. Admin only (access_group 90 and above).
+     *
+     * Every profile attribute passed in `params` is written to the account when the
+     * invitation is sent and is kept unchanged when the user accepts; accepting only
+     * activates the account and marks its e-mail verified.
+     *
+     * Refused with EXISTS when the e-mail, or the username when one is given, is
+     * already another account's login ID, and with EXISTS "User is already
+     * invited." while the e-mail has a pending invitation.
+     * @param params The invited user's e-mail, and optionally their profile.
+     * @param options Where to send them after accepting, newsletter opt-in, and a custom template.
      * @returns A promise that resolves to Promise<'SUCCESS: Invitation has been sent. (User ID: xxx...)'>.
      */
     inviteUser(params: UserAttributes & {
+        /** Required. The invitation, with the temporary password and the link to accept, is sent here. */
+        email: string;
+        /**
+         * Optional. Becomes the invited account's PERMANENT login username and
+         * can never be changed. The e-mail also logs the account in once the
+         * invitation is accepted (best effort), not while it is pending. Refused
+         * with EXISTS when the username or the e-mail is already another
+         * account's login ID.
+         */
+        username?: string;
+        /** ID of an OpenID logger registered in the project, to link the invited account to it. */
         openid_id?: string;
+        /** 1~99. Defaults to 1. 99 is admin level. */
         access_group?: number;
     }, options?: {
+        /** URL the user is taken to after accepting. Must not contain "#". */
         confirmation_url?: string;
+        /**
+         * Subscribe the user to Service Email (group 1) once they accept.
+         * Requires `confirmation_url`. Defaults to false.
+         */
         email_subscription?: boolean;
+        /** A custom HTML template for this invitation e-mail. Both fields are required. */
         template?: {
+            /** URL of the HTML template. Must include the required invitation placeholders. */
             url: string;
+            /** Subject line of the e-mail. */
             subject: string;
         };
     }): Promise<'SUCCESS: Invitation has been sent. (User ID: xxx...)'>;
     /**
      * Creates a user account directly from admin context.
+     *
+     * Refused with EXISTS when the e-mail, or the username when one is given, is
+     * already another account's login ID.
      * @param params Payload for the request.
      * @returns A promise that resolves to Promise<UserProfile & { email_admin: string; username: string; }>.
      */
     createAccount(params: UserAttributes & {
+        /** Required. Always. */
         email: string;
         password: string;
+        /**
+         * Optional. Becomes the account's PERMANENT login username, which
+         * always logs the account in. The e-mail is created unverified, so it
+         * logs the account in only once the user verifies it with verifyEmail()
+         * after logging in with the username. Refused with EXISTS when the
+         * username or the e-mail is already another account's login ID.
+         */
+        username?: string;
         access_group?: number;
     }): Promise<UserProfile & {
         email_admin: string;
@@ -1331,6 +1829,29 @@ declare class Skapi {
     /**
      * Updates another user's profile attributes from admin context.
      * Requires the target user's user_id plus at least one attribute to update.
+     *
+     * Never the caller's own account, the project owner and access group 99 admins
+     * included: the caller's own user_id is refused with INVALID_REQUEST and
+     * 'Cannot modify attributes of the current user.' before any request is sent.
+     * Change your own profile with updateProfile() without user_id.
+     *
+     * An admin in access groups 90 ~ 98 cannot update an account whose access group
+     * is at or above their own, a disabled account included (it counts at the group
+     * it had): refused with INVALID_REQUEST and 'No access to modify admin.', and
+     * nothing is written. Access group 99 admins and the project owner are not limited.
+     *
+     * A changed e-mail is written unverified: this method never marks an e-mail
+     * verified, for an admin in access groups 90 ~ 98 or anyone else. The new e-mail
+     * logs the account in only once the user verifies it with verifyEmail(). The
+     * previous e-mail stops logging in when the change is written, unless it is the
+     * e-mail an account without a username was created with, which stays its login
+     * ID. A username always logs in. The change is refused with EXISTS and
+     * 'E-mail "user@email.com" is already a login ID in this service.' when the
+     * e-mail is a login ID another account of the project was granted: the address
+     * that account was created or invited with, or one it has verified. An e-mail
+     * login another account holds without having verified the address blocks
+     * nothing; it is removed, and that account keeps the login ID it was created
+     * with.
      * @param params Target user_id and the attributes to update.
      * @returns A promise that resolves to Promise<'SUCCESS: User attributes updated.'>.
      */
@@ -1433,32 +1954,67 @@ declare class Skapi {
     }>(params: Params[] | Form<Params>, url?: string): Promise<Response | Response[]>;
     /**
      * Relays a request to a destination of your choosing from the server side,
-     * with the service api key added where the browser cannot read it, and
-     * streams the destination's response back as it arrives.
-     *
-     * The body is relayed verbatim, so an html form reaches the destination as
-     * multipart/form-data, files included; the form's own enctype and method
-     * attributes are not used. Supply options.onStream to receive the response
-     * chunk by chunk. An error response throws a SkapiError either way; reading
-     * the status code or a response header needs options.responseType
-     * 'response'. options.signal stops the client receiving the response, it
-     * does not cancel the request already sent to the destination.
-     *
-     * @param form Form element, submit event, FormData, or a plain object. Sent to the destination verbatim.
-     * @param options Destination url, method, headers, and an optional onStream callback.
-     * @returns A promise that resolves to the destination's response.
-     */
-    forwardRequest(form: any, options: {
+     * optionally with one of your stored client secrets substituted in where you
+     * put "$CLIENT_SECRET", so the secret never reaches the browser.
+     *
+     * The first argument is the form: a submit event, a form element, FormData, a
+     * plain object, or null when everything is already in the options. It is
+     * FLATTENED to fields and merged into the request, into `params` for GET,
+     * DELETE and HEAD and into `data` otherwise; where a key is in both, the one
+     * you typed in options wins. Files are dropped by that flattening, because
+     * the merged object travels as JSON. Pass `multipart: true` to relay the
+     * form's own bytes instead, files included, the way a browser would send
+     * them; keep that body under 2 MB once encoded, and `data` is refused
+     * alongside it.
+     *
+     * `secretName` is optional: name one and its value is substituted server side
+     * and its allowed destinations are enforced, name none and only what you
+     * supplied is forwarded. `skapiHeaders` tells the destination who is calling,
+     * from the verified identity of the request; a header of your own starting
+     * with "x-skapi-" is refused, which is what makes that prefix worth trusting.
+     *
+     * Queueing, polling, `stream`, `realtime` and the poll handle on the reply all
+     * behave exactly as they do for the deprecated clientSecretRequest, because
+     * they are the same code.
+     *
+     * @param form Submit event, form element, FormData, plain object, or null for no form body.
+     * @param options Destination url and method, the optional secret name, and how to read the answer.
+     * @returns A promise that resolves to the destination's response, or to a status object when the request is queued.
+     */
+    forwardRequest(form: SubmitEvent | HTMLFormElement | FormData | {
+        [key: string]: any;
+    } | null, options: {
+        secretName?: string;
         url: string;
         method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
         headers?: {
             [key: string]: string;
         };
-        apiKeyHeader?: string;
-        apiKeyScheme?: string;
-        onStream?: (chunk: string) => void;
-        signal?: AbortSignal;
+        data?: {
+            [key: string]: any;
+        };
+        params?: {
+            [key: string]: string;
+        };
+        multipart?: boolean;
+        skapiHeaders?: boolean | {
+            user?: boolean;
+            service?: boolean;
+        };
+        service?: string;
+        owner?: string;
+        poll?: number;
+        queue?: string;
+        expires?: number;
+        stream?: boolean;
+        realtime?: boolean;
+        onStream?: (chunk: string, seq: number, via?: 'socket' | 'poll') => void;
+        onResponse?: (res: any, meta?: {
+            executed?: number;
+        }) => void;
+        onError?: (err: any) => void;
         responseType?: 'json' | 'text' | 'response';
+        signal?: AbortSignal;
     }): Promise<any>;
     /**
      * Returns a normalized response object for form-based handler flows.
@@ -1476,6 +2032,52 @@ declare class Skapi {
     }, fetchOptions?: FetchOptions): Promise<DatabaseResponse<RecordData>>;
     /**
      * Lists table metadata with optional table-name filters.
+     *
+     * With `table` given and `condition` omitted, the table name is matched
+     * exactly. With `table` omitted entirely, every table is returned.
+     * `gte` / `>=` is a prefix search ("table names starting with x"), while
+     * `gt` / `>` is a lexicographic greater-than that spills past the prefix
+     * into every later table name.
+     *
+     * Every combination:
+     * - `getTables({})`: every table in the project.
+     * - `getTables({ table: 'x' })`: exact match on 'x'.
+     * - `getTables({ table: 'x', condition: 'gte' })`: prefix, every table
+     *   name starting with 'x'.
+     * - `getTables({ table: '' })`: errors with '"table" should not be empty.'
+     * - `getTables({ condition: 'gte' })` with no `table`: errors with
+     *   '"table" is required for condition.'
+     *
+     * When you are looking for a table rather than listing them all, pass
+     * `gte`: a name recorded two ways, such as "Asian Spice House" and "Asian
+     * Spice House (alias)", is only found by the prefix. Real table names
+     * very often carry a leading name shared with the rest of their data set,
+     * a source or dataset prefix, so an exact match finds one spelling and
+     * silently misses its siblings while the prefix finds the family. When
+     * you already know the exact name, omitting `condition` is the exact
+     * match you want. Omit the key to get the default: an explicit undefined
+     * or null `condition` is rejected with INVALID_PARAMETER.
+     *
+     * Refused to a signed out caller when the project's `require_login`
+     * setting is on. The SDK throws REQUIRE_LOGIN before the request leaves,
+     * and the backend refuses the same call with INVALID_REQUEST, so a direct
+     * HTTP call or an older SDK with no gate is refused too. A project that
+     * has never set the flag counts as ON, the same default
+     * `getConnectionInfo()` already reports as `conf.require_login`. Table
+     * metadata used to be served to anyone who knew the project id, so an
+     * integration that listed tables with no signed in user now gets an error
+     * where it used to get a list.
+     *
+     * Table NAMES are never filtered: every table in the project is listed,
+     * whatever access group the records inside it live in. The per access
+     * group counters are filtered to the caller.
+     * `number_of_records_in_access_group_public` goes to everyone, a signed in
+     * user also receives the counters up to and including their own access
+     * group, and `number_of_records_in_access_group_private` and
+     * `number_of_records_in_access_group_admin` go to an admin or the project
+     * owner only. `number_of_records` and `size` are NOT filtered: both stay
+     * totals over every access group, so `number_of_records` is normally
+     * larger than the counters you can see add up to.
      * @param query Query object used to filter results.
      * @param fetchOptions Pagination and fetch behavior options.
      * @returns A promise that resolves to Promise<DatabaseResponse<Table>>.
@@ -1484,11 +2086,58 @@ declare class Skapi {
     /** If omitted, fetches the full list of tables. */
     query?: {
         table?: string;
-        /** Condition operator of table name. */
+        /** Condition operator of table name. Omitted: exact match on the given table name. `gte` / `>=`: prefix. */
         condition?: Condition;
     }, fetchOptions?: FetchOptions): Promise<DatabaseResponse<Table>>;
     /**
      * Lists index metadata and aggregated index statistics for a table.
+     *
+     * There is no top-level `condition` here. With no `index` and no `order`,
+     * every index of the table is listed, which is a prefix read. An `index`
+     * without a trailing '.' is an exact match on that index name; an `index`
+     * ending in '.' is a prefix that lists the children of that compound
+     * index, so "Band." lists Band.name, Band.year.
+     *
+     * The only condition is `order.condition`, which requires `order.value`.
+     * Omitting it matches `order.value` exactly.
+     *
+     * Every combination (`table` is required, so there is no no-argument
+     * form):
+     * - `getIndexes({ table: 't' })`: every index of table 't'.
+     * - `getIndexes({ table: 't', index: 'Band' })`: exact match on the index
+     *   'Band'.
+     * - `getIndexes({ table: 't', index: 'Band.' })`: prefix, the children of
+     *   the compound index, so Band.name, Band.year.
+     * - `getIndexes({ table: 't', order: { by: 'index_name', value: 'B' } })`:
+     *   exact match against the value.
+     * - `getIndexes({ table: 't', order: { by: 'total_number' } })`: the whole
+     *   partition, ordered by that attribute.
+     * - `order.condition` without `order.value`: errors.
+     * - no `table`: errors with '"table" is required.'
+     *
+     * When you are looking for an index rather than listing them all, use the
+     * prefix form (no `index`, or a name ending in '.') the way `gte` explores
+     * in getTables and getTags, since an exact `index` name returns only that
+     * one entry. Index names very often carry a leading name shared with the
+     * rest of their data set, so an exact match finds one spelling and
+     * silently misses its siblings while the prefix finds the family. Omit the
+     * key to get the default: an explicit undefined or null condition is
+     * rejected with INVALID_PARAMETER.
+     *
+     * Refused to a signed out caller when the project's `require_login`
+     * setting is on: REQUIRE_LOGIN from the SDK, INVALID_REQUEST from the
+     * backend for a caller that skips it. A project that has never set the
+     * flag counts as ON. Index metadata used to be served to anyone who knew
+     * the project id.
+     *
+     * The listing is NOT filtered by access group, for any caller. A stored
+     * index row is keyed by table and index name with the access group left
+     * out of the key, so one row aggregates every group: `number_of_records`,
+     * `total_number`, `average_number` and the rest span the whole table,
+     * private and admin records included. Anyone who gets past the sign in
+     * check therefore reads the project's entire index vocabulary. The
+     * records behind it stay gated, but an index name is visible to every
+     * signed in user.
      * @param query Query object used to filter results.
      * @param fetchOptions Pagination and fetch behavior options.
      * @returns A promise that resolves to Promise<DatabaseResponse<Index>>.
@@ -1504,11 +2153,56 @@ declare class Skapi {
             by: 'average_number' | 'total_number' | 'number_count' | 'average_bool' | 'total_bool' | 'bool_count' | 'string_count' | 'index_name' | 'number_of_records';
             /** Value to query. */
             value?: number | boolean | string;
+            /** Requires "value". Omitted: exact match against "value". */
             condition?: Condition;
         };
     }, fetchOptions?: FetchOptions): Promise<DatabaseResponse<Index>>;
     /**
      * Lists tags used in a table with optional tag-name filtering.
+     *
+     * With `condition` omitted the default depends on what else you gave:
+     * `table` and `tag` together match the tag exactly, `table` alone is a
+     * prefix ('>=') that lists every tag in that table, and neither one
+     * returns every tag in the project, ordered by record count, descending.
+     * `gte` / `>=` is a prefix search.
+     *
+     * Every combination:
+     * - `getTags({})`: every tag in the project, ordered by record count,
+     *   descending.
+     * - `getTags({ table: 't' })`: every tag in table 't'.
+     * - `getTags({ table: 't', tag: 'g' })`: exact match on the tag 'g' in
+     *   table 't'.
+     * - `getTags({ tag: 'g' })` with no `table`: the tag 'g' across all
+     *   tables.
+     * - `getTags({ table: 't', tag: 'g', condition: 'gte' })`: prefix, every
+     *   tag in 't' starting with 'g'.
+     * - `getTags({ condition: 'gte' })` with neither `table` nor `tag`: errors
+     *   with '"table" or "tag" is required for condition.'
+     *
+     * When you are looking for a tag rather than listing them all, pass
+     * `gte`: a name recorded two ways, such as "Asian Spice House" and "Asian
+     * Spice House (alias)", is only found by the prefix. Real tags very often
+     * carry a leading name shared with the rest of their data set, a series
+     * name or an artist recorded once plainly and once with a parenthesised
+     * alias, so an exact match finds one spelling and silently misses its
+     * siblings while the prefix finds the family. When you already know the
+     * exact name, omitting `condition` is the exact match you want. Omit the
+     * key to get the default: an explicit undefined or null `condition` is
+     * rejected with INVALID_PARAMETER.
+     *
+     * Refused to a signed out caller when the project's `require_login`
+     * setting is on: REQUIRE_LOGIN from the SDK, INVALID_REQUEST from the
+     * backend for a caller that skips it. A project that has never set the
+     * flag counts as ON. Tag metadata used to be served to anyone who knew
+     * the project id.
+     *
+     * The listing is NOT filtered by access group, for any caller. A stored
+     * tag row is keyed by tag and table name with the access group left out
+     * of the key, so `number_of_records` counts the records in every group
+     * together. Anyone who gets past the sign in check reads the project's
+     * entire tag vocabulary, tags carried only by private or admin records
+     * included. The records behind it stay gated, but a tag name is visible
+     * to every signed in user, so do not put anything secret in one.
      * @param query Query object used to filter results.
      * @param fetchOptions Pagination and fetch behavior options.
      * @returns A promise that resolves to Promise<DatabaseResponse<Tag>>.
@@ -1518,7 +2212,7 @@ declare class Skapi {
         table?: string;
         /** Tag name */
         tag?: string;
-        /** String query condition for tag name. */
+        /** String query condition for tag name. Omitted: exact match when `table` and `tag` are both given, prefix when only `table` is given. */
         condition?: Condition;
     }, fetchOptions?: FetchOptions): Promise<DatabaseResponse<Tag>>;
     /**
@@ -1646,36 +2340,45 @@ declare class Skapi {
     /**
      * Gets newsletter subscription status for the requested groups.
      * Takes a numeric group, "public", "authorized" or a named newsletter group. Omit the group for every group the user is subscribed to.
+     * The project owner, Skapi staff and access group 99 admins get every subscriber of the group instead, and can pass "email" to get only the subscribers whose e-mail address starts with it.
+     * An admin in access groups 90 ~ 98 gets the subscriber list too, but reads it through a privacy layer:
+     * "subscribed_email" is masked ("j**@**.com") and the mask is lossy, so two different subscribers can read the same;
+     * "subscriber_token" comes with each masked row as an opaque, stable, per address key, and it is the only value that tells such rows apart, so key lists and selections on it, never on the masked address;
+     * the token is not a readable address and is scoped to this service, owner and group, so it cannot be matched against a token from another group or project;
+     * "startKey" is sealed by the server and has to be handed back verbatim, which fetchMore already does;
+     * and "email" is refused with "No access.".
      * @param params Request parameters.
      * @param fetchOptions Pagination and fetch behavior options.
-     * @returns A promise that resolves to Promise<{ active: boolean; timestamp: number; group: number | string; subscribed_email: string; }[]>.
+     * @returns A promise that resolves to Promise<{ active: boolean; timestamp: number; group: number | string; subscribed_email: string; subscriber_token?: string; }[]>.
      */
     getNewsletterSubscription(params?: {
         /** Numeric group, "public", "authorized" or a named newsletter group. Omit or null for every group. */
         group?: number | 'public' | 'authorized' | (string & {}) | null;
+        /**
+         * Another user's subscriptions. The project owner's account, Skapi staff and
+         * admins (access groups 90 ~ 99) only. An admin in access groups 90 ~ 98 reads
+         * that user's address masked.
+         */
         user_id?: string;
+        /** Owner, Skapi staff and access group 99 only. Returns the subscribers of "group" whose e-mail address starts with this text. Requires "group", cannot be used with "user_id". Admins 90 ~ 98 are refused with "No access.". */
+        email?: string;
     }, fetchOptions?: FetchOptions): Promise<{
         active: boolean;
+        /** Undefined on a group's whole subscriber list, which the index does not carry it on. */
         timestamp: number;
         group: number | string;
         subscribed_email: string;
+        /** Only when the address above is masked. Opaque, stable per address key. */
+        subscriber_token?: string;
     }[] | DatabaseResponse<{
         active: boolean;
+        /** Undefined on a group's whole subscriber list, which the index does not carry it on. */
         timestamp: number;
         group: number | string;
         subscribed_email: string;
+        /** Only when the address above is masked. Opaque, stable per address key. */
+        subscriber_token?: string;
     }>>;
-    /**
-     * Requests a username change confirmation flow for the current user.
-     * @param params Request parameters.
-     * @returns A promise that resolves to Promise<'SUCCESS: confirmation e-mail has been sent.'>.
-     */
-    requestUsernameChange(params: {
-        /** Redirect URL when user clicks on the link. */
-        redirect?: string;
-        /** username(e-mail) user wish to change to. */
-        username: string;
-    }): Promise<'SUCCESS: confirmation e-mail has been sent.'>;
     /**
      * Reports whether client-side record encryption is on, and whether it is
      * currently unlocked.
@@ -1863,9 +2566,13 @@ declare class Skapi {
      * @returns A promise that resolves to Promise<UserProfile>.
      */
     login(params: Form<{
-        /** if given, username will be used instead of email. */
+        /** if given, username will be used instead of email. A username always logs its account in. */
         username?: string;
-        /** E-Mail for signin. 64 character max. */
+        /**
+         * E-Mail for signin. 64 character max. The e-mail an account without a username
+         * was created with always logs it in. Any other e-mail (that of an account created
+         * with a username, or a changed e-mail) logs in only once it is verified (verifyEmail()).
+         */
         email: string;
         /** Password for signin. Should be at least 6 characters. */
         password: string;
@@ -1885,7 +2592,19 @@ declare class Skapi {
      * @returns A promise that resolves to Promise<UserProfile | "SUCCESS: The account has been created. User's signup confirmation is required." | 'SUCCESS: The account has been created.'>.
      */
     signup(params: Form<UserAttributes & {
+        /** Required. Always. */
+        email: string;
         password: String;
+        /**
+         * Optional. When given it becomes the account's PERMANENT login
+         * username, which always logs the account in and can never be changed.
+         * The e-mail also logs the account in, but only once it is verified:
+         * opening the signup confirmation link verifies it, and without signup
+         * confirmation the user verifies it with verifyEmail() after logging in
+         * with the username. After an e-mail change the new e-mail logs in once
+         * it is verified the same way. E-mail login is not enabled while that
+         * e-mail is already another account's login ID.
+         */
         username?: string;
     }>, option?: {
         /**
@@ -1896,7 +2615,7 @@ declare class Skapi {
          */
         signup_confirmation?: boolean | string;
         /**
-         * When true, user will be subscribed to the service newsletter (group 1) once they are signed up.
+         * When true, user will be subscribed to Service Email (group 1) once they are signed up.
          * User's signup confirmation is required for this parameter.
          * Default is false.
          */
@@ -1927,6 +2646,13 @@ declare class Skapi {
     }>): Promise<'SUCCESS: New password has been set.'>;
     /**
      * Verifies the user email address with a confirmation code.
+     * Call it without `code` to send the code, then with the code the user received.
+     * Once the e-mail is verified it also logs the account in (a few seconds after
+     * the verification succeeds) when the account was created with a username or its
+     * e-mail was changed, unless that e-mail is a login ID another account of the
+     * project was granted: the address that account was created or invited with, or
+     * one it has verified. An e-mail login another account holds without having
+     * verified the address is removed, and this account gets the login.
      * @param params Payload for the request.
      * @returns A promise that resolves to Promise<string>.
      */
@@ -1974,6 +2700,19 @@ declare class Skapi {
     }): Promise<'SUCCESS: Password has been changed.'>;
     /**
      * Updates profile attributes for the authenticated user.
+     *
+     * A changed e-mail is written unverified, and it logs the account in only once
+     * it is verified with verifyEmail(): the login follows a few seconds after the
+     * verification succeeds. The previous e-mail stops logging in right after the
+     * change, unless it is the e-mail an account without a username was created with,
+     * which stays its login ID. A username always logs in. E-mail login is not added
+     * while the new e-mail is a login ID another account of the project was granted:
+     * the address that account was created or invited with, or one it has verified.
+     * An e-mail login another account holds without having verified the address is
+     * removed instead, and this account gets the login.
+     *
+     * With another user's `user_id` it updates that user from admin context and
+     * follows the rules of updateUserAttributes(). Your own `user_id` is ignored.
      * @param params Payload for the request.
      * @returns A promise that resolves to Promise<UserProfile>.
      */
@@ -2060,12 +2799,13 @@ declare class Skapi {
 
 declare class SkapiError extends Error {
     code: string | number;
-    cause: Error;
+    /** 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;
+        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, 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 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 TicketRequestCondition, type TicketResponseCondition, type TicketSignatureCondition, Types, type UniqueId, type UserAttributes, type UserProfile, type UserPublic, type WebSocketMessage };