@superdoc/sdk 2.25.0 → 2.26.0-next.13

package/tools/tools.vercel.json

@@ -272,6 +272,10 @@
             "SelectionTarget": {
               "type": "object",
               "properties": {
+                "captureState": {
+                  "type": "string",
+                  "description": "Opaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing."
+                },
                 "kind": {
                   "const": "selection",
                   "type": "string"
@@ -2019,6 +2023,10 @@
             "SelectionTarget": {
               "type": "object",
               "properties": {
+                "captureState": {
+                  "type": "string",
+                  "description": "Opaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing."
+                },
                 "kind": {
                   "const": "selection",
                   "type": "string"
@@ -3577,6 +3585,10 @@
             "SelectionTarget": {
               "type": "object",
               "properties": {
+                "captureState": {
+                  "type": "string",
+                  "description": "Opaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing."
+                },
                 "kind": {
                   "const": "selection",
                   "type": "string"
@@ -5101,6 +5113,10 @@
               "additionalProperties": true,
               "description": "Caller-owned JSON metadata persisted with the comment. Only for action 'create'. Omit for other actions."
             },
+            "expectedText": {
+              "type": "string",
+              "description": "Require the exact text currently at target before creating the comment. Pass the text the user selected, such as selection.current({ includeText: true }).text. A mismatch fails with PRECONDITION_FAILED and creates nothing. Only single-paragraph text targets support this guard; it checks the words, so it does not tell repeated identical text apart. Only for action 'create'. Omit for other actions."
+            },
             "id": {
               "type": "string",
               "description": "Required for actions 'delete', 'get'."
@@ -5285,6 +5301,10 @@
             "SelectionTarget": {
               "type": "object",
               "properties": {
+                "captureState": {
+                  "type": "string",
+                  "description": "Opaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing."
+                },
                 "kind": {
                   "const": "selection",
                   "type": "string"
@@ -5473,6 +5493,10 @@
             "TextAddress": {
               "type": "object",
               "properties": {
+                "captureState": {
+                  "type": "string",
+                  "description": "Opaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing."
+                },
                 "kind": {
                   "const": "text",
                   "type": "string"
@@ -5519,6 +5543,10 @@
             "TextTarget": {
               "type": "object",
               "properties": {
+                "captureState": {
+                  "type": "string",
+                  "description": "Opaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing."
+                },
                 "kind": {
                   "const": "text",
                   "type": "string"
@@ -6183,6 +6211,10 @@
             "TextTarget": {
               "type": "object",
               "properties": {
+                "captureState": {
+                  "type": "string",
+                  "description": "Opaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing."
+                },
                 "kind": {
                   "const": "text",
                   "type": "string"
@@ -9245,6 +9277,10 @@
             "SelectionTarget": {
               "type": "object",
               "properties": {
+                "captureState": {
+                  "type": "string",
+                  "description": "Opaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing."
+                },
                 "kind": {
                   "const": "selection",
                   "type": "string"
@@ -9433,6 +9469,10 @@
             "TextAddress": {
               "type": "object",
               "properties": {
+                "captureState": {
+                  "type": "string",
+                  "description": "Opaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing."
+                },
                 "kind": {
                   "const": "text",
                   "type": "string"

package/dist/runtime/document-rpc.cjs

@@ -1,351 +0,0 @@
-'use strict';
-
-var node_crypto = require('node:crypto');
-var errors = require('./errors.cjs');
-var sdkPolicy = require('./sdk-policy.cjs');
-var trackedSupport = require('./tracked-support.cjs');
-var transportCommon = require('./transport-common.cjs');
-
-const DOCUMENT_RPC_FEATURES = sdkPolicy.SDK_POLICY.documentRpcFeatures;
-const DOCUMENT_RPC_REPLACE_FILE_FEATURE = sdkPolicy.SDK_POLICY.features.replaceFile;
-const DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE = sdkPolicy.SDK_POLICY.features.defaultChangeMode;
-const DOCUMENT_RPC_SOURCE_SAVE_FEATURE = sdkPolicy.SDK_POLICY.features.sourceSave;
-const DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE = sdkPolicy.SDK_POLICY.features.requestTimeout;
-const DOCUMENT_RPC_OPEN_FIELDS = new Set(sdkPolicy.SDK_POLICY.documentOpenFields);
-const DOCUMENT_RPC_SAVE_FIELDS = new Set(sdkPolicy.SDK_POLICY.documentSaveFields);
-const DOCUMENT_API_OPTION_FIELDS = new Set(sdkPolicy.SDK_POLICY.documentOptionFields);
-const DOCUMENT_API_REVISION_PREFLIGHT_OPERATIONS = new Set(sdkPolicy.SDK_POLICY.revisionPreflightOperations);
-function unsupported(message, operationId) {
-    return new errors.SuperDocCliError(message, {
-        code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
-        ...(operationId === undefined ? {} : { details: { operationId } }),
-    });
-}
-function buildDocumentAuthor(user) {
-    if (user === undefined)
-        return undefined;
-    if (typeof user !== 'object' || user === null || Array.isArray(user)) {
-        throw new errors.SuperDocCliError('user must be an object with a non-empty name.', {
-            code: 'INVALID_ARGUMENT',
-        });
-    }
-    const record = user;
-    if (typeof record.name !== 'string' || record.name.trim().length === 0) {
-        throw new errors.SuperDocCliError('user.name must be a non-empty string.', {
-            code: 'INVALID_ARGUMENT',
-        });
-    }
-    if (record.email !== undefined && typeof record.email !== 'string') {
-        throw new errors.SuperDocCliError('user.email must be a string.', {
-            code: 'INVALID_ARGUMENT',
-        });
-    }
-    return {
-        name: record.name,
-        ...(record.email === undefined ? {} : { email: record.email }),
-    };
-}
-function documentRpcEnabled(env) {
-    return (env?.SUPERDOC_SDK_DOCUMENT_RPC ?? process.env.SUPERDOC_SDK_DOCUMENT_RPC) === '1';
-}
-function supportsDocumentRpc(features) {
-    return DOCUMENT_RPC_FEATURES.every((feature) => features.has(feature));
-}
-function canOpenWithDocumentRpc(params, options) {
-    if (options.stdinBytes !== undefined)
-        return false;
-    if (options.dryRun !== undefined || options.expectedRevision !== undefined || options.changeMode !== undefined) {
-        return false;
-    }
-    if (typeof params.doc !== 'string' || params.doc.trim().length === 0 || params.doc === '-')
-        return false;
-    if (params.runtime !== undefined && params.runtime !== 'v2')
-        return false;
-    if (params.sessionId !== undefined && (typeof params.sessionId !== 'string' || params.sessionId.length === 0)) {
-        return false;
-    }
-    return Object.entries(params).every(([key, value]) => value === undefined || DOCUMENT_RPC_OPEN_FIELDS.has(key));
-}
-function buildDocumentOpenParams(params, user, defaultChangeMode) {
-    const sessionId = typeof params.sessionId === 'string' && params.sessionId.length > 0 ? params.sessionId : node_crypto.randomUUID();
-    const author = buildDocumentAuthor(user);
-    return {
-        sessionId,
-        params: {
-            sessionId,
-            path: params.doc,
-            ...(author === undefined ? {} : { author }),
-            ...(defaultChangeMode == null ? {} : { defaultChangeMode }),
-        },
-    };
-}
-function mapDocumentOpenResult(response, sessionId, path) {
-    if (typeof response !== 'object' || response == null || Array.isArray(response)) {
-        throw new errors.SuperDocCliError('Host returned invalid document.open result.', {
-            code: 'HOST_PROTOCOL_ERROR',
-            details: { result: response },
-        });
-    }
-    const record = response;
-    if (record.sessionId !== sessionId || typeof record.byteLength !== 'number') {
-        throw new errors.SuperDocCliError('Host returned invalid document.open session metadata.', {
-            code: 'HOST_PROTOCOL_ERROR',
-            details: { result: response },
-        });
-    }
-    return {
-        active: true,
-        contextId: sessionId,
-        runtime: 'v2',
-        sessionType: 'local',
-        document: { path, source: 'path', byteLength: record.byteLength, revision: 0 },
-        dirty: false,
-    };
-}
-function mapDocumentReplaceFileResult(response, sessionId) {
-    if (typeof response !== 'object' || response == null || Array.isArray(response)) {
-        throw new errors.SuperDocCliError('Host returned invalid document.replaceFile result.', {
-            code: 'HOST_PROTOCOL_ERROR',
-            details: { result: response },
-        });
-    }
-    const record = response;
-    if (record.sessionId !== sessionId ||
-        record.replaced !== true ||
-        typeof record.byteLength !== 'number' ||
-        typeof record.revision !== 'string') {
-        throw new errors.SuperDocCliError('Host returned invalid document.replaceFile session metadata.', {
-            code: 'HOST_PROTOCOL_ERROR',
-            details: { expectedSessionId: sessionId, result: response },
-        });
-    }
-    return {
-        contextId: sessionId,
-        runtime: 'v2',
-        replaced: true,
-        document: { byteLength: record.byteLength, revision: record.revision },
-    };
-}
-function documentInvokePayload(operation, params, invokeOptions) {
-    params = transportCommon.captureMutationPlanAuthor(operation.operationId, params, invokeOptions);
-    const normalizedParams = transportCommon.applyOperationParamAliases(operation, params);
-    if (invokeOptions.stdinBytes !== undefined) {
-        throw unsupported('Structured document RPC does not support stdinBytes.', operation.operationId);
-    }
-    if (typeof normalizedParams.out === 'string' && normalizedParams.out.length > 0) {
-        throw unsupported('Structured document RPC does not support per-operation output paths.', operation.operationId);
-    }
-    if (normalizedParams.force === true) {
-        throw unsupported('Structured document RPC does not support per-operation force.', operation.operationId);
-    }
-    const input = {};
-    const options = {};
-    const paramsByName = new Map(operation.params.map((param) => [param.name, param]));
-    for (const [name, value] of Object.entries(normalizedParams)) {
-        if (value === undefined || name === 'doc' || name === 'sessionId' || name === 'out' || name === 'force')
-            continue;
-        const param = paramsByName.get(name);
-        if (!param) {
-            throw unsupported(`Structured document RPC does not support ${operation.operationId} field ${name}.`, operation.operationId);
-        }
-        if (typeof param.documentApiInputName === 'string' && param.documentApiInputName.length > 0) {
-            input[param.documentApiInputName] = value;
-            continue;
-        }
-        if (DOCUMENT_API_OPTION_FIELDS.has(name)) {
-            options[name] = value;
-            continue;
-        }
-        throw unsupported(`Structured document RPC does not support ${operation.operationId} field ${name}.`, operation.operationId);
-    }
-    for (const name of ['expectedRevision', 'changeMode', 'dryRun']) {
-        const value = invokeOptions[name];
-        if (value === undefined || normalizedParams[name] !== undefined)
-            continue;
-        const projectedValue = name === 'expectedRevision' ? String(value) : value;
-        const param = paramsByName.get(name);
-        if (typeof param?.documentApiInputName === 'string' && param.documentApiInputName.length > 0) {
-            input[param.documentApiInputName] = projectedValue;
-        }
-        else {
-            options[name] = projectedValue;
-        }
-    }
-    if (options.changeMode !== undefined && !trackedSupport.operationAcceptsTrackedMode(operation)) {
-        if (options.changeMode === 'tracked') {
-            throw unsupported(`Structured document RPC does not support tracked mode for ${operation.operationId}.`, operation.operationId);
-        }
-        if (options.changeMode !== 'direct') {
-            throw unsupported(`Structured document RPC received an invalid change mode for ${operation.operationId}.`, operation.operationId);
-        }
-        delete options.changeMode;
-    }
-    if (options.dryRun !== undefined && operation.supportsDryRun !== true) {
-        if (options.dryRun === true) {
-            throw unsupported(`Structured document RPC does not support dry run for ${operation.operationId}.`, operation.operationId);
-        }
-        delete options.dryRun;
-    }
-    if (options.expectedRevision !== undefined && DOCUMENT_API_REVISION_PREFLIGHT_OPERATIONS.has(operation.operationId)) {
-        throw unsupported(`Structured document RPC does not yet support expectedRevision for ${operation.operationId}.`, operation.operationId);
-    }
-    if (options.expectedRevision !== undefined && operation.mutates !== true) {
-        throw unsupported(`Structured document RPC does not support expectedRevision for ${operation.operationId}.`, operation.operationId);
-    }
-    return {
-        input,
-        ...(Object.keys(options).length === 0 ? {} : { options }),
-    };
-}
-function buildDocumentInvokeParams(sessionId, operation, params, options, hostFeatures) {
-    if (operation.operationId === 'doc.save') {
-        if (options.stdinBytes !== undefined ||
-            options.dryRun !== undefined ||
-            options.expectedRevision !== undefined ||
-            options.changeMode !== undefined) {
-            throw unsupported('Structured document RPC does not support document.save invoke options.', operation.operationId);
-        }
-        const unknownField = Object.entries(params).find(([name, value]) => value !== undefined && !DOCUMENT_RPC_SAVE_FIELDS.has(name))?.[0];
-        if (unknownField !== undefined) {
-            throw unsupported(`Structured document RPC does not support doc.save field ${unknownField}.`, operation.operationId);
-        }
-        if (params.inPlace !== undefined && typeof params.inPlace !== 'boolean') {
-            throw unsupported('Structured document RPC requires inPlace to be a boolean.', operation.operationId);
-        }
-        if (params.inPlace === true && params.out !== undefined) {
-            throw unsupported('Structured document RPC requires either inPlace or out, not both.', operation.operationId);
-        }
-        if (params.out !== undefined && (typeof params.out !== 'string' || params.out.length === 0)) {
-            throw unsupported('Structured document RPC requires out to be a non-empty path.', operation.operationId);
-        }
-        if (params.out === undefined && hostFeatures?.has(DOCUMENT_RPC_SOURCE_SAVE_FEATURE) !== true) {
-            throw unsupported('Structured document RPC host does not support source saves.', operation.operationId);
-        }
-        return {
-            method: 'document.save',
-            params: {
-                sessionId,
-                ...(params.out === undefined ? {} : { path: params.out }),
-                ...(params.force === true ? { overwrite: true } : {}),
-                ...(params.mode === undefined ? {} : { mode: params.mode }),
-            },
-        };
-    }
-    if (operation.operationId === 'doc.close') {
-        if (options.stdinBytes !== undefined ||
-            options.dryRun !== undefined ||
-            options.expectedRevision !== undefined ||
-            options.changeMode !== undefined) {
-            throw unsupported('Structured document RPC does not support document.close invoke options.', operation.operationId);
-        }
-        return {
-            method: 'document.close',
-            params: {
-                sessionId,
-                ...(params.discard === undefined ? {} : { discard: params.discard }),
-            },
-        };
-    }
-    const documentOperation = operation;
-    if (typeof documentOperation.documentApiOperationId !== 'string' ||
-        documentOperation.documentApiOperationId.length === 0) {
-        throw unsupported(`Structured document RPC does not support ${operation.operationId}.`, operation.operationId);
-    }
-    const payload = documentInvokePayload(documentOperation, params, options);
-    return {
-        method: 'document.invoke',
-        params: {
-            sessionId,
-            operationId: documentOperation.documentApiOperationId,
-            input: payload.input,
-            ...(payload.options === undefined ? {} : { options: payload.options }),
-        },
-    };
-}
-function documentRpcRequestSupportsResponseTimeout(operation, request) {
-    if (request.method === 'document.save')
-        return false;
-    if (request.method !== 'document.invoke')
-        return true;
-    const documentOperation = operation;
-    const requestOptions = typeof request.params.options === 'object' &&
-        request.params.options !== null &&
-        !Array.isArray(request.params.options)
-        ? request.params.options
-        : undefined;
-    if (requestOptions?.dryRun === true)
-        return true;
-    if (documentOperation.mutates === false)
-        return true;
-    return documentOperation.idempotency === 'idempotent';
-}
-function mapDocumentLifecycleResult(operationId, response, sessionId, expectedInPlace) {
-    if (operationId !== 'doc.save' && operationId !== 'doc.close')
-        return response;
-    if (typeof response !== 'object' || response == null || Array.isArray(response)) {
-        throw new errors.SuperDocCliError(`Host returned invalid ${operationId.slice('doc.'.length)} result.`, {
-            code: 'HOST_PROTOCOL_ERROR',
-            details: { result: response },
-        });
-    }
-    const record = response;
-    if (record.sessionId !== sessionId) {
-        throw new errors.SuperDocCliError('Host returned a result for the wrong document session.', {
-            code: 'HOST_PROTOCOL_ERROR',
-            details: { expectedSessionId: sessionId, result: response },
-        });
-    }
-    if (operationId === 'doc.close') {
-        if (record.closed !== true || typeof record.discarded !== 'boolean') {
-            throw new errors.SuperDocCliError('Host returned invalid document.close result.', {
-                code: 'HOST_PROTOCOL_ERROR',
-                details: { result: response },
-            });
-        }
-        return {
-            contextId: sessionId,
-            runtime: 'v2',
-            closed: true,
-            saved: false,
-            discarded: record.discarded,
-            defaultSessionCleared: false,
-        };
-    }
-    const output = record.output;
-    if (record.saved !== true ||
-        (typeof record.inPlace !== 'boolean' && !(record.inPlace === undefined && expectedInPlace === false)) ||
-        typeof output !== 'object' ||
-        output == null ||
-        Array.isArray(output) ||
-        typeof output.path !== 'string' ||
-        typeof output.byteLength !== 'number') {
-        throw new errors.SuperDocCliError('Host returned invalid document.save result.', {
-            code: 'HOST_PROTOCOL_ERROR',
-            details: { result: response },
-        });
-    }
-    return {
-        contextId: sessionId,
-        runtime: 'v2',
-        saved: true,
-        inPlace: record.inPlace ?? false,
-        mode: record.mode,
-        output,
-        report: record.report,
-    };
-}
-
-exports.DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE = DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE;
-exports.DOCUMENT_RPC_FEATURES = DOCUMENT_RPC_FEATURES;
-exports.DOCUMENT_RPC_REPLACE_FILE_FEATURE = DOCUMENT_RPC_REPLACE_FILE_FEATURE;
-exports.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE = DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE;
-exports.DOCUMENT_RPC_SOURCE_SAVE_FEATURE = DOCUMENT_RPC_SOURCE_SAVE_FEATURE;
-exports.buildDocumentInvokeParams = buildDocumentInvokeParams;
-exports.buildDocumentOpenParams = buildDocumentOpenParams;
-exports.canOpenWithDocumentRpc = canOpenWithDocumentRpc;
-exports.documentRpcEnabled = documentRpcEnabled;
-exports.documentRpcRequestSupportsResponseTimeout = documentRpcRequestSupportsResponseTimeout;
-exports.mapDocumentLifecycleResult = mapDocumentLifecycleResult;
-exports.mapDocumentOpenResult = mapDocumentOpenResult;
-exports.mapDocumentReplaceFileResult = mapDocumentReplaceFileResult;
-exports.supportsDocumentRpc = supportsDocumentRpc;

package/dist/runtime/document-rpc.d.ts

@@ -1,26 +0,0 @@
-import { type ChangeMode, type InvokeOptions, type OperationSpec, type UserIdentity } from './transport-common.js';
-export declare const DOCUMENT_RPC_FEATURES: readonly string[];
-export declare const DOCUMENT_RPC_REPLACE_FILE_FEATURE: string;
-export declare const DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE: string;
-export declare const DOCUMENT_RPC_SOURCE_SAVE_FEATURE: string;
-export declare const DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE: string;
-type DocumentRpcRequest = {
-    readonly method: string;
-    readonly params: Record<string, unknown>;
-};
-export declare function documentRpcEnabled(env: Record<string, string | undefined> | undefined): boolean;
-export declare function supportsDocumentRpc(features: ReadonlySet<string>): boolean;
-export declare function canOpenWithDocumentRpc(params: Record<string, unknown>, options: InvokeOptions): boolean;
-export declare function buildDocumentOpenParams(params: Record<string, unknown>, user?: UserIdentity, defaultChangeMode?: ChangeMode): {
-    readonly sessionId: string;
-    readonly params: Record<string, unknown>;
-};
-export declare function mapDocumentOpenResult(response: unknown, sessionId: string, path: string): Record<string, unknown>;
-export declare function mapDocumentReplaceFileResult(response: unknown, sessionId: string): Record<string, unknown>;
-export declare function buildDocumentInvokeParams(sessionId: string, operation: OperationSpec, params: Record<string, unknown>, options: InvokeOptions, hostFeatures?: ReadonlySet<string>): {
-    readonly method: string;
-    readonly params: Record<string, unknown>;
-};
-export declare function documentRpcRequestSupportsResponseTimeout(operation: OperationSpec, request: DocumentRpcRequest): boolean;
-export declare function mapDocumentLifecycleResult(operationId: string, response: unknown, sessionId: string, expectedInPlace?: boolean): unknown;
-export {};