things-api 0.10.0 → 0.12.0

package/dist/client.d.ts

@@ -4,7 +4,8 @@
  */
 import type { AuditWriter } from "./audit/log.ts";
 import { type ThingsApiConfig } from "./config.ts";
-import { type GroupedTruncation, type Truncation } from "./contracts.ts";
+import { type ClockMeta } from "./model/clock.ts";
+import { type Truncation } from "./contracts.ts";
 import { type FingerprintStatus, type SchemaStatus } from "./db/fingerprint.ts";
 import type { AnyTask, Area, Project, Tag } from "./model/entities.ts";
 import { type AreaView } from "./read/area-view.ts";
@@ -12,13 +13,16 @@ import { type ProjectView } from "./read/project-view.ts";
 import { type Snapshot } from "./read/snapshot.ts";
 import { type ShowTarget } from "./read/show-target.ts";
 import { type ChangedItem, type InboxFilter, type LiteSearchResult, type ListItem, type LogbookFilter, type SearchOptions, type SearchResultItem, type SidebarSection, type SomedayFilter, type TodayFilter, type TodayView, type UpcomingFilter, type ViewFilter } from "./read/views.ts";
-import type { AreaAddParams, AreaUpdateParams, ContainerRef, ProjectCancelParams, OperationKind, OperationParamsMap, ProjectAddParams, ProjectCompleteParams, ProjectCreateRepeatingParams, ProjectUpdateParams, RepeatRuleParams, ReorderParams, TagAddParams, TagUpdateParams, HeadingArchiveParams, HeadingUnarchiveParams, TodoAddLoggedParams, TodoAddParams, TodoBackdateParams, TodoMoveParams, TodoUpdateParams } from "./write/operations.ts";
+import { type AreaScopedRead, type ViewFilterMeta } from "./read/area-filter.ts";
+import { type ScopeMeta } from "./read/scope.ts";
+import type { AreaAddParams, AreaUpdateParams, ContainerRef, ProjectCancelParams, OperationKind, OperationParamsMap, ProjectAddParams, ProjectCompleteParams, ProjectAddRepeatingParams, ProjectUpdateParams, RepeatRuleParams, ReorderParams, TagAddParams, TagUpdateParams, HeadingArchiveParams, HeadingUnarchiveParams, HeadingPlacement, TodoAddLoggedParams, TodoAddParams, TodoBackdateParams, TodoMoveParams, TodoUpdateParams } from "./write/operations.ts";
 import { type MutationResult, type WriteOptions } from "./write/pipeline.ts";
-import { type BatchItemResult, type BatchOp, type BatchOptions } from "./write/batch.ts";
+import { type BatchItemResult, type BatchOp, type BatchOptions, type BatchResult } from "./write/batch.ts";
 import { type EnvironmentTracker } from "./write/environment.ts";
 import { type HeadingArchiveResult, type HeadingUnarchiveResult } from "./write/heading.ts";
 import type { ChecklistEdit } from "./write/checklist.ts";
 import { type ReorderResult } from "./write/reorder.ts";
+import { type MoveResult, type ProjectMoveRequest, type ReorderRequest, type TodoMoveRequest } from "./write/move.ts";
 import { type UndoItemResult, type UndoOptions } from "./write/undo.ts";
 import { type ProjectReopenOptions, type ProjectReopenResult } from "./write/reopen.ts";
 import type { WriteVector } from "./write/vectors/types.ts";
@@ -27,10 +31,26 @@ export interface OpenOptions {
     dbPath?: string;
     /** Injectable clock (tests, pinned-clock lab runs). */
     now?: () => Date;
+    /**
+     * Default consumer IANA zone for every date boundary (tests / explicit
+     * embedding). Overrides `THINGS_TZ` from the environment; a per-read `zone`
+     * still overrides this. Absent uses `THINGS_TZ`, else the host zone.
+     */
+    zone?: string;
     /** Injectable write vectors (tests: FakeVector; lab: probe vectors). */
     vectors?: WriteVector[];
     /** Env for config/state-dir resolution (tests). */
     env?: NodeJS.ProcessEnv;
+    /**
+     * Container scope: a ref (uuid / uuid-prefix / unique area or project name)
+     * that jails this client to one container — reads see only in-scope rows,
+     * writes are refused (or redirected) outside it, and out-of-scope refs are
+     * indistinguishable from nonexistent ones. This is the MCP `--scope` flag's
+     * entry point and OUTRANKS `THINGS_API_SCOPE` / the stored `scope` config
+     * (the launcher's boundary must not be agent-overridable). Unresolvable →
+     * fail closed (ScopeResolutionError). See docs/design/container-scope.md.
+     */
+    scope?: string;
     /** Test seams for the mutation pipeline. */
     writeOverrides?: {
         ensureRunning?: (alreadyRunning: boolean) => Promise<boolean>;
@@ -50,6 +70,15 @@ export interface ListBound {
     limit?: number | null;
     all?: boolean;
 }
+/**
+ * Per-read consumer-zone override (the MCP `tz` argument). Overrides the
+ * process default (`THINGS_TZ` / the `OpenOptions.zone` embedding / the host)
+ * for THIS read only. Absent uses that default; an invalid zone is rejected by
+ * the calling surface before it reaches here.
+ */
+export interface ClockScopedRead {
+    zone?: string;
+}
 /**
  * Per-block caps for a bounded GROUPED view (anytime/someday) or the composite
  * area card. Each omitted cap falls back to the view's own default (anytime:
@@ -65,6 +94,8 @@ export interface GroupedBound {
 export interface BoundedList<T> {
     items: T[];
     truncation: Truncation;
+    /** The active `area` scope, when one was applied (surfaced as `meta.filter`). */
+    filter?: ViewFilterMeta;
 }
 /**
  * A bounded Today view: `view` is the shown split (capped in render order —
@@ -74,24 +105,49 @@ export interface BoundedList<T> {
 export interface BoundedTodayView {
     view: TodayView;
     truncation: Truncation;
+    /** The active `area` scope, when one was applied (surfaced as `meta.filter`). */
+    filter?: ViewFilterMeta;
 }
 /**
  * A bounded sidebar catalogue (anytime/someday): `view` is the
- * per-block-capped sections and `grouped` the per-block counts (identity-
- * carrying, project blocks nested under their area/loose block).
+ * per-block-capped sections and `truncation` the unified completeness metadata
+ * whose `blocks` carry the identity-bearing per-block counts (project blocks
+ * nested under their area/loose block).
  */
 export interface BoundedSectionsView {
     view: SidebarSection[];
-    grouped: GroupedTruncation;
+    truncation: Truncation;
+    /** The active `area` scope, when one was applied (surfaced as `meta.filter`). */
+    filter?: ViewFilterMeta;
 }
-/** A bounded composite area card: the per-section-capped view and the per-block counts. */
+/** A bounded composite area card: the per-section-capped view and the per-block truncation. */
 export interface BoundedAreaView {
     view: AreaView;
-    grouped: GroupedTruncation;
+    truncation: Truncation;
+    /**
+     * A resolution disclosure — present ONLY on the `loose` pseudo-area read when
+     * a real area shadows the reserved word (names it, by uuid, for targeting).
+     * Surfaced by the consumers as a `meta.warnings` advisory.
+     */
+    notice?: string;
+    /**
+     * The live count of the area's logged rows (subtree-inclusive, past the
+     * log-move boundary — the population `things logbook --area <ref>` returns).
+     * Present for a real area, absent for the `loose` pseudo-area. A DISPLAY
+     * sibling of `view`: it feeds the TTY card's logbook footer and never enters
+     * the JSON area-view `data`.
+     */
+    loggedCount?: number;
 }
 export interface ThingsClient {
     dbPath: string;
     config: ThingsApiConfig;
+    /**
+     * The active container scope (pinned at open), or undefined when unscoped.
+     * The consumer surfaces surface it as the additive `meta.scope` and the
+     * one-line "scoped to …" banner so the jail is never silently on.
+     */
+    scope?: ScopeMeta;
     fingerprint(): FingerprintStatus;
     /**
      * The read-path schema check: the cached fingerprint comparison reduced to a
@@ -100,6 +156,30 @@ export interface ThingsClient {
      * once per client, so it costs nothing after the first read.
      */
     schemaStatus(): SchemaStatus;
+    /**
+     * The additive `meta.clock` honesty field for this client's effective clock,
+     * or undefined when the host clock is in force (no `THINGS_TZ`/`THINGS_NOW`
+     * and no per-read override). `zoneOverride` reflects a per-read zone (the MCP
+     * `tz` argument) so the reported `today` matches what that read computed.
+     */
+    clockMeta(zoneOverride?: string): ClockMeta | undefined;
+    /**
+     * Reference resolvers the consumer surfaces (CLI/MCP) call to turn a project
+     * ref + heading selector into uuids before invoking a heading verb. Both
+     * throw {@link ReferenceResolutionError} (uuid candidates on ambiguity),
+     * scope-aware when a container scope is active. `heading` shares the one
+     * heading-selector core (title | uuid | empty-string literal; no ordinal).
+     */
+    resolve: {
+        project(ref: string): {
+            uuid: string;
+            title: string;
+        };
+        heading(projectUuid: string, sel: string): {
+            uuid: string;
+            title: string;
+        };
+    };
     read: {
         /**
          * The Today list (Today + This Evening split) with the sidebar badge,
@@ -107,27 +187,29 @@ export interface ThingsClient {
          * first, then This Evening. `all`/`limit: null` returns every row; the
          * `truncation` metadata carries the per-section (`today`/`evening`) counts.
          */
-        today(options?: TodayFilter & ListBound): BoundedTodayView;
+        today(options?: TodayFilter & ListBound & ClockScopedRead & AreaScopedRead): BoundedTodayView;
         /** Inbox captures, bounded (default 50). */
-        inbox(options?: InboxFilter & ListBound): BoundedList<ListItem>;
+        inbox(options?: InboxFilter & ListBound & ClockScopedRead): BoundedList<ListItem>;
         /**
          * Anytime catalogue: every area header and project row is always present;
          * `areaLimit` (default 30) caps each area/loose block, `projectLimit`
-         * (default 3) each project block. `all` lifts both.
+         * (default 3) each project block. `all` lifts both. `area` restricts the
+         * catalogue to one area (its rows survive; the rest drop).
          */
-        anytime(options?: ViewFilter & GroupedBound): BoundedSectionsView;
+        anytime(options?: ViewFilter & GroupedBound & ClockScopedRead & AreaScopedRead): BoundedSectionsView;
         /** Future-scheduled items in date order, bounded (default 50). */
-        upcoming(options?: UpcomingFilter & ListBound): BoundedList<ListItem>;
+        upcoming(options?: UpcomingFilter & ListBound & ClockScopedRead & AreaScopedRead): BoundedList<ListItem>;
         /**
          * Someday catalogue: `areaLimit` (default 30) caps each group; with
          * `activeProjectItems`, `projectLimit` (default: every item) caps each
-         * active project's trailing child list. `all` lifts both.
+         * active project's trailing child list. `all` lifts both. `area` restricts
+         * the catalogue to one area.
          */
-        someday(options?: SomedayFilter & GroupedBound): BoundedSectionsView;
+        someday(options?: SomedayFilter & GroupedBound & ClockScopedRead & AreaScopedRead): BoundedSectionsView;
         /** Logbook entries (most recent first), bounded (default 50). */
-        logbook(options?: Omit<LogbookFilter, "limit"> & ListBound): BoundedList<ListItem>;
+        logbook(options?: Omit<LogbookFilter, "limit"> & ListBound & ClockScopedRead): BoundedList<ListItem>;
         /** Trashed items (most recently modified first), bounded (default 50). */
-        trash(options?: ListBound): BoundedList<ListItem>;
+        trash(options?: ListBound & ClockScopedRead): BoundedList<ListItem>;
         /**
          * Projects in sidebar order. LATER (someday + future-scheduled) projects
          * are excluded by default — `later: true` appends them after the active
@@ -137,7 +219,7 @@ export interface ThingsClient {
             areaUuid?: string;
             later?: boolean;
             overdue?: boolean;
-        } & ViewFilter): Project[];
+        } & ViewFilter & ClockScopedRead): Project[];
         /**
          * Composite project view. Targets by uuid, unique name, or uuid prefix.
          * `overdue: true` keeps only child to-dos whose own deadline is overdue
@@ -146,7 +228,7 @@ export interface ThingsClient {
          * inherited from this project are ignored). Any content scope collapses
          * headings left with no surviving child.
          */
-        projectView(ref: string, options?: ViewFilter): ProjectView;
+        projectView(ref: string, options?: ViewFilter & ClockScopedRead): ProjectView;
         /**
          * Composite area view: direct to-dos, projects in sidebar order, later,
          * logged. `overdue: true` keeps only the loose to-dos AND child projects
@@ -157,11 +239,11 @@ export interface ThingsClient {
          * always survive, routed to the card's later sections); `all` lifts both.
          * The `grouped` metadata carries the per-section counts.
          */
-        areaView(ref: string, options?: ViewFilter & GroupedBound): BoundedAreaView;
+        areaView(ref: string, options?: ViewFilter & GroupedBound & ClockScopedRead): BoundedAreaView;
         areas(): Area[];
         tags(): Tag[];
         /** Title/notes substring search, ranked, bounded (default 50). */
-        search(query: string, options?: SearchOptions): BoundedList<SearchResultItem>;
+        search(query: string, options?: SearchOptions & ClockScopedRead): BoundedList<SearchResultItem>;
         /**
          * Did-you-mean fallback: case-insensitive title-only substring match over
          * areas/projects/to-dos (open + untrashed), ordered and capped. `type`
@@ -174,7 +256,7 @@ export interface ThingsClient {
         /** Rows created/modified since a moment — incl. trashed/logged/templates — bounded (default 50). */
         changes(options: {
             since: Date;
-        } & ListBound): BoundedList<ChangedItem>;
+        } & ListBound & ClockScopedRead): BoundedList<ChangedItem>;
         byUuid(uuid: string): AnyTask | null;
         /**
          * Classify a loose reference (uuid, >=6-char prefix, share link, or
@@ -193,6 +275,23 @@ export interface ThingsClient {
         cancelTodo(uuid: string, options?: WriteOptions): Promise<MutationResult>;
         reopenTodo(uuid: string, options?: WriteOptions): Promise<MutationResult>;
         moveTodo(uuid: string, dest: Omit<TodoMoveParams, "uuid">, options?: WriteOptions): Promise<MutationResult>;
+        /**
+         * Move one or more to-dos as an ordered block (spec §4). Give a destination
+         * (--to-project / --to-heading / --to-area / --no-heading / --loose) and an
+         * optional position (first/last/before/after), or a position alone to
+         * reposition items already sharing a container. Membership always succeeds;
+         * placement is guaranteed top-of-bucket only where a reorder protocol exists
+         * (the result states the placement class). Compiles onto the todo.move +
+         * reorder wire primitives — no new op kind.
+         */
+        moveTodos(request: TodoMoveRequest, options?: WriteOptions): Promise<MoveResult>;
+        /**
+         * Reorder to-dos IN PLACE within their shared container+bucket (spec §4).
+         * Bare (no position) assembles the movees as a contiguous block at the
+         * earliest movee's current slot, in argument order. Cross-container operands
+         * fail closed.
+         */
+        reorderTodos(request: ReorderRequest, options?: WriteOptions): Promise<MoveResult>;
         /** Replace the full tag set (an empty list clears all tags). */
         setTags(uuid: string, tags: string[], options?: WriteOptions): Promise<MutationResult>;
         /** Merge: current direct tags + new ones, then replace. */
@@ -225,11 +324,43 @@ export interface ThingsClient {
         /**
          * Create a heading inside an EXISTING project; the new heading's uuid is
          * on the result. Delivered through the Things proxy shortcuts (run
-         * `things setup shortcuts` once first).
+         * `things setup shortcuts` once first). A `placement` positions the new
+         * heading among the project's headings via a native `move-heading` leg
+         * (requires allow-experimental); omitted, it appends. Anchor uuids in the
+         * placement are resolved by the caller.
          */
-        createHeading(project: ContainerRef, title: string, options?: WriteOptions): Promise<MutationResult>;
+        addHeading(project: ContainerRef, title: string, placement?: HeadingPlacement, options?: WriteOptions): Promise<MutationResult>;
         /** Rename a heading in place (works on archived headings too). */
         renameHeading(uuid: string, title: string, options?: WriteOptions): Promise<MutationResult>;
+        /**
+         * Reposition one or more of a project's headings as an ordered block
+         * (selection order = resulting order; children follow). `headings` and the
+         * placement anchors are resolved heading uuids. Native reorder wire
+         * (requires allow-experimental).
+         */
+        moveHeading(project: ContainerRef, headings: string[], placement: HeadingPlacement, options?: WriteOptions): Promise<MutationResult>;
+        /**
+         * Relocate ONE heading (with its children) to a DIFFERENT project — the
+         * cross-project move the within-project `moveHeading` reorder cannot express
+         * (HEADXPROJ). GUI-only: drives the heading row's `…` ellipsis → Move… →
+         * keyboard-driven project picker, so it needs `ui.enabled` + the
+         * `dangerouslyDriveGui` acknowledgement. `heading` is an exact title or uuid
+         * within `project`; both same-titled source headings AND a same-titled
+         * destination project fail closed (the drive addresses by title). No wired
+         * undo — it is app-reversible by moving it back.
+         */
+        moveHeadingToProject(project: ContainerRef, heading: string, toProject: ContainerRef, options?: WriteOptions): Promise<MutationResult>;
+        /**
+         * Dissolve a heading: remove it while its to-dos SURVIVE as direct children
+         * of the project (heading→NULL, keeping their order) — NOT trashed (DISS1).
+         * This is the OPPOSITE of a delete cascade (contrast the Shortcuts heading
+         * delete, P12, which trashes the children). GUI-only (heading row's `…`
+         * ellipsis → Delete), so it needs `ui.enabled` + `dangerouslyDriveGui`. Fails
+         * closed on a title shared by another heading in the project. No wired undo —
+         * the children are kept, so re-create the heading and move them back to
+         * reverse. `uuid` is the heading.
+         */
+        dissolveHeading(uuid: string, options?: WriteOptions): Promise<MutationResult>;
         /**
          * Archive a heading (the UI's Archive — it leaves the active project
          * view, reversibly). With open children the policy is mandatory:
@@ -255,6 +386,14 @@ export interface ThingsClient {
         moveProject(uuid: string, area: ContainerRef, options?: WriteOptions): Promise<MutationResult>;
         /** Detach a project from its current area. */
         detachProject(uuid: string, options?: WriteOptions): Promise<MutationResult>;
+        /**
+         * Move one or more projects as an ordered block (spec §4/§5): --to-area, or
+         * --no-area to leave the area, plus an optional position — or a position
+         * alone to reorder them among their siblings.
+         */
+        moveProjects(request: ProjectMoveRequest, options?: WriteOptions): Promise<MoveResult>;
+        /** Reorder projects IN PLACE among their siblings (spec §4). */
+        reorderProjects(request: ReorderRequest, options?: WriteOptions): Promise<MoveResult>;
         /** Cancel a project — open children are canceled with it, so the children policy is mandatory. */
         cancelProject(uuid: string, policy: Pick<ProjectCancelParams, "children">, options?: WriteOptions): Promise<MutationResult>;
         /**
@@ -284,7 +423,7 @@ export interface ThingsClient {
          * two-key gated, same as makeRepeatingProject). Give an `area` to place it,
          * or omit it to create in Someday. The new template's uuid is on the result.
          */
-        createRepeatingProject(params: ProjectCreateRepeatingParams, options?: WriteOptions): Promise<MutationResult>;
+        addRepeatingProject(params: ProjectAddRepeatingParams, options?: WriteOptions): Promise<MutationResult>;
         /** Replace a project's full tag set (an empty list clears all tags). */
         setProjectTags(uuid: string, tags: string[], options?: WriteOptions): Promise<MutationResult>;
         /** Merge: current project tags + new ones, then replace. */
@@ -303,9 +442,14 @@ export interface ThingsClient {
         reorder(params: ReorderParams, options?: WriteOptions): Promise<ReorderResult>;
         /**
          * Run N ops sequentially and independently — no transactions, a failure
-         * does not roll back earlier ops. Per-op results.
+         * does not roll back earlier ops. Per-op results stream through `onResult`;
+         * the resolved {@link BatchResult} adds the temp-id → uuid mapping and the
+         * batch-level undo token (undo the whole submission as one unit). An op may
+         * carry a `tempId` (a handle bound to its created uuid, referenceable as
+         * `"$name"` by a later op) and/or an `opId` (idempotency id — a resubmitted
+         * op with a matching applied id is skipped, not re-created).
          */
-        batch(ops: BatchOp[], options?: BatchOptions, onResult?: (result: BatchItemResult) => void): Promise<BatchItemResult[]>;
+        batch(ops: BatchOp[], options?: BatchOptions, onResult?: (result: BatchItemResult) => void): Promise<BatchResult>;
         /**
          * Undo changes made through this client, newest first, by applying the
          * inverse change. Selection: `last` trailing changes (default 1), narrowed