nomyo-ai/nomyo-js
2
0
Fork 0
Code Issues Pull requests 3 Projects Releases Packages Wiki Activity Actions
nomyo-js/doc/api-reference.md

273 lines
14 KiB
Markdown
Raw Normal View History

fix: base_url doc: created
2026-04-16 16:44:26 +02:00
# 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<ChatCompletionResponse>`
Send an encrypted chat completion request. Returns the decrypted response.
```typescript
async create(request: ChatCompletionRequest): Promise<ChatCompletionResponse>
```
**`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<string, number>` | 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<ChatCompletionResponse>`
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<void>`
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<void>`
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<string>`
Fetch the server's RSA public key from `/pki/public_key` over HTTPS. Called automatically on every encryption; exposed for diagnostics.
#### `encryptPayload(payload): Promise<ArrayBuffer>`
Encrypt a request payload. Returns the encrypted binary package ready to POST.
#### `decryptResponse(encrypted, payloadId): Promise<object>`
Decrypt a response body received from the secure endpoint.
#### `sendSecureRequest(payload, payloadId, apiKey?, securityTier?): Promise<object>`
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`.
Reference in a new issue Copy permalink