fix: base_url
doc: created
This commit is contained in:
parent
6e02559f4e
commit
43165f86f2
SSH key fingerprint:
SHA256:QkkAgVoYi9TQ0UKPkiKSfnerZy2h4qhi3SVPXJmBN+M
17 changed files with 2151 additions and 293 deletions
272
doc/api-reference.md
Normal file
272
doc/api-reference.md
Normal file
|
|
@ -0,0 +1,272 @@
|
|||
# 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`.
|
||||
Loading…
Add table
Add a link
Reference in a new issue