nuabase 1.1.0 → 2.0.0

package/dist/esm/index.mjs

@@ -1,4 +1,78 @@
+import { NuaLlmClient, wrapArraySchema } from 'nua-llm-core';
 import { z } from 'zod';
+export { z } from 'zod';
+
+const normalizedUsageZero = {
+  promptTokens: 0,
+  completionTokens: 0,
+  totalTokens: 0
+};
+class DirectBackend {
+  constructor(config) {
+    if (!config.model) {
+      throw new Error("model is required for direct mode");
+    }
+    this.model = config.model;
+    this.client = new NuaLlmClient({ providers: config.providers });
+  }
+  async castValue(params) {
+    const startTime = Date.now();
+    const result = await this.client.castValue({
+      model: this.model,
+      input: { prompt: params.prompt, data: params.data },
+      output: { name: params.outputName, effectiveSchema: params.outputSchema }
+    });
+    const latencyMs = Date.now() - startTime;
+    if (!result.success) {
+      return {
+        success: false,
+        error: result.error || "Unknown error",
+        source: "direct",
+        latencyMs
+      };
+    }
+    return {
+      success: true,
+      data: result.data,
+      usage: result.usage || normalizedUsageZero,
+      model: this.model,
+      latencyMs,
+      source: "direct",
+      meta: {}
+    };
+  }
+  async castArray(params) {
+    const startTime = Date.now();
+    const wrappedSchema = wrapArraySchema(params.outputSchema, {
+      primaryKey: params.primaryKey,
+      outputName: params.outputName
+    });
+    const result = await this.client.castArray({
+      model: this.model,
+      data: params.data,
+      input: { prompt: params.prompt, primaryKey: params.primaryKey },
+      output: { name: params.outputName, effectiveSchema: wrappedSchema }
+    });
+    const latencyMs = Date.now() - startTime;
+    if (!result.success) {
+      return {
+        success: false,
+        error: result.error || "Unknown error",
+        source: "direct",
+        latencyMs
+      };
+    }
+    return {
+      success: true,
+      data: result.data,
+      usage: result.usage || normalizedUsageZero,
+      model: this.model,
+      latencyMs,
+      source: "direct",
+      meta: {}
+    };
+  }
+}
 
 function resolveConfigValue(config, key, envVar) {
   if (config[key]) return config[key];
@@ -10,6 +84,50 @@ function resolveConfigValue(config, key, envVar) {
   return void 0;
 }
 
+const isBrowserEnvironment = () => typeof window !== "undefined" && !!window.document;
+class AuthTokenManager {
+  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(
+        "found config.apiKey. It is a private secret that must only be used in server environments."
+      );
+    }
+  }
+  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;
+  }
+}
+
 async function parseErrorResponse(response, urlPath) {
   const fallbackMessage = `Request to ${urlPath} failed with status ${response.status}${response.statusText ? ` ${response.statusText}` : ""}`;
   let responseBody = "";
@@ -38,9 +156,17 @@ function safeParseJson(payload) {
   }
 }
 function extractErrorMessage(body) {
-  const e = body["error"];
-  if (e && typeof e === "string") return e;
-  return void 0;
+  const parts = [];
+  const error = body["error"];
+  if (typeof error === "string" && error.trim()) {
+    parts.push(error.trim());
+  }
+  const message = body["message"];
+  if (typeof message === "string" && message.trim()) {
+    parts.push(message.trim());
+  }
+  if (parts.length === 0) return void 0;
+  return parts.join(". ");
 }
 
 function isErrorWithMessage(error) {
@@ -53,398 +179,210 @@ function getErrorMessageFromException(error) {
   return String(error);
 }
 
-class NuabaseAPIClient {
-  constructor(config = {}) {
-    this.apiKey = resolveConfigValue(config, "apiKey", "NUABASE_API_KEY") || "";
+function isErrorResponse(response) {
+  return Boolean(response && typeof response === "object" && "error" in response);
+}
+class GatewayBackend {
+  constructor(config) {
     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."
-      );
+    this.authManager = new AuthTokenManager(config);
+  }
+  async castValue(params) {
+    const startTime = Date.now();
+    const response = await this.post("cast/value/now", {
+      input: { prompt: params.prompt, data: params.data },
+      output: { name: params.outputName, schema: params.outputSchema }
+    });
+    const latencyMs = Date.now() - startTime;
+    if (isErrorResponse(response)) {
+      return { success: false, error: response.error, source: "gateway", latencyMs };
+    }
+    const apiResponse = response;
+    const usage = {
+      promptTokens: apiResponse.llmUsage.promptTokens + apiResponse.cacheUsage.promptTokens,
+      completionTokens: apiResponse.llmUsage.completionTokens + apiResponse.cacheUsage.completionTokens,
+      totalTokens: apiResponse.llmUsage.totalTokens + apiResponse.cacheUsage.totalTokens
+    };
+    return {
+      success: true,
+      data: apiResponse.data,
+      usage,
+      model: apiResponse.model ?? "unknown",
+      latencyMs,
+      source: "gateway",
+      meta: {
+        requestId: apiResponse.llmRequestId,
+        cached: apiResponse.isCacheHit,
+        llmUsage: apiResponse.llmUsage,
+        cacheUsage: apiResponse.cacheUsage
+      }
+    };
+  }
+  async castArray(params) {
+    const startTime = Date.now();
+    const response = await this.post("cast/array/now", {
+      input: { prompt: params.prompt, data: params.data, primaryKey: params.primaryKey },
+      output: { name: params.outputName, schema: params.outputSchema }
+    });
+    const latencyMs = Date.now() - startTime;
+    if (isErrorResponse(response)) {
+      return { success: false, error: response.error, source: "gateway", latencyMs };
+    }
+    const apiResponse = response;
+    const usage = {
+      promptTokens: apiResponse.llmUsage.promptTokens + apiResponse.cacheUsage.promptTokens,
+      completionTokens: apiResponse.llmUsage.completionTokens + apiResponse.cacheUsage.completionTokens,
+      totalTokens: apiResponse.llmUsage.totalTokens + apiResponse.cacheUsage.totalTokens
+    };
+    return {
+      success: true,
+      data: apiResponse.data,
+      usage,
+      model: apiResponse.model ?? "unknown",
+      latencyMs,
+      source: "gateway",
+      meta: {
+        requestId: apiResponse.llmRequestId,
+        cached: apiResponse.cacheHits === apiResponse.data.length,
+        llmUsage: apiResponse.llmUsage,
+        cacheUsage: apiResponse.cacheUsage
+      }
+    };
+  }
+  async queueCastValue(params) {
+    const response = await this.post("cast/value", {
+      input: { prompt: params.prompt, data: params.data },
+      output: { name: params.outputName, schema: params.outputSchema }
+    });
+    if (isErrorResponse(response)) {
+      return { success: false, error: response.error, source: "gateway" };
     }
+    const apiResponse = response;
+    return { success: true, jobId: apiResponse.jobId, source: "gateway" };
   }
-  async request(method, urlPath, params) {
-    const url = `${this.baseUrl}/${urlPath}`;
+  async queueCastArray(params) {
+    const response = await this.post("cast/array", {
+      input: { prompt: params.prompt, data: params.data, primaryKey: params.primaryKey },
+      output: { name: params.outputName, schema: params.outputSchema }
+    });
+    if (isErrorResponse(response)) {
+      return { success: false, error: response.error, source: "gateway" };
+    }
+    const apiResponse = response;
+    return { success: true, jobId: apiResponse.jobId, source: "gateway" };
+  }
+  async post(path, body) {
+    const url = `${this.baseUrl}/${path}`;
     let response;
-    const hasBody = method !== "GET" && params !== void 0;
     const headers = {
-      Authorization: `Bearer ${this.apiKey}`
+      Authorization: `Bearer ${await this.authManager.getToken()}`,
+      "Content-Type": "application/json"
     };
-    if (hasBody) {
-      headers["Content-Type"] = "application/json";
-    }
     try {
       response = await fetch(url, {
-        method,
+        method: "POST",
         headers,
-        body: hasBody ? JSON.stringify(params) : void 0
+        body: JSON.stringify(body)
       });
     } catch (e) {
       return { error: `Error calling Nuabase API: ${getErrorMessageFromException(e)}` };
     }
-    let result;
     if (!response.ok) {
-      return await parseErrorResponse(response, urlPath);
+      return await parseErrorResponse(response, path);
     }
     try {
-      result = await response.json();
+      return await response.json();
     } catch {
       return { error: "Invalid response received from Nuabase API call, unable to parse" };
     }
-    return result;
   }
 }
 
-const zs_NuaQueuedResponse = z.object({
-  id: z.string(),
-  sseUrl: z.string().min(1)
-}).strict();
-
-const validateArrayRequestParams = (data, primaryKeyName) => {
-  if (!Array.isArray(data)) {
-    throw new Error("`data` must be an array of objects.");
+class Nua {
+  constructor(backend) {
+    this.backend = backend;
   }
-  if (!primaryKeyName || typeof primaryKeyName !== "string") {
-    throw new Error("`primaryKeyName` must be a non-empty string.");
+  static gateway(config) {
+    return new Nua(new GatewayBackend(config));
   }
-  data.forEach((item, index) => {
-    if (item === null || typeof item !== "object" || Array.isArray(item)) {
-      throw new Error(`data[${index}] must be a non-null object.`);
-    }
-    if (!(primaryKeyName in item)) {
-      throw new Error(`data[${index}] must contain property '${primaryKeyName}'.`);
-    }
-  });
-};
-
-const zs_ResponseRecord = (primaryKeyName, outputKey, outputSchema) => {
-  const primaryKeySchema = z.any();
-  const shape = {
-    [primaryKeyName]: primaryKeySchema,
-    [outputKey]: outputSchema
-  };
-  return z.object(shape).strict();
-};
-const createNuaApiResponseCastArray = (primaryKeyName, outputKey, outputSchema) => {
-  const recordSchema = zs_ResponseRecord(
-    primaryKeyName,
-    outputKey,
-    outputSchema
-  );
-  const dataSchema = z.array(recordSchema);
-  return z.object({
-    llmRequestId: z.string(),
-    kind: z.literal("cast/array"),
-    data: dataSchema,
-    cacheHits: z.number(),
-    rowsWithNoResults: z.array(z.string()),
-    isSuccess: z.literal(true),
-    isError: z.optional(z.literal(false))
-  }).strict();
-};
-const zs_NuaApiResponse_CastArray = createNuaApiResponseCastArray;
-
-const zs_ArrayFnDef = z.object({
-  prompt: z.string(),
-  output: z.object({
-    name: z.string(),
-    schema: z.custom(
-      (value) => value instanceof z.ZodType,
-      "Expected a Zod schema"
-    )
-  })
-});
-const validateArrayFnDef = (fnDef) => {
-  const parsed = zs_ArrayFnDef.safeParse(fnDef);
-  if (!parsed.success) {
-    const message = z.prettifyError(parsed.error);
-    throw new TypeError(`Invalid array function definition: ${message}`);
+  static direct(config) {
+    return new Nua(new DirectBackend(config));
   }
-  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.`
-      );
+  // Implementation
+  async get(prompt, options) {
+    if (typeof prompt !== "string" || prompt.trim() === "") {
+      throw new TypeError("Prompt must be a non-empty string");
     }
-    return {
-      ...row,
-      sourceRow
-    };
-  });
-}
-const toCastArrayApiRequest = (prompt, data, primaryKeyName, outputName, outputSchema) => ({
-  input: {
-    prompt,
-    data,
-    primaryKey: primaryKeyName
-  },
-  output: {
-    schema: outputSchema,
-    name: outputName
+    const outputSchema = options?.output?.schema ?? z.string();
+    const outputName = options?.output?.name ?? "result";
+    const jsonSchema = z.toJSONSchema(outputSchema);
+    return this.backend.castValue({
+      prompt,
+      data: options?.input ?? null,
+      outputName,
+      outputSchema: jsonSchema
+    });
   }
-});
-const createArrayFn = (client, inputFnDef) => {
-  const fnDef = validateArrayFnDef(inputFnDef);
-  const outputJsonSchema = z.toJSONSchema(fnDef.output.schema);
-  const toNuabaseError = (response) => {
-    if (response && typeof response === "object" && "error" in response)
-      return { error: String(response.error), isError: true };
-    return void 0;
-  };
-  const baseFn = async (data, primaryKeyName) => {
-    validateArrayRequestParams(data, primaryKeyName);
-    const response = await client.request(
-      "POST",
-      "cast/array",
-      toCastArrayApiRequest(
-        fnDef.prompt,
-        data,
-        primaryKeyName,
-        fnDef.output.name,
-        outputJsonSchema
-      )
-    );
-    const error = toNuabaseError(response);
-    if (error) return error;
-    const parsedResponse = zs_NuaQueuedResponse.safeParse(response);
-    if (!parsedResponse.success) {
-      const emsg = z.prettifyError(parsedResponse.error);
-      return { error: `Invalid queued response received from Nuabase API: ${emsg}`, isError: true };
+  // ========== list() - Array Operations ==========
+  async list(prompt, options) {
+    if (typeof prompt !== "string" || prompt.trim() === "") {
+      throw new TypeError("Prompt must be a non-empty string");
     }
-    return parsedResponse.data;
-  };
-  const nowFn = async (data, primaryKeyName) => {
-    validateArrayRequestParams(data, primaryKeyName);
-    const response = await client.request(
-      "POST",
-      "cast/array/now",
-      toCastArrayApiRequest(
-        fnDef.prompt,
-        data,
-        primaryKeyName,
-        fnDef.output.name,
-        outputJsonSchema
-      )
-    );
-    const error = toNuabaseError(response);
-    if (error) return error;
-    const outputKey = fnDef.output.name;
-    const successSchema = zs_NuaApiResponse_CastArray(primaryKeyName, outputKey, fnDef.output.schema);
-    const parsedResponse = successSchema.safeParse(response);
-    if (!parsedResponse.success) {
-      const emsg = z.prettifyError(parsedResponse.error);
-      return { error: `Invalid data received from Nuabase API: ${emsg}`, isError: true };
+    if (!Array.isArray(options.input)) {
+      throw new TypeError("Input must be an array for list()");
     }
-    return {
-      isSuccess: true,
-      llmRequestId: parsedResponse.data.llmRequestId,
-      kind: parsedResponse.data.kind,
-      data: addOriginalInputRows(
-        data,
-        parsedResponse.data.data,
-        primaryKeyName
-      ),
-      rowsWithNoResults: parsedResponse.data.rowsWithNoResults,
-      cacheHits: parsedResponse.data.cacheHits
-    };
-  };
-  return Object.assign(baseFn, {
-    now: nowFn
-  });
-};
-
-const createNuaApiResponseCastValue = (outputKey, outputSchema) => {
-  return z.object({
-    llmRequestId: z.string(),
-    kind: z.literal("cast/value"),
-    data: outputSchema,
-    isCacheHit: z.boolean(),
-    isSuccess: z.literal(true),
-    isError: z.optional(z.literal(false))
-  }).strict();
-};
-const zs_NuaApiResponse_CastValue = createNuaApiResponseCastValue;
-
-const zs_ValueFnDef = z.object({
-  prompt: z.string(),
-  output: z.object({
-    name: z.string(),
-    schema: z.custom(
-      (value) => value instanceof z.ZodType,
-      "Expected a Zod schema for `output.schema`"
-    )
-  })
-});
-const validateValueFnDef = (fnDef) => {
-  const parsed = zs_ValueFnDef.safeParse(fnDef);
-  if (!parsed.success) {
-    const message = z.prettifyError(parsed.error);
-    throw new TypeError(`Invalid value function definition: ${message}`);
+    if (typeof options.primaryKey !== "string" || options.primaryKey.trim() === "") {
+      throw new TypeError("primaryKey must be a non-empty string");
+    }
+    const jsonSchema = z.toJSONSchema(options.output.schema);
+    return this.backend.castArray({
+      prompt,
+      data: options.input,
+      primaryKey: options.primaryKey,
+      outputName: options.output.name,
+      outputSchema: jsonSchema
+    });
   }
-  return parsed.data;
-};
-
-const toCastValueApiRequest = (prompt, data, outputName, outputSchema) => ({
-  input: {
-    prompt,
-    data
-  },
-  output: {
-    schema: outputSchema,
-    name: outputName
+  // Implementation
+  async queueGet(prompt, options) {
+    if (typeof prompt !== "string" || prompt.trim() === "") {
+      throw new TypeError("Prompt must be a non-empty string");
+    }
+    if (!this.backend.queueCastValue) {
+      throw new Error("Queue operations are only supported in gateway mode");
+    }
+    const outputSchema = options?.output?.schema ?? z.string();
+    const outputName = options?.output?.name ?? "result";
+    const jsonSchema = z.toJSONSchema(outputSchema);
+    return this.backend.queueCastValue({
+      prompt,
+      data: options?.input ?? null,
+      outputName,
+      outputSchema: jsonSchema
+    });
   }
-});
-const createValueFn = (client, inputFnDef) => {
-  const fnDef = validateValueFnDef(inputFnDef);
-  const outputJsonSchema = z.toJSONSchema(fnDef.output.schema);
-  const toNuabaseError = (response) => {
-    if (response && typeof response === "object" && "error" in response)
-      return { error: String(response.error), isError: true };
-    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 response = await sendRequest("cast/value", data);
-    const error = toNuabaseError(response);
-    if (error) return error;
-    const parsedResponse = zs_NuaQueuedResponse.safeParse(response);
-    if (!parsedResponse.success) {
-      const emsg = z.prettifyError(parsedResponse.error);
-      return { error: `Invalid queued response received from Nuabase API: ${emsg}`, isError: true };
+  // ========== queueList() - Async Array Operations ==========
+  async queueList(prompt, options) {
+    if (typeof prompt !== "string" || prompt.trim() === "") {
+      throw new TypeError("Prompt must be a non-empty string");
     }
-    return parsedResponse.data;
-  };
-  const nowFn = async (data) => {
-    const response = await sendRequest("cast/value/now", data);
-    const error = toNuabaseError(response);
-    if (error) return error;
-    const outputKey = fnDef.output.name;
-    const successSchema = zs_NuaApiResponse_CastValue(
-      outputKey,
-      fnDef.output.schema
-    );
-    const parsedResponse = successSchema.safeParse(response);
-    if (!parsedResponse.success) {
-      const emsg = z.prettifyError(parsedResponse.error);
-      return { error: `Invalid data received from Nuabase API: ${emsg}`, isError: true };
+    if (!this.backend.queueCastArray) {
+      throw new Error("Queue operations are only supported in gateway mode");
     }
-    return {
-      isSuccess: true,
-      llmRequestId: parsedResponse.data.llmRequestId,
-      kind: parsedResponse.data.kind,
-      data: parsedResponse.data.data,
-      isCacheHit: parsedResponse.data.isCacheHit
-    };
-  };
-  return Object.assign(baseFn, {
-    now: nowFn
-  });
-};
-
-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;
+    if (!Array.isArray(options.input)) {
+      throw new TypeError("Input must be an array for queueList()");
     }
-    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);
-  }
-  createArrayFn(fnDef) {
-    return createArrayFn(this.apiClient, fnDef);
-  }
-  createFn(fnDef) {
-    return createValueFn(this.apiClient, fnDef);
-  }
-  async getRequest(llmRequestId) {
-    return getRequest(this.apiClient, llmRequestId);
+    if (typeof options.primaryKey !== "string" || options.primaryKey.trim() === "") {
+      throw new TypeError("primaryKey must be a non-empty string");
+    }
+    const jsonSchema = z.toJSONSchema(options.output.schema);
+    return this.backend.queueCastArray({
+      prompt,
+      data: options.input,
+      primaryKey: options.primaryKey,
+      outputName: options.output.name,
+      outputSchema: jsonSchema
+    });
   }
 }