orbitmap 0.3.0 → 0.4.1

package/dist/adapters/cloud.d.ts

@@ -0,0 +1,367 @@
+import { type OrbitMapConfig } from '../config.js';
+import type { WorkspaceAdapter } from './types.js';
+export declare class CloudAdapter implements WorkspaceAdapter {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly area?;
+    /**
+     * Task reference → uuid, for the lifetime of this adapter. A command that touches the same
+     * task twice (`dep add TS-a TS-b` resolves two, `status` then reads back) pays for one
+     * `/tasks/by-number/{n}` lookup per distinct reference, not per call site.
+     */
+    private readonly taskIdCache;
+    constructor(apiKey: string, area?: string, apiUrl?: string);
+    private request;
+    getContext(areaId?: string): Promise<unknown>;
+    /**
+     * The area this client was constructed with (`--area` → `ORBITMAP_AREA` →
+     * `.orbitmap/link.json` → nearest project `.orbitmap/config.json` that sets `area` →
+     * global config `area` (deprecated) — the one ladder, `resolveArea` in
+     * `workspace-resolve.ts`, applied by `createClient`). No request is made.
+     */
+    getDefaultArea(): Promise<string | undefined>;
+    getTasks(options?: {
+        status?: string;
+        priority?: string;
+        areaId?: string;
+        orbit?: string;
+    }): Promise<unknown>;
+    /**
+     * Resolve any task reference — uuid, `TS-uw9yh5` or the bare code — to the uuid the task
+     * endpoints require. A uuid costs no extra request; see `id-resolve.ts` for why tasks need
+     * this at all when every other entity resolves its prefix server-side.
+     */
+    private taskId;
+    getTask(taskId: string): Promise<unknown>;
+    getTaskByNumber(taskNumber: string): Promise<unknown>;
+    startTask(taskId?: string): Promise<unknown>;
+    updateTaskStatus(taskId: string, status?: string, deliveryStatus?: string | null, _force?: boolean): Promise<unknown>;
+    createSubtasks(parentId: string, subtasks: Array<{
+        title: string;
+        description?: string;
+        priority?: string;
+        estimated_effort?: string;
+    }>): Promise<unknown>;
+    createTask(data: {
+        title: string;
+        description?: string;
+        status?: string;
+        priority?: string;
+        agent_instructions?: string;
+        branch_name?: string;
+        estimated_effort?: string;
+        agent_id?: string;
+        area_id?: string;
+        source_issue_id?: string;
+        intent_id?: string;
+        orbit_id?: string | null;
+    }): Promise<unknown>;
+    editTaskContent(taskId: string, data: {
+        title?: string;
+        description?: string;
+        agent_instructions?: string;
+    }): Promise<unknown>;
+    assignTask(taskId: string, assignment: {
+        agent_id: string;
+    } | {
+        user_id: number;
+    }): Promise<unknown>;
+    assignItem(objectType: 'task' | 'issue' | 'idea' | 'intent', objectId: string, assignment: {
+        agent_id: string;
+    } | {
+        user_id: number;
+    }): Promise<unknown>;
+    addTaskDependency(taskId: string, data: {
+        target_task_id: string;
+        type?: string;
+        note?: string;
+    }): Promise<unknown>;
+    removeTaskDependency(taskId: string, targetTaskId: string, type?: string): Promise<unknown>;
+    logWork(taskId: string, type: string, content: string, metadata?: Record<string, unknown>): Promise<unknown>;
+    getDocuments(options?: {
+        type?: string;
+        search?: string;
+        areaId?: string;
+    }): Promise<unknown>;
+    getDocument(idOrSlug: string, mode?: 'inline' | 'file', options?: {
+        full?: boolean;
+        section?: string;
+    }): Promise<unknown>;
+    importDocument(data: {
+        title: string;
+        type: string;
+        content: string;
+        source_path?: string;
+        context?: string;
+        workspace_id?: string;
+    }): Promise<unknown>;
+    updateDocument(idOrSlug: string, content: string, changelog?: string): Promise<unknown>;
+    patchDocument(idOrSlug: string, operations: Array<Record<string, unknown>>, baseVersion: number, changelog?: string): Promise<unknown>;
+    requestUploadUrl(data: {
+        title: string;
+        type: string;
+        filename?: string;
+        source_path?: string;
+        context?: string;
+        workspace_id?: string;
+    }): Promise<{
+        data: {
+            upload_id: string;
+            document_id: string;
+            presigned_url: string;
+            storage_path: string;
+            expires_at: string;
+        };
+    }>;
+    confirmUpload(uploadId: string): Promise<{
+        data: {
+            document_id: string;
+            slug: string;
+            imported: boolean;
+        };
+    }>;
+    requestUpdateUploadUrl(idOrSlug: string, changelog?: string): Promise<{
+        data: {
+            upload_id: string;
+            document_id: string;
+            version: number;
+            presigned_url: string;
+            storage_path: string;
+            expires_at: string;
+        };
+    }>;
+    confirmUpdateUpload(idOrSlug: string, uploadId: string): Promise<{
+        data: {
+            document_id: string;
+            version: number;
+            updated: boolean;
+        };
+    }>;
+    uploadToPresignedUrl(presignedUrl: string, filePath: string, onProgress?: (bytesUploaded: number, totalBytes: number) => void): Promise<void>;
+    /**
+     * Attempts presigned URL upload for a new document.
+     * Returns null if the endpoint is not available (404), signaling caller to fall back.
+     */
+    presignedImport(filePath: string, data: {
+        title: string;
+        type: string;
+        source_path?: string;
+        context?: string;
+        workspace_id?: string;
+    }, onProgress?: (bytesUploaded: number, totalBytes: number) => void): Promise<{
+        data: {
+            document_id: string;
+            slug: string;
+            imported: boolean;
+        };
+        upload_method: string;
+    } | null>;
+    /**
+     * Attempts presigned URL upload for updating a document.
+     * Returns null if the endpoint is not available (404), signaling caller to fall back.
+     */
+    presignedUpdate(idOrSlug: string, filePath: string, changelog?: string, onProgress?: (bytesUploaded: number, totalBytes: number) => void): Promise<{
+        data: {
+            document_id: string;
+            version: number;
+            updated: boolean;
+        };
+        upload_method: string;
+    } | null>;
+    shareDocument(documentId: string, areaId: string, agentIds?: string[]): Promise<unknown>;
+    unshareDocument(documentId: string, areaId: string): Promise<unknown>;
+    setDocumentVisibility(documentId: string, areaId: string, agentIds: string[]): Promise<unknown>;
+    getAreas(): Promise<unknown>;
+    getAreaMembers(areaId: string): Promise<unknown>;
+    getAreaOverview(areaId: string): Promise<unknown>;
+    createArea(data: {
+        name: string;
+        description?: string;
+        slug?: string;
+        workspace_id?: string;
+    }): Promise<unknown>;
+    registerIssue(data: {
+        title: string;
+        description: string;
+        severity?: string;
+        related_task_id?: string;
+        intent_id?: string;
+    }): Promise<unknown>;
+    listIssues(options?: {
+        status?: string;
+        severity?: string;
+        limit?: string;
+    }): Promise<unknown>;
+    getIssue(idOrNumber: string): Promise<unknown>;
+    getIssueByNumber(issueNumber: string): Promise<unknown>;
+    resolveIssueByNumber(issueNumber: string, data: {
+        status: string;
+        resolution?: string;
+        resolved_by_task_id?: string;
+    }): Promise<unknown>;
+    resolveIssue(idOrNumber: string, data: {
+        status: string;
+        resolution?: string;
+        resolved_by_task_id?: string;
+    }): Promise<unknown>;
+    updateIssueStatus(idOrNumber: string, data: {
+        status: string;
+        resolution?: string;
+        resolved_task_id?: string;
+    }): Promise<unknown>;
+    updateIssueStatusByNumber(issueNumber: string, data: {
+        status: string;
+        resolution?: string;
+        resolved_task_id?: string;
+    }): Promise<unknown>;
+    logVibe(data: {
+        content: string;
+        type: string;
+        title?: string;
+        task_id?: string;
+    }): Promise<unknown>;
+    listVibes(options?: {
+        type?: string;
+        since?: string;
+        limit?: string;
+    }): Promise<unknown>;
+    getVibe(id: string): Promise<unknown>;
+    updateVibe(id: string, data: {
+        type?: string;
+        title?: string;
+        content?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<unknown>;
+    listIdeas(options?: {
+        status?: string;
+        priority?: string;
+        limit?: string;
+    }): Promise<unknown>;
+    getIdea(idOrNumber: string): Promise<unknown>;
+    getIdeaByNumber(ideaNumber: string): Promise<unknown>;
+    createIdea(data: {
+        content: string;
+        title?: string;
+        priority?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<unknown>;
+    updateIdeaStatus(idOrNumber: string, data: {
+        status: string;
+    }): Promise<unknown>;
+    updateIdeaStatusByNumber(ideaNumber: string, data: {
+        status: string;
+    }): Promise<unknown>;
+    listOrbits(options?: {
+        areaId?: string;
+        workspaceId?: string;
+    }): Promise<unknown>;
+    getOrbit(idOrSlug: string): Promise<unknown>;
+    createOrbit(data: {
+        name: string;
+        description?: string;
+        color?: string;
+        area_ids?: string[];
+    }): Promise<unknown>;
+    updateOrbit(idOrSlug: string, data: {
+        name?: string;
+        description?: string;
+        status?: string;
+        color?: string;
+    }): Promise<unknown>;
+    getOrbitItems(orbitIdOrSlug: string, options?: {
+        type?: string;
+    }): Promise<unknown>;
+    orbitAttach(orbitIdOrSlug: string, data: {
+        object_type: string;
+        object_id: string;
+        note?: string;
+    }): Promise<unknown>;
+    orbitDetach(orbitIdOrSlug: string, data: {
+        object_type: string;
+        object_id: string;
+    }): Promise<unknown>;
+    addOrbitArea(orbitIdOrSlug: string, areaId: string): Promise<unknown>;
+    removeOrbitArea(orbitIdOrSlug: string, areaId: string): Promise<unknown>;
+    addOrbitDependency(orbitIdOrSlug: string, data: {
+        target_orbit_id: string;
+        note?: string;
+    }): Promise<unknown>;
+    listIntents(options?: {
+        status?: string;
+        limit?: string;
+    }): Promise<unknown>;
+    getIntent(idOrNumber: string): Promise<unknown>;
+    createIntent(data: {
+        name: string;
+        outcome?: string;
+        status?: string;
+        area_id?: string;
+    }): Promise<unknown>;
+    updateIntent(idOrNumber: string, data: {
+        name?: string;
+        outcome?: string;
+        status?: string;
+    }): Promise<unknown>;
+    linkIntentItem(idOrNumber: string, data: {
+        item_type: string;
+        item_id: string;
+    }): Promise<unknown>;
+    unlinkIntentItem(idOrNumber: string, data: {
+        item_type: string;
+        item_id: string;
+    }): Promise<unknown>;
+    setIntentOrbit(idOrNumber: string, orbitId: string | null): Promise<unknown>;
+    listMissions(options?: {
+        status?: string;
+        limit?: string;
+    }): Promise<unknown>;
+    getMission(idOrNumber: string): Promise<unknown>;
+    createMission(data: {
+        name: string;
+        description?: string;
+        outcome?: string;
+        end_date?: string;
+        area_id?: string;
+    }): Promise<unknown>;
+    updateMission(idOrNumber: string, data: {
+        name?: string;
+        description?: string;
+        outcome?: string;
+        end_date?: string;
+    }): Promise<unknown>;
+    setMissionStatus(idOrNumber: string, data: {
+        status: string;
+        move_target_mission_id?: string;
+    }): Promise<unknown>;
+    linkMissionItem(idOrNumber: string, data: {
+        item_type: string;
+        item_id: string;
+    }): Promise<unknown>;
+    unlinkMissionItem(idOrNumber: string, data: {
+        item_type: string;
+        item_id: string;
+    }): Promise<unknown>;
+    getWorkPrompt(): Promise<unknown>;
+    getImportDocsPrompt(): Promise<unknown>;
+}
+/** Backwards-compatible alias for the pre-adapter class name. */
+export { CloudAdapter as OrbitMapClient };
+export interface CreateClientOptions {
+    /**
+     * Area already produced by the one area ladder (`resolveWorkspaceContext`). Pass it
+     * whenever the caller has it — `createAdapter` always does — so the ladder is walked
+     * once per command instead of twice.
+     */
+    area?: string;
+    /** Global config the caller already loaded, to avoid a second read of the same file. */
+    config?: OrbitMapConfig;
+}
+/**
+ * Build a {@link CloudAdapter} from the resolved credentials and area.
+ *
+ * There is exactly **one** area ladder — `resolveArea` in `workspace-resolve.ts` (ADR
+ * 0002 §2). `resolveAuth` used to carry a second, shorter copy of it that was missing the
+ * `link.json` rung, so a cloud project with a `.orbitmap/link.json` got a different area
+ * depending on which entry point it came through.
+ */
+export declare function createClient(explicitArea?: string, options?: CreateClientOptions): Promise<CloudAdapter>;