segmind 0.0.1 → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,362 @@
+/** Model inputs, forwarded to the model exactly as given. */
+type Params = Record<string, unknown>;
+/** A v2 request's state. */
+type JobState = 'QUEUED' | 'PROCESSING' | 'COMPLETED' | 'FAILED';
+/**
+ * The body of a finished v2 request. Every model returns `status`, `output`
+ * and `metrics`; the rest is model-specific, so do not assume a fixed key set.
+ */
+interface RunResult {
+    status?: JobState | string;
+    output?: unknown;
+    request_id?: string;
+    metrics?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** `GET /v2/requests/{id}/status`. */
+interface JobStatus {
+    status: JobState | string;
+    request_id?: string;
+    status_url?: string;
+    response_url?: string;
+    metrics?: Record<string, unknown>;
+    model?: string;
+    error?: string;
+    retry_count?: number;
+    [key: string]: unknown;
+}
+/** `POST /v2/{slug}` (also the body of a 409 for a repeated `X-Request-ID`). */
+interface SubmitResponse {
+    request_id: string;
+    status: JobState | string;
+    status_url: string;
+    response_url: string;
+    poll_url?: string;
+    [key: string]: unknown;
+}
+interface CallOptions {
+    /** Cancels the call. */
+    signal?: AbortSignal;
+    /** Milliseconds per HTTP request; defaults to the client's `timeout`. */
+    timeout?: number;
+}
+interface SubmitOptions {
+    signal?: AbortSignal;
+    /**
+     * Idempotency key sent as `X-Request-ID` ([A-Za-z0-9_-]{8,128}). Submitting
+     * again with the same id returns the existing request instead of a new one.
+     * Generated when omitted.
+     */
+    requestId?: string;
+}
+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;
+}
+type RunOptions = SubmitOptions & WaitOptions;
+
+/** An OpenAI-style chat message; content may be text or a list of parts. */
+interface ChatMessage {
+    role: 'system' | 'developer' | 'user' | 'assistant' | 'tool' | (string & {});
+    content: string | Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+/** Chat inputs: `messages` or `prompt` (at least one), plus any model params. */
+type ChatParams = Params & {
+    messages?: ChatMessage[];
+    prompt?: string;
+};
+type Raw = Record<string, unknown>;
+/**
+ * One reply from any chat model. The gateway returns each provider's own JSON
+ * (OpenAI, Anthropic or Gemini shape); this reads the common fields from all
+ * three. `raw` is always the provider's body, untouched.
+ */
+declare class ChatResponse {
+    readonly raw: Raw;
+    constructor(raw: Raw);
+    /** The assistant's text. Throws when the body holds none (inspect `raw`). */
+    get text(): string;
+    /** `text` parsed as JSON, for JSON mode and structured outputs. */
+    json<T = unknown>(): T;
+    /** The provider's token usage (`usage` or Gemini's `usageMetadata`). */
+    get usage(): Record<string, unknown> | undefined;
+    /** Why generation stopped (`finish_reason`, `stop_reason` or `finishReason`). */
+    get finishReason(): string | undefined;
+    /** Tool calls in the OpenAI shape, when the model made any. */
+    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;
+    /** Sent as JSON. */
+    body?: unknown;
+    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;
+}
+
+declare const DEFAULT_WAIT_TIMEOUT_MS = 600000;
+declare const DEFAULT_WAIT_INTERVAL_MS = 1000;
+/**
+ * A submitted v2 request. `wait()` polls until it finishes; `status()` and
+ * `result()` read it once.
+ */
+declare class Job<T = RunResult> {
+    private readonly http;
+    /** The body the submit returned. */
+    readonly submitResponse: SubmitResponse;
+    private readonly transform;
+    readonly requestId: string;
+    readonly statusUrl: string;
+    readonly responseUrl: string;
+    constructor(http: HttpClient, 
+    /** The body the submit returned. */
+    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).
+     */
+    result(options?: {
+        signal?: AbortSignal;
+    }): Promise<T>;
+    /** Polls until the request finishes, then returns its result. */
+    wait(options?: WaitOptions): Promise<T>;
+    /**
+     * The gateway serves a FAILED request's body with HTTP 422 on both the status
+     * and result URLs. A body that names a terminal state is the answer whatever
+     * its status code; anything else outside 2xx is a real error.
+     */
+    private read;
+}
+
+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. */
+    apiKey?: string;
+    /** The inference API root, without `/v1`. Defaults to `SEGMIND_BASE_URL` or https://api.segmind.com. */
+    baseURL?: string;
+    /** The catalog and history API. Default https://api.spotprod.segmind.com. */
+    spotURL?: string;
+    /** The account API. Default https://cloud.segmind.com/api. */
+    consoleURL?: string;
+    /** Milliseconds per HTTP request. Default 600 000. */
+    timeout?: number;
+    /** Retries for requests that cannot bill twice. Default 2. */
+    maxRetries?: number;
+    /** A `fetch` implementation. Defaults to the global one. */
+    fetch?: typeof fetch;
+    /** Headers added to every request. */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Allow an API key in a browser or React Native app. Anyone who can open the
+     * app can read the key and spend your credits. Prefer calling your own
+     * backend, or realtime session tokens.
+     */
+    dangerouslyAllowBrowser?: boolean;
+}
+/**
+ * The Segmind API client.
+ *
+ * ```ts
+ * const segmind = new Segmind(); // reads SEGMIND_API_KEY
+ * const result = await segmind.run('seedream-4.5', { prompt: 'A sunset over mountains' });
+ * ```
+ */
+declare class Segmind {
+    readonly baseURL: string;
+    readonly spotURL: string;
+    readonly consoleURL: string;
+    readonly models: Models;
+    readonly accounts: Accounts;
+    /** @internal */
+    readonly http: HttpClient;
+    constructor(options?: ClientOptions);
+    /**
+     * Runs a model and returns its result: submits to the v2 queue, then polls
+     * until it finishes. `params` go to the model unchanged.
+     */
+    run(slug: string, params?: Params, options?: RunOptions): Promise<RunResult>;
+    /**
+     * One blocking `POST /v1/{slug}`. Returns the fetch `Response`: call
+     * `.arrayBuffer()` for media or `.json()` for JSON models. Never retried,
+     * because the call bills.
+     */
+    runSync(slug: string, params?: Params, options?: CallOptions): Promise<Response>;
+    /**
+     * Submits to the v2 queue and returns a `Job` to wait on. Safe to retry: the
+     * submit carries an `X-Request-ID`, and the gateway answers a repeat with
+     * the existing request rather than a second one.
+     */
+    submit(slug: string, params?: Params, options?: SubmitOptions): Promise<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}`. */
+    chatSync(slug: string, params: ChatParams, options?: CallOptions): Promise<ChatResponse>;
+    /** Submits a chat to the v2 queue and returns a `Job` whose result is a `ChatResponse`. */
+    submitChat(slug: string, params: ChatParams, options?: SubmitOptions): Promise<Job<ChatResponse>>;
+    private submitJob;
+}
+/** One catalog entry. Only the commonly used fields are typed. */
+interface ModelInfo {
+    slug: string;
+    title?: string;
+    type?: string;
+    description?: string;
+    is_visible?: boolean;
+    is_depreciated?: boolean;
+    is_new?: boolean;
+    coming_soon?: boolean;
+    parameters_schema?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** The catalog response, as the API returns it. */
+interface ModelsListResponse {
+    'Inference Model Information List': ModelInfo[];
+    [key: string]: unknown;
+}
+/** The model catalog. */
+declare class Models {
+    private readonly client;
+    constructor(client: Segmind);
+    /** Every model in the catalog, under the key `Inference Model Information List`. */
+    list(options?: {
+        signal?: AbortSignal;
+    }): Promise<ModelsListResponse>;
+}
+/** The account the API key belongs to. */
+declare class Accounts {
+    private readonly client;
+    constructor(client: Segmind);
+    /** Account details for the API key. */
+    current(options?: {
+        signal?: AbortSignal;
+    }): Promise<Record<string, unknown>>;
+}
+
+/** An OpenAI-style image part, for the `content` list of a chat message. */
+interface ImageUrlPart {
+    type: 'image_url';
+    image_url: {
+        url: string;
+    };
+}
+type ImageInput = string | Blob | ArrayBuffer | Uint8Array;
+/**
+ * Builds an image part for a chat message.
+ *
+ * - An `http(s)://` or `data:` URL passes through.
+ * - A file path (Node only) is read and inlined as a base64 `data:` URI.
+ * - A `Blob`, `ArrayBuffer` or `Uint8Array` is inlined; pass `mimeType` when
+ *   it cannot be told from the blob or the bytes.
+ *
+ * Inlining is the safer route: the gateway cannot fetch URLs on every host.
+ */
+declare function imageUrl(input: ImageInput, options?: {
+    mimeType?: string;
+}): Promise<ImageUrlPart>;
+
+interface SegmindErrorOptions {
+    status?: number;
+    detail?: string;
+    requestId?: string;
+    body?: unknown;
+    cause?: unknown;
+}
+/** Base class of every error the SDK throws (except an `AbortSignal`'s own reason). */
+declare class SegmindError extends Error {
+    /** HTTP status, when the error came from a response. */
+    readonly status: number | undefined;
+    /** The server's error text (`error` in the response body), when it sent one. */
+    readonly detail: string | undefined;
+    /** The v2 request id the error belongs to, when there is one. */
+    readonly requestId: string | undefined;
+    /** The parsed response body, or its text when it was not JSON. */
+    readonly body: unknown;
+    constructor(message: string, options?: SegmindErrorOptions);
+    /** Reads the response body and builds the error. Consumes the body. */
+    static fromResponse(response: Response, requestId?: string): Promise<SegmindError>;
+}
+/** The request never got a response: DNS, TLS, connection reset, or the client's timeout. */
+declare class APIConnectionError extends SegmindError {
+}
+/** 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. */
+    readonly statusBody: Record<string, unknown>;
+    constructor(requestId: string, statusBody: Record<string, unknown>);
+}
+/**
+ * `wait()` ran past its timeout. The request may still finish on the server:
+ * `job.status()` or a new `wait()` picks it up again.
+ */
+declare class InferenceTimeout extends SegmindError {
+    readonly elapsedMs: number;
+    constructor(requestId: string, elapsedMs: number);
+}
+
+declare const VERSION = "0.1.0";
+
+/** `new Segmind().run(...)` with the key from `SEGMIND_API_KEY`. */
+declare const run: (slug: string, params?: Params, options?: RunOptions) => Promise<RunResult>;
+/** `new Segmind().runSync(...)` with the key from `SEGMIND_API_KEY`. */
+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().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`. */
+declare const chatSync: (slug: string, params: ChatParams, options?: CallOptions) => Promise<ChatResponse>;
+/** `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>;
+};
+/** `new Segmind().accounts` with the key from `SEGMIND_API_KEY`. */
+declare const accounts: {
+    current: (options?: {
+        signal?: AbortSignal;
+    }) => Promise<Record<string, unknown>>;
+};
+
+export { APIConnectionError, Accounts, ChatResponse, DEFAULT_BASE_URL, DEFAULT_CONSOLE_URL, DEFAULT_SPOT_URL, DEFAULT_WAIT_INTERVAL_MS, DEFAULT_WAIT_TIMEOUT_MS, InferenceFailed, InferenceTimeout, Job, Models, Segmind, SegmindError, VERSION, accounts, chat, chatSync, imageUrl, models, run, runSync, submit, submitChat };
+export type { CallOptions, ChatMessage, ChatParams, ClientOptions, ImageInput, ImageUrlPart, JobState, JobStatus, ModelInfo, ModelsListResponse, Params, RunOptions, RunResult, SubmitOptions, SubmitResponse, WaitOptions };