things-api 0.5.0

package/dist/write/operations.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Operation catalog: every mutation the write layer can express, plus the
+ * typed parameter shapes. Vector support for each operation lives in the
+ * per-vector matrices (data, produced by the lab), not here.
+ */
+import type { IsoDate, ReminderTime } from "../model/dates.ts";
+export declare const OPERATION_KINDS: readonly ["todo.add", "todo.update", "todo.complete", "todo.cancel", "todo.reopen", "todo.move", "todo.set-tags", "todo.replace-checklist", "todo.delete", "project.add", "project.update", "project.complete", "project.delete", "area.add", "area.delete", "tag.add", "tag.delete", "trash.empty", "reorder", "todo.duplicate", "area.update", "tag.update", "project.move", "todo.restore", "project.duplicate", "project.cancel", "project.reopen", "project.restore", "project.set-tags", "todo.backdate", "todo.add-logged"];
+export type OperationKind = (typeof OPERATION_KINDS)[number];
+/** `when` scheduling value: list keyword or a concrete date. */
+export type WhenValue = "today" | "evening" | "anytime" | "someday" | IsoDate;
+/** Container reference by uuid or (unique, case-insensitive) title. */
+export interface ContainerRef {
+    uuid?: string;
+    title?: string;
+}
+export interface TodoAddParams {
+    title: string;
+    notes?: string;
+    when?: WhenValue;
+    /**
+     * Time-of-day reminder, `HH:mm` 24h. Requires a schedulable `when`
+     * (today, evening, or a date) in the same call.
+     */
+    reminder?: ReminderTime;
+    deadline?: IsoDate;
+    tags?: string[];
+    checklistItems?: string[];
+    project?: ContainerRef;
+    area?: ContainerRef;
+    /** Existing heading inside the target project (placement only). */
+    heading?: string;
+}
+export interface TodoUpdateParams {
+    uuid: string;
+    title?: string;
+    notes?: string;
+    /** Append to the existing notes (newline-joined). Exclusive with notes/prependNotes. */
+    appendNotes?: string;
+    /** Prepend to the existing notes (newline-joined). Exclusive with notes/appendNotes. */
+    prependNotes?: string;
+    when?: WhenValue;
+    /**
+     * `HH:mm` sets a reminder (requires when: today|evening in the same call);
+     * null clears it (today/evening only — a dated reminder can only be
+     * changed, not cleared). When re-scheduling with this OMITTED, an existing
+     * reminder is auto-preserved.
+     */
+    reminder?: ReminderTime | null;
+    deadline?: IsoDate | null;
+}
+export interface UuidParams {
+    uuid: string;
+}
+export interface TodoBackdateParams {
+    uuid: string;
+    /**
+     * Rewrite the completion timestamp to noon (local) on this date. The
+     * to-do must already be completed or canceled.
+     */
+    completionDate?: IsoDate;
+    /** Rewrite the creation timestamp to noon (local) on this date. */
+    creationDate?: IsoDate;
+}
+export interface TodoAddLoggedParams {
+    title: string;
+    notes?: string;
+    /** The completion timestamp the created row carries (logged in the past). */
+    completionDate: IsoDate;
+    /** Optional backdated creation timestamp (must be <= completionDate). */
+    creationDate?: IsoDate;
+}
+export interface TodoMoveParams {
+    uuid: string;
+    project?: ContainerRef;
+    area?: ContainerRef;
+    /** Existing heading inside the destination project. */
+    heading?: string;
+    /** Move back to the Inbox — removes any schedule. Exclusive with the others. */
+    inbox?: boolean;
+    /**
+     * Detach from the current project/area/heading, keeping the schedule and
+     * everything else. Exclusive with the others.
+     */
+    detach?: boolean;
+}
+export interface TodoSetTagsParams {
+    uuid: string;
+    /** Full replacement set (an empty list clears all tags). */
+    tags: string[];
+}
+/** One checklist item in a stateful replacement. */
+export interface ChecklistItemSpec {
+    title: string;
+    /** Recreate the item pre-checked. */
+    completed?: boolean;
+}
+export interface TodoReplaceChecklistParams {
+    uuid: string;
+    /**
+     * Full replacement list. Plain strings recreate items unchecked; object
+     * entries can recreate items pre-checked. Item uuids are NOT stable
+     * across a rewrite.
+     */
+    items: (string | ChecklistItemSpec)[];
+}
+export interface ProjectAddParams {
+    title: string;
+    notes?: string;
+    area?: ContainerRef;
+    when?: WhenValue;
+    deadline?: IsoDate;
+    todos?: string[];
+}
+export interface ProjectUpdateParams {
+    uuid: string;
+    title?: string;
+    notes?: string;
+    /** Append to the existing notes (newline-joined). Exclusive with notes/prependNotes. */
+    appendNotes?: string;
+    /** Prepend to the existing notes (newline-joined). Exclusive with notes/appendNotes. */
+    prependNotes?: string;
+    when?: WhenValue;
+    /**
+     * `HH:mm` sets a reminder (requires when: today|evening|YYYY-MM-DD in the
+     * same call); null clears it (today/evening only — a dated reminder can
+     * only be changed, not cleared). Same semantics as to-do reminders.
+     */
+    reminder?: ReminderTime | null;
+    deadline?: IsoDate | null;
+}
+export interface ProjectSetTagsParams {
+    uuid: string;
+    /** Full replacement set (an empty list clears all tags). */
+    tags: string[];
+}
+export interface ProjectMoveParams {
+    uuid: string;
+    /** Destination area (uuid or unique name). */
+    area?: ContainerRef;
+    /** Detach from the current area. Exclusive with area. */
+    detach?: boolean;
+}
+export interface ProjectCompleteParams {
+    uuid: string;
+    /**
+     * Open-children policy — REQUIRED, no default: completing a project also
+     * completes its open children.
+     */
+    children: "require-resolved" | "auto-complete";
+}
+export interface ProjectCancelParams {
+    uuid: string;
+    /**
+     * Open-children policy — REQUIRED, no default: canceling a project also
+     * cancels its open children; completed children are untouched.
+     */
+    children: "require-resolved" | "auto-cancel";
+}
+export interface AreaAddParams {
+    title: string;
+    tags?: string[];
+}
+export interface TagAddParams {
+    title: string;
+    /** Existing parent tag title to nest under. */
+    parent?: string;
+}
+export interface NameOrUuidParams {
+    /** uuid or unique case-insensitive title. */
+    target: string;
+}
+export interface AreaUpdateParams {
+    /** uuid or unique case-insensitive title. */
+    target: string;
+    title?: string;
+    /** Full replacement set of EXISTING tag titles. */
+    tags?: string[];
+}
+export interface TagUpdateParams {
+    /** uuid or unique case-insensitive title. */
+    target: string;
+    title?: string;
+    /** Existing tag to nest under. Exclusive with unnest. */
+    parent?: string;
+    /** Un-nest the tag to the root of the hierarchy. Exclusive with parent. */
+    unnest?: boolean;
+    /** Single character to bind. Exclusive with clearShortcut. */
+    shortcut?: string;
+    /** Remove the tag's keyboard shortcut. Exclusive with shortcut. */
+    clearShortcut?: boolean;
+}
+export type ReorderScope = "today" | "evening" | "project" | "area" | "inbox" | "headings" | "someday" | "projects";
+export type ReorderStrategy = "native" | "bounce";
+export interface ReorderParams {
+    scope: ReorderScope;
+    /**
+     * Required for project/area/headings scopes (headings: the project whose
+     * heading rows are being reordered); must be omitted for
+     * today/evening/inbox/someday/projects.
+     */
+    container?: ContainerRef;
+    /**
+     * Desired order, top-first. May be a SUBSET of the scope's members: the
+     * requested uuids are placed at the top in this order and every remaining
+     * member keeps its current relative order below them.
+     */
+    uuids: string[];
+    /**
+     * Omit for the default per scope: native for today/project/area/inbox/
+     * headings/someday (requires allowExperimental), bounce for evening and
+     * projects. Today accepts an explicit "bounce" fallback; evening is
+     * bounce-only; "projects" (top-level sidebar order) is bounce-only — each
+     * project takes a when=someday -> when=anytime round-trip, which
+     * front-inserts it (P8e).
+     */
+    strategy?: ReorderStrategy;
+}
+export type EmptyParams = Record<string, never>;
+export interface OperationParamsMap {
+    "todo.add": TodoAddParams;
+    "todo.update": TodoUpdateParams;
+    "todo.complete": UuidParams;
+    "todo.cancel": UuidParams;
+    "todo.reopen": UuidParams;
+    "todo.move": TodoMoveParams;
+    "todo.set-tags": TodoSetTagsParams;
+    "todo.replace-checklist": TodoReplaceChecklistParams;
+    "todo.delete": UuidParams;
+    "project.add": ProjectAddParams;
+    "project.update": ProjectUpdateParams;
+    "project.complete": ProjectCompleteParams;
+    "project.delete": UuidParams;
+    "area.add": AreaAddParams;
+    "area.delete": NameOrUuidParams;
+    "tag.add": TagAddParams;
+    "tag.delete": NameOrUuidParams;
+    "trash.empty": EmptyParams;
+    reorder: ReorderParams;
+    "todo.duplicate": UuidParams;
+    "area.update": AreaUpdateParams;
+    "tag.update": TagUpdateParams;
+    "project.move": ProjectMoveParams;
+    "todo.restore": UuidParams;
+    "project.duplicate": UuidParams;
+    "project.cancel": ProjectCancelParams;
+    "project.reopen": UuidParams;
+    "project.restore": UuidParams;
+    "project.set-tags": ProjectSetTagsParams;
+    "todo.backdate": TodoBackdateParams;
+    "todo.add-logged": TodoAddLoggedParams;
+}
+/** Explicit confirmations for operations with cascading or permanent effects (never defaulted). */
+export interface Acknowledgements {
+    /** Confirm a wholesale checklist replacement that discards existing items and their checked states. */
+    acknowledgeChecklistReset?: boolean;
+    /** Confirm adding/moving an open item into a completed/canceled project (this reopens the project). */
+    acknowledgeProjectReopen?: boolean;
+    /** Confirm a permanent deletion: area/tag delete and empty-trash skip the Trash entirely. */
+    dangerouslyPermanent?: boolean;
+    /** Confirm that deleting a parent tag permanently deletes ALL of its descendant tags. */
+    acknowledgeTagSubtree?: boolean;
+}

package/dist/write/operations.js

@@ -0,0 +1,34 @@
+export const OPERATION_KINDS = [
+    "todo.add",
+    "todo.update",
+    "todo.complete",
+    "todo.cancel",
+    "todo.reopen",
+    "todo.move",
+    "todo.set-tags",
+    "todo.replace-checklist",
+    "todo.delete",
+    "project.add",
+    "project.update",
+    "project.complete",
+    "project.delete",
+    "area.add",
+    "area.delete",
+    "tag.add",
+    "tag.delete",
+    "trash.empty",
+    "reorder",
+    "todo.duplicate",
+    "area.update",
+    "tag.update",
+    "project.move",
+    "todo.restore",
+    "project.duplicate",
+    "project.cancel",
+    "project.reopen",
+    "project.restore",
+    "project.set-tags",
+    "todo.backdate",
+    "todo.add-logged",
+];
+//# sourceMappingURL=operations.js.map

package/dist/write/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../src/write/operations.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,UAAU;IACV,aAAa;IACb,eAAe;IACf,aAAa;IACb,aAAa;IACb,WAAW;IACX,eAAe;IACf,wBAAwB;IACxB,aAAa;IACb,aAAa;IACb,gBAAgB;IAChB,kBAAkB;IAClB,gBAAgB;IAChB,UAAU;IACV,aAAa;IACb,SAAS;IACT,YAAY;IACZ,aAAa;IACb,SAAS;IACT,gBAAgB;IAChB,aAAa;IACb,YAAY;IACZ,cAAc;IACd,cAAc;IACd,mBAAmB;IACnB,gBAAgB;IAChB,gBAAgB;IAChB,iBAAiB;IACjB,kBAAkB;IAClB,eAAe;IACf,iBAAiB;CACT,CAAC"}

package/dist/write/pipeline.d.ts

@@ -0,0 +1,90 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { AuditWriter } from "../audit/log.ts";
+import type { DisruptionTier, ThingsApiConfig } from "../config.ts";
+import type { FingerprintStatus } from "../db/fingerprint.ts";
+import { type EnvironmentTracker } from "./environment.ts";
+import { type LikelyCause } from "./failure-hints.ts";
+import { type HazardId } from "./guards.ts";
+import type { Acknowledgements, OperationKind, OperationParamsMap } from "./operations.ts";
+import type { VectorId, WriteVector } from "./vectors/types.ts";
+import { type DeltaSpec } from "./verify/delta.ts";
+import { type PollerDeps } from "./verify/poller.ts";
+export interface WriteOptions extends Acknowledgements {
+    /** Caps vector selection; defaults from the config profile. */
+    maxDisruption?: DisruptionTier;
+    /** Force a specific vector (must still be validated + support the op). */
+    vector?: VectorId;
+    verifyTimeoutMs?: number;
+    /** Return the plan without executing (nothing is audited). */
+    dryRun?: boolean;
+    /** Audit attribution. */
+    actor?: string;
+}
+export interface MutationPlan {
+    op: OperationKind;
+    vector: VectorId;
+    tier: DisruptionTier;
+    invocation: string;
+    expectedDelta: DeltaSpec;
+    hazardsChecked: HazardId[];
+}
+export type MutationResult = {
+    kind: "ok";
+    op: OperationKind;
+    uuid: string | null;
+    observed: Record<string, unknown> | null;
+    vector: VectorId;
+    tier: DisruptionTier;
+    /** Advisory notes (e.g. a changed environment tuple — consent may re-prompt later). */
+    warnings?: string[];
+} | {
+    kind: "verify-failed";
+    op: OperationKind;
+    reason: "timeout" | "mismatch" | "silent-noop";
+    expected: DeltaSpec;
+    observed: Record<string, unknown> | null;
+    detail: string;
+    /** Advisory attribution when the failure signals point somewhere. */
+    likelyCause?: LikelyCause;
+    hint?: string;
+} | {
+    kind: "blocked";
+    op: OperationKind;
+    reason: "hazard" | "disruption-tier" | "drift" | "lock" | "environment";
+    hazard?: HazardId;
+    detail: string;
+    remediation: string;
+    likelyCause?: LikelyCause;
+} | {
+    kind: "unsupported";
+    op: OperationKind;
+    considered: {
+        vector: VectorId;
+        why: string;
+    }[];
+} | {
+    kind: "dry-run";
+    op: OperationKind;
+    plan: MutationPlan;
+};
+export interface WriteDeps {
+    db: DatabaseSync;
+    vectors: WriteVector[];
+    config: ThingsApiConfig;
+    audit: AuditWriter;
+    fingerprint(): FingerprintStatus;
+    lockPath: string;
+    /** Injectable for tests/lab: returns true when Things is up (launching if needed). */
+    ensureRunning?: (alreadyRunning: boolean) => Promise<boolean>;
+    isAppRunning?: () => boolean;
+    /** Canary seam: does the installed sdef still declare the private command? */
+    sdefProbe?: () => boolean;
+    /** Consent-churn tripwire: tuple recorded per verified mutation (client wires the default). */
+    environment?: EnvironmentTracker;
+    now?: () => Date;
+    poller?: PollerDeps;
+    pkgVersion?: string;
+}
+export declare function readAuthToken(db: DatabaseSync): string | null;
+export declare function runMutation<K extends OperationKind>(deps: WriteDeps, op: K, params: OperationParamsMap[K], options?: WriteOptions): Promise<MutationResult>;
+export declare function fingerprintLabel(fp: FingerprintStatus, config: ThingsApiConfig): "ok" | "drift" | "user-accepted" | "unknown";