better-supabase 0.13.0 → 0.15.0

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

@@ -0,0 +1,346 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, f as Result, t as AsyncResult } from "../../result-DZeA5KS6.js";
+import { t as StandardSchemaV1 } from "../../standard-DBV730sF.js";
+import { n as ExtraFields, r as FieldsOf } from "../../block-fields-BE7pInWZ.js";
+import { Ct as Events } from "../../events-vcqenSYU.js";
+import { R as WorkItemEventData } from "../../index-CG9rA8H8.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-CRpAHrp_.js";
+import { a as dbTransport, i as RpcClient, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DWZSJrwN.js";
+import { a as BlockTransportMiddleware, d as extendBlock, f as withBlockHooks, n as BlockHooks, p as wrapTransport } from "../../block-hooks-DZN2w69m.js";
+import { Bt as Action, Sn as EntitySchema, c as BlockOf, rn as RecordBinding } from "../../define-block-BVcLQ3DF.js";
+import { i as EventSink } from "../../cloud-event-CzZTJkXv.js";
+import { n as ConversionContext, t as ConversionClients } from "../../conversion-BAbucuXq.js";
+import { i as Conversation } from "../../types-Dp3UCr1e.js";
+//#region src/blocks/tasks/tasks.d.ts
+/** The state a stage's category sets; `completed` and `canceled` are closed. */
+type WorkItemState = "triage" | "backlog" | "unstarted" | "started" | "completed" | "canceled";
+type CloseReason = "completed" | "not_planned" | "duplicate";
+/** A work item. `F` types the extra columns the `fields` schema describes. */
+interface WorkItem<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly number: bigint;
+  /** `TASK-12`, or the numbering format. */
+  readonly identifier: string;
+  readonly title: string;
+  readonly body?: string;
+  readonly parentId?: string;
+  readonly teamId?: string;
+  readonly projectId?: string;
+  readonly iterationId?: string;
+  /** 0 none, 1 urgent, 2 high, 3 medium, 4 low. */
+  readonly priority: number;
+  readonly estimate?: number;
+  /** Its own progress; `tree` rolls children up when it has none. */
+  readonly progress?: number;
+  readonly startAt?: Temporal.Instant;
+  readonly endAt?: Temporal.Instant;
+  readonly dueAt?: Temporal.Instant;
+  readonly pipelineId?: string;
+  readonly stageId?: string;
+  readonly stageEnteredAt?: Temporal.Instant;
+  readonly state: WorkItemState;
+  readonly closeReason?: CloseReason;
+  readonly closedAt?: Temporal.Instant;
+  /** A locked item keeps its dates, as a locked Gantt bar. */
+  readonly locked: boolean;
+  readonly rank: string;
+  readonly assigneeIds: readonly string[];
+  /** How many checklist items it has, and how many are done. */
+  readonly checklist: {
+    readonly total: number;
+    readonly done: number;
+  };
+  /** Its repeat rule, with the reminders block. */
+  readonly recurrence?: WorkItemRecurrence;
+  /** The item this one repeats. */
+  readonly recursFromId?: string;
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
+  readonly archived: boolean;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+interface WorkItemInput<F extends object = Record<never, never>> {
+  readonly title: string;
+  readonly body?: string;
+  readonly parentId?: string;
+  readonly teamId?: string;
+  readonly projectId?: string;
+  readonly iterationId?: string;
+  readonly priority?: number;
+  readonly estimate?: number;
+  readonly progress?: number;
+  readonly startAt?: Temporal.Instant;
+  readonly endAt?: Temporal.Instant;
+  readonly dueAt?: Temporal.Instant;
+  readonly pipelineId?: string;
+  readonly stageId?: string;
+  /**
+   * Files to attach: ids of your own attachments in the organization that have
+   * no subject yet, such as uploads made before the item existed.
+   */
+  readonly attachmentIds?: readonly string[];
+  /** The extra columns to set. */
+  readonly fields?: Partial<F>;
+}
+type WorkItemField = "title" | "body" | "parentId" | "teamId" | "projectId" | "iterationId" | "priority" | "estimate" | "progress" | "startAt" | "endAt" | "dueAt" | "stageId" | "closeReason" | "attachments";
+/** A work item's repeat rule: an RFC 5545 RRULE from `dtstart` in `tzid`. */
+interface WorkItemRecurrence {
+  readonly rrule: string;
+  readonly tzid: string;
+  readonly dtstart: Temporal.Instant;
+}
+interface ChecklistItem {
+  readonly id: string;
+  readonly workItemId: string;
+  readonly title: string;
+  readonly done: boolean;
+  readonly doneAt?: Temporal.Instant;
+  readonly doneBy?: string;
+  readonly rank: string;
+  readonly createdAt: Temporal.Instant;
+}
+interface ChecklistItemInput {
+  readonly title?: string;
+  readonly done?: boolean;
+  /** A rank key; a new item without one goes last. */
+  readonly rank?: string;
+}
+/** `all` watches, `participating` follows, `ignore` mutes. */
+type WorkItemWatchLevel = "all" | "participating" | "ignore";
+interface WorkItemWatcher {
+  readonly userId: string;
+  readonly level: Exclude<WorkItemWatchLevel, "ignore">;
+}
+/**
+ * One cell edit or drag: a built-in field or an extra column. `null` clears the
+ * field.
+ */
+interface WorkItemChange<F extends object = Record<never, never>> {
+  readonly workItemId: string;
+  readonly field: WorkItemField | (keyof F & string);
+  readonly value: unknown;
+}
+interface WorkItemChangeResult {
+  readonly accepted: readonly {
+    readonly workItemId: string;
+    readonly field: string;
+  }[];
+  readonly rejected: readonly {
+    readonly workItemId: string;
+    readonly field: string;
+    readonly hint?: string;
+    readonly reason: string;
+  }[];
+}
+/** A node of `tree`, for a Gantt chart or a nested list. */
+interface WorkItemNode {
+  readonly id: string;
+  readonly parentId?: string;
+  readonly identifier: string;
+  readonly title: string;
+  readonly state: WorkItemState;
+  readonly startAt?: Temporal.Instant;
+  readonly endAt?: Temporal.Instant;
+  readonly dueAt?: Temporal.Instant;
+  readonly locked: boolean;
+  readonly depth: number;
+  readonly progress: number;
+}
+interface WorkItemListOptions {
+  readonly teamId?: string;
+  readonly projectId?: string;
+  readonly iterationId?: string;
+  readonly parentId?: string;
+  readonly assigneeId?: string;
+  readonly states?: readonly WorkItemState[];
+  /** Only items that aren't completed or canceled. */
+  readonly open?: boolean;
+  /** Matches the title, or the start of the identifier. */
+  readonly search?: string;
+  /** Continues after this item. */
+  readonly after?: string;
+  readonly limit?: number;
+}
+interface Project {
+  readonly id: string;
+  readonly key: string;
+  readonly name: string;
+  readonly ownerId?: string;
+  readonly status: "planned" | "active" | "paused" | "completed" | "canceled";
+  readonly startOn?: Temporal.PlainDate;
+  readonly targetOn?: Temporal.PlainDate;
+  /** The share of its items that are completed, canceled ones left out. */
+  readonly progress?: number;
+}
+interface Iteration {
+  readonly id: string;
+  readonly teamId?: string;
+  readonly name: string;
+  readonly startsOn: Temporal.PlainDate;
+  readonly endsOn: Temporal.PlainDate;
+}
+interface Tasks<F extends object = Record<never, never>> {
+  create(organizationId: string, input: WorkItemInput<F>, assigneeIds?: readonly string[]): AsyncResult<WorkItem<F>>;
+  /** Extra column changes are validated with the `fields` schema first. */
+  update(changes: readonly WorkItemChange<F>[]): AsyncResult<WorkItemChangeResult>;
+  /** Replaces the assignees; new ones are notified and every one watches. */
+  assign(workItemId: string, userIds: readonly string[]): AsyncResult<number>;
+  archive(workItemId: string, archived?: boolean): AsyncResult<boolean>;
+  remove(workItemId: string): AsyncResult<boolean>;
+  tree(rootId: string): AsyncResult<WorkItemNode[]>;
+  /** One item you can read, or `undefined`. */
+  get(workItemId: string): AsyncResult<WorkItem<F> | undefined>;
+  checklist(workItemId: string): AsyncResult<ChecklistItem[]>;
+  /** Adds a checklist item, or changes the one `checklistItemId` names. */
+  saveChecklistItem(workItemId: string, input: ChecklistItemInput, checklistItemId?: string): AsyncResult<ChecklistItem>;
+  removeChecklistItem(checklistItemId: string): AsyncResult<boolean>;
+  /**
+   * Makes the item repeat (`null` stops it). Needs the reminders block;
+   * `workItemRecurrenceSink` creates the next item when one is completed.
+   */
+  setRecurrence(workItemId: string, rule: {
+    readonly rrule: string;
+    readonly tzid?: string;
+  } | null): AsyncResult<WorkItemRecurrence | undefined>;
+  /** Creates the next item of a repeating one. Service only, idempotent. */
+  repeat(workItemId: string, dueAt: Temporal.Instant): AsyncResult<WorkItem<F>>;
+  /** Watches, follows or mutes an item (`null` clears). Needs notifications. */
+  watch(workItemId: string, level: WorkItemWatchLevel | null): AsyncResult<boolean>;
+  watchers(workItemId: string): AsyncResult<WorkItemWatcher[]>;
+  list(organizationId: string, options?: WorkItemListOptions): AsyncResult<WorkItem<F>[]>;
+  saveProject(organizationId: string, project: Partial<Omit<Project, "id" | "progress" | "startOn" | "targetOn">> & {
+    readonly id?: string;
+    readonly startOn?: Temporal.PlainDate | null;
+    readonly targetOn?: Temporal.PlainDate | null;
+    readonly archived?: boolean;
+  }): AsyncResult<Project>;
+  saveIteration(organizationId: string, iteration: Partial<Omit<Iteration, "id">> & {
+    readonly id?: string;
+  }): AsyncResult<Iteration>;
+}
+interface TasksOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  readonly schema?: string;
+  /**
+   * A Standard Schema for the item's extra columns
+   * (`blocks.tasks.options.extraColumns`), keyed by database name. It types and
+   * parses them on reads, and validates them on `create` and `update`.
+   */
+  readonly fields?: S;
+  readonly hooks?: NoInfer<BlockHooks<Tasks<FieldsOf<S>>>>;
+  readonly logger?: Logger;
+  readonly mappers?: readonly ErrorMapper[];
+}
+/**
+ * The tasks block: issues and tasks on pipelines, with batched edits for a grid
+ * or a Gantt chart, assignees, a progress tree, projects and iterations.
+ */
+export declare function createTasks<S extends StandardSchemaV1 | undefined = undefined>(options: TasksOptions<S>): Tasks<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/tasks/recurrence.d.ts
+/**
+ * The first occurrence of `rule` after `after`, or `undefined` when the rule
+ * has ended (COUNT or UNTIL) or has none in the next five years.
+ */
+export declare function nextWorkItemOccurrence(rule: WorkItemRecurrence, after: Temporal.Instant): Temporal.Instant | undefined;
+interface WorkItemRecurrenceSinkOptions {
+  /**
+   * The closed event's type without `typePrefix`, after `blocks.tasks.entities`
+   * (`task.closed`). Default `work_item.closed`.
+   */
+  readonly type?: string;
+  /** Stripped from each event type. Defaults to `dev.better-supabase`. */
+  readonly typePrefix?: string;
+  /** The current time, for an item without a due date. */
+  readonly now?: () => Temporal.Instant;
+}
+/**
+ * An outbox sink that creates the next item when a repeating one is completed:
+ * `outbox.relay('tasks', workItemRecurrenceSink(workItems))`. Build `workItems`
+ * with a service transport. The next item is due at the rule's first occurrence
+ * after the completed item's due date (or now), and `repeat` runs once per
+ * item, so a redelivered event changes nothing.
+ */
+export declare function workItemRecurrenceSink(workItems: Pick<Tasks, "get" | "repeat">, options?: WorkItemRecurrenceSinkOptions): EventSink;
+//#endregion
+//#region src/blocks/tasks/events.d.ts
+/** The events of the `tasks` block: type to data. */
+type TasksEvents = {
+  readonly "work_item.created": WorkItemEventData;
+  readonly "work_item.updated": WorkItemEventData;
+  readonly "work_item.assigned": WorkItemEventData;
+  readonly "work_item.closed": WorkItemEventData;
+  readonly "work_item.reopened": WorkItemEventData;
+  readonly "work_item.archived": WorkItemEventData;
+  readonly "work_item.deleted": WorkItemEventData;
+};
+/** The `tasks` block's event types, for its manifest and `onBlockEvent`. */
+export declare const tasksEvents: Events<TasksEvents>;
+//#endregion
+//#region src/blocks/tasks/record-binding.d.ts
+/** A pending write to a work item's checklist, for `useOptimistic`. */
+type WorkItemChecklistOptimisticAction = {
+  readonly type: "save";
+  readonly item: ChecklistItem;
+} | {
+  readonly type: "remove";
+  readonly id: string;
+};
+/**
+ * The checklist with a pending write applied: `save` adds the item or replaces
+ * the one with the same id, kept in rank order; `remove` takes it out.
+ */
+export declare function workItemChecklistOptimistic(state: readonly ChecklistItem[], action: WorkItemChecklistOptimisticAction): readonly ChecklistItem[];
+/**
+ * A work item's checklist, on the work item's own page: the subject is the work
+ * item (`{ type: "work_item", id }`, or its renamed type). A checklist change
+ * emits `work_item.updated`, which makes the binding stale.
+ */
+export declare const workItemChecklistBinding: RecordBinding<Tasks, readonly ChecklistItem[], never, WorkItemChecklistOptimisticAction>;
+//#endregion
+//#region src/blocks/tasks/manifest.d.ts
+/** The `tasks` block's manifest (ADR 0029). */
+export declare const tasksBlock: BlockOf<"tasks", typeof createTasks, TasksEvents, Record<never, never>, "sink", typeof workItemChecklistBinding>;
+//#endregion
+//#region src/blocks/tasks/schemas.d.ts
+/** What `create` takes, with the bounds the SQL checks. */
+export declare const workItemInputSchema: EntitySchema<WorkItemInput>;
+/**
+ * One edit `update` takes. `field` is a built-in field or an extra column, so
+ * any name passes; the SQL rejects an unknown one.
+ */
+export declare const workItemChangeSchema: EntitySchema<WorkItemChange>;
+/** The options `list` takes. */
+export declare const workItemListFilterSchema: EntitySchema<WorkItemListOptions>;
+//#endregion
+//#region src/blocks/tasks/actions.d.ts
+/** `blocks.inbox`, `blocks.tasks` and `blocks.relations` for one organization. */
+interface TaskFromConversationClients extends ConversionClients {
+  readonly inbox: {
+    readonly conversations: {
+      get(conversationId: string): PromiseLike<Result<Conversation | null>>;
+    };
+  };
+  readonly tasks: {
+    create(organizationId: string, input: WorkItemInput, assigneeIds?: readonly string[]): PromiseLike<Result<WorkItem>>;
+  };
+}
+interface TaskFromConversationOptions {
+  /** The clients for one organization, over a service connection. */
+  readonly clients: (tenant: string) => TaskFromConversationClients | PromiseLike<TaskFromConversationClients>;
+  /** The task for a conversation. Default: its subject or preview as the title. */
+  readonly map?: (conversation: Conversation, context: ConversionContext<TaskFromConversationClients>) => WorkItemInput;
+  /** Assigns the task to the conversation's assignee. Default: true. */
+  readonly assign?: boolean;
+}
+/**
+ * The `tasks.from_conversation` action, which the inbox block's default
+ * automation runs on `inbox_conversation.opened`: a task from the conversation,
+ * linked `created_from` it.
+ */
+export declare function taskFromConversationAction(options: TaskFromConversationOptions): Action;
+//#endregion
+export { type BlockHooks, type BlockTransport, type BlockTransportMiddleware, type ChecklistItem, type ChecklistItemInput, type CloseReason, type Iteration, type Project, type RpcClient, type TaskFromConversationClients, type TaskFromConversationOptions, type Tasks, type TasksEvents, type TasksOptions, type WorkItem, type WorkItemChange, type WorkItemChangeResult, type WorkItemChecklistOptimisticAction, type WorkItemField, type WorkItemInput, type WorkItemListOptions, type WorkItemNode, type WorkItemRecurrence, type WorkItemRecurrenceSinkOptions, type WorkItemState, type WorkItemWatchLevel, type WorkItemWatcher, dbTransport, extendBlock, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };