@outfitcanvas/fitview-sdk 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,729 @@
+/**
+ * Available models for virtual try-on
+ */
+declare enum OutfitCanvasModel {
+    CanvasPro = "canvas-pro",
+    CanvasProFast = "canvas-pro-fast",
+    CanvasStandard = "canvas-standard",
+    CanvasPlus = "canvas-plus",
+    CanvasExpress = "canvas-express",
+    CanvasInstant = "canvas-instant",
+    CanvasFashion = "canvas-fashion",
+    CanvasCasual = "canvas-casual",
+    CanvasFormal = "canvas-formal",
+    Canvas4K = "canvas-4k",
+    CanvasVideo = "canvas-video"
+}
+/**
+ * Image input format
+ */
+interface ImageInput {
+    type: 'url' | 'base64';
+    data: string;
+    mimeType?: string;
+}
+/**
+ * Device information
+ */
+interface DeviceInfo {
+    userAgent?: string;
+    ipAddress?: string;
+    deviceType?: 'mobile' | 'tablet' | 'desktop' | 'other';
+    os?: string;
+    browser?: string;
+}
+/**
+ * User demographics (with consent)
+ */
+interface UserDemographics {
+    ageRange?: string;
+    age?: string;
+    gender?: string;
+    income_bracket?: string;
+    education_level?: string;
+    consentGiven?: boolean;
+}
+/**
+ * Location information
+ */
+interface LocationInfo {
+    country?: string;
+    region?: string;
+    city?: string;
+    timezone?: string;
+    latitude?: number;
+    longitude?: number;
+}
+/**
+ * User preferences
+ */
+interface UserPreferences {
+    styleKeywords?: string[];
+    favoriteBrands?: string[];
+    colorPreferences?: string[];
+}
+/**
+ * User context
+ */
+interface UserContext {
+    device?: DeviceInfo;
+    demographics?: UserDemographics;
+    location?: LocationInfo;
+    preferences?: UserPreferences;
+}
+/** Garment category for multi-garment requests */
+type GarmentType = 'top' | 'bottom' | 'shoes' | 'accessories' | 'dress' | 'outerwear' | 'footwear';
+/** Single garment input (for garments array) */
+interface GarmentInput {
+    image: string | ImageInput;
+    category?: GarmentType;
+    order?: number;
+    recommended_items?: Array<{
+        type: GarmentType;
+        id?: string;
+        name?: string;
+        image_url?: string;
+        metadata?: Record<string, unknown>;
+    }>;
+    size_letters_to_dimensions?: Array<{
+        size: string;
+        dimensions: Record<string, string>;
+    }>;
+    metadata?: Record<string, unknown>;
+}
+/** Director mode options (canvas-pro, canvas-fashion) */
+interface DirectorModeOptions {
+    pose_presets?: Array<'front_facing' | 'left_shoulder' | 'right_shoulder' | 'three_quarter_left' | 'three_quarter_right' | 'profile_left' | 'profile_right' | 'full_body_front' | 'full_body_side'>;
+    number_of_poses?: number;
+    video_style_presets?: Array<'walking' | 'posing' | 'turning' | 'casual' | 'runway' | 'natural' | 'dynamic'>;
+    image_prompt?: string;
+    video_prompt?: string;
+}
+/**
+ * FitView generation request
+ */
+interface FitViewRequest {
+    person_image: string | ImageInput;
+    garment_image?: string | ImageInput;
+    garments?: GarmentInput[];
+    model?: OutfitCanvasModel | string;
+    quality?: 'fast' | 'balanced' | 'high';
+    use_case?: 'casual' | 'fashion' | 'formal';
+    multi_garment_mode?: 'fast' | 'advanced';
+    user_id?: string;
+    session_id?: string;
+    product_id?: string;
+    idempotency_key?: string;
+    webhook_url?: string;
+    video_duration?: 5 | 10;
+    video_length?: 'short' | 'long';
+    ads_mode?: boolean;
+    director_mode?: DirectorModeOptions;
+    context?: UserContext;
+    demographics?: UserDemographics;
+    location?: LocationInfo;
+    usage_preferences?: UsagePreferences;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Usage and content preferences (top-level or in context)
+ */
+interface UsagePreferences {
+    person_image_is_actual_user?: boolean;
+    allow_public_feed?: boolean;
+    occasion?: string;
+    marketing_consent?: boolean;
+}
+/**
+ * FitView result data
+ */
+interface FitViewResultData {
+    fitview_url: string;
+    thumbnail_url?: string;
+    generation_time_ms?: number;
+    model_used?: string;
+    model_version?: string;
+}
+/**
+ * Enriched data
+ */
+interface EnrichedData {
+    detected_garment_category?: string;
+    color_palette?: string[];
+    recommended_colors?: string[];
+    person_attributes?: Record<string, any>;
+    garment_attributes?: Record<string, any>;
+}
+/**
+ * FitView error details
+ */
+/** Retry guidance from the API */
+interface RetryGuidance {
+    shouldRetry?: boolean;
+    retryAfter?: number;
+    maxRetries?: number;
+    guidance?: string;
+    isTransient?: boolean;
+}
+interface FitViewError$1 {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+    retry?: RetryGuidance;
+}
+/**
+ * Response metadata
+ */
+interface ResponseMetadata {
+    api_version?: string;
+    request_id?: string;
+    timestamp?: string;
+    credit_cost?: number;
+    credit_cost_type?: 'estimated' | 'charged';
+    total_time_ms?: number;
+}
+/**
+ * FitView response from API (inner payload; API wraps in { success, data, requestId, timestamp })
+ */
+interface FitViewResponse {
+    job_id: string;
+    status: 'queued' | 'processing' | 'completed' | 'failed';
+    result?: FitViewResultData;
+    enriched_data?: EnrichedData;
+    error?: FitViewError$1;
+    metadata?: ResponseMetadata;
+}
+/** API response envelope */
+interface ApiResponseEnvelope<T> {
+    success: boolean;
+    data?: T;
+    requestId?: string;
+    timestamp?: string;
+    error?: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+}
+/**
+ * Model information
+ */
+interface ModelInfo {
+    id: OutfitCanvasModel;
+    displayName: string;
+    description?: string;
+    creditCost: number;
+    estimatedLatencyMs: number;
+    maxImageSize?: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Batch request
+ */
+interface FitViewBatchRequest {
+    requests: FitViewRequest[];
+}
+/**
+ * Batch result item
+ */
+interface FitViewBatchResultItem {
+    request: FitViewRequest;
+    response?: FitViewResponse;
+    error?: FitViewError$1;
+}
+/**
+ * Batch response
+ */
+interface FitViewBatchResponse {
+    batch_id: string;
+    total_requests: number;
+    success_count: number;
+    failure_count: number;
+    results: FitViewBatchResultItem[];
+    metadata?: ResponseMetadata;
+}
+/** Rate limit add-on item */
+interface RateLimitAddon {
+    id: string;
+    additional_requests_per_minute: number;
+    duration_days: number;
+    expires_at: string;
+    created_at: string;
+}
+/** Billing rate limit add-ons response */
+interface RateLimitAddonsResponse {
+    active_addons: RateLimitAddon[];
+    total_boost: number;
+}
+/** Component health (for readiness) */
+interface ComponentHealth {
+    status: 'up' | 'down' | 'degraded';
+    latency?: number;
+    message?: string;
+}
+/** Health status (ready/live) */
+interface HealthStatus {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    version?: string;
+    uptime?: number;
+    timestamp?: string;
+    checks?: {
+        database?: ComponentHealth;
+        redis?: ComponentHealth;
+        providers?: Record<string, ComponentHealth>;
+    };
+}
+/**
+ * Client configuration options
+ */
+interface FitViewClientOptions {
+    /**
+     * API key for authentication (Bearer token or X-API-Key depending on authMethod)
+     */
+    apiKey: string;
+    /**
+     * Base URL of the API (default: https://api.fitview.com)
+     */
+    baseURL?: string;
+    /**
+     * Request timeout in milliseconds (default: 300000 = 5 minutes)
+     */
+    timeout?: number;
+    /**
+     * API version (default: v1)
+     */
+    apiVersion?: string;
+    /**
+     * Max retries for 429 and 5xx (default: 3). Set 0 to disable.
+     */
+    maxRetries?: number;
+    /**
+     * Base delay in ms between retries (default: 1000). Exponential backoff is used.
+     */
+    retryDelay?: number;
+    /**
+     * Use Bearer token (default) or X-API-Key header
+     */
+    authMethod?: 'bearer' | 'apiKey';
+    /**
+     * Custom fetch implementation
+     */
+    fetch?: typeof fetch;
+    /**
+     * Additional headers to include in requests
+     */
+    headers?: Record<string, string>;
+    /**
+     * Validate image inputs (format, size) before sending (default: true).
+     * Reduces unnecessary API calls and returns clear errors from the SDK.
+     */
+    validateInputImages?: boolean;
+    /**
+     * Optimize base64 images client-side (resize/recompress) when sharp is available (default: false).
+     * Saves backend compute; URLs are not optimized.
+     */
+    optimizeImages?: boolean;
+    /**
+     * Options for client-side image optimization (only used when optimizeImages is true).
+     */
+    optimizeImageOptions?: {
+        maxDimension?: number;
+        jpegQuality?: number;
+        outputFormat?: 'jpeg' | 'png' | 'webp' | 'original';
+    };
+}
+/** Response from the upload image endpoint (POST /fitview/upload) */
+interface UploadImageResponse {
+    url: string;
+    signed_url?: string;
+    filename?: string;
+    size?: number;
+    content_type?: string;
+}
+/**
+ * Wait options for polling
+ */
+interface WaitOptions {
+    /**
+     * Maximum time to wait in milliseconds (default: 300000 = 5 minutes)
+     */
+    timeout?: number;
+    /**
+     * Ms to wait before the first status fetch. Default: 10000 (10 seconds).
+     * ⚠️ Consult FitView support before changing this default; other values may affect rate limits and reliability.
+     */
+    initialDelay?: number;
+    /**
+     * Ms between subsequent status fetches after the first. Default: 2000 (2 seconds).
+     * ⚠️ Consult FitView support before changing this default; other values may affect rate limits and reliability.
+     */
+    interval?: number;
+    /**
+     * Callback function called on each poll
+     */
+    onProgress?: (response: FitViewResponse | any) => void;
+}
+
+/**
+ * FitViewResult - Wrapper class for FitView API responses
+ * Provides convenient methods and getters for working with results
+ */
+declare class FitViewResult {
+    private readonly _response;
+    private readonly _client;
+    constructor(response: FitViewResponse, client: FitViewClient);
+    /**
+     * Get the job ID
+     */
+    get jobId(): string;
+    /**
+     * Get the current status
+     */
+    get status(): FitViewResponse['status'];
+    /**
+     * Get the fitview image URL (if completed)
+     */
+    get fitviewUrl(): string | undefined;
+    /**
+     * Get the thumbnail URL (if available)
+     */
+    get thumbnailUrl(): string | undefined;
+    /**
+     * Get the model used for generation
+     */
+    get modelUsed(): string | undefined;
+    /**
+     * Get the model version
+     */
+    get modelVersion(): string | undefined;
+    /**
+     * Get generation time in milliseconds
+     */
+    get generationTimeMs(): number | undefined;
+    /**
+     * Get enriched data
+     */
+    get enrichedData(): EnrichedData | undefined;
+    /**
+     * Get error information (if failed)
+     */
+    get error(): FitViewError$1 | undefined;
+    /**
+     * Get the full result data
+     */
+    get result(): FitViewResultData | undefined;
+    /**
+     * Get response metadata
+     */
+    get metadata(): FitViewResponse['metadata'];
+    /**
+     * Get the raw API response
+     */
+    get rawResponse(): FitViewResponse;
+    /**
+     * Check if the job is completed
+     */
+    isCompleted(): boolean;
+    /**
+     * Check if the job has failed
+     */
+    isFailed(): boolean;
+    /**
+     * Check if the job is still processing
+     */
+    isProcessing(): boolean;
+    /**
+     * Download the fitview image
+     * @returns Promise resolving to the image as a Buffer or Blob
+     */
+    download(): Promise<Buffer | Blob>;
+    /**
+     * Refresh the result by fetching the latest status from the API
+     * @returns Updated FitViewResult
+     */
+    refresh(): Promise<FitViewResult>;
+    /**
+     * Wait for the job to complete
+     * @param options Wait options
+     * @returns Promise resolving when job completes
+     */
+    waitForCompletion(options?: {
+        timeout?: number;
+        initialDelay?: number;
+        interval?: number;
+        onProgress?: (result: FitViewResult) => void;
+    }): Promise<FitViewResult>;
+    /**
+     * Convert to JSON
+     */
+    toJSON(): FitViewResponse;
+    /**
+     * Convert to string
+     */
+    toString(): string;
+}
+
+/**
+ * FitViewClient - Main client class for interacting with the FitView API
+ */
+declare class FitViewClient {
+    private readonly apiKey;
+    private readonly baseURL;
+    private readonly timeout;
+    private readonly apiVersion;
+    private readonly maxRetries;
+    private readonly retryDelay;
+    readonly fetchImpl: typeof fetch;
+    private readonly headers;
+    private readonly authHeader;
+    private readonly validateInputImages;
+    private readonly optimizeImages;
+    private readonly optimizeImageOptions;
+    constructor(options: FitViewClientOptions);
+    /**
+     * Make an HTTP request with optional retries for 429 and 5xx
+     */
+    private request;
+    private doRequest;
+    /**
+     * Handle error responses from the API. Throws a typed error with a clear message.
+     */
+    private handleErrorResponse;
+    /**
+     * Create a new virtual try-on job. Use URLs or base64 for person_image and garment_image (or garments array).
+     * @param request - FitView generation request. Requires person_image; requires garment_image or garments.
+     * @returns Promise resolving to FitViewResult with jobId, status; call waitForCompletion() or poll getFitView(jobId).
+     * @throws FitViewValidationError if request is invalid, FitViewInsufficientCreditsError on 402, FitViewRateLimitError on 429
+     * @example
+     * const result = await client.generateFitView({ person_image: 'https://...', garment_image: 'https://...', model: OutfitCanvasModel.CanvasStandard });
+     * const completed = await result.waitForCompletion();
+     */
+    generateFitView(request: FitViewRequest): Promise<FitViewResult>;
+    /**
+     * Get the status of a FitView job
+     * @param jobId Job ID (must start with 'fv_')
+     * @returns Promise resolving to FitViewResult
+     */
+    getFitView(jobId: string): Promise<FitViewResult>;
+    /**
+     * Generate multiple virtual try-on results in a batch (max 50)
+     * @param requests Array of FitView requests
+     * @returns Promise resolving to FitViewBatchResponse with batch_id and results
+     */
+    batchGenerateFitView(requests: FitViewRequest[]): Promise<FitViewBatchResponse>;
+    /**
+     * List available models for your account tier
+     * @returns Promise resolving to array of ModelInfo (id, displayName, creditCost, etc.)
+     */
+    listModels(): Promise<ModelInfo[]>;
+    /**
+     * Get active rate limit add-ons and total boost (billing)
+     * @returns Promise resolving to active_addons and total_boost
+     */
+    getRateLimitAddons(): Promise<RateLimitAddonsResponse>;
+    /**
+     * Basic health check (no auth required)
+     * @returns Promise resolving to { status, timestamp }
+     */
+    healthCheck(): Promise<{
+        status: string;
+        timestamp?: string;
+    }>;
+    /**
+     * Readiness check (dependency health; no auth required)
+     * @returns Promise resolving to HealthStatus
+     */
+    readinessCheck(): Promise<HealthStatus>;
+    /**
+     * Liveness check (no auth required)
+     * @returns Promise resolving to { status: 'alive' }
+     */
+    livenessCheck(): Promise<{
+        status: string;
+    }>;
+    /**
+     * Upload an image (base64) to FitView storage and get back a URL.
+     * Use this for device images: upload first, then pass the returned URL to generateFitView.
+     * @param base64Image Base64 string (with or without data:image/...;base64, prefix)
+     * @param filename Optional filename hint for the stored file
+     * @returns Object with url (and optionally signed_url, filename, size, content_type)
+     */
+    uploadImage(base64Image: string, filename?: string): Promise<UploadImageResponse>;
+    /**
+     * Upload an image from a local file path (Node.js only).
+     * Reads the file, encodes as base64, and calls uploadImage. Use for server-side apps.
+     * @param filePath Absolute or relative path to the image file
+     * @param filename Optional filename hint (defaults to the base name of filePath)
+     * @returns Object with url (and optionally signed_url, filename, size, content_type)
+     */
+    uploadImageFromFile(filePath: string, filename?: string): Promise<UploadImageResponse>;
+    /**
+     * Generate a new idempotency key (UUID v4) for create-job requests.
+     * Send this in the `idempotency_key` field when calling generateFitView to safely retry the same request without creating duplicate jobs.
+     */
+    static generateIdempotencyKey(): string;
+    /**
+     * Poll until the job completes, fails, or times out. Defaults: 10s initial delay, then 2s interval.
+     * @param jobId - Job ID (e.g. from generateFitView result)
+     * @param options - Optional timeout (ms), initialDelay (ms), interval (ms), onProgress callback
+     * @returns Promise resolving to completed or failed FitViewResult
+     * @throws FitViewTimeoutError if timeout is reached, FitViewAPIError if job fails
+     * @example
+     * const completed = await client.waitForFitView(result.jobId, { timeout: 300000, onProgress: r => console.log(r.status) });
+     */
+    waitForFitView(jobId: string, options?: WaitOptions): Promise<FitViewResult>;
+    /**
+     * Verify webhook signature
+     * @param payload Raw webhook payload (string or Buffer)
+     * @param signature Signature from X-FitView-Signature header
+     * @param secret Webhook signing secret
+     * @returns True if signature is valid
+     */
+    verifyWebhook(payload: string | Buffer, signature: string, secret: string): boolean;
+}
+
+/**
+ * Generate a new idempotency key (UUID v4) for create-job requests.
+ * Use when calling generateFitView to safely retry the same request without creating duplicate jobs.
+ */
+declare function generateIdempotencyKey(): string;
+
+/**
+ * Base error class for all FitView SDK errors
+ */
+declare class FitViewError extends Error {
+    readonly code: string;
+    readonly statusCode?: number;
+    readonly details?: Record<string, any>;
+    constructor(message: string, code: string, statusCode?: number, details?: Record<string, any>);
+}
+/**
+ * API error - errors returned from the FitView API
+ */
+declare class FitViewAPIError extends FitViewError {
+    readonly response?: Response;
+    constructor(message: string, code: string, statusCode: number, response?: Response, details?: Record<string, any>);
+}
+/**
+ * Validation error - invalid request parameters
+ */
+declare class FitViewValidationError extends FitViewError {
+    readonly validationErrors?: Array<{
+        path: string;
+        message: string;
+    }>;
+    constructor(message: string, validationErrors?: Array<{
+        path: string;
+        message: string;
+    }>);
+}
+/**
+ * Timeout error - request or polling timeout
+ */
+declare class FitViewTimeoutError extends FitViewError {
+    constructor(message?: string);
+}
+/**
+ * Network error - connection or network issues
+ */
+declare class FitViewNetworkError extends FitViewError {
+    readonly originalError?: Error;
+    constructor(message: string, originalError?: Error);
+}
+/**
+ * Authentication error - invalid or missing API key
+ */
+declare class FitViewAuthenticationError extends FitViewError {
+    constructor(message?: string);
+}
+/**
+ * Rate limit error - too many requests
+ */
+declare class FitViewRateLimitError extends FitViewError {
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number);
+}
+/**
+ * Insufficient credits error
+ */
+declare class FitViewInsufficientCreditsError extends FitViewError {
+    readonly available?: number;
+    readonly required?: number;
+    constructor(message?: string, available?: number, required?: number);
+}
+
+/** Max image size in bytes (20MB - matches API) */
+declare const MAX_IMAGE_SIZE_BYTES: number;
+/** Accepted image formats (lowercase, matches API) */
+declare const ACCEPTED_IMAGE_FORMATS: readonly ["jpeg", "jpg", "png", "webp", "heic", "heif"];
+type AcceptedImageFormat = (typeof ACCEPTED_IMAGE_FORMATS)[number];
+/** Result of validating a single image */
+interface ImageValidationResult {
+    valid: boolean;
+    message?: string;
+    sizeBytes?: number;
+    format?: string;
+}
+/** Check if a string looks like valid base64 image data */
+declare function isValidBase64(str: string): boolean;
+/** Get decoded size in bytes from base64 string */
+declare function getBase64Size(base64: string): number;
+/** Detect image format from base64 data URL (e.g. data:image/jpeg;base64,...) */
+declare function detectImageFormat(base64: string): string | null;
+/**
+ * Validate a base64 image: format, size, and structure.
+ * Use this before sending to the API to fail fast and save backend compute.
+ */
+declare function validateBase64Image(base64: string): ImageValidationResult;
+/**
+ * Validate a single image input (URL or base64 string).
+ * URLs are only checked for valid http(s) format; size/format are validated server-side.
+ */
+declare function validateImageInput(input: string): ImageValidationResult;
+/** Constructor for validation errors (e.g. FitViewValidationError) - called with (message: string) */
+type ValidationErrorConstructor = new (message: string) => Error;
+/**
+ * Validate all image inputs in a FitView request.
+ * Call this before generateFitView when validateInputImages is enabled (default).
+ * @throws FitViewValidationError if any image fails validation
+ */
+declare function validateFitViewRequestImages(request: {
+    person_image?: string | {
+        type?: string;
+        data?: string;
+    };
+    garment_image?: string | {
+        type?: string;
+        data?: string;
+    };
+    garments?: Array<{
+        image?: string | {
+            type?: string;
+            data?: string;
+        };
+    }>;
+}, ValidationErrorClass: ValidationErrorConstructor): void;
+
+interface OptimizeImageOptions {
+    /** Max width or height in pixels (default 2048) */
+    maxDimension?: number;
+    /** JPEG quality 1–100 when output is JPEG (default 85) */
+    jpegQuality?: number;
+    /** Output format: jpeg (smaller) or keep original */
+    outputFormat?: 'jpeg' | 'png' | 'webp' | 'original';
+}
+/**
+ * Optimize a base64 image: resize to max dimension and optionally recompress.
+ * Uses sharp if installed; otherwise returns the original string unchanged.
+ * Only works in Node.js (sharp is not used in browser builds).
+ */
+declare function optimizeBase64Image(base64: string, options?: OptimizeImageOptions): Promise<string>;
+/**
+ * Optimize all base64 image fields in a request (in place).
+ * URL inputs are left unchanged. Only runs when optimizeImages is true and sharp is available.
+ */
+declare function optimizeRequestImages(request: Record<string, unknown>, options?: OptimizeImageOptions): Promise<void>;
+
+export { ACCEPTED_IMAGE_FORMATS, type AcceptedImageFormat, type ApiResponseEnvelope, type ComponentHealth, type DeviceInfo, type DirectorModeOptions, type EnrichedData, FitViewAPIError, FitViewAuthenticationError, type FitViewBatchRequest, type FitViewBatchResponse, type FitViewBatchResultItem, FitViewClient, type FitViewClientOptions, FitViewError, type FitViewError$1 as FitViewErrorType, FitViewInsufficientCreditsError, FitViewNetworkError, FitViewRateLimitError, type FitViewRequest, type FitViewResponse, FitViewResult, type FitViewResultData, FitViewTimeoutError, FitViewValidationError, type GarmentInput, type GarmentType, type HealthStatus, type ImageInput, type ImageValidationResult, type LocationInfo, MAX_IMAGE_SIZE_BYTES, type ModelInfo, type OptimizeImageOptions, OutfitCanvasModel, type RateLimitAddon, type RateLimitAddonsResponse, type ResponseMetadata, type RetryGuidance, type UploadImageResponse, type UsagePreferences, type UserContext, type UserDemographics, type UserPreferences, type WaitOptions, detectImageFormat, generateIdempotencyKey, getBase64Size, isValidBase64, optimizeBase64Image, optimizeRequestImages, validateBase64Image, validateFitViewRequestImages, validateImageInput };