nuabase 1.0.1 → 1.2.0

package/README.md

@@ -46,9 +46,9 @@ const classifyLeads = new Nua().createArrayFn({
 **4. Invoke.** Call it like any other async function:
 
 ```ts
-const result = await classifyLeads.now(leads, 'id');
+const result = await classifyLeads(leads, 'id');
 if (result.isError) throw new Error(result.error);
-console.log(result.data[0].insights);
+console.log(result.data[0].leadInsights);
 // -> { industry: 'Software', company_size: 'Mid-market' }
 ```
 
@@ -107,34 +107,35 @@ const rows = [
   },
 ];
 
-const response = await enrichLeads.now(rows, 'leadId'); // `leadId` is the primary key field
+const response = await enrichLeads(rows, 'leadId'); // `leadId` is the primary key field
 
 if (response.isError) {
   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',
 //       company_size: 'Mid-market',
 //       recommended_follow_up: 'Call',
 //     },
+//     sourceRow: { leadId: 'lead-101', name: 'Acme Analytics', notes: '...' },
 //   },
 //   // ...
 // ];
 ```
 
-`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 `.queue(data, primaryKey)` to submit an asynchronous job and receive streaming updates via SSE.
 
 ## Why Nuabase
 
@@ -149,14 +150,15 @@ Every call returns a discriminated union. When `isError` is `true`, you get a fl
 
 **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                                                                                                                  |
+| ------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `isSuccess`         | `true`                                                                                         | Indicates that the request completed successfully.                                                                           |
+| `data`              | `Array<{ [primaryKey]: unknown; [outputName]: z.infer<typeof output>; sourceRow: InputRow }>` | Rows that merged the original primary key with the validated schema output, plus the full `sourceRow` for convenience.      |
+| `llmRequestId`      | `string`                                                                                       | Unique identifier for tracing each Nuabase LLM execution.                                                                    |
+| `usage`             | `{ promptTokens: number; completionTokens: number; totalTokens: number }`                      | Token usage statistics for the LLM request.                                                                                  |
+| `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.                                                                              |
 
 **Error**
 
@@ -173,28 +175,33 @@ Creates a client bound to your Nuabase account. Provide:
 - `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.createArrayFn({ prompt, output })`**
+Declares a typed array mapping function backed by Nuabase. 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.
+- `output: { name: string; schema: ZodSchema }` – Output configuration with a name and Zod schema describing the output shape.
 
-Returns a callable object (the mapper) with two entry points:
+Returns a callable function with two modes:
 
-- `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.
+- `fn(data, primaryKey)` – Default mode. Runs the job and waits until the full enriched result set is ready.
+- `fn.queue(data, primaryKey)` – Submits the job asynchronously and returns streaming metadata via SSE.
 
-Both entry points expect:
+Both modes expect:
 
 - `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.
 
-Both entry points resolve to either:
+Both modes resolve to either:
 
-- **Success** – `{ isSuccess: true, data, llmRequestId, cacheHits, rowsWithNoResults }`.
+- **Success** – `{ isSuccess: true, data, llmRequestId, usage, cacheHits, rowsWithNoResults }`.
 - **Error** – `{ isError: true, error }`.
 
+**`nua.createFn({ prompt, output })`**
+Declares a typed single-value function backed by Nuabase. Similar to `createArrayFn` but for processing a single input value instead of an array. Returns a function that accepts a single input value.
+
+**`nua.getRequest(llmRequestId)`**
+Retrieves request details for a completed LLM execution using its request ID.
+
 ## Next Steps
 
 - Create an API key or inspect request logs in the [Nuabase Console](https://console.nuabase.com/).

package/dist/cjs/index.cjs

@@ -2,6 +2,16 @@
 
 var zod = require('zod');
 
+function resolveConfigValue(config, key, envVar) {
+  if (config[key]) return config[key];
+  const pe = globalThis.process;
+  const isNode = !!pe?.versions?.node;
+  if (isNode) {
+    return pe?.env?.[envVar];
+  }
+  return void 0;
+}
+
 async function parseErrorResponse(response, urlPath) {
   const fallbackMessage = `Request to ${urlPath} failed with status ${response.status}${response.statusText ? ` ${response.statusText}` : ""}`;
   let responseBody = "";
@@ -45,27 +55,69 @@ function getErrorMessageFromException(error) {
   return String(error);
 }
 
-class NuabaseAPIClient {
-  constructor(config = {}) {
-    this.apiKey = config.apiKey || process.env.NUABASE_API_KEY || "";
-    this.baseUrl = config.baseUrl || process.env.NUABASE_API_URL || "https://api.nuabase.com";
-    if (!this.apiKey) {
+const isBrowserEnvironment = () => typeof window !== "undefined" && !!window.document;
+class NuabaseAuthTokenManager {
+  constructor(config) {
+    this.apiKey = resolveConfigValue(config, "apiKey", "NUABASE_API_KEY") || void 0;
+    this.fetchToken = config.fetchToken;
+    if (this.apiKey && this.fetchToken) {
+      throw new Error("Provide either an apiKey or a fetchToken function, but not both.");
+    }
+    if (!this.apiKey && !this.fetchToken) {
+      throw new Error(
+        "Authentication is required. Provide config.apiKey/NUABASE_API_KEY or a fetchToken function."
+      );
+    }
+    if (this.apiKey && isBrowserEnvironment()) {
       throw new Error(
-        "API key is required. Provide it via config.apiKey or NUABASE_API_KEY environment variable."
+        "found config.apiKey. It is a private secret that must only be used in server environments."
       );
     }
   }
-  async request(urlPath, params) {
+  async getToken() {
+    if (this.apiKey) {
+      return this.apiKey;
+    }
+    if (!this.fetchToken) {
+      throw new Error("Unable to resolve API token because no fetchToken function is configured.");
+    }
+    if (this.apiToken) {
+      return this.apiToken;
+    }
+    if (!this.pendingTokenPromise) {
+      this.pendingTokenPromise = this.fetchToken().then((token) => {
+        if (!token) {
+          throw new Error("fetchToken must resolve a non-empty API token.");
+        }
+        this.apiToken = token;
+        return token;
+      }).finally(() => {
+        this.pendingTokenPromise = void 0;
+      });
+    }
+    return this.pendingTokenPromise;
+  }
+}
+class NuabaseAPIClient {
+  constructor(config = {}) {
+    this.baseUrl = resolveConfigValue(config, "baseUrl", "NUABASE_API_URL") || "https://api.nuabase.com";
+    this.authTokenManager = new NuabaseAuthTokenManager(config);
+  }
+  async request(method, urlPath, params) {
     const url = `${this.baseUrl}/${urlPath}`;
     let response;
+    const hasBody = method !== "GET" && params !== void 0;
+    const headers = {
+      Authorization: `Bearer ${await this.authTokenManager.getToken()}`
+    };
+    if (hasBody) {
+      headers["Content-Type"] = "application/json";
+    }
     try {
       response = await fetch(url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.apiKey}`
-        },
-        body: JSON.stringify(params)
+        method,
+        headers,
+        body: hasBody ? JSON.stringify(params) : void 0
       });
     } catch (e) {
       return { error: `Error calling Nuabase API: ${getErrorMessageFromException(e)}` };
@@ -105,6 +157,12 @@ const validateArrayRequestParams = (data, primaryKeyName) => {
   });
 };
 
+const zs_NormalizedUsage = zod.z.object({
+  promptTokens: zod.z.number(),
+  completionTokens: zod.z.number(),
+  totalTokens: zod.z.number()
+}).strict();
+
 const zs_ResponseRecord = (primaryKeyName, outputKey, outputSchema) => {
   const primaryKeySchema = zod.z.any();
   const shape = {
@@ -127,7 +185,8 @@ const createNuaApiResponseCastArray = (primaryKeyName, outputKey, outputSchema)
     cacheHits: zod.z.number(),
     rowsWithNoResults: zod.z.array(zod.z.string()),
     isSuccess: zod.z.literal(true),
-    isError: zod.z.optional(zod.z.literal(false))
+    isError: zod.z.optional(zod.z.literal(false)),
+    usage: zs_NormalizedUsage
   }).strict();
 };
 const zs_NuaApiResponse_CastArray = createNuaApiResponseCastArray;
@@ -151,6 +210,25 @@ const validateArrayFnDef = (fnDef) => {
   return parsed.data;
 };
 
+function addOriginalInputRows(inputRows, outputRows, primaryKeyName) {
+  const lookup = /* @__PURE__ */ new Map();
+  for (const row of inputRows) {
+    lookup.set(row[primaryKeyName], row);
+  }
+  return outputRows.map((row) => {
+    const primaryKeyValue = row[primaryKeyName];
+    const sourceRow = lookup.get(primaryKeyValue);
+    if (!sourceRow) {
+      throw new Error(
+        `Unable to locate source row for primary key "${String(primaryKeyValue)}" in cast array response.`
+      );
+    }
+    return {
+      ...row,
+      sourceRow
+    };
+  });
+}
 const toCastArrayApiRequest = (prompt, data, primaryKeyName, outputName, outputSchema) => ({
   input: {
     prompt,
@@ -170,9 +248,10 @@ const createArrayFn = (client, inputFnDef) => {
       return { error: String(response.error), isError: true };
     return void 0;
   };
-  const baseFn = async (data, primaryKeyName) => {
+  const queueFn = async (data, primaryKeyName) => {
     validateArrayRequestParams(data, primaryKeyName);
     const response = await client.request(
+      "POST",
       "cast/array",
       toCastArrayApiRequest(
         fnDef.prompt,
@@ -191,9 +270,10 @@ const createArrayFn = (client, inputFnDef) => {
     }
     return parsedResponse.data;
   };
-  const nowFn = async (data, primaryKeyName) => {
+  const baseNowFn = async (data, primaryKeyName) => {
     validateArrayRequestParams(data, primaryKeyName);
     const response = await client.request(
+      "POST",
       "cast/array/now",
       toCastArrayApiRequest(
         fnDef.prompt,
@@ -216,13 +296,18 @@ const createArrayFn = (client, inputFnDef) => {
       isSuccess: true,
       llmRequestId: parsedResponse.data.llmRequestId,
       kind: parsedResponse.data.kind,
-      data: parsedResponse.data.data,
+      data: addOriginalInputRows(
+        data,
+        parsedResponse.data.data,
+        primaryKeyName
+      ),
       rowsWithNoResults: parsedResponse.data.rowsWithNoResults,
-      cacheHits: parsedResponse.data.cacheHits
+      cacheHits: parsedResponse.data.cacheHits,
+      usage: parsedResponse.data.usage
     };
   };
-  return Object.assign(baseFn, {
-    now: nowFn
+  return Object.assign(baseNowFn, {
+    queue: queueFn
   });
 };
 
@@ -233,7 +318,8 @@ const createNuaApiResponseCastValue = (outputKey, outputSchema) => {
     data: outputSchema,
     isCacheHit: zod.z.boolean(),
     isSuccess: zod.z.literal(true),
-    isError: zod.z.optional(zod.z.literal(false))
+    isError: zod.z.optional(zod.z.literal(false)),
+    usage: zs_NormalizedUsage
   }).strict();
 };
 const zs_NuaApiResponse_CastValue = createNuaApiResponseCastValue;
@@ -276,10 +362,11 @@ const createValueFn = (client, inputFnDef) => {
     return void 0;
   };
   const sendRequest = async (path, data) => client.request(
+    "POST",
     path,
     toCastValueApiRequest(fnDef.prompt, data, fnDef.output.name, outputJsonSchema)
   );
-  const baseFn = async (data) => {
+  const queueFn = async (data) => {
     const response = await sendRequest("cast/value", data);
     const error = toNuabaseError(response);
     if (error) return error;
@@ -290,7 +377,7 @@ const createValueFn = (client, inputFnDef) => {
     }
     return parsedResponse.data;
   };
-  const nowFn = async (data) => {
+  const baseNowFn = async (data) => {
     const response = await sendRequest("cast/value/now", data);
     const error = toNuabaseError(response);
     if (error) return error;
@@ -309,14 +396,93 @@ const createValueFn = (client, inputFnDef) => {
       llmRequestId: parsedResponse.data.llmRequestId,
       kind: parsedResponse.data.kind,
       data: parsedResponse.data.data,
-      isCacheHit: parsedResponse.data.isCacheHit
+      isCacheHit: parsedResponse.data.isCacheHit,
+      usage: parsedResponse.data.usage
     };
   };
-  return Object.assign(baseFn, {
-    now: nowFn
+  return Object.assign(baseNowFn, {
+    queue: queueFn
   });
 };
 
+const errorParseFailed = {
+  kind: "internal-error",
+  message: "Unable to parse stored LLM result"
+};
+const dateFromIso = zod.z.preprocess(
+  (value) => {
+    if (value == null) return null;
+    if (value instanceof Date) return value;
+    if (typeof value === "string") {
+      const parsed = new Date(value);
+      if (!Number.isNaN(parsed.getTime())) return parsed;
+    }
+    return zod.z.NEVER;
+  },
+  zod.z.union([zod.z.date(), zod.z.null()])
+);
+const mandatoryDateFromIso = zod.z.preprocess((value) => {
+  if (value instanceof Date) return value;
+  if (typeof value === "string") {
+    const parsed = new Date(value);
+    if (!Number.isNaN(parsed.getTime())) return parsed;
+  }
+  return zod.z.NEVER;
+}, zod.z.date());
+const apiResponseSchema = zod.z.object({
+  id: zod.z.string(),
+  requestType: zod.z.string(),
+  llmStatus: zod.z.union([
+    zod.z.literal("pending"),
+    zod.z.literal("processing"),
+    zod.z.literal("success"),
+    zod.z.literal("failed")
+  ]),
+  sseStatus: zod.z.union([
+    zod.z.literal("n/a"),
+    zod.z.literal("pending"),
+    zod.z.literal("sent"),
+    zod.z.literal("failed")
+  ]),
+  webhookStatus: zod.z.union([
+    zod.z.literal("n/a"),
+    zod.z.literal("pending"),
+    zod.z.literal("sent"),
+    zod.z.literal("failed")
+  ]),
+  input: zod.z.object({
+    prompt: zod.z.union([zod.z.string(), zod.z.null()]),
+    data: zod.z.union([zod.z.string(), zod.z.null()]),
+    primaryKey: zod.z.union([zod.z.string(), zod.z.null()])
+  }),
+  output: zod.z.object({
+    name: zod.z.string(),
+    schema: zod.z.string(),
+    effectiveSchema: zod.z.string()
+  }),
+  result: zod.z.union([zod.z.record(zod.z.string(), zod.z.unknown()), zod.z.null()]).optional(),
+  error: zod.z.union([zod.z.string(), zod.z.null()]),
+  fullPrompt: zod.z.string(),
+  model: zod.z.string(),
+  provider: zod.z.string(),
+  startedAt: dateFromIso,
+  finishedAt: dateFromIso,
+  createdAt: mandatoryDateFromIso,
+  updatedAt: mandatoryDateFromIso
+});
+const isNuabaseError = (value) => Boolean(value && typeof value === "object" && "isError" in value && value.isError);
+async function getRequest(client, llmRequestId) {
+  const response = await client.request("GET", `requests/${encodeURIComponent(llmRequestId)}`);
+  if (isNuabaseError(response)) {
+    return response;
+  }
+  const parsedResponse = apiResponseSchema.safeParse(response);
+  if (!parsedResponse.success) {
+    return errorParseFailed;
+  }
+  return parsedResponse.data;
+}
+
 class Nua {
   constructor(config) {
     this.apiClient = new NuabaseAPIClient(config);
@@ -327,6 +493,9 @@ class Nua {
   createFn(fnDef) {
     return createValueFn(this.apiClient, fnDef);
   }
+  async getRequest(llmRequestId) {
+    return getRequest(this.apiClient, llmRequestId);
+  }
 }
 
 exports.Nua = Nua;

package/dist/esm/index.mjs

@@ -1,5 +1,15 @@
 import { z } from 'zod';
 
+function resolveConfigValue(config, key, envVar) {
+  if (config[key]) return config[key];
+  const pe = globalThis.process;
+  const isNode = !!pe?.versions?.node;
+  if (isNode) {
+    return pe?.env?.[envVar];
+  }
+  return void 0;
+}
+
 async function parseErrorResponse(response, urlPath) {
   const fallbackMessage = `Request to ${urlPath} failed with status ${response.status}${response.statusText ? ` ${response.statusText}` : ""}`;
   let responseBody = "";
@@ -43,27 +53,69 @@ function getErrorMessageFromException(error) {
   return String(error);
 }
 
-class NuabaseAPIClient {
-  constructor(config = {}) {
-    this.apiKey = config.apiKey || process.env.NUABASE_API_KEY || "";
-    this.baseUrl = config.baseUrl || process.env.NUABASE_API_URL || "https://api.nuabase.com";
-    if (!this.apiKey) {
+const isBrowserEnvironment = () => typeof window !== "undefined" && !!window.document;
+class NuabaseAuthTokenManager {
+  constructor(config) {
+    this.apiKey = resolveConfigValue(config, "apiKey", "NUABASE_API_KEY") || void 0;
+    this.fetchToken = config.fetchToken;
+    if (this.apiKey && this.fetchToken) {
+      throw new Error("Provide either an apiKey or a fetchToken function, but not both.");
+    }
+    if (!this.apiKey && !this.fetchToken) {
+      throw new Error(
+        "Authentication is required. Provide config.apiKey/NUABASE_API_KEY or a fetchToken function."
+      );
+    }
+    if (this.apiKey && isBrowserEnvironment()) {
       throw new Error(
-        "API key is required. Provide it via config.apiKey or NUABASE_API_KEY environment variable."
+        "found config.apiKey. It is a private secret that must only be used in server environments."
       );
     }
   }
-  async request(urlPath, params) {
+  async getToken() {
+    if (this.apiKey) {
+      return this.apiKey;
+    }
+    if (!this.fetchToken) {
+      throw new Error("Unable to resolve API token because no fetchToken function is configured.");
+    }
+    if (this.apiToken) {
+      return this.apiToken;
+    }
+    if (!this.pendingTokenPromise) {
+      this.pendingTokenPromise = this.fetchToken().then((token) => {
+        if (!token) {
+          throw new Error("fetchToken must resolve a non-empty API token.");
+        }
+        this.apiToken = token;
+        return token;
+      }).finally(() => {
+        this.pendingTokenPromise = void 0;
+      });
+    }
+    return this.pendingTokenPromise;
+  }
+}
+class NuabaseAPIClient {
+  constructor(config = {}) {
+    this.baseUrl = resolveConfigValue(config, "baseUrl", "NUABASE_API_URL") || "https://api.nuabase.com";
+    this.authTokenManager = new NuabaseAuthTokenManager(config);
+  }
+  async request(method, urlPath, params) {
     const url = `${this.baseUrl}/${urlPath}`;
     let response;
+    const hasBody = method !== "GET" && params !== void 0;
+    const headers = {
+      Authorization: `Bearer ${await this.authTokenManager.getToken()}`
+    };
+    if (hasBody) {
+      headers["Content-Type"] = "application/json";
+    }
     try {
       response = await fetch(url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.apiKey}`
-        },
-        body: JSON.stringify(params)
+        method,
+        headers,
+        body: hasBody ? JSON.stringify(params) : void 0
       });
     } catch (e) {
       return { error: `Error calling Nuabase API: ${getErrorMessageFromException(e)}` };
@@ -103,6 +155,12 @@ const validateArrayRequestParams = (data, primaryKeyName) => {
   });
 };
 
+const zs_NormalizedUsage = z.object({
+  promptTokens: z.number(),
+  completionTokens: z.number(),
+  totalTokens: z.number()
+}).strict();
+
 const zs_ResponseRecord = (primaryKeyName, outputKey, outputSchema) => {
   const primaryKeySchema = z.any();
   const shape = {
@@ -125,7 +183,8 @@ const createNuaApiResponseCastArray = (primaryKeyName, outputKey, outputSchema)
     cacheHits: z.number(),
     rowsWithNoResults: z.array(z.string()),
     isSuccess: z.literal(true),
-    isError: z.optional(z.literal(false))
+    isError: z.optional(z.literal(false)),
+    usage: zs_NormalizedUsage
   }).strict();
 };
 const zs_NuaApiResponse_CastArray = createNuaApiResponseCastArray;
@@ -149,6 +208,25 @@ const validateArrayFnDef = (fnDef) => {
   return parsed.data;
 };
 
+function addOriginalInputRows(inputRows, outputRows, primaryKeyName) {
+  const lookup = /* @__PURE__ */ new Map();
+  for (const row of inputRows) {
+    lookup.set(row[primaryKeyName], row);
+  }
+  return outputRows.map((row) => {
+    const primaryKeyValue = row[primaryKeyName];
+    const sourceRow = lookup.get(primaryKeyValue);
+    if (!sourceRow) {
+      throw new Error(
+        `Unable to locate source row for primary key "${String(primaryKeyValue)}" in cast array response.`
+      );
+    }
+    return {
+      ...row,
+      sourceRow
+    };
+  });
+}
 const toCastArrayApiRequest = (prompt, data, primaryKeyName, outputName, outputSchema) => ({
   input: {
     prompt,
@@ -168,9 +246,10 @@ const createArrayFn = (client, inputFnDef) => {
       return { error: String(response.error), isError: true };
     return void 0;
   };
-  const baseFn = async (data, primaryKeyName) => {
+  const queueFn = async (data, primaryKeyName) => {
     validateArrayRequestParams(data, primaryKeyName);
     const response = await client.request(
+      "POST",
       "cast/array",
       toCastArrayApiRequest(
         fnDef.prompt,
@@ -189,9 +268,10 @@ const createArrayFn = (client, inputFnDef) => {
     }
     return parsedResponse.data;
   };
-  const nowFn = async (data, primaryKeyName) => {
+  const baseNowFn = async (data, primaryKeyName) => {
     validateArrayRequestParams(data, primaryKeyName);
     const response = await client.request(
+      "POST",
       "cast/array/now",
       toCastArrayApiRequest(
         fnDef.prompt,
@@ -214,13 +294,18 @@ const createArrayFn = (client, inputFnDef) => {
       isSuccess: true,
       llmRequestId: parsedResponse.data.llmRequestId,
       kind: parsedResponse.data.kind,
-      data: parsedResponse.data.data,
+      data: addOriginalInputRows(
+        data,
+        parsedResponse.data.data,
+        primaryKeyName
+      ),
       rowsWithNoResults: parsedResponse.data.rowsWithNoResults,
-      cacheHits: parsedResponse.data.cacheHits
+      cacheHits: parsedResponse.data.cacheHits,
+      usage: parsedResponse.data.usage
     };
   };
-  return Object.assign(baseFn, {
-    now: nowFn
+  return Object.assign(baseNowFn, {
+    queue: queueFn
   });
 };
 
@@ -231,7 +316,8 @@ const createNuaApiResponseCastValue = (outputKey, outputSchema) => {
     data: outputSchema,
     isCacheHit: z.boolean(),
     isSuccess: z.literal(true),
-    isError: z.optional(z.literal(false))
+    isError: z.optional(z.literal(false)),
+    usage: zs_NormalizedUsage
   }).strict();
 };
 const zs_NuaApiResponse_CastValue = createNuaApiResponseCastValue;
@@ -274,10 +360,11 @@ const createValueFn = (client, inputFnDef) => {
     return void 0;
   };
   const sendRequest = async (path, data) => client.request(
+    "POST",
     path,
     toCastValueApiRequest(fnDef.prompt, data, fnDef.output.name, outputJsonSchema)
   );
-  const baseFn = async (data) => {
+  const queueFn = async (data) => {
     const response = await sendRequest("cast/value", data);
     const error = toNuabaseError(response);
     if (error) return error;
@@ -288,7 +375,7 @@ const createValueFn = (client, inputFnDef) => {
     }
     return parsedResponse.data;
   };
-  const nowFn = async (data) => {
+  const baseNowFn = async (data) => {
     const response = await sendRequest("cast/value/now", data);
     const error = toNuabaseError(response);
     if (error) return error;
@@ -307,14 +394,93 @@ const createValueFn = (client, inputFnDef) => {
       llmRequestId: parsedResponse.data.llmRequestId,
       kind: parsedResponse.data.kind,
       data: parsedResponse.data.data,
-      isCacheHit: parsedResponse.data.isCacheHit
+      isCacheHit: parsedResponse.data.isCacheHit,
+      usage: parsedResponse.data.usage
     };
   };
-  return Object.assign(baseFn, {
-    now: nowFn
+  return Object.assign(baseNowFn, {
+    queue: queueFn
   });
 };
 
+const errorParseFailed = {
+  kind: "internal-error",
+  message: "Unable to parse stored LLM result"
+};
+const dateFromIso = z.preprocess(
+  (value) => {
+    if (value == null) return null;
+    if (value instanceof Date) return value;
+    if (typeof value === "string") {
+      const parsed = new Date(value);
+      if (!Number.isNaN(parsed.getTime())) return parsed;
+    }
+    return z.NEVER;
+  },
+  z.union([z.date(), z.null()])
+);
+const mandatoryDateFromIso = z.preprocess((value) => {
+  if (value instanceof Date) return value;
+  if (typeof value === "string") {
+    const parsed = new Date(value);
+    if (!Number.isNaN(parsed.getTime())) return parsed;
+  }
+  return z.NEVER;
+}, z.date());
+const apiResponseSchema = z.object({
+  id: z.string(),
+  requestType: z.string(),
+  llmStatus: z.union([
+    z.literal("pending"),
+    z.literal("processing"),
+    z.literal("success"),
+    z.literal("failed")
+  ]),
+  sseStatus: z.union([
+    z.literal("n/a"),
+    z.literal("pending"),
+    z.literal("sent"),
+    z.literal("failed")
+  ]),
+  webhookStatus: z.union([
+    z.literal("n/a"),
+    z.literal("pending"),
+    z.literal("sent"),
+    z.literal("failed")
+  ]),
+  input: z.object({
+    prompt: z.union([z.string(), z.null()]),
+    data: z.union([z.string(), z.null()]),
+    primaryKey: z.union([z.string(), z.null()])
+  }),
+  output: z.object({
+    name: z.string(),
+    schema: z.string(),
+    effectiveSchema: z.string()
+  }),
+  result: z.union([z.record(z.string(), z.unknown()), z.null()]).optional(),
+  error: z.union([z.string(), z.null()]),
+  fullPrompt: z.string(),
+  model: z.string(),
+  provider: z.string(),
+  startedAt: dateFromIso,
+  finishedAt: dateFromIso,
+  createdAt: mandatoryDateFromIso,
+  updatedAt: mandatoryDateFromIso
+});
+const isNuabaseError = (value) => Boolean(value && typeof value === "object" && "isError" in value && value.isError);
+async function getRequest(client, llmRequestId) {
+  const response = await client.request("GET", `requests/${encodeURIComponent(llmRequestId)}`);
+  if (isNuabaseError(response)) {
+    return response;
+  }
+  const parsedResponse = apiResponseSchema.safeParse(response);
+  if (!parsedResponse.success) {
+    return errorParseFailed;
+  }
+  return parsedResponse.data;
+}
+
 class Nua {
   constructor(config) {
     this.apiClient = new NuabaseAPIClient(config);
@@ -325,6 +491,9 @@ class Nua {
   createFn(fnDef) {
     return createValueFn(this.apiClient, fnDef);
   }
+  async getRequest(llmRequestId) {
+    return getRequest(this.apiClient, llmRequestId);
+  }
 }
 
 export { Nua };

package/dist/types/lib/api-client.d.ts

@@ -1,11 +1,19 @@
 import { NuabaseError } from './error-response';
-export type NuabaseConfig = {
+type NuabaseApiKeyConfig = {
     apiKey?: string;
+    fetchToken?: never;
     baseUrl?: string;
 };
+type NuabaseTokenConfig = {
+    fetchToken: () => Promise<string>;
+    apiKey?: never;
+    baseUrl?: string;
+};
+export type NuabaseConfig = NuabaseApiKeyConfig | NuabaseTokenConfig;
 export declare class NuabaseAPIClient {
-    private readonly apiKey;
     private readonly baseUrl;
+    private readonly authTokenManager;
     constructor(config?: NuabaseConfig);
-    request(urlPath: string, params: object): Promise<NuabaseError | unknown>;
+    request(method: 'GET' | 'POST', urlPath: string, params?: object): Promise<NuabaseError | unknown>;
 }
+export {};

package/dist/types/lib/env.d.ts

@@ -0,0 +1 @@
+export declare function resolveConfigValue<T extends Record<string, any>>(config: T, key: keyof T, envVar: string): string | undefined;

package/dist/types/nua/cast_array/response-schema.d.ts

@@ -1,3 +1,4 @@
+import { NormalizedUsage } from '../common/normalized-usage';
 import { z } from 'zod';
 export type UserDataPKValue = string | number;
 export type PrimaryKeyedInputRecord<PrimaryKeyName extends string> = Record<PrimaryKeyName, UserDataPKValue> & Record<string, unknown>;
@@ -7,9 +8,10 @@ type NuaApiResponseShape<OutputZodSchema extends z.ZodTypeAny, OutputName extend
     kind: 'cast/array';
     data: Array<ResponseRow<OutputZodSchema, OutputName, PrimaryKeyName, InputRecord>>;
     cacheHits: number;
-    rowsWithNoResults: string[];
+    rowsWithNoResults: UserDataPKValue[];
     isSuccess: true;
     isError?: false;
+    usage: NormalizedUsage;
 };
 type NuaApiResponseCastArrayBuilder = <OutputZodSchema extends z.ZodTypeAny, OutputName extends string, PrimaryKeyName extends string, InputRecord extends PrimaryKeyedInputRecord<PrimaryKeyName>>(primaryKeyName: PrimaryKeyName, outputKey: OutputName, outputSchema: OutputZodSchema) => z.ZodType<NuaApiResponseShape<OutputZodSchema, OutputName, PrimaryKeyName, InputRecord>>;
 export declare const zs_NuaApiResponse_CastArray: NuaApiResponseCastArrayBuilder;

package/dist/types/nua/cast_array/types.d.ts

@@ -10,9 +10,24 @@ export type ArrayFnDef<OutputName extends string, OutputZodSchema extends z.ZodT
     };
 };
 export declare const validateArrayFnDef: <OutputName extends string, OutputZodSchema extends z.ZodTypeAny>(fnDef: ArrayFnDef<OutputName, OutputZodSchema>) => ArrayFnDef<OutputName, OutputZodSchema>;
-export type ArrayFnResult<OutputZodSchema extends z.ZodTypeAny, OutputName extends string, PrimaryKeyName extends string, InputRecord extends PrimaryKeyedInputRecord<PrimaryKeyName>> = NuabaseError | NuaApiResponse_CastArray<OutputZodSchema, OutputName, PrimaryKeyName, InputRecord>;
+type CastArraySuccessFromApi<OutputZodSchema extends z.ZodTypeAny, OutputName extends string, PrimaryKeyName extends string, InputRecord extends PrimaryKeyedInputRecord<PrimaryKeyName>> = NuaApiResponse_CastArray<OutputZodSchema, OutputName, PrimaryKeyName, InputRecord>;
+type CastArraySourceRowAugmentation<PrimaryKeyName extends string, InputRecord extends PrimaryKeyedInputRecord<PrimaryKeyName>> = {
+    /**
+     * SDK-added field containing the full input row for convenience; not returned by the API.
+     */
+    sourceRow: InputRecord;
+};
+type CastArraySuccessRowWithSource<OutputZodSchema extends z.ZodTypeAny, OutputName extends string, PrimaryKeyName extends string, InputRecord extends PrimaryKeyedInputRecord<PrimaryKeyName>> = CastArraySuccessFromApi<OutputZodSchema, OutputName, PrimaryKeyName, InputRecord>['data'][number] & CastArraySourceRowAugmentation<PrimaryKeyName, InputRecord>;
+export type CastArraySuccessWithSource<OutputZodSchema extends z.ZodTypeAny, OutputName extends string, PrimaryKeyName extends string, InputRecord extends PrimaryKeyedInputRecord<PrimaryKeyName>> = Omit<CastArraySuccessFromApi<OutputZodSchema, OutputName, PrimaryKeyName, InputRecord>, 'data'> & {
+    /**
+     * Each row mirrors the API payload and includes the SDK-provided `sourceRow`.
+     */
+    data: CastArraySuccessRowWithSource<OutputZodSchema, OutputName, PrimaryKeyName, InputRecord>[];
+};
+export type ArrayFnResult<OutputZodSchema extends z.ZodTypeAny, OutputName extends string, PrimaryKeyName extends string, InputRecord extends PrimaryKeyedInputRecord<PrimaryKeyName>> = NuabaseError | CastArraySuccessWithSource<OutputZodSchema, OutputName, PrimaryKeyName, InputRecord>;
 export type ArrayFnQueuedResult = NuabaseError | NuaQueuedResponse;
 export type ArrayFn<OutputZodSchema extends z.ZodTypeAny, OutputName extends string> = {
-    <PrimaryKeyName extends string, InputRecord extends PrimaryKeyedInputRecord<PrimaryKeyName>>(data: InputRecord[], primaryKeyName: PrimaryKeyName): Promise<ArrayFnQueuedResult>;
-    now: <PrimaryKeyName extends string, InputRecord extends PrimaryKeyedInputRecord<PrimaryKeyName>>(data: InputRecord[], primaryKeyName: PrimaryKeyName) => Promise<ArrayFnResult<OutputZodSchema, OutputName, PrimaryKeyName, InputRecord>>;
+    <PrimaryKeyName extends string, InputRecord extends PrimaryKeyedInputRecord<PrimaryKeyName>>(data: InputRecord[], primaryKeyName: PrimaryKeyName): Promise<ArrayFnResult<OutputZodSchema, OutputName, PrimaryKeyName, InputRecord>>;
+    queue: <PrimaryKeyName extends string, InputRecord extends PrimaryKeyedInputRecord<PrimaryKeyName>>(data: InputRecord[], primaryKeyName: PrimaryKeyName) => Promise<ArrayFnQueuedResult>;
 };
+export {};

package/dist/types/nua/cast_value/response-schema.d.ts

@@ -1,3 +1,4 @@
+import { NormalizedUsage } from '../common/normalized-usage';
 import { z } from 'zod';
 type NuaApiResponseShape<OutputZodSchema extends z.ZodTypeAny> = {
     llmRequestId: string;
@@ -6,6 +7,7 @@ type NuaApiResponseShape<OutputZodSchema extends z.ZodTypeAny> = {
     isCacheHit: boolean;
     isSuccess: true;
     isError?: false;
+    usage: NormalizedUsage;
 };
 type NuaApiResponseCastValueBuilder = <OutputZodSchema extends z.ZodTypeAny, OutputName extends string>(outputKey: OutputName, outputSchema: OutputZodSchema) => z.ZodType<NuaApiResponseShape<OutputZodSchema>>;
 export declare const zs_NuaApiResponse_CastValue: NuaApiResponseCastValueBuilder;

package/dist/types/nua/cast_value/types.d.ts

@@ -13,6 +13,6 @@ export declare const validateValueFnDef: <OutputName extends string, OutputZodSc
 export type ValueFnResult<OutputZodSchema extends z.ZodTypeAny, OutputName extends string> = NuabaseError | NuaApiResponse_CastValue<OutputZodSchema, OutputName>;
 export type ValueFnQueuedResult = NuabaseError | NuaQueuedResponse;
 export type ValueFn<OutputZodSchema extends z.ZodTypeAny, OutputName extends string> = {
-    (data: unknown): Promise<ValueFnQueuedResult>;
-    now: (data: unknown) => Promise<ValueFnResult<OutputZodSchema, OutputName>>;
+    (data: unknown): Promise<ValueFnResult<OutputZodSchema, OutputName>>;
+    queue: (data: unknown) => Promise<ValueFnQueuedResult>;
 };

package/dist/types/nua/common/normalized-usage.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export type NormalizedUsage = {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+};
+export declare const zs_NormalizedUsage: z.ZodType<NormalizedUsage>;

package/dist/types/nua/core.d.ts

@@ -1,10 +1,12 @@
 import { NuabaseAPIClient, NuabaseConfig } from '../lib/api-client';
 import { ArrayFn, ArrayFnDef } from './cast_array/types';
 import { ValueFn, ValueFnDef } from './cast_value/types';
+import { GetRequestResult } from './get-request';
 import { z } from 'zod';
 export declare class Nua {
     apiClient: NuabaseAPIClient;
     constructor(config?: NuabaseConfig);
     createArrayFn<OutputName extends string, OutputZodSchema extends z.ZodTypeAny>(fnDef: ArrayFnDef<OutputName, OutputZodSchema>): ArrayFn<OutputZodSchema, OutputName>;
     createFn<OutputName extends string, OutputZodSchema extends z.ZodTypeAny>(fnDef: ValueFnDef<OutputName, OutputZodSchema>): ValueFn<OutputZodSchema, OutputName>;
+    getRequest(llmRequestId: string): Promise<GetRequestResult>;
 }

package/dist/types/nua/get-request/index.d.ts

@@ -0,0 +1,6 @@
+import { NuabaseAPIClient } from '../../lib/api-client';
+import { NuabaseError } from '../../lib/error-response';
+import { ApiResponseLlmRequest, NuaInternalError } from './types';
+export type GetRequestResult = ApiResponseLlmRequest | NuaInternalError | NuabaseError;
+export declare function getRequest(client: NuabaseAPIClient, llmRequestId: string): Promise<GetRequestResult>;
+export type { ApiResponseLlmRequest, LlmRequestStatus, NuaInternalError, SseRequestStatus, WebhookRequestStatus, } from './types';

package/dist/types/nua/get-request/types.d.ts

@@ -0,0 +1,34 @@
+export type LlmRequestType = string;
+export type LlmRequestStatus = 'pending' | 'processing' | 'success' | 'failed';
+export type SseRequestStatus = 'n/a' | 'pending' | 'sent' | 'failed';
+export type WebhookRequestStatus = 'n/a' | 'pending' | 'sent' | 'failed';
+export type NuaInternalError = {
+    kind: 'internal-error';
+    message: string;
+};
+export type ApiResponseLlmRequest = {
+    id: string;
+    requestType: LlmRequestType;
+    llmStatus: LlmRequestStatus;
+    sseStatus: SseRequestStatus;
+    webhookStatus: WebhookRequestStatus;
+    input: {
+        prompt: string | null;
+        data: string | null;
+        primaryKey: string | null;
+    };
+    output: {
+        name: string;
+        schema: string;
+        effectiveSchema: string;
+    };
+    result?: Record<string, unknown> | null;
+    error: string | null;
+    fullPrompt: string;
+    model: string;
+    provider: string;
+    startedAt: Date | null;
+    finishedAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+};

package/dist/types/nua/index.d.ts

@@ -2,3 +2,4 @@ export { Nua } from './core';
 export { createArrayFn } from './cast_array/factory';
 export { validateArrayRequestParams } from './cast_array/request-validation';
 export type { ArrayFn, ArrayFnDef } from './cast_array/types';
+export type { ApiResponseLlmRequest, GetRequestResult, LlmRequestStatus, NuaInternalError, SseRequestStatus, WebhookRequestStatus, } from './get-request';

package/package.json

@@ -2,7 +2,7 @@
   "name": "nuabase",
   "description": "Nuabase TypeScript client to create typed functions from LLM prompts",
   "packageManager": "yarn@4.10.3+sha512.c38cafb5c7bb273f3926d04e55e1d8c9dfa7d9c3ea1f36a4868fa028b9e5f72298f0b7f401ad5eb921749eb012eb1c3bb74bf7503df3ee43fd600d14a018266f",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "type": "module",
   "author": "Jasim A Basheer <jasim@nuabase.com>",
   "engines": {