@voltro/protocol 0.84.0 → 0.86.0

package/dist/rest.d.ts

@@ -1,8 +1,9 @@
 import * as AST from 'effect/SchemaAST';
 import { DataStore } from '@voltro/database';
+import { Effect } from 'effect';
 import { Schema } from 'effect';
 
-declare interface ActionProcedureDescriptor<Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Error extends Schema.Schema.All> {
+declare interface ActionProcedureDescriptor<Name extends string, Input extends Schema.Top, Output extends Schema.Top, Error extends Schema.Top> {
     readonly kind: 'action';
     readonly name: Name;
     readonly input: Input;
@@ -113,7 +114,7 @@ export declare const bytes: (stream: ReadableStream<Uint8Array> | (() => Readabl
  * Field by field for a struct; the object is returned unchanged for any other
  * shape (the schema then decides). Unknown keys pass through untouched.
  */
-export declare const coerceQueryObject: (query: unknown, input: Schema.Schema.All) => unknown;
+export declare const coerceQueryObject: (query: unknown, input: Schema.Top) => unknown;
 
 /**
  * Coerce ONE query-string value toward what `ast` (an ENCODED shape) expects.
@@ -144,7 +145,7 @@ export declare const collectPublicApiRoutes: (entries: ReadonlyArray<PublicApiEn
 declare type DeclaredAccess<Input = unknown> = ReadonlyArray<AnyGuardSpec<Input> | OpenAccessSpec | ServiceAccessSpec>;
 
 /** The `_tag` literals a descriptor's `error:` union declares (empty for none). */
-export declare const declaredErrorTags: (error: Schema.Schema.All | undefined) => ReadonlySet<string>;
+export declare const declaredErrorTags: (error: Schema.Top | undefined) => ReadonlySet<string>;
 
 /**
  * Identity helper that fixes the descriptor's types (like `defineAction` /
@@ -210,7 +211,7 @@ export declare const encodeRestSuccess: (format: RestFormat, value: unknown, ctx
 
 /** The member of an error union that declares `tag`, as a schema of its own —
  *  for the spec's per-status responses. */
-export declare const errorMemberSchema: (error: Schema.Schema.All | undefined, tag: string) => Schema.Schema.All | undefined;
+export declare const errorMemberSchema: (error: Schema.Top | undefined, tag: string) => Schema.Top | undefined;
 
 /** Normalize the `exposeAsTool` shorthand. `true` is only valid when the
  *  descriptor carries a top-level `description`; callers pass that in. */
@@ -359,7 +360,7 @@ export declare const matchPathParams: (pattern: string, path: string) => Record<
  * (for example joining a room) must execute once for EACH native connection. */
 declare type MutationIdempotencyScope = 'subject' | 'connection';
 
-declare interface MutationProcedureDescriptor<Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Error extends Schema.Schema.All> {
+declare interface MutationProcedureDescriptor<Name extends string, Input extends Schema.Top, Output extends Schema.Top, Error extends Schema.Top> {
     readonly kind: 'mutation';
     readonly name: Name;
     readonly input: Input;
@@ -498,7 +499,7 @@ export declare const pathParamNames: (path: string) => ReadonlyArray<string>;
  * Requires the plugin to ship the schema as a NAMED export from `module`.
  */
 declare interface PluginErrorSchema {
-    readonly schema: Schema.Schema.All;
+    readonly schema: Schema.Top;
     readonly import: {
         readonly module: string;
         readonly name: string;
@@ -589,6 +590,9 @@ declare interface PluginHttpRoute {
      * handler branches on: exempting `/saml` exempts `POST /saml/anything`.
      */
     readonly originGuard?: 'exempt';
+    readonly cors?: RestCors;
+    /** Bearer-only routes must discard cookie authority before authentication. */
+    readonly credentials?: 'bearer';
 }
 
 /**
@@ -827,7 +831,7 @@ export declare interface PublicApiClientConfig {
 }
 
 /** A descriptor kind that can be projected to REST (streams are not, in v1). */
-export declare type PublicApiDescriptor = QueryProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | MutationProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | ActionProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All>;
+export declare type PublicApiDescriptor = QueryProcedureDescriptor<string, Schema.Top, Schema.Top, Schema.Top> | MutationProcedureDescriptor<string, Schema.Top, Schema.Top, Schema.Top> | ActionProcedureDescriptor<string, Schema.Top, Schema.Top, Schema.Top>;
 
 /** A descriptor paired with its bound executor, for batch projection at boot. */
 export declare interface PublicApiEntry {
@@ -1061,7 +1065,7 @@ declare interface QueryCacheConfig {
     readonly scope: 'subject' | 'tenant' | 'global';
 }
 
-declare interface QueryProcedureDescriptor<Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Error extends Schema.Schema.All> {
+declare interface QueryProcedureDescriptor<Name extends string, Input extends Schema.Top, Output extends Schema.Top, Error extends Schema.Top> {
     readonly kind: 'query';
     readonly name: Name;
     readonly input: Input;
@@ -1196,7 +1200,18 @@ export declare interface RestByteResponse {
  * headers CDNs purge by. A request that carries a credential (`Authorization`
  * or a cookie) gets `private, no-cache` and no tags, whatever is declared:
  * what a key or a session may see must never land in a shared cache. Every
- * such answer says `Vary: Authorization, Cookie`. Errors are not affected.
+ * such answer says `Vary: Authorization, Cookie`.
+ *
+ * With `audience`, the ANSWER decides instead of the request's cookies: an
+ * answer that is the same for every reader (`'public'`) is shared even when
+ * the request carries cookies (a consent choice, a signed-in reader on a
+ * public page) — the cache serves it to everyone, so it says only
+ * `Vary: Authorization`; an answer for this reader alone (`'private'`: a
+ * members page, a running experiment) is `private, no-store`. A request with
+ * `Authorization` is private either way.
+ *
+ * Any other answer than a 200 (a 404, a 410, a 401) of a route with `cache`
+ * is `private, no-store`: one reader's "not found" can be another's page.
  */
 export declare interface RestCache {
     /** Seconds a cache may serve the answer without asking again. */
@@ -1206,8 +1221,30 @@ export declare interface RestCache {
     /** Purge tags from the answer as it goes on the wire, and the input.
      *  A tag with whitespace or a comma is dropped (no header can carry it). */
     readonly tags?: (output: unknown, input: unknown) => ReadonlyArray<string>;
+    /** Who may share the answer, decided by the answer and the reader it was
+     *  made for: `'public'` — every reader gets the same, cookies are ignored;
+     *  `'private'` — this reader's alone, never shared. Answer `'private'` for
+     *  a signed-in `subject` whenever anything in the answer depends on who
+     *  reads it. Without it, any cookie makes the answer private. */
+    readonly audience?: (output: unknown, input: unknown, subject: Subject) => 'public' | 'private';
 }
 
+/** Cross-origin browser access for one route. Origins are exact, including opaque `null`. */
+export declare interface RestCors {
+    readonly origins: ReadonlyArray<string>;
+    readonly headers?: ReadonlyArray<string>;
+    readonly methods?: ReadonlyArray<RestMethod>;
+    /** Preflight cache lifetime in seconds. */
+    readonly maxAge?: number;
+    readonly exposeHeaders?: ReadonlyArray<string>;
+}
+
+/** Shared by the descriptor adapter and listener, including early transport refusals. */
+export declare const restCorsHeaders: (cors: RestCors | undefined, origin: string | undefined) => Record<string, string>;
+
+/** Preflight never authenticates, consumes quota, reads a body or executes a handler. */
+export declare const restCorsPreflight: (cors: RestCors, method: string, headers: Readonly<Record<string, string>>) => PluginHttpRouteResult;
+
 export declare type RestDates = 'iso' | 'epoch-ms';
 
 export declare type RestEnvelope = 'none' | 'data' | 'jsonapi';
@@ -1310,6 +1347,13 @@ export declare type RestNaming = 'camelCase' | 'snake_case';
 
 export declare type RestPagination = 'link-header' | 'body-cursor';
 
+/** Uses the mounted rate-limit plugin's store, algorithms and dynamic policy. */
+export declare interface RestRateLimit {
+    readonly limit: number;
+    readonly window: string;
+    readonly by?: 'subject' | 'tenant' | 'apiKey' | 'ip' | 'global';
+}
+
 /** A schema-encoded REST body with an application-selected HTTP status and
  *  response headers. The marker keeps ordinary domain objects unambiguous.
  *  `output` still validates/encodes `body`; use `Schema.Void` with a 204 when
@@ -1363,10 +1407,10 @@ export declare interface RestRouteDescriptor<I, O> {
      *  before decoding. Omit for routes that take no input. The schema's
      *  decoded `Type` flows to the handler's `input`; its `Encoded` is left
      *  open (`any`) so any `Schema.Struct(...)` is accepted. */
-    readonly input?: Schema.Schema<I, any, never>;
+    readonly input?: Schema.Codec<I, any, never, never>;
     /** Output schema. The handler returns the decoded `Type`; the desugar
      *  encodes it to JSON for the `200` response. */
-    readonly output: Schema.Schema<O, any, never>;
+    readonly output: Schema.Codec<O, any, never, never>;
     readonly handler: (input: I, ctx: RestRouteContext) => Promise<RestHandlerResult<O>> | RestHandlerResult<O>;
     readonly summary?: string;
     readonly description?: string;
@@ -1408,6 +1452,10 @@ export declare interface RestRouteDescriptor<I, O> {
      */
     readonly version?: `v${number}`;
     readonly guards?: ReadonlyArray<RestGuard>;
+    readonly cors?: RestCors;
+    /** Only an explicit bearer header may authenticate; cookies are removed before auth and context construction. */
+    readonly credentials?: 'bearer';
+    readonly rateLimit?: RestRateLimit;
     /**
      * This route STREAMS (Server-Sent Events) rather than resolving one value — its
      * handler returns `sse(...)`. Declared on the descriptor, not left implicit in
@@ -1462,10 +1510,10 @@ export declare interface RestRouteProjection {
     /** `publicApi.idempotent` — the route honours `Idempotency-Key` (under the
      *  app's idempotency binding); a client sends one per attempt. */
     readonly idempotent: boolean;
-    readonly input: Schema.Schema.All;
+    readonly input: Schema.Top;
     /** The wire names of the input fields bound from the path. */
     readonly pathParams: ReadonlyArray<string>;
-    readonly output: Schema.Schema.All;
+    readonly output: Schema.Top;
     /** The first `source` table, when the procedure declares one. */
     readonly source: string | undefined;
     /** Every failure the operation answers with a typed body, and its status:
@@ -1474,7 +1522,7 @@ export declare interface RestRouteProjection {
     readonly errorResponses: ReadonlyArray<{
         readonly status: number;
         readonly tag: string;
-        readonly schema: Schema.Schema.All;
+        readonly schema: Schema.Top;
     }>;
     readonly format: RestFormat;
 }
@@ -1493,6 +1541,8 @@ export declare const restRoutesToHttpRoutes: (routes: ReadonlyArray<RestRouteDes
  * auth subject + the bound DataStore.
  */
 export declare interface RestServeBindings {
+    /** Bound once from the app's mounted rate-limit plugin. */
+    readonly rateLimit?: (policy: RestRateLimit, ctx: RestRouteContext, route: RestRouteDescriptor<any, any>) => Effect.Effect<void, unknown>;
     /** Resolve the calling subject from the request headers. */
     readonly resolveSubject?: (headers: Readonly<Record<string, string>>) => Subject | Promise<Subject>;
     /** The bound framework DataStore. */
@@ -1528,15 +1578,15 @@ export declare interface RestStreamResponse {
 
 /**
  * Rewrite a descriptor's schema into the shape the profile puts on the wire:
- * `timestampMs` (`DateFromNumber`) becomes an RFC 3339 string under
- * `dates: 'iso'`, and every struct's property names become `snake_case` under
- * `naming: 'snake_case'` — as a transformation, so decoding a wire value yields
- * the descriptor's own typed value and encoding the typed value yields the
- * wire form. `JSONSchema.make` of the result documents the wire (a
- * `format: date-time` string, the snake keys). Classes and other opaque
- * transformations pass through unchanged; a struct inside one keeps its keys.
+ * `timestampMs` becomes an RFC 3339 string under `dates: 'iso'`, and every
+ * struct's property names become `snake_case` under `naming: 'snake_case'` —
+ * as an encoding, so decoding a wire value yields the descriptor's own typed
+ * value and encoding the typed value yields the wire form.
+ * `Schema.toJsonSchemaDocument` of the result documents the wire (a
+ * `format: date-time` string, the snake keys). Classes and other opaque codecs
+ * pass through unchanged; a struct inside one keeps its keys.
  */
-export declare const restViewSchema: (schema: Schema.Schema.All, format: RestFormat) => Schema.Schema.All;
+export declare const restViewSchema: (schema: Schema.Top, format: RestFormat) => Schema.Top;
 
 /**
  * Whether `path` is one the route declared. The underlying router folds case
@@ -1602,33 +1652,31 @@ export declare const sse: (subscribe: (emit: (chunk: string) => void) => () => v
  *  the protocol requires — a raw `\n` inside one would truncate the event. */
 export declare const sseFrame: (event: string, data: unknown) => string;
 
-declare const Subject: Schema.Union<[Schema.Struct<{
-    type: Schema.Literal<["user"]>;
-    id: typeof Schema.String;
-    tenantId: typeof Schema.String;
-    scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
-    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+declare const Subject: Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"user">;
+    readonly id: Schema.String;
+    readonly tenantId: Schema.String;
+    readonly scopes: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
 }>, Schema.Struct<{
-    type: Schema.Literal<["apiKey"]>;
-    id: typeof Schema.String;
-    tenantId: typeof Schema.String;
-    scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
-    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    readonly type: Schema.Literal<"apiKey">;
+    readonly id: Schema.String;
+    readonly tenantId: Schema.String;
+    readonly scopes: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
 }>, Schema.Struct<{
-    type: Schema.Literal<["serviceAccount"]>;
-    id: typeof Schema.String;
-    tenantId: typeof Schema.String;
+    readonly type: Schema.Literal<"serviceAccount">;
+    readonly id: Schema.String;
+    readonly tenantId: Schema.String;
     /** Application actor used for audit columns; null means machine work with
      * no application actor. Identity only, never a permission grant. */
-    auditActorId: Schema.optionalWith<Schema.NullOr<typeof Schema.String>, {
-        exact: true;
-    }>;
-    scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
-    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    readonly auditActorId: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+    readonly scopes: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
 }>, Schema.Struct<{
-    type: Schema.Literal<["anonymous"]>;
-    id: typeof Schema.Null;
-    tenantId: Schema.NullOr<typeof Schema.String>;
+    readonly type: Schema.Literal<"anonymous">;
+    readonly id: Schema.Null;
+    readonly tenantId: Schema.NullOr<Schema.String>;
     /**
      * Set when this caller PRESENTED a credential and it was rejected — an
      * expired token above all. Absent when they presented none.
@@ -1645,21 +1693,21 @@ declare const Subject: Schema.Union<[Schema.Struct<{
      * must not break an `openAccess` procedure that needs no session at all. The
      * fact travels, and only a guard that actually refuses spends it.
      */
-    credentialRejected: Schema.optional<typeof Schema.String>;
+    readonly credentialRejected: Schema.optional<Schema.String>;
 }>, Schema.Struct<{
-    type: Schema.Literal<["system"]>;
-    id: typeof Schema.String;
-    tenantId: typeof Schema.Null;
-    scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
-    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    readonly type: Schema.Literal<"system">;
+    readonly id: Schema.String;
+    readonly tenantId: Schema.Null;
+    readonly scopes: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
 }>, Schema.Struct<{
-    type: Schema.Literal<["service"]>;
-    id: typeof Schema.String;
+    readonly type: Schema.Literal<"service">;
+    readonly id: Schema.String;
     /** The calling app's name, as the callee lists it in `serviceCallers`. */
-    service: typeof Schema.String;
-    tenantId: typeof Schema.Null;
-    scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
-    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    readonly service: Schema.String;
+    readonly tenantId: Schema.Null;
+    readonly scopes: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
 }>]>;
 
 declare type Subject = typeof Subject.Type;
@@ -1737,7 +1785,7 @@ declare interface UpdateTarget<Input = unknown, Row = unknown, Item = Record<str
 export declare const wireExample: (example: {
     readonly request?: unknown;
     readonly response?: unknown;
-}, wireInput: Schema.Schema.All, wireOutput: Schema.Schema.All) => {
+}, wireInput: Schema.Top, wireOutput: Schema.Top) => {
     readonly request?: unknown;
     readonly response?: unknown;
 };