@spendguard/sdk 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,190 @@
+# `@spendguard/sdk` Changelog
+
+All notable changes to the TypeScript half of the SpendGuard SDK.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+The Python SDK ([spendguard-sdk on PyPI](https://pypi.org/project/spendguard-sdk/),
+currently v0.5.1) and this TypeScript SDK are kept in lockstep on the public
+surface — see
+[`docs/specs/coverage/D05_ts_sdk_substrate/design.md`](../../docs/specs/coverage/D05_ts_sdk_substrate/design.md)
+§9 for the lockstep contract.
+
+---
+
+## [0.5.0] — 2026-06-19
+
+First public npm release of `@spendguard/sdk`. Version chosen to track the
+Python SDK line (PyPI at 0.6.0) rather than continue the internal 0.1.x
+sequence; no 0.2–0.4 npm releases exist.
+
+### Added
+
+- `UnitRef.unitId` — optional canonical-truth UUID of the ledger unit row.
+  Adapters that issue ledger-backed reserve calls now thread this through to
+  `BudgetClaim.unit.unit_id` on the wire. Closes the HARDEN_D05_UR substrate
+  gap that previously blocked DENY+STREAM full assertion across ~14 adapter
+  demos. Backward-compat: omitting `unitId` matches prior behavior.
+
+---
+
+## [0.1.0] — 2026-06-07
+
+First public release. Mirrors `spendguard-sdk` (Python) v0.5.1 public surface.
+Closes deliverable D05 (TypeScript SDK substrate).
+
+### Added
+
+#### Client (SLICE 3-5)
+
+- `SpendGuardClient` — gRPC-over-UDS client for the SpendGuard sidecar.
+  - `handshake()` — protocol-version + capabilities negotiation.
+  - `reserve()` — pre-flight budget decision (the canonical method name).
+  - `requestDecision()` — `reserve()` alias for migration ergonomics; `===`
+    identity is asserted as a P0 surface invariant
+    (review-standards §1.5).
+  - `commitEstimated()` — observed-output commit (cost rounded up).
+  - `release()` — terminal reservation release with explicit
+    `releaseReason`.
+  - `queryBudget()` — wire stub (throws "not yet wired" until cross-component
+    slice; documented in JSDoc per review-standards §11.3).
+- `SpendGuardClientOptions`, `HandshakeOutcome`, `DecisionOutcome`,
+  `ReleaseOutcome` types.
+- Default deadlines: `DEFAULT_DECISION_TIMEOUT_MS`,
+  `DEFAULT_HANDSHAKE_TIMEOUT_MS`, `DEFAULT_PUBLISH_TIMEOUT_MS`,
+  `DEFAULT_TRACE_TIMEOUT_MS`.
+- `unix:` URI handling matches Python (sets
+  `grpc.default_authority: "localhost"` so `tonic` does not 400 with
+  `PROTOCOL_ERROR` on the URL-encoded path).
+
+#### IDs (SLICE 6)
+
+- `newUuid7()` — UUIDv7 generator (sortable, embedded ms timestamp).
+- `deriveIdempotencyKey()` — deterministic `sg-…` key. **P0 cross-language
+  byte-equivalent with Python `spendguard.derive_idempotency_key()` and the
+  Rust sidecar's `audit_chain::derive_key`** (sidecar-side dedup correctness).
+- `deriveUuidFromSignature()` — BLAKE2b-based UUID derivation from an
+  application signature + scope. **Byte-equivalent with Python.** Uses
+  `@noble/hashes` BLAKE2b implementation.
+- `defaultCallSignature()` — framework-agnostic signature helper.
+- `workloadInstanceId()` — process-stable identifier.
+
+#### Pricing (SLICE 6)
+
+- `PricingLookup` — typed lookup with provider+model+kind keys.
+- `USD_MICROS_PER_USD` — wire-unit conversion constant.
+- `DEMO_PRICING` — embedded pricing snapshot for the demo seed
+  (`pricing_version: v2026.05.09-1`, regenerated at release time from
+  `deploy/demo/init/pricing/seed.yaml`).
+
+#### Prompt hash (SLICE 6)
+
+- `computePromptHash()` — HMAC-SHA256 lowercase hex. **P0 cross-language
+  byte-equivalent with Python `spendguard.compute_prompt_hash()` and the
+  sidecar `prompt_hash::compute`**. Tenant ID is canonicalised to lowercase
+  before hashing — the `crossLanguage` test suite pins this.
+
+#### Run plan / Signal 3 (SLICE 7)
+
+- `withRunPlan()` + `currentRunPlan()` — `AsyncLocalStorage`-scoped
+  budget-hint context. Adapters set the plan once at run boundary; nested
+  `reserve()` calls read it transparently.
+
+#### OTel (SLICE 8)
+
+- `otelTracer` config field — optional `@opentelemetry/api` `Tracer`.
+- Per-RPC spans named `spendguard.<rpc>` with attributes documented in
+  `design.md` §6.4 + `SPENDGUARD_OTEL_ATTR` constant export.
+- `@opentelemetry/api` is a peer dep, marked optional in
+  `peerDependenciesMeta`.
+
+#### Retry (SLICE 8)
+
+- Bounded retry for the `UNAVAILABLE` / `DEADLINE_EXCEEDED` / `CANCELLED`
+  cluster. Max 2 attempts, constant 25 ms + jitter backoff. Idempotency-key
+  required (the substrate enforces).
+
+#### Idempotency cache (SLICE 8)
+
+- In-process LRU keyed by `(tenantId, idempotencyKey)` so re-attempts after
+  retry observation surface the cached decision rather than re-RPC'ing.
+
+#### Cross-language fixtures (SLICE 9)
+
+- `sdk/fixtures/cross-language/v1.json` — the SINGLE SOURCE OF TRUTH for
+  byte-equivalence between the Rust sidecar, Python SDK, and TS SDK. v1.json
+  ships with ≥20 fixtures spanning `compute_prompt_hash`,
+  `derive_idempotency_key`, and `derive_uuid_from_signature` (see
+  `sdk/fixtures/cross-language/README.md` for the add-a-fixture / mint-v2
+  runbook).
+- The fixture file is **included in the published npm tarball** under
+  `fixtures/cross-language/v1.json` so consumer-side conformance suites can
+  pin against the exact same vectors.
+
+#### Errors
+
+- `SpendGuardError`, `HandshakeError`, `SidecarUnavailable`,
+  `DecisionDenied`, `DecisionStopped`, `DecisionSkipped`, `ApprovalRequired`,
+  `ApprovalDeniedError`, `ApprovalLapsedError`,
+  `ApprovalBundleHotReloadedError`, `MutationApplyFailed`,
+  `SpendGuardConfigError` — full hierarchy mirror of the Python SDK.
+
+### Locked invariants
+
+- **P0 cross-language byte-equivalence** with the Python SDK (and the Rust
+  sidecar) on `computePromptHash`, `deriveIdempotencyKey`, and
+  `deriveUuidFromSignature`. Drift breaks audit-chain dedup and the
+  idempotency replay collapse contract. Enforced by the
+  `tests/crossLanguage.test.ts` suite consuming
+  `sdk/fixtures/cross-language/v1.json` (also consumed by
+  `sdk/python/tests/test_cross_language_fixtures.py`).
+- **`reserve()` === `requestDecision()` reference identity** (P0 surface
+  invariant, `tests/locked-surface.test.ts`).
+- **ESM-only.** No CJS shim. `"type": "module"`.
+- **camelCase on the public surface, snake_case on the wire** — every wire
+  conversion is centralised in `src/client.ts` so adapter authors never see
+  snake_case.
+
+### Compatibility
+
+- Node 20.10+ (uses `using` / `await using`, stable `AsyncLocalStorage`,
+  Web Crypto).
+- Bun 1.1+ tested as secondary target.
+- Deno 1.46+ tested as secondary target.
+- **Browser is NOT supported in v0.1.x.** UDS gRPC is server-only. A future
+  v0.x ASP HTTP gateway transport is forward-reserved in the config type but
+  not built.
+
+### Known limitations (deferred to future slices)
+
+- `queryBudget()` wire body — stub-throws "not yet wired". Cross-component
+  slice unblocks.
+- LLM_CALL_OUTCOME proto bump — deferred to a cross-component slice that
+  spans D05 + Rust sidecar + Python SDK simultaneously.
+- Per-framework `defaultCallSignature()` defaults for LangChain / Vercel AI
+  / OpenAI Agents / Inngest — each adapter package (D04 / D06 / D08 / D29)
+  provides its own message-type-specific signature.
+- Identity-propagation `RunContext` (parentRunId / traceparent threading) —
+  deferred per SLICE 7 R2. Use the explicit `ReserveRequest` fields for now.
+
+### Verification
+
+- 366 tests pass under vitest 2.x (Node 20).
+- `npm pack` tarball ≤ 250 KB (`scripts/size-budget.sh`).
+- Minified `dist/index.js` ≤ 120 KB (design.md §10 budget).
+- `package.json#version` == `src/version.ts#VERSION` (`scripts/version-check.sh`).
+- All P0 byte-equivalence fixtures match the Python SDK.
+
+---
+
+## Future versions
+
+The lockstep contract with `spendguard-sdk` (Python) v0.5.1 means the next
+minor (v0.2.x) will track whatever Python's next minor mints. Any change to
+the v0.1.0 public surface listed under "Added" requires a coordinated
+v0.minor bump on both packages — see
+[`docs/specs/coverage/D05_ts_sdk_substrate/design.md`](../../docs/specs/coverage/D05_ts_sdk_substrate/design.md)
+§§4 / 9 for the contract.
+
+[0.1.0]: https://github.com/m24927605/agentic-spendguard/releases/tag/ts-sdk-v0.1.0

package/LICENSE_NOTICES.md

@@ -0,0 +1,127 @@
+# `@spendguard/sdk` — Third-Party License Notices
+
+This package (`@spendguard/sdk`) is itself licensed under Apache License 2.0
+— see the repository root `LICENSE` file
+(<https://github.com/m24927605/agentic-spendguard/blob/main/LICENSE>) for the
+full Apache-2.0 text.
+
+This document satisfies review-standards §11.6 by listing every direct
+runtime dependency and its license. Transitive deps that flow in via these
+direct deps follow their own license; this notice is required only for the
+direct edges below.
+
+---
+
+## Runtime dependencies (shipped to consumers)
+
+These are the packages declared under `"dependencies"` in `package.json`
+that ship inside the consumer's `node_modules/@spendguard/sdk` tree and
+that the published `dist/*.js` imports at runtime.
+
+### `@grpc/grpc-js`
+
+- License: **Apache License 2.0**
+- Project: <https://github.com/grpc/grpc-node/tree/master/packages/grpc-js>
+- Use: Node-native gRPC client transport for the UDS sidecar connection
+  (`SpendGuardClient.handshake() / reserve() / commitEstimated() / release()`).
+- Full Apache-2.0 text:
+  <https://github.com/grpc/grpc-node/blob/master/LICENSE>
+
+### `@noble/hashes`
+
+- License: **MIT**
+- Project: <https://github.com/paulmillr/noble-hashes>
+- Use: BLAKE2b primitive backing `deriveUuidFromSignature()` (P0
+  byte-equivalent with the Python SDK and Rust sidecar). The package is also
+  used via Node's `node:crypto` HMAC-SHA256 for `computePromptHash()` — the
+  `@noble/hashes` dependency is BLAKE2b-only.
+- Full MIT text:
+  <https://github.com/paulmillr/noble-hashes/blob/main/LICENSE>
+
+  > Copyright (c) 2022 Paul Miller (https://paulmillr.com)
+  >
+  > Permission is hereby granted, free of charge, to any person obtaining
+  > a copy of this software and associated documentation files (the
+  > "Software"), to deal in the Software without restriction, including
+  > without limitation the rights to use, copy, modify, merge, publish,
+  > distribute, sublicense, and/or sell copies of the Software, and to
+  > permit persons to whom the Software is furnished to do so, subject to
+  > the following conditions:
+  >
+  > The above copyright notice and this permission notice shall be included
+  > in all copies or substantial portions of the Software.
+  >
+  > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+  > OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+  > MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+  > IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+  > CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+  > TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+  > SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+### `@protobuf-ts/runtime`
+
+- License: **Apache License 2.0**
+- Project: <https://github.com/timostamm/protobuf-ts>
+- Use: Generated `src/_proto/**/*.ts` modules import this runtime for
+  message encode/decode.
+
+### `@protobuf-ts/runtime-rpc`
+
+- License: **Apache License 2.0**
+- Project: <https://github.com/timostamm/protobuf-ts>
+- Use: gRPC service-client surface that `_proto/spendguard/sidecar_adapter/v1/adapter.client.ts`
+  builds against.
+
+### `@protobuf-ts/grpc-transport`
+
+- License: **Apache License 2.0**
+- Project: <https://github.com/timostamm/protobuf-ts>
+- Use: Adapter from the generated `runtime-rpc` clients to `@grpc/grpc-js`
+  channels (the UDS transport).
+
+---
+
+## Optional peer dependencies
+
+### `@opentelemetry/api`
+
+- License: **Apache License 2.0**
+- Project: <https://github.com/open-telemetry/opentelemetry-js-api>
+- Use: Optional. Consumers that supply an `otelTracer` config field get
+  per-RPC spans (design.md §6.4). Not shipped inside `@spendguard/sdk`'s
+  tree because it is declared under `"peerDependencies"`; consumers install
+  the version they want.
+
+---
+
+## Build/Dev-only dependencies
+
+Dev-only dependencies (`tsup`, `vitest`, `typescript`, `@biomejs/biome`,
+`@protobuf-ts/plugin`, `tsx`, `@types/node`) are NOT shipped to consumers
+— they live under `"devDependencies"` and are stripped from the published
+tarball. They do not require notice attribution because they do not appear
+in the consumer's runtime tree.
+
+---
+
+## Generated proto sources
+
+`src/_proto/spendguard/**` is generated from `proto/spendguard/**` at
+build time via the `@protobuf-ts/plugin` codegen. The `.proto` source files
+in this repository are Apache-2.0 licensed under the repo root `LICENSE`.
+
+The generated TypeScript files inherit the original proto's license
+(Apache-2.0); they are not third-party code and do not need separate notice
+beyond the repo root `LICENSE`.
+
+---
+
+## Apache-2.0 compliance summary
+
+Per Apache-2.0 §4(c), this `LICENSE_NOTICES.md` file is the NOTICE document
+for redistribution. Consumers that re-distribute `@spendguard/sdk` in
+binary form (e.g. as part of a larger Node application's deploy artifact)
+should preserve this file. Consumers that depend on `@spendguard/sdk` via
+npm and ship it as-installed are already compliant — npm's install tree
+preserves this file under `node_modules/@spendguard/sdk/LICENSE_NOTICES.md`.

package/README.md

@@ -0,0 +1,151 @@
+# `@spendguard/sdk`
+
+[![npm](https://img.shields.io/npm/v/@spendguard/sdk.svg)](https://www.npmjs.com/package/@spendguard/sdk)
+[![license](https://img.shields.io/npm/l/@spendguard/sdk.svg)](https://github.com/m24927605/agentic-spendguard/blob/main/LICENSE)
+[![publish](https://github.com/m24927605/agentic-spendguard/actions/workflows/sdk-ts-publish.yml/badge.svg)](https://github.com/m24927605/agentic-spendguard/actions/workflows/sdk-ts-publish.yml)
+
+> Runtime safety-layer client for AI-agent frameworks (TypeScript).
+> Mirror of [`spendguard-sdk`](https://pypi.org/project/spendguard-sdk/) (Python).
+
+`@spendguard/sdk` is the shared substrate that per-framework adapters
+(`@spendguard/langchain`, `@spendguard/vercel-ai`, `@spendguard/openai-agents`,
+`@spendguard/inngest-agentkit`) build against. It implements the gRPC-over-UDS
+client for the SpendGuard sidecar, plus the deterministic helpers that produce
+**byte-identical** output to the Python SDK and the Rust sidecar — the
+audit-chain invariants that make idempotency replay and dedup correct
+across languages.
+
+## Install
+
+```bash
+pnpm add @spendguard/sdk @opentelemetry/api
+# or
+npm install @spendguard/sdk @opentelemetry/api
+# or
+bun add @spendguard/sdk @opentelemetry/api
+```
+
+`@opentelemetry/api` is an **optional** peer dep — install it only if you
+plan to pass an `otelTracer`. Adapters that never enable OTel pay zero
+extra dependency cost.
+
+## Quick start
+
+```ts
+// reserve -> commitEstimated -> release  (the v0.1.0 happy path)
+import {
+  SpendGuardClient,
+  deriveIdempotencyKey,
+  newUuid7,
+  USD_MICROS_PER_USD,
+} from "@spendguard/sdk";
+
+const client = new SpendGuardClient({
+  tenantId: "acme-prod",
+  socketPath: "/run/spendguard/sidecar.sock",
+  handshake: { protocolVersion: 1, capabilities: {} },
+});
+
+await client.handshake();
+
+const decision = await client.reserve({
+  trigger: "LLM_CALL_PRE",
+  runId: newUuid7(),
+  stepId: newUuid7(),
+  llmCallId: newUuid7(),
+  decisionId: newUuid7(),
+  route: "openai:gpt-4o-mini",
+  projectedClaims: [
+    { scopeId: "team:eng", amountAtomic: "150000", unit: { unit: "usd_micros", denomination: 1 } },
+  ],
+  idempotencyKey: deriveIdempotencyKey({
+    tenantId: "acme-prod",
+    sessionId: "sess-1",
+    runId: "run-1",
+    stepId: "step-1",
+    llmCallId: "call-1",
+    trigger: "LLM_CALL_PRE",
+  }),
+});
+
+if (decision.decision === "CONTINUE") {
+  // ...call the provider (OpenAI, Anthropic, etc.) here...
+  await client.commitEstimated({
+    runId: "run-1", stepId: "step-1", llmCallId: "call-1",
+    decisionId: decision.decisionId,
+    reservationId: decision.reservationIds[0]!,
+    estimatedAmountAtomic: String(123 * USD_MICROS_PER_USD / 1_000_000),
+    unit: { unit: "usd_micros", denomination: 1 },
+    pricing: { pricingVersion: "v2026.05.09-1", pricingHash: new Uint8Array() },
+    providerEventId: "openai:chatcmpl-abc",
+    outcome: "SUCCESS",
+  });
+  await client.release({
+    runId: "run-1", stepId: "step-1", llmCallId: "call-1",
+    decisionId: decision.decisionId,
+    reservationId: decision.reservationIds[0]!,
+    releaseReason: "COMPLETED",
+  });
+}
+```
+
+The substrate also exposes `requestDecision()` as a referential alias for
+`reserve()` (`client.reserve === client.requestDecision`) so call-sites
+written against the Python SDK transliterate without semantic surprise.
+
+## Subpath exports
+
+Tree-shake what you need:
+
+| Subpath | Contents |
+|---|---|
+| `@spendguard/sdk` | Full barrel (everything below). |
+| `@spendguard/sdk/client` | `SpendGuardClient` + request/response types. |
+| `@spendguard/sdk/errors` | Typed error hierarchy. |
+| `@spendguard/sdk/ids` | `newUuid7`, `deriveIdempotencyKey`, `deriveUuidFromSignature`. |
+| `@spendguard/sdk/pricing` | `PricingLookup`, `USD_MICROS_PER_USD`. |
+| `@spendguard/sdk/pricing/demo` | Embedded `DEMO_PRICING` snapshot. |
+| `@spendguard/sdk/promptHash` | `computePromptHash`. |
+| `@spendguard/sdk/runPlan` | `withRunPlan`, `currentRunPlan` (AsyncLocalStorage). |
+| `@spendguard/sdk/otel` | Optional OTel span wrapper. |
+| `@spendguard/sdk/retry` | Bounded retry helper. |
+| `@spendguard/sdk/cache` | In-memory idempotency cache. |
+| `@spendguard/sdk/proto` | Generated proto types. |
+
+## Cross-language byte-equivalence (P0)
+
+Three functions in this SDK MUST produce byte-identical output to the
+Python SDK and the Rust sidecar:
+
+- `computePromptHash(text, tenantId)` — HMAC-SHA256 lowercase hex.
+- `deriveIdempotencyKey({ ... })` — `sg-` + 32 hex chars.
+- `deriveUuidFromSignature(sig, { scope })` — BLAKE2b-based UUID.
+
+Drift breaks audit-chain rule dedup and the idempotency-replay collapse
+contract. The corpus that pins this is shipped inside the npm tarball at
+`fixtures/cross-language/v1.json` — both this SDK and the Python SDK consume
+the same file. See `sdk/fixtures/cross-language/README.md` in the source repo
+for the runbook.
+
+## Compatibility
+
+- **Node 20.10+** is the primary target.
+- **Bun 1.1+** and **Deno 1.46+** are tested as secondary targets.
+- Browser is **NOT supported in v0.1.x** — UDS transport is server-only.
+
+## Links
+
+- [Full design spec](https://github.com/m24927605/agentic-spendguard/blob/main/docs/specs/coverage/D05_ts_sdk_substrate/design.md)
+  — public surface (§4), architecture (§6), locked decisions (§9), bundle-size budget (§10).
+- [Implementation spec](https://github.com/m24927605/agentic-spendguard/blob/main/docs/specs/coverage/D05_ts_sdk_substrate/implementation.md)
+  — repo layout + codegen pipeline.
+- [Review standards](https://github.com/m24927605/agentic-spendguard/blob/main/docs/specs/coverage/D05_ts_sdk_substrate/review-standards.md)
+  — P0/P1/P2 review gates applied to every D05 slice.
+- [Python SDK on PyPI](https://pypi.org/project/spendguard-sdk/) — the
+  lockstep counterpart.
+- [CHANGELOG.md](./CHANGELOG.md) — release history.
+- [LICENSE_NOTICES.md](./LICENSE_NOTICES.md) — third-party license attribution.
+
+## License
+
+Apache-2.0. See `LICENSE` in the repository root.