@onyx.dev/onyx-database 1.0.3 → 1.2.0

package/README.md

@@ -18,8 +18,10 @@ 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)
 - [Examples](#usage-examples-with-user-role-permission)
 - [Error handling](#error-handling)
 - [HTTP retries](#http-retries)
@@ -91,6 +93,7 @@ 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`)
 
 ```ts
 import { onyx } from '@onyx.dev/onyx-database';
@@ -106,6 +109,7 @@ 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
   databaseId: 'YOUR_DATABASE_ID',
   apiKey: 'YOUR_KEY',
   apiSecret: 'YOUR_SECRET',
@@ -178,6 +182,105 @@ 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. 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 completion = await db.chat().create({
+  model: 'onyx-chat',
+  messages: [{ role: 'user', content: 'Summarize last week’s traffic.' }],
+});
+console.log(completion.choices[0]?.message?.content);
+```
+
+Streaming works as an async iterable:
+
+```ts
+const stream = await db.chat().create({
+  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.chat().create(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.chat().create({
+    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.getModels();
+const chatModel = await db.getModel('onyx-chat');
+```
+
+### Script mutation approvals
+
+```ts
+const approval = await db.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.
@@ -410,7 +513,7 @@ import {
   between,
   gt, gte, lt, lte,
   like, notLike, contains, notContains,
-  startsWith, notStartsWith, matches, notMatches,
+  startsWith, notStartsWith, matches, notMatches, search,
   isNull, notNull,
   asc, desc
 } from '@onyx.dev/onyx-database';
@@ -418,6 +521,7 @@ import {
 
 - Prefer `within`/`notWithin` for inclusion checks (supports arrays, comma-separated strings, or inner queries).  
 - `inOp`/`notIn` remain available for backward compatibility and are exact aliases.
+- `search(text, minScore?)` builds a Lucene `MATCHES` predicate on `__full_text__` and always serializes `minScore` (null when omitted).
 
 ### Inner queries (IN/NOT IN with sub-selects)
 
@@ -453,6 +557,42 @@ const rolesMissingPermission = await db
 
 ---
 
+## Full-text search (Lucene)
+
+Use `.search(text, minScore?)` on a query builder for table-level full-text search, or call `db.search(...)` to target **all** tables (`table = "ALL"` in the request body). The search value always includes `minScore` and falls back to `null` when you omit it.
+
+```ts
+import { desc, eq, onyx, search, tables, type Schema } from '@onyx.dev/onyx-database';
+
+const db = onyx.init<Schema>();
+
+// Table-specific search with a minimum score
+const recentUsers = await db
+  .from(tables.User)
+  .search('user bio text', 4.4)
+  .orderBy(desc('createdAt'))
+  .limit(5)
+  .list();
+
+// Search across all tables (table: "ALL")
+const acrossTables = await db.search('user bio text').list({ pageSize: 5 });
+
+// Combine a search predicate with other filters
+const activeMatch = await db
+  .from(tables.User)
+  .where(search('user bio text'))
+  .and(eq('isActive', true))
+  .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`
 
 > The examples assume your schema has tables named `User`, `Role`, and `Permission`.  

package/dist/{aggregates-BGXzij4U.d.cts → aggregates-LoteczVS.d.cts}

@@ -7,6 +7,11 @@
  * ```
  */
 type QueryCriteriaOperator = 'EQUAL' | 'NOT_EQUAL' | 'IN' | 'NOT_IN' | 'GREATER_THAN' | 'GREATER_THAN_EQUAL' | 'LESS_THAN' | 'LESS_THAN_EQUAL' | 'MATCHES' | 'NOT_MATCHES' | 'BETWEEN' | 'LIKE' | 'NOT_LIKE' | 'CONTAINS' | 'CONTAINS_IGNORE_CASE' | 'NOT_CONTAINS' | 'NOT_CONTAINS_IGNORE_CASE' | 'STARTS_WITH' | 'NOT_STARTS_WITH' | 'IS_NULL' | 'NOT_NULL';
+/** Value payload for full-text (Lucene) searches. */
+interface FullTextQuery {
+    queryText: string;
+    minScore: number | null;
+}
 /** Logical operator used to join conditions in a query. */
 type LogicalOperator = 'AND' | 'OR';
 /**
@@ -133,6 +138,7 @@ type QueryCondition = {
  */
 interface SelectQuery {
     type: 'SelectQuery';
+    table?: string | null;
     fields?: string[] | null;
     conditions?: QueryCondition | null;
     sort?: Sort[] | null;
@@ -473,6 +479,16 @@ interface IQueryBuilder<T = unknown> {
      * ```
      */
     resolve(...values: Array<string | string[]>): IQueryBuilder<T>;
+    /**
+     * Adds a Lucene full-text search predicate.
+     * @example
+     * ```ts
+     * const results = await db.from('User').search('hello world', 4.4).list();
+     * ```
+     * @param queryText - Text to match against `__full_text__`.
+     * @param minScore - Optional minimum score; serializes as `null` when omitted.
+     */
+    search(queryText: string, minScore?: number | null): IQueryBuilder<T>;
     /**
      * Adds a filter condition.
      * @example
@@ -798,6 +814,10 @@ 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;
@@ -824,7 +844,187 @@ 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 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 IOnyxDatabase<Schema = Record<string, unknown>> {
+    /**
+     * Access OpenAI-compatible chat completions.
+     *
+     * @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(): AiChatClient;
+    /**
+     * List available AI models.
+     *
+     * @example
+     * ```ts
+     * const models = await db.getModels();
+     * ```
+     */
+    getModels(): Promise<AiModelsResponse>;
+    /**
+     * Retrieve a single AI model by ID.
+     *
+     * @example
+     * ```ts
+     * const model = await db.getModel('onyx-chat');
+     * ```
+     */
+    getModel(modelId: string): Promise<AiModel>;
+    /**
+     * Request mutation approval for a script.
+     *
+     * @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.
      *
@@ -861,6 +1061,18 @@ interface IOnyxDatabase<Schema = Record<string, unknown>> {
      * @param fields Field names to project; omit to select all.
      */
     select(...fields: string[]): IQueryBuilder<Record<string, unknown>>;
+    /**
+     * Run a Lucene full-text search across all tables.
+     *
+     * @example
+     * ```ts
+     * const results = await db.search('hello world', 4.4).list();
+     * ```
+     *
+     * @param queryText Text to match against `__full_text__`.
+     * @param minScore Optional minimum score; serialized as `null` when omitted.
+     */
+    search(queryText: string, minScore?: number | null): IQueryBuilder<Record<string, unknown>>;
     /**
      * Include related records in the next save or delete.
      *
@@ -1395,6 +1607,7 @@ declare const gte: (field: string, value: unknown) => ConditionBuilderImpl;
 declare const lt: (field: string, value: unknown) => ConditionBuilderImpl;
 declare const lte: (field: string, value: unknown) => ConditionBuilderImpl;
 declare const matches: (field: string, regex: string) => ConditionBuilderImpl;
+declare const search: (queryText: string, minScore?: number | null) => ConditionBuilderImpl;
 declare const notMatches: (field: string, regex: string) => ConditionBuilderImpl;
 declare const like: (field: string, pattern: string) => ConditionBuilderImpl;
 declare const notLike: (field: string, pattern: string) => ConditionBuilderImpl;
@@ -1421,4 +1634,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 { within as $, type QueryCriteriaOperator as A, type Sort as B, type StreamAction as C, type OnyxDocument as D, type FetchImpl as E, type FetchResponse as F, type QueryCriteria as G, type QueryCondition as H, type IOnyxDatabase as I, type SelectQuery as J, type QueryPage as K, type LogicalOperator as L, type IConditionBuilder as M, type IQueryBuilder as N, type OnyxFacade as O, type ISaveBuilder as P, QueryResults as Q, type RetryOptions as R, type SecretMetadata as S, type ICascadeBuilder as T, type UpdateQuery as U, type ICascadeRelationshipBuilder as V, asc as W, desc as X, eq as Y, neq as Z, inOp as _, type QueryResultsPromise as a, notIn as a0, notWithin as a1, between as a2, gt as a3, gte as a4, lt as a5, lte as a6, matches as a7, notMatches as a8, like 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 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 SchemaDiff as $, type AiRequestOptions as A, type SchemaDataType as B, type SchemaIdentifierGenerator as C, type SchemaIdentifier as D, type SchemaAttribute as E, type FullTextQuery as F, type SchemaIndexType as G, type SchemaIndex as H, type IOnyxDatabase as I, type SchemaResolver as J, type SchemaTriggerEvent as K, type SchemaTrigger as L, type SchemaEntity as M, type SchemaRevisionMetadata as N, type OnyxFacade as O, type SchemaRevision as P, QueryResults as Q, type RetryOptions as R, type SecretMetadata as S, type SchemaHistoryEntry as T, type SchemaUpsertRequest as U, type SchemaValidationResult as V, type SchemaAttributeChange as W, type SchemaIndexChange as X, type SchemaResolverChange as Y, type SchemaTriggerChange as Z, type SchemaTableDiff as _, type QueryResultsPromise as a, type QueryCriteriaOperator as a0, type LogicalOperator as a1, type Sort as a2, type StreamAction as a3, type OnyxDocument as a4, type FetchResponse as a5, type FetchImpl as a6, type QueryCriteria as a7, type QueryCondition as a8, type SelectQuery as a9, containsIgnoreCase as aA, notContains as aB, notContainsIgnoreCase as aC, startsWith as aD, notStartsWith as aE, isNull as aF, notNull as aG, avg as aH, sum as aI, count as aJ, min as aK, max as aL, std as aM, variance as aN, median as aO, upper as aP, lower as aQ, substring as aR, replace as aS, percentile as aT, type UpdateQuery as aa, type QueryPage as ab, type IConditionBuilder as ac, type IQueryBuilder as ad, type ISaveBuilder as ae, type ICascadeBuilder as af, type ICascadeRelationshipBuilder as ag, asc as ah, desc as ai, eq as aj, neq as ak, inOp as al, within as am, notIn as an, notWithin as ao, between as ap, gt as aq, gte as ar, lt as as, lte as at, matches as au, search as av, notMatches as aw, like as ax, notLike as ay, contains 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 AiChatClient as r, type AiScriptApprovalRequest as s, type AiScriptApprovalResponse as t, type AiModelsResponse as u, type AiModel as v, type AiErrorResponse as w, type SecretRecord as x, type SecretsListResponse as y, type SecretSaveRequest as z };