@onyx.dev/onyx-database 1.1.0 → 2.0.0

package/README.md

@@ -18,6 +18,7 @@ TypeScript client SDK for **Onyx Cloud Database** — a zero-dependency, strict-
 - [Getting started](#getting-started-cloud--keys--connect)
 - [Install](#install)
 - [Initialize the client](#initialize-the-client)
+- [Onyx AI (chat & models)](#onyx-ai-chat--models)
 - [Generate schema types](#optional-generate-typescript-types-from-your-schema)
 - [Query helpers](#query-helpers-at-a-glance)
 - [Full-text search](#full-text-search-lucene)
@@ -92,6 +93,8 @@ Set the following environment variables for your database:
 - `ONYX_DATABASE_BASE_URL`
 - `ONYX_DATABASE_API_KEY`
 - `ONYX_DATABASE_API_SECRET`
+- `ONYX_AI_BASE_URL` (optional; defaults to `https://ai.onyx.dev`)
+- `ONYX_DEFAULT_MODEL` (optional; used by `db.chat('...')`, defaults to `onyx`)
 
 ```ts
 import { onyx } from '@onyx.dev/onyx-database';
@@ -107,6 +110,8 @@ import { onyx } from '@onyx.dev/onyx-database';
 
 const db = onyx.init({
   baseUrl: 'https://api.onyx.dev',
+  aiBaseUrl: 'https://ai.onyx.dev', // optional: override AI base path
+  defaultModel: 'onyx', // optional: shorthand `db.chat()` model
   databaseId: 'YOUR_DATABASE_ID',
   apiKey: 'YOUR_KEY',
   apiSecret: 'YOUR_SECRET',
@@ -179,6 +184,115 @@ necessary unless you create many short‑lived clients.
 
 ---
 
+## Onyx AI (chat & models)
+
+AI endpoints are OpenAI-compatible and use the same credentials as database calls. Use `db.ai` for chat, models, and script approvals; `db.chat()`/`db.chat('...')` remain supported as equivalent entrypoints. A shorthand `db.chat('content')` call is available and uses `config.defaultModel` (defaults to `onyx`). The AI base URL defaults to `https://ai.onyx.dev` and can be overridden with `aiBaseUrl` (or `ONYX_AI_BASE_URL`). The `databaseId` query param is optional; when omitted, the configured databaseId is used for grounding and billing.
+
+### Chat completions
+
+Examples: `examples/ai/chat.ts`, `examples/ai/chat-stream.ts`.
+
+```ts
+import { onyx } from '@onyx.dev/onyx-database';
+
+const db = onyx.init();
+
+const quick = await db.chat('Reply with exactly one short greeting sentence.'); // returns first message content
+
+const completion = await db.ai.chat({
+  model: 'onyx-chat',
+  messages: [{ role: 'user', content: 'Summarize last week’s traffic.' }],
+});
+console.log(completion.choices[0]?.message?.content);
+
+// Override defaults (model/role/temperature/stream) in shorthand form
+const custom = await db.chat('List three colors.', {
+  model: 'onyx-chat',
+  role: 'user',
+  temperature: 0.2,
+  stream: false, // set raw: true to receive full completion response instead of the first message content
+});
+```
+
+Streaming works as an async iterable:
+
+```ts
+const stream = await db.ai.chat({
+  model: 'onyx-chat',
+  stream: true,
+  messages: [{ role: 'user', content: 'Write a short onboarding checklist.' }],
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+}
+// stream.cancel() is available if you need to stop early
+```
+
+Tool calls mirror the ChatGPT TypeScript client:
+
+```ts
+const prompt = {
+  model: 'onyx-chat',
+  messages: [{ role: 'user', content: 'Find revenue for ACME in 2023.' }],
+  tools: [
+    {
+      type: 'function',
+      function: {
+        name: 'get_revenue',
+        description: 'Fetch revenue for a company and year',
+        parameters: {
+          type: 'object',
+          properties: {
+            company: { type: 'string' },
+            year: { type: 'number' },
+          },
+          required: ['company', 'year'],
+        },
+      },
+    },
+  ],
+};
+
+const first = await db.ai.chat(prompt);
+const toolCall = first.choices[0]?.message?.tool_calls?.[0];
+
+if (toolCall) {
+  const toolResult = await getRevenue(JSON.parse(toolCall.function.arguments)); // your impl
+  const followup = await db.ai.chat({
+    model: prompt.model,
+    messages: [
+      ...prompt.messages,
+      first.choices[0].message,
+      { role: 'tool', tool_call_id: toolCall.id ?? '', content: JSON.stringify(toolResult) },
+    ],
+  });
+  console.log(followup.choices[0]?.message?.content);
+}
+```
+
+### Model metadata
+
+Example: `examples/ai/models.ts`.
+
+```ts
+const models = await db.ai.getModels();
+const chatModel = await db.ai.getModel('onyx-chat');
+```
+
+### Script mutation approvals
+
+```ts
+const approval = await db.ai.requestScriptApproval({
+  script: "db.save({ id: 'u1', email: 'a@b.com' })",
+});
+if (approval.requiresApproval) {
+  console.log(`Requires approval until ${approval.expiresAtIso}`);
+}
+```
+
+---
+
 ## Optional: generate TypeScript types from your schema
 
 The package ships a small codegen CLI that emits per-table interfaces, a `tables` enum, and a `Schema` mapping for compile-time safety and IntelliSense. Each generated interface also includes an index signature so extra properties (for graph attachments in cascade saves) don't trigger type errors.
@@ -483,6 +597,12 @@ const activeMatch = await db
   .firstOrNull();
 ```
 
+**Examples**
+- Table search (minScore null): `examples/query/lucine-table-search.ts`
+- Table search (minScore 4.4): `examples/query/lucine-table-search-min-score.ts`
+- ALL tables search (minScore null): `examples/query/lucine-search-all-tables.ts`
+- ALL tables search (minScore 4.4): `examples/query/lucine-search-all-tables-min-score.ts`
+
 ---
 
 ## Usage examples with `User`, `Role`, `Permission`

package/dist/{aggregates-DodZNu9-.d.cts → aggregates-BJT5DGGX.d.cts}

@@ -814,10 +814,18 @@ interface RetryOptions {
 }
 interface OnyxConfig {
     baseUrl?: string;
+    /**
+     * Base URL for AI endpoints. Defaults to https://ai.onyx.dev.
+     */
+    aiBaseUrl?: string;
     databaseId?: string;
     apiKey?: string;
     apiSecret?: string;
     fetch?: FetchImpl;
+    /**
+     * Default AI model when using shorthand chat calls (`db.chat('...')`). Defaults to `onyx`.
+     */
+    defaultModel?: string;
     /**
      * Default partition for queries, `findById`, and deletes when removing by
      * primary key. Saves rely on the entity's partition field instead.
@@ -840,7 +848,306 @@ interface OnyxConfig {
      */
     retry?: RetryOptions;
 }
+interface AiRequestOptions {
+    /**
+     * Optional database scope for AI calls. Defaults to the configured databaseId.
+     */
+    databaseId?: string;
+}
+type AiChatRole = 'system' | 'user' | 'assistant' | 'tool';
+interface AiToolCallFunction {
+    name: string;
+    arguments: string;
+}
+interface AiToolCall {
+    id?: string | null;
+    type?: string | null;
+    function: AiToolCallFunction;
+}
+interface AiChatMessage {
+    role: AiChatRole;
+    content?: string | null;
+    tool_calls?: AiToolCall[] | null;
+    tool_call_id?: string | null;
+    name?: string | null;
+}
+interface AiToolFunction {
+    name: string;
+    description?: string | null;
+    parameters?: Record<string, unknown> | null;
+}
+interface AiTool {
+    type: string;
+    function: AiToolFunction;
+}
+type AiToolChoice = 'none' | 'auto' | {
+    type: 'function';
+    function: {
+        name: string;
+    };
+} | null;
+interface AiChatCompletionRequest {
+    model: string;
+    messages: AiChatMessage[];
+    stream?: boolean;
+    temperature?: number | null;
+    top_p?: number | null;
+    max_tokens?: number | null;
+    metadata?: Record<string, unknown>;
+    tools?: AiTool[];
+    tool_choice?: AiToolChoice;
+    user?: string | null;
+}
+interface AiChatCompletionUsage {
+    prompt_tokens?: number | null;
+    completion_tokens?: number | null;
+    total_tokens?: number | null;
+}
+interface AiChatCompletionChoice {
+    index: number;
+    message: AiChatMessage;
+    finish_reason?: string | null;
+}
+interface AiChatCompletionResponse {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: AiChatCompletionChoice[];
+    usage?: AiChatCompletionUsage;
+}
+interface AiChatCompletionChunkDelta {
+    role?: AiChatRole | null;
+    content?: string | null;
+    tool_calls?: AiToolCall[] | null;
+    tool_call_id?: string | null;
+    name?: string | null;
+}
+interface AiChatCompletionChunkChoice {
+    index: number;
+    delta: AiChatCompletionChunkDelta;
+    finish_reason?: string | null;
+}
+interface AiChatCompletionChunk {
+    id: string;
+    object: string;
+    created: number;
+    model?: string | null;
+    choices: AiChatCompletionChunkChoice[];
+}
+interface AiChatCompletionStream extends AsyncIterable<AiChatCompletionChunk> {
+    cancel(): void;
+}
+interface AiChatOptions extends AiRequestOptions {
+    /**
+     * Model to use for the shorthand `db.chat()` call. Defaults to config.defaultModel or `onyx`.
+     */
+    model?: string;
+    /**
+     * Role for the constructed message. Defaults to `user`.
+     */
+    role?: AiChatRole;
+    /**
+     * Temperature for the completion. Omit to use the service default.
+     */
+    temperature?: number | null;
+    /**
+     * Enable SSE streaming. Defaults to `false`.
+     */
+    stream?: boolean;
+    /**
+     * When true, return the raw completion response instead of the first message content.
+     */
+    raw?: boolean;
+}
+interface AiChatClient {
+    create(request: AiChatCompletionRequest & {
+        stream?: false;
+    }, options?: AiRequestOptions): Promise<AiChatCompletionResponse>;
+    create(request: AiChatCompletionRequest & {
+        stream: true;
+    }, options?: AiRequestOptions): Promise<AiChatCompletionStream>;
+    create(request: AiChatCompletionRequest, options?: AiRequestOptions): Promise<AiChatCompletionResponse | AiChatCompletionStream>;
+}
+interface AiScriptApprovalRequest {
+    script: string;
+}
+interface AiScriptApprovalResponse {
+    normalizedScript: string;
+    expiresAtIso: string;
+    requiresApproval: boolean;
+    findings?: string;
+}
+interface AiModelsResponse {
+    object: string;
+    data: AiModel[];
+}
+interface AiModel {
+    id: string;
+    object: string;
+    created: number;
+    owned_by: string;
+}
+interface AiErrorResponse {
+    error?: string | {
+        message?: string;
+        [key: string]: unknown;
+    } | null;
+}
+interface AiClient {
+    /**
+     * Run a chat completion. Accepts shorthand strings or full requests.
+     *
+     * @example
+     * ```ts
+     * const quick = await db.ai.chat('Summarize last week.'); // returns first message content
+     * const completion = await db.ai.chat(
+     *   { model: 'onyx-chat', messages: [{ role: 'user', content: 'Summarize last week.' }] },
+     *   { databaseId: 'db1', raw: true }, // returns full response
+     * );
+     * ```
+     */
+    chat(content: string, options?: AiChatOptions & {
+        stream?: false;
+        raw?: false | undefined;
+    }): Promise<string>;
+    chat(content: string, options: AiChatOptions & {
+        stream: true;
+    }): Promise<AiChatCompletionStream>;
+    chat(content: string, options: AiChatOptions & {
+        raw: true;
+    }): Promise<AiChatCompletionResponse | AiChatCompletionStream>;
+    chat(request: AiChatCompletionRequest & {
+        stream?: false;
+    }, options?: AiRequestOptions): Promise<AiChatCompletionResponse>;
+    chat(request: AiChatCompletionRequest & {
+        stream: true;
+    }, options?: AiRequestOptions): Promise<AiChatCompletionStream>;
+    chat(request: AiChatCompletionRequest, options?: AiRequestOptions): Promise<AiChatCompletionResponse | AiChatCompletionStream>;
+    /**
+     * Access the chat client for more control over streaming and cancellation.
+     */
+    chatClient(): AiChatClient;
+    /**
+     * List available AI models.
+     *
+     * @example
+     * ```ts
+     * const models = await db.ai.getModels();
+     * ```
+     */
+    getModels(): Promise<AiModelsResponse>;
+    /**
+     * Retrieve a single AI model by ID.
+     *
+     * @example
+     * ```ts
+     * const model = await db.ai.getModel('onyx-chat');
+     * ```
+     */
+    getModel(modelId: string): Promise<AiModel>;
+    /**
+     * Request mutation approval for a script.
+     *
+     * @example
+     * ```ts
+     * const approval = await db.ai.requestScriptApproval({
+     *   script: "db.save({ id: 'u1', email: 'a@b.com' })"
+     * });
+     * ```
+     */
+    requestScriptApproval(input: AiScriptApprovalRequest): Promise<AiScriptApprovalResponse>;
+}
 interface IOnyxDatabase<Schema = Record<string, unknown>> {
+    /**
+     * AI helpers (chat, models, script approvals) grouped under `db.ai`.
+     *
+     * @example
+     * ```ts
+     * const completion = await db.ai.chat({
+     *   model: 'onyx-chat',
+     *   messages: [{ role: 'user', content: 'Summarize last week.' }],
+     * });
+     * ```
+     */
+    ai: AiClient;
+    /**
+     * Access OpenAI-compatible chat completions via `db.chat('...')` or `db.chat().create(...)`.
+     *
+     * @example
+     * ```ts
+     * const completion = await db.chat('Summarize last week.'); // returns first message content
+     * ```
+     *
+     * @example
+     * ```ts
+     * const chat = db.chat();
+     * const completion = await chat.create({
+     *   model: 'onyx-chat',
+     *   messages: [{ role: 'user', content: 'Summarize last week.' }],
+     * });
+     * ```
+     *
+     * @example
+     * ```ts
+     * const stream = await db
+     *   .chat()
+     *   .create({
+     *     model: 'onyx-chat',
+     *     stream: true,
+     *     messages: [{ role: 'user', content: 'Draft an onboarding checklist.' }],
+     *   });
+     * for await (const chunk of stream) {
+     *   process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+     * }
+     * ```
+     */
+    chat(content: string, options?: AiChatOptions & {
+        stream?: false;
+        raw?: false | undefined;
+    }): Promise<string>;
+    chat(content: string, options: AiChatOptions & {
+        stream: true;
+    }): Promise<AiChatCompletionStream>;
+    chat(content: string, options: AiChatOptions & {
+        raw: true;
+    }): Promise<AiChatCompletionResponse | AiChatCompletionStream>;
+    chat(): AiChatClient;
+    /**
+     * List available AI models.
+     *
+     * @deprecated Prefer `db.ai.getModels()`.
+     *
+     * @example
+     * ```ts
+     * const models = await db.getModels();
+     * ```
+     */
+    getModels(): Promise<AiModelsResponse>;
+    /**
+     * Retrieve a single AI model by ID.
+     *
+     * @deprecated Prefer `db.ai.getModel(...)`.
+     *
+     * @example
+     * ```ts
+     * const model = await db.getModel('onyx-chat');
+     * ```
+     */
+    getModel(modelId: string): Promise<AiModel>;
+    /**
+     * Request mutation approval for a script.
+     *
+     * @deprecated Prefer `db.ai.requestScriptApproval(...)`.
+     *
+     * @example
+     * ```ts
+     * const approval = await db.requestScriptApproval({
+     *   script: "db.save({ id: 'u1', email: 'a@b.com' })"
+     * });
+     * ```
+     */
+    requestScriptApproval(input: AiScriptApprovalRequest): Promise<AiScriptApprovalResponse>;
     /**
      * Begin a query against a table.
      *
@@ -1450,4 +1757,4 @@ declare const substring: (attribute: string, from: number, length: number) => st
 declare const replace: (attribute: string, pattern: string, repl: string) => string;
 declare const percentile: (attribute: string, p: number) => string;
 
-export { inOp as $, type QueryCriteriaOperator as A, type Sort as B, type StreamAction as C, type OnyxDocument as D, type FetchResponse as E, type FullTextQuery as F, type FetchImpl as G, type QueryCriteria as H, type IOnyxDatabase as I, type QueryCondition as J, type SelectQuery as K, type LogicalOperator as L, type QueryPage as M, type IConditionBuilder as N, type OnyxFacade as O, type IQueryBuilder as P, QueryResults as Q, type RetryOptions as R, type SecretMetadata as S, type ISaveBuilder as T, type UpdateQuery as U, type ICascadeBuilder as V, type ICascadeRelationshipBuilder as W, asc as X, desc as Y, eq as Z, neq as _, type QueryResultsPromise as a, within as a0, notIn as a1, notWithin as a2, between as a3, gt as a4, gte as a5, lt as a6, lte as a7, matches as a8, search as a9, notMatches as aa, like as ab, notLike as ac, contains as ad, containsIgnoreCase as ae, notContains as af, notContainsIgnoreCase as ag, startsWith as ah, notStartsWith as ai, isNull as aj, notNull as ak, avg as al, sum as am, count as an, min as ao, max as ap, std as aq, variance as ar, median as as, upper as at, lower as au, substring as av, replace as aw, percentile as ax, type OnyxConfig as b, type SecretRecord as c, type SecretsListResponse as d, type SecretSaveRequest as e, type SchemaDataType as f, type SchemaIdentifierGenerator as g, type SchemaIdentifier as h, type SchemaAttribute as i, type SchemaIndexType as j, type SchemaIndex as k, type SchemaResolver as l, type SchemaTriggerEvent as m, type SchemaTrigger as n, type SchemaEntity as o, type SchemaRevisionMetadata as p, type SchemaRevision as q, type SchemaHistoryEntry as r, type SchemaUpsertRequest as s, type SchemaValidationResult as t, type SchemaAttributeChange as u, type SchemaIndexChange as v, type SchemaResolverChange as w, type SchemaTriggerChange as x, type SchemaTableDiff as y, type SchemaDiff as z };
+export { type SchemaTriggerChange as $, type AiRequestOptions as A, type SecretsListResponse as B, type SecretSaveRequest as C, type SchemaDataType as D, type SchemaIdentifierGenerator as E, type FullTextQuery as F, type SchemaIdentifier as G, type SchemaAttribute as H, type IOnyxDatabase as I, type SchemaIndexType as J, type SchemaIndex as K, type SchemaResolver as L, type SchemaTriggerEvent as M, type SchemaTrigger as N, type OnyxFacade as O, type SchemaEntity as P, QueryResults as Q, type RetryOptions as R, type SecretMetadata as S, type SchemaRevisionMetadata as T, type SchemaRevision as U, type SchemaHistoryEntry as V, type SchemaUpsertRequest as W, type SchemaValidationResult as X, type SchemaAttributeChange as Y, type SchemaIndexChange as Z, type SchemaResolverChange as _, type QueryResultsPromise as a, type SchemaTableDiff as a0, type SchemaDiff as a1, type QueryCriteriaOperator as a2, type LogicalOperator as a3, type Sort as a4, type StreamAction as a5, type OnyxDocument as a6, type FetchResponse as a7, type FetchImpl as a8, type QueryCriteria as a9, notLike as aA, contains as aB, containsIgnoreCase as aC, notContains as aD, notContainsIgnoreCase as aE, startsWith as aF, notStartsWith as aG, isNull as aH, notNull as aI, avg as aJ, sum as aK, count as aL, min as aM, max as aN, std as aO, variance as aP, median as aQ, upper as aR, lower as aS, substring as aT, replace as aU, percentile as aV, type QueryCondition as aa, type SelectQuery as ab, type UpdateQuery as ac, type QueryPage as ad, type IConditionBuilder as ae, type IQueryBuilder as af, type ISaveBuilder as ag, type ICascadeBuilder as ah, type ICascadeRelationshipBuilder as ai, asc as aj, desc as ak, eq as al, neq as am, inOp as an, within as ao, notIn as ap, notWithin as aq, between as ar, gt as as, gte as at, lt as au, lte as av, matches as aw, search as ax, notMatches as ay, like as az, type OnyxConfig as b, type AiChatRole as c, type AiToolCallFunction as d, type AiToolCall as e, type AiChatMessage as f, type AiToolFunction as g, type AiTool as h, type AiToolChoice as i, type AiChatCompletionRequest as j, type AiChatCompletionUsage as k, type AiChatCompletionChoice as l, type AiChatCompletionResponse as m, type AiChatCompletionChunkDelta as n, type AiChatCompletionChunkChoice as o, type AiChatCompletionChunk as p, type AiChatCompletionStream as q, type AiChatOptions as r, type AiChatClient as s, type AiScriptApprovalRequest as t, type AiScriptApprovalResponse as u, type AiModelsResponse as v, type AiModel as w, type AiErrorResponse as x, type AiClient as y, type SecretRecord as z };