better-supabase 0.14.0 → 0.15.1

package/dist/index-BxYOB1Oc.d.ts

@@ -0,0 +1,149 @@
+import { n as RouteGuardOptions } from "./refusal-CSntB_x8.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.list(),
+ *   ),
+ * );
+ * ```
+ */
+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.bsb`). Mount it before the routes.
+ *
+ * ```ts
+ * app.use(toExpress([withBetterSupabase(server)]));
+ * app.get("/notes", async (req, res) =>
+ *   res.json(await res.locals.db.notes.list().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.list().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.list().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 };

package/dist/index-CG9rA8H8.d.ts

@@ -0,0 +1,407 @@
+import { d as MutationIntent, ot as SchemaMeta } from "./types-DFdg_4yN.js";
+import { Ct as Events, D as BlockEventPattern, T as BlockEvent, bt as EventMap, c as MutationNotice, k as BlockEventsMatching, o as EventHub, st as SubjectEventData } from "./events-vcqenSYU.js";
+import { i as EventSink, n as CloudEventOptions, t as CloudEvent } from "./cloud-event-CzZTJkXv.js";
+//#region src/core/block-event-listener.d.ts
+/**
+ * Listens to the block events that match `pattern` (`'support.started'` or
+ * `'support.*'`), typed by `events`: a block's events, `defineBlocks(...)` or
+ * `defineEvents(...)`. Returns a function that stops listening.
+ */
+declare function onBlockEvent<M extends EventMap, const P extends BlockEventPattern<M>>(betterSupabase: {
+  readonly events: EventHub;
+}, events: Events<M>, pattern: P, handler: (event: BlockEvent<M, BlockEventsMatching<M, P>>) => void): () => void;
+//#endregion
+//#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;
+  }[];
+}
+/** `engagement.recorded` and `engagement.transcribed`: a recording's turn. */
+interface EngagementRecordingEventData extends EngagementEventData {
+  readonly recordingId: string;
+}
+/** `mail_account.connected` and `mail_account.disconnected`: a synced mailbox. */
+interface MailAccountEventData {
+  readonly organizationId: string;
+  readonly accountId: string;
+  /** The member whose mailbox it is. */
+  readonly userId: string;
+  /** `gmail`, `outlook` or a custom provider name. */
+  readonly provider: string;
+  readonly address: string;
+}
+/**
+ * `mail_message.received` and `mail_message.sent`: a message stored on a
+ * thread. `subjects` lists the records the thread is linked to.
+ */
+interface MailMessageEventData {
+  readonly organizationId: string;
+  readonly accountId: string;
+  readonly userId: string;
+  readonly threadId: string;
+  readonly messageId: string;
+  readonly direction: "inbound" | "outbound";
+  readonly fromAddress: string | null;
+  readonly subjects: readonly {
+    readonly type: string;
+    readonly id: string;
+  }[];
+}
+/**
+ * `mail_message.opened` (the first open) and `mail_message.clicked` (each
+ * click): a tracked message its recipient opened, or a link in it they followed
+ * (`url`, null for an open).
+ */
+interface MailTrackingEventData {
+  readonly organizationId: string;
+  readonly accountId: string;
+  readonly userId: string;
+  readonly threadId: string;
+  readonly messageId: string;
+  /** The template version the message was sent from, when it had one. */
+  readonly templateVersionId: string | null;
+  readonly url: string | null;
+  readonly subjects: readonly {
+    readonly type: string;
+    readonly id: string;
+  }[];
+}
+/**
+ * `segment.saved` and `segment.removed`: a tenant's filter over one subject
+ * type.
+ */
+interface SegmentEventData {
+  readonly organizationId: string;
+  readonly segmentId: string;
+  readonly subjectType: string;
+  readonly name: string;
+}
+/**
+ * `segment.entered` and `segment.left`: a record started or stopped matching a
+ * segment's conditions when the segment was refreshed.
+ */
+interface SegmentMemberEventData {
+  readonly organizationId: string;
+  readonly segmentId: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+}
+/** `subject.assigned`: an assignment queue picked an owner for a record. */
+interface AssignmentEventData {
+  readonly organizationId: string;
+  readonly queueId: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  /** The member the queue picked. */
+  readonly userId: string;
+  readonly strategy: "round_robin" | "weighted";
+}
+/**
+ * `party.enriched`: a provider's result for a company or a person was stored,
+ * with the empty columns the match filled.
+ */
+interface EnrichmentEventData {
+  readonly organizationId: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  readonly provider: string;
+  readonly status: "matched" | "not_found";
+  /** The record's columns the match filled, such as `domain` or `title`. */
+  readonly filled: readonly string[];
+}
+/**
+ * `forecast.snapshotted`: the forecast call for a period and currency was
+ * stored with the deals it counted.
+ */
+interface ForecastSnapshotEventData {
+  readonly organizationId: string;
+  readonly snapshotId: string;
+  /** `null` for a snapshot of every pipeline. */
+  readonly pipelineId: string | null;
+  /** ISO dates. */
+  readonly since: string;
+  readonly until: string;
+  readonly currency: string;
+  readonly dealCount: number;
+}
+/** `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;
+}
+/**
+ * `saved_item.reminded`: a record a member saved for later reached its reminder
+ * time.
+ */
+interface SavedItemEventData extends SubjectEventData {
+  readonly organizationId: string;
+  readonly savedItemId: string;
+  /** The member who saved it. */
+  readonly userId: string;
+  readonly note?: string;
+  readonly remindAt: 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 tasks 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.records, 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;
+/** Events from the messaging module about a conversation. */
+interface ConversationEventData extends SubjectEventData {
+  readonly organizationId: string;
+  readonly conversationId: string;
+  /** `channel`, `dm`, `group_dm`, `subject` or `inbox`. */
+  readonly kind: string;
+  /** For `conversation.created` of a record conversation: the record. */
+  readonly recordType?: string | null;
+  readonly recordId?: string | null;
+  /** For `conversation.member_added` and `member_removed`. */
+  readonly userId?: string;
+}
+/** Events from the messaging module about a message. */
+interface MessageEventData extends SubjectEventData {
+  readonly organizationId: string;
+  readonly conversationId: string;
+  readonly messageId: string;
+  readonly authorId: string | null;
+  /** The thread's root message, null for a top-level message. */
+  readonly threadId: string | null;
+  /** The conversation's kind: `subject` for a record's comments. */
+  readonly conversationKind?: string;
+  /** The record a `subject` conversation discusses, null otherwise. */
+  readonly recordType?: string | null;
+  readonly recordId?: string | null;
+  /** For `message.sent`: the users it mentions. */
+  readonly mentionIds?: readonly string[];
+  /**
+   * For `message.sent`: the records it mentions
+   * (`@[Name](subject:<type>/<id>)`).
+   */
+  readonly recordMentions?: readonly {
+    readonly type: string;
+    readonly id: string;
+  }[];
+  /** For `message.pinned` and `message.resolved`: the new state. */
+  readonly pinned?: boolean;
+  readonly resolved?: boolean;
+}
+/** Events from the channels module. */
+interface ChannelEventData extends SubjectEventData {
+  readonly organizationId: string;
+  /** The channel's id, which is also its conversation's id. */
+  readonly channelId: string;
+  readonly name: string;
+  /** `public` or `private`. */
+  readonly visibility: string;
+  /** The record the channel is linked to. */
+  readonly recordType: string | null;
+  readonly recordId: string | null;
+}
+//#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 { PartyEventData as A, ForecastSnapshotEventData as C, MailMessageEventData as D, MailAccountEventData as E, SegmentEventData as F, SegmentMemberEventData as I, SlaEventData as L, PipelineStageEventData as M, QuoteEventData as N, MailTrackingEventData as O, SavedItemEventData as P, WorkItemEventData as R, EnrichmentEventData as S, JobEventData as T, ConversationEventData as _, RowEventData as a, EngagementEventData as b, httpSink as c, toHttp as d, ApplicationEventData as f, CollectionEventData as g, CollectionEntryEventData as h, ROW_EVENT_TYPES as i, PipelineEventData as j, MessageEventData as k, isCloudEvent as l, ChannelEventData as m, HttpMode as n, forwardMutations as o, AssignmentEventData as p, HttpSinkOptions as r, fromHttp as s, ForwardOptions as t, toCloudEvents as u, DealEventData as v, InvoiceEventData as w, EngagementRecordingEventData as x, EmployeeEventData as y, onBlockEvent as z };