better-supabase 0.8.0 → 0.10.0

package/dist/blocks/state-machine/index.d.ts

@@ -0,0 +1,105 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult } from "../../result-Cj3yWhjH.js";
+import { et as SaasSubjectEventData, wt as Events } from "../../events-CtAHxPal.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { i as CursorPageOptions, n as BlockOptions } from "../../block-helpers-7pMBVsE6.js";
+import { n as BlockHooks } from "../../block-hooks-C_WaodoA.js";
+import { s as BlockOf } from "../../define-block-BlHQxDIQ.js";
+//#region src/blocks/state-machine/state-machine.d.ts
+interface StateMachineOptions<S extends string = string> extends BlockOptions {
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<StateMachine<S>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/** Where a record is in its machine, from `state()`. */
+interface StatusState {
+  readonly organizationId: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  readonly status: string;
+  /** The machine's `order`, empty when it sets none. */
+  readonly order: readonly string[];
+  /** The status's 1-based position in `order`, `undefined` outside it. */
+  readonly step: number | undefined;
+  readonly steps: number | undefined;
+  /** 0 at the first status of `order`, 1 at the last, `undefined` outside it. */
+  readonly progress: number | undefined;
+  /**
+   * The machine version the record is pinned to. `undefined` without
+   * `lifecycle: true`, or for a record created before it was on and never
+   * paused or flagged since.
+   */
+  readonly version: number | undefined;
+  readonly flags: readonly string[];
+  /** True while a pause holds: no end, or an end still in the future. */
+  readonly paused: boolean;
+  readonly pausedAt: Temporal.Instant | undefined;
+  readonly pausedUntil: Temporal.Instant | undefined;
+  readonly pauseReason: string | undefined;
+}
+/** One status change from `history()`. */
+interface StatusChange {
+  readonly id: string;
+  /** `undefined` for the first status of a history table that records it. */
+  readonly from: string | undefined;
+  readonly to: string;
+  readonly actorId: string | undefined;
+  readonly reason: string | undefined;
+  readonly createdAt: Temporal.Instant;
+}
+/** One row of a machine's stages timeline, from `stages()`. */
+interface StatusStage {
+  readonly id: string;
+  readonly label: string;
+  readonly outcome: string | undefined;
+  readonly display: number;
+  /** When the record moved on from this stage; `undefined` for the open one. */
+  readonly clearedAt: Temporal.Instant | undefined;
+  readonly createdAt: Temporal.Instant;
+}
+interface StateMachine<S extends string = string> {
+  /**
+   * Sets the status as the caller: the record table's policies decide
+   * whether they may update it, and the trigger rejects a change the
+   * machine does not allow. `not_found` for a record they can't see.
+   */
+  transition(subjectType: S, subjectId: string, to: string, reason?: string): AsyncResult<boolean>;
+  /**
+   * Pauses the record (`lifecycle: true`): transitions fail with
+   * `STATE_PAUSED` until `until` passes, or until `resume()` without one.
+   */
+  pause(subjectType: S, subjectId: string, options?: {
+    readonly until?: Temporal.Instant;
+    readonly reason?: string;
+  }): AsyncResult<boolean>;
+  /** Ends a pause; `false` when the record wasn't paused. */
+  resume(subjectType: S, subjectId: string): AsyncResult<boolean>;
+  /** Turns a flag the machine lists in `flags` on or off; `false` when it already was. */
+  setFlag(subjectType: S, subjectId: string, flag: string, enabled: boolean): AsyncResult<boolean>;
+  /** The record's status, progress, flags, pause and pinned version. */
+  state(subjectType: S, subjectId: string): AsyncResult<StatusState>;
+  /** Status changes, newest first; page with the last `createdAt` as `cursor`. Default 50, at most 500. */
+  history(subjectType: S, subjectId: string, page?: CursorPageOptions<Temporal.Instant>): AsyncResult<readonly StatusChange[]>;
+  /** The stages timeline in display order; empty for a machine without `stages: true`. */
+  stages(subjectType: S, subjectId: string): AsyncResult<readonly StatusStage[]>;
+}
+/** The `state-machine` SQL module as typed calls. */
+export declare function createStateMachine<S extends string = string>(options: StateMachineOptions<S>): StateMachine<S>;
+//#endregion
+//#region src/blocks/state-machine/events.d.ts
+/** The events of the `state-machine` block: type to data. */
+type StateMachineEvents = {
+  readonly "status.changed": SaasSubjectEventData;
+  readonly "status.paused": SaasSubjectEventData;
+  readonly "status.resumed": SaasSubjectEventData;
+  readonly "status.flagged": SaasSubjectEventData;
+};
+/** The `state-machine` block's event types, for its manifest and `onBlockEvent`. */
+export declare const stateMachineEvents: Events<StateMachineEvents>;
+//#endregion
+//#region src/blocks/state-machine/manifest.d.ts
+/** The `state-machine` block's manifest (ADR 0029). */
+export declare const stateMachineBlock: BlockOf<"state-machine", typeof createStateMachine, StateMachineEvents>;
+//#endregion
+export type { StateMachine, StateMachineEvents, StateMachineOptions, StatusChange, StatusStage, StatusState };

package/dist/blocks/state-machine/index.js

@@ -0,0 +1,116 @@
+import { t as stateMachineSqlOptions } from "../../options-B0FcEKtH.js";
+import { n as event, t as defineEvents } from "../../event-map-Dy2vKHai.js";
+import { A as requiredInstant, C as optionalText, D as recordOf, F as stringsOf, I as textOf, S as optionalInstant, k as recordsOf, m as instantArg, n as applyTemporal, o as blockCall, w as pageOf } from "../../block-helpers-BfVCR5Fc.js";
+import { r as withBlockHooks } from "../../block-hooks-ByKlh8Qy.js";
+import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
+//#region src/blocks/state-machine/state-machine.ts
+const optionalNumber = (value) => value === null || value === void 0 ? void 0 : Number(value);
+function stateOf(value) {
+	const row = recordOf(value, "status_state");
+	return {
+		organizationId: textOf(row["organizationId"]),
+		subjectType: textOf(row["subjectType"]),
+		subjectId: textOf(row["subjectId"]),
+		status: textOf(row["status"]),
+		order: stringsOf(row["order"]),
+		step: optionalNumber(row["step"]),
+		steps: optionalNumber(row["steps"]),
+		progress: optionalNumber(row["progress"]),
+		version: optionalNumber(row["version"]),
+		flags: stringsOf(row["flags"]),
+		paused: row["paused"] === true,
+		pausedAt: optionalInstant(row["pausedAt"]),
+		pausedUntil: optionalInstant(row["pausedUntil"]),
+		pauseReason: optionalText(row["pauseReason"])
+	};
+}
+function changeOf(row) {
+	return {
+		id: textOf(row["id"]),
+		from: optionalText(row["from"]),
+		to: textOf(row["to"]),
+		actorId: optionalText(row["actorId"]),
+		reason: optionalText(row["reason"]),
+		createdAt: requiredInstant(row["createdAt"], "createdAt")
+	};
+}
+function stageOf(row) {
+	return {
+		id: textOf(row["id"]),
+		label: textOf(row["label"]),
+		outcome: optionalText(row["outcome"]),
+		display: Number(row["display"]),
+		clearedAt: optionalInstant(row["clearedAt"]),
+		createdAt: requiredInstant(row["createdAt"], "createdAt")
+	};
+}
+/** The `state-machine` SQL module as typed calls. */
+function createStateMachine(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const isTrue = (value) => value === true;
+	return withBlockHooks({
+		transition: (subjectType, subjectId, to, reason) => call("transition", {
+			subject_type: subjectType,
+			subject_id: subjectId,
+			to_status: to,
+			reason: reason ?? null
+		}, isTrue),
+		pause: (subjectType, subjectId, pause = {}) => call("pause_lifecycle", {
+			subject_type: subjectType,
+			subject_id: subjectId,
+			until: instantArg(pause.until) ?? null,
+			reason: pause.reason ?? null
+		}, isTrue),
+		resume: (subjectType, subjectId) => call("resume_lifecycle", {
+			subject_type: subjectType,
+			subject_id: subjectId
+		}, isTrue),
+		setFlag: (subjectType, subjectId, flag, enabled) => call("set_lifecycle_flag", {
+			subject_type: subjectType,
+			subject_id: subjectId,
+			flag,
+			enabled
+		}, isTrue),
+		state: (subjectType, subjectId) => call("status_state", {
+			subject_type: subjectType,
+			subject_id: subjectId
+		}, stateOf),
+		history: (subjectType, subjectId, page) => call("list_status_history", {
+			subject_type: subjectType,
+			subject_id: subjectId,
+			before: instantArg(pageOf(page).cursor),
+			max_rows: page?.limit
+		}, (value) => recordsOf(value, "list_status_history").map(changeOf)),
+		stages: (subjectType, subjectId) => call("list_status_stages", {
+			subject_type: subjectType,
+			subject_id: subjectId
+		}, (value) => recordsOf(value, "list_status_stages").map(stageOf))
+	}, options.hooks, {
+		block: "state-machine",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+//#region src/blocks/state-machine/events.ts
+/** The `state-machine` block's event types, for its manifest and `onBlockEvent`. */
+const stateMachineEvents = defineEvents({
+	"status.changed": event(),
+	"status.paused": event(),
+	"status.resumed": event(),
+	"status.flagged": event()
+});
+//#endregion
+//#region src/blocks/state-machine/manifest.ts
+/** The `state-machine` block's manifest (ADR 0029). */
+const stateMachineBlock = defineBlock({
+	name: "state-machine",
+	sql: ["state-machine"],
+	options: { "state-machine": stateMachineSqlOptions },
+	events: stateMachineEvents,
+	create: createStateMachine,
+	category: "work",
+	recipes: ["work-item-board"]
+});
+//#endregion
+export { createStateMachine, stateMachineBlock, stateMachineEvents };

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

@@ -0,0 +1,20 @@
+import { $ as SaasEventData, et as SaasSubjectEventData, wt as Events } from "../../events-CtAHxPal.js";
+import { s as BlockOf } from "../../define-block-BlHQxDIQ.js";
+import { a as TagInputSnapshot, c as Tags, i as TagInputControllerOptions, l as TagsOptions, n as TagInputActions, o as createTagInputController, r as TagInputController, s as Tag, t as TagChange, u as createTags } from "../../client-BtBkVSk2.js";
+//#region src/blocks/tags/events.d.ts
+/** The events of the `tags` block: type to data. */
+type TagsEvents = {
+  readonly "tag.created": SaasEventData;
+  readonly "tag.updated": SaasEventData;
+  readonly "tag.deleted": SaasEventData;
+  readonly "subject.tagged": SaasSubjectEventData;
+  readonly "subject.untagged": SaasSubjectEventData;
+};
+/** The `tags` block's event types, for its manifest and `onBlockEvent`. */
+export declare const tagsEvents: Events<TagsEvents>;
+//#endregion
+//#region src/blocks/tags/manifest.d.ts
+/** The `tags` block's manifest (ADR 0029). */
+export declare const tagsBlock: BlockOf<"tags", typeof createTags, TagsEvents>;
+//#endregion
+export { type Tag, type TagChange, type TagInputActions, type TagInputController, type TagInputControllerOptions, type TagInputSnapshot, type Tags, type TagsEvents, type TagsOptions, createTagInputController, createTags };

package/dist/blocks/tags/index.js

@@ -0,0 +1,28 @@
+import { t as tagsSqlOptions } from "../../options-I8zVkB_y.js";
+import { n as event, t as defineEvents } from "../../event-map-Dy2vKHai.js";
+import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
+import { t as createTags } from "../../tags-DGldvcA4.js";
+import { t as createTagInputController } from "../../client-fpvgtQKE.js";
+//#region src/blocks/tags/events.ts
+/** The `tags` block's event types, for its manifest and `onBlockEvent`. */
+const tagsEvents = defineEvents({
+	"tag.created": event(),
+	"tag.updated": event(),
+	"tag.deleted": event(),
+	"subject.tagged": event(),
+	"subject.untagged": event()
+});
+//#endregion
+//#region src/blocks/tags/manifest.ts
+/** The `tags` block's manifest (ADR 0029). */
+const tagsBlock = defineBlock({
+	name: "tags",
+	sql: ["tags"],
+	options: { tags: tagsSqlOptions },
+	events: tagsEvents,
+	create: createTags,
+	category: "work",
+	recipes: ["record-page", "tag-input"]
+});
+//#endregion
+export { createTagInputController, createTags, tagsBlock, tagsEvents };

package/dist/blocks/tags/react/index.d.ts

@@ -0,0 +1,28 @@
+import { a as TagInputSnapshot, n as TagInputActions, t as TagChange } from "../../../client-BtBkVSk2.js";
+//#region src/blocks/tags/react/index.d.ts
+export interface UseTagInputOptions {
+  /** The organization; the input waits without one. */
+  readonly organizationId: string | null | undefined;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  /** The kind of tags the input offers and creates, such as `customer`. */
+  readonly kind: string;
+  /** The schema the calls go to: the module schema (default `better_supabase`), or the API schema from `blocks.<module>.api`. */
+  readonly schema?: string;
+  /** Runs after a tag was added or removed. */
+  readonly onChanged?: (change: TagChange) => void | Promise<void>;
+}
+export interface TagInputState extends TagInputSnapshot, TagInputActions {}
+/**
+ * One subject's tags through the browser client, for a tag input: the
+ * tags on it, every tag of the kind for suggestions, and `add`, `remove`
+ * and `create`, which show the change at once. The same hook runs in
+ * React DOM and React Native.
+ *
+ * ```tsx
+ * const { tags, available, add, remove, create } = useTagInput({ organizationId, subjectType: "customer", subjectId, kind: "customer" });
+ * ```
+ */
+export declare function useTagInput(options: UseTagInputOptions): TagInputState;
+//#endregion
+export type { TagChange };

package/dist/blocks/tags/react/index.js

@@ -0,0 +1,47 @@
+"use client";
+import { r as rpcTransport } from "../../../block-transport-G4t1umrR.js";
+import { n as useLatest, t as useController } from "../../../react-controller-Xn-IU44p.js";
+import { t as useBlockEnv } from "../../../react-env-Cc7Vf6eb.js";
+import { t as createTags } from "../../../tags-DGldvcA4.js";
+import { t as createTagInputController } from "../../../client-fpvgtQKE.js";
+//#region src/blocks/tags/react/index.ts
+/**
+* One subject's tags through the browser client, for a tag input: the
+* tags on it, every tag of the kind for suggestions, and `add`, `remove`
+* and `create`, which show the change at once. The same hook runs in
+* React DOM and React Native.
+*
+* ```tsx
+* const { tags, available, add, remove, create } = useTagInput({ organizationId, subjectType: "customer", subjectId, kind: "customer" });
+* ```
+*/
+function useTagInput(options) {
+	const { supabase, auth } = useBlockEnv();
+	const latest = useLatest(options);
+	const { organizationId, subjectType, subjectId, kind, schema } = options;
+	return useController(() => createTagInputController({
+		client: createTags({
+			transport: rpcTransport(supabase),
+			...schema === void 0 ? {} : { schema }
+		}),
+		auth,
+		organizationId: organizationId ?? null,
+		subjectType,
+		subjectId,
+		kind,
+		onChanged: async (change) => {
+			await latest.current.onChanged?.(change);
+		}
+	}), [
+		supabase,
+		auth,
+		organizationId,
+		subjectType,
+		subjectId,
+		kind,
+		schema,
+		latest
+	]).view;
+}
+//#endregion
+export { useTagInput };

package/dist/blocks/tags/react/server.d.ts

@@ -0,0 +1,7 @@
+import { t as TagChange } from "../../../client-BtBkVSk2.js";
+import { TagInputState, UseTagInputOptions } from "./index.js";
+//#region src/blocks/tags/react/server.d.ts
+/** The `react-server` build of `useTagInput`: call `tags.forSubject()` instead. */
+export declare const useTagInput: (options: UseTagInputOptions) => TagInputState;
+//#endregion
+export type { TagChange, TagInputState, UseTagInputOptions };

package/dist/blocks/tags/react/server.js

@@ -0,0 +1,7 @@
+//#region src/blocks/tags/react/server.ts
+/** The `react-server` build of `useTagInput`: call `tags.forSubject()` instead. */
+const useTagInput = () => {
+	throw new Error("better-supabase: useTagInput() runs in Client Components only. In Server Components call `tags.forSubject()` instead.");
+};
+//#endregion
+export { useTagInput };

package/dist/blocks/tags/solid/index.d.ts

@@ -0,0 +1,13 @@
+import { t as BlockOptions } from "../../../block-env-Dxl7rsI0.js";
+import { t as SolidController } from "../../../solid-controller-CZrt1Tg6.js";
+import { a as TagInputSnapshot, i as TagInputControllerOptions, n as TagInputActions } from "../../../client-BtBkVSk2.js";
+//#region src/blocks/tags/solid/index.d.ts
+/**
+ * `createTagInputController` as a Solid primitive: `state()` reads the
+ * snapshot. Call it in a component; the work starts on mount and the controller
+ * is disposed with the owner. `auth` and `ports` default to the client of
+ * `<BetterSupabaseProvider client={bs}>`.
+ */
+export declare function useTagInput(options: BlockOptions<TagInputControllerOptions>): SolidController<TagInputSnapshot, TagInputActions>;
+//#endregion
+export type { BlockOptions, SolidController, TagInputActions, TagInputControllerOptions, TagInputSnapshot };

package/dist/blocks/tags/solid/index.js

@@ -0,0 +1,14 @@
+import { t as useBlockController } from "../../../solid-controller-DLsmrczT.js";
+import { t as createTagInputController } from "../../../client-fpvgtQKE.js";
+//#region src/blocks/tags/solid/index.ts
+/**
+* `createTagInputController` as a Solid primitive: `state()` reads the
+* snapshot. Call it in a component; the work starts on mount and the controller
+* is disposed with the owner. `auth` and `ports` default to the client of
+* `<BetterSupabaseProvider client={bs}>`.
+*/
+function useTagInput(options) {
+	return useBlockController(createTagInputController, options);
+}
+//#endregion
+export { useTagInput };

package/dist/blocks/tags/svelte/index.d.ts

@@ -0,0 +1,13 @@
+import { t as BlockOptions } from "../../../block-env-Dxl7rsI0.js";
+import { t as SvelteController } from "../../../svelte-controller-DDbju9CW.js";
+import { a as TagInputSnapshot, i as TagInputControllerOptions, n as TagInputActions } from "../../../client-BtBkVSk2.js";
+//#region src/blocks/tags/svelte/index.d.ts
+/**
+ * `createTagInputController` as a Svelte readable store of the snapshot, with
+ * the actions on `.actions`. Call it in a component's script; the work starts
+ * on mount and the controller is disposed with the component. `auth` and
+ * `ports` default to the client of `setBetterSupabase(bs)`.
+ */
+export declare function useTagInput(options: BlockOptions<TagInputControllerOptions>): SvelteController<TagInputSnapshot, TagInputActions>;
+//#endregion
+export type { BlockOptions, SvelteController, TagInputActions, TagInputControllerOptions, TagInputSnapshot };

package/dist/blocks/tags/svelte/index.js

@@ -0,0 +1,14 @@
+import { t as useBlockController } from "../../../svelte-controller-CDAujo-_.js";
+import { t as createTagInputController } from "../../../client-fpvgtQKE.js";
+//#region src/blocks/tags/svelte/index.ts
+/**
+* `createTagInputController` as a Svelte readable store of the snapshot, with
+* the actions on `.actions`. Call it in a component's script; the work starts
+* on mount and the controller is disposed with the component. `auth` and
+* `ports` default to the client of `setBetterSupabase(bs)`.
+*/
+function useTagInput(options) {
+	return useBlockController(createTagInputController, options);
+}
+//#endregion
+export { useTagInput };

package/dist/blocks/tags/vue/index.d.ts

@@ -0,0 +1,13 @@
+import { t as BlockOptions } from "../../../block-env-Dxl7rsI0.js";
+import { t as VueController } from "../../../vue-controller-D_ohttBZ.js";
+import { a as TagInputSnapshot, i as TagInputControllerOptions, n as TagInputActions } from "../../../client-BtBkVSk2.js";
+//#region src/blocks/tags/vue/index.d.ts
+/**
+ * `createTagInputController` as a Vue composable: `state` is a shallow ref of
+ * the snapshot. Call it in `setup` or an effect scope; the work starts on mount
+ * and the controller is disposed with the scope. `auth` and `ports` default to
+ * the client of `app.use(betterSupabase(bs))`.
+ */
+export declare function useTagInput(options: BlockOptions<TagInputControllerOptions>): VueController<TagInputSnapshot, TagInputActions>;
+//#endregion
+export type { BlockOptions, TagInputActions, TagInputControllerOptions, TagInputSnapshot, VueController };

package/dist/blocks/tags/vue/index.js

@@ -0,0 +1,14 @@
+import { t as useBlockController } from "../../../vue-controller-C9tFzqAc.js";
+import { t as createTagInputController } from "../../../client-fpvgtQKE.js";
+//#region src/blocks/tags/vue/index.ts
+/**
+* `createTagInputController` as a Vue composable: `state` is a shallow ref of
+* the snapshot. Call it in `setup` or an effect scope; the work starts on mount
+* and the controller is disposed with the scope. `auth` and `ports` default to
+* the client of `app.use(betterSupabase(bs))`.
+*/
+function useTagInput(options) {
+	return useBlockController(createTagInputController, options);
+}
+//#endregion
+export { useTagInput };

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

@@ -0,0 +1,82 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult } from "../../result-Cj3yWhjH.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { t as StandardSchemaV1 } from "../../standard-C3_AAF3g.js";
+import { a as dbTransport, i as RpcClient, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-NbUJygA7.js";
+import { n as BlockOptions } from "../../block-helpers-7pMBVsE6.js";
+import { a as BlockTransportMiddleware, d as extendBlock, f as withBlockHooks, n as BlockHooks, p as wrapTransport } from "../../block-hooks-C_WaodoA.js";
+import { n as ExtraFields, r as FieldsOf } from "../../block-fields-5UA84ZUg.js";
+import { s as BlockOf } from "../../define-block-BlHQxDIQ.js";
+//#region src/blocks/targets/targets.d.ts
+/**
+ * A metric the database computes, or any other name the app keeps the
+ * actual value of itself.
+ */
+type TargetMetric = "deals.won_amount" | "deals.won_count" | "work_items.completed" | "invoices.paid_amount" | (string & {});
+/** A target. `F` types the extra columns the `fields` schema describes. */
+interface Target<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly name: string;
+  readonly metric: TargetMetric;
+  /** The member it is for; `undefined` for a team or the organization. */
+  readonly ownerId?: string;
+  readonly teamId?: string;
+  readonly periodStart: Temporal.PlainDate;
+  readonly periodEnd: Temporal.PlainDate;
+  /** For amount metrics. */
+  readonly currency?: string;
+  /** Minor units for amounts, a count otherwise. */
+  readonly goal: bigint;
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
+}
+interface TargetProgress<F extends object = Record<never, never>> extends Target<F> {
+  readonly progress: bigint;
+  /** Progress over the goal: 0.5 is halfway. */
+  readonly attainment: number;
+}
+interface TargetInput<F extends object = Record<never, never>> {
+  readonly id?: string;
+  readonly name?: string;
+  readonly metric?: TargetMetric;
+  readonly ownerId?: string;
+  readonly teamId?: string;
+  readonly periodStart?: Temporal.PlainDate;
+  readonly periodEnd?: Temporal.PlainDate;
+  readonly currency?: string;
+  readonly goal?: bigint;
+  /** The value of a metric no block computes. */
+  readonly actual?: bigint;
+  readonly archived?: boolean;
+  /** The extra columns to set. */
+  readonly fields?: Partial<F>;
+}
+interface Targets<F extends object = Record<never, never>> {
+  save(organizationId: string, target: TargetInput<F>): AsyncResult<Target<F>>;
+  /** The targets running on `on` (today by default), with progress. */
+  progress(organizationId: string, options?: {
+    readonly on?: Temporal.PlainDate;
+    readonly ownerId?: string;
+  }): AsyncResult<TargetProgress<F>[]>;
+}
+interface TargetsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockOptions {
+  /**
+   * A Standard Schema for the target's extra columns
+   * (`blocks.targets.options.extraColumns`), keyed by database name. It
+   * types and parses them on reads, and validates them on `save`.
+   */
+  readonly fields?: S;
+  readonly hooks?: NoInfer<BlockHooks<Targets<FieldsOf<S>>>>;
+  readonly logger?: Logger;
+}
+/**
+ * The targets block: goals per period for a member, a team or the
+ * organization, and their progress.
+ */
+export declare function createTargets<S extends StandardSchemaV1 | undefined = undefined>(options: TargetsOptions<S>): Targets<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/targets/manifest.d.ts
+/** The `targets` block's manifest (ADR 0029). */
+export declare const targetsBlock: BlockOf<"targets", typeof createTargets>;
+//#endregion
+export { type BlockHooks, type BlockTransport, type BlockTransportMiddleware, type RpcClient, type Target, type TargetInput, type TargetMetric, type TargetProgress, type Targets, type TargetsOptions, dbTransport, extendBlock, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };

package/dist/blocks/targets/index.js

@@ -0,0 +1,73 @@
+import { n as isRecord } from "../../guards-6F2bCtQR.js";
+import { t as targetsSqlOptions } from "../../options-CGKSUFUq.js";
+import { i as sqlTransport, r as rpcTransport, t as dbTransport } from "../../block-transport-G4t1umrR.js";
+import { C as optionalText, D as recordOf, I as textOf, a as bigintOf, k as recordsOf, n as applyTemporal, o as blockCall } from "../../block-helpers-BfVCR5Fc.js";
+import { i as wrapTransport, n as extendBlock, r as withBlockHooks } from "../../block-hooks-ByKlh8Qy.js";
+import { n as blockFields } from "../../block-fields-BANwJ9Y_.js";
+import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
+import { n as compact, r as plainDate, t as attrsArg } from "../../sales-shared-DjCuN8xG.js";
+//#region src/blocks/targets/targets.ts
+function targetOf(value) {
+	const row = recordOf(value, "target");
+	return compact({
+		id: textOf(row["id"]),
+		name: textOf(row["name"]),
+		metric: textOf(row["metric"]),
+		ownerId: optionalText(row["owner_user_id"]),
+		teamId: optionalText(row["team_id"]),
+		periodStart: plainDate(row["period_start"]) ?? plainDate("1970-01-01"),
+		periodEnd: plainDate(row["period_end"]) ?? plainDate("1970-01-01"),
+		currency: optionalText(row["currency"]),
+		goal: bigintOf(row["goal"], "target goal"),
+		fields: isRecord(row["fields"]) ? row["fields"] : {}
+	});
+}
+/**
+* The targets block: goals per period for a member, a team or the
+* organization, and their progress.
+*/
+function createTargets(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const fields = blockFields(options.fields, "target fields");
+	return withBlockHooks({
+		save: (organizationId, target) => {
+			const { id, goal, actual, fields: extra, ...rest } = target;
+			return fields.args(extra).andThen((checked) => call("save_target", {
+				tenant: organizationId,
+				target: id ?? null,
+				attrs: {
+					...attrsArg(rest),
+					...goal === void 0 ? {} : { goal: goal.toString() },
+					...actual === void 0 ? {} : { actual: actual.toString() },
+					...checked === void 0 ? {} : { fields: checked }
+				}
+			}, targetOf).andThen(fields.row));
+		},
+		progress: (organizationId, progress = {}) => call("target_progress", {
+			tenant: organizationId,
+			on_date: progress.on === void 0 ? null : progress.on.toString(),
+			owner: progress.ownerId ?? null
+		}, (value) => recordsOf(value, "target_progress").map((row) => ({
+			...targetOf(row),
+			progress: bigintOf(row["progress"], "target progress"),
+			attainment: Number(row["attainment"] ?? 0)
+		}))).andThen(fields.rows)
+	}, options.hooks, {
+		block: "targets",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+//#region src/blocks/targets/manifest.ts
+/** The `targets` block's manifest (ADR 0029). */
+const targetsBlock = defineBlock({
+	name: "targets",
+	sql: ["targets"],
+	options: { targets: targetsSqlOptions },
+	create: createTargets,
+	category: "crm",
+	recipes: ["targets-progress"]
+});
+//#endregion
+export { createTargets, dbTransport, extendBlock, rpcTransport, sqlTransport, targetsBlock, withBlockHooks, wrapTransport };