@token2chat/t2c 0.2.0-beta.1 → 0.2.0

package/dist/proxy/errors.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Proxy error classes with OpenAI-compatible JSON serialization.
+ */
+export interface ProxyErrorJSON {
+    error: {
+        code: string;
+        message: string;
+        type?: string;
+    };
+}
+/**
+ * Base error class for proxy errors.
+ * Serializes to OpenAI-compatible error format.
+ */
+export declare class ProxyError extends Error {
+    readonly code: string;
+    readonly httpStatus: number;
+    readonly type?: string;
+    constructor(code: string, message: string, httpStatus?: number, type?: string);
+    toJSON(): ProxyErrorJSON;
+}
+/**
+ * Thrown when wallet balance is insufficient for the requested model.
+ */
+export declare class InsufficientBalanceError extends ProxyError {
+    readonly balance: number;
+    readonly required: number;
+    readonly model: string;
+    constructor(balance: number, required: number, model: string);
+}
+/**
+ * Thrown when the Gate is unreachable.
+ */
+export declare class GateUnreachableError extends ProxyError {
+    readonly gateUrl: string;
+    constructor(gateUrl: string, cause?: Error);
+}
+/**
+ * Thrown when request body exceeds size limit.
+ */
+export declare class PayloadTooLargeError extends ProxyError {
+    readonly size: number;
+    readonly limit: number;
+    constructor(size: number, limit: number);
+}
+/**
+ * Thrown when authentication fails.
+ */
+export declare class UnauthorizedError extends ProxyError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when endpoint is not found.
+ */
+export declare class NotFoundError extends ProxyError {
+    readonly path: string;
+    constructor(path: string);
+}

package/dist/proxy/errors.js

@@ -0,0 +1,95 @@
+/**
+ * Proxy error classes with OpenAI-compatible JSON serialization.
+ */
+/**
+ * Base error class for proxy errors.
+ * Serializes to OpenAI-compatible error format.
+ */
+export class ProxyError extends Error {
+    code;
+    httpStatus;
+    type;
+    constructor(code, message, httpStatus = 500, type) {
+        super(message);
+        this.name = "ProxyError";
+        this.code = code;
+        this.httpStatus = httpStatus;
+        this.type = type;
+    }
+    toJSON() {
+        return {
+            error: {
+                code: this.code,
+                message: this.message,
+                ...(this.type && { type: this.type }),
+            },
+        };
+    }
+}
+/**
+ * Thrown when wallet balance is insufficient for the requested model.
+ */
+export class InsufficientBalanceError extends ProxyError {
+    balance;
+    required;
+    model;
+    constructor(balance, required, model) {
+        super("insufficient_balance", `Wallet balance ${balance} < ${required} required for ${model}. Run 't2c mint' to add funds.`, 402, "insufficient_funds");
+        this.name = "InsufficientBalanceError";
+        this.balance = balance;
+        this.required = required;
+        this.model = model;
+    }
+}
+/**
+ * Thrown when the Gate is unreachable.
+ */
+export class GateUnreachableError extends ProxyError {
+    gateUrl;
+    constructor(gateUrl, cause) {
+        const host = new URL(gateUrl).host;
+        super("gate_unreachable", `Gate at ${host} is unreachable`, 502);
+        this.name = "GateUnreachableError";
+        this.gateUrl = gateUrl;
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+function formatBytes(bytes) {
+    const mb = bytes / (1024 * 1024);
+    return `${mb.toFixed(1)} MB`;
+}
+/**
+ * Thrown when request body exceeds size limit.
+ */
+export class PayloadTooLargeError extends ProxyError {
+    size;
+    limit;
+    constructor(size, limit) {
+        super("payload_too_large", `Request body ${formatBytes(size)} exceeds limit of ${formatBytes(limit)}`, 413);
+        this.name = "PayloadTooLargeError";
+        this.size = size;
+        this.limit = limit;
+    }
+}
+/**
+ * Thrown when authentication fails.
+ */
+export class UnauthorizedError extends ProxyError {
+    constructor(message = "Unauthorized. Provide a valid Bearer token.") {
+        super("unauthorized", message, 401, "authentication_error");
+        this.name = "UnauthorizedError";
+    }
+}
+/**
+ * Thrown when endpoint is not found.
+ */
+export class NotFoundError extends ProxyError {
+    path;
+    constructor(path) {
+        super("not_found", `Endpoint not found: ${path}`, 404);
+        this.name = "NotFoundError";
+        this.path = path;
+    }
+}

package/dist/proxy/gate-client.d.ts

@@ -0,0 +1,34 @@
+/**
+ * GateClient - HTTP client for token2chat Gate with retry logic.
+ */
+import { type Logger } from "./types.js";
+export interface GateClientOptions {
+    fetchFn?: typeof fetch;
+    logger?: Logger;
+}
+export interface GateRequestOptions {
+    path: string;
+    body: string;
+    token: string;
+    gateUrl?: string;
+    stream?: boolean;
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+}
+export interface GateResponse {
+    status: number;
+    body?: string;
+    stream?: ReadableStream<Uint8Array>;
+    contentType?: string;
+    changeToken?: string;
+    refundToken?: string;
+    retriesExhausted?: boolean;
+}
+export declare class GateClient {
+    private readonly gateUrl;
+    private readonly fetchFn;
+    private readonly logger;
+    constructor(gateUrl: string, options?: GateClientOptions);
+    request(options: GateRequestOptions): Promise<GateResponse>;
+}

package/dist/proxy/gate-client.js

@@ -0,0 +1,81 @@
+/**
+ * GateClient - HTTP client for token2chat Gate with retry logic.
+ */
+import { defaultLogger, parseRetryAfter, MAX_RETRY_DELAY_MS } from "./types.js";
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class GateClient {
+    gateUrl;
+    fetchFn;
+    logger;
+    constructor(gateUrl, options = {}) {
+        this.gateUrl = gateUrl;
+        this.fetchFn = options.fetchFn ?? fetch;
+        this.logger = options.logger ?? defaultLogger;
+    }
+    async request(options) {
+        const { path, body, token, gateUrl = this.gateUrl, stream = false, maxRetries = 0, baseDelayMs = 2000, maxDelayMs = MAX_RETRY_DELAY_MS, } = options;
+        const url = `${gateUrl}${path}`;
+        let lastResponse = null;
+        let lastBody;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const res = await this.fetchFn(url, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        "X-Cashu": token,
+                    },
+                    body,
+                });
+                // Extract change/refund tokens
+                const changeToken = res.headers.get("X-Cashu-Change") ?? undefined;
+                const refundToken = res.headers.get("X-Cashu-Refund") ?? undefined;
+                const contentType = res.headers.get("content-type") ?? undefined;
+                // If not 429, return immediately
+                if (res.status !== 429) {
+                    if (stream && res.body) {
+                        return {
+                            status: res.status,
+                            stream: res.body,
+                            contentType,
+                            changeToken,
+                            refundToken,
+                        };
+                    }
+                    return {
+                        status: res.status,
+                        body: await res.text(),
+                        contentType,
+                        changeToken,
+                        refundToken,
+                    };
+                }
+                // Store for potential return after retries exhausted
+                lastResponse = res;
+                lastBody = await res.text();
+                // Log and wait before retry
+                if (attempt < maxRetries) {
+                    const retryAfterMs = parseRetryAfter(res.headers.get("Retry-After"));
+                    const backoffMs = Math.min(retryAfterMs ?? baseDelayMs * Math.pow(2, attempt), maxDelayMs);
+                    this.logger.warn(`Rate limited (429), retrying in ${backoffMs}ms...`);
+                    await sleep(backoffMs);
+                }
+            }
+            catch (e) {
+                this.logger.error("Gate request failed:", e);
+                throw e;
+            }
+        }
+        // All retries exhausted
+        return {
+            status: lastResponse.status,
+            body: lastBody,
+            contentType: lastResponse.headers.get("content-type") ?? undefined,
+            changeToken: lastResponse.headers.get("X-Cashu-Change") ?? undefined,
+            refundToken: lastResponse.headers.get("X-Cashu-Refund") ?? undefined,
+            retriesExhausted: true,
+        };
+    }
+}

package/dist/proxy/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Proxy module exports.
+ */
+export * from "./types.js";
+export * from "./errors.js";
+export { PricingCache, type PricingCacheOptions } from "./pricing.js";
+export { GateClient, type GateClientOptions, type GateRequestOptions, type GateResponse } from "./gate-client.js";
+export { PaymentService, type PaymentServiceOptions, type Wallet, type TokenSelectionResult, type GateTokensResult } from "./payment-service.js";
+export { createAuthChecker, type AuthChecker, type AuthRequest } from "./auth.js";
+export { handleError, sendError, sendJsonResponse, type ResponseWriter } from "./response.js";

package/dist/proxy/index.js

@@ -0,0 +1,17 @@
+/**
+ * Proxy module exports.
+ */
+// Types and utilities
+export * from "./types.js";
+// Error classes
+export * from "./errors.js";
+// Pricing cache
+export { PricingCache } from "./pricing.js";
+// Gate client
+export { GateClient } from "./gate-client.js";
+// Payment service
+export { PaymentService } from "./payment-service.js";
+// Auth
+export { createAuthChecker } from "./auth.js";
+// Response utilities
+export { handleError, sendError, sendJsonResponse } from "./response.js";

package/dist/proxy/payment-service.d.ts

@@ -0,0 +1,65 @@
+/**
+ * PaymentService - Handles ecash payment operations for proxy requests.
+ */
+import { type Logger } from "./types.js";
+/**
+ * Minimal wallet interface for PaymentService.
+ */
+export interface Wallet {
+    balance: number;
+    selectAndEncode(amount: number): Promise<string>;
+    receiveToken(token: string): Promise<number>;
+}
+export interface PaymentServiceOptions {
+    wallet: Wallet;
+    logger?: Logger;
+    appendFailedToken?: (token: string, type: "change" | "refund", error: string) => Promise<void>;
+    lowBalanceThreshold?: number;
+}
+export interface TokenSelectionResult {
+    token: string;
+    balanceBefore: number;
+    balanceAfter: number;
+}
+export interface GateTokensResult {
+    changeSat: number;
+    refundSat: number;
+}
+export declare class PaymentService {
+    private readonly wallet;
+    private readonly logger;
+    private readonly appendFailedToken;
+    private readonly lowBalanceThreshold;
+    constructor(options: PaymentServiceOptions);
+    /**
+     * Check if wallet has sufficient balance for the request.
+     * @throws InsufficientBalanceError if balance is insufficient
+     */
+    checkBalance(required: number, model: string): boolean;
+    /**
+     * Select and encode tokens for payment.
+     */
+    selectToken(amount: number): Promise<TokenSelectionResult>;
+    /**
+     * Receive change token from Gate.
+     * Returns amount received, or 0 if failed.
+     */
+    receiveChange(token: string): Promise<number>;
+    /**
+     * Receive refund token from Gate.
+     * Returns amount received, or 0 if failed.
+     */
+    receiveRefund(token: string): Promise<number>;
+    /**
+     * Process change and refund tokens from Gate response.
+     */
+    processGateTokens(changeToken?: string, refundToken?: string): Promise<GateTokensResult>;
+    /**
+     * Check and warn if balance is below threshold.
+     */
+    checkLowBalance(): void;
+    /**
+     * Get current wallet balance.
+     */
+    getBalance(): number;
+}

package/dist/proxy/payment-service.js

@@ -0,0 +1,101 @@
+/**
+ * PaymentService - Handles ecash payment operations for proxy requests.
+ */
+import { defaultLogger } from "./types.js";
+import { InsufficientBalanceError } from "./errors.js";
+export class PaymentService {
+    wallet;
+    logger;
+    appendFailedToken;
+    lowBalanceThreshold;
+    constructor(options) {
+        this.wallet = options.wallet;
+        this.logger = options.logger ?? defaultLogger;
+        this.appendFailedToken = options.appendFailedToken ?? (async () => { });
+        this.lowBalanceThreshold = options.lowBalanceThreshold ?? 100;
+    }
+    /**
+     * Check if wallet has sufficient balance for the request.
+     * @throws InsufficientBalanceError if balance is insufficient
+     */
+    checkBalance(required, model) {
+        const balance = this.wallet.balance;
+        if (balance < required) {
+            this.logger.warn(`Insufficient balance: ${balance} < ${required} for ${model}`);
+            throw new InsufficientBalanceError(balance, required, model);
+        }
+        return true;
+    }
+    /**
+     * Select and encode tokens for payment.
+     */
+    async selectToken(amount) {
+        const balanceBefore = this.wallet.balance;
+        const token = await this.wallet.selectAndEncode(amount);
+        const balanceAfter = this.wallet.balance;
+        return { token, balanceBefore, balanceAfter };
+    }
+    /**
+     * Receive change token from Gate.
+     * Returns amount received, or 0 if failed.
+     */
+    async receiveChange(token) {
+        try {
+            const amount = await this.wallet.receiveToken(token);
+            this.logger.info(`Received ${amount} change`);
+            return amount;
+        }
+        catch (e) {
+            const errMsg = e instanceof Error ? e.message : String(e);
+            this.logger.warn(`Failed to store change: ${errMsg}`);
+            await this.appendFailedToken(token, "change", errMsg);
+            return 0;
+        }
+    }
+    /**
+     * Receive refund token from Gate.
+     * Returns amount received, or 0 if failed.
+     */
+    async receiveRefund(token) {
+        try {
+            const amount = await this.wallet.receiveToken(token);
+            this.logger.info(`Received ${amount} refund`);
+            return amount;
+        }
+        catch (e) {
+            const errMsg = e instanceof Error ? e.message : String(e);
+            this.logger.warn(`Failed to store refund: ${errMsg}`);
+            await this.appendFailedToken(token, "refund", errMsg);
+            return 0;
+        }
+    }
+    /**
+     * Process change and refund tokens from Gate response.
+     */
+    async processGateTokens(changeToken, refundToken) {
+        let changeSat = 0;
+        let refundSat = 0;
+        if (changeToken) {
+            changeSat = await this.receiveChange(changeToken);
+        }
+        if (refundToken) {
+            refundSat = await this.receiveRefund(refundToken);
+        }
+        return { changeSat, refundSat };
+    }
+    /**
+     * Check and warn if balance is below threshold.
+     */
+    checkLowBalance() {
+        const balance = this.wallet.balance;
+        if (balance < this.lowBalanceThreshold) {
+            this.logger.warn(`⚠️ Low ecash balance: ${balance} (threshold: ${this.lowBalanceThreshold})`);
+        }
+    }
+    /**
+     * Get current wallet balance.
+     */
+    getBalance() {
+        return this.wallet.balance;
+    }
+}

package/dist/proxy/pricing.d.ts

@@ -0,0 +1,37 @@
+/**
+ * PricingCache - Caches model pricing from Gate with TTL.
+ */
+export interface PricingCacheOptions {
+    ttlMs?: number;
+    fetchFn?: typeof fetch;
+}
+export declare class PricingCache {
+    private cache;
+    private fetchedAt;
+    private fetchPromise;
+    private readonly gateUrl;
+    private readonly ttlMs;
+    private readonly fetchFn;
+    constructor(gateUrl: string, options?: PricingCacheOptions);
+    /**
+     * Get cached pricing, refreshing if stale.
+     */
+    get(): Promise<Record<string, number>>;
+    /**
+     * Force refresh pricing from gate.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Clear cache, forcing next get() to refetch.
+     */
+    invalidate(): void;
+    /**
+     * Get price for a model. Uses wildcard "*" or default if not found.
+     */
+    getPrice(model: string, defaultPrice?: number): number;
+    /**
+     * Get list of available models (excludes wildcard).
+     */
+    getModels(): string[];
+    private doFetch;
+}

package/dist/proxy/pricing.js

@@ -0,0 +1,90 @@
+/**
+ * PricingCache - Caches model pricing from Gate with TTL.
+ */
+const DEFAULT_TTL_MS = 5 * 60_000; // 5 minutes
+const DEFAULT_PRICE = 500; // units
+export class PricingCache {
+    cache = null;
+    fetchedAt = 0;
+    fetchPromise = null;
+    gateUrl;
+    ttlMs;
+    fetchFn;
+    constructor(gateUrl, options = {}) {
+        this.gateUrl = gateUrl;
+        this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        this.fetchFn = options.fetchFn ?? fetch;
+    }
+    /**
+     * Get cached pricing, refreshing if stale.
+     */
+    async get() {
+        const now = Date.now();
+        if (this.cache && now - this.fetchedAt < this.ttlMs) {
+            return this.cache;
+        }
+        // Deduplicate concurrent fetches
+        if (this.fetchPromise) {
+            return this.fetchPromise;
+        }
+        this.fetchPromise = this.doFetch();
+        try {
+            return await this.fetchPromise;
+        }
+        finally {
+            this.fetchPromise = null;
+        }
+    }
+    /**
+     * Force refresh pricing from gate.
+     */
+    async refresh() {
+        this.fetchPromise = null;
+        await this.doFetch();
+    }
+    /**
+     * Clear cache, forcing next get() to refetch.
+     */
+    invalidate() {
+        this.cache = null;
+        this.fetchedAt = 0;
+        this.fetchPromise = null;
+    }
+    /**
+     * Get price for a model. Uses wildcard "*" or default if not found.
+     */
+    getPrice(model, defaultPrice = DEFAULT_PRICE) {
+        if (!this.cache) {
+            return defaultPrice;
+        }
+        return this.cache[model] ?? this.cache["*"] ?? defaultPrice;
+    }
+    /**
+     * Get list of available models (excludes wildcard).
+     */
+    getModels() {
+        if (!this.cache) {
+            return [];
+        }
+        return Object.keys(this.cache).filter((m) => m !== "*");
+    }
+    async doFetch() {
+        try {
+            const res = await this.fetchFn(`${this.gateUrl}/v1/pricing`);
+            if (!res.ok) {
+                return this.cache ?? {};
+            }
+            const data = (await res.json());
+            const prices = {};
+            for (const [model, rule] of Object.entries(data.models)) {
+                prices[model] = rule.per_request;
+            }
+            this.cache = prices;
+            this.fetchedAt = Date.now();
+            return prices;
+        }
+        catch {
+            return this.cache ?? {};
+        }
+    }
+}

package/dist/proxy/response.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Response utilities and error handler for proxy.
+ */
+import { type Logger } from "./types.js";
+/**
+ * Minimal response writer interface.
+ */
+export interface ResponseWriter {
+    writeHead(status: number, headers?: Record<string, string>): void;
+    end(body?: string): void;
+}
+/**
+ * Send a JSON response.
+ */
+export declare function sendJsonResponse(res: ResponseWriter, status: number, body?: unknown): void;
+/**
+ * Send an error response in OpenAI-compatible format.
+ */
+export declare function sendError(res: ResponseWriter, status: number, code: string, message: string, type?: string): void;
+/**
+ * Handle an error and send appropriate response.
+ * Supports ProxyError subclasses and standard Errors.
+ */
+export declare function handleError(res: ResponseWriter, error: unknown, logger?: Logger): void;

package/dist/proxy/response.js

@@ -0,0 +1,48 @@
+/**
+ * Response utilities and error handler for proxy.
+ */
+import { defaultLogger } from "./types.js";
+import { ProxyError } from "./errors.js";
+/**
+ * Send a JSON response.
+ */
+export function sendJsonResponse(res, status, body) {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(body ?? {}));
+}
+/**
+ * Send an error response in OpenAI-compatible format.
+ */
+export function sendError(res, status, code, message, type) {
+    const error = { code, message };
+    if (type)
+        error.type = type;
+    sendJsonResponse(res, status, { error });
+}
+/**
+ * Handle an error and send appropriate response.
+ * Supports ProxyError subclasses and standard Errors.
+ */
+export function handleError(res, error, logger = defaultLogger) {
+    // Handle ProxyError (and subclasses)
+    if (error instanceof ProxyError) {
+        logger.error("Proxy error:", error);
+        sendJsonResponse(res, error.httpStatus, error.toJSON());
+        return;
+    }
+    // Handle standard Error
+    if (error instanceof Error) {
+        logger.error("Proxy error:", error);
+        // Special case for body too large
+        if (error.message === "Request body too large") {
+            sendError(res, 413, "payload_too_large", "Request body too large");
+            return;
+        }
+        // Generic internal error
+        sendError(res, 500, "proxy_error", "Internal proxy error");
+        return;
+    }
+    // Handle unknown error types
+    logger.error("Proxy error:", error);
+    sendError(res, 500, "proxy_error", "Internal proxy error");
+}

package/dist/proxy/sse-parser.d.ts

@@ -0,0 +1,19 @@
+/**
+ * SSE stream parser that extracts cashu-change events.
+ *
+ * The Gate emits change tokens via `event: cashu-change` SSE events
+ * during streaming responses. This parser intercepts those events,
+ * extracts the token, and filters them out so they are not forwarded
+ * to the AI tool.
+ */
+export interface SSEFilterResult {
+    /** The filtered stream with cashu-change events removed. */
+    filtered: ReadableStream<Uint8Array>;
+    /** Returns the extracted change token (available after stream is consumed). */
+    changeToken: () => string | undefined;
+}
+/**
+ * Create a TransformStream that filters out `event: cashu-change` SSE events
+ * and captures the token data.
+ */
+export declare function extractCashuChangeFromSSE(input: ReadableStream<Uint8Array>): SSEFilterResult;