better-supabase 0.13.0 → 0.15.0

package/dist/blocks/segments/index.d.ts

@@ -0,0 +1,130 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, t as AsyncResult } from "../../result-DZeA5KS6.js";
+import { Ct as Events } from "../../events-vcqenSYU.js";
+import { F as SegmentEventData, I as SegmentMemberEventData } from "../../index-CG9rA8H8.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-CRpAHrp_.js";
+import { a as dbTransport, i as RpcClient, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DWZSJrwN.js";
+import { a as BlockTransportMiddleware, d as extendBlock, f as withBlockHooks, n as BlockHooks, p as wrapTransport } from "../../block-hooks-DZN2w69m.js";
+import { n as segmentsSqlOptions, t as SegmentsSqlOptions } from "../../options-pOVWwbAK.js";
+import { h as FilterQuery } from "../../filter-query-BXLs72G9.js";
+import { Sn as EntitySchema, c as BlockOf } from "../../define-block-BVcLQ3DF.js";
+//#region src/blocks/segments/segments.d.ts
+/** A saved filter over one subject type, with its materialized members. */
+interface Segment {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly name: string;
+  readonly description: string | undefined;
+  /** A type in `config.records`, such as `company` or `deal`. */
+  readonly subjectType: string;
+  /** The filter tree over the subject type's rule fields. */
+  readonly conditions: FilterQuery;
+  /** The records that matched at the last refresh. */
+  readonly memberCount: number;
+  /**
+   * When the members were last evaluated, or undefined before the first
+   * refresh.
+   */
+  readonly refreshedAt: Temporal.Instant | undefined;
+  readonly createdBy: string | undefined;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+/** What `upsert` takes. Leave `id` out to create a segment. */
+interface SegmentInput {
+  readonly id?: string;
+  /** Required to create; a segment's subject type can't change. */
+  readonly subjectType?: string;
+  readonly name?: string;
+  readonly description?: string | null;
+  readonly conditions?: FilterQuery;
+}
+/** A record in a segment. */
+interface SegmentMember {
+  readonly subjectId: string;
+  readonly enteredAt: Temporal.Instant;
+}
+/** A segment a record is in. */
+interface SegmentMembership {
+  readonly segmentId: string;
+  readonly name: string;
+  readonly enteredAt: Temporal.Instant;
+}
+/** What a refresh changed. */
+interface SegmentRefresh {
+  readonly entered: number;
+  readonly left: number;
+  readonly memberCount: number;
+}
+/** What `refreshDue` did. */
+interface SegmentRefreshReport {
+  readonly segments: number;
+  readonly entered: number;
+  readonly left: number;
+}
+interface Segments {
+  /** Creates or changes a segment. Changing its conditions marks it due. */
+  upsert(organizationId: string, segment: SegmentInput): AsyncResult<Segment>;
+  /** Deletes a segment and its members. False when there was none. */
+  remove(segmentId: string): AsyncResult<boolean>;
+  list(organizationId: string, options?: {
+    readonly subjectType?: string;
+  }): AsyncResult<Segment[]>;
+  get(segmentId: string): AsyncResult<Segment | undefined>;
+  /**
+   * A page of members, newest first; `after` is the last page's oldest
+   * `enteredAt`.
+   */
+  members(segmentId: string, options?: {
+    readonly after?: Temporal.Instant;
+    readonly limit?: number;
+  }): AsyncResult<SegmentMember[]>;
+  /** The segments a record is in. */
+  of(subject: {
+    readonly type: string;
+    readonly id: string;
+  }): AsyncResult<SegmentMembership[]>;
+  /** Evaluates a segment now and stores who entered and left. */
+  refresh(segmentId: string): AsyncResult<SegmentRefresh>;
+  /** Refreshes the segments not refreshed within `staleAfter`. Service role. */
+  refreshDue(options?: {
+    /** At most this many segments. Default: 25. */
+    readonly segments?: number;
+    /** A Postgres interval. Default: `1 hour`. */
+    readonly staleAfter?: string;
+  }): AsyncResult<SegmentRefreshReport>;
+}
+interface SegmentsOptions extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  /**
+   * The module schema, or its API schema: `defineBlocks` passes it from
+   * `blocks.generated.ts`.
+   */
+  readonly schema?: string;
+  readonly hooks?: NoInfer<BlockHooks<Segments>>;
+  readonly logger?: Logger;
+  readonly mappers?: readonly ErrorMapper[];
+}
+export declare function createSegments(options: SegmentsOptions): Segments;
+//#endregion
+//#region src/blocks/segments/events.d.ts
+/** The events of the `segments` block: type to data. */
+type SegmentsEvents = {
+  readonly "segment.saved": SegmentEventData;
+  readonly "segment.removed": SegmentEventData;
+  readonly "segment.entered": SegmentMemberEventData;
+  readonly "segment.left": SegmentMemberEventData;
+};
+/** The `segments` block's event types, for its manifest and `onBlockEvent`. */
+export declare const segmentsEvents: Events<SegmentsEvents>;
+//#endregion
+//#region src/blocks/segments/manifest.d.ts
+/** The `segments` block's manifest (ADR 0029). */
+export declare const segmentsBlock: BlockOf<"segments", typeof createSegments, SegmentsEvents>;
+//#endregion
+//#region src/blocks/segments/schemas.d.ts
+/** What `upsert` takes. The SQL checks the conditions against the rule fields. */
+export declare const segmentInputSchema: EntitySchema<SegmentInput>;
+//#endregion
+export { type BlockHooks, type BlockTransport, type BlockTransportMiddleware, type RpcClient, type Segment, type SegmentInput, type SegmentMember, type SegmentMembership, type SegmentRefresh, type SegmentRefreshReport, type Segments, type SegmentsOptions, type SegmentsSqlOptions, dbTransport, extendBlock, rpcTransport, segmentsSqlOptions, sqlTransport, withBlockHooks, wrapTransport };

package/dist/blocks/segments/index.js

@@ -0,0 +1,135 @@
+import { t as segmentsSqlOptions } from "../../options-CF7nRWXS.js";
+import { A as requiredInstant, B as dbTransport, C as optionalText, D as recordOf, H as rpcTransport, I as textOf, S as optionalInstant, U as sqlTransport, k as recordsOf, m as instantArg, n as applyTemporal, o as blockCall } from "../../block-helpers-CtBdjgO4.js";
+import { i as wrapTransport, n as extendBlock, r as withBlockHooks } from "../../block-hooks-BfxX3682.js";
+import { n as entitySchema } from "../../entity-schema-BDv6w-OQ.js";
+import { n as event, t as defineEvents } from "../../event-map-CtPFhcOp.js";
+import { n as defineBlock } from "../../define-block-BGqOO8B3.js";
+import { t as conditionsOf } from "../../automations-BYsz43AG.js";
+//#region src/blocks/segments/segments.ts
+function segmentOf(value) {
+	const row = recordOf(value, "segment");
+	return {
+		id: textOf(row["id"]),
+		organizationId: textOf(row["organizationId"]),
+		name: textOf(row["name"]),
+		description: optionalText(row["description"]),
+		subjectType: textOf(row["subjectType"]),
+		conditions: conditionsOf(row["conditions"]),
+		memberCount: Number(row["memberCount"]),
+		refreshedAt: optionalInstant(row["refreshedAt"]),
+		createdBy: optionalText(row["createdBy"]),
+		createdAt: requiredInstant(row["createdAt"], "createdAt"),
+		updatedAt: requiredInstant(row["updatedAt"], "updatedAt")
+	};
+}
+function createSegments(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	return withBlockHooks({
+		upsert: (organizationId, segment) => call("save_segment", {
+			tenant: organizationId,
+			segment
+		}, segmentOf),
+		remove: (segmentId) => call("remove_segment", { segment: segmentId }, (value) => value === true),
+		list: (organizationId, list = {}) => call("segments_list", {
+			tenant: organizationId,
+			subject_type: list.subjectType ?? null
+		}, (value) => recordsOf(value, "segments_list").map(segmentOf)),
+		get: (segmentId) => call("segment_get", { segment: segmentId }, (value) => value === null || value === void 0 ? void 0 : segmentOf(value)),
+		members: (segmentId, page = {}) => call("list_segment_members", {
+			segment: segmentId,
+			after: instantArg(page.after) ?? null,
+			max_count: page.limit ?? null
+		}, (value) => recordsOf(value, "list_segment_members").map((row) => ({
+			subjectId: textOf(row["subjectId"]),
+			enteredAt: requiredInstant(row["enteredAt"], "enteredAt")
+		}))),
+		of: (subject) => call("segments_of", {
+			subject_type: subject.type,
+			subject_id: subject.id
+		}, (value) => recordsOf(value, "segments_of").map((row) => ({
+			segmentId: textOf(row["id"]),
+			name: textOf(row["name"]),
+			enteredAt: requiredInstant(row["enteredAt"], "enteredAt")
+		}))),
+		refresh: (segmentId) => call("refresh_segment", { segment: segmentId }, (value) => {
+			const row = recordOf(value, "refresh_segment");
+			return {
+				entered: Number(row["entered"]),
+				left: Number(row["left"]),
+				memberCount: Number(row["memberCount"])
+			};
+		}),
+		refreshDue: (run = {}) => call("refresh_due_segments", {
+			max_count: run.segments ?? null,
+			stale_after: run.staleAfter ?? null
+		}, (value) => {
+			const row = recordOf(value, "refresh_due_segments");
+			return {
+				segments: Number(row["segments"]),
+				entered: Number(row["entered"]),
+				left: Number(row["left"])
+			};
+		})
+	}, options.hooks, {
+		block: "segments",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+//#region src/blocks/segments/events.ts
+/** The `segments` block's event types, for its manifest and `onBlockEvent`. */
+const segmentsEvents = defineEvents({
+	"segment.saved": event(),
+	"segment.removed": event(),
+	"segment.entered": event(),
+	"segment.left": event()
+});
+//#endregion
+//#region src/blocks/segments/schemas.ts
+/** What `upsert` takes. The SQL checks the conditions against the rule fields. */
+const segmentInputSchema = entitySchema({
+	title: "SegmentInput",
+	fields: {
+		id: {
+			kind: "uuid",
+			optional: true
+		},
+		subjectType: {
+			kind: "string",
+			minLength: 1,
+			maxLength: 63,
+			optional: true
+		},
+		name: {
+			kind: "string",
+			minLength: 1,
+			maxLength: 200,
+			optional: true
+		},
+		description: {
+			kind: "string",
+			maxLength: 2e3,
+			optional: true
+		},
+		conditions: {
+			kind: "json",
+			optional: true,
+			description: "A FilterQuery over the subject type's rule fields."
+		}
+	}
+});
+//#endregion
+//#region src/blocks/segments/manifest.ts
+/** The `segments` block's manifest (ADR 0029). */
+const segmentsBlock = defineBlock({
+	name: "segments",
+	sql: ["segments"],
+	options: { segments: segmentsSqlOptions },
+	events: segmentsEvents,
+	schemas: { segment: { input: segmentInputSchema } },
+	create: createSegments,
+	category: "crm"
+});
+//#endregion
+export { createSegments, dbTransport, extendBlock, rpcTransport, segmentInputSchema, segmentsBlock, segmentsEvents, segmentsSqlOptions, sqlTransport, withBlockHooks, wrapTransport };

package/dist/blocks/sequences/index.d.ts

@@ -0,0 +1,259 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult } from "../../result-DZeA5KS6.js";
+import { $ as RecordRef } from "../../types-DFdg_4yN.js";
+import { Ct as Events } from "../../events-vcqenSYU.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { n as BlockOptions } from "../../block-helpers-CRpAHrp_.js";
+import { a as dbTransport, i as RpcClient, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DWZSJrwN.js";
+import { a as BlockTransportMiddleware, d as extendBlock, f as withBlockHooks, n as BlockHooks, p as wrapTransport } from "../../block-hooks-DZN2w69m.js";
+import { n as sequencesSqlOptions, t as SequencesSqlOptions } from "../../options-y_-AkVCs.js";
+import { F as BlockPorts, Sn as EntitySchema, V as MailSendDraft, c as BlockOf } from "../../define-block-BVcLQ3DF.js";
+//#region src/blocks/sequences/sequences.d.ts
+declare const SEQUENCE_STATUSES: readonly ["draft", "active", "paused", "archived"];
+declare const RUN_STATUSES: readonly ["active", "paused", "completed", "exited"];
+declare const EXIT_REASONS: readonly ["replied", "manual", "failed", "archived"];
+/** Only an active sequence takes enrollments and runs its steps. */
+type SequenceStatus = (typeof SEQUENCE_STATUSES)[number];
+/** Where a recipient's run stands. */
+type SequenceEnrollmentStatus = (typeof RUN_STATUSES)[number];
+/** Why a run exited. */
+type SequenceExitReason = (typeof EXIT_REASONS)[number];
+/**
+ * Sends an email from the recipient's mailbox. `subject`, `text` and `html`
+ * take `{{key}}` placeholders, filled from the enrollment's variables
+ * (HTML-escaped in `html`). After the first email, the rest reply on its
+ * thread.
+ */
+interface SequenceEmailStep {
+  readonly id: string;
+  readonly kind: "email";
+  readonly subject: string;
+  readonly text?: string;
+  readonly html?: string;
+  /** The `templates` version the email was written from. */
+  readonly templateVersionId?: string;
+  /** Tracks opens and clicks when mail-sync tracking is on. Default true. */
+  readonly track?: boolean;
+}
+/** Creates a work item for whoever enrolled the recipient. */
+interface SequenceTaskStep {
+  readonly id: string;
+  readonly kind: "task";
+  readonly title: string;
+  readonly body?: string;
+  /** Minutes until the work item is due. */
+  readonly dueInMinutes?: number;
+}
+/** Waits before the next step. */
+interface SequenceWaitStep {
+  readonly id: string;
+  readonly kind: "wait";
+  /** 1 to 525600 (a year). */
+  readonly minutes: number;
+}
+/** One step of a sequence; its id is a step of the enrollment program. */
+type SequenceStep = SequenceEmailStep | SequenceTaskStep | SequenceWaitStep;
+/** How many recipients are in each state. */
+interface SequenceCounts {
+  readonly active: number;
+  readonly paused: number;
+  readonly completed: number;
+  readonly exited: number;
+  /** Of the exited, how many replied. */
+  readonly replied: number;
+}
+interface Sequence {
+  readonly id: string;
+  readonly organizationId: string;
+  /** Unique in the organization. */
+  readonly key: string;
+  readonly name: string;
+  readonly description?: string;
+  readonly status: SequenceStatus;
+  /** Whether a reply ends the recipient's run. */
+  readonly exitOnReply: boolean;
+  /** The mailbox email steps send from when the enrollment names none. */
+  readonly accountId?: string;
+  readonly steps: readonly SequenceStep[];
+  /** Raised each time the steps change. */
+  readonly version: number;
+  readonly counts: SequenceCounts;
+  readonly createdBy?: string;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+/** What `upsert` takes; keys left out keep their value. */
+interface SequenceInput {
+  readonly id?: string;
+  readonly key?: string;
+  readonly name?: string;
+  readonly description?: string | null;
+  readonly status?: SequenceStatus;
+  readonly exitOnReply?: boolean;
+  readonly accountId?: string | null;
+  readonly steps?: readonly SequenceStep[];
+}
+/** A recipient's run through a sequence. `id` is the enrollment. */
+interface SequenceEnrollment {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly sequenceId: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  readonly address?: string;
+  readonly name?: string;
+  readonly accountId?: string;
+  /** The thread the first email started. */
+  readonly threadId?: string;
+  /** The step that runs next, absent once the run ended. */
+  readonly step?: string;
+  readonly nextRunAt?: Temporal.Instant;
+  readonly status: SequenceEnrollmentStatus;
+  readonly exitReason?: SequenceExitReason;
+  /** Send attempts of the current email step. */
+  readonly attempts: number;
+  readonly lastError?: string;
+  readonly variables: Readonly<Record<string, unknown>>;
+  readonly enrolledBy?: string;
+  /** The ids of the steps done, in the order they finished. */
+  readonly completedSteps: readonly string[];
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+/** What `enroll` takes. */
+interface SequenceEnrollInput {
+  /** The recipient's address; a person's email when left out. */
+  readonly address?: string;
+  readonly name?: string;
+  /** The mailbox to send from; the sequence's, then the caller's, by default. */
+  readonly accountId?: string;
+  /** Values for the `{{key}}` placeholders. */
+  readonly variables?: Readonly<Record<string, string | number | boolean | null>>;
+}
+/** What `enrollments` filters on. */
+interface SequenceEnrollmentsFilter {
+  readonly sequenceId?: string;
+  readonly subject?: RecordRef;
+  readonly status?: SequenceEnrollmentStatus;
+  /** 1 to 200. Default 50. */
+  readonly limit?: number;
+  /** The `createdAt` of the last row of the previous page. */
+  readonly before?: Temporal.Instant;
+}
+/** What one `runDue` call did. */
+interface SequenceRunReport {
+  /** Wait and task steps finished. */
+  readonly ran: number;
+  /** Email steps sent. */
+  readonly sent: number;
+  /** Email steps that failed to send; they run again later. */
+  readonly failed: number;
+}
+interface Sequences {
+  upsert(input: SequenceInput): AsyncResult<Sequence>;
+  /** The organization's sequences; archived ones only with that status. */
+  list(filter?: {
+    readonly status?: SequenceStatus;
+  }): AsyncResult<readonly Sequence[]>;
+  get(sequenceId: string): AsyncResult<Sequence>;
+  /** Deletes a sequence with its enrollments; false when there was none. */
+  delete(sequenceId: string): AsyncResult<boolean>;
+  /**
+   * Enrolls a record in an active sequence. Enrolling a record already running
+   * returns its run; a finished or exited run starts over.
+   */
+  enroll(sequenceId: string, subject: RecordRef, input?: SequenceEnrollInput): AsyncResult<SequenceEnrollment>;
+  pause(enrollmentId: string): AsyncResult<SequenceEnrollment>;
+  resume(enrollmentId: string): AsyncResult<SequenceEnrollment>;
+  /** Ends a run by hand; its completed steps stay. */
+  exit(enrollmentId: string): AsyncResult<SequenceEnrollment>;
+  enrollments(filter?: SequenceEnrollmentsFilter): AsyncResult<readonly SequenceEnrollment[]>;
+  /**
+   * Runs the due steps as the service role and sends the due emails through the
+   * `mailer` port. Call it from a cron route or a job every few minutes.
+   */
+  runDue(options?: {
+    readonly limit?: number;
+  }): AsyncResult<SequenceRunReport>;
+}
+interface SequencesOptions extends BlockOptions {
+  /** Sends email steps: the `mail-sync` block, which `createBlocks` passes. */
+  readonly mailer?: BlockPorts["mailer"];
+  readonly hooks?: NoInfer<BlockHooks<Sequences>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/**
+ * `template` with each `{{key}}` replaced by `variables[key]`; an unknown key
+ * becomes empty. `html` escapes the values.
+ */
+export declare function fillPlaceholders(template: string, variables: Readonly<Record<string, unknown>>, html?: boolean): string;
+/** The draft one claimed email step sends, placeholders filled. */
+export declare function sequenceDraft(claim: {
+  readonly to: {
+    readonly address: string;
+    readonly name?: string;
+  };
+  readonly threadId?: string;
+  readonly step: SequenceEmailStep;
+  readonly variables: Readonly<Record<string, unknown>>;
+}): MailSendDraft;
+/**
+ * Multi-step outreach sequences: email, task and wait steps that run per
+ * recipient as an enrollment program, until a reply ends the run.
+ */
+export declare function createSequences(options: SequencesOptions): Sequences;
+//#endregion
+//#region src/blocks/sequences/events.d.ts
+/** `sequence.saved` and `sequence.deleted`. */
+interface SequenceEventData {
+  readonly organizationId: string;
+  /** The sequence. */
+  readonly id: string;
+  readonly key: string;
+  readonly status: string;
+}
+/**
+ * The `sequence_enrollment.*` events: a recipient enrolled, finished a step,
+ * paused, resumed, exited or completed the sequence.
+ */
+interface SequenceEnrollmentEventData {
+  readonly organizationId: string;
+  /** The enrollment. */
+  readonly id: string;
+  readonly sequenceId: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  readonly status: string;
+  /** The step, on `step_completed`. */
+  readonly step: string | null;
+  /** Why the run ended, on `exited`: replied, manual, failed or archived. */
+  readonly reason: string | null;
+}
+/** The events of the `sequences` block: type to data. */
+type SequencesEvents = {
+  readonly "sequence.saved": SequenceEventData;
+  readonly "sequence.deleted": SequenceEventData;
+  readonly "sequence_enrollment.created": SequenceEnrollmentEventData;
+  readonly "sequence_enrollment.step_completed": SequenceEnrollmentEventData;
+  readonly "sequence_enrollment.paused": SequenceEnrollmentEventData;
+  readonly "sequence_enrollment.resumed": SequenceEnrollmentEventData;
+  readonly "sequence_enrollment.exited": SequenceEnrollmentEventData;
+  readonly "sequence_enrollment.completed": SequenceEnrollmentEventData;
+};
+/** The `sequences` block's event types, for its manifest and `onBlockEvent`. */
+export declare const sequencesEvents: Events<SequencesEvents>;
+//#endregion
+//#region src/blocks/sequences/manifest.d.ts
+/** The `sequences` block's manifest (ADR 0029). */
+export declare const sequencesBlock: BlockOf<"sequences", typeof createSequences, SequencesEvents, {
+  readonly mailer: "optional";
+}>;
+//#endregion
+//#region src/blocks/sequences/schemas.d.ts
+/** What `upsert` takes, with the bounds the SQL checks. */
+export declare const sequenceInputSchema: EntitySchema<SequenceInput>;
+/** What `enroll` takes, with the bounds the SQL checks. */
+export declare const sequenceEnrollInputSchema: EntitySchema<SequenceEnrollInput>;
+//#endregion
+export { type BlockHooks, type BlockTransport, type BlockTransportMiddleware, type RpcClient, type Sequence, type SequenceCounts, type SequenceEmailStep, type SequenceEnrollInput, type SequenceEnrollment, type SequenceEnrollmentEventData, type SequenceEnrollmentStatus, type SequenceEnrollmentsFilter, type SequenceEventData, type SequenceExitReason, type SequenceInput, type SequenceRunReport, type SequenceStatus, type SequenceStep, type SequenceTaskStep, type SequenceWaitStep, type Sequences, type SequencesEvents, type SequencesOptions, type SequencesSqlOptions, dbTransport, extendBlock, rpcTransport, sequencesSqlOptions, sqlTransport, withBlockHooks, wrapTransport };