upthing-sdk 1.0.0

package/README.md

@@ -0,0 +1,123 @@
+# upthing-sdk
+
+TypeScript SDK for [upthing.2klabs.xyz](https://upthing.2klabs.xyz) — upload files and proxy images with one function call.
+
+## Install
+
+```bash
+npm install upthing-sdk
+```
+
+## Quick start
+
+```typescript
+import { UpThingClient } from "upthing-sdk";
+
+const upthing = new UpThingClient({
+  apiKey: process.env.UPTHING_API_KEY!,
+});
+
+// Upload a file
+const file = await upthing.uploadFile("./photo.jpg");
+console.log(file.url);
+// https://upthing.2klabs.xyz/f/UgjIzXI3ZolZ
+
+// Proxy an external image — get a URL you can use directly
+const src = upthing.proxyUrl("https://example.com/banner.jpg");
+// <img src={src} />
+```
+
+## API
+
+### `new UpThingClient(options)`
+
+| Option    | Type   | Default                          |
+| --------- | ------ | -------------------------------- |
+| `apiKey`  | string | **required**                     |
+| `baseUrl` | string | `https://upthing.2klabs.xyz`    |
+
+### Upload methods
+
+```typescript
+// From a file path (Node.js)
+await upthing.uploadFile("./photo.jpg");
+await upthing.uploadFile("./photo.jpg", { ttlSeconds: 3600 });
+
+// From a Blob/File (Node.js + browser)
+await upthing.uploadBlob(file, "photo.jpg");
+
+// From a buffer
+await upthing.uploadBuffer(uint8array, "data.bin");
+
+// From base64
+await upthing.uploadBase64(base64String, "avatar.png");
+```
+
+#### Upload options
+
+| Option        | Type   | Description                              |
+| ------------- | ------ | ---------------------------------------- |
+| `filename`    | string | Override the filename                    |
+| `projectUuid` | string | Target project (if key isn't pinned)     |
+| `ttlSeconds`  | number | Auto-delete after N seconds              |
+
+### Proxy
+
+```typescript
+// Build a URL that serves the proxied image (use in <img>, fetch, etc.)
+const src = upthing.proxyUrl("https://example.com/image.jpg");
+const src = upthing.proxyUrl("https://example.com/image.jpg", {
+  projectUuid: "07595179-...",
+  ttlSeconds: 3600,
+});
+
+// Fetch the image bytes server-side
+const response = await upthing.proxyFetch("https://example.com/image.jpg");
+const buffer = await response.arrayBuffer();
+```
+
+### Helpers
+
+```typescript
+// Build a permanent URL from a public_id
+upthing.permanentUrl("UgjIzXI3ZolZ");
+// https://upthing.2klabs.xyz/f/UgjIzXI3ZolZ
+```
+
+### Error handling
+
+```typescript
+import { UpThingSDKError } from "upthing-sdk";
+
+try {
+  await upthing.uploadFile("./huge.mp4");
+} catch (err) {
+  if (err instanceof UpThingSDKError) {
+    console.error(err.status, err.message);
+    // 413 "File exceeds max size"
+  }
+}
+```
+
+## Browser usage
+
+```typescript
+const upthing = new UpThingClient({ apiKey: "ak_..." });
+
+// Proxy images directly in HTML — no async needed
+document.querySelector("img")!.src = upthing.proxyUrl("https://example.com/photo.jpg");
+
+// Upload from a file input
+const input = document.querySelector<HTMLInputElement>("#file-input")!;
+input.addEventListener("change", async () => {
+  const file = input.files?.[0];
+  if (!file) return;
+  const result = await upthing.uploadBlob(file, file.name);
+  console.log("Uploaded:", result.url);
+});
+```
+
+## Requirements
+
+- Node.js 18+ (native `fetch`) or any modern browser
+- No dependencies

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+export interface UpThingFile {
+    uuid: string;
+    public_id: string;
+    filename: string;
+    mime_type: string;
+    size_bytes: number;
+    url_mode: "permanent" | "signed";
+    url: string | null;
+    expires_at: string | null;
+    ttl_seconds: number | null;
+    is_proxied: boolean;
+    source_url: string | null;
+    view_count: number;
+    download_bytes: number;
+    created_at: string;
+    project_id: number | null;
+}
+export interface UploadOptions {
+    filename?: string;
+    projectUuid?: string;
+    ttlSeconds?: number;
+}
+export interface ProxyOptions {
+    projectUuid?: string;
+    ttlSeconds?: number;
+}
+export interface UpThingError {
+    error: string;
+    code: number;
+}
+export declare class UpThingSDKError extends Error {
+    readonly status: number;
+    readonly body: UpThingError;
+    constructor(status: number, body: UpThingError);
+}
+export interface UpThingClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+export declare class UpThingClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(options: UpThingClientOptions);
+    /**
+     * Upload a file from a local path (Node.js only).
+     */
+    uploadFile(filePath: string, options?: UploadOptions): Promise<UpThingFile>;
+    /**
+     * Upload a Blob/File (works in Node.js and browsers).
+     */
+    uploadBlob(blob: Blob, filename: string, options?: UploadOptions): Promise<UpThingFile>;
+    /**
+     * Upload raw bytes with a filename.
+     */
+    uploadBuffer(buffer: ArrayBuffer | Uint8Array, filename: string, options?: UploadOptions): Promise<UpThingFile>;
+    /**
+     * Upload base64-encoded data.
+     */
+    uploadBase64(base64Data: string, filename: string, options?: UploadOptions): Promise<UpThingFile>;
+    /**
+     * Build a proxy query-string URL (without auth).  Useful when the
+     * project uses `domain` auth mode and no API key is needed in the
+     * request — e.g. for `<img src>` on an authorized domain.
+     */
+    proxyUrl(url: string, options?: ProxyOptions): string;
+    /**
+     * Fetch a proxied image and return the raw Response.
+     * Sends the API key via header (never exposed in the URL).
+     */
+    proxyFetch(url: string, options?: ProxyOptions): Promise<Response>;
+    /**
+     * Build a permanent delivery URL for a public_id.
+     */
+    permanentUrl(publicId: string): string;
+    private request;
+}
+export default UpThingClient;

package/dist/index.js

@@ -0,0 +1,126 @@
+export class UpThingSDKError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(body.error);
+        this.status = status;
+        this.body = body;
+        this.name = "UpThingSDKError";
+    }
+}
+export class UpThingClient {
+    apiKey;
+    baseUrl;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? "https://upthing.2klabs.xyz").replace(/\/$/, "");
+    }
+    // ── Upload ──────────────────────────────────────────────────────────
+    /**
+     * Upload a file from a local path (Node.js only).
+     */
+    async uploadFile(filePath, options) {
+        const fs = await import("fs");
+        const path = await import("path");
+        const form = new FormData();
+        const blob = new Blob([fs.readFileSync(filePath)]);
+        const name = options?.filename ?? path.basename(filePath);
+        form.append("file", blob, name);
+        if (options?.projectUuid)
+            form.append("project_uuid", options.projectUuid);
+        if (options?.ttlSeconds != null)
+            form.append("ttl_seconds", String(options.ttlSeconds));
+        return this.request("POST", "/api/upload", form).then((r) => r.file);
+    }
+    /**
+     * Upload a Blob/File (works in Node.js and browsers).
+     */
+    async uploadBlob(blob, filename, options) {
+        const form = new FormData();
+        form.append("file", blob, filename);
+        if (options?.projectUuid)
+            form.append("project_uuid", options.projectUuid);
+        if (options?.ttlSeconds != null)
+            form.append("ttl_seconds", String(options.ttlSeconds));
+        return this.request("POST", "/api/upload", form).then((r) => r.file);
+    }
+    /**
+     * Upload raw bytes with a filename.
+     */
+    async uploadBuffer(buffer, filename, options) {
+        const blob = new Blob([new Uint8Array(buffer)]);
+        return this.uploadBlob(blob, filename, options);
+    }
+    /**
+     * Upload base64-encoded data.
+     */
+    async uploadBase64(base64Data, filename, options) {
+        return this.request("POST", "/api/upload", {
+            filename,
+            data_base64: base64Data,
+            project_uuid: options?.projectUuid,
+            ttl_seconds: options?.ttlSeconds,
+        }).then((r) => r.file);
+    }
+    // ── Proxy ───────────────────────────────────────────────────────────
+    /**
+     * Build a proxy query-string URL (without auth).  Useful when the
+     * project uses `domain` auth mode and no API key is needed in the
+     * request — e.g. for `<img src>` on an authorized domain.
+     */
+    proxyUrl(url, options) {
+        const params = new URLSearchParams({ url });
+        if (options?.projectUuid)
+            params.set("project_uuid", options.projectUuid);
+        if (options?.ttlSeconds != null)
+            params.set("ttl_seconds", String(options.ttlSeconds));
+        return `${this.baseUrl}/?${params.toString()}`;
+    }
+    /**
+     * Fetch a proxied image and return the raw Response.
+     * Sends the API key via header (never exposed in the URL).
+     */
+    async proxyFetch(url, options) {
+        const target = this.proxyUrl(url, options);
+        const res = await fetch(target, {
+            headers: { "X-API-Key": this.apiKey },
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: `HTTP ${res.status}`, code: 0 }));
+            throw new UpThingSDKError(res.status, err);
+        }
+        return res;
+    }
+    // ── Helpers ─────────────────────────────────────────────────────────
+    /**
+     * Build a permanent delivery URL for a public_id.
+     */
+    permanentUrl(publicId) {
+        return `${this.baseUrl}/f/${publicId}`;
+    }
+    // ── Internal ────────────────────────────────────────────────────────
+    async request(method, path, body) {
+        const headers = {
+            "X-API-Key": this.apiKey,
+        };
+        let requestBody;
+        if (body instanceof FormData) {
+            requestBody = body;
+        }
+        else if (body != null) {
+            headers["Content-Type"] = "application/json";
+            requestBody = JSON.stringify(body);
+        }
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: requestBody,
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: `HTTP ${res.status}`, code: 0 }));
+            throw new UpThingSDKError(res.status, err);
+        }
+        return res.json();
+    }
+}
+export default UpThingClient;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "upthing-sdk",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for upthing.2klabs.xyz — upload files, proxy images",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "typescript": "^5.7"
+  },
+  "license": "MIT",
+  "keywords": [
+    "upthing",
+    "file-upload",
+    "image-proxy",
+    "s3",
+    "cdn"
+  ]
+}