lemon-model 1.2.4 → 1.4.0

package/dist/upload/types.d.ts

@@ -0,0 +1,230 @@
+/**
+ * `upload/types.ts`
+ * - client <-> server contract for uploading files.
+ * - transport-neutral: the client always runs `start` -> transfer -> `complete`; whether the server
+ *   stores bytes inline (base64 in JSON) or hands out a presigned PUT only changes which
+ *   `UploadTransfer` variant it issues.
+ * - runtime-neutral like `socket/`: no Node, DOM, or AWS SDK types. Storage coordinates
+ *   (bucket, key, region) never appear here.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import type { Body, View } from '../cores/transformer';
+/** kind of stored content. same vocabulary as lemon-uploads-api `MediaStereo` minus its internal markers */
+export declare const UPLOAD_STEREO: {
+    readonly image: "image";
+    readonly video: "video";
+    readonly sound: "sound";
+    readonly docs: "docs";
+};
+export declare type UploadStereo = typeof UPLOAD_STEREO[keyof typeof UPLOAD_STEREO];
+/** lifecycle of one upload as the client sees it. `url` is meaningful only when `stored` */
+export declare const UPLOAD_STATUS: {
+    /** ticket issued; bytes not confirmed by the server yet */
+    readonly pending: "pending";
+    /** bytes durable and `url` valid */
+    readonly stored: "stored";
+    /** terminal; `error` carries "<status> <LABEL> - <detail>" */
+    readonly failed: "failed";
+};
+export declare type UploadStatus = typeof UPLOAD_STATUS[keyof typeof UPLOAD_STATUS];
+/** how bytes travel. the only axis that changes across the roadmap */
+export declare const UPLOAD_TRANSFER_KIND: {
+    /** base64 JSON to the API via the `send` operation (roadmap 1) */
+    readonly inline: "inline";
+    /** HTTP PUT straight to storage with a server-issued url + headers (roadmap 2) */
+    readonly presignedPut: "presigned-put";
+};
+export declare type UploadTransferKind = typeof UPLOAD_TRANSFER_KIND[keyof typeof UPLOAD_TRANSFER_KIND];
+/**
+ * snapshot other models embed as `upload$` / `upload$$` (see `UploadRef`, `UploadRefs`).
+ * - what a list screen needs to draw a tile or a file chip without a second fetch.
+ */
+export interface UploadHead {
+    id?: string;
+    stereo?: UploadStereo;
+    /** file name as the sender picked it */
+    name?: string;
+    /** MIME type */
+    contentType?: string;
+    /** size in bytes of the original content */
+    contentSize?: number;
+    /** stable url to serve; present iff status is `stored` */
+    url?: string;
+    /** thumbnail url; may arrive after `stored` (server post-processing) */
+    thumbnail?: string;
+    /** pixel size for image/video */
+    width?: number;
+    height?: number;
+}
+/** response layout of one upload */
+export interface UploadView extends View, UploadHead {
+    status: UploadStatus;
+    /** sha256 hex(64) of the content, when known to the server */
+    hash?: string;
+}
+/**
+ * request layout of one upload intent.
+ * - deviates from `XBody extends Body, Partial<XView>`: the three fields are required because
+ *   the server picks the transfer and validates limits from them before any byte moves.
+ * - inherited `id` set = re-issue the transfer of a still-`pending` upload (expired ticket).
+ */
+export interface UploadBody extends Body {
+    name: string;
+    contentType: string;
+    contentSize: number;
+    /** sha256 hex(64). optional forever: servers MUST accept uploads without it, MUST verify it when given */
+    hash?: string;
+}
+/** single reference pair. add both fields or neither */
+export interface UploadRef {
+    uploadId?: string;
+    upload$?: UploadHead;
+}
+/** array reference pair. add both fields or neither */
+export interface UploadRefs {
+    uploadIds?: string[];
+    upload$$?: UploadHead[];
+}
+/** transfer instruction (roadmap 1): send base64 through `UploadService.send()` */
+export interface UploadInlineTransfer {
+    kind: typeof UPLOAD_TRANSFER_KIND.inline;
+    /** max original bytes (before base64) this server accepts inline */
+    maxBytes: number;
+}
+/**
+ * transfer instruction (roadmap 2): PUT the raw bytes to `url` with `headers` verbatim.
+ * - `url` is a credential. never log, persist, or put it in an error message.
+ * - `expiresAt` is an upper bound only (signing credentials may expire earlier). on 403 re-`start` with `id`.
+ */
+export interface UploadPresignedPutTransfer {
+    kind: typeof UPLOAD_TRANSFER_KIND.presignedPut;
+    method: 'PUT';
+    url: string;
+    /**
+     * every header the signature covers; send them unchanged.
+     * - EXCEPT the ones the user agent owns: `content-length` and `host`. `fetch` and
+     *   `XMLHttpRequest` forbid setting them and the UA fills them from the request itself,
+     *   so a shell adapter must drop them from this map before sending. The signature still
+     *   matches because the UA's value is the one that was signed. `[실측]`
+     */
+    headers: Record<string, string>;
+    maxBytes: number;
+    /** epoch-ms */
+    expiresAt?: number;
+}
+export declare type UploadTransfer = UploadInlineTransfer | UploadPresignedPutTransfer;
+/**
+ * one slot of `start`'s answer.
+ * - `upload` is safe to store and log. `transfer` is consumed once by the executor and dropped.
+ * - no `transfer` = nothing to send: already `stored` (dedup) or `failed` at validation.
+ */
+export interface UploadTicket {
+    upload: UploadView;
+    transfer?: UploadTransfer;
+}
+export interface UploadStartBody {
+    list: UploadBody[];
+    /** transfer kinds this client can execute, preferred first. absent = `['inline']` */
+    transfers?: UploadTransferKind[];
+}
+/** same length and order as `UploadStartBody.list` */
+export interface UploadStartResult {
+    list: UploadTicket[];
+}
+/** body of the `send` operation (inline transfer only) */
+export interface UploadSendBody {
+    /** base64 of the whole content; size must match the declared `contentSize` */
+    content: string;
+}
+/** who produced a failure */
+export declare const UPLOAD_FAILURE_SOURCE: {
+    /** our API answered with an error */
+    readonly api: "api";
+    /** the storage endpoint (presigned PUT) answered with an error */
+    readonly storage: "storage";
+    /** the client gave up before or without a response */
+    readonly client: "client";
+};
+export declare type UploadFailureSource = typeof UPLOAD_FAILURE_SOURCE[keyof typeof UPLOAD_FAILURE_SOURCE];
+/** normalized failure codes; the app branches on these, never on raw HTTP status */
+export declare const UPLOAD_FAILURE_CODE: {
+    readonly invalid: "invalid";
+    readonly tooLarge: "too-large";
+    readonly unsupported: "unsupported";
+    readonly notAcceptable: "not-acceptable";
+    readonly notFound: "not-found";
+    readonly conflict: "conflict";
+    readonly expired: "expired";
+    readonly signature: "signature";
+    readonly checksum: "checksum";
+    readonly network: "network";
+    readonly aborted: "aborted";
+    readonly unknown: "unknown";
+};
+export declare type UploadFailureCode = typeof UPLOAD_FAILURE_CODE[keyof typeof UPLOAD_FAILURE_CODE];
+/** failure as the client reports it (to the app, and to the server in `complete`) */
+export interface UploadFailure {
+    source: UploadFailureSource;
+    code: UploadFailureCode;
+    /** HTTP status as observed, if any */
+    status?: number;
+    /** origin code: S3 `<Code>` or the lemon-core LABEL */
+    reason?: string;
+    /** human detail. MUST NOT contain a transfer url */
+    message?: string;
+}
+/** one slot of `complete`'s request */
+export interface UploadCompleteItem {
+    id: string;
+    /** set when the transfer did not succeed; the server marks the upload `failed` */
+    failure?: UploadFailure;
+}
+export interface UploadCompleteBody {
+    list: UploadCompleteItem[];
+}
+/** same length and order as `UploadCompleteBody.list` */
+export interface UploadCompleteResult {
+    list: UploadView[];
+}
+/**
+ * the four operations. the server controller and the client API adapter both implement this.
+ * - all four require the caller's normal API auth; a presigned url is the only unauthenticated hop.
+ */
+export interface UploadService {
+    /** declare intents; get tickets. validation failures come back per slot as `failed`, never as HTTP 4xx */
+    start(body: UploadStartBody): Promise<UploadStartResult>;
+    /** inline transfer: deliver the bytes of one pending upload */
+    send(id: string, body: UploadSendBody): Promise<UploadView>;
+    /** confirm; the server verifies what it cannot see (presigned) and settles `status`. idempotent */
+    complete(body: UploadCompleteBody): Promise<UploadCompleteResult>;
+    /** re-read (post-processing fields may arrive later) */
+    read(id: string): Promise<UploadView>;
+}
+/** HTTP binding relative to the server's upload base path (lemon-core `/{type}/{id}/{cmd}` shape) */
+export declare const UPLOAD_ROUTES: {
+    readonly start: {
+        readonly method: "POST";
+        readonly path: "/start";
+    };
+    readonly send: {
+        readonly method: "POST";
+        readonly path: "/{id}/send";
+    };
+    readonly complete: {
+        readonly method: "POST";
+        readonly path: "/complete";
+    };
+    readonly read: {
+        readonly method: "GET";
+        readonly path: "/{id}";
+    };
+};
+/** a view whose bytes are durable: `id` and `url` are guaranteed */
+export declare type UploadStoredView = UploadView & {
+    id: string;
+    url: string;
+};
+export declare const isUploadStored: (view: UploadView) => view is UploadStoredView;
+/** shared stereo derivation so an optimistic client tile and the server agree */
+export declare const uploadStereoOf: (contentType: string) => UploadStereo | undefined;

package/dist/upload/types.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadStereoOf = exports.isUploadStored = exports.UPLOAD_ROUTES = exports.UPLOAD_FAILURE_CODE = exports.UPLOAD_FAILURE_SOURCE = exports.UPLOAD_TRANSFER_KIND = exports.UPLOAD_STATUS = exports.UPLOAD_STEREO = void 0;
+/** kind of stored content. same vocabulary as lemon-uploads-api `MediaStereo` minus its internal markers */
+exports.UPLOAD_STEREO = {
+    image: 'image',
+    video: 'video',
+    sound: 'sound',
+    docs: 'docs',
+};
+/** lifecycle of one upload as the client sees it. `url` is meaningful only when `stored` */
+exports.UPLOAD_STATUS = {
+    /** ticket issued; bytes not confirmed by the server yet */
+    pending: 'pending',
+    /** bytes durable and `url` valid */
+    stored: 'stored',
+    /** terminal; `error` carries "<status> <LABEL> - <detail>" */
+    failed: 'failed',
+};
+/** how bytes travel. the only axis that changes across the roadmap */
+exports.UPLOAD_TRANSFER_KIND = {
+    /** base64 JSON to the API via the `send` operation (roadmap 1) */
+    inline: 'inline',
+    /** HTTP PUT straight to storage with a server-issued url + headers (roadmap 2) */
+    presignedPut: 'presigned-put',
+};
+/** who produced a failure */
+exports.UPLOAD_FAILURE_SOURCE = {
+    /** our API answered with an error */
+    api: 'api',
+    /** the storage endpoint (presigned PUT) answered with an error */
+    storage: 'storage',
+    /** the client gave up before or without a response */
+    client: 'client',
+};
+/** normalized failure codes; the app branches on these, never on raw HTTP status */
+exports.UPLOAD_FAILURE_CODE = {
+    invalid: 'invalid',
+    tooLarge: 'too-large',
+    unsupported: 'unsupported',
+    notAcceptable: 'not-acceptable',
+    notFound: 'not-found',
+    conflict: 'conflict',
+    expired: 'expired',
+    signature: 'signature',
+    checksum: 'checksum',
+    network: 'network',
+    aborted: 'aborted',
+    unknown: 'unknown',
+};
+/** HTTP binding relative to the server's upload base path (lemon-core `/{type}/{id}/{cmd}` shape) */
+exports.UPLOAD_ROUTES = {
+    start: { method: 'POST', path: '/start' },
+    send: { method: 'POST', path: '/{id}/send' },
+    complete: { method: 'POST', path: '/complete' },
+    read: { method: 'GET', path: '/{id}' },
+};
+const isUploadStored = (view) => view.status === exports.UPLOAD_STATUS.stored && typeof view.id === 'string' && typeof view.url === 'string';
+exports.isUploadStored = isUploadStored;
+/** shared stereo derivation so an optimistic client tile and the server agree */
+const uploadStereoOf = (contentType) => {
+    const type = contentType.toLowerCase().split(';')[0].trim();
+    if (type.startsWith('image/'))
+        return exports.UPLOAD_STEREO.image;
+    if (type.startsWith('video/'))
+        return exports.UPLOAD_STEREO.video;
+    if (type.startsWith('audio/'))
+        return exports.UPLOAD_STEREO.sound;
+    if (type === 'application/pdf')
+        return exports.UPLOAD_STEREO.docs;
+    return undefined;
+};
+exports.uploadStereoOf = uploadStereoOf;
+//# sourceMappingURL=types.js.map

package/dist/upload/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/upload/types.ts"],"names":[],"mappings":";;;AAaA,4GAA4G;AAC/F,QAAA,aAAa,GAAG;IACzB,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;CACN,CAAC;AAGX,4FAA4F;AAC/E,QAAA,aAAa,GAAG;IACzB,2DAA2D;IAC3D,OAAO,EAAE,SAAS;IAClB,oCAAoC;IACpC,MAAM,EAAE,QAAQ;IAChB,8DAA8D;IAC9D,MAAM,EAAE,QAAQ;CACV,CAAC;AAGX,sEAAsE;AACzD,QAAA,oBAAoB,GAAG;IAChC,kEAAkE;IAClE,MAAM,EAAE,QAAQ;IAChB,kFAAkF;IAClF,YAAY,EAAE,eAAe;CACvB,CAAC;AAoHX,6BAA6B;AAChB,QAAA,qBAAqB,GAAG;IACjC,qCAAqC;IACrC,GAAG,EAAE,KAAK;IACV,kEAAkE;IAClE,OAAO,EAAE,SAAS;IAClB,sDAAsD;IACtD,MAAM,EAAE,QAAQ;CACV,CAAC;AAGX,oFAAoF;AACvE,QAAA,mBAAmB,GAAG;IAC/B,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,WAAW;IACrB,WAAW,EAAE,aAAa;IAC1B,aAAa,EAAE,gBAAgB;IAC/B,QAAQ,EAAE,WAAW;IACrB,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,WAAW;IACtB,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;CACZ,CAAC;AA8CX,qGAAqG;AACxF,QAAA,aAAa,GAAG;IACzB,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE;IACzC,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE;IAC5C,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE;IAC/C,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE;CAChC,CAAC;AAKJ,MAAM,cAAc,GAAG,CAAC,IAAgB,EAA4B,EAAE,CACzE,IAAI,CAAC,MAAM,KAAK,qBAAa,CAAC,MAAM,IAAI,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,CAAC;AAD3F,QAAA,cAAc,kBAC6E;AAExG,iFAAiF;AAC1E,MAAM,cAAc,GAAG,CAAC,WAAmB,EAA4B,EAAE;IAC5E,MAAM,IAAI,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5D,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,qBAAa,CAAC,KAAK,CAAC;IAC1D,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,qBAAa,CAAC,KAAK,CAAC;IAC1D,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,qBAAa,CAAC,KAAK,CAAC;IAC1D,IAAI,IAAI,KAAK,iBAAiB;QAAE,OAAO,qBAAa,CAAC,IAAI,CAAC;IAC1D,OAAO,SAAS,CAAC;AACrB,CAAC,CAAC;AAPW,QAAA,cAAc,kBAOzB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lemon-model",
-  "version": "1.2.4",
+  "version": "1.4.0",
   "description": "Common shared model definitions for Lemon Micro-Service Platform",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",
@@ -42,8 +42,33 @@
       "require": "./dist/logtrace/testing.js",
       "default": "./dist/logtrace/testing.js"
     },
+    "./upload": {
+      "types": "./dist/upload/index.d.ts",
+      "import": "./dist/esm/upload/index.js",
+      "require": "./dist/upload/index.js",
+      "default": "./dist/upload/index.js"
+    },
+    "./upload/testing": {
+      "types": "./dist/upload/testing.d.ts",
+      "import": "./dist/esm/upload/testing.js",
+      "require": "./dist/upload/testing.js",
+      "default": "./dist/upload/testing.js"
+    },
+    "./upload/engine": {
+      "types": "./dist/upload/engine/index.d.ts",
+      "import": "./dist/esm/upload/engine/index.js",
+      "require": "./dist/upload/engine/index.js",
+      "default": "./dist/upload/engine/index.js"
+    },
     "./package.json": "./package.json"
   },
+  "typesVersions": {
+    "*": {
+      "upload": ["dist/upload/index.d.ts"],
+      "upload/testing": ["dist/upload/testing.d.ts"],
+      "upload/engine": ["dist/upload/engine/index.d.ts"]
+    }
+  },
   "scripts": {
     "build": "npm run build-ts && npm run build-esm",
     "build-ts": "tsc -v && tsc",