yungle-client 0.2.1 → 0.3.1

package/README.md

@@ -18,11 +18,21 @@ const { transfers } = await yungle.listTransfers();
 const { downloads } = await yungle.transferDownloads(transfers[0].id);
 
 // Sending works on the free plan too; collections need a paid one.
+import { openAsBlob } from 'node:fs';
+
 const draft = await yungle.createTransfer({
   files: [{ name: 'final-cut.mov', size: 8_123_456_789 }],
+  // …or let Yungle fetch a file that is already online, any size:
+  imports: [{ url: 'https://my-bucket.s3.eu-central-1.amazonaws.com/render.mov?X-Amz-Signature=…' }],
 });
-// …stream the bytes to draft.tusEndpoint using draft.files[n].uploadToken…
+// Resumable, retried, and its two-hour token renewed for as long as it runs.
+await yungle.uploadFile(draft.tusEndpoint, draft.files[0], await openAsBlob('final-cut.mov'));
+await yungle.waitForImports(draft.imports!.map((i) => i.fileId));
 await yungle.finalizeTransfer(draft.transfer.id, { recipients: ['client@example.com'] });
+
+// Getting files out: your own, or a link someone sent you.
+const links = await yungle.resolveLink('https://yungle.co/t/k3v9…');
+for (const f of links.files) console.log(f.path, f.name, f.downloadUrl, f.crc32);
 ```
 
 Get a key from Settings → API keys. Every account can use the API: transfers and contacts on the free plan,
@@ -37,11 +47,13 @@ collections on a paid one. The first 10 GB of API uploads each month are free.
   lost response to `createTransfer` gets the first draft back instead of making a second.
 - **Pages are walked for you.** Lists take `{ limit, cursor }` and return `nextCursor`;
   `allTransfers()` and `allCollectionFiles(id)` are async iterators over everything.
-- **Does not upload bytes.** Endpoints that accept files return a tus endpoint
-  and per-file tokens; streaming to those is the caller's job. Keeping the byte
-  pipeline out is what lets this stay one small file. If you want that handled
-  for you, use [`yungle-cli`](https://www.npmjs.com/package/yungle-cli), which
-  does it resumably.
+- **Uploads any `Blob`, resumably.** `uploadFile` speaks tus with nothing but
+  `fetch`: it resumes from the server's last committed part after a drop, never
+  re-creates an upload in progress, and renews the two-hour upload token as it
+  goes. In Node, `fs.openAsBlob(path)` streams from disk.
+- **Imports and downloads.** `imports` on the create calls has Yungle fetch a file
+  from a URL; `transferDownloadLinks`, `collectionDownloadLinks` and `resolveLink`
+  return signed, `Range`-resumable URLs with a CRC-32 per file.
 - **Errors carry a stable `code`.** Branch on `err.code`, never on the message.
 
 ```ts

package/dist/index.d.ts

@@ -1,5 +1,9 @@
-import type { Collection, CollectionFile, CollectionSummary, Contact, ContactInput, DownloadEvent, FileInput, Folder, Guest, Me, RecipientStatus, Transfer, TransferFile, TransferSummary, UploadTargets, WebhookDelivery, WebhookEndpoint, WebhookEvent, WebhookEventType } from './types.js';
+import type { Collection, CollectionFile, CollectionSummary, Contact, ContactInput, DownloadEvent, DownloadLinks, ImportInput, ImportStatus, Submission, UploadRequest, UploadRequestInput, FileInput, Folder, Guest, Me, Referral, PulledWebhookEvent, RecipientStatus, Transfer, TransferFile, TransferSummary, UploadTargets, WebhookDelivery, WebhookEndpoint, WebhookEventType } from './types.js';
+import { type RenewOutcome as Renewal } from './upload-token.js';
+import { type UploadFileOptions } from './upload.js';
+export { chunkSize, uploadFile, UploadError, type UploadFileOptions } from './upload.js';
 export * from './types.js';
+export { createTokenKeeper, renewDelayMs, renewUploadToken, tokenExpiry, type RenewOutcome, type TokenKeeper, type TokenKeeperDeps, } from './upload-token.js';
 /**
  * A typed client for the Yungle API.
  *
@@ -8,16 +12,22 @@ export * from './types.js';
  * are both thin layers over this — which is the point: one place understands
  * the wire format, so neither can drift from the other.
  *
- * It does **not** upload bytes. `createTransfer` and `addCollectionFiles`
- * return a tus endpoint and per-file tokens, and streaming to those is the
- * caller's job (`yungle-cli` does it with `tus-js-client`). Keeping the byte
- * pipeline out of here is what lets this stay a few hundred lines with no
- * dependencies.
+ * `createTransfer` and `addCollectionFiles` return a tus endpoint and
+ * per-file tokens; `client.uploadFile` streams a `Blob` to one, resumably,
+ * renewing its two-hour token as it goes.
  */
 export interface YungleErrorBody {
     code: string;
     message: string;
     details?: Record<string, unknown>;
+    /** A link to the explanation of `code` and what to do about it. */
+    docs?: string;
+}
+export interface YungleApiErrorExtras {
+    /** `error.docs` from the body: where `code` is explained. */
+    docs?: string;
+    /** The `Retry-After` header, in seconds, when the server sent one. */
+    retryAfterHeader?: number;
 }
 /**
  * A failed request. Carries the machine-readable `code` — branch on that, never
@@ -27,10 +37,20 @@ export declare class YungleApiError extends Error {
     readonly status: number;
     readonly code: string;
     readonly details?: Record<string, unknown> | undefined;
-    constructor(status: number, code: string, message: string, details?: Record<string, unknown> | undefined);
+    /** Where `code` is explained, with what to do about it. Absent on older servers. */
+    readonly docs?: string;
+    private readonly retryAfterHeader?;
+    constructor(status: number, code: string, message: string, details?: Record<string, unknown> | undefined, extras?: YungleApiErrorExtras);
     /** Worth trying again: throttled, or our fault. */
     get retryable(): boolean;
-    /** Seconds to wait, when the server said. */
+    /**
+     * Seconds to wait, when the server said — in the body's
+     * `details.retryAfterSeconds` or, failing that, the `Retry-After` header.
+     *
+     * The header matters on its own: the monthly-allowance 429 states its wait
+     * (an hour) only there, and reading the body alone sent clients back in half
+     * a second to be refused again.
+     */
     get retryAfterSeconds(): number | null;
 }
 export interface ClientOptions {
@@ -64,7 +84,30 @@ export declare class YungleClient {
     private readonly maxRetries;
     private readonly userAgent;
     constructor(options: ClientOptions);
+    /** The site root this client talks to (`https://yungle.co`), for the few endpoints outside `/api/v1`. */
+    get origin(): string;
+    /**
+     * Trade a still-valid upload token for a fresh one (two more hours). Returns
+     * `'final'` when the token is dead or the upload finished, `'retry'` on a
+     * transient failure. `createTokenKeeper(token, { renew: (t) => client.renewUploadToken(t) })`
+     * schedules this for you.
+     */
+    renewUploadToken(token: string): Promise<Renewal>;
+    /**
+     * Upload one file to a target from `createTransfer` / `addTransferFiles` /
+     * `addCollectionFiles`: resumable, retried, and with its token renewed for
+     * as long as it runs. In Node, pass `await fs.openAsBlob(path)` as `source`.
+     */
+    uploadFile(tusEndpoint: string, target: {
+        id: string;
+        name: string;
+        uploadToken: string;
+    }, source: Blob, opts?: Omit<UploadFileOptions, 'endpoint' | 'target' | 'source' | 'renew' | 'fetch'>): Promise<{
+        uploadUrl: string;
+    }>;
     me(): Promise<Me>;
+    /** Your invite code and link, and the free months it has earned. */
+    getReferral(): Promise<Referral>;
     /**
      * One page of transfers, newest first — 100 by default, up to 500. Pass the
      * returned `nextCursor` back as `cursor` for the next page; it is null on the
@@ -79,10 +122,21 @@ export declare class YungleClient {
     /**
      * Create a draft. Nothing is live and nobody is emailed until `finalizeTransfer`.
      */
+    /**
+     * A draft transfer. `files` are uploaded by you (tus, to the returned
+     * targets); `imports` are fetched by Yungle from URLs. Send either or both.
+     */
     createTransfer(input: {
-        files: FileInput[];
+        files?: FileInput[];
+        imports?: ImportInput[];
         title?: string;
         expiresInDays?: number;
+        /**
+         * Encrypted by the client (`yungle-e2e`); the key travels only in the link's
+         * fragment. Such a transfer takes no title and cannot be emailed. File
+         * `size`s are then ciphertext lengths, and names go in `sealTransferFile`.
+         */
+        e2ee?: boolean;
     }): Promise<{
         transfer: {
             id: string;
@@ -107,11 +161,32 @@ export declare class YungleClient {
         message?: string;
         password?: string;
         title?: string;
+        /** End-to-end encrypted transfers only: the sealed `{ message }`. */
+        e2eeMeta?: string;
     }): Promise<{
         transfer: Transfer;
         notified: string[];
     }>;
-    addTransferFiles(id: string, files: FileInput[]): Promise<UploadTargets>;
+    /**
+     * End-to-end encrypted transfers only: a file's sealed `{ name, path, size,
+     * type }` and/or thumbnail, from `yungle-e2e`. Called after the file exists,
+     * because each blob binds the file's id.
+     */
+    sealTransferFile(id: string, fileId: string, sealed: {
+        meta?: string;
+        thumb?: string;
+    }): Promise<{
+        stored: true;
+    }>;
+    addTransferFiles(id: string, files: FileInput[], imports?: ImportInput[]): Promise<UploadTargets>;
+    /** Where a URL import stands: `importing` (with `receivedBytes`), `ready` or `failed`. */
+    getImport(fileId: string): Promise<ImportStatus>;
+    /**
+     * Poll `getImport` until every import is `ready` or `failed`, every
+     * `intervalMs` (default 5 s). Resolves with the final statuses; never throws
+     * for a failed import — check `status`.
+     */
+    waitForImports(fileIds: string[], intervalMs?: number): Promise<ImportStatus[]>;
     removeTransferFile(id: string, fileId: string): Promise<{
         deleted: boolean;
     }>;
@@ -125,6 +200,18 @@ export declare class YungleClient {
     revokeTransfer(id: string): Promise<{
         transfer: Transfer;
     }>;
+    /**
+     * Signed download URLs for your own transfer. Fetching them is not a
+     * recipient download — it never appears in receipts. Throws
+     * `e2ee_unsupported` for an end-to-end encrypted transfer.
+     */
+    transferDownloadLinks(id: string): Promise<DownloadLinks>;
+    /**
+     * A link someone shared with you (`…/t/…` or `…/c/…`), as signed download
+     * URLs — what a person opening it in a browser could download, under the same
+     * rules. Pass `password` for a protected link. Any key works, free included.
+     */
+    resolveLink(url: string, password?: string): Promise<DownloadLinks>;
     transferDownloads(id: string): Promise<{
         downloads: DownloadEvent[];
         recipients: RecipientStatus[];
@@ -139,6 +226,11 @@ export declare class YungleClient {
     }): Promise<{
         collection: Collection;
     }>;
+    /**
+     * Signed download URLs for your own collection: every file with its folder
+     * `path`, and a whole-collection ZIP. The URLs need no key and support `Range`.
+     */
+    collectionDownloadLinks(id: string): Promise<DownloadLinks>;
     getCollection(id: string): Promise<{
         collection: Collection;
     }>;
@@ -162,7 +254,7 @@ export declare class YungleClient {
     }>;
     /** Every file in a collection, oldest first, a page at a time. */
     allCollectionFiles(id: string, folderId?: string, pageSize?: number): AsyncGenerator<CollectionFile>;
-    addCollectionFiles(id: string, files: FileInput[], folderId?: string | null): Promise<UploadTargets>;
+    addCollectionFiles(id: string, files: FileInput[], folderId?: string | null, imports?: ImportInput[]): Promise<UploadTargets>;
     deleteCollectionFiles(id: string, fileIds: string[]): Promise<{
         deleted: number;
     }>;
@@ -227,12 +319,30 @@ export declare class YungleClient {
      * even when nothing is new, so keep the latest and poll with it.
      */
     listWebhookEvents(id: string, page?: PageOptions): Promise<{
-        events: (WebhookEvent & {
-            deliveryId: string;
-        })[];
+        events: PulledWebhookEvent[];
         nextCursor: string | null;
         hasMore: boolean;
     }>;
+    /** Your upload links, newest first (up to 100). */
+    listRequests(): Promise<{
+        requests: UploadRequest[];
+    }>;
+    /**
+     * A public page where anyone with the link can upload into one of your
+     * collections. Subscribe to the `request.submitted` webhook to hear about
+     * each finished submission.
+     */
+    createRequest(input: UploadRequestInput): Promise<{
+        request: UploadRequest;
+    }>;
+    getRequest(id: string): Promise<{
+        request: UploadRequest;
+        submissions: Submission[];
+    }>;
+    /** `paused` stops uploads until set back to `active`; `closed` stops them for good. */
+    setRequestStatus(id: string, status: UploadRequest['status']): Promise<{
+        request: UploadRequest;
+    }>;
     listContacts(): Promise<{
         contacts: Contact[];
     }>;
@@ -258,6 +368,11 @@ export declare class YungleClient {
      */
     private request;
 }
+/**
+ * `Retry-After` is delay-seconds or an HTTP-date (RFC 9110 §10.2.3). Anything
+ * else — including a negative number or a date already past — is no statement.
+ */
+export declare function parseRetryAfter(value: string | null, now?: number): number | null;
 /**
  * Check a webhook's `Yungle-Signature` header against the RAW request body.
  *

package/dist/index.mjs

@@ -1,23 +1,215 @@
+// src/upload-token.ts
+var MIN_RENEW_DELAY_MS = 6e4;
+var RETRY_DELAY_MS = 6e4;
+function tokenExpiry(token) {
+  const dot = token.indexOf(".");
+  if (dot <= 0) return null;
+  try {
+    const b642 = token.slice(0, dot).replace(/-/g, "+").replace(/_/g, "/");
+    const json = atob(b642);
+    const exp = JSON.parse(json).exp;
+    return typeof exp === "number" ? exp : null;
+  } catch {
+    return null;
+  }
+}
+function renewDelayMs(expiresAt, now) {
+  return Math.max(MIN_RENEW_DELAY_MS, Math.floor((expiresAt - now) / 2));
+}
+function createTokenKeeper(initial, deps) {
+  const now = deps.now ?? (() => Date.now());
+  const setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = deps.clearTimer ?? ((h) => clearTimeout(h));
+  let token = initial;
+  let expiresAt = tokenExpiry(initial);
+  let stopped = false;
+  let handle = null;
+  const schedule = (ms) => {
+    if (stopped) return;
+    handle = setTimer(() => void attempt(), ms);
+  };
+  const attempt = async () => {
+    if (stopped) return;
+    let outcome;
+    try {
+      outcome = await deps.renew(token);
+    } catch {
+      outcome = "retry";
+    }
+    if (stopped) return;
+    if (outcome === "final") {
+      stopped = true;
+      return;
+    }
+    if (outcome === "retry") {
+      if (expiresAt !== null && now() >= expiresAt) {
+        stopped = true;
+        return;
+      }
+      schedule(RETRY_DELAY_MS);
+      return;
+    }
+    token = outcome.token;
+    expiresAt = outcome.expiresAt;
+    schedule(renewDelayMs(expiresAt, now()));
+  };
+  schedule(expiresAt === null ? 60 * 6e4 : renewDelayMs(expiresAt, now()));
+  return {
+    current: () => token,
+    stop: () => {
+      stopped = true;
+      if (handle !== null) clearTimer(handle);
+    }
+  };
+}
+async function renewUploadToken(origin, current, doFetch = globalThis.fetch.bind(globalThis)) {
+  const res = await doFetch(`${origin.replace(/\/+$/, "")}/api/uploads/token`, {
+    method: "POST",
+    headers: { "x-yungle-upload-token": current }
+  });
+  if (res.status === 401 || res.status === 404) return "final";
+  if (!res.ok) return "retry";
+  const body = await res.json();
+  return { token: body.uploadToken, expiresAt: Date.parse(body.expiresAt) };
+}
+
+// src/upload.ts
+var MiB = 1024 * 1024;
+function chunkSize(size) {
+  return Math.max(64 * MiB, (Math.floor(size / (9e3 * MiB)) + 2) * MiB);
+}
+var UploadError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "UploadError";
+  }
+  status;
+};
+function transient(status) {
+  return status === 0 || status === 408 || status === 409 || status === 423 || status === 429 || status >= 500;
+}
+var b64 = (s) => {
+  const bytes = new TextEncoder().encode(s);
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin);
+};
+async function uploadFile(o) {
+  const doFetch = o.fetch ?? globalThis.fetch.bind(globalThis);
+  const size = o.source.size;
+  const delays = o.retryDelaysMs ?? [0, 1e3, 3e3, 5e3, 1e4, 3e4];
+  const keeper = o.renew ? createTokenKeeper(o.target.uploadToken, {
+    renew: async (t) => {
+      const outcome = await o.renew(t);
+      if (typeof outcome === "object") o.onToken?.(outcome.token);
+      return outcome;
+    }
+  }) : null;
+  const auth = () => ({ "Tus-Resumable": "1.0.0", "x-yungle-upload-token": keeper?.current() ?? o.target.uploadToken });
+  const request = async (url, init) => {
+    let res;
+    try {
+      res = await doFetch(url, { ...init, signal: o.signal });
+    } catch (err) {
+      if (o.signal?.aborted) throw err;
+      throw new UploadError(`Connection failed: ${err.message}`, 0);
+    }
+    if (!res.ok) throw new UploadError(`Upload of ${o.target.name} got HTTP ${res.status}.`, res.status);
+    return res;
+  };
+  const head = async (url) => Number((await request(url, { method: "HEAD", headers: auth() })).headers.get("upload-offset") ?? 0);
+  try {
+    let url = o.uploadUrl;
+    let offset = 0;
+    if (url) {
+      try {
+        offset = await head(url);
+      } catch (err) {
+        if (!(err instanceof UploadError && err.status === 404)) throw err;
+        url = void 0;
+      }
+    }
+    if (!url) {
+      const created = await request(o.endpoint, {
+        method: "POST",
+        headers: {
+          ...auth(),
+          "Upload-Length": String(size),
+          "Upload-Metadata": `fileId ${b64(o.target.id)},token ${b64(o.target.uploadToken)},filename ${b64(o.target.name)}`
+        }
+      });
+      url = new URL(created.headers.get("location") ?? "", o.endpoint).toString();
+      o.onUploadUrl?.(url);
+    }
+    o.onProgress?.(offset, size);
+    const step = chunkSize(size);
+    let failures = 0;
+    let stalls = 0;
+    while (offset < size) {
+      try {
+        const res = await request(url, {
+          method: "PATCH",
+          headers: { ...auth(), "Upload-Offset": String(offset), "Content-Type": "application/offset+octet-stream" },
+          body: o.source.slice(offset, Math.min(size, offset + step))
+        });
+        const next = Number(res.headers.get("upload-offset"));
+        if (!(next > offset)) {
+          if (++stalls > 3) throw new UploadError(`Upload of ${o.target.name} made no progress.`, res.status);
+        } else stalls = 0;
+        offset = next;
+        failures = 0;
+        o.onProgress?.(offset, size);
+      } catch (err) {
+        if (o.signal?.aborted) throw err;
+        if (!(err instanceof UploadError) || !transient(err.status) || failures >= delays.length) throw err;
+        await new Promise((r) => setTimeout(r, delays[failures++]));
+        try {
+          offset = await head(url);
+        } catch (headErr) {
+          if (!(headErr instanceof UploadError) || !transient(headErr.status)) throw headErr;
+        }
+      }
+    }
+    return { uploadUrl: url };
+  } finally {
+    keeper?.stop();
+  }
+}
+
 // src/index.ts
 var YungleApiError = class extends Error {
-  constructor(status, code, message, details) {
+  constructor(status, code, message, details, extras = {}) {
     super(message);
     this.status = status;
     this.code = code;
     this.details = details;
     this.name = "YungleApiError";
+    if (extras.docs !== void 0) this.docs = extras.docs;
+    if (extras.retryAfterHeader !== void 0) this.retryAfterHeader = extras.retryAfterHeader;
   }
   status;
   code;
   details;
+  /** Where `code` is explained, with what to do about it. Absent on older servers. */
+  docs;
+  retryAfterHeader;
   /** Worth trying again: throttled, or our fault. */
   get retryable() {
     return this.status === 429 || this.status >= 500;
   }
-  /** Seconds to wait, when the server said. */
+  /**
+   * Seconds to wait, when the server said — in the body's
+   * `details.retryAfterSeconds` or, failing that, the `Retry-After` header.
+   *
+   * The header matters on its own: the monthly-allowance 429 states its wait
+   * (an hour) only there, and reading the body alone sent clients back in half
+   * a second to be refused again.
+   */
   get retryAfterSeconds() {
     const value = this.details?.retryAfterSeconds;
-    return typeof value === "number" ? value : null;
+    if (typeof value === "number") return value;
+    return this.retryAfterHeader ?? null;
   }
 };
 var DEFAULT_BASE = "https://yungle.co/api/v1";
@@ -28,7 +220,7 @@ function pageQuery(page, extra = {}) {
   const q = params.toString();
   return q ? `?${q}` : "";
 }
-var CLIENT_VERSION = true ? "0.2.1" : "dev";
+var CLIENT_VERSION = true ? "0.3.1" : "dev";
 var YungleClient = class {
   baseUrl;
   apiKey;
@@ -43,10 +235,35 @@ var YungleClient = class {
     this.maxRetries = options.maxRetries ?? 3;
     this.userAgent = options.userAgent ?? `yungle-client/${CLIENT_VERSION}`;
   }
+  /** The site root this client talks to (`https://yungle.co`), for the few endpoints outside `/api/v1`. */
+  get origin() {
+    return this.baseUrl.replace(/\/api\/v1$/, "");
+  }
+  /**
+   * Trade a still-valid upload token for a fresh one (two more hours). Returns
+   * `'final'` when the token is dead or the upload finished, `'retry'` on a
+   * transient failure. `createTokenKeeper(token, { renew: (t) => client.renewUploadToken(t) })`
+   * schedules this for you.
+   */
+  renewUploadToken(token) {
+    return renewUploadToken(this.origin, token, this.doFetch);
+  }
+  /**
+   * Upload one file to a target from `createTransfer` / `addTransferFiles` /
+   * `addCollectionFiles`: resumable, retried, and with its token renewed for
+   * as long as it runs. In Node, pass `await fs.openAsBlob(path)` as `source`.
+   */
+  uploadFile(tusEndpoint, target, source, opts = {}) {
+    return uploadFile({ ...opts, endpoint: tusEndpoint, target, source, renew: (t) => this.renewUploadToken(t), fetch: this.doFetch });
+  }
   // ── Account ───────────────────────────────────────────────────────────────
   me() {
     return this.request("GET", "/me");
   }
+  /** Your invite code and link, and the free months it has earned. */
+  getReferral() {
+    return this.request("GET", "/me/referral");
+  }
   // ── Transfers ─────────────────────────────────────────────────────────────
   /**
    * One page of transfers, newest first — 100 by default, up to 500. Pass the
@@ -68,6 +285,10 @@ var YungleClient = class {
   /**
    * Create a draft. Nothing is live and nobody is emailed until `finalizeTransfer`.
    */
+  /**
+   * A draft transfer. `files` are uploaded by you (tus, to the returned
+   * targets); `imports` are fetched by Yungle from URLs. Send either or both.
+   */
   createTransfer(input) {
     return this.request("POST", "/transfers", input);
   }
@@ -83,8 +304,32 @@ var YungleClient = class {
   finalizeTransfer(id, input = {}) {
     return this.request("POST", `/transfers/${enc(id)}/finalize`, input, { idempotent: true });
   }
-  addTransferFiles(id, files) {
-    return this.request("POST", `/transfers/${enc(id)}/files`, { files });
+  /**
+   * End-to-end encrypted transfers only: a file's sealed `{ name, path, size,
+   * type }` and/or thumbnail, from `yungle-e2e`. Called after the file exists,
+   * because each blob binds the file's id.
+   */
+  sealTransferFile(id, fileId, sealed) {
+    return this.request("POST", `/transfers/${enc(id)}/files/${enc(fileId)}/sealed`, sealed, { idempotent: true });
+  }
+  addTransferFiles(id, files, imports) {
+    return this.request("POST", `/transfers/${enc(id)}/files`, { files, ...imports?.length ? { imports } : {} });
+  }
+  /** Where a URL import stands: `importing` (with `receivedBytes`), `ready` or `failed`. */
+  getImport(fileId) {
+    return this.request("GET", `/imports/${enc(fileId)}`);
+  }
+  /**
+   * Poll `getImport` until every import is `ready` or `failed`, every
+   * `intervalMs` (default 5 s). Resolves with the final statuses; never throws
+   * for a failed import — check `status`.
+   */
+  async waitForImports(fileIds, intervalMs = 5e3) {
+    for (; ; ) {
+      const all = await Promise.all(fileIds.map((id) => this.getImport(id)));
+      if (all.every((s) => s.status !== "importing")) return all;
+      await sleep(intervalMs);
+    }
   }
   removeTransferFile(id, fileId) {
     return this.request("DELETE", `/transfers/${enc(id)}/files/${enc(fileId)}`);
@@ -96,6 +341,22 @@ var YungleClient = class {
   revokeTransfer(id) {
     return this.request("DELETE", `/transfers/${enc(id)}`);
   }
+  /**
+   * Signed download URLs for your own transfer. Fetching them is not a
+   * recipient download — it never appears in receipts. Throws
+   * `e2ee_unsupported` for an end-to-end encrypted transfer.
+   */
+  transferDownloadLinks(id) {
+    return this.request("GET", `/transfers/${enc(id)}/download-links`);
+  }
+  /**
+   * A link someone shared with you (`…/t/…` or `…/c/…`), as signed download
+   * URLs — what a person opening it in a browser could download, under the same
+   * rules. Pass `password` for a protected link. Any key works, free included.
+   */
+  resolveLink(url, password) {
+    return this.request("POST", "/links/resolve", { url, ...password ? { password } : {} });
+  }
   transferDownloads(id) {
     return this.request("GET", `/transfers/${enc(id)}/downloads`);
   }
@@ -106,6 +367,13 @@ var YungleClient = class {
   createCollection(input) {
     return this.request("POST", "/collections", input);
   }
+  /**
+   * Signed download URLs for your own collection: every file with its folder
+   * `path`, and a whole-collection ZIP. The URLs need no key and support `Range`.
+   */
+  collectionDownloadLinks(id) {
+    return this.request("GET", `/collections/${enc(id)}/download-links`);
+  }
   getCollection(id) {
     return this.request("GET", `/collections/${enc(id)}`);
   }
@@ -133,8 +401,8 @@ var YungleClient = class {
       cursor = page.nextCursor ?? void 0;
     } while (cursor);
   }
-  addCollectionFiles(id, files, folderId) {
-    return this.request("POST", `/collections/${enc(id)}/files`, { files, folderId });
+  addCollectionFiles(id, files, folderId, imports) {
+    return this.request("POST", `/collections/${enc(id)}/files`, { files, folderId, ...imports?.length ? { imports } : {} });
   }
   deleteCollectionFiles(id, fileIds) {
     return this.request("DELETE", `/collections/${enc(id)}/files`, { fileIds });
@@ -190,6 +458,26 @@ var YungleClient = class {
   listWebhookEvents(id, page = {}) {
     return this.request("GET", `/webhooks/${enc(id)}/events${pageQuery(page)}`);
   }
+  // ── Upload requests ───────────────────────────────────────────────────────
+  /** Your upload links, newest first (up to 100). */
+  listRequests() {
+    return this.request("GET", "/requests");
+  }
+  /**
+   * A public page where anyone with the link can upload into one of your
+   * collections. Subscribe to the `request.submitted` webhook to hear about
+   * each finished submission.
+   */
+  createRequest(input) {
+    return this.request("POST", "/requests", input);
+  }
+  getRequest(id) {
+    return this.request("GET", `/requests/${enc(id)}`);
+  }
+  /** `paused` stops uploads until set back to `active`; `closed` stops them for good. */
+  setRequestStatus(id, status) {
+    return this.request("PATCH", `/requests/${enc(id)}`, { status });
+  }
   // ── Contacts ──────────────────────────────────────────────────────────────
   listContacts() {
     return this.request("GET", "/contacts");
@@ -250,13 +538,27 @@ async function toError(res) {
   } catch {
   }
   const err = body?.error;
+  const retryAfterHeader = parseRetryAfter(res.headers.get("retry-after"));
   return new YungleApiError(
     res.status,
     err?.code ?? "http_error",
     err?.message ?? `Request failed with status ${res.status}.`,
-    err?.details
+    err?.details,
+    {
+      ...typeof err?.docs === "string" ? { docs: err.docs } : {},
+      ...retryAfterHeader === null ? {} : { retryAfterHeader }
+    }
   );
 }
+function parseRetryAfter(value, now = Date.now()) {
+  if (value === null) return null;
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) return Number(trimmed);
+  const at = Date.parse(trimmed);
+  if (Number.isNaN(at)) return null;
+  const seconds = Math.ceil((at - now) / 1e3);
+  return seconds >= 0 ? seconds : null;
+}
 function backoffMs(attempt, error) {
   const stated = error.retryAfterSeconds;
   if (stated !== null) return stated * 1e3;
@@ -285,7 +587,15 @@ async function verifyWebhook(rawBody, signatureHeader, secret, { toleranceSecond
 }
 export {
   CLIENT_VERSION,
+  UploadError,
   YungleApiError,
   YungleClient,
+  chunkSize,
+  createTokenKeeper,
+  parseRetryAfter,
+  renewDelayMs,
+  renewUploadToken,
+  tokenExpiry,
+  uploadFile,
   verifyWebhook
 };

package/dist/types.d.ts

@@ -40,6 +40,23 @@ export interface KeyInfo {
     /** Whether this credential may make Yungle email anyone. Absent on older servers. */
     canEmail?: boolean;
 }
+/** Your invite code and what it has earned (`GET /me/referral`). */
+export interface Referral {
+    /** Your invite code. A friend can type it in Settings › Plan. */
+    code: string;
+    /** Your invite link: the same code, as a page that signs them up. */
+    url: string;
+    /** Free months earned so far. */
+    earnedMonths: number;
+    /** Free months still available to earn. */
+    remainingMonths: number;
+    /** The most free months one person can earn, ever. */
+    cap: number;
+    /** True once `earnedMonths` reached `cap`. The link still gives friends their month. */
+    capped: boolean;
+    /** Friends in their free month, or inside the 14 days after their first payment. */
+    pending: number;
+}
 export interface Me {
     workspace: Workspace;
     plan: PlanInfo;
@@ -59,10 +76,50 @@ export interface UploadTarget {
     name: string;
     size: number;
     uploadToken: string;
+    /**
+     * When `uploadToken` stops working (two hours after issue). Renew before then
+     * with `renewUploadToken` — or let `createTokenKeeper` do it — for any upload
+     * that may run longer. Absent from servers older than 2026-09-29.
+     */
+    uploadTokenExpiresAt?: string;
 }
 export interface UploadTargets {
     tusEndpoint: string;
+    /** One per `files` entry, in order. */
     files: UploadTarget[];
+    /** One per `imports` entry, in order. Absent from servers before 2026-09-29. */
+    imports?: ImportStarted[];
+}
+/**
+ * A file for Yungle to fetch from a URL itself, so the bytes never pass
+ * through you — a presigned S3 link, a CDN, a release asset. The source must
+ * state the size (Content-Length or a Range answer).
+ */
+export interface ImportInput {
+    url: string;
+    /** Defaults to the name the source gives. */
+    name?: string;
+    /** Folder to place it in. */
+    path?: string;
+}
+export interface ImportStarted {
+    fileId: string;
+    name: string;
+    size: number;
+    /** The source's host; never the full URL. */
+    source: string;
+    status: 'queued';
+}
+/** Where one import stands (`getImport`). */
+export interface ImportStatus {
+    fileId: string;
+    name: string;
+    size: number;
+    /** Committed so far; moves in steps of one storage part. */
+    receivedBytes: number;
+    source: string | null;
+    status: 'importing' | 'ready' | 'failed';
+    error: string | null;
 }
 export interface Transfer {
     id: string;
@@ -74,12 +131,18 @@ export interface Transfer {
     fileCount?: number;
     recipients: string[];
     hasPassword: boolean;
+    /**
+     * End-to-end encrypted: the working link carries a key Yungle never holds,
+     * so `url` alone does not open it. Absent on servers before 2026-09-29.
+     */
+    e2ee?: boolean;
     downloadCount: number;
     maxDownloads: number | null;
     /** Null while it is still a draft. A draft is not shareable. */
     finalizedAt: Iso8601 | null;
-    expiresAt: Iso8601 | null;
-    createdAt: Iso8601 | null;
+    /** Every transfer expires; a paid plan chooses when. */
+    expiresAt: Iso8601;
+    createdAt: Iso8601;
 }
 export interface TransferSummary extends Omit<Transfer, 'hasPassword' | 'fileCount'> {
     fileCount: number;
@@ -93,6 +156,8 @@ export interface TransferFile {
     path: string | null;
     /** Null until the malware scan finishes, then `clean` or `infected`. */
     scanResult: string | null;
+    /** CRC-32 of the bytes (IEEE, as `zlib.crc32`), 8 hex digits; null while unknown. */
+    crc32: string | null;
     createdAt: Iso8601;
 }
 export interface RecipientStatus {
@@ -136,8 +201,8 @@ export interface Collection {
     sizeBytes: number;
     coverFileId: string | null;
     expiresAt: Iso8601 | null;
-    createdAt: Iso8601 | null;
-    updatedAt: Iso8601 | null;
+    createdAt: Iso8601;
+    updatedAt: Iso8601;
     fileCount?: number;
 }
 export interface CollectionSummary {
@@ -148,7 +213,7 @@ export interface CollectionSummary {
     fileCount: number;
     sizeBytes: number;
     coverFileId: string | null;
-    updatedAt: Iso8601 | null;
+    updatedAt: Iso8601;
 }
 export interface CollectionFile {
     id: string;
@@ -157,7 +222,9 @@ export interface CollectionFile {
     mimeType: string;
     folderId: string | null;
     hasThumbnail: boolean;
-    createdAt: Iso8601 | null;
+    /** CRC-32 of the bytes (IEEE, as `zlib.crc32`), 8 hex digits; null while unknown. */
+    crc32: string | null;
+    createdAt: Iso8601;
 }
 export interface Folder {
     id: string;
@@ -180,8 +247,8 @@ export interface Contact {
     email: string;
     phone: string | null;
     type: string;
-    createdAt: Iso8601 | null;
-    updatedAt: Iso8601 | null;
+    createdAt: Iso8601;
+    updatedAt: Iso8601;
 }
 export interface ContactInput {
     firstName?: string | null;
@@ -191,7 +258,7 @@ export interface ContactInput {
     phone?: string | null;
     type?: string | null;
 }
-export type WebhookEventType = 'transfer.ready' | 'transfer.downloaded' | 'transfer.expiring' | 'transfer.expired' | 'collection.file_uploaded';
+export type WebhookEventType = 'transfer.ready' | 'transfer.downloaded' | 'transfer.expiring' | 'transfer.expired' | 'collection.file_uploaded' | 'request.submitted';
 export interface WebhookEndpoint {
     id: string;
     /** Null for a pull endpoint. */
@@ -224,3 +291,79 @@ export interface WebhookEvent<T = Record<string, unknown>> {
     createdAt: Iso8601;
     data: T;
 }
+/** An event read from `/webhooks/{id}/events`: the push payload plus the cursor to resume from. */
+export type PulledWebhookEvent<T = Record<string, unknown>> = WebhookEvent<T> & {
+    /** Pass the last one back as `cursor`. */
+    deliveryId: string;
+};
+/** One file in a set of download links. */
+export interface DownloadLink {
+    id: string;
+    /** For an end-to-end encrypted transfer, a placeholder; the real name is sealed in `e2eeMeta`. */
+    name: string;
+    size: number;
+    mimeType: string;
+    /** Folder path, `""` at the root. Join it onto your output directory. */
+    path: string;
+    /** A signed GET that needs no key. Supports `Range`. Valid until `urlsExpireAt`. */
+    downloadUrl: string;
+    e2eeMeta?: string | null;
+    /** CRC-32 of the bytes (IEEE, as `zlib.crc32`), 8 hex digits. Null while unknown. */
+    crc32?: string | null;
+}
+/**
+ * Signed download URLs for a transfer or collection — your own
+ * (`transferDownloadLinks`, `collectionDownloadLinks`) or a link shared with
+ * you (`resolveLink`).
+ */
+export interface DownloadLinks {
+    kind: 'transfer' | 'collection';
+    /** A collection's title. Always null for a transfer, whose title recipients never see. */
+    title: string | null;
+    message: string | null;
+    expiresAt: Iso8601 | null;
+    /** End-to-end encrypted: the bytes are ciphertext and the key is in the link's `#` part. */
+    e2ee: boolean;
+    e2eeMeta?: string | null;
+    /** False while a transfer is still uploading: `files` is what has arrived so far. */
+    complete: boolean;
+    zipUrl: string | null;
+    /** When the URLs stop working; ask again for fresh ones. */
+    urlsExpireAt: Iso8601;
+    files: DownloadLink[];
+}
+/** A public upload link that feeds one of your collections ("file request" in the dashboard). */
+export interface UploadRequest {
+    id: string;
+    /** The page to give people. Anyone with it can upload until it is paused, closed or expires. */
+    url: string;
+    title: string;
+    message: string | null;
+    collectionId: string;
+    status: 'active' | 'paused' | 'closed';
+    hasPassword: boolean;
+    requiredItems: string[];
+    expiresAt: Iso8601 | null;
+    submissionCount: number;
+    receivedBytes: number;
+    createdAt: Iso8601;
+}
+export interface UploadRequestInput {
+    collectionId: string;
+    title: string;
+    message?: string;
+    password?: string;
+    /** A checklist shown on the page — guidance, not enforcement. */
+    requiredItems?: string[];
+    expiresAt?: Iso8601;
+}
+/** One person's upload through a request. Name, email and message are as they typed them: untrusted. */
+export interface Submission {
+    id: string;
+    uploaderName: string | null;
+    uploaderEmail: string | null;
+    message: string | null;
+    fileCount: number;
+    sizeBytes: number;
+    createdAt: Iso8601;
+}

package/dist/upload-token.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Keeps an upload token fresh for as long as an upload runs.
+ *
+ * Upload tokens live two hours and every tus request presents one, so an
+ * upload that outlasts its token — a big file on a home connection — dies at
+ * the first request after expiry: the next PATCH of a chunked client, or the
+ * HEAD a dropped connection resumes with. The keeper trades the token for a
+ * fresh one (`POST /api/uploads/token`) once half its remaining life is gone,
+ * which also tells the server the upload is alive (its quota stays reserved and
+ * recipients keep seeing "still arriving").
+ *
+ * Pure apart from the injected clock, timer and `renew`, so the schedule tests
+ * on the fast rung. The same rule lives in the web app's browser uploader
+ * (`apps/web/lib/upload-token-keeper.ts` in the Yungle repo) and the Python SDK.
+ */
+/** A renewal attempt: the new token, `'final'` (stop — the upload is over or the token dead), or `'retry'`. */
+export type RenewOutcome = {
+    token: string;
+    expiresAt: number;
+} | 'final' | 'retry';
+export interface TokenKeeperDeps {
+    renew: (current: string) => Promise<RenewOutcome>;
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+/** Never renew more often than this, however short the remaining life. */
+export declare const MIN_RENEW_DELAY_MS = 60000;
+/** After a failed attempt (offline, 5xx), try again this soon. */
+export declare const RETRY_DELAY_MS = 60000;
+/** `exp` (epoch ms) from a signed token's payload, or null if it has none. */
+export declare function tokenExpiry(token: string): number | null;
+/**
+ * How long to wait before renewing a token that expires at `expiresAt`: half
+ * the remaining life, floored at a minute. Half, not "five minutes before",
+ * because a laptop that sleeps through the renewal time wakes up with the
+ * other half still to spend on a retry.
+ */
+export declare function renewDelayMs(expiresAt: number, now: number): number;
+export interface TokenKeeper {
+    /** The token to send on the next request. */
+    current(): string;
+    /** Stop renewing (the upload finished, failed or was cancelled). */
+    stop(): void;
+}
+export declare function createTokenKeeper(initial: string, deps: TokenKeeperDeps): TokenKeeper;
+/**
+ * The HTTP half of a renewal: POST the current token to
+ * `<origin>/api/uploads/token`, read the fresh one. 401/404 are final (the
+ * token is dead, or the upload is over); anything else is worth a retry.
+ *
+ * `origin` is the site root (`https://yungle.co`), not the `/api/v1` base: the
+ * credential is the upload token, not an API key, so this lives outside v1.
+ */
+export declare function renewUploadToken(origin: string, current: string, doFetch?: typeof globalThis.fetch): Promise<RenewOutcome>;

package/dist/upload.d.ts

@@ -0,0 +1,35 @@
+import { type RenewOutcome } from './upload-token.js';
+/** At least one server part per PATCH, or the committed offset never advances. */
+export declare function chunkSize(size: number): number;
+export interface UploadFileOptions {
+    /** `tusEndpoint` from the create response. */
+    endpoint: string;
+    /** One entry of the create response's `files`. */
+    target: {
+        id: string;
+        name: string;
+        uploadToken: string;
+    };
+    /** The bytes. In Node: `await fs.openAsBlob(path)`. */
+    source: Blob;
+    /** Renew the two-hour token; without it an upload longer than that fails. */
+    renew?: (token: string) => Promise<RenewOutcome>;
+    /** Resume this upload rather than creating one. */
+    uploadUrl?: string;
+    /** Called once the upload exists — store it to resume after a crash. */
+    onUploadUrl?: (url: string) => void;
+    /** Called with each renewed token — store it with `uploadUrl`. */
+    onToken?: (token: string) => void;
+    onProgress?: (sent: number, total: number) => void;
+    signal?: AbortSignal;
+    fetch?: typeof globalThis.fetch;
+    /** Waits between retries of a failed request; its length is the retry budget. */
+    retryDelaysMs?: number[];
+}
+export declare class UploadError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare function uploadFile(o: UploadFileOptions): Promise<{
+    uploadUrl: string;
+}>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yungle-client",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": {