runcycles 0.1.1 → 0.1.2

package/README.md

@@ -58,6 +58,15 @@ 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.
 
 ### 2. Streaming adapter
@@ -234,7 +243,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 |

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) {
@@ -1414,6 +1423,7 @@ async function reserveForStream(options) {
   CyclesError,
   CyclesProtocolError,
   CyclesResponse,
+  CyclesTransportError,
   DebtOutstandingError,
   Decision,
   ErrorCode,

package/dist/index.d.cts

@@ -335,9 +335,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 +360,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 +508,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 +549,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

@@ -335,9 +335,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 +360,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 +508,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 +549,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) {
@@ -1339,6 +1347,7 @@ export {
   CyclesError,
   CyclesProtocolError,
   CyclesResponse,
+  CyclesTransportError,
   DebtOutstandingError,
   Decision,
   ErrorCode,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcycles",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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": {