@gullabs/xai 0.2.5 → 0.4.0

package/README.md

@@ -30,6 +30,10 @@ xAI has no first-party TypeScript SDK. xAI's own quickstart recommends using the
 | `XaiModelRates`         | Per-model rate entry type (`inputPerM`, `cachedPerM`, `outputPerM`, optional `gt200k`)          |
 | `Grok45ConfigSchema`    | Strict Zod config schema for `grok-4.5`                                                         |
 | `XaiProviderOptions`    | `{ promptCacheKey? }` — typed `providerOptions.xai` extension shape                             |
+| `XaiFileStore`          | Files API store: upload (TTL), get, list, idempotent delete, content                            |
+| `XaiFileHandle`         | `{ id, filename?, bytes?, expiresAt?, … }` returned by the store                                |
+| `FileDeleteOptions`     | `{ failClosed?, signal? }` — opt-in fail-closed delete for durable release gates                |
+| `XAI_FILE_TTL_*`        | TTL bounds (`3600`…`2592000` seconds) and `XAI_FILE_MAX_BYTES` (48 MiB)                         |
 
 ## Quick example
 
@@ -63,12 +67,62 @@ The default registry ships exactly one model: `grok-4.5` (500k token context win
 - **No penalties/stop** — `presence_penalty`, `frequency_penalty`, and `stop` are not in the config schema at all; xAI hard-rejects these on reasoning models, so the schema never admits them (reject-don't-map).
 - **No service tiers** — xAI has no service-tier concept for `grok-4.5`; setting `serviceTier` on the request throws `bad_request`.
 
+## Files store (`XaiFileStore`)
+
+Thin REST wrapper over xAI Files (`POST/GET/DELETE /v1/files`). Auth is injected — the store never reads `process.env`.
+
+```ts
+import { XaiFileStore } from '@gullabs/xai'
+
+const store = new XaiFileStore({
+  auth: { apiKey: 'YOUR_XAI_API_KEY' },
+  // Optional: onDeleteError, logger, fetch, baseUrl
+})
+
+const handle = await store.upload({
+  data: pdfBytes,
+  filename: 'matter.pdf',
+  mimeType: 'application/pdf',
+  expiresAfterSeconds: 86_400, // 24h; range 3600…2592000
+})
+
+// Attach on generate via core FileRefPart:
+// { kind: 'file-ref', fileId: handle.id }
+
+await store.delete(handle.id) // default fail-open; 404 = success
+await store.delete(handle.id) // safe to call twice
+
+// Durable gate (Temporal release / orphan sweep) — mark DB only after success:
+try {
+  await store.delete(handle.id, { failClosed: true })
+  await db.markReleased(handle.id)
+} catch (err) {
+  // leave released_at null; do not rethrow from workflow finally
+  logger.warn({ err }, 'delete failed')
+}
+```
+
+| Behavior                    | Detail                                                                                                                                                                                                        |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| TTL                         | `expiresAfterSeconds` validated client-side; multipart sends `expires_after` **before** `file` (xAI requirement)                                                                                              |
+| Delete (default)            | Fail-open: non-404 errors call `onDeleteError` and resolve; 404 is silent success                                                                                                                             |
+| Delete (`failClosed: true`) | Non-404 failures **throw** `LlmError`; `onDeleteError` is not called. Prefer **per-id** delete + markReleased when writing durable release state — fail-closed `deleteAll` does not cancel in-flight siblings |
+| Empty `fileId`              | Always throws `bad_request` (both modes)                                                                                                                                                                      |
+| Storage cost                | ~$0.025/GiB/day — **not** injected into `computeCost` token lanes                                                                                                                                             |
+| ZDR teams                   | New uploads and `file_id` attachments are blocked by xAI; errors mention Zero Data Retention when detectable                                                                                                  |
+| Max size                    | 48 MiB (conservative vs docs 48–50 MB)                                                                                                                                                                        |
+
+**Billing note:** attaching files on Responses implicitly enables xAI's `attachment_search` agentic tool. Expect tool-invocation fees and reasoning tokens beyond a plain completion. When xAI returns numeric counters such as `num_server_side_tools_used` / `num_sources_used`, they appear on `usage.details` under those raw names (and full payload in `usage.raw`) for host visibility — they are **not** folded into `computeXaiCost` token lanes yet (no tool Cost lane). Collections / public URL minting are out of scope for this store.
+
+**Host tests:** `@gullabs/testing` exports `FakeXaiFileStore` (in-memory upload/get/delete with optional TTL clock and `failClosed`).
+
 ## Vision constraints
 
-`grok-4.5` accepts image input as an `inline-media` or `file-uri` `Part`:
+`grok-4.5` accepts image input as an `inline-media` or `file-uri` `Part`, and document attachments as a `file-ref` `Part`:
 
 - **`inline-media`** — only `image/jpeg` and `image/png` are accepted; anything else throws `bad_request`. The decoded payload must be at most 20 MiB (xAI's documented inline-image ceiling); larger images throw `bad_request` before the request is sent.
 - **`file-uri`** — only accepted when the URI is a public `http(s)://` URL **and** the declared `mimeType` is jpg/png. A provider-hosted URI from another provider — for example a Gemini Files API URI (`https://generativelanguage.googleapis.com/...`) — is technically `https://` but is not dereferenceable by xAI and is not portable across providers. The adapter rejects it rather than trying to map or proxy it (reject-don't-map).
+- **`file-ref`** — maps to Responses `{ type: 'input_file', file_id }`. Upload first with `XaiFileStore`, then pass `{ kind: 'file-ref', fileId: handle.id }`. Empty ids throw `bad_request`.
 - **Undocumented minimum size** — xAI enforces an undocumented server-side minimum image size (observed ~8px/side, ~512 total px). This adapter does **not** pre-validate pixel dimensions; a too-small image surfaces as a live `bad_request` error from the xAI API itself, classified normally by `classifyXaiError`, not rejected client-side.
 
 ## Caching
@@ -96,7 +150,7 @@ xAI's own `/v1/models` listing surfaces `grok-4.5-latest` and `grok-build-latest
 
 ## Explicitly deferred (not built in v1)
 
-- Server-side agentic tools (`web_search`, `x_search`, `code_interpreter`, file/collections search, remote MCP) and their per-invocation billing (e.g. `web_search` at $5/1k) — no `Cost` lane exists for these yet.
+- Server-side agentic tools as an explicit API (`web_search`, `x_search`, `code_interpreter`, collections search, remote MCP) and their per-invocation billing lanes in `computeCost`. Note: **file attachments still auto-enable `attachment_search`** on xAI's side — that implicit tool is documented above, not modeled as a first-class library tool surface.
 - `/v1/chat/completions` (documented by xAI as legacy) and `/v1/messages` (the Anthropic-compatible migration shim) — this adapter only targets `/v1/responses`.
 - Batch API (`grok-4.5` is not eligible at launch) and image generation models.
 - Stateful conversations — `store` is always sent as `false`, and `previous_response_id` is not supported.

package/dist/index.cjs

@@ -64,8 +64,19 @@ function mapPart(p) {
           `xAI only accepts public http(s) image URLs via FileUriPart; got scheme of "${p.uri}" / mimeType "${p.mimeType}".`
         );
       }
+      if (p.uri.includes("generativelanguage.googleapis.com") || p.uri.includes("googleapis.com/v1beta/files")) {
+        throw badXaiRequest(
+          `xAI cannot dereference Gemini/Google Files URIs via FileUriPart; upload to xAI Files and use FileRefPart (file_id) instead. Got "${p.uri}".`
+        );
+      }
       return { type: "input_image", image_url: p.uri };
     }
+    case "file-ref": {
+      if (typeof p.fileId !== "string" || p.fileId.trim() === "") {
+        throw badXaiRequest("FileRefPart.fileId must be a non-empty string.");
+      }
+      return { type: "input_file", file_id: p.fileId };
+    }
     default:
       return core.assertNever(p);
   }
@@ -364,6 +375,461 @@ function xaiAdapter(opts) {
     }
   };
 }
+var XAI_FILE_TTL_MIN_SECONDS = 3600;
+var XAI_FILE_TTL_MAX_SECONDS = 2592e3;
+var XAI_FILE_MAX_BYTES = 48 * 1024 * 1024;
+var XAI_FILES_DEFAULT_BASE_URL = "https://api.x.ai/v1";
+function isPlainRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function badRequest(message) {
+  return new core.LlmError(message, {
+    kind: "bad_request",
+    retryable: false,
+    provider: "xai"
+  });
+}
+function resolveFileId(fileIdOrHandle) {
+  if (typeof fileIdOrHandle === "string") {
+    return fileIdOrHandle;
+  }
+  return fileIdOrHandle.id;
+}
+function unixSecondsToDate(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return void 0;
+  }
+  return new Date(value * 1e3);
+}
+function makeHandle(raw) {
+  if (typeof raw.id !== "string" || raw.id.length === 0) {
+    throw new core.LlmError("File response missing required field (id)", {
+      kind: "server",
+      retryable: false,
+      provider: "xai"
+    });
+  }
+  const handle = {
+    id: raw.id,
+    raw
+  };
+  if (typeof raw.filename === "string" && raw.filename.length > 0) {
+    handle.filename = raw.filename;
+  }
+  if (typeof raw.bytes === "number" && Number.isFinite(raw.bytes)) {
+    handle.bytes = raw.bytes;
+  }
+  if (typeof raw.purpose === "string") {
+    handle.purpose = raw.purpose;
+  }
+  const createdAt = unixSecondsToDate(raw.created_at);
+  if (createdAt !== void 0) {
+    handle.createdAt = createdAt;
+  }
+  if (raw.expires_at !== null && raw.expires_at !== void 0) {
+    const expiresAt = unixSecondsToDate(raw.expires_at);
+    if (expiresAt !== void 0) {
+      handle.expiresAt = expiresAt;
+    }
+  }
+  return handle;
+}
+function byteLengthOf(data) {
+  return data instanceof Uint8Array ? data.byteLength : data.size;
+}
+function toBlob(data, mimeType) {
+  if (data instanceof Blob) {
+    return data;
+  }
+  const copy = Uint8Array.from(data);
+  return mimeType !== void 0 && mimeType.length > 0 ? new Blob([copy], { type: mimeType }) : new Blob([copy]);
+}
+var XaiFilesHttpError = class extends Error {
+  status;
+  error;
+  constructor(status, message, errorBody) {
+    super(message);
+    this.name = "XaiFilesHttpError";
+    this.status = status;
+    this.error = errorBody;
+  }
+};
+async function throwHttpFailure(res) {
+  const status = res.status;
+  let bodyText = "";
+  try {
+    bodyText = await res.text();
+  } catch {
+    bodyText = "";
+  }
+  let parsed = bodyText;
+  if (bodyText.length > 0) {
+    try {
+      parsed = JSON.parse(bodyText);
+    } catch {
+      parsed = bodyText;
+    }
+  }
+  let message = `xAI Files API HTTP ${status}`;
+  if (typeof parsed === "string" && parsed.length > 0) {
+    message = parsed;
+  } else if (isPlainRecord2(parsed) && typeof parsed["error"] === "string") {
+    message = parsed["error"];
+  }
+  throw new XaiFilesHttpError(status, message, parsed);
+}
+function isNotFoundError(err) {
+  if (err instanceof core.LlmError && err.httpStatus === 404) {
+    return true;
+  }
+  if (typeof err === "object" && err !== null) {
+    const status = err.status;
+    if (status === 404) return true;
+    const httpStatus = err.httpStatus;
+    if (httpStatus === 404) return true;
+  }
+  return false;
+}
+function notFoundError(fileId, operation) {
+  return new core.LlmError(`xAI file not found during ${operation}: "${fileId}"`, {
+    kind: "bad_request",
+    retryable: false,
+    httpStatus: 404,
+    provider: "xai"
+  });
+}
+function maybeZdrHint(message) {
+  if (/zero\s*data\s*retention|\bzdr\b|files?\s+(api\s+)?(disabled|unavailable|not supported)/i.test(
+    message
+  )) {
+    return `${message} (xAI Zero Data Retention blocks new file uploads and file_id attachments for this team.)`;
+  }
+  return message;
+}
+function extractThrownMessage(raw) {
+  if (raw === null || typeof raw !== "object") return void 0;
+  const obj = raw;
+  if (typeof obj["message"] === "string" && obj["message"].length > 0) {
+    return obj["message"];
+  }
+  const err = obj["error"];
+  if (typeof err === "string" && err.length > 0) return err;
+  if (typeof err === "object" && err !== null) {
+    const nested = err;
+    if (typeof nested["error"] === "string" && nested["error"].length > 0) {
+      return nested["error"];
+    }
+    if (typeof nested["message"] === "string" && nested["message"].length > 0) {
+      return nested["message"];
+    }
+  }
+  return void 0;
+}
+function classifyStoreError(raw) {
+  if (raw instanceof core.LlmError) {
+    return raw;
+  }
+  const classified = classifyXaiError(raw);
+  const bodyMessage = extractThrownMessage(raw);
+  const baseMessage = bodyMessage !== void 0 && (classified.message.startsWith("HTTP ") || classified.message.length === 0) ? bodyMessage : classified.message;
+  const hinted = maybeZdrHint(baseMessage);
+  if (hinted === classified.message && classified.provider === "xai" && bodyMessage === void 0) {
+    return classified;
+  }
+  return new core.LlmError(hinted, {
+    kind: classified.kind,
+    retryable: classified.retryable,
+    ...classified.httpStatus !== void 0 ? { httpStatus: classified.httpStatus } : {},
+    ...classified.retryAfterMs !== void 0 ? { retryAfterMs: classified.retryAfterMs } : {},
+    provider: "xai",
+    cause: classified.cause ?? raw
+  });
+}
+var XaiFileStore = class {
+  apiKey;
+  baseUrl;
+  fetchImpl;
+  onDeleteError;
+  logger;
+  constructor(opts) {
+    this.apiKey = requireApiKey(opts.auth);
+    this.baseUrl = (opts.baseUrl ?? XAI_FILES_DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.fetchImpl = opts.fetch ?? fetch;
+    this.logger = opts.logger;
+    this.onDeleteError = opts.onDeleteError ?? ((fileId, err) => {
+      const message = core.redactSecrets(core.classifyError(err).message);
+      if (this.logger !== void 0) {
+        this.logger.error({ fileId, error: message }, "xai.file.delete.failed");
+      } else {
+        console.error(`[XaiFileStore] delete failed for "${fileId}":`, message);
+      }
+    });
+  }
+  authHeaders() {
+    const headers = new Headers();
+    headers.set("Authorization", `Bearer ${this.apiKey}`);
+    return headers;
+  }
+  filesUrl(path = "") {
+    if (path.length === 0) return `${this.baseUrl}/files`;
+    return `${this.baseUrl}/files/${path.replace(/^\//, "")}`;
+  }
+  /** Build RequestInit without writing `signal: undefined` (exactOptionalPropertyTypes). */
+  requestInit(method, opts) {
+    const init = {
+      method,
+      headers: this.authHeaders()
+    };
+    if (opts?.body !== void 0) {
+      init.body = opts.body;
+    }
+    if (opts?.signal !== void 0) {
+      init.signal = opts.signal;
+    }
+    return init;
+  }
+  /**
+   * Upload bytes to xAI Files. Returns immediately with metadata (no poll).
+   *
+   * Multipart field order is load-bearing: `expires_after` then `purpose`
+   * then `file` — reversing order yields HTTP 400 from xAI.
+   */
+  async upload(input, signal) {
+    if (typeof input.filename !== "string" || input.filename.trim() === "") {
+      throw badRequest("XaiFileUploadInput.filename must be a non-empty string.");
+    }
+    const size = byteLengthOf(input.data);
+    if (size > XAI_FILE_MAX_BYTES) {
+      throw badRequest(
+        `xAI file uploads must be at most ${XAI_FILE_MAX_BYTES} bytes (48 MiB); got ${size}.`
+      );
+    }
+    if (input.expiresAfterSeconds !== void 0) {
+      const ttl = input.expiresAfterSeconds;
+      if (typeof ttl !== "number" || !Number.isInteger(ttl) || ttl < XAI_FILE_TTL_MIN_SECONDS || ttl > XAI_FILE_TTL_MAX_SECONDS) {
+        throw badRequest(
+          `expiresAfterSeconds must be an integer in [${XAI_FILE_TTL_MIN_SECONDS}, ${XAI_FILE_TTL_MAX_SECONDS}]; got ${String(ttl)}.`
+        );
+      }
+    }
+    const purpose = input.purpose ?? "assistants";
+    const form = new FormData();
+    if (input.expiresAfterSeconds !== void 0) {
+      form.append("expires_after", String(input.expiresAfterSeconds));
+    }
+    form.append("purpose", purpose);
+    form.append("file", toBlob(input.data, input.mimeType), input.filename);
+    let res;
+    try {
+      res = await this.fetchImpl(
+        this.filesUrl(),
+        this.requestInit("POST", {
+          body: form,
+          ...signal !== void 0 ? { signal } : {}
+        })
+      );
+    } catch (e) {
+      if (signal?.aborted === true) {
+        throw new core.LlmError("xAI file upload aborted", {
+          kind: "aborted",
+          retryable: false,
+          provider: "xai"
+        });
+      }
+      throw classifyStoreError(e);
+    }
+    if (!res.ok) {
+      try {
+        await throwHttpFailure(res);
+      } catch (e) {
+        throw classifyStoreError(e);
+      }
+    }
+    let json;
+    try {
+      json = await res.json();
+    } catch (e) {
+      throw new core.LlmError("xAI file upload returned non-JSON body", {
+        kind: "server",
+        retryable: false,
+        provider: "xai",
+        cause: e
+      });
+    }
+    return makeHandle(json);
+  }
+  async get(fileId, signal) {
+    if (typeof fileId !== "string" || fileId.trim() === "") {
+      throw badRequest("fileId must be a non-empty string.");
+    }
+    let res;
+    try {
+      res = await this.fetchImpl(
+        this.filesUrl(fileId),
+        this.requestInit("GET", signal !== void 0 ? { signal } : {})
+      );
+    } catch (e) {
+      if (signal?.aborted === true) {
+        throw new core.LlmError("xAI file get aborted", {
+          kind: "aborted",
+          retryable: false,
+          provider: "xai"
+        });
+      }
+      throw classifyStoreError(e);
+    }
+    if (res.status === 404) {
+      throw notFoundError(fileId, "get");
+    }
+    if (!res.ok) {
+      try {
+        await throwHttpFailure(res);
+      } catch (e) {
+        throw classifyStoreError(e);
+      }
+    }
+    const json = await res.json();
+    return makeHandle(json);
+  }
+  async list(opts = {}, signal) {
+    if (opts.limit !== void 0) {
+      if (typeof opts.limit !== "number" || !Number.isInteger(opts.limit) || opts.limit < 1 || opts.limit > 100) {
+        throw badRequest("list.limit must be an integer in [1, 100].");
+      }
+    }
+    const params = new URLSearchParams();
+    if (opts.limit !== void 0) params.set("limit", String(opts.limit));
+    if (opts.order !== void 0) params.set("order", opts.order);
+    if (opts.sortBy !== void 0) params.set("sort_by", opts.sortBy);
+    if (opts.paginationToken !== void 0) {
+      params.set("pagination_token", opts.paginationToken);
+    }
+    const qs = params.toString();
+    const url = qs.length > 0 ? `${this.filesUrl()}?${qs}` : this.filesUrl();
+    let res;
+    try {
+      res = await this.fetchImpl(
+        url,
+        this.requestInit("GET", signal !== void 0 ? { signal } : {})
+      );
+    } catch (e) {
+      if (signal?.aborted === true) {
+        throw new core.LlmError("xAI file list aborted", {
+          kind: "aborted",
+          retryable: false,
+          provider: "xai"
+        });
+      }
+      throw classifyStoreError(e);
+    }
+    if (!res.ok) {
+      try {
+        await throwHttpFailure(res);
+      } catch (e) {
+        throw classifyStoreError(e);
+      }
+    }
+    const json = await res.json();
+    const files = Array.isArray(json.data) ? json.data.map((f) => makeHandle(f)) : [];
+    const result = { files };
+    if (typeof json.pagination_token === "string" && json.pagination_token.length > 0) {
+      result.paginationToken = json.pagination_token;
+    }
+    return result;
+  }
+  /**
+   * Delete a file. Idempotent: HTTP 404 → success.
+   *
+   * Default (`failClosed` omitted/false): non-404 errors go to `onDeleteError`
+   * and resolve (P5 fail-open). With `failClosed: true`, non-404 errors throw
+   * typed `LlmError` and `onDeleteError` is not called.
+   *
+   * Empty/blank ids always throw `bad_request` (caller fault).
+   */
+  async delete(fileIdOrHandle, opts) {
+    const fileId = resolveFileId(fileIdOrHandle);
+    if (typeof fileId !== "string" || fileId.trim() === "") {
+      throw badRequest("fileId must be a non-empty string.");
+    }
+    const failClosed = opts?.failClosed === true;
+    const signal = opts?.signal;
+    try {
+      const res = await this.fetchImpl(
+        this.filesUrl(fileId),
+        this.requestInit("DELETE", signal !== void 0 ? { signal } : {})
+      );
+      if (res.status === 404) {
+        return;
+      }
+      if (!res.ok) {
+        await throwHttpFailure(res);
+      }
+    } catch (err) {
+      if (isNotFoundError(err)) {
+        return;
+      }
+      const classified = signal?.aborted === true && !(err instanceof core.LlmError) ? new core.LlmError("xAI file delete aborted", {
+        kind: "aborted",
+        retryable: false,
+        provider: "xai",
+        cause: err
+      }) : classifyStoreError(err);
+      if (failClosed) {
+        throw classified;
+      }
+      this.onDeleteError(fileId, classified);
+    }
+  }
+  /**
+   * Delete many files.
+   *
+   * Fail-open (default): `Promise.allSettled` — each failure → `onDeleteError`.
+   * Fail-closed: `Promise.all` — first throw rejects; in-flight siblings are
+   * not cancelled (partial deletes may already have succeeded at the provider).
+   * Prefer per-id delete + host DB mark when gating durable release state.
+   */
+  async deleteAll(ids, opts) {
+    if (opts?.failClosed === true) {
+      await Promise.all(ids.map((id) => this.delete(id, opts)));
+      return;
+    }
+    await Promise.allSettled(ids.map((id) => this.delete(id, opts)));
+  }
+  /** Download raw file bytes. */
+  async getContent(fileId, signal) {
+    if (typeof fileId !== "string" || fileId.trim() === "") {
+      throw badRequest("fileId must be a non-empty string.");
+    }
+    let res;
+    try {
+      res = await this.fetchImpl(
+        this.filesUrl(`${fileId}/content`),
+        this.requestInit("GET", signal !== void 0 ? { signal } : {})
+      );
+    } catch (e) {
+      if (signal?.aborted === true) {
+        throw new core.LlmError("xAI file content download aborted", {
+          kind: "aborted",
+          retryable: false,
+          provider: "xai"
+        });
+      }
+      throw classifyStoreError(e);
+    }
+    if (res.status === 404) {
+      throw notFoundError(fileId, "getContent");
+    }
+    if (!res.ok) {
+      try {
+        await throwHttpFailure(res);
+      } catch (e) {
+        throw classifyStoreError(e);
+      }
+    }
+    const buf = await res.arrayBuffer();
+    return new Uint8Array(buf);
+  }
+};
 var Grok45ConfigSchema = zod.z.strictObject({
   temperature: zod.z.number().optional().meta({
     title: "Temperature",
@@ -530,7 +996,12 @@ function xaiProvider(opts) {
 }
 
 exports.Grok45ConfigSchema = Grok45ConfigSchema;
+exports.XAI_FILES_DEFAULT_BASE_URL = XAI_FILES_DEFAULT_BASE_URL;
+exports.XAI_FILE_MAX_BYTES = XAI_FILE_MAX_BYTES;
+exports.XAI_FILE_TTL_MAX_SECONDS = XAI_FILE_TTL_MAX_SECONDS;
+exports.XAI_FILE_TTL_MIN_SECONDS = XAI_FILE_TTL_MIN_SECONDS;
 exports.XAI_PRICING = XAI_PRICING;
+exports.XaiFileStore = XaiFileStore;
 exports.buildXaiClient = buildXaiClient;
 exports.classifyXaiError = classifyXaiError;
 exports.computeXaiCost = computeXaiCost;