@curvet/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,380 @@
+/** Credit/cost usage block returned by synchronous endpoints. */
+interface Usage {
+    cost: number;
+    credits: number;
+    remainingBalance?: number;
+    remainingPoints?: number;
+}
+/** Per-request overrides accepted by every SDK method. */
+interface RequestOptions {
+    /** Abort the request (and any polling) via an AbortSignal. */
+    signal?: AbortSignal;
+    /** Per-request timeout in ms (overrides the client default). */
+    timeout?: number;
+    /** Per-request max retries (overrides the client default). */
+    maxRetries?: number;
+    /** Extra headers merged into the request. */
+    headers?: Record<string, string>;
+}
+/** Minimal structural type for a fetch Response (keeps the SDK runtime-agnostic). */
+interface FetchResponse {
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}
+/** Minimal structural type for fetch init options. */
+interface FetchInit {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}
+/** Injectable fetch implementation (defaults to global fetch on Node 18+). */
+type FetchLike = (url: string, init?: FetchInit) => Promise<FetchResponse>;
+
+interface HttpClientOptions {
+    appKey: string;
+    baseURL: string;
+    timeout: number;
+    maxRetries: number;
+    fetch: FetchLike;
+}
+interface RequestArgs {
+    method: string;
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | number | undefined>;
+    options?: RequestOptions;
+}
+/**
+ * The single place that knows about fetch, headers, base URL, error mapping,
+ * and retries. Resources call `request()`; everything else stays mockable.
+ */
+declare class HttpClient {
+    private opts;
+    constructor(opts: HttpClientOptions);
+    request<T = any>(args: RequestArgs): Promise<T>;
+    private backoff;
+    private buildUrl;
+    /** Combine a per-request timeout with an optional user AbortSignal. */
+    private makeSignal;
+}
+
+type ModelType = "chat" | "image" | "video" | "audio" | "3d" | "web-browse" | "design" | "ui-builder" | "presentation" | (string & {});
+interface ModelInfo {
+    id: string;
+    name: string;
+    cost: number;
+    type: ModelType;
+    provider: string;
+    credits: number;
+    supportsVision?: boolean;
+}
+interface RateLimits {
+    requestsPerHour: number;
+    costCapPerDay: number;
+}
+/**
+ * Known model IDs — provided purely for editor autocomplete.
+ * The model catalog is dynamic and per-app filtered, so any string is accepted
+ * (see {@link ModelId}); always call `models.list()` for the live catalog.
+ */
+type KnownModelId = "gpt-4o" | "gpt-4o-mini" | "qwen-235b" | "gemma-4-26b" | "perplexity-sonar" | "claude-haiku-4-5-20251001" | "claude-sonnet-4-6" | "claude-opus-4-7" | "flux-2-klein-4b" | "wan-2.2" | "auto" | "smart";
+/** A model ID. Accepts any string; {@link KnownModelId} drives autocomplete only. */
+type ModelId = KnownModelId | (string & {});
+
+type ChatRole = "system" | "user" | "assistant";
+interface ChatMessage {
+    role: ChatRole;
+    content: string;
+}
+interface ChatCreateParams {
+    model: ModelId;
+    messages: ChatMessage[];
+    /** Creativity control (default 0.7). */
+    temperature?: number;
+    /** Maximum response tokens (default 1000). */
+    maxTokens?: number;
+}
+interface ChatResponse {
+    success: boolean;
+    response: string;
+    usage: Usage;
+    metadata: {
+        model: string;
+        latencyMs: number;
+        requestId: string;
+    };
+}
+
+declare class Chat {
+    private client;
+    constructor(client: HttpClient);
+    /** Create a chat completion. Synchronous — resolves with the model's reply. */
+    create(params: ChatCreateParams, options?: RequestOptions): Promise<ChatResponse>;
+}
+
+interface ImageGenerateParams {
+    model: ModelId;
+    prompt: string;
+    /**
+     * Output dimensions as "<width>x<height>" (default "1024x1024").
+     * Note: the API uses a single `size` field, NOT separate width/height.
+     */
+    size?: string;
+}
+interface ImageResponse {
+    success: boolean;
+    imageUrl: string;
+    usage: Usage;
+    metadata: {
+        model: string;
+        latencyMs: number;
+        requestId: string;
+    };
+}
+
+declare class Images {
+    private client;
+    constructor(client: HttpClient);
+    /** Generate an image from a prompt. Synchronous — resolves with `imageUrl`. */
+    generate(params: ImageGenerateParams, options?: RequestOptions): Promise<ImageResponse>;
+}
+
+type JobStatus = "processing" | "completed" | "failed";
+type MediaKind = "video" | "audio" | "3d";
+/**
+ * Unified media-job result. The raw API uses three different URL keys
+ * (`videoUrl`/`audioUrl`/`modelUrl`) and a 200-vs-202 split; this normalizes
+ * all of them to a single shape with `mediaUrl`.
+ */
+interface MediaJob {
+    jobId?: string;
+    status: JobStatus;
+    progress?: number;
+    /** Final media URL once completed (image/video/audio/3d output). */
+    mediaUrl?: string;
+    usage?: Usage;
+    metadata?: Record<string, unknown>;
+    error?: string | null;
+    cost?: unknown;
+    eta?: string;
+    /** The raw, unnormalized response body. */
+    raw: unknown;
+}
+interface VideoGenerateParams {
+    model: ModelId;
+    prompt: string;
+    mode?: "text_to_video" | "image_to_video";
+    duration?: number;
+    resolution?: string;
+    [key: string]: unknown;
+}
+interface PollOptions {
+    /** Poll interval in ms (default 2500). */
+    pollIntervalMs?: number;
+    /** Total poll timeout in ms before throwing JobTimeoutError (default 180000). */
+    pollTimeoutMs?: number;
+    signal?: AbortSignal;
+    /** Called on each poll tick with progress (0-100) and ETA if available. */
+    onProgress?: (progress: number, eta?: string) => void;
+}
+
+interface JobDefaults {
+    pollIntervalMs: number;
+    pollTimeoutMs: number;
+}
+declare class Jobs {
+    private client;
+    private defaults;
+    constructor(client: HttpClient, defaults: JobDefaults);
+    /** Fetch the current status of an async job once (no polling). */
+    retrieve(jobId: string, options?: RequestOptions): Promise<MediaJob>;
+    /** Get a {@link Job} handle to poll/await an existing job by id. */
+    handle(jobId: string): Job;
+}
+/** A handle to a single async media job. */
+declare class Job {
+    readonly id: string;
+    private client;
+    private defaults;
+    constructor(id: string, client: HttpClient, defaults: JobDefaults);
+    /** One status fetch (no polling). */
+    retrieve(options?: RequestOptions): Promise<MediaJob>;
+    /**
+     * Poll until the job reaches a terminal state.
+     * Resolves with the completed job, or throws JobFailedError / JobTimeoutError.
+     */
+    wait(opts?: PollOptions): Promise<MediaJob>;
+}
+
+/**
+ * Video generation. Backed by an async job queue: `generate()` submits and
+ * polls to completion (the common case); `submit()` fires and returns the job
+ * handle for manual polling.
+ *
+ * The same implementation backs audio and 3D (v1.1) via the `path` arg.
+ */
+declare class Video {
+    private client;
+    private defaults;
+    private path;
+    constructor(client: HttpClient, defaults: JobDefaults, path?: string);
+    /**
+     * Submit a job WITHOUT polling. Returns once the server responds — either the
+     * 200 fast-path (already done) or a 202 with a jobId.
+     *
+     * The media POST long-polls server-side and can block well past a normal
+     * request timeout, so we default its timeout to the poll budget and disable
+     * auto-retry (a retried POST would enqueue a duplicate, double-charged job).
+     */
+    submit(params: VideoGenerateParams, options?: RequestOptions): Promise<MediaJob>;
+    /**
+     * Submit and resolve to the finished media. Handles the 200-vs-202 split and
+     * polls `/jobs/:id` internally. Throws JobFailedError / JobTimeoutError.
+     */
+    generate(params: VideoGenerateParams, options?: RequestOptions & PollOptions): Promise<MediaJob>;
+}
+
+interface ModelsListOptions extends RequestOptions {
+    /** Filter to a single model type (e.g. "chat", "image", "video"). */
+    type?: string;
+    /** Bypass the in-memory cache and fetch fresh. */
+    refresh?: boolean;
+}
+/**
+ * Live model catalog. The list is dynamic and per-app filtered server-side, so
+ * it is always fetched (with a short in-memory cache), never hardcoded.
+ */
+declare class Models {
+    private client;
+    private cacheTtlMs;
+    private cache?;
+    constructor(client: HttpClient, cacheTtlMs?: number);
+    private load;
+    private ensure;
+    /** List available models, optionally filtered by `type`. */
+    list(options?: ModelsListOptions): Promise<ModelInfo[]>;
+    /** Find a single model by id (or undefined). */
+    get(id: string, options?: ModelsListOptions): Promise<ModelInfo | undefined>;
+    /** The app's rate limits as reported by GET /models. */
+    rateLimits(options?: ModelsListOptions): Promise<RateLimits | undefined>;
+}
+
+interface BalanceInfo {
+    walletBalance?: number;
+    totalAvailableUSD: number;
+    totalPoints?: number;
+    breakdown?: {
+        walletCredits?: number;
+        totalCredits?: number;
+        organizationLimit?: number;
+        monthlyUsed?: number;
+        isEnterprise?: boolean;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+declare class Balance {
+    private client;
+    constructor(client: HttpClient);
+    /** Get the current credit balance for the app owner. */
+    get(options?: RequestOptions): Promise<BalanceInfo>;
+}
+
+declare const DEFAULT_BASE_URL = "https://curvet.ai/api/v1/playground";
+interface CurvetOptions {
+    /** Your app key. Falls back to the CURVET_APP_KEY env var. */
+    appKey?: string;
+    /** Override the gateway base URL (defaults to production). */
+    baseURL?: string;
+    /** Per-request timeout in ms (default 60000). */
+    timeout?: number;
+    /** Max automatic retries for 429/5xx and network errors (default 2). */
+    maxRetries?: number;
+    /** Inject a fetch implementation (defaults to global fetch on Node 18+). */
+    fetch?: FetchLike;
+    /** Default poll interval for async media jobs, in ms (default 2500). */
+    defaultPollIntervalMs?: number;
+    /** Default poll timeout for async media jobs, in ms (default 180000). */
+    defaultPollTimeoutMs?: number;
+}
+/**
+ * The Curvet client. One instance per app key.
+ *
+ * ```ts
+ * const curvet = new Curvet({ appKey: process.env.CURVET_APP_KEY });
+ * const { response } = await curvet.chat.create({
+ *   model: "gpt-4o-mini",
+ *   messages: [{ role: "user", content: "hi" }],
+ * });
+ * ```
+ */
+declare class Curvet {
+    readonly chat: Chat;
+    readonly image: Images;
+    readonly video: Video;
+    readonly jobs: Jobs;
+    readonly models: Models;
+    readonly balance: Balance;
+    constructor(options?: CurvetOptions);
+}
+
+interface CurvetErrorOptions {
+    status?: number;
+    requestId?: string;
+    raw?: unknown;
+}
+/** Base class for every error thrown by the SDK. */
+declare class CurvetError extends Error {
+    readonly status?: number;
+    readonly requestId?: string;
+    readonly raw?: unknown;
+    constructor(message: string, opts?: CurvetErrorOptions);
+}
+/** 401 — missing or invalid `x-app-key`. */
+declare class AuthError extends CurvetError {
+}
+/** 403 — app not active, playground not enabled, or model/category not allowed. */
+declare class PermissionError extends CurvetError {
+}
+/** 400 — invalid/unknown model or malformed payload. */
+declare class BadRequestError extends CurvetError {
+}
+/** 404 — job or workflow not found. */
+declare class NotFoundError extends CurvetError {
+}
+/** 5xx — upstream/server error (retried automatically). */
+declare class APIError extends CurvetError {
+}
+/** Network failure or timeout before a response was received. */
+declare class ConnectionError extends CurvetError {
+}
+/** 402 — not enough credits to complete the request. */
+declare class InsufficientBalanceError extends CurvetError {
+    required?: number;
+    available?: number;
+}
+/** 429 — hourly request limit or daily cost cap exceeded. */
+declare class RateLimitError extends CurvetError {
+    kind?: "rate" | "cost";
+    limit?: number;
+    used?: number;
+    resetsAt?: Date;
+    retryAfterMs?: number;
+}
+/** An async media job finished with status "failed". */
+declare class JobFailedError extends CurvetError {
+    readonly jobId: string;
+    constructor(message: string, jobId: string, opts?: CurvetErrorOptions);
+}
+/** An async media job did not finish within the poll timeout. */
+declare class JobTimeoutError extends CurvetError {
+    readonly jobId: string;
+    constructor(message: string, jobId: string, opts?: CurvetErrorOptions);
+}
+
+export { APIError, AuthError, BadRequestError, Balance, type BalanceInfo, Chat, type ChatCreateParams, type ChatMessage, type ChatResponse, type ChatRole, ConnectionError, Curvet, CurvetError, type CurvetErrorOptions, type CurvetOptions, DEFAULT_BASE_URL, type FetchLike, type ImageGenerateParams, type ImageResponse, Images, InsufficientBalanceError, Job, type JobDefaults, JobFailedError, type JobStatus, JobTimeoutError, Jobs, type KnownModelId, type MediaJob, type MediaKind, type ModelId, type ModelInfo, type ModelType, Models, type ModelsListOptions, NotFoundError, PermissionError, type PollOptions, RateLimitError, type RateLimits, type RequestOptions, type Usage, Video, type VideoGenerateParams };