better-supabase 0.8.0 → 0.9.0

package/dist/testing/index.d.ts

@@ -1,31 +1,37 @@
-import { H as Update, L as TableKey, P as SchemaMeta, a as AnyModels, i as AnyFunctions, x as Insert } from "../types-CoE5Zwy4.js";
-import { r as Executor } from "../executor-Drzu3dBK.js";
-import { t as SqlClient } from "../executor-ngjKL_Pe.js";
-import { m as RequestContext, n as AnyPlugin } from "../plugin-CPK2HsbY.js";
-import { t as BetterSupabaseEnv } from "../index-BUK7jUzR.js";
-import { n as AuthResolver } from "../resolve-MxXVWyhd.js";
-import { a as CredentialSubject, i as CredentialRef, r as CredentialProvider } from "../provider-ib9wzUDz.js";
-import { k as QueueBackend } from "../types-D__3EN0q.js";
-import { n as Embedder } from "../knowledge-CAReFpRA.js";
-import { o as StreamStore } from "../store-DsIYEBnv.js";
-import { t as ApiModel } from "../model-OgBxvk3N.js";
-import { l as VersionOf, t as AnyDocumentFormat } from "../format-DTXdu8ya.js";
+import { P as SchemaMeta, W as Update, a as AnyModels, i as AnyFunctions, x as Insert, z as TableKey } from "../types-YfwpIE-d.js";
+import { r as Executor } from "../executor-DoE-5iM8.js";
+import { m as RequestContext, n as AnyPlugin } from "../plugin-CDLJRFFg.js";
+import { t as BetterSupabaseEnv } from "../index-CETRk4YO.js";
+import { n as AuthResolver } from "../resolve-w9EpHzuM.js";
+import { a as CredentialSubject, i as CredentialRef, r as CredentialProvider } from "../provider-9gBq9W6k.js";
+import { n as SqlClient } from "../executor-BBHgjUJu.js";
+import { a as BlockTransportMiddleware } from "../block-hooks-BLPWD3Jt.js";
+import { a as SessionActor, o as SessionDelegation } from "../actor-BAhb-d1S.js";
+import { M as QueueBackend } from "../types-CdP0z5tS.js";
+import { n as Embedder } from "../knowledge-BXQ2-V0a.js";
+import { a as AuthorizationProvider } from "../authorization-DpRfs6Wx.js";
+import { o as StreamStore } from "../store-B5qYKsTh.js";
+import { t as ApiModel } from "../model-lUafmeBQ.js";
+import { l as VersionOf, t as AnyDocumentFormat } from "../format-CNwSjXUU.js";
 import { o as Authorizer } from "../authorizer-eiOjo-3l.js";
-import { i as EventSink, t as CloudEvent } from "../cloud-event-Dune0KI7.js";
-import { Wt as DbStats, _ as Db, s as CacheAdapter, t as BetterSupabase } from "../define-DmcfoNXB.js";
-import { s as Impersonator } from "../mfa-SZc9YYyb.js";
-import { t as BetterPostgres } from "../pool-gkhbGp2E.js";
-import { B as SupportSessionStore, i as ServerContext, s as ServerOptions } from "../server-types-CrAmZ8jv.js";
-import { n as SessionActor, r as SessionDelegation } from "../actor-CQTlc1Hh.js";
-import { r as GuardOptions } from "../respond-Cw-zanCm.js";
-import { i as AuthorizationProvider } from "../authorization-BFCqamMs.js";
-import { i as AiTaskRun, o as AiTaskRunner, t as AiTask } from "../ai-tasks-BRQ6iQLc.js";
-import { B as ResolvedConfig, D as GeneratorModel, E as GeneratorInput, w as Generator } from "../index-Ba1SI-uO.js";
-import { a as BlockTransportMiddleware } from "../block-hooks-DaOVC7SC.js";
-import { t as NotificationChannel } from "../channel-_2Mx1Oyu.js";
-import { c as WebhookSecretStore, i as WebhookSigner, m as WebhookTransport } from "../signers-cpdmZYrv.js";
-import { T as WorkflowGraph, i as BuilderStarter, r as BuilderStartCall, s as GraphCompiler } from "../types-CD6yCDx3.js";
-import { t as EveDocumentBackend } from "../eve-CoAIcCkq.js";
+import { i as EventSink, t as CloudEvent } from "../cloud-event-5rCEzIgK.js";
+import { Wt as DbStats, _ as Db, s as CacheAdapter, t as BetterSupabase } from "../define-DxHHbNEb.js";
+import { n as Impersonator } from "../impersonation-D5chOkrO.js";
+import { i as AuthorizationHooks } from "../authorization-hooks-DkmrnDX7.js";
+import { t as BetterPostgres } from "../pool-CwOCsX9e.js";
+import { R as SupportSessionStore, i as ServerContext, s as ServerOptions } from "../server-types-OohhIQb2.js";
+import { r as GuardOptions } from "../respond-C7I8kLK_.js";
+import { n as Controller } from "../controller-D845qKh2.js";
+import { i as AiTaskRun, o as AiTaskRunner, t as AiTask } from "../ai-tasks-Ih5oHfyj.js";
+import { r as WebhookInput } from "../signatures-BMdJ7neI.js";
+import { n as Money } from "../money-DFpWzQvk.js";
+import { a as Generator, c as GeneratorModel, s as GeneratorInput, x as ResolvedConfig } from "../codegen-DeoSt1mi.js";
+import { t as NotificationChannel } from "../channel-D-LHCY11.js";
+import { a as DeliveryTransport } from "../delivery-BeHgwS3k.js";
+import { C as PaymentProvider, l as TaxProvider, r as TaxAddress, y as Payment } from "../tax-DDZUB_oc.js";
+import { c as GraphCompiler, i as BuilderStarter, r as BuilderStartCall, z as WorkflowGraph } from "../types-vaoP9S9_.js";
+import { O as IncomingDestination, f as WebhookSecretStore, o as WebhookSigner, v as WebhookTransport } from "../signers-CXt_wA9S.js";
+import { t as EveDocumentBackend } from "../eve-DUF70Vgi.js";
 import { SupabaseClient } from "@supabase/supabase-js";
 import { Message, StateAdapter } from "chat";
 import { webcrypto } from "node:crypto";
@@ -400,18 +406,48 @@ interface SupabaseClaimFixture {
     readonly actor: SessionActor;
     /** Set for support and impersonated sessions only. */
     readonly impersonator?: Impersonator;
-    /** Set for an `oauth-client` actor only. */
+    /** Set for an `oauth-client` actor, and an `agent` on a token with a `scope`. */
     readonly delegation?: SessionDelegation;
   };
 }
-type SupabaseClaimFixtureName = "supportSession" | "supportSessionReadOnly" | "impersonation" | "oauthClient" | "agentChain";
+type SupabaseClaimFixtureName = "supportSession" | "supportSessionReadOnly" | "impersonation" | "oauthClient" | "agentChain" | "agentRun" | "agentRunReadOnly";
 /**
  * `supportSession` and `supportSessionReadOnly` are what `supportClaims`
  * mints (`act.kind: "support"`), `impersonation` what `actingAs` mints
- * (`act.kind: "impersonation"`), `oauthClient` a Supabase OAuth server token
- * and `agentChain` an RFC 8693 chain without `kind`.
+ * (`act.kind: "impersonation"`), `oauthClient` a Supabase OAuth server
+ * token (its identity scopes `openid` and `email` are left out of the
+ * delegation), `agentChain` an RFC 8693 chain without `kind`, and
+ * `agentRun` and `agentRunReadOnly` what `agentClaims` mints over that
+ * chain (`act.kind: "agent"`, with `readOnly: true` for the second).
  */
 export declare const supabaseClaimFixtures: Readonly<Record<SupabaseClaimFixtureName, SupabaseClaimFixture>>;
+/**
+ * Claims whose `act` chain better-supabase refuses, so the session must
+ * not pass as the user alone. `resolveAuth` and `toSession` both answer
+ * with this verdict.
+ */
+interface SupabaseInvalidClaimFixture {
+  /** Without `iat` and `exp`, so a test signer sets them. */
+  readonly claims: {
+    readonly sub: string;
+    readonly [claim: string]: unknown;
+  };
+  readonly expect: {
+    readonly kind: "invalid";
+    readonly reason: "actor";
+    readonly code: "ACTOR_INVALID";
+  };
+}
+type SupabaseInvalidClaimFixtureName = "legacySupportSession" | "supportReadOnlyNotBoolean" | "agentWithSessionId" | "agentEmptyToolName" | "agentToolsNotArray" | "agentReadOnlyNotBoolean" | "unknownKind" | "levelWithoutSub";
+/**
+ * `legacySupportSession` is a 0.5.0 support token: `session_id` without
+ * `kind`. better-supabase refuses it instead of reading it as a support
+ * session; mint a new one with `supportClaims`. The others are malformed
+ * levels: a support or agent `read_only` that is not a boolean, an agent
+ * with a `session_id`, an empty tool name or `tools` that is not a list, a
+ * `kind` better-supabase does not know, and a nested level without `sub`.
+ */
+export declare const supabaseInvalidClaimFixtures: Readonly<Record<SupabaseInvalidClaimFixtureName, SupabaseInvalidClaimFixture>>;
 //#endregion
 //#region src/testing/seed.d.ts
 /** Named rows per table, in app casing: `{ customers: { acme: { ... } } }`. */
@@ -500,6 +536,71 @@ interface TestExecutorOptions {
  */
 export declare function testExecutor(executor: Executor, options: TestExecutorOptions): Promise<ConformanceReport>;
 //#endregion
+//#region src/testing/kits/payment-provider.d.ts
+interface TestPaymentProviderOptions {
+  /** What the kit charges. Defaults to 10.00 EUR. */
+  readonly amount?: Money;
+  /**
+   * Has the customer approve a `manual` payment, so it reaches
+   * `authorized` (with Stripe, confirm it with a test card). Without it
+   * the capture and refund checks are skipped.
+   */
+  readonly authorize?: (payment: Payment) => void | Promise<void>;
+  /**
+   * A delivery the provider's endpoint would receive for `payment`, signed
+   * with the provider's secret, and the same delivery with its body
+   * changed. Without it the webhook checks are skipped.
+   */
+  readonly webhook?: (payment: Payment) => Promise<{
+    readonly valid: WebhookInput;
+    readonly tampered: WebhookInput;
+  }>;
+}
+/**
+ * Runs the `PaymentProvider` contract against `provider`: the API version,
+ * refused amounts, a created payment and its fields, an idempotency key
+ * that pays once, `not_found` for an unknown payment, and, with the
+ * options that drive them, capture and refunds of an authorized payment
+ * and webhook verification. Every call carries a fresh reference, so the
+ * kit runs against a test account without cleanup.
+ */
+export declare function testPaymentProvider(provider: PaymentProvider, options?: TestPaymentProviderOptions): Promise<ConformanceReport>;
+//#endregion
+//#region src/testing/kits/tax-provider.d.ts
+interface TestTaxProviderOptions {
+  /** An address the provider taxes, such as `{ country: "NL" }`. */
+  readonly address: TaxAddress;
+  /** Defaults to `EUR`. */
+  readonly currency?: string;
+  /** The category of the kit's lines; unset uses the provider's default. */
+  readonly taxCategory?: string;
+  /** The address has tax above zero. Defaults to `true`. */
+  readonly expectTax?: boolean;
+}
+/**
+ * Runs the `TaxProvider` contract against `provider`: the API version,
+ * refused carts, a quote with one line per cart line in order and a total
+ * that adds up, inclusive prices, shipping, exempt customers, commit, and
+ * full and partial reversals with their limits. Every commit carries a
+ * fresh reference, so the kit runs against a test account without cleanup.
+ */
+export declare function testTaxProvider(provider: TaxProvider, options: TestTaxProviderOptions): Promise<ConformanceReport>;
+//#endregion
+//#region src/testing/kits/incoming-destination.d.ts
+interface TestIncomingDestinationOptions {
+  /** The tenant the test deliveries belong to. */
+  readonly tenant: string;
+  /** Defaults to `conformance`. */
+  readonly source?: string;
+}
+/**
+ * Proves an `IncomingDestination` accepts a delivery once per endpoint and
+ * message id: a repeat reports the first id as a duplicate, while another
+ * message id or another endpoint is new.
+ * It delivers four messages with random endpoint ids; the destination keeps them.
+ */
+export declare function testIncomingDestination(destination: IncomingDestination, options: TestIncomingDestinationOptions): Promise<ConformanceReport>;
+//#endregion
 //#region src/testing/kits/plugin.d.ts
 interface TestPluginOptions {
   /** The definition without this plugin. */
@@ -554,6 +655,44 @@ interface TestSupportSessionStoreOptions {
  */
 export declare function testSupportSessionStore(store: SupportSessionStore, options: TestSupportSessionStoreOptions): Promise<ConformanceReport>;
 //#endregion
+//#region src/testing/kits/controller-binding.d.ts
+/** The state of the probe controller a binding is tested over. */
+interface ProbeSnapshot {
+  readonly count: number;
+  readonly label: string;
+}
+interface ProbeActions {
+  readonly increment: () => void;
+  readonly rename: (label: string) => void;
+}
+type ProbeController = Controller<ProbeSnapshot, ProbeActions>;
+/** A binding mounted over one controller, the way a component uses it. */
+interface MountedBinding {
+  /** The state the binding renders now. */
+  readonly read: () => ProbeSnapshot;
+  /** The actions the binding hands the component. */
+  readonly actions: ProbeActions;
+  readonly unmount: () => void | Promise<void>;
+}
+interface ControllerBindingHarness {
+  /** Mounts the binding over the controller `create` returns, as a component would. */
+  readonly mount: (create: () => ProbeController) => MountedBinding | Promise<MountedBinding>;
+  /** Lets the framework apply pending updates: a tick, a flush. */
+  readonly settle?: () => void | Promise<void>;
+  /**
+   * Whether unmounting disposes the controller. React keeps it for
+   * StrictMode's second mount and only stops its work. Default true.
+   */
+  readonly disposes?: boolean;
+}
+export declare const PROBE_INITIAL: ProbeSnapshot;
+/**
+ * Proves a framework binding over a block controller renders the initial
+ * snapshot, follows each change, passes the actions through and stops the
+ * controller's work (and disposes it) on unmount.
+ */
+export declare function testControllerBinding(name: string, harness: ControllerBindingHarness): Promise<ConformanceReport>;
+//#endregion
 //#region src/testing/adapter.d.ts
 type AnySupabase = BetterSupabase<any, any, any, any>;
 /** What the adapter module asks a handler to do with the caller's context. */
@@ -610,6 +749,41 @@ export declare function testBlockTransportMiddleware(middleware: BlockTransportM
  */
 export declare function testAuthorizationProvider(provider: AuthorizationProvider): Promise<ConformanceReport>;
 //#endregion
+//#region src/testing/authorization-hooks.d.ts
+/**
+ * Proves `AuthorizationHooks` target API v1 and fail closed for strangers:
+ * fan-out returns only subscribers it was given, an identity nobody linked
+ * and a forged ticket resolve to `null`, a requester never approves their
+ * own request, an unknown publisher can neither publish nor run, an
+ * unlinked chat author gets nothing, an admin with no claims cannot start
+ * a support session and never approves their own, and a delegated token
+ * with no scopes maps to no permissions.
+ */
+export declare function testAuthorizationHooks(hooks: AuthorizationHooks): Promise<ConformanceReport>;
+//#endregion
+//#region src/testing/delivery-transport.d.ts
+/** What the provider received for one message, as the test's fake reports it. */
+interface ReceivedDelivery {
+  readonly idempotencyKey: string;
+  readonly headers: Readonly<Record<string, string>>;
+}
+interface TestDeliveryTransportOptions {
+  /** The sample's recipient. Defaults to `delivered@example.test`. */
+  readonly to?: string;
+  /**
+   * What the provider received, read after the kit sends. When given, the
+   * kit checks that the idempotency key and the headers arrived as sent.
+   */
+  readonly received?: () => Promise<readonly ReceivedDelivery[]>;
+}
+/**
+ * Runs the `DeliveryTransport` contract against `transport`: API version 1,
+ * the `email` channel, a provider name, and one frozen sample message it
+ * sends without mutating, with the delivery id as its idempotency key.
+ * Throws a `ConformanceError` listing every failed check.
+ */
+export declare function testDeliveryTransport(transport: DeliveryTransport, options?: TestDeliveryTransportOptions): Promise<ConformanceReport>;
+//#endregion
 //#region src/testing/authorizer.d.ts
 interface TestAuthorizerOptions<Ref> {
   /** Permission references to check; give at least one. */
@@ -850,4 +1024,33 @@ interface TestCredentialProviderOptions {
  */
 export declare function testCredentialProvider(provider: CredentialProvider, options: TestCredentialProviderOptions): Promise<ConformanceReport>;
 //#endregion
-export type { AdapterRun, BudgetPage, BudgetRequest, BudgetResponse, ConformanceCheck, ConformanceReport, DbBudgetExpectation, ExactSeed, InstantBrowserContext, InstantExpectation, InstantLocator, InstantPage, IsolationTable, IsolationTables, IsolationTenant, LiteStack, LiteStackOptions, LocalStack, MeasuredRender, ResponseBudgetExpectation, ResponseDbStats, Seed, SeedFixtures, SigningJwk, StaticAuthorizerOptions, SupabaseClaimFixture, SupabaseClaimFixtureName, TenantIsolationOptions, TestAdapterOptions, TestAiTaskRunnerOptions, TestAuthResolverOptions, TestAuthorizerOptions, TestBuilderStarterOptions, TestChatStateOptions, TestCredentialProviderOptions, TestDocumentFormatOptions, TestEmbedderOptions, TestEveDocumentBackendOptions, TestEventSinkOptions, TestExecutorOptions, TestGeneratorOptions, TestGraphCompilerOptions, TestJwtClaims, TestNotificationChannelOptions, TestPluginOptions, TestQueueBackendOptions, TestSigner, TestStreamStoreOptions, TestSupportSessionStoreOptions, TestUser, TestWebhookSecretStoreOptions, TestWebhookSignerOptions, TestWebhookTransportOptions };
+//#region src/testing/act-cases.d.ts
+/** One `act` claim set, with what `actorOf` and `actor_may_write()` say about it. */
+interface ActCase {
+  readonly name: string;
+  /** Only the claims the verdict reads: `act`, `client_id` and `scope`. */
+  readonly claims: Readonly<Record<string, unknown>>;
+  /** `false` when the chain is invalid and the session must be refused. */
+  readonly valid: boolean;
+  /** The actor's kind; `null` without an actor or for an invalid chain. */
+  readonly kind: SessionActor["kind"] | null;
+  /** The actor's `readOnly` (support and agent); `null` otherwise. */
+  readonly readOnly: boolean | null;
+  /** An agent's `tools`; `null` when it lists none, which means every tool. */
+  readonly tools: readonly string[] | null;
+  /** What `better_supabase.actor_may_write()` returns for these claims. */
+  readonly mayWrite: boolean;
+}
+/** `better-supabase/testing/act-cases.json`, versioned so other parsers can pin it. */
+interface ActCases {
+  readonly version: 1;
+  readonly cases: readonly ActCase[];
+}
+/**
+ * The RFC 8693 `act` chains better-supabase accepts and refuses, as plain
+ * JSON (`better-supabase/testing/act-cases.json`), so another library that
+ * reads the same claims can run the same cases.
+ */
+export declare const actCases: ActCases;
+//#endregion
+export type { ActCase, ActCases, AdapterRun, BudgetPage, BudgetRequest, BudgetResponse, ConformanceCheck, ConformanceReport, ControllerBindingHarness, DbBudgetExpectation, ExactSeed, InstantBrowserContext, InstantExpectation, InstantLocator, InstantPage, IsolationTable, IsolationTables, IsolationTenant, LiteStack, LiteStackOptions, LocalStack, MeasuredRender, MountedBinding, ProbeActions, ProbeController, ProbeSnapshot, ReceivedDelivery, ResponseBudgetExpectation, ResponseDbStats, Seed, SeedFixtures, SigningJwk, StaticAuthorizerOptions, SupabaseClaimFixture, SupabaseClaimFixtureName, SupabaseInvalidClaimFixture, SupabaseInvalidClaimFixtureName, TenantIsolationOptions, TestAdapterOptions, TestAiTaskRunnerOptions, TestAuthResolverOptions, TestAuthorizerOptions, TestBuilderStarterOptions, TestChatStateOptions, TestCredentialProviderOptions, TestDeliveryTransportOptions, TestDocumentFormatOptions, TestEmbedderOptions, TestEveDocumentBackendOptions, TestEventSinkOptions, TestExecutorOptions, TestGeneratorOptions, TestGraphCompilerOptions, TestIncomingDestinationOptions, TestJwtClaims, TestNotificationChannelOptions, TestPaymentProviderOptions, TestPluginOptions, TestQueueBackendOptions, TestSigner, TestStreamStoreOptions, TestSupportSessionStoreOptions, TestTaxProviderOptions, TestUser, TestWebhookSecretStoreOptions, TestWebhookSignerOptions, TestWebhookTransportOptions };