skapi-js 2.0.5 → 2.2.0

package/dist/skapi.d.ts

@@ -85,7 +85,7 @@ type PostRecordConfig = {
         name?: string;
         /** Number range: 0 ~ 99. 'public' = 0, 'authorized' = 1, 'admin' = 99. '*' is shorthand for 'private'. Default: 'public' */
         access_group?: number | 'private' | '*' | 'public' | 'authorized' | 'admin';
-        /** When true, Record will be only accessible for subscribed users. */
+        /** How the record reaches the uploader's subscribers. Signed-in users only. */
         subscription?: {
             is_subscription_record?: boolean;
             upload_to_feed?: boolean;
@@ -94,6 +94,16 @@ type PostRecordConfig = {
             notify_referencing_records?: boolean;
         } | null;
     };
+    /**
+     * Title and body of the push notification the record's creation sends to the uploader's
+     * subscribers with table.subscription.notify_subscribers. Both are required, and together
+     * they must fit 3072 bytes. Without it, subscribers get a default text. Ignored on updates
+     * and without notify_subscribers.
+     */
+    notification?: {
+        title: string;
+        body: string;
+    } | null;
     source?: {
         referencing_limit?: number;
         prevent_multiple_referencing?: boolean;
@@ -186,8 +196,9 @@ type RecordData = {
         name: string;
         /** Number range: 0 ~ 99 */
         access_group: number | 'private' | 'public' | 'authorized' | 'admin';
-        /** User ID of subscription */
+        /** Subscription settings of the record. See PostRecordConfig.table.subscription. */
         subscription?: {
+            is_subscription_record: boolean;
             upload_to_feed: boolean;
             notify_subscribers: boolean;
             feed_referencing_records: boolean;
@@ -660,6 +671,393 @@ type Subscription = {
     get_notified: boolean;
     get_email: boolean;
 };
+/**
+ * Comparison operator of a ticket condition row, and of `ip` and `user_agent`. The word forms
+ * are normalized to the symbols on registration.
+ *
+ * - '=' and '!=' compare the way JavaScript's === does: true is not 1 and "1" is not 1.
+ * - On two numbers, '>', '>=', '<' and '<=' compare numerically.
+ * - On two strings, '>=' means "starts with" and '<=' means "ends with". '>' and '<' use plain string order.
+ * - A string against a number (or the reverse), a boolean, null or undefined never passes '>', '>=', '<' or '<='.
+ * - With a list value, '=' and the ordering operators pass when any member passes. '!=' passes when the value is none of them.
+ */
+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.
+ *
+ * How a list decides:
+ * - Rows on the same key are alternatives: the key passes when any one of them matches.
+ * - Every different key that has a match row (a row with an `operator`) must pass. The first key
+ *   that does not fails the consumption with CONDITION_FAILED, `detail: { field, keys }`.
+ * - 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.
+ * - 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
+ *   JSON-parsed when they parse, otherwise they stay strings: `?qty=2` is the number 2 and
+ *   `?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` 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.
+ * - undefined is a row with an `operator` and no `value` key, which is what `value: undefined` sends.
+ *   A value list may contain null. undefined is only ever a single value.
+ */
+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`.
+     * - `params` rows: a path into the query string, read the same way.
+     * - `data` rows of a req action's response condition: a path into the response body ("status" is the response's `status`).
+     * - `headers` rows: the header name, matched case-insensitively.
+     * - `user` rows: the consumer attribute name.
+     *
+     * Never templated.
+     */
+    key: string;
+    /** Absent on a capture-only row, which has a `placeholder` and no `value`. */
+    operator?: TicketConditionOperator;
+    /**
+     * 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.
+     */
+    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. */
+    setValueWhenMatch?: any;
+    /**
+     * `data` 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_]*$.
+     */
+    placeholder?: string;
+};
+/**
+ * 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. These tokens exist only in
+ * the signature templates: they are not the references actions use (see TicketAction).
+ *
+ * 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. It is only used to verify the signature: no action sends it, and its
+     * Destinations do not limit the ticket's req actions.
+     */
+    secretName: 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. The parts are
+ * checked in the order listed here and the first part that fails is the reported one. An absent
+ * or empty part checks nothing.
+ */
+type TicketCondition = {
+    /** Answer HTTP 200 even when the consumption fails. For webhooks that retry on errors. It only changes the status: a failing request still fails. */
+    return200?: boolean;
+    /** Absent = both allowed. */
+    method?: 'GET' | 'POST';
+    /** Verified first, over the raw request body. See TicketSignatureCondition. */
+    signature?: TicketSignatureCondition;
+    /**
+     * The caller's IP address. Fails only when none of the listed values passes ('!=': when it
+     * is one of them). A value that is empty ("" or []), null or missing checks nothing, and
+     * registration drops it.
+     */
+    ip?: {
+        operator: TicketConditionOperator;
+        value: string | string[];
+    };
+    /** The User-Agent header, decided like `ip`. */
+    user_agent?: {
+        operator: TicketConditionOperator;
+        value: string | string[];
+    };
+    /** 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 query string, read on GET and on POST. */
+    params?: TicketConditionRow[];
+    /**
+     * Rows against the consumer's attributes (user_id, email, access_group, ...). Signed requests
+     * only: an app user of this project calling consumeTicket() with `auth: true`. A third-party
+     * webhook has no session, so a ticket using this always fails for webhooks (AUTH_REQUIRED).
+     * The actions read the same attributes as `${user[key]}`. Every row compares with a value:
+     * null, or no `value`, is refused.
+     */
+    user?: TicketConditionRow[];
+    /**
+     * Record ID the consumer must own or have been granted. Signed requests only, like `user`:
+     * a ticket using this always fails for webhooks. The actions read it as `${record_access}`.
+     */
+    record_access?: string;
+};
+/**
+ * What a `req` action checks on the response before its nested actions run: `headers` and
+ * `data` rows work as in the ticket's condition (captures and `setValueWhenMatch` included).
+ * `headers` rows read the response headers and `data` row keys are paths into the parsed
+ * response body. `user` and `record_access` still check the consumer, so they only work for
+ * signed requests. A response that is not 2xx fails before this is checked.
+ */
+type TicketResponseCondition = Pick<TicketCondition, 'headers' | 'data' | 'user' | 'record_access'>;
+/**
+ * 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.
+ *
+ * `exe` values are templated right before the action runs. Every reference is written inside
+ * `${ }`, and text outside `${ }` is always literal, whatever it looks like: "order[id]" is just
+ * that text. A value that is exactly one `${...}` keeps the type of what it reads; inside longer
+ * text it becomes text (JSON for anything but a string). `$${...}` writes a literal `${...}`.
+ * Object keys, condition rows and `setValueWhenMatch` are never templated.
+ *
+ * | 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. |
+ * | `${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`. |
+ * | `${user}`, `${user[key]}` | The signed-in user's attributes. Signed requests only. |
+ * | `${ip}`, `${user_agent}`, `${method}` | The caller's IP address, User-Agent and HTTP method. |
+ * | `${record_access}` | The record ID the condition's `record_access` names. Signed requests only. |
+ * | `${response}`, `${response[key]}` | The parsed body of the enclosing req action's response. Only in that req's nested `actions` and their `err` chains. |
+ * | `${result}`, `${result[key]}` | The result of the previous action in the same chain. A nested chain and an `err` chain start without one. |
+ * | `${error}`, `${error[key]}` | In an `err` chain, the failure: `code`, `message`, `detail`, `action` (the act) and `path`. |
+ * | `${ticket}`, `${ticket[key]}` | This consumption: `id`, `service`, `owner`, `consume_id` and `timestamp`. |
+ * | `${CLIENT_SECRET}` | Reserved. See `secretName` on the req action. |
+ *
+ * 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, and a reference written where it can
+ * never resolve (`${response}` outside a req's nested actions, `${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,
+ * PLACEHOLDER_MISSING for a placeholder that was never captured, or AUTH_REQUIRED for `${user}`
+ * on a request that is not signed in. Its `err` chain runs and the consumption stops.
+ */
+type TicketAction = {
+    /** Set the access group of a user. */
+    act: 'acsg';
+    exe: {
+        /** 1 ~ 99, or "admin", or a reference that gives one when the action runs, such as "${placeholder[GROUP]}". */
+        group: number | 'admin' | `${string}\${${string}}${string}`;
+        /** 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, such as "https://api.example.com/orders/${data[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
+         * segments or query parameters ("." and ".." are refused). `${CLIENT_SECRET}` is
+         * never allowed here. Sent as a browser sends it: a hostname outside ASCII is
+         * IDNA-encoded, a tab or line break is removed, and in the path and query a space,
+         * any other control character and every character outside ASCII is percent-encoded.
+         */
+        url: string;
+        /** Default GET. */
+        method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+        /**
+         * The name of a Secret Key of the project, never the secret itself. Must exist at
+         * registration. Never templated.
+         *
+         * - `${CLIENT_SECRET}` in this action's `headers`, `data` and `params` values is
+         *   replaced by the key's value, server side, when the call is sent. It is refused
+         *   anywhere else: in the url, in other actions, in a req without `secretName`, in
+         *   header names or object keys, and in condition rows. Text in the incoming request
+         *   that reads "${CLIENT_SECRET}" is never expanded.
+         * - The url's scheme and host must be written out: no "${...}" before the path.
+         * - When the key has Destinations, the call must go to one of them, or it fails with
+         *   REQUEST_FAILED, `detail: { reason: 'refused_address' }`. A req without
+         *   `secretName` is not limited.
+         * - The value is never logged. A copy in the answer or an error, as sent or escaped
+         *   up to three times over (percent, backslash or HTML escapes; each level in one
+         *   notation), reads "${CLIENT_SECRET}" instead. An answer of any size is read whole
+         *   and still parses as JSON; reading a very long answer can run out of the
+         *   ticket's time, which fails with REQUEST_FAILED, `detail: { reason: 'timeout' }`.
+         *   A key that no longer exists fails with
+         *   REQUEST_FAILED, `detail: { reason: 'secret_missing', secretName }`.
+         */
+        secretName?: string;
+        /**
+         * Request headers, values templated. Two headers are the engine's own, and
+         * registration refuses either one, in any case and with any surrounding spaces:
+         * Host (always the url's host) and X-Skapi-Ticket (every call carries
+         * `X-Skapi-Ticket: <service id>/<ticket id>`).
+         *
+         * A name must be ASCII, with no ":", line break or NUL. A value cannot hold a line
+         * break, NUL or a character outside Latin-1 (send such values in the body).
+         * - Registration refuses a name that breaks this rule, and a value whose text outside
+         *   its `${...}` references breaks it, so a header the call could never send is not
+         *   saved.
+         * - A value that breaks it only once templated fails the call with REQUEST_FAILED,
+         *   `detail: { reason: 'invalid_header', header }`, before anything is sent.
+         *
+         * Each message names the header, never its value.
+         */
+        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. Registration moves these rows to the end of `condition.data`. */
+        match?: TicketConditionRow[];
+        /** Checked against the response. Captures land in the shared placeholder pool. See TicketResponseCondition. */
+        condition?: TicketResponseCondition;
+        /**
+         * Nested chain, run when the response passes `condition`. It reads the response body
+         * as `${response}` and `${response[key]}`, while `${data}` is still the incoming
+         * request body. Any action can nest, including another req with its own `secretName`.
+         */
+        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[];
+    /**
+     * true on a ticket saved before this release (the dashboard marks it "previous rules"). It
+     * keeps running by the rules it was saved with until it is registered again, which applies
+     * the current rules. `condition` and `actions` are shown converted to the current format.
+     * Returned to the project owner only. See
+     * https://docs.skapi.com/deprecated/deprecated.html#tickets-saved-before-this-release
+     */
+    legacy?: boolean;
+};
+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, and { field, keys }
+     * on CONDITION_FAILED, where `field` is the part that failed ("data", "headers", ...) and
+     * `keys` the row keys that did not pass. `field` is "loop" when the request was sent by a
+     * ticket's own req action (a ticket cannot consume a ticket).
+     *
+     * REQUEST_FAILED carries { status, body } for an answer of 300 or above (`body` is the parsed
+     * answer, or the first 4 KB of its text when longer, compact JSON for a JSON answer, with a
+     * Secret Key the req sent replaced by the text "${CLIENT_SECRET}"), { reason } with reason
+     * "timeout", "refused_address" or "connection", { reason: "invalid_header", header } for a
+     * header that cannot be sent, or { reason: "secret_missing", secretName }.
+     */
+    detail?: {
+        [key: string]: any;
+    };
+    ticket_id: string;
+};
 
 type Types_BinaryFile = BinaryFile;
 type Types_Condition = Condition;
@@ -689,13 +1087,22 @@ 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_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_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;
@@ -859,12 +1266,16 @@ declare class Skapi {
     };
     private __connection;
     private __authConnection;
+    private __projectIdInput;
     private __network_logs;
     private __endpoint_version;
     private __public_identifier;
     private bearerToken;
     private _alert;
     constructor(service: string, owner?: string | Options, options?: Options | any, __etc?: any);
+    private _resolveProject;
+    private _startAfterProjectIdInput;
+    private _start;
     /**
      * Returns current connection metadata such as service name, client IP, user agent, locale, and SDK version.
      * @param params Request parameters. When `refresh` is true, the cached connection metadata is re-fetched before returning; otherwise the cached connection is returned.
@@ -948,6 +1359,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>>.
@@ -991,6 +1414,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). */
@@ -1035,9 +1475,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;
@@ -1070,6 +1513,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
@@ -1083,6 +1528,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;
@@ -1094,11 +1540,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.
      *
@@ -1117,6 +1560,7 @@ declare class Skapi {
      *     onStream: (chunk) => parser.feed(chunk)
      * });
      * ```
+     * @deprecated Use forwardRequestStream, which is this same function.
      */
     clientSecretRequestStream(requestId: string, options: {
         url?: string;
@@ -1130,6 +1574,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.
      *
@@ -1145,6 +1591,7 @@ declare class Skapi {
      *     method: 'POST'
      * });
      * ```
+     * @deprecated Use forwardRequestFinalize, which is this same function.
      */
     clientSecretRequestFinalize(requestId: string, data?: any, options?: {
         url?: string;
@@ -1155,6 +1602,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';
@@ -1165,6 +1620,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.
      *
@@ -1180,6 +1637,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;
@@ -1190,14 +1648,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;
@@ -1208,34 +1670,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>>;
     /**
@@ -1292,30 +1911,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;
@@ -1333,6 +1993,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.'>.
      */
@@ -1435,32 +2118,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.
@@ -1478,6 +2196,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>>.
@@ -1486,11 +2250,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>>.
@@ -1506,11 +2317,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>>.
@@ -1520,7 +2376,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>>;
     /**
@@ -1612,10 +2468,10 @@ declare class Skapi {
         VAPIDPublicKey: string;
     }>;
     /**
-     * Sends push notifications to one or more users.
-     * @param params Payload for the request.
-     * @param user_ids Parameter for this operation.
-     * @returns A promise that resolves to Promise<"SUCCESS: Notification sent.">.
+     * Sends push notifications to one or more users. Admins only.
+     * @param params Title and body of the push. Together at most 3072 bytes.
+     * @param user_ids Users to push to, up to 1000. Every device each of them registered with subscribeNotification() gets it. Without it, every registered device of the project gets it.
+     * @returns A promise that resolves to Promise<"SUCCESS: Notification sent.">. The pushes are sent right after it resolves.
      */
     pushNotification(params: {
         title: string;
@@ -1648,36 +2504,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, and it is a key for working with a listing, not an id to store: the platform can reissue tokens;
+     * "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.
@@ -1865,9 +2730,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;
@@ -1887,7 +2756,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?: {
         /**
@@ -1898,7 +2779,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.
          */
@@ -1929,6 +2810,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>.
      */
@@ -1976,6 +2864,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>.
      */
@@ -2007,7 +2908,9 @@ declare class Skapi {
     }, fetchOptions?: FetchOptions): Promise<DatabaseResponse<Subscription>>;
     /**
      * Subscribes to another user with optional feed/notification/email preferences.
-     * @param params Request parameters.
+     * Calling it again on the same user changes only the options given and keeps the rest,
+     * so `get_notified` can be turned on or off without touching `get_feed`.
+     * @param params Request parameters. `get_feed`: the user's records posted with `upload_to_feed` appear in getFeed(). `get_notified`: push notifications for the user's records posted with `notify_subscribers`, and for new references to their records with `notify_referencing_records` (the device also needs subscribeNotification()). A new subscription starts with every option off.
      * @returns A promise that resolves to Promise<Subscription>.
      */
     subscribe(params: {
@@ -2062,12 +2965,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 TicketResponseCondition, type TicketSignatureCondition, Types, type UniqueId, type UserAttributes, type UserProfile, type UserPublic, type WebSocketMessage };