@decartai/sdk 0.1.0 → 0.1.1

package/dist/files/client.d.ts

@@ -0,0 +1,33 @@
+import { FileReference, FileUploadInput } from "./types.js";
+
+//#region src/files/client.d.ts
+
+type UploadFileOptions = {
+  signal?: AbortSignal;
+  /**
+   * Expiration:
+   * - omit → platform default (24 h)
+   * - a positive integer → TTL in seconds (60 .. 2_592_000)
+   * - `"persistent"` → never expires
+   */
+  ttlSeconds?: number | "persistent";
+};
+type FilesClient = {
+  /**
+   * Upload a file once and get a reusable reference. Pass `ref.id` to
+   * realtime `set({ image })` to reuse the same asset across generations
+   * without re-uploading.
+   *
+   * @example
+   * ```ts
+   * const ref = await client.files.upload(blob);
+   * await rt.set({ image: ref.id, prompt: "make it cinematic" });
+   * await rt.set({ image: ref.id, prompt: "now in noir" });   // reused, no re-upload
+   * ```
+   */
+  upload: (file: FileUploadInput, options?: UploadFileOptions) => Promise<FileReference>;
+  get: (fileId: string) => Promise<FileReference>;
+  delete: (fileId: string) => Promise<void>;
+};
+//#endregion
+export { FilesClient, UploadFileOptions };

package/dist/files/client.js

@@ -0,0 +1,65 @@
+import { createInvalidInputError, createSDKError } from "../utils/errors.js";
+import { buildAuthHeaders } from "../shared/request.js";
+import { z } from "zod";
+//#region src/files/client.ts
+const MAX_TTL_SECONDS = 720 * 60 * 60;
+const ttlSecondsSchema = z.union([z.number().int().min(60).max(MAX_TTL_SECONDS), z.literal("persistent")]);
+const createFilesClient = (opts) => {
+	const { baseUrl, apiKey, integration } = opts;
+	const upload = async (file, options) => {
+		if (options?.ttlSeconds !== void 0) {
+			if (!ttlSecondsSchema.safeParse(options.ttlSeconds).success) throw createInvalidInputError(`ttlSeconds must be an integer in [60, ${MAX_TTL_SECONDS}] or the literal "persistent"`);
+		}
+		const formData = new FormData();
+		formData.append("file", file);
+		if (options?.ttlSeconds !== void 0) formData.append("ttl_seconds", String(options.ttlSeconds));
+		const response = await fetch(`${baseUrl}/v1/files`, {
+			method: "POST",
+			headers: buildAuthHeaders({
+				apiKey,
+				integration
+			}),
+			body: formData,
+			signal: options?.signal
+		});
+		if (!response.ok) {
+			const errorText = await response.text().catch(() => "Unknown error");
+			throw createSDKError("FILES_UPLOAD_ERROR", `Failed to upload file: ${response.status} - ${errorText}`, { status: response.status });
+		}
+		return response.json();
+	};
+	const get = async (fileId) => {
+		const response = await fetch(`${baseUrl}/v1/files/${encodeURIComponent(fileId)}`, {
+			method: "GET",
+			headers: buildAuthHeaders({
+				apiKey,
+				integration
+			})
+		});
+		if (!response.ok) {
+			const errorText = await response.text().catch(() => "Unknown error");
+			throw createSDKError("FILES_GET_ERROR", `Failed to get file: ${response.status} - ${errorText}`, { status: response.status });
+		}
+		return response.json();
+	};
+	const deleteFile = async (fileId) => {
+		const response = await fetch(`${baseUrl}/v1/files/${encodeURIComponent(fileId)}`, {
+			method: "DELETE",
+			headers: buildAuthHeaders({
+				apiKey,
+				integration
+			})
+		});
+		if (!response.ok) {
+			const errorText = await response.text().catch(() => "Unknown error");
+			throw createSDKError("FILES_DELETE_ERROR", `Failed to delete file: ${response.status} - ${errorText}`, { status: response.status });
+		}
+	};
+	return {
+		upload,
+		get,
+		delete: deleteFile
+	};
+};
+//#endregion
+export { createFilesClient };

package/dist/files/types.d.ts

@@ -0,0 +1,22 @@
+import { ReactNativeFile } from "../process/types.js";
+
+//#region src/files/types.d.ts
+
+/**
+ * Metadata for a previously-uploaded file. Returned by `client.files.upload(...)`.
+ * Pass `ref.id` to `realtime.set({ image })` / `setImage(...)` to reuse it.
+ *
+ * Files expire after a server-configured TTL (default 24 h). `expires_at` is
+ * `null` when the upload was created with `persistent: true`.
+ */
+interface FileReference {
+  id: string;
+  filename: string | null;
+  mime_type: string;
+  size_bytes: number;
+  created_at: string;
+  expires_at: string | null;
+}
+type FileUploadInput = File | Blob | ReactNativeFile;
+//#endregion
+export { FileReference, FileUploadInput };

package/dist/files/types.js

@@ -0,0 +1,4 @@
+/** True if `value` is a `"file_..."` reference id from `client.files.upload(...)`. */
+const isFileRefId = (value) => typeof value === "string" && value.startsWith("file_");
+//#endregion
+export { isFileRefId };

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { LogLevel, Logger, createConsoleLogger, noopLogger } from "./utils/logger.js";
 import { CanonicalModel, CustomModelDefinition, ImageModelDefinition, ImageModels, ListedModelDefinition, Model, ModelDefinition, ModelKind, RealTimeModels, VideoModelDefinition, VideoModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, resolveCanonicalModelAlias, resolveModelAlias } from "./shared/model.js";
 import { FileInput, ProcessOptions, ReactNativeFile } from "./process/types.js";
+import { FileReference, FileUploadInput } from "./files/types.js";
+import { FilesClient, UploadFileOptions } from "./files/client.js";
 import { ProcessClient } from "./process/client.js";
 import { JobStatus, JobStatusResponse, JobSubmitResponse, QueueJobResult, QueueSubmitAndPollOptions, QueueSubmitOptions } from "./queue/types.js";
 import { QueueClient } from "./queue/client.js";
@@ -134,6 +136,17 @@ declare const createDecartClient: (options?: DecartClientOptions) => {
    * ```
    */
   tokens: TokensClient;
+  /**
+   * Upload files once and reuse them across generations.
+   *
+   * @example
+   * ```ts
+   * const ref = await client.files.upload(blob);
+   * await rt.set({ image: ref.id, prompt: "make it cinematic" });
+   * await rt.set({ image: ref.id, prompt: "now in noir" });
+   * ```
+   */
+  files: FilesClient;
 };
 //#endregion
-export { type CanonicalModel, type ClientSessionConnectionBreakdownEvent, type ClientSessionConnectionBreakdownPhase, type ConnectionState, type CreateTokenOptions, type CreateTokenResponse, type CustomModelDefinition, DecartClientOptions, type DecartSDKError, type DiagnosticEvent, type DiagnosticEventName, type DiagnosticEvents, ERROR_CODES, type FileInput, type GenerationEndedMessage, type ImageModelDefinition, type ImageModels, type JobStatus, type JobStatusResponse, type JobSubmitResponse, type ListedModelDefinition, type LogLevel, type Logger, type Model, type ModelDefinition, type ModelKind, type ModelState, type ProcessClient, type ProcessOptions, type QueueClient, type QueueJobResult, type QueuePosition, type QueuePositionMessage, type QueueSubmitAndPollOptions, type QueueSubmitOptions, type ReactNativeFile, type RealTimeClient, type RealTimeClientConnectOptions, type RealTimeClientInitialState, type Events as RealTimeEvents, type RealTimeModels, type RealTimeSubscribeClient, type ReconnectEvent, type SetInput, type SubscribeEvents, type SubscribeOptions, type TokensClient, type VideoModelDefinition, type VideoModels, type VideoStallEvent, type WebRTCStats, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveModelAlias };
+export { type CanonicalModel, type ClientSessionConnectionBreakdownEvent, type ClientSessionConnectionBreakdownPhase, type ConnectionState, type CreateTokenOptions, type CreateTokenResponse, type CustomModelDefinition, DecartClientOptions, type DecartSDKError, type DiagnosticEvent, type DiagnosticEventName, type DiagnosticEvents, ERROR_CODES, type FileInput, type FileReference, type FileUploadInput, type FilesClient, type GenerationEndedMessage, type ImageModelDefinition, type ImageModels, type JobStatus, type JobStatusResponse, type JobSubmitResponse, type ListedModelDefinition, type LogLevel, type Logger, type Model, type ModelDefinition, type ModelKind, type ModelState, type ProcessClient, type ProcessOptions, type QueueClient, type QueueJobResult, type QueuePosition, type QueuePositionMessage, type QueueSubmitAndPollOptions, type QueueSubmitOptions, type ReactNativeFile, type RealTimeClient, type RealTimeClientConnectOptions, type RealTimeClientInitialState, type Events as RealTimeEvents, type RealTimeModels, type RealTimeSubscribeClient, type ReconnectEvent, type SetInput, type SubscribeEvents, type SubscribeOptions, type TokensClient, type UploadFileOptions, type VideoModelDefinition, type VideoModels, type VideoStallEvent, type WebRTCStats, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveModelAlias };

package/dist/index.js

@@ -1,4 +1,5 @@
 import { ERROR_CODES, createInvalidApiKeyError, createInvalidBaseUrlError } from "./utils/errors.js";
+import { createFilesClient } from "./files/client.js";
 import { createProcessClient } from "./process/client.js";
 import { createQueueClient } from "./queue/client.js";
 import { isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, resolveCanonicalModelAlias, resolveModelAlias } from "./shared/model.js";
@@ -92,6 +93,11 @@ const createDecartClient = (options = {}) => {
 		apiKey: apiKey || "",
 		integration
 	});
+	const files = createFilesClient({
+		baseUrl,
+		apiKey: apiKey || "",
+		integration
+	});
 	return {
 		realtime: {
 			connect: realtimePublish.connect,
@@ -99,7 +105,8 @@ const createDecartClient = (options = {}) => {
 		},
 		process,
 		queue,
-		tokens
+		tokens,
+		files
 	};
 };
 //#endregion

package/dist/realtime/client.d.ts

@@ -78,6 +78,12 @@ type RealTimeClient = {
   sessionId: string | null;
   subscribeToken: string | null;
   getSubscribeToken: () => string | null;
+  /**
+   * Set the reference image for the session.
+   * - `Blob`/`File`/data URL/http(s) URL/base64 string: bytes traverse the wire as base64.
+   * - `"file_..."` id (from `client.files.upload(...).id`): sent as a server-side reference.
+   * - `null`: clear the current image.
+   */
   setImage: (image: Blob | File | string | null, options?: ImageSetOptions) => Promise<void>;
 };
 //#endregion

package/dist/realtime/client.js

@@ -1,4 +1,5 @@
 import { classifyWebrtcError } from "../utils/errors.js";
+import { isFileRefId } from "../files/types.js";
 import { modelDefinitionSchema, resolveFpsNumber } from "../shared/model.js";
 import { modelStateSchema } from "../shared/types.js";
 import { createConsoleLogger } from "../utils/logger.js";
@@ -44,7 +45,8 @@ const createRealTimeClient = (opts) => {
 		let session;
 		let observability;
 		try {
-			const initialImage = initialState?.image ? await imageToBase64(initialState.image) : void 0;
+			const initialImageRef = isFileRefId(initialState?.image) ? initialState.image : void 0;
+			const initialImage = initialImageRef === void 0 && initialState?.image ? await imageToBase64(initialState.image) : void 0;
 			const initialPrompt = initialState?.prompt ? {
 				text: initialState.prompt.text,
 				enhance: initialState.prompt.enhance
@@ -73,6 +75,7 @@ const createRealTimeClient = (opts) => {
 				observability,
 				localStream: inputStream,
 				initialImage,
+				initialImageRef,
 				initialPrompt,
 				logger,
 				videoCodec: safariCodec
@@ -121,9 +124,19 @@ const createRealTimeClient = (opts) => {
 				},
 				getSubscribeToken: () => subscribeToken,
 				setImage: async (image, imgOptions) => {
-					if (image === null) return activeSession.setImage(null, imgOptions);
+					if (isFileRefId(image)) return activeSession.setImage({
+						kind: "ref",
+						ref: image
+					}, imgOptions);
+					if (image === null) return activeSession.setImage({
+						kind: "data",
+						data: null
+					}, imgOptions);
 					const base64 = await imageToBase64(image);
-					return activeSession.setImage(base64, imgOptions);
+					return activeSession.setImage({
+						kind: "data",
+						data: base64
+					}, imgOptions);
 				}
 			};
 			flush();

package/dist/realtime/methods.js

@@ -1,3 +1,4 @@
+import { isFileRefId } from "../files/types.js";
 import { REALTIME_CONFIG } from "./config-realtime.js";
 import { z } from "zod";
 //#region src/realtime/methods.ts
@@ -20,12 +21,23 @@ const realtimeMethods = (session, imageToBase64) => {
 		const parsed = setInputSchema.safeParse(input);
 		if (!parsed.success) throw parsed.error;
 		const { prompt, enhance, image } = parsed.data;
-		const imageBase64 = image !== void 0 && image !== null ? await imageToBase64(image) : null;
-		await session.setImage(imageBase64, {
+		const options = {
 			prompt,
 			enhance,
 			timeout: REALTIME_CONFIG.methods.updateTimeoutMs
-		});
+		};
+		if (isFileRefId(image)) {
+			await session.setImage({
+				kind: "ref",
+				ref: image
+			}, options);
+			return;
+		}
+		const imageBase64 = image !== void 0 && image !== null ? await imageToBase64(image) : null;
+		await session.setImage({
+			kind: "data",
+			data: imageBase64
+		}, options);
 	};
 	const setPrompt = async (prompt, { enhance } = {}) => {
 		const parsed = setPromptInputSchema.safeParse({

package/dist/realtime/signaling-channel.js

@@ -79,10 +79,13 @@ var SignalingChannel = class {
 		});
 		if (!ack.success) throw new Error(ack.error ?? "Failed to send prompt");
 	}
-	async setImage(image, opts = {}) {
-		const message = {
+	async setImage(payload, opts = {}) {
+		const message = payload.kind === "ref" ? {
 			type: "set_image",
-			image_data: image
+			image_ref: payload.ref
+		} : {
+			type: "set_image",
+			image_data: payload.data
 		};
 		if (opts.prompt !== void 0) message.prompt = opts.prompt;
 		if (opts.enhance !== void 0) message.enhance_prompt = opts.enhance;
@@ -179,8 +182,21 @@ var SignalingChannel = class {
 	}
 	async sendInitialState(initialState) {
 		if (!initialState) return;
+		if (initialState.imageRef !== void 0) {
+			await this.setImage({
+				kind: "ref",
+				ref: initialState.imageRef
+			}, {
+				prompt: initialState.prompt,
+				enhance: initialState.enhance
+			});
+			return;
+		}
 		if (initialState.image !== void 0) {
-			await this.setImage(initialState.image, {
+			await this.setImage({
+				kind: "data",
+				data: initialState.image
+			}, {
 				prompt: initialState.prompt,
 				enhance: initialState.enhance
 			});

package/dist/realtime/stream-session.js

@@ -68,9 +68,9 @@ var StreamSession = class {
 		this.assertConnected();
 		return this.signaling.sendPrompt(text, opts);
 	}
-	async setImage(image, opts) {
+	async setImage(payload, opts) {
 		this.assertConnected();
-		return this.signaling.setImage(image, opts);
+		return this.signaling.setImage(payload, opts);
 	}
 	disconnect() {
 		this.disposed = true;
@@ -141,6 +141,11 @@ var StreamSession = class {
 		}
 	}
 	getInitialState() {
+		if (this.config.initialImageRef !== void 0) return {
+			imageRef: this.config.initialImageRef,
+			prompt: this.config.initialPrompt?.text,
+			enhance: this.config.initialPrompt?.enhance
+		};
 		if (this.config.initialImage !== void 0) return {
 			image: this.config.initialImage,
 			prompt: this.config.initialPrompt?.text,

package/dist/utils/errors.d.ts

@@ -17,6 +17,9 @@ declare const ERROR_CODES: {
   readonly QUEUE_RESULT_ERROR: "QUEUE_RESULT_ERROR";
   readonly JOB_NOT_COMPLETED: "JOB_NOT_COMPLETED";
   readonly TOKEN_CREATE_ERROR: "TOKEN_CREATE_ERROR";
+  readonly FILES_UPLOAD_ERROR: "FILES_UPLOAD_ERROR";
+  readonly FILES_GET_ERROR: "FILES_GET_ERROR";
+  readonly FILES_DELETE_ERROR: "FILES_DELETE_ERROR";
   readonly WEBRTC_WEBSOCKET_ERROR: "WEBRTC_WEBSOCKET_ERROR";
   readonly WEBRTC_ICE_ERROR: "WEBRTC_ICE_ERROR";
   readonly WEBRTC_TIMEOUT_ERROR: "WEBRTC_TIMEOUT_ERROR";

package/dist/utils/errors.js

@@ -11,6 +11,9 @@ const ERROR_CODES = {
 	QUEUE_RESULT_ERROR: "QUEUE_RESULT_ERROR",
 	JOB_NOT_COMPLETED: "JOB_NOT_COMPLETED",
 	TOKEN_CREATE_ERROR: "TOKEN_CREATE_ERROR",
+	FILES_UPLOAD_ERROR: "FILES_UPLOAD_ERROR",
+	FILES_GET_ERROR: "FILES_GET_ERROR",
+	FILES_DELETE_ERROR: "FILES_DELETE_ERROR",
 	WEBRTC_WEBSOCKET_ERROR: "WEBRTC_WEBSOCKET_ERROR",
 	WEBRTC_ICE_ERROR: "WEBRTC_ICE_ERROR",
 	WEBRTC_TIMEOUT_ERROR: "WEBRTC_TIMEOUT_ERROR",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decartai/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Decart's JavaScript SDK",
   "type": "module",
   "license": "MIT",