better-supabase 0.8.0 → 0.9.0

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

@@ -1,89 +1,23 @@
-import { t as AsyncResult, w as ErrorMapper } from "../../result-BchM1XZn.js";
-import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-inD4fFq-.js";
-import { r as BlockTemporalOptions } from "../../block-helpers-C0Xj8War.js";
-import { StandardSchemaV1 } from "@standard-schema/spec";
-//#region src/blocks/settings/settings.d.ts
-/** One setting: its Standard Schema and the value `get` returns when none is stored. */
-interface SettingEntry<S extends StandardSchemaV1 = StandardSchemaV1> {
-  readonly schema: S;
-  readonly default?: StandardSchemaV1.InferOutput<S>;
-  /**
-   * Platform settings only: the platform permission (`is_platform`) that
-   * may change this key. Default `sql.modules.settings.options.platform.permission`,
-   * then `settings.manage`.
-   */
-  readonly permission?: string;
-  /**
-   * Platform settings only: who reads this key, `public` (anyone, also
-   * signed out), `authenticated` (default) or `staff` (holders of its
-   * permission).
-   */
-  readonly read?: "public" | "authenticated" | "staff";
-}
-type SettingEntries = Readonly<Record<string, SettingEntry>>;
-/** The value type of each key: the schema output, or `undefined` without a default. */
-type SettingValues<E extends SettingEntries> = { readonly [K in keyof E]: E[K] extends SettingEntry<infer S> ? E[K] extends {
-  readonly default: unknown;
-} ? StandardSchemaV1.InferOutput<S> : StandardSchemaV1.InferOutput<S> | undefined : never; };
-/** What a scope's `set` accepts per key: the schema input. */
-type SettingInputs<E extends SettingEntries> = { readonly [K in keyof E]: E[K] extends SettingEntry<infer S> ? StandardSchemaV1.InferInput<S> : never; };
-interface SettingsSpec<U extends SettingEntries = SettingEntries, O extends SettingEntries = SettingEntries, P extends SettingEntries = SettingEntries> {
-  readonly user?: U;
-  readonly organization?: O;
-  /** Settings for the whole product, such as an admin console edits. */
-  readonly platform?: P;
-}
-interface SettingsConnectOptions extends BlockTemporalOptions {
-  readonly transport: BlockTransport;
-  /** The module schema (`sql.modules.settings.schema`), default `better_supabase`. */
-  readonly schema?: string;
-  readonly mappers?: readonly ErrorMapper[];
-}
-/** The caller's own settings. */
-interface UserSettings<E extends SettingEntries> {
-  /** Every key, stored values merged over the defaults. */
-  get(): AsyncResult<SettingValues<E>>;
-  get<K extends keyof E & string>(key: K): AsyncResult<SettingValues<E>[K]>;
-  /** Validates `value` with the key's schema, then stores the output. */
-  set<K extends keyof E & string>(key: K, value: SettingInputs<E>[K]): AsyncResult<SettingValues<E>[K]>;
-  /** Removes the stored value, so `get` returns the default again. */
-  reset(key: keyof E & string): AsyncResult<boolean>;
-}
-/** One organization's settings; reads need `settings.read`, writes `settings.update`. */
-interface OrganizationSettings<E extends SettingEntries> {
-  get(organizationId: string): AsyncResult<SettingValues<E>>;
-  get<K extends keyof E & string>(organizationId: string, key: K): AsyncResult<SettingValues<E>[K]>;
-  set<K extends keyof E & string>(organizationId: string, key: K, value: SettingInputs<E>[K]): AsyncResult<SettingValues<E>[K]>;
-  reset(organizationId: string, key: keyof E & string): AsyncResult<boolean>;
-}
-/**
- * The product-wide settings: reads follow each key's `read`, writes need
- * its platform permission.
- */
-type PlatformSettings<E extends SettingEntries> = UserSettings<E>;
-interface SettingsClient<U extends SettingEntries, O extends SettingEntries, P extends SettingEntries = Record<never, never>> {
-  readonly user: UserSettings<U>;
-  readonly organization: OrganizationSettings<O>;
-  readonly platform: PlatformSettings<P>;
-}
-interface SettingsDefinition<U extends SettingEntries, O extends SettingEntries, P extends SettingEntries = Record<never, never>> {
-  /**
-   * Pass as `sql.modules.settings.options.schemas` for the database checks,
-   * and the platform keys' permissions and read rules.
-   */
-  readonly schemas: {
-    readonly user: U;
-    readonly organization: O;
-    readonly platform: P;
-  };
-  /** Typed `get`, `set` and `reset` over the settings module's functions. */
-  connect(options: SettingsConnectOptions): SettingsClient<U, O, P>;
-}
+import { rt as SettingEventData, wt as Events } from "../../events-CTreRrgP.js";
+import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DaGGXjIw.js";
+import { s as BlockOf } from "../../define-block-CLZMEFeK.js";
+import { _ as createSettings, a as SettingsControllerOptions, c as settingFields, d as SettingInputs, f as SettingValues, g as SettingsSpec, h as SettingsOptions, i as SettingsController, l as SettingEntries, m as SettingsDefinition, n as SettingKind, o as SettingsSnapshot, p as Settings, r as SettingsActions, s as createSettingsController, t as SettingField, u as SettingEntry, v as defineSettings } from "../../client-DAHsEOVV.js";
+//#region src/blocks/settings/events.d.ts
+/** The events of the `settings` block: type to data. */
+type SettingsEvents = {
+  readonly "organization_setting.updated": SettingEventData;
+  readonly "organization_setting.reset": SettingEventData;
+  readonly "platform_setting.updated": SettingEventData;
+  readonly "platform_setting.reset": SettingEventData;
+};
+/** The `settings` block's event types, for its manifest and `onBlockEvent`. */
+export declare const settingsEvents: Events<SettingsEvents>;
+//#endregion
+//#region src/blocks/settings/manifest.d.ts
 /**
- * Declares the app's settings with a Standard Schema per key. Values are
- * validated before they are written, and stored values that no longer match
- * their schema read as the default.
+ * The `settings` block's manifest (ADR 0029). Pass the app's settings with
+ * `settingsBlock.using((options) => createSettings({ ...options, settings }))`.
  */
-export declare function defineSettings<const U extends SettingEntries = Record<never, never>, const O extends SettingEntries = Record<never, never>, const P extends SettingEntries = Record<never, never>>(spec: SettingsSpec<U, O, P>): SettingsDefinition<U, O, P>;
+export declare const settingsBlock: BlockOf<"settings", typeof createSettings, SettingsEvents>;
 //#endregion
-export { type BlockTransport, type OrganizationSettings, type PlatformSettings, type SettingEntries, type SettingEntry, type SettingInputs, type SettingValues, type SettingsClient, type SettingsConnectOptions, type SettingsDefinition, type SettingsSpec, type UserSettings, dbTransport, rpcTransport, sqlTransport };
+export { type BlockTransport, type SettingEntries, type SettingEntry, type SettingField, type SettingInputs, type SettingKind, type SettingValues, type Settings, type SettingsActions, type SettingsController, type SettingsControllerOptions, type SettingsDefinition, type SettingsEvents, type SettingsOptions, type SettingsSnapshot, type SettingsSpec, createSettings, createSettingsController, dbTransport, defineSettings, rpcTransport, settingFields, sqlTransport };

package/dist/blocks/settings/index.js

@@ -1,105 +1,31 @@
-import { n as dbError } from "../../errors-2M6CKMP4.js";
-import { r as err, t as AsyncResult } from "../../result-DEqHCMKP.js";
-import { n as isRecord } from "../../guards-6F2bCtQR.js";
-import { n as validate } from "../../standard-DkzZUneg.js";
-import { i as sqlTransport, r as rpcTransport, t as dbTransport } from "../../block-transport-bAKh-dGc.js";
-import { i as blockCall, n as applyTemporal } from "../../block-helpers-Cy3pB96I.js";
-//#region src/blocks/settings/settings.ts
+import { n as event, t as defineEvents } from "../../event-map-Dy2vKHai.js";
+import { i as sqlTransport, r as rpcTransport, t as dbTransport } from "../../block-transport-G4t1umrR.js";
+import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
+import { n as defineSettings, t as createSettings } from "../../settings-BXFn9zpS.js";
+import { t as settingsSqlOptions } from "../../options-CVSWgZpY.js";
+import { n as settingFields, t as createSettingsController } from "../../client-01MAuqzW.js";
+//#region src/blocks/settings/events.ts
+/** The `settings` block's event types, for its manifest and `onBlockEvent`. */
+const settingsEvents = defineEvents({
+	"organization_setting.updated": event(),
+	"organization_setting.reset": event(),
+	"platform_setting.updated": event(),
+	"platform_setting.reset": event()
+});
+//#endregion
+//#region src/blocks/settings/manifest.ts
 /**
-* Declares the app's settings with a Standard Schema per key. Values are
-* validated before they are written, and stored values that no longer match
-* their schema read as the default.
+* The `settings` block's manifest (ADR 0029). Pass the app's settings with
+* `settingsBlock.using((options) => createSettings({ ...options, settings }))`.
 */
-function defineSettings(spec) {
-	const user = spec.user ?? {};
-	const organization = spec.organization ?? {};
-	const platform = spec.platform ?? {};
-	return {
-		schemas: {
-			user,
-			organization,
-			platform
-		},
-		connect: (options) => {
-			applyTemporal(options);
-			const call = blockCall(options.transport, options.schema, options.mappers);
-			return {
-				user: userScope(user, call),
-				organization: organizationScope(organization, call),
-				platform: platformScope(platform, call)
-			};
-		}
-	};
-}
-/** Stored values merged over the defaults; unknown keys are dropped. */
-async function merged(entries, stored) {
-	const values = isRecord(stored) ? stored : {};
-	const out = {};
-	for (const [key, entry] of Object.entries(entries)) out[key] = await readValue(entry, values[key]);
-	return out;
-}
-async function readValue(entry, stored) {
-	if (stored === void 0) return entry.default;
-	const parsed = await validate(entry.schema, stored);
-	return parsed.ok ? parsed.data : entry.default;
-}
-function unknownSetting(key) {
-	return AsyncResult.from(() => Promise.resolve(err(dbError("invalid_input", `Unknown setting "${key}"`))));
-}
-/** Reads every key, or one key, through `fn`. */
-function reader(entries, call, fn, args, key) {
-	if (key !== void 0 && !(key in entries)) return unknownSetting(key);
-	return call(fn, args, async (stored) => {
-		const values = await merged(entries, stored);
-		return key === void 0 ? values : values[key];
-	});
-}
-/** Validates `value` with the key's schema, then writes the output through `fn`. */
-function writer(entries, call, fn, args, key, value) {
-	const entry = entries[key];
-	if (!entry) return unknownSetting(key);
-	return AsyncResult.from(() => validate(entry.schema, value, `setting "${key}"`)).andThen((output) => call(fn, {
-		...args,
-		key,
-		value: { value: output ?? null }
-	}, () => output));
-}
-function remover(entries, call, fn, args, key) {
-	if (!(key in entries)) return unknownSetting(key);
-	return call(fn, {
-		...args,
-		key
-	}, (removed) => removed === true);
-}
-function userScope(entries, call) {
-	function get(key) {
-		return reader(entries, call, "get_user_settings", {}, key);
-	}
-	return {
-		get,
-		set: (key, value) => writer(entries, call, "set_user_setting", {}, key, value),
-		reset: (key) => remover(entries, call, "reset_user_setting", {}, key)
-	};
-}
-function organizationScope(entries, call) {
-	function get(organizationId, key) {
-		return reader(entries, call, "get_organization_settings", { tenant: organizationId }, key);
-	}
-	return {
-		get,
-		set: (organizationId, key, value) => writer(entries, call, "set_organization_setting", { tenant: organizationId }, key, value),
-		reset: (organizationId, key) => remover(entries, call, "reset_organization_setting", { tenant: organizationId }, key)
-	};
-}
-function platformScope(entries, call) {
-	function get(key) {
-		return reader(entries, call, "get_platform_settings", {}, key);
-	}
-	return {
-		get,
-		set: (key, value) => writer(entries, call, "set_platform_setting", {}, key, value),
-		reset: (key) => remover(entries, call, "reset_platform_setting", {}, key)
-	};
-}
+const settingsBlock = defineBlock({
+	name: "settings",
+	sql: ["settings"],
+	options: { settings: settingsSqlOptions },
+	events: settingsEvents,
+	create: createSettings,
+	category: "tenancy",
+	recipes: ["settings-layout"]
+});
 //#endregion
-export { dbTransport, defineSettings, rpcTransport, sqlTransport };
+export { createSettings, createSettingsController, dbTransport, defineSettings, rpcTransport, settingFields, settingsBlock, settingsEvents, sqlTransport };

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

@@ -0,0 +1,25 @@
+import { l as SettingEntries, m as SettingsDefinition, n as SettingKind, o as SettingsSnapshot, r as SettingsActions, t as SettingField } from "../../../client-DAHsEOVV.js";
+//#region src/blocks/settings/react/index.d.ts
+export interface UseSettingsOptions<S extends "user" | "organization"> {
+  /** Which part of the definition the page edits. */
+  readonly scope: S;
+  /** The organization, for `scope: "organization"`; the page waits without one. */
+  readonly organizationId?: string | null;
+  /** The schema the calls go to: the module schema (default `better_supabase`), or the API schema from `blocks.<module>.api`. */
+  readonly schema?: string;
+}
+export interface SettingsState<E extends SettingEntries> extends SettingsSnapshot<E>, SettingsActions<E> {}
+/**
+ * One scope of a `defineSettings()` definition for a settings page,
+ * through the browser client: `fields` to render, generated from the
+ * definition, the stored `values`, and `set` and `reset` per key. The same
+ * hook runs in React DOM and React Native.
+ *
+ * ```tsx
+ * const { fields, values, set } = useSettings(settings, { scope: "organization", organizationId });
+ * ```
+ */
+export declare function useSettings<U extends SettingEntries, O extends SettingEntries, P extends SettingEntries>(settings: SettingsDefinition<U, O, P>, options: UseSettingsOptions<"user">): SettingsState<U>;
+export declare function useSettings<U extends SettingEntries, O extends SettingEntries, P extends SettingEntries>(settings: SettingsDefinition<U, O, P>, options: UseSettingsOptions<"organization">): SettingsState<O>;
+//#endregion
+export type { SettingField, SettingKind };

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

@@ -0,0 +1,37 @@
+"use client";
+import { r as rpcTransport } from "../../../block-transport-G4t1umrR.js";
+import { t as useController } from "../../../react-controller-Xn-IU44p.js";
+import { t as useBlockEnv } from "../../../react-env-Cc7Vf6eb.js";
+import { t as createSettings } from "../../../settings-BXFn9zpS.js";
+import { t as createSettingsController } from "../../../client-01MAuqzW.js";
+//#region src/blocks/settings/react/index.ts
+function useSettings(settings, options) {
+	const { supabase, auth } = useBlockEnv();
+	const { scope, organizationId, schema } = options;
+	return useController(() => {
+		const client = createSettings({
+			settings,
+			transport: rpcTransport(supabase),
+			...schema === void 0 ? {} : { schema }
+		});
+		return scope === "user" ? createSettingsController({
+			entries: settings.schemas.user,
+			auth,
+			user: client
+		}) : createSettingsController({
+			entries: settings.schemas.organization,
+			auth,
+			organization: client,
+			organizationId: organizationId ?? null
+		});
+	}, [
+		settings,
+		supabase,
+		auth,
+		scope,
+		organizationId,
+		schema
+	]).view;
+}
+//#endregion
+export { useSettings };

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

@@ -0,0 +1,7 @@
+import { n as SettingKind, t as SettingField } from "../../../client-DAHsEOVV.js";
+import { SettingsState, UseSettingsOptions, useSettings as useSettings$1 } from "./index.js";
+//#region src/blocks/settings/react/server.d.ts
+/** The `react-server` build of `useSettings`: call `createSettings(...).getUser()` instead. */
+export declare const useSettings: typeof useSettings$1;
+//#endregion
+export type { SettingField, SettingKind, SettingsState, UseSettingsOptions };

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

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

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

@@ -0,0 +1,13 @@
+import { t as BlockOptions } from "../../../block-env-Dxl7rsI0.js";
+import { t as SolidController } from "../../../solid-controller-DqlvYFZa.js";
+import { a as SettingsControllerOptions, l as SettingEntries, o as SettingsSnapshot, r as SettingsActions } from "../../../client-DAHsEOVV.js";
+//#region src/blocks/settings/solid/index.d.ts
+/**
+ * `createSettingsController` 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 useSettings<E extends SettingEntries>(options: BlockOptions<SettingsControllerOptions<E>>): SolidController<SettingsSnapshot<E>, SettingsActions<E>>;
+//#endregion
+export type { BlockOptions, SettingEntries, SettingsActions, SettingsControllerOptions, SettingsSnapshot, SolidController };

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

@@ -0,0 +1,14 @@
+import { t as useBlockController } from "../../../solid-controller-DLsmrczT.js";
+import { t as createSettingsController } from "../../../client-01MAuqzW.js";
+//#region src/blocks/settings/solid/index.ts
+/**
+* `createSettingsController` 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 useSettings(options) {
+	return useBlockController(createSettingsController, options);
+}
+//#endregion
+export { useSettings };

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

@@ -0,0 +1,13 @@
+import { t as BlockOptions } from "../../../block-env-Dxl7rsI0.js";
+import { t as SvelteController } from "../../../svelte-controller-DxxHEHxD.js";
+import { a as SettingsControllerOptions, l as SettingEntries, o as SettingsSnapshot, r as SettingsActions } from "../../../client-DAHsEOVV.js";
+//#region src/blocks/settings/svelte/index.d.ts
+/**
+ * `createSettingsController` 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 useSettings<E extends SettingEntries>(options: BlockOptions<SettingsControllerOptions<E>>): SvelteController<SettingsSnapshot<E>, SettingsActions<E>>;
+//#endregion
+export type { BlockOptions, SettingEntries, SettingsActions, SettingsControllerOptions, SettingsSnapshot, SvelteController };

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

@@ -0,0 +1,14 @@
+import { t as useBlockController } from "../../../svelte-controller-CDAujo-_.js";
+import { t as createSettingsController } from "../../../client-01MAuqzW.js";
+//#region src/blocks/settings/svelte/index.ts
+/**
+* `createSettingsController` 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 useSettings(options) {
+	return useBlockController(createSettingsController, options);
+}
+//#endregion
+export { useSettings };

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

@@ -0,0 +1,13 @@
+import { t as BlockOptions } from "../../../block-env-Dxl7rsI0.js";
+import { t as VueController } from "../../../vue-controller-HPfMTDa2.js";
+import { a as SettingsControllerOptions, l as SettingEntries, o as SettingsSnapshot, r as SettingsActions } from "../../../client-DAHsEOVV.js";
+//#region src/blocks/settings/vue/index.d.ts
+/**
+ * `createSettingsController` 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 useSettings<E extends SettingEntries>(options: BlockOptions<SettingsControllerOptions<E>>): VueController<SettingsSnapshot<E>, SettingsActions<E>>;
+//#endregion
+export type { BlockOptions, SettingEntries, SettingsActions, SettingsControllerOptions, SettingsSnapshot, VueController };

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

@@ -0,0 +1,14 @@
+import { t as useBlockController } from "../../../vue-controller-C9tFzqAc.js";
+import { t as createSettingsController } from "../../../client-01MAuqzW.js";
+//#region src/blocks/settings/vue/index.ts
+/**
+* `createSettingsController` 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 useSettings(options) {
+	return useBlockController(createSettingsController, options);
+}
+//#endregion
+export { useSettings };

package/dist/blocks/share-links/index.d.ts

@@ -0,0 +1,99 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult } from "../../result-Cj3yWhjH.js";
+import { $ as SaasEventData, et as SaasSubjectEventData, 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/share-links/share-links.d.ts
+interface ShareLinksOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockOptions {
+  /**
+   * A Standard Schema for the link's extra columns
+   * (`blocks.share-links.options.extraColumns`), keyed by database name. It
+   * types and parses them on `create` and `list`, and validates them on
+   * `create`.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<ShareLinks<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+interface CreatedShareLink<F extends object = Record<never, never>> {
+  readonly id: string;
+  /** Returned once. Later calls only see the hash. */
+  readonly token: string;
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
+}
+/** A link `list` returns. The token is never returned again. */
+interface ShareLink<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly role: string;
+  readonly expiresAt: Temporal.Instant | null;
+  readonly revokedAt: Temporal.Instant | null;
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
+}
+interface CreateShareLinkOptions<F extends object = Record<never, never>> {
+  /** The link's extra columns. */
+  readonly fields?: Partial<F>;
+  /** `view` unless set. */
+  readonly role?: string;
+  /**
+   * Pins the link to one of the subject's versions (the versions module),
+   * which `versions.getShared(token)` reads for anon.
+   */
+  readonly versionId?: string;
+  /**
+   * When the link stops resolving. It must be in the future
+   * (`SHARE_EXPIRY_INVALID`); without it the link lives until revoked.
+   */
+  readonly expiresAt?: Temporal.Instant;
+}
+/** What a live token points at. */
+interface ResolvedShareLink {
+  readonly id: string;
+  /** The organization the link was created in. */
+  readonly organizationId: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  readonly role: string;
+  /** The version the link is pinned to, when it has one. */
+  readonly versionId?: string;
+  /** When the link stops resolving, when it has an expiry. */
+  readonly expiresAt?: Temporal.Instant;
+}
+interface ShareLinks<F extends object = Record<never, never>> {
+  /** A role string is the same as `{ role }`. */
+  create(organizationId: string, subjectType: string, subjectId: string, options?: string | CreateShareLinkOptions<F>): AsyncResult<CreatedShareLink<F>>;
+  /** The link's creator, or a member with `share_links.create`. */
+  revoke(id: string): AsyncResult<boolean>;
+  /** `null` for an unknown, revoked or expired token. */
+  resolve(token: string): AsyncResult<ResolvedShareLink | null>;
+  /** A member of the organization records a view. */
+  recordView(organizationId: string, subjectType: string, subjectId: string, viewerKind: string, viewer?: string): AsyncResult<boolean>;
+  /** The links the caller created or may read (`share_links.read`), revoked ones included. */
+  list(subjectType: string, subjectId: string): AsyncResult<readonly ShareLink<F>[]>;
+  setState(subjectType: string, subjectId: string, starred: boolean): AsyncResult<boolean>;
+}
+/** The `share-links` SQL module as typed calls. */
+export declare function createShareLinks<S extends StandardSchemaV1 | undefined = undefined>(options: ShareLinksOptions<S>): ShareLinks<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/share-links/events.d.ts
+/** The events of the `share-links` block: type to data. */
+type ShareLinksEvents = {
+  readonly "share_link.created": SaasSubjectEventData;
+  readonly "share_link.revoked": SaasEventData;
+  readonly "subject.viewed": SaasSubjectEventData;
+};
+/** The `share-links` block's event types, for its manifest and `onBlockEvent`. */
+export declare const shareLinksEvents: Events<ShareLinksEvents>;
+//#endregion
+//#region src/blocks/share-links/manifest.d.ts
+/** The `share-links` block's manifest (ADR 0029). */
+export declare const shareLinksBlock: BlockOf<"share-links", typeof createShareLinks, ShareLinksEvents>;
+//#endregion
+export type { CreateShareLinkOptions, CreatedShareLink, ResolvedShareLink, ShareLink, ShareLinks, ShareLinksEvents, ShareLinksOptions };

package/dist/blocks/share-links/index.js

@@ -0,0 +1,99 @@
+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, S as optionalInstant, k as recordsOf, m as instantArg, n as applyTemporal, o as blockCall, v as nullableInstant } 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 shareLinksSqlOptions } from "../../options-CAzVf-1T.js";
+//#region src/blocks/share-links/share-links.ts
+const fieldsOf = (row) => isRecord(row["fields"]) ? row["fields"] : {};
+/** The `share-links` SQL module as typed calls. */
+function createShareLinks(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const fields = blockFields(options.fields, "share link fields");
+	return withBlockHooks({
+		create: (organizationId, subjectType, subjectId, link = {}) => {
+			const { role, versionId, expiresAt, fields: extra } = typeof link === "string" ? { role: link } : link;
+			return fields.args(extra).andThen((checked) => call("create_share_link", {
+				tenant: organizationId,
+				subject_type: subjectType,
+				subject_id: subjectId,
+				role: role ?? "view",
+				version_id: versionId ?? null,
+				expires_at: instantArg(expiresAt) ?? null,
+				fields: checked
+			}, (value) => {
+				const row = recordOf(value, "create_share_link");
+				return {
+					id: textOf(row["id"]),
+					token: textOf(row["token"]),
+					fields: fieldsOf(row)
+				};
+			}).andThen(fields.row));
+		},
+		revoke: (id) => call("revoke_share_link", { id }, (value) => value === true),
+		resolve: (token) => call("resolve_share_link", { token }, (value) => {
+			if (value === null || value === void 0) return null;
+			const row = recordOf(value, "resolve_share_link");
+			const versionId = optionalText(row["versionId"]);
+			const expiresAt = optionalInstant(row["expiresAt"]);
+			return {
+				id: textOf(row["id"]),
+				organizationId: textOf(row["organizationId"]),
+				subjectType: textOf(row["subjectType"]),
+				subjectId: textOf(row["subjectId"]),
+				role: textOf(row["role"]),
+				...versionId === void 0 ? {} : { versionId },
+				...expiresAt === void 0 ? {} : { expiresAt }
+			};
+		}),
+		recordView: (organizationId, subjectType, subjectId, viewerKind, viewer) => call("record_view", {
+			tenant: organizationId,
+			subject_type: subjectType,
+			subject_id: subjectId,
+			viewer_kind: viewerKind,
+			viewer: viewer ?? null
+		}, (value) => value === true),
+		list: (subjectType, subjectId) => call("list_share_links", {
+			subject_type: subjectType,
+			subject_id: subjectId
+		}, (value) => recordsOf(value, "list_share_links").map((row) => ({
+			id: textOf(row["id"]),
+			role: textOf(row["role"]),
+			expiresAt: nullableInstant(row["expiresAt"]),
+			revokedAt: nullableInstant(row["revokedAt"]),
+			fields: fieldsOf(row)
+		}))).andThen(fields.rows),
+		setState: (subjectType, subjectId, starred) => call("set_user_state", {
+			subject_type: subjectType,
+			subject_id: subjectId,
+			starred
+		}, (value) => value === true)
+	}, options.hooks, {
+		block: "share-links",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+//#region src/blocks/share-links/events.ts
+/** The `share-links` block's event types, for its manifest and `onBlockEvent`. */
+const shareLinksEvents = defineEvents({
+	"share_link.created": event(),
+	"share_link.revoked": event(),
+	"subject.viewed": event()
+});
+//#endregion
+//#region src/blocks/share-links/manifest.ts
+/** The `share-links` block's manifest (ADR 0029). */
+const shareLinksBlock = defineBlock({
+	name: "share-links",
+	sql: ["share-links"],
+	options: { "share-links": shareLinksSqlOptions },
+	events: shareLinksEvents,
+	create: createShareLinks,
+	category: "collaboration",
+	recipes: ["share-link-dialog"]
+});
+//#endregion
+export { createShareLinks, shareLinksBlock, shareLinksEvents };