@worldlabsai/client 0.1.0

package/src/core/assets.ts

@@ -0,0 +1,162 @@
+import type {
+  Asset,
+  AssetCreate,
+  CompleteUploadRequest,
+  CreateAssetResponse,
+  CreateReadUrlResponse,
+  CreateUploadUrlResponse,
+  ListAssetsResponse,
+  TaskAsset,
+} from "../generated/developer-api.gen.ts";
+import { ApiError } from "./transport.ts";
+import type { Transport } from "./transport.ts";
+
+/** Settings for uploading asset bytes. */
+export interface UploadOptions extends Pick<RequestInit, "signal"> {
+  /** Name shown for the asset. */
+  displayName: string;
+  /** Overrides `Blob.type`. Required for byte arrays or a `Blob` without a type. */
+  mimeType?: string;
+}
+
+/** Pagination and cancellation settings for listing assets. */
+export interface ListAssetsOptions extends Pick<RequestInit, "signal"> {
+  /** Maximum number of assets to return. */
+  pageSize?: number;
+  /** `nextPageToken` from the previous list response. Omit for the first page. */
+  pageToken?: string;
+}
+
+/** Return the id an asset is addressed by in task requests. */
+export const assetId = (asset: Asset): string => asset.id;
+
+/** Convert an asset resource into a task media reference. */
+export const assetRef = (asset: Asset): TaskAsset => ({ assetId: assetId(asset) });
+
+const toBlob = (data: Blob | BufferSource, mimeType: string | undefined): Blob => {
+  if (data instanceof Blob) {
+    return mimeType === undefined || mimeType === data.type
+      ? data
+      : new Blob([data], { type: mimeType });
+  }
+  return new Blob([data], { type: mimeType ?? "" });
+};
+
+/**
+ * Create asset upload and management methods.
+ * @param transport - Authenticated API transport, with a separate fetch for signed uploads.
+ * @param assetsPath - Asset collection route. Item routes append an `{asset}` placeholder.
+ */
+export const createAssets = (transport: Transport, assetsPath: string) => {
+  const itemPath = `${assetsPath}/{asset}`;
+
+  const create = async (asset: AssetCreate, signal?: AbortSignal | null) =>
+    await transport.request<CreateAssetResponse>(assetsPath, {
+      body: { asset },
+      method: "POST",
+      ...(signal ? { signal } : {}),
+    });
+
+  const completeUpload = async (
+    id: string,
+    body: CompleteUploadRequest = {},
+    options: Pick<RequestInit, "signal"> = {},
+  ) =>
+    await transport.request<Asset>(`${itemPath}:completeUpload`, {
+      body,
+      method: "POST",
+      params: { asset: id },
+      ...options,
+    });
+
+  return {
+    /**
+     * Finalize an asset after its bytes have been uploaded.
+     * @param id - Asset ID from {@link assetId}.
+     * @returns The updated asset resource.
+     */
+    completeUpload,
+
+    /** Create an asset record. Use `upload` to create and upload a single file in one call. */
+    create: async (asset: AssetCreate, options: Pick<RequestInit, "signal"> = {}) =>
+      await create(asset, options.signal),
+
+    /**
+     * Create a temporary signed URL for reading an asset's stored bytes.
+     * @param id - Asset ID from {@link assetId}.
+     */
+    createReadUrl: async (id: string, options: Pick<RequestInit, "signal"> = {}) =>
+      await transport.request<CreateReadUrlResponse>(`${itemPath}:createReadUrl`, {
+        method: "POST",
+        params: { asset: id },
+        ...options,
+      }),
+
+    /**
+     * Soft-delete an asset.
+     * @param id - Asset ID from {@link assetId}.
+     */
+    delete: async (id: string, options: Pick<RequestInit, "signal"> = {}) => {
+      await transport.request(itemPath, { method: "DELETE", params: { asset: id }, ...options });
+    },
+
+    /**
+     * Fetch asset metadata.
+     * @param id - Asset ID from {@link assetId}.
+     */
+    get: async (id: string, options: Pick<RequestInit, "signal"> = {}) =>
+      await transport.request<Asset>(itemPath, { params: { asset: id }, ...options }),
+
+    /** Return one page of assets. Pass the response's `nextPageToken` to retrieve the next page. */
+    list: async ({ pageSize, pageToken, ...options }: ListAssetsOptions = {}) =>
+      await transport.request<ListAssetsResponse>(assetsPath, {
+        query: { pageSize, pageToken },
+        ...options,
+      }),
+
+    /**
+     * Create an asset, upload the bytes, and mark the upload complete.
+     *
+     * @param data - Bytes to upload. A `Blob` supplies its own MIME type when present.
+     * @param options - Display name, MIME type, and cancellation settings.
+     * @returns The completed asset. Pass it to {@link assetRef} to use it in a task.
+     * @throws {Error} If neither `mimeType` nor the input `Blob` supplies a MIME type.
+     * @throws {ApiError} If an API request or storage upload fails with a non-2xx status.
+     */
+    upload: async (data: Blob | BufferSource, { displayName, mimeType, signal }: UploadOptions) => {
+      const blob = toBlob(data, mimeType);
+      if (blob.type === "") {
+        throw new Error("upload needs a mimeType when the data does not carry one");
+      }
+      const init = signal ? { signal } : {};
+
+      const created = await create({ displayName }, signal);
+      const id = assetId(created);
+
+      const ticket = await transport.request<CreateUploadUrlResponse>(
+        `${itemPath}:createUploadUrl`,
+        {
+          body: { contentLength: blob.size, contentType: blob.type },
+          method: "POST",
+          params: { asset: id },
+          ...init,
+        },
+      );
+
+      // The signed URL belongs to the storage host: no base URL, no API auth.
+      const stored = await transport.fetch(
+        new Request(ticket.uploadUrl, {
+          body: blob,
+          headers: ticket.headers ?? {},
+          method: ticket.method,
+          ...init,
+        }),
+      );
+      if (!stored.ok) {
+        throw new ApiError(stored, await stored.text());
+      }
+
+      return await completeUpload(id, { sizeBytes: blob.size }, init);
+    },
+  };
+};

package/src/core/index.ts

@@ -0,0 +1,27 @@
+export {
+  assetId,
+  assetRef,
+  createAssets,
+  type ListAssetsOptions,
+  type UploadOptions,
+} from "./assets.ts";
+export {
+  createOperations,
+  type DoneOperation,
+  type Operation,
+  waitForOperation,
+  type WaitOptions,
+} from "./operations.ts";
+export { type SubmitOptions, submitTask } from "./tasks.ts";
+export {
+  ApiError,
+  type ApiKey,
+  apiKeyAuth,
+  createTransport,
+  type Fetch,
+  type Middleware,
+  type RequestOptions,
+  type Transport,
+  type TransportOptions,
+  withHeader,
+} from "./transport.ts";

package/src/core/operations.ts

@@ -0,0 +1,114 @@
+import type { Operation as WireOperation } from "../generated/developer-api.gen.ts";
+import { sleep } from "./sleep.ts";
+import { ApiError } from "./transport.ts";
+import type { Transport } from "./transport.ts";
+
+/**
+ * A long-running task operation whose `response` is typed by the task that created it.
+ * A pending operation has `done: false`; a finished operation has `done: true` and
+ * may contain either a response or an error reported by the task.
+ */
+export type Operation<TResponse = Record<string, unknown>> = Omit<WireOperation, "response"> & {
+  response?: TResponse | null;
+};
+
+/** A task operation known to have finished. Inspect `error` before using `response`. */
+export type DoneOperation<TResponse> = Operation<TResponse> & { done: true };
+
+/** Polling and local cancellation settings. Waiting has no default overall timeout. */
+export interface WaitOptions extends Pick<RequestInit, "signal"> {
+  /** Delay after an incomplete poll, in milliseconds. Defaults to 1,000 ms. */
+  pollIntervalMs?: number;
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+
+/**
+ * Poll an operation until it reports `done`.
+ * Checks for cancellation before each poll and passes the signal to `fetchOperation`.
+ *
+ * @param fetchOperation - Fetches the current state; honor its signal to abort an in-flight poll.
+ * @param options - Polling interval and cancellation settings.
+ * @returns The finished operation, which may contain `error` instead of `response`.
+ */
+export const waitForOperation = async <TResponse>(
+  fetchOperation: (signal?: AbortSignal | null) => Promise<Operation<TResponse>>,
+  { pollIntervalMs = DEFAULT_POLL_INTERVAL_MS, signal }: WaitOptions = {},
+): Promise<DoneOperation<TResponse>> => {
+  // oxlint-disable no-await-in-loop -- polling is sequential by definition
+  for (;;) {
+    signal?.throwIfAborted();
+    const operation = await fetchOperation(signal);
+    if (operation.done) {
+      return { ...operation, done: true };
+    }
+    await sleep(pollIntervalMs, signal);
+  }
+  // oxlint-enable no-await-in-loop
+};
+
+/**
+ * Create operation lookup and polling methods.
+ * @param transport - Authenticated API transport.
+ * @param operationPath - Lookup route containing an `{operation}` placeholder.
+ */
+export const createOperations = (transport: Transport, operationPath: string) => {
+  const get = async <TResponse = Record<string, unknown>>(
+    operationId: string,
+    { signal, wait }: Pick<RequestInit, "signal"> & { wait?: boolean } = {},
+  ) =>
+    await transport.request<Operation<TResponse>>(operationPath, {
+      params: { operation: operationId },
+      query: { wait },
+      ...(signal ? { signal } : {}),
+    });
+
+  return {
+    /** Fetch the current state of an operation by its id. */
+    get: async (operationId: string, options: Pick<RequestInit, "signal"> = {}) =>
+      await get(operationId, options),
+
+    /**
+     * Poll until an operation is done. The returned operation keeps the response type
+     * associated with the task that created it.
+     *
+     * An operation can finish with an API-reported task error; inspect `error` before
+     * reading `response`. Aborting stops local waiting without canceling the task.
+     * HTTP 502, 503, and 504 polling failures are retried up to three times in a row;
+     * a successful poll resets the retry count.
+     *
+     * @param operation - Operation returned by task submission. Completed operations return immediately.
+     * @param options - Polling interval and abort signal; no overall timeout by default.
+     * @throws {ApiError} If polling fails with an unretried status or exhausts gateway retries.
+     */
+    wait: async <TResponse>(operation: Operation<TResponse>, options?: WaitOptions) => {
+      options?.signal?.throwIfAborted();
+      if (operation.done) {
+        return { ...operation, done: true as const };
+      }
+      let gatewayErrors = 0;
+      return await waitForOperation<TResponse>(async (signal) => {
+        try {
+          const current = await get<TResponse>(operation.id, {
+            ...(signal ? { signal } : {}),
+            wait: true,
+          });
+          gatewayErrors = 0;
+          return current;
+        } catch (error) {
+          // A gateway timeout does not cancel the task. Resume the same read;
+          // the caller's signal still bounds the entire wait, including retries.
+          gatewayErrors += 1;
+          if (
+            !(error instanceof ApiError) ||
+            ![502, 503, 504].includes(error.response.status) ||
+            gatewayErrors > 3
+          ) {
+            throw error;
+          }
+          return operation;
+        }
+      }, options);
+    },
+  };
+};

package/src/core/sleep.ts

@@ -0,0 +1,22 @@
+/**
+ * Resolves after `ms`, or as soon as `signal` aborts. Uses `setTimeout` rather than
+ * `AbortSignal.timeout` because Node does not keep the event loop alive for the latter;
+ * a script whose only pending work is this sleep would exit before the next poll.
+ */
+export const sleep = async (ms: number, signal?: AbortSignal | null): Promise<void> => {
+  if (signal?.aborted) {
+    return;
+  }
+  // oxlint-disable-next-line promise/avoid-new -- waiting on a timer has no promise-returning API
+  await new Promise<void>((resolve) => {
+    const finish = (): void => {
+      // oxlint-disable-next-line no-use-before-define -- finish runs after the timer is initialized
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", finish);
+      // oxlint-disable-next-line promise/no-multiple-resolved -- cleanup does not invoke the callbacks
+      resolve();
+    };
+    const timer = setTimeout(finish, ms);
+    signal?.addEventListener("abort", finish, { once: true });
+  });
+};

package/src/core/tasks.ts

@@ -0,0 +1,45 @@
+import type { Transport } from "./transport.ts";
+
+export interface SubmitOptions extends Pick<RequestInit, "signal"> {
+  /**
+   * Ask the server to wait up to its time limit. The returned operation may still
+   * be running; use `operations.wait` to await completion. Defaults to false.
+   */
+  wait?: boolean;
+  /**
+   * Nonempty key shared by every attempt. Defaults to a fresh UUID per call;
+   * reuse your own key when retrying across calls or processes.
+   */
+  idempotencyKey?: string;
+}
+
+/**
+ * Submit a task request and return its operation resource.
+ * Retries network failures and HTTP 429/502/503/504 up to three times with the
+ * same key and body. Uses jittered exponential backoff and honors Retry-After.
+ *
+ * @param transport - Transport used to send the request.
+ * @param path - Task submission path.
+ * @param body - Task-specific request payload.
+ * @param options - Server wait, idempotency key, and local cancellation settings.
+ * @returns The operation created for the task.
+ * @throws {ApiError} If the API rejects the submission or retries are exhausted.
+ */
+export const submitTask = async <TOperation>(
+  transport: Transport,
+  path: string,
+  body: unknown,
+  { idempotencyKey = crypto.randomUUID(), signal, wait }: SubmitOptions = {},
+): Promise<TOperation> => {
+  if (idempotencyKey.trim() === "") {
+    throw new Error("Idempotency key must not be empty");
+  }
+  return await transport.request<TOperation>(path, {
+    body,
+    headers: { "Idempotency-Key": idempotencyKey },
+    method: "POST",
+    query: { wait },
+    retry: true,
+    ...(signal ? { signal } : {}),
+  });
+};

package/src/core/transport.ts

@@ -0,0 +1,246 @@
+import { sleep } from "./sleep.ts";
+
+/** Handles a `Request` for API calls and signed uploads; standard `fetch` is compatible. */
+export type Fetch = (request: Request) => Promise<Response>;
+
+/**
+ * Middleware around a request handler. It may alter the request, return a response
+ * without calling `next`, call `next` more than once for retries, or inspect the response.
+ * Clone requests before sending them if a retry may need to reuse the body.
+ */
+export type Middleware = (request: Request, next: Fetch) => Promise<Response>;
+
+/** Values accepted in a request query. `null` and `undefined` are omitted. */
+export type QueryValue = string | number | boolean | null | undefined;
+
+/**
+ * Options for a JSON API request. Other Fetch settings, including headers and an
+ * abort signal, pass through to the request.
+ */
+export interface RequestOptions extends Omit<RequestInit, "body"> {
+  /** Values URL-encoded into `{name}` placeholders in the path. */
+  params?: Record<string, string>;
+  /** Query values. `null` and `undefined` entries are omitted. */
+  query?: Record<string, QueryValue>;
+  /** JSON-serializable request body. */
+  body?: unknown;
+  /** Retry transient failures up to three times. Requires an idempotent request. */
+  retry?: boolean;
+}
+
+/** Configuration for the fetch transport. */
+export interface TransportOptions {
+  /** API origin used to resolve request paths. Trailing slashes are ignored. */
+  baseUrl: string | URL;
+  /** Fetch implementation for API requests and uploads. Defaults to `globalThis.fetch`. */
+  fetch?: Fetch;
+  /** Middleware applied to API requests, in outermost-first order. */
+  middleware?: Middleware[];
+  /** Path values used when a request does not provide its own value. */
+  pathParams?: Record<string, string>;
+}
+
+/** FastAPI puts its reason under `detail`; operation and storage errors use `message`. */
+const errorDetail = (body: unknown): string | undefined => {
+  if (typeof body !== "object" || body === null) {
+    return undefined;
+  }
+  for (const key of ["detail", "message"]) {
+    const value = Reflect.get(body, key);
+    if (typeof value === "string" && value !== "") {
+      return value;
+    }
+  }
+  return undefined;
+};
+
+/** An API request or signed upload returned a non-2xx HTTP status. */
+export class ApiError extends Error {
+  override name = "ApiError";
+  /** HTTP status and headers. The response body has already been consumed. */
+  readonly response: Response;
+  /**
+   * Parsed JSON or text for API failures; raw text for upload failures.
+   * Empty API response bodies are `undefined`.
+   */
+  readonly body: unknown;
+
+  constructor(response: Response, body: unknown) {
+    const where = response.url === "" ? "" : ` for ${response.url}`;
+    super(`${response.status} ${errorDetail(body) ?? response.statusText}${where}`);
+    this.response = response;
+    this.body = body;
+  }
+}
+
+const fillPath = (path: string, params: Record<string, string>): string =>
+  path.replaceAll(/\{(?<name>\w+)\}/gu, (_, name: string) => {
+    const value = params[name];
+    if (value === undefined) {
+      throw new Error(`Missing path parameter "${name}" for ${path}`);
+    }
+    return encodeURIComponent(value);
+  });
+
+const compose = (middleware: Middleware[], fetch: Fetch): Fetch => {
+  let next = fetch;
+  for (const layer of middleware.toReversed()) {
+    const inner = next;
+    next = async (request) => await layer(request, inner);
+  }
+  return next;
+};
+
+const parseBody = async (response: Response): Promise<unknown> => {
+  const text = await response.text();
+  if (text === "") {
+    return undefined;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+};
+
+const RETRYABLE_STATUS_CODES = new Set([429, 502, 503, 504]);
+
+const retryDelay = (error: unknown, attempt: number): number => {
+  const backoff = 1000 * 2 ** attempt * (0.5 + Math.random() / 2);
+  const value =
+    error instanceof ApiError ? error.response.headers.get("retry-after")?.trim() : undefined;
+  if (!value) {
+    return backoff;
+  }
+  const delay = /^\d+$/u.test(value) ? Number(value) * 1000 : Date.parse(value) - Date.now();
+  return Math.max(backoff, Number.isFinite(delay) ? delay : 0);
+};
+
+export interface Transport {
+  /**
+   * Send a request and parse its response as JSON, falling back to text.
+   * Empty responses resolve to `undefined`; `T` is not validated at runtime.
+   * @throws {ApiError} If the response has a non-2xx status.
+   */
+  request: <T>(path: string, init?: RequestOptions) => Promise<T>;
+  /** Run middleware and fetch, leaving status handling and body parsing to the caller. */
+  send: Fetch;
+  /**
+   * Send a request without the API base URL, middleware, or auth. Use for URLs
+   * supplied by the API, such as signed upload URLs.
+   */
+  fetch: Fetch;
+}
+
+/**
+ * Create a JSON-over-fetch transport for an API surface.
+ *
+ * Requests use `baseUrl`, substitute path and query values, serialize `body` as JSON,
+ * and pass through middleware. Non-2xx responses reject with {@link ApiError}.
+ *
+ * @param options - Transport origin, fetch implementation, middleware, and bound paths.
+ * @returns JSON requests, raw requests through middleware, and the underlying fetch function.
+ */
+export const createTransport = (options: TransportOptions): Transport => {
+  const fetch = options.fetch ?? (async (request: Request) => await globalThis.fetch(request));
+  const send = compose(options.middleware ?? [], fetch);
+  const baseUrl = String(options.baseUrl).replace(/\/+$/u, "");
+  const boundParams = options.pathParams ?? {};
+
+  return {
+    fetch,
+    send,
+    request: async <T>(
+      path: string,
+      { body, params, query, retry = false, ...init }: RequestOptions = {},
+    ): Promise<T> => {
+      const url = new URL(baseUrl + fillPath(path, { ...boundParams, ...params }));
+      for (const [key, value] of Object.entries(query ?? {})) {
+        if (value !== undefined && value !== null) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+      const headers = new Headers(init.headers);
+      if (body !== undefined) {
+        headers.set("content-type", "application/json");
+      }
+      const request = new Request(url, {
+        ...init,
+        headers,
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      });
+
+      // Provider and middleware TypeErrors must not be mistaken for network failures.
+      let networkError: unknown;
+      const sendRequest = retry
+        ? compose(options.middleware ?? [], async (attempt) => {
+            try {
+              return await fetch(attempt);
+            } catch (error) {
+              networkError = error;
+              throw error;
+            }
+          })
+        : send;
+
+      // oxlint-disable no-await-in-loop -- retries are sequential and preserve the original request
+      for (let attempt = 0; ; attempt += 1) {
+        request.signal.throwIfAborted();
+        networkError = undefined;
+        try {
+          const response = await sendRequest(retry ? request.clone() : request);
+          let parsed: unknown;
+          try {
+            parsed = await parseBody(response);
+          } catch (error) {
+            if (!response.ok) {
+              throw new ApiError(response, undefined);
+            }
+            networkError = error;
+            throw error;
+          }
+          if (!response.ok) {
+            throw new ApiError(response, parsed);
+          }
+          // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- JSON boundary
+          return parsed as T;
+        } catch (error) {
+          request.signal.throwIfAborted();
+          const transient =
+            error instanceof ApiError
+              ? RETRYABLE_STATUS_CODES.has(error.response.status)
+              : error instanceof TypeError && error === networkError;
+          if (!retry || attempt >= 3 || !transient) {
+            throw error;
+          }
+          await sleep(retryDelay(error, attempt), request.signal);
+        }
+      }
+      // oxlint-enable no-await-in-loop
+    },
+  };
+};
+
+/** Return a request with one header set, preserving its method, body, and other headers. */
+export const withHeader = (request: Request, name: string, value: string): Request => {
+  const headers = new Headers(request.headers);
+  headers.set(name, value);
+  return new Request(request, { headers });
+};
+
+/** API key, or a provider resolved immediately before each API request. */
+export type ApiKey = string | (() => string | Promise<string>);
+
+/**
+ * Create middleware that resolves an API key and sends it as `WLT-Api-Key`.
+ *
+ * @param apiKey - Key or provider resolved before each request.
+ * @throws {Error} On a request whose key is empty. Provider failures also propagate before sending.
+ */
+export const apiKeyAuth =
+  (apiKey: ApiKey): Middleware =>
+  async (request, next) => {
+    const key = typeof apiKey === "function" ? await apiKey() : apiKey;
+    if (!key) throw new Error("No API key is available for the Developer API request");
+    return await next(withHeader(request, "WLT-Api-Key", key));
+  };