@statelyai/sdk 0.5.1 → 0.6.1

package/README.md

@@ -27,10 +27,9 @@ npm install @statelyai/sdk
 The embed supports three common deployment models:
 
 - Hosted Stately: pass an API key to `createStatelyEmbed()`
-- Same-origin deployments: rely on the host application's session/cookie auth
 - Self-hosted deployments: configure auth in the editor server and omit `apiKey` when no token is required
 
-### With Stately (default)
+### Hosted Stately
 
 An API key is required. To get one:
 
@@ -50,29 +49,19 @@ const embed = createStatelyEmbed({
 });
 ```
 
-### Same-origin embed (cookie auth)
-
-When the embed host and the editor share a domain, you can omit `apiKey` and rely on the host application's auth/session layer:
-
-```ts
-const embed = createStatelyEmbed({
-  baseUrl: process.env.NEXT_PUBLIC_BETA_EDITOR_URL ?? window.location.origin,
-});
-```
-
 ### Self-hosting
 
 When self-hosting the editor, authentication is enforced by the editor server, not by this npm package.
 
 The common environment variables are:
 
-| Variable | Purpose |
-| --- | --- |
-| `AUTH_PROVIDER` | Auth strategy used by the editor host |
+| Variable                    | Purpose                                                                 |
+| --------------------------- | ----------------------------------------------------------------------- |
+| `AUTH_PROVIDER`             | Auth strategy used by the editor host                                   |
 | `EDITOR_SYNC_AUTH_REQUIRED` | Set to `false` to disable API-key checks for editor-sync endpoints only |
-| `STATELY_API_KEY` | Server-side API key for Stately data fetching |
-| `STATELY_API_URL` | Stately API base URL override |
-| `NEXT_PUBLIC_BASE_URL` | Public-facing editor URL |
+| `STATELY_API_KEY`           | Server-side API key for Stately data fetching                           |
+| `STATELY_API_URL`           | Stately API base URL override                                           |
+| `NEXT_PUBLIC_BASE_URL`      | Public-facing editor URL                                                |
 
 For a fully self-contained deployment with no auth, omit `apiKey` in the SDK and configure the host/editor to allow unauthenticated access:
 
@@ -143,9 +132,13 @@ The SDK ships root exports for the most common entry points and helpers:
 
 ```ts
 import {
+  createStatelyApiClient,
+  createStatelyApiUrl,
   createStatelyClient,
   createStatelyEmbed,
   createStatelyInspector,
+  createS3AssetUploadAdapter,
+  createSupabaseAssetUploadAdapter,
   fromStudioMachine,
   graphToMachineConfig,
   graphToXStateTS,
@@ -159,11 +152,21 @@ It also supports narrower subpath imports:
 import { createStatelyClient } from '@statelyai/sdk/studio';
 import { createStatelyInspector } from '@statelyai/sdk/inspect';
 import { createStatelyEmbed } from '@statelyai/sdk/embed';
+import {
+  createStatelyApiClient,
+  createStatelyApiUrl,
+} from '@statelyai/sdk/api';
 import { fromStudioMachine, toStudioMachine } from '@statelyai/sdk/graph';
-import { planSync, pullSync } from '@statelyai/sdk/sync';
+import { planSync, pullSync, pushSync } from '@statelyai/sdk/sync';
+import {
+  createS3AssetUploadAdapter,
+  createSupabaseAssetUploadAdapter,
+} from '@statelyai/sdk/assetStorage';
 import type { GraphPatch } from '@statelyai/sdk/patchTypes';
 ```
 
+The root package also exports `getStatelyPragma()`, `findStatelyPragmaAttachments()`, and `upsertStatelyPragma()` for working with canonical source annotations such as `// @statelyai id=machine-123`.
+
 ## Studio API Client
 
 ```ts
@@ -173,21 +176,84 @@ const studio = createStatelyClient({
   apiKey: process.env.STATELY_API_KEY,
 });
 
+const createdProject = await studio.projects.create({
+  name: 'My project',
+  visibility: 'Private',
+});
 const project = await studio.projects.get('project-id');
+const projects = await studio.projects.list();
+const createdMachine = await studio.machines.create({
+  projectVersionId: createdProject.projectVersionId!,
+  definition: digraphDefinition,
+  xstateVersion: 5,
+});
 const machine = await studio.machines.get('machine-id', { version: '42' });
 const extracted = await studio.code.extractMachines(sourceCode);
 ```
 
+`studio.projects.list(...)`, `studio.projects.create(...)`, and `studio.machines.create(...)` use the documented Studio REST API. `studio.projects.ensure(...)` is a client-side helper that uses the documented list/create endpoints to reuse an existing connected project when the repo metadata matches.
+
 <!-- public methods of StudioClient from src/studio.ts -->
 
 Available client methods:
 
-| Method | Description |
-| --- | --- |
-| `studio.auth.verify(apiKey?)` | Verify an API key against the registry API |
-| `studio.projects.get(projectId)` | Fetch a project and its machines |
-| `studio.machines.get(machineId, { version? })` | Fetch a machine, optionally pinned to a version |
-| `studio.code.extractMachines(code, { apiKey? })` | Extract machine configs from source text |
+| Method                                                                  | Description                                                              |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `studio.auth.verify(apiKey?)`                                           | Verify an API key against the registry API                               |
+| `studio.projects.list()`                                                | List accessible projects, including connected repo metadata when present |
+| `studio.projects.create({ name, visibility, description?, keywords? })` | Create a new project through the published REST API                      |
+| `studio.projects.ensure({ name, visibility, repo?, ... })`              | Reuse an existing connected project or create one through the REST API   |
+| `studio.projects.get(projectId)`                                        | Fetch a project and its machines                                         |
+| `studio.machines.create({ projectVersionId, ... })`                     | Create a machine through the published REST API                          |
+| `studio.machines.createMany({ projectVersionId, ... })`                 | Compatibility wrapper around `create()` that returns a one-item array    |
+| `studio.machines.get(machineId, { version? })`                          | Fetch a machine, optionally pinned to a version                          |
+| `studio.code.extractMachines(code, { apiKey? })`                        | Extract machine configs from source text                                 |
+
+## Sync Helpers
+
+`pushSync()` complements `planSync()` and `pullSync()` for local-to-Studio flows. It resolves a local source file, ensures there is a target project, creates the remote machine, and writes `// @statelyai id=...` back into XState source files.
+
+```ts
+import { pushSync } from '@statelyai/sdk/sync';
+
+const result = await pushSync({
+  source: './src/machines/toggle.ts',
+  apiKey: process.env.STATELY_API_KEY,
+  project: {
+    visibility: 'Private',
+    repo: {
+      url: 'https://github.com/statelyai/viz',
+      owner: 'statelyai',
+      repo: 'viz',
+      branch: 'main',
+      treeSha: 'abc123',
+    },
+  },
+});
+```
+
+Projects can also check in a `statelyai.json` file to describe which local sources belong to a Studio project. The published schema lives at `@statelyai/sdk/statelyai.schema.json` and the canonical schema id is `https://stately.ai/schemas/statelyai.json`.
+
+```json
+{
+  "$schema": "https://stately.ai/schemas/statelyai.json",
+  "version": "1.0.0",
+  "projectId": "project_123",
+  "studioUrl": "https://stately.ai",
+  "defaultXStateVersion": 5,
+  "sources": [
+    {
+      "include": ["src/**/*.ts", "src/**/*.tsx"],
+      "exclude": ["**/*.test.ts", "**/dist/**"],
+      "format": "xstate"
+    },
+    {
+      "include": ["docs/**/*.mmd"],
+      "format": "mermaid"
+    }
+  ]
+}
+```
 
 ## Inspector
 
@@ -211,18 +277,18 @@ actor.start();
 
 Key options:
 
-| Option | Description |
-| --- | --- |
-| `actor` | Root actor to adopt and inspect automatically |
-| `url` | Devtools relay URL. Defaults to `ws://localhost:4242` |
-| `autoOpen` | Whether to ask the relay to open the inspector UI |
-| `sessionId` | Override the relay session id |
-| `name` | Display name shown to the inspector |
-| `serializeSnapshot` | Customize snapshot serialization before sending it over the wire |
-| `extractMachineConfig` | Customize how machine config is derived from an actor |
-| `selectedActorId` | Focus a specific actor first |
-| `panels`, `theme`, `readOnly`, `depth` | Initial inspector UI options |
-| `transport` | Inject an existing transport instead of opening a new WebSocket |
+| Option                                 | Description                                                      |
+| -------------------------------------- | ---------------------------------------------------------------- |
+| `actor`                                | Root actor to adopt and inspect automatically                    |
+| `url`                                  | Devtools relay URL. Defaults to `ws://localhost:4242`            |
+| `autoOpen`                             | Whether to ask the relay to open the inspector UI                |
+| `sessionId`                            | Override the relay session id                                    |
+| `name`                                 | Display name shown to the inspector                              |
+| `serializeSnapshot`                    | Customize snapshot serialization before sending it over the wire |
+| `extractMachineConfig`                 | Customize how machine config is derived from an actor            |
+| `selectedActorId`                      | Focus a specific actor first                                     |
+| `panels`, `theme`, `readOnly`, `depth` | Initial inspector UI options                                     |
+| `transport`                            | Inject an existing transport instead of opening a new WebSocket  |
 
 Key methods:
 
@@ -241,17 +307,17 @@ Creates an embed instance.
 
 <!-- public options of StatelyEmbedOptions from src/embed.ts -->
 
-| Option | Type | Description |
-| --- | --- | --- |
-| `baseUrl` | `string` | **Required.** Base URL of the Stately app |
-| `apiKey` | `string` | API key for hosted Stately deployments |
-| `origin` | `string` | Optional strict target origin for `postMessage`; defaults to permissive wildcard messaging for local/self-hosted testing |
-| `assets` | `AssetConfig` | Asset upload configuration |
-| `onReady` | `() => void` | Called when the embed is ready |
-| `onLoaded` | `(graph) => void` | Called when a machine is loaded |
-| `onChange` | `(graph, machineConfig) => void` | Called on every change |
-| `onSave` | `(graph, machineConfig) => void` | Called on save |
-| `onError` | `({ code, message }) => void` | Called when the embed reports an error |
+| Option     | Type                             | Description                                                                                                              |
+| ---------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `baseUrl`  | `string`                         | **Required.** Base URL of the Stately app                                                                                |
+| `apiKey`   | `string`                         | API key for hosted Stately deployments                                                                                   |
+| `origin`   | `string`                         | Optional strict target origin for `postMessage`; defaults to permissive wildcard messaging for local/self-hosted testing |
+| `assets`   | `AssetConfig`                    | Asset upload configuration                                                                                               |
+| `onReady`  | `() => void`                     | Called when the embed is ready                                                                                           |
+| `onLoaded` | `(graph) => void`                | Called when a machine is loaded                                                                                          |
+| `onChange` | `(graph, machineConfig) => void` | Called on every change                                                                                                   |
+| `onSave`   | `(graph, machineConfig) => void` | Called on save                                                                                                           |
+| `onError`  | `({ code, message }) => void`    | Called when the embed reports an error                                                                                   |
 
 ### Embed methods
 
@@ -295,20 +361,20 @@ embed.init({
 
 `comments` accepts:
 
-| Field | Type | Description |
-| --- | --- | --- |
-| `roomId` | `string` | **Required.** Liveblocks room identifier |
-| `publicApiKey` | `string` | Liveblocks public key |
-| `authEndpoint` | `string` | Custom Liveblocks auth endpoint |
-| `baseUrl` | `string` | Custom Liveblocks base URL for self-hosting |
-| `userId` | `string \| null` | Optional user identity metadata |
+| Field          | Type             | Description                                 |
+| -------------- | ---------------- | ------------------------------------------- |
+| `roomId`       | `string`         | **Required.** Liveblocks room identifier    |
+| `publicApiKey` | `string`         | Liveblocks public key                       |
+| `authEndpoint` | `string`         | Custom Liveblocks auth endpoint             |
+| `baseUrl`      | `string`         | Custom Liveblocks base URL for self-hosting |
+| `userId`       | `string \| null` | Optional user identity metadata             |
 
 `unsavedIndicator` accepts:
 
-| Field | Type | Description |
-| --- | --- | --- |
-| `enabled` | `boolean` | Show the persistent "Save to apply" pill |
-| `mode` | `'structural' \| 'all'` | Track only structural graph edits or all edits |
+| Field     | Type                    | Description                                    |
+| --------- | ----------------------- | ---------------------------------------------- |
+| `enabled` | `boolean`               | Show the persistent "Save to apply" pill       |
+| `mode`    | `'structural' \| 'all'` | Track only structural graph edits or all edits |
 
 #### `embed.updateMachine(machine, format?)`
 
@@ -331,16 +397,18 @@ embed.setSettings({
 
 Available core settings:
 
-| Path | Type | Default |
-| --- | --- | --- |
-| `appearance.colorMode` | `'light' \| 'dark' \| 'system'` | `'dark'` |
-| `canvas.showGrid` | `boolean` | `true` |
-| `canvas.viewMode` | `'graph' \| 'list'` | `'graph'` |
-| `canvas.enableSnapLines` | `boolean` | `true` |
-| `canvas.dimUnselected` | `boolean` | `true` |
-| `validation.showValidations` | `boolean` | `true` |
-| `autolayout.autoEnabled` | `boolean` | `false` |
-| `developer.devMode` | `boolean` | `false` |
+<!-- core setting paths from ../../src/settings.ts -->
+
+| Path                         | Type                            | Default   |
+| ---------------------------- | ------------------------------- | --------- |
+| `appearance.colorMode`       | `'light' \| 'dark' \| 'system'` | `'dark'`  |
+| `canvas.showGrid`            | `boolean`                       | `true`    |
+| `canvas.viewMode`            | `'graph' \| 'list'`             | `'graph'` |
+| `canvas.enableSnapLines`     | `boolean`                       | `true`    |
+| `canvas.dimUnselected`       | `boolean`                       | `true`    |
+| `validation.showValidations` | `boolean`                       | `true`    |
+| `layout.autolayout`          | `boolean`                       | `false`   |
+| `developer.devMode`          | `boolean`                       | `false`   |
 
 #### `embed.export(format, options?)`
 
@@ -349,13 +417,13 @@ Export the current machine. Returns a promise.
 ```ts
 const xstateCode = await embed.export('xstate', { version: 5 });
 const digraph = await embed.export('digraph');
-const rtk = await embed.export('rtk');
+const redux = await embed.export('redux');
 const aslYaml = await embed.export('asl-yaml');
 ```
 
 <!-- supported export formats from ExportFormatMap in src/protocol.ts -->
 
-Supported formats: `xstate`, `json`, `xgraph`, `digraph`, `mermaid`, `rtk`, `zustand`, `asl-json`, `asl-yaml`, `scxml`
+Supported formats: `xstate`, `json`, `xgraph`, `digraph`, `mermaid`, `redux`, `zustand`, `asl-json`, `asl-yaml`, `scxml`
 
 #### `embed.on(event, handler)` / `embed.off(event, handler)`
 
@@ -400,11 +468,56 @@ const embed = createStatelyEmbed({
 });
 ```
 
-| Option | Type | Description |
-| --- | --- | --- |
-| `onUploadRequest` | `(file: File, context: { stateNodeId: string }) => Promise<UploadResult>` | **Required.** Called when the editor needs to upload a file |
-| `accept` | `string[]` | Accepted MIME types. Supports wildcards like `image/*` |
-| `maxFileSize` | `number` | Max file size in bytes. Defaults to `10_485_760` |
+For reusable integrations, pass an upload adapter instead of wiring the callback inline:
+
+```ts
+import { createStatelyEmbed, createS3AssetUploadAdapter } from '@statelyai/sdk';
+
+const adapter = createS3AssetUploadAdapter({
+  bucket: 'assets',
+  publicBaseUrl: 'https://cdn.example.com/assets',
+  async getUploadTarget({ key, contentType }) {
+    const response = await fetch('/api/assets/presign', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ key, contentType }),
+    });
+    return response.json();
+  },
+});
+
+const embed = createStatelyEmbed({
+  baseUrl: 'https://stately.ai',
+  assets: { adapter },
+});
+```
+
+Supabase storage can use the same adapter contract:
+
+```ts
+import {
+  createStatelyEmbed,
+  createSupabaseAssetUploadAdapter,
+} from '@statelyai/sdk';
+
+const adapter = createSupabaseAssetUploadAdapter({
+  client: supabaseClient,
+  bucket: 'assets',
+  projectVersionId,
+});
+
+const embed = createStatelyEmbed({
+  baseUrl: 'https://stately.ai',
+  assets: { adapter },
+});
+```
+
+| Option            | Type                                                                      | Description                                                 |
+| ----------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `onUploadRequest` | `(file: File, context: { stateNodeId: string }) => Promise<UploadResult>` | Called when the editor needs to upload a file               |
+| `adapter`         | `AssetUploadAdapter`                                                      | Provider-specific uploader, such as the S3 or Supabase adapter |
+| `accept`          | `string[]`                                                                | Accepted MIME types. Supports wildcards like `image/*`      |
+| `maxFileSize`     | `number`                                                                  | Max file size in bytes. Defaults to `10_485_760`            |
 
 `UploadResult`:
 
@@ -446,6 +559,8 @@ const digraph = toStudioMachine(graph);
 Other exported helpers:
 
 - `studioMachineConverter` for reusable format conversion
+- `createStatelyApiUrl()` and `createStatelyApiClient()` for building and
+  calling self-hosted Viz API routes from a shared API base URL
 - `serializeJS()`, `raw()`, and `RawCode` for emitting JavaScript source
 - `jsonSchemaToTSType()`, `contextSchemaToTSType()`, and `eventsSchemaToTSType()` for generating inline TypeScript types from JSON Schema
 - `GraphPatch` and `ActionLocation` types from `@statelyai/sdk/patchTypes`
@@ -489,6 +604,9 @@ Installing the package also exposes a `statelyai` binary:
 ```bash
 npx statelyai open ./checkout.machine.ts
 
+statelyai init
+statelyai login
+statelyai auth status
 statelyai plan ./checkout.machine.ts machine-id
 statelyai diff ./checkout.machine.ts machine-id --fail-on-changes
 statelyai pull machine-id ./checkout.machine.ts
@@ -499,12 +617,16 @@ For one-off use, `npx statelyai ...` installs the small `statelyai` CLI package,
 
 Available commands:
 
-| Command | Description |
-| --- | --- |
-| `statelyai plan <source> <target>` | Print a semantic sync summary |
-| `statelyai diff <source> <target>` | Diff two locators and optionally fail on changes |
-| `statelyai pull <source> <target>` | Materialize a source into a local target file |
-| `statelyai open <file>` | Open a local file in a browser-backed visual editor session |
+| Command                            | Description                                                                 |
+| ---------------------------------- | --------------------------------------------------------------------------- |
+| `statelyai init`                   | Create or reuse a Studio project for the current directory and write `statelyai.json` |
+| `statelyai login`                  | Store an API key for future CLI use                                         |
+| `statelyai logout`                 | Remove a stored API key                                                     |
+| `statelyai auth status`            | Show whether the CLI would use an environment variable or stored credential |
+| `statelyai plan <source> <target>` | Print a semantic sync summary                                               |
+| `statelyai diff <source> <target>` | Diff two locators and optionally fail on changes                            |
+| `statelyai pull <source> <target>` | Materialize a source into a local target file                               |
+| `statelyai open <file>`            | Open a local file in a browser-backed visual editor session                 |
 
 Common flags:
 
@@ -512,7 +634,9 @@ Common flags:
 - `--base-url` for self-hosted or non-default Stately deployments
 - `--fail-on-changes` to return a nonzero exit code when a diff is detected
 
-`statelyai open` also supports `--api-key`, `--editor-url`, `--host`, `--port`, `--no-open`, and `--debug`. It watches the local file on disk and sends source snapshots to `/api/editor-sync/*` endpoints, which return the text replacements to apply locally. Pass `--api-key` or set `STATELY_API_KEY` when the editor server requires auth. Self-hosted servers can disable editor-sync API-key checks with `EDITOR_SYNC_AUTH_REQUIRED=false`. The private source reconciliation engine is not bundled into the published CLI.
+The CLI resolves credentials in this order: `--api-key`, then `STATELY_API_KEY`/`NEXT_PUBLIC_STATELY_API_KEY`, then the key stored by `statelyai login`. `login` stores the key in the OS credential store when available, with a private file fallback.
+
+`statelyai open` also supports `--api-key`, `--editor-url`, `--host`, `--port`, `--no-open`, and `--debug`. It watches the local file on disk and sends source snapshots to `/api/editor-sync/*` endpoints, which return the text replacements to apply locally. When the source file contains `// @statelyai id=...` and an API key is available, the editor session also reuses the referenced remote machine layout while continuing to treat the local source as the semantic source of truth. Pass `--api-key`, set `STATELY_API_KEY`, or run `statelyai login` when the editor server requires auth. Self-hosted servers can disable editor-sync API-key checks with `EDITOR_SYNC_AUTH_REQUIRED=false`. The private source reconciliation engine is not bundled into the published CLI.
 
 ## Transport Helpers
 

package/dist/api.d.mts

@@ -0,0 +1,20 @@
+//#region src/api.d.ts
+interface StatelyApiUrlOptions {
+  baseUrl?: string | null;
+}
+interface StatelyApiClientOptions extends StatelyApiUrlOptions {
+  fetch?: typeof fetch;
+}
+declare class StatelyApiError extends Error {
+  readonly status: number;
+  readonly data: unknown;
+  constructor(message: string, status: number, data: unknown);
+}
+declare function createStatelyApiUrl(path: string, options?: StatelyApiUrlOptions): string;
+declare function createStatelyApiClient(options?: StatelyApiClientOptions): {
+  url(path: string): string;
+  request: <T>(path: string, init?: RequestInit) => Promise<T>;
+  post<T>(path: string, body: unknown, init?: RequestInit): Promise<T>;
+};
+//#endregion
+export { StatelyApiClientOptions, StatelyApiError, StatelyApiUrlOptions, createStatelyApiClient, createStatelyApiUrl };

package/dist/api.mjs

@@ -0,0 +1,56 @@
+//#region src/api.ts
+var StatelyApiError = class extends Error {
+	status;
+	data;
+	constructor(message, status, data) {
+		super(message);
+		this.name = "StatelyApiError";
+		this.status = status;
+		this.data = data;
+	}
+};
+function getFetch(fetchImpl) {
+	const resolvedFetch = fetchImpl ?? globalThis.fetch;
+	if (!resolvedFetch) throw new Error("No fetch implementation available. Pass one via createStatelyApiClient({ fetch }).");
+	return resolvedFetch;
+}
+function getErrorMessage(data, status) {
+	if (typeof data === "object" && data !== null && "error" in data && typeof data.error === "string") return data.error;
+	return `HTTP ${status}`;
+}
+async function parseJson(response) {
+	if (!response.headers.get("content-type")?.includes("application/json")) return null;
+	return response.json().catch(() => null);
+}
+function createStatelyApiUrl(path, options) {
+	return `${(options?.baseUrl ?? "/api").replace(/\/+$/, "")}${path.startsWith("/") ? path : `/${path}`}`;
+}
+function createStatelyApiClient(options = {}) {
+	const fetchImpl = getFetch(options.fetch);
+	async function request(path, init) {
+		const response = await fetchImpl(createStatelyApiUrl(path, options), init);
+		const data = await parseJson(response);
+		if (!response.ok) throw new StatelyApiError(getErrorMessage(data, response.status), response.status, data);
+		return data;
+	}
+	return {
+		url(path) {
+			return createStatelyApiUrl(path, options);
+		},
+		request,
+		post(path, body, init) {
+			return request(path, {
+				...init,
+				method: init?.method ?? "POST",
+				headers: {
+					"content-type": "application/json",
+					...init?.headers
+				},
+				body: JSON.stringify(body)
+			});
+		}
+	};
+}
+
+//#endregion
+export { StatelyApiError, createStatelyApiClient, createStatelyApiUrl };

package/dist/assetStorage.d.mts

@@ -0,0 +1,73 @@
+import { m as UploadResult } from "./protocol-CDoCcaIP.mjs";
+
+//#region src/assetStorage.d.ts
+interface AssetUploadContext {
+  stateNodeId: string;
+}
+interface AssetUploadRequest extends AssetUploadContext {
+  file: File;
+}
+interface AssetUploadAdapter {
+  upload(request: AssetUploadRequest): Promise<UploadResult>;
+  accept?: string[];
+  maxFileSize?: number;
+}
+type AssetObjectKeyFactory = (request: AssetUploadRequest) => string | Promise<string>;
+interface S3UploadTarget {
+  uploadUrl: string;
+  publicUrl?: string;
+  method?: 'PUT' | 'POST';
+  headers?: Record<string, string>;
+  fields?: Record<string, string>;
+}
+interface CreateS3AssetUploadAdapterOptions {
+  bucket?: string;
+  publicBaseUrl?: string;
+  accept?: string[];
+  maxFileSize?: number;
+  key?: AssetObjectKeyFactory;
+  getUploadTarget: (request: AssetUploadRequest & {
+    key: string;
+    contentType: string;
+    bucket?: string;
+  }) => Promise<S3UploadTarget>;
+}
+interface SupabaseStorageBucket {
+  upload(path: string, file: File, options?: {
+    cacheControl?: string;
+    contentType?: string;
+    upsert?: boolean;
+  }): Promise<{
+    data: {
+      path: string;
+    } | null;
+    error: Error | {
+      message: string;
+    } | null;
+  }>;
+  getPublicUrl?(path: string): {
+    data: {
+      publicUrl: string;
+    };
+  };
+}
+interface SupabaseStorageClient {
+  storage: {
+    from(bucket: string): SupabaseStorageBucket;
+  };
+}
+interface CreateSupabaseAssetUploadAdapterOptions {
+  client: SupabaseStorageClient;
+  bucket?: string;
+  publicBaseUrl?: string;
+  projectVersionId?: string;
+  accept?: string[];
+  maxFileSize?: number;
+  cacheControl?: string;
+  upsert?: boolean;
+  key?: AssetObjectKeyFactory;
+}
+declare function createS3AssetUploadAdapter(options: CreateS3AssetUploadAdapterOptions): AssetUploadAdapter;
+declare function createSupabaseAssetUploadAdapter(options: CreateSupabaseAssetUploadAdapterOptions): AssetUploadAdapter;
+//#endregion
+export { AssetObjectKeyFactory, AssetUploadAdapter, AssetUploadContext, AssetUploadRequest, CreateS3AssetUploadAdapterOptions, CreateSupabaseAssetUploadAdapterOptions, S3UploadTarget, SupabaseStorageClient, createS3AssetUploadAdapter, createSupabaseAssetUploadAdapter };