# API Reference ## `SecureChatCompletion` High-level OpenAI-compatible client. The recommended entry point for most use cases. ### Constructor ```typescript new SecureChatCompletion(config?: ChatCompletionConfig) ``` #### `ChatCompletionConfig` | Option | Type | Default | Description | | ----------------------- | ----------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `baseUrl` | `string` | `'https://api.nomyo.ai'` | NOMYO router URL. Must be HTTPS in production. | | `allowHttp` | `boolean` | `false` | Allow HTTP connections.**Local development only.** | | `apiKey` | `string` | `undefined` | Bearer token sent in`Authorization` header. | | `secureMemory` | `boolean` | `true` | Enable immediate zeroing of sensitive buffers after use. | | `timeout` | `number` | `60000` | Request timeout in milliseconds. | | `debug` | `boolean` | `false` | Print verbose logging to the console. | | `keyDir` | `string` | `'client_keys'` | Directory to load/save RSA keys on startup. If the directory contains an existing key pair it is loaded; otherwise a new pair is generated and saved there. Node.js only. | | `keyRotationInterval` | `number` | `86400000` (24 h) | Auto-rotate RSA keys every N milliseconds. Set to`0` to disable. | | `keyRotationDir` | `string` | `'client_keys'` | Directory where rotated key files are saved. Node.js only. | | `keyRotationPassword` | `string` | `undefined` | Password used to encrypt rotated key files. | | `maxRetries` | `number` | `2` | Maximum extra attempts on retryable errors (429, 500, 502, 503, 504, network errors). Uses exponential backoff (1 s, 2 s, …). Set to`0` to disable retries. | ### Methods #### `create(request): Promise` Send an encrypted chat completion request. Returns the decrypted response. ```typescript async create(request: ChatCompletionRequest): Promise ``` **`ChatCompletionRequest` fields:** | Field | Type | Description | | --------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `model` | `string` | **Required.** Model ID (see [Models](models.md)). | | `messages` | `Message[]` | **Required.** Conversation history. | | `temperature` | `number` | Sampling temperature (0–2). | | `top_p` | `number` | Nucleus sampling. | | `max_tokens` | `number` | Maximum tokens to generate. | | `stop` | `string | string[]` | Stop sequences. | | `n` | `number` | Number of completions to generate. | | `stream` | `boolean` | Ignored server-side (encryption requires full response). | | `presence_penalty` | `number` | Presence penalty (−2.0–2.0). | | `frequency_penalty` | `number` | Frequency penalty (−2.0–2.0). | | `logit_bias` | `Record` | Token bias map. | | `user` | `string` | End-user identifier (passed through). | | `tools` | `Tool[]` | Tool/function definitions. | | `tool_choice` | `ToolChoice` | Tool selection strategy (`"auto"`, `"none"`, `"required"`, or specific tool). | | `security_tier` | `string` | NOMYO-specific.`"standard"` \| `"high"` \| `"maximum"`. Not encrypted into the payload. | | `api_key` | `string` | NOMYO-specific. Per-request API key override. Not encrypted into the payload. | | `base_url` | `string` | NOMYO-specific. Per-request router URL override. Creates a temporary client for this one call. Not encrypted into the payload. | **Response shape (`ChatCompletionResponse`):** ```typescript { id: string; object: 'chat.completion'; created: number; model: string; choices: Array<{ index: number; message: { role: string; content: string; tool_calls?: ToolCall[]; // present if tools were invoked reasoning_content?: string; // chain-of-thought (Qwen3, DeepSeek-R1, etc.) }; finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | null; }>; usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number; }; _metadata?: { payload_id: string; // echoes the X-Payload-ID sent with the request processed_at: number; // Unix timestamp of server-side processing is_encrypted: boolean; // always true for this endpoint encryption_algorithm: string; // e.g. "hybrid-aes256-rsa4096" response_status: string; // "success" on success security_tier?: string; // active tier used by the server memory_protection?: { platform: string; memory_locking: boolean; secure_zeroing: boolean; core_dump_prevention: boolean; }; cuda_device?: { available: boolean; device_hash: string; // SHA-256 of device name (not the raw name) }; }; } ``` #### `acreate(request): Promise` Alias for `create()`. Provided for code that follows the OpenAI SDK naming convention. #### `dispose(): void` Stop the key-rotation timer and sever in-memory RSA key references so they can be garbage-collected. After calling `dispose()`, all methods throw `DisposedError`. ```javascript client.dispose(); ``` --- ## `SecureCompletionClient` Lower-level client that exposes key management and individual encryption/decryption operations. Use this when you need fine-grained control; for most use cases prefer `SecureChatCompletion`. ### Constructor ```typescript new SecureCompletionClient(config?: ClientConfig) ``` #### `ClientConfig` All options from `ChatCompletionConfig`, plus: | Option | Type | Default | Description | | ------------- | --------------- | -------------------------------- | --------------------------------------------------------------- | | `routerUrl` | `string` | `'https://api.nomyo.ai'` | NOMYO router base URL. | | `keySize` | `2048 | 4096` | `4096` | RSA modulus length. 2048 is accepted but 4096 is recommended. | (`baseUrl` is renamed to `routerUrl` at this level; all other options are identical.) ### Methods #### `generateKeys(options?): Promise` Generate a fresh RSA key pair. ```typescript await client.generateKeys({ keySize?: 2048 | 4096, // default: 4096 saveToFile?: boolean, // default: false keyDir?: string, // default: 'client_keys' password?: string, // minimum 8 characters if provided }); ``` #### `loadKeys(privateKeyPath, publicKeyPath?, password?): Promise` Load an existing key pair from PEM files. Node.js only. ```typescript await client.loadKeys( 'client_keys/private_key.pem', 'client_keys/public_key.pem', // optional; derived from private key path if omitted 'your-password' // required if private key is encrypted ); ``` #### `fetchServerPublicKey(): Promise` Fetch the server's RSA public key from `/pki/public_key` over HTTPS. Called automatically on every encryption; exposed for diagnostics. #### `encryptPayload(payload): Promise` Encrypt a request payload. Returns the encrypted binary package ready to POST. #### `decryptResponse(encrypted, payloadId): Promise` Decrypt a response body received from the secure endpoint. #### `sendSecureRequest(payload, payloadId, apiKey?, securityTier?): Promise` Full encrypt → POST → decrypt cycle with retry logic. Called internally by `SecureChatCompletion.create()`. #### `dispose(): void` Same as `SecureChatCompletion.dispose()`. --- ## Secure Memory API ```typescript import { getMemoryProtectionInfo, disableSecureMemory, enableSecureMemory, SecureByteContext, } from 'nomyo-js'; ``` ### `getMemoryProtectionInfo(): ProtectionInfo` Returns information about the memory protection available on the current platform: ```typescript interface ProtectionInfo { canLock: boolean; // true if mlock is available (requires native addon) isPlatformSecure: boolean; method: 'mlock' | 'zero-only' | 'none'; details?: string; } ``` ### `disableSecureMemory(): void` Disable secure-memory zeroing globally. Affects new `SecureByteContext` instances that do not pass an explicit `useSecure` argument. Existing client instances are unaffected (they pass `useSecure` explicitly). ### `enableSecureMemory(): void` Re-enable secure memory operations globally. ### `SecureByteContext` Low-level context manager that zeros an `ArrayBuffer` in a `finally` block even if an exception occurs. Analogous to Python's `secure_bytearray()` context manager. ```typescript const context = new SecureByteContext(sensitiveBuffer); const result = await context.use(async (data) => { return doSomethingWith(data); }); // sensitiveBuffer is zeroed here regardless of whether doSomethingWith threw ``` --- ## Error Classes All errors are exported from the package root. ```typescript import { APIError, AuthenticationError, InvalidRequestError, RateLimitError, ForbiddenError, ServerError, ServiceUnavailableError, APIConnectionError, SecurityError, DisposedError, } from 'nomyo-js'; ``` | Class | HTTP status | Thrown when | | --------------------------- | ------------- | -------------------------------------------------------------- | | `AuthenticationError` | 401 | Invalid or missing API key | | `InvalidRequestError` | 400 | Malformed request (e.g. streaming requested) | | `ForbiddenError` | 403 | Model not allowed for the requested security tier | | `RateLimitError` | 429 | Rate limit exceeded (after all retries exhausted) | | `ServerError` | 500 | Internal server error (after all retries exhausted) | | `ServiceUnavailableError` | 503 | Inference backend unavailable (after all retries exhausted) | | `APIError` | varies | Other HTTP errors (404, 502, 504, etc.) | | `APIConnectionError` | — | Network failure or timeout (after all retries exhausted) | | `SecurityError` | — | HTTPS not used, header injection detected, or crypto failure | | `DisposedError` | — | Method called after`dispose()` | All errors that extend `APIError` expose `statusCode?: number` and `errorDetails?: object`.