@rig-ts/client 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,810 @@
+//#region src/credential.d.ts
+/**
+ * What authorizes each request.
+ *
+ * `apply` is handed the headers a request is about to go out with, rather than
+ * a value to return, because a credential that has to refresh first needs
+ * somewhere to await — and because a future one may want to set more than a
+ * single header.
+ */
+type Credential = {
+  apply(headers: Headers, signal?: AbortSignal): void | Promise<void>;
+};
+/**
+ * A credential that can do something about a 401.
+ *
+ * The runtime asks once, and only ever once per call: a blind retry on 401 is a
+ * way to lock an account out with a wrong password. Answering `false` leaves the
+ * 401 as the answer, which is what a credential with nothing left to try should
+ * say — throwing would replace the server's refusal with the client's opinion
+ * of it.
+ */
+type Reauthorizer = Credential & {
+  reauthorize(signal?: AbortSignal): Promise<boolean>;
+};
+/**
+ * A credential that needs the client it authorizes in order to work.
+ *
+ * `Session` is the one: refreshing is itself a call, and the only moment the
+ * runtime can be known is when the credential is installed. Kept structural so
+ * the runtime does not have to import the session, which would be a cycle.
+ */
+type Bindable = {
+  bind(runtime: unknown): void;
+};
+/** Reports whether a credential can answer a 401 with something new. */
+declare function isReauthorizer(c: Credential | undefined): c is Reauthorizer;
+/**
+ * A bearer token that never changes.
+ *
+ * Right for a token from somewhere else — a test fixture, an environment
+ * variable, a token minted by the surrounding application. A token that expires
+ * wants a `Session`, which refreshes ahead of the expiry rather than discovering
+ * it through a failed request.
+ */
+declare function staticToken(token: string): Credential;
+/**
+ * An API key, presented the same way a token is.
+ *
+ * The server tells the two apart by what the value is, not by how it arrived, so
+ * this is a separate name only because a caller holding one should not have to
+ * know that. It is {@link staticToken} and not a copy of it: two bodies that
+ * have to stay identical is how one of them eventually does not, and there is
+ * nothing here that could correctly differ — the day a key travels somewhere a
+ * token does not, this stops being an alias and starts being a function.
+ */
+declare const apiKey: typeof staticToken;
+//#endregion
+//#region src/retry.d.ts
+/**
+ * How a call the server could not answer is sent again, and how long the client
+ * waits in between.
+ *
+ * It applies to the calls where sending the same request twice cannot mean two
+ * different things. A read and a delete are that by nature. A create and an
+ * update are made so: each one goes out named by an idempotency key, and a rig
+ * server that sees the same key twice answers the second one with what it
+ * answered the first rather than doing the work again.
+ *
+ * An upload is not, and is the one write this never repeats — a rig server does
+ * not record an upload route against a key, so a second send would store the
+ * file twice.
+ */
+type Retry = {
+  /**
+   * How many times a call is sent, the first try included. Absent takes
+   * {@link DEFAULT_ATTEMPTS}; one sends it once and reports whatever came
+   * back.
+   */
+  attempts?: number;
+  /**
+   * The first backoff window in milliseconds, doubling per attempt after it.
+   * Absent takes {@link DEFAULT_RETRY_BASE_MS}.
+   *
+   * The first retry does not use it: it goes out immediately, because the
+   * commonest retryable failure there is — a pooled connection the server had
+   * already closed — is fixed by opening another one, and waiting a second
+   * first would only be slower.
+   */
+  baseMs?: number;
+  /**
+   * Bounds one backoff window, however many attempts have already failed.
+   * Absent takes {@link DEFAULT_RETRY_CAP_MS}.
+   *
+   * It does not bind at the default attempt count, which is why it is a
+   * setting rather than a number anybody has to choose: a caller who raises
+   * `attempts` to eight is asking for eight tries, not for a two-minute sleep
+   * in the middle of them.
+   */
+  capMs?: number;
+};
+//#endregion
+//#region src/rate-limit.d.ts
+/**
+ * What a response said about the caller's budget.
+ *
+ * It is the tightest limit the caller is under rather than a list of every one
+ * that applied: the server evaluates each and reports the one closest to
+ * refusing, because that is the only number a client can act on.
+ */
+type RateLimitStatus = {
+  /**
+   * The operation that was called, as the document names it — `listTodos`.
+   * A gauge keyed on it says which call is spending the budget.
+   */
+  readonly op: string; /** How many calls the window allows. */
+  readonly limit: number; /** How many are left. Zero on the response that was refused. */
+  readonly remaining: number;
+  /**
+   * How long until the window frees, in milliseconds.
+   *
+   * Only stated on a refusal — an allowed response says how much is left but
+   * not when it comes back. Zero means the server did not say.
+   */
+  readonly resetAfterMs: number; /** True when this response was the 429 rather than a call that went through. */
+  readonly refused: boolean;
+};
+/** How much of the budget has been spent. */
+declare const used: (s: RateLimitStatus) => number;
+/**
+ * How much of the budget is spent, from 0 to 1.
+ *
+ * It is the number worth alerting on, and it is here rather than left to the
+ * caller because the obvious arithmetic divides by zero: a response from a
+ * server with no limit configured carries no headers and leaves `limit` at 0.
+ */
+declare const fraction: (s: RateLimitStatus) => number;
+/**
+ * Reads the status out of a response, or `undefined` when the server said
+ * nothing at all.
+ *
+ * A server with no `throttle:` block sends none of these headers, and a caller
+ * that treated an absent header as zero would read "no budget left" out of a
+ * server that has no limits.
+ */
+declare const rateLimitOf: (op: string, res: Response) => RateLimitStatus | undefined;
+//#endregion
+//#region src/runtime.d.ts
+/**
+ * The authentication profile, as the document describes it.
+ *
+ * The lifetimes here are the ones the server enforces rather than numbers a
+ * client author guessed, which is why a `Session` can refresh ahead of an expiry
+ * instead of waiting for a 401 to tell it.
+ */
+type AuthProfile = {
+  /** Where the endpoints sit, for example `/auth`. */basePath: string; /** The lifetime of the token that travels on every request, in milliseconds. */
+  accessTtlMs: number; /** How long an ordinary session lasts, in milliseconds. */
+  refreshTtlMs: number;
+  /**
+   * How long a refresh token stays usable after it has been exchanged, in
+   * milliseconds. It is also what this package refreshes ahead by: the server
+   * having decided how much slack a swap deserves, a client has no business
+   * picking a different number.
+   */
+  rotationLeewayMs: number;
+};
+/**
+ * What the generated client knows about the server and this package does not.
+ * Generated code fills it in; a caller never sees it.
+ */
+type ApiDescriptor = {
+  /** The prefix every route sits under, for example `/api/v1`. */basePath: string; /** The authentication profile, or absent for a project with none. */
+  auth?: AuthProfile;
+  /**
+   * The date the API surface this client was generated from last changed. It
+   * is sent on every request, which is how a server's logs can answer how old
+   * the oldest caller still calling is.
+   */
+  revision?: string; /** Where `revision` is sent — the header the generated server reads. */
+  revisionHeader?: string;
+};
+/** What a caller supplies. Every field but `baseUrl` has a default. */
+type Config = {
+  /**
+   * The origin the API is served from, for example `https://api.example.com`.
+   * A path on it is kept and the API's own base path is appended, so a server
+   * behind `/gateway` is a base URL and not a special case.
+   *
+   * A relative value works in a browser and is the ordinary same-origin case:
+   * `""` resolves against the page.
+   */
+  baseUrl: string;
+  /**
+   * What authorizes each request. Absent sends no `Authorization` header,
+   * which is what a public API or a cookie-authenticated deployment wants.
+   */
+  credential?: Credential;
+  /**
+   * Sent on every request. Where a tenant header, a trace header, or anything
+   * else a deployment adds belongs.
+   */
+  headers?: HeadersInit;
+  /**
+   * How long a whole call may take, in milliseconds, retries and backoff
+   * included. Absent leaves it unbounded and lets the caller's own
+   * `AbortSignal` decide, which is what a browser application usually wants.
+   */
+  timeoutMs?: number;
+  /**
+   * Supplies the value of the request-ID header, so a client-side log line and
+   * a server-side one can be joined. Absent sends none, and the server
+   * generates its own.
+   */
+  requestId?: () => string; /** Defaults to `X-Request-Id`, which is what the generated server reads. */
+  requestIdHeader?: string;
+  /**
+   * Overrides the API revision this client says it was built against.
+   *
+   * Almost nobody should set it. The generated client carries the revision
+   * from the document it was generated from, which is the honest answer and
+   * the one the server's logs are for.
+   */
+  revision?: string; /** Overrides where the revision is sent. */
+  revisionHeader?: string;
+  /**
+   * The transport. Swapping it is how a test intercepts requests and how a
+   * server runtime supplies its own. Defaults to the ambient `fetch`.
+   */
+  fetch?: typeof fetch; /** The clock, for a test that has to cross a token expiry without waiting. */
+  now?: () => number; /** How a call the server could not answer is sent again. See {@link Retry}. */
+  retry?: Retry;
+  /**
+   * Called with what each response said about the caller's budget, when the
+   * server said anything at all.
+   *
+   * It is the other half of rate limiting, and the half a client can act on. A
+   * 429 is already handled without it — the client reads `Retry-After` and
+   * backs off — but by then the call has been refused. These numbers arrive on
+   * every response, so a caller that watches them can slow down, shed work, or
+   * raise an alarm while its calls are still succeeding.
+   *
+   * Deliberately a callback and not automatic pacing. A client library that
+   * silently waited because `remaining` was low would turn a batch job's
+   * throughput into a mystery, and it cannot know whether this caller would
+   * rather go slower or fail sooner. The numbers are handed over; the policy
+   * is the application's.
+   *
+   * Called once per attempt, before the call returns. Keep it quick, do not
+   * throw from it, and do not call back into the client.
+   */
+  onRateLimit?: (status: RateLimitStatus) => void;
+};
+/** Where the generated server looks for a caller's own request identifier. */
+declare const DEFAULT_REQUEST_ID_HEADER = "X-Request-Id";
+/**
+ * Carries the API revision, and is what `rig.yaml`'s `api.revision_header`
+ * defaults to. A generated client passes its project's own, so this is the
+ * fallback for a client somebody built by hand.
+ */
+declare const DEFAULT_REVISION_HEADER = "API-Revision";
+/**
+ * One client's configuration and the state it accumulates.
+ *
+ * The remembered QUERY decision is the reason this is state rather than
+ * configuration: a client that learned an intermediary refuses QUERY should not
+ * have to learn it again on the next search.
+ */
+declare class Runtime {
+  readonly api: ApiDescriptor;
+  readonly fetch: typeof fetch;
+  readonly now: () => number;
+  readonly retry: Retry;
+  readonly timeoutMs: number | undefined;
+  /**
+   * Where a caller's own request identifier is sent. Readable rather than
+   * private because the transport writes to it too: a call that names its own
+   * identifier has to land in the header this client was configured with, or a
+   * deployment that moved the header gets two of them disagreeing.
+   */
+  readonly requestIdHeader: string;
+  /** The randomness in a backoff, held here so a test can make one deterministic. */
+  jitter: (n: number) => number;
+  private readonly baseUrl;
+  private readonly headers;
+  private readonly requestIdOf;
+  private readonly revision;
+  private readonly revisionHeader;
+  private credential;
+  private readonly onRateLimit;
+  /** Records that QUERY was refused once and is not worth trying again. */
+  private searchByPost;
+  constructor(config: Config, api: ApiDescriptor);
+  /**
+   * Hands the caller's budget to the configured callback, if the response said
+   * anything about it and anybody is listening.
+   *
+   * A throwing callback must not fail the call it was observing: it is
+   * telemetry about a request that otherwise succeeded, and turning a bad
+   * gauge into a failed write would be the wrong trade in both directions.
+   */
+  observeRateLimit(op: string, res: Response): void;
+  /** The origin requests go to. */
+  get origin(): string;
+  /** The credential in force, or `undefined`. */
+  getCredential(): Credential | undefined;
+  /**
+   * Installs a credential, replacing whatever was there. It is what signing in
+   * does, and what a caller does by hand when they already hold a token from
+   * somewhere else.
+   */
+  use(credential: Credential | undefined): void;
+  /** Whether this client has learned that QUERY does not get through. */
+  searchesByPost(): boolean;
+  /** Remembers a refused QUERY, so it is tried once per client and not once per call. */
+  rememberSearchByPost(): void;
+  /**
+   * The absolute URL for an operation.
+   *
+   * `extra` is what a call option added, and it wins where the two name the
+   * same parameter: the operation's own query came from the typed arguments of
+   * a generated method, and an option is the caller saying something about
+   * this one call afterwards.
+   */
+  url(path: string, query: URLSearchParams | undefined, extra: URLSearchParams | undefined, root: boolean): string;
+  /** The headers every request from this client carries, before the call's own. */
+  baseHeaders(): Headers;
+}
+//#endregion
+//#region src/session.d.ts
+/**
+ * The pair a sign-in returns, in the shape the wire uses.
+ *
+ * The names are the server's, verbatim — a client that renamed them would be a
+ * second description of the same exchange, and this is a value programs store
+ * between runs.
+ */
+type TokenPair = {
+  accessToken?: string;
+  refreshToken?: string; /** RFC 3339, or absent from a server that did not say. */
+  expiresAt?: string;
+  /**
+   * When the session itself ends. A client needs both: one says when to
+   * refresh, the other says when to stop trying.
+   */
+  refreshExpiresAt?: string;
+  sessionId?: string;
+};
+/** Thrown when a session has nothing left to present. */
+declare class NoSessionError extends Error {
+  constructor();
+}
+/**
+ * A credential that keeps itself fresh.
+ *
+ * It holds the pair a sign-in returned and exchanges the refresh token before
+ * the access token expires, using the leeway in the document's auth profile — so
+ * a page open all day makes a handful of refresh calls at moments of its own
+ * choosing, rather than discovering the expiry through a failed request in the
+ * middle of something.
+ *
+ * Several calls arriving at an expiry at once take turns: the ones behind find
+ * the work already done instead of each spending a rotation. That matters more
+ * than it sounds — the server bounds how often a session may rotate, and a
+ * client that raced with itself would spend that budget on nothing.
+ */
+declare class Session implements Reauthorizer, Credential {
+  private tokens;
+  private runtime;
+  /**
+   * Held for the length of an exchange, so a hundred callers discovering the
+   * same expiry produce one refresh.
+   */
+  private inFlight;
+  /** Called when a new pair is issued — a place to persist it. */
+  onTokens: ((tokens: TokenPair) => void) | undefined;
+  constructor(tokens?: TokenPair);
+  /** The pair currently held, for a program that stores it between runs. */
+  getTokens(): TokenPair;
+  /** Identifies the session, for showing it in a list and revoking it. */
+  get sessionId(): string;
+  /**
+   * Swaps in a newly issued pair, which is what a refresh, a tenant switch and
+   * a password change all produce.
+   */
+  replace(pair: TokenPair): void;
+  /** Receives the client this session refreshes through. */
+  bind(runtime: unknown): void;
+  /**
+   * Adds the token, refreshing first if this request might outlive it.
+   */
+  apply(headers: Headers, signal?: AbortSignal): Promise<void>;
+  /**
+   * A 401 despite a token that looked current is a revoked or invalidated one,
+   * and the refresh token is the only thing left to try.
+   *
+   * It exchanges whatever the expiry says, because the expiry is exactly what
+   * has just been proved wrong.
+   */
+  reauthorize(signal?: AbortSignal): Promise<boolean>;
+  /** Whether the access token is expired or close enough to it. */
+  private stale;
+  /**
+   * Exchanges the refresh token for a new pair, once however many callers ask.
+   *
+   * Answers false rather than throwing when there is nothing to exchange: a
+   * session that was never signed in leaves the 401 that prompted this as the
+   * answer, which is what the caller needs to see.
+   */
+  private exchange;
+}
+//#endregion
+//#region src/op.d.ts
+/**
+ * One call, as the generated method describes it.
+ *
+ * The path is relative to the API's base path and already has its parameters
+ * substituted: escaping an identifier into a route is the generated method's
+ * job, because only it knows which argument goes where.
+ */
+type Op = {
+  /**
+   * The operation this call is, as the document named it — `listTodos`,
+   * `createTodo`.
+   *
+   * A field rather than something derived from method and path, because the
+   * path here already has its identifiers substituted: a name built from it
+   * would be a new name for every row anybody ever fetched.
+   */
+  name: string;
+  method: string;
+  path: string;
+  query?: URLSearchParams;
+  /**
+   * Encoded as JSON when it is present. `undefined` means no body at all,
+   * which is not the same as an empty object.
+   */
+  body?: unknown;
+  /**
+   * A form body, sent instead of `body`.
+   *
+   * The two are exclusive rather than ordered: an op carrying both is a
+   * generated method with a bug in it, and it is reported rather than resolved
+   * by a precedence somebody would have to look up.
+   */
+  form?: FormData;
+  /**
+   * The media type this call will take back. Absent means `application/json`,
+   * which is every endpoint but a download: a download answers with whatever
+   * the file turned out to be, and a client that insisted on JSON would be
+   * asking for the one thing it is not.
+   */
+  accept?: string;
+  /**
+   * The path to POST to when `method` is QUERY and something between here and
+   * the server refuses it — the `_search` alias the router mounts beside the
+   * QUERY route. Absent means there is none, and a refusal is reported rather
+   * than worked around.
+   */
+  fallback?: string;
+  /**
+   * Says the path is relative to the server rather than to the API's base
+   * path. The authentication endpoints are: `/auth/login` is mounted beside
+   * `/api/v1` and not inside it, because a sign-in is not a version of the
+   * application's API.
+   */
+  root?: boolean;
+};
+/**
+ * The HTTP method a generated search uses.
+ *
+ * A method rather than a POST because a search is a read: it has a body, and it
+ * is safe and idempotent, and pretending otherwise is what made every API in the
+ * world invent `/_search`.
+ */
+declare const METHOD_QUERY = "QUERY";
+//#endregion
+//#region src/errors.d.ts
+/**
+ * A request the server refused.
+ *
+ * The code, not the status, is what to switch on. Three unrelated failures
+ * share a 400 and none of them share a code, which is the whole reason the
+ * generated server sends one.
+ *
+ * `TFields` is the shape of the body that caused the refusal. A caller does not
+ * name it: the generated client declares a guard per call that does, so
+ * `isTodoCreateError(err)` reads back what `todos.create` refused. Naming it by
+ * hand is what `fieldsAs` asks for, and it is why the per-call guard exists —
+ * the wrong shape decodes perfectly and answers with an empty object, because
+ * every member of a field-error shape is optional.
+ */
+declare class RigError<TFields = unknown> extends Error {
+  /**
+   * The HTTP status, for the cases where only it is meaningful — a 502 from
+   * something in front of the server, say, which carries no code.
+   */
+  readonly status: number;
+  /**
+   * The machine-readable reason. Empty when the failure came from something
+   * that is not a rig server.
+   */
+  readonly code: ErrorCode | "";
+  /** Prose, for a person. It is not meant to be parsed. */
+  readonly detail: string;
+  /**
+   * Correlates this failure with the server's logs. Quoting it in a bug
+   * report is the difference between a search and a guess.
+   */
+  readonly requestId: string;
+  /**
+   * What was wrong with each member of the body — one member per field,
+   * holding what was wrong with it.
+   *
+   * `undefined` for every refusal but a 422. A 404 has a code and a message
+   * and nothing to put beside a control, and an empty object there would read
+   * as a body nobody complained about.
+   */
+  readonly fields: TFields | undefined;
+  /**
+   * How long the server asked the caller to wait, in milliseconds, from the
+   * header of the same name in either form it takes: the seconds rig's own
+   * server sends, and the date something in front of it might. Zero when it
+   * said nothing, or asked for a moment already past.
+   *
+   * The SDK honours it for a call it may repeat, so this is mostly for the
+   * refusal that came back anyway — where the interval was longer than the
+   * call had left to spend.
+   */
+  readonly retryAfterMs: number;
+  /**
+   * The start of the raw response, kept for a failure that decoded into
+   * nothing useful — a proxy's HTML error page, say. Bounded even where the
+   * read was not, so a large validation failure is complete in `fields` and
+   * cut short here.
+   */
+  readonly body: string;
+  constructor(init: {
+    status: number;
+    code?: ErrorCode | "";
+    detail?: string;
+    requestId?: string;
+    fields?: TFields;
+    retryAfterMs?: number;
+    body?: string;
+  });
+}
+/**
+ * The codes a rig server sends, matching `rig/runtime/rigerr`. The constant a
+ * client switches on is the constant a handler returned.
+ */
+declare const ErrorCode: {
+  readonly BadRequest: "BadRequest";
+  readonly Unauthorized: "Unauthorized";
+  readonly Forbidden: "Forbidden";
+  readonly NotFound: "NotFound";
+  readonly Conflict: "Conflict";
+  readonly UnprocessableEntity: "UnprocessableEntity";
+  readonly RateLimited: "RateLimited";
+  readonly TooLarge: "TooLarge";
+  readonly UnsupportedMediaType: "UnsupportedMediaType";
+  readonly UpgradeRequired: "UpgradeRequired";
+  readonly Internal: "Internal";
+};
+/** One of the codes in {@link ErrorCode}. */
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/**
+ * Why one member of a body was refused, matching `rig/runtime/rigerr`.
+ *
+ * The same nine codes for every project, so a form can decide what to show from
+ * the code and fall back to the message rather than parsing it.
+ */
+declare const FieldCode: {
+  readonly CannotBeEmpty: "CannotBeEmpty";
+  readonly CannotBeNull: "CannotBeNull";
+  readonly TooLong: "TooLong";
+  readonly TooShort: "TooShort";
+  readonly OutOfRange: "OutOfRange";
+  readonly InvalidValue: "InvalidValue";
+  readonly AlreadyExists: "AlreadyExists";
+  readonly NotFound: "NotFound";
+  readonly NotAllowed: "NotAllowed";
+};
+/** One of the codes in {@link FieldCode}. */
+type FieldCode = (typeof FieldCode)[keyof typeof FieldCode];
+/**
+ * What was wrong with one member of a body.
+ *
+ * It does not name the field. It is reached through the member of a generated
+ * field-error shape that stands for that field, so the name is where the value
+ * is and there is no second copy of it to disagree.
+ */
+type FieldError = {
+  code: FieldCode;
+  message: string;
+};
+/**
+ * Reports whether a thrown value is a refusal the server explained.
+ *
+ * False for anything that never reached the server — a DNS failure, an aborted
+ * request — because there is no envelope for a code or a field to have come
+ * from.
+ */
+declare function isRigError(err: unknown): err is RigError;
+/**
+ * The code on a refusal, or the empty string for anything else.
+ *
+ * The predicates below are one line each on top of it; reach for it directly
+ * when switching over several codes at once.
+ */
+declare function codeOf(err: unknown): ErrorCode | "";
+/** True when the row, or the route, was not there. */
+declare const isNotFound: (err: unknown) => boolean;
+/** True when the write lost a race, or would have broken a uniqueness rule. */
+declare const isConflict: (err: unknown) => boolean;
+/** True when the caller was not signed in, or the token had expired. */
+declare const isUnauthorized: (err: unknown) => boolean;
+/** True when the caller was signed in and still not allowed. */
+declare const isForbidden: (err: unknown) => boolean;
+/** True when the body was refused field by field. `fields` says which. */
+declare const isInvalid: (err: unknown) => boolean;
+/** True when the caller was asked to slow down. `retryAfterMs` says how long. */
+declare const isRateLimited: (err: unknown) => boolean;
+/** True when the body, or the upload, was over the limit. */
+declare const isTooLarge: (err: unknown) => boolean;
+/** True when the content type was not one this route accepts. */
+declare const isUnsupportedMediaType: (err: unknown) => boolean;
+/** True when the client is older than the API surface still supports. */
+declare const isUpgradeRequired: (err: unknown) => boolean;
+/**
+ * Reads a refusal back as the shape of the body that caused it.
+ *
+ * This is the hand-written counterpart of the generated per-call guards, for a
+ * request made through the runtime directly. It cannot check that the shape is
+ * the right one — that is what the generated guard is for.
+ */
+declare function fieldsAs<TFields>(err: unknown): TFields | undefined;
+//#endregion
+//#region src/transport.d.ts
+/** What a caller says about one call, on top of what the method already knows. */
+type CallOptions = {
+  /** Added to this request, replacing a client-wide header of the same name. */headers?: HeadersInit;
+  /**
+   * Added to the query string, winning over the operation's own where both
+   * name the same parameter.
+   */
+  query?: Record<string, string> | URLSearchParams; /** Aborts the call, retries and backoff included. */
+  signal?: AbortSignal; /** Bounds this call in milliseconds, overriding the client's own. */
+  timeoutMs?: number; /** Overrides how many times this one call is sent. */
+  attempts?: number;
+  /**
+   * Names this write, so a server that sees the same key twice answers the
+   * second send with what it answered the first.
+   *
+   * The SDK generates one for a write it may repeat. A caller's own is worth
+   * having where it is derived from the data — an import job naming a row by
+   * its line deduplicates a re-run of the whole job, which a fresh random name
+   * cannot.
+   */
+  idempotencyKey?: string; /** Overrides the request identifier for this call. */
+  requestId?: string; /** Sends no credential, for a route that must be reached signed out. */
+  anonymous?: boolean;
+  /**
+   * Asks for every row in the tenant rather than the caller's own, on a
+   * resource that is owner-scoped. Refused unless the caller holds the
+   * permission for it.
+   */
+  wide?: boolean;
+  /**
+   * Makes the read conditional. A 304 then comes back as `undefined` rather
+   * than as a failure — which is why it is gated on the option and not on the
+   * status alone: a 304 nobody asked for is an unexplained failure.
+   */
+  ifNoneMatch?: string;
+};
+/**
+ * Performs a call the document says answers with a body, and decodes it.
+ *
+ * A 204 where a body was promised throws rather than resolving to `undefined`.
+ * That is a deliberate trade against {@link sendOptional}: the alternative is
+ * every generated method answering `T | undefined`, so every call site narrows a
+ * value that in practice is always there — and the one time it is not, the
+ * server and the document disagree, which is a bug and reads better as one.
+ */
+declare function send<T>(rt: Runtime, op: Op, opts?: CallOptions): Promise<T>;
+/**
+ * Performs a call and decodes the response body, or `undefined` when there was
+ * none.
+ *
+ * This is the shape for an endpoint that can honestly answer either way, and for
+ * a request made through the runtime by hand.
+ */
+declare function sendOptional<T>(rt: Runtime, op: Op, opts?: CallOptions): Promise<T | undefined>;
+/**
+ * Performs a call that answers with nothing, such as a delete.
+ *
+ * Any body is drained and discarded rather than parsed: an endpoint that grows
+ * one later should not break a client that never wanted it.
+ */
+declare function sendNoContent(rt: Runtime, op: Op, opts?: CallOptions): Promise<void>;
+/**
+ * Performs a call and hands back the response unread, for a download.
+ *
+ * The caller owns the body from here: nothing below reads it, so streaming a
+ * large file does not require buffering it first.
+ */
+declare function sendContent(rt: Runtime, op: Op, opts?: CallOptions): Promise<Response>;
+//#endregion
+//#region src/paginate.d.ts
+/** One page of a paginated read, as far as the iteration cares. */
+type Page<T> = {
+  items: T[];
+  /**
+   * Every row matching the query, ignoring pagination. It is what says whether
+   * there is another page.
+   */
+  total: number; /** Where this page started, as the server reported it. */
+  offset: number;
+};
+/**
+ * Walks a paginated read to its end.
+ *
+ * `fetch` is handed the offset to ask for and returns one page; the limit is
+ * whatever the caller's query said, which `fetch` closes over. Iteration stops
+ * after the page that reaches the reported total, at the first failure, or when
+ * a page comes back empty — that last one is the guard against a server whose
+ * total disagrees with what it returns, which would otherwise be an infinite
+ * loop rather than a bug report.
+ *
+ * A failure is thrown, so `for await` reports it where the caller is standing.
+ * There is no partial answer: what came before the failure was yielded, and
+ * nothing after it is.
+ *
+ * ```ts
+ * for await (const todo of paginate(0, (offset) =>
+ *     client.todos.list({ limit: 100, offset }).then(toPage)
+ * )) {
+ *     …
+ * }
+ * ```
+ */
+declare function paginate<T>(startOffset: number, fetch: (offset: number) => Promise<Page<T>>): AsyncGenerator<T, void, undefined>;
+//#endregion
+//#region src/query.d.ts
+/**
+ * The query-string writers the generated methods call.
+ *
+ * Every one of them writes nothing for `undefined`, which is the point: the
+ * generated server applies a parameter's default only when the parameter is
+ * absent, so a client that helpfully sent `limit=0` would get an empty page
+ * instead of the default one. Absent has to stay absent.
+ *
+ * The formats match what the server parses: RFC 3339 for a time, the canonical
+ * hyphenated form for a UUID, `"true"`/`"false"` for a boolean.
+ */
+/** The types a query parameter can be given as. */
+type ParamValue = string | number | boolean | Date;
+/** Writes one parameter, or nothing when the value is absent. */
+declare function setParam(query: URLSearchParams, key: string, value: ParamValue | null | undefined): void;
+/**
+ * Writes a repeated parameter, one key per value.
+ *
+ * An empty array writes nothing rather than an empty key, for the same reason a
+ * single absent value does: the server distinguishes "no filter" from "a filter
+ * matching nothing".
+ */
+declare function setParams(query: URLSearchParams, key: string, values: readonly ParamValue[] | null | undefined): void;
+/**
+ * Escapes a value for a path segment.
+ *
+ * An identifier that arrived from somewhere else can be anything at all, and a
+ * slash in one would otherwise silently address a different route.
+ */
+declare function pathValue(value: string): string;
+//#endregion
+//#region src/upload.d.ts
+/** One file a caller is sending. */
+type Upload = {
+  /**
+   * What the file is called. The server records it on the row and puts it in
+   * the download path, and it never becomes the storage key — so a name with a
+   * slash in it is a strange name and not a way out of the bucket.
+   */
+  name: string; /** The bytes. A `File` from an `<input type="file">` is already one of these. */
+  body: Blob;
+  /**
+   * What the caller claims the bytes are. Absent takes the blob's own type,
+   * and it makes little difference either way: the server sniffs the content,
+   * and the sniffed type is the one it stores and the one it serves back.
+   */
+  contentType?: string;
+};
+/**
+ * Builds the `multipart/form-data` body rig's upload endpoints take: the row,
+ * and the files beside it.
+ *
+ * It is the shape rig's own endpoints take rather than a general form encoder. A
+ * generated method calls it; a caller supplies the {@link Upload}s.
+ *
+ * `row` is left out entirely when absent, which is what a bare upload does:
+ * there is no row to send, only bytes for a row that already exists.
+ *
+ * An absent upload is left out the same way, so a generated method can name
+ * every file column of a create unconditionally. What makes a required one
+ * impossible to leave out is the generated shape it arrives in — the member is
+ * optional there only where the column is nullable — and not a check here,
+ * which would report at runtime what the compiler has already refused.
+ */
+declare function multipart(row: unknown, files: ReadonlyArray<readonly [field: string, upload: Upload | undefined]>): FormData;
+//#endregion
+export { type ApiDescriptor, type AuthProfile, type Bindable, type CallOptions, type Config, type Credential, DEFAULT_REQUEST_ID_HEADER, DEFAULT_REVISION_HEADER, ErrorCode, FieldCode, type FieldError, METHOD_QUERY, NoSessionError, type Op, type Page, type ParamValue, type RateLimitStatus, type Reauthorizer, type Retry, RigError, Runtime, Session, type TokenPair, type Upload, apiKey, codeOf, fieldsAs, fraction, isConflict, isForbidden, isInvalid, isNotFound, isRateLimited, isReauthorizer, isRigError, isTooLarge, isUnauthorized, isUnsupportedMediaType, isUpgradeRequired, multipart, paginate, pathValue, rateLimitOf, send, sendContent, sendNoContent, sendOptional, setParam, setParams, staticToken, used };