segmind 0.2.4 → 0.3.0

package/dist/index.d.cts

@@ -1,3 +1,59 @@
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/** Returns the signed-in user's token, or null when there is none. Called before every request. */
+type TokenProvider = () => string | null | undefined | Promise<string | null | undefined>;
+/** Milliseconds between status checks: fixed, or worked out from the milliseconds elapsed so far. */
+type PollInterval = number | ((elapsedMs: number) => number);
+interface HttpConfig {
+    apiKey: string | undefined;
+    tokenProvider?: TokenProvider;
+    onUnauthorized?: () => void | Promise<void>;
+    fetch: typeof fetch;
+    timeout: number;
+    maxRetries: number;
+    headers: Record<string, string>;
+}
+interface HttpRequest {
+    method: HttpMethod;
+    url: string;
+    /** Query parameters; `undefined` values are left out. */
+    query?: Record<string, string | number | boolean | undefined>;
+    /** Sent as JSON. */
+    body?: unknown;
+    /** Sent as is, instead of a JSON `body`. */
+    rawBody?: Uint8Array | Blob;
+    /**
+     * Send only `headers`: no API key, no `X-Initiator`, no default headers. For
+     * presigned URLs on other hosts, which must never see the key.
+     */
+    bare?: boolean;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    /** Milliseconds for this attempt; defaults to the client's timeout. */
+    timeout?: number;
+    /**
+     * Retry connection errors and retryable statuses. Only for requests that
+     * cannot bill twice: reads, polls, and v2 submits that carry an
+     * `X-Request-ID` (the gateway answers a repeat with 409, not a second job).
+     */
+    retry?: boolean;
+}
+declare class HttpClient {
+    readonly config: HttpConfig;
+    /** The hook call in flight, so that requests failing together share one refresh. */
+    private unauthorized;
+    constructor(config: HttpConfig);
+    /** The response whatever its status, after retries when `retry` is set. */
+    fetchRaw(req: HttpRequest): Promise<Response>;
+    /** The response, or a `SegmindError` for any status outside 2xx. */
+    request(req: HttpRequest): Promise<Response>;
+    /** The parsed JSON body of a 2xx response. */
+    json<T>(req: HttpRequest): Promise<T>;
+    private sessionToken;
+    /** Tells the app its token was refused. True when it now has a different one to try. */
+    private reauthenticate;
+    private attempt;
+}
+
 /** Model inputs, forwarded to the model exactly as given. */
 type Params = Record<string, unknown>;
 /** A v2 request's state. */
@@ -34,13 +90,26 @@ interface SubmitResponse {
     poll_url?: string;
     [key: string]: unknown;
 }
-interface CallOptions {
+/**
+ * Which surface a request is recorded under in usage history. Known values are
+ * listed, but any string is accepted: the platform records one it does not know
+ * as `OTHERS`, and values are case-sensitive. Give the bare name: the gateway
+ * adds the `-V2` itself on queued requests.
+ */
+type Initiator = 'API' | 'WEBPROD' | 'WEBSTAGE' | 'WORKFLOWS' | 'MCP' | 'AGENT' | 'PIXIE' | 'SDK-JS' | (string & {});
+interface InitiatorOptions {
+    /** Overrides the client's `initiator` for this request. */
+    initiator?: Initiator;
+    /** Overrides the client's `initiatorId`: what the request belongs to, such as a workflow id. */
+    initiatorId?: string;
+}
+interface CallOptions extends InitiatorOptions {
     /** Cancels the call. */
     signal?: AbortSignal;
     /** Milliseconds per HTTP request; defaults to the client's `timeout`. */
     timeout?: number;
 }
-interface SubmitOptions {
+interface SubmitOptions extends InitiatorOptions {
     signal?: AbortSignal;
     /**
      * Idempotency key sent as `X-Request-ID` ([A-Za-z0-9_-]{8,128}). Submitting
@@ -53,8 +122,13 @@ interface WaitOptions {
     signal?: AbortSignal;
     /** Give up after this many milliseconds. Default 600 000 (10 minutes). */
     timeout?: number;
-    /** Milliseconds between status checks. Default 1000. */
-    interval?: number;
+    /**
+     * Milliseconds between status checks, or a function of the milliseconds
+     * elapsed since `wait()` began, for a schedule. Default 1000.
+     */
+    interval?: PollInterval;
+    /** Called with every status read, including the final one. */
+    onStatus?: (status: JobStatus) => void;
 }
 type RunOptions = SubmitOptions & WaitOptions;
 
@@ -94,51 +168,6 @@ declare class ChatResponse {
     get toolCalls(): unknown[];
 }
 
-type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-interface HttpConfig {
-    apiKey: string | undefined;
-    fetch: typeof fetch;
-    timeout: number;
-    maxRetries: number;
-    headers: Record<string, string>;
-}
-interface HttpRequest {
-    method: HttpMethod;
-    url: string;
-    /** Query parameters; `undefined` values are left out. */
-    query?: Record<string, string | number | boolean | undefined>;
-    /** Sent as JSON. */
-    body?: unknown;
-    /** Sent as is, instead of a JSON `body`. */
-    rawBody?: Uint8Array | Blob;
-    /**
-     * Send only `headers`: no API key, no `X-Initiator`, no default headers. For
-     * presigned URLs on other hosts, which must never see the key.
-     */
-    bare?: boolean;
-    headers?: Record<string, string>;
-    signal?: AbortSignal;
-    /** Milliseconds for this attempt; defaults to the client's timeout. */
-    timeout?: number;
-    /**
-     * Retry connection errors and retryable statuses. Only for requests that
-     * cannot bill twice: reads, polls, and v2 submits that carry an
-     * `X-Request-ID` (the gateway answers a repeat with 409, not a second job).
-     */
-    retry?: boolean;
-}
-declare class HttpClient {
-    readonly config: HttpConfig;
-    constructor(config: HttpConfig);
-    /** The response whatever its status, after retries when `retry` is set. */
-    fetchRaw(req: HttpRequest): Promise<Response>;
-    /** The response, or a `SegmindError` for any status outside 2xx. */
-    request(req: HttpRequest): Promise<Response>;
-    /** The parsed JSON body of a 2xx response. */
-    json<T>(req: HttpRequest): Promise<T>;
-    private attempt;
-}
-
 /** A file to send: a path (Node only), a `Blob` or `File`, or raw bytes. */
 type FileInput = string | Blob | ArrayBuffer | Uint8Array;
 
@@ -287,22 +316,22 @@ declare const DEFAULT_WAIT_INTERVAL_MS = 1000;
  */
 declare class Job<T = RunResult> {
     private readonly http;
-    /** The body the submit returned. */
+    /** The body the submit returned. A job rebuilt with `segmind.job()` has only its id and URLs. */
     readonly submitResponse: SubmitResponse;
     private readonly transform;
     readonly requestId: string;
     readonly statusUrl: string;
     readonly responseUrl: string;
     constructor(http: HttpClient, 
-    /** The body the submit returned. */
+    /** The body the submit returned. A job rebuilt with `segmind.job()` has only its id and URLs. */
     submitResponse: SubmitResponse, transform?: (body: RunResult) => T);
     /** The current state, without waiting. */
     status(options?: {
         signal?: AbortSignal;
     }): Promise<JobStatus>;
     /**
-     * The finished result. Throws `InferenceFailed` when the request failed, and
-     * a `SegmindError` when it has not finished yet (use `wait()` for that).
+     * The finished result. Throws `InferenceFailed` when the request failed
+     * (`InsufficientCredits` when that was for lack of credits), and a `SegmindError` when it has not finished yet (use `wait()` for that).
      */
     result(options?: {
         signal?: AbortSignal;
@@ -317,7 +346,7 @@ declare class Job<T = RunResult> {
     private read;
 }
 
-interface PixelflowSubmitOptions {
+interface PixelflowSubmitOptions extends InitiatorOptions {
     /**
      * `v2` (default) runs on the current workflow engine, which also loads
      * older graphs. `v1` is the legacy engine.
@@ -328,8 +357,13 @@ interface PixelflowSubmitOptions {
 interface PixelflowWaitOptions {
     /** Give up after this many milliseconds. Default 600 000. */
     timeout?: number;
-    /** Milliseconds between status checks. Default 2000. */
-    interval?: number;
+    /**
+     * Milliseconds between status checks, or a function of the milliseconds
+     * elapsed since `wait()` began, for a schedule. Default 2000.
+     */
+    interval?: PollInterval;
+    /** Called with every status read, including the final one. */
+    onStatus?: (status: PixelflowStatus) => void;
     signal?: AbortSignal;
 }
 interface PixelflowStatus {
@@ -369,7 +403,7 @@ declare class PixelflowJob {
     }): Promise<PixelflowStatus>;
     /**
      * Polls until the run finishes. Throws `InferenceFailed` (its `detail` names
-     * the failing node) or `InferenceTimeout`; the run may still finish after a
+     * the failing node), `InsufficientCredits` or `InferenceTimeout`; the run may still finish after a
      * timeout, so `wait()` can be called again.
      */
     wait(options?: PixelflowWaitOptions): Promise<PixelflowStatus>;
@@ -433,11 +467,29 @@ declare const DEFAULT_BASE_URL = "https://api.segmind.com";
 declare const DEFAULT_SPOT_URL = "https://api.spotprod.segmind.com";
 declare const DEFAULT_CONSOLE_URL = "https://cloud.segmind.com/api";
 interface ClientOptions {
-    /** Your Segmind API key. Defaults to `SEGMIND_API_KEY` from the environment. */
+    /** Your Segmind API key. Defaults to `SEGMIND_API_KEY` from the environment, unless `tokenProvider` is set. */
     apiKey?: string;
+    /**
+     * Authenticates as a signed-in Segmind user instead of with an API key, sending
+     * `Authorization: Bearer <token>`. Called before every request, so a rotated
+     * token is picked up mid-poll. Allowed in browsers, because the token is the
+     * user's own session. When it returns nothing, requests go out unauthenticated.
+     */
+    tokenProvider?: TokenProvider;
+    /**
+     * Called when a request made with `tokenProvider` gets a 401: refresh the
+     * session here. If `tokenProvider` then returns a different token, the request
+     * is sent once more; otherwise the 401 is thrown. Requests failing at the same
+     * time share one call.
+     */
+    onUnauthorized?: () => void | Promise<void>;
+    /** Recorded as the source of these requests in usage history. Default `SDK-JS`. */
+    initiator?: Initiator;
+    /** Recorded with `initiator`: what the requests belong to, such as a workflow id. */
+    initiatorId?: string;
     /** The inference API root, without `/v1`. Defaults to `SEGMIND_BASE_URL` or https://api.segmind.com. */
     baseURL?: string;
-    /** The catalog, history, webhook and upload API. Default https://api.spotprod.segmind.com. */
+    /** The history, webhook and upload API. Default https://api.spotprod.segmind.com. */
     spotURL?: string;
     /** The account API. Default https://cloud.segmind.com/api. */
     consoleURL?: string;
@@ -501,6 +553,13 @@ declare class Segmind {
      * the existing request rather than a second one.
      */
     submit(slug: string, params?: Params, options?: SubmitOptions): Promise<Job>;
+    /**
+     * A job submitted earlier, from its id alone, for picking one up after a
+     * reload or in another process. Makes no request. The result is kept for about
+     * an hour, and only for the user who submitted it: anything else reads as a
+     * `SegmindError` with status 404.
+     */
+    job(requestId: string): Job;
     /** Chat with an LLM through the v2 queue. Returns a provider-neutral reply. */
     chat(slug: string, params: ChatParams, options?: RunOptions): Promise<ChatResponse>;
     /** Chat with one blocking `POST /v1/{slug}`. */
@@ -509,32 +568,96 @@ declare class Segmind {
     submitChat(slug: string, params: ChatParams, options?: SubmitOptions): Promise<Job<ChatResponse>>;
     private submitJob;
 }
-/** One catalog entry. Only the commonly used fields are typed. */
+type ModelInput = 'text' | 'image' | 'video' | 'audio';
+type ModelOutput = ModelInput | '3d' | 'embedding' | 'data';
+type ModelSort = 'popular' | 'newest' | 'name' | 'cheapest' | 'fastest' | 'relevance';
+/** One catalog entry, as `GET /models` returns it. */
 interface ModelInfo {
     slug: string;
-    title?: string;
-    type?: string;
+    name: string;
     description?: string;
-    is_visible?: boolean;
-    is_depreciated?: boolean;
+    /** For example `textToImage` or `imageToVideo`. */
+    category?: string;
+    modality?: string;
+    input?: ModelInput;
+    output?: ModelOutput;
+    provider?: string;
+    thumbnail_url?: string;
     is_new?: boolean;
     coming_soon?: boolean;
-    parameters_schema?: Record<string, unknown>;
+    /** 0–100, across the whole catalog. */
+    popularity_score?: number;
+    /** 0–100, within the model's category. */
+    category_percentile?: number;
+    /** Observed average spend per request in USD, not the list price. */
+    average_cost?: number | null;
+    latency_seconds?: number | null;
+    created_at?: string;
+    operations?: string[];
+    features?: string[];
     [key: string]: unknown;
 }
-/** The catalog response, as the API returns it. */
-interface ModelsListResponse {
-    'Inference Model Information List': ModelInfo[];
+/** Filters and paging for `models.list()`. Every filter is optional. */
+interface ModelListParams {
+    /** Free-text search; sorts by relevance unless `sort` is given. */
+    q?: string;
+    /** Default `popular`, or `relevance` when `q` is set. */
+    sort?: ModelSort;
+    category?: string;
+    modality?: string;
+    /** Models that take any of these inputs. */
+    input?: ModelInput | ModelInput[];
+    /** Models that produce any of these outputs. */
+    output?: ModelOutput | ModelOutput[];
+    provider?: string;
+    /** Look up these slugs, up to 100. Unlisted models resolve too. */
+    slugs?: string[];
+    operations?: string | string[];
+    features?: string | string[];
+    minPopularity?: number;
+    minCategoryPercentile?: number;
+    minCost?: number;
+    maxCost?: number;
+    maxLatency?: number;
+    isNew?: boolean;
+    /** `YYYY-MM-DD`. */
+    createdAfter?: string;
+    includeComingSoon?: boolean;
+    /** Also return filter counts under `facets`. */
+    facets?: boolean;
+    /** 1–100, default 50. */
+    limit?: number;
+    offset?: number;
+}
+/** One page of the catalog. */
+interface ModelsPage {
+    models: ModelInfo[];
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+    facets?: Record<string, unknown>;
     [key: string]: unknown;
 }
-/** The model catalog. */
+/** The model catalog, served by the gateway at `GET /models`. */
 declare class Models {
     private readonly client;
     constructor(client: Segmind);
-    /** Every model in the catalog, under the key `Inference Model Information List`. */
-    list(options?: {
+    /** One page of the catalog. Pass `offset` from the previous page while `has_more` is true. */
+    list(params?: ModelListParams, options?: {
+        signal?: AbortSignal;
+    }): Promise<ModelsPage>;
+    /** Every model matching `params`, reading page after page. */
+    listAll(params?: Omit<ModelListParams, 'limit' | 'offset' | 'facets'>, options?: {
         signal?: AbortSignal;
-    }): Promise<ModelsListResponse>;
+    }): Promise<ModelInfo[]>;
+}
+/** The balance of the account or team making the request. */
+interface AccountCredits {
+    /** The stored balance. Credits held by requests still running are not taken off. */
+    credits: number;
+    freeCredits: number;
+    [key: string]: unknown;
 }
 /** The account the API key belongs to. */
 declare class Accounts {
@@ -544,6 +667,10 @@ declare class Accounts {
     current(options?: {
         signal?: AbortSignal;
     }): Promise<Record<string, unknown>>;
+    /** The current credit balance. */
+    credits(options?: {
+        signal?: AbortSignal;
+    }): Promise<AccountCredits>;
 }
 
 /** An OpenAI-style image part, for the `content` list of a chat message. */
@@ -592,6 +719,24 @@ declare class SegmindError extends Error {
 /** The request never got a response: DNS, TLS, connection reset, or the client's timeout. */
 declare class APIConnectionError extends SegmindError {
 }
+/**
+ * The account cannot pay for the request. The gateway reports this at submit, or
+ * as a failed job when the balance is positive but below the model's cost, so
+ * this one class covers both. `detail` holds the server's message.
+ */
+declare class InsufficientCredits extends SegmindError {
+}
+/**
+ * Too many requests, after the SDK's own retries for calls that are safe to
+ * repeat. `retryAfterMs` is set when the server sent `Retry-After` and the
+ * runtime could read it: a browser only sees the header if the server exposes it.
+ */
+declare class RateLimited extends SegmindError {
+    readonly retryAfterMs: number | undefined;
+    constructor(message: string, options?: SegmindErrorOptions & {
+        retryAfterMs?: number;
+    });
+}
 /** A v2 request reached `FAILED`. The server's error text is in `detail`. */
 declare class InferenceFailed extends SegmindError {
     /** The status body that reported the failure. */
@@ -607,7 +752,7 @@ declare class InferenceTimeout extends SegmindError {
     constructor(requestId: string, elapsedMs: number);
 }
 
-declare const VERSION = "0.2.4";
+declare const VERSION = "0.3.0";
 
 /** `new Segmind().run(...)` with the key from `SEGMIND_API_KEY`. */
 declare const run: (slug: string, params?: Params, options?: RunOptions) => Promise<RunResult>;
@@ -615,6 +760,8 @@ declare const run: (slug: string, params?: Params, options?: RunOptions) => Prom
 declare const runSync: (slug: string, params?: Params, options?: CallOptions) => Promise<Response>;
 /** `new Segmind().submit(...)` with the key from `SEGMIND_API_KEY`. */
 declare const submit: (slug: string, params?: Params, options?: SubmitOptions) => Promise<Job>;
+/** `new Segmind().job(...)` with the key from `SEGMIND_API_KEY`. */
+declare const job: (requestId: string) => Job;
 /** `new Segmind().chat(...)` with the key from `SEGMIND_API_KEY`. */
 declare const chat: (slug: string, params: ChatParams, options?: RunOptions) => Promise<ChatResponse>;
 /** `new Segmind().chatSync(...)` with the key from `SEGMIND_API_KEY`. */
@@ -622,16 +769,15 @@ declare const chatSync: (slug: string, params: ChatParams, options?: CallOptions
 /** `new Segmind().submitChat(...)` with the key from `SEGMIND_API_KEY`. */
 declare const submitChat: (slug: string, params: ChatParams, options?: SubmitOptions) => Promise<Job<ChatResponse>>;
 /** `new Segmind().models` with the key from `SEGMIND_API_KEY`. */
-declare const models: {
-    list: (options?: {
-        signal?: AbortSignal;
-    }) => Promise<ModelsListResponse>;
-};
+declare const models: Pick<Models, 'list' | 'listAll'>;
 /** `new Segmind().accounts` with the key from `SEGMIND_API_KEY`. */
 declare const accounts: {
     current: (options?: {
         signal?: AbortSignal;
     }) => Promise<Record<string, unknown>>;
+    credits: (options?: {
+        signal?: AbortSignal;
+    }) => Promise<AccountCredits>;
 };
 /** `new Segmind().files` with the key from `SEGMIND_API_KEY`. */
 declare const files: Pick<Files, 'upload'>;
@@ -642,5 +788,5 @@ declare const webhooks: Pick<Webhooks, 'get' | 'add' | 'update' | 'delete' | 'lo
 /** `new Segmind().pixelflows` with the key from `SEGMIND_API_KEY`. */
 declare const pixelflows: Pick<PixelFlows, 'run' | 'submit' | 'getStatus' | 'poll'>;
 
-export { APIConnectionError, Accounts, ChatResponse, DEFAULT_BASE_URL, DEFAULT_CONSOLE_URL, DEFAULT_SPOT_URL, DEFAULT_WAIT_INTERVAL_MS, DEFAULT_WAIT_TIMEOUT_MS, Files, Generations, InferenceFailed, InferenceTimeout, Job, Models, PixelFlows, PixelflowJob, Segmind, SegmindError, VERSION, Webhooks, accounts, chat, chatSync, files, generations, imageUrl, models, pixelflows, run, runSync, submit, submitChat, webhooks };
-export type { CallOptions, ChatMessage, ChatParams, ClientOptions, FileInput, Generation, GenerationsListOptions, HistoryOptions, ImageInput, ImageUrlPart, JobState, JobStatus, ModelInfo, ModelsListResponse, Page, Params, PixelflowStatus, PixelflowSubmitOptions, PixelflowWaitOptions, RequestRecord, RunOptions, RunResult, SubmitOptions, SubmitResponse, UploadOptions, UploadedFile, WaitOptions, Webhook, WebhookEventType };
+export { APIConnectionError, Accounts, ChatResponse, DEFAULT_BASE_URL, DEFAULT_CONSOLE_URL, DEFAULT_SPOT_URL, DEFAULT_WAIT_INTERVAL_MS, DEFAULT_WAIT_TIMEOUT_MS, Files, Generations, InferenceFailed, InferenceTimeout, InsufficientCredits, Job, Models, PixelFlows, PixelflowJob, RateLimited, Segmind, SegmindError, VERSION, Webhooks, accounts, chat, chatSync, files, generations, imageUrl, job, models, pixelflows, run, runSync, submit, submitChat, webhooks };
+export type { AccountCredits, CallOptions, ChatMessage, ChatParams, ClientOptions, FileInput, Generation, GenerationsListOptions, HistoryOptions, ImageInput, ImageUrlPart, Initiator, InitiatorOptions, JobState, JobStatus, ModelInfo, ModelInput, ModelListParams, ModelOutput, ModelSort, ModelsPage, Page, Params, PixelflowStatus, PixelflowSubmitOptions, PixelflowWaitOptions, PollInterval, RequestRecord, RunOptions, RunResult, SubmitOptions, SubmitResponse, TokenProvider, UploadOptions, UploadedFile, WaitOptions, Webhook, WebhookEventType };