@lotics/app-sdk 0.8.0 → 0.9.0

package/dist/src/rpc.js

@@ -1,4 +1,5 @@
 import { promptForPassword } from "./password_gate.js";
+import { runUploadPipeline } from "./upload/pipeline.js";
 /** The embedding Lotics host's origin — present iff the app is bridged. */
 const hostOrigin = new URLSearchParams(window.location.search).get("lotics_host");
 export function rpc(op, payload) {
@@ -197,23 +198,9 @@ async function standaloneUpload(file) {
         throw new Error("upload payload must include a File");
     }
     const { app_id } = await boot();
-    const init = (await apiCall("POST", `/v1/apps/${app_id}/files/upload-url`, {
-        filename: file.name,
-        mime_type: file.type,
-        file_size: file.size,
-    }, { appId: app_id }));
-    const put = await fetch(init.upload_url, {
-        method: "PUT",
-        body: file,
-        headers: { "Content-Type": file.type },
+    const uploaded = await runUploadPipeline(file, {
+        initUpload: (input) => apiCall("POST", `/v1/apps/${app_id}/files/upload-url`, input, { appId: app_id }),
+        completeUpload: (input) => apiCall("POST", `/v1/apps/${app_id}/files/complete`, input, { appId: app_id }),
     });
-    if (!put.ok) {
-        throw new Error(`Storage upload failed (${put.status})`);
-    }
-    const done = (await apiCall("POST", `/v1/apps/${app_id}/files/complete`, {
-        file_id: init.file_id,
-        file_storage_key: init.file_storage_key,
-        filename: file.name,
-    }, { appId: app_id }));
-    return done.file;
+    return uploaded;
 }

package/dist/src/upload/optimize.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Browser-side image compression for app uploads.
+ *
+ * Phone-camera photos are huge (4–10 MB HEIC/JPEG) but documents only need
+ * legible bytes, not megapixel ones. Resize to ≤1280px on the long edge and
+ * re-encode as JPEG at q=0.75 before uploading — typically 10–20× smaller
+ * with no visible quality loss for the doc-scan use case.
+ *
+ * HEIC/HEIF / PNG / WebP are converted to JPEG. Non-image files (PDF, etc.)
+ * pass through unchanged. Falls through gracefully on any browser API gap
+ * — the original file is always returned as a usable upload candidate.
+ *
+ * Ported from `frontend/lib/upload_file_optimization.ts` so public-app forms
+ * get the same mobile-friendly upload behavior as the in-Lotics UI. Kept
+ * dependency-free (no logger, no UploadIntent abstraction) so the SDK ships
+ * as a single drop-in.
+ */
+export type OptimizationReason = "optimized" | "skipped_unsupported_format" | "skipped_environment_unsupported" | "skipped_decode_unavailable" | "skipped_invalid_dimensions" | "skipped_small_dimensions" | "skipped_canvas_unavailable" | "skipped_canvas_type_mismatch";
+export interface OptimizationResult {
+    file: File;
+    optimized: boolean;
+    reason: OptimizationReason;
+    originalSizeBytes: number;
+    optimizedSizeBytes: number;
+    width: number;
+    height: number;
+    targetWidth: number;
+    targetHeight: number;
+}
+export declare function optimizeImageForUpload(file: File): Promise<OptimizationResult>;

package/dist/src/upload/optimize.js

@@ -0,0 +1,182 @@
+/**
+ * Browser-side image compression for app uploads.
+ *
+ * Phone-camera photos are huge (4–10 MB HEIC/JPEG) but documents only need
+ * legible bytes, not megapixel ones. Resize to ≤1280px on the long edge and
+ * re-encode as JPEG at q=0.75 before uploading — typically 10–20× smaller
+ * with no visible quality loss for the doc-scan use case.
+ *
+ * HEIC/HEIF / PNG / WebP are converted to JPEG. Non-image files (PDF, etc.)
+ * pass through unchanged. Falls through gracefully on any browser API gap
+ * — the original file is always returned as a usable upload candidate.
+ *
+ * Ported from `frontend/lib/upload_file_optimization.ts` so public-app forms
+ * get the same mobile-friendly upload behavior as the in-Lotics UI. Kept
+ * dependency-free (no logger, no UploadIntent abstraction) so the SDK ships
+ * as a single drop-in.
+ */
+const MAX_IMAGE_DIMENSION_PX = 1280;
+const JPEG_QUALITY = 0.75;
+const CONVERTIBLE_EXTENSION_PATTERN = /\.(heic|heif|png|webp)$/i;
+export async function optimizeImageForUpload(file) {
+    const format = getOptimizableFormat(file);
+    const mimeType = format?.outputMimeType;
+    const unsupportedReason = getUnsupportedReason(file, mimeType);
+    if (unsupportedReason)
+        return unchanged(file, unsupportedReason);
+    if (!mimeType || !format)
+        return unchanged(file, "skipped_unsupported_format");
+    const loaded = await loadImage(file);
+    if (loaded.status === "decode_unavailable")
+        return unchanged(file, "skipped_decode_unavailable");
+    const { source, width, height } = loaded;
+    if (width <= 0 || height <= 0) {
+        closeSource(source);
+        return unchanged(file, "skipped_invalid_dimensions");
+    }
+    if (Math.max(width, height) <= MAX_IMAGE_DIMENSION_PX) {
+        closeSource(source);
+        return unchanged(file, "skipped_small_dimensions", width, height);
+    }
+    const { width: targetWidth, height: targetHeight } = scale(width, height);
+    const canvas = document.createElement("canvas");
+    canvas.width = targetWidth;
+    canvas.height = targetHeight;
+    const ctx = canvas.getContext("2d");
+    if (!ctx || typeof canvas.toBlob !== "function") {
+        closeSource(source);
+        return unchanged(file, "skipped_canvas_unavailable", width, height);
+    }
+    ctx.imageSmoothingEnabled = true;
+    ctx.imageSmoothingQuality = "high";
+    ctx.drawImage(source, 0, 0, targetWidth, targetHeight);
+    closeSource(source);
+    const blob = await canvasToBlob(canvas, mimeType);
+    if (blob.type !== mimeType) {
+        return unchanged(file, "skipped_canvas_type_mismatch", width, height, targetWidth, targetHeight);
+    }
+    return {
+        file: new File([blob], format.outputFilename, {
+            type: mimeType,
+            lastModified: file.lastModified,
+        }),
+        optimized: true,
+        reason: "optimized",
+        originalSizeBytes: file.size,
+        optimizedSizeBytes: blob.size,
+        width,
+        height,
+        targetWidth,
+        targetHeight,
+    };
+}
+function getUnsupportedReason(file, mimeType) {
+    void file;
+    if (mimeType === undefined)
+        return "skipped_unsupported_format";
+    if (typeof window === "undefined" ||
+        typeof document === "undefined" ||
+        typeof document.createElement !== "function" ||
+        typeof URL.createObjectURL !== "function" ||
+        typeof URL.revokeObjectURL !== "function" ||
+        typeof Image === "undefined") {
+        return "skipped_environment_unsupported";
+    }
+    return undefined;
+}
+function getOptimizableFormat(file) {
+    const mimeType = normalizeMimeType(file.type);
+    if (!mimeType)
+        return undefined;
+    if (mimeType === "image/jpeg") {
+        return { outputMimeType: "image/jpeg", outputFilename: file.name };
+    }
+    // PNG / WebP / HEIC / HEIF → JPEG (transparency lost on PNG; acceptable
+    // for document uploads where we explicitly opt into lossy compression).
+    return { outputMimeType: "image/jpeg", outputFilename: replaceExtensionWithJpeg(file.name) };
+}
+function normalizeMimeType(mimeType) {
+    const m = mimeType.toLowerCase();
+    if (m === "image/jpeg" || m === "image/jpg")
+        return "image/jpeg";
+    if (m === "image/heic" || m === "image/heif")
+        return m;
+    if (m === "image/png" || m === "image/webp")
+        return m;
+    return undefined;
+}
+function replaceExtensionWithJpeg(filename) {
+    if (CONVERTIBLE_EXTENSION_PATTERN.test(filename)) {
+        return filename.replace(CONVERTIBLE_EXTENSION_PATTERN, ".jpg");
+    }
+    return `${filename}.jpg`;
+}
+function unchanged(file, reason, width = 0, height = 0, targetWidth = width, targetHeight = height) {
+    return {
+        file,
+        optimized: false,
+        reason,
+        originalSizeBytes: file.size,
+        optimizedSizeBytes: file.size,
+        width,
+        height,
+        targetWidth,
+        targetHeight,
+    };
+}
+function closeSource(source) {
+    if ("close" in source && typeof source.close === "function")
+        source.close();
+}
+function scale(width, height) {
+    const largest = Math.max(width, height);
+    if (largest <= MAX_IMAGE_DIMENSION_PX)
+        return { width, height };
+    const factor = MAX_IMAGE_DIMENSION_PX / largest;
+    return {
+        width: Math.max(1, Math.round(width * factor)),
+        height: Math.max(1, Math.round(height * factor)),
+    };
+}
+async function loadImage(file) {
+    // Prefer createImageBitmap — off-main-thread decode, more reliable on
+    // mobile under memory pressure where Image() silently fails.
+    if (typeof createImageBitmap === "function") {
+        try {
+            const bitmap = await createImageBitmap(file);
+            return { status: "decoded", source: bitmap, width: bitmap.width, height: bitmap.height };
+        }
+        catch {
+            // unsupported format / corrupt — fall back to Image()
+        }
+    }
+    const objectUrl = URL.createObjectURL(file);
+    return new Promise((resolve) => {
+        const image = new Image();
+        const cleanup = () => {
+            image.onload = null;
+            image.onerror = null;
+            URL.revokeObjectURL(objectUrl);
+        };
+        image.onload = () => {
+            cleanup();
+            resolve({ status: "decoded", source: image, width: image.naturalWidth, height: image.naturalHeight });
+        };
+        image.onerror = () => {
+            cleanup();
+            resolve({ status: "decode_unavailable" });
+        };
+        image.src = objectUrl;
+    });
+}
+async function canvasToBlob(canvas, mimeType) {
+    return new Promise((resolve, reject) => {
+        canvas.toBlob((blob) => {
+            if (!blob) {
+                reject(new Error("Canvas export returned no data during upload optimization"));
+                return;
+            }
+            resolve(blob);
+        }, mimeType, JPEG_QUALITY);
+    });
+}

package/dist/src/upload/pipeline.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Orchestrator for the app-upload pipeline.
+ *
+ *   File → optimize (image only) → request presigned URL →
+ *     PUT to storage (with retry) → complete → ProcessedFile
+ *
+ * Each step is a focused module (see `optimize.ts`, `transport.ts`); this
+ * file just wires them together so `useFileUpload` callers get one robust
+ * "uploaded" promise instead of a bare-fetch happy path.
+ *
+ * Surface is intentionally minimal: the only knob is an optional
+ * `AbortSignal` for caller cancellation. Optimization, retries, and
+ * timeouts use platform-internal defaults — same conventions as the
+ * in-Lotics direct-upload pipeline.
+ */
+interface UploadInitResponse {
+    upload_url: string;
+    file_id: string;
+    file_storage_key: string;
+}
+interface CompleteResponseFile {
+    id: string;
+    filename: string;
+    mime_type: string;
+    url?: string;
+    thumbnail_url?: string;
+    preview_url?: string;
+}
+/**
+ * Caller injects the RPC primitives so this module stays decoupled from the
+ * SDK's auth / bootstrap layer. The pipeline targets a specific app's upload
+ * endpoints via the supplied `initUpload` and `completeUpload`.
+ */
+export interface UploadRpc {
+    initUpload(input: {
+        filename: string;
+        mime_type: string;
+        file_size: number;
+    }): Promise<UploadInitResponse>;
+    completeUpload(input: {
+        file_id: string;
+        file_storage_key: string;
+        filename: string;
+    }): Promise<{
+        file: CompleteResponseFile;
+    }>;
+}
+export interface RunUploadPipelineOptions {
+    signal?: AbortSignal;
+}
+export declare function runUploadPipeline(file: File, rpc: UploadRpc, options?: RunUploadPipelineOptions): Promise<CompleteResponseFile>;
+export {};

package/dist/src/upload/pipeline.js

@@ -0,0 +1,52 @@
+/**
+ * Orchestrator for the app-upload pipeline.
+ *
+ *   File → optimize (image only) → request presigned URL →
+ *     PUT to storage (with retry) → complete → ProcessedFile
+ *
+ * Each step is a focused module (see `optimize.ts`, `transport.ts`); this
+ * file just wires them together so `useFileUpload` callers get one robust
+ * "uploaded" promise instead of a bare-fetch happy path.
+ *
+ * Surface is intentionally minimal: the only knob is an optional
+ * `AbortSignal` for caller cancellation. Optimization, retries, and
+ * timeouts use platform-internal defaults — same conventions as the
+ * in-Lotics direct-upload pipeline.
+ */
+import { optimizeImageForUpload } from "./optimize.js";
+import { putToStorageWithRetry } from "./transport.js";
+export async function runUploadPipeline(file, rpc, options = {}) {
+    const { signal } = options;
+    // 1. Compress images. Non-image files return unchanged. Failures here are
+    //    intentionally swallowed — the user shouldn't see an upload error
+    //    because canvas threw; we just upload the original bytes.
+    let candidate = file;
+    try {
+        const optimized = await optimizeImageForUpload(file);
+        candidate = optimized.file;
+    }
+    catch {
+        // fall through with original file
+    }
+    if (signal?.aborted)
+        throw new Error("Upload aborted");
+    // 2. Ask the backend for a presigned upload URL.
+    const init = await rpc.initUpload({
+        filename: candidate.name,
+        mime_type: candidate.type,
+        file_size: candidate.size,
+    });
+    // 3. PUT the bytes with timeout + retry. This is the mobile-network
+    //    failure point.
+    const putResponse = await putToStorageWithRetry(init.upload_url, candidate, signal);
+    if (!putResponse.ok) {
+        throw new Error(`Storage upload failed (${putResponse.status}). Please check your connection and try again.`);
+    }
+    // 4. Finalize — the server validates the object and creates the file row.
+    const { file: uploaded } = await rpc.completeUpload({
+        file_id: init.file_id,
+        file_storage_key: init.file_storage_key,
+        filename: candidate.name,
+    });
+    return uploaded;
+}

package/dist/src/upload/transport.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Transport-layer helpers for the SDK upload pipeline.
+ *
+ * Two concerns this module owns:
+ *
+ * 1. **Per-request timeout.** A bare `fetch` hangs forever if the network is
+ *    unreachable; we wrap it in an `AbortController` so a stuck request fails
+ *    after `UPLOAD_TIMEOUT_MS` instead of leaving the user staring at a
+ *    spinner.
+ *
+ * 2. **Retry with exponential backoff** for the presigned `PUT` to object
+ *    storage — the single most failure-prone step on mobile networks. We
+ *    retry on network errors / 5xx / timeouts up to `UPLOAD_PUT_MAX_ATTEMPTS`
+ *    with 1s → 2s → 4s waits between attempts. We do NOT retry on 4xx
+ *    (client error, retrying won't help) or on caller-initiated aborts.
+ *
+ * Mirrors the conventions in `frontend/lib/api_utils.ts` and
+ * `frontend/lib/file_upload.ts`, simplified for the SDK (no logger, no
+ * correlation headers).
+ */
+export declare const UPLOAD_TIMEOUT_MS: number;
+export declare class UploadTimeoutError extends Error {
+    readonly url: string;
+    readonly timeoutMs: number;
+    readonly name = "UploadTimeoutError";
+    constructor(url: string, timeoutMs: number);
+}
+export declare class UploadAbortedError extends Error {
+    readonly name = "UploadAbortedError";
+    constructor();
+}
+/** `fetch` with timeout + optional external `AbortSignal`. */
+export declare function fetchWithTimeout(url: string, init: RequestInit, timeoutMs: number): Promise<Response>;
+/**
+ * Presigned-PUT to object storage with retry + backoff.
+ *
+ * Retries network errors, timeouts, and 5xx responses up to
+ * `UPLOAD_PUT_MAX_ATTEMPTS` times. A 4xx response is returned to the caller
+ * unchanged (retrying a 403/400 won't help; the caller decides). Aborts
+ * propagate immediately without retry.
+ */
+export declare function putToStorageWithRetry(uploadUrl: string, file: File, signal: AbortSignal | undefined): Promise<Response>;

package/dist/src/upload/transport.js

@@ -0,0 +1,128 @@
+/**
+ * Transport-layer helpers for the SDK upload pipeline.
+ *
+ * Two concerns this module owns:
+ *
+ * 1. **Per-request timeout.** A bare `fetch` hangs forever if the network is
+ *    unreachable; we wrap it in an `AbortController` so a stuck request fails
+ *    after `UPLOAD_TIMEOUT_MS` instead of leaving the user staring at a
+ *    spinner.
+ *
+ * 2. **Retry with exponential backoff** for the presigned `PUT` to object
+ *    storage — the single most failure-prone step on mobile networks. We
+ *    retry on network errors / 5xx / timeouts up to `UPLOAD_PUT_MAX_ATTEMPTS`
+ *    with 1s → 2s → 4s waits between attempts. We do NOT retry on 4xx
+ *    (client error, retrying won't help) or on caller-initiated aborts.
+ *
+ * Mirrors the conventions in `frontend/lib/api_utils.ts` and
+ * `frontend/lib/file_upload.ts`, simplified for the SDK (no logger, no
+ * correlation headers).
+ */
+export const UPLOAD_TIMEOUT_MS = 5 * 60 * 1000;
+const UPLOAD_PUT_MAX_ATTEMPTS = 3;
+const UPLOAD_PUT_BACKOFF_BASE_MS = 1000;
+export class UploadTimeoutError extends Error {
+    url;
+    timeoutMs;
+    name = "UploadTimeoutError";
+    constructor(url, timeoutMs) {
+        super(`Upload request to ${url} timed out after ${timeoutMs}ms`);
+        this.url = url;
+        this.timeoutMs = timeoutMs;
+    }
+}
+export class UploadAbortedError extends Error {
+    name = "UploadAbortedError";
+    constructor() {
+        super("Upload aborted");
+    }
+}
+/** `fetch` with timeout + optional external `AbortSignal`. */
+export async function fetchWithTimeout(url, init, timeoutMs) {
+    const controller = new AbortController();
+    let didTimeout = false;
+    const timeoutId = setTimeout(() => {
+        didTimeout = true;
+        controller.abort();
+    }, timeoutMs);
+    if (init.signal) {
+        if (init.signal.aborted) {
+            clearTimeout(timeoutId);
+            throw new UploadAbortedError();
+        }
+        init.signal.addEventListener("abort", () => controller.abort(), { once: true });
+    }
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    catch (err) {
+        if (didTimeout)
+            throw new UploadTimeoutError(url, timeoutMs);
+        if (init.signal?.aborted)
+            throw new UploadAbortedError();
+        throw err;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Presigned-PUT to object storage with retry + backoff.
+ *
+ * Retries network errors, timeouts, and 5xx responses up to
+ * `UPLOAD_PUT_MAX_ATTEMPTS` times. A 4xx response is returned to the caller
+ * unchanged (retrying a 403/400 won't help; the caller decides). Aborts
+ * propagate immediately without retry.
+ */
+export async function putToStorageWithRetry(uploadUrl, file, signal) {
+    let lastError;
+    for (let attempt = 1; attempt <= UPLOAD_PUT_MAX_ATTEMPTS; attempt += 1) {
+        try {
+            const response = await fetchWithTimeout(uploadUrl, {
+                method: "PUT",
+                headers: { "Content-Type": file.type },
+                body: file,
+                signal,
+            }, UPLOAD_TIMEOUT_MS);
+            if (response.ok)
+                return response;
+            // 4xx is terminal — retrying a malformed/expired URL is pointless.
+            if (response.status >= 400 && response.status < 500)
+                return response;
+            // 5xx — fall through to retry.
+            lastError = new Error(`Storage PUT returned ${response.status}`);
+        }
+        catch (err) {
+            // Caller-initiated abort: stop immediately.
+            if (err instanceof UploadAbortedError)
+                throw err;
+            lastError = err;
+        }
+        if (attempt < UPLOAD_PUT_MAX_ATTEMPTS) {
+            const delayMs = UPLOAD_PUT_BACKOFF_BASE_MS * 2 ** (attempt - 1);
+            await sleep(delayMs, signal);
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error("Storage PUT failed");
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new UploadAbortedError());
+            return;
+        }
+        const timeoutId = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        const cleanup = () => {
+            clearTimeout(timeoutId);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const onAbort = () => {
+            cleanup();
+            reject(new UploadAbortedError());
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {