@ibanzajoe/uploader 1.2.1 → 1.3.0

package/README.md

@@ -37,22 +37,77 @@ function App() {
 }
 ```
 
-## Headless client (no React required)
+## Headless upload client (no React required)
+
+The `@ibanzajoe/uploader/core` entry is a framework-free client — use it in a Node
+script, a serverless function, a Vue/Svelte app, or behind your own UI. It has no
+React dependency.
 
 ```ts
 import { UploaderClient } from '@ibanzajoe/uploader/core'
 
 const client = new UploaderClient({
-  apikey: 'pk_your_api_key',
+  apikey: 'pk_your_api_key',            // required — your public key
   apiUrl: 'https://your-api.example.com',
 })
 
-const result = await client.upload(file, { filename: 'photo.jpg' })
-console.log(result.handle)   // e.g. "abc123def456"
-console.log(result.url)      // public delivery URL
+// Upload one file (a browser File/Blob, or a Node Blob/File):
+const result = await client.upload(file, {
+  filename: 'photo.jpg',
+  onProgress: (pct) => console.log(`${pct}%`),
+})
+
+console.log(result.handle)   // stable id, e.g. "abc123def456"
+console.log(result.url)      // delivery URL (cdn for public, edge for hotlink/signed)
+console.log(result.size, result.mimetype)
+```
+
+Upload **many** files with bounded concurrency:
+
+```ts
+const results = await client.uploadAll(files, { concurrency: 3 })
+```
+
+**`new UploaderClient(options)`**
+
+| Option | Type | Description |
+|---|---|---|
+| `apikey` | `string` | **Required.** Public key (`pk_…`). |
+| `apiUrl` | `string` | Base URL of the API. Omit for same-origin. |
+| `security` | `{ policy, signature }` | Signed policy applied to every request (see Delivery protection). |
+| `deliveryProtection` | `'public' \| 'hotlink' \| 'signed'` | Client-wide **default** protection for uploads (see below). |
+| `allowedOrigins` | `string[]` | Client-wide default per-file origin lock. |
+| `directUpload` | `boolean` | Leave unset to auto-detect direct-to-bucket; `false` forces the proxied flow. |
+
+**`client.upload(file, options?) → Promise<FileResult>`**
+
+| Upload option | Type | Description |
+|---|---|---|
+| `onProgress` | `(percent: number) => void` | `0`–`100`. Real byte progress on the direct + multipart paths. |
+| `filename` | `string` | Override the stored filename. |
+| `path` | `string` | Storage path prefix. |
+| `signal` | `AbortSignal` | Cancel the upload (throws `UploaderError` code `ABORTED`). |
+| `chunkSize` | `number` | Multipart chunk size in bytes (default ~5 MB). |
+| `deliveryProtection` | `'public' \| 'hotlink' \| 'signed'` | **Per-upload** protection for this file — overrides the client default. |
+| `allowedOrigins` | `string[]` | Per-upload origin lock for this file. |
+
+**`FileResult`**
+
+```ts
+type FileResult = {
+  handle: string      // stable public id — build delivery/transform URLs from it
+  url: string         // delivery URL for the original
+  filename: string
+  mimetype: string
+  size: number        // bytes
+  status: 'Stored'
+}
 ```
 
-Large files (≥ 6 MiB) are automatically uploaded via multipart; smaller files use a single PUT.
+Large files (≥ ~6 MiB) upload via multipart automatically; smaller files use a
+single PUT. When the account/plan allows it, bytes go **direct to storage** via a
+presigned URL (they never transit the API); otherwise the client transparently
+falls back to a proxied upload.
 
 ## Components
 
@@ -67,16 +122,93 @@ Full-screen modal picker with drag-and-drop, progress, and error UI.
 | `open` | `boolean` | Whether the modal is open. **Required.** |
 | `onClose` | `() => void` | Called when the modal should close (ESC, backdrop, cancel) |
 | `onUploadDone` | `(res: PickerResponse) => void` | Called when all uploads complete |
+| `deliveryProtection` | `'public' \| 'hotlink' \| 'signed'` | Protection for every file this picker uploads (see Delivery protection). Omit → account default. |
+| `allowedOrigins` | `string[]` | Per-file origin lock (see Delivery protection). Omit → account allowlist. |
 | `pickerOptions` | `PickerOptions` | File constraints + sources — `{ accept?: string[], maxFiles?, maxSize?, fromSources?, cameraFacingMode? }` |
 | `theme` | `UploaderTheme` | Per-instance design tokens (see Theming) |
 
+`<DropPane>` accepts the same `apikey` / `apiUrl` / `deliveryProtection` /
+`allowedOrigins` / callback props.
+
+> **Requires `@ibanzajoe/uploader` ≥ 1.3.0** for `deliveryProtection` /
+> `allowedOrigins` on the picker components. (Earlier versions only honored them
+> on the headless client.)
+
 ### `<DropPane>`
 
 Inline drop zone that can be embedded in a form.
 
 ### `usePicker(options)`
 
-Headless hook — returns `{ open, uploading, files, errors }`.
+Headless hook for building a fully custom picker UI. Takes the same options as the
+components (all `UploaderClientOptions` incl. `deliveryProtection`/`allowedOrigins`,
+plus `pickerOptions` and the `onUpload*` callbacks) and returns:
+
+```ts
+{ files, addFiles, removeFile, editFile, retryFile, upload, progress, isUploading, isDone }
+```
+
+## Delivery protection (public / hotlink / signed)
+
+Every file is served under one of three protection modes. **You choose the mode per
+upload** (or set a client-wide default); it must be one your account's plan allows.
+
+| Mode | Who can access | Delivery URL you get back |
+|---|---|---|
+| `public` | anyone with the link | `https://cdn.…/<key>` (CDN-cached, cheapest) |
+| `hotlink` | requests from your allowed domains (Origin/Referer allowlist) | `https://edge.…/file/<handle>` |
+| `signed` | only holders of a valid **signed URL** you mint server-side | `https://edge.…/file/<handle>` |
+
+Set it per upload (headless or picker), or as a client-wide default:
+
+```ts
+// headless — per upload wins over the client default
+await client.upload(logo,       { deliveryProtection: 'public' })
+await client.upload(productImg,  { deliveryProtection: 'hotlink' })
+await client.upload(idScan,      { deliveryProtection: 'signed' })
+
+// client-wide default
+const client = new UploaderClient({ apikey, apiUrl, deliveryProtection: 'signed' })
+```
+
+```tsx
+// React picker (≥ 1.3.0)
+<PickerOverlay apikey="pk_…" deliveryProtection="signed" open={open} onClose={close} />
+```
+
+Resolution order: **per-upload → client default → the account default** configured in
+the dashboard. If you request a mode your plan doesn't allow, the API responds `403
+DELIVERY_MODE_NOT_ALLOWED`.
+
+**`allowedOrigins`** (the domain list):
+- For `hotlink`: omit it and the file uses your **account allowlist** (set in the
+  dashboard settings). Pass a per-file `allowedOrigins` only to override it for that
+  file (it replaces, not merges).
+- For `signed`: the signature is the gate; a per-file `allowedOrigins` is an optional
+  extra domain lock layered on top.
+
+### Viewing a `signed` file
+
+A `signed` file's `url` is not directly loadable — each view needs a fresh signed URL,
+minted **server-side** with your API key secret. Use the one-call helper from the
+**server** entry (Node only — never ship the secret to the browser):
+
+```ts
+import { getSignedDeliveryUrl } from '@ibanzajoe/uploader/server'
+
+// in an authenticated backend route:
+const url = getSignedDeliveryUrl({
+  handle: file.handle,
+  secret: process.env.UPLOADER_API_SECRET,  // the API key's secret
+  baseUrl: 'https://edge.your-domain.com',   // origin of FileResult.url
+  expiresIn: 300,                            // seconds (default 300)
+  // ops: [resize({ w: 400 }), output({ format: 'webp' })],  // optional transform
+})
+// → https://edge.…/file/<handle>?policy=…&signature=…  (hand to <img src>)
+```
+
+Prefer to build it yourself? `withSignedPolicy(url, { policy, signature })` from
+`@ibanzajoe/uploader/core` appends a `policy`/`signature` pair you produced.
 
 ## Theming
 
@@ -178,11 +310,13 @@ const client = new UploaderClient({
 })
 ```
 
-For building **read** URLs of signed files, use `withSignedPolicy(url, { policy,
-signature })`. The `policy`/`signature` pair is always produced **server-side** by
-your backend (HMAC over the API key's secret) — the SDK never signs and never sees
-the secret. Compute it yourself, or use the dev helper
-`POST /api/admin/api-keys/:id/sign`. Full recipe + example:
+For building **read** URLs of signed files, prefer the one-call
+`getSignedDeliveryUrl()` from `@ibanzajoe/uploader/server` (see
+[Delivery protection → Viewing a signed file](#viewing-a-signed-file)). It signs and
+assembles the URL for you. If you'd rather bring your own `policy`/`signature`
+(produced **server-side** — HMAC over the API key's secret; the SDK never signs in
+the browser), append them with `withSignedPolicy(url, { policy, signature })`. Full
+recipe + example:
 [docs/14 §7.3](https://github.com/ibanzajoe/file-uploader/blob/main/docs/14-sdk-developer-guide.md#73-signed-urls-the-private-tier).
 
 ## Building

package/dist/index.cjs

@@ -506,11 +506,22 @@ function nextId() {
 function usePicker(opts) {
   const [files, setFiles] = (0, import_react.useState)([]);
   const clientRef = (0, import_react.useRef)(null);
-  if (!clientRef.current || clientRef.current.apikey !== opts.apikey || clientRef.current.apiUrl !== (opts.apiUrl ?? "https://api.uploaderhq.io")) {
+  const clientSigRef = (0, import_react.useRef)("");
+  const clientSig = JSON.stringify({
+    apikey: opts.apikey,
+    apiUrl: opts.apiUrl ?? null,
+    security: opts.security ?? null,
+    deliveryProtection: opts.deliveryProtection ?? null,
+    allowedOrigins: opts.allowedOrigins ?? null
+  });
+  if (!clientRef.current || clientSigRef.current !== clientSig) {
+    clientSigRef.current = clientSig;
     clientRef.current = new UploaderClient({
       apikey: opts.apikey,
       apiUrl: opts.apiUrl,
-      security: opts.security
+      security: opts.security,
+      deliveryProtection: opts.deliveryProtection,
+      allowedOrigins: opts.allowedOrigins
     });
   }
   const addFiles = (0, import_react.useCallback)(
@@ -1613,6 +1624,8 @@ function PickerOverlay({
   apikey,
   apiUrl,
   security,
+  deliveryProtection,
+  allowedOrigins,
   pickerOptions,
   onUploadDone,
   onFileUploadFinished,
@@ -1631,6 +1644,8 @@ function PickerOverlay({
     apikey,
     apiUrl,
     security,
+    deliveryProtection,
+    allowedOrigins,
     pickerOptions,
     onUploadDone,
     onFileUploadFinished,
@@ -1913,6 +1928,8 @@ function DropPane({
   apikey,
   apiUrl,
   security,
+  deliveryProtection,
+  allowedOrigins,
   pickerOptions,
   onUploadDone,
   onFileUploadFinished,
@@ -1930,6 +1947,8 @@ function DropPane({
     apikey,
     apiUrl,
     security,
+    deliveryProtection,
+    allowedOrigins,
     pickerOptions,
     onUploadDone,
     onFileUploadFinished,