better-supabase 0.13.0 → 0.14.0

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

@@ -1,12 +1,13 @@
 /// <reference lib="esnext.temporal" />
-import { t as AsyncResult } from "../../result-mijqfoJN.js";
-import { t as StandardSchemaV1 } from "../../standard-16AIDny5.js";
-import { n as ExtraFields, r as FieldsOf } from "../../block-fields-DnXkMney.js";
-import { $ as SaasEventData, et as SaasSubjectEventData, wt as Events } from "../../events-DhGgwqQA.js";
+import { t as AsyncResult } from "../../result-C6jDfedy.js";
+import { t as StandardSchemaV1 } from "../../standard-DbQsD2xZ.js";
+import { n as ExtraFields, r as FieldsOf } from "../../block-fields-3w4MZr8U.js";
+import { dt as SubjectRef } from "../../executor-CPyrQdjh.js";
+import { $ as SaasEventData, Ct as Events, et as SaasSubjectEventData } from "../../events-DbLjvxDX.js";
 import { n as Logger } from "../../logger-DWVYUmwi.js";
-import { n as BlockOptions } from "../../block-helpers-DyA5BAW4.js";
-import { n as BlockHooks } from "../../block-hooks-BadAniNI.js";
-import { s as BlockOf } from "../../define-block-MyM4lH42.js";
+import { n as BlockOptions } from "../../block-helpers-BaugZlJV.js";
+import { n as BlockHooks } from "../../block-hooks-CmjPKqQ_.js";
+import { Gt as SectionWrite, Lt as Section, Wt as SectionRowInput, c as BlockOf, rn as EntitySchema } from "../../define-block-COpcS6aT.js";
 //#region src/blocks/share-links/share-links.d.ts
 interface ShareLinksOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockOptions {
   /**
@@ -63,8 +64,7 @@ interface ResolvedShareLink {
   readonly id: string;
   /** The organization the link was created in. */
   readonly organizationId: string;
-  readonly subjectType: string;
-  readonly subjectId: string;
+  readonly subject: SubjectRef;
   readonly role: string;
   /** The version the link is pinned to, when it has one. */
   readonly versionId?: string;
@@ -73,9 +73,13 @@ interface ResolvedShareLink {
   /** How many times the link may be opened, when it has a limit. */
   readonly maxUses?: number;
 }
+/**
+ * `F` is the extra fields `options.fields` describes. `create` and `recordView`
+ * act in the block's `tenant`.
+ */
 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>>;
+  /** A link to `subject`. A role string is the same as `{ role }`. */
+  create(subject: SubjectRef, options?: string | CreateShareLinkOptions<F>): AsyncResult<CreatedShareLink<F>>;
   /** The link's creator, or a member with `share_links.create`. */
   revoke(id: string): AsyncResult<boolean>;
   /**
@@ -83,14 +87,15 @@ interface ShareLinks<F extends object = Record<never, never>> {
    * one use.
    */
   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>;
+  /** A member of the tenant records a view of `subject`. */
+  recordView(subject: SubjectRef, viewerKind: string, viewer?: string): AsyncResult<boolean>;
   /**
-   * The links the caller created or may read (`share_links.read`), revoked ones
-   * included.
+   * The links to `subject` 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>;
+  list(subject: SubjectRef): AsyncResult<readonly ShareLink<F>[]>;
+  /** Stars or unstars `subject` for the caller. */
+  setState(subject: SubjectRef, 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>>;
@@ -105,8 +110,32 @@ type ShareLinksEvents = {
 /** The `share-links` block's event types, for its manifest and `onBlockEvent`. */
 export declare const shareLinksEvents: Events<ShareLinksEvents>;
 //#endregion
+//#region src/blocks/share-links/section.d.ts
+/**
+ * What creating a share link from a record page takes. `expiresAt` is an ISO
+ * 8601 string, because a Server Action argument can't be a `Temporal.Instant`.
+ */
+interface ShareLinkInput {
+  readonly role?: string;
+  readonly expiresAt?: string;
+  readonly maxUses?: number;
+}
+/** The input schema of the share links section's `create`. */
+export declare const shareLinkInput: EntitySchema<ShareLinkInput>;
+/** The writes of the share links section. */
+type ShareLinksWrites = {
+  /** A new link to the record; its token is in the result, once. */
+  readonly create: SectionWrite<ShareLinks, ShareLinkInput, CreatedShareLink>;
+  /** Revokes one link; its creator or a member with `share_links.create`. */
+  readonly revoke: SectionWrite<ShareLinks, SectionRowInput, boolean>;
+};
+/** The share links to a record the caller created or may read. */
+export declare const shareLinksSection: Section<ShareLinks, readonly ShareLink[], never, never, ShareLinksWrites>;
+//#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>;
+export declare const shareLinksBlock: BlockOf<"share-links", typeof createShareLinks, ShareLinksEvents, Record<never, never>, never, {
+  readonly shareLinks: typeof shareLinksSection;
+}>;
 //#endregion
-export type { CreateShareLinkOptions, CreatedShareLink, ResolvedShareLink, ShareLink, ShareLinks, ShareLinksEvents, ShareLinksOptions };
+export type { CreateShareLinkOptions, CreatedShareLink, ResolvedShareLink, ShareLink, ShareLinkInput, ShareLinks, ShareLinksEvents, ShareLinksOptions, ShareLinksWrites };

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

@@ -1,10 +1,14 @@
 import { n as isRecord } from "../../guards-6F2bCtQR.js";
 import { t as shareLinksSqlOptions } from "../../options-CAzVf-1T.js";
+import { C as optionalText, D as recordOf, I as textOf, R as toInstant, S as optionalInstant, k as recordsOf, m as instantArg, n as applyTemporal, o as blockCall, v as nullableInstant } from "../../block-helpers-CiKtrb6g.js";
+import { r as withBlockHooks } from "../../block-hooks-BymdcD0V.js";
+import { n as entitySchema } from "../../entity-schema-BXXC1NnT.js";
+import { r as sectionRowInput, t as defineSection } from "../../sections-DjxYmpu-.js";
 import { n as event, t as defineEvents } from "../../event-map-CtPFhcOp.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-DwE32_gT.js";
-import { r as withBlockHooks } from "../../block-hooks-C1r-R2r0.js";
-import { n as blockFields } from "../../block-fields-Cwd4c8m-.js";
-import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
+import { n as blockFields } from "../../block-fields-DBSJSeaO.js";
+import { n as defineBlock } from "../../define-block-Dze77QTw.js";
+import { i as subjectRefOf } from "../../block-subjects-Dzq5Xn_0.js";
+import { t as requireTenant } from "../../block-tenant-C1sNV8_4.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. */
@@ -12,13 +16,14 @@ function createShareLinks(options) {
 	applyTemporal(options);
 	const call = blockCall(options.transport, options.schema, options.mappers);
 	const fields = blockFields(options.fields, "share link fields");
+	const tenant = () => requireTenant(options.tenant);
 	return withBlockHooks({
-		create: (organizationId, subjectType, subjectId, link = {}) => {
+		create: (subject, link = {}) => {
 			const { role, versionId, expiresAt, maxUses, fields: extra } = typeof link === "string" ? { role: link } : link;
-			return fields.args(extra).andThen((checked) => call("create_share_link", {
+			return tenant().andThen((organizationId) => fields.args(extra).andThen((checked) => call("create_share_link", {
 				tenant: organizationId,
-				subject_type: subjectType,
-				subject_id: subjectId,
+				subject_type: subject.type,
+				subject_id: subject.id,
 				role: role ?? "view",
 				version_id: versionId ?? null,
 				expires_at: instantArg(expiresAt) ?? null,
@@ -31,7 +36,7 @@ function createShareLinks(options) {
 					token: textOf(row["token"]),
 					fields: fieldsOf(row)
 				};
-			}).andThen(fields.row));
+			}).andThen(fields.row)));
 		},
 		revoke: (id) => call("revoke_share_link", { id }, (value) => value === true),
 		resolve: (token) => call("resolve_share_link", { token }, (value) => {
@@ -43,24 +48,23 @@ function createShareLinks(options) {
 			return {
 				id: textOf(row["id"]),
 				organizationId: textOf(row["organizationId"]),
-				subjectType: textOf(row["subjectType"]),
-				subjectId: textOf(row["subjectId"]),
+				subject: subjectRefOf(row["subjectType"], row["subjectId"]),
 				role: textOf(row["role"]),
 				...versionId === void 0 ? {} : { versionId },
 				...expiresAt === void 0 ? {} : { expiresAt },
 				...maxUses === void 0 ? {} : { maxUses }
 			};
 		}),
-		recordView: (organizationId, subjectType, subjectId, viewerKind, viewer) => call("record_view", {
+		recordView: (subject, viewerKind, viewer) => tenant().andThen((organizationId) => call("record_view", {
 			tenant: organizationId,
-			subject_type: subjectType,
-			subject_id: subjectId,
+			subject_type: subject.type,
+			subject_id: subject.id,
 			viewer_kind: viewerKind,
 			viewer: viewer ?? null
-		}, (value) => value === true),
-		list: (subjectType, subjectId) => call("list_share_links", {
-			subject_type: subjectType,
-			subject_id: subjectId
+		}, (value) => value === true)),
+		list: (subject) => call("list_share_links", {
+			subject_type: subject.type,
+			subject_id: subject.id
 		}, (value) => recordsOf(value, "list_share_links").map((row) => ({
 			id: textOf(row["id"]),
 			role: textOf(row["role"]),
@@ -68,9 +72,9 @@ function createShareLinks(options) {
 			revokedAt: nullableInstant(row["revokedAt"]),
 			fields: fieldsOf(row)
 		}))).andThen(fields.rows),
-		setState: (subjectType, subjectId, starred) => call("set_user_state", {
-			subject_type: subjectType,
-			subject_id: subjectId,
+		setState: (subject, starred) => call("set_user_state", {
+			subject_type: subject.type,
+			subject_id: subject.id,
 			starred
 		}, (value) => value === true)
 	}, options.hooks, {
@@ -87,6 +91,52 @@ const shareLinksEvents = defineEvents({
 	"subject.viewed": event()
 });
 //#endregion
+//#region src/blocks/share-links/section.ts
+/** The input schema of the share links section's `create`. */
+const shareLinkInput = entitySchema({
+	title: "ShareLinkInput",
+	fields: {
+		role: {
+			kind: "string",
+			optional: true,
+			minLength: 1
+		},
+		expiresAt: {
+			kind: "datetime",
+			optional: true
+		},
+		maxUses: {
+			kind: "integer",
+			optional: true,
+			minimum: 1
+		}
+	}
+});
+/** The share links to a record the caller created or may read. */
+const shareLinksSection = defineSection({
+	permissions: {
+		read: "read",
+		write: "create"
+	},
+	module: "share-links",
+	load: (client, subject) => client.list(subject),
+	events: ["share_link.*"],
+	writes: {
+		create: {
+			input: shareLinkInput,
+			run: (client, subject, input) => client.create(subject, {
+				...input.role === void 0 ? {} : { role: input.role },
+				...input.maxUses === void 0 ? {} : { maxUses: input.maxUses },
+				...input.expiresAt === void 0 ? {} : { expiresAt: toInstant(input.expiresAt) }
+			})
+		},
+		revoke: {
+			input: sectionRowInput,
+			run: (client, _subject, { id }) => client.revoke(id)
+		}
+	}
+});
+//#endregion
 //#region src/blocks/share-links/manifest.ts
 /** The `share-links` block's manifest (ADR 0029). */
 const shareLinksBlock = defineBlock({
@@ -95,8 +145,9 @@ const shareLinksBlock = defineBlock({
 	options: { "share-links": shareLinksSqlOptions },
 	events: shareLinksEvents,
 	create: createShareLinks,
+	sections: { shareLinks: shareLinksSection },
 	category: "collaboration",
 	recipes: ["share-link-dialog"]
 });
 //#endregion
-export { createShareLinks, shareLinksBlock, shareLinksEvents };
+export { createShareLinks, shareLinkInput, shareLinksBlock, shareLinksEvents, shareLinksSection };

package/dist/blocks/shared-signals/index.d.ts

@@ -1,14 +1,14 @@
 /// <reference lib="esnext.temporal" />
-import { t as AsyncResult } from "../../result-mijqfoJN.js";
-import { wt as Events } from "../../events-DhGgwqQA.js";
+import { t as AsyncResult } from "../../result-C6jDfedy.js";
+import { Ct as Events } from "../../events-DbLjvxDX.js";
 import { n as Logger } from "../../logger-DWVYUmwi.js";
-import { s as sqlTransport, t as BlockTransport } from "../../block-transport-DBPhgF3W.js";
-import { n as BlockOptions } from "../../block-helpers-DyA5BAW4.js";
-import { n as BlockHooks } from "../../block-hooks-BadAniNI.js";
-import { n as VaultCredentials } from "../../vault-BQThkbws.js";
-import { s as BlockOf } from "../../define-block-MyM4lH42.js";
+import { n as BlockOptions } from "../../block-helpers-BaugZlJV.js";
+import { s as sqlTransport, t as BlockTransport } from "../../block-transport-d53POsem.js";
+import { n as BlockHooks } from "../../block-hooks-CmjPKqQ_.js";
+import { n as VaultCredentials } from "../../vault-BQTdu4eH.js";
+import { c as BlockOf } from "../../define-block-COpcS6aT.js";
 import { n as Jwks } from "../../jws-D0toeQlA.js";
-import { o as Signer } from "../../signing-keys-i2Rsll6L.js";
+import { o as Signer } from "../../signing-keys-B3RHGMMu.js";
 //#region src/blocks/shared-signals/set.d.ts
 /** The `typ` header of a Security Event Token (RFC 8417 §2.3). */
 export declare const SET_TYP = "secevent+jwt";

package/dist/blocks/shared-signals/index.js

@@ -1,15 +1,14 @@
-import { n as dbError } from "../../errors-D7u24ZJH.js";
-import { a as ok, r as err, t as AsyncResult } from "../../result-DIT_qp4G.js";
+import { n as dbError } from "../../errors-03ysrOt4.js";
+import { a as ok, r as err, t as AsyncResult } from "../../result-B3m7xtRY.js";
 import { t as consoleLogger } from "../../logger-glM28NVN.js";
 import { n as isRecord } from "../../guards-6F2bCtQR.js";
-import { o as problemResponse } from "../../problem-D0KDiYPk.js";
+import { o as problemResponse } from "../../problem-BWElIgIb.js";
 import { n as SSF_PUSH, r as sharedSignalsSqlOptions, t as SSF_POLL } from "../../methods-7u6vSgz_.js";
+import { A as requiredInstant, D as recordOf, E as readBodyCapped, F as stringsOf, I as textOf, U as sqlTransport, f as errorText, k as recordsOf, n as applyTemporal, o as blockCall, y as nullableText } from "../../block-helpers-CiKtrb6g.js";
+import { r as withBlockHooks } from "../../block-hooks-BymdcD0V.js";
 import { n as event, t as defineEvents } from "../../event-map-CtPFhcOp.js";
-import { i as sqlTransport } from "../../block-transport-Ds0C2mUf.js";
-import { A as requiredInstant, D as recordOf, E as readBodyCapped, F as stringsOf, I as textOf, f as errorText, k as recordsOf, n as applyTemporal, o as blockCall, y as nullableText } from "../../block-helpers-DwE32_gT.js";
 import { a as jwksOf, c as verifyCompact, t as JwsError } from "../../jws-DOgHJKHb.js";
-import { r as withBlockHooks } from "../../block-hooks-C1r-R2r0.js";
-import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
+import { n as defineBlock } from "../../define-block-Dze77QTw.js";
 //#region src/blocks/shared-signals/set.ts
 /** The `typ` header of a Security Event Token (RFC 8417 §2.3). */
 const SET_TYP = "secevent+jwt";

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

@@ -0,0 +1,238 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult } from "../../result-C6jDfedy.js";
+import { t as StandardSchemaV1 } from "../../standard-DbQsD2xZ.js";
+import { n as ExtraFields, r as FieldsOf } from "../../block-fields-3w4MZr8U.js";
+import { dt as SubjectRef } from "../../executor-CPyrQdjh.js";
+import { Ct as Events } from "../../events-DbLjvxDX.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { n as BlockOptions } from "../../block-helpers-BaugZlJV.js";
+import { a as dbTransport, i as RpcClient, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-d53POsem.js";
+import { a as BlockTransportMiddleware, d as extendBlock, f as withBlockHooks, n as BlockHooks, p as wrapTransport } from "../../block-hooks-CmjPKqQ_.js";
+import { n as shipmentsSqlOptions, t as ShipmentsSqlOptions } from "../../options-DZupPoI0.js";
+import { Gt as SectionWrite, Lt as Section, Wt as SectionRowInput, c as BlockOf, rn as EntitySchema } from "../../define-block-COpcS6aT.js";
+import { n as Money } from "../../money-BNRdJQzA.js";
+import { r as WebhookInput } from "../../signatures-zbu6KTNQ.js";
+import { C as TrackingStatus, S as TRACKING_STATUSES, _ as trackingUpdatesOf, a as FlatRateCarrierOptions, b as SHIPMENT_STATUSES, c as ShipmentCarrier, d as ShipmentParcel, f as ShipmentRate, g as shipmentCarrierOf, h as invalidShipmentRequest, i as CarrierTrackingUpdate, l as ShipmentLabel, m as flatRateCarrier, n as CarrierCancelInput, o as FlatRateService, p as ShipmentRateRequest, r as CarrierTrackingEvent, s as ShipmentAddress, t as CarrierCallOptions, u as ShipmentLabelRequest, v as LABEL_FORMATS, x as ShipmentStatus, y as LabelFormat } from "../../carrier-C7Q_21Kd.js";
+//#region src/blocks/shipments/shipments.d.ts
+interface ShipmentsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockOptions {
+  /**
+   * A Standard Schema for the shipments' extra columns
+   * (`blocks.shipments.options.extraColumns`), keyed by database name.
+   */
+  readonly fields?: S;
+  /**
+   * The carriers that quote, label and track, by `name`. Without one the block
+   * still records shipments and tracking events by hand.
+   */
+  readonly carriers?: readonly ShipmentCarrier[];
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Shipments<FieldsOf<S>>>>;
+  /**
+   * Receives the errors `after` hooks throw and a label the block failed to
+   * void. Default: `console`.
+   */
+  readonly logger?: Logger;
+}
+interface ShipmentPackage {
+  readonly id: string;
+  /** From 1. */
+  readonly position: number;
+  readonly weightGrams: number;
+  readonly lengthMm?: number;
+  readonly widthMm?: number;
+  readonly heightMm?: number;
+  readonly reference?: string;
+}
+/** A shipment: its packages, its addresses and, once bought, its label. */
+interface Shipment<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly reference: string;
+  /** `draft` until labeled, then the latest tracking event's status. */
+  readonly status: ShipmentStatus;
+  readonly from: ShipmentAddress;
+  readonly to: ShipmentAddress;
+  /** The assets location it ships from. */
+  readonly fromLocationId?: string;
+  readonly subject?: SubjectRef;
+  readonly carrier?: string;
+  readonly service?: string;
+  readonly trackingNumber?: string;
+  readonly trackingUrl?: string;
+  readonly labelId?: string;
+  readonly labelUrl?: string;
+  readonly labelFormat?: LabelFormat;
+  readonly labelCost?: Money;
+  readonly labeledAt?: Temporal.Instant;
+  readonly deliveredAt?: Temporal.Instant;
+  readonly cancelledAt?: Temporal.Instant;
+  readonly createdBy?: string;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+  readonly packages: readonly ShipmentPackage[];
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
+}
+interface ShipmentInput<F extends object = Record<never, never>> {
+  readonly from: ShipmentAddress;
+  readonly to: ShipmentAddress;
+  /** 1 to 50 packages. */
+  readonly packages: readonly ShipmentParcel[];
+  /** Defaults to a generated `SHP-…` code. */
+  readonly reference?: string;
+  /** Needs the assets block. */
+  readonly fromLocationId?: string;
+  /** The record it ships for, such as an order. */
+  readonly subject?: SubjectRef;
+  readonly fields?: Partial<F>;
+}
+interface ShipmentListOptions {
+  readonly status?: ShipmentStatus;
+  readonly subject?: SubjectRef;
+  readonly carrier?: string;
+  /** Shipments created before this, for the next page. */
+  readonly before?: Temporal.Instant;
+  /** Default 50, at most 500. */
+  readonly limit?: number;
+}
+interface ShipmentLabelChoice {
+  /** A carrier's `name` from `options.carriers`. */
+  readonly carrier: string;
+  /** A service code the carrier quoted. */
+  readonly service: string;
+}
+/** One entry of a shipment's tracking timeline. */
+interface TrackingEvent {
+  readonly id: string;
+  /** The carrier's event id; `label:<labelId>` for the label itself. */
+  readonly externalId: string;
+  readonly status: TrackingStatus;
+  readonly occurredAt: Temporal.Instant;
+  readonly description?: string;
+  readonly location?: string;
+  readonly source: "carrier" | "webhook" | "manual";
+  readonly createdAt: Temporal.Instant;
+}
+interface TrackingRecorded<F extends object = Record<never, never>> {
+  /** The events that were new; repeats are skipped. */
+  readonly recorded: number;
+  readonly shipment: Shipment<F>;
+}
+/** What `ingest` did with one tracking number of a webhook. */
+interface TrackingIngested {
+  readonly trackingNumber: string;
+  /** Unset when no shipment has the tracking number. */
+  readonly shipmentId?: string;
+  readonly status?: ShipmentStatus;
+  readonly recorded: number;
+}
+/**
+ * Shipments with packages, carrier labels and a tracking timeline. `F` is the
+ * extra fields `options.fields` describes.
+ */
+interface Shipments<F extends object = Record<never, never>> {
+  /** Creates a draft shipment in the block's tenant. */
+  create(input: ShipmentInput<F>): AsyncResult<Shipment<F>>;
+  /** `null` when it doesn't exist or the caller can't read it. */
+  get(id: string): AsyncResult<Shipment<F> | null>;
+  list(options?: ShipmentListOptions): AsyncResult<readonly Shipment<F>[]>;
+  /** Every configured carrier's quotes, by currency and then cheapest first. */
+  rates(id: string, options?: {
+    readonly currency?: string;
+  }): AsyncResult<readonly ShipmentRate[]>;
+  /**
+   * Buys the label from the carrier and stores it on the draft shipment. The
+   * shipment id is the idempotency key, so a retry doesn't buy twice.
+   */
+  buyLabel(id: string, choice: ShipmentLabelChoice): AsyncResult<Shipment<F>>;
+  /** Pulls the carrier's tracking events and records the new ones. */
+  refresh(id: string): AsyncResult<TrackingRecorded<F>>;
+  /** Records tracking events by hand, such as a courier without an API. */
+  recordTracking(id: string, events: readonly CarrierTrackingEvent[]): AsyncResult<TrackingRecorded<F>>;
+  /**
+   * Verifies a carrier's tracking webhook and records its events on the
+   * shipments with those tracking numbers. Runs on `options.service`, since a
+   * webhook has no user; a redelivery records nothing twice.
+   */
+  ingest(carrier: string, request: WebhookInput): AsyncResult<readonly TrackingIngested[]>;
+  /**
+   * Cancels a shipment that hasn't shipped, voiding its label with the carrier
+   * first.
+   */
+  cancel(id: string): AsyncResult<Shipment<F>>;
+  /** The tracking timeline, oldest first. */
+  trackingEvents(id: string): AsyncResult<readonly TrackingEvent[]>;
+}
+/** The `shipments` SQL module and the configured carriers as typed calls. */
+export declare function createShipments<S extends StandardSchemaV1 | undefined = undefined>(options: ShipmentsOptions<S>): Shipments<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/shipments/events.d.ts
+/** `shipment.created`. */
+interface ShipmentCreatedEventData {
+  readonly organizationId: string;
+  /** The shipment. */
+  readonly id: string;
+  readonly reference: string;
+  readonly subjectType: string | null;
+  readonly subjectId: string | null;
+}
+/** `shipment.labeled`: a label was bought for it. */
+interface ShipmentLabeledEventData {
+  readonly organizationId: string;
+  readonly id: string;
+  readonly carrier: string;
+  readonly service: string;
+  readonly trackingNumber: string;
+}
+/** `shipment.status_changed`: its latest tracking event has another status. */
+interface ShipmentStatusChangedEventData {
+  readonly organizationId: string;
+  readonly id: string;
+  readonly from: string;
+  readonly to: string;
+  readonly trackingNumber: string | null;
+}
+/** `shipment.cancelled`. */
+interface ShipmentCancelledEventData {
+  readonly organizationId: string;
+  readonly id: string;
+  /** Set when the shipment had a label the carrier voided. */
+  readonly trackingNumber: string | null;
+}
+/** The events of the `shipments` block: type to data. */
+type ShipmentsEvents = {
+  readonly "shipment.created": ShipmentCreatedEventData;
+  readonly "shipment.labeled": ShipmentLabeledEventData;
+  readonly "shipment.status_changed": ShipmentStatusChangedEventData;
+  readonly "shipment.cancelled": ShipmentCancelledEventData;
+};
+/** The `shipments` block's event types, for its manifest and `onBlockEvent`. */
+export declare const shipmentsEvents: Events<ShipmentsEvents>;
+//#endregion
+//#region src/blocks/shipments/schemas.d.ts
+/** What `create` takes, with the bounds the SQL checks. */
+export declare const shipmentInputSchema: EntitySchema<ShipmentInput>;
+/** What the section's `create` write takes: the record is the subject. */
+type ShipmentSectionInput = Omit<ShipmentInput, "subject" | "fields">;
+export declare const shipmentSectionInputSchema: EntitySchema<ShipmentSectionInput>;
+/** One event `recordTracking` takes. */
+export declare const trackingEventInputSchema: EntitySchema<CarrierTrackingEvent>;
+//#endregion
+//#region src/blocks/shipments/section.d.ts
+/** The writes of the shipments section. */
+type ShipmentsWrites = {
+  /** Creates a draft shipment for the record, such as an order's parcel. */
+  readonly create: SectionWrite<Shipments, ShipmentSectionInput, Shipment>;
+  /** Cancels one of the record's shipments that hasn't shipped. */
+  readonly cancel: SectionWrite<Shipments, SectionRowInput, Shipment>;
+};
+/** The shipments sent for a record, with their status and tracking. */
+export declare const shipmentsSection: Section<Shipments, readonly Shipment[], undefined, never, ShipmentsWrites>;
+//#endregion
+//#region src/blocks/shipments/manifest.d.ts
+/** The `shipments` block's manifest (ADR 0029). */
+export declare const shipmentsBlock: BlockOf<"shipments", typeof createShipments, ShipmentsEvents, Record<never, never>, never, {
+  readonly shipments: typeof shipmentsSection;
+}>;
+//#endregion
+export { type BlockHooks, type BlockTransport, type BlockTransportMiddleware, type CarrierCallOptions, type CarrierCancelInput, type CarrierTrackingEvent, type CarrierTrackingUpdate, type FlatRateCarrierOptions, type FlatRateService, LABEL_FORMATS, type LabelFormat, type RpcClient, SHIPMENT_STATUSES, type Shipment, type ShipmentAddress, type ShipmentCancelledEventData, type ShipmentCarrier, type ShipmentCreatedEventData, type ShipmentInput, type ShipmentLabel, type ShipmentLabelChoice, type ShipmentLabelRequest, type ShipmentLabeledEventData, type ShipmentListOptions, type ShipmentPackage, type ShipmentParcel, type ShipmentRate, type ShipmentRateRequest, type ShipmentSectionInput, type ShipmentStatus, type ShipmentStatusChangedEventData, type Shipments, type ShipmentsEvents, type ShipmentsOptions, type ShipmentsSqlOptions, type ShipmentsWrites, TRACKING_STATUSES, type TrackingEvent, type TrackingIngested, type TrackingRecorded, type TrackingStatus, dbTransport, extendBlock, flatRateCarrier, invalidShipmentRequest, rpcTransport, shipmentCarrierOf, shipmentsSqlOptions, sqlTransport, trackingUpdatesOf, withBlockHooks, wrapTransport };