@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 +21 -0
- package/README.md +22 -12
- package/dist/errors.d.mts +6 -0
- package/dist/errors.mjs +9 -1
- package/dist/index.d.mts +2 -2
- package/dist/index.mjs +2 -2
- package/dist/server/client.d.mts +2 -0
- package/dist/server/client.mjs +3 -2
- package/dist/server/gateway.d.mts +2 -0
- package/dist/server/gateway.mjs +5 -1
- package/dist/server/index.d.mts +2 -2
- package/dist/server/index.mjs +2 -2
- package/dist/types.d.mts +11 -1
- package/dist/types.mjs +21 -1
- package/package.json +6 -6
- package/stub/server.d.mts +2 -0
- package/stub/server.mjs +82 -2
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
|
|
392
|
-
|
|
|
393
|
-
| `POST /stub/reset`
|
|
394
|
-
| `POST /stub/mode {"down":true}`
|
|
395
|
-
| `POST /stub/mode {"providerError":true}`
|
|
396
|
-
| `POST /stub/
|
|
397
|
-
| `POST /stub/
|
|
398
|
-
| `POST /stub/
|
|
399
|
-
| `POST /stub/
|
|
400
|
-
| `
|
|
401
|
-
| `GET /stub/
|
|
402
|
-
| `GET /stub/
|
|
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 };
|
package/dist/server/client.d.mts
CHANGED
|
@@ -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>;
|
package/dist/server/client.mjs
CHANGED
|
@@ -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
|
/**
|
package/dist/server/gateway.mjs
CHANGED
|
@@ -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 };
|
package/dist/server/index.d.mts
CHANGED
|
@@ -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 };
|
package/dist/server/index.mjs
CHANGED
|
@@ -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.
|
|
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: {
|
|
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,
|
|
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)
|