@visgate_ai/client 0.2.17

package/dist/index.d.cts

@@ -0,0 +1,511 @@
+/** Billing: GET /billing/stats, /billing/info, /billing/pricing, POST /billing/checkout, /billing/subscription */
+
+interface BillingInfo {
+    tier: string;
+    balanceMicro: number;
+    billingStatus: string;
+    monthlyBudgetCents?: number | null;
+    usageThisMonthCents?: number;
+    supportEmail?: string | null;
+    companyName?: string | null;
+    freeModeEnabled?: boolean;
+}
+declare function billingInfoFromResponse(data: Record<string, unknown>): BillingInfo;
+interface ModelPricing {
+    id: string;
+    providerType: string;
+    model: string;
+    modelName: string;
+    modelType: string;
+    modelClass?: string | null;
+    costPerUnitMicro: number;
+    usageCount: number;
+    totalSavingsMicro: number;
+    avgSavingsMicro: number;
+}
+declare function modelPricingFromResponse(data: Record<string, unknown>): ModelPricing;
+interface PricingResponse {
+    lastUpdated: string | null;
+    pricing: ModelPricing[];
+}
+declare function pricingResponseFromResponse(data: Record<string, unknown>): PricingResponse;
+interface CheckoutOptions {
+    customerEmail?: string | null;
+    firebaseUid?: string | null;
+}
+declare class Billing {
+    private _client;
+    constructor(_client: Client);
+    /** Public billing stats for landing/marketing (GET /billing/stats). May not require auth. */
+    getStats(): Promise<Record<string, unknown>>;
+    /** Organization billing info (GET /billing/info). */
+    getInfo(): Promise<BillingInfo>;
+    /** Create checkout session (POST /billing/checkout). */
+    checkout(amountDollars: number, returnUrl: string, options?: CheckoutOptions): Promise<Record<string, unknown>>;
+    /** Get pricing for all models (GET /billing/pricing). */
+    getPricing(): Promise<PricingResponse>;
+    /** Update organization subscription tier (POST /billing/subscription). */
+    updateSubscription(tier: string): Promise<{
+        success: boolean;
+        tier: string;
+    }>;
+}
+
+/** Unified image generation: POST /generate */
+
+interface GenerateResult {
+    id: string;
+    status: string;
+    imageUrl: string | null;
+    images: string[];
+    model: string;
+    provider: string;
+    mode: string;
+    cost: number;
+    costPerMegapixel: number;
+    latencyMs: number;
+    resolution: Record<string, number>;
+    createdAt: Date | null;
+}
+declare function generateResultFromResponse(data: Record<string, unknown>): GenerateResult;
+declare class Generate {
+    private _client;
+    constructor(_client: Client);
+    __call__(prompt: string, model?: string, params?: Record<string, unknown>): Promise<GenerateResult>;
+}
+
+/** Image generation: POST /images/generate */
+
+interface ImageResult {
+    id: string;
+    /** Request status: "success" | "cached" | "failed" */
+    status?: string;
+    images: string[];
+    model: string;
+    provider: string;
+    cost: number;
+    /** True when response was served from cache (exact or semantic match). */
+    cacheHit: boolean;
+    latencyMs: number | null;
+    savedAmount?: number;
+    marginPercent?: number;
+    /** When cache hit: "exact" (hash match) or "semantic" (similarity match). Optional if API returns it. */
+    cacheSource?: "exact" | "semantic" | null;
+    createdAt: Date | null;
+}
+declare function imageResultFromResponse(data: Record<string, unknown>): ImageResult;
+interface ImagesGenerateOptions {
+    negativePrompt?: string | null;
+    width?: number;
+    height?: number;
+    numImages?: number;
+    seed?: number | null;
+    /** Input image URL for image-to-image */
+    imageUrl?: string | null;
+    /** Prefer cache (exact or semantic match). Default true. Set false to force fresh generation. */
+    preferCache?: boolean;
+    /** Max acceptable latency in ms; API may use for routing. */
+    maxLatencyMs?: number | null;
+    /** URL to call when generation is complete (async callback). */
+    webhookUrl?: string | null;
+    /** ID to include in the callback payload. */
+    callbackId?: string | null;
+    params?: Record<string, unknown>;
+}
+declare class Images {
+    private _client;
+    constructor(_client: Client);
+    generate(model: string, prompt: string, options?: ImagesGenerateOptions): Promise<ImageResult>;
+}
+
+/** Model catalog: GET /models */
+
+interface ModelInfo {
+    id: string;
+    name: string;
+    provider: string;
+    mediaType: string;
+    description?: string | null;
+    category?: string | null;
+    tags: string[];
+    coverImageUrl?: string | null;
+    author?: string | null;
+    url?: string | null;
+    baseCostMicro: number;
+    normalizedCostMicro: number;
+    pricing?: string | null;
+    pricingUnit?: string | null;
+    runCount: number;
+    inputTypes: string[];
+    outputType?: string | null;
+    capabilities: string[];
+    firstSeenAt?: string | null;
+    providerCreatedAt?: string | null;
+    lastSyncedAt?: string | null;
+    compliance?: Record<string, unknown> | null;
+}
+declare function modelInfoFromResponse(data: Record<string, unknown>): ModelInfo;
+interface FeaturedSection {
+    title: string;
+    key: string;
+    models: ModelInfo[];
+}
+declare function featuredSectionFromResponse(data: Record<string, unknown>): FeaturedSection;
+interface ModelsResponse {
+    models: ModelInfo[];
+    totalCount: number;
+    lastUpdated?: string | null;
+    featured?: FeaturedSection[] | null;
+}
+declare function modelsResponseFromResponse(data: Record<string, unknown>): ModelsResponse;
+interface ModelsListOptions {
+    provider?: string | null;
+    mediaType?: string | null;
+    capability?: string | null;
+    search?: string | null;
+    sort?: string | null;
+    limit?: number;
+    featured?: boolean;
+}
+declare class Models {
+    private _client;
+    constructor(_client: Client);
+    list(options?: ModelsListOptions): Promise<ModelsResponse>;
+    get(modelId: string): Promise<ModelInfo>;
+    search(query: string, limit?: number): Promise<ModelsResponse>;
+}
+
+/** Provider key management and balance resources */
+
+interface ProviderKeyInfo {
+    provider: string;
+    validated: boolean;
+    validatedAt?: string | null;
+    maskedKey?: string | null;
+}
+declare function providerKeyInfoFromResponse(data: Record<string, unknown>): ProviderKeyInfo;
+interface ProviderKeysResponse {
+    keys: ProviderKeyInfo[];
+}
+declare function providerKeysResponseFromResponse(data: Record<string, unknown>): ProviderKeysResponse;
+interface ProviderValidationResult {
+    valid: boolean;
+    message: string;
+}
+declare function providerValidationResultFromResponse(data: Record<string, unknown>): ProviderValidationResult;
+interface ProviderBalanceItem {
+    provider: string;
+    configured: boolean;
+    available: boolean;
+    limit?: number | null;
+    remaining?: number | null;
+    currency?: string | null;
+    message?: string | null;
+}
+declare function providerBalanceItemFromResponse(data: Record<string, unknown>): ProviderBalanceItem;
+interface ProviderBalancesResponse {
+    balances: ProviderBalanceItem[];
+}
+declare function providerBalancesResponseFromResponse(data: Record<string, unknown>): ProviderBalancesResponse;
+declare class Providers {
+    private _client;
+    constructor(_client: Client);
+    listKeys(): Promise<ProviderKeysResponse>;
+    setKey(provider: string, apiKey: string): Promise<ProviderKeyInfo>;
+    deleteKey(provider: string): Promise<Record<string, unknown>>;
+    validateKey(provider: string, apiKey: string): Promise<ProviderValidationResult>;
+    balances(): Promise<ProviderBalancesResponse>;
+}
+
+/**
+ * Async generation request status: GET /v1/requests/{request_id}
+ * Used after POST /videos/generate or /images/generate with Prefer: respond-async (202).
+ */
+
+interface RequestStatusResult {
+    requestId: string;
+    status: "pending" | "processing" | "completed" | "failed";
+    mediaType: string;
+    provider: string;
+    model: string;
+    outputUrl: string | null;
+    errorMessage: string | null;
+    createdAt: string | null;
+    completedAt: string | null;
+}
+declare function requestStatusFromResponse(data: Record<string, unknown>): RequestStatusResult;
+declare class Requests {
+    private _client;
+    constructor(_client: Client);
+    /** Get status of an async generation request (video/image). */
+    get(requestId: string): Promise<RequestStatusResult>;
+}
+
+/** Usage and billing: GET /usage, /usage/logs, /dashboard */
+
+/** Dashboard response shape (GET /dashboard). */
+interface DashboardResponse {
+    total_generations: number;
+    total_cost_usd: number;
+    avg_latency_ms: number;
+    cache_hit_rate: number;
+    cached_requests: number;
+    success_rate: number;
+    cost_per_day: Array<{
+        date: string;
+        cost_usd: number;
+        requests: number;
+    }>;
+    top_models_used: Array<{
+        model: string;
+        count: number;
+        total_cost_usd: number;
+    }>;
+    period_days: number;
+}
+interface UsageSummary {
+    totalRequests: number;
+    successfulRequests: number;
+    failedRequests: number;
+    cachedRequests: number;
+    totalProviderCost: number;
+    totalBilledCost: number;
+    totalSavings: number;
+    byProvider: Record<string, number>;
+    byModel: Record<string, number>;
+    period: string;
+    periodStart: Date | null;
+    periodEnd: Date | null;
+    cacheHitRate: number;
+    /** Average latency in seconds (from API avg_latency) */
+    avgLatency?: number;
+    /** Raw provider breakdown: provider -> { requests, cost, ... } */
+    providerBreakdown?: Record<string, {
+        requests: number;
+        cost: number;
+        providerChargeCost?: number;
+        providerEffectiveCost?: number;
+        savingsCost?: number;
+    }>;
+    /** Daily/history records when returned by API */
+    history?: Record<string, unknown>[];
+}
+declare function usageSummaryFromResponse(data: Record<string, unknown>): UsageSummary;
+declare class Usage {
+    private _client;
+    constructor(_client: Client);
+    get(period?: string): Promise<UsageSummary>;
+    logs(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Record<string, unknown>[]>;
+    dashboard(period?: string): Promise<Record<string, unknown>>;
+    /**
+     * Track a download event for a request (POST /usage/downloads).
+     * Increments download_count and adds timestamp to downloaded_at.
+     */
+    trackDownload(requestId: string, outputUrl: string, options?: {
+        mediaType?: string;
+    }): Promise<{
+        success: boolean;
+        request_id: string;
+        download_count: number;
+    }>;
+}
+
+/**
+ * Video generation: POST /videos/generate
+ *
+ * Mirrors the Python SDK example 04_videos_all_providers: managed mode and
+ * BYOK (Fal, Replicate, Runway) with provider-specific model IDs.
+ *
+ * @example Managed (platform keys)
+ * ```ts
+ * const r = await client.videos.generate("fal-ai/veo3", prompt, { durationSeconds: 6, skipGcsUpload: true, preferAsync: true });
+ * ```
+ *
+ * @example BYOK – use client options or proxy env (X-Fal-Key, X-Replicate-Key, X-Runway-Key)
+ * ```ts
+ * // Fal (veo3; alternative: fal-ai/flux-pro)
+ * client.videos.generate("fal-ai/veo3", prompt, { durationSeconds: 6, skipGcsUpload: true, preferAsync: true });
+ * // Replicate
+ * client.videos.generate("replicate/lucataco/cogvideox-5b", prompt, { durationSeconds: 5, skipGcsUpload: true, preferAsync: true });
+ * // Runway
+ * client.videos.generate("runway/gen4_turbo", prompt, { durationSeconds: 5, skipGcsUpload: true, preferAsync: true });
+ * ```
+ */
+
+/** Recommended video model IDs per provider (align with working 06_videos_all_providers; Fal uses veo3). */
+declare const VIDEO_MODEL_PRESETS: {
+    readonly fal: "fal-ai/veo3";
+    readonly replicate: "replicate/lucataco/cogvideox-5b";
+    readonly runway: "runway/gen4_turbo";
+};
+interface VideoResult {
+    id: string;
+    /** Request status: "success" | "cached" | "failed" */
+    status?: string;
+    videoUrl: string | null;
+    model: string;
+    provider: string;
+    cost: number;
+    /** True when response was served from cache (exact or semantic match). */
+    cacheHit: boolean;
+    latencyMs: number | null;
+    savedAmount?: number;
+    marginPercent?: number;
+    /** When cache hit: "exact" (hash match) or "semantic" (similarity match). */
+    cacheSource?: "exact" | "semantic" | null;
+    createdAt: Date | null;
+}
+declare function videoResultFromResponse(data: Record<string, unknown>): VideoResult;
+/** Result when using preferAsync: true — API returns 202, poll client.requests.get(requestId). */
+interface AsyncVideoAccepted {
+    requestId: string;
+    status: "accepted";
+}
+interface VideosGenerateOptions {
+    /** Input image URL for image-to-video. */
+    imageUrl?: string | null;
+    /**
+     * Input image as File or Blob (e.g. from file input). Converted to data URL and sent as image_url.
+     * Takes precedence over imageUrl if both are set.
+     */
+    imageFile?: File | Blob;
+    /** Duration in seconds (default 5). */
+    durationSeconds?: number;
+    fps?: number;
+    /** URL to call when generation is complete (async callback). */
+    webhookUrl?: string | null;
+    /** ID to include in the callback payload. */
+    callbackId?: string | null;
+    /** Skip uploading result to GCS; return provider URL directly. Faster, use when behind short timeouts. */
+    skipGcsUpload?: boolean;
+    /**
+     * Use async mode: API returns 202 immediately, poll client.requests.get(requestId) for status.
+     * Avoids 502 when video takes longer than proxy/Cloudflare timeout.
+     */
+    preferAsync?: boolean;
+    /** Extra provider-specific params (merged into request body). */
+    params?: Record<string, unknown>;
+}
+declare class Videos {
+    private _client;
+    constructor(_client: Client);
+    /**
+     * Generate a video from a prompt (and optional image for img2vid).
+     * Supports managed mode and BYOK (set falKey/replicateKey/runwayKey on client or via proxy env).
+     * Use preferAsync: true to avoid 502 when video takes longer than proxy/Cloudflare timeout.
+     */
+    generate(model: string, prompt: string, options?: VideosGenerateOptions): Promise<VideoResult | AsyncVideoAccepted>;
+}
+
+/**
+ * Visgate API client (all methods return Promises in JS).
+ */
+
+interface ClientOptions {
+    apiKey?: string | null;
+    /** When set, requests go to this URL and no API key is sent (key is added by the proxy). */
+    proxyUrl?: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+    falKey?: string | null;
+    replicateKey?: string | null;
+    runwayKey?: string | null;
+}
+interface RequestInitWithBody {
+    body?: string;
+    headers?: Record<string, string>;
+}
+declare class Client {
+    readonly apiKey: string | null;
+    readonly baseUrl: string;
+    readonly maxRetries: number;
+    readonly timeout: number;
+    private readonly headers;
+    readonly images: Images;
+    readonly models: Models;
+    readonly videos: Videos;
+    readonly requests: Requests;
+    readonly usage: Usage;
+    readonly providers: Providers;
+    readonly billing: Billing;
+    private _generate;
+    constructor(options?: ClientOptions);
+    /**
+     * Generate an image with a single call.
+     */
+    generate(prompt: string, options?: {
+        model?: string;
+        params?: Record<string, unknown>;
+    }): Promise<GenerateResult>;
+    /**
+     * Check API health status.
+     */
+    health(): Promise<Record<string, unknown>>;
+    _request(method: string, path: string, init?: RequestInitWithBody): Promise<unknown>;
+    /** No-op for API compatibility (JS has no connection pool to close). */
+    close(): void;
+    toString(): string;
+}
+/**
+ * Async client — same as Client; all methods return Promises.
+ * Provided for API parity with Python AsyncClient.
+ */
+declare class AsyncClient extends Client {
+    constructor(options?: ClientOptions);
+    toString(): string;
+}
+
+/** Visgate SDK exceptions. All extend VisgateError. */
+interface VisgateErrorDetails {
+    [key: string]: unknown;
+}
+/**
+ * Base exception for all Visgate SDK errors.
+ */
+declare class VisgateError extends Error {
+    readonly message: string;
+    readonly errorCode: string;
+    readonly details: VisgateErrorDetails;
+    readonly statusCode?: number;
+    constructor(message: string, errorCode?: string, details?: VisgateErrorDetails, statusCode?: number);
+    toString(): string;
+}
+/** 401 — invalid or missing API key. */
+declare class AuthenticationError extends VisgateError {
+    constructor(message?: string);
+}
+/** 422 — invalid request parameters. */
+declare class ValidationError extends VisgateError {
+    readonly field?: string;
+    constructor(message: string, field?: string);
+}
+/** 429 — too many requests. */
+declare class RateLimitError extends VisgateError {
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number);
+}
+/** Upstream provider error (e.g. Fal, Replicate, Runway). */
+declare class ProviderError extends VisgateError {
+    readonly provider: string;
+    constructor(message: string, provider?: string);
+}
+/** Request timed out before the server responded. */
+declare class VisgateTimeoutError extends VisgateError {
+    constructor(message?: string);
+}
+/** Network connection failed. */
+declare class VisgateConnectionError extends VisgateError {
+    constructor(message?: string);
+}
+
+/**
+ * Visgate JavaScript/TypeScript SDK — unified client for the Visgate vision AI gateway.
+ */
+
+declare const VERSION = "0.2.2";
+
+export { AsyncClient, type AsyncVideoAccepted, AuthenticationError, Billing, type BillingInfo, type CheckoutOptions, Client, type ClientOptions, type DashboardResponse, type FeaturedSection, Generate, type GenerateResult, type ImageResult, Images, type ImagesGenerateOptions, type ModelInfo, type ModelPricing, Models, type ModelsListOptions, type ModelsResponse, type PricingResponse, type ProviderBalanceItem, type ProviderBalancesResponse, ProviderError, type ProviderKeyInfo, type ProviderKeysResponse, type ProviderValidationResult, Providers, RateLimitError, type RequestStatusResult, Requests, Usage, type UsageSummary, VERSION, VIDEO_MODEL_PRESETS, ValidationError, type VideoResult, Videos, type VideosGenerateOptions, VisgateConnectionError, VisgateError, type VisgateErrorDetails, VisgateTimeoutError, billingInfoFromResponse, featuredSectionFromResponse, generateResultFromResponse, imageResultFromResponse, modelInfoFromResponse, modelPricingFromResponse, modelsResponseFromResponse, pricingResponseFromResponse, providerBalanceItemFromResponse, providerBalancesResponseFromResponse, providerKeyInfoFromResponse, providerKeysResponseFromResponse, providerValidationResultFromResponse, requestStatusFromResponse, usageSummaryFromResponse, videoResultFromResponse };