yungle-client 0.1.0 → 0.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Hein de Wilde
+Copyright (c) 2026 Brainpower
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -13,11 +13,11 @@ import { YungleClient } from 'yungle-client';
 
 const yungle = new YungleClient({ apiKey: process.env.YUNGLE_API_KEY! });
 
-// Reading is free on any account.
+// Everything here works on the free plan.
 const { transfers } = await yungle.listTransfers();
 const { downloads } = await yungle.transferDownloads(transfers[0].id);
 
-// Sending needs a paid plan.
+// Sending works on the free plan too; collections need a paid one.
 const draft = await yungle.createTransfer({
   files: [{ name: 'final-cut.mov', size: 8_123_456_789 }],
 });
@@ -25,16 +25,18 @@ const draft = await yungle.createTransfer({
 await yungle.finalizeTransfer(draft.transfer.id, { recipients: ['client@example.com'] });
 ```
 
-Get a key from Settings → API keys. Reads are free; creating, sending and
-uploading come with a paid plan.
+Get a key from Settings → API keys. Every account can use the API: transfers and contacts on the free plan,
+collections on a paid one. The first 10 GB of API uploads each month are free.
 
 ## What it does and doesn't do
 
 - **Dependency-free**, built on `fetch`, so it runs unchanged on Node 22+, Bun,
   Deno and edge runtimes.
-- **Retries what is safe to retry** — throttles always, and 5xx only on
-  idempotent operations. `createTransfer` is never retried automatically,
-  because repeating it would make a second draft.
+- **Retries are safe.** Throttles are always retried; 5xx and dropped connections are retried
+  for GET, DELETE and POST. Every POST carries an `Idempotency-Key`, reused on each retry, so a
+  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
@@ -46,14 +48,27 @@ uploading come with a paid plan.
 import { YungleApiError } from 'yungle-client';
 
 try {
-  await yungle.createTransfer({ files });
+  await yungle.createCollection({ title: 'Client deliveries' });
 } catch (err) {
   if (err instanceof YungleApiError && err.code === 'upgrade_required') {
-    // Reads are free; this is a write.
+    // A free account wrote to a collection; collections come with a plan.
   }
 }
 ```
 
+## Webhooks
+
+```ts
+import { verifyWebhook } from 'yungle-client';
+
+const { secret } = await yungle.createWebhook({ url: 'https://example.com/hooks/yungle', events: ['transfer.downloaded'] });
+// The secret is returned once. In your handler, with the RAW request body:
+if (!(await verifyWebhook(rawBody, req.headers['yungle-signature'], secret))) return res.status(400).end();
+```
+
+Signed with HMAC-SHA256 over a timestamp and the body; stale signatures (over 5 minutes) are
+refused. No public URL? Create the endpoint with `url: null` and poll `listWebhookEvents(id, { cursor })` instead.
+
 ## Not reachable
 
 Your vault and end-to-end encrypted transfers, because their keys are derived in
@@ -63,7 +78,7 @@ the client and never sent to Yungle. See
 ## Related
 
 - [`yungle-cli`](https://www.npmjs.com/package/yungle-cli) — resumable uploads from your terminal
-- [`yungle-mcp`](https://www.npmjs.com/package/yungle-mcp) — read your transfers from an AI assistant
-- [Full API reference](https://yungle.co/developers) · [OpenAPI spec](https://yungle.co/api/v1/openapi.json)
+- [`yungle-mcp`](https://www.npmjs.com/package/yungle-mcp) — connect Claude or Cursor to Yungle
+- [API reference](https://yungle.co/developers/reference?ref=npm) · [OpenAPI spec](https://yungle.co/api/v1/openapi.json)
 
 MIT

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import type { Collection, CollectionFile, CollectionSummary, Contact, ContactInput, DownloadEvent, FileInput, Folder, Guest, Me, RecipientStatus, Transfer, TransferFile, TransferSummary, UploadTargets } from './types';
-export * from './types';
+import type { Collection, CollectionFile, CollectionSummary, Contact, ContactInput, DownloadEvent, FileInput, Folder, Guest, Me, RecipientStatus, Transfer, TransferFile, TransferSummary, UploadTargets, WebhookDelivery, WebhookEndpoint, WebhookEvent, WebhookEventType } from './types.js';
+export * from './types.js';
 /**
  * A typed client for the Yungle API.
  *
@@ -44,17 +44,38 @@ export interface ClientOptions {
      * Only ever applied to requests that are safe to repeat — see `request()`.
      */
     maxRetries?: number;
+    /**
+     * Sent as `User-Agent`. The CLI and the MCP server set their own; anything
+     * else is reported as this package, so Yungle can tell integrations apart.
+     */
+    userAgent?: string;
 }
+export interface PageOptions {
+    /** Page size. The server's default applies when omitted. */
+    limit?: number;
+    /** The `nextCursor` from the previous page, unchanged. */
+    cursor?: string;
+}
+export declare const CLIENT_VERSION: string;
 export declare class YungleClient {
     private readonly baseUrl;
     private readonly apiKey;
     private readonly doFetch;
     private readonly maxRetries;
+    private readonly userAgent;
     constructor(options: ClientOptions);
     me(): Promise<Me>;
-    listTransfers(): Promise<{
+    /**
+     * 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
+     * last one. `allTransfers()` does the walking for you.
+     */
+    listTransfers(page?: PageOptions): Promise<{
         transfers: TransferSummary[];
+        nextCursor: string | null;
     }>;
+    /** Every transfer, newest first, fetched a page at a time as you iterate. */
+    allTransfers(pageSize?: number): AsyncGenerator<TransferSummary>;
     /**
      * Create a draft. Nothing is live and nobody is emailed until `finalizeTransfer`.
      */
@@ -130,10 +151,17 @@ export declare class YungleClient {
     deleteCollection(id: string): Promise<{
         deleted: boolean;
     }>;
-    /** `folderId` omitted lists everything; `'root'` lists the top level only. */
-    listCollectionFiles(id: string, folderId?: string): Promise<{
+    /**
+     * `folderId` omitted lists everything; `'root'` lists the top level only.
+     * Without `page.limit` the whole collection comes back in one response; with
+     * it, follow `nextCursor` (or use `allCollectionFiles`).
+     */
+    listCollectionFiles(id: string, folderId?: string, page?: PageOptions): Promise<{
         files: CollectionFile[];
+        nextCursor: string | null;
     }>;
+    /** 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>;
     deleteCollectionFiles(id: string, fileIds: string[]): Promise<{
         deleted: number;
@@ -156,6 +184,55 @@ export declare class YungleClient {
     removeGuest(id: string, guestId: string): Promise<{
         removed: boolean;
     }>;
+    listWebhooks(): Promise<{
+        webhooks: WebhookEndpoint[];
+    }>;
+    /** `url: null` makes a pull endpoint. The `secret` is returned here only. */
+    createWebhook(input: {
+        url: string | null;
+        events: WebhookEventType[];
+        description?: string;
+    }): Promise<{
+        webhook: WebhookEndpoint;
+        secret: string;
+    }>;
+    getWebhook(id: string): Promise<{
+        webhook: WebhookEndpoint;
+    }>;
+    updateWebhook(id: string, input: {
+        url?: string | null;
+        events?: WebhookEventType[];
+        description?: string | null;
+        enabled?: boolean;
+    }): Promise<{
+        webhook: WebhookEndpoint;
+    }>;
+    deleteWebhook(id: string): Promise<{
+        deleted: boolean;
+    }>;
+    rotateWebhookSecret(id: string): Promise<{
+        secret: string;
+    }>;
+    testWebhook(id: string): Promise<{
+        deliveryId: string;
+    }>;
+    listWebhookDeliveries(id: string): Promise<{
+        deliveries: WebhookDelivery[];
+    }>;
+    retryWebhookDelivery(id: string, deliveryId: string): Promise<{
+        queued: boolean;
+    }>;
+    /**
+     * An endpoint's events, oldest first, after `cursor`. `nextCursor` comes back
+     * even when nothing is new, so keep the latest and poll with it.
+     */
+    listWebhookEvents(id: string, page?: PageOptions): Promise<{
+        events: (WebhookEvent & {
+            deliveryId: string;
+        })[];
+        nextCursor: string | null;
+        hasMore: boolean;
+    }>;
     listContacts(): Promise<{
         contacts: Contact[];
     }>;
@@ -173,12 +250,22 @@ export declare class YungleClient {
         deleted: boolean;
     }>;
     /**
-     * `idempotent` widens what may be retried.
+     * What may be retried after a 5xx or a lost connection.
      *
-     * GET and DELETE are safe by nature. POST is not — retrying `createTransfer`
-     * after a 500 would make a second draft — so it is opt-in per method, and set
-     * only where the server documents the operation as repeatable. Retrying a
-     * *throttle* is always fine regardless: a 429 means nothing happened.
+     * GET and DELETE are safe by nature. A POST is safe because it carries an
+     * `Idempotency-Key` (see below). PATCH is not retried. Retrying a *throttle*
+     * is always fine regardless: a 429 means nothing happened.
      */
     private request;
 }
+/**
+ * Check a webhook's `Yungle-Signature` header against the RAW request body.
+ *
+ * WebCrypto rather than `node:crypto`, so it runs wherever this client does:
+ * Node, Bun, Deno and edge runtimes. Rejects a timestamp more than
+ * `toleranceSeconds` away, which is what stops a captured request being replayed.
+ */
+export declare function verifyWebhook(rawBody: string, signatureHeader: string, secret: string, { toleranceSeconds, now }?: {
+    toleranceSeconds?: number;
+    now?: number;
+}): Promise<boolean>;

package/dist/index.mjs

@@ -7,6 +7,9 @@ var YungleApiError = class extends Error {
     this.details = details;
     this.name = "YungleApiError";
   }
+  status;
+  code;
+  details;
   /** Worth trying again: throttled, or our fault. */
   get retryable() {
     return this.status === 429 || this.status >= 500;
@@ -18,25 +21,49 @@ var YungleApiError = class extends Error {
   }
 };
 var DEFAULT_BASE = "https://yungle.co/api/v1";
+function pageQuery(page, extra = {}) {
+  const params = new URLSearchParams(extra);
+  if (page.limit !== void 0) params.set("limit", String(page.limit));
+  if (page.cursor) params.set("cursor", page.cursor);
+  const q = params.toString();
+  return q ? `?${q}` : "";
+}
+var CLIENT_VERSION = true ? "0.2.0" : "dev";
 var YungleClient = class {
   baseUrl;
   apiKey;
   doFetch;
   maxRetries;
+  userAgent;
   constructor(options) {
     if (!options.apiKey) throw new Error("An API key is required.");
     this.apiKey = options.apiKey;
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "");
     this.doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
     this.maxRetries = options.maxRetries ?? 3;
+    this.userAgent = options.userAgent ?? `yungle-client/${CLIENT_VERSION}`;
   }
   // ── Account ───────────────────────────────────────────────────────────────
   me() {
     return this.request("GET", "/me");
   }
   // ── Transfers ─────────────────────────────────────────────────────────────
-  listTransfers() {
-    return this.request("GET", "/transfers");
+  /**
+   * 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
+   * last one. `allTransfers()` does the walking for you.
+   */
+  listTransfers(page = {}) {
+    return this.request("GET", `/transfers${pageQuery(page)}`);
+  }
+  /** Every transfer, newest first, fetched a page at a time as you iterate. */
+  async *allTransfers(pageSize = 500) {
+    let cursor;
+    do {
+      const page = await this.listTransfers({ limit: pageSize, cursor });
+      yield* page.transfers;
+      cursor = page.nextCursor ?? void 0;
+    } while (cursor);
   }
   /**
    * Create a draft. Nothing is live and nobody is emailed until `finalizeTransfer`.
@@ -88,11 +115,24 @@ var YungleClient = class {
   deleteCollection(id) {
     return this.request("DELETE", `/collections/${enc(id)}`);
   }
-  /** `folderId` omitted lists everything; `'root'` lists the top level only. */
-  listCollectionFiles(id, folderId) {
-    const query = folderId ? `?folderId=${encodeURIComponent(folderId)}` : "";
+  /**
+   * `folderId` omitted lists everything; `'root'` lists the top level only.
+   * Without `page.limit` the whole collection comes back in one response; with
+   * it, follow `nextCursor` (or use `allCollectionFiles`).
+   */
+  listCollectionFiles(id, folderId, page = {}) {
+    const query = pageQuery(page, folderId ? { folderId } : {});
     return this.request("GET", `/collections/${enc(id)}/files${query}`);
   }
+  /** Every file in a collection, oldest first, a page at a time. */
+  async *allCollectionFiles(id, folderId, pageSize = 1e3) {
+    let cursor;
+    do {
+      const page = await this.listCollectionFiles(id, folderId, { limit: pageSize, cursor });
+      yield* page.files;
+      cursor = page.nextCursor ?? void 0;
+    } while (cursor);
+  }
   addCollectionFiles(id, files, folderId) {
     return this.request("POST", `/collections/${enc(id)}/files`, { files, folderId });
   }
@@ -114,6 +154,42 @@ var YungleClient = class {
   removeGuest(id, guestId) {
     return this.request("DELETE", `/collections/${enc(id)}/guests/${enc(guestId)}`);
   }
+  // ── Webhooks ──────────────────────────────────────────────────────────────
+  listWebhooks() {
+    return this.request("GET", "/webhooks");
+  }
+  /** `url: null` makes a pull endpoint. The `secret` is returned here only. */
+  createWebhook(input) {
+    return this.request("POST", "/webhooks", input);
+  }
+  getWebhook(id) {
+    return this.request("GET", `/webhooks/${enc(id)}`);
+  }
+  updateWebhook(id, input) {
+    return this.request("PATCH", `/webhooks/${enc(id)}`, input);
+  }
+  deleteWebhook(id) {
+    return this.request("DELETE", `/webhooks/${enc(id)}`);
+  }
+  rotateWebhookSecret(id) {
+    return this.request("POST", `/webhooks/${enc(id)}/rotate-secret`);
+  }
+  testWebhook(id) {
+    return this.request("POST", `/webhooks/${enc(id)}/test`);
+  }
+  listWebhookDeliveries(id) {
+    return this.request("GET", `/webhooks/${enc(id)}/deliveries`);
+  }
+  retryWebhookDelivery(id, deliveryId) {
+    return this.request("POST", `/webhooks/${enc(id)}/deliveries/${enc(deliveryId)}/retry`);
+  }
+  /**
+   * An endpoint's events, oldest first, after `cursor`. `nextCursor` comes back
+   * even when nothing is new, so keep the latest and poll with it.
+   */
+  listWebhookEvents(id, page = {}) {
+    return this.request("GET", `/webhooks/${enc(id)}/events${pageQuery(page)}`);
+  }
   // ── Contacts ──────────────────────────────────────────────────────────────
   listContacts() {
     return this.request("GET", "/contacts");
@@ -133,15 +209,15 @@ var YungleClient = class {
   }
   // ── Transport ─────────────────────────────────────────────────────────────
   /**
-   * `idempotent` widens what may be retried.
+   * What may be retried after a 5xx or a lost connection.
    *
-   * GET and DELETE are safe by nature. POST is not — retrying `createTransfer`
-   * after a 500 would make a second draft — so it is opt-in per method, and set
-   * only where the server documents the operation as repeatable. Retrying a
-   * *throttle* is always fine regardless: a 429 means nothing happened.
+   * GET and DELETE are safe by nature. A POST is safe because it carries an
+   * `Idempotency-Key` (see below). PATCH is not retried. Retrying a *throttle*
+   * is always fine regardless: a 429 means nothing happened.
    */
   async request(method, path, body, opts) {
-    const safe = method === "GET" || method === "DELETE" || opts?.idempotent === true;
+    const idempotencyKey = method === "POST" ? globalThis.crypto.randomUUID() : void 0;
+    const safe = method === "GET" || method === "DELETE" || idempotencyKey !== void 0 || opts?.idempotent === true;
     let attempt = 0;
     for (; ; ) {
       const res = await this.doFetch(`${this.baseUrl}${path}`, {
@@ -149,6 +225,8 @@ var YungleClient = class {
         headers: {
           Authorization: `Bearer ${this.apiKey}`,
           Accept: "application/json",
+          "User-Agent": this.userAgent,
+          ...idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {},
           ...body === void 0 ? {} : { "Content-Type": "application/json" }
         },
         ...body === void 0 ? {} : { body: JSON.stringify(body) }
@@ -187,7 +265,27 @@ function backoffMs(attempt, error) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function verifyWebhook(rawBody, signatureHeader, secret, { toleranceSeconds = 300, now = Date.now() } = {}) {
+  const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")));
+  const t = Number(parts.t);
+  if (!Number.isInteger(t) || Math.abs(now / 1e3 - t) > toleranceSeconds || !parts.v1) return false;
+  const key = await globalThis.crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const mac = new Uint8Array(await globalThis.crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${t}.${rawBody}`)));
+  const expected = [...mac].map((b) => b.toString(16).padStart(2, "0")).join("");
+  if (expected.length !== parts.v1.length) return false;
+  let diff = 0;
+  for (let i = 0; i < expected.length; i++) diff |= expected.charCodeAt(i) ^ parts.v1.charCodeAt(i);
+  return diff === 0;
+}
 export {
+  CLIENT_VERSION,
   YungleApiError,
-  YungleClient
+  YungleClient,
+  verifyWebhook
 };

package/dist/types.d.ts

@@ -21,7 +21,8 @@ export interface Workspace {
     id: string;
     email: string | null;
     displayName: string | null;
-    handle: string | null;
+    /** The workspace's verified custom domain, or null. */
+    customDomain: string | null;
 }
 export interface PlanInfo {
     tier: string | null;
@@ -34,6 +35,10 @@ export interface KeyInfo {
     id: string;
     name: string;
     scopes: string[];
+    /** Absent on servers before 2026-09-26. */
+    via?: 'key' | 'oauth';
+    /** Whether this credential may make Yungle email anyone. Absent on older servers. */
+    canEmail?: boolean;
 }
 export interface Me {
     workspace: Workspace;
@@ -95,6 +100,15 @@ export interface RecipientStatus {
     email: string;
     notifiedAt: Iso8601 | null;
     downloaded: boolean;
+    /** Loaded the link. Recorded from a browser, so link scanners do not count. */
+    opened: boolean;
+    /**
+     * Set when mail to this address permanently failed. Additive since 2026-09;
+     * clients that predate it are unaffected.
+     */
+    bouncedAt: Iso8601 | null;
+    /** 'hard_bounce' | 'blocked' | 'refused', or null. */
+    bounceKind: string | null;
 }
 export interface DownloadEvent {
     id: string;
@@ -103,6 +117,7 @@ export interface DownloadEvent {
     recipientEmail: string | null;
     /** One page visit is one download; several files in it share this. */
     sessionId: string;
+    /** Always null since 2026-09 — the truncated IP is no longer recorded. */
     ipTruncated: string | null;
     createdAt: Iso8601;
 }
@@ -173,3 +188,36 @@ export interface ContactInput {
     phone?: string | null;
     type?: string | null;
 }
+export type WebhookEventType = 'transfer.ready' | 'transfer.downloaded' | 'transfer.expiring' | 'transfer.expired' | 'collection.file_uploaded';
+export interface WebhookEndpoint {
+    id: string;
+    /** Null for a pull endpoint. */
+    url: string | null;
+    mode: 'push' | 'pull';
+    description: string | null;
+    events: WebhookEventType[];
+    enabled: boolean;
+    disabledReason: 'failing' | 'user' | null;
+    lastSuccessAt: Iso8601 | null;
+    lastFailureAt: Iso8601 | null;
+    createdAt: Iso8601;
+}
+export interface WebhookDelivery {
+    id: string;
+    eventId: string;
+    type: WebhookEventType | 'webhook.test';
+    status: 'pending' | 'succeeded' | 'failed' | 'available';
+    attempts: number;
+    nextAttemptAt: Iso8601 | null;
+    lastStatusCode: number | null;
+    lastError: string | null;
+    deliveredAt: Iso8601 | null;
+    createdAt: Iso8601;
+}
+/** The JSON a push delivery sends, and what `/events` returns (plus `deliveryId`). */
+export interface WebhookEvent<T = Record<string, unknown>> {
+    id: string;
+    type: WebhookEventType | 'webhook.test';
+    createdAt: Iso8601;
+    data: T;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yungle-client",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": {
@@ -9,28 +9,20 @@
       "default": "./dist/index.mjs"
     }
   },
-  "scripts": {
-    "build": "node build.mjs && tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test src/*.test.ts",
-    "lint": "eslint .",
-    "prepublishOnly": "node build.mjs && tsc -p tsconfig.build.json",
-    "prepare": "node build.mjs && tsc -p tsconfig.build.json"
-  },
   "devDependencies": {
     "@types/node": "^22.10.5",
     "tsx": "^4.19.2",
     "typescript": "^5.7.3",
-    "esbuild": "^0.25.0"
+    "esbuild": "^0.28.1"
   },
-  "description": "Typed client for the Yungle API \u2014 send file transfers, build collections and sync contacts from Node.",
+  "description": "Typed client for the Yungle API — send file transfers, build collections and sync contacts from Node.",
   "license": "MIT",
-  "author": "Hein de Wilde",
+  "author": "Brainpower <hello@yungle.co> (https://yungle.co)",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/heindewilde/yungle-clients.git"
   },
-  "homepage": "https://yungle.co/developers",
+  "homepage": "https://yungle.co/developers/reference?ref=npm",
   "bugs": {
     "url": "https://github.com/heindewilde/yungle-clients/issues"
   },
@@ -40,8 +32,12 @@
   "keywords": [
     "yungle",
     "file-transfer",
+    "file-sharing",
     "api-client",
     "sdk",
+    "typescript",
+    "webhooks",
+    "upload",
     "wetransfer-alternative",
     "eu",
     "gdpr"
@@ -51,5 +47,10 @@
     "README.md",
     "LICENSE"
   ],
-  "types": "./dist/index.d.ts"
-}
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test src/*.test.ts"
+  }
+}