@gullabs/xai 0.3.0 → 0.4.1

package/README.md

@@ -5,10 +5,10 @@ xAI Grok provider adapter for any-llm. A thin mapping layer over the `openai` np
 ## Install
 
 ```bash
-pnpm add @gullabs/xai @gullabs/core openai
+pnpm add @gullabs/xai @gullabs/core openai  # peer: openai ^6 || ^7
 ```
 
-**Peer dependency:** `openai ^6`
+**Peer dependency:** `openai ^6 || ^7`
 
 xAI has no first-party TypeScript SDK. xAI's own quickstart recommends using the `openai` npm package with a `baseURL` override pointed at xAI's endpoint — that is the path this adapter takes. `buildXaiClient` is the only place in `packages/xai/src` that imports `openai`, so the rest of the adapter (and its tests) stay decoupled from the real SDK via the structural `XaiClientLike` interface.
 
@@ -32,6 +32,7 @@ xAI has no first-party TypeScript SDK. xAI's own quickstart recommends using the
 | `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
@@ -88,19 +89,32 @@ const handle = await store.upload({
 // Attach on generate via core FileRefPart:
 // { kind: 'file-ref', fileId: handle.id }
 
-await store.delete(handle.id) // 404 = success (idempotent)
+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       | Fail-open: non-404 errors call `onDeleteError` and resolve; 404 is silent success                                |
-| 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)                                                                           |
+| 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.
 
-**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. 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
 

package/dist/index.cjs

@@ -739,35 +739,25 @@ var XaiFileStore = class {
   }
   /**
    * Delete a file. Idempotent: HTTP 404 → success.
-   * Other errors are forwarded to `onDeleteError` and **not** rethrown (P5).
+   *
+   * 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, signal) {
+  async delete(fileIdOrHandle, opts) {
     const fileId = resolveFileId(fileIdOrHandle);
     if (typeof fileId !== "string" || fileId.trim() === "") {
-      this.onDeleteError(String(fileId), badRequest("fileId must be a non-empty string."));
-      return;
+      throw badRequest("fileId must be a non-empty string.");
     }
+    const failClosed = opts?.failClosed === true;
+    const signal = opts?.signal;
     try {
-      let res;
-      try {
-        res = await this.fetchImpl(
-          this.filesUrl(fileId),
-          this.requestInit("DELETE", signal !== void 0 ? { signal } : {})
-        );
-      } catch (e) {
-        if (signal?.aborted === true) {
-          this.onDeleteError(
-            fileId,
-            new core.LlmError("xAI file delete aborted", {
-              kind: "aborted",
-              retryable: false,
-              provider: "xai"
-            })
-          );
-          return;
-        }
-        throw e;
-      }
+      const res = await this.fetchImpl(
+        this.filesUrl(fileId),
+        this.requestInit("DELETE", signal !== void 0 ? { signal } : {})
+      );
       if (res.status === 404) {
         return;
       }
@@ -778,14 +768,32 @@ var XaiFileStore = class {
       if (isNotFoundError(err)) {
         return;
       }
-      this.onDeleteError(fileId, classifyStoreError(err));
+      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. Each failure is individually fail-open; none are thrown.
+   * 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, signal) {
-    await Promise.allSettled(ids.map((id) => this.delete(id, signal)));
+  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) {