better-supabase 0.13.0 → 0.15.0

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

@@ -0,0 +1,325 @@
+/// <reference lib="esnext.temporal" />
+import { 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 { $ as RecordRef } from "../../types-DFdg_4yN.js";
+import { Ct as Events } from "../../events-vcqenSYU.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { n as BlockOptions } 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 { n as dispatchSqlOptions, t as DispatchSqlOptions } from "../../options-CyAhRKKm.js";
+import { Sn as EntitySchema, c as BlockOf, ln as RecordBindingWrite, mn as RecordRowInput, rn as RecordBinding } from "../../define-block-BVcLQ3DF.js";
+//#region src/blocks/dispatch/statuses.d.ts
+/** Where a work order is in its life. */
+export declare const WORK_ORDER_STATUSES: readonly ["unscheduled", "scheduled", "en_route", "on_site", "done", "cancelled"];
+type WorkOrderStatus = (typeof WORK_ORDER_STATUSES)[number];
+export declare const WORK_ORDER_PRIORITIES: readonly ["low", "normal", "high", "urgent"];
+type WorkOrderPriority = (typeof WORK_ORDER_PRIORITIES)[number];
+//#endregion
+//#region src/blocks/dispatch/dispatch.d.ts
+interface DispatchOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockOptions {
+  /**
+   * A Standard Schema for the work orders' extra columns
+   * (`blocks.dispatch.options.extraColumns`), keyed by database name. It types
+   * and parses them on reads and validates them on writes.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Dispatch<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/** A job at a place, for an asset or a record, in a technician's slot. */
+interface WorkOrder<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly priority: WorkOrderPriority;
+  readonly status: WorkOrderStatus;
+  readonly technicianId?: string;
+  readonly startsAt?: Temporal.Instant;
+  readonly endsAt?: Temporal.Instant;
+  /** The day it starts, in the block's `timeZone`. */
+  readonly day?: Temporal.PlainDate;
+  /** An assets location. */
+  readonly locationId?: string;
+  readonly assetId?: string;
+  /** The booking its slot came from. */
+  readonly bookingId?: string;
+  readonly subject?: RecordRef;
+  /** A free-text address, for a place that isn't an assets location. */
+  readonly address?: string;
+  readonly enRouteAt?: Temporal.Instant;
+  readonly arrivedAt?: Temporal.Instant;
+  readonly completedAt?: Temporal.Instant;
+  readonly cancelledAt?: Temporal.Instant;
+  readonly cancelReason?: string;
+  readonly completionNote?: string;
+  readonly createdBy?: string;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
+}
+interface WorkOrderInput<F extends object = Record<never, never>> {
+  readonly title: string;
+  readonly description?: string;
+  /** Default `normal`. */
+  readonly priority?: WorkOrderPriority;
+  readonly locationId?: string;
+  readonly assetId?: string;
+  /** Takes the slot from the booking when `startsAt` is unset. */
+  readonly bookingId?: string;
+  /** The record the job is for, registered in `config.records`. */
+  readonly subject?: RecordRef;
+  readonly address?: string;
+  /** With `startsAt` (or a booking), the work order is scheduled at once. */
+  readonly technicianId?: string;
+  readonly startsAt?: Temporal.Instant;
+  /** Defaults to `startsAt` plus the block's `defaultDuration`. */
+  readonly endsAt?: Temporal.Instant;
+  /** The extra columns. */
+  readonly fields?: Partial<F>;
+}
+/** What to change; unset keeps a value. */
+interface WorkOrderPatch<F extends object = Record<never, never>> {
+  readonly title?: string;
+  readonly description?: string;
+  readonly priority?: WorkOrderPriority;
+  readonly locationId?: string;
+  readonly assetId?: string;
+  readonly address?: string;
+  readonly fields?: Partial<F>;
+}
+interface WorkOrderSlot {
+  readonly technicianId: string;
+  readonly startsAt: Temporal.Instant;
+  /** Defaults to `startsAt` plus the block's `defaultDuration`. */
+  readonly endsAt?: Temporal.Instant;
+}
+/** The statuses `setStatus` moves a work order to. */
+type WorkOrderTransition = Extract<WorkOrderStatus, "en_route" | "on_site" | "done" | "cancelled">;
+interface WorkOrderListOptions {
+  readonly status?: WorkOrderStatus;
+  readonly technicianId?: string;
+  readonly subject?: RecordRef;
+  /** Work orders whose slot ends after this. */
+  readonly from?: Temporal.Instant;
+  /** Work orders whose slot starts before this. */
+  readonly until?: Temporal.Instant;
+  /** Work orders created before this, for the next page. */
+  readonly before?: Temporal.Instant;
+  /** Default 50, at most 500. */
+  readonly limit?: number;
+}
+interface DispatchBoardOptions {
+  readonly from: Temporal.PlainDate;
+  /** Inclusive; at most 31 days after `from`. */
+  readonly to: Temporal.PlainDate;
+  /**
+   * The board's rows, such as the members holding `dispatch.work`. Unset: the
+   * technicians with work orders in the range.
+   */
+  readonly technicianIds?: readonly string[];
+}
+/** The schedule board: technicians by day, and the unscheduled backlog. */
+interface DispatchBoard<F extends object = Record<never, never>> {
+  readonly from: Temporal.PlainDate;
+  readonly to: Temporal.PlainDate;
+  /** The zone `day` is computed in. */
+  readonly timeZone: string;
+  readonly technicianIds: readonly string[];
+  /** The scheduled and worked orders in the range, by start. */
+  readonly scheduled: readonly WorkOrder<F>[];
+  /** Unscheduled work orders, most urgent first. */
+  readonly backlog: readonly WorkOrder<F>[];
+}
+interface TechnicianStop<F extends object = Record<never, never>> {
+  /** From 1. */
+  readonly position: number;
+  readonly workOrder: WorkOrder<F>;
+}
+/** A technician's day: the route's stops in order, then the rest by start. */
+interface TechnicianDay<F extends object = Record<never, never>> {
+  readonly technicianId: string;
+  readonly date: Temporal.PlainDate;
+  /** Set once the day has a planned route. */
+  readonly routeId?: string;
+  readonly stops: readonly TechnicianStop<F>[];
+}
+interface DispatchRoute {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly technicianId: string;
+  readonly routeDate: Temporal.PlainDate;
+  /** In driving order. */
+  readonly workOrderIds: readonly string[];
+}
+/** A part a job used. */
+interface WorkOrderPart {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly workOrderId: string;
+  readonly name: string;
+  /** A decimal string, such as `"2"` or `"1.5"`. */
+  readonly quantity: string;
+  readonly unit?: string;
+  readonly assetId?: string;
+  /** A catalog variant. */
+  readonly variantId?: string;
+  /** The inventory location it was taken from. */
+  readonly locationId?: string;
+  readonly recordedBy?: string;
+  readonly createdAt: Temporal.Instant;
+}
+interface WorkOrderPartInput {
+  readonly name: string;
+  /** A decimal above zero with at most three places. */
+  readonly quantity: string | number;
+  readonly unit?: string;
+  /** Needs the assets block. */
+  readonly assetId?: string;
+  /** Needs the catalog block. */
+  readonly variantId?: string;
+  /** Needs the inventory block. */
+  readonly locationId?: string;
+}
+/**
+ * Field service dispatch. `F` is the extra fields `options.fields` describes.
+ * Methods that take no work order id act in the block's `tenant`.
+ */
+interface Dispatch<F extends object = Record<never, never>> {
+  create(input: WorkOrderInput<F>): AsyncResult<WorkOrder<F>>;
+  update(id: string, patch: WorkOrderPatch<F>): AsyncResult<WorkOrder<F>>;
+  /**
+   * Puts the work order in a technician's slot: `DISPATCH_SLOT_TAKEN` when the
+   * technician already has work then.
+   */
+  schedule(id: string, slot: WorkOrderSlot): AsyncResult<WorkOrder<F>>;
+  /** Sends a scheduled work order back to the backlog. */
+  unschedule(id: string): AsyncResult<WorkOrder<F>>;
+  /**
+   * Moves the work order on: `en_route`, `on_site`, `done` (with an optional
+   * completion note) or `cancelled` (with an optional reason). The assigned
+   * technician moves their own work orders with `dispatch.work`; cancelling
+   * needs `dispatch.manage`.
+   */
+  setStatus(id: string, status: WorkOrderTransition, note?: string): AsyncResult<WorkOrder<F>>;
+  /** `null` when it doesn't exist or the caller can't read it. */
+  get(id: string): AsyncResult<WorkOrder<F> | null>;
+  list(options?: WorkOrderListOptions): AsyncResult<readonly WorkOrder<F>[]>;
+  board(options: DispatchBoardOptions): AsyncResult<DispatchBoard<F>>;
+  /** The technician's day plan; `technicianId` defaults to the caller. */
+  technicianDay(day: Temporal.PlainDate, technicianId?: string): AsyncResult<TechnicianDay<F>>;
+  /** Replaces the technician's route for the day with these stops, in order. */
+  planRoute(technicianId: string, day: Temporal.PlainDate, workOrderIds: readonly string[]): AsyncResult<DispatchRoute>;
+  recordPart(workOrderId: string, input: WorkOrderPartInput): AsyncResult<WorkOrderPart>;
+  parts(workOrderId: string): AsyncResult<readonly WorkOrderPart[]>;
+  /** `false` when the part was already gone. */
+  removePart(partId: string): AsyncResult<boolean>;
+}
+/** The `dispatch` SQL module as typed calls. */
+export declare function createDispatch<S extends StandardSchemaV1 | undefined = undefined>(options: DispatchOptions<S>): Dispatch<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/dispatch/events.d.ts
+/** `work_order.created`. */
+interface WorkOrderCreatedEventData {
+  readonly organizationId: string;
+  /** The work order. */
+  readonly id: string;
+  /** `unscheduled`, or `scheduled` when it was created with a slot. */
+  readonly status: string;
+  readonly technicianId: string | null;
+  readonly subjectType: string | null;
+  readonly subjectId: string | null;
+}
+/** `work_order.updated`: its title, description, priority or place changed. */
+interface WorkOrderUpdatedEventData {
+  readonly organizationId: string;
+  readonly id: string;
+}
+/** `work_order.scheduled`: it got a technician and a slot, or a new one. */
+interface WorkOrderScheduledEventData {
+  readonly organizationId: string;
+  readonly id: string;
+  readonly technicianId: string;
+  /** ISO 8601. */
+  readonly startsAt: string;
+  readonly endsAt: string;
+}
+/** `work_order.unscheduled`: it went back to the backlog. */
+interface WorkOrderUnscheduledEventData {
+  readonly organizationId: string;
+  readonly id: string;
+  /** The technician it had. */
+  readonly technicianId: string | null;
+}
+/** `work_order.status_changed`: en route, on site, done or cancelled. */
+interface WorkOrderStatusChangedEventData {
+  readonly organizationId: string;
+  readonly id: string;
+  readonly from: string;
+  readonly to: string;
+  readonly technicianId: string | null;
+}
+/** `work_order.part_used`: a part was recorded on the work order. */
+interface WorkOrderPartUsedEventData {
+  readonly organizationId: string;
+  /** The work order. */
+  readonly id: string;
+  readonly partId: string;
+  readonly assetId: string | null;
+  readonly variantId: string | null;
+  /** A decimal string. */
+  readonly quantity: string;
+}
+/** `dispatch_route.planned`: a technician's day got its ordered stops. */
+interface DispatchRoutePlannedEventData {
+  readonly organizationId: string;
+  /** The route. */
+  readonly id: string;
+  readonly technicianId: string;
+  /** `YYYY-MM-DD`. */
+  readonly routeDate: string;
+  readonly stops: number;
+}
+/** The events of the `dispatch` block: type to data. */
+type DispatchEvents = {
+  readonly "work_order.created": WorkOrderCreatedEventData;
+  readonly "work_order.updated": WorkOrderUpdatedEventData;
+  readonly "work_order.scheduled": WorkOrderScheduledEventData;
+  readonly "work_order.unscheduled": WorkOrderUnscheduledEventData;
+  readonly "work_order.status_changed": WorkOrderStatusChangedEventData;
+  readonly "work_order.part_used": WorkOrderPartUsedEventData;
+  readonly "dispatch_route.planned": DispatchRoutePlannedEventData;
+};
+/** The `dispatch` block's event types, for its manifest and `onBlockEvent`. */
+export declare const dispatchEvents: Events<DispatchEvents>;
+//#endregion
+//#region src/blocks/dispatch/schemas.d.ts
+/** What `create` takes, with the bounds the SQL checks. */
+export declare const workOrderInputSchema: EntitySchema<WorkOrderInput>;
+/** What the section's `create` write takes: the record is the subject. */
+type WorkOrderSectionInput = Omit<WorkOrderInput, "subject" | "fields">;
+export declare const workOrderSectionInputSchema: EntitySchema<WorkOrderSectionInput>;
+/** What `recordPart` takes. */
+export declare const workOrderPartInputSchema: EntitySchema<WorkOrderPartInput>;
+//#endregion
+//#region src/blocks/dispatch/record-binding.d.ts
+/** The writes of the dispatch binding. */
+type DispatchWrites = {
+  /** Opens a work order for the record, such as a repair for a customer. */
+  readonly create: RecordBindingWrite<Dispatch, WorkOrderSectionInput, WorkOrder>;
+  /** Cancels one of the record's work orders. */
+  readonly cancel: RecordBindingWrite<Dispatch, RecordRowInput, WorkOrder>;
+};
+/** The work orders opened for a record: a customer's or a site's jobs. */
+export declare const dispatchBinding: RecordBinding<Dispatch, readonly WorkOrder[], undefined, never, DispatchWrites>;
+//#endregion
+//#region src/blocks/dispatch/manifest.d.ts
+/** The `dispatch` block's manifest (ADR 0029). */
+export declare const dispatchBlock: BlockOf<"dispatch", typeof createDispatch, DispatchEvents, Record<never, never>, never, typeof dispatchBinding>;
+//#endregion
+export { type BlockHooks, type BlockTransport, type BlockTransportMiddleware, type Dispatch, type DispatchBoard, type DispatchBoardOptions, type DispatchEvents, type DispatchOptions, type DispatchRoute, type DispatchRoutePlannedEventData, type DispatchSqlOptions, type DispatchWrites, type RpcClient, type TechnicianDay, type TechnicianStop, type WorkOrder, type WorkOrderCreatedEventData, type WorkOrderInput, type WorkOrderListOptions, type WorkOrderPart, type WorkOrderPartInput, type WorkOrderPartUsedEventData, type WorkOrderPatch, type WorkOrderPriority, type WorkOrderScheduledEventData, type WorkOrderSectionInput, type WorkOrderSlot, type WorkOrderStatus, type WorkOrderStatusChangedEventData, type WorkOrderTransition, type WorkOrderUnscheduledEventData, type WorkOrderUpdatedEventData, dbTransport, dispatchSqlOptions, extendBlock, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };