@ibanzajoe/uploader 0.3.0 → 1.2.1

package/dist/client-CUmYuQ7Z.d.cts

@@ -0,0 +1,154 @@
+/**
+ * SDK-level option and result types for UploaderClient.
+ *
+ * The upload-contract types below are VENDORED from @uploader/shared so that
+ * @ibanzajoe/uploader is self-contained for consumers outside this monorepo — one
+ * install, no @uploader/* or zod transitive deps. They mirror the API contract
+ * exactly; `contract.conformance.ts` asserts at typecheck time that they stay
+ * structurally identical to the shared definitions, failing the build on drift.
+ */
+/** A stored file result returned by the upload API and SDK. Mirrors Filestack's FileResult. */
+type FileResult = {
+    handle: string;
+    url: string;
+    filename: string;
+    mimetype: string;
+    size: number;
+    status: 'Stored';
+    uploadId?: string;
+};
+/** Response from the picker overlay / upload batch. */
+type PickerResponse = {
+    filesUploaded: FileResult[];
+    filesFailed: FileResult[];
+};
+/** JSON payload that is base64-encoded and HMAC-signed as a security policy. */
+type PolicySpec = {
+    /** Unix epoch seconds when the policy expires. */
+    expiry: number;
+    /** Allowed API calls, e.g. ["store", "read", "remove"]. */
+    call: string[];
+    /** Restrict to a specific file handle (read/remove). */
+    handle?: string;
+    /** Maximum file size in bytes (store). */
+    maxSize?: number;
+    /** Minimum file size in bytes (store). */
+    minSize?: number;
+    /** Restrict store destination path prefix. */
+    path?: string;
+};
+/** Options passed to UploaderClient constructor. */
+/**
+ * Per-file delivery-protection mode (docs/13). Chosen by the developer at upload:
+ *   public  — anyone with the link.
+ *   hotlink — only loads from an allowed origin (Origin/Referer allowlist).
+ *   signed  — requires a valid signed read URL (optionally origin-locked too).
+ * The chosen mode must be permitted by the account's plan or the server rejects
+ * the upload (403). Omitted → the file inherits the account's default mode.
+ */
+type DeliveryProtection = 'public' | 'hotlink' | 'signed';
+type UploaderClientOptions = {
+    /** Public API key (pk_...). */
+    apikey: string;
+    /** Base URL of the upload API. Defaults to the hosted endpoint. */
+    apiUrl?: string;
+    /** Optional signed security policy. */
+    security?: {
+        policy: string;
+        signature: string;
+    };
+    /**
+     * Direct-to-bucket upload control:
+     *   undefined (default) — auto-detect via GET /api/capabilities.
+     *   false — always use the proxied flow (skip direct upload + the probe).
+     * The server ultimately gates direct upload per account regardless.
+     */
+    directUpload?: boolean;
+    /**
+     * Client-level default delivery protection applied to every upload from this
+     * client (docs/13). Useful for a dedicated uploader configured for sensitive
+     * files. A per-upload `deliveryProtection` overrides it. Omitted → inherit the
+     * account default server-side.
+     */
+    deliveryProtection?: DeliveryProtection;
+    /**
+     * Client-level default per-file allowed origins (a domain lock layered on top
+     * of `signed`, or the allowlist for `hotlink`). Overridden per upload by
+     * `allowedOrigins`. Omitted → no per-file lock.
+     */
+    allowedOrigins?: string[];
+};
+/** Per-file upload options. */
+type UploadOptions = {
+    /** Progress callback, value 0–100. */
+    onProgress?: (percent: number) => void;
+    /** Storage path prefix. */
+    path?: string;
+    /** Override the file's stored name. */
+    filename?: string;
+    /** AbortSignal to cancel the upload. */
+    signal?: AbortSignal;
+    /**
+     * Chunk size in bytes for multipart uploads.
+     * Defaults to ~5 MB; files larger than this threshold use multipart.
+     */
+    chunkSize?: number;
+    /**
+     * Per-upload delivery protection (docs/13). Overrides the client-level default
+     * for this file. Must be permitted by the account's plan. Omitted → the client
+     * default, else the account default.
+     */
+    deliveryProtection?: DeliveryProtection;
+    /**
+     * Per-upload allowed origins for this file's domain lock. Overrides the
+     * client-level default. Omitted → the client default, else no per-file lock.
+     */
+    allowedOrigins?: string[];
+};
+/** Options for uploadAll — extends per-file options with concurrency control. */
+type UploadAllOptions = UploadOptions & {
+    /** Maximum concurrent uploads. Defaults to 3. */
+    concurrency?: number;
+};
+
+/**
+ * UploaderClient — headless upload client.
+ *
+ * Chooses single-shot (POST /api/store, multipart/form-data) vs multipart
+ * (start/part/complete) based on file size relative to MULTIPART_THRESHOLD
+ * (5 MB). Parts are retried individually with exponential backoff. Progress
+ * is emitted as a 0–100 integer. AbortSignal cancels in-flight work.
+ */
+
+declare class UploaderClient {
+    #private;
+    readonly apikey: string;
+    readonly apiUrl: string;
+    readonly security: UploaderClientOptions['security'];
+    constructor(options: UploaderClientOptions);
+    /**
+     * Upload a single file.
+     *
+     * Automatically selects single-shot vs multipart upload based on file size.
+     * Emits progress via `opts.onProgress` (0–100). Respects `opts.signal` for
+     * cancellation. Retries network errors and 5xx responses up to 3 times with
+     * exponential backoff; 4xx errors are surfaced immediately.
+     *
+     * @throws {UploaderError} with code ABORTED | NETWORK_ERROR | SERVER_ERROR |
+     *   CLIENT_ERROR | INVALID_RESPONSE
+     */
+    upload(file: File | Blob, opts?: UploadOptions): Promise<FileResult>;
+    /**
+     * Upload multiple files with concurrency limiting.
+     *
+     * Resolves once all uploads settle (fulfilled or rejected). The returned
+     * array preserves input order. `opts.concurrency` caps simultaneous
+     * in-flight uploads (default 3). Each file shares the same opts
+     * (including onProgress — the callback fires per-file, not aggregate).
+     *
+     * @returns Array of PromiseSettledResult in input order.
+     */
+    uploadAll(files: Array<File | Blob>, opts?: UploadAllOptions): Promise<PromiseSettledResult<FileResult>[]>;
+}
+
+export { type DeliveryProtection as D, type FileResult as F, type PickerResponse as P, type UploadAllOptions as U, type PolicySpec as a, type UploadOptions as b, UploaderClient as c, type UploaderClientOptions as d };

package/dist/client-CUmYuQ7Z.d.ts

@@ -0,0 +1,154 @@
+/**
+ * SDK-level option and result types for UploaderClient.
+ *
+ * The upload-contract types below are VENDORED from @uploader/shared so that
+ * @ibanzajoe/uploader is self-contained for consumers outside this monorepo — one
+ * install, no @uploader/* or zod transitive deps. They mirror the API contract
+ * exactly; `contract.conformance.ts` asserts at typecheck time that they stay
+ * structurally identical to the shared definitions, failing the build on drift.
+ */
+/** A stored file result returned by the upload API and SDK. Mirrors Filestack's FileResult. */
+type FileResult = {
+    handle: string;
+    url: string;
+    filename: string;
+    mimetype: string;
+    size: number;
+    status: 'Stored';
+    uploadId?: string;
+};
+/** Response from the picker overlay / upload batch. */
+type PickerResponse = {
+    filesUploaded: FileResult[];
+    filesFailed: FileResult[];
+};
+/** JSON payload that is base64-encoded and HMAC-signed as a security policy. */
+type PolicySpec = {
+    /** Unix epoch seconds when the policy expires. */
+    expiry: number;
+    /** Allowed API calls, e.g. ["store", "read", "remove"]. */
+    call: string[];
+    /** Restrict to a specific file handle (read/remove). */
+    handle?: string;
+    /** Maximum file size in bytes (store). */
+    maxSize?: number;
+    /** Minimum file size in bytes (store). */
+    minSize?: number;
+    /** Restrict store destination path prefix. */
+    path?: string;
+};
+/** Options passed to UploaderClient constructor. */
+/**
+ * Per-file delivery-protection mode (docs/13). Chosen by the developer at upload:
+ *   public  — anyone with the link.
+ *   hotlink — only loads from an allowed origin (Origin/Referer allowlist).
+ *   signed  — requires a valid signed read URL (optionally origin-locked too).
+ * The chosen mode must be permitted by the account's plan or the server rejects
+ * the upload (403). Omitted → the file inherits the account's default mode.
+ */
+type DeliveryProtection = 'public' | 'hotlink' | 'signed';
+type UploaderClientOptions = {
+    /** Public API key (pk_...). */
+    apikey: string;
+    /** Base URL of the upload API. Defaults to the hosted endpoint. */
+    apiUrl?: string;
+    /** Optional signed security policy. */
+    security?: {
+        policy: string;
+        signature: string;
+    };
+    /**
+     * Direct-to-bucket upload control:
+     *   undefined (default) — auto-detect via GET /api/capabilities.
+     *   false — always use the proxied flow (skip direct upload + the probe).
+     * The server ultimately gates direct upload per account regardless.
+     */
+    directUpload?: boolean;
+    /**
+     * Client-level default delivery protection applied to every upload from this
+     * client (docs/13). Useful for a dedicated uploader configured for sensitive
+     * files. A per-upload `deliveryProtection` overrides it. Omitted → inherit the
+     * account default server-side.
+     */
+    deliveryProtection?: DeliveryProtection;
+    /**
+     * Client-level default per-file allowed origins (a domain lock layered on top
+     * of `signed`, or the allowlist for `hotlink`). Overridden per upload by
+     * `allowedOrigins`. Omitted → no per-file lock.
+     */
+    allowedOrigins?: string[];
+};
+/** Per-file upload options. */
+type UploadOptions = {
+    /** Progress callback, value 0–100. */
+    onProgress?: (percent: number) => void;
+    /** Storage path prefix. */
+    path?: string;
+    /** Override the file's stored name. */
+    filename?: string;
+    /** AbortSignal to cancel the upload. */
+    signal?: AbortSignal;
+    /**
+     * Chunk size in bytes for multipart uploads.
+     * Defaults to ~5 MB; files larger than this threshold use multipart.
+     */
+    chunkSize?: number;
+    /**
+     * Per-upload delivery protection (docs/13). Overrides the client-level default
+     * for this file. Must be permitted by the account's plan. Omitted → the client
+     * default, else the account default.
+     */
+    deliveryProtection?: DeliveryProtection;
+    /**
+     * Per-upload allowed origins for this file's domain lock. Overrides the
+     * client-level default. Omitted → the client default, else no per-file lock.
+     */
+    allowedOrigins?: string[];
+};
+/** Options for uploadAll — extends per-file options with concurrency control. */
+type UploadAllOptions = UploadOptions & {
+    /** Maximum concurrent uploads. Defaults to 3. */
+    concurrency?: number;
+};
+
+/**
+ * UploaderClient — headless upload client.
+ *
+ * Chooses single-shot (POST /api/store, multipart/form-data) vs multipart
+ * (start/part/complete) based on file size relative to MULTIPART_THRESHOLD
+ * (5 MB). Parts are retried individually with exponential backoff. Progress
+ * is emitted as a 0–100 integer. AbortSignal cancels in-flight work.
+ */
+
+declare class UploaderClient {
+    #private;
+    readonly apikey: string;
+    readonly apiUrl: string;
+    readonly security: UploaderClientOptions['security'];
+    constructor(options: UploaderClientOptions);
+    /**
+     * Upload a single file.
+     *
+     * Automatically selects single-shot vs multipart upload based on file size.
+     * Emits progress via `opts.onProgress` (0–100). Respects `opts.signal` for
+     * cancellation. Retries network errors and 5xx responses up to 3 times with
+     * exponential backoff; 4xx errors are surfaced immediately.
+     *
+     * @throws {UploaderError} with code ABORTED | NETWORK_ERROR | SERVER_ERROR |
+     *   CLIENT_ERROR | INVALID_RESPONSE
+     */
+    upload(file: File | Blob, opts?: UploadOptions): Promise<FileResult>;
+    /**
+     * Upload multiple files with concurrency limiting.
+     *
+     * Resolves once all uploads settle (fulfilled or rejected). The returned
+     * array preserves input order. `opts.concurrency` caps simultaneous
+     * in-flight uploads (default 3). Each file shares the same opts
+     * (including onProgress — the callback fires per-file, not aggregate).
+     *
+     * @returns Array of PromiseSettledResult in input order.
+     */
+    uploadAll(files: Array<File | Blob>, opts?: UploadAllOptions): Promise<PromiseSettledResult<FileResult>[]>;
+}
+
+export { type DeliveryProtection as D, type FileResult as F, type PickerResponse as P, type UploadAllOptions as U, type PolicySpec as a, type UploadOptions as b, UploaderClient as c, type UploaderClientOptions as d };

package/dist/core.cjs

@@ -32,7 +32,8 @@ __export(core_exports, {
   quality: () => quality,
   resize: () => resize,
   rotate: () => rotate,
-  transformUrl: () => transformUrl
+  transformUrl: () => transformUrl,
+  withSignedPolicy: () => withSignedPolicy
 });
 module.exports = __toCommonJS(core_exports);
 
@@ -68,6 +69,8 @@ function planChunks(file, chunkSize = DEFAULT_CHUNK_SIZE) {
 // src/core/client.ts
 var MAX_RETRIES = 3;
 var RETRY_BASE_MS = 200;
+var MAX_DIRECT_PUT_BYTES = 5 * 1024 * 1024 * 1024;
+var SHA256_MAX_BYTES = 64 * 1024 * 1024;
 function sleep(ms, signal) {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) {
@@ -129,14 +132,153 @@ async function fetchWithRetry(url, init, signal, maxRetries = MAX_RETRIES) {
   }
   throw lastErr;
 }
+async function sha256Hex(blob) {
+  try {
+    const c = globalThis.crypto;
+    if (!c?.subtle || blob.size > SHA256_MAX_BYTES) return void 0;
+    const digest = await c.subtle.digest("SHA-256", await blob.arrayBuffer());
+    return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  } catch {
+    return void 0;
+  }
+}
+function xhrPut(url, body, opts) {
+  return new Promise((resolve, reject) => {
+    if (opts.signal?.aborted) {
+      reject(new UploaderError("ABORTED", "Upload aborted"));
+      return;
+    }
+    const xhr = new XMLHttpRequest();
+    xhr.open("PUT", url);
+    xhr.setRequestHeader("Content-Type", opts.contentType);
+    if (opts.onProgress) {
+      xhr.upload.onprogress = (e) => {
+        if (e.lengthComputable) {
+          opts.onProgress(Math.round(e.loaded / e.total * 95));
+        }
+      };
+    }
+    xhr.onload = () => {
+      if (xhr.status >= 200 && xhr.status < 300) {
+        resolve();
+      } else {
+        const code = xhr.status >= 400 && xhr.status < 500 ? "CLIENT_ERROR" : "SERVER_ERROR";
+        reject(new UploaderError(code, `Bucket PUT failed: HTTP ${xhr.status}`, xhr.status));
+      }
+    };
+    xhr.onerror = () => reject(new UploaderError("NETWORK_ERROR", "Bucket PUT network error"));
+    xhr.onabort = () => reject(new UploaderError("ABORTED", "Upload aborted"));
+    if (opts.signal) {
+      opts.signal.addEventListener("abort", () => xhr.abort(), { once: true });
+    }
+    xhr.send(body);
+  });
+}
 var UploaderClient = class {
   apikey;
   apiUrl;
   security;
+  #directUploadOption;
+  /** Client-level default per-file delivery protection (docs/13). */
+  #deliveryProtection;
+  /** Client-level default per-file allowed origins (docs/13). */
+  #allowedOrigins;
+  /** Memoized capability probe — one request per client, shared across uploads. */
+  #capsPromise = null;
   constructor(options) {
     this.apikey = options.apikey;
     this.apiUrl = (options.apiUrl ?? "https://api.uploaderhq.io").replace(/\/$/, "");
     this.security = options.security;
+    this.#directUploadOption = options.directUpload;
+    this.#deliveryProtection = options.deliveryProtection;
+    this.#allowedOrigins = options.allowedOrigins;
+  }
+  /**
+   * Resolve the effective per-file protection for one upload: a per-upload value
+   * overrides the client-level default (docs/13). Returns an object carrying ONLY
+   * the keys that are set, so callers spread it into the request body and unset
+   * fields are omitted entirely — an old server ignores them and the file inherits
+   * the account mode (`null`).
+   */
+  #resolveProtection(opts) {
+    const out = {};
+    const mode = opts.deliveryProtection ?? this.#deliveryProtection;
+    if (mode !== void 0) out.deliveryProtection = mode;
+    const origins = opts.allowedOrigins ?? this.#allowedOrigins;
+    if (origins !== void 0) out.allowedOrigins = origins;
+    return out;
+  }
+  // ─── Capability negotiation ─────────────────────────────────────────────────
+  /**
+   * Probe GET /api/capabilities once per client and cache the result. Fails OPEN
+   * to the proxied flow ({ directUpload: false }) on any error/timeout, so a
+   * flaky probe never blocks uploads and old servers (404) are handled.
+   */
+  #getCapabilities() {
+    if (this.#directUploadOption === false) {
+      return Promise.resolve({ directUpload: false });
+    }
+    if (!this.#capsPromise) {
+      this.#capsPromise = fetch(`${this.apiUrl}/api/capabilities`, {
+        headers: this.#authHeaders()
+      }).then(async (res) => {
+        if (!res.ok) return { directUpload: false };
+        const body = await res.json().catch(() => ({}));
+        return { directUpload: body["directUpload"] === true };
+      }).catch(() => ({ directUpload: false }));
+    }
+    return this.#capsPromise;
+  }
+  // ─── Direct-to-bucket upload ────────────────────────────────────────────────
+  /**
+   * Presign → PUT-to-bucket → confirm. Bytes go browser → bucket directly; our
+   * server only signs and records. Used when the account has the directUpload
+   * capability and the file fits a single PUT.
+   */
+  async #uploadDirect(file, opts) {
+    const { onProgress, filename, signal } = opts;
+    const name = filename ?? (file instanceof File ? file.name : "upload");
+    const contentType = file instanceof File && file.type ? file.type : "application/octet-stream";
+    onProgress?.(0);
+    checkAbort(signal);
+    const protection = this.#resolveProtection(opts);
+    const presign = async () => {
+      const res = await fetchWithRetry(
+        `${this.apiUrl}/api/uploads/presign`,
+        {
+          method: "POST",
+          headers: { ...this.#authHeaders(), "Content-Type": "application/json" },
+          body: JSON.stringify({ filename: name, contentType, size: file.size, ...protection })
+        },
+        signal
+      );
+      return await res.json();
+    };
+    let signed = await presign();
+    const checksum = await sha256Hex(file);
+    try {
+      await xhrPut(signed.putUrl, file, { contentType: signed.contentType, onProgress, signal });
+    } catch (err) {
+      if (err instanceof UploaderError && err.statusCode === 403) {
+        signed = await presign();
+        await xhrPut(signed.putUrl, file, { contentType: signed.contentType, onProgress, signal });
+      } else {
+        throw err;
+      }
+    }
+    checkAbort(signal);
+    const confirmRes = await fetchWithRetry(
+      `${this.apiUrl}/api/uploads/confirm`,
+      {
+        method: "POST",
+        headers: { ...this.#authHeaders(), "Content-Type": "application/json" },
+        body: JSON.stringify({ handle: signed.handle, checksum })
+      },
+      signal
+    );
+    const body = await confirmRes.json();
+    onProgress?.(100);
+    return this.#parseFileResult(body);
   }
   // ─── Auth headers ──────────────────────────────────────────────────────────
   /**
@@ -164,6 +306,9 @@ var UploaderClient = class {
     const form = new FormData();
     form.append("file", file, filename ?? (file instanceof File ? file.name : "upload"));
     if (filename) form.append("filename", filename);
+    const protection = this.#resolveProtection(opts);
+    if (protection.deliveryProtection) form.append("deliveryProtection", protection.deliveryProtection);
+    if (protection.allowedOrigins) form.append("allowedOrigins", JSON.stringify(protection.allowedOrigins));
     const res = await fetchWithRetry(
       `${this.apiUrl}/api/store`,
       {
@@ -187,12 +332,13 @@ var UploaderClient = class {
     const mime = file instanceof File ? file.type : "application/octet-stream";
     onProgress?.(0);
     checkAbort(signal);
+    const protection = this.#resolveProtection(opts);
     const startRes = await fetchWithRetry(
       `${this.apiUrl}/api/upload/start`,
       {
         method: "POST",
         headers: { ...this.#authHeaders(), "Content-Type": "application/json" },
-        body: JSON.stringify({ filename: name, mimetype: mime, size: file.size })
+        body: JSON.stringify({ filename: name, mimetype: mime, size: file.size, ...protection })
       },
       signal
     );
@@ -255,6 +401,10 @@ var UploaderClient = class {
    *   CLIENT_ERROR | INVALID_RESPONSE
    */
   async upload(file, opts = {}) {
+    const caps = await this.#getCapabilities();
+    if (caps.directUpload && file.size <= MAX_DIRECT_PUT_BYTES) {
+      return this.#uploadDirect(file, opts);
+    }
     const plan = planChunks(file, opts.chunkSize);
     if (plan.mode === "single") {
       return this.#uploadSingleShot(file, opts);
@@ -334,6 +484,10 @@ function transformUrl({ handle, ops, apiUrl = "" }) {
   const chain = ops.map(serializeOp).join("/");
   return chain ? `${base}/${chain}/${handle}` : `${base}/${handle}`;
 }
+function withSignedPolicy(url, security) {
+  const sep = url.includes("?") ? "&" : "?";
+  return `${url}${sep}policy=${encodeURIComponent(security.policy)}&signature=${encodeURIComponent(security.signature)}`;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_CHUNK_SIZE,
@@ -348,6 +502,7 @@ function transformUrl({ handle, ops, apiUrl = "" }) {
   quality,
   resize,
   rotate,
-  transformUrl
+  transformUrl,
+  withSignedPolicy
 });
 //# sourceMappingURL=core.cjs.map