@tchavi/sdk 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,635 @@
+/** Standard error response from the Tchavi API */
+interface TchaviErrorResponse {
+    error: string;
+    message: string;
+    statusCode: number;
+    details?: unknown;
+}
+/** Paginated list response wrapper */
+interface PaginatedResponse<T> {
+    data: T[];
+    page: number;
+    limit: number;
+    total: number;
+    hasMore: boolean;
+}
+/** Client constructor options */
+interface TchaviClientOptions {
+    /** API key for proxy auth: `sk-tch-...` */
+    apiKey?: string;
+    /** Email for dashboard JWT auth (requires password) */
+    email?: string;
+    /** Password for dashboard JWT auth (requires email) */
+    password?: string;
+    /** Base URL override. Default: http://localhost:3001 */
+    baseURL?: string;
+    /** Max retry attempts on 429/502/503. Default: 2 */
+    maxRetries?: number;
+    /** Request timeout in ms. Default: 60000 */
+    timeout?: number;
+}
+/** Tchavi metadata appended to every proxy response */
+interface TchaviMeta {
+    tier: string;
+    model_type: 'chat' | 'embedding' | 'image';
+    mode: string;
+    mode_effective: string;
+    credits_used: number;
+    credits_remaining: number;
+}
+
+type AuthMode = 'api-key' | 'jwt';
+/**
+ * AuthStrategy holds and refreshes credentials.
+ * - API key mode: static header, no state
+ * - JWT mode: logs in lazily, stores the access token in memory,
+ *   refreshes via /auth/refresh cookie when the token expires
+ */
+declare class AuthStrategy {
+    private mode;
+    private apiKey?;
+    private accessToken?;
+    private tokenExpiresAt?;
+    private baseURL;
+    private email?;
+    private password?;
+    constructor(options: TchaviClientOptions);
+    /**
+     * Returns the Authorization header value for the current request.
+     * For JWT mode, lazily logs in and refreshes the token as needed.
+     */
+    getAuthHeader(): Promise<string>;
+    /** Store a token (e.g. after explicit login() call from AuthResource) */
+    setAccessToken(token: string, expiresInSeconds?: number): void;
+    getMode(): AuthMode;
+    private isTokenExpired;
+    private loginOrRefresh;
+    private tryRefresh;
+    private loginWithPassword;
+}
+
+interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+    /** Skip auth header (used for public endpoints) */
+    skipAuth?: boolean;
+    /** Override timeout for this specific request */
+    timeout?: number;
+}
+/**
+ * Core HTTP client. All resource classes use this.
+ *
+ * Handles:
+ * - Auth header injection
+ * - Query string serialization
+ * - JSON body serialization
+ * - Non-2xx error mapping to typed error classes
+ * - Exponential backoff with jitter for retryable responses
+ * - AbortController-based timeouts
+ */
+declare class HttpClient {
+    private baseURL;
+    private maxRetries;
+    private defaultTimeout;
+    private auth;
+    constructor(auth: AuthStrategy, baseURL: string, maxRetries: number, timeout: number);
+    request<T>(options: RequestOptions): Promise<T>;
+    /**
+     * Returns the raw Response — used for streaming so callers can pipe the body.
+     */
+    requestRaw(options: RequestOptions): Promise<Response>;
+    private buildURL;
+    /** Exponential backoff with full jitter */
+    private backoffMs;
+    private sleep;
+}
+
+/** A raw SSE event from the gateway */
+interface SSEEvent {
+    event?: string;
+    data: string;
+}
+/** Final event emitted after [DONE] with credit metadata */
+interface TchaviEvent {
+    type: 'tchavi';
+    data: TchaviMeta;
+}
+/** A parsed data chunk event */
+interface DataEvent<T = unknown> {
+    type: 'data';
+    data: T;
+}
+/** Signal that the stream has ended */
+interface DoneEvent {
+    type: 'done';
+}
+type StreamEvent<T> = DataEvent<T> | TchaviEvent | DoneEvent;
+
+/**
+ * Wraps an SSE ReadableStream as an AsyncIterable<T>.
+ * Stores the final Tchavi metadata so it can be accessed after iteration.
+ *
+ * @example
+ * ```ts
+ * const stream = await client.chat.completions.create({ ..., stream: true });
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+ * }
+ * console.log('Credits used:', stream.finalMeta()?.credits_used);
+ * ```
+ */
+declare class TchaviStream<T> implements AsyncIterable<T> {
+    private body;
+    private _tchaviMeta;
+    constructor(body: ReadableStream<Uint8Array>);
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    private _consume;
+    /** Returns Tchavi credit metadata once the stream is fully consumed. */
+    finalMeta(): TchaviMeta | null;
+}
+
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | null;
+    name?: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+}
+interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface Tool {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+interface ChatCompletionCreateParamsBase {
+    model: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    top_p?: number;
+    max_tokens?: number;
+    max_completion_tokens?: number;
+    n?: number;
+    stop?: string | string[];
+    presence_penalty?: number;
+    frequency_penalty?: number;
+    logit_bias?: Record<string, number>;
+    user?: string;
+    response_format?: {
+        type: 'text' | 'json_object' | 'json_schema';
+        json_schema?: unknown;
+    };
+    seed?: number;
+    tools?: Tool[];
+    tool_choice?: 'none' | 'auto' | 'required' | {
+        type: 'function';
+        function: {
+            name: string;
+        };
+    };
+    stream_options?: {
+        include_usage?: boolean;
+    };
+}
+interface ChatCompletionCreateParamsNonStreaming extends ChatCompletionCreateParamsBase {
+    stream?: false | null;
+}
+interface ChatCompletionCreateParamsStreaming extends ChatCompletionCreateParamsBase {
+    stream: true;
+}
+type ChatCompletionCreateParams = ChatCompletionCreateParamsNonStreaming | ChatCompletionCreateParamsStreaming;
+interface ChatCompletionUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+interface ChatCompletionChoice {
+    index: number;
+    message: ChatMessage;
+    finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | null;
+    logprobs?: unknown;
+}
+interface ChatCompletion {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: ChatCompletionChoice[];
+    usage?: ChatCompletionUsage;
+    system_fingerprint?: string;
+    tchavi: TchaviMeta;
+}
+interface ChatCompletionChunkChoice {
+    index: number;
+    delta: {
+        role?: 'assistant';
+        content?: string | null;
+        tool_calls?: Partial<ToolCall>[];
+    };
+    finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | null;
+}
+interface ChatCompletionChunk {
+    id: string;
+    object: 'chat.completion.chunk';
+    created: number;
+    model: string;
+    choices: ChatCompletionChunkChoice[];
+    usage?: ChatCompletionUsage;
+    system_fingerprint?: string;
+}
+
+declare class Completions {
+    private http;
+    constructor(http: HttpClient);
+    create(params: ChatCompletionCreateParamsNonStreaming): Promise<ChatCompletion>;
+    create(params: ChatCompletionCreateParamsStreaming): Promise<TchaviStream<ChatCompletionChunk>>;
+}
+
+declare class Chat {
+    readonly completions: Completions;
+    constructor(http: HttpClient);
+}
+
+interface EmbeddingCreateParams {
+    model: string;
+    input: string | string[] | number[] | number[][];
+    encoding_format?: 'float' | 'base64';
+    dimensions?: number;
+    user?: string;
+}
+interface Embedding {
+    object: 'embedding';
+    index: number;
+    embedding: number[];
+}
+interface EmbeddingsResponse {
+    object: 'list';
+    data: Embedding[];
+    model: string;
+    usage: {
+        prompt_tokens: number;
+        total_tokens: number;
+    };
+    tchavi: TchaviMeta;
+}
+
+declare class Embeddings {
+    private http;
+    constructor(http: HttpClient);
+    create(params: EmbeddingCreateParams): Promise<EmbeddingsResponse>;
+}
+
+interface ImageGenerationParams {
+    prompt: string;
+    model?: string;
+    n?: number;
+    quality?: 'low' | 'medium' | 'high' | 'standard' | 'hd' | 'fast' | 'ultra';
+    response_format?: 'url' | 'b64_json';
+    size?: '256x256' | '512x512' | '1024x1024' | '1792x1024' | '1024x1792' | '1536x1024' | '1024x1536';
+    style?: 'vivid' | 'natural';
+    user?: string;
+}
+interface Image {
+    url?: string;
+    b64_json?: string;
+    revised_prompt?: string;
+}
+interface ImagesResponse {
+    created: number;
+    data: Image[];
+    tchavi: TchaviMeta;
+}
+
+declare class Generations {
+    private http;
+    constructor(http: HttpClient);
+    create(params: ImageGenerationParams): Promise<ImagesResponse>;
+}
+
+declare class Images {
+    readonly generations: Generations;
+    constructor(http: HttpClient);
+}
+
+type PackDuration = 'ONE_SHOT' | 'MONTHLY' | 'ANNUAL';
+interface CreditBalance {
+    creditsBalance: number;
+}
+interface CreditPack {
+    id: string;
+    name: string;
+    credits: number;
+    price: number;
+    currency: string;
+    duration: PackDuration;
+    maxKeys: number;
+    rateLimit: number;
+    isActive: boolean;
+    description: string | null;
+}
+
+declare class Credits {
+    private http;
+    constructor(http: HttpClient);
+    getBalance(): Promise<CreditBalance>;
+    listPacks(): Promise<CreditPack[]>;
+}
+
+type KeyStatus = 'ACTIVE' | 'REVOKED' | 'EXPIRED' | 'SUSPENDED';
+interface ApiKey {
+    id: string;
+    keyPrefix: string;
+    label: string | null;
+    status: KeyStatus;
+    allowedIps: string[] | null;
+    allowedEndpoints: string[] | null;
+    expiresAt: string | null;
+    lastUsedAt: string | null;
+    createdAt: string;
+}
+/** Returned only at creation — full key is shown once */
+interface ApiKeyWithSecret extends ApiKey {
+    key: string;
+}
+interface CreateApiKeyParams {
+    label?: string;
+    allowedIps?: string[];
+    allowedEndpoints?: string[];
+    expiresAt?: string;
+}
+interface UpdateApiKeyParams {
+    label?: string;
+    allowedIps?: string[];
+    allowedEndpoints?: string[];
+}
+
+declare class ApiKeys {
+    private http;
+    constructor(http: HttpClient);
+    list(): Promise<ApiKey[]>;
+    create(params?: CreateApiKeyParams): Promise<ApiKeyWithSecret>;
+    retrieve(id: string): Promise<ApiKey>;
+    update(id: string, params: UpdateApiKeyParams): Promise<ApiKey>;
+    delete(id: string): Promise<{
+        message: string;
+    }>;
+}
+
+type UsagePeriod = 'day' | 'week' | 'month';
+type LogStatus = 'SUCCESS' | 'ERROR' | 'RATE_LIMITED';
+interface UsageStats {
+    totalRequests: number;
+    totalTokens: number;
+    totalCreditsUsed: number;
+    periodStart: string;
+    periodEnd: string;
+}
+interface UsageLog {
+    id: string;
+    apiKeyPrefix?: string;
+    endpoint: string;
+    model: string;
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    creditsCharged: number;
+    latencyMs: number | null;
+    status: LogStatus;
+    errorCode: string | null;
+    createdAt: string;
+}
+interface GetStatsParams {
+    period?: UsagePeriod;
+}
+interface GetHistoryParams {
+    page?: number;
+    limit?: number;
+    model?: string;
+    endpoint?: string;
+    startDate?: string;
+    endDate?: string;
+}
+
+declare class Usage {
+    private http;
+    constructor(http: HttpClient);
+    getStats(params?: GetStatsParams): Promise<UsageStats>;
+    getHistory(params?: GetHistoryParams): Promise<PaginatedResponse<UsageLog>>;
+}
+
+type ModelTier = 'NANO' | 'STANDARD' | 'PRO' | 'PREMIUM';
+type ModelType = 'chat' | 'embedding' | 'image';
+interface ModelTierConfig {
+    id: string;
+    modelId: string;
+    tier: ModelTier;
+    creditsPerKInput: number;
+    creditsPerKOutput: number;
+    displayName: string;
+    provider: string;
+    supportsFlex: boolean;
+    isActive: boolean;
+}
+
+declare class Models {
+    private http;
+    constructor(http: HttpClient);
+    /** Lists all active model tiers. Pass `all: true` to include inactive ones (admin only). */
+    list(params?: {
+        all?: boolean;
+    }): Promise<ModelTierConfig[]>;
+}
+
+type PaymentStatus = 'PENDING' | 'COMPLETED' | 'FAILED' | 'REFUNDED';
+type PaymentProvider = 'KKIAPAY' | 'PAWAPAY' | 'PAYSTACK' | 'STRIPE';
+interface Payment {
+    id: string;
+    packId: string;
+    packName?: string;
+    amount: number;
+    currency: string;
+    provider: PaymentProvider;
+    status: PaymentStatus;
+    creditsGranted: number;
+    createdAt: string;
+    completedAt: string | null;
+}
+interface InitiatePaymentParams {
+    packId: string;
+    phone?: string;
+    correspondent?: string;
+}
+interface PaymentInitiateResponse {
+    paymentId: string;
+    status: PaymentStatus;
+    redirectUrl?: string;
+    depositId?: string;
+}
+
+declare class Payments {
+    private http;
+    constructor(http: HttpClient);
+    initiate(params: InitiatePaymentParams): Promise<PaymentInitiateResponse>;
+    getStatus(id: string): Promise<Payment>;
+    getHistory(params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<Payment>>;
+}
+
+interface LoginParams {
+    email: string;
+    password: string;
+}
+interface RegisterParams {
+    email: string;
+    password: string;
+    name?: string;
+}
+interface LoginResponse {
+    accessToken: string;
+    user: User;
+}
+interface User {
+    id: string;
+    email: string;
+    name: string | null;
+    role: 'USER' | 'ADMIN';
+    status: 'ACTIVE' | 'SUSPENDED' | 'BANNED' | 'DELETED';
+    emailVerified: boolean;
+    creditsBalance: number;
+    createdAt: string;
+}
+interface UpdateUserParams {
+    name?: string;
+    email?: string;
+    language?: 'fr' | 'en';
+    currentPassword?: string;
+    newPassword?: string;
+}
+
+declare class AuthResource {
+    private http;
+    private authStrategy;
+    constructor(http: HttpClient, authStrategy: AuthStrategy);
+    login(email: string, password: string): Promise<LoginResponse>;
+    register(params: RegisterParams): Promise<{
+        message: string;
+        user: User;
+    }>;
+    logout(): Promise<{
+        message: string;
+    }>;
+}
+
+declare class Users {
+    private http;
+    constructor(http: HttpClient);
+    me(): Promise<User>;
+    update(params: UpdateUserParams): Promise<User>;
+}
+
+/**
+ * Main Tchavi client. Mirrors the OpenAI SDK's resource-based API.
+ *
+ * @example API key mode (proxy endpoints):
+ * ```ts
+ * import Tchavi from '@tchavi/sdk';
+ *
+ * const client = new Tchavi({ apiKey: 'sk-tch-...' });
+ *
+ * const completion = await client.chat.completions.create({
+ *   model: 'gpt-4o-mini',
+ *   messages: [{ role: 'user', content: 'Hello' }],
+ * });
+ * console.log(completion.choices[0].message.content);
+ * console.log(completion.tchavi.credits_used);
+ * ```
+ *
+ * @example JWT mode (account management):
+ * ```ts
+ * const client = new Tchavi({ email: 'me@example.com', password: 'S3cret!' });
+ * const balance = await client.credits.getBalance();
+ * const keys = await client.apiKeys.list();
+ * ```
+ *
+ * @example Streaming:
+ * ```ts
+ * const stream = await client.chat.completions.create({
+ *   model: 'gpt-4o',
+ *   messages: [{ role: 'user', content: 'Tell me a story' }],
+ *   stream: true,
+ * });
+ * for await (const chunk of stream) {
+ *   process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+ * }
+ * console.log('\nCredits used:', stream.finalMeta()?.credits_used);
+ * ```
+ */
+declare class Tchavi {
+    readonly chat: Chat;
+    readonly embeddings: Embeddings;
+    readonly images: Images;
+    readonly credits: Credits;
+    readonly apiKeys: ApiKeys;
+    readonly usage: Usage;
+    readonly models: Models;
+    readonly payments: Payments;
+    readonly auth: AuthResource;
+    readonly users: Users;
+    constructor(options: TchaviClientOptions);
+}
+
+/**
+ * Base error for all Tchavi SDK errors.
+ * Catches both network-level and API-level failures.
+ */
+declare class TchaviError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * An error returned by the Tchavi API as a JSON response.
+ * Maps directly to the server's { error, message, statusCode } shape.
+ */
+declare class TchaviAPIError extends TchaviError {
+    readonly statusCode: number;
+    readonly errorCode: string;
+    readonly details?: unknown;
+    readonly headers: Record<string, string>;
+    constructor(response: TchaviErrorResponse, headers?: Record<string, string>);
+    /**
+     * Factory: inspect the raw response and construct the most specific subclass.
+     */
+    static fromResponse(response: TchaviErrorResponse, headers: Record<string, string>): TchaviAPIError;
+}
+
+/** Thrown when the gateway returns 401 (invalid/missing API key or JWT) */
+declare class TchaviAuthenticationError extends TchaviAPIError {
+    constructor(response: TchaviErrorResponse, headers?: Record<string, string>);
+}
+
+/** Thrown on 429. `retryAfter` is in seconds if provided by the server. */
+declare class TchaviRateLimitError extends TchaviAPIError {
+    readonly retryAfter: number | null;
+    constructor(response: TchaviErrorResponse, headers?: Record<string, string>);
+}
+
+/** Thrown on 402. `creditsRemaining` reflects your current balance. */
+declare class TchaviInsufficientCreditsError extends TchaviAPIError {
+    readonly creditsRemaining: number;
+    constructor(response: TchaviErrorResponse, headers?: Record<string, string>);
+}
+
+export { type ApiKey, type ApiKeyWithSecret, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionChunk, type ChatCompletionChunkChoice, type ChatCompletionCreateParams, type ChatCompletionCreateParamsNonStreaming, type ChatCompletionCreateParamsStreaming, type ChatCompletionUsage, type ChatMessage, type CreateApiKeyParams, type CreditBalance, type CreditPack, type DataEvent, type DoneEvent, type Embedding, type EmbeddingCreateParams, type EmbeddingsResponse, type GetHistoryParams, type GetStatsParams, type Image, type ImageGenerationParams, type ImagesResponse, type InitiatePaymentParams, type KeyStatus, type LogStatus, type LoginParams, type LoginResponse, type ModelTier, type ModelTierConfig, type ModelType, type PackDuration, type PaginatedResponse, type Payment, type PaymentInitiateResponse, type PaymentProvider, type PaymentStatus, type RegisterParams, type SSEEvent, type StreamEvent, Tchavi, TchaviAPIError, TchaviAuthenticationError, type TchaviClientOptions, TchaviError, type TchaviErrorResponse, type TchaviEvent, TchaviInsufficientCreditsError, type TchaviMeta, TchaviRateLimitError, TchaviStream, type Tool, type ToolCall, type UpdateApiKeyParams, type UpdateUserParams, type UsageLog, type UsagePeriod, type UsageStats, type User, Tchavi as default };