@dtelecom/x402-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dTelecom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# @dtelecom/x402-client
+
+TypeScript SDK for the [dTelecom x402 gateway](https://x402.dtelecom.org) — buy credits with USDC and create WebRTC, STT, and TTS sessions for AI agents.
+
+Uses the [x402 HTTP payment protocol](https://www.x402.org/) for on-chain micropayments on Base.
+
+## Install
+
+```bash
+npm install @dtelecom/x402-client @x402/fetch @x402/evm viem
+```
+
+`@x402/fetch` and `@x402/evm` are peer dependencies — they handle the 402 payment flow.
+
+## Quick Start
+
+```typescript
+import { DtelecomGateway } from '@dtelecom/x402-client';
+import { privateKeyToAccount } from 'viem/accounts';
+
+const gateway = new DtelecomGateway({
+  gatewayUrl: 'https://x402.dtelecom.org',
+  account: privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`),
+});
+
+// Buy credits ($0.10 USDC on Base)
+const purchase = await gateway.buyCredits({ amountUsd: 0.10 });
+console.log(`Credits: ${purchase.creditedMicrocredits}`);
+
+// Create agent session (WebRTC + STT + TTS bundle)
+const session = await gateway.createAgentSession({
+  roomName: 'tutor-room-123',
+  participantIdentity: 'student-1',
+  durationMinutes: 10,
+  language: 'en',
+});
+
+console.log(session.webrtc.token);  // JWT for WebRTC SFU
+console.log(session.stt.token);     // Token for STT server
+console.log(session.tts.token);     // Token for TTS server
+```
+
+## Wallet Support
+
+The SDK accepts a viem `LocalAccount` — the standard interface for server-side wallets:
+
+```typescript
+// Private key
+import { privateKeyToAccount } from 'viem/accounts';
+const account = privateKeyToAccount('0x...');
+
+// Coinbase CDP server wallet
+import { toAccount } from 'viem/accounts';
+const account = toAccount(cdpServerAccount);
+
+// AWS/GCP KMS via viem adapters
+const account = await createKmsAccount({ ... });
+```
+
+## API
+
+### Constructor
+
+```typescript
+new DtelecomGateway({ gatewayUrl: string, account: LocalAccount })
+```
+
+### Credits
+
+| Method | Description |
+|--------|-------------|
+| `buyCredits({ amountUsd })` | Purchase credits via x402 USDC payment on Base |
+
+### Account
+
+| Method | Description |
+|--------|-------------|
+| `getAccount()` | Get account details and balance |
+| `getTransactions({ limit?, offset? })` | List credit transactions |
+| `getSessions({ limit?, offset?, status? })` | List sessions |
+
+### Agent Session (WebRTC + STT + TTS bundle)
+
+| Method | Description |
+|--------|-------------|
+| `createAgentSession({ roomName, participantIdentity, durationMinutes, language?, ttsMaxCharacters?, metadata? })` | Create bundled session |
+| `extendAgentSession({ bundleId, additionalMinutes, additionalTtsCharacters? })` | Extend all sessions in bundle |
+
+### Standalone Sessions
+
+| Method | Description |
+|--------|-------------|
+| `createWebRTCToken({ roomName, participantIdentity, durationMinutes, metadata? })` | Create WebRTC session |
+| `extendWebRTCToken({ sessionId, additionalMinutes })` | Extend WebRTC session |
+| `createSTTSession({ durationMinutes, language? })` | Create STT session |
+| `extendSTTSession({ sessionId, additionalMinutes })` | Extend STT session |
+| `createTTSSession({ maxCharacters, language? })` | Create TTS session |
+| `extendTTSSession({ sessionId, additionalCharacters })` | Extend TTS session |
+
+### Error Handling
+
+```typescript
+import {
+  GatewayError,              // Base error (any non-2xx)
+  InsufficientCreditsError,  // 402 — not enough credits
+  ConcurrencyLimitError,     // 429 — too many active sessions
+  RateLimitError,            // 429 — too many requests
+  NoCapacityError,           // 503 — no servers available
+  PaymentError,              // x402 payment failed
+} from '@dtelecom/x402-client';
+
+try {
+  await gateway.createAgentSession({ ... });
+} catch (err) {
+  if (err instanceof InsufficientCreditsError) {
+    await gateway.buyCredits({ amountUsd: 1.00 });
+  }
+}
+```
+
+## Pricing
+
+| Service | Rate | Unit |
+|---------|------|------|
+| WebRTC | $0.001 | per minute |
+| STT | $0.006 | per minute |
+| TTS | $0.008 | per 1K characters |
+
+1 USD = 1,000,000 microcredits.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,231 @@
+import { LocalAccount } from 'viem/accounts';
+
+interface BuyCreditsRequest {
+    amountUsd: number;
+}
+interface CreateWebRTCTokenRequest {
+    roomName: string;
+    participantIdentity: string;
+    durationMinutes: number;
+    metadata?: string;
+}
+interface ExtendWebRTCTokenRequest {
+    sessionId: string;
+    additionalMinutes: number;
+}
+interface CreateSTTSessionRequest {
+    durationMinutes: number;
+    language?: string;
+}
+interface ExtendSTTSessionRequest {
+    sessionId: string;
+    additionalMinutes: number;
+}
+interface CreateTTSSessionRequest {
+    maxCharacters: number;
+    language?: string;
+}
+interface ExtendTTSSessionRequest {
+    sessionId: string;
+    additionalCharacters: number;
+}
+interface CreateAgentSessionRequest {
+    roomName: string;
+    participantIdentity: string;
+    durationMinutes: number;
+    language?: string;
+    ttsMaxCharacters?: number;
+    metadata?: string;
+}
+interface ExtendAgentSessionRequest {
+    bundleId: string;
+    additionalMinutes: number;
+    additionalTtsCharacters?: number;
+}
+interface PaginationOptions {
+    limit?: number;
+    offset?: number;
+}
+interface SessionsOptions extends PaginationOptions {
+    status?: string;
+}
+interface BuyCreditsResponse {
+    accountId: string;
+    creditedMicrocredits: string;
+    amountUsd: number;
+}
+interface AccountResponse {
+    id: string;
+    walletAddress: string;
+    walletChain: string;
+    creditBalance: string;
+    availableBalance: string;
+    maxConcurrentSessions: number;
+    maxApiRate: number;
+    createdAt: string;
+}
+interface Transaction {
+    id: string;
+    amount: string;
+    balanceAfter: string;
+    type: string;
+    referenceId: string | null;
+    service: string | null;
+    description: string | null;
+    createdAt: string;
+}
+interface TransactionsResponse {
+    transactions: Transaction[];
+    limit: number;
+    offset: number;
+}
+interface Session {
+    id: string;
+    service: string;
+    bundleId: string | null;
+    status: string;
+    roomName: string | null;
+    serverUrl: string | null;
+    reservedMicrocredits: string;
+    chargedMicrocredits: string;
+    tokenExpiresAt: string | null;
+    startedAt: string | null;
+    endedAt: string | null;
+    settlementMethod: string;
+    createdAt: string;
+}
+interface SessionsResponse {
+    sessions: Session[];
+    limit: number;
+    offset: number;
+}
+interface WebRTCTokenResponse {
+    sessionId: string;
+    token: string;
+    wsUrl: string;
+    expiresAt: string;
+}
+interface ExtendWebRTCTokenResponse {
+    token: string;
+    wsUrl: string;
+    newExpiresAt: string;
+}
+interface STTSessionResponse {
+    sessionId: string;
+    token: string;
+    serverUrl: string;
+    expiresAt: string;
+}
+interface ExtendSTTSessionResponse {
+    token: string;
+    newExpiresAt: string;
+}
+interface TTSSessionResponse {
+    sessionId: string;
+    token: string;
+    serverUrl: string;
+    expiresAt: string;
+}
+interface ExtendTTSSessionResponse {
+    token: string;
+    maxCharacters: number;
+    newExpiresAt: string;
+}
+interface AgentSessionResponse {
+    bundleId: string;
+    webrtc: {
+        sessionId: string;
+        token: string;
+        wsUrl: string;
+    };
+    stt: {
+        sessionId: string;
+        token: string;
+        serverUrl: string;
+    };
+    tts: {
+        sessionId: string;
+        token: string;
+        serverUrl: string;
+    };
+    expiresAt: string;
+}
+interface ExtendAgentSessionResponse {
+    webrtc?: {
+        token: string;
+        newExpiresAt: string;
+    };
+    stt?: {
+        token: string;
+        newExpiresAt: string;
+    };
+    tts?: {
+        token: string;
+        newExpiresAt: string;
+    };
+}
+
+interface DtelecomGatewayConfig {
+    /** Gateway base URL (e.g. "https://x402.dtelecom.org") */
+    gatewayUrl: string;
+    /** viem LocalAccount — from privateKeyToAccount(), CDP toAccount(), KMS adapter, etc. */
+    account: LocalAccount;
+}
+declare class DtelecomGateway {
+    private readonly baseUrl;
+    private readonly account;
+    private readonly fetchWithPayment;
+    constructor(config: DtelecomGatewayConfig);
+    buyCredits(options: BuyCreditsRequest): Promise<BuyCreditsResponse>;
+    getAccount(): Promise<AccountResponse>;
+    getTransactions(options?: PaginationOptions): Promise<TransactionsResponse>;
+    getSessions(options?: SessionsOptions): Promise<SessionsResponse>;
+    createAgentSession(options: CreateAgentSessionRequest): Promise<AgentSessionResponse>;
+    extendAgentSession(options: ExtendAgentSessionRequest): Promise<ExtendAgentSessionResponse>;
+    createWebRTCToken(options: CreateWebRTCTokenRequest): Promise<WebRTCTokenResponse>;
+    extendWebRTCToken(options: ExtendWebRTCTokenRequest): Promise<ExtendWebRTCTokenResponse>;
+    createSTTSession(options: CreateSTTSessionRequest): Promise<STTSessionResponse>;
+    extendSTTSession(options: ExtendSTTSessionRequest): Promise<ExtendSTTSessionResponse>;
+    createTTSSession(options: CreateTTSSessionRequest): Promise<TTSSessionResponse>;
+    extendTTSSession(options: ExtendTTSSessionRequest): Promise<ExtendTTSSessionResponse>;
+    private request;
+    private requestWithPayment;
+    private handleResponse;
+}
+
+declare class GatewayError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+declare class InsufficientCreditsError extends GatewayError {
+    constructor(message: string);
+}
+declare class ConcurrencyLimitError extends GatewayError {
+    constructor(message: string);
+}
+declare class RateLimitError extends GatewayError {
+    constructor(message: string);
+}
+declare class NoCapacityError extends GatewayError {
+    readonly service: string;
+    constructor(message: string, service: string);
+}
+declare class PaymentError extends GatewayError {
+    constructor(message: string);
+}
+
+interface AuthHeaders {
+    Authorization: string;
+    "X-Wallet-Address": string;
+    "X-Wallet-Chain": string;
+    "X-Timestamp": string;
+}
+/**
+ * Create wallet-auth headers for the gateway.
+ *
+ * Signs: `${METHOD}\n${path}\n${timestamp}`
+ * Result: `Authorization: evm:<signature>`
+ */
+declare function createAuthHeaders(account: LocalAccount, method: string, path: string): Promise<AuthHeaders>;
+
+export { type AccountResponse, type AgentSessionResponse, type AuthHeaders, type BuyCreditsRequest, type BuyCreditsResponse, ConcurrencyLimitError, type CreateAgentSessionRequest, type CreateSTTSessionRequest, type CreateTTSSessionRequest, type CreateWebRTCTokenRequest, DtelecomGateway, type DtelecomGatewayConfig, type ExtendAgentSessionRequest, type ExtendAgentSessionResponse, type ExtendSTTSessionRequest, type ExtendSTTSessionResponse, type ExtendTTSSessionRequest, type ExtendTTSSessionResponse, type ExtendWebRTCTokenRequest, type ExtendWebRTCTokenResponse, GatewayError, InsufficientCreditsError, NoCapacityError, type PaginationOptions, PaymentError, RateLimitError, type STTSessionResponse, type Session, type SessionsOptions, type SessionsResponse, type TTSSessionResponse, type Transaction, type TransactionsResponse, type WebRTCTokenResponse, createAuthHeaders };

package/dist/index.d.ts

@@ -0,0 +1,231 @@
+import { LocalAccount } from 'viem/accounts';
+
+interface BuyCreditsRequest {
+    amountUsd: number;
+}
+interface CreateWebRTCTokenRequest {
+    roomName: string;
+    participantIdentity: string;
+    durationMinutes: number;
+    metadata?: string;
+}
+interface ExtendWebRTCTokenRequest {
+    sessionId: string;
+    additionalMinutes: number;
+}
+interface CreateSTTSessionRequest {
+    durationMinutes: number;
+    language?: string;
+}
+interface ExtendSTTSessionRequest {
+    sessionId: string;
+    additionalMinutes: number;
+}
+interface CreateTTSSessionRequest {
+    maxCharacters: number;
+    language?: string;
+}
+interface ExtendTTSSessionRequest {
+    sessionId: string;
+    additionalCharacters: number;
+}
+interface CreateAgentSessionRequest {
+    roomName: string;
+    participantIdentity: string;
+    durationMinutes: number;
+    language?: string;
+    ttsMaxCharacters?: number;
+    metadata?: string;
+}
+interface ExtendAgentSessionRequest {
+    bundleId: string;
+    additionalMinutes: number;
+    additionalTtsCharacters?: number;
+}
+interface PaginationOptions {
+    limit?: number;
+    offset?: number;
+}
+interface SessionsOptions extends PaginationOptions {
+    status?: string;
+}
+interface BuyCreditsResponse {
+    accountId: string;
+    creditedMicrocredits: string;
+    amountUsd: number;
+}
+interface AccountResponse {
+    id: string;
+    walletAddress: string;
+    walletChain: string;
+    creditBalance: string;
+    availableBalance: string;
+    maxConcurrentSessions: number;
+    maxApiRate: number;
+    createdAt: string;
+}
+interface Transaction {
+    id: string;
+    amount: string;
+    balanceAfter: string;
+    type: string;
+    referenceId: string | null;
+    service: string | null;
+    description: string | null;
+    createdAt: string;
+}
+interface TransactionsResponse {
+    transactions: Transaction[];
+    limit: number;
+    offset: number;
+}
+interface Session {
+    id: string;
+    service: string;
+    bundleId: string | null;
+    status: string;
+    roomName: string | null;
+    serverUrl: string | null;
+    reservedMicrocredits: string;
+    chargedMicrocredits: string;
+    tokenExpiresAt: string | null;
+    startedAt: string | null;
+    endedAt: string | null;
+    settlementMethod: string;
+    createdAt: string;
+}
+interface SessionsResponse {
+    sessions: Session[];
+    limit: number;
+    offset: number;
+}
+interface WebRTCTokenResponse {
+    sessionId: string;
+    token: string;
+    wsUrl: string;
+    expiresAt: string;
+}
+interface ExtendWebRTCTokenResponse {
+    token: string;
+    wsUrl: string;
+    newExpiresAt: string;
+}
+interface STTSessionResponse {
+    sessionId: string;
+    token: string;
+    serverUrl: string;
+    expiresAt: string;
+}
+interface ExtendSTTSessionResponse {
+    token: string;
+    newExpiresAt: string;
+}
+interface TTSSessionResponse {
+    sessionId: string;
+    token: string;
+    serverUrl: string;
+    expiresAt: string;
+}
+interface ExtendTTSSessionResponse {
+    token: string;
+    maxCharacters: number;
+    newExpiresAt: string;
+}
+interface AgentSessionResponse {
+    bundleId: string;
+    webrtc: {
+        sessionId: string;
+        token: string;
+        wsUrl: string;
+    };
+    stt: {
+        sessionId: string;
+        token: string;
+        serverUrl: string;
+    };
+    tts: {
+        sessionId: string;
+        token: string;
+        serverUrl: string;
+    };
+    expiresAt: string;
+}
+interface ExtendAgentSessionResponse {
+    webrtc?: {
+        token: string;
+        newExpiresAt: string;
+    };
+    stt?: {
+        token: string;
+        newExpiresAt: string;
+    };
+    tts?: {
+        token: string;
+        newExpiresAt: string;
+    };
+}
+
+interface DtelecomGatewayConfig {
+    /** Gateway base URL (e.g. "https://x402.dtelecom.org") */
+    gatewayUrl: string;
+    /** viem LocalAccount — from privateKeyToAccount(), CDP toAccount(), KMS adapter, etc. */
+    account: LocalAccount;
+}
+declare class DtelecomGateway {
+    private readonly baseUrl;
+    private readonly account;
+    private readonly fetchWithPayment;
+    constructor(config: DtelecomGatewayConfig);
+    buyCredits(options: BuyCreditsRequest): Promise<BuyCreditsResponse>;
+    getAccount(): Promise<AccountResponse>;
+    getTransactions(options?: PaginationOptions): Promise<TransactionsResponse>;
+    getSessions(options?: SessionsOptions): Promise<SessionsResponse>;
+    createAgentSession(options: CreateAgentSessionRequest): Promise<AgentSessionResponse>;
+    extendAgentSession(options: ExtendAgentSessionRequest): Promise<ExtendAgentSessionResponse>;
+    createWebRTCToken(options: CreateWebRTCTokenRequest): Promise<WebRTCTokenResponse>;
+    extendWebRTCToken(options: ExtendWebRTCTokenRequest): Promise<ExtendWebRTCTokenResponse>;
+    createSTTSession(options: CreateSTTSessionRequest): Promise<STTSessionResponse>;
+    extendSTTSession(options: ExtendSTTSessionRequest): Promise<ExtendSTTSessionResponse>;
+    createTTSSession(options: CreateTTSSessionRequest): Promise<TTSSessionResponse>;
+    extendTTSSession(options: ExtendTTSSessionRequest): Promise<ExtendTTSSessionResponse>;
+    private request;
+    private requestWithPayment;
+    private handleResponse;
+}
+
+declare class GatewayError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+declare class InsufficientCreditsError extends GatewayError {
+    constructor(message: string);
+}
+declare class ConcurrencyLimitError extends GatewayError {
+    constructor(message: string);
+}
+declare class RateLimitError extends GatewayError {
+    constructor(message: string);
+}
+declare class NoCapacityError extends GatewayError {
+    readonly service: string;
+    constructor(message: string, service: string);
+}
+declare class PaymentError extends GatewayError {
+    constructor(message: string);
+}
+
+interface AuthHeaders {
+    Authorization: string;
+    "X-Wallet-Address": string;
+    "X-Wallet-Chain": string;
+    "X-Timestamp": string;
+}
+/**
+ * Create wallet-auth headers for the gateway.
+ *
+ * Signs: `${METHOD}\n${path}\n${timestamp}`
+ * Result: `Authorization: evm:<signature>`
+ */
+declare function createAuthHeaders(account: LocalAccount, method: string, path: string): Promise<AuthHeaders>;
+
+export { type AccountResponse, type AgentSessionResponse, type AuthHeaders, type BuyCreditsRequest, type BuyCreditsResponse, ConcurrencyLimitError, type CreateAgentSessionRequest, type CreateSTTSessionRequest, type CreateTTSSessionRequest, type CreateWebRTCTokenRequest, DtelecomGateway, type DtelecomGatewayConfig, type ExtendAgentSessionRequest, type ExtendAgentSessionResponse, type ExtendSTTSessionRequest, type ExtendSTTSessionResponse, type ExtendTTSSessionRequest, type ExtendTTSSessionResponse, type ExtendWebRTCTokenRequest, type ExtendWebRTCTokenResponse, GatewayError, InsufficientCreditsError, NoCapacityError, type PaginationOptions, PaymentError, RateLimitError, type STTSessionResponse, type Session, type SessionsOptions, type SessionsResponse, type TTSSessionResponse, type Transaction, type TransactionsResponse, type WebRTCTokenResponse, createAuthHeaders };