@anvailabs/sandhi 0.5.0

package/sandhi.d.ts

@@ -0,0 +1,22 @@
+// Type entry point for @anvai-labs/sandhi. Re-exports the napi-generated types and augments
+// `ByteStream` with the `Symbol.asyncIterator` that `sandhi.js` installs at runtime (ADR-0047 D10
+// step 3c), so `for await (const chunk of stream)` type-checks.
+
+export * from "./index";
+export * from "./contracts";
+import type { ProviderErrorV1 } from "./contracts";
+
+/** Provider-boundary error; `payload` is the parsed ProviderErrorV1 (TD-0008 P2/C). */
+export declare class SandhiProviderError extends Error {
+  payload: ProviderErrorV1;
+  code: string;
+  httpStatus: number | null;
+  retryable: boolean;
+  requestId: string | null;
+  details: Record<string, unknown>;
+}
+declare module "./index" {
+  interface TypedEventStream {
+    [Symbol.asyncIterator](): AsyncIterator<string>;
+  }
+}

package/sandhi.js

@@ -0,0 +1,113 @@
+// Sandhi Node entry point (ADR-0047 D10 step 3c).
+//
+// Re-exports the napi-generated binding (`index.js`) and adds the one thing the Rust addon can't
+// declare itself: a `Symbol.asyncIterator` on `ByteStream`, so a streaming transport call is usable
+// with `for await`. `ByteStream.read()` resolves to the next chunk, or `null` when exhausted.
+//
+// This file is hand-written and stable; `index.js` / `index.d.ts` are regenerated by `napi build`.
+// The named re-exports below are literal (not `module.exports = native`) so ESM consumers can do
+// `import { complete } from "@anvai-labs/sandhi"` — cjs-module-lexer only sees literal assignments.
+// Keep this list in sync with `index.js` when the addon gains a new export.
+
+const native = require("./index.js");
+
+/**
+ * Provider-boundary error (parity with the Python binding's SandhiProviderError,
+ * TD-0008 P2/C). `payload` is the parsed ProviderErrorV1; `code` / `httpStatus` /
+ * `retryable` / `requestId` are conveniences so consumers branch on typed fields
+ * instead of string-sniffing arbitrary Error messages.
+ */
+class SandhiProviderError extends Error {
+  constructor(payload, message) {
+    super(message);
+    this.name = "SandhiProviderError";
+    this.payload = payload;
+    this.code = payload.code;
+    this.httpStatus = payload.http_status ?? null;
+    this.retryable = Boolean(payload.retryable);
+    this.requestId = payload.request_id ?? null;
+    this.details = payload.details ?? {};
+  }
+}
+
+// The native layer throws plain Errors whose message is the ProviderErrorV1 JSON.
+// Rewrap into the typed class when the shape matches; anything else passes through
+// (binding-internal failures stay ordinary Errors — the distinction is the point).
+function toSandhiError(error) {
+  if (error instanceof SandhiProviderError) return error;
+  const message = error && typeof error.message === "string" ? error.message : null;
+  if (message && message.startsWith("{")) {
+    try {
+      const payload = JSON.parse(message);
+      if (payload && typeof payload.code === "string") {
+        return new SandhiProviderError(payload, message);
+      }
+    } catch (_) {
+      /* not a typed payload — fall through */
+    }
+  }
+  return error;
+}
+
+if (native.TypedEventStream && !native.TypedEventStream.prototype[Symbol.asyncIterator]) {
+  native.TypedEventStream.prototype[Symbol.asyncIterator] = function asyncIterator() {
+    const stream = this;
+    return {
+      async next() {
+        let event;
+        try {
+          event = await stream.read();
+        } catch (error) {
+          throw toSandhiError(error);
+        }
+        return event === null || event === undefined
+          ? { done: true, value: undefined }
+          : { done: false, value: event };
+      },
+    };
+  };
+}
+
+if (native.TypedProvider && !native.TypedProvider.prototype.__sandhiTypedErrors) {
+  const rawCompleteJson = native.TypedProvider.prototype.completeJson;
+  if (typeof rawCompleteJson === "function") {
+    // Variadic forward: the wrapper adds typed-error rewiring only — every call argument
+    // (incl. the optional per-call wireHeadersJson, TD-0022 D1) reaches the native method.
+    native.TypedProvider.prototype.completeJson = async function completeJson(
+      ...args
+    ) {
+      try {
+        return await rawCompleteJson.call(this, ...args);
+      } catch (error) {
+        throw toSandhiError(error);
+      }
+    };
+  }
+  // streamJson: the SETUP call can itself fail (upstream 401/timeout at connect)
+  // before any iterator exists — those must be instanceof-checkable too, not just
+  // the per-event read() errors (TD-0021 P1 / G22 close-out).
+  const rawStreamJson = native.TypedProvider.prototype.streamJson;
+  if (typeof rawStreamJson === "function") {
+    native.TypedProvider.prototype.streamJson = function streamJson(...args) {
+      try {
+        return rawStreamJson.call(this, ...args);
+      } catch (error) {
+        throw toSandhiError(error);
+      }
+    };
+  }
+  native.TypedProvider.prototype.__sandhiTypedErrors = true;
+}
+
+module.exports.wireContractVersion = native.wireContractVersion;
+module.exports.chatContractVersion = native.chatContractVersion;
+module.exports.parseUsage = native.parseUsage;
+module.exports.providerDescriptorJson = native.providerDescriptorJson;
+module.exports.providerSpecJson = native.providerSpecJson;
+module.exports.chatContractSchemaJson = native.chatContractSchemaJson;
+module.exports.providerModelsJson = native.providerModelsJson;
+module.exports.SandhiProviderError = SandhiProviderError;
+module.exports.Gateway = native.Gateway;
+module.exports.ProviderRuntime = native.ProviderRuntime;
+module.exports.TypedProvider = native.TypedProvider;
+module.exports.TypedEventStream = native.TypedEventStream;