better-supabase 0.8.0 → 0.9.0

package/dist/index-BkzNUPId.d.ts

@@ -0,0 +1,131 @@
+import { t as AsyncResult } from "./result-Cj3yWhjH.js";
+import { a as AnyModels, i as AnyFunctions } from "./types-YfwpIE-d.js";
+import { l as PublicEnv } from "./index-CETRk4YO.js";
+import { h as SessionEncoding } from "./resolve-w9EpHzuM.js";
+import { t as BetterSupabase } from "./define-DxHHbNEb.js";
+import { i as KeyboardPort, l as StoragePort, n as DeepLinkPort, r as FilePickerPort, s as PushTokenPort, t as ClientPorts } from "./ports-DAdQyjZz.js";
+import { r as BetterClient } from "./bind-a7sUgvf4.js";
+import { n as FunctionContract } from "./function-contract-B4c0XuTU.js";
+import { FunctionInvokeOptions, SupabaseClient, SupabaseClientOptions } from "@supabase/supabase-js";
+//#region src/client/functions.d.ts
+/** `supabase.functions.invoke` options, without the body: `invoke` sends the input. */
+type InvokeOptions = Omit<FunctionInvokeOptions, "body">;
+/** Edge Function contracts by function name. */
+type FunctionContracts = Readonly<Record<string, FunctionContract>>;
+/** Anything with supabase-js's `functions` client, e.g. a `SupabaseClient`. */
+interface FunctionsHost {
+  readonly functions: {
+    invoke(name: string, options?: FunctionInvokeOptions): Promise<{
+      data: unknown;
+      error: unknown;
+      response?: Response;
+    }>;
+  };
+}
+interface TypedFunctions<Contracts extends FunctionContracts> {
+  /**
+   * Calls the function with `input` as the JSON body. Problem Details from
+   * the function come back as their `DbError`; a network or relay failure is
+   * a `network` error.
+   */
+  invoke<N extends keyof Contracts & string>(name: N, ...[input, options]: undefined extends Contracts[N]["input"] ? [input?: Contracts[N]["input"], options?: InvokeOptions] : [input: Contracts[N]["input"], options?: InvokeOptions]): AsyncResult<Contracts[N]["output"]>;
+}
+/**
+ * Typed Edge Function calls over supabase-js's `functions` client. The
+ * contracts come from the functions' own code, imported as types:
+ *
+ * ```ts
+ * import type { SendInvite } from "../supabase/functions/send-invite/index.ts";
+ *
+ * const fns = functions<{ "send-invite": SendInvite }>(supabase);
+ * const invite = await fns.invoke("send-invite", { email }).orThrow();
+ * ```
+ */
+declare function functions<Contracts extends FunctionContracts>(host: FunctionsHost): TypedFunctions<Contracts>;
+//#endregion
+//#region src/client/web-ports.d.ts
+/** The part of a `ServiceWorkerRegistration` the push token port uses. */
+interface PushRegistrationLike {
+  readonly pushManager: {
+    getSubscription(): Promise<unknown>;
+    subscribe(options: {
+      readonly userVisibleOnly: boolean;
+      readonly applicationServerKey: Uint8Array<ArrayBuffer>;
+    }): Promise<unknown>;
+  };
+}
+/**
+ * The storage port over `localStorage` (or `sessionStorage`). Reads resolve
+ * with `null` and writes do nothing where storage is missing or blocked.
+ */
+declare function webStorage(kind?: "local" | "session"): StoragePort;
+/** The keyboard port over `keydown` on `window`; `mod` matches Cmd and Ctrl. */
+declare function webKeyboard(): KeyboardPort;
+/** The file picker port over a hidden `<input type="file">`. */
+declare function webFilePicker(): FilePickerPort;
+/** The deep link port over `location`, `popstate` and `hashchange`. */
+declare function webDeepLinks(): DeepLinkPort;
+interface WebPushTokenOptions {
+  /** The VAPID public key, base64url-encoded. */
+  readonly vapidPublicKey: string;
+  /** The service worker that receives the pushes. Default `navigator.serviceWorker.ready`. */
+  readonly registration?: () => Promise<PushRegistrationLike>;
+}
+/**
+ * The push token port over the Push API: the token is the JSON of the
+ * browser's push subscription, which a Web Push sender needs.
+ */
+declare function webPushToken(options: WebPushTokenOptions): PushTokenPort;
+/** The web ports `createClient` uses: storage, the keyboard, the file picker and deep links. */
+declare function webPorts(): ClientPorts;
+//#endregion
+//#region src/client/index.d.ts
+interface ClientOptions {
+  /** URL and publishable key. Not needed when `client` is given. */
+  readonly env?: PublicEnv;
+  /**
+   * Bring your own supabase-js client (custom storage). React Native apps
+   * use `better-supabase/client/native`, which doesn't load `@supabase/ssr`.
+   */
+  readonly client?: SupabaseClient;
+  /**
+   * `cookies` (default) shares the session with the server through
+   * `@supabase/ssr`; `local` keeps it in localStorage for SPAs without a server.
+   */
+  readonly storage?: "cookies" | "local";
+  readonly cookies?: {
+    /**
+     * `tokens-only` keeps the user object out of the cookie (it lives in
+     * `auth.userStorage`, localStorage by default), so cookies stay small.
+     * Use the same value as the server's `encode`. Defaults to
+     * `user-and-tokens`.
+     */
+    readonly encode?: SessionEncoding;
+  };
+  readonly auth?: {
+    /** Where auth-js keeps the user object with `cookies.encode: 'tokens-only'`. */
+    readonly userStorage?: UserStorage;
+  };
+  /**
+   * `staleTime` for every query option in `bs.queries`. Above zero, a
+   * remount or a window focus reuses cached rows instead of refetching.
+   */
+  readonly staleTime?: number;
+  /**
+   * Platform services for the block hooks, over the web defaults
+   * (`webPorts()` and an upload port over Supabase Storage).
+   */
+  readonly ports?: ClientPorts;
+}
+type UserStorage = NonNullable<NonNullable<SupabaseClientOptions<"public">["auth"]>["userStorage"]>;
+/**
+ * The browser side: a supabase-js client, repositories that follow the
+ * session, TanStack Query options and an auth store for UI state.
+ *
+ * ```ts
+ * export const bs = createClient(betterSupabase, { env: { url, publishableKey } });
+ * ```
+ */
+declare function createClient$1<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown>(betterSupabase: BetterSupabase<M, D, F, E, C, P>, options?: ClientOptions): BetterClient<M, F, E, C, P>;
+//#endregion
+export { webDeepLinks as a, webPorts as c, FunctionContracts as d, FunctionsHost as f, functions as h, WebPushTokenOptions as i, webPushToken as l, TypedFunctions as m, createClient$1 as n, webFilePicker as o, InvokeOptions as p, PushRegistrationLike as r, webKeyboard as s, ClientOptions as t, webStorage as u };

package/dist/index-BlqrGvb3.d.ts

@@ -0,0 +1,227 @@
+import { P as SchemaMeta } from "./types-YfwpIE-d.js";
+import { h as MutationIntent } from "./executor-DoE-5iM8.js";
+import { c as MutationNotice, o as EventHub, st as SubjectEventData } from "./events-CTreRrgP.js";
+import { i as EventSink, n as CloudEventOptions, t as CloudEvent } from "./cloud-event-5rCEzIgK.js";
+//#region src/core/block-events-records.d.ts
+/** Events from the parties module: a company, a person, or a link between them. */
+interface PartyEventData {
+  readonly organizationId: string;
+  readonly companyId?: string;
+  readonly personId?: string;
+  readonly name?: string;
+  /** For `*.merged`: the record merged into this one, now archived. */
+  readonly mergedId?: string;
+  /** For `company.person_*`: the person's role at the company. */
+  readonly role?: string | null;
+}
+/**
+ * Events from the engagements module. `subjectType` and `subjectId` name
+ * the engagement's main record; `subjects` lists every record it is on.
+ */
+interface EngagementEventData extends SubjectEventData {
+  readonly organizationId: string;
+  readonly engagementId: string;
+  /** `call`, `email`, `meeting`, `note`, `task` or a configured type. */
+  readonly type: string;
+  readonly subjects: readonly {
+    readonly type: string;
+    readonly id: string;
+  }[];
+}
+/** `collection.created` and `collection.archived`: a list of one subject type. */
+interface CollectionEventData {
+  readonly organizationId: string;
+  readonly collectionId: string;
+  /** The type of the records the collection holds. */
+  readonly subjectType: string;
+  readonly name: string;
+  /** For `collection.created`: `user`, `team` or `tenant`. */
+  readonly scope?: string;
+}
+/** `collection.entry_added` and `collection.entry_removed`: a record in a list. */
+interface CollectionEntryEventData extends SubjectEventData {
+  readonly organizationId: string;
+  readonly collectionId: string;
+}
+/** Events from the deals module. Amounts are minor units as text. */
+interface DealEventData extends SubjectEventData {
+  readonly organizationId: string;
+  readonly dealId: string;
+  readonly name: string;
+  readonly amount?: string;
+  readonly currency?: string;
+  /** For `deal.closed`: `won` or `lost`. */
+  readonly outcome?: string;
+  /** For `deal.closed` as lost: why. */
+  readonly reason?: string | null;
+  /** For `deal.updated`: the fields the batch changed. */
+  readonly fields?: readonly string[];
+}
+/** Events from the work-items module. */
+interface WorkItemEventData extends SubjectEventData {
+  readonly organizationId: string;
+  readonly workItemId: string;
+  readonly title: string;
+  /** For `work_item.updated`: the fields the batch changed. */
+  readonly fields?: readonly string[];
+  /** For `work_item.assigned`: everyone assigned now. */
+  readonly assigneeIds?: readonly string[];
+  /** For `work_item.closed`: `completed` or `canceled`, and why. */
+  readonly state?: string;
+  readonly closeReason?: string;
+}
+/** Events from the quotes module. Amounts are minor units as text. */
+interface QuoteEventData extends SubjectEventData {
+  readonly organizationId: string;
+  readonly quoteId: string;
+  readonly identifier: string;
+  readonly total?: string;
+  readonly currency?: string;
+  /** For `quote.accepted`: who accepted, by name. */
+  readonly byName?: string;
+  /** For `quote.rejected` and `quote.changes_requested`. */
+  readonly note?: string | null;
+  /** For `quote.revised`: the new revision. */
+  readonly revisionId?: string;
+}
+/** Events from the invoices module. Amounts are minor units as text. */
+interface InvoiceEventData extends SubjectEventData {
+  readonly organizationId: string;
+  readonly invoiceId: string;
+  /** Null while the invoice is a draft. */
+  readonly identifier: string | null;
+  readonly total?: string;
+  readonly currency?: string;
+  readonly dueOn?: string;
+  readonly paymentId?: string;
+  readonly amount?: string;
+  readonly balance?: string;
+  readonly creditNoteId?: string;
+  readonly reason?: string | null;
+}
+/** Events from the sla module: a clock on a record warned, breached or was met. */
+interface SlaEventData extends SubjectEventData {
+  readonly organizationId: string;
+  readonly clockId: string;
+  /** `first_response`, `next_response` or `resolution`. */
+  readonly metric: string;
+  readonly dueAt: string;
+  /** For `sla.completed`: whether it was met after its due time. */
+  readonly late?: boolean;
+}
+/** Events from the hiring module about a job. */
+interface JobEventData {
+  readonly organizationId: string;
+  readonly jobId: string;
+  readonly title: string;
+}
+/** Events from the hiring module about an application. */
+interface ApplicationEventData extends SubjectEventData {
+  readonly organizationId: string;
+  readonly applicationId: string;
+  readonly jobId: string;
+  /** The candidate's record in config.subjects, a person by default. */
+  readonly candidateType: string;
+  readonly candidateId: string;
+  /** For `application.rejected`. */
+  readonly reason?: string | null;
+  /** For `scorecard.submitted`. */
+  readonly reviewerId?: string;
+  readonly recommendation?: string;
+  /** For `interview.scheduled`. */
+  readonly interviewId?: string;
+  readonly startsAt?: string;
+}
+/** Events from the employees module. */
+interface EmployeeEventData extends SubjectEventData {
+  readonly organizationId: string;
+  readonly employeeId: string;
+  readonly name: string;
+  /** For `employee.created`. */
+  readonly userId?: string | null;
+  readonly managerId?: string | null;
+  readonly status?: string;
+  /** For `employee.updated`: the fields the batch changed, or `contract`. */
+  readonly fields?: readonly string[];
+  /** For `employee.offboarded`: the last day and why. */
+  readonly endDate?: string;
+  readonly reason?: string | null;
+  /** For `employee.manager_changed`. */
+  readonly fromManagerId?: string | null;
+  readonly toManagerId?: string | null;
+}
+/**
+ * Events from the pipelines module. `pipeline.stage_changed` carries the
+ * record that moved as `subjectType` and `subjectId`; the configuration
+ * events (`pipeline.created`, `pipeline_stage.saved`) carry none.
+ */
+interface PipelineEventData {
+  readonly organizationId: string;
+  readonly pipelineId: string;
+  readonly subjectType?: string;
+  readonly subjectId?: string;
+  readonly key?: string;
+  readonly stageId?: string;
+  readonly fromStageId?: string | null;
+  readonly toStageId?: string;
+  /** The stage category, such as `won` or `started`. */
+  readonly category?: string;
+  /** `open`, `success` or `failure`. */
+  readonly outcome?: string;
+}
+/** `pipeline.stage_changed`: the record that moved and its stages. */
+type PipelineStageEventData = PipelineEventData & SubjectEventData;
+//#endregion
+//#region src/events/index.d.ts
+declare const ROW_EVENT_TYPES: { readonly [K in MutationIntent]: string; };
+interface RowEventData {
+  readonly table: string;
+  readonly row: Readonly<Record<string, unknown>>;
+  readonly actorId?: string;
+}
+/**
+ * One CloudEvent per mutated row: `dev.better-supabase.row.created` with the
+ * app-cased row and the actor in `data`, the primary key as `subject` and the
+ * tenant as `partitionkey`. Writes that return no rows (soft
+ * deletes, `returning: false`) send one event per known primary key, with the
+ * key as `row`.
+ */
+declare function toCloudEvents(notice: MutationNotice, options: CloudEventOptions & {
+  readonly meta?: SchemaMeta;
+}): CloudEvent<RowEventData>[];
+interface ForwardOptions extends CloudEventOptions {
+  /** Only forward these tables or kinds. */
+  readonly filter?: (notice: MutationNotice) => boolean;
+  /** Sink failures never fail the mutation. Defaults to the `Logger`. */
+  readonly onError?: (error: unknown, events: readonly CloudEvent[]) => void;
+}
+/**
+ * Sends a CloudEvent for every mutation to `sink`. Returns a function that
+ * stops forwarding. Sends in flight are tracked on `betterSupabase.events`
+ * (`settled()`), which the Next adapter hands to `after()` and the edge
+ * entry to `waitUntil`. Use an outbox (SQL modules) when events must not be lost.
+ */
+declare function forwardMutations(betterSupabase: {
+  readonly events: EventHub;
+  readonly meta: SchemaMeta;
+}, sink: EventSink, options: ForwardOptions): () => void;
+type HttpMode = "structured" | "binary" | "batch";
+/** The HTTP protocol binding: headers and body for one event (or a batch). */
+declare function toHttp(events: CloudEvent | readonly CloudEvent[], mode?: HttpMode): {
+  headers: Record<string, string>;
+  body: string;
+}[];
+declare function isCloudEvent(value: unknown): value is CloudEvent;
+/** Reads CloudEvents from a request in any of the three HTTP modes. */
+declare function fromHttp(request: Request): Promise<CloudEvent[]>;
+interface HttpSinkOptions {
+  readonly mode?: HttpMode;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly fetch?: typeof fetch;
+  /** Abort a request that takes longer than this. Defaults to 10 seconds. */
+  readonly timeoutMs?: number;
+}
+/** POSTs events to `url`. Non-2xx responses and timeouts reject. */
+declare function httpSink(url: string | URL, options?: HttpSinkOptions): EventSink;
+//#endregion
+export { QuoteEventData as C, PipelineStageEventData as S, WorkItemEventData as T, EngagementEventData as _, RowEventData as a, PartyEventData as b, httpSink as c, toHttp as d, ApplicationEventData as f, EmployeeEventData as g, DealEventData as h, ROW_EVENT_TYPES as i, isCloudEvent as l, CollectionEventData as m, HttpMode as n, forwardMutations as o, CollectionEntryEventData as p, HttpSinkOptions as r, fromHttp as s, ForwardOptions as t, toCloudEvents as u, InvoiceEventData as v, SlaEventData as w, PipelineEventData as x, JobEventData as y };

package/dist/index-Brhm22eL.d.ts

@@ -0,0 +1,138 @@
+import { n as RouteGuardOptions } from "./refusal-oD3ISM9h.js";
+import { t as Validated } from "./shared-DDSjEGDR.js";
+import { AnyEntry, Contributions } from "@supabase/middleware";
+import { IncomingMessage, ServerResponse } from "node:http";
+//#region src/node/http.d.ts
+interface WebRequestOptions {
+  /**
+   * Read the protocol and host from `x-forwarded-proto` and
+   * `x-forwarded-host`. Turn it on behind a proxy you control. Defaults to false.
+   */
+  readonly trustProxy?: boolean;
+  /** Stream the request body into the `Request`. Defaults to true. */
+  readonly body?: boolean;
+}
+/**
+ * A Node `IncomingMessage` as a Web `Request`. Express, Fastify and Koa
+ * pass theirs (`req`, `request.raw`, `ctx.req`). With `body: false` the
+ * stream stays unread, for middleware that runs before a body parser.
+ */
+declare function toWebRequest(req: IncomingMessage, options?: WebRequestOptions): Request;
+/** Writes a Web `Response` to a Node `ServerResponse`, streaming the body. */
+declare function sendWebResponse(res: ServerResponse, response: Response): Promise<void>;
+//#endregion
+//#region src/node/index.d.ts
+interface ToNodeOptions<Req = IncomingMessage> extends Omit<WebRequestOptions, "body"> {
+  /** The host's env object for `getEnv`; defaults to `process.env` through `getEnv`. */
+  readonly env?: (req: Req) => unknown;
+}
+/**
+ * A `node:http` request listener running the entries around `handler`.
+ * Response-phase entries see the handler's response, so refreshed cookies
+ * and `withDbStats` totals reach the client.
+ *
+ * ```ts
+ * createServer(toNodeHandler([withBetterSupabase(server)], (request, { db }) => db.notes.findMany()))
+ * ```
+ */
+declare function toNodeHandler<const Entries extends readonly AnyEntry[]>(entries: Entries & Validated<Entries>, handler: (request: Request, contributions: Contributions<Entries>) => unknown, options?: ToNodeOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+/** The part of an Express response the middleware writes. */
+interface ExpressResponse extends ServerResponse {
+  /** Express's per-request locals; the contributions land here. */
+  locals: Record<string, unknown>;
+}
+/** Express (or Connect) middleware, typed structurally. */
+type ExpressMiddleware = (req: IncomingMessage, res: ExpressResponse, next: (error?: unknown) => void) => void;
+/** An Express error handler, typed structurally. */
+type ExpressErrorHandler = (error: unknown, req: IncomingMessage, res: ExpressResponse, next: (error?: unknown) => void) => void;
+/**
+ * Express middleware that puts every contribution on `res.locals`
+ * (`res.locals.db`, `res.locals.bs`). Mount it before the routes.
+ *
+ * ```ts
+ * app.use(toExpress([withBetterSupabase(server)]))
+ * app.get('/notes', async (req, res) => res.json(await res.locals.db.notes.findMany().orThrow()))
+ * ```
+ */
+declare function toExpress<const Entries extends readonly AnyEntry[]>(entries: Entries & Validated<Entries>, options?: ToNodeOptions): ExpressMiddleware;
+/**
+ * Express route middleware that refuses callers outside `options`:
+ * Problem Details, or a redirect to `signIn` or `mfa`. Runs after `toExpress`.
+ *
+ * ```ts
+ * app.get('/admin', guard({ roles: ['admin'] }), handler)
+ * ```
+ */
+declare function guard(options?: RouteGuardOptions): ExpressMiddleware;
+/**
+ * An Express error handler that answers thrown `DbException`s (from
+ * `.orThrow()`) with Problem Details and passes every other error on.
+ * Register it after the routes.
+ */
+declare function problemErrorHandler(options?: {
+  readonly expose?: boolean;
+}): ExpressErrorHandler;
+/** The part of a Fastify request the hook reads and writes. */
+interface FastifyRequestLike {
+  readonly raw: IncomingMessage;
+  /** The contributions land here: `request.locals.db`. */
+  locals?: Record<string, unknown>;
+}
+/** The part of a Fastify reply the hook writes. */
+interface FastifyReplyLike {
+  readonly raw: ServerResponse;
+  readonly sent: boolean;
+  code(status: number): FastifyReplyLike;
+  header(name: string, value: string | readonly string[]): FastifyReplyLike;
+  getHeader(name: string): number | string | string[] | undefined;
+  send(payload?: unknown): FastifyReplyLike;
+}
+/** A Fastify `onRequest` or `preHandler` hook, typed structurally. */
+type FastifyHook = (request: FastifyRequestLike, reply: FastifyReplyLike) => Promise<void>;
+/**
+ * A Fastify `onRequest` hook that puts every contribution on
+ * `request.locals`. Declare `locals` with `app.decorateRequest('locals', null)`.
+ *
+ * ```ts
+ * app.decorateRequest('locals', null)
+ * app.addHook('onRequest', toFastify([withBetterSupabase(server)]))
+ * app.get('/notes', (request) => request.locals.db.notes.findMany().orThrow())
+ * ```
+ */
+declare function toFastify<const Entries extends readonly AnyEntry[]>(entries: Entries & Validated<Entries>, options?: ToNodeOptions<FastifyRequestLike>): FastifyHook;
+/**
+ * A Fastify `preHandler` hook that refuses callers outside `options`. Runs
+ * after `toFastify`.
+ */
+declare function fastifyGuard(options?: RouteGuardOptions): FastifyHook;
+/** The part of a Koa context the middleware reads and writes. */
+interface KoaContextLike {
+  readonly req: IncomingMessage;
+  readonly res: ServerResponse;
+  /** Koa's per-request state; the contributions land here. */
+  state: Record<string, unknown>;
+  status: number;
+  body: unknown;
+  set(name: string, value: string | readonly string[]): void;
+  get response(): {
+    get(name: string): string | string[] | undefined;
+  };
+}
+/** Koa middleware, typed structurally. */
+type KoaMiddleware = (ctx: KoaContextLike, next: () => Promise<unknown>) => Promise<void>;
+/**
+ * Koa middleware that puts every contribution on `ctx.state`, then awaits
+ * the rest of the chain. Thrown `DbException`s become Problem Details.
+ *
+ * ```ts
+ * app.use(toKoa([withBetterSupabase(server)]))
+ * app.use(async (ctx) => { ctx.body = await ctx.state.db.notes.findMany().orThrow() })
+ * ```
+ */
+declare function toKoa<const Entries extends readonly AnyEntry[]>(entries: Entries & Validated<Entries>, options?: ToNodeOptions<KoaContextLike> & {
+  readonly expose?: boolean;
+}): KoaMiddleware;
+/** Koa middleware that refuses callers outside `options`. Runs after `toKoa`. */
+declare function koaGuard(options?: RouteGuardOptions): KoaMiddleware;
+//#endregion
+export { toNodeHandler as _, FastifyReplyLike as a, toWebRequest as b, KoaMiddleware as c, guard as d, koaGuard as f, toKoa as g, toFastify as h, FastifyHook as i, ToNodeOptions as l, toExpress as m, ExpressMiddleware as n, FastifyRequestLike as o, problemErrorHandler as p, ExpressResponse as r, KoaContextLike as s, ExpressErrorHandler as t, fastifyGuard as u, WebRequestOptions as v, sendWebResponse as y };