lemon-model 1.2.4 → 1.5.0

package/dist/upload/engine/engine.js

@@ -0,0 +1,210 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asStorageFailure = exports.asApiFailure = exports.UploadEngine = exports.UPLOAD_DEFAULT_CONCURRENCY = void 0;
+const types_1 = require("../types");
+const progress_1 = require("./progress");
+/**
+ * transfers in flight at once.
+ * - a browser queues beyond ~6 per origin, and a queued presigned url burns its `expiresAt` while it waits.
+ * - override per engine when a shell measures something better.
+ */
+exports.UPLOAD_DEFAULT_CONCURRENCY = 3;
+/** run `task` over 0..count-1 with at most `limit` in flight; results keep input order */
+const runPooled = (count, limit, task) => __awaiter(void 0, void 0, void 0, function* () {
+    const results = new Array(count);
+    let next = 0;
+    const worker = () => __awaiter(void 0, void 0, void 0, function* () {
+        for (;;) {
+            const index = next++;
+            if (index >= count)
+                return;
+            results[index] = yield task(index);
+        }
+    });
+    const size = Math.max(1, Math.min(limit, count));
+    yield Promise.all(new Array(size).fill(0).map(() => worker()));
+    return results;
+});
+const asContent = (source) => __awaiter(void 0, void 0, void 0, function* () {
+    return ({
+        contentType: source.contentType,
+        contentSize: source.contentSize,
+        width: source.width,
+        height: source.height,
+        hash: source.hash ? yield source.hash() : undefined,
+    });
+});
+const asIntent = (source) => __awaiter(void 0, void 0, void 0, function* () {
+    return (Object.assign(Object.assign({}, (yield asContent(source))), { name: source.name, thumbnail: source.thumbnail ? yield asContent(source.thumbnail) : undefined }));
+});
+/** bytes this source puts on the wire in total; the thumbnail rides along so the bar counts it */
+const sizeOf = (source) => { var _a, _b; return source.contentSize + ((_b = (_a = source.thumbnail) === null || _a === void 0 ? void 0 : _a.contentSize) !== null && _b !== void 0 ? _b : 0); };
+class UploadEngine {
+    constructor(service, executors, options) {
+        this.service = service;
+        this.executors = executors;
+        this.options = options;
+        this.kinds = executors.map(executor => executor.kind);
+    }
+    /** returns one view per source, in order: `stored`, or `failed` with the reason. `onProgress` gets a snapshot per change */
+    upload(sources, onProgress) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const tracker = new progress_1.UploadProgressTracker(sources.map(sizeOf), onProgress);
+            tracker.publish();
+            const list = yield Promise.all(sources.map(asIntent));
+            const { list: tickets } = yield this.service.start({ list, transfers: this.kinds });
+            const limit = (_b = (_a = this.options) === null || _a === void 0 ? void 0 : _a.concurrency) !== null && _b !== void 0 ? _b : exports.UPLOAD_DEFAULT_CONCURRENCY;
+            const receipts = yield runPooled(tickets.length, limit, i => this.transferTracked(tickets[i], sources[i], tracker, i));
+            // a server that broke rule 1 (shorter list) must not leave the bar hanging
+            sources.forEach((_, i) => tracker.settle(i));
+            const pending = receipts.filter((item) => !!item);
+            const settled = pending.length ? (yield this.service.complete({ list: pending })).list : [];
+            const byId = new Map(settled.filter(upload => !!upload.id).map((upload) => [upload.id, upload]));
+            return tickets.map(ticket => (ticket.upload.id && byId.get(ticket.upload.id)) || ticket.upload);
+        });
+    }
+    transferTracked(ticket, source, tracker, index) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                return yield this.transfer(ticket, source, tracker.sink(index));
+            }
+            catch (error) {
+                // an executor that throws (a CORS preflight failure surfaces as one) must not take the batch down
+                const id = ticket.upload.id;
+                if (!id)
+                    return undefined;
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    id,
+                    failure: { source: types_1.UPLOAD_FAILURE_SOURCE.client, code: types_1.UPLOAD_FAILURE_CODE.unknown, message },
+                };
+            }
+            finally {
+                tracker.settle(index);
+            }
+        });
+    }
+    transfer(ticket, source, onProgress) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const id = ticket.upload.id;
+            // rejected at start: nothing was created, nothing to complete
+            if (!id)
+                return undefined;
+            const receipt = yield this.transferOriginal(id, ticket.transfer, source, onProgress);
+            // a failed original has nothing to preview; otherwise the thumbnail rides after it (never with it)
+            if (!receipt.failure)
+                yield this.transferThumbnail(id, ticket.thumbnailTransfer, source, onProgress);
+            return receipt;
+        });
+    }
+    transferOriginal(id, transfer, source, onProgress) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // no instruction: already stored (dedup, or a stored upload taking only a thumbnail) — complete still confirms it
+            if (!transfer)
+                return { id };
+            const executor = this.executors.find(candidate => candidate.kind === transfer.kind);
+            if (!executor)
+                return { id, failure: { source: types_1.UPLOAD_FAILURE_SOURCE.client, code: types_1.UPLOAD_FAILURE_CODE.notAcceptable } };
+            // NOTE: `transfer` must not be logged or stored — it may carry a credential url
+            return executor.run(id, transfer, source, onProgress);
+        });
+    }
+    /**
+     * the preview is subordinate: whatever happens here never reaches `complete`.
+     * - `UploadCompleteItem` is one per upload, so reporting a thumbnail failure would fail the original.
+     * - the server settles the thumbnail by looking at storage at `complete` time, so silence is enough.
+     */
+    transferThumbnail(id, transfer, source, onProgress) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const thumbnail = source.thumbnail;
+            if (!transfer || !thumbnail)
+                return;
+            const executor = this.executors.find(candidate => candidate.kind === transfer.kind);
+            if (!executor)
+                return;
+            // the original's bytes are already counted, so the thumbnail reports on top of them
+            const base = source.contentSize;
+            try {
+                yield executor.run(id, transfer, thumbnail, sent => onProgress(base + sent));
+            }
+            catch (_a) {
+                // swallowed on purpose: see the note above
+            }
+        });
+    }
+}
+exports.UploadEngine = UploadEngine;
+/** lemon-core error convention: "<status> <LABEL> - <detail>" (status 0 = no response, XHR convention) */
+const API_ERROR = /^(\d{1,3}) ([A-Z][A-Z ]*?) - ([\s\S]*)$/;
+const codeOfApiStatus = (status) => {
+    switch (status) {
+        case 0:
+            return types_1.UPLOAD_FAILURE_CODE.network;
+        case 400:
+            return types_1.UPLOAD_FAILURE_CODE.invalid;
+        case 404:
+            return types_1.UPLOAD_FAILURE_CODE.notFound;
+        case 406:
+            return types_1.UPLOAD_FAILURE_CODE.notAcceptable;
+        case 409:
+            return types_1.UPLOAD_FAILURE_CODE.conflict;
+        case 410:
+            return types_1.UPLOAD_FAILURE_CODE.expired;
+        case 413:
+            return types_1.UPLOAD_FAILURE_CODE.tooLarge;
+        case 415:
+            return types_1.UPLOAD_FAILURE_CODE.unsupported;
+        default:
+            return types_1.UPLOAD_FAILURE_CODE.unknown;
+    }
+};
+/** normalize an error thrown by the API adapter */
+const asApiFailure = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    const match = API_ERROR.exec(message);
+    if (!match)
+        return { source: types_1.UPLOAD_FAILURE_SOURCE.api, code: types_1.UPLOAD_FAILURE_CODE.unknown, message };
+    const status = Number(match[1]);
+    return {
+        source: types_1.UPLOAD_FAILURE_SOURCE.api,
+        code: codeOfApiStatus(status),
+        status,
+        reason: match[2],
+        message: match[3],
+    };
+};
+exports.asApiFailure = asApiFailure;
+/** S3 error `<Code>` -> normalized code. unknown codes fall back by status */
+const STORAGE_CODES = {
+    SignatureDoesNotMatch: types_1.UPLOAD_FAILURE_CODE.signature,
+    AccessDenied: types_1.UPLOAD_FAILURE_CODE.expired,
+    ExpiredToken: types_1.UPLOAD_FAILURE_CODE.expired,
+    BadDigest: types_1.UPLOAD_FAILURE_CODE.checksum,
+    XAmzContentSHA256Mismatch: types_1.UPLOAD_FAILURE_CODE.checksum,
+    EntityTooLarge: types_1.UPLOAD_FAILURE_CODE.tooLarge,
+    RequestTimeout: types_1.UPLOAD_FAILURE_CODE.network,
+};
+/** normalize a non-2xx answer from the storage endpoint (status 0 = no response) */
+const asStorageFailure = (status, code) => {
+    const known = code ? STORAGE_CODES[code] : undefined;
+    const byStatus = status === 0
+        ? types_1.UPLOAD_FAILURE_CODE.network
+        : status === 403
+            ? types_1.UPLOAD_FAILURE_CODE.signature
+            : status === 413
+                ? types_1.UPLOAD_FAILURE_CODE.tooLarge
+                : types_1.UPLOAD_FAILURE_CODE.unknown;
+    return { source: types_1.UPLOAD_FAILURE_SOURCE.storage, code: known !== null && known !== void 0 ? known : byStatus, status, reason: code };
+};
+exports.asStorageFailure = asStorageFailure;
+//# sourceMappingURL=engine.js.map

package/dist/upload/engine/engine.js.map

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

package/dist/upload/engine/executors.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `upload/engine/executors.ts`
+ * - one executor per `UploadTransfer` kind. **this is the only file that grows when the server
+ *   changes how bytes travel** — `UploadEngine` never does.
+ * - each executor takes its HTTP primitive from the shell: a fetch-based adapter reports no
+ *   progress, an `XMLHttpRequest`-based one forwards `upload.onprogress`.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import type { UploadCompleteItem, UploadInlineTransfer, UploadPresignedPutTransfer, UploadSendRequest, Upload } from '../types';
+import type { UploadContentSource, UploadTransferExecutor } from './engine';
+import type { UploadProgressSink, UploadWireProgress } from './progress';
+/**
+ * the `send` call as the shell provides it.
+ * - a fetch-based API adapter is `(id, body) => service.send(id, body)` and reports nothing;
+ * - an `XMLHttpRequest`-based one forwards `upload.onprogress` through `onProgress`.
+ */
+export declare type InlineSendCall = (id: string, body: UploadSendRequest, onProgress?: UploadWireProgress) => Promise<Upload>;
+/** inline transfer — the only place that knows bytes go to the API as base64 */
+export declare class InlineExecutor implements UploadTransferExecutor<UploadInlineTransfer> {
+    private readonly send;
+    /** shell-specific base64 encoder (btoa / Buffer / RN polyfill) */
+    private readonly toBase64;
+    readonly kind: "inline";
+    constructor(send: InlineSendCall, 
+    /** shell-specific base64 encoder (btoa / Buffer / RN polyfill) */
+    toBase64: (bytes: Uint8Array) => string);
+    run(id: string, transfer: UploadInlineTransfer, source: UploadContentSource, onProgress: UploadProgressSink): Promise<UploadCompleteItem>;
+}
+/**
+ * raw HTTP PUT provided by the shell; `code` = parsed S3 `<Code>`.
+ * - fetch-based: never calls `onProgress`. `XMLHttpRequest`-based: forwards `upload.onprogress`.
+ */
+export declare type RawPut = (url: string, headers: Record<string, string>, body: Uint8Array, onProgress?: UploadWireProgress) => Promise<{
+    status: number;
+    code?: string;
+}>;
+/** presigned PUT transfer — raw bytes straight to storage */
+export declare class PresignedPutExecutor implements UploadTransferExecutor<UploadPresignedPutTransfer> {
+    private readonly put;
+    readonly kind: "presigned-put";
+    constructor(put: RawPut);
+    run(id: string, transfer: UploadPresignedPutTransfer, source: UploadContentSource, onProgress: UploadProgressSink): Promise<UploadCompleteItem>;
+}

package/dist/upload/engine/executors.js

@@ -0,0 +1,62 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PresignedPutExecutor = exports.InlineExecutor = void 0;
+const types_1 = require("../types");
+const engine_1 = require("./engine");
+const progress_1 = require("./progress");
+/** inline transfer — the only place that knows bytes go to the API as base64 */
+class InlineExecutor {
+    constructor(send, 
+    /** shell-specific base64 encoder (btoa / Buffer / RN polyfill) */
+    toBase64) {
+        this.send = send;
+        this.toBase64 = toBase64;
+        this.kind = types_1.UPLOAD_TRANSFER_KIND.inline;
+    }
+    run(id, transfer, source, onProgress) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (source.contentSize > transfer.maxBytes) {
+                return { id, failure: { source: types_1.UPLOAD_FAILURE_SOURCE.client, code: types_1.UPLOAD_FAILURE_CODE.tooLarge } };
+            }
+            try {
+                const body = { content: this.toBase64(yield source.bytes()) };
+                // wire bytes are base64 JSON (~4/3 of the send): report in send bytes
+                yield this.send(id, body, (loaded, total) => onProgress((0, progress_1.asContentBytes)(loaded, total, source.contentSize)));
+                return { id };
+            }
+            catch (error) {
+                return { id, failure: (0, engine_1.asApiFailure)(error) };
+            }
+        });
+    }
+}
+exports.InlineExecutor = InlineExecutor;
+/** presigned PUT transfer — raw bytes straight to storage */
+class PresignedPutExecutor {
+    constructor(put) {
+        this.put = put;
+        this.kind = types_1.UPLOAD_TRANSFER_KIND.presignedPut;
+    }
+    run(id, transfer, source, onProgress) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const res = yield this.put(transfer.url, transfer.headers, yield source.bytes(), (loaded, total) => onProgress((0, progress_1.asContentBytes)(loaded, total, source.contentSize)));
+            if (res.status >= 200 && res.status < 300)
+                return { id };
+            // 412 = object already exists under this key; the server decides at complete
+            if (res.status === 412)
+                return { id };
+            return { id, failure: (0, engine_1.asStorageFailure)(res.status, res.code) };
+        });
+    }
+}
+exports.PresignedPutExecutor = PresignedPutExecutor;
+//# sourceMappingURL=executors.js.map

package/dist/upload/engine/executors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executors.js","sourceRoot":"","sources":["../../../src/upload/engine/executors.ts"],"names":[],"mappings":";;;;;;;;;;;;AAgBA,oCAA4F;AAE5F,qCAA0D;AAE1D,yCAA4C;AAS5C,gFAAgF;AAChF,MAAa,cAAc;IAGvB,YACqB,IAAoB;IACrC,kEAAkE;IACjD,QAAuC;QAFvC,SAAI,GAAJ,IAAI,CAAgB;QAEpB,aAAQ,GAAR,QAAQ,CAA+B;QAL5C,SAAI,GAAG,4BAAoB,CAAC,MAAM,CAAC;IAMhD,CAAC;IAES,GAAG,CACZ,EAAU,EACV,QAA8B,EAC9B,MAA2B,EAC3B,UAA8B;;YAE9B,IAAI,MAAM,CAAC,WAAW,GAAG,QAAQ,CAAC,QAAQ,EAAE;gBACxC,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,6BAAqB,CAAC,MAAM,EAAE,IAAI,EAAE,2BAAmB,CAAC,QAAQ,EAAE,EAAE,CAAC;aACxG;YACD,IAAI;gBACA,MAAM,IAAI,GAAsB,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC;gBACjF,sEAAsE;gBACtE,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,IAAA,yBAAc,EAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;gBAC5G,OAAO,EAAE,EAAE,EAAE,CAAC;aACjB;YAAC,OAAO,KAAK,EAAE;gBACZ,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,IAAA,qBAAY,EAAC,KAAK,CAAC,EAAE,CAAC;aAC/C;QACL,CAAC;KAAA;CACJ;AA3BD,wCA2BC;AAaD,6DAA6D;AAC7D,MAAa,oBAAoB;IAG7B,YAAoC,GAAW;QAAX,QAAG,GAAH,GAAG,CAAQ;QAF/B,SAAI,GAAG,4BAAoB,CAAC,YAAY,CAAC;IAEP,CAAC;IAEtC,GAAG,CACZ,EAAU,EACV,QAAoC,EACpC,MAA2B,EAC3B,UAA8B;;YAE9B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAC/F,UAAU,CAAC,IAAA,yBAAc,EAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,CAChE,CAAC;YACF,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG;gBAAE,OAAO,EAAE,EAAE,EAAE,CAAC;YACzD,6EAA6E;YAC7E,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;gBAAE,OAAO,EAAE,EAAE,EAAE,CAAC;YACtC,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,IAAA,yBAAgB,EAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACnE,CAAC;KAAA;CACJ;AAnBD,oDAmBC"}

package/dist/upload/engine/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `upload/engine/index.ts`
+ * - isolated entry for the client upload engine: `import { ... } from 'lemon-model/upload/engine'`.
+ * - kept OUT of both the package root barrel and `lemon-model/upload`: a server consumer needs the
+ *   contract only, and must not pull the engine in with it.
+ * - shell adapters (XHR, RN bridge, Electron fs) are NOT here — they belong to the consuming app.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+export * from './progress';
+export * from './engine';
+export * from './executors';

package/dist/upload/engine/index.js

@@ -0,0 +1,29 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `upload/engine/index.ts`
+ * - isolated entry for the client upload engine: `import { ... } from 'lemon-model/upload/engine'`.
+ * - kept OUT of both the package root barrel and `lemon-model/upload`: a server consumer needs the
+ *   contract only, and must not pull the engine in with it.
+ * - shell adapters (XHR, RN bridge, Electron fs) are NOT here — they belong to the consuming app.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+__exportStar(require("./progress"), exports);
+__exportStar(require("./engine"), exports);
+__exportStar(require("./executors"), exports);
+//# sourceMappingURL=index.js.map

package/dist/upload/engine/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/upload/engine/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;;GAQG;AACH,6CAA2B;AAC3B,2CAAyB;AACzB,8CAA4B"}

package/dist/upload/engine/progress.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `upload/engine/progress.ts`
+ * - progress is a CLIENT-LOCAL signal: nothing here travels on the wire and no server ever sees it.
+ *   the server's knowledge of progress differs per transfer kind (a presigned PUT it cannot see at all),
+ *   so the contract deliberately carries none of it.
+ * - per-file percent + one batch percent. everything is measured in bytes of the ORIGINAL
+ *   content, never in wire bytes, so the bar means the same thing whichever executor runs.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+/** bytes of the ORIGINAL send sent so far for one file. called 0..n times; never after run() settles */
+export declare type UploadProgressSink = (sent: number) => void;
+/** what an HTTP primitive can observe: request-body bytes (`XMLHttpRequest.upload.onprogress`). fetch never calls it */
+export declare type UploadWireProgress = (loaded: number, total: number) => void;
+/** scale request-body progress (base64 JSON or raw bytes) to original-send bytes */
+export declare const asContentBytes: (loaded: number, total: number, contentSize: number) => number;
+/** progress of one file in the batch; `index` matches the `sources` array (exists before any server id does) */
+export interface UploadFileProgress {
+    index: number;
+    /** original send bytes — known before `start` */
+    total: number;
+    /** bytes reported by the executor; undefined until the first report = indeterminate */
+    sent?: number;
+    /** the slot is done for the bar's purpose: stored, failed, rejected at start, or dedup */
+    settled: boolean;
+}
+export interface UploadBatchProgress {
+    files: ReadonlyArray<UploadFileProgress>;
+    /** sum of `total` — fixed for the whole batch so the bar never moves backwards */
+    totalBytes: number;
+    /** sum of (settled ? total : sent ?? 0) */
+    sentBytes: number;
+    /** sentBytes / totalBytes in [0, 1]; when totalBytes is 0, settled files / all files */
+    ratio: number;
+}
+export declare type UploadBatchProgressSink = (progress: UploadBatchProgress) => void;
+/** byte-weighted aggregation; one immutable snapshot per change so a UI store can replace state as-is */
+export declare class UploadProgressTracker {
+    private readonly emit?;
+    private files;
+    private readonly totalBytes;
+    constructor(totals: ReadonlyArray<number>, emit?: UploadBatchProgressSink);
+    /** the per-file sink handed to an executor: clamps to [previous, total], ignores reports after settle */
+    sink(index: number): UploadProgressSink;
+    settle(index: number): void;
+    snapshot(): UploadBatchProgress;
+    publish(): void;
+}

package/dist/upload/engine/progress.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * `upload/engine/progress.ts`
+ * - progress is a CLIENT-LOCAL signal: nothing here travels on the wire and no server ever sees it.
+ *   the server's knowledge of progress differs per transfer kind (a presigned PUT it cannot see at all),
+ *   so the contract deliberately carries none of it.
+ * - per-file percent + one batch percent. everything is measured in bytes of the ORIGINAL
+ *   content, never in wire bytes, so the bar means the same thing whichever executor runs.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UploadProgressTracker = exports.asContentBytes = void 0;
+/** scale request-body progress (base64 JSON or raw bytes) to original-send bytes */
+const asContentBytes = (loaded, total, contentSize) => total > 0 ? Math.min(contentSize, Math.round((loaded / total) * contentSize)) : 0;
+exports.asContentBytes = asContentBytes;
+/** byte-weighted aggregation; one immutable snapshot per change so a UI store can replace state as-is */
+class UploadProgressTracker {
+    constructor(totals, emit) {
+        this.emit = emit;
+        this.files = totals.map((total, index) => ({ index, total: Math.max(0, total), settled: false }));
+        this.totalBytes = this.files.reduce((sum, file) => sum + file.total, 0);
+    }
+    /** the per-file sink handed to an executor: clamps to [previous, total], ignores reports after settle */
+    sink(index) {
+        return sent => {
+            var _a;
+            const file = this.files[index];
+            if (!file || file.settled)
+                return;
+            const next = Math.min(file.total, Math.max(sent, (_a = file.sent) !== null && _a !== void 0 ? _a : 0));
+            if (next === file.sent)
+                return;
+            this.files = this.files.map(item => (item.index === index ? Object.assign(Object.assign({}, item), { sent: next }) : item));
+            this.publish();
+        };
+    }
+    settle(index) {
+        const file = this.files[index];
+        if (!file || file.settled)
+            return;
+        this.files = this.files.map(item => (item.index === index ? Object.assign(Object.assign({}, item), { settled: true }) : item));
+        this.publish();
+    }
+    snapshot() {
+        const sentBytes = this.files.reduce((sum, file) => { var _a; return sum + (file.settled ? file.total : (_a = file.sent) !== null && _a !== void 0 ? _a : 0); }, 0);
+        const settled = this.files.filter(file => file.settled).length;
+        const ratio = this.totalBytes > 0 ? sentBytes / this.totalBytes : this.files.length > 0 ? settled / this.files.length : 1;
+        return { files: this.files, totalBytes: this.totalBytes, sentBytes, ratio };
+    }
+    publish() {
+        if (this.emit)
+            this.emit(this.snapshot());
+    }
+}
+exports.UploadProgressTracker = UploadProgressTracker;
+//# sourceMappingURL=progress.js.map

package/dist/upload/engine/progress.js.map

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

package/dist/upload/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `upload/index.ts`
+ * - isolated entry for the upload contract: `import { ... } from 'lemon-model/upload'`.
+ * - kept OUT of the package root barrel: a consumer that only needs this contract must not pull
+ *   the socket/genai runtime, and a subpath can be promoted to the root later without a breaking
+ *   change (the reverse is not true).
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+export * from './types';

package/dist/upload/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `upload/index.ts`
+ * - isolated entry for the upload contract: `import { ... } from 'lemon-model/upload'`.
+ * - kept OUT of the package root barrel: a consumer that only needs this contract must not pull
+ *   the socket/genai runtime, and a subpath can be promoted to the root later without a breaking
+ *   change (the reverse is not true).
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+__exportStar(require("./types"), exports);
+//# sourceMappingURL=index.js.map

package/dist/upload/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/upload/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;;GAQG;AACH,0CAAwB"}

package/dist/upload/testing.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `upload/testing.ts`
+ * - shared fixtures so a server spec and a client spec assert against the same payloads.
+ * - kept OUT of the root barrel like the other `<module>/testing` entries: `lemon-model/upload/testing`.
+ * - fixtures never carry a real signature or a real host.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import type { Upload, UploadTicket } from './types';
+/** a settled image as the server returns it after `complete`, with the preview the client sent */
+export declare const SAMPLE_UPLOAD_STORED: Upload;
+/** start slot: inline ticket */
+export declare const SAMPLE_UPLOAD_TICKET_INLINE: UploadTicket;
+/** start slot: presigned PUT ticket */
+export declare const SAMPLE_UPLOAD_TICKET_PRESIGNED: UploadTicket;
+/**
+ * start slot for an upload that is already `stored` and is only taking a thumbnail.
+ * - `transfer` absent + `thumbnailTransfer` present: the original's bytes are immutable.
+ * - an engine that returns early on a missing `transfer` silently drops the preview.
+ */
+export declare const SAMPLE_UPLOAD_TICKET_THUMBNAIL_ONLY: UploadTicket;
+/** start slot rejected at validation: no id, nothing to transfer or complete */
+export declare const SAMPLE_UPLOAD_REJECTED: UploadTicket;

package/dist/upload/testing.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SAMPLE_UPLOAD_REJECTED = exports.SAMPLE_UPLOAD_TICKET_THUMBNAIL_ONLY = exports.SAMPLE_UPLOAD_TICKET_PRESIGNED = exports.SAMPLE_UPLOAD_TICKET_INLINE = exports.SAMPLE_UPLOAD_STORED = void 0;
+const types_1 = require("./types");
+/** a settled image as the server returns it after `complete`, with the preview the client sent */
+exports.SAMPLE_UPLOAD_STORED = {
+    id: 'up-001',
+    status: types_1.UPLOAD_STATUS.stored,
+    stereo: types_1.UPLOAD_STEREO.image,
+    name: 'photo.png',
+    contentType: 'image/png',
+    contentSize: 123456,
+    url: 'https://cdn.example.com/up-001.png',
+    width: 1024,
+    height: 768,
+    thumbnail: { url: 'https://cdn.example.com/up-001-thumb.jpg', contentType: 'image/jpeg' },
+};
+/** start slot: inline ticket */
+exports.SAMPLE_UPLOAD_TICKET_INLINE = {
+    upload: {
+        id: 'up-002',
+        status: types_1.UPLOAD_STATUS.pending,
+        stereo: types_1.UPLOAD_STEREO.image,
+        name: 'photo.png',
+        contentType: 'image/png',
+        contentSize: 123456,
+    },
+    transfer: { kind: types_1.UPLOAD_TRANSFER_KIND.inline, maxBytes: 4000000 },
+};
+/** start slot: presigned PUT ticket */
+exports.SAMPLE_UPLOAD_TICKET_PRESIGNED = {
+    upload: {
+        id: 'up-003',
+        status: types_1.UPLOAD_STATUS.pending,
+        stereo: types_1.UPLOAD_STEREO.image,
+        name: 'photo.png',
+        contentType: 'image/png',
+        contentSize: 123456,
+    },
+    transfer: {
+        kind: types_1.UPLOAD_TRANSFER_KIND.presignedPut,
+        method: 'PUT',
+        url: 'https://storage.example.com/up-003?X-Amz-Signature=masked',
+        headers: { 'content-type': 'image/png', 'content-length': '123456' },
+        maxBytes: 50000000,
+        expiresAt: 1757895300000,
+    },
+};
+/**
+ * start slot for an upload that is already `stored` and is only taking a thumbnail.
+ * - `transfer` absent + `thumbnailTransfer` present: the original's bytes are immutable.
+ * - an engine that returns early on a missing `transfer` silently drops the preview.
+ */
+exports.SAMPLE_UPLOAD_TICKET_THUMBNAIL_ONLY = {
+    upload: {
+        id: 'up-001',
+        status: types_1.UPLOAD_STATUS.stored,
+        stereo: types_1.UPLOAD_STEREO.image,
+        name: 'photo.png',
+        contentType: 'image/png',
+        contentSize: 123456,
+        url: 'https://cdn.example.com/up-001.png',
+    },
+    thumbnailTransfer: {
+        kind: types_1.UPLOAD_TRANSFER_KIND.presignedPut,
+        method: 'PUT',
+        url: 'https://storage.example.com/up-001-thumb?X-Amz-Signature=masked',
+        headers: { 'content-type': 'image/jpeg' },
+        maxBytes: 200000,
+        expiresAt: 1757895300000,
+    },
+};
+/** start slot rejected at validation: no id, nothing to transfer or complete */
+exports.SAMPLE_UPLOAD_REJECTED = {
+    upload: {
+        status: types_1.UPLOAD_STATUS.failed,
+        name: 'big.png',
+        contentType: 'image/png',
+        contentSize: 6291456,
+        error: '413 TOO LARGE - 6291456 > 4000000',
+    },
+};
+//# sourceMappingURL=testing.js.map