better-supabase 0.11.0 → 0.13.0

package/dist/api-DwLhJS1j.d.ts

@@ -0,0 +1,444 @@
+import { F as SchemaMeta } from "./types-DmshMaXz.js";
+import { h as MutationIntent } from "./executor-C29668fO.js";
+import { xt as EventMap } from "./events-DhGgwqQA.js";
+import { n as AnyPlugin } from "./plugin-DouW0Kvg.js";
+import { t as SPEC_PINS } from "./spec-pins-CZ2CL8YZ.js";
+import { C as ModelWebhook, E as OperationSource, O as SecurityRequirement, S as ModelTag, a as JsonSchema, b as ModelServer, d as ModelInfo, f as ModelMessage, i as JsonObject, m as ModelOperation, n as DataApiOperation, p as ModelMessageTrait, r as HttpMethod, s as ModelChannel, t as ApiModel, v as ModelSecurityProfileRequirement, w as ModelWorkflow, y as ModelSecurityScheme } from "./model-Btl8X9cs.js";
+import { c as SpecDiagnostic, i as DocumentOf, l as VersionOf, s as RenderedOf, t as AnyDocumentFormat } from "./format-AYHceC2m.js";
+import { o as Authorizer } from "./authorizer-DFP3gHv8.js";
+import { a as ResourcePlan, o as StandardLike, r as ResourceDescription, t as ErrorResponse } from "./resource-DxQOPkZ5.js";
+import { t as RealtimeStatus } from "./realtime-status-BhNkb-Ow.js";
+import { n as CloudEventOptions } from "./cloud-event-CidL9jiw.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/openapi/types.d.ts
+type Json = Record<string, unknown>;
+/**
+ * The OpenAPI versions `openapiFormat` renders. `3.3-preview` follows the
+ * v3.3-dev branch.
+ */
+type OpenApiVersion = "3.0" | "3.1" | "3.2" | "3.3-preview";
+/** The `openapi` field `3.3-preview` emits, as in the v3.3-dev branch. */
+declare const OPENAPI_33_PREVIEW_VERSION = "3.3.0";
+interface OpenApiInfo {
+  readonly title: string;
+  readonly version: string;
+  /** OpenAPI 3.1 and later. */
+  readonly summary?: string;
+  readonly description?: string;
+  readonly termsOfService?: string;
+  readonly contact?: {
+    readonly name?: string;
+    readonly url?: string;
+    readonly email?: string;
+  };
+  readonly license?: {
+    readonly name: string;
+    /** OpenAPI 3.1 and later. */
+    readonly identifier?: string;
+    readonly url?: string;
+  };
+}
+type OpenApiSecurityRequirement = Readonly<Record<string, readonly string[]>>;
+type OpenApiComponents = {
+  readonly schemas: Readonly<Record<string, Json>>;
+  readonly responses: Readonly<Record<string, Json>>;
+  readonly securitySchemes: Readonly<Record<string, Json>>;
+};
+interface OpenApiDocumentBase {
+  readonly info: OpenApiInfo;
+  readonly servers?: readonly Json[];
+  readonly tags: readonly Json[];
+  /** Path templates to Path Item objects. */
+  readonly paths: Readonly<Record<string, Json>>;
+  readonly components: OpenApiComponents;
+  readonly security: readonly OpenApiSecurityRequirement[];
+  readonly [extension: `x-${string}`]: unknown;
+}
+/** OpenAPI 3.0 (legacy): schemas use `nullable` and `example`, no webhooks. */
+interface OpenApi30Document extends OpenApiDocumentBase {
+  readonly openapi: typeof SPEC_PINS.openapi30;
+}
+/** OpenAPI 3.1: 3.2 fields travel as the registered `x-oai-*` extensions. */
+interface OpenApi31Document extends OpenApiDocumentBase {
+  readonly openapi: typeof SPEC_PINS.openapi31;
+  readonly jsonSchemaDialect: string;
+  readonly webhooks?: Readonly<Record<string, Json>>;
+}
+/**
+ * OpenAPI 3.2: native `$self`, nested tags, `itemSchema`, `oauth2MetadataUrl`
+ * and `query`.
+ */
+interface OpenApi32Document extends OpenApiDocumentBase {
+  readonly openapi: typeof SPEC_PINS.openapi32;
+  readonly $self?: string;
+  readonly jsonSchemaDialect: string;
+  readonly webhooks?: Readonly<Record<string, Json>>;
+}
+/**
+ * The 3.3 draft: 3.2 plus Path Item `security` and the Security Profiles
+ * proposal.
+ */
+interface OpenApi33PreviewDocument extends OpenApiDocumentBase {
+  readonly openapi: typeof OPENAPI_33_PREVIEW_VERSION;
+  readonly $self?: string;
+  readonly jsonSchemaDialect: string;
+  readonly webhooks?: Readonly<Record<string, Json>>;
+  readonly components: OpenApiComponents & {
+    readonly securityProfileRequirements?: Readonly<Record<string, Json>>;
+  };
+}
+interface OpenApiDocuments {
+  readonly "3.0": OpenApi30Document;
+  readonly "3.1": OpenApi31Document;
+  readonly "3.2": OpenApi32Document;
+  readonly "3.3-preview": OpenApi33PreviewDocument;
+}
+/** An OpenAPI document of one version; 3.1 by default. */
+type OpenApiDocument<V extends OpenApiVersion = "3.1"> = OpenApiDocuments[V];
+type AnyOpenApiDocument = OpenApiDocuments[OpenApiVersion];
+/** What an OpenAPI `transform` receives, discriminated by `version`. */
+type RenderedOpenApi = { readonly [V in OpenApiVersion]: {
+  readonly format: "openapi";
+  readonly version: V;
+  readonly document: OpenApiDocuments[V];
+}; }[OpenApiVersion];
+//#endregion
+//#region src/spec/presets.d.ts
+/** JSON Schema for RFC 9457 Problem Details as better-supabase sends them. */
+declare const PROBLEM_SCHEMA: Record<string, unknown>;
+/** The default error responses: today's Problem Details answers, 400 to 422. */
+declare const DEFAULT_ERRORS: readonly ErrorResponse[];
+/** A security scheme of your own, with the scopes its requirement asks for. */
+interface CustomSecurity {
+  /** The component name of the scheme. */
+  readonly name: string;
+  readonly scheme: ModelSecurityScheme;
+  readonly scopes?: readonly string[];
+}
+/**
+ * `bearer`: a Supabase access token (`supabaseJwt`). `oauth2`: the Supabase
+ * OAuth 2.1 server (`supabaseOAuth`, needs `supabaseUrl`). `apiKey`: the
+ * project's publishable key in the `apikey` header (`supabaseApiKey`). Each
+ * preset is one alternative requirement.
+ */
+type SecurityPreset = "bearer" | "oauth2" | "apiKey" | CustomSecurity;
+//#endregion
+//#region src/spec/data-api.d.ts
+/** Which tables and functions the Data API (PostgREST) section documents. */
+interface DataApiOptions {
+  /** Tables and views by app key, or `true` for all of them. */
+  readonly tables?: true | readonly string[];
+  /** Functions by key, or `true` for all of them, as `POST /rest/v1/rpc/<name>`. */
+  readonly functions?: true | readonly string[];
+  /**
+   * The operations per table, by app key. Defaults to all four for a table and
+   * to the ones its columns allow for a view.
+   */
+  readonly operations?: Readonly<Record<string, readonly DataApiOperation[]>>;
+  /** The tag of every Data API operation. Defaults to `Data API`. */
+  readonly tag?: string;
+}
+//#endregion
+//#region src/spec/events.d.ts
+/** A schema for a block event's data, checked against the block's event map. */
+type BlockEventSchema<T> = StandardSchemaV1<unknown, T>;
+/**
+ * Data schemas for block events, by event type, typed by an event map such as
+ * `EventMapOf<typeof commentsEvents>`. `true` documents the event with an open
+ * payload. A block can export its own map of this type.
+ */
+type BlockEventSchemas<M extends EventMap = EventMap> = { readonly [K in keyof M & string]?: true | BlockEventSchema<M[K]>; };
+/**
+ * A Realtime broadcast topic. A `defineTopic()` result fits as it is, with its
+ * event and presence schemas, `send` and `permission`; `topicsFrom()` collects
+ * them from a module.
+ */
+interface TopicInput<Ref = string> {
+  readonly template: string;
+  readonly name?: string;
+  readonly private?: boolean;
+  readonly presence?: boolean;
+  /** The schema of each tracked presence state; open when unset. */
+  readonly presenceSchema?: StandardLike | undefined;
+  /** Payload schema per broadcast event; `true` for an open payload. */
+  readonly events?: Readonly<Record<string, StandardLike | true>>;
+  /**
+   * Clients may broadcast on the topic, not only receive. Only `true` counts,
+   * so a `defineTopic()` result's `send` method is ignored.
+   */
+  readonly send?: boolean | ((...args: never[]) => unknown);
+  /** The same as `send: true`; what a `defineTopic()` result carries. */
+  readonly clientSend?: boolean;
+  readonly permission?: Ref | undefined;
+  /** Supabase's status for the topic's features. Defaults from `private`. */
+  readonly status?: RealtimeStatus;
+  readonly summary?: string;
+  readonly description?: string;
+}
+/**
+ * The `defineTopic()` results in modules or arrays, for `events.topics`. A
+ * module's topics are keyed by export name; a topic in an array by its `name`.
+ * Other values are skipped, and a topic reached twice is kept once.
+ *
+ * ```ts
+ * import * as topics from "../realtime/topics";
+ * defineApi(betterSupabase, {
+ *   info,
+ *   events: { topics: topicsFrom(topics) },
+ * });
+ * ```
+ */
+declare function topicsFrom(...sources: readonly (Readonly<Record<string, unknown>> | readonly unknown[])[]): Readonly<Record<string, TopicInput>>;
+/** CloudEvents the app sends (`forwardMutations`, `forwardBlockEvents`). */
+interface CloudEventsInput extends Pick<CloudEventOptions, "source" | "typePrefix" | "dataschema"> {
+  /** The sink's address. Defaults to `events`. */
+  readonly address?: string;
+  /** Row events for these tables (`true` for every table). Defaults to none. */
+  readonly rows?: boolean | readonly string[];
+  /** Which row events. Defaults to insert, update and delete. */
+  readonly intents?: readonly MutationIntent[];
+  /** Block events and their data schemas. */
+  readonly blocks?: BlockEventSchemas;
+}
+/** Channels and messages for AsyncAPI, built from the schema and the app. */
+interface EventsOptions<Ref = string> {
+  /**
+   * Table change signals (`bs:t:<schema>.<table>`) for the tables in
+   * `realtime.tables`: `true` for all, or app keys. Defaults to `true`.
+   */
+  readonly tables?: boolean | readonly string[];
+  /** Realtime broadcast topics, by key. */
+  readonly topics?: Readonly<Record<string, TopicInput<Ref>>>;
+  readonly cloudEvents?: CloudEventsInput;
+}
+/** The CloudEvents attributes in HTTP binary mode (`ce-*` headers). */
+declare const CLOUD_EVENT_TRAIT: ModelMessageTrait;
+//#endregion
+//#region src/spec/options.d.ts
+/** What `defineApi` reads from a `defineSupabase()` result. */
+interface ApiSource {
+  readonly meta: SchemaMeta;
+  readonly plugins?: readonly AnyPlugin[];
+}
+/**
+ * A resource: its description, `true` for the defaults, or a handler that
+ * carries its plan.
+ */
+type ResourceInput<Ref = string> = ResourceDescription<Ref> | true | {
+  readonly plan: ResourcePlan<Ref>;
+};
+/** A custom route, documented from its Standard Schemas (Standard JSON Schema). */
+interface RouteSpec<Ref = string> {
+  readonly method: HttpMethod | Uppercase<HttpMethod>;
+  /** Relative to `basePath`, with `{name}` path parameters. */
+  readonly path: string;
+  readonly operationId?: string;
+  readonly summary?: string;
+  readonly description?: string;
+  readonly tags?: readonly string[];
+  readonly deprecated?: boolean;
+  /** The path parameters, as an object schema. Unlisted ones are strings. */
+  readonly params?: StandardLike;
+  /** The query parameters, as an object schema. */
+  readonly query?: StandardLike;
+  /** The JSON body. */
+  readonly input?: StandardLike;
+  /** The JSON response. Without it (and without `stream`) the route answers 204. */
+  readonly output?: StandardLike;
+  /**
+   * A stream response: each item's schema (`itemSchema`), by default as
+   * `text/event-stream`.
+   */
+  readonly stream?: {
+    readonly item: StandardLike;
+    readonly contentType?: string;
+  };
+  /** Success status. Defaults to 200 with an output or stream, 204 without. */
+  readonly status?: number;
+  /** Overrides the API's security; `[]` makes the route public. */
+  readonly security?: readonly SecurityRequirement[];
+  readonly permission?: Ref;
+  /** The shared error responses. Defaults to the API's `errors`. */
+  readonly errors?: readonly ErrorResponse[];
+  /** Deep-merged into the rendered operation. */
+  readonly extend?: JsonObject;
+}
+interface OperationIdContext {
+  readonly source: OperationSource;
+  readonly method: HttpMethod;
+  readonly path: string;
+  /** The id better-supabase would use, e.g. `listCustomers`. */
+  readonly defaultId: string;
+}
+type ComponentNameContext = {
+  readonly kind: "table";
+  readonly table: string;
+  readonly variant: "Row" | "Insert" | "Update" | "Page";
+  readonly defaultName: string;
+} | {
+  readonly kind: "schema";
+  /** The name from the schema's own `$id` or `id` metadata. */
+  readonly id: string | undefined;
+  readonly schema: JsonSchema;
+  readonly role: "input" | "output" | "item";
+  readonly operationId: string;
+};
+/**
+ * Version-neutral hooks on the model. Return a replacement, or nothing to keep
+ * it.
+ */
+interface EnrichHooks {
+  readonly operation?: (operation: ModelOperation) => ModelOperation | undefined;
+  readonly schema?: (schema: JsonSchema, context: {
+    readonly name: string;
+  }) => JsonSchema | undefined;
+  readonly channel?: (channel: ModelChannel) => ModelChannel | undefined;
+  readonly message?: (message: ModelMessage, context: {
+    readonly id: string;
+  }) => ModelMessage | undefined;
+  readonly workflow?: (workflow: ModelWorkflow) => ModelWorkflow | undefined;
+}
+interface ApiOptions<Ref = string> {
+  readonly info: ModelInfo;
+  /** The document's own URL (`$self`). */
+  readonly self?: string;
+  readonly servers?: readonly ModelServer[];
+  /** Prefix for every path, e.g. `/api`. */
+  readonly basePath?: string;
+  /** Tags listed before the resource tags, with summaries and parents. */
+  readonly tags?: readonly ModelTag[];
+  /** Tables to publish, by app key. */
+  readonly resources?: Readonly<Record<string, ResourceInput<Ref>>>;
+  readonly routes?: readonly RouteSpec<Ref>[];
+  /**
+   * Tables and functions to document as the Supabase Data API (`/rest/v1`),
+   * with database names.
+   */
+  readonly dataApi?: DataApiOptions;
+  /** Parsed OpenAPI fragments, merged over the generated document. */
+  readonly fragments?: readonly JsonObject[];
+  /** Defaults to `['bearer']`. */
+  readonly security?: readonly SecurityPreset[];
+  /** The project URL, for the `oauth2` preset. */
+  readonly supabaseUrl?: string;
+  /** Shared error responses. Defaults to `DEFAULT_ERRORS`. */
+  readonly errors?: readonly ErrorResponse[];
+  readonly operationId?: (context: OperationIdContext) => string;
+  /**
+   * Names a component; `undefined` keeps the default (tables) or inlines it
+   * (schemas).
+   */
+  readonly componentName?: (context: ComponentNameContext) => string | undefined;
+  /** Prefix of generated `x-` fields. Defaults to `x-better-supabase-`. */
+  readonly extensionPrefix?: string;
+  /** Example rows per table (app-cased), set as the Row schema's `examples`. */
+  readonly examples?: Readonly<Record<string, readonly JsonObject[]>>;
+  readonly enrich?: EnrichHooks;
+  /** Resolves permission references to keys (`key()`) and `permissions: true`. */
+  readonly authorizer?: Authorizer<Ref>;
+  /** Report `permission-missing` for writes that declare no permission. */
+  readonly requirePermissions?: boolean;
+  /** `keys`: each permission key is also an OAuth scope of the `oauth2` preset. */
+  readonly permissionScopes?: "keys";
+  /** Security Profile Requirements (preview; only `3.3-preview` renders them). */
+  readonly securityProfileRequirements?: Readonly<Record<string, ModelSecurityProfileRequirement>>;
+  /** The Realtime websocket URL, for AsyncAPI. */
+  readonly realtimeUrl?: string;
+  readonly channels?: readonly ModelChannel[];
+  readonly messages?: Readonly<Record<string, ModelMessage>>;
+  /** Realtime tables, topics and CloudEvents, as channels and messages. */
+  readonly events?: EventsOptions<Ref>;
+  readonly webhooks?: readonly ModelWebhook[];
+  /**
+   * Workflows, or functions that build them from the operations (the Arazzo
+   * built-ins).
+   */
+  readonly workflows?: readonly (ModelWorkflow | WorkflowSource)[];
+  /** Tables with a JSON column typed in `better-supabase.config.ts`. */
+  readonly json?: Readonly<Record<string, unknown>>;
+}
+/** Builds workflows from the model's operations, after enrich hooks ran on them. */
+type WorkflowSource = (operations: readonly ModelOperation[]) => readonly ModelWorkflow[];
+interface BuiltModel {
+  readonly model: ApiModel;
+  /** Findings while building: permissions, components, schemas, plugins. */
+  readonly diagnostics: readonly SpecDiagnostic[];
+}
+//#endregion
+//#region src/spec/api.d.ts
+/**
+ * Applies Overlay documents in order to a rendered document and reports what it
+ * found. `better-supabase/overlay` provides one: `(doc, overlays) =>
+ * applyOverlays(doc, overlays, { jsonpath })`.
+ */
+type OverlayEngine = (document: unknown, overlays: readonly unknown[]) => {
+  readonly document: unknown;
+  readonly diagnostics?: readonly SpecDiagnostic[];
+};
+interface RenderOptions<F extends AnyDocumentFormat> {
+  /** Defaults to the format's default version. */
+  readonly version?: VersionOf<F>;
+  /**
+   * Last change to the lowered document, before overlays. It receives a copy,
+   * typed per version; return a replacement or change it in place.
+   */
+  readonly transform?: (rendered: RenderedOf<F>) => DocumentOf<F> | undefined;
+  readonly overlays?: readonly unknown[];
+  /** Overrides the API's `applyOverlays`. */
+  readonly applyOverlays?: OverlayEngine;
+}
+interface RenderResult<F extends AnyDocumentFormat> {
+  readonly format: F["id"];
+  readonly version: VersionOf<F>;
+  readonly document: DocumentOf<F>;
+  /** Building, lowering, overlay and lint findings, without duplicates. */
+  readonly diagnostics: readonly SpecDiagnostic[];
+  readonly fileName: string;
+}
+interface OpenApiRenderOptions<V extends OpenApiVersion> {
+  readonly version?: V;
+  readonly transform?: (rendered: Extract<RenderedOpenApi, {
+    readonly version: V;
+  }>) => OpenApiDocuments[OpenApiVersion] | undefined;
+  readonly overlays?: readonly unknown[];
+  readonly applyOverlays?: OverlayEngine;
+}
+interface OpenApiRenderResult<V extends OpenApiVersion> {
+  readonly format: "openapi";
+  readonly version: V;
+  readonly document: OpenApiDocuments[V];
+  readonly diagnostics: readonly SpecDiagnostic[];
+  readonly fileName: string;
+}
+interface DefineApiOptions<Ref = string> extends ApiOptions<Ref> {
+  /** The default overlay engine for `overlays` in `render`. */
+  readonly applyOverlays?: OverlayEngine;
+}
+interface Api {
+  readonly model: ApiModel;
+  /** Findings while building the model. */
+  readonly diagnostics: readonly SpecDiagnostic[];
+  /**
+   * Lowers the model to a version of any `DocumentFormat`, then runs
+   * `transform`, overlays and the format's lint.
+   */
+  render<F extends AnyDocumentFormat>(format: F, options?: RenderOptions<F>): RenderResult<F>;
+  /** `render(openapiFormat, options)`, typed per version. Defaults to 3.1. */
+  openapi<V extends OpenApiVersion = "3.1">(options?: OpenApiRenderOptions<V>): OpenApiRenderResult<V>;
+}
+/**
+ * The API model for a `defineSupabase()` result, and the documents it renders.
+ * The model is built once per options object; each format and version is
+ * lowered once and copied for every render.
+ *
+ * ```ts
+ * const api = defineApi(betterSupabase, {
+ *   info: { title: "CRM API", version: "1.0.0" },
+ *   resources: { customers: { list: customerList } },
+ * });
+ * const { document } = api.openapi({ version: "3.2" });
+ * ```
+ */
+declare function defineApi<Ref = string>(source: ApiSource, options: DefineApiOptions<Ref>): Api;
+//#endregion
+export { AnyOpenApiDocument as A, OpenApiSecurityRequirement as B, TopicInput as C, DEFAULT_ERRORS as D, CustomSecurity as E, OpenApi33PreviewDocument as F, RenderedOpenApi as H, OpenApiComponents as I, OpenApiDocument as L, OpenApi30Document as M, OpenApi31Document as N, PROBLEM_SCHEMA as O, OpenApi32Document as P, OpenApiDocuments as R, EventsOptions as S, DataApiOptions as T, OpenApiVersion as V, WorkflowSource as _, OverlayEngine as a, CLOUD_EVENT_TRAIT as b, defineApi as c, BuiltModel as d, ComponentNameContext as f, RouteSpec as g, ResourceInput as h, OpenApiRenderResult as i, OPENAPI_33_PREVIEW_VERSION as j, SecurityPreset as k, ApiOptions as l, OperationIdContext as m, DefineApiOptions as n, RenderOptions as o, EnrichHooks as p, OpenApiRenderOptions as r, RenderResult as s, Api as t, ApiSource as u, BlockEventSchema as v, topicsFrom as w, CloudEventsInput as x, BlockEventSchemas as y, OpenApiInfo as z };

package/dist/api-keys-Bade6Qtl.d.ts

@@ -0,0 +1,213 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult } from "./result-mijqfoJN.js";
+import { t as StandardSchemaV1 } from "./standard-16AIDny5.js";
+import { r as FieldsOf } from "./block-fields-DnXkMney.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { n as AuthResolver } from "./resolve-D57oDWNr.js";
+import { t as BlockTransport } from "./block-transport-DBPhgF3W.js";
+import { r as BlockTemporalOptions } from "./block-helpers-DyA5BAW4.js";
+import { n as BlockHooks } from "./block-hooks-BadAniNI.js";
+import { JWTClaims } from "@supabase/server";
+//#region src/blocks/api-keys/api-keys.d.ts
+type ApiKeyState = "active" | "grace" | "revoked" | "expired";
+interface ApiKey {
+  readonly id: string;
+  /** Set for a tenant key, and for a personal key limited to one tenant. */
+  readonly organizationId?: string;
+  /** Set for a personal key: it acts as this user. */
+  readonly userId?: string;
+  readonly name: string;
+  readonly prefix: string;
+  readonly publicId: string;
+  readonly scopes: readonly string[];
+  /** What the key is for, one of `blocks.api-keys.options.kinds`. */
+  readonly kind?: string;
+  /** Requests per minute, when the key has a limit. */
+  readonly rateLimit?: number;
+  readonly expiresAt?: Temporal.Instant;
+  readonly lastUsedAt?: Temporal.Instant;
+  /** In the future while a rotated key's grace period runs. */
+  readonly revokedAt?: Temporal.Instant;
+  readonly rotatedFrom?: string;
+  readonly createdBy?: string;
+  readonly createdAt: Temporal.Instant;
+  readonly state: ApiKeyState;
+  readonly successorId?: string;
+}
+/** A new key. `token` is shown once: only its hash is stored. */
+interface CreatedApiKey<F extends object = Record<never, never>> {
+  readonly key: ApiKey & F;
+  readonly token: string;
+}
+interface CreateApiKeyInput {
+  readonly name: string;
+  /** The tenant the key acts in. Required unless `personal`. */
+  readonly organizationId?: string;
+  /** Acts as the signed-in user (in `organizationId` only, when set). */
+  readonly personal?: boolean;
+  /** `*` grants every scope. */
+  readonly scopes?: readonly string[];
+  /** What the key is for, one of `blocks.api-keys.options.kinds`. */
+  readonly kind?: string;
+  readonly expiresAt?: Temporal.Instant;
+  /** Requests per minute. */
+  readonly rateLimit?: number;
+}
+type ApiKeyCheck<F extends object = Record<never, never>> = {
+  readonly status: "ok";
+  readonly key: ApiKey & F;
+} | {
+  readonly status: "invalid";
+} | {
+  readonly status: "rate_limited";
+  readonly retryAfter: number;
+};
+/** `F` is the extra key fields `options.fields` describes. */
+interface ApiKeys<F extends object = Record<never, never>> {
+  /** Keys besides the input's own are the key's extra columns. */
+  create(input: CreateApiKeyInput & Partial<F>): AsyncResult<CreatedApiKey<F>>;
+  /**
+   * A tenant's keys for its managers (the caller's own otherwise), or the
+   * caller's personal keys.
+   */
+  list(organizationId?: string): AsyncResult<readonly (ApiKey & F)[]>;
+  revoke(id: string): AsyncResult<boolean>;
+  /**
+   * A new token for the key, with its extra columns; the old one keeps working
+   * for `grace` (one day by default).
+   */
+  rotate(id: string, options?: {
+    readonly grace?: Temporal.Duration;
+  }): AsyncResult<CreatedApiKey<F>>;
+  /**
+   * Checks a presented token and counts the request. Needs a service transport.
+   * A token that doesn't parse, such as `<prefix>_bad`, is `invalid`.
+   */
+  verify(token: string): AsyncResult<ApiKeyCheck<F>>;
+  /**
+   * Whether a token claims to be one of these keys: it starts with the prefix
+   * and `_`, well formed or not. Use it to send a Bearer token to `verify`
+   * instead of JWT verification.
+   */
+  isApiKey(token: string): boolean;
+}
+interface ApiKeysOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  /**
+   * A Standard Schema for the key columns the app adds
+   * (`blocks.api-keys.options.extraColumns`), keyed by column name. It types
+   * and parses them on every read, and validates them on `create`, which
+   * returns a `validation` error for a bad value.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<ApiKeys<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  readonly transport: BlockTransport;
+  readonly schema?: string;
+  /** The token's first segment, lowercase letters and digits. Defaults to `bs`. */
+  readonly prefix?: string;
+}
+interface ParsedApiKey {
+  readonly prefix: string;
+  readonly publicId: string;
+  readonly secret: string;
+  /** Whether the token ends in a checksum; keys created before it have none. */
+  readonly checksum: boolean;
+}
+/**
+ * The CRC-32 (IEEE 802.3) of `text` as 6 base62 characters: the checksum
+ * GitHub-style tokens end in, so a secret scanner or the server rejects a
+ * mistyped key without a lookup.
+ */
+declare function apiKeyChecksum(text: string): string;
+/**
+ * Splits `<prefix>_<public id>_<secret><checksum>`: a 43-character base62
+ * secret and the 6-character checksum of everything before it. A key from
+ * before the checksum (`<prefix>_<public id>_<secret>`) still parses. A
+ * checksum that doesn't match, or anything else (a JWT, say), is `undefined`.
+ */
+declare function parseApiKey(token: string): ParsedApiKey | undefined;
+/**
+ * API keys over the `api-keys` SQL module. Members create and rotate keys with
+ * their own transport; `verify` (and `apiKeyResolver`) need one that runs as
+ * the service role.
+ */
+declare function createApiKeys<S extends StandardSchemaV1 | undefined = undefined>(options: ApiKeysOptions<S>): ApiKeys<FieldsOf<S>>;
+/**
+ * A second claim for an authorization provider's SQL functions, with the field
+ * names they read. Every field but `name` is optional.
+ */
+interface ApiKeyExtraClaim {
+  /** The claim. `api_key` adds the fields to the module's own claim. */
+  readonly name: string;
+  /** The field with the permission keys, default `scopes`. */
+  readonly scopes?: string;
+  /** The field with a tenant key's tenant, default `tenant`. */
+  readonly tenant?: string;
+  /** The field with a tenant key's roles, default `roles`. */
+  readonly roles?: string;
+  /**
+   * The roles a tenant key holds in its tenant, unless `serviceRoles` in the
+   * options answers.
+   */
+  readonly serviceRoles?: readonly string[];
+}
+/** The claims a key's JWT always carries, which `claims` cannot set. */
+type ApiKeyReservedClaim = "sub" | "role" | "aud" | "api_key";
+/** Extra claims from the `claims` hook: any key but the reserved ones. */
+type ApiKeyExtraClaims = Readonly<Record<string, unknown>> & { readonly [K in ApiKeyReservedClaim]?: never; };
+/** `F` is the extra key fields of `createApiKeys({ fields })`. */
+interface ApiKeyClaimsOptions<F extends object = Record<never, never>> {
+  /**
+   * Also write the claim an authorization provider's SQL functions read: the
+   * scopes as a ceiling, and a tenant key's tenant and roles.
+   */
+  readonly claim?: ApiKeyExtraClaim;
+  /** The roles a tenant key holds in its tenant; default `claim.serviceRoles`. */
+  readonly serviceRoles?: (key: ApiKey & F) => readonly string[];
+  /**
+   * Claims to add for a key, such as one read from its `kind` or an extra
+   * column. `sub`, `role`, `aud`, `api_key` and the claims the other options
+   * write keep their values.
+   */
+  readonly claims?: (key: ApiKey & F) => ApiKeyExtraClaims;
+  /**
+   * The permission keys `*` stands for in `claim`, which has no wildcard, so
+   * without this a key with `*` allows nothing there.
+   */
+  readonly allPermissions?: readonly string[];
+  /**
+   * The claim that narrows a provider's functions to one tenant (such as
+   * `tenant_id`), set for a personal key limited to a tenant.
+   */
+  readonly tenantClaim?: string;
+}
+interface ApiKeyResolverOptions<F extends object = Record<never, never>> extends ApiKeyClaimsOptions<F> {
+  /**
+   * `createApiKeys` over a service transport. With `isApiKey`, a Bearer token
+   * with the key prefix is checked as a key even when it is malformed, so it
+   * gets `INVALID_API_KEY`.
+   */
+  readonly keys: Pick<ApiKeys<F>, "verify"> & Partial<Pick<ApiKeys<F>, "isApiKey">>;
+  /**
+   * The header that carries the key besides `Authorization: Bearer`. Defaults
+   * to `x-api-key`.
+   */
+  readonly header?: string;
+}
+/**
+ * The claims queries run with for a key: `api_key` with `id`, `name`, `scopes`
+ * and `organization_id` for the module's `has_scope()` and `api_key_tenant()`,
+ * plus `options.claim` and `options.claims`.
+ */
+declare function apiKeyClaims<F extends object = Record<never, never>>(key: ApiKey & F, options?: ApiKeyClaimsOptions<F>): JWTClaims;
+/**
+ * Resolves `x-api-key` (or a Bearer token shaped like a key, or one with the
+ * key prefix) to an `apiKey` auth state. Requests without one fall through to
+ * the JWT and cookie resolution. Pass it to `createServer({ auth: { resolvers:
+ * [...] } })`.
+ */
+declare function apiKeyResolver<F extends object = Record<never, never>>(options: ApiKeyResolverOptions<F>): AuthResolver;
+//#endregion
+export { createApiKeys as _, ApiKeyExtraClaims as a, ApiKeyState as c, CreateApiKeyInput as d, CreatedApiKey as f, apiKeyResolver as g, apiKeyClaims as h, ApiKeyExtraClaim as i, ApiKeys as l, apiKeyChecksum as m, ApiKeyCheck as n, ApiKeyReservedClaim as o, ParsedApiKey as p, ApiKeyClaimsOptions as r, ApiKeyResolverOptions as s, ApiKey as t, ApiKeysOptions as u, parseApiKey as v };