nuabase 1.1.0 → 2.0.0

package/README.md

@@ -31,24 +31,23 @@ const LeadInsights = z.object({
 });
 ```
 
-**3. Declare the prompt.** Turn it into a typed function:
+**3. Call the API.** Use `list()` for array operations:
 
 ```ts
-const classifyLeads = new Nua().createArrayFn({
-  prompt: 'Classify each lead with industry and company_size bucket.',
-  output: {
-    name: 'leadInsights',
-    schema: LeadInsights,
-  },
+const nua = Nua.gateway({ apiKey: 'YOUR_API_KEY' });
+
+const result = await nua.list('Classify each lead with industry and company_size bucket.', {
+  input: leads,
+  primaryKey: 'id',
+  output: { name: 'leadInsights', schema: LeadInsights },
 });
 ```
 
-**4. Invoke.** Call it like any other async function:
+**4. Use the result.** Check for success and access typed data:
 
 ```ts
-const result = await classifyLeads.now(leads, 'id');
-if (result.isError) throw new Error(result.error);
-console.log(result.data[0].insights);
+if (!result.success) throw new Error(result.error);
+console.log(result.data[0].leadInsights);
 // -> { industry: 'Software', company_size: 'Mid-market' }
 ```
 
@@ -62,7 +61,7 @@ npm install nuabase zod
 
 2. Get your API key from the [Nuabase Console](https://console.nuabase.com/dashboard/api-keys/new).
 
-3. Set `NUABASE_API_KEY` environment variable, or pass it directly in `new Nua({apiKey: "KEY"})`):
+3. Set `NUABASE_API_KEY` environment variable, or pass it directly in `Nua.gateway({ apiKey: "KEY" })`:
 
 ## Lead Enrichment Example
 
@@ -70,7 +69,7 @@ npm install nuabase zod
 import { Nua } from 'nuabase';
 import { z } from 'zod';
 
-const nua = new Nua({ apiKey: 'API-KEY' });
+const nua = Nua.gateway({ apiKey: 'API-KEY' });
 
 const LeadInsights = z.object({
   company_name: z.string(),
@@ -79,15 +78,6 @@ const LeadInsights = z.object({
   recommended_follow_up: z.enum(['Call', 'Email', 'Event']),
 });
 
-const enrichLeads = nua.createArrayFn({
-  prompt:
-    'Summarize each inbound lead by extracting company_name, industry, company_size bucket (SMB, Mid-market, Enterprise), and the recommended_follow_up channel (Call, Email, or Event) based on their notes.',
-  output: {
-    name: 'leadInsights',
-    schema: LeadInsights,
-  },
-});
-
 const rows = [
   {
     leadId: 'lead-101',
@@ -107,22 +97,29 @@ const rows = [
   },
 ];
 
-const response = await enrichLeads.now(rows, 'leadId'); // `leadId` is the primary key field
+const response = await nua.list(
+  'Summarize each inbound lead by extracting company_name, industry, company_size bucket (SMB, Mid-market, Enterprise), and the recommended_follow_up channel (Call, Email, or Event) based on their notes.',
+  {
+    input: rows,
+    primaryKey: 'leadId',
+    output: { name: 'leadInsights', schema: LeadInsights },
+  }
+);
 
-if (response.isError) {
+if (!response.success) {
   console.error(response.error);
   return;
 }
 
-response.data.forEach(({ id, leadInsights }) => {
+response.data.forEach(({ leadId, leadInsights }) => {
   // leadInsights satisfies the LeadInsights schema
-  console.log(id, leadInsights.company_name, leadInsights.industry, leadInsights.company_size);
+  console.log(leadId, leadInsights.company_name, leadInsights.industry, leadInsights.company_size);
 });
 
 console.log(response.data);
 // -> [
 //   {
-//     id: 'lead-101',
+//     leadId: 'lead-101',
 //     leadInsights: {
 //       company_name: 'Acme Analytics',
 //       industry: 'Software',
@@ -134,7 +131,7 @@ console.log(response.data);
 // ];
 ```
 
-`map(data, primaryKey)` submits an asynchronous mapping job. But `map.now(data, primaryKey)` is immediate — it waits for completion and returns the full result.
+The default invocation waits for completion and returns the full result. Use `nua.queueList()` to submit an asynchronous job and receive streaming updates via SSE.
 
 ## Why Nuabase
 
@@ -145,55 +142,103 @@ console.log(response.data);
 
 ## API Response
 
-Every call returns a discriminated union. When `isError` is `true`, you get a flat error object. Otherwise `isSuccess` is `true`, and `data` contains rows merged with your typed output—along with metadata for observability and caching.
+Every call returns a discriminated union. When `success` is `false`, you get an error object. Otherwise `success` is `true`, and `data` contains your typed output along with metadata.
 
 **Success**
 
-| Field               | Type                                                                     | Description                                                                 |
-| ------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
-| `isSuccess`         | `true`                                                                   | Indicates that the request completed successfully.                          |
-| `data`              | `Array<{ [primaryKey]: unknown; [outputName]: z.infer<typeof output> }>` | Rows that merged the original primary key with the validated schema output. |
-| `llmRequestId`      | `string`                                                                 | Unique identifier for tracing each Nuabase LLM execution.                   |
-| `cacheHits`         | `number`                                                                 | Count of input rows served from Nuabase response cache.                     |
-| `rowsWithNoResults` | `string[]`                                                               | Primary keys that could not be resolved by the model.                       |
-| `isError`           | `false \| undefined`                                                     | Absent on success; included for type narrowing.                             |
+| Field       | Type                                                      | Description                                             |
+| ----------- | --------------------------------------------------------- | ------------------------------------------------------- |
+| `success`   | `true`                                                    | Indicates that the request completed successfully.      |
+| `data`      | `T` (for `get`) or `Array<{ [pk]: value; [output]: T }>` (for `list`) | The typed result matching your schema.    |
+| `usage`     | `{ promptTokens, completionTokens, totalTokens }`         | Token usage statistics for the LLM request.             |
+| `model`     | `string`                                                  | The LLM model used for this request.                    |
+| `latencyMs` | `number`                                                  | Request latency in milliseconds.                        |
+| `source`    | `'gateway'` \| `'direct'`                                 | Which backend processed the request.                    |
+| `meta`      | `object`                                                  | Additional metadata (varies by source).                 |
+
+**Gateway-specific metadata** (`meta` when `source` is `'gateway'`):
+
+| Field        | Type      | Description                                    |
+| ------------ | --------- | ---------------------------------------------- |
+| `requestId`  | `string`  | Unique identifier for tracing.                 |
+| `cached`     | `boolean` | Whether the result was served from cache.      |
+| `llmUsage`   | `object`  | Token usage from LLM calls.                    |
+| `cacheUsage` | `object`  | Token usage served from cache.                 |
 
 **Error**
 
-| Field     | Type     | Description                                              |
-| --------- | -------- | -------------------------------------------------------- |
-| `isError` | `true`   | Indicates the request failed.                            |
-| `error`   | `string` | Message describing the error returned by the API or SDK. |
+| Field       | Type                          | Description                                              |
+| ----------- | ----------------------------- | -------------------------------------------------------- |
+| `success`   | `false`                       | Indicates the request failed.                            |
+| `error`     | `string`                      | Message describing the error.                            |
+| `source`    | `'gateway'` \| `'direct'`     | Which backend returned the error.                        |
+| `latencyMs` | `number`                      | Time until failure in milliseconds.                      |
 
 ## SDK API
 
-**`new Nua(config?)`**
-Creates a client bound to your Nuabase account. Provide:
+### Constructors
+
+**`Nua.gateway(config?)`**
+Creates a client that connects to the Nuabase API gateway. Use this for production deployments with caching, request tracking, and async job support.
 
 - `apiKey?: string` – API key for authentication. Defaults to `process.env.NUABASE_API_KEY`.
 - `baseUrl?: string` – Override the API host. Defaults to `https://api.nuabase.com`.
 
-**`nua.map({ name, prompt, output })`**
-Declares a typed mapping function backed by Nuabase. Parameters:
+**`Nua.direct(config)`**
+Creates a client that calls LLM providers directly (in-process). Use this for serverless, edge functions, or CLI tools where you don't need the gateway infrastructure.
+
+- `model: string` – The model to use (e.g., `'gpt-4o-mini'`).
+- `providers: { openai?: { apiKey: string }, ... }` – Provider credentials.
+
+### Methods
+
+**`nua.get(prompt)`**
+Returns a simple string response from the LLM.
+
+```ts
+const result = await nua.get("Tell me a joke");
+if (result.success) console.log(result.data); // string
+```
+
+**`nua.get(prompt, options)`**
+Returns a typed single value. Parameters:
 
-- `name: string` – Label applied to the enriched payload in each response row (e.g., `result.data[i][name]`).
 - `prompt: string` – Natural-language instructions sent to the LLM.
-- `output: ZodSchema` – Zod schema describing the output shape. Nuabase stores the JSON Schema twin and validates responses against it before returning.
+- `options.input?: unknown` – Optional input data to include in the prompt.
+- `options.output: { name: string; schema: ZodSchema }` – Output name and Zod schema.
 
-Returns a callable object (the mapper) with two entry points:
+```ts
+const result = await nua.get("Extract the address", {
+  input: "123 Main St, Springfield, IL 62701",
+  output: { name: 'address', schema: AddressSchema },
+});
+if (result.success) console.log(result.data); // typed as z.infer<typeof AddressSchema>
+```
 
-- `mapper(data, primaryKey)` – Submits the job asynchronously and returns immediately with metadata and eventual results.
-- `mapper.now(data, primaryKey)` – Runs the job and waits until the full enriched result set is ready.
+**`nua.list(prompt, options)`**
+Processes an array of items. Parameters:
 
-Both entry points expect:
+- `prompt: string` – Natural-language instructions for each item.
+- `options.input: Array<Record<string, unknown>>` – Rows to process.
+- `options.primaryKey: string` – Field that uniquely identifies each row.
+- `options.output: { name: string; schema: ZodSchema }` – Output configuration.
 
-- `data: Array<Record<string, unknown>>` – Rows you want Nuabase to enrich. Each row must include the primary key.
-- `primaryKey: string` – Field name that uniquely identifies each row within `data`. The SDK throws if the field is missing on any item.
+```ts
+const result = await nua.list("Classify each lead", {
+  input: leads,
+  primaryKey: 'id',
+  output: { name: 'classification', schema: ClassificationSchema },
+});
+if (result.success) {
+  result.data.forEach(row => console.log(row.id, row.classification));
+}
+```
 
-Both entry points resolve to either:
+**`nua.queueGet(prompt, options?)`** *(Gateway mode only)*
+Submits an async job for single-value operations. Returns `{ success: true, jobId }`.
 
-- **Success** – `{ isSuccess: true, data, llmRequestId, cacheHits, rowsWithNoResults }`.
-- **Error** – `{ isError: true, error }`.
+**`nua.queueList(prompt, options)`** *(Gateway mode only)*
+Submits an async job for array operations. Returns `{ success: true, jobId }`.
 
 ## Next Steps
 
@@ -204,6 +249,10 @@ Both entry points resolve to either:
 
 Email us at [hello@nuabase.com](mailto:hello@nuabase.com). On X at [@NuabaseHQ](x.com/NuabaseHQ).
 
+## Tests
+
+See [TESTING.md](TESTING.md)
+
 ## Credits
 
 The template for this package comes from https://github.com/rtivital/ts-package-template