runcycles 0.1.1 → 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.
@@ -58,8 +62,35 @@ const callLlm = withCycles(
 const result = await callLlm("Hello", 100);
 ```
 
+> **Need an API key?** API keys are created via the Cycles Admin Server (port 7979). See the [deployment guide](https://runcycles.io/quickstart/deploying-the-full-cycles-stack#step-3-create-an-api-key) to create one, or run:
+> ```bash
+> curl -s -X POST http://localhost:7979/v1/admin/api-keys \
+>   -H "Content-Type: application/json" \
+>   -H "X-Admin-API-Key: admin-bootstrap-key" \
+>   -d '{"tenant_id":"acme-corp","name":"dev-key","permissions":["reservations:create","reservations:commit","reservations:release","reservations:extend","reservations:list","balances:read","decide","events:create"]}' | jq -r '.key_secret'
+> ```
+> The key (e.g. `cyc_live_abc123...`) is shown only once — save it immediately. For key rotation and lifecycle details, see [API Key Management](https://runcycles.io/how-to/api-key-management-in-cycles).
+
 **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:
@@ -234,7 +265,7 @@ const config = CyclesConfig.fromEnv();
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `CYCLES_BASE_URL` | Yes | Cycles server URL |
-| `CYCLES_API_KEY` | Yes | API key for authentication |
+| `CYCLES_API_KEY` | Yes | API key for authentication (see [how to create one](https://runcycles.io/quickstart/deploying-the-full-cycles-stack#step-3-create-an-api-key)) |
 | `CYCLES_TENANT` | No | Default tenant |
 | `CYCLES_WORKSPACE` | No | Default workspace |
 | `CYCLES_APP` | No | Default app |
@@ -294,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)
@@ -786,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:
@@ -815,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

@@ -28,6 +28,7 @@ __export(index_exports, {
   CyclesError: () => CyclesError,
   CyclesProtocolError: () => CyclesProtocolError,
   CyclesResponse: () => CyclesResponse,
+  CyclesTransportError: () => CyclesTransportError,
   DebtOutstandingError: () => DebtOutstandingError,
   Decision: () => Decision,
   ErrorCode: () => ErrorCode,
@@ -722,6 +723,14 @@ var ReservationFinalizedError = class extends CyclesProtocolError {
     this.name = "ReservationFinalizedError";
   }
 };
+var CyclesTransportError = class extends CyclesError {
+  cause;
+  constructor(message, options) {
+    super(message);
+    this.name = "CyclesTransportError";
+    this.cause = options?.cause;
+  }
+};
 
 // src/errors.ts
 function buildProtocolException(prefix, response) {
@@ -826,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;
@@ -953,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) {
@@ -1275,7 +1287,7 @@ async function reserveForStream(options) {
     actionTags,
     ttlMs = DEFAULT_TTL_MS,
     gracePeriodMs,
-    overagePolicy = "REJECT",
+    overagePolicy = "ALLOW_IF_AVAILABLE",
     dimensions
   } = options;
   validateNonNegative(estimate, "estimate");
@@ -1414,6 +1426,7 @@ async function reserveForStream(options) {
   CyclesError,
   CyclesProtocolError,
   CyclesResponse,
+  CyclesTransportError,
   DebtOutstandingError,
   Decision,
   ErrorCode,

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 {
@@ -335,9 +339,9 @@ declare class CyclesClient {
 
 /** Lifecycle orchestration: reserve -> execute -> commit/release. */
 
-interface WithCyclesConfig {
-    estimate: number | ((...args: unknown[]) => number);
-    actual?: number | ((result: unknown) => number);
+interface WithCyclesConfig<TArgs extends unknown[] = unknown[], TResult = unknown> {
+    estimate: number | ((...args: TArgs) => number);
+    actual?: number | ((result: TResult) => number);
     actionKind?: string;
     actionName?: string;
     actionTags?: string[];
@@ -360,7 +364,7 @@ interface WithCyclesConfig {
 
 declare function setDefaultClient(client: CyclesClient): void;
 declare function setDefaultConfig(config: CyclesConfig): void;
-declare function withCycles<TArgs extends unknown[], TResult>(options: WithCyclesConfig & {
+declare function withCycles<TArgs extends unknown[], TResult>(options: WithCyclesConfig<TArgs, TResult> & {
     client?: CyclesClient;
 }, fn: (...args: TArgs) => Promise<TResult>): (...args: TArgs) => Promise<TResult>;
 
@@ -508,6 +512,12 @@ declare class ReservationExpiredError extends CyclesProtocolError {
 declare class ReservationFinalizedError extends CyclesProtocolError {
     constructor(message: string, options?: ConstructorParameters<typeof CyclesProtocolError>[1]);
 }
+declare class CyclesTransportError extends CyclesError {
+    readonly cause: Error | undefined;
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
+}
 
 /**
  * Explicit request/response mappers between camelCase TypeScript interfaces
@@ -543,4 +553,4 @@ declare function reservationExtendRequestToWire(req: ReservationExtendRequest):
 declare function decisionRequestToWire(req: DecisionRequest): Record<string, unknown>;
 declare function eventCreateRequestToWire(req: EventCreateRequest): Record<string, unknown>;
 
-export { type Action, type Amount, type Balance, type BalanceResponse, BudgetExceededError, type Caps, CommitOveragePolicy, type CommitRequest, type CommitResponse, CommitStatus, CyclesClient, CyclesConfig, type CyclesContext, CyclesError, type CyclesMetrics, CyclesProtocolError, CyclesResponse, DebtOutstandingError, Decision, type DecisionRequest, type DecisionResponse, type DryRunResult, ErrorCode, type ErrorResponse, type EventCreateRequest, type EventCreateResponse, EventStatus, ExtendStatus, OverdraftLimitExceededError, type ReleaseRequest, type ReleaseResponse, ReleaseStatus, type ReservationCreateRequest, type ReservationCreateResponse, type ReservationDetail, ReservationExpiredError, type ReservationExtendRequest, type ReservationExtendResponse, ReservationFinalizedError, type ReservationListResponse, ReservationStatus, type ReservationSummary, type SignedAmount, type StreamReservation, type StreamReservationOptions, type Subject, Unit, type WithCyclesConfig, balanceResponseFromWire, capsFromWire, commitRequestToWire, commitResponseFromWire, decisionRequestToWire, decisionResponseFromWire, errorCodeFromString, errorResponseFromWire, eventCreateRequestToWire, eventCreateResponseFromWire, getCyclesContext, isAllowed, isDenied, isMetricsEmpty, isRetryableErrorCode, isToolAllowed, metricsToWire, releaseRequestToWire, releaseResponseFromWire, reservationCreateRequestToWire, reservationCreateResponseFromWire, reservationDetailFromWire, reservationExtendRequestToWire, reservationExtendResponseFromWire, reservationListResponseFromWire, reservationSummaryFromWire, reserveForStream, setDefaultClient, setDefaultConfig, withCycles };
+export { type Action, type Amount, type Balance, type BalanceResponse, BudgetExceededError, type Caps, CommitOveragePolicy, type CommitRequest, type CommitResponse, CommitStatus, CyclesClient, CyclesConfig, type CyclesContext, CyclesError, type CyclesMetrics, CyclesProtocolError, CyclesResponse, CyclesTransportError, DebtOutstandingError, Decision, type DecisionRequest, type DecisionResponse, type DryRunResult, ErrorCode, type ErrorResponse, type EventCreateRequest, type EventCreateResponse, EventStatus, ExtendStatus, OverdraftLimitExceededError, type ReleaseRequest, type ReleaseResponse, ReleaseStatus, type ReservationCreateRequest, type ReservationCreateResponse, type ReservationDetail, ReservationExpiredError, type ReservationExtendRequest, type ReservationExtendResponse, ReservationFinalizedError, type ReservationListResponse, ReservationStatus, type ReservationSummary, type SignedAmount, type StreamReservation, type StreamReservationOptions, type Subject, Unit, type WithCyclesConfig, balanceResponseFromWire, capsFromWire, commitRequestToWire, commitResponseFromWire, decisionRequestToWire, decisionResponseFromWire, errorCodeFromString, errorResponseFromWire, eventCreateRequestToWire, eventCreateResponseFromWire, getCyclesContext, isAllowed, isDenied, isMetricsEmpty, isRetryableErrorCode, isToolAllowed, metricsToWire, releaseRequestToWire, releaseResponseFromWire, reservationCreateRequestToWire, reservationCreateResponseFromWire, reservationDetailFromWire, reservationExtendRequestToWire, reservationExtendResponseFromWire, reservationListResponseFromWire, reservationSummaryFromWire, reserveForStream, setDefaultClient, setDefaultConfig, withCycles };

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 {
@@ -335,9 +339,9 @@ declare class CyclesClient {
 
 /** Lifecycle orchestration: reserve -> execute -> commit/release. */
 
-interface WithCyclesConfig {
-    estimate: number | ((...args: unknown[]) => number);
-    actual?: number | ((result: unknown) => number);
+interface WithCyclesConfig<TArgs extends unknown[] = unknown[], TResult = unknown> {
+    estimate: number | ((...args: TArgs) => number);
+    actual?: number | ((result: TResult) => number);
     actionKind?: string;
     actionName?: string;
     actionTags?: string[];
@@ -360,7 +364,7 @@ interface WithCyclesConfig {
 
 declare function setDefaultClient(client: CyclesClient): void;
 declare function setDefaultConfig(config: CyclesConfig): void;
-declare function withCycles<TArgs extends unknown[], TResult>(options: WithCyclesConfig & {
+declare function withCycles<TArgs extends unknown[], TResult>(options: WithCyclesConfig<TArgs, TResult> & {
     client?: CyclesClient;
 }, fn: (...args: TArgs) => Promise<TResult>): (...args: TArgs) => Promise<TResult>;
 
@@ -508,6 +512,12 @@ declare class ReservationExpiredError extends CyclesProtocolError {
 declare class ReservationFinalizedError extends CyclesProtocolError {
     constructor(message: string, options?: ConstructorParameters<typeof CyclesProtocolError>[1]);
 }
+declare class CyclesTransportError extends CyclesError {
+    readonly cause: Error | undefined;
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
+}
 
 /**
  * Explicit request/response mappers between camelCase TypeScript interfaces
@@ -543,4 +553,4 @@ declare function reservationExtendRequestToWire(req: ReservationExtendRequest):
 declare function decisionRequestToWire(req: DecisionRequest): Record<string, unknown>;
 declare function eventCreateRequestToWire(req: EventCreateRequest): Record<string, unknown>;
 
-export { type Action, type Amount, type Balance, type BalanceResponse, BudgetExceededError, type Caps, CommitOveragePolicy, type CommitRequest, type CommitResponse, CommitStatus, CyclesClient, CyclesConfig, type CyclesContext, CyclesError, type CyclesMetrics, CyclesProtocolError, CyclesResponse, DebtOutstandingError, Decision, type DecisionRequest, type DecisionResponse, type DryRunResult, ErrorCode, type ErrorResponse, type EventCreateRequest, type EventCreateResponse, EventStatus, ExtendStatus, OverdraftLimitExceededError, type ReleaseRequest, type ReleaseResponse, ReleaseStatus, type ReservationCreateRequest, type ReservationCreateResponse, type ReservationDetail, ReservationExpiredError, type ReservationExtendRequest, type ReservationExtendResponse, ReservationFinalizedError, type ReservationListResponse, ReservationStatus, type ReservationSummary, type SignedAmount, type StreamReservation, type StreamReservationOptions, type Subject, Unit, type WithCyclesConfig, balanceResponseFromWire, capsFromWire, commitRequestToWire, commitResponseFromWire, decisionRequestToWire, decisionResponseFromWire, errorCodeFromString, errorResponseFromWire, eventCreateRequestToWire, eventCreateResponseFromWire, getCyclesContext, isAllowed, isDenied, isMetricsEmpty, isRetryableErrorCode, isToolAllowed, metricsToWire, releaseRequestToWire, releaseResponseFromWire, reservationCreateRequestToWire, reservationCreateResponseFromWire, reservationDetailFromWire, reservationExtendRequestToWire, reservationExtendResponseFromWire, reservationListResponseFromWire, reservationSummaryFromWire, reserveForStream, setDefaultClient, setDefaultConfig, withCycles };
+export { type Action, type Amount, type Balance, type BalanceResponse, BudgetExceededError, type Caps, CommitOveragePolicy, type CommitRequest, type CommitResponse, CommitStatus, CyclesClient, CyclesConfig, type CyclesContext, CyclesError, type CyclesMetrics, CyclesProtocolError, CyclesResponse, CyclesTransportError, DebtOutstandingError, Decision, type DecisionRequest, type DecisionResponse, type DryRunResult, ErrorCode, type ErrorResponse, type EventCreateRequest, type EventCreateResponse, EventStatus, ExtendStatus, OverdraftLimitExceededError, type ReleaseRequest, type ReleaseResponse, ReleaseStatus, type ReservationCreateRequest, type ReservationCreateResponse, type ReservationDetail, ReservationExpiredError, type ReservationExtendRequest, type ReservationExtendResponse, ReservationFinalizedError, type ReservationListResponse, ReservationStatus, type ReservationSummary, type SignedAmount, type StreamReservation, type StreamReservationOptions, type Subject, Unit, type WithCyclesConfig, balanceResponseFromWire, capsFromWire, commitRequestToWire, commitResponseFromWire, decisionRequestToWire, decisionResponseFromWire, errorCodeFromString, errorResponseFromWire, eventCreateRequestToWire, eventCreateResponseFromWire, getCyclesContext, isAllowed, isDenied, isMetricsEmpty, isRetryableErrorCode, isToolAllowed, metricsToWire, releaseRequestToWire, releaseResponseFromWire, reservationCreateRequestToWire, reservationCreateResponseFromWire, reservationDetailFromWire, reservationExtendRequestToWire, reservationExtendResponseFromWire, reservationListResponseFromWire, reservationSummaryFromWire, reserveForStream, setDefaultClient, setDefaultConfig, withCycles };

package/dist/index.js

@@ -648,6 +648,14 @@ var ReservationFinalizedError = class extends CyclesProtocolError {
     this.name = "ReservationFinalizedError";
   }
 };
+var CyclesTransportError = class extends CyclesError {
+  cause;
+  constructor(message, options) {
+    super(message);
+    this.name = "CyclesTransportError";
+    this.cause = options?.cause;
+  }
+};
 
 // src/errors.ts
 function buildProtocolException(prefix, response) {
@@ -752,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;
@@ -879,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) {
@@ -1201,7 +1212,7 @@ async function reserveForStream(options) {
     actionTags,
     ttlMs = DEFAULT_TTL_MS,
     gracePeriodMs,
-    overagePolicy = "REJECT",
+    overagePolicy = "ALLOW_IF_AVAILABLE",
     dimensions
   } = options;
   validateNonNegative(estimate, "estimate");
@@ -1339,6 +1350,7 @@ export {
   CyclesError,
   CyclesProtocolError,
   CyclesResponse,
+  CyclesTransportError,
   DebtOutstandingError,
   Decision,
   ErrorCode,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcycles",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "TypeScript client for the Cycles budget-management protocol",
   "license": "Apache-2.0",
   "author": "runcycles",
@@ -52,7 +52,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
     "prepublishOnly": "npm run lint && npm run build"
   },
   "devDependencies": {