@worldlabsai/client 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,109 @@
+# @worldlabsai/client
+
+Upload images, submit World Labs tasks, and retrieve typed results with the
+World Labs Developer API client for JavaScript and TypeScript.
+
+**Zero runtime dependencies.** The client uses the standard Fetch API and ships
+as ES modules. It supports Node.js 22+ and other Fetch-compatible runtimes.
+Keep API keys on your server, out of browser bundles.
+
+## Install
+
+Install with `npm install @worldlabsai/client`.
+
+Methods marked `@beta` require beta access for your World Labs account.
+Use a World Labs Developer API key to authenticate API requests.
+
+## Usage
+
+The client provides `assets` for uploads, `tasks` for submissions, and
+`operations` for results. This example combines them to estimate camera poses
+and depth from a local `frame.png`, with `WLT_API_KEY` set on the server:
+
+```ts
+import { readFile } from "node:fs/promises";
+import { assetRef, createClient } from "@worldlabsai/client";
+
+const apiKey = process.env.WLT_API_KEY;
+if (!apiKey) throw new Error("Set WLT_API_KEY before running this example");
+
+const wl = createClient({ apiKey });
+const image = await wl.assets.upload(await readFile("./frame.png"), {
+  displayName: "frame.png",
+  mimeType: "image/png",
+});
+const operation = await wl.tasks.images2PosedRGBD({
+  frames: [{ imageAsset: assetRef(image) }],
+});
+const result = await wl.operations.wait(operation, {
+  signal: AbortSignal.timeout(120_000),
+});
+if (result.error) throw new Error(result.error.message ?? "Task failed");
+
+for (const { camera, depth } of result.response?.results ?? []) {
+  console.log(camera.extrinsics.position, depth.depthAsset.url);
+}
+```
+
+`assetRef` converts an uploaded asset into a task input. Task methods infer the
+operation's response type, which `operations.wait` preserves. Other tasks use
+the same submission and polling pattern.
+
+See [`examples/`](examples/) for runnable scripts.
+[`posing.ts`](examples/posing.ts) accepts a local file or a downloadable image
+URL and documents its environment variables.
+
+## Operations and errors
+
+A finished task can still have `result.error`; check that field before using
+`result.response`, as in the example above.
+
+HTTP failures reject with `ApiError`. Its `response.status` and `body` provide
+the status code and error details. Network failures and aborts reject with the
+underlying error.
+
+Aborting stops the local request or polling; it does not cancel the server-side
+task. Keep `operation.id` to check its status later with `operations.get(id)`.
+Polling has no default overall timeout. `pollIntervalMs` sets the pause between
+incomplete polls and defaults to 1,000 milliseconds.
+
+`operations.wait` retries HTTP 502, 503, and 504 polling failures up to three
+times in a row, with `pollIntervalMs` between attempts. A successful poll resets
+the retry count. Other failures, including HTTP 429 rate limits, reject without
+retrying.
+
+Task submissions retry network failures and HTTP 429, 502, 503, and 504 up to
+three times. Every attempt sends the same idempotency key and body. Retries use
+exponential backoff with jitter and wait at least as long as `Retry-After` when
+the server supplies it. Aborting the submission also stops retries. Validation
+and authentication failures are not retried.
+
+If you call the task method again yourself, reuse its `idempotencyKey`. Each
+method call otherwise generates a new key. Passing `{ wait: true }` when
+submitting asks the server to wait up to its own limit; it can still return an
+unfinished operation.
+
+## Client options
+
+Uploads accept bytes or a `Blob`. Set `mimeType` for byte arrays or a `Blob`
+without a type. Signed storage uploads use the configured `fetch` but bypass
+API middleware and API-key authentication.
+
+| Option       | Use                                                                                                                   |
+| ------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `apiKey`     | Your Developer API key, or a function that returns a key or a promise of one before each API request.                 |
+| `baseUrl`    | API base URL. Defaults to `https://api.atlas-beta.worldlabs.ai`.                                                      |
+| `fetch`      | Custom Fetch implementation for API requests and uploads. Defaults to `globalThis.fetch`.                             |
+| `middleware` | Wrap API requests for logging or retries. The first supplied middleware runs outermost, after API-key authentication. |
+
+An empty key or a rejected key provider stops the request before it is sent.
+Retry middleware must clone a request before sending it so its body can be
+sent again, and preserve the `Idempotency-Key` across attempts.
+
+See the [World Labs API documentation](https://docs.worldlabs.ai/) for API
+access and usage. JSDoc and TypeScript declarations in the package describe
+individual methods and options.
+
+## License
+
+Copyright 2026 World Labs. Licensed under the [Apache License, Version 2.0](LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,34 @@
+import { createAssets, createOperations } from "./core/index.ts";
+import type { ApiKey, Fetch, Middleware } from "./core/index.ts";
+import { createTasks } from "./generated/tasks.gen.ts";
+/** Developer API origin used when `ClientOptions.baseUrl` is omitted. */
+export declare const DEFAULT_BASE_URL = "https://api.atlas-beta.worldlabs.ai";
+/** Configuration for a {@link WorldLabsClient}. */
+export interface ClientOptions {
+    /** Key, or a provider resolved before each API request. Omit only when middleware handles auth. */
+    apiKey?: ApiKey;
+    /** Developer API origin. Defaults to {@link DEFAULT_BASE_URL}. */
+    baseUrl?: string;
+    /** Fetch implementation for API requests and uploads. Defaults to `globalThis.fetch`. */
+    fetch?: Fetch;
+    /** Wraps API requests after API-key auth, outermost first. Signed uploads bypass middleware. */
+    middleware?: Middleware[];
+}
+/** Client returned by {@link createClient}; reuse it across requests. */
+export interface WorldLabsClient {
+    /** Upload images and manage stored assets. */
+    assets: ReturnType<typeof createAssets>;
+    /** Check task status and wait for results. */
+    operations: ReturnType<typeof createOperations>;
+    /** Submit tasks with typed inputs and responses. */
+    tasks: ReturnType<typeof createTasks>;
+}
+/**
+ * Create a client for the World Labs Developer API.
+ *
+ * @param options - Authentication, API origin, fetch, and middleware settings.
+ * @returns Asset uploads, task submission, and operation polling methods.
+ * @throws {Error} If no API key and no middleware are supplied.
+ */
+export declare const createClient: (options: ClientOptions) => WorldLabsClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,YAAY,EAAE,gBAAgB,EAAmB,MAAM,iBAAiB,CAAC;AAC9F,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAc,WAAW,EAAiB,MAAM,0BAA0B,CAAC;AAElF,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,wCAAwC,CAAC;AAEtE,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC5B,mGAAmG;IACnG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,gGAAgG;IAChG,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;CAC3B;AAED,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,MAAM,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;IACxC,8CAA8C;IAC9C,UAAU,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;IAChD,oDAAoD;IACpD,KAAK,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;CACvC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,aAAa,KAAG,eAkBrD,CAAC"}

package/dist/client.js

@@ -0,0 +1,31 @@
+import { apiKeyAuth, createAssets, createOperations, createTransport } from "./core/index.js";
+import { assetsPath, createTasks, operationPath } from "./generated/tasks.gen.js";
+/** Developer API origin used when `ClientOptions.baseUrl` is omitted. */
+export const DEFAULT_BASE_URL = "https://api.atlas-beta.worldlabs.ai";
+/**
+ * Create a client for the World Labs Developer API.
+ *
+ * @param options - Authentication, API origin, fetch, and middleware settings.
+ * @returns Asset uploads, task submission, and operation polling methods.
+ * @throws {Error} If no API key and no middleware are supplied.
+ */
+export const createClient = (options) => {
+    const middleware = [
+        ...(options.apiKey === undefined ? [] : [apiKeyAuth(options.apiKey)]),
+        ...(options.middleware ?? []),
+    ];
+    if (middleware.length === 0) {
+        throw new Error("createClient needs an apiKey or middleware that authenticates requests");
+    }
+    const transport = createTransport({
+        baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+        middleware,
+    });
+    return {
+        assets: createAssets(transport, assetsPath),
+        operations: createOperations(transport, operationPath),
+        tasks: createTasks(transport),
+    };
+};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE9F,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAElF,yEAAyE;AACzE,MAAM,CAAC,MAAM,gBAAgB,GAAG,qCAAqC,CAAC;AAwBtE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAsB,EAAmB,EAAE;IACtE,MAAM,UAAU,GAAG;QACjB,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QACrE,GAAG,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC;KAC9B,CAAC;IACF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAC;IAC5F,CAAC;IACD,MAAM,SAAS,GAAG,eAAe,CAAC;QAChC,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,gBAAgB;QAC5C,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,UAAU;KACX,CAAC,CAAC;IACH,OAAO;QACL,MAAM,EAAE,YAAY,CAAC,SAAS,EAAE,UAAU,CAAC;QAC3C,UAAU,EAAE,gBAAgB,CAAC,SAAS,EAAE,aAAa,CAAC;QACtD,KAAK,EAAE,WAAW,CAAC,SAAS,CAAC;KAC9B,CAAC;AACJ,CAAC,CAAC"}

package/dist/core/assets.d.ts

@@ -0,0 +1,138 @@
+import type { Asset, AssetCreate, CompleteUploadRequest, TaskAsset } from "../generated/developer-api.gen.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 declare const assetId: (asset: Asset) => string;
+/** Convert an asset resource into a task media reference. */
+export declare const assetRef: (asset: Asset) => TaskAsset;
+/**
+ * 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 declare const createAssets: (transport: Transport, assetsPath: string) => {
+    /**
+     * Finalize an asset after its bytes have been uploaded.
+     * @param id - Asset ID from {@link assetId}.
+     * @returns The updated asset resource.
+     */
+    completeUpload: (id: string, body?: CompleteUploadRequest, options?: Pick<RequestInit, "signal">) => Promise<{
+        id: string;
+        displayName: string;
+        mimeType: string;
+        state?: import("../generated/developer-api.gen.ts").components["schemas"]["AssetState"];
+        width?: number | null;
+        height?: number | null;
+        sizeBytes?: string | null;
+        checksum?: string | null;
+        createTime?: string | null;
+        type?: string | null;
+        parts?: import("../generated/developer-api.gen.ts").components["schemas"]["AssetPart"][];
+        structure?: {
+            [key: string]: unknown;
+        } | null;
+        producedBy?: import("../generated/developer-api.gen.ts").components["schemas"]["ProducedBy"] | null;
+        contentPath?: string | null;
+    }>;
+    /** Create an asset record. Use `upload` to create and upload a single file in one call. */
+    create: (asset: AssetCreate, options?: Pick<RequestInit, "signal">) => Promise<{
+        id: string;
+        displayName: string;
+        mimeType: string;
+        state?: import("../generated/developer-api.gen.ts").components["schemas"]["AssetState"];
+        width?: number | null;
+        height?: number | null;
+        sizeBytes?: string | null;
+        checksum?: string | null;
+        createTime?: string | null;
+        type?: string | null;
+        parts?: import("../generated/developer-api.gen.ts").components["schemas"]["AssetPart"][];
+        structure?: {
+            [key: string]: unknown;
+        } | null;
+        producedBy?: import("../generated/developer-api.gen.ts").components["schemas"]["ProducedBy"] | null;
+        contentPath?: string | null;
+        uploads?: import("../generated/developer-api.gen.ts").components["schemas"]["UploadGrant"][];
+    }>;
+    /**
+     * Create a temporary signed URL for reading an asset's stored bytes.
+     * @param id - Asset ID from {@link assetId}.
+     */
+    createReadUrl: (id: string, options?: Pick<RequestInit, "signal">) => Promise<{
+        readUrl: string;
+        expiresAt: string;
+    }>;
+    /**
+     * Soft-delete an asset.
+     * @param id - Asset ID from {@link assetId}.
+     */
+    delete: (id: string, options?: Pick<RequestInit, "signal">) => Promise<void>;
+    /**
+     * Fetch asset metadata.
+     * @param id - Asset ID from {@link assetId}.
+     */
+    get: (id: string, options?: Pick<RequestInit, "signal">) => Promise<{
+        id: string;
+        displayName: string;
+        mimeType: string;
+        state?: import("../generated/developer-api.gen.ts").components["schemas"]["AssetState"];
+        width?: number | null;
+        height?: number | null;
+        sizeBytes?: string | null;
+        checksum?: string | null;
+        createTime?: string | null;
+        type?: string | null;
+        parts?: import("../generated/developer-api.gen.ts").components["schemas"]["AssetPart"][];
+        structure?: {
+            [key: string]: unknown;
+        } | null;
+        producedBy?: import("../generated/developer-api.gen.ts").components["schemas"]["ProducedBy"] | null;
+        contentPath?: string | null;
+    }>;
+    /** Return one page of assets. Pass the response's `nextPageToken` to retrieve the next page. */
+    list: ({ pageSize, pageToken, ...options }?: ListAssetsOptions) => Promise<{
+        assets?: import("../generated/developer-api.gen.ts").components["schemas"]["Asset"][];
+        nextPageToken?: string;
+    }>;
+    /**
+     * 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: (data: Blob | BufferSource, { displayName, mimeType, signal }: UploadOptions) => Promise<{
+        id: string;
+        displayName: string;
+        mimeType: string;
+        state?: import("../generated/developer-api.gen.ts").components["schemas"]["AssetState"];
+        width?: number | null;
+        height?: number | null;
+        sizeBytes?: string | null;
+        checksum?: string | null;
+        createTime?: string | null;
+        type?: string | null;
+        parts?: import("../generated/developer-api.gen.ts").components["schemas"]["AssetPart"][];
+        structure?: {
+            [key: string]: unknown;
+        } | null;
+        producedBy?: import("../generated/developer-api.gen.ts").components["schemas"]["ProducedBy"] | null;
+        contentPath?: string | null;
+    }>;
+};
+//# sourceMappingURL=assets.d.ts.map

package/dist/core/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../../src/core/assets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,WAAW,EACX,qBAAqB,EAKrB,SAAS,EACV,MAAM,mCAAmC,CAAC;AAE3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,0CAA0C;AAC1C,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC;IAChE,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,+DAA+D;AAC/D,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC;IACpE,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,+DAA+D;AAC/D,eAAO,MAAM,OAAO,GAAI,OAAO,KAAK,KAAG,MAAkB,CAAC;AAE1D,6DAA6D;AAC7D,eAAO,MAAM,QAAQ,GAAI,OAAO,KAAK,KAAG,SAA0C,CAAC;AAWnF;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,WAAW,SAAS,EAAE,YAAY,MAAM;IAuBjE;;;;OAIG;yBAhBC,MAAM,SACJ,qBAAqB,YAClB,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC;;;;gBAoGqrI,iEAAsB;;;;;;;gBAAmsC,iEAAsB;;;;qBAAiU,iEAAsB;;;IAnF/xL,2FAA2F;oBACrE,WAAW,YAAW,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC;;;;gBAkFomoC,iEAAsB;;;;;;;gBAAmsC,iEAAsB;;;;qBAAiU,iEAAsB;;kBAA6rB,iEAAsB;;IA/Ep8sC;;;OAGG;wBACuB,MAAM,YAAW,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC;;;;IAOtE;;;OAGG;iBACgB,MAAM,YAAW,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC;IAI/D;;;OAGG;cACa,MAAM,YAAW,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC;;;;gBAwD6pI,iEAAsB;;;;;;;gBAAmsC,iEAAsB;;;;qBAAiU,iEAAsB;;;IArD/xL,gGAAgG;iDAC9C,iBAAiB;iBAoDg+jD,iEAAsB;;;IA9CzjkD;;;;;;;;OAQG;mBACkB,IAAI,GAAG,YAAY,qCAAqC,aAAa;;;;gBAqC+nI,iEAAsB;;;;;;;gBAAmsC,iEAAsB;;;;qBAAiU,iEAAsB;;;CADlyL,CAAC"}

package/dist/core/assets.js

@@ -0,0 +1,104 @@
+import { ApiError } from "./transport.js";
+/** Return the id an asset is addressed by in task requests. */
+export const assetId = (asset) => asset.id;
+/** Convert an asset resource into a task media reference. */
+export const assetRef = (asset) => ({ assetId: assetId(asset) });
+const toBlob = (data, mimeType) => {
+    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, assetsPath) => {
+    const itemPath = `${assetsPath}/{asset}`;
+    const create = async (asset, signal) => await transport.request(assetsPath, {
+        body: { asset },
+        method: "POST",
+        ...(signal ? { signal } : {}),
+    });
+    const completeUpload = async (id, body = {}, options = {}) => await transport.request(`${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, options = {}) => 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, options = {}) => await transport.request(`${itemPath}:createReadUrl`, {
+            method: "POST",
+            params: { asset: id },
+            ...options,
+        }),
+        /**
+         * Soft-delete an asset.
+         * @param id - Asset ID from {@link assetId}.
+         */
+        delete: async (id, options = {}) => {
+            await transport.request(itemPath, { method: "DELETE", params: { asset: id }, ...options });
+        },
+        /**
+         * Fetch asset metadata.
+         * @param id - Asset ID from {@link assetId}.
+         */
+        get: async (id, options = {}) => await transport.request(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 } = {}) => await transport.request(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, { displayName, mimeType, signal }) => {
+            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(`${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);
+        },
+    };
+};
+//# sourceMappingURL=assets.js.map

package/dist/core/assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.js","sourceRoot":"","sources":["../../src/core/assets.ts"],"names":[],"mappings":"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"}

package/dist/core/index.d.ts

@@ -0,0 +1,5 @@
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,QAAQ,EACR,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,gBAAgB,EAChB,KAAK,WAAW,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EACL,QAAQ,EACR,KAAK,MAAM,EACX,UAAU,EACV,eAAe,EACf,KAAK,KAAK,EACV,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,UAAU,GACX,MAAM,gBAAgB,CAAC"}