yungle-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hein de Wilde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# yungle-client
+
+Typed client for the [Yungle](https://yungle.co) API — a private, EU-hosted file
+transfer service. Send transfers, build client collections and sync contacts
+from Node.
+
+```bash
+npm install yungle-client
+```
+
+```ts
+import { YungleClient } from 'yungle-client';
+
+const yungle = new YungleClient({ apiKey: process.env.YUNGLE_API_KEY! });
+
+// Reading is free on any account.
+const { transfers } = await yungle.listTransfers();
+const { downloads } = await yungle.transferDownloads(transfers[0].id);
+
+// Sending needs a paid plan.
+const draft = await yungle.createTransfer({
+  files: [{ name: 'final-cut.mov', size: 8_123_456_789 }],
+});
+// …stream the bytes to draft.tusEndpoint using draft.files[n].uploadToken…
+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.
+
+## 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.
+- **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.
+- **Errors carry a stable `code`.** Branch on `err.code`, never on the message.
+
+```ts
+import { YungleApiError } from 'yungle-client';
+
+try {
+  await yungle.createTransfer({ files });
+} catch (err) {
+  if (err instanceof YungleApiError && err.code === 'upgrade_required') {
+    // Reads are free; this is a write.
+  }
+}
+```
+
+## Not reachable
+
+Your vault and end-to-end encrypted transfers, because their keys are derived in
+the client and never sent to Yungle. See
+<https://yungle.co/developers/unsupported>.
+
+## 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)
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,184 @@
+import type { Collection, CollectionFile, CollectionSummary, Contact, ContactInput, DownloadEvent, FileInput, Folder, Guest, Me, RecipientStatus, Transfer, TransferFile, TransferSummary, UploadTargets } from './types';
+export * from './types';
+/**
+ * A typed client for the Yungle API.
+ *
+ * Deliberately dependency-free and built on `fetch`, so it runs unchanged in
+ * Node 22, Bun, Deno and a server-side edge runtime. The CLI and the MCP server
+ * 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.
+ */
+export interface YungleErrorBody {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * A failed request. Carries the machine-readable `code` — branch on that, never
+ * on `message`, which is written for a human reading a log and may change.
+ */
+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);
+    /** Worth trying again: throttled, or our fault. */
+    get retryable(): boolean;
+    /** Seconds to wait, when the server said. */
+    get retryAfterSeconds(): number | null;
+}
+export interface ClientOptions {
+    apiKey: string;
+    /** Defaults to production. Point it at a local server for development. */
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Retries for throttles and 5xx. Set to 0 to handle it yourself.
+     *
+     * Only ever applied to requests that are safe to repeat — see `request()`.
+     */
+    maxRetries?: number;
+}
+export declare class YungleClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly doFetch;
+    private readonly maxRetries;
+    constructor(options: ClientOptions);
+    me(): Promise<Me>;
+    listTransfers(): Promise<{
+        transfers: TransferSummary[];
+    }>;
+    /**
+     * Create a draft. Nothing is live and nobody is emailed until `finalizeTransfer`.
+     */
+    createTransfer(input: {
+        files: FileInput[];
+        title?: string;
+        expiresInDays?: number;
+    }): Promise<{
+        transfer: {
+            id: string;
+            slug: string;
+            expiresAt: string;
+            maxBytes: number;
+        };
+    } & UploadTargets>;
+    getTransfer(id: string): Promise<{
+        transfer: Transfer;
+        files: TransferFile[];
+        recipients: RecipientStatus[];
+    }>;
+    /**
+     * Send it. Omit `recipients` for a link-only transfer, which costs nothing
+     * from the daily email budget.
+     *
+     * Idempotent server-side, so a lost response is safe to repeat.
+     */
+    finalizeTransfer(id: string, input?: {
+        recipients?: string[];
+        message?: string;
+        password?: string;
+        title?: string;
+    }): Promise<{
+        transfer: Transfer;
+        notified: string[];
+    }>;
+    addTransferFiles(id: string, files: FileInput[]): Promise<UploadTargets>;
+    removeTransferFile(id: string, fileId: string): Promise<{
+        deleted: boolean;
+    }>;
+    updateTransfer(id: string, input: {
+        expiresInDays?: number;
+        maxDownloads?: number | null;
+    }): Promise<{
+        transfer: Transfer;
+    }>;
+    /** Immediate and irreversible — the encryption keys are destroyed. */
+    revokeTransfer(id: string): Promise<{
+        transfer: Transfer;
+    }>;
+    transferDownloads(id: string): Promise<{
+        downloads: DownloadEvent[];
+        recipients: RecipientStatus[];
+        totalDownloads: number;
+    }>;
+    listCollections(): Promise<{
+        collections: CollectionSummary[];
+    }>;
+    createCollection(input: {
+        title: string;
+        description?: string;
+    }): Promise<{
+        collection: Collection;
+    }>;
+    getCollection(id: string): Promise<{
+        collection: Collection;
+    }>;
+    updateCollection(id: string, input: {
+        title?: string;
+        description?: string;
+    }): Promise<{
+        collection: Collection;
+    }>;
+    deleteCollection(id: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** `folderId` omitted lists everything; `'root'` lists the top level only. */
+    listCollectionFiles(id: string, folderId?: string): Promise<{
+        files: CollectionFile[];
+    }>;
+    addCollectionFiles(id: string, files: FileInput[], folderId?: string | null): Promise<UploadTargets>;
+    deleteCollectionFiles(id: string, fileIds: string[]): Promise<{
+        deleted: number;
+    }>;
+    listFolders(id: string): Promise<{
+        folders: Folder[];
+    }>;
+    createFolder(id: string, input: {
+        name: string;
+        parentId?: string | null;
+    }): Promise<{
+        folder: Folder;
+    }>;
+    listGuests(id: string): Promise<{
+        guests: Guest[];
+    }>;
+    inviteGuests(id: string, emails: string[]): Promise<{
+        invited: string[];
+    }>;
+    removeGuest(id: string, guestId: string): Promise<{
+        removed: boolean;
+    }>;
+    listContacts(): Promise<{
+        contacts: Contact[];
+    }>;
+    createContact(input: ContactInput): Promise<{
+        contact: Contact;
+    }>;
+    getContact(id: string): Promise<{
+        contact: Contact;
+    }>;
+    /** A full replacement: any field omitted is cleared. */
+    updateContact(id: string, input: ContactInput): Promise<{
+        contact: Contact;
+    }>;
+    deleteContact(id: string): Promise<{
+        deleted: boolean;
+    }>;
+    /**
+     * `idempotent` widens what may be retried.
+     *
+     * 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.
+     */
+    private request;
+}

package/dist/index.mjs

@@ -0,0 +1,193 @@
+// src/index.ts
+var YungleApiError = class extends Error {
+  constructor(status, code, message, details) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.name = "YungleApiError";
+  }
+  /** Worth trying again: throttled, or our fault. */
+  get retryable() {
+    return this.status === 429 || this.status >= 500;
+  }
+  /** Seconds to wait, when the server said. */
+  get retryAfterSeconds() {
+    const value = this.details?.retryAfterSeconds;
+    return typeof value === "number" ? value : null;
+  }
+};
+var DEFAULT_BASE = "https://yungle.co/api/v1";
+var YungleClient = class {
+  baseUrl;
+  apiKey;
+  doFetch;
+  maxRetries;
+  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;
+  }
+  // ── Account ───────────────────────────────────────────────────────────────
+  me() {
+    return this.request("GET", "/me");
+  }
+  // ── Transfers ─────────────────────────────────────────────────────────────
+  listTransfers() {
+    return this.request("GET", "/transfers");
+  }
+  /**
+   * Create a draft. Nothing is live and nobody is emailed until `finalizeTransfer`.
+   */
+  createTransfer(input) {
+    return this.request("POST", "/transfers", input);
+  }
+  getTransfer(id) {
+    return this.request("GET", `/transfers/${enc(id)}`);
+  }
+  /**
+   * Send it. Omit `recipients` for a link-only transfer, which costs nothing
+   * from the daily email budget.
+   *
+   * Idempotent server-side, so a lost response is safe to repeat.
+   */
+  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 });
+  }
+  removeTransferFile(id, fileId) {
+    return this.request("DELETE", `/transfers/${enc(id)}/files/${enc(fileId)}`);
+  }
+  updateTransfer(id, input) {
+    return this.request("PATCH", `/transfers/${enc(id)}`, input);
+  }
+  /** Immediate and irreversible — the encryption keys are destroyed. */
+  revokeTransfer(id) {
+    return this.request("DELETE", `/transfers/${enc(id)}`);
+  }
+  transferDownloads(id) {
+    return this.request("GET", `/transfers/${enc(id)}/downloads`);
+  }
+  // ── Collections ───────────────────────────────────────────────────────────
+  listCollections() {
+    return this.request("GET", "/collections");
+  }
+  createCollection(input) {
+    return this.request("POST", "/collections", input);
+  }
+  getCollection(id) {
+    return this.request("GET", `/collections/${enc(id)}`);
+  }
+  updateCollection(id, input) {
+    return this.request("PATCH", `/collections/${enc(id)}`, input);
+  }
+  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)}` : "";
+    return this.request("GET", `/collections/${enc(id)}/files${query}`);
+  }
+  addCollectionFiles(id, files, folderId) {
+    return this.request("POST", `/collections/${enc(id)}/files`, { files, folderId });
+  }
+  deleteCollectionFiles(id, fileIds) {
+    return this.request("DELETE", `/collections/${enc(id)}/files`, { fileIds });
+  }
+  listFolders(id) {
+    return this.request("GET", `/collections/${enc(id)}/folders`);
+  }
+  createFolder(id, input) {
+    return this.request("POST", `/collections/${enc(id)}/folders`, input);
+  }
+  listGuests(id) {
+    return this.request("GET", `/collections/${enc(id)}/guests`);
+  }
+  inviteGuests(id, emails) {
+    return this.request("POST", `/collections/${enc(id)}/guests`, { emails });
+  }
+  removeGuest(id, guestId) {
+    return this.request("DELETE", `/collections/${enc(id)}/guests/${enc(guestId)}`);
+  }
+  // ── Contacts ──────────────────────────────────────────────────────────────
+  listContacts() {
+    return this.request("GET", "/contacts");
+  }
+  createContact(input) {
+    return this.request("POST", "/contacts", input);
+  }
+  getContact(id) {
+    return this.request("GET", `/contacts/${enc(id)}`);
+  }
+  /** A full replacement: any field omitted is cleared. */
+  updateContact(id, input) {
+    return this.request("PATCH", `/contacts/${enc(id)}`, input);
+  }
+  deleteContact(id) {
+    return this.request("DELETE", `/contacts/${enc(id)}`);
+  }
+  // ── Transport ─────────────────────────────────────────────────────────────
+  /**
+   * `idempotent` widens what may be retried.
+   *
+   * 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.
+   */
+  async request(method, path, body, opts) {
+    const safe = method === "GET" || method === "DELETE" || opts?.idempotent === true;
+    let attempt = 0;
+    for (; ; ) {
+      const res = await this.doFetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          Accept: "application/json",
+          ...body === void 0 ? {} : { "Content-Type": "application/json" }
+        },
+        ...body === void 0 ? {} : { body: JSON.stringify(body) }
+      });
+      if (res.ok) return await res.json();
+      const error = await toError(res);
+      const mayRetry = error.status === 429 || safe && error.retryable;
+      if (!mayRetry || attempt >= this.maxRetries) throw error;
+      await sleep(backoffMs(attempt, error));
+      attempt++;
+    }
+  }
+};
+function enc(segment) {
+  return encodeURIComponent(segment);
+}
+async function toError(res) {
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+  }
+  const err = body?.error;
+  return new YungleApiError(
+    res.status,
+    err?.code ?? "http_error",
+    err?.message ?? `Request failed with status ${res.status}.`,
+    err?.details
+  );
+}
+function backoffMs(attempt, error) {
+  const stated = error.retryAfterSeconds;
+  if (stated !== null) return stated * 1e3;
+  return Math.min(2 ** attempt * 500, 8e3) + Math.floor(Math.random() * 250);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export {
+  YungleApiError,
+  YungleClient
+};

package/dist/types.d.ts

@@ -0,0 +1,175 @@
+/**
+ * The wire shapes `/api/v1` emits.
+ *
+ * Hand-written rather than generated, and deliberately **not** imported by
+ * `apps/web`. Two reasons, both practical:
+ *
+ *  - Having the server import this package would put it in the web app's
+ *    dependency graph, which means a `COPY packages/api-client/package.json`
+ *    line in two Dockerfiles for something production never runs. The cost of
+ *    forgetting that line is an image build failure, not a test failure.
+ *  - The server's own definitions live in `lib/api/serialize.ts` and are the
+ *    authority. These are a client's *reading* of the contract.
+ *
+ * Drift is managed by the OpenAPI document at `/api/v1/openapi.json`, which is
+ * generated from the server's Zod schemas — and by both sides living in one
+ * repo and shipping in one commit. If this package ever gains a second consumer
+ * outside the repo, generate it from the spec instead.
+ */
+export type Iso8601 = string;
+export interface Workspace {
+    id: string;
+    email: string | null;
+    displayName: string | null;
+    handle: string | null;
+}
+export interface PlanInfo {
+    tier: string | null;
+    name: string | null;
+    status: string;
+    quotaBytes: number;
+    usedBytes: number;
+}
+export interface KeyInfo {
+    id: string;
+    name: string;
+    scopes: string[];
+}
+export interface Me {
+    workspace: Workspace;
+    plan: PlanInfo;
+    key: KeyInfo;
+}
+/** What you send when registering a file for upload. */
+export interface FileInput {
+    name: string;
+    size: number;
+    type?: string;
+    /** Directory inside an uploaded folder, e.g. `Ceremony/Raw`. */
+    path?: string;
+}
+/** Where to put the bytes, and the token that authorizes every tus request. */
+export interface UploadTarget {
+    id: string;
+    name: string;
+    size: number;
+    uploadToken: string;
+}
+export interface UploadTargets {
+    tusEndpoint: string;
+    files: UploadTarget[];
+}
+export interface Transfer {
+    id: string;
+    slug: string;
+    url: string;
+    title: string | null;
+    status: string;
+    sizeBytes: number;
+    fileCount?: number;
+    recipients: string[];
+    hasPassword: 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;
+}
+export interface TransferSummary extends Omit<Transfer, 'hasPassword' | 'fileCount'> {
+    fileCount: number;
+    firstFileName: string | null;
+}
+export interface TransferFile {
+    id: string;
+    name: string;
+    sizeBytes: number;
+    mimeType: string;
+    path: string | null;
+    /** Null until the malware scan finishes, then `clean` or `infected`. */
+    scanResult: string | null;
+    createdAt: Iso8601;
+}
+export interface RecipientStatus {
+    id: string;
+    email: string;
+    notifiedAt: Iso8601 | null;
+    downloaded: boolean;
+}
+export interface DownloadEvent {
+    id: string;
+    /** Null means the whole-transfer zip rather than one file. */
+    fileName: string | null;
+    recipientEmail: string | null;
+    /** One page visit is one download; several files in it share this. */
+    sessionId: string;
+    ipTruncated: string | null;
+    createdAt: Iso8601;
+}
+export interface Collection {
+    id: string;
+    title: string;
+    slug: string;
+    description: string | null;
+    visibility: string;
+    /** The secret link. Null only for rows created before it was minted eagerly. */
+    url: string | null;
+    customLink: boolean;
+    sizeBytes: number;
+    coverFileId: string | null;
+    expiresAt: Iso8601 | null;
+    createdAt: Iso8601 | null;
+    updatedAt: Iso8601 | null;
+    fileCount?: number;
+}
+export interface CollectionSummary {
+    id: string;
+    title: string;
+    slug: string;
+    visibility: string;
+    fileCount: number;
+    sizeBytes: number;
+    coverFileId: string | null;
+    updatedAt: Iso8601 | null;
+}
+export interface CollectionFile {
+    id: string;
+    name: string;
+    sizeBytes: number;
+    mimeType: string;
+    folderId: string | null;
+    hasThumbnail: boolean;
+    createdAt: Iso8601 | null;
+}
+export interface Folder {
+    id: string;
+    name: string;
+    /** Materialized, e.g. `/Ceremony/Raw`. */
+    path: string;
+    parentId: string | null;
+    depth: number;
+}
+export interface Guest {
+    id: string;
+    email: string;
+    status: string;
+}
+export interface Contact {
+    id: string;
+    firstName: string | null;
+    lastName: string | null;
+    company: string | null;
+    email: string;
+    phone: string | null;
+    type: string;
+    createdAt: Iso8601 | null;
+    updatedAt: Iso8601 | null;
+}
+export interface ContactInput {
+    firstName?: string | null;
+    lastName?: string | null;
+    company?: string | null;
+    email: string;
+    phone?: string | null;
+    type?: string | null;
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "yungle-client",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "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"
+  },
+  "description": "Typed client for the Yungle API \u2014 send file transfers, build collections and sync contacts from Node.",
+  "license": "MIT",
+  "author": "Hein de Wilde",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heindewilde/yungle-clients.git"
+  },
+  "homepage": "https://yungle.co/developers",
+  "bugs": {
+    "url": "https://github.com/heindewilde/yungle-clients/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "yungle",
+    "file-transfer",
+    "api-client",
+    "sdk",
+    "wetransfer-alternative",
+    "eu",
+    "gdpr"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "types": "./dist/index.d.ts"
+}