segmind 0.2.3 → 0.3.0

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/core/errors.ts
-var SegmindError = class _SegmindError extends Error {
+var SegmindError = class extends Error {
   /** HTTP status, when the error came from a response. */
   status;
   /** The server's error text (`error` in the response body), when it sent one. */
@@ -17,20 +17,21 @@ var SegmindError = class _SegmindError extends Error {
     this.body = options.body;
   }
   /** Reads the response body and builds the error. Consumes the body. */
-  static async fromResponse(response, requestId) {
-    const text = await response.text().catch(() => "");
-    let body = text;
-    try {
-      body = text ? JSON.parse(text) : void 0;
-    } catch {
-    }
-    const detail = errorDetail(body) ?? (typeof body === "string" && body ? body.slice(0, 500) : void 0);
-    const message = detail ? `${response.status} ${detail}` : `${response.status} ${response.statusText || "request failed"}`;
-    return new _SegmindError(message, { status: response.status, detail, requestId, body });
+  static fromResponse(response, requestId) {
+    return errorFromResponse(response, requestId);
   }
 };
 var APIConnectionError = class extends SegmindError {
 };
+var InsufficientCredits = class extends SegmindError {
+};
+var RateLimited = class extends SegmindError {
+  retryAfterMs;
+  constructor(message, options = {}) {
+    super(message, options);
+    this.retryAfterMs = options.retryAfterMs;
+  }
+};
 var InferenceFailed = class extends SegmindError {
   /** The status body that reported the failure. */
   statusBody;
@@ -51,6 +52,43 @@ var InferenceTimeout = class extends SegmindError {
     this.elapsedMs = elapsedMs;
   }
 };
+async function errorFromResponse(response, requestId) {
+  const text = await response.text().catch(() => "");
+  let body = text;
+  try {
+    body = text ? JSON.parse(text) : void 0;
+  } catch {
+  }
+  const detail = errorDetail(body) ?? plainText(body);
+  const message = detail ? `${response.status} ${detail}` : `${response.status} ${response.statusText || "request failed"}`;
+  const options = { status: response.status, detail, requestId, body };
+  if (response.status === 429) {
+    return new RateLimited(message, { ...options, retryAfterMs: parseRetryAfter(response.headers.get("retry-after")) });
+  }
+  if (response.status === 402 || isOutOfCredits(detail)) return new InsufficientCredits(message, options);
+  return new SegmindError(message, options);
+}
+function requestFailure(requestId, statusBody, detail) {
+  detail ??= typeof statusBody.error === "string" ? statusBody.error : void 0;
+  if (isOutOfCredits(detail)) {
+    return new InsufficientCredits(`request ${requestId} failed: ${detail}`, { detail, requestId, body: statusBody });
+  }
+  return new InferenceFailed(requestId, statusBody, detail);
+}
+function parseRetryAfter(value, now = Date.now()) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? void 0 : Math.max(date - now, 0);
+}
+function isOutOfCredits(detail) {
+  return detail?.startsWith("Insufficient credits.") ?? false;
+}
+function plainText(body) {
+  if (typeof body !== "string" || !body || body.trimStart().startsWith("<")) return void 0;
+  return body.slice(0, 500);
+}
 function errorDetail(body) {
   if (!body || typeof body !== "object") return void 0;
   const record2 = body;
@@ -168,6 +206,12 @@ function detectRuntime() {
   if (g.process?.versions?.node) return "node";
   return "other";
 }
+function initiatorHeaders(options) {
+  return {
+    ...options.initiator ? { "X-Initiator": options.initiator } : {},
+    ...options.initiatorId ? { "X-Initiator-ID": options.initiatorId } : {}
+  };
+}
 function readEnv(name) {
   try {
     const value = g.process?.env?.[name];
@@ -200,15 +244,15 @@ function toBase64(bytes) {
 var RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 429, 502, 503, 504]);
 var MAX_RETRY_DELAY_MS = 6e4;
 function retryDelay(attempt, retryAfter, now = Date.now()) {
-  if (retryAfter) {
-    const seconds = Number(retryAfter);
-    if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1e3, MAX_RETRY_DELAY_MS);
-    const date = Date.parse(retryAfter);
-    if (!Number.isNaN(date)) return Math.min(Math.max(date - now, 0), MAX_RETRY_DELAY_MS);
-  }
+  const asked = parseRetryAfter(retryAfter, now);
+  if (asked !== void 0) return Math.min(asked, MAX_RETRY_DELAY_MS);
   const base = Math.min(500 * 2 ** attempt, 8e3);
   return base * (0.75 + Math.random() * 0.25);
 }
+function pollDelay(interval, elapsedMs, fallback) {
+  const delay = typeof interval === "function" ? interval(elapsedMs) : interval ?? fallback;
+  return Number.isFinite(delay) && delay >= 0 ? delay : fallback;
+}
 function sleep(ms, signal) {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) return reject(signal.reason);
@@ -228,23 +272,35 @@ var HttpClient = class {
     this.config = config;
   }
   config;
+  /** The hook call in flight, so that requests failing together share one refresh. */
+  unauthorized;
   /** The response whatever its status, after retries when `retry` is set. */
   async fetchRaw(req) {
-    for (let attempt = 0; ; attempt++) {
+    let attempt = 0;
+    let reauthenticated = false;
+    for (; ; ) {
       const canRetry = req.retry === true && attempt < this.config.maxRetries;
+      const token = await this.sessionToken(req);
       let response;
       try {
-        response = await this.attempt(req);
+        response = await this.attempt(req, token);
       } catch (err) {
         if (canRetry && err instanceof APIConnectionError) {
           await sleep(retryDelay(attempt, null), req.signal);
+          attempt++;
           continue;
         }
         throw err;
       }
+      if (response.status === 401 && !reauthenticated && await this.reauthenticate(req, token)) {
+        reauthenticated = true;
+        await response.body?.cancel().catch(() => void 0);
+        continue;
+      }
       if (canRetry && RETRYABLE_STATUS.has(response.status)) {
         await response.body?.cancel().catch(() => void 0);
         await sleep(retryDelay(attempt, response.headers.get("retry-after")), req.signal);
+        attempt++;
         continue;
       }
       return response;
@@ -260,7 +316,31 @@ var HttpClient = class {
   async json(req) {
     return readJson(await this.request(req));
   }
-  async attempt(req) {
+  async sessionToken(req) {
+    if (!this.config.tokenProvider || req.bare) return void 0;
+    try {
+      return await this.config.tokenProvider() ?? void 0;
+    } catch (err) {
+      throw new SegmindError(`tokenProvider failed: ${describe(err)}`, { cause: err });
+    }
+  }
+  /** Tells the app its token was refused. True when it now has a different one to try. */
+  async reauthenticate(req, refused) {
+    if (!this.config.tokenProvider || req.bare) return false;
+    try {
+      if (this.config.onUnauthorized) {
+        this.unauthorized ??= Promise.resolve(this.config.onUnauthorized()).finally(() => {
+          this.unauthorized = void 0;
+        });
+        await this.unauthorized;
+      }
+      const next = await this.config.tokenProvider();
+      return Boolean(next) && next !== refused;
+    } catch {
+      return false;
+    }
+  }
+  async attempt(req, token) {
     const { signal } = req;
     if (signal?.aborted) throw signal.reason;
     const timeout = req.timeout ?? this.config.timeout;
@@ -274,6 +354,7 @@ var HttpClient = class {
     signal?.addEventListener("abort", onAbort, { once: true });
     const headers = req.bare ? { ...req.headers } : { ...this.config.headers, ...req.headers };
     if (this.config.apiKey && !req.bare) headers["x-api-key"] = this.config.apiKey;
+    if (token) headers.Authorization = `Bearer ${token}`;
     if (req.body !== void 0) headers["content-type"] = "application/json";
     const body = req.rawBody ?? (req.body === void 0 ? void 0 : JSON.stringify(req.body));
     try {
@@ -368,7 +449,12 @@ async function readFileInput(input, options) {
     if (detectRuntime() !== "node") {
       throw new SegmindError(`${options.caller}: file paths work in Node only; pass a Blob or bytes`);
     }
-    const { readFile } = await import("node:fs/promises");
+    const { readFile } = await import(
+      /* webpackIgnore: true */
+      /* turbopackIgnore: true */
+      /* @vite-ignore */
+      "node:fs/promises"
+    );
     try {
       bytes = new Uint8Array(await readFile(input));
     } catch (err) {
@@ -551,12 +637,12 @@ var Job = class {
     return await this.read(this.statusUrl, options.signal);
   }
   /**
-   * 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).
    */
   async result(options = {}) {
     const body = await this.read(this.responseUrl, options.signal);
-    if (body.status === "FAILED") throw new InferenceFailed(this.requestId, body);
+    if (body.status === "FAILED") throw requestFailure(this.requestId, body);
     if (body.status !== void 0 && body.status !== "COMPLETED") {
       throw new SegmindError(`request ${this.requestId} is still ${String(body.status)}; use wait()`, {
         requestId: this.requestId,
@@ -568,15 +654,16 @@ var Job = class {
   /** Polls until the request finishes, then returns its result. */
   async wait(options = {}) {
     const timeout = options.timeout ?? DEFAULT_WAIT_TIMEOUT_MS;
-    const interval = options.interval ?? DEFAULT_WAIT_INTERVAL_MS;
     const started = Date.now();
     for (; ; ) {
       const status = await this.status({ signal: options.signal });
+      options.onStatus?.(status);
       if (status.status === "COMPLETED") return this.result({ signal: options.signal });
-      if (status.status === "FAILED") throw new InferenceFailed(this.requestId, status);
+      if (status.status === "FAILED") throw requestFailure(this.requestId, status);
       const elapsed = Date.now() - started;
       if (elapsed >= timeout) throw new InferenceTimeout(this.requestId, elapsed);
-      await sleep(Math.min(interval, timeout - elapsed), options.signal);
+      const delay = pollDelay(options.interval, elapsed, DEFAULT_WAIT_INTERVAL_MS);
+      await sleep(Math.min(delay, timeout - elapsed), options.signal);
     }
   }
   /**
@@ -608,8 +695,8 @@ var PixelFlows = class {
   client;
   /** Runs a workflow and waits for its outputs. */
   async run(slug, inputs = {}, options = {}) {
-    const job = await this.submit(slug, inputs, options);
-    return job.wait(options);
+    const job2 = await this.submit(slug, inputs, options);
+    return job2.wait(options);
   }
   /** Starts a workflow and returns a job to wait on. Never retried: a run bills. */
   async submit(slug, inputs = {}, options = {}) {
@@ -620,6 +707,7 @@ var PixelFlows = class {
       method: "POST",
       url: `${this.client.baseURL}${route}${clean}`,
       body: inputs,
+      headers: initiatorHeaders(options),
       signal: options.signal
     });
     const requestId = body.request_id;
@@ -655,20 +743,21 @@ var PixelflowJob = class {
   }
   /**
    * 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.
    */
   async wait(options = {}) {
     const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
-    const interval = options.interval ?? DEFAULT_INTERVAL_MS;
     const started = Date.now();
     for (; ; ) {
       const state = await this.status({ signal: options.signal });
+      options.onStatus?.(state);
       if (DONE.has(state.status)) return state;
-      if (FAILED.has(state.status)) throw new InferenceFailed(this.requestId, state.raw, failureDetail(state.raw));
+      if (FAILED.has(state.status)) throw requestFailure(this.requestId, state.raw, failureDetail(state.raw));
       const elapsed = Date.now() - started;
-      if (elapsed + interval > timeout) throw new InferenceTimeout(this.requestId, elapsed);
-      await sleep(interval, options.signal);
+      const delay = pollDelay(options.interval, elapsed, DEFAULT_INTERVAL_MS);
+      if (elapsed + delay > timeout) throw new InferenceTimeout(this.requestId, elapsed);
+      await sleep(delay, options.signal);
     }
   }
 };
@@ -713,7 +802,7 @@ function failureDetail(body) {
 }
 
 // src/version.ts
-var VERSION = "0.2.3";
+var VERSION = "0.3.0";
 
 // src/webhooks.ts
 var Webhooks = class {
@@ -732,16 +821,26 @@ var Webhooks = class {
       signal: options.signal
     });
   }
-  /** Changes a registration's URL and event types. */
-  async update(webhookId, webhookUrl, eventTypes, options = {}) {
-    return this.call("POST", "/update", {
-      body: { webhook_id: webhookId, webhook_url: webhookUrl, event: { types: requireTypes(eventTypes) } },
-      signal: options.signal
+  /**
+   * Points an active registration at a new URL. The event types stay as
+   * registered: to change them, `delete` the registration and `add` a new one.
+   *
+   * @param _eventTypes Ignored. Kept so 0.2 calls still compile; the API never
+   *   changed event types in place.
+   */
+  async update(webhookId, webhookUrl, _eventTypes, options = {}) {
+    return this.call("PUT", "/update", {
+      body: { webhook_id: webhookId, webhook_url: webhookUrl },
+      signal: options.signal,
+      retry: true
     });
   }
-  /** Deactivates a registration. */
+  /**
+   * Deactivates a registration. Not retried: a second attempt after a lost
+   * response would report the registration as already deactivated.
+   */
   async delete(webhookId, options = {}) {
-    return this.call("GET", "/inactive", { query: { webhook_id: webhookId }, signal: options.signal, retry: true });
+    return this.call("DELETE", "/inactive", { query: { webhook_id: webhookId }, signal: options.signal });
   }
   /** Delivery history for one registration. */
   async logs(webhookId, options = {}) {
@@ -781,14 +880,17 @@ var Segmind = class {
   /** @internal */
   http;
   constructor(options = {}) {
-    const apiKey = options.apiKey ?? readEnv("SEGMIND_API_KEY");
+    if (options.apiKey && options.tokenProvider) {
+      throw new SegmindError("Pass either apiKey or tokenProvider, not both.");
+    }
+    const apiKey = options.apiKey ?? (options.tokenProvider ? void 0 : readEnv("SEGMIND_API_KEY"));
     const runtime = detectRuntime();
     if (apiKey && (runtime === "browser" || runtime === "react-native") && !options.dangerouslyAllowBrowser) {
       throw new SegmindError(
         "An API key in a browser or mobile app exposes it to every user. Call Segmind from your backend instead, or pass dangerouslyAllowBrowser: true if you accept that risk."
       );
     }
-    if (!apiKey) {
+    if (!apiKey && !options.tokenProvider) {
       throw new SegmindError("Missing API key: pass { apiKey } or set the SEGMIND_API_KEY environment variable.");
     }
     const fetchImpl = options.fetch ?? globalThis.fetch?.bind(globalThis);
@@ -797,11 +899,17 @@ var Segmind = class {
     this.spotURL = trimSlash(options.spotURL ?? DEFAULT_SPOT_URL);
     this.consoleURL = trimSlash(options.consoleURL ?? DEFAULT_CONSOLE_URL);
     this.assetsURL = trimSlash(options.assetsURL ?? DEFAULT_ASSETS_URL);
-    const headers = { "X-Initiator": "SDK-JS", ...options.defaultHeaders };
+    const headers = {
+      "X-Initiator": "SDK-JS",
+      ...initiatorHeaders(options),
+      ...options.defaultHeaders
+    };
     const node = nodeVersion();
     if (runtime === "node" && node) headers["User-Agent"] = `segmind-js/${VERSION} node/${node}`;
     this.http = new HttpClient({
       apiKey,
+      tokenProvider: options.tokenProvider,
+      onUnauthorized: options.onUnauthorized,
       fetch: fetchImpl,
       timeout: options.timeout ?? 6e5,
       maxRetries: options.maxRetries ?? 2,
@@ -819,8 +927,8 @@ var Segmind = class {
    * until it finishes. `params` go to the model unchanged.
    */
   async run(slug, params = {}, options = {}) {
-    const job = await this.submit(slug, params, options);
-    return job.wait(options);
+    const job2 = await this.submit(slug, params, options);
+    return job2.wait(options);
   }
   /**
    * One blocking `POST /v1/{slug}`. Returns the fetch `Response`: call
@@ -832,6 +940,7 @@ var Segmind = class {
       method: "POST",
       url: `${this.baseURL}/v1/${path(slug)}`,
       body: params,
+      headers: initiatorHeaders(options),
       signal: options.signal,
       timeout: options.timeout
     });
@@ -844,10 +953,27 @@ var Segmind = class {
   async submit(slug, params = {}, options = {}) {
     return this.submitJob(slug, params, options, (body) => body);
   }
+  /**
+   * 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) {
+    const clean = requestId.trim();
+    if (!clean) throw new SegmindError("A request id is required.");
+    const url = `${this.baseURL}/v2/requests/${encodeURIComponent(clean)}`;
+    return new Job(this.http, {
+      request_id: clean,
+      status: "UNKNOWN",
+      status_url: `${url}/status`,
+      response_url: url
+    });
+  }
   /** Chat with an LLM through the v2 queue. Returns a provider-neutral reply. */
   async chat(slug, params, options = {}) {
-    const job = await this.submitChat(slug, params, options);
-    return job.wait(options);
+    const job2 = await this.submitChat(slug, params, options);
+    return job2.wait(options);
   }
   /** Chat with one blocking `POST /v1/{slug}`. */
   async chatSync(slug, params, options = {}) {
@@ -870,7 +996,7 @@ var Segmind = class {
           method: "POST",
           url,
           body: params,
-          headers: { "X-Request-ID": requestId },
+          headers: { "X-Request-ID": requestId, ...initiatorHeaders(options) },
           signal: options.signal
         });
       } catch (err) {
@@ -889,7 +1015,7 @@ var Segmind = class {
             body
           });
         }
-        return new Job(this.http, validateSubmit(body, response.status), transform);
+        return new Job(this.http, onBase(validateSubmit(body, response.status), this.baseURL), transform);
       }
       if (canRetry && response.status === 503) {
         await response.body?.cancel().catch(() => void 0);
@@ -906,21 +1032,62 @@ var Segmind = class {
     }
   }
 };
+var MODELS_PAGE_LIMIT = 100;
 var Models = class {
   constructor(client2) {
     this.client = client2;
   }
   client;
-  /** Every model in the catalog, under the key `Inference Model Information List`. */
-  async list(options = {}) {
+  /** One page of the catalog. Pass `offset` from the previous page while `has_more` is true. */
+  async list(params = {}, options = {}) {
     return this.client.http.json({
       method: "GET",
-      url: `${this.client.spotURL}/inference-model-information/list`,
+      url: `${this.client.baseURL}/models`,
+      query: modelsQuery(params),
       signal: options.signal,
       retry: true
     });
   }
+  /** Every model matching `params`, reading page after page. */
+  async listAll(params = {}, options = {}) {
+    const models2 = [];
+    for (let offset = 0; ; ) {
+      const page = await this.list({ ...params, limit: MODELS_PAGE_LIMIT, offset }, options);
+      models2.push(...page.models);
+      offset += page.models.length;
+      if (!page.has_more || !page.models.length || offset >= page.total) return models2;
+    }
+  }
 };
+function modelsQuery(p) {
+  return {
+    q: p.q,
+    sort: p.sort,
+    category: p.category,
+    modality: p.modality,
+    input: joinList(p.input),
+    output: joinList(p.output),
+    provider: p.provider,
+    slugs: joinList(p.slugs),
+    operations: joinList(p.operations),
+    features: joinList(p.features),
+    min_popularity: p.minPopularity,
+    min_category_percentile: p.minCategoryPercentile,
+    min_cost: p.minCost,
+    max_cost: p.maxCost,
+    max_latency: p.maxLatency,
+    is_new: p.isNew,
+    created_after: p.createdAfter,
+    include_coming_soon: p.includeComingSoon,
+    facets: p.facets,
+    limit: p.limit,
+    offset: p.offset
+  };
+}
+function joinList(value) {
+  if (value === void 0) return void 0;
+  return Array.isArray(value) ? value.join(",") : value;
+}
 var Accounts = class {
   constructor(client2) {
     this.client = client2;
@@ -935,6 +1102,16 @@ var Accounts = class {
       retry: true
     });
   }
+  /** The current credit balance. */
+  async credits(options = {}) {
+    const { "free-credits": freeCredits, ...rest } = await this.client.http.json({
+      method: "GET",
+      url: `${this.client.baseURL}/v1/get-user-credits`,
+      signal: options.signal,
+      retry: true
+    });
+    return { ...rest, credits: Number(rest.credits), freeCredits: Number(freeCredits) };
+  }
 };
 function validateSubmit(body, status) {
   if (!body.request_id || !body.status_url || !body.response_url) {
@@ -950,6 +1127,14 @@ function path(slug) {
   if (!clean) throw new SegmindError("A model slug is required.");
   return clean;
 }
+function onBase(body, baseURL) {
+  const origin = new URL(baseURL).origin;
+  const pin = (url) => {
+    const target = new URL(url, `${baseURL}/`);
+    return target.origin === origin ? target.href : `${baseURL}${target.pathname}${target.search}`;
+  };
+  return { ...body, status_url: pin(body.status_url), response_url: pin(body.response_url) };
+}
 function trimSlash(url) {
   return url.replace(/\/+$/, "");
 }
@@ -975,14 +1160,17 @@ function client() {
 var run = (slug, params, options) => client().run(slug, params, options);
 var runSync = (slug, params, options) => client().runSync(slug, params, options);
 var submit = (slug, params, options) => client().submit(slug, params, options);
+var job = (requestId) => client().job(requestId);
 var chat = (slug, params, options) => client().chat(slug, params, options);
 var chatSync = (slug, params, options) => client().chatSync(slug, params, options);
 var submitChat = (slug, params, options) => client().submitChat(slug, params, options);
 var models = {
-  list: (options) => client().models.list(options)
+  list: (params, options) => client().models.list(params, options),
+  listAll: (params, options) => client().models.listAll(params, options)
 };
 var accounts = {
-  current: (options) => client().accounts.current(options)
+  current: (options) => client().accounts.current(options),
+  credits: (options) => client().accounts.credits(options)
 };
 var files = {
   upload: ((input, options) => client().files.upload(input, options))
@@ -1019,10 +1207,12 @@ export {
   Generations,
   InferenceFailed,
   InferenceTimeout,
+  InsufficientCredits,
   Job,
   Models,
   PixelFlows,
   PixelflowJob,
+  RateLimited,
   Segmind,
   SegmindError,
   VERSION,
@@ -1033,6 +1223,7 @@ export {
   files,
   generations,
   imageUrl,
+  job,
   models,
   pixelflows,
   run,