upthing-sdk 1.0.1 → 1.0.3

package/README.md

@@ -8,38 +8,64 @@ TypeScript SDK for [upthing.2klabs.xyz](https://upthing.2klabs.xyz) — upload f
 npm install upthing-sdk
 ```
 
-## Quick start
+## Two entry points
+
+| Import | Environment | Has `uploadFile`? |
+| ------ | ----------- | ----------------- |
+| `upthing-sdk` | Browser + Node.js | No (`fs` would break bundlers) |
+| `upthing-sdk/node` | Node.js only | Yes |
+
+Use the default import for browser/edge/client-side code (Next.js `"use client"`, React, etc.).
+Use `upthing-sdk/node` in server-only code when you need `uploadFile()`.
+
+## Quick start (Node.js)
 
 ```typescript
-import { UpThingClient } from "upthing-sdk";
+import { UpThingNodeClient } from "upthing-sdk/node";
 
-const upthing = new UpThingClient({
+const upthing = new UpThingNodeClient({
   apiKey: process.env.UPTHING_API_KEY!,
 });
 
-// Upload a file
+// Upload a file from disk
 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
+// Proxy an external image
 const src = upthing.proxyUrl("https://example.com/banner.jpg");
-// <img src={src} />
+```
+
+## Quick start (Browser / Next.js client)
+
+```typescript
+"use client";
+import { UpThingClient } from "upthing-sdk";
+
+// No API key needed for domain-auth proxy
+const upthing = new UpThingClient();
+
+// Use directly in JSX
+<img src={upthing.proxyUrl("https://example.com/photo.jpg", {
+  projectUuid: "07595179-..."
+})} />
 ```
 
 ## API
 
-### `new UpThingClient(options)`
+### `new UpThingClient(options?)`
 
-| Option    | Type   | Default                          |
-| --------- | ------ | -------------------------------- |
-| `apiKey`  | string | **required**                     |
-| `baseUrl` | string | `https://upthing.2klabs.xyz`    |
+| Option    | Type   | Default                       |
+| --------- | ------ | ----------------------------- |
+| `apiKey`  | string | `""` (optional for proxy URL builders) |
+| `baseUrl` | string | `https://upthing.2klabs.xyz`  |
+
+`UpThingNodeClient` (from `upthing-sdk/node`) extends `UpThingClient` and adds `uploadFile()`.
 
 ### Upload methods
 
 ```typescript
-// From a file path (Node.js)
+// From a file path (Node.js only — use UpThingNodeClient)
 await upthing.uploadFile("./photo.jpg");
 await upthing.uploadFile("./photo.jpg", { ttlSeconds: 3600 });
 
@@ -61,17 +87,48 @@ await upthing.uploadBase64(base64String, "avatar.png");
 | `projectUuid` | string | Target project (if key isn't pinned)     |
 | `ttlSeconds`  | number | Auto-delete after N seconds              |
 
+### File management
+
+```typescript
+// List files (paginated)
+const { data, pagination } = await upthing.listFiles({ limit: 20, offset: 0 });
+console.log(`${pagination.total} files total`);
+
+// Filter by project
+const { data: projectFiles } = await upthing.listFiles({
+  projectUuid: "07595179-...",
+});
+
+// Get a single file
+const file = await upthing.getFile("d98b6a92-...");
+console.log(file.url, file.mime_type, file.size_bytes);
+
+// Delete a file (removes S3 object + soft-deletes DB row)
+await upthing.deleteFile("d98b6a92-...");
+
+// Generate a signed URL (for files with url_mode: "signed")
+const { url, expires_in } = await upthing.getSignedUrl("d98b6a92-...", 7200);
+```
+
+#### List files options
+
+| Option        | Type   | Default | Description                          |
+| ------------- | ------ | ------- | ------------------------------------ |
+| `projectUuid` | string | —       | Filter by project                    |
+| `limit`       | number | 50      | Results per page (1–200)             |
+| `offset`      | number | 0       | Pagination offset                    |
+
 ### Proxy
 
 ```typescript
-// Build a URL that serves the proxied image (use in <img>, fetch, etc.)
+// Build a URL for domain-auth proxy (no API key needed)
 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
+// Fetch the image bytes server-side (requires API key)
 const response = await upthing.proxyFetch("https://example.com/image.jpg");
 const buffer = await response.arrayBuffer();
 ```
@@ -90,7 +147,7 @@ upthing.permanentUrl("UgjIzXI3ZolZ");
 import { UpThingSDKError } from "upthing-sdk";
 
 try {
-  await upthing.uploadFile("./huge.mp4");
+  await upthing.uploadBlob(file, "huge.mp4");
 } catch (err) {
   if (err instanceof UpThingSDKError) {
     console.error(err.status, err.message);
@@ -99,20 +156,26 @@ try {
 }
 ```
 
-## Browser usage
+All methods except `proxyUrl()` and `permanentUrl()` require an API key and throw immediately with a helpful message if none was provided.
+
+## Browser / React / Next.js usage
 
 ```typescript
-const upthing = new UpThingClient({ apiKey: "ak_..." });
+"use client";
+import { UpThingClient } from "upthing-sdk";
+
+const upthing = new UpThingClient();
 
-// Proxy images directly in HTML — no async needed
-document.querySelector("img")!.src = upthing.proxyUrl("https://example.com/photo.jpg");
+// Proxy images directly in HTML — no API key needed with domain auth
+<img src={upthing.proxyUrl("https://example.com/photo.jpg")} />
 
-// Upload from a file input
+// Upload from a file input (requires API key)
+const uploader = new UpThingClient({ apiKey: "ak_..." });
 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);
+  const result = await uploader.uploadBlob(file, file.name);
   console.log("Uploaded:", result.url);
 });
 ```

package/dist/index.d.ts

@@ -20,6 +20,23 @@ export interface UploadOptions {
     projectUuid?: string;
     ttlSeconds?: number;
 }
+export interface ListFilesOptions {
+    projectUuid?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface ListFilesResponse {
+    data: UpThingFile[];
+    pagination: {
+        limit: number;
+        offset: number;
+        total: number;
+    };
+}
+export interface SignedUrlResponse {
+    url: string;
+    expires_in: number;
+}
 export interface ProxyOptions {
     projectUuid?: string;
     ttlSeconds?: number;
@@ -41,10 +58,6 @@ 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).
      */
@@ -57,6 +70,26 @@ export declare class UpThingClient {
      * Upload base64-encoded data.
      */
     uploadBase64(base64Data: string, filename: string, options?: UploadOptions): Promise<UpThingFile>;
+    /**
+     * List files owned by the authenticated user.
+     * Requires the `read` scope if the API key uses scoped permissions.
+     */
+    listFiles(options?: ListFilesOptions): Promise<ListFilesResponse>;
+    /**
+     * Get a single file's metadata by UUID.
+     * Requires the `read` scope if the API key uses scoped permissions.
+     */
+    getFile(uuid: string): Promise<UpThingFile>;
+    /**
+     * Delete a file by UUID. Removes the S3 object and soft-deletes the DB row.
+     * Requires the `delete` scope if the API key uses scoped permissions.
+     */
+    deleteFile(uuid: string): Promise<void>;
+    /**
+     * Generate a time-limited signed delivery URL for a file.
+     * Requires the `read` scope if the API key uses scoped permissions.
+     */
+    getSignedUrl(uuid: string, ttlSeconds?: number): Promise<SignedUrlResponse>;
     /**
      * Build a proxy query-string URL (without auth).  Useful when the
      * project uses `domain` auth mode and no API key is needed in the
@@ -73,7 +106,9 @@ export declare class UpThingClient {
      * Build a permanent delivery URL for a public_id.
      */
     permanentUrl(publicId: string): string;
-    private requireKey;
-    private request;
+    /** @internal */
+    requireKey(method: string): void;
+    /** @internal */
+    request<T>(method: string, path: string, body?: FormData | Record<string, unknown>): Promise<T>;
 }
 export default UpThingClient;

package/dist/index.js

@@ -16,22 +16,6 @@ export class UpThingClient {
         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).
      */
@@ -62,6 +46,47 @@ export class UpThingClient {
             ttl_seconds: options?.ttlSeconds,
         }).then((r) => r.file);
     }
+    // ── Files ───────────────────────────────────────────────────────────
+    /**
+     * List files owned by the authenticated user.
+     * Requires the `read` scope if the API key uses scoped permissions.
+     */
+    async listFiles(options) {
+        const params = new URLSearchParams();
+        if (options?.projectUuid)
+            params.set("project_uuid", options.projectUuid);
+        if (options?.limit != null)
+            params.set("limit", String(options.limit));
+        if (options?.offset != null)
+            params.set("offset", String(options.offset));
+        const qs = params.toString();
+        return this.request("GET", `/api/files${qs ? `?${qs}` : ""}`);
+    }
+    /**
+     * Get a single file's metadata by UUID.
+     * Requires the `read` scope if the API key uses scoped permissions.
+     */
+    async getFile(uuid) {
+        return this.request("GET", `/api/files/${uuid}`).then((r) => r.file);
+    }
+    /**
+     * Delete a file by UUID. Removes the S3 object and soft-deletes the DB row.
+     * Requires the `delete` scope if the API key uses scoped permissions.
+     */
+    async deleteFile(uuid) {
+        await this.request("DELETE", `/api/files/${uuid}`);
+    }
+    /**
+     * Generate a time-limited signed delivery URL for a file.
+     * Requires the `read` scope if the API key uses scoped permissions.
+     */
+    async getSignedUrl(uuid, ttlSeconds) {
+        const params = new URLSearchParams();
+        if (ttlSeconds != null)
+            params.set("ttl_seconds", String(ttlSeconds));
+        const qs = params.toString();
+        return this.request("GET", `/api/files/${uuid}/signed-url${qs ? `?${qs}` : ""}`);
+    }
     // ── Proxy ───────────────────────────────────────────────────────────
     /**
      * Build a proxy query-string URL (without auth).  Useful when the
@@ -101,12 +126,14 @@ export class UpThingClient {
         return `${this.baseUrl}/f/${publicId}`;
     }
     // ── Internal ────────────────────────────────────────────────────────
+    /** @internal */
     requireKey(method) {
         if (!this.apiKey) {
             throw new Error(`UpThingClient.${method}() requires an apiKey. ` +
                 `Pass one via new UpThingClient({ apiKey: "ak_..." }).`);
         }
     }
+    /** @internal */
     async request(method, path, body) {
         this.requireKey("request");
         const headers = {
@@ -125,6 +152,8 @@ export class UpThingClient {
             headers,
             body: requestBody,
         });
+        if (res.status === 204)
+            return undefined;
         if (!res.ok) {
             const err = await res.json().catch(() => ({ error: `HTTP ${res.status}`, code: 0 }));
             throw new UpThingSDKError(res.status, err);

package/dist/node.d.ts

@@ -0,0 +1,9 @@
+import { UpThingClient, type UploadOptions, type UpThingFile } from "./index.js";
+export declare class UpThingNodeClient extends UpThingClient {
+    /**
+     * Upload a file from a local path (Node.js only).
+     */
+    uploadFile(filePath: string, options?: UploadOptions): Promise<UpThingFile>;
+}
+export * from "./index.js";
+export default UpThingNodeClient;

package/dist/node.js

@@ -0,0 +1,22 @@
+import { UpThingClient } from "./index.js";
+import { readFileSync } from "fs";
+import { basename } from "path";
+export class UpThingNodeClient extends UpThingClient {
+    /**
+     * Upload a file from a local path (Node.js only).
+     */
+    async uploadFile(filePath, options) {
+        const form = new FormData();
+        const blob = new Blob([readFileSync(filePath)]);
+        const name = options?.filename ?? 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));
+        this.requireKey("uploadFile");
+        return this.request("POST", "/api/upload", form).then((r) => r.file);
+    }
+}
+export * from "./index.js";
+export default UpThingNodeClient;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "upthing-sdk",
-  "version": "1.0.1",
-  "description": "TypeScript SDK for upthing.2klabs.xyz — upload files, proxy images",
+  "version": "1.0.3",
+  "description": "TypeScript SDK for upthing.2klabs.xyz — upload, manage, and proxy files",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,6 +12,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./node": {
+      "import": "./dist/node.js",
+      "types": "./dist/node.d.ts"
     }
   },
   "scripts": {