better-supabase 0.12.0 → 0.13.0

package/dist/index-C7-2ZS9f.d.ts

@@ -0,0 +1,127 @@
+import { b as DbError, f as Result } from "./result-mijqfoJN.js";
+import { F as SchemaMeta } from "./types-DmshMaXz.js";
+import { J as QuerySpec } from "./define-D0LSXmUP.js";
+import { c as RealtimeClient, p as SubscriptionStatus } from "./topic-CZvLXFND.js";
+//#region src/realtime/live.d.ts
+/**
+ * What `liveQuery` needs from `betterSupabase`: metadata and the tables a spec
+ * reads.
+ */
+interface LiveSource {
+  readonly meta: SchemaMeta;
+  tablesOf(spec: QuerySpec): string[];
+}
+interface LiveQueryOptions {
+  /**
+   * Called once per burst of changes, with the app keys of the tables that
+   * changed.
+   */
+  readonly onChange: (tables: readonly string[]) => void;
+  /**
+   * Tenant value for tables scoped by a tenant column (`realtime-tables`
+   * topics).
+   */
+  readonly tenant?: string;
+  /**
+   * The signed-in user's id, for tables that broadcast per user
+   * (`realtime.users`).
+   */
+  readonly user?: string;
+  /**
+   * Waits this long after the last change before calling `onChange`. Defaults
+   * to 100 ms.
+   */
+  readonly debounceMs?: number;
+  /**
+   * Also reports a channel that errors after it joined (`error`) and its rejoin
+   * (`subscribed`), not only the first join.
+   */
+  readonly onStatus?: (status: SubscriptionStatus, error?: Error) => void;
+  /**
+   * Retries a first join that failed, after 1 s and then twice as long each
+   * time, up to 30 s. Pass `false` to stay in `error`. Defaults to `true`.
+   */
+  readonly retry?: boolean;
+}
+interface LiveSubscription extends Disposable, AsyncDisposable {
+  /** App keys of the watched tables. */
+  readonly tables: readonly string[];
+  /**
+   * Tables the query reads that don't broadcast changes (not in
+   * `realtime.tables`).
+   */
+  readonly unwatched: readonly string[];
+  readonly ready: Promise<void>;
+  unsubscribe(): Promise<void>;
+}
+/**
+ * A count from the server plus the spec to keep it live on the client:
+ * `bs.liveCount(spec)` makes one, `useLiveCount(seed)` reads it. `count` is
+ * `null` when the server read failed; the client then fetches it.
+ */
+interface LiveCountSeed<T extends string = string> {
+  readonly spec: QuerySpec<T, "count", number>;
+  readonly count: number | null;
+  /**
+   * When the count was taken (epoch ms). `useLiveCount` counts again after
+   * joining when it is older than a second.
+   */
+  readonly at?: number;
+}
+/**
+ * Topic a `realtime-tables` trigger broadcasts on:
+ * `bs:t:<schema>.<table>[:<tenant>]`, or `bs:t:<schema>.<table>:u:<user>` for a
+ * `realtime.users` table.
+ */
+declare function liveTopic(meta: SchemaMeta, table: string, tenant?: string, user?: string): string;
+/**
+ * Calls `onChange` when a table the spec reads changes, so you can refetch.
+ * Needs the `realtime-tables` SQL module and the tables in `realtime.tables`.
+ * Live queries on the same client share one channel per table, so any number of
+ * them can run at once.
+ *
+ * ```ts
+ * using live = liveQuery(betterSupabase, supabase, spec, {
+ *   onChange: () => refetch(),
+ * });
+ * ```
+ */
+declare function liveQuery(betterSupabase: LiveSource, client: RealtimeClient, spec: QuerySpec | readonly string[], options: LiveQueryOptions): LiveSubscription;
+/**
+ * What `liveCount` runs the spec with: a `db` from `betterSupabase.connect()`
+ * or `createClient()`.
+ */
+interface CountRunner {
+  $run(spec: QuerySpec): PromiseLike<Result<unknown>>;
+}
+interface LiveCountOptions extends Omit<LiveQueryOptions, "onChange"> {
+  readonly onCount: (count: number) => void;
+  /** A failed refetch; the previous count stays valid. */
+  readonly onError?: (error: DbError) => void;
+  /** Count right away. Defaults to `true`; pass `false` when you have a seed. */
+  readonly immediate?: boolean;
+  /**
+   * When the count you already have was taken (epoch ms). Counts again once the
+   * channel joins when that is more than a second ago, so a change made before
+   * the join is not lost.
+   */
+  readonly since?: number;
+}
+/**
+ * Keeps a count current: runs the `count` spec (a HEAD request) now, after each
+ * debounced change to a table it reads, and after the channel rejoins.
+ * Responses that arrive out of order are dropped.
+ *
+ * ```ts
+ * using live = liveCount(
+ *   betterSupabase,
+ *   supabase,
+ *   db,
+ *   betterSupabase.spec.notes.count(),
+ *   { onCount: (count) => render(count) },
+ * );
+ * ```
+ */
+declare function liveCount(betterSupabase: LiveSource, client: RealtimeClient, db: CountRunner, spec: QuerySpec<string, "count", number>, options: LiveCountOptions): LiveSubscription;
+//#endregion
+export { LiveSource as a, liveQuery as c, LiveQueryOptions as i, liveTopic as l, LiveCountOptions as n, LiveSubscription as o, LiveCountSeed as r, liveCount as s, CountRunner as t };

package/dist/index-CE0p3st5.d.ts

@@ -0,0 +1,227 @@
+import { F as SchemaMeta } from "./types-DmshMaXz.js";
+import { h as MutationIntent } from "./executor-C29668fO.js";
+import { c as MutationNotice, o as EventHub, st as SubjectEventData } from "./events-DhGgwqQA.js";
+import { i as EventSink, n as CloudEventOptions, t as CloudEvent } from "./cloud-event-CidL9jiw.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-CcpGT2GI.d.ts

@@ -0,0 +1,151 @@
+import { n as RouteGuardOptions } from "./refusal-BEyNVFy7.js";
+import { t as Validated } from "./shared-CRRfQAKG.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 };