@kaperkunde/tokens 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kaperkunde
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -69,6 +69,15 @@ a call that was cut short; `provider_error` (502) covers a provider failure and
69
69
  a problem with the center's own provider key, never with the provider's text,
70
70
  and `forbidden` (403) a test key used where no test provider is set.
71
71
 
72
+ Provider refusals: `provider_out_of_credit` (503, `error.provider`, `error.model`) means the
73
+ center's own account with that AI provider is out of credit; nothing is charged and asking
74
+ again is pointless until an admin tops up, so an app should pause that feature for a while
75
+ rather than retry. `provider_rate_limited` (429) and `provider_overloaded` (503) are upstream
76
+ conditions worth one retry; `error.retryable` (`RETRYABLE_ERROR_CODES`) says which codes can work again, and
77
+ `error.detail.retryAfterSeconds` carries `Retry-After`. A speech answer names the voice it
78
+ used in place of the one asked for in `x-token-voice-fallback` (`SpeechResult.voiceFallback`,
79
+ `voiceFallbackFromHeaders`).
80
+
72
81
  ### Model calls: the gateway
73
82
 
74
83
  Point an AI SDK provider at the center, with the payer in `x-token-user`:
@@ -388,18 +397,19 @@ per million characters. A model id containing `unpriced` answers
388
397
 
389
398
  Test controls (no auth; the real center has none of these):
390
399
 
391
- | Call | Does |
392
- | --------------------------------------------------------------- | ---------------------------------------------------------------------- |
393
- | `POST /stub/reset` | Forget everything |
394
- | `POST /stub/mode {"down":true}` | Every call answers 503 `center_unavailable` (fail-closed tests) |
395
- | `POST /stub/mode {"providerError":true}` | Gateway calls answer 502 `provider_error` |
396
- | `POST /stub/balance {"userId","purchasedMicros"}` | Set purchased (0 → `insufficient_balance` on the next call) |
397
- | `POST /stub/grant {"userId","micros","provider"?,"expiresAt"?}` | Add a lot and send `grant.received` |
398
- | `POST /stub/expire {"lotId"}` | Expire a lot, send `grant.expired` |
399
- | `POST /stub/autorefill-fail {"userId"}` | Turn auto-refill off, send `autorefill.failed` |
400
- | `GET /stub/checkout/:purchaseId` | The "Stripe page": pays, credits, sends `purchase.completed`, 303 back |
401
- | `GET /stub/card/:userId?to=` | Saves a Visa ending 4242 and redirects to `to` |
402
- | `GET /stub/state` | Every balance and call, for assertions |
400
+ | Call | Does |
401
+ | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
402
+ | `POST /stub/reset` | Forget everything |
403
+ | `POST /stub/mode {"down":true}` | Every call answers 503 `center_unavailable` (fail-closed tests) |
404
+ | `POST /stub/mode {"providerError":true}` | Gateway calls answer 502 `provider_error` |
405
+ | `POST /stub/mode {"fail":"out_of_credit"}` (or env `TOKENS_STUB_FAIL`, the `fail` option, or the request header `x-stub-fail`) | Gateway calls answer 503 `provider_out_of_credit` (provider, model, `x-should-retry: false`); `"rate_limited"` 429 `provider_rate_limited` + `Retry-After: 7`; `"overloaded"` 503 `provider_overloaded`; `null` clears it. Speech does not fail: `stub-voice` falls back to `stub-voice-eleven` and answers with `x-token-voice-fallback` |
406
+ | `POST /stub/balance {"userId","purchasedMicros"}` | Set purchased (0 → `insufficient_balance` on the next call) |
407
+ | `POST /stub/grant {"userId","micros","provider"?,"expiresAt"?}` | Add a lot and send `grant.received` |
408
+ | `POST /stub/expire {"lotId"}` | Expire a lot, send `grant.expired` |
409
+ | `POST /stub/autorefill-fail {"userId"}` | Turn auto-refill off, send `autorefill.failed` |
410
+ | `GET /stub/checkout/:purchaseId` | The "Stripe page": pays, credits, sends `purchase.completed`, 303 back |
411
+ | `GET /stub/card/:userId?to=` | Saves a Visa ending 4242 and redirects to `to` |
412
+ | `GET /stub/state` | Every balance and call, for assertions |
403
413
 
404
414
  A Playwright test follows the checkout URL the app returns and lands on the
405
415
  app's success URL with the wallet credited. The stub's webhooks are signed
package/dist/errors.d.mts CHANGED
@@ -18,6 +18,12 @@ export declare class TokenCenterError extends Error {
18
18
  get callId(): string | undefined;
19
19
  /** `invalid_request`: the JSON path of the offending field or header (`amountCents`, `tools[0].type`, `body`). */
20
20
  get path(): string | undefined;
21
+ /**
22
+ * Whether asking again can work: `provider_rate_limited`, `provider_overloaded`,
23
+ * `provider_timeout`, `rate_limited` and `center_unavailable` can; `provider_out_of_credit`
24
+ * cannot until an admin tops the center's account up.
25
+ */
26
+ get retryable(): boolean;
21
27
  /** What the app should offer the user: buy tokens, set up an own model, wait. */
22
28
  get action(): TokenErrorDetail["action"];
23
29
  }
package/dist/errors.mjs CHANGED
@@ -1,4 +1,4 @@
1
- import { ERROR_CODES, ERROR_STATUS } from "./types.mjs";
1
+ import { ERROR_CODES, ERROR_STATUS, RETRYABLE_ERROR_CODES } from "./types.mjs";
2
2
  // src/errors.ts
3
3
  /**
4
4
  * An error the Token Center answered with (or that the client synthesised for
@@ -27,6 +27,14 @@ var TokenCenterError = class extends Error {
27
27
  get path() {
28
28
  return this.detail.path;
29
29
  }
30
+ /**
31
+ * Whether asking again can work: `provider_rate_limited`, `provider_overloaded`,
32
+ * `provider_timeout`, `rate_limited` and `center_unavailable` can; `provider_out_of_credit`
33
+ * cannot until an admin tops the center's account up.
34
+ */
35
+ get retryable() {
36
+ return RETRYABLE_ERROR_CODES.includes(this.code);
37
+ }
30
38
  /** What the app should offer the user: buy tokens, set up an own model, wait. */
31
39
  get action() {
32
40
  return this.detail.action;
package/dist/index.d.mts CHANGED
@@ -1,5 +1,5 @@
1
- import { APP_KEY_HEADERS, APP_KEY_PATTERN, AnthropicMessagesRequest, AppInfo, AppUnit, AppUser, Attribution, AutoRefill, AutoRefillFailedEvent, AutoRefillInput, BackendOrder, BackendOrderInput, Balance, BalanceEmptyEvent, BalanceLowEvent, BalanceSummary, CONTRACT_VERSION, CallCharge, CallEndpoint, CallRecord, CallStatus, CallUsage, CallsPage, CallsQuery, Capability, CardSetupRequest, CardSetupSession, Cents, ChatCompletionsRequest, CheckoutRequest, CheckoutSession, Currency, ERROR_CODES, ERROR_STATUS, ErrorCode, GatewayAnthropicError, GatewayModelList, GatewayOpenAIError, GrantExpiredEvent, GrantLot, GrantReceivedEvent, HeaderCharge, HistoryEntry, HistoryPage, IsoTime, Micros, ModelInfo, ModelPrice, OwnEndpoint, OwnEndpointInput, OwnEndpointResponse, OwnEndpointTest, Protocol, ProviderId, Purchase, PurchaseCompletedEvent, PurchaseOptions, PurchaseStatus, RouteDecision, RouteRequest, SalePrice, SalePrices, Source, SpeechRequest, TOKEN_HEADERS, TokenErrorBody, TokenErrorDetail, ToolChoice, UpsertUserRequest, VoiceInfo, WEBHOOK_EVENT_TYPES, WEBHOOK_RETRY_SECONDS, WEBHOOK_TOLERANCE_SECONDS, WebhookEnvelope, WebhookEvent, WebhookEventType } from "./types.mjs";
1
+ import { APP_KEY_HEADERS, APP_KEY_PATTERN, AnthropicMessagesRequest, AppInfo, AppUnit, AppUser, Attribution, AutoRefill, AutoRefillFailedEvent, AutoRefillInput, BackendOrder, BackendOrderInput, Balance, BalanceEmptyEvent, BalanceLowEvent, BalanceSummary, CONTRACT_VERSION, CallCharge, CallEndpoint, CallRecord, CallStatus, CallUsage, CallsPage, CallsQuery, Capability, CardSetupRequest, CardSetupSession, Cents, ChatCompletionsRequest, CheckoutRequest, CheckoutSession, Currency, ERROR_CODES, ERROR_STATUS, ErrorCode, GatewayAnthropicError, GatewayModelList, GatewayOpenAIError, GrantExpiredEvent, GrantLot, GrantReceivedEvent, HeaderCharge, HistoryEntry, HistoryPage, IsoTime, Micros, ModelInfo, ModelPrice, OwnEndpoint, OwnEndpointInput, OwnEndpointResponse, OwnEndpointTest, Protocol, ProviderId, Purchase, PurchaseCompletedEvent, PurchaseOptions, PurchaseStatus, RETRYABLE_ERROR_CODES, RouteDecision, RouteRequest, SalePrice, SalePrices, Source, SpeechRequest, TOKEN_HEADERS, TokenErrorBody, TokenErrorDetail, ToolChoice, UpsertUserRequest, VoiceInfo, WEBHOOK_EVENT_TYPES, WEBHOOK_RETRY_SECONDS, WEBHOOK_TOLERANCE_SECONDS, WebhookEnvelope, WebhookEvent, WebhookEventType } from "./types.mjs";
2
2
  import { TokenCenterError, centerUnavailable, detailOf, errorFromResponse, isErrorCode, isTokenError } from "./errors.mjs";
3
3
  import { FormatUnitsOptions, MICROS_PER_DOLLAR, creditFor, formatCompact, formatMoney, formatUnits, microsOf, microsToUsd, unitsOf } from "./units.mjs";
4
4
  import { CardInput, CheckoutInput, TokenApi, TokenApiOptions, createTokenApi } from "./browser-api.mjs";
5
- export { APP_KEY_HEADERS, APP_KEY_PATTERN, AnthropicMessagesRequest, AppInfo, AppUnit, AppUser, Attribution, AutoRefill, AutoRefillFailedEvent, AutoRefillInput, BackendOrder, BackendOrderInput, Balance, BalanceEmptyEvent, BalanceLowEvent, BalanceSummary, CONTRACT_VERSION, CallCharge, CallEndpoint, CallRecord, CallStatus, CallUsage, CallsPage, CallsQuery, Capability, CardInput, CardSetupRequest, CardSetupSession, Cents, ChatCompletionsRequest, CheckoutInput, CheckoutRequest, CheckoutSession, Currency, ERROR_CODES, ERROR_STATUS, ErrorCode, FormatUnitsOptions, GatewayAnthropicError, GatewayModelList, GatewayOpenAIError, GrantExpiredEvent, GrantLot, GrantReceivedEvent, HeaderCharge, HistoryEntry, HistoryPage, IsoTime, MICROS_PER_DOLLAR, Micros, ModelInfo, ModelPrice, OwnEndpoint, OwnEndpointInput, OwnEndpointResponse, OwnEndpointTest, Protocol, ProviderId, Purchase, PurchaseCompletedEvent, PurchaseOptions, PurchaseStatus, RouteDecision, RouteRequest, SalePrice, SalePrices, Source, SpeechRequest, TOKEN_HEADERS, TokenApi, TokenApiOptions, TokenCenterError, TokenErrorBody, TokenErrorDetail, ToolChoice, UpsertUserRequest, VoiceInfo, WEBHOOK_EVENT_TYPES, WEBHOOK_RETRY_SECONDS, WEBHOOK_TOLERANCE_SECONDS, WebhookEnvelope, WebhookEvent, WebhookEventType, centerUnavailable, createTokenApi, creditFor, detailOf, errorFromResponse, formatCompact, formatMoney, formatUnits, isErrorCode, isTokenError, microsOf, microsToUsd, unitsOf };
5
+ export { APP_KEY_HEADERS, APP_KEY_PATTERN, AnthropicMessagesRequest, AppInfo, AppUnit, AppUser, Attribution, AutoRefill, AutoRefillFailedEvent, AutoRefillInput, BackendOrder, BackendOrderInput, Balance, BalanceEmptyEvent, BalanceLowEvent, BalanceSummary, CONTRACT_VERSION, CallCharge, CallEndpoint, CallRecord, CallStatus, CallUsage, CallsPage, CallsQuery, Capability, CardInput, CardSetupRequest, CardSetupSession, Cents, ChatCompletionsRequest, CheckoutInput, CheckoutRequest, CheckoutSession, Currency, ERROR_CODES, ERROR_STATUS, ErrorCode, FormatUnitsOptions, GatewayAnthropicError, GatewayModelList, GatewayOpenAIError, GrantExpiredEvent, GrantLot, GrantReceivedEvent, HeaderCharge, HistoryEntry, HistoryPage, IsoTime, MICROS_PER_DOLLAR, Micros, ModelInfo, ModelPrice, OwnEndpoint, OwnEndpointInput, OwnEndpointResponse, OwnEndpointTest, Protocol, ProviderId, Purchase, PurchaseCompletedEvent, PurchaseOptions, PurchaseStatus, RETRYABLE_ERROR_CODES, RouteDecision, RouteRequest, SalePrice, SalePrices, Source, SpeechRequest, TOKEN_HEADERS, TokenApi, TokenApiOptions, TokenCenterError, TokenErrorBody, TokenErrorDetail, ToolChoice, UpsertUserRequest, VoiceInfo, WEBHOOK_EVENT_TYPES, WEBHOOK_RETRY_SECONDS, WEBHOOK_TOLERANCE_SECONDS, WebhookEnvelope, WebhookEvent, WebhookEventType, centerUnavailable, createTokenApi, creditFor, detailOf, errorFromResponse, formatCompact, formatMoney, formatUnits, isErrorCode, isTokenError, microsOf, microsToUsd, unitsOf };
package/dist/index.mjs CHANGED
@@ -1,5 +1,5 @@
1
- import { APP_KEY_HEADERS, APP_KEY_PATTERN, CONTRACT_VERSION, ERROR_CODES, ERROR_STATUS, TOKEN_HEADERS, WEBHOOK_EVENT_TYPES, WEBHOOK_RETRY_SECONDS, WEBHOOK_TOLERANCE_SECONDS } from "./types.mjs";
1
+ import { APP_KEY_HEADERS, APP_KEY_PATTERN, CONTRACT_VERSION, ERROR_CODES, ERROR_STATUS, RETRYABLE_ERROR_CODES, TOKEN_HEADERS, WEBHOOK_EVENT_TYPES, WEBHOOK_RETRY_SECONDS, WEBHOOK_TOLERANCE_SECONDS } from "./types.mjs";
2
2
  import { TokenCenterError, centerUnavailable, detailOf, errorFromResponse, isErrorCode, isTokenError } from "./errors.mjs";
3
3
  import { MICROS_PER_DOLLAR, creditFor, formatCompact, formatMoney, formatUnits, microsOf, microsToUsd, unitsOf } from "./units.mjs";
4
4
  import { createTokenApi } from "./browser-api.mjs";
5
- export { APP_KEY_HEADERS, APP_KEY_PATTERN, CONTRACT_VERSION, ERROR_CODES, ERROR_STATUS, MICROS_PER_DOLLAR, TOKEN_HEADERS, TokenCenterError, WEBHOOK_EVENT_TYPES, WEBHOOK_RETRY_SECONDS, WEBHOOK_TOLERANCE_SECONDS, centerUnavailable, createTokenApi, creditFor, detailOf, errorFromResponse, formatCompact, formatMoney, formatUnits, isErrorCode, isTokenError, microsOf, microsToUsd, unitsOf };
5
+ export { APP_KEY_HEADERS, APP_KEY_PATTERN, CONTRACT_VERSION, ERROR_CODES, ERROR_STATUS, MICROS_PER_DOLLAR, RETRYABLE_ERROR_CODES, TOKEN_HEADERS, TokenCenterError, WEBHOOK_EVENT_TYPES, WEBHOOK_RETRY_SECONDS, WEBHOOK_TOLERANCE_SECONDS, centerUnavailable, createTokenApi, creditFor, detailOf, errorFromResponse, formatCompact, formatMoney, formatUnits, isErrorCode, isTokenError, microsOf, microsToUsd, unitsOf };
@@ -18,6 +18,8 @@ export type SpeechResult = {
18
18
  charge: HeaderCharge | null;
19
19
  /** Characters metered. */
20
20
  chars: number | null;
21
+ /** The voice that actually spoke, when the center used another than the one asked for (`x-token-voice-fallback`). */
22
+ voiceFallback: string | null;
21
23
  };
22
24
  /** Every `/api/v1` path as a typed method. See {@link createTokenCenter}. */
23
25
  export type TokenCenter = ReturnType<typeof createTokenCenter>;
@@ -1,5 +1,5 @@
1
1
  import { centerUnavailable, errorFromResponse } from "../errors.mjs";
2
- import { chargeFromHeaders, gatewayHeaders, trimBaseUrl } from "./gateway.mjs";
2
+ import { chargeFromHeaders, gatewayHeaders, trimBaseUrl, voiceFallbackFromHeaders } from "./gateway.mjs";
3
3
  // src/server/client.ts
4
4
  /**
5
5
  * The app-API client. Fetch-based, one timeout per request, and every
@@ -129,7 +129,8 @@ function createTokenCenter(options) {
129
129
  audio: new Uint8Array(await response.arrayBuffer()),
130
130
  contentType: response.headers.get("content-type") ?? "audio/mpeg",
131
131
  charge: chargeFromHeaders(response.headers),
132
- chars: Number.isFinite(chars) && chars > 0 ? chars : null
132
+ chars: Number.isFinite(chars) && chars > 0 ? chars : null,
133
+ voiceFallback: voiceFallbackFromHeaders(response.headers)
133
134
  };
134
135
  }
135
136
  };
@@ -45,6 +45,8 @@ export declare function gatewayConfig(input: GatewayConfigInput): GatewayConfig;
45
45
  type HeadersLike = Headers | {
46
46
  get(name: string): string | null | undefined;
47
47
  } | Record<string, string | string[] | undefined>;
48
+ /** The voice a speech answer used in place of the one asked for (`x-token-voice-fallback`), or `null` when it was the asked one. */
49
+ export declare function voiceFallbackFromHeaders(headers: HeadersLike): string | null;
48
50
  /** The call id a gateway response carries up front (streams have it before any cost is known), or `null`. */
49
51
  export declare function callIdFromHeaders(headers: HeadersLike): string | null;
50
52
  /**
@@ -60,6 +60,10 @@ const micros = (value) => {
60
60
  const n = Number(value);
61
61
  return Number.isFinite(n) ? n : null;
62
62
  };
63
+ /** The voice a speech answer used in place of the one asked for (`x-token-voice-fallback`), or `null` when it was the asked one. */
64
+ function voiceFallbackFromHeaders(headers) {
65
+ return headerOf(headers, TOKEN_HEADERS.voiceFallback);
66
+ }
63
67
  /** The call id a gateway response carries up front (streams have it before any cost is known), or `null`. */
64
68
  function callIdFromHeaders(headers) {
65
69
  return headerOf(headers, TOKEN_HEADERS.callId);
@@ -107,4 +111,4 @@ function parseTrailer(sse) {
107
111
  }
108
112
  return null;
109
113
  }
110
- export { callIdFromHeaders, chargeFromHeaders, gatewayConfig, gatewayHeaders, parseTrailer, trimBaseUrl };
114
+ export { callIdFromHeaders, chargeFromHeaders, gatewayConfig, gatewayHeaders, parseTrailer, trimBaseUrl, voiceFallbackFromHeaders };
@@ -1,7 +1,7 @@
1
1
  import { CallsFilter, SpeechResult, TokenCenter, TokenCenterOptions, createTokenCenter } from "./client.mjs";
2
- import { GatewayConfig, GatewayConfigInput, GatewayHeaderInput, callIdFromHeaders, chargeFromHeaders, gatewayConfig, gatewayHeaders, parseTrailer, trimBaseUrl } from "./gateway.mjs";
2
+ import { GatewayConfig, GatewayConfigInput, GatewayHeaderInput, callIdFromHeaders, chargeFromHeaders, gatewayConfig, gatewayHeaders, parseTrailer, trimBaseUrl, voiceFallbackFromHeaders } from "./gateway.mjs";
3
3
  import { tokenErrorOf } from "./error-of.mjs";
4
4
  import { VerifyWebhookOptions, WebhookFailure, WebhookHandlers, WebhookRouteOptions, WebhookVerificationError, parseWebhookEvent, signWebhook, verifyWebhook, webhookRoute } from "./webhook.mjs";
5
5
  import { ReturnKind, TokenRoutesOptions, TokenUser, safeReturnPath, tokenRoutes } from "./routes.mjs";
6
6
  import { NodeHandlerOptions, nodeHandler, requestFromNode, sendResponse } from "./node.mjs";
7
- export { CallsFilter, GatewayConfig, GatewayConfigInput, GatewayHeaderInput, NodeHandlerOptions, ReturnKind, SpeechResult, TokenCenter, TokenCenterOptions, TokenRoutesOptions, TokenUser, VerifyWebhookOptions, WebhookFailure, WebhookHandlers, WebhookRouteOptions, WebhookVerificationError, callIdFromHeaders, chargeFromHeaders, createTokenCenter, gatewayConfig, gatewayHeaders, nodeHandler, parseTrailer, parseWebhookEvent, requestFromNode, safeReturnPath, sendResponse, signWebhook, tokenErrorOf, tokenRoutes, trimBaseUrl, verifyWebhook, webhookRoute };
7
+ export { CallsFilter, GatewayConfig, GatewayConfigInput, GatewayHeaderInput, NodeHandlerOptions, ReturnKind, SpeechResult, TokenCenter, TokenCenterOptions, TokenRoutesOptions, TokenUser, VerifyWebhookOptions, WebhookFailure, WebhookHandlers, WebhookRouteOptions, WebhookVerificationError, callIdFromHeaders, chargeFromHeaders, createTokenCenter, gatewayConfig, gatewayHeaders, nodeHandler, parseTrailer, parseWebhookEvent, requestFromNode, safeReturnPath, sendResponse, signWebhook, tokenErrorOf, tokenRoutes, trimBaseUrl, verifyWebhook, voiceFallbackFromHeaders, webhookRoute };
@@ -1,7 +1,7 @@
1
1
  import { createTokenCenter } from "./client.mjs";
2
- import { callIdFromHeaders, chargeFromHeaders, gatewayConfig, gatewayHeaders, parseTrailer, trimBaseUrl } from "./gateway.mjs";
2
+ import { callIdFromHeaders, chargeFromHeaders, gatewayConfig, gatewayHeaders, parseTrailer, trimBaseUrl, voiceFallbackFromHeaders } from "./gateway.mjs";
3
3
  import { tokenErrorOf } from "./error-of.mjs";
4
4
  import { WebhookVerificationError, parseWebhookEvent, signWebhook, verifyWebhook, webhookRoute } from "./webhook.mjs";
5
5
  import { safeReturnPath, tokenRoutes } from "./routes.mjs";
6
6
  import { nodeHandler, requestFromNode, sendResponse } from "./node.mjs";
7
- export { WebhookVerificationError, callIdFromHeaders, chargeFromHeaders, createTokenCenter, gatewayConfig, gatewayHeaders, nodeHandler, parseTrailer, parseWebhookEvent, requestFromNode, safeReturnPath, sendResponse, signWebhook, tokenErrorOf, tokenRoutes, trimBaseUrl, verifyWebhook, webhookRoute };
7
+ export { WebhookVerificationError, callIdFromHeaders, chargeFromHeaders, createTokenCenter, gatewayConfig, gatewayHeaders, nodeHandler, parseTrailer, parseWebhookEvent, requestFromNode, safeReturnPath, sendResponse, signWebhook, tokenErrorOf, tokenRoutes, trimBaseUrl, verifyWebhook, voiceFallbackFromHeaders, webhookRoute };
package/dist/types.d.mts CHANGED
@@ -67,6 +67,8 @@ export declare const TOKEN_HEADERS: {
67
67
  readonly error: "x-token-error";
68
68
  /** Rate limited / in-flight cap: seconds to wait (standard header). */
69
69
  readonly retryAfter: "retry-after";
70
+ /** On a speech answer: the voice id actually used, present only when it was not the one asked for. */
71
+ readonly voiceFallback: "x-token-voice-fallback";
70
72
  /** `t=<unix seconds>,v1=<hex HMAC-SHA256(secret, `${t}.${rawBody}`)>` */
71
73
  readonly signature: "token-signature";
72
74
  readonly eventId: "token-event-id";
@@ -77,9 +79,15 @@ export declare const APP_KEY_HEADERS: readonly ["x-api-key", "authorization"];
77
79
  export declare const APP_KEY_PATTERN: RegExp;
78
80
  /** Webhook signature tolerance. */
79
81
  export declare const WEBHOOK_TOLERANCE_SECONDS = 300;
80
- export declare const ERROR_CODES: readonly ["unauthenticated", "forbidden", "invalid_request", "unknown_user", "not_found", "unknown_model", "model_not_priced", "wrong_protocol", "insufficient_balance", "capability_unavailable", "byo_not_configured", "byo_failed", "byo_limit_reached", "provider_error", "provider_timeout", "rate_limited", "payments_unavailable", "purchase_too_small", "no_card", "conflict", "center_unavailable", "internal_error"];
82
+ export declare const ERROR_CODES: readonly ["unauthenticated", "forbidden", "invalid_request", "unknown_user", "not_found", "unknown_model", "model_not_priced", "wrong_protocol", "insufficient_balance", "capability_unavailable", "byo_not_configured", "byo_failed", "byo_limit_reached", "provider_error", "provider_timeout", "provider_out_of_credit", "provider_rate_limited", "provider_overloaded", "rate_limited", "payments_unavailable", "purchase_too_small", "no_card", "conflict", "center_unavailable", "internal_error"];
81
83
  export type ErrorCode = (typeof ERROR_CODES)[number];
82
84
  export declare const ERROR_STATUS: Record<ErrorCode, number>;
85
+ /**
86
+ * Codes a client may retry (after `Retry-After` / `retryAfterSeconds` where given). Notably NOT
87
+ * `provider_out_of_credit`: the center's own account with the provider is empty, so retrying
88
+ * changes nothing until the operator tops it up; an app shows the error and moves on.
89
+ */
90
+ export declare const RETRYABLE_ERROR_CODES: readonly ErrorCode[];
83
91
  export type Capability = "tools" | "streaming" | "vision" | "json" | "voice";
84
92
  export type TokenErrorDetail = {
85
93
  code: ErrorCode;
@@ -89,6 +97,8 @@ export type TokenErrorDetail = {
89
97
  action?: "buy_tokens" | "configure_own" | "wait";
90
98
  capability?: Capability;
91
99
  provider?: ProviderId;
100
+ /** provider_out_of_credit: the model the refused call asked for. */
101
+ model?: string;
92
102
  minimumCents?: Cents;
93
103
  retryAfterSeconds?: number;
94
104
  /** Upstream HTTP status for provider_error / byo_failed. */
package/dist/types.mjs CHANGED
@@ -63,6 +63,8 @@ const TOKEN_HEADERS = {
63
63
  error: "x-token-error",
64
64
  /** Rate limited / in-flight cap: seconds to wait (standard header). */
65
65
  retryAfter: "retry-after",
66
+ /** On a speech answer: the voice id actually used, present only when it was not the one asked for. */
67
+ voiceFallback: "x-token-voice-fallback",
66
68
  /** `t=<unix seconds>,v1=<hex HMAC-SHA256(secret, `${t}.${rawBody}`)>` */
67
69
  signature: "token-signature",
68
70
  eventId: "token-event-id"
@@ -89,6 +91,9 @@ const ERROR_CODES = [
89
91
  "byo_limit_reached",
90
92
  "provider_error",
91
93
  "provider_timeout",
94
+ "provider_out_of_credit",
95
+ "provider_rate_limited",
96
+ "provider_overloaded",
92
97
  "rate_limited",
93
98
  "payments_unavailable",
94
99
  "purchase_too_small",
@@ -113,6 +118,9 @@ const ERROR_STATUS = {
113
118
  byo_limit_reached: 402,
114
119
  provider_error: 502,
115
120
  provider_timeout: 504,
121
+ provider_out_of_credit: 503,
122
+ provider_rate_limited: 429,
123
+ provider_overloaded: 503,
116
124
  rate_limited: 429,
117
125
  payments_unavailable: 503,
118
126
  purchase_too_small: 400,
@@ -121,6 +129,18 @@ const ERROR_STATUS = {
121
129
  center_unavailable: 503,
122
130
  internal_error: 500
123
131
  };
132
+ /**
133
+ * Codes a client may retry (after `Retry-After` / `retryAfterSeconds` where given). Notably NOT
134
+ * `provider_out_of_credit`: the center's own account with the provider is empty, so retrying
135
+ * changes nothing until the operator tops it up; an app shows the error and moves on.
136
+ */
137
+ const RETRYABLE_ERROR_CODES = [
138
+ "rate_limited",
139
+ "provider_rate_limited",
140
+ "provider_overloaded",
141
+ "provider_timeout",
142
+ "center_unavailable"
143
+ ];
124
144
  const WEBHOOK_EVENT_TYPES = [
125
145
  "grant.received",
126
146
  "purchase.completed",
@@ -139,4 +159,4 @@ const WEBHOOK_RETRY_SECONDS = [
139
159
  43200,
140
160
  86400
141
161
  ];
142
- export { APP_KEY_HEADERS, APP_KEY_PATTERN, CONTRACT_VERSION, ERROR_CODES, ERROR_STATUS, TOKEN_HEADERS, WEBHOOK_EVENT_TYPES, WEBHOOK_RETRY_SECONDS, WEBHOOK_TOLERANCE_SECONDS };
162
+ export { APP_KEY_HEADERS, APP_KEY_PATTERN, CONTRACT_VERSION, ERROR_CODES, ERROR_STATUS, RETRYABLE_ERROR_CODES, TOKEN_HEADERS, WEBHOOK_EVENT_TYPES, WEBHOOK_RETRY_SECONDS, WEBHOOK_TOLERANCE_SECONDS };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kaperkunde/tokens",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "The client for the Token Center: the contract types, a typed server client and gateway config for AI SDK providers, webhook verification, browser-facing route handlers, React components for balance, buying, auto-refill, usage and own models, and a stand-in center for tests.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -45,10 +45,6 @@
45
45
  },
46
46
  "./styles.css": "./dist/styles.css"
47
47
  },
48
- "scripts": {
49
- "build": "tsdown",
50
- "typecheck": "tsc --noEmit -p tsconfig.json"
51
- },
52
48
  "peerDependencies": {
53
49
  "react": "^19.0.0",
54
50
  "react-dom": "^19.0.0"
@@ -71,5 +67,9 @@
71
67
  "publishConfig": {
72
68
  "access": "public",
73
69
  "provenance": true
70
+ },
71
+ "scripts": {
72
+ "build": "tsdown",
73
+ "typecheck": "tsc --noEmit -p tsconfig.json"
74
74
  }
75
- }
75
+ }
package/stub/server.d.mts CHANGED
@@ -23,6 +23,8 @@ export type StubOptions = {
23
23
  packsCents?: number[] | string
24
24
  /** Allow only the packs. */
25
25
  packsOnly?: boolean
26
+ /** A provider failure every gateway call answers with until `POST /stub/mode {"fail":null}`. */
27
+ fail?: "out_of_credit" | "rate_limited" | "overloaded"
26
28
  }
27
29
 
28
30
  export type Stub = {
package/stub/server.mjs CHANGED
@@ -33,6 +33,7 @@ export function startStub(options = {}) {
33
33
  ...set("TOKENS_STUB_REPLY", options.reply),
34
34
  ...set("TOKENS_STUB_PACKS", options.packsCents),
35
35
  ...set("TOKENS_STUB_PACKS_ONLY", options.packsOnly),
36
+ ...set("TOKENS_STUB_FAIL", options.fail),
36
37
  }
37
38
  const timers = new Set()
38
39
  let PORT = Number(env.TOKENS_STUB_PORT ?? 4100)
@@ -103,6 +104,13 @@ export function startStub(options = {}) {
103
104
  usdPerMChars: "15",
104
105
  isDefault: true,
105
106
  },
107
+ {
108
+ id: "stub-voice-eleven",
109
+ name: "Stub voice (ElevenLabs)",
110
+ provider: "elevenlabs",
111
+ usdPerMChars: "30",
112
+ isDefault: false,
113
+ },
106
114
  ]
107
115
  const SALE = [
108
116
  {
@@ -147,6 +155,9 @@ export function startStub(options = {}) {
147
155
  byo_limit_reached: 402,
148
156
  provider_error: 502,
149
157
  provider_timeout: 504,
158
+ provider_out_of_credit: 503,
159
+ provider_rate_limited: 429,
160
+ provider_overloaded: 503,
150
161
  rate_limited: 429,
151
162
  payments_unavailable: 503,
152
163
  purchase_too_small: 400,
@@ -156,13 +167,37 @@ export function startStub(options = {}) {
156
167
  internal_error: 500,
157
168
  }
158
169
 
170
+ // A provider failure the test asked for: TOKENS_STUB_FAIL, POST /stub/mode {"fail"} or the request
171
+ // header `x-stub-fail`: out_of_credit, rate_limited or overloaded (see the README).
172
+ const FAIL_FROM_ENV = [
173
+ "out_of_credit",
174
+ "rate_limited",
175
+ "overloaded",
176
+ ].includes(env.TOKENS_STUB_FAIL)
177
+ ? env.TOKENS_STUB_FAIL
178
+ : null
179
+ const FAILS = {
180
+ out_of_credit: "provider_out_of_credit",
181
+ rate_limited: "provider_rate_limited",
182
+ overloaded: "provider_overloaded",
183
+ }
184
+ const PROVIDER_NAME = {
185
+ anthropic: "Anthropic",
186
+ openai: "OpenAI",
187
+ elevenlabs: "ElevenLabs",
188
+ }
189
+
159
190
  let state
160
191
  const reset = () => {
161
192
  state = {
162
193
  users: new Map(),
163
194
  calls: [],
164
195
  purchases: new Map(),
165
- mode: { down: false, providerError: false },
196
+ mode: {
197
+ down: false,
198
+ providerError: false,
199
+ fail: FAIL_FROM_ENV,
200
+ },
166
201
  }
167
202
  }
168
203
  reset()
@@ -379,6 +414,15 @@ export function startStub(options = {}) {
379
414
  json(res, STATUS[code], body, {
380
415
  "x-token-error": code,
381
416
  ...(extra.callId ? { "x-token-call-id": extra.callId } : {}),
417
+ ...(code === "provider_out_of_credit"
418
+ ? { "x-should-retry": "false" }
419
+ : {}),
420
+ ...(extra.retryAfterSeconds !== undefined &&
421
+ ["rate_limited", "provider_rate_limited", "provider_overloaded"].includes(
422
+ code,
423
+ )
424
+ ? { "retry-after": String(extra.retryAfterSeconds) }
425
+ : {}),
382
426
  })
383
427
  }
384
428
  const attribution = (req) =>
@@ -731,6 +775,41 @@ export function startStub(options = {}) {
731
775
  callId: call.id,
732
776
  })
733
777
  }
778
+ const failKind = FAILS[req.headers["x-stub-fail"]]
779
+ ? req.headers["x-stub-fail"]
780
+ : state.mode.fail
781
+ const failing =
782
+ backend === "tokens" &&
783
+ failKind &&
784
+ (!speech || (body.voice ?? "stub-voice") !== "stub-voice-eleven")
785
+ if (failing && !speech) {
786
+ const code = FAILS[failKind]
787
+ const name = PROVIDER_NAME[provider]
788
+ const message =
789
+ failKind === "out_of_credit"
790
+ ? `The ${name} account behind the token center is out of credit; nothing was charged.`
791
+ : failKind === "overloaded"
792
+ ? `${name} is overloaded; nothing was charged. Try again shortly.`
793
+ : `${name} is rate limiting the token center; nothing was charged. Try again shortly.`
794
+ Object.assign(call, {
795
+ status: "failed",
796
+ finishedAt: now(),
797
+ error: { code, message, provider, model },
798
+ })
799
+ return fail(res, code, message, shape, {
800
+ provider,
801
+ model,
802
+ callId: call.id,
803
+ ...(failKind === "out_of_credit" ? {} : { retryAfterSeconds: 7 }),
804
+ })
805
+ }
806
+ // Speech does not fail: it falls back to the app's other voice, on a provider that is not failing.
807
+ let fallbackVoice = null
808
+ if (failing && speech) {
809
+ fallbackVoice = "stub-voice-eleven"
810
+ call.model = fallbackVoice
811
+ call.provider = "elevenlabs"
812
+ }
734
813
  if (speech) {
735
814
  const chars = [...String(body.input ?? "")].length
736
815
  if (!chars || chars > 4096) {
@@ -744,11 +823,12 @@ export function startStub(options = {}) {
744
823
  )
745
824
  }
746
825
  call.usage = { ...zeroUsage(), units: { tts_chars: chars } }
747
- charge(u, call, "openai", costOf(call.usage))
826
+ charge(u, call, call.provider, costOf(call.usage))
748
827
  const audio = silentMp3()
749
828
  res.writeHead(200, {
750
829
  "content-type": "audio/mpeg",
751
830
  "x-token-chars": String(chars),
831
+ ...(fallbackVoice ? { "x-token-voice-fallback": fallbackVoice } : {}),
752
832
  ...chargeHeaders(call),
753
833
  })
754
834
  return res.end(audio)