@medialit/uploader 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @medialit/uploader
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Resumable browser uploads to [MediaLit](https://medialit.cloud), with no framework dependency. For React, use [`@medialit/react`](../react), which wraps this package.
+
+## Install
+
+```bash
+npm install @medialit/uploader
+```
+
+## Usage
+
+Your backend returns an upload signature (see `createSignatureHandler` in the [`medialit`](../medialit) SDK). The browser then uploads directly to MediaLit:
+
+```ts
+import { uploadFile, isUploadAbortedError } from "@medialit/uploader";
+
+const controller = new AbortController();
+
+try {
+    const media = await uploadFile(file, {
+        signatureEndpoint: "/api/medialit/signature",
+        access: "public",
+        signal: controller.signal,
+        onProgress: ({ percentage }) => console.log(`${percentage}%`),
+    });
+    console.log(media.mediaId, media.file);
+} catch (err) {
+    if (!isUploadAbortedError(err)) console.error(err.message);
+}
+```
+
+Call `controller.abort()` to cancel. An interrupted upload of the same file resumes where it stopped unless you pass `resume: false`.
+
+Uploads are temporary until your backend seals them with `medialit.seal(mediaId)`.
+
+## Options
+
+| Option              | Type                                                  | Description                                                  |
+| ------------------- | ----------------------------------------------------- | ------------------------------------------------------------ |
+| `signatureEndpoint` | `string`                                              | Your route that returns `{ signature, endpoint }` on `POST`. |
+| `getSignature`      | `() => Promise<{ signature, endpoint }>`              | Use instead of `signatureEndpoint` to fetch it yourself.     |
+| `access`            | `"public" \| "private"`                               | Defaults to `private`.                                       |
+| `caption`           | `string`                                              |                                                              |
+| `fileName`          | `string`                                              | Required for a `Blob` that is not a `File`.                  |
+| `chunkSize`         | `number`                                              | Bytes per request. Defaults to one request.                  |
+| `retryDelays`       | `number[]`                                            | Milliseconds before each retry.                              |
+| `resume`            | `boolean`                                             | Defaults to `true`.                                          |
+| `signal`            | `AbortSignal`                                         | Cancels the upload.                                          |
+| `onProgress`        | `({ bytesUploaded, bytesTotal, percentage }) => void` |                                                              |
+
+## Errors
+
+Failures reject with `MediaLitUploadError`. Its `message` is MediaLit's reason (for example a file over your plan's limit) and `status` is the HTTP status when there was one. Cancelling rejects with `UploadAbortedError`.

package/dist/index.cjs

@@ -0,0 +1,184 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MediaLitUploadError: () => MediaLitUploadError,
+  UploadAbortedError: () => UploadAbortedError,
+  isUploadAbortedError: () => isUploadAbortedError,
+  uploadFile: () => uploadFile
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/upload.ts
+var import_tus_js_client = require("tus-js-client");
+
+// src/errors.ts
+var MediaLitUploadError = class extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "MediaLitUploadError";
+    this.status = options.status;
+    this.cause = options.cause;
+  }
+};
+var UploadAbortedError = class extends Error {
+  constructor() {
+    super("Upload cancelled");
+    this.name = "UploadAbortedError";
+  }
+};
+function isUploadAbortedError(err) {
+  return err instanceof Error && err.name === "UploadAbortedError";
+}
+
+// src/signature.ts
+async function resolveSignature(options, signal) {
+  if (options.getSignature) {
+    return validate(await options.getSignature());
+  }
+  if (!options.signatureEndpoint) {
+    throw new MediaLitUploadError(
+      "Pass either signatureEndpoint or getSignature"
+    );
+  }
+  const response = await fetch(options.signatureEndpoint, {
+    method: "POST",
+    credentials: "same-origin",
+    signal
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new MediaLitUploadError(
+      body?.error || body?.message || `Signature request failed with status ${response.status}`,
+      { status: response.status }
+    );
+  }
+  return validate(body);
+}
+function validate(value) {
+  if (!value?.signature || !value?.endpoint) {
+    throw new MediaLitUploadError(
+      "The signature response must include signature and endpoint"
+    );
+  }
+  return { signature: value.signature, endpoint: value.endpoint };
+}
+
+// src/upload.ts
+var DEFAULT_RETRY_DELAYS = [0, 3e3, 5e3, 1e4];
+async function uploadFile(file, options) {
+  const { signal } = options;
+  if (signal?.aborted) throw new UploadAbortedError();
+  const { signature, endpoint } = await resolveSignature(
+    options,
+    signal
+  ).catch((err) => {
+    throw signal?.aborted ? new UploadAbortedError() : err;
+  });
+  if (signal?.aborted) throw new UploadAbortedError();
+  const blob = typeof Blob !== "undefined" && file instanceof Blob ? file : null;
+  const fileName = options.fileName || blob?.name;
+  if (!fileName) {
+    throw new MediaLitUploadError(
+      "Pass fileName when uploading a Blob or a stream"
+    );
+  }
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const settle = (finish) => {
+      if (settled) return;
+      settled = true;
+      signal?.removeEventListener("abort", onAbort);
+      finish();
+    };
+    const tusOptions = {
+      endpoint: `${endpoint.replace(/\/+$/, "")}/media/create/resumable`,
+      headers: { "x-medialit-signature": signature },
+      metadata: {
+        fileName,
+        mimeType: options.mimeType || blob?.type || "application/octet-stream",
+        access: options.access || "private",
+        caption: options.caption || ""
+      },
+      retryDelays: options.retryDelays || DEFAULT_RETRY_DELAYS,
+      removeFingerprintOnSuccess: true,
+      onProgress: (bytesUploaded, bytesTotal) => {
+        options.onProgress?.({
+          bytesUploaded,
+          bytesTotal,
+          percentage: bytesTotal ? bytesUploaded / bytesTotal * 100 : 0
+        });
+      },
+      onSuccess: ({ lastResponse }) => {
+        const media = parseMedia(lastResponse.getHeader("media"));
+        settle(
+          () => media ? resolve(media) : reject(
+            new MediaLitUploadError(
+              "The upload finished but MediaLit did not return the media"
+            )
+          )
+        );
+      },
+      onError: (err) => settle(() => reject(toUploadError(err)))
+    };
+    if (options.chunkSize) tusOptions.chunkSize = options.chunkSize;
+    const upload = new import_tus_js_client.Upload(file, tusOptions);
+    const onAbort = () => {
+      upload.abort().catch(() => void 0);
+      settle(() => reject(new UploadAbortedError()));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const start = async () => {
+      if (options.resume !== false) {
+        const previous = await upload.findPreviousUploads().catch(() => []);
+        if (previous.length) {
+          upload.resumeFromPreviousUpload(previous[0]);
+        }
+      }
+      if (!settled) upload.start();
+    };
+    start();
+  });
+}
+function parseMedia(header) {
+  if (!header) return null;
+  try {
+    const media = JSON.parse(header);
+    return media?.mediaId ? media : null;
+  } catch {
+    return null;
+  }
+}
+function toUploadError(err) {
+  const response = err.originalResponse;
+  const body = response?.getBody()?.trim();
+  return new MediaLitUploadError(body || err.message, {
+    status: response?.getStatus(),
+    cause: err
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MediaLitUploadError,
+  UploadAbortedError,
+  isUploadAbortedError,
+  uploadFile
+});

package/dist/index.d.cts

@@ -0,0 +1,83 @@
+type Access = "public" | "private";
+/**
+ * A `File` or `Blob` in the browser. In Node.js, a stream from
+ * `fs.createReadStream`, which can be resumed after a dropped connection.
+ */
+type UploadSource = Blob | {
+    readonly path: unknown;
+    pipe(destination: never): unknown;
+};
+/** The media object MediaLit returns once an upload finishes. */
+interface UploadedMedia {
+    mediaId: string;
+    originalFileName: string;
+    mimeType: string;
+    size: number;
+    access: Access;
+    /** Signed URL until the media is sealed and public. */
+    file: string;
+    /** Empty when MediaLit did not generate a thumbnail. */
+    thumbnail: string;
+    caption?: string;
+    group?: string;
+}
+/** What your backend returns after asking MediaLit for an upload signature. */
+interface UploadSignature {
+    signature: string;
+    /** MediaLit API URL that the browser can reach. */
+    endpoint: string;
+}
+interface UploadProgress {
+    bytesUploaded: number;
+    bytesTotal: number;
+    /** 0 to 100. */
+    percentage: number;
+}
+interface SignatureOptions {
+    /**
+     * Your backend route that returns `{ signature, endpoint }`. It is called
+     * with `POST` and the browser's cookies.
+     */
+    signatureEndpoint?: string;
+    /** Use instead of `signatureEndpoint` when you need to fetch it yourself. */
+    getSignature?: () => Promise<UploadSignature>;
+}
+interface UploadFileOptions extends SignatureOptions {
+    /** Defaults to `private`. */
+    access?: Access;
+    caption?: string;
+    /** Required for a `Blob` that is not a `File`, and for a Node.js stream. */
+    fileName?: string;
+    /** Defaults to the `Blob`'s type. */
+    mimeType?: string;
+    /** Bytes per request. Defaults to sending the file in one request. */
+    chunkSize?: number;
+    /** Milliseconds to wait before each retry. */
+    retryDelays?: number[];
+    /** Resume an interrupted upload of the same file. Defaults to `true`. */
+    resume?: boolean;
+    signal?: AbortSignal;
+    onProgress?: (progress: UploadProgress) => void;
+}
+
+/**
+ * Uploads a file to MediaLit with the tus resumable protocol. The upload stays
+ * temporary until your backend seals it with the MediaLit SDK.
+ */
+declare function uploadFile(file: UploadSource, options: UploadFileOptions): Promise<UploadedMedia>;
+
+declare class MediaLitUploadError extends Error {
+    /** HTTP status from MediaLit or your signature endpoint, when there was one. */
+    readonly status?: number;
+    readonly cause?: unknown;
+    constructor(message: string, options?: {
+        status?: number;
+        cause?: unknown;
+    });
+}
+declare class UploadAbortedError extends Error {
+    constructor();
+}
+declare function isUploadAbortedError(err: unknown): err is UploadAbortedError;
+
+export { type Access, MediaLitUploadError, type SignatureOptions, UploadAbortedError, type UploadFileOptions, type UploadProgress, type UploadSignature, type UploadSource, type UploadedMedia, isUploadAbortedError, uploadFile };

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+type Access = "public" | "private";
+/**
+ * A `File` or `Blob` in the browser. In Node.js, a stream from
+ * `fs.createReadStream`, which can be resumed after a dropped connection.
+ */
+type UploadSource = Blob | {
+    readonly path: unknown;
+    pipe(destination: never): unknown;
+};
+/** The media object MediaLit returns once an upload finishes. */
+interface UploadedMedia {
+    mediaId: string;
+    originalFileName: string;
+    mimeType: string;
+    size: number;
+    access: Access;
+    /** Signed URL until the media is sealed and public. */
+    file: string;
+    /** Empty when MediaLit did not generate a thumbnail. */
+    thumbnail: string;
+    caption?: string;
+    group?: string;
+}
+/** What your backend returns after asking MediaLit for an upload signature. */
+interface UploadSignature {
+    signature: string;
+    /** MediaLit API URL that the browser can reach. */
+    endpoint: string;
+}
+interface UploadProgress {
+    bytesUploaded: number;
+    bytesTotal: number;
+    /** 0 to 100. */
+    percentage: number;
+}
+interface SignatureOptions {
+    /**
+     * Your backend route that returns `{ signature, endpoint }`. It is called
+     * with `POST` and the browser's cookies.
+     */
+    signatureEndpoint?: string;
+    /** Use instead of `signatureEndpoint` when you need to fetch it yourself. */
+    getSignature?: () => Promise<UploadSignature>;
+}
+interface UploadFileOptions extends SignatureOptions {
+    /** Defaults to `private`. */
+    access?: Access;
+    caption?: string;
+    /** Required for a `Blob` that is not a `File`, and for a Node.js stream. */
+    fileName?: string;
+    /** Defaults to the `Blob`'s type. */
+    mimeType?: string;
+    /** Bytes per request. Defaults to sending the file in one request. */
+    chunkSize?: number;
+    /** Milliseconds to wait before each retry. */
+    retryDelays?: number[];
+    /** Resume an interrupted upload of the same file. Defaults to `true`. */
+    resume?: boolean;
+    signal?: AbortSignal;
+    onProgress?: (progress: UploadProgress) => void;
+}
+
+/**
+ * Uploads a file to MediaLit with the tus resumable protocol. The upload stays
+ * temporary until your backend seals it with the MediaLit SDK.
+ */
+declare function uploadFile(file: UploadSource, options: UploadFileOptions): Promise<UploadedMedia>;
+
+declare class MediaLitUploadError extends Error {
+    /** HTTP status from MediaLit or your signature endpoint, when there was one. */
+    readonly status?: number;
+    readonly cause?: unknown;
+    constructor(message: string, options?: {
+        status?: number;
+        cause?: unknown;
+    });
+}
+declare class UploadAbortedError extends Error {
+    constructor();
+}
+declare function isUploadAbortedError(err: unknown): err is UploadAbortedError;
+
+export { type Access, MediaLitUploadError, type SignatureOptions, UploadAbortedError, type UploadFileOptions, type UploadProgress, type UploadSignature, type UploadSource, type UploadedMedia, isUploadAbortedError, uploadFile };

package/dist/index.mjs

@@ -0,0 +1,154 @@
+// src/upload.ts
+import { Upload } from "tus-js-client";
+
+// src/errors.ts
+var MediaLitUploadError = class extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "MediaLitUploadError";
+    this.status = options.status;
+    this.cause = options.cause;
+  }
+};
+var UploadAbortedError = class extends Error {
+  constructor() {
+    super("Upload cancelled");
+    this.name = "UploadAbortedError";
+  }
+};
+function isUploadAbortedError(err) {
+  return err instanceof Error && err.name === "UploadAbortedError";
+}
+
+// src/signature.ts
+async function resolveSignature(options, signal) {
+  if (options.getSignature) {
+    return validate(await options.getSignature());
+  }
+  if (!options.signatureEndpoint) {
+    throw new MediaLitUploadError(
+      "Pass either signatureEndpoint or getSignature"
+    );
+  }
+  const response = await fetch(options.signatureEndpoint, {
+    method: "POST",
+    credentials: "same-origin",
+    signal
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new MediaLitUploadError(
+      body?.error || body?.message || `Signature request failed with status ${response.status}`,
+      { status: response.status }
+    );
+  }
+  return validate(body);
+}
+function validate(value) {
+  if (!value?.signature || !value?.endpoint) {
+    throw new MediaLitUploadError(
+      "The signature response must include signature and endpoint"
+    );
+  }
+  return { signature: value.signature, endpoint: value.endpoint };
+}
+
+// src/upload.ts
+var DEFAULT_RETRY_DELAYS = [0, 3e3, 5e3, 1e4];
+async function uploadFile(file, options) {
+  const { signal } = options;
+  if (signal?.aborted) throw new UploadAbortedError();
+  const { signature, endpoint } = await resolveSignature(
+    options,
+    signal
+  ).catch((err) => {
+    throw signal?.aborted ? new UploadAbortedError() : err;
+  });
+  if (signal?.aborted) throw new UploadAbortedError();
+  const blob = typeof Blob !== "undefined" && file instanceof Blob ? file : null;
+  const fileName = options.fileName || blob?.name;
+  if (!fileName) {
+    throw new MediaLitUploadError(
+      "Pass fileName when uploading a Blob or a stream"
+    );
+  }
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const settle = (finish) => {
+      if (settled) return;
+      settled = true;
+      signal?.removeEventListener("abort", onAbort);
+      finish();
+    };
+    const tusOptions = {
+      endpoint: `${endpoint.replace(/\/+$/, "")}/media/create/resumable`,
+      headers: { "x-medialit-signature": signature },
+      metadata: {
+        fileName,
+        mimeType: options.mimeType || blob?.type || "application/octet-stream",
+        access: options.access || "private",
+        caption: options.caption || ""
+      },
+      retryDelays: options.retryDelays || DEFAULT_RETRY_DELAYS,
+      removeFingerprintOnSuccess: true,
+      onProgress: (bytesUploaded, bytesTotal) => {
+        options.onProgress?.({
+          bytesUploaded,
+          bytesTotal,
+          percentage: bytesTotal ? bytesUploaded / bytesTotal * 100 : 0
+        });
+      },
+      onSuccess: ({ lastResponse }) => {
+        const media = parseMedia(lastResponse.getHeader("media"));
+        settle(
+          () => media ? resolve(media) : reject(
+            new MediaLitUploadError(
+              "The upload finished but MediaLit did not return the media"
+            )
+          )
+        );
+      },
+      onError: (err) => settle(() => reject(toUploadError(err)))
+    };
+    if (options.chunkSize) tusOptions.chunkSize = options.chunkSize;
+    const upload = new Upload(file, tusOptions);
+    const onAbort = () => {
+      upload.abort().catch(() => void 0);
+      settle(() => reject(new UploadAbortedError()));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const start = async () => {
+      if (options.resume !== false) {
+        const previous = await upload.findPreviousUploads().catch(() => []);
+        if (previous.length) {
+          upload.resumeFromPreviousUpload(previous[0]);
+        }
+      }
+      if (!settled) upload.start();
+    };
+    start();
+  });
+}
+function parseMedia(header) {
+  if (!header) return null;
+  try {
+    const media = JSON.parse(header);
+    return media?.mediaId ? media : null;
+  } catch {
+    return null;
+  }
+}
+function toUploadError(err) {
+  const response = err.originalResponse;
+  const body = response?.getBody()?.trim();
+  return new MediaLitUploadError(body || err.message, {
+    status: response?.getStatus(),
+    cause: err
+  });
+}
+export {
+  MediaLitUploadError,
+  UploadAbortedError,
+  isUploadAbortedError,
+  uploadFile
+};

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@medialit/uploader",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Resumable browser uploads to MediaLit",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "test": "node --import tsx --test '__tests__/**/*.test.ts'",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "medialit",
+    "upload",
+    "tus",
+    "resumable"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codelitdev/medialit"
+  },
+  "dependencies": {
+    "tus-js-client": "^4.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "bun@1.4.1"
+}