better-supabase 0.12.0 → 0.14.0

package/dist/block-events-records-BGVyoz57.d.ts

@@ -0,0 +1,343 @@
+import { st as SubjectEventData } from "./events-DbLjvxDX.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;
+  }[];
+}
+/** `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 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;
+/** 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
+export { SavedItemEventData as C, WorkItemEventData as D, SlaEventData as E, QuoteEventData as S, SegmentMemberEventData as T, MailTrackingEventData as _, CollectionEventData as a, PipelineEventData as b, EmployeeEventData as c, EnrichmentEventData as d, ForecastSnapshotEventData as f, MailMessageEventData as g, MailAccountEventData as h, CollectionEntryEventData as i, EngagementEventData as l, JobEventData as m, AssignmentEventData as n, ConversationEventData as o, InvoiceEventData as p, ChannelEventData as r, DealEventData as s, ApplicationEventData as t, EngagementRecordingEventData as u, MessageEventData as v, SegmentEventData as w, PipelineStageEventData as x, PartyEventData as y };

package/dist/block-fields-3w4MZr8U.d.ts

@@ -0,0 +1,58 @@
+import { f as Result, t as AsyncResult } from "./result-C6jDfedy.js";
+import { t as StandardSchemaV1 } from "./standard-DbQsD2xZ.js";
+//#region src/core/block-fields.d.ts
+/** The fields a `fields` schema adds, or none when the block has no schema. */
+type FieldsOf<S> = S extends StandardSchemaV1<unknown, infer O> ? O extends object ? O : never : Record<never, never>;
+/** The extra columns of a row, keyed by database name, typed by `F`. */
+type ExtraFields<F extends object = Record<never, never>> = Readonly<Record<string, unknown>> & F;
+/** A row whose extra columns a block read under `fields`. */
+interface WithExtraFields {
+  readonly fields: Readonly<Record<string, unknown>>;
+}
+/**
+ * Parses and validates the extra fields an app adds to a block's table, with
+ * any Standard Schema (zod, valibot, arktype) for an object.
+ */
+interface BlockFields<T extends object> {
+  /**
+   * Parses a row the block read: the schema's output replaces the fields it
+   * covers, and the other fields stay as read. A row the schema rejects is a
+   * `validation` error.
+   */
+  read<R extends object>(row: R): Promise<Result<R & T>>;
+  /**
+   * Validates the fields a write sets. Issues about fields the write leaves out
+   * are ignored, so partial updates pass; the database applies its defaults and
+   * `not null` checks. A rejected write is a `validation` error, and nothing is
+   * sent to the database.
+   */
+  write<A extends object>(attrs: A): Promise<Result<A>>;
+  /**
+   * Parses the `fields` of a row the block read: the extra columns its SQL
+   * returns under `fields`, keyed by database name.
+   */
+  readonly row: <R extends WithExtraFields>(row: R) => AsyncResult<R & {
+    readonly fields: ExtraFields<T>;
+  }>;
+  /** `row` for each row, stopping at the first rejected one. */
+  readonly rows: <R extends WithExtraFields>(rows: readonly R[]) => AsyncResult<(R & {
+    readonly fields: ExtraFields<T>;
+  })[]>;
+  /**
+   * Validates the extra fields a write sets, as the jsonb argument the SQL
+   * function takes; `undefined` without any, so the argument is left out.
+   */
+  readonly args: (fields: object | undefined) => AsyncResult<Readonly<Record<string, unknown>> | undefined>;
+}
+/**
+ * The extra columns a block row carries, by column name, typed by its `fields`
+ * schema.
+ */
+type RowFields<F extends object> = Readonly<Record<string, unknown>> & F;
+/**
+ * The `fields` helper block creators use. Without a schema, reads and writes
+ * pass through unchanged.
+ */
+declare function blockFields<T extends object = Record<never, never>>(schema: StandardSchemaV1 | undefined, label: string): BlockFields<T>;
+//#endregion
+export { WithExtraFields as a, RowFields as i, ExtraFields as n, blockFields as o, FieldsOf as r, BlockFields as t };

package/dist/block-fields-DBSJSeaO.js

@@ -0,0 +1,139 @@
+import { n as dbError } from "./errors-03ysrOt4.js";
+import { a as ok, r as err, t as AsyncResult } from "./result-B3m7xtRY.js";
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+import { t as toIssues } from "./standard-DtkpFGkS.js";
+//#region src/core/block-fields.ts
+/** Parses the `fields` of one row with `fields.read`. */
+function readFields(fields, row) {
+	return AsyncResult.from(() => fields.read(row.fields)).map((parsed) => ({
+		...row,
+		fields: parsed
+	}));
+}
+/** Parses the `fields` of each row; the first rejected row fails the read. */
+function readAllFields(fields, rows) {
+	return AsyncResult.from(async () => {
+		const out = [];
+		for (const row of rows) {
+			const parsed = await fields.read(row.fields);
+			if (!parsed.ok) return parsed;
+			out.push({
+				...row,
+				fields: parsed.data
+			});
+		}
+		return ok(out);
+	});
+}
+/**
+* Validates the `fields` a write sets with `fields.write`, then builds the
+* call. A write without fields skips the check and passes none.
+*/
+function writeFields(fields, values, then) {
+	if (values === void 0) return then(void 0);
+	return AsyncResult.from(() => fields.write({ ...values })).andThen(then);
+}
+/** The `fields` object of a row a block function returned, or none. */
+function rowFields(value) {
+	return isRecord(value) ? value : {};
+}
+async function run(schema, value) {
+	return schema["~standard"].validate(value);
+}
+const invalid = (label, issues) => err(dbError("validation", `Invalid ${label}`, { issues }));
+/**
+* The `fields` helper block creators use. Without a schema, reads and writes
+* pass through unchanged.
+*/
+function blockFields(schema, label) {
+	const fields = {
+		async read(row) {
+			if (schema === void 0) return ok(row);
+			const outcome = await run(schema, row);
+			if (outcome.issues) return invalid(label, toIssues(outcome.issues));
+			if (!isRecord(outcome.value)) return invalid(label, [{ message: "fields must parse to an object" }]);
+			return ok({
+				...row,
+				...outcome.value
+			});
+		},
+		async write(attrs) {
+			if (schema === void 0) return ok(attrs);
+			const outcome = await run(schema, attrs);
+			if (!outcome.issues) {
+				if (!isRecord(outcome.value)) return ok(attrs);
+				const parsed = outcome.value;
+				const picked = Object.fromEntries(Object.keys(attrs).filter((key) => key in parsed).map((key) => [key, parsed[key]]));
+				return ok({
+					...attrs,
+					...picked
+				});
+			}
+			const given = new Set(Object.keys(attrs));
+			const relevant = toIssues(outcome.issues).filter((issue) => {
+				const [first] = issue.path ?? [];
+				return first === void 0 || given.has(String(first));
+			});
+			if (relevant.length === 0) return ok(attrs);
+			return invalid(label, relevant);
+		},
+		row: (row) => AsyncResult.from(() => fields.read(row.fields)).map((parsed) => ({
+			...row,
+			fields: parsed
+		})),
+		rows: (rows) => AsyncResult.from(async () => {
+			const out = [];
+			for (const row of rows) {
+				const parsed = await fields.row(row);
+				if (!parsed.ok) return parsed;
+				out.push(parsed.data);
+			}
+			return ok(out);
+		}),
+		args: (extra) => AsyncResult.from(async () => {
+			if (extra === void 0 || Object.keys(extra).length === 0) return ok(void 0);
+			const checked = await fields.write({ ...extra });
+			return checked.ok ? ok(checked.data) : checked;
+		})
+	};
+	return fields;
+}
+/** The keys of a write the block doesn't type itself: its extra fields. */
+const extraOf = (input, known) => Object.fromEntries(Object.entries(input).filter(([key]) => !known.has(key)));
+/** The extra columns a block read returns under its `fields` key. */
+const extraFieldsOf = (value) => isRecord(value) && isRecord(value["fields"]) ? value["fields"] : {};
+/**
+* Parses the extra columns of `raw` (a row a block function returned) and adds
+* them to `row`, the block's typed row. The row's own keys win, so an extra
+* column never replaces one the block types.
+*/
+async function withFields(fields, raw, row) {
+	const parsed = await fields.read(extraFieldsOf(raw));
+	if (!parsed.ok) return parsed;
+	return ok({
+		...parsed.data,
+		...row
+	});
+}
+/** `withFields` over a list of pairs: the raw row and the typed row. */
+async function allWithFields(fields, rows) {
+	const out = [];
+	for (const [raw, row] of rows) {
+		const parsed = await withFields(fields, raw, row);
+		if (!parsed.ok) return parsed;
+		out.push(parsed.data);
+	}
+	return ok(out);
+}
+/**
+* Validates the extra fields of a write: `{ fields }` to spread into the call's
+* arguments, or `{}` when the write sets none, so a module without extra
+* columns is called as before.
+*/
+async function extraFieldsArg(fields, extra) {
+	if (Object.keys(extra).length === 0) return ok({});
+	const valid = await fields.write(extra);
+	return valid.ok ? ok({ fields: valid.data }) : valid;
+}
+//#endregion
+export { readAllFields as a, withFields as c, extraOf as i, writeFields as l, blockFields as n, readFields as o, extraFieldsArg as r, rowFields as s, allWithFields as t };

package/dist/block-helpers-BaugZlJV.d.ts

@@ -0,0 +1,62 @@
+import { T as ErrorMapper, t as AsyncResult } from "./result-C6jDfedy.js";
+import { t as BlockTransport } from "./block-transport-d53POsem.js";
+//#region src/core/tenant-source.d.ts
+/**
+ * Where a block reads the active tenant: an organization id, or a function that
+ * returns the current one, such as `() => db.$context.tenant` on the server or
+ * the session's tenant claim in the browser.
+ */
+type BlockTenant = string | (() => string | null | undefined);
+//#endregion
+//#region src/core/block-tenant.d.ts
+/** The `tenant` option of the blocks whose methods work in one tenant. */
+interface BlockTenantOptions {
+  /**
+   * The organization the calls act in. `createBlocks` and `createBlockClient`
+   * pass the request's tenant; a call without one fails with
+   * `TENANT_REQUIRED`.
+   */
+  readonly tenant?: BlockTenant;
+}
+//#endregion
+//#region src/core/block-helpers.d.ts
+/** The `temporal` option every block creator takes. */
+interface BlockTemporalOptions {
+  /**
+   * The Temporal namespace for runtimes without a global one, such as `import {
+   * Temporal } from "temporal-polyfill"`. Blocks use it instead of
+   * `globalThis.Temporal`, which stays untouched; like `defineSupabase(schema,
+   * { temporal })`, it applies to the whole process.
+   */
+  readonly temporal?: typeof Temporal;
+}
+/** The options every block creator shares. */
+interface BlockOptions extends BlockTemporalOptions, BlockTenantOptions {
+  /**
+   * `sqlTransport(ctx.postgres)` for members, or `rpcTransport` over an API
+   * schema.
+   */
+  readonly transport: BlockTransport;
+  /**
+   * The transport for service-only calls (jobs, purges). Defaults to
+   * `transport`.
+   */
+  readonly service?: BlockTransport;
+  /** The module's schema, or its API schema. Default `better_supabase`. */
+  readonly schema?: string;
+  /** Error mappers that run before the built-in ones. */
+  readonly mappers?: readonly ErrorMapper[];
+}
+/** Calls one block function and maps a rejection to a `DbError`. */
+type BlockCall = <T>(fn: string, args: Readonly<Record<string, unknown>>, then: (value: unknown) => T | Promise<T>) => AsyncResult<T>;
+/**
+ * One page of a list. `cursor` is the previous page's `next` cursor or last
+ * item, in the shape each list documents.
+ */
+interface CursorPageOptions<Cursor> {
+  /** The most items to return. Each list documents its default and maximum. */
+  readonly limit?: number;
+  readonly cursor?: Cursor;
+}
+//#endregion
+export { BlockTenantOptions as a, CursorPageOptions as i, BlockOptions as n, BlockTenant as o, BlockTemporalOptions as r, BlockCall as t };