@qvac/sdk 0.18.2 → 0.19.0

package/dist/src/schemas/sdk-errors-client.js

@@ -0,0 +1,192 @@
+import { addCodes, isCodeRegistered } from '@qvac/error';
+// Load @qvac/inference's registration first, then add only codes not already present, so a
+// shared @qvac/error instance (packed consumers, the Bare worker) is not double-registered.
+import '@qvac/inference/surface';
+// Client-side error codes (50,001-52,000 range for this SDK)
+export const SDK_CLIENT_ERROR_CODES = {
+    // Response Validation Errors (50,001-50,199)
+    INVALID_RESPONSE_TYPE: 50001,
+    INVALID_OPERATION_IN_RESPONSE: 50002,
+    STREAM_ENDED_WITHOUT_RESPONSE: 50003,
+    INVALID_AUDIO_CHUNK_TYPE: 50004,
+    INVALID_TOOLS_ARRAY: 50005,
+    INVALID_TOOL_SCHEMA: 50006,
+    OCR_FAILED: 50007,
+    MODEL_TYPE_REQUIRED: 50008,
+    MODEL_SRC_TYPE_MISMATCH: 50009,
+    REQUEST_VALIDATION_FAILED: 50010,
+    // RPC Communication Errors (50,200-50,399)
+    RPC_NO_HANDLER: 50200,
+    RPC_REQUEST_NOT_SENT: 50201,
+    RPC_RESPONSE_STREAM_NOT_CREATED: 50202,
+    RPC_CONNECTION_FAILED: 50203,
+    RPC_INIT_TIMEOUT: 50204,
+    WORKER_CRASHED: 50205,
+    WORKER_SHUTDOWN: 50206,
+    WORKER_STARTUP_FAILED: 50207,
+    // Build/Bundle Errors (50,600-50,799)
+    SDK_NOT_FOUND_IN_NODE_MODULES: 50600,
+    WORKER_FILE_NOT_FOUND: 50601,
+    CONFIG_FILE_NOT_FOUND: 50602,
+    CONFIG_FILE_INVALID: 50603,
+    CONFIG_FILE_PARSE_FAILED: 50604,
+    CONFIG_VALIDATION_FAILED: 50605,
+    PEAR_WORKER_ENTRY_REQUIRED: 50606,
+    MULTIPLE_SDK_INSTALLATIONS: 50607,
+    WORKER_PLUGINS_NOT_REGISTERED: 50608,
+    BUNDLE_VERIFICATION_FAILED: 50609,
+    BARE_PACK_NOT_INSTALLED: 50610,
+    BARE_PACK_ERROR: 50611,
+    INVALID_PLUGIN_SPECIFIER: 50612,
+    BARE_IMPORTS_MAP_NOT_FOUND: 50613,
+    BARE_RUNTIME_BINARY_NOT_FOUND: 50614,
+    // Profiler Errors (50,800-50,899)
+    PROFILER_INVALID_CAPACITY: 50800
+};
+const clientErrorDefinitions = {
+    // Response Validation Errors (50,001-50,199)
+    [SDK_CLIENT_ERROR_CODES.INVALID_RESPONSE_TYPE]: {
+        name: 'INVALID_RESPONSE_TYPE',
+        message: (expected) => `Invalid response type received, expected: ${expected}`
+    },
+    [SDK_CLIENT_ERROR_CODES.INVALID_OPERATION_IN_RESPONSE]: {
+        name: 'INVALID_OPERATION_IN_RESPONSE',
+        message: 'Invalid operation type in response'
+    },
+    [SDK_CLIENT_ERROR_CODES.STREAM_ENDED_WITHOUT_RESPONSE]: {
+        name: 'STREAM_ENDED_WITHOUT_RESPONSE',
+        message: 'Stream ended without receiving final response'
+    },
+    [SDK_CLIENT_ERROR_CODES.INVALID_AUDIO_CHUNK_TYPE]: {
+        name: 'INVALID_AUDIO_CHUNK_TYPE',
+        message: 'Invalid audio chunk type received'
+    },
+    [SDK_CLIENT_ERROR_CODES.INVALID_TOOLS_ARRAY]: {
+        name: 'INVALID_TOOLS_ARRAY',
+        message: 'Invalid tools array provided'
+    },
+    [SDK_CLIENT_ERROR_CODES.INVALID_TOOL_SCHEMA]: {
+        name: 'INVALID_TOOL_SCHEMA',
+        message: (details) => `Invalid tool schema: ${details}`
+    },
+    [SDK_CLIENT_ERROR_CODES.OCR_FAILED]: {
+        name: 'OCR_FAILED',
+        message: (details) => `OCR operation failed${details ? `: ${details}` : ''}`
+    },
+    [SDK_CLIENT_ERROR_CODES.MODEL_TYPE_REQUIRED]: {
+        name: 'MODEL_TYPE_REQUIRED',
+        message: 'modelType is required: modelSrc is a plain string or lacks an engine/addon descriptor that can be inferred. Pass an explicit canonical modelType (e.g. "llamacpp-completion", "whispercpp-transcription", "nmtcpp-translation", "llamacpp-embedding", "tts-ggml", "ggml-ocr", "parakeet-transcription", "sdcpp-generation") or use a model constant that carries engine metadata.'
+    },
+    [SDK_CLIENT_ERROR_CODES.MODEL_SRC_TYPE_MISMATCH]: {
+        name: 'MODEL_SRC_TYPE_MISMATCH',
+        message: (inferred, resolved) => `modelSrc describes "${inferred}", but modelType resolves to "${resolved}". Omit modelType to infer it automatically, or pass a matching modelType.`
+    },
+    [SDK_CLIENT_ERROR_CODES.REQUEST_VALIDATION_FAILED]: {
+        name: 'REQUEST_VALIDATION_FAILED',
+        message: (errors) => `Invalid request:\n${errors}`
+    },
+    // RPC Communication Errors (50,200-50,399)
+    [SDK_CLIENT_ERROR_CODES.RPC_NO_HANDLER]: {
+        name: 'RPC_NO_HANDLER',
+        message: (requestType) => `No handler function registered for request type: ${requestType}`
+    },
+    [SDK_CLIENT_ERROR_CODES.RPC_REQUEST_NOT_SENT]: {
+        name: 'RPC_REQUEST_NOT_SENT',
+        message: 'Cannot perform operation - request has not been sent yet'
+    },
+    [SDK_CLIENT_ERROR_CODES.RPC_RESPONSE_STREAM_NOT_CREATED]: {
+        name: 'RPC_RESPONSE_STREAM_NOT_CREATED',
+        message: 'Cannot perform operation - response stream not created'
+    },
+    [SDK_CLIENT_ERROR_CODES.RPC_CONNECTION_FAILED]: {
+        name: 'RPC_CONNECTION_FAILED',
+        message: (details) => `RPC connection failed: ${details}`
+    },
+    [SDK_CLIENT_ERROR_CODES.RPC_INIT_TIMEOUT]: {
+        name: 'RPC_INIT_TIMEOUT',
+        message: (timeoutMs) => `RPC initialization timed out after ${timeoutMs}ms — the worker process may have failed to start`
+    },
+    [SDK_CLIENT_ERROR_CODES.WORKER_CRASHED]: {
+        name: 'WORKER_CRASHED',
+        message: (code, signal) => `Bare worker exited mid-request (code=${code}, signal=${signal}) — in-flight calls were aborted`
+    },
+    [SDK_CLIENT_ERROR_CODES.WORKER_SHUTDOWN]: {
+        name: 'WORKER_SHUTDOWN',
+        message: () => `SDK is shutting down — in-flight RPC call aborted`
+    },
+    [SDK_CLIENT_ERROR_CODES.WORKER_STARTUP_FAILED]: {
+        name: 'WORKER_STARTUP_FAILED',
+        // `details` is the full sentence; `stderrTail` is appended under a
+        // `Worker stderr:` header when non-empty.
+        message: (details, stderrTail) => stderrTail ? `${details}\n\nWorker stderr:\n${stderrTail}` : details
+    },
+    // Build/Bundle Errors (50,600-50,799)
+    [SDK_CLIENT_ERROR_CODES.SDK_NOT_FOUND_IN_NODE_MODULES]: {
+        name: 'SDK_NOT_FOUND_IN_NODE_MODULES',
+        message: 'QVAC SDK not found in node_modules. Checked: @qvac/sdk, @tetherto/sdk-mono, @tetherto/sdk-dev'
+    },
+    [SDK_CLIENT_ERROR_CODES.WORKER_FILE_NOT_FOUND]: {
+        name: 'WORKER_FILE_NOT_FOUND',
+        message: (workerPath) => `Worker file not found at ${workerPath}`
+    },
+    [SDK_CLIENT_ERROR_CODES.CONFIG_FILE_NOT_FOUND]: {
+        name: 'CONFIG_FILE_NOT_FOUND',
+        message: (searchPaths) => `Config file not found. Searched: ${searchPaths}. Create qvac.config.json, qvac.config.js, or qvac.config.ts in your project root.`
+    },
+    [SDK_CLIENT_ERROR_CODES.CONFIG_FILE_INVALID]: {
+        name: 'CONFIG_FILE_INVALID',
+        message: (filePath, reason) => `Config file at ${filePath} is invalid: ${reason}`
+    },
+    [SDK_CLIENT_ERROR_CODES.CONFIG_FILE_PARSE_FAILED]: {
+        name: 'CONFIG_FILE_PARSE_FAILED',
+        message: (filePath, error) => `Failed to parse config file at ${filePath}: ${error}`
+    },
+    [SDK_CLIENT_ERROR_CODES.CONFIG_VALIDATION_FAILED]: {
+        name: 'CONFIG_VALIDATION_FAILED',
+        message: (errors) => `Config validation failed: ${errors}`
+    },
+    [SDK_CLIENT_ERROR_CODES.MULTIPLE_SDK_INSTALLATIONS]: {
+        name: 'MULTIPLE_SDK_INSTALLATIONS',
+        message: (packages) => `Multiple QVAC SDK installations found: ${packages}. Remove all but one to avoid conflicts.`
+    },
+    [SDK_CLIENT_ERROR_CODES.PEAR_WORKER_ENTRY_REQUIRED]: {
+        name: 'PEAR_WORKER_ENTRY_REQUIRED',
+        message: (workerEntry) => `No plugins registered. Pear apps must spawn ${workerEntry} as the worker entry. Run \`npx qvac bundle sdk\` to generate it, then spawn the generated file instead of your worker directly.`
+    },
+    [SDK_CLIENT_ERROR_CODES.WORKER_PLUGINS_NOT_REGISTERED]: {
+        name: 'WORKER_PLUGINS_NOT_REGISTERED',
+        message: () => 'No plugins registered in the worker. For in-process Bare use `@qvac/inference` and register plugins with `plugins([...])` (or `registerPlugin(...)`). See https://docs.qvac.tether.io/configuration/plugins#runtime-registration-on-bare'
+    },
+    [SDK_CLIENT_ERROR_CODES.BUNDLE_VERIFICATION_FAILED]: {
+        name: 'BUNDLE_VERIFICATION_FAILED',
+        message: (bundlePath) => `qvac verify bundle reported error-level issues for ${bundlePath}. See the CLI output above for the failing addons/hosts; resolve them before shipping.`
+    },
+    [SDK_CLIENT_ERROR_CODES.BARE_PACK_NOT_INSTALLED]: {
+        name: 'BARE_PACK_NOT_INSTALLED',
+        message: 'bare-pack binary not found. Install bare-pack as a peer dependency: npm install bare-pack'
+    },
+    [SDK_CLIENT_ERROR_CODES.BARE_PACK_ERROR]: {
+        name: 'BARE_PACK_ERROR',
+        message: (exitCode, entryPath, outputPath) => `bare-pack exited with code ${exitCode}\n\n  Entry file: ${entryPath}\n  Output file: ${outputPath}\n\n  Run bare-pack manually for more details.`
+    },
+    [SDK_CLIENT_ERROR_CODES.INVALID_PLUGIN_SPECIFIER]: {
+        name: 'INVALID_PLUGIN_SPECIFIER',
+        message: (specifiers) => `Invalid plugin specifiers (must end with /plugin):\n${specifiers}`
+    },
+    [SDK_CLIENT_ERROR_CODES.BARE_IMPORTS_MAP_NOT_FOUND]: {
+        name: 'BARE_IMPORTS_MAP_NOT_FOUND',
+        message: (sdkName, expectedPath) => `bare-imports.json not found.\n\n  Expected at: ${expectedPath}\n\n  Make sure ${sdkName} is installed in your project.`
+    },
+    [SDK_CLIENT_ERROR_CODES.BARE_RUNTIME_BINARY_NOT_FOUND]: {
+        name: 'BARE_RUNTIME_BINARY_NOT_FOUND',
+        message: (platform, arch) => `Could not load the Bare runtime binary for ${platform}-${arch}. The platform package "bare-runtime-${platform}-${arch}" (or one of its dependencies) is missing from node_modules — commonly seen with pnpm, which does not always install nested optional dependencies. Fix it by installing the platform package directly (e.g. \`pnpm add bare-runtime-${platform}-${arch}\`) or by installing with npm or bun. See https://github.com/tetherto/qvac/issues/1492`
+    },
+    // Profiler Errors (50,800-50,899)
+    [SDK_CLIENT_ERROR_CODES.PROFILER_INVALID_CAPACITY]: {
+        name: 'PROFILER_INVALID_CAPACITY',
+        message: (minCapacity) => `Ring buffer capacity must be at least ${minCapacity}`
+    }
+};
+const clientDefinitionsToRegister = Object.fromEntries(Object.entries(clientErrorDefinitions).filter(([code]) => !isCodeRegistered(Number(code))));
+addCodes(clientDefinitionsToRegister, { name: 'qvac-sdk-client', version: '1.2.0' });
+export { clientErrorDefinitions as SDK_CLIENT_ERROR_DEFINITIONS };

package/dist/src/schemas/sdk-errors-server.d.ts

@@ -0,0 +1,101 @@
+import { type ErrorCodesMap } from '@qvac/error';
+import '@qvac/inference/surface';
+export declare const SDK_SERVER_ERROR_CODES: {
+    readonly MODEL_ALREADY_REGISTERED: 52001;
+    readonly MODEL_NOT_FOUND: 52002;
+    readonly MODEL_NOT_LOADED: 52003;
+    readonly UNKNOWN_MODEL_TYPE: 52005;
+    readonly MODEL_LOAD_FAILED: 52200;
+    readonly MODEL_FILE_NOT_FOUND: 52201;
+    readonly MODEL_FILE_NOT_FOUND_IN_DIR: 52202;
+    readonly MODEL_FILE_LOCATE_FAILED: 52203;
+    readonly PROJECTION_MODEL_REQUIRED: 52204;
+    readonly VAD_MODEL_REQUIRED: 52205;
+    readonly TTS_ARTIFACTS_REQUIRED: 52208;
+    readonly TTS_REFERENCE_AUDIO_REQUIRED: 52209;
+    readonly LEGACY_PARAKEET_MODEL_DEPRECATED: 52210;
+    readonly LEGACY_TTS_MODEL_DEPRECATED: 52211;
+    readonly MODEL_UNLOAD_FAILED: 52400;
+    readonly EMBED_FAILED: 52401;
+    readonly EMBED_NO_EMBEDDINGS: 52402;
+    readonly TRANSCRIPTION_FAILED: 52403;
+    readonly AUDIO_FILE_NOT_FOUND: 52404;
+    readonly TRANSLATION_FAILED: 52405;
+    readonly COMPLETION_FAILED: 52406;
+    readonly ATTACHMENT_NOT_FOUND: 52407;
+    readonly CANCEL_FAILED: 52408;
+    readonly TEXT_TO_SPEECH_FAILED: 52409;
+    readonly CONFIG_RELOAD_NOT_SUPPORTED: 52410;
+    readonly MODEL_TYPE_MISMATCH: 52411;
+    readonly OCR_FAILED: 52412;
+    readonly IMAGE_FILE_NOT_FOUND: 52413;
+    readonly INVALID_IMAGE_INPUT: 52414;
+    readonly TEXT_TO_SPEECH_STREAM_FAILED: 52415;
+    readonly MODEL_OPERATION_NOT_SUPPORTED: 52416;
+    readonly REQUEST_ID_CONFLICT: 52417;
+    readonly REQUEST_NOT_FOUND: 52418;
+    readonly INFERENCE_CANCELLED: 52419;
+    readonly REQUEST_REJECTED_BY_POLICY: 52420;
+    readonly CONTEXT_OVERFLOW: 52421;
+    readonly INVALID_AUDIO_INPUT: 52422;
+    readonly RAG_SAVE_FAILED: 52800;
+    readonly RAG_SEARCH_FAILED: 52801;
+    readonly RAG_DELETE_FAILED: 52802;
+    readonly RAG_UNKNOWN_OPERATION: 52803;
+    readonly RAG_HYPERDB_FAILED: 52804;
+    readonly RAG_WORKSPACE_MODEL_MISMATCH: 52805;
+    readonly RAG_WORKSPACE_NOT_FOUND: 52806;
+    readonly RAG_WORKSPACE_IN_USE: 52807;
+    readonly RAG_WORKSPACE_CLOSE_FAILED: 52808;
+    readonly RAG_LIST_WORKSPACES_FAILED: 52809;
+    readonly RAG_CHUNK_FAILED: 52810;
+    readonly RAG_WORKSPACE_NOT_OPEN: 52811;
+    readonly FILE_NOT_FOUND: 53000;
+    readonly DOWNLOAD_CANCELLED: 53001;
+    readonly CHECKSUM_VALIDATION_FAILED: 53002;
+    readonly HTTP_ERROR: 53003;
+    readonly NO_RESPONSE_BODY: 53004;
+    readonly RESPONSE_BODY_NOT_READABLE: 53005;
+    readonly NO_BLOB_FOUND: 53006;
+    readonly DOWNLOAD_ASSET_FAILED: 53007;
+    readonly SEEDING_NOT_SUPPORTED: 53008;
+    readonly HYPERDRIVE_DOWNLOAD_FAILED: 53009;
+    readonly INVALID_SHARD_URL_PATTERN: 53010;
+    readonly ARCHIVE_EXTRACTION_FAILED: 53011;
+    readonly ARCHIVE_UNSUPPORTED_TYPE: 53012;
+    readonly ARCHIVE_MISSING_SHARDS: 53013;
+    readonly PARTIAL_DOWNLOAD_OFFLINE: 53014;
+    readonly REGISTRY_DOWNLOAD_FAILED: 53015;
+    readonly INSECURE_MODEL_SOURCE: 53016;
+    readonly CHECKSUM_UNAVAILABLE: 53017;
+    readonly DELETE_CACHE_FAILED: 53200;
+    readonly INVALID_DELETE_CACHE_PARAMS: 53201;
+    readonly CACHE_DIR_NOT_ABSOLUTE: 53202;
+    readonly CACHE_DIR_NOT_WRITABLE: 53203;
+    readonly SET_CONFIG_FAILED: 53350;
+    readonly CONFIG_ALREADY_SET: 53351;
+    readonly FFMPEG_NOT_AVAILABLE: 53500;
+    readonly AUDIO_PLAYER_FAILED: 53501;
+    readonly INVALID_AUDIO_CHUNK_TYPE: 53502;
+    readonly ASYNC_DISPOSE_UNAVAILABLE: 53503;
+    readonly RPC_NO_DATA_RECEIVED: 53703;
+    readonly RPC_UNKNOWN_REQUEST_TYPE: 53704;
+    readonly PLUGIN_NOT_FOUND: 53850;
+    readonly PLUGIN_HANDLER_NOT_FOUND: 53851;
+    readonly PLUGIN_REQUEST_VALIDATION_FAILED: 53852;
+    readonly PLUGIN_RESPONSE_VALIDATION_FAILED: 53853;
+    readonly PLUGIN_ALREADY_REGISTERED: 53854;
+    readonly PLUGIN_HANDLER_TYPE_MISMATCH: 53855;
+    readonly PLUGIN_LOGGING_INVALID: 53856;
+    readonly PLUGIN_DEFINITION_INVALID: 53857;
+    readonly PLUGIN_MODEL_TYPE_RESERVED: 53858;
+    readonly PLUGIN_LOAD_CONFIG_VALIDATION_FAILED: 53859;
+    readonly LIFECYCLE_SUSPEND_FAILED: 53600;
+    readonly LIFECYCLE_RESUME_FAILED: 53601;
+    readonly LIFECYCLE_OPERATION_BLOCKED: 53602;
+    readonly PATH_TRAVERSAL: 53900;
+    readonly QVAC_MODEL_REGISTRY_QUERY_FAILED: 53950;
+};
+declare const serverErrorDefinitions: ErrorCodesMap;
+export { serverErrorDefinitions as SDK_SERVER_ERROR_DEFINITIONS };
+//# sourceMappingURL=sdk-errors-server.d.ts.map