upthing-sdk 1.0.2 → 1.0.3

package/README.md

@@ -87,6 +87,37 @@ 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
@@ -125,7 +156,7 @@ try {
 }
 ```
 
-Methods that require an API key (`uploadBlob`, `uploadBuffer`, `uploadBase64`, `uploadFile`, `proxyFetch`) throw immediately with a helpful message if no key was provided.
+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
 

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;
@@ -53,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

package/dist/index.js

@@ -46,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
@@ -111,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "upthing-sdk",
-  "version": "1.0.2",
-  "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",