openworkgraph 0.2.12

package/dist/resources.d.ts

@@ -0,0 +1,246 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { BlobStore } from './blob-store.js';
+import type { PreparedBlob } from './blob-store.js';
+export interface ResourceScope {
+    projectId: string;
+    serviceId?: string;
+}
+export interface CanvasScope extends ResourceScope {
+    graphId: string;
+}
+export type LibraryTarget = ResourceScope & {
+    name: string;
+} & ({
+    mode: 'new';
+} | {
+    mode: 'update';
+    assetId: string;
+    expectedVersion: number;
+});
+export type UploadTarget = LibraryTarget | (CanvasScope & {
+    name: string;
+    mode: 'canvas';
+});
+export interface UploadStart extends ResourceScope {
+    name: string;
+    bytes: number;
+    mime: string;
+    sha256?: string;
+}
+export interface UploadStatus {
+    uploadId: string;
+    projectId: string;
+    name: string;
+    bytes: number;
+    received: number;
+    mime: string;
+    state: string;
+    sha256: string | null;
+}
+export interface PreparedAppend {
+    readonly uploadId: string;
+    readonly projectId: string;
+    readonly offset: number;
+    readonly bytes: number;
+    readonly sha256: string;
+    readonly path: string;
+}
+export interface PreparedFinish {
+    readonly uploadId: string;
+    readonly projectId: string;
+    readonly blob: PreparedBlob;
+}
+export interface ResourceVersion {
+    version: number;
+    sha256: string;
+    bytes: number;
+    mime: string;
+    state: 'ready';
+    representationVersion: number | null;
+}
+export interface LibraryAsset {
+    id: string;
+    projectId: string;
+    name: string;
+    shared: boolean;
+    deleted: boolean;
+    current: ResourceVersion & {
+        assetId: string;
+    };
+}
+export interface CanvasResource {
+    id: string;
+    projectId: string;
+    graphId: string;
+    name: string;
+    current: ResourceVersion & {
+        resourceId: string;
+    };
+}
+export interface CanvasCreated {
+    resource: CanvasResource;
+    referenceId: string;
+}
+export declare const IMAGE_THUMBNAIL_LEVELS: readonly [320, 640, 1280, 2560, 4096];
+/** All commit methods require the caller's synchronous authenticated transaction. */
+export declare class Resources {
+    readonly db: DatabaseSync;
+    readonly blobs: BlobStore;
+    readonly now: () => number;
+    private readonly appends;
+    private readonly finishes;
+    private readonly videoFrames;
+    constructor(db: DatabaseSync, blobs: BlobStore, options?: {
+        now?: () => number;
+    });
+    private tx;
+    private outside;
+    private project;
+    private graph;
+    private writable;
+    private writableGraph;
+    private event;
+    startUpload(request: UploadStart): UploadStatus;
+    uploadStatus(scope: ResourceScope, uploadId: string): UploadStatus;
+    prepareAppend(scope: ResourceScope, uploadId: string, offset: number, bytes: Uint8Array): Promise<PreparedAppend>;
+    commitAppend(scope: ResourceScope, prepared: PreparedAppend): UploadStatus;
+    prepareFinish(scope: ResourceScope, uploadId: string): Promise<PreparedFinish>;
+    prepareBytes(bytes: Uint8Array, mime?: string, sha256?: string): Promise<PreparedBlob>;
+    prepareProjectFile(scope: ResourceScope, path: string, mime?: string): Promise<PreparedBlob>;
+    private register;
+    private queueFile;
+    /** Explicit cleanup of a known failed preparation; never scan unknown files.
+     * The permanent tombstone prevents any later commit from reusing this path. */
+    discardPrepared(blob: PreparedBlob): boolean;
+    discardAppend(scope: ResourceScope, prepared: PreparedAppend): boolean;
+    cancelUpload(scope: ResourceScope, uploadId: string): void;
+    commitFinish(scope: ResourceScope, prepared: PreparedFinish, target: UploadTarget): LibraryAsset | CanvasCreated;
+    createLibraryFromPrepared(target: LibraryTarget, blob: PreparedBlob): LibraryAsset;
+    private libraryFromBlob;
+    createCanvasFromPrepared(scope: CanvasScope, blob: PreparedBlob, title: string): CanvasCreated;
+    private representationVersion;
+    /** Editing is separate from canvas upload (which always creates an identity).
+     * Existing node/history refs stay pinned; caller explicitly attaches the new hold. */
+    updateCanvasFromPrepared(scope: CanvasScope, resourceId: string, expectedVersion: number, blob: PreparedBlob, title?: string): CanvasCreated;
+    /** Trusted helper: caller authorizes source; never expose as a public hash API. */
+    createCanvasFromReadyBlob(scope: CanvasScope, sha256: string, mime: string, title: string): CanvasCreated;
+    holdCanvasResource(scope: CanvasScope, resourceId: string, version: number): string;
+    attachNodeReference(scope: CanvasScope, resourceId: string, version: number, nodeId: string, releaseGraphHold?: string): string;
+    releaseCanvasReference(scope: CanvasScope, referenceId: string): void;
+    /** Public temp-upload release cannot remove node/snapshot/history ownership. */
+    releaseGraphReference(scope: CanvasScope, referenceId: string): void;
+    /** Called after Graphs inserts node/history ownership, in the same transaction.
+     * Consume only the attached immutable version's temporary graph holds. */
+    consumeGraphHolds(scope: CanvasScope, resourceId: string, version: number): number;
+    copyAssetToCanvas(scope: CanvasScope, assetId: string, expectedAssetVersion: number): CanvasCreated;
+    /** Clipboard copies a pinned, authorized canvas version into a new identity.
+     * Never expose an arbitrary blob-hash copy API or resurrect a collected source. */
+    copyCanvasToCanvas(scope: CanvasScope, sourceGraphId: string, resourceId: string, version: number): CanvasCreated;
+    saveCanvasToLibrary(scope: CanvasScope, resourceId: string, expectedResourceVersion: number, title: string): LibraryAsset;
+    copyAssetToProject(scope: ResourceScope, assetId: string, expectedVersion: number, title?: string): LibraryAsset;
+    private version;
+    getAsset(scope: ResourceScope, id: string): LibraryAsset;
+    listAssets(scope: ResourceScope, options?: {
+        name?: string;
+        search?: string;
+        deleted?: boolean;
+        scope?: 'project' | 'shared' | 'available';
+        limit?: number;
+        offset?: number;
+    }): LibraryAsset[];
+    listSameNameAssets(scope: ResourceScope, title: string): LibraryAsset[];
+    setShared(scope: ResourceScope, id: string, shared: boolean): LibraryAsset;
+    emptyTrash(scope: ResourceScope): {
+        removed: number;
+        retained: number;
+    };
+    softDelete(scope: ResourceScope, id: string): LibraryAsset;
+    restore(scope: ResourceScope, id: string): LibraryAsset;
+    getCanvas(scope: CanvasScope, id: string): CanvasResource;
+    listCanvas(scope: CanvasScope): CanvasResource[];
+    readCanvasVersion(scope: CanvasScope, id: string, version: number): ResourceVersion;
+    readAssetVersion(scope: ResourceScope, id: string, version: number): ResourceVersion;
+    readContent(scope: ResourceScope | CanvasScope, kind: 'asset' | 'canvas', id: string, version: number, range?: {
+        start: number;
+        end?: number;
+    }): Promise<{
+        bytes: Buffer;
+        mime: string;
+        total: number;
+        start: number;
+        end: number;
+    }>;
+    thumbnail(scope: ResourceScope | CanvasScope, kind: 'asset' | 'canvas', id: string, version: number, size?: number): Promise<{
+        bytes: Buffer;
+        mime: string;
+        total: number;
+        start: number;
+        end: number;
+        cacheable?: boolean;
+    }>;
+    representation(scope: ResourceScope | CanvasScope, kind: 'asset' | 'canvas', id: string, version: number): Promise<{
+        state: 'ready' | 'unsupported';
+        processor: string;
+        version: number;
+        mime: string;
+        text: string | null;
+        reason: string | null;
+    }>;
+    /** DB-only resolver for InputPreparation; caller already selected a scoped version.
+     * No extraction or file I/O is performed in the snapshot transaction. */
+    readPreparedRepresentation(resource: {
+        resourceId: string;
+        version: number;
+        sha256: string;
+        mime: string;
+        bytes: number;
+        representationVersion: number | null;
+    }): {
+        state: 'ready' | 'failed';
+        resourceSha256: string;
+        representationVersion: number | null;
+        text: string | null;
+        contentHash: string | null;
+    } | null;
+    preview(scope: ResourceScope | CanvasScope, kind: 'asset' | 'canvas', id: string, version: number): Promise<{
+        state: 'ready' | 'unsupported';
+        processor: string;
+        version: number;
+        mime: string;
+        text: string | null;
+        reason: string | null;
+    } | {
+        state: 'ready';
+        processor: string;
+        version: number;
+        content: {
+            bytes: Buffer;
+            mime: string;
+            total: number;
+            start: number;
+            end: number;
+        };
+    }>;
+    /** Preserve exact ID/hash leaves in legacy snapshot JSON without rewriting it. */
+    private snapshotMentions;
+    /** Typed snapshots protect only their named identity; shared hashes protect bytes. */
+    private snapshotUnboundHash;
+    private assetReferenced;
+    private canvasReferenced;
+    collectGarbage(only?: {
+        graphId: string;
+        blobHashes: string[];
+    }, canvasOnly?: boolean): {
+        canvas: number;
+        assets: number;
+        blobs: number;
+    };
+    drainFileDeletions(): Promise<{
+        removed: number;
+        failed: number;
+    }>;
+    /** Global cross-connection GC barrier for online SQLite + immutable-file copies.
+     * Existing drains finish first; new drains and logical GC stop at the barrier.
+     * Crashed leases fail closed; only an exclusive offline owner may clear them. */
+    withBlobLease<T>(work: () => Promise<T>): Promise<T>;
+}