@primeradianthq/obol 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# obol — TypeScript binding (Bun + Node)
+
+A thin TypeScript binding over obol's C ABI (`obol-ffi`). It runs under **both Bun and Node**:
+Bun uses the built-in `bun:ffi` (zero runtime deps), Node uses [`koffi`](https://koffi.dev). The
+Rust core does all the accounting; this binding only `dlopen`s the cdylib and re-types the JSON.
+
+## Install
+
+```sh
+npm install @primeradianthq/obol     # or: bun add @primeradianthq/obol
+```
+
+The published package **bundles the native library** for macOS (arm64 / x64) and Linux
+(x64 / arm64) — no `cargo build` needed for consumers, no postinstall, no network at install.
+Requires **Node 18+** (or Bun). Other platforms (Windows, musl/Alpine) aren't bundled yet and
+will get a clear "library not found" error.
+
+### From source (contributors)
+
+Running the binding straight from this repo (not the published package) needs the cdylib built:
+
+```sh
+cargo build -p obol-ffi    # produces target/{debug,release}/libobol_ffi.{dylib,so}
+```
+
+The library is resolved in order: `$OBOL_LIB` (explicit path) → the package's bundled
+`native/<platform>-<arch>/` (published installs) → `target/{release,debug}` (in-repo dev).
+
+## Usage
+
+```ts
+import { estimatePath, estimateBytes, refresh, version, ObolError } from "obol";
+
+const est = await estimatePath("session.jsonl", "claude"); // dialect optional → auto-detect
+console.log(est.total_usd, est.pricing_as_of);
+
+try {
+  await estimateBytes(new Uint8Array(/* … */));
+} catch (e) {
+  if (e instanceof ObolError) console.error(e.code, e.kind, e.message);
+}
+```
+
+The API is async because the FFI backend is loaded lazily (and cached) on first use.
+
+Pricing tables must exist before estimating — run `obol refresh` (the CLI) or point
+`OBOL_PRICING_DIR` at a directory containing a `current.json` snapshot.
+
+## Ownership
+
+You never touch raw pointers. Each call copies obol's returned string into a JS string and then
+frees the obol-owned pointer (via `obol_string_free`) inside the adapter — the single place that
+can get it right.
+
+## Bun environment caveat
+
+obol's Rust core reads `OBOL_PRICING_DIR` / `OBOL_LIB` from the OS environment via `getenv`, which
+is resolved per call. **Under Bun, mutating `process.env` at runtime does not reach the native
+library** — set these variables in the environment *before launching* the process (the normal
+way). Node propagates `process.env` to `getenv`, so runtime mutation works there; Bun does not.
+(The test suite works around this by calling libc `setenv` directly under Bun — see
+`test/pricing-env.ts`.)

package/dist/ffi-bun-C6QZKITS.js

@@ -0,0 +1,42 @@
+// src/ffi-bun.ts
+import { dlopen, FFIType, ptr, CString } from "bun:ffi";
+function createBackend(libPath) {
+  const { symbols } = dlopen(libPath, {
+    obol_version: { args: [], returns: FFIType.ptr },
+    obol_string_free: { args: [FFIType.ptr], returns: FFIType.void },
+    obol_estimate_path: { args: [FFIType.cstring, FFIType.cstring, FFIType.ptr], returns: FFIType.i32 },
+    obol_estimate_bytes: { args: [FFIType.ptr, FFIType.u64, FFIType.cstring, FFIType.ptr], returns: FFIType.i32 },
+    obol_refresh_pricing: { args: [FFIType.cstring, FFIType.ptr], returns: FFIType.i32 }
+  });
+  const cstr = (s) => s === null ? null : Buffer.from(s + "\0");
+  const nonEmpty = (data) => data.length === 0 ? new Uint8Array(1) : data;
+  const drain = (code, out) => {
+    const p = out[0];
+    if (p === 0n) return { code, json: null };
+    const json = new CString(Number(p)).toString();
+    symbols.obol_string_free(Number(p));
+    return { code, json };
+  };
+  return {
+    version: () => new CString(symbols.obol_version()).toString(),
+    // static; never freed
+    estimatePath(path, dialect) {
+      const out = new BigUint64Array(1);
+      const code = symbols.obol_estimate_path(cstr(path), cstr(dialect), ptr(out));
+      return drain(code, out);
+    },
+    estimateBytes(data, dialect) {
+      const out = new BigUint64Array(1);
+      const code = symbols.obol_estimate_bytes(ptr(nonEmpty(data)), BigInt(data.length), cstr(dialect), ptr(out));
+      return drain(code, out);
+    },
+    refresh(asOf) {
+      const out = new BigUint64Array(1);
+      const code = symbols.obol_refresh_pricing(cstr(asOf), ptr(out));
+      return drain(code, out);
+    }
+  };
+}
+export {
+  createBackend
+};

package/dist/ffi-node-27DIUBG7.js

@@ -0,0 +1,44 @@
+// src/ffi-node.ts
+import koffi from "koffi";
+function createBackend(libPath) {
+  const lib = koffi.load(libPath);
+  const obol_version = lib.func("const char* obol_version()");
+  const obol_string_free = lib.func("void obol_string_free(void* s)");
+  const obol_estimate_path = lib.func(
+    "int obol_estimate_path(const char* path, const char* dialect, _Out_ void** out)"
+  );
+  const obol_estimate_bytes = lib.func(
+    "int obol_estimate_bytes(const uint8_t* data, size_t len, const char* dialect, _Out_ void** out)"
+  );
+  const obol_refresh = lib.func("int obol_refresh_pricing(const char* as_of, _Out_ void** out)");
+  const nonEmpty = (data) => data.length === 0 ? Buffer.alloc(1) : data;
+  const drain = (code, out) => {
+    const p = out[0];
+    if (p === null || p === void 0) return { code, json: null };
+    const json = koffi.decode(p, "char", -1);
+    obol_string_free(p);
+    return { code, json };
+  };
+  return {
+    version: () => obol_version(),
+    // koffi marshals const char* return to a JS string
+    estimatePath(path, dialect) {
+      const out = [null];
+      const code = obol_estimate_path(path, dialect, out);
+      return drain(code, out);
+    },
+    estimateBytes(data, dialect) {
+      const out = [null];
+      const code = obol_estimate_bytes(nonEmpty(data), data.length, dialect, out);
+      return drain(code, out);
+    },
+    refresh(asOf) {
+      const out = [null];
+      const code = obol_refresh(asOf, out);
+      return drain(code, out);
+    }
+  };
+}
+export {
+  createBackend
+};

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+interface TokenBuckets {
+    input: number;
+    output: number;
+    cache_read: number;
+    cache_write: number;
+}
+interface ModelCost {
+    model: string;
+    provider: string;
+    tokens: TokenBuckets;
+    subtotal_usd: number;
+}
+interface Approximation {
+    kind: string;
+    detail?: string;
+}
+interface CostEstimate {
+    total_usd: number;
+    per_model: ModelCost[];
+    tokens: TokenBuckets;
+    unpriced_models: string[];
+    approximations: Approximation[];
+    pricing_as_of: string;
+}
+interface RefreshReport {
+    models: number;
+    as_of: string;
+    written_to: string;
+}
+type Dialect = "claude" | "codex" | "pi";
+declare class ObolError extends Error {
+    code: number;
+    kind: string;
+    constructor(code: number, kind: string, message: string);
+}
+
+declare function version(): Promise<string>;
+declare function estimatePath(path: string, dialect?: Dialect | null): Promise<CostEstimate>;
+declare function estimateBytes(data: Uint8Array, dialect?: Dialect | null): Promise<CostEstimate>;
+declare function refresh(asOf: string): Promise<RefreshReport>;
+
+export { type Approximation, type CostEstimate, type Dialect, type ModelCost, ObolError, type RefreshReport, type TokenBuckets, estimateBytes, estimatePath, refresh, version };

package/dist/index.js

@@ -0,0 +1,101 @@
+// src/lib-path.ts
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+function libFilename() {
+  switch (process.platform) {
+    case "darwin":
+      return "libobol_ffi.dylib";
+    case "win32":
+      return "obol_ffi.dll";
+    default:
+      return "libobol_ffi.so";
+  }
+}
+function resolveLibPath() {
+  const tried = [];
+  const env = process.env.OBOL_LIB;
+  if (env) {
+    tried.push(env);
+    if (existsSync(env)) return env;
+  }
+  const name = libFilename();
+  const here = dirname(fileURLToPath(import.meta.url));
+  const bundled = join(here, "..", "native", `${process.platform}-${process.arch}`, name);
+  tried.push(bundled);
+  if (existsSync(bundled)) return bundled;
+  const repo = join(here, "..", "..", "..");
+  for (const profile of ["release", "debug"]) {
+    const p = join(repo, "target", profile, name);
+    tried.push(p);
+    if (existsSync(p)) return p;
+  }
+  throw new Error(
+    "obol_ffi shared library not found. Set OBOL_LIB or install a platform with a bundled lib. Tried:\n  " + tried.join("\n  ")
+  );
+}
+
+// src/ffi.ts
+var cached;
+function backend() {
+  return cached ??= load();
+}
+async function load() {
+  const isBun = typeof globalThis.Bun !== "undefined";
+  const libPath = resolveLibPath();
+  const mod = isBun ? await import("./ffi-bun-C6QZKITS.js") : await import("./ffi-node-27DIUBG7.js");
+  return mod.createBackend(libPath);
+}
+
+// src/types.ts
+var ObolError = class extends Error {
+  code;
+  kind;
+  constructor(code, kind, message) {
+    super(`obol: ${kind} (code ${code}): ${message}`);
+    this.name = "ObolError";
+    this.code = code;
+    this.kind = kind;
+  }
+};
+
+// src/index.ts
+function unwrap(r) {
+  if (r.code !== 0) {
+    let kind = "Unknown";
+    let message = "no detail";
+    let code = r.code;
+    if (r.json) {
+      try {
+        const e = JSON.parse(r.json).error;
+        if (e) {
+          kind = e.kind ?? kind;
+          message = e.message ?? message;
+          code = e.code ?? code;
+        }
+      } catch {
+      }
+    }
+    throw new ObolError(code, kind, message);
+  }
+  return JSON.parse(r.json);
+}
+async function version() {
+  return (await backend()).version();
+}
+async function estimatePath(path, dialect = null) {
+  return unwrap((await backend()).estimatePath(path, dialect));
+}
+async function estimateBytes(data, dialect = null) {
+  return unwrap((await backend()).estimateBytes(data, dialect));
+}
+async function refresh(asOf) {
+  return unwrap((await backend()).refresh(asOf));
+}
+export {
+  ObolError,
+  estimateBytes,
+  estimatePath,
+  refresh,
+  version
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@primeradianthq/obol",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "description": "Agent-transcript cost estimation — TypeScript binding over the obol C ABI (Bun + Node).",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "native",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "koffi": "2.16.2"
+  },
+  "devDependencies": {
+    "tsup": "^8.5",
+    "typescript": "^5.9"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prime-radiant-inc/obol.git",
+    "directory": "bindings/typescript"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}