@gullabs/xai 0.5.0 → 0.5.1

package/dist/index.d.cts

@@ -240,28 +240,23 @@ declare function buildXaiClient(auth: AuthMaterial): Promise<XaiClientLike>;
  * Classify a raw error thrown from the xAI Responses API call into a typed
  * {@link LlmError}.
  *
- * xAI's Responses API returns HTTP 400 (NOT 401) for an invalid API key, so
- * generic {@link classifyHttpStatus}-based classification (which maps 400 →
- * `bad_request`) is wrong for this one case. This function special-cases it:
- * a 400 response whose STRUCTURED parsed body matches the exact recorded
- * xAI auth-failure signature (`code: 'invalid-argument'` AND message prefix
- * `"Incorrect API key provided"` — see fixture 09) is reclassified as
- * `invalid_auth`. Free-form `Error.message` text is never scanned, so a 400
- * whose message merely *mentions* an API key (e.g. schema validation echoing
- * user content) stays `bad_request`. When the structured body is unavailable
- * or unparseable, classification falls through to the status-based
- * `classifyError` from `@gullabs/core`.
- *
- * A second special case widens `classifyError`'s generic fallback: when the
- * base classification lands on `kind: 'unknown'` (no HTTP status to route
- * by) AND the raw error matches a known transport-failure signature (see
- * {@link isXaiTransportError}), it is reclassified `kind: 'server',
- * retryable: true` — the same "provider fault, not caller fault, safe to
- * retry" bucket this adapter's `countTokens` path already uses for
- * provider-side failures with no HTTP status. A connection that never
- * reached xAI is not the caller's fault and is safe to retry; it must never
- * be surfaced as the non-retryable `unknown` kind, which Temporal treats as
- * fatal and uses to kill the run outright.
+ * HTTP status is a hint, not a kind. Overlays inspect the STRUCTURED parsed
+ * body only — never free-form `Error.message` — so echoed user content cannot
+ * change classification.
+ *
+ * 1. Already an {@link LlmError} → returned unchanged (including an untagged
+ *    one).
+ * 2. HTTP 400 whose structured body starts with
+ *    `"Incorrect API key provided"` (fixture 09; prefix only — the SDK may
+ *    drop `code`) → `invalid_auth`.
+ * 3. HTTP 403 whose structured body starts with
+ *    `"Content violates usage guidelines"` (fixture 15; `SAFETY_CHECK_TYPE_*`
+ *    suffixes vary) → `content_filter`. A bare 403 without that body stays
+ *    the core default, `invalid_auth`.
+ * 4. `kind: 'unknown'` with a known transport-failure signature (see
+ *    {@link isXaiTransportError}) → `server`, retryable. A connection that
+ *    never reached xAI is not the caller's fault.
+ * 5. Else rebuild the core classification tagged `provider: 'xai'`.
  */
 declare function classifyXaiError(rawErr: unknown): LlmError;
 interface XaiAdapterOptions {

package/dist/index.d.ts

@@ -240,28 +240,23 @@ declare function buildXaiClient(auth: AuthMaterial): Promise<XaiClientLike>;
  * Classify a raw error thrown from the xAI Responses API call into a typed
  * {@link LlmError}.
  *
- * xAI's Responses API returns HTTP 400 (NOT 401) for an invalid API key, so
- * generic {@link classifyHttpStatus}-based classification (which maps 400 →
- * `bad_request`) is wrong for this one case. This function special-cases it:
- * a 400 response whose STRUCTURED parsed body matches the exact recorded
- * xAI auth-failure signature (`code: 'invalid-argument'` AND message prefix
- * `"Incorrect API key provided"` — see fixture 09) is reclassified as
- * `invalid_auth`. Free-form `Error.message` text is never scanned, so a 400
- * whose message merely *mentions* an API key (e.g. schema validation echoing
- * user content) stays `bad_request`. When the structured body is unavailable
- * or unparseable, classification falls through to the status-based
- * `classifyError` from `@gullabs/core`.
- *
- * A second special case widens `classifyError`'s generic fallback: when the
- * base classification lands on `kind: 'unknown'` (no HTTP status to route
- * by) AND the raw error matches a known transport-failure signature (see
- * {@link isXaiTransportError}), it is reclassified `kind: 'server',
- * retryable: true` — the same "provider fault, not caller fault, safe to
- * retry" bucket this adapter's `countTokens` path already uses for
- * provider-side failures with no HTTP status. A connection that never
- * reached xAI is not the caller's fault and is safe to retry; it must never
- * be surfaced as the non-retryable `unknown` kind, which Temporal treats as
- * fatal and uses to kill the run outright.
+ * HTTP status is a hint, not a kind. Overlays inspect the STRUCTURED parsed
+ * body only — never free-form `Error.message` — so echoed user content cannot
+ * change classification.
+ *
+ * 1. Already an {@link LlmError} → returned unchanged (including an untagged
+ *    one).
+ * 2. HTTP 400 whose structured body starts with
+ *    `"Incorrect API key provided"` (fixture 09; prefix only — the SDK may
+ *    drop `code`) → `invalid_auth`.
+ * 3. HTTP 403 whose structured body starts with
+ *    `"Content violates usage guidelines"` (fixture 15; `SAFETY_CHECK_TYPE_*`
+ *    suffixes vary) → `content_filter`. A bare 403 without that body stays
+ *    the core default, `invalid_auth`.
+ * 4. `kind: 'unknown'` with a known transport-failure signature (see
+ *    {@link isXaiTransportError}) → `server`, retryable. A connection that
+ *    never reached xAI is not the caller's fault.
+ * 5. Else rebuild the core classification tagged `provider: 'xai'`.
  */
 declare function classifyXaiError(rawErr: unknown): LlmError;
 interface XaiAdapterOptions {

package/dist/index.js

@@ -171,6 +171,11 @@ function isXaiAuthFailureBody(rawErr) {
   const text = extractXaiErrorBodyText(rawErr);
   return text !== void 0 && text.startsWith(XAI_AUTH_ERROR_MESSAGE_PREFIX);
 }
+var XAI_SAFETY_CHECK_MESSAGE_PREFIX = "Content violates usage guidelines";
+function isXaiSafetyCheckBody(rawErr) {
+  const text = extractXaiErrorBodyText(rawErr);
+  return text !== void 0 && text.startsWith(XAI_SAFETY_CHECK_MESSAGE_PREFIX);
+}
 var XAI_TRANSPORT_ERROR_PATTERN = /connection error|econnreset|econnrefused|etimedout|eai_again|epipe|socket hang up|fetch failed/i;
 function matchesXaiTransportSignature(err) {
   if (!(err instanceof Error)) return false;
@@ -209,6 +214,16 @@ function classifyXaiError(rawErr) {
       cause: base.cause ?? rawErr
     });
   }
+  if (base.httpStatus === 403 && isXaiSafetyCheckBody(rawErr)) {
+    const bodyText = extractXaiErrorBodyText(rawErr);
+    return new LlmError(bodyText ?? base.message, {
+      kind: "content_filter",
+      retryable: false,
+      httpStatus: base.httpStatus,
+      provider: "xai",
+      cause: base.cause ?? rawErr
+    });
+  }
   if (base.kind === "unknown" && isXaiTransportError(rawErr)) {
     return new LlmError(base.message, {
       kind: "server",