better-supabase 0.8.0 → 0.9.0

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

@@ -0,0 +1,61 @@
+import { t as AsyncResult } from "../../result-Cj3yWhjH.js";
+import { $ as SaasEventData, wt as Events } from "../../events-CTreRrgP.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { t as StandardSchemaV1 } from "../../standard-C3_AAF3g.js";
+import { n as BlockOptions } from "../../block-helpers-C86hPEjI.js";
+import { n as BlockHooks } from "../../block-hooks-BLPWD3Jt.js";
+import { n as ExtraFields, r as FieldsOf } from "../../block-fields-5UA84ZUg.js";
+import { s as BlockOf } from "../../define-block-CLZMEFeK.js";
+//#region src/blocks/teams/teams.d.ts
+interface TeamsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockOptions {
+  /**
+   * A Standard Schema for the team's extra columns
+   * (`blocks.teams.options.extraColumns`), keyed by database name. It types
+   * and parses them on reads, and validates them on `create` and `update`.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Teams<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/** A team. `F` types the extra columns the `fields` schema describes. */
+interface Team<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly name: string;
+  readonly slug: string;
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
+}
+interface Teams<F extends object = Record<never, never>> {
+  /** Creates a team; `fields` sets its extra columns. */
+  create(organizationId: string, name: string, description?: string, fields?: Partial<F>): AsyncResult<Team<F>>;
+  /** Renames a team and sets the extra columns `fields` names. */
+  update(id: string, name: string, description?: string, fields?: Partial<F>): AsyncResult<Team<F>>;
+  archive(id: string): AsyncResult<boolean>;
+  delete(id: string): AsyncResult<boolean>;
+  addMember(teamId: string, userId: string): AsyncResult<boolean>;
+  removeMember(teamId: string, userId: string): AsyncResult<boolean>;
+  list(organizationId: string): AsyncResult<readonly Team<F>[]>;
+}
+/** The `teams` SQL module as typed calls. */
+export declare function createTeams<S extends StandardSchemaV1 | undefined = undefined>(options: TeamsOptions<S>): Teams<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/teams/events.d.ts
+/** The events of the `teams` block: type to data. */
+type TeamsEvents = {
+  readonly "team.created": SaasEventData;
+  readonly "team.updated": SaasEventData;
+  readonly "team.archived": SaasEventData;
+  readonly "team.deleted": SaasEventData;
+  readonly "team_member.added": SaasEventData;
+  readonly "team_member.removed": SaasEventData;
+};
+/** The `teams` block's event types, for its manifest and `onBlockEvent`. */
+export declare const teamsEvents: Events<TeamsEvents>;
+//#endregion
+//#region src/blocks/teams/manifest.d.ts
+/** The `teams` block's manifest (ADR 0029). */
+export declare const teamsBlock: BlockOf<"teams", typeof createTeams, TeamsEvents>;
+//#endregion
+export type { Team, Teams, TeamsEvents, TeamsOptions };

package/dist/blocks/teams/index.js

@@ -0,0 +1,83 @@
+import { n as isRecord } from "../../guards-6F2bCtQR.js";
+import { n as event, t as defineEvents } from "../../event-map-Dy2vKHai.js";
+import { C as optionalText, D as recordOf, I as textOf, k as recordsOf, n as applyTemporal, o as blockCall } from "../../block-helpers-CfG_MvDR.js";
+import { r as withBlockHooks } from "../../block-hooks-BsXncUlZ.js";
+import { n as blockFields } from "../../block-fields-ffD6Gxe4.js";
+import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
+import { t as teamsSqlOptions } from "../../options-C6rEL6U5.js";
+//#region src/blocks/teams/teams.ts
+function teamOf(value) {
+	const row = recordOf(value, "team");
+	return {
+		id: textOf(row["id"]),
+		name: optionalText(row["name"]) ?? "",
+		slug: optionalText(row["slug"]) ?? "",
+		fields: isRecord(row["fields"]) ? row["fields"] : {}
+	};
+}
+/** The `teams` SQL module as typed calls. */
+function createTeams(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const fields = blockFields(options.fields, "team fields");
+	return withBlockHooks({
+		create: (organizationId, name, description, extra) => fields.args(extra).andThen((checked) => call("create_team", {
+			tenant: organizationId,
+			name,
+			description: description ?? null,
+			fields: checked
+		}, (value) => ({
+			...teamOf(value),
+			name
+		})).andThen(fields.row)),
+		update: (id, name, description, extra) => fields.args(extra).andThen((checked) => call("update_team", {
+			team: id,
+			name,
+			description: description ?? null,
+			fields: checked
+		}, (value) => ({
+			...teamOf(value),
+			name,
+			slug: optionalText(recordOf(value, "team")["slug"]) ?? ""
+		})).andThen(fields.row)),
+		archive: (id) => call("archive_team", { team: id }, (value) => value === true),
+		delete: (id) => call("delete_team", { team: id }, (value) => value === true),
+		addMember: (teamId, userId) => call("add_team_member", {
+			team: teamId,
+			member: userId
+		}, (value) => value === true),
+		removeMember: (teamId, userId) => call("remove_team_member", {
+			team: teamId,
+			member: userId
+		}, (value) => value === true),
+		list: (organizationId) => call("list_teams", { tenant: organizationId }, (value) => recordsOf(value, "list_teams").map(teamOf)).andThen(fields.rows)
+	}, options.hooks, {
+		block: "teams",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+//#region src/blocks/teams/events.ts
+/** The `teams` block's event types, for its manifest and `onBlockEvent`. */
+const teamsEvents = defineEvents({
+	"team.created": event(),
+	"team.updated": event(),
+	"team.archived": event(),
+	"team.deleted": event(),
+	"team_member.added": event(),
+	"team_member.removed": event()
+});
+//#endregion
+//#region src/blocks/teams/manifest.ts
+/** The `teams` block's manifest (ADR 0029). */
+const teamsBlock = defineBlock({
+	name: "teams",
+	sql: ["teams"],
+	options: { teams: teamsSqlOptions },
+	events: teamsEvents,
+	create: createTeams,
+	category: "tenancy",
+	recipes: ["team-picker"]
+});
+//#endregion
+export { createTeams, teamsBlock, teamsEvents };

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

@@ -0,0 +1,362 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, t as AsyncResult, w as ErrorMapper } from "../../result-Cj3yWhjH.js";
+import { dt as TemplateEventData, ut as TemplateApplicationEventData, wt as Events } from "../../events-CTreRrgP.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { t as StandardSchemaV1 } from "../../standard-C3_AAF3g.js";
+import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DaGGXjIw.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-C86hPEjI.js";
+import { n as BlockHooks } from "../../block-hooks-BLPWD3Jt.js";
+import { n as ExtraFields, r as FieldsOf } from "../../block-fields-5UA84ZUg.js";
+import { s as BlockOf } from "../../define-block-CLZMEFeK.js";
+import { t as ComposedEmail } from "../../email-BcmbIWOX.js";
+import { D as WorkflowStepInfo, _ as WorkflowBuilder } from "../../types-vaoP9S9_.js";
+import { i as GraphStepCall } from "../../executor-BINiCFNp.js";
+//#region src/blocks/templates/merge-fields.d.ts
+/** How a rendered value is escaped: for HTML markup, or left as it is. */
+type MergeEscape = "html" | "text";
+/** One merge field a record type offers, as an editor lists it. */
+interface MergeFieldSpec {
+  readonly label?: string;
+  readonly description?: string;
+  /** A value for previews and for the editor's sample render. */
+  readonly example?: string;
+}
+/**
+ * Values for `renderMergeFields`, by field name. A dotted name such as
+ * `customer.name` reads that key first, then the nested path.
+ */
+type MergeValues<K extends string = string> = { readonly [P in K]?: unknown; } & Readonly<Record<string, unknown>>;
+interface RenderMergeFieldsOptions {
+  /** Default `text`. `{{{ name }}}` is never escaped. */
+  readonly escape?: MergeEscape;
+  /** What a field without a value renders as: `empty` (default) or the `{{ name }}` it was. */
+  readonly missing?: "empty" | "keep";
+  /**
+   * Turns a value into text. The default prints strings, numbers and
+   * booleans as they are, Temporal values and other objects with their own
+   * `toString`, a `Date` as ISO 8601, arrays joined by `, `, and plain
+   * objects as JSON.
+   */
+  readonly format?: (value: unknown, name: string) => string;
+}
+/** A typed list of the merge fields one record type offers. */
+interface MergeFieldCatalog<K extends string = string> {
+  readonly subjectType: string;
+  readonly fields: Readonly<Record<K, MergeFieldSpec>>;
+  readonly names: readonly K[];
+  /** The fields `text` uses that the catalog doesn't define, in order of first use. */
+  unknown(text: string): readonly string[];
+  /** `renderMergeFields` with values typed by the catalog. */
+  render(text: string, values: MergeValues<K>, options?: RenderMergeFieldsOptions): string;
+  /** Each field's `example`, for a preview. */
+  examples(): Readonly<Record<string, string>>;
+}
+/** The merge field names `text` uses, in order of first use. */
+export declare function mergeFieldsIn(text: string): readonly string[];
+/**
+ * Replaces each `{{ name }}` in `text` with its value, escaped for HTML with
+ * `escape: "html"`, and each `{{{ name }}}` with its value unescaped. It
+ * has no dependencies and runs on every WinterTC runtime.
+ */
+export declare function renderMergeFields(text: string, values: Readonly<Record<string, unknown>>, options?: RenderMergeFieldsOptions): string;
+/**
+ * The merge fields a record type offers, such as an invoice's
+ * `customer.name` and `total`. The catalog types `render` and lists the
+ * fields a template uses that it doesn't define.
+ */
+export declare function defineMergeFields<const K extends string>(subjectType: string, fields: Readonly<Record<K, MergeFieldSpec>>): MergeFieldCatalog<K>;
+/** An email body with merge fields, as an email template stores it. */
+interface EmailTemplateBody {
+  readonly subject: string;
+  readonly text?: string;
+  readonly html?: string;
+}
+interface TemplateEmailOptions extends Pick<RenderMergeFieldsOptions, "missing" | "format">, Pick<ComposedEmail, "replyTo" | "category"> {
+  /** Stored on the delivery, e.g. `invoice-sent-v3`. */
+  readonly templateKey?: string;
+}
+/**
+ * Renders an email template for the notifications email channel's
+ * `compose`: the subject and text as text, the HTML escaped for HTML.
+ */
+export declare function composeTemplateEmail(body: EmailTemplateBody, values: Readonly<Record<string, unknown>>, options?: TemplateEmailOptions): ComposedEmail;
+//#endregion
+//#region src/blocks/templates/templates.d.ts
+/** Where a template lives: one organization, or every one as a system starter. */
+type TemplateScope = "tenant" | "system";
+/**
+ * A template type, such as `invoice` or `project`: Standard Schemas for its
+ * settings and body (checked on every write and parsed on apply), the merge
+ * fields it offers, and `apply`, which creates the record.
+ */
+interface TemplateType<Settings = unknown, Body = unknown> {
+  readonly settings?: StandardSchemaV1<unknown, Settings>;
+  readonly body?: StandardSchemaV1<unknown, Body>;
+  readonly mergeFields?: MergeFieldCatalog;
+  /**
+   * Creates the record from the published snapshot and names it. A method,
+   * so a type with typed settings is still a `TemplateType` in `types`.
+   */
+  apply?(call: TemplateApplyCall<Settings, Body>): TemplateApplied | Promise<TemplateApplied>;
+}
+interface TemplateApplyCall<Settings = unknown, Body = unknown> {
+  readonly template: Template;
+  readonly version: TemplateVersion;
+  readonly settings: Settings;
+  readonly body: Body;
+  /** The organization the record is created in. */
+  readonly organizationId: string;
+  /** The values `apply` was called with, such as merge field values. */
+  readonly values: Readonly<Record<string, unknown>>;
+  /**
+   * The caller's idempotency key, when it has one (the `templates.apply`
+   * step passes `<runKey>:<node>`), so a retried apply can find the record
+   * it created.
+   */
+  readonly key?: string;
+}
+/** The record `apply` created. */
+interface TemplateApplied {
+  readonly subject: TemplateSubject;
+}
+interface TemplateSubject {
+  readonly type: string;
+  readonly id: string;
+}
+/** Declares a template type with its schemas typed. */
+export declare function defineTemplateType<Settings = unknown, Body = unknown>(type: TemplateType<Settings, Body>): TemplateType<Settings, Body>;
+/** A template. `F` types the extra columns the `fields` schema describes. */
+interface Template<F extends object = Record<never, never>> {
+  readonly id: string;
+  /** `undefined` for a system template. */
+  readonly organizationId: string | undefined;
+  readonly scope: TemplateScope;
+  /** The key `sync` keeps a system template by. */
+  readonly key: string | undefined;
+  readonly type: string;
+  readonly name: string;
+  readonly language: string;
+  /** The default for its organization, type and language. */
+  readonly isDefault: boolean;
+  readonly settings: Readonly<Record<string, unknown>>;
+  /** The template a fork copied, and the version it copied. */
+  readonly forkedFrom: string | undefined;
+  readonly forkedFromVersion: number | undefined;
+  /** The newest published version; `undefined` before the first publish. */
+  readonly publishedVersion: number | undefined;
+  /** For a fork: the source's newest published version. */
+  readonly upstreamVersion: number | undefined;
+  /** For a fork: whether the source published a version after the one it copied. */
+  readonly behind: boolean;
+  readonly createdBy: string | undefined;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
+}
+interface TemplateVersion {
+  readonly id: string;
+  readonly template: string;
+  readonly version: number;
+  /** The SHA-256 of the body. */
+  readonly hash: string;
+  /** `undefined` for the draft. */
+  readonly publishedAt: Temporal.Instant | undefined;
+  readonly createdBy: string | undefined;
+  readonly createdAt: Temporal.Instant;
+  /** Set by `get`, `versions.save` and `versions.publish`; lists leave it out. */
+  readonly body?: unknown;
+}
+interface TemplateDetail<F extends object = Record<never, never>> extends Template<F> {
+  readonly published: TemplateVersion | undefined;
+  readonly draft: TemplateVersion | undefined;
+}
+interface TemplateApplication {
+  readonly id: string;
+  readonly template: string;
+  readonly version: string;
+  readonly organizationId: string;
+  readonly subject: TemplateSubject;
+  readonly appliedBy: string | undefined;
+  readonly appliedAt: Temporal.Instant;
+}
+/** A workflow a template starts on each record it creates. */
+interface TemplateWorkflow {
+  readonly id: string;
+  readonly template: string;
+  readonly definition: string;
+  /** The run's input, checked against the definition's `inputSchema`. */
+  readonly inputs: Readonly<Record<string, unknown>>;
+  readonly enabled: boolean;
+  readonly createdBy: string | undefined;
+  readonly createdAt: Temporal.Instant;
+}
+interface TemplateInput<F extends object = Record<never, never>> {
+  /** Leave it out to create a template. */
+  readonly id?: string;
+  /** `null` for a system template, which only the service role saves. */
+  readonly organizationId: string | null;
+  /** Fixed once the template exists. */
+  readonly type: string;
+  readonly name?: string;
+  /** Default `en`. */
+  readonly language?: string;
+  readonly settings?: Readonly<Record<string, unknown>>;
+  /** The extra columns to set. */
+  readonly fields?: Partial<F>;
+}
+/** A system template `sync` keeps, by key. */
+interface TemplateStarter {
+  readonly key: string;
+  readonly type: string;
+  readonly name: string;
+  readonly language?: string;
+  readonly settings?: Readonly<Record<string, unknown>>;
+  readonly body: unknown;
+}
+interface TemplateWorkflowInput {
+  readonly template: string;
+  readonly definition: string;
+  readonly inputs?: Readonly<Record<string, unknown>>;
+  /** Default `true`. */
+  readonly enabled?: boolean;
+}
+interface ApplyOptions {
+  /** The organization to create the record in. */
+  readonly into: string;
+  readonly values?: Readonly<Record<string, unknown>>;
+  /** Passed to the type's `apply` as `key`. */
+  readonly key?: string;
+}
+/** A workflow `apply` started on the new record, or why it didn't. */
+type TemplateRunStart = {
+  readonly definition: string;
+  readonly runId: string;
+} | {
+  readonly definition: string;
+  readonly error: DbError;
+};
+interface TemplateApplyResult {
+  readonly application: TemplateApplication;
+  readonly subject: TemplateSubject;
+  readonly runs: readonly TemplateRunStart[];
+}
+interface Templates<F extends object = Record<never, never>> {
+  save(input: TemplateInput<F>): AsyncResult<Template<F>>;
+  /** The organization's templates and the system ones (only those with `null`), defaults first. */
+  list(organizationId: string | null, filter?: {
+    readonly type?: string;
+    readonly language?: string;
+  }): AsyncResult<readonly Template<F>[]>;
+  /** With its newest published version and its draft; `undefined` when the caller can't read it. */
+  get(id: string): AsyncResult<TemplateDetail<F> | undefined>;
+  remove(id: string): AsyncResult<boolean>;
+  /** Makes it the default for its organization, type and language (or stops it being one). */
+  setDefault(id: string, isDefault?: boolean): AsyncResult<boolean>;
+  /**
+   * Copies the newest published version of a system template (or one of
+   * the organization's) into a new template there, published as version 1,
+   * with its workflow attachments.
+   */
+  fork(source: string, organizationId: string): AsyncResult<Template<F>>;
+  /**
+   * Upserts the system templates by key and publishes a new version of
+   * each whose body changed. Service role. Returns how many it published.
+   */
+  sync(starters: readonly TemplateStarter[]): AsyncResult<number>;
+  readonly versions: {
+    /** Saves the draft: updates the open one, or opens the next version. */
+    save(template: string, body: unknown): AsyncResult<TemplateVersion>;
+    publish(template: string): AsyncResult<TemplateVersion>;
+    /** Newest first, without bodies. */
+    list(template: string): AsyncResult<readonly TemplateVersion[]>;
+  };
+  /** Needs the workflow-builder module. */
+  readonly workflows: {
+    attach(input: TemplateWorkflowInput): AsyncResult<TemplateWorkflow>;
+    detach(template: string, definition: string): AsyncResult<boolean>;
+    list(template: string): AsyncResult<readonly TemplateWorkflow[]>;
+  };
+  /**
+   * Creates a record from the template's newest published version through
+   * its type's `apply`, records the application and starts the attached
+   * workflows on the new record. `templates.apply` in `into`.
+   */
+  apply(template: string, options: ApplyOptions): AsyncResult<TemplateApplyResult>;
+  readonly applications: {
+    /** Newest first, at most 200. */
+    list(organizationId: string, filter?: {
+      readonly template?: string;
+      readonly subject?: TemplateSubject;
+    }): AsyncResult<readonly TemplateApplication[]>;
+  };
+}
+interface TemplatesOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  /** The module schema, or its API schema: `defineBlocks` passes it from `blocks.generated.ts`. */
+  readonly schema?: string;
+  /**
+   * A Standard Schema for the template's extra columns
+   * (`blocks.templates.options.extraColumns`), keyed by database name. It
+   * types and parses them on reads, and validates them on `save`.
+   */
+  readonly fields?: S;
+  /** The template types, by name. A type without `apply` can't be applied. */
+  readonly types?: Readonly<Record<string, TemplateType>>;
+  /** Starts the attached workflows; `createWorkflowBuilder` as the caller. */
+  readonly workflows?: Pick<WorkflowBuilder, "run">;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Templates<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  readonly mappers?: readonly ErrorMapper[];
+}
+/**
+ * The `templates` SQL module as typed calls: typed, versioned templates
+ * that create records, system starters and forks, and the workflows each
+ * record starts.
+ */
+export declare function createTemplates<S extends StandardSchemaV1 | undefined = undefined>(options: TemplatesOptions<S>): Templates<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/templates/step.d.ts
+/** The `templates.apply` step for the workflow-builder step library. */
+export declare const TEMPLATES_APPLY_STEP: WorkflowStepInfo;
+/** What a `templates.apply` node returns: plain data, so it serializes. */
+interface TemplatesApplyOutput {
+  readonly applicationId: string;
+  readonly subject: {
+    readonly type: string;
+    readonly id: string;
+  };
+  readonly runs: readonly ({
+    readonly definition: string;
+    readonly runId: string;
+  } | {
+    readonly definition: string;
+    readonly error: string;
+  })[];
+}
+/**
+ * Runs a `templates.apply` node: applies `config.template` in the run's
+ * organization, with `config.values`, and keys the apply on
+ * `<runKey>:<node>` so the type's `apply` can find the record a retry
+ * already created. Pass the client, or a function that builds one for the
+ * call (for example as the run's actor). Throws a `DbException` on error,
+ * which fails the node.
+ */
+export declare function templatesApplyStep(templates: Templates | ((call: GraphStepCall) => Templates | Promise<Templates>)): (call: GraphStepCall) => Promise<TemplatesApplyOutput>;
+//#endregion
+//#region src/blocks/templates/events.d.ts
+/** The events of the `templates` block: type to data. */
+type TemplatesEvents = {
+  readonly "template.published": TemplateEventData;
+  readonly "template.applied": TemplateApplicationEventData;
+};
+/** The `templates` block's event types, for its manifest and `onBlockEvent`. */
+export declare const templatesEvents: Events<TemplatesEvents>;
+//#endregion
+//#region src/blocks/templates/manifest.d.ts
+/** The `templates` block's manifest (ADR 0029). */
+export declare const templatesBlock: BlockOf<"templates", typeof createTemplates, TemplatesEvents>;
+//#endregion
+export { type ApplyOptions, type BlockTransport, type EmailTemplateBody, type MergeEscape, type MergeFieldCatalog, type MergeFieldSpec, type MergeValues, type RenderMergeFieldsOptions, type Template, type TemplateApplication, type TemplateApplied, type TemplateApplyCall, type TemplateApplyResult, type TemplateDetail, type TemplateEmailOptions, type TemplateInput, type TemplateRunStart, type TemplateScope, type TemplateStarter, type TemplateSubject, type TemplateType, type TemplateVersion, type TemplateWorkflow, type TemplateWorkflowInput, type Templates, type TemplatesApplyOutput, type TemplatesEvents, type TemplatesOptions, dbTransport, rpcTransport, sqlTransport };