better-supabase 0.8.0 → 0.10.0

package/dist/blocks/time-tracking/index.d.ts

@@ -0,0 +1,250 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "../../result-Cj3yWhjH.js";
+import { ft as TimeEntryEventData, pt as TimesheetEventData, wt as Events } from "../../events-CtAHxPal.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-NbUJygA7.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-7pMBVsE6.js";
+import { n as BlockHooks } from "../../block-hooks-C_WaodoA.js";
+import { n as ExtraFields, r as FieldsOf } from "../../block-fields-5UA84ZUg.js";
+import { t as CloudEvent } from "../../cloud-event-bwsBwVNG.js";
+import { s as BlockOf } from "../../define-block-BlHQxDIQ.js";
+import { n as Money } from "../../money-DFpWzQvk.js";
+import { n as MetricDefinition } from "../../metric-definition-95HFoW1V.js";
+//#region src/blocks/time-tracking/time-tracking.d.ts
+interface TimeTrackingOptions<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 entry's extra columns
+   * (`blocks.time-tracking.options.extraColumns`), keyed by database name.
+   * It types and parses them on reads, and validates them on `start`, `log`
+   * and `update`.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<TimeTracking<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  readonly mappers?: readonly ErrorMapper[];
+}
+/** A time entry. `F` types the extra columns the `fields` schema describes. */
+interface TimeEntry<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly userId: string;
+  readonly subjectType?: string;
+  readonly subjectId?: string;
+  readonly startedAt: Temporal.Instant;
+  /** Missing while the timer runs. */
+  readonly endedAt?: Temporal.Instant;
+  /** Missing while the timer runs. */
+  readonly seconds?: number;
+  readonly billable: boolean;
+  /** The hourly rate, in minor units of its currency. */
+  readonly rate?: Money;
+  readonly note?: string;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
+}
+/** The record time is tracked on, how it bills, and the extra columns. */
+interface TimeEntryFields<F extends object = Record<never, never>> {
+  readonly subjectType?: string;
+  readonly subjectId?: string;
+  readonly billable?: boolean;
+  /** The hourly rate, in minor units of its currency. */
+  readonly rate?: Money;
+  readonly note?: string;
+  /** The extra columns to set. */
+  readonly fields?: Partial<F>;
+}
+interface LogTimeInput<F extends object = Record<never, never>> extends TimeEntryFields<F> {
+  readonly startedAt: Temporal.Instant;
+  readonly endedAt: Temporal.Instant;
+  /** Another member; needs `time_tracking.manage`. Default: the caller. */
+  readonly userId?: string;
+}
+/** The fields to change. `null` clears the subject, rate or note. */
+interface TimeEntryPatch<F extends object = Record<never, never>> {
+  readonly startedAt?: Temporal.Instant;
+  readonly endedAt?: Temporal.Instant;
+  readonly subject?: {
+    readonly subjectType: string;
+    readonly subjectId: string;
+  } | null;
+  readonly billable?: boolean;
+  readonly rate?: Money | null;
+  readonly note?: string | null;
+  /** The extra columns to set. */
+  readonly fields?: Partial<F>;
+}
+interface TimeEntryListOptions {
+  /** Another member's entries; needs `time_tracking.read`. Default: the caller. */
+  readonly userId?: string;
+  /** Every member's entries; needs `time_tracking.read`. */
+  readonly everyone?: boolean;
+  /** Entries that end after this instant. */
+  readonly from?: Temporal.Instant;
+  /** Entries that start before this instant. */
+  readonly to?: Temporal.Instant;
+  readonly subjectType?: string;
+  readonly subjectId?: string;
+  readonly pageSize?: number;
+}
+type TimesheetStatus = "open" | "submitted" | "approved" | "rejected";
+interface Timesheet {
+  /** Missing for a week that was never submitted. */
+  readonly id?: string;
+  readonly organizationId: string;
+  readonly userId: string;
+  /** The Monday the week starts on. */
+  readonly week: Temporal.PlainDate;
+  readonly status: TimesheetStatus;
+  readonly approvalId?: string;
+  readonly note?: string;
+  readonly submittedAt?: Temporal.Instant;
+  readonly approvedAt?: Temporal.Instant;
+}
+interface TimesheetTotals {
+  /** Every entry, running ones up to now. */
+  readonly seconds: number;
+  readonly billableSeconds: number;
+  /**
+   * Billable hours times their rate, rounded to minor units: one amount per
+   * currency, ordered by currency code.
+   */
+  readonly amounts: readonly Money[];
+}
+interface TimesheetDetail<F extends object = Record<never, never>> extends Timesheet {
+  /** The entries that start in the week, oldest first. */
+  readonly entries: readonly TimeEntry<F>[];
+  readonly totals: TimesheetTotals;
+}
+interface TimesheetListOptions {
+  /** Another member's timesheets; needs `time_tracking.read`. */
+  readonly userId?: string;
+  readonly status?: TimesheetStatus;
+  readonly pageSize?: number;
+  /** Weeks before this one, for the next page. */
+  readonly before?: Temporal.PlainDate;
+}
+interface TimeTracking<F extends object = Record<never, never>> {
+  /** Starts a timer for the caller and stops the one that runs. */
+  start(organizationId: string, fields?: TimeEntryFields<F>): AsyncResult<TimeEntry<F>>;
+  stop(organizationId: string): AsyncResult<TimeEntry<F>>;
+  /** The caller's running timer. */
+  running(organizationId: string): AsyncResult<TimeEntry<F> | undefined>;
+  log(organizationId: string, input: LogTimeInput<F>): AsyncResult<TimeEntry<F>>;
+  update(entryId: string, patch: TimeEntryPatch<F>): AsyncResult<TimeEntry<F>>;
+  remove(entryId: string): AsyncResult<TimeEntry<F>>;
+  /** Newest first. */
+  list(organizationId: string, options?: TimeEntryListOptions): AsyncResult<readonly TimeEntry<F>[]>;
+  /** A member's week (the caller's by default) with its entries and totals. */
+  timesheet(organizationId: string, week: Temporal.PlainDate, userId?: string): AsyncResult<TimesheetDetail<F>>;
+  /** Sends the caller's week for approval; it locks until a rejection. */
+  submit(organizationId: string, week: Temporal.PlainDate, note?: string): AsyncResult<Timesheet>;
+  /** Unlocks an approved week; needs `time_tracking.manage`. */
+  reopen(timesheetId: string): AsyncResult<Timesheet>;
+  /** Newest week first. */
+  timesheets(organizationId: string, options?: TimesheetListOptions): AsyncResult<readonly Timesheet[]>;
+}
+/** The `time-tracking` SQL module as typed calls. */
+export declare function createTimeTracking<S extends StandardSchemaV1 | undefined = undefined>(options: TimeTrackingOptions<S>): TimeTracking<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/time-tracking/metrics.d.ts
+interface TimeTrackingMetricsOptions {
+  /** The time-tracking module's schema. Default `better_supabase`. */
+  readonly schema?: string;
+  /** The IANA time zone buckets start in. Default `UTC`. */
+  readonly tz?: string;
+}
+type TimeTrackingMetrics = readonly [MetricDefinition<"time_tracked", "billable" | "user_id" | "subject_type">];
+/**
+ * A metric over finished time entries: the seconds tracked per day the entry
+ * started, which a series can filter or group by `billable`, `user_id` and
+ * `subject_type`. Running timers count once they stop.
+ */
+export declare function timeTrackingMetrics(options?: TimeTrackingMetricsOptions): TimeTrackingMetrics;
+/** The events that change `timeTrackingMetrics`, for `metricsSink` or `createBlocks({ metricEvents })`. */
+export declare const TIME_TRACKING_METRIC_EVENTS: {
+  readonly "time_entry.recorded": readonly ["time_tracked"];
+  readonly "time_entry.updated": readonly ["time_tracked"];
+  readonly "time_entry.deleted": readonly ["time_tracked"];
+};
+/**
+ * The entry's `startedAt`, the time its seconds are bucketed by, for
+ * `metricsSink({ time })` or `createBlocks({ metricTime })`. An update that
+ * moves the entry to another day also returns its `previousStartedAt`, so
+ * the old day's total drops. Undefined for other events, so they keep
+ * their own time.
+ */
+export declare function timeEntryMetricTime(event: CloudEvent): string | readonly string[] | undefined;
+//#endregion
+//#region src/blocks/time-tracking/weekly-grid.d.ts
+/** The fields `toWeeklyGrid` reads from an entry. */
+type WeeklyGridEntry = Pick<TimeEntry, "id" | "subjectType" | "subjectId" | "startedAt" | "endedAt" | "billable">;
+interface WeeklyGridOptions<E extends WeeklyGridEntry> {
+  /** Any day of the week; the grid starts on its Monday. */
+  readonly week: Temporal.PlainDate;
+  /** The IANA zone days start in: `blockConfig["time-tracking"].options.timeZone` from `blocks.generated.ts`. */
+  readonly timeZone: string;
+  /** Where a running entry ends. Default: now. */
+  readonly now?: Temporal.Instant;
+  /** The row an entry adds to. Default: its subject and whether it bills. */
+  readonly rowKey?: (entry: E) => string;
+}
+/** One day column, Monday first. */
+interface WeeklyGridDay {
+  /** `YYYY-MM-DD`, for a column id or accessor. */
+  readonly id: string;
+  readonly date: Temporal.PlainDate;
+  /** Seconds tracked that day across every row. */
+  readonly seconds: number;
+}
+/** One row of the grid: the time one record (or key) took each day. */
+interface WeeklyGridRow {
+  readonly id: string;
+  readonly subjectType?: string;
+  readonly subjectId?: string;
+  readonly billable: boolean;
+  /** Seconds per day, Monday first. */
+  readonly days: readonly number[];
+  readonly seconds: number;
+  readonly entryIds: readonly string[];
+}
+/** A week of entries as rows and day columns. */
+interface WeeklyGrid {
+  readonly days: readonly WeeklyGridDay[];
+  readonly rows: readonly WeeklyGridRow[];
+  readonly seconds: number;
+  readonly billableSeconds: number;
+}
+/**
+ * Time entries as a weekly grid: one row per record (or `rowKey`) with the
+ * seconds of each day, the shape of a weekly timesheet Data Grid. An entry
+ * that crosses midnight counts on each day it covers.
+ */
+export declare function toWeeklyGrid<E extends WeeklyGridEntry>(entries: readonly E[], options: WeeklyGridOptions<E>): WeeklyGrid;
+//#endregion
+//#region src/blocks/time-tracking/events.d.ts
+/** The events of the `time-tracking` block: type to data. */
+type TimeTrackingEvents = {
+  readonly "time_entry.started": TimeEntryEventData;
+  readonly "time_entry.recorded": TimeEntryEventData;
+  readonly "time_entry.updated": TimeEntryEventData;
+  readonly "time_entry.deleted": TimeEntryEventData;
+  readonly "timesheet.submitted": TimesheetEventData;
+  readonly "timesheet.approved": TimesheetEventData;
+  readonly "timesheet.reopened": TimesheetEventData;
+};
+/** The `time-tracking` block's event types, for its manifest and `onBlockEvent`. */
+export declare const timeTrackingEvents: Events<TimeTrackingEvents>;
+//#endregion
+//#region src/blocks/time-tracking/manifest.d.ts
+/** The `time-tracking` block's manifest (ADR 0029). */
+export declare const timeTrackingBlock: BlockOf<"time-tracking", typeof createTimeTracking, TimeTrackingEvents>;
+//#endregion
+export { type BlockTransport, type LogTimeInput, type TimeEntry, type TimeEntryFields, type TimeEntryListOptions, type TimeEntryPatch, type TimeTracking, type TimeTrackingEvents, type TimeTrackingMetrics, type TimeTrackingMetricsOptions, type TimeTrackingOptions, type Timesheet, type TimesheetDetail, type TimesheetListOptions, type TimesheetStatus, type TimesheetTotals, type WeeklyGrid, type WeeklyGridDay, type WeeklyGridEntry, type WeeklyGridOptions, type WeeklyGridRow, dbTransport, rpcTransport, sqlTransport };

package/dist/blocks/time-tracking/index.js

@@ -0,0 +1,317 @@
+import { s as nowInstant } from "../../temporal-CB5Fpo5d.js";
+import { t as temporal } from "../../temporal-required-DqRzr7i0.js";
+import { t as AsyncResult } from "../../result-COkvI9t5.js";
+import { n as isRecord } from "../../guards-6F2bCtQR.js";
+import { t as timeTrackingSqlOptions } from "../../options-HSv8R6h5.js";
+import { r as defineMetric } from "../../metric-definition-BjxVn4R5.js";
+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 { A as requiredInstant, C as optionalText, D as recordOf, I as textOf, S as optionalInstant, d as enumOrThrow, k as recordsOf, m as instantArg, n as applyTemporal, o as blockCall } from "../../block-helpers-BfVCR5Fc.js";
+import { 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 { s as isCurrency } from "../../money-95Rff2vT.js";
+import { i as moneyOf, o as optionalMoneyOf, s as unknownCurrency, t as amountText } from "../../money-codec-DCGgzO26.js";
+//#region src/blocks/time-tracking/time-tracking.ts
+const STATUSES = [
+	"open",
+	"submitted",
+	"approved",
+	"rejected"
+];
+function optional(key, value) {
+	return value === void 0 ? {} : { [key]: value };
+}
+const numberOf = (value) => typeof value === "number" ? value : void 0;
+function entryOf(value, fn) {
+	const row = recordOf(value, fn);
+	return {
+		id: textOf(row["id"]),
+		organizationId: textOf(row["organizationId"]),
+		userId: textOf(row["userId"]),
+		startedAt: requiredInstant(row["startedAt"], "startedAt"),
+		billable: row["billable"] === true,
+		createdAt: requiredInstant(row["createdAt"], "createdAt"),
+		updatedAt: requiredInstant(row["updatedAt"], "updatedAt"),
+		...optional("subjectType", optionalText(row["subjectType"])),
+		...optional("subjectId", optionalText(row["subjectId"])),
+		...optional("endedAt", optionalInstant(row["endedAt"])),
+		...optional("seconds", numberOf(row["seconds"])),
+		...optional("rate", optionalMoneyOf(row["rate"], row["rateCurrency"], "rate")),
+		...optional("note", optionalText(row["note"])),
+		fields: isRecord(row["fields"]) ? row["fields"] : {}
+	};
+}
+function timesheetOf(value, fn) {
+	const row = recordOf(value, fn);
+	return {
+		organizationId: textOf(row["organizationId"]),
+		userId: textOf(row["userId"]),
+		week: temporal().PlainDate.from(textOf(row["week"])),
+		status: enumOrThrow(row["status"], STATUSES, "timesheet status"),
+		...optional("id", optionalText(row["id"])),
+		...optional("approvalId", optionalText(row["approvalId"])),
+		...optional("note", optionalText(row["note"])),
+		...optional("submittedAt", optionalInstant(row["submittedAt"])),
+		...optional("approvedAt", optionalInstant(row["approvedAt"]))
+	};
+}
+function totalsOf(value) {
+	const row = isRecord(value) ? value : {};
+	return {
+		seconds: numberOf(row["seconds"]) ?? 0,
+		billableSeconds: numberOf(row["billableSeconds"]) ?? 0,
+		amounts: (Array.isArray(row["amounts"]) ? row["amounts"] : []).map((item) => {
+			const entry = isRecord(item) ? item : {};
+			return moneyOf(entry["amount"], entry["currency"], "totals.amounts");
+		})
+	};
+}
+/** Why a rate can't be sent, or `undefined` when it can. */
+const rateError = (rate) => rate === void 0 || rate === null || isCurrency(rate.currency) ? void 0 : unknownCurrency(rate.currency);
+function patchOf(patch) {
+	const out = {};
+	if (patch.startedAt !== void 0) out["startedAt"] = patch.startedAt.toString();
+	if (patch.endedAt !== void 0) out["endedAt"] = patch.endedAt.toString();
+	if (patch.subject !== void 0) {
+		out["subjectType"] = patch.subject?.subjectType ?? null;
+		out["subjectId"] = patch.subject?.subjectId ?? null;
+	}
+	if (patch.billable !== void 0) out["billable"] = patch.billable;
+	if (patch.rate !== void 0) {
+		out["rate"] = patch.rate === null ? null : amountText(patch.rate);
+		out["rateCurrency"] = patch.rate?.currency ?? null;
+	}
+	if (patch.note !== void 0) out["note"] = patch.note;
+	return out;
+}
+/** The `time-tracking` SQL module as typed calls. */
+function createTimeTracking(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const fields = blockFields(options.fields, "time entry fields");
+	return withBlockHooks({
+		start: (organizationId, entry = {}) => {
+			const invalid = rateError(entry.rate);
+			if (invalid !== void 0) return AsyncResult.err(invalid);
+			return fields.args(entry.fields).andThen((checked) => call("start_timer", {
+				tenant: organizationId,
+				subject_type: entry.subjectType ?? null,
+				subject_id: entry.subjectId ?? null,
+				billable: entry.billable ?? false,
+				rate: entry.rate === void 0 ? null : amountText(entry.rate),
+				rate_currency: entry.rate?.currency ?? null,
+				note: entry.note ?? null,
+				fields: checked
+			}, (value) => entryOf(value, "start_timer")).andThen(fields.row));
+		},
+		stop: (organizationId) => call("stop_timer", { tenant: organizationId }, (value) => entryOf(value, "stop_timer")).andThen(fields.row),
+		running: (organizationId) => call("running_timer", { tenant: organizationId }, (value) => value === null || value === void 0 ? void 0 : entryOf(value, "running_timer")).andThen((entry) => entry === void 0 ? AsyncResult.ok(void 0) : fields.row(entry)),
+		log: (organizationId, input) => {
+			const invalid = rateError(input.rate);
+			if (invalid !== void 0) return AsyncResult.err(invalid);
+			return fields.args(input.fields).andThen((checked) => call("log_time", {
+				tenant: organizationId,
+				started_at: instantArg(input.startedAt),
+				ended_at: instantArg(input.endedAt),
+				subject_type: input.subjectType ?? null,
+				subject_id: input.subjectId ?? null,
+				billable: input.billable ?? false,
+				rate: input.rate === void 0 ? null : amountText(input.rate),
+				rate_currency: input.rate?.currency ?? null,
+				note: input.note ?? null,
+				user_id: input.userId ?? null,
+				fields: checked
+			}, (value) => entryOf(value, "log_time")).andThen(fields.row));
+		},
+		update: (entryId, patch) => {
+			const invalid = rateError(patch.rate);
+			if (invalid !== void 0) return AsyncResult.err(invalid);
+			return fields.args(patch.fields).andThen((checked) => call("update_time_entry", {
+				entry_id: entryId,
+				patch: {
+					...patchOf(patch),
+					...checked === void 0 ? {} : { fields: checked }
+				}
+			}, (value) => entryOf(value, "update_time_entry")).andThen(fields.row));
+		},
+		remove: (entryId) => call("delete_time_entry", { entry_id: entryId }, (value) => entryOf(value, "delete_time_entry")).andThen(fields.row),
+		list: (organizationId, list = {}) => call("list_time_entries", {
+			tenant: organizationId,
+			user_id: list.userId ?? null,
+			starts: instantArg(list.from) ?? null,
+			ends: instantArg(list.to) ?? null,
+			subject_type: list.subjectType ?? null,
+			subject_id: list.subjectId ?? null,
+			everyone: list.everyone ?? false,
+			page_size: list.pageSize ?? null
+		}, (value) => recordsOf(value, "list_time_entries").map((row) => entryOf(row, "list_time_entries"))).andThen(fields.rows),
+		timesheet: (organizationId, week, userId) => call("get_timesheet", {
+			tenant: organizationId,
+			week: week.toString(),
+			user_id: userId ?? null
+		}, (value) => {
+			const row = recordOf(value, "get_timesheet");
+			return {
+				...timesheetOf(row, "get_timesheet"),
+				entries: recordsOf(row["entries"], "get_timesheet").map((item) => entryOf(item, "get_timesheet")),
+				totals: totalsOf(row["totals"])
+			};
+		}).andThen((detail) => fields.rows(detail.entries).map((entries) => ({
+			...detail,
+			entries
+		}))),
+		submit: (organizationId, week, note) => call("submit_timesheet", {
+			tenant: organizationId,
+			week: week.toString(),
+			note: note ?? null
+		}, (value) => timesheetOf(value, "submit_timesheet")),
+		reopen: (timesheetId) => call("reopen_timesheet", { timesheet_id: timesheetId }, (value) => timesheetOf(value, "reopen_timesheet")),
+		timesheets: (organizationId, list = {}) => call("list_timesheets", {
+			tenant: organizationId,
+			user_id: list.userId ?? null,
+			status: list.status ?? null,
+			page_size: list.pageSize ?? null,
+			before: list.before?.toString() ?? null
+		}, (value) => recordsOf(value, "list_timesheets").map((row) => timesheetOf(row, "list_timesheets")))
+	}, options.hooks, {
+		block: "time-tracking",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+//#region src/blocks/time-tracking/metrics.ts
+/**
+* A metric over finished time entries: the seconds tracked per day the entry
+* started, which a series can filter or group by `billable`, `user_id` and
+* `subject_type`. Running timers count once they stop.
+*/
+function timeTrackingMetrics(options = {}) {
+	return [defineMetric({
+		key: "time_tracked",
+		label: "Time tracked",
+		table: `${options.schema ?? "better_supabase"}.time_entries`,
+		tenant: "tenant_id",
+		measure: { sum: "seconds" },
+		timeColumn: "started_at",
+		dimensions: [
+			"billable",
+			"user_id",
+			"subject_type"
+		],
+		unit: "s",
+		...options.tz === void 0 ? {} : { tz: options.tz }
+	})];
+}
+/** The events that change `timeTrackingMetrics`, for `metricsSink` or `createBlocks({ metricEvents })`. */
+const TIME_TRACKING_METRIC_EVENTS = {
+	"time_entry.recorded": ["time_tracked"],
+	"time_entry.updated": ["time_tracked"],
+	"time_entry.deleted": ["time_tracked"]
+};
+/**
+* The entry's `startedAt`, the time its seconds are bucketed by, for
+* `metricsSink({ time })` or `createBlocks({ metricTime })`. An update that
+* moves the entry to another day also returns its `previousStartedAt`, so
+* the old day's total drops. Undefined for other events, so they keep
+* their own time.
+*/
+function timeEntryMetricTime(event) {
+	if (!event.type.includes("time_entry.") || !isRecord(event.data)) return;
+	const startedAt = event.data["startedAt"];
+	if (typeof startedAt !== "string") return;
+	const previous = event.data["previousStartedAt"];
+	return typeof previous === "string" && previous !== startedAt ? [startedAt, previous] : startedAt;
+}
+//#endregion
+//#region src/blocks/time-tracking/weekly-grid.ts
+const defaultKey = (entry) => `${entry.subjectType ?? ""}:${entry.subjectId ?? ""}:${String(entry.billable)}`;
+/**
+* Time entries as a weekly grid: one row per record (or `rowKey`) with the
+* seconds of each day, the shape of a weekly timesheet Data Grid. An entry
+* that crosses midnight counts on each day it covers.
+*/
+function toWeeklyGrid(entries, options) {
+	const monday = options.week.subtract({ days: options.week.dayOfWeek - 1 });
+	const dates = Array.from({ length: 7 }, (_, day) => monday.add({ days: day }));
+	const starts = [...dates, monday.add({ days: 7 })].map((date) => date.toZonedDateTime(options.timeZone).toInstant());
+	let now = options.now;
+	const keyOf = options.rowKey ?? defaultKey;
+	const rows = /* @__PURE__ */ new Map();
+	const totals = Array.from({ length: 7 }, () => 0);
+	let billable = 0;
+	for (const entry of entries) {
+		const end = entry.endedAt ?? (now ??= nowInstant());
+		const key = keyOf(entry);
+		let row = rows.get(key);
+		let counted = false;
+		for (let day = 0; day < 7; day += 1) {
+			const from = maxInstant(entry.startedAt, starts[day]);
+			const to = minInstant(end, starts[day + 1]);
+			const seconds = Math.max(0, Math.round(from.until(to).total("seconds")));
+			if (seconds === 0) continue;
+			row ??= {
+				id: key,
+				entry,
+				days: Array.from({ length: 7 }, () => 0),
+				entryIds: []
+			};
+			rows.set(key, row);
+			row.days[day] += seconds;
+			totals[day] += seconds;
+			if (entry.billable) billable += seconds;
+			if (!counted) row.entryIds.push(entry.id);
+			counted = true;
+		}
+	}
+	return {
+		days: dates.map((date, day) => ({
+			id: date.toString(),
+			date,
+			seconds: totals[day]
+		})),
+		rows: [...rows.values()].map((row) => ({
+			id: row.id,
+			billable: row.entry.billable,
+			days: row.days,
+			seconds: row.days.reduce((sum, value) => sum + value, 0),
+			entryIds: row.entryIds,
+			...row.entry.subjectType === void 0 ? {} : { subjectType: row.entry.subjectType },
+			...row.entry.subjectId === void 0 ? {} : { subjectId: row.entry.subjectId }
+		})),
+		seconds: totals.reduce((sum, value) => sum + value, 0),
+		billableSeconds: billable
+	};
+}
+function maxInstant(a, b) {
+	return a.epochNanoseconds >= b.epochNanoseconds ? a : b;
+}
+function minInstant(a, b) {
+	return a.epochNanoseconds <= b.epochNanoseconds ? a : b;
+}
+//#endregion
+//#region src/blocks/time-tracking/events.ts
+/** The `time-tracking` block's event types, for its manifest and `onBlockEvent`. */
+const timeTrackingEvents = defineEvents({
+	"time_entry.started": event(),
+	"time_entry.recorded": event(),
+	"time_entry.updated": event(),
+	"time_entry.deleted": event(),
+	"timesheet.submitted": event(),
+	"timesheet.approved": event(),
+	"timesheet.reopened": event()
+});
+//#endregion
+//#region src/blocks/time-tracking/manifest.ts
+/** The `time-tracking` block's manifest (ADR 0029). */
+const timeTrackingBlock = defineBlock({
+	name: "time-tracking",
+	sql: ["time-tracking"],
+	options: { "time-tracking": timeTrackingSqlOptions },
+	events: timeTrackingEvents,
+	create: createTimeTracking,
+	category: "people",
+	recipes: ["timesheet"]
+});
+//#endregion
+export { TIME_TRACKING_METRIC_EVENTS, createTimeTracking, dbTransport, rpcTransport, sqlTransport, timeEntryMetricTime, timeTrackingBlock, timeTrackingEvents, timeTrackingMetrics, toWeeklyGrid };

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

@@ -0,0 +1,78 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult } from "../../result-Cj3yWhjH.js";
+import { A as CollaborationEventData, wt as Events } from "../../events-CtAHxPal.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-NbUJygA7.js";
+import { n as BlockOptions } from "../../block-helpers-7pMBVsE6.js";
+import { n as BlockHooks } 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/trash/trash.d.ts
+interface TrashOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockOptions {
+  /**
+   * A Standard Schema for the trash item's extra columns
+   * (`blocks.trash.options.extraColumns`), keyed by database name, such as a
+   * reason. It types and parses them on `list`, and validates them on
+   * `trash`.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Trash<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/** What `trash` and `restore` return: the batch and how many rows it holds. */
+interface TrashBatch {
+  /** The trash item of the subject that was trashed. */
+  readonly id: string;
+  readonly batchId: string;
+  /** The subject and the children trashed with it. */
+  readonly count: number;
+}
+/** A subject in the trash, with the children trashed along with it counted in. */
+interface TrashItem<F extends object = Record<never, never>> extends TrashBatch {
+  readonly subjectType: string;
+  readonly subjectId: string;
+  readonly title?: string;
+  readonly trashedBy?: string;
+  readonly trashedAt: Temporal.Instant;
+  /** When `purge_expired_trash` deletes it; absent when retention is off. */
+  readonly purgeAfter?: Temporal.Instant;
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
+}
+interface TrashListOptions {
+  readonly subjectType?: string;
+  readonly pageSize?: number;
+  /** Items trashed before this time, for the next page. */
+  readonly before?: Temporal.Instant;
+}
+interface Trash<F extends object = Record<never, never>> {
+  /** Trashes the subject and its children in one batch; `fields` sets the item's extra columns. */
+  trash(organizationId: string, subjectType: string, subjectId: string, fields?: Partial<F>): AsyncResult<TrashBatch>;
+  /** Restores the whole batch of a trash item. */
+  restore(id: string): AsyncResult<TrashBatch>;
+  /** Newest first, one entry per batch. */
+  list(organizationId: string, options?: TrashListOptions): AsyncResult<readonly TrashItem<F>[]>;
+  /** Deletes the batch's rows for good; returns how many were deleted. */
+  purge(id: string): AsyncResult<number>;
+}
+/** The `trash` SQL module as typed calls. */
+export declare function createTrash<S extends StandardSchemaV1 | undefined = undefined>(options: TrashOptions<S>): Trash<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/trash/events.d.ts
+/** The events of the `trash` block: type to data. */
+type TrashEvents = {
+  readonly "subject.trashed": CollaborationEventData;
+  readonly "subject.restored": CollaborationEventData;
+  readonly "subject.purged": CollaborationEventData;
+};
+/** The `trash` block's event types, for its manifest and `onBlockEvent`. */
+export declare const trashEvents: Events<TrashEvents>;
+//#endregion
+//#region src/blocks/trash/manifest.d.ts
+/** The `trash` block's manifest (ADR 0029). */
+export declare const trashBlock: BlockOf<"trash", typeof createTrash, TrashEvents>;
+//#endregion
+export { type BlockTransport, type Trash, type TrashBatch, type TrashEvents, type TrashItem, type TrashListOptions, type TrashOptions, dbTransport, rpcTransport, sqlTransport };