@superdoc-dev/sdk 1.0.0-next.72 → 1.0.0-next.74

package/dist/index.js

@@ -1,29 +1,152 @@
-import { createDocApi } from './generated/client.js';
-import { SuperDocRuntime } from './runtime/process.js';
+import { createDocApi, createBoundDocApi, } from './generated/client.js';
+import { CONTRACT } from './generated/contract.js';
+import { SuperDocRuntime, } from './runtime/process.js';
+import { SuperDocCliError } from './runtime/errors.js';
+// ---------------------------------------------------------------------------
+// Session-bound runtime wrapper
+// ---------------------------------------------------------------------------
 /**
- * High-level client for interacting with SuperDoc documents via the CLI.
+ * Wraps a raw runtime and injects a fixed sessionId into every invoke call.
+ * Implements RuntimeInvoker so generated code can use it directly.
  *
- * Provides a typed `doc` API for opening, querying, and mutating documents.
- * Call {@link connect} before operations and {@link dispose} when finished
- * to manage the host process lifecycle.
+ * @internal
+ */
+class BoundRuntime {
+    runtime;
+    sessionId;
+    closed = false;
+    constructor(runtime, sessionId) {
+        this.runtime = runtime;
+        this.sessionId = sessionId;
+    }
+    async invoke(operation, params = {}, options = {}) {
+        if (this.closed) {
+            throw new SuperDocCliError('Document handle is closed.', {
+                code: 'DOCUMENT_CLOSED',
+                details: { sessionId: this.sessionId },
+            });
+        }
+        return this.runtime.invoke(operation, { ...params, sessionId: this.sessionId }, options);
+    }
+    markClosed() {
+        this.closed = true;
+    }
+}
+// ---------------------------------------------------------------------------
+// Document handle
+// ---------------------------------------------------------------------------
+/**
+ * Bound document handle. All document operations are available as typed methods.
+ * The handle injects its session id automatically — callers never pass
+ * doc or sessionId.
+ */
+class SuperDocDocumentCore {
+    boundRuntime;
+    _sessionId;
+    _openResult;
+    client;
+    /** @internal */
+    constructor(boundRuntime, sessionId, openResult, client) {
+        this.boundRuntime = boundRuntime;
+        this._sessionId = sessionId;
+        this._openResult = openResult;
+        this.client = client;
+        attachBoundDocApi(this, createBoundDocApi(this.boundRuntime));
+    }
+    get sessionId() {
+        return this._sessionId;
+    }
+    /** Read-only snapshot of the initial doc.open response metadata. */
+    get openResult() {
+        return this._openResult;
+    }
+    async save(params = {}, options = {}) {
+        return this.boundRuntime.invoke(CONTRACT.operations['doc.save'], params, options);
+    }
+    async close(params = {}, options = {}) {
+        const result = await this.boundRuntime.invoke(CONTRACT.operations['doc.close'], params, options);
+        this.boundRuntime.markClosed();
+        this.client.removeHandle(this._sessionId);
+        return result;
+    }
+    /** @internal */
+    markClosed() {
+        this.boundRuntime.markClosed();
+    }
+}
+function attachBoundDocApi(target, api) {
+    const { save: _save, close: _close, ...boundMethods } = api;
+    Object.assign(target, boundMethods);
+}
+export const SuperDocDocument = SuperDocDocumentCore;
+/**
+ * SuperDoc client — transport manager and document factory.
+ *
+ * Use `client.open()` to get bound document handles. Each handle is
+ * independently session-scoped and safe for concurrent use.
+ *
+ *     const client = new SuperDocClient({ user: { name: 'bot' } });
+ *     await client.connect();
+ *     const doc = await client.open({ doc: './file.docx' });
+ *     const markdown = await doc.getMarkdown();
+ *     await doc.close();
+ *     await client.dispose();
  */
 export class SuperDocClient {
     runtime;
-    doc;
+    rawApi;
+    handles = new Map();
     constructor(options = {}) {
         this.runtime = new SuperDocRuntime(options);
-        this.doc = createDocApi(this.runtime);
+        this.rawApi = createDocApi(this.runtime);
     }
     async connect() {
         await this.runtime.connect();
     }
+    /**
+     * Open a document and return a bound document handle.
+     *
+     * The returned handle injects its session id into every operation
+     * automatically. The same file can be opened multiple times with
+     * different session ids (useful for diff workflows).
+     */
+    async open(params, options) {
+        const explicitSessionId = params.sessionId;
+        if (typeof explicitSessionId === 'string' && this.handles.has(explicitSessionId)) {
+            throw new SuperDocCliError(`Session id already open in this client: ${explicitSessionId}`, {
+                code: 'SESSION_ALREADY_OPEN',
+                details: { sessionId: explicitSessionId },
+            });
+        }
+        const result = (await this.rawApi.open(params, options));
+        const contextId = result.contextId;
+        const boundRuntime = new BoundRuntime(this.runtime, contextId);
+        const handle = new SuperDocDocument(boundRuntime, contextId, result, this);
+        this.handles.set(contextId, handle);
+        return handle;
+    }
+    async describe(params = {}, options) {
+        return this.rawApi.describe(params, options);
+    }
+    async describeCommand(params, options) {
+        return this.rawApi.describeCommand(params, options);
+    }
     async dispose() {
+        for (const handle of this.handles.values()) {
+            handle.markClosed();
+        }
+        this.handles.clear();
         await this.runtime.dispose();
     }
+    /** @internal */
+    removeHandle(sessionId) {
+        this.handles.delete(sessionId);
+    }
 }
 export function createSuperDocClient(options = {}) {
     return new SuperDocClient(options);
 }
 export { getSkill, installSkill, listSkills } from './skills.js';
-export { chooseTools, dispatchSuperDocTool, getToolCatalog, inferDocumentFeatures, listTools, resolveToolOperation, } from './tools.js';
+export { chooseTools, dispatchSuperDocTool, getSystemPrompt, getToolCatalog, listTools } from './tools.js';
+export { dispatchIntentTool } from './generated/intent-dispatch.generated.js';
 export { SuperDocCliError } from './runtime/errors.js';

package/dist/runtime/process.d.ts

@@ -1,4 +1,4 @@
-import type { InvokeOptions, OperationParamSpec, OperationSpec, SuperDocClientOptions } from './transport-common.js';
+import type { InvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions } from './transport-common.js';
 /**
  * Internal runtime that delegates CLI invocations to a persistent host transport.
  *
@@ -12,5 +12,5 @@ export declare class SuperDocRuntime {
     dispose(): Promise<void>;
     invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
 }
-export type { InvokeOptions, OperationParamSpec, OperationSpec, SuperDocClientOptions };
+export type { InvokeOptions, OperationParamSpec, OperationSpec, RuntimeInvoker, SuperDocClientOptions };
 //# sourceMappingURL=process.d.ts.map

package/dist/runtime/process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/runtime/process.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAErH;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;gBAE9B,OAAO,GAAE,qBAA0B;IASzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,MAAM,CAAC,KAAK,GAAG,OAAO,EAC1B,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,KAAK,CAAC;CAGlB;AAED,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,aAAa,EAAE,qBAAqB,EAAE,CAAC"}
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/runtime/process.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AAE/B;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;gBAE9B,OAAO,GAAE,qBAA0B;IASzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,MAAM,CAAC,KAAK,GAAG,OAAO,EAC1B,SAAS,EAAE,aAAa,EACxB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,KAAK,CAAC;CAGlB;AAED,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,aAAa,EAAE,cAAc,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/runtime/transport-common.cjs

@@ -35,6 +35,14 @@ function buildOperationArgv(operation, params, options, runtimeTimeoutMs, defaul
             normalizedParams = { ...normalizedParams, userEmail: user.email };
         }
     }
+    // Legacy alias: tables.split renamed atRowIndex → rowIndex (SD-2132).
+    if (operation.operationId === 'doc.tables.split' && normalizedParams.atRowIndex !== undefined) {
+        if (normalizedParams.rowIndex !== undefined && normalizedParams.rowIndex !== normalizedParams.atRowIndex) {
+            throw new Error('tables.split: cannot provide both rowIndex and atRowIndex with different values.');
+        }
+        const { atRowIndex, ...rest } = normalizedParams;
+        normalizedParams = { ...rest, rowIndex: atRowIndex };
+    }
     const argv = [...operation.commandTokens];
     for (const spec of operation.params) {
         const value = normalizedParams[spec.name];
@@ -61,6 +69,8 @@ function buildOperationArgv(operation, params, options, runtimeTimeoutMs, defaul
                 }
                 break;
             case 'jsonFlag':
+                // CLI always parses --*-json values via JSON.parse, so even scalar
+                // strings must be serialized as JSON string literals.
                 argv.push(flag, JSON.stringify(value));
                 break;
         }

package/dist/runtime/transport-common.d.ts

@@ -16,6 +16,13 @@ export interface InvokeOptions {
     timeoutMs?: number;
     stdinBytes?: Uint8Array;
 }
+/**
+ * Minimal invoke interface that both SuperDocRuntime and BoundRuntime satisfy.
+ * Generated code depends on this interface, not on the concrete runtime class.
+ */
+export interface RuntimeInvoker {
+    invoke<TData = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions): Promise<TData>;
+}
 export type ChangeMode = 'direct' | 'tracked';
 export interface UserIdentity {
     name: string;

package/dist/runtime/transport-common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport-common.d.ts","sourceRoot":"","sources":["../../src/runtime/transport-common.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAC9E,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,CAAC;AAEpD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAMD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAU/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,aAAa,EACtB,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,iBAAiB,CAAC,EAAE,UAAU,EAC9B,IAAI,CAAC,EAAE,YAAY,GAClB,MAAM,EAAE,CAsDV"}
+{"version":3,"file":"transport-common.d.ts","sourceRoot":"","sources":["../../src/runtime/transport-common.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAC9E,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,CAAC;AAEpD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,KAAK,GAAG,OAAO,EACpB,SAAS,EAAE,aAAa,EACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,KAAK,CAAC,CAAC;CACnB;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAMD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAU/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,aAAa,EACtB,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,iBAAiB,CAAC,EAAE,UAAU,EAC9B,IAAI,CAAC,EAAE,YAAY,GAClB,MAAM,EAAE,CAiEV"}

package/dist/runtime/transport-common.js

@@ -33,6 +33,14 @@ export function buildOperationArgv(operation, params, options, runtimeTimeoutMs,
             normalizedParams = { ...normalizedParams, userEmail: user.email };
         }
     }
+    // Legacy alias: tables.split renamed atRowIndex → rowIndex (SD-2132).
+    if (operation.operationId === 'doc.tables.split' && normalizedParams.atRowIndex !== undefined) {
+        if (normalizedParams.rowIndex !== undefined && normalizedParams.rowIndex !== normalizedParams.atRowIndex) {
+            throw new Error('tables.split: cannot provide both rowIndex and atRowIndex with different values.');
+        }
+        const { atRowIndex, ...rest } = normalizedParams;
+        normalizedParams = { ...rest, rowIndex: atRowIndex };
+    }
     const argv = [...operation.commandTokens];
     for (const spec of operation.params) {
         const value = normalizedParams[spec.name];
@@ -59,6 +67,8 @@ export function buildOperationArgv(operation, params, options, runtimeTimeoutMs,
                 }
                 break;
             case 'jsonFlag':
+                // CLI always parses --*-json values via JSON.parse, so even scalar
+                // strings must be serialized as JSON string literals.
                 argv.push(flag, JSON.stringify(value));
                 break;
         }