runcycles 0.1.2 → 0.2.0

package/README.md

@@ -1,3 +1,7 @@
+[![npm](https://img.shields.io/npm/v/runcycles)](https://www.npmjs.com/package/runcycles)
+[![CI](https://github.com/runcycles/cycles-client-typescript/actions/workflows/ci.yml/badge.svg)](https://github.com/runcycles/cycles-client-typescript/actions)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+
 # Cycles TypeScript Client
 
 TypeScript client for the [Cycles](https://runcycles.io) budget-management protocol — govern spend on AI calls, API usage, and any metered resource.
@@ -69,6 +73,24 @@ const result = await callLlm("Hello", 100);
 
 **What happens:** `withCycles` reserves budget before calling your function, runs it inside an async context (so `getCyclesContext()` works), commits the actual cost on success, or releases the reservation on failure. A background heartbeat keeps the reservation alive.
 
+### Budget lifecycle
+
+| Scenario | Outcome | Detail |
+|---|---|---|
+| Reservation denied | **Neither** | `BudgetExceededError`, `OverdraftLimitExceededError`, or `DebtOutstandingError` thrown; function never executes |
+| `dryRun: true`, any decision | **Neither** | Returns `DryRunResult` or throws; no real reservation created |
+| Function returns successfully | **Commit** | Actual amount charged; unused remainder auto-released |
+| Function throws any error | **Release** | Full reserved amount returned to budget; error re-thrown |
+| Commit fails (5xx / network) | **Retry** | Exponential backoff with configurable attempts |
+| Commit fails (non-retryable 4xx) | **Release** | Reservation released after non-retryable client error |
+| Commit gets RESERVATION_EXPIRED | **Neither** | Server already reclaimed budget on TTL expiry |
+| Commit gets RESERVATION_FINALIZED | **Neither** | Already committed or released (idempotent replay) |
+| Commit gets IDEMPOTENCY_MISMATCH | **Neither** | Previous commit already processed; no release attempted |
+
+**Streaming (`reserveForStream`):** Call `handle.commit(actual)` on success or `handle.release(reason)` on failure. If neither is called, the server reclaims the budget when the reservation TTL expires.
+
+All thrown errors from the guarded function trigger release. See [How Reserve-Commit Works](https://runcycles.io/protocol/how-reserve-commit-works-in-cycles) for the full protocol-level explanation.
+
 ### 2. Streaming adapter
 
 For LLM streaming where usage is only known after the stream finishes:
@@ -303,7 +325,7 @@ interface WithCyclesConfig {
   // Reservation settings
   ttlMs?: number;          // Time-to-live in ms (default: 60000, range: 1000–86400000)
   gracePeriodMs?: number;  // Grace period in ms (range: 0–60000)
-  overagePolicy?: string;  // "REJECT" (default), "ALLOW_IF_AVAILABLE", "ALLOW_WITH_OVERDRAFT"
+  overagePolicy?: string;  // "ALLOW_IF_AVAILABLE" (default), "REJECT", "ALLOW_WITH_OVERDRAFT"
   dryRun?: boolean;        // Shadow mode — evaluates budget without executing
 
   // Subject fields (override config defaults)
@@ -795,6 +817,29 @@ ErrorCode.INTERNAL_ERROR
 ErrorCode.UNKNOWN
 ```
 
+## Nested `withCycles` Calls
+
+Calling a `withCycles`-wrapped function from inside another `withCycles`-wrapped function is allowed — it will not throw an error. However, each wrapper creates an **independent reservation** that deducts budget separately:
+
+```typescript
+const inner = withCycles({ estimate: 100, actionName: "inner" }, async () => "done");
+const outer = withCycles({ estimate: 500, actionName: "outer" }, async () => {
+  return await inner(); // creates a SECOND reservation — 600 total deducted, not 500
+});
+```
+
+This means nested guards **double-count budget**. The outer reservation already covers the full estimated cost of the operation, so an inner reservation deducts additional budget from the same pool.
+
+**Recommended pattern:** Place `withCycles` at the outermost entry point only. Inner functions should be plain async functions without their own guard:
+
+```typescript
+const inner = async () => "done"; // no withCycles — called within a guarded operation
+
+const outer = withCycles({ estimate: 500, actionName: "outer" }, async () => {
+  return await inner(); // single reservation — 500 total
+});
+```
+
 ## Examples
 
 See the [`examples/`](./examples/) directory:
@@ -824,6 +869,13 @@ See the [`examples/`](./examples/) directory:
 - **Dual ESM/CJS**: Works with both module systems
 - **Input validation**: Client-side validation of TTL, amounts, subject fields, and more
 
+## Documentation
+
+- [Cycles Documentation](https://runcycles.io) — full docs site
+- [TypeScript Quickstart](https://runcycles.io/quickstart/getting-started-with-the-typescript-client) — getting started guide
+- [TypeScript Client Configuration Reference](https://runcycles.io/configuration/typescript-client-configuration-reference) — all configuration options
+- [Error Handling Patterns in TypeScript](https://runcycles.io/how-to/error-handling-patterns-in-typescript) — handling budget errors
+
 ## License
 
 Apache-2.0

package/dist/index.cjs

@@ -835,12 +835,15 @@ var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
   ErrorCode2["FORBIDDEN"] = "FORBIDDEN";
   ErrorCode2["NOT_FOUND"] = "NOT_FOUND";
   ErrorCode2["BUDGET_EXCEEDED"] = "BUDGET_EXCEEDED";
+  ErrorCode2["BUDGET_FROZEN"] = "BUDGET_FROZEN";
+  ErrorCode2["BUDGET_CLOSED"] = "BUDGET_CLOSED";
   ErrorCode2["RESERVATION_EXPIRED"] = "RESERVATION_EXPIRED";
   ErrorCode2["RESERVATION_FINALIZED"] = "RESERVATION_FINALIZED";
   ErrorCode2["IDEMPOTENCY_MISMATCH"] = "IDEMPOTENCY_MISMATCH";
   ErrorCode2["UNIT_MISMATCH"] = "UNIT_MISMATCH";
   ErrorCode2["OVERDRAFT_LIMIT_EXCEEDED"] = "OVERDRAFT_LIMIT_EXCEEDED";
   ErrorCode2["DEBT_OUTSTANDING"] = "DEBT_OUTSTANDING";
+  ErrorCode2["MAX_EXTENSIONS_EXCEEDED"] = "MAX_EXTENSIONS_EXCEEDED";
   ErrorCode2["INTERNAL_ERROR"] = "INTERNAL_ERROR";
   ErrorCode2["UNKNOWN"] = "UNKNOWN";
   return ErrorCode2;
@@ -962,7 +965,7 @@ function buildReservationBody(cfg, estimate, defaultSubject) {
     action,
     estimate: { unit, amount: estimate },
     ttl_ms: ttlMs,
-    overage_policy: cfg.overagePolicy ?? "REJECT"
+    overage_policy: cfg.overagePolicy ?? "ALLOW_IF_AVAILABLE"
   };
   validateGracePeriodMs(cfg.gracePeriodMs);
   if (cfg.gracePeriodMs !== void 0) {
@@ -1284,7 +1287,7 @@ async function reserveForStream(options) {
     actionTags,
     ttlMs = DEFAULT_TTL_MS,
     gracePeriodMs,
-    overagePolicy = "REJECT",
+    overagePolicy = "ALLOW_IF_AVAILABLE",
     dimensions
   } = options;
   validateNonNegative(estimate, "estimate");

package/dist/index.d.cts

@@ -76,12 +76,15 @@ declare enum ErrorCode {
     FORBIDDEN = "FORBIDDEN",
     NOT_FOUND = "NOT_FOUND",
     BUDGET_EXCEEDED = "BUDGET_EXCEEDED",
+    BUDGET_FROZEN = "BUDGET_FROZEN",
+    BUDGET_CLOSED = "BUDGET_CLOSED",
     RESERVATION_EXPIRED = "RESERVATION_EXPIRED",
     RESERVATION_FINALIZED = "RESERVATION_FINALIZED",
     IDEMPOTENCY_MISMATCH = "IDEMPOTENCY_MISMATCH",
     UNIT_MISMATCH = "UNIT_MISMATCH",
     OVERDRAFT_LIMIT_EXCEEDED = "OVERDRAFT_LIMIT_EXCEEDED",
     DEBT_OUTSTANDING = "DEBT_OUTSTANDING",
+    MAX_EXTENSIONS_EXCEEDED = "MAX_EXTENSIONS_EXCEEDED",
     INTERNAL_ERROR = "INTERNAL_ERROR",
     UNKNOWN = "UNKNOWN"
 }
@@ -213,6 +216,7 @@ interface DecisionResponse {
 interface EventCreateResponse {
     status: EventStatus;
     eventId: string;
+    charged?: Amount;
     balances?: Balance[];
 }
 interface DryRunResult {

package/dist/index.d.ts

@@ -76,12 +76,15 @@ declare enum ErrorCode {
     FORBIDDEN = "FORBIDDEN",
     NOT_FOUND = "NOT_FOUND",
     BUDGET_EXCEEDED = "BUDGET_EXCEEDED",
+    BUDGET_FROZEN = "BUDGET_FROZEN",
+    BUDGET_CLOSED = "BUDGET_CLOSED",
     RESERVATION_EXPIRED = "RESERVATION_EXPIRED",
     RESERVATION_FINALIZED = "RESERVATION_FINALIZED",
     IDEMPOTENCY_MISMATCH = "IDEMPOTENCY_MISMATCH",
     UNIT_MISMATCH = "UNIT_MISMATCH",
     OVERDRAFT_LIMIT_EXCEEDED = "OVERDRAFT_LIMIT_EXCEEDED",
     DEBT_OUTSTANDING = "DEBT_OUTSTANDING",
+    MAX_EXTENSIONS_EXCEEDED = "MAX_EXTENSIONS_EXCEEDED",
     INTERNAL_ERROR = "INTERNAL_ERROR",
     UNKNOWN = "UNKNOWN"
 }
@@ -213,6 +216,7 @@ interface DecisionResponse {
 interface EventCreateResponse {
     status: EventStatus;
     eventId: string;
+    charged?: Amount;
     balances?: Balance[];
 }
 interface DryRunResult {

package/dist/index.js

@@ -760,12 +760,15 @@ var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
   ErrorCode2["FORBIDDEN"] = "FORBIDDEN";
   ErrorCode2["NOT_FOUND"] = "NOT_FOUND";
   ErrorCode2["BUDGET_EXCEEDED"] = "BUDGET_EXCEEDED";
+  ErrorCode2["BUDGET_FROZEN"] = "BUDGET_FROZEN";
+  ErrorCode2["BUDGET_CLOSED"] = "BUDGET_CLOSED";
   ErrorCode2["RESERVATION_EXPIRED"] = "RESERVATION_EXPIRED";
   ErrorCode2["RESERVATION_FINALIZED"] = "RESERVATION_FINALIZED";
   ErrorCode2["IDEMPOTENCY_MISMATCH"] = "IDEMPOTENCY_MISMATCH";
   ErrorCode2["UNIT_MISMATCH"] = "UNIT_MISMATCH";
   ErrorCode2["OVERDRAFT_LIMIT_EXCEEDED"] = "OVERDRAFT_LIMIT_EXCEEDED";
   ErrorCode2["DEBT_OUTSTANDING"] = "DEBT_OUTSTANDING";
+  ErrorCode2["MAX_EXTENSIONS_EXCEEDED"] = "MAX_EXTENSIONS_EXCEEDED";
   ErrorCode2["INTERNAL_ERROR"] = "INTERNAL_ERROR";
   ErrorCode2["UNKNOWN"] = "UNKNOWN";
   return ErrorCode2;
@@ -887,7 +890,7 @@ function buildReservationBody(cfg, estimate, defaultSubject) {
     action,
     estimate: { unit, amount: estimate },
     ttl_ms: ttlMs,
-    overage_policy: cfg.overagePolicy ?? "REJECT"
+    overage_policy: cfg.overagePolicy ?? "ALLOW_IF_AVAILABLE"
   };
   validateGracePeriodMs(cfg.gracePeriodMs);
   if (cfg.gracePeriodMs !== void 0) {
@@ -1209,7 +1212,7 @@ async function reserveForStream(options) {
     actionTags,
     ttlMs = DEFAULT_TTL_MS,
     gracePeriodMs,
-    overagePolicy = "REJECT",
+    overagePolicy = "ALLOW_IF_AVAILABLE",
     dimensions
   } = options;
   validateNonNegative(estimate, "estimate");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcycles",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "TypeScript client for the Cycles budget-management protocol",
   "license": "Apache-2.0",
   "author": "runcycles",