nuabase 1.0.1 → 1.1.0

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 = "";
@@ -47,25 +57,29 @@ function getErrorMessageFromException(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";
+    this.apiKey = resolveConfigValue(config, "apiKey", "NUABASE_API_KEY") || "";
+    this.baseUrl = resolveConfigValue(config, "baseUrl", "NUABASE_API_URL") || "https://api.nuabase.com";
     if (!this.apiKey) {
       throw new Error(
         "API key is required. Provide it via config.apiKey or NUABASE_API_KEY environment variable."
       );
     }
   }
-  async request(urlPath, params) {
+  async request(method, urlPath, params) {
     const url = `${this.baseUrl}/${urlPath}`;
     let response;
+    const hasBody = method !== "GET" && params !== void 0;
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`
+    };
+    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)}` };
@@ -151,6 +165,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,
@@ -173,6 +206,7 @@ const createArrayFn = (client, inputFnDef) => {
   const baseFn = async (data, primaryKeyName) => {
     validateArrayRequestParams(data, primaryKeyName);
     const response = await client.request(
+      "POST",
       "cast/array",
       toCastArrayApiRequest(
         fnDef.prompt,
@@ -194,6 +228,7 @@ const createArrayFn = (client, inputFnDef) => {
   const nowFn = async (data, primaryKeyName) => {
     validateArrayRequestParams(data, primaryKeyName);
     const response = await client.request(
+      "POST",
       "cast/array/now",
       toCastArrayApiRequest(
         fnDef.prompt,
@@ -216,7 +251,11 @@ 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
     };
@@ -276,6 +315,7 @@ const createValueFn = (client, inputFnDef) => {
     return void 0;
   };
   const sendRequest = async (path, data) => client.request(
+    "POST",
     path,
     toCastValueApiRequest(fnDef.prompt, data, fnDef.output.name, outputJsonSchema)
   );
@@ -317,6 +357,84 @@ const createValueFn = (client, inputFnDef) => {
   });
 };
 
+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 +445,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 = "";
@@ -45,25 +55,29 @@ function getErrorMessageFromException(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";
+    this.apiKey = resolveConfigValue(config, "apiKey", "NUABASE_API_KEY") || "";
+    this.baseUrl = resolveConfigValue(config, "baseUrl", "NUABASE_API_URL") || "https://api.nuabase.com";
     if (!this.apiKey) {
       throw new Error(
         "API key is required. Provide it via config.apiKey or NUABASE_API_KEY environment variable."
       );
     }
   }
-  async request(urlPath, params) {
+  async request(method, urlPath, params) {
     const url = `${this.baseUrl}/${urlPath}`;
     let response;
+    const hasBody = method !== "GET" && params !== void 0;
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`
+    };
+    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)}` };
@@ -149,6 +163,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,
@@ -171,6 +204,7 @@ const createArrayFn = (client, inputFnDef) => {
   const baseFn = async (data, primaryKeyName) => {
     validateArrayRequestParams(data, primaryKeyName);
     const response = await client.request(
+      "POST",
       "cast/array",
       toCastArrayApiRequest(
         fnDef.prompt,
@@ -192,6 +226,7 @@ const createArrayFn = (client, inputFnDef) => {
   const nowFn = async (data, primaryKeyName) => {
     validateArrayRequestParams(data, primaryKeyName);
     const response = await client.request(
+      "POST",
       "cast/array/now",
       toCastArrayApiRequest(
         fnDef.prompt,
@@ -214,7 +249,11 @@ 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
     };
@@ -274,6 +313,7 @@ const createValueFn = (client, inputFnDef) => {
     return void 0;
   };
   const sendRequest = async (path, data) => client.request(
+    "POST",
     path,
     toCastValueApiRequest(fnDef.prompt, data, fnDef.output.name, outputJsonSchema)
   );
@@ -315,6 +355,84 @@ const createValueFn = (client, inputFnDef) => {
   });
 };
 
+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 +443,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

@@ -7,5 +7,5 @@ export declare class NuabaseAPIClient {
     private readonly apiKey;
     private readonly baseUrl;
     constructor(config?: NuabaseConfig);
-    request(urlPath: string, params: object): Promise<NuabaseError | unknown>;
+    request(method: 'GET' | 'POST', urlPath: string, params?: object): Promise<NuabaseError | unknown>;
 }

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

@@ -7,7 +7,7 @@ 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;
 };

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>>;
 };
+export {};

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.1.0",
   "type": "module",
   "author": "Jasim A Basheer <jasim@nuabase.com>",
   "engines": {