@thetechfossil/upfiles 0.1.1 → 0.3.0

package/README.md

@@ -4,6 +4,7 @@ Lightweight JavaScript client and React component to upload files via a presigne
 
 - Client: get presigned URLs and PUT to S3
 - React `<Uploader />`: drag/drop, progress, single/multiple, accepts/types, size limits
+- React `<ProjectFilesWidget />`: list all files for a project (Plugin API), pick one, and optionally auto-save to your app
 
 ## Installation
 
@@ -23,16 +24,16 @@ yarn add @thetechfossil/upfiles
 
 ## Server prerequisites
 
-Your server must expose a presign endpoint compatible with:
+Your Upfiles app must expose the Plugin API presign endpoint:
 
 - Method: `POST`
-- Path: `/api/upload/presigned-url` (default; configurable)
-- Body: `{ fileName, fileType, fileSize? }`
-- Response: `{ presignedUrl, fileKey, publicUrl }`
+- Path: `/api/plugin/upload/presigned-url` (default; configurable)
+- Body: `{ fileName, fileType, fileSize, folderPath?, projectId? }` (`fileSize` is required)
+- Response: `{ presignedUrl, fileKey, publicUrl, apiKeyId?, projectId? }`
 
-This repository already provides a Next.js route at `src/app/api/upload/presigned-url/route.ts`.
+This repository already provides a Next.js route at `src/app/api/plugin/upload/presigned-url/route.ts`.
 
-If your server requires auth, you may need cookies (`withCredentials`) or an Authorization header.
+For plugins/packages calling across origins, authenticate using an API key header as documented below. CORS must allow your plugin origin.
 
 ## Basic usage (React)
 
@@ -53,6 +54,13 @@ export default function Page() {
       }}
       dropzoneClassName="border border-dashed rounded-md p-6 cursor-pointer"
       buttonClassName="px-3 py-2 rounded bg-blue-600 text-white"
+      // Optional: pass clientOptions for cross-origin + API key auth
+      // clientOptions={{
+      //   baseUrl: 'https://YOUR_APP_HOST',
+      //   // or presignUrl: 'https://YOUR_APP_HOST/api/plugin/upload/presigned-url',
+      //   apiKey: process.env.NEXT_PUBLIC_UPFILES_API_KEY!,
+      //   apiKeyHeader: 'authorization', // or 'x-api-key' | 'x-up-api-key'
+      // }}
     />
   );
 }
@@ -65,17 +73,21 @@ import { UpfilesClient } from '@thetechfossil/upfiles';
 
 // Same-origin by default; only set these when needed:
 const client = new UpfilesClient({
-  // presignUrl: 'https://api.example.com/api/upload/presigned-url', // full override
-  // baseUrl: 'https://api.example.com', // used with presignPath
-  // presignPath: '/api/upload/presigned-url', // default
-  // withCredentials: true,
+  // presignUrl: 'https://YOUR_APP_HOST/api/plugin/upload/presigned-url', // full override
+  // baseUrl: 'https://YOUR_APP_HOST', // used with presignPath
+  // presignPath: '/api/plugin/upload/presigned-url', // default
+  // withCredentials: true, // for session routes (not typical for Plugin API)
+  // Provide API key for Plugin API auth:
+  // apiKey: 'upk_...'
+  // apiKeyHeader: 'authorization' // or 'x-api-key' | 'x-up-api-key'
 });
 
 async function upload(file) {
   const { presignedUrl, publicUrl } = await client.getPresignedUrl({
     fileName: file.name,
     fileType: file.type,
-    fileSize: file.size,
+    fileSize: file.size, // required
+    folderPath: 'my-plugin/uploads/',
   });
   const res = await client.uploadToS3(presignedUrl, file);
   if (!res.ok) throw new Error('Upload failed');
@@ -88,12 +100,17 @@ async function upload(file) {
 - `new UpfilesClient(options)`
   - `presignUrl` (optional): full absolute URL to presign endpoint. Highest priority.
   - `baseUrl` (optional): API base origin. Used with `presignPath`.
-  - `presignPath` (optional): relative path, default `/api/upload/presigned-url`.
-  - `headers` (optional): headers for your server, e.g. Authorization.
+  - `presignPath` (optional): relative path, default `/api/plugin/upload/presigned-url`.
+  - `headers` (optional): extra headers to send.
+  - `apiKey` (optional): API key value (e.g., `upk_...`).
+  - `apiKeyHeader` (optional): one of `'authorization' | 'x-api-key' | 'x-up-api-key'` (default `'authorization'`). If `'authorization'`, `Bearer` prefix is auto-added for `upk_...`.
   - `withCredentials` (optional): `true` to send cookies.
-  - Defaults: same-origin requests to `/api/upload/presigned-url`.
-- `client.getPresignedUrl({ fileName, fileType, fileSize? })`
+  - Defaults: same-origin requests to `/api/plugin/upload/presigned-url`.
+- `client.getPresignedUrl({ fileName, fileType, fileSize, projectId?, folderPath? })`
 - `client.uploadToS3(presignedUrl, file)`
+- `client.upload(file, { projectId?, folderPath?, fetchThumbnails? })` → returns `{ publicUrl, fileKey, fileName, fileType, fileSize, projectId?, apiKeyId?, thumbnails? }`
+- `client.getThumbnails(fileKey)` → returns `Thumbnail[]`
+- `client.getProjectFiles({ folderPath? })` → returns `FileListItem[]`
 
 - `<Uploader />` props
   - `clientOptions` (optional): same as `UpfilesClient` options (only needed for cross-origin or auth customization)
@@ -101,13 +118,81 @@ async function upload(file) {
   - `accept` (array of MIME patterns)
   - `maxFileSize` (bytes, default 100MB)
   - `maxFiles` (default 10)
+  - `fetchThumbnails` (boolean): if true, fetch thumbnails after upload via Plugin API
   - `onComplete(files)` and `onError(error)`
   - `className`, `buttonClassName`, `dropzoneClassName`
   - `children`: custom dropzone inner content
 
+### Thumbnails usage
+
+Your Upfiles app exposes `GET /api/plugin/thumbnails?fileKey=...` for plugins. Enable `fetchThumbnails` to auto-fetch after upload, or call `client.getThumbnails(fileKey)` yourself.
+
+Example with `client.upload`:
+
+```ts
+const result = await client.upload(file, { folderPath: 'my-plugin/', fetchThumbnails: true });
+console.log(result.thumbnails);
+```
+
+### List project files (Plugin API)
+
+Your Upfiles app exposes `GET /api/plugin/files?folderPath=...` for plugins (API key auth + CORS). The client can call it via `getProjectFiles`:
+
+```ts
+import { UpfilesClient } from '@thetechfossil/upfiles';
+
+const client = new UpfilesClient({
+  baseUrl: 'https://YOUR_APP_HOST',
+  apiKey: 'upk_...',
+  thumbnailsPath: '/api/plugin/thumbnails', // used to derive /api/plugin/files
+});
+
+const files = await client.getProjectFiles({ folderPath: 'optional/subfolder' });
+// [{ key, originalName, size, contentType, uploadedAt, url }, ...]
+```
+
+### `<ProjectFilesWidget />`
+
+Simple UI to fetch and select a file for the project tied to the API key. Emits the selection, and can optionally POST it to your backend.
+
+```tsx
+import { ProjectFilesWidget } from '@thetechfossil/upfiles';
+
+export default function PickFile() {
+  return (
+    <ProjectFilesWidget
+      clientOptions={{
+        baseUrl: 'https://YOUR_APP_HOST',
+        apiKey: process.env.NEXT_PUBLIC_UPFILES_API_KEY!,
+        apiKeyHeader: 'authorization',
+        thumbnailsPath: '/api/plugin/thumbnails',
+      }}
+      // Optional: filter within a folder
+      // folderPath="my-plugin/"
+
+      onSelect={(f) => {
+        // { name, key, url, size, contentType }
+        console.log('Selected:', f.name, f.key);
+      }}
+
+      // Optional: built-in save
+      // saveUrl="/api/files/save" // Your app route to persist selection
+      // onSave={async (f) => { await fetch('/api/files/save', { method: 'POST', body: JSON.stringify(f) }); }}
+      // onSaved={(result) => console.log('Saved!', result)}
+    />
+  );
+}
+```
+
 ## Notes
 
 - Dev with Vite: configure a proxy so `/api/*` maps to your backend (e.g., `http://localhost:4000`), then `<Uploader />` works with no config.
-- Ensure CORS where applicable (S3 bucket CORS; server CORS only when using cross-origin calls).
+- Ensure CORS where applicable (S3 bucket CORS; and set `PLUGIN_ALLOWED_ORIGINS` on your Upfiles app for cross-origin Plugin API calls).
 - For cross-origin with cookies (NextAuth), set `withCredentials: true` and configure your server to allow credentials.
-- Consider adding API token auth if distributing the SDK publicly.
+  Plugin API typically uses API keys instead of cookies.
+
+### Plugin endpoints provided by this repo
+
+- `POST /api/plugin/upload/presigned-url` – generate presigned S3 URL for upload
+- `GET /api/plugin/thumbnails?fileKey=...` – list thumbnails for a file
+- `GET /api/plugin/files?folderPath=...` – list project files (API key scoped), optional folder prefix

package/dist/index.d.mts

@@ -4,6 +4,34 @@ type PresignResponse = {
     presignedUrl: string;
     fileKey: string;
     publicUrl: string;
+    apiKeyId?: string;
+    projectId?: string;
+};
+type UploadedFileResult = {
+    publicUrl: string;
+    fileKey: string;
+    fileName: string;
+    fileType: string;
+    fileSize: number;
+    projectId?: string;
+    apiKeyId?: string;
+    thumbnails?: Thumbnail[];
+};
+type Thumbnail = {
+    id: string;
+    key: string;
+    url: string;
+    size: number;
+    sizeType?: string;
+    createdAt?: string;
+};
+type FileListItem = {
+    key: string;
+    originalName: string;
+    size: number;
+    contentType: string;
+    uploadedAt: string;
+    url: string;
 };
 type UpfilesClientOptions = {
     baseUrl?: string;
@@ -11,6 +39,9 @@ type UpfilesClientOptions = {
     presignUrl?: string;
     headers?: Record<string, string>;
     withCredentials?: boolean;
+    apiKey?: string;
+    apiKeyHeader?: 'authorization' | 'x-api-key' | 'x-up-api-key';
+    thumbnailsPath?: string;
 };
 declare class UpfilesClient {
     private baseUrl?;
@@ -18,15 +49,27 @@ declare class UpfilesClient {
     private presignUrl?;
     private headers?;
     private withCredentials?;
+    private apiKey?;
+    private apiKeyHeader;
+    private thumbnailsPath;
     constructor(opts: UpfilesClientOptions);
     getPresignedUrl(params: {
         fileName: string;
         fileType: string;
-        fileSize?: number;
+        fileSize: number;
         projectId?: string;
         folderPath?: string;
     }): Promise<PresignResponse>;
     uploadToS3(presignedUrl: string, file: File): Promise<Response>;
+    upload(file: File, extras?: {
+        projectId?: string;
+        folderPath?: string;
+        fetchThumbnails?: boolean;
+    }): Promise<UploadedFileResult>;
+    getThumbnails(fileKey: string): Promise<Thumbnail[]>;
+    getProjectFiles(params?: {
+        folderPath?: string;
+    }): Promise<FileListItem[]>;
 }
 
 type UploaderFile = {
@@ -40,6 +83,8 @@ type UploaderFile = {
     error?: string;
     publicUrl?: string;
     fileKey?: string;
+    projectId?: string;
+    apiKeyId?: string;
 };
 type UploaderProps = {
     clientOptions?: UpfilesClientOptions;
@@ -55,7 +100,33 @@ type UploaderProps = {
     buttonClassName?: string;
     dropzoneClassName?: string;
     children?: React.ReactNode;
+    fetchThumbnails?: boolean;
 };
 declare const Uploader: React.FC<UploaderProps>;
 
-export { type PresignResponse, UpfilesClient, type UpfilesClientOptions, Uploader, type UploaderFile, type UploaderProps };
+type ProjectFilesWidgetProps = {
+    clientOptions: UpfilesClientOptions;
+    folderPath?: string;
+    className?: string;
+    listClassName?: string;
+    itemClassName?: string;
+    onSelect: (file: {
+        name: string;
+        key: string;
+        url: string;
+        size: number;
+        contentType: string;
+    }) => void;
+    saveUrl?: string;
+    onSave?: (file: {
+        name: string;
+        key: string;
+        url: string;
+        size: number;
+        contentType: string;
+    }) => Promise<void> | void;
+    onSaved?: (result?: any) => void;
+};
+declare const ProjectFilesWidget: React.FC<ProjectFilesWidgetProps>;
+
+export { type FileListItem, type PresignResponse, ProjectFilesWidget, type ProjectFilesWidgetProps, type Thumbnail, UpfilesClient, type UpfilesClientOptions, type UploadedFileResult, Uploader, type UploaderFile, type UploaderProps };

package/dist/index.d.ts

@@ -4,6 +4,34 @@ type PresignResponse = {
     presignedUrl: string;
     fileKey: string;
     publicUrl: string;
+    apiKeyId?: string;
+    projectId?: string;
+};
+type UploadedFileResult = {
+    publicUrl: string;
+    fileKey: string;
+    fileName: string;
+    fileType: string;
+    fileSize: number;
+    projectId?: string;
+    apiKeyId?: string;
+    thumbnails?: Thumbnail[];
+};
+type Thumbnail = {
+    id: string;
+    key: string;
+    url: string;
+    size: number;
+    sizeType?: string;
+    createdAt?: string;
+};
+type FileListItem = {
+    key: string;
+    originalName: string;
+    size: number;
+    contentType: string;
+    uploadedAt: string;
+    url: string;
 };
 type UpfilesClientOptions = {
     baseUrl?: string;
@@ -11,6 +39,9 @@ type UpfilesClientOptions = {
     presignUrl?: string;
     headers?: Record<string, string>;
     withCredentials?: boolean;
+    apiKey?: string;
+    apiKeyHeader?: 'authorization' | 'x-api-key' | 'x-up-api-key';
+    thumbnailsPath?: string;
 };
 declare class UpfilesClient {
     private baseUrl?;
@@ -18,15 +49,27 @@ declare class UpfilesClient {
     private presignUrl?;
     private headers?;
     private withCredentials?;
+    private apiKey?;
+    private apiKeyHeader;
+    private thumbnailsPath;
     constructor(opts: UpfilesClientOptions);
     getPresignedUrl(params: {
         fileName: string;
         fileType: string;
-        fileSize?: number;
+        fileSize: number;
         projectId?: string;
         folderPath?: string;
     }): Promise<PresignResponse>;
     uploadToS3(presignedUrl: string, file: File): Promise<Response>;
+    upload(file: File, extras?: {
+        projectId?: string;
+        folderPath?: string;
+        fetchThumbnails?: boolean;
+    }): Promise<UploadedFileResult>;
+    getThumbnails(fileKey: string): Promise<Thumbnail[]>;
+    getProjectFiles(params?: {
+        folderPath?: string;
+    }): Promise<FileListItem[]>;
 }
 
 type UploaderFile = {
@@ -40,6 +83,8 @@ type UploaderFile = {
     error?: string;
     publicUrl?: string;
     fileKey?: string;
+    projectId?: string;
+    apiKeyId?: string;
 };
 type UploaderProps = {
     clientOptions?: UpfilesClientOptions;
@@ -55,7 +100,33 @@ type UploaderProps = {
     buttonClassName?: string;
     dropzoneClassName?: string;
     children?: React.ReactNode;
+    fetchThumbnails?: boolean;
 };
 declare const Uploader: React.FC<UploaderProps>;
 
-export { type PresignResponse, UpfilesClient, type UpfilesClientOptions, Uploader, type UploaderFile, type UploaderProps };
+type ProjectFilesWidgetProps = {
+    clientOptions: UpfilesClientOptions;
+    folderPath?: string;
+    className?: string;
+    listClassName?: string;
+    itemClassName?: string;
+    onSelect: (file: {
+        name: string;
+        key: string;
+        url: string;
+        size: number;
+        contentType: string;
+    }) => void;
+    saveUrl?: string;
+    onSave?: (file: {
+        name: string;
+        key: string;
+        url: string;
+        size: number;
+        contentType: string;
+    }) => Promise<void> | void;
+    onSaved?: (result?: any) => void;
+};
+declare const ProjectFilesWidget: React.FC<ProjectFilesWidgetProps>;
+
+export { type FileListItem, type PresignResponse, ProjectFilesWidget, type ProjectFilesWidgetProps, type Thumbnail, UpfilesClient, type UpfilesClientOptions, type UploadedFileResult, Uploader, type UploaderFile, type UploaderProps };

package/dist/index.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ProjectFilesWidget: () => ProjectFilesWidget,
   UpfilesClient: () => UpfilesClient,
   Uploader: () => Uploader
 });
@@ -29,19 +30,35 @@ module.exports = __toCommonJS(index_exports);
 var UpfilesClient = class {
   constructor(opts) {
     this.baseUrl = opts.baseUrl?.replace(/\/$/, "");
-    this.presignPath = opts.presignPath ?? "/api/upload/presigned-url";
+    this.presignPath = opts.presignPath ?? "/api/plugin/upload/presigned-url";
     this.presignUrl = opts.presignUrl;
     this.headers = opts.headers;
     this.withCredentials = opts.withCredentials;
+    this.apiKey = opts.apiKey;
+    this.apiKeyHeader = opts.apiKeyHeader ?? "authorization";
+    this.thumbnailsPath = opts.thumbnailsPath ?? "/api/plugin/thumbnails";
   }
   async getPresignedUrl(params) {
+    if (!params.fileName) throw new Error("fileName is required");
+    if (!params.fileType) throw new Error("fileType is required");
+    if (!params.fileSize || params.fileSize <= 0) throw new Error("fileSize must be > 0");
     const target = this.presignUrl ? this.presignUrl : this.baseUrl ? `${this.baseUrl}${this.presignPath}` : this.presignPath;
+    const headers = {
+      "content-type": "application/json",
+      ...this.headers || {}
+    };
+    if (this.apiKey) {
+      if (this.apiKeyHeader === "authorization") {
+        headers["authorization"] = this.apiKey.startsWith("upk_") ? `Bearer ${this.apiKey}` : this.apiKey;
+      } else if (this.apiKeyHeader === "x-api-key") {
+        headers["x-api-key"] = this.apiKey;
+      } else {
+        headers["x-up-api-key"] = this.apiKey;
+      }
+    }
     const res = await fetch(target, {
       method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        ...this.headers || {}
-      },
+      headers,
       credentials: this.withCredentials ? "include" : "same-origin",
       body: JSON.stringify(params)
     });
@@ -65,6 +82,92 @@ var UpfilesClient = class {
       }
     });
   }
+  // Convenience: perform full flow and return URL/path metadata for DB
+  async upload(file, extras) {
+    const presign = await this.getPresignedUrl({
+      fileName: file.name,
+      fileType: file.type || "application/octet-stream",
+      fileSize: file.size,
+      projectId: extras?.projectId,
+      folderPath: extras?.folderPath
+    });
+    const res = await this.uploadToS3(presign.presignedUrl, file);
+    if (!res.ok) {
+      throw new Error(`Upload failed with status ${res.status}`);
+    }
+    let thumbnails;
+    if (extras?.fetchThumbnails) {
+      try {
+        const t = await this.getThumbnails(presign.fileKey);
+        thumbnails = t;
+      } catch {
+      }
+    }
+    return {
+      publicUrl: presign.publicUrl,
+      fileKey: presign.fileKey,
+      fileName: file.name,
+      fileType: file.type,
+      fileSize: file.size,
+      projectId: presign.projectId,
+      apiKeyId: presign.apiKeyId,
+      thumbnails
+    };
+  }
+  async getThumbnails(fileKey) {
+    const target = this.baseUrl ? `${this.baseUrl}${this.thumbnailsPath}` : this.thumbnailsPath;
+    const url = `${target}?fileKey=${encodeURIComponent(fileKey)}`;
+    const headers = { ...this.headers || {} };
+    if (this.apiKey) {
+      if (this.apiKeyHeader === "authorization") {
+        headers["authorization"] = this.apiKey.startsWith("upk_") ? `Bearer ${this.apiKey}` : this.apiKey;
+      } else if (this.apiKeyHeader === "x-api-key") {
+        headers["x-api-key"] = this.apiKey;
+      } else {
+        headers["x-up-api-key"] = this.apiKey;
+      }
+    }
+    const res = await fetch(url, { method: "GET", headers, credentials: this.withCredentials ? "include" : "same-origin" });
+    if (!res.ok) {
+      let msg = "Failed to fetch thumbnails";
+      try {
+        const data2 = await res.json();
+        msg = data2.error || msg;
+      } catch {
+      }
+      throw new Error(msg);
+    }
+    const data = await res.json();
+    return data?.thumbnails ?? [];
+  }
+  async getProjectFiles(params) {
+    const basePath = this.thumbnailsPath.replace(/\/thumbnails$/, "");
+    const filesPath = `${basePath}/files`;
+    const target = this.baseUrl ? `${this.baseUrl}${filesPath}` : filesPath;
+    const url = params?.folderPath ? `${target}?folderPath=${encodeURIComponent(params.folderPath)}` : target;
+    const headers = { ...this.headers || {} };
+    if (this.apiKey) {
+      if (this.apiKeyHeader === "authorization") {
+        headers["authorization"] = this.apiKey.startsWith("upk_") ? `Bearer ${this.apiKey}` : this.apiKey;
+      } else if (this.apiKeyHeader === "x-api-key") {
+        headers["x-api-key"] = this.apiKey;
+      } else {
+        headers["x-up-api-key"] = this.apiKey;
+      }
+    }
+    const res = await fetch(url, { method: "GET", headers, credentials: this.withCredentials ? "include" : "same-origin" });
+    if (!res.ok) {
+      let msg = "Failed to fetch files";
+      try {
+        const data2 = await res.json();
+        msg = data2.error || msg;
+      } catch {
+      }
+      throw new Error(msg);
+    }
+    const data = await res.json();
+    return data?.files ?? [];
+  }
 };
 
 // src/Uploader.tsx
@@ -83,7 +186,8 @@ var Uploader = ({
   dropzoneClassName,
   children,
   projectId,
-  folderPath
+  folderPath,
+  fetchThumbnails
 }) => {
   const inputRef = (0, import_react.useRef)(null);
   const client = (0, import_react.useMemo)(() => new UpfilesClient(clientOptions ?? {}), [clientOptions]);
@@ -153,14 +257,31 @@ var Uploader = ({
         xhr.setRequestHeader("Content-Type", item.type || "application/octet-stream");
         xhr.send(item.file);
       });
+      let thumbs;
+      try {
+        if (fetchThumbnails) {
+          thumbs = await client.getThumbnails(presign.fileKey);
+        }
+      } catch {
+      }
       update({ status: "success", progress: 100, fileKey: presign.fileKey, publicUrl: presign.publicUrl });
-      return { ...item, status: "success", progress: 100, fileKey: presign.fileKey, publicUrl: presign.publicUrl };
+      return {
+        ...item,
+        status: "success",
+        progress: 100,
+        fileKey: presign.fileKey,
+        publicUrl: presign.publicUrl,
+        projectId: presign.projectId,
+        apiKeyId: presign.apiKeyId,
+        // @ts-ignore - allow downstream to access thumbs if present
+        thumbnails: thumbs
+      };
     } catch (err) {
       const message = err instanceof Error ? err.message : "Upload failed";
       update({ status: "error", error: message });
       throw err;
     }
-  }, [client]);
+  }, [client, projectId, folderPath, fetchThumbnails]);
   const uploadAll = (0, import_react.useCallback)(async () => {
     const targets = files.filter((f) => f.status === "pending");
     if (!targets.length) return;
@@ -261,8 +382,152 @@ var Uploader = ({
     ] })
   ] });
 };
+
+// src/ProjectFilesWidget.tsx
+var import_react2 = require("react");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var ProjectFilesWidget = ({
+  clientOptions,
+  folderPath,
+  className,
+  listClassName,
+  itemClassName,
+  onSelect,
+  saveUrl,
+  onSave,
+  onSaved
+}) => {
+  const client = (0, import_react2.useMemo)(() => new UpfilesClient(clientOptions ?? {}), [clientOptions]);
+  const [files, setFiles] = (0, import_react2.useState)([]);
+  const [loading, setLoading] = (0, import_react2.useState)(false);
+  const [error, setError] = (0, import_react2.useState)(null);
+  const [query, setQuery] = (0, import_react2.useState)("");
+  const [savingKey, setSavingKey] = (0, import_react2.useState)(null);
+  (0, import_react2.useEffect)(() => {
+    let cancelled = false;
+    const run = async () => {
+      setLoading(true);
+      setError(null);
+      try {
+        const data = await client.getProjectFiles({ folderPath });
+        if (!cancelled) setFiles(data);
+      } catch (e) {
+        if (!cancelled) setError(e?.message || "Failed to load files");
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    };
+    run();
+    return () => {
+      cancelled = true;
+    };
+  }, [client, folderPath]);
+  const visible = files.filter(
+    (f) => !query ? true : (f.originalName || "").toLowerCase().includes(query.toLowerCase())
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { style: { display: "flex", gap: 8, alignItems: "center", marginBottom: 8 }, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+        "input",
+        {
+          type: "text",
+          placeholder: "Search by filename...",
+          value: query,
+          onChange: (e) => setQuery(e.target.value),
+          style: { flex: 1, padding: 8, border: "1px solid #e5e7eb", borderRadius: 6 }
+        }
+      ),
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+        "button",
+        {
+          onClick: () => {
+            setQuery("");
+            (async () => {
+              setLoading(true);
+              setError(null);
+              try {
+                const data = await client.getProjectFiles({ folderPath });
+                setFiles(data);
+              } catch (e) {
+                setError(e?.message || "Failed to load files");
+              } finally {
+                setLoading(false);
+              }
+            })();
+          },
+          style: { padding: "8px 12px", border: "1px solid #e5e7eb", borderRadius: 6, background: "#fff" },
+          children: "Refresh"
+        }
+      )
+    ] }),
+    loading && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { style: { fontSize: 12, color: "#666" }, children: "Loading files\u2026" }),
+    error && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { style: { fontSize: 12, color: "#b91c1c" }, children: error }),
+    !loading && !error && /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("ul", { className: listClassName, style: { listStyle: "none", padding: 0, margin: 0, display: "grid", gap: 8 }, children: [
+      visible.map((f) => /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
+        "li",
+        {
+          className: itemClassName,
+          style: { border: "1px solid #e5e7eb", borderRadius: 8, padding: 10, display: "flex", justifyContent: "space-between", alignItems: "center" },
+          children: [
+            /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { style: { minWidth: 0 }, children: [
+              /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { style: { fontWeight: 500, overflow: "hidden", textOverflow: "ellipsis" }, children: f.originalName }),
+              /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { style: { fontSize: 12, color: "#666" }, children: [
+                (f.size / (1024 * 1024)).toFixed(2),
+                " MB \u2022 ",
+                f.contentType
+              ] })
+            ] }),
+            /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { style: { display: "flex", gap: 8, alignItems: "center" }, children: [
+              /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("a", { href: f.url, target: "_blank", rel: "noreferrer", style: { fontSize: 12, color: "#2563eb" }, children: "View" }),
+              /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+                "button",
+                {
+                  onClick: async () => {
+                    const selected = { name: f.originalName, key: f.key, url: f.url, size: f.size, contentType: f.contentType };
+                    onSelect(selected);
+                    if (typeof onSave === "function" || !!saveUrl) {
+                      try {
+                        setSavingKey(f.key);
+                        if (typeof onSave === "function") {
+                          await onSave(selected);
+                          onSaved?.();
+                        }
+                        if (saveUrl) {
+                          const res = await fetch(saveUrl, {
+                            method: "POST",
+                            headers: { "content-type": "application/json" },
+                            body: JSON.stringify(selected),
+                            credentials: "same-origin"
+                          });
+                          const data = await res.json().catch(() => void 0);
+                          if (!res.ok) throw new Error(data?.error || "Failed to save");
+                          onSaved?.(data);
+                        }
+                      } catch (e) {
+                        console.error("Save selection failed", e);
+                        alert(e?.message || "Failed to save");
+                      } finally {
+                        setSavingKey(null);
+                      }
+                    }
+                  },
+                  disabled: savingKey === f.key,
+                  style: { padding: "6px 10px", background: "#2563eb", color: "#fff", border: "1px solid #1d4ed8", borderRadius: 6, opacity: savingKey === f.key ? 0.7 : 1 },
+                  children: savingKey === f.key ? "Saving\u2026" : "Use"
+                }
+              )
+            ] })
+          ]
+        },
+        f.key
+      )),
+      visible.length === 0 && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("li", { style: { fontSize: 12, color: "#666" }, children: "No files found" })
+    ] })
+  ] });
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ProjectFilesWidget,
   UpfilesClient,
   Uploader
 });

package/dist/index.mjs

@@ -2,19 +2,35 @@
 var UpfilesClient = class {
   constructor(opts) {
     this.baseUrl = opts.baseUrl?.replace(/\/$/, "");
-    this.presignPath = opts.presignPath ?? "/api/upload/presigned-url";
+    this.presignPath = opts.presignPath ?? "/api/plugin/upload/presigned-url";
     this.presignUrl = opts.presignUrl;
     this.headers = opts.headers;
     this.withCredentials = opts.withCredentials;
+    this.apiKey = opts.apiKey;
+    this.apiKeyHeader = opts.apiKeyHeader ?? "authorization";
+    this.thumbnailsPath = opts.thumbnailsPath ?? "/api/plugin/thumbnails";
   }
   async getPresignedUrl(params) {
+    if (!params.fileName) throw new Error("fileName is required");
+    if (!params.fileType) throw new Error("fileType is required");
+    if (!params.fileSize || params.fileSize <= 0) throw new Error("fileSize must be > 0");
     const target = this.presignUrl ? this.presignUrl : this.baseUrl ? `${this.baseUrl}${this.presignPath}` : this.presignPath;
+    const headers = {
+      "content-type": "application/json",
+      ...this.headers || {}
+    };
+    if (this.apiKey) {
+      if (this.apiKeyHeader === "authorization") {
+        headers["authorization"] = this.apiKey.startsWith("upk_") ? `Bearer ${this.apiKey}` : this.apiKey;
+      } else if (this.apiKeyHeader === "x-api-key") {
+        headers["x-api-key"] = this.apiKey;
+      } else {
+        headers["x-up-api-key"] = this.apiKey;
+      }
+    }
     const res = await fetch(target, {
       method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        ...this.headers || {}
-      },
+      headers,
       credentials: this.withCredentials ? "include" : "same-origin",
       body: JSON.stringify(params)
     });
@@ -38,6 +54,92 @@ var UpfilesClient = class {
       }
     });
   }
+  // Convenience: perform full flow and return URL/path metadata for DB
+  async upload(file, extras) {
+    const presign = await this.getPresignedUrl({
+      fileName: file.name,
+      fileType: file.type || "application/octet-stream",
+      fileSize: file.size,
+      projectId: extras?.projectId,
+      folderPath: extras?.folderPath
+    });
+    const res = await this.uploadToS3(presign.presignedUrl, file);
+    if (!res.ok) {
+      throw new Error(`Upload failed with status ${res.status}`);
+    }
+    let thumbnails;
+    if (extras?.fetchThumbnails) {
+      try {
+        const t = await this.getThumbnails(presign.fileKey);
+        thumbnails = t;
+      } catch {
+      }
+    }
+    return {
+      publicUrl: presign.publicUrl,
+      fileKey: presign.fileKey,
+      fileName: file.name,
+      fileType: file.type,
+      fileSize: file.size,
+      projectId: presign.projectId,
+      apiKeyId: presign.apiKeyId,
+      thumbnails
+    };
+  }
+  async getThumbnails(fileKey) {
+    const target = this.baseUrl ? `${this.baseUrl}${this.thumbnailsPath}` : this.thumbnailsPath;
+    const url = `${target}?fileKey=${encodeURIComponent(fileKey)}`;
+    const headers = { ...this.headers || {} };
+    if (this.apiKey) {
+      if (this.apiKeyHeader === "authorization") {
+        headers["authorization"] = this.apiKey.startsWith("upk_") ? `Bearer ${this.apiKey}` : this.apiKey;
+      } else if (this.apiKeyHeader === "x-api-key") {
+        headers["x-api-key"] = this.apiKey;
+      } else {
+        headers["x-up-api-key"] = this.apiKey;
+      }
+    }
+    const res = await fetch(url, { method: "GET", headers, credentials: this.withCredentials ? "include" : "same-origin" });
+    if (!res.ok) {
+      let msg = "Failed to fetch thumbnails";
+      try {
+        const data2 = await res.json();
+        msg = data2.error || msg;
+      } catch {
+      }
+      throw new Error(msg);
+    }
+    const data = await res.json();
+    return data?.thumbnails ?? [];
+  }
+  async getProjectFiles(params) {
+    const basePath = this.thumbnailsPath.replace(/\/thumbnails$/, "");
+    const filesPath = `${basePath}/files`;
+    const target = this.baseUrl ? `${this.baseUrl}${filesPath}` : filesPath;
+    const url = params?.folderPath ? `${target}?folderPath=${encodeURIComponent(params.folderPath)}` : target;
+    const headers = { ...this.headers || {} };
+    if (this.apiKey) {
+      if (this.apiKeyHeader === "authorization") {
+        headers["authorization"] = this.apiKey.startsWith("upk_") ? `Bearer ${this.apiKey}` : this.apiKey;
+      } else if (this.apiKeyHeader === "x-api-key") {
+        headers["x-api-key"] = this.apiKey;
+      } else {
+        headers["x-up-api-key"] = this.apiKey;
+      }
+    }
+    const res = await fetch(url, { method: "GET", headers, credentials: this.withCredentials ? "include" : "same-origin" });
+    if (!res.ok) {
+      let msg = "Failed to fetch files";
+      try {
+        const data2 = await res.json();
+        msg = data2.error || msg;
+      } catch {
+      }
+      throw new Error(msg);
+    }
+    const data = await res.json();
+    return data?.files ?? [];
+  }
 };
 
 // src/Uploader.tsx
@@ -56,7 +158,8 @@ var Uploader = ({
   dropzoneClassName,
   children,
   projectId,
-  folderPath
+  folderPath,
+  fetchThumbnails
 }) => {
   const inputRef = useRef(null);
   const client = useMemo(() => new UpfilesClient(clientOptions ?? {}), [clientOptions]);
@@ -126,14 +229,31 @@ var Uploader = ({
         xhr.setRequestHeader("Content-Type", item.type || "application/octet-stream");
         xhr.send(item.file);
       });
+      let thumbs;
+      try {
+        if (fetchThumbnails) {
+          thumbs = await client.getThumbnails(presign.fileKey);
+        }
+      } catch {
+      }
       update({ status: "success", progress: 100, fileKey: presign.fileKey, publicUrl: presign.publicUrl });
-      return { ...item, status: "success", progress: 100, fileKey: presign.fileKey, publicUrl: presign.publicUrl };
+      return {
+        ...item,
+        status: "success",
+        progress: 100,
+        fileKey: presign.fileKey,
+        publicUrl: presign.publicUrl,
+        projectId: presign.projectId,
+        apiKeyId: presign.apiKeyId,
+        // @ts-ignore - allow downstream to access thumbs if present
+        thumbnails: thumbs
+      };
     } catch (err) {
       const message = err instanceof Error ? err.message : "Upload failed";
       update({ status: "error", error: message });
       throw err;
     }
-  }, [client]);
+  }, [client, projectId, folderPath, fetchThumbnails]);
   const uploadAll = useCallback(async () => {
     const targets = files.filter((f) => f.status === "pending");
     if (!targets.length) return;
@@ -234,7 +354,151 @@ var Uploader = ({
     ] })
   ] });
 };
+
+// src/ProjectFilesWidget.tsx
+import { useEffect, useMemo as useMemo2, useState as useState2 } from "react";
+import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+var ProjectFilesWidget = ({
+  clientOptions,
+  folderPath,
+  className,
+  listClassName,
+  itemClassName,
+  onSelect,
+  saveUrl,
+  onSave,
+  onSaved
+}) => {
+  const client = useMemo2(() => new UpfilesClient(clientOptions ?? {}), [clientOptions]);
+  const [files, setFiles] = useState2([]);
+  const [loading, setLoading] = useState2(false);
+  const [error, setError] = useState2(null);
+  const [query, setQuery] = useState2("");
+  const [savingKey, setSavingKey] = useState2(null);
+  useEffect(() => {
+    let cancelled = false;
+    const run = async () => {
+      setLoading(true);
+      setError(null);
+      try {
+        const data = await client.getProjectFiles({ folderPath });
+        if (!cancelled) setFiles(data);
+      } catch (e) {
+        if (!cancelled) setError(e?.message || "Failed to load files");
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    };
+    run();
+    return () => {
+      cancelled = true;
+    };
+  }, [client, folderPath]);
+  const visible = files.filter(
+    (f) => !query ? true : (f.originalName || "").toLowerCase().includes(query.toLowerCase())
+  );
+  return /* @__PURE__ */ jsxs2("div", { className, children: [
+    /* @__PURE__ */ jsxs2("div", { style: { display: "flex", gap: 8, alignItems: "center", marginBottom: 8 }, children: [
+      /* @__PURE__ */ jsx2(
+        "input",
+        {
+          type: "text",
+          placeholder: "Search by filename...",
+          value: query,
+          onChange: (e) => setQuery(e.target.value),
+          style: { flex: 1, padding: 8, border: "1px solid #e5e7eb", borderRadius: 6 }
+        }
+      ),
+      /* @__PURE__ */ jsx2(
+        "button",
+        {
+          onClick: () => {
+            setQuery("");
+            (async () => {
+              setLoading(true);
+              setError(null);
+              try {
+                const data = await client.getProjectFiles({ folderPath });
+                setFiles(data);
+              } catch (e) {
+                setError(e?.message || "Failed to load files");
+              } finally {
+                setLoading(false);
+              }
+            })();
+          },
+          style: { padding: "8px 12px", border: "1px solid #e5e7eb", borderRadius: 6, background: "#fff" },
+          children: "Refresh"
+        }
+      )
+    ] }),
+    loading && /* @__PURE__ */ jsx2("div", { style: { fontSize: 12, color: "#666" }, children: "Loading files\u2026" }),
+    error && /* @__PURE__ */ jsx2("div", { style: { fontSize: 12, color: "#b91c1c" }, children: error }),
+    !loading && !error && /* @__PURE__ */ jsxs2("ul", { className: listClassName, style: { listStyle: "none", padding: 0, margin: 0, display: "grid", gap: 8 }, children: [
+      visible.map((f) => /* @__PURE__ */ jsxs2(
+        "li",
+        {
+          className: itemClassName,
+          style: { border: "1px solid #e5e7eb", borderRadius: 8, padding: 10, display: "flex", justifyContent: "space-between", alignItems: "center" },
+          children: [
+            /* @__PURE__ */ jsxs2("div", { style: { minWidth: 0 }, children: [
+              /* @__PURE__ */ jsx2("div", { style: { fontWeight: 500, overflow: "hidden", textOverflow: "ellipsis" }, children: f.originalName }),
+              /* @__PURE__ */ jsxs2("div", { style: { fontSize: 12, color: "#666" }, children: [
+                (f.size / (1024 * 1024)).toFixed(2),
+                " MB \u2022 ",
+                f.contentType
+              ] })
+            ] }),
+            /* @__PURE__ */ jsxs2("div", { style: { display: "flex", gap: 8, alignItems: "center" }, children: [
+              /* @__PURE__ */ jsx2("a", { href: f.url, target: "_blank", rel: "noreferrer", style: { fontSize: 12, color: "#2563eb" }, children: "View" }),
+              /* @__PURE__ */ jsx2(
+                "button",
+                {
+                  onClick: async () => {
+                    const selected = { name: f.originalName, key: f.key, url: f.url, size: f.size, contentType: f.contentType };
+                    onSelect(selected);
+                    if (typeof onSave === "function" || !!saveUrl) {
+                      try {
+                        setSavingKey(f.key);
+                        if (typeof onSave === "function") {
+                          await onSave(selected);
+                          onSaved?.();
+                        }
+                        if (saveUrl) {
+                          const res = await fetch(saveUrl, {
+                            method: "POST",
+                            headers: { "content-type": "application/json" },
+                            body: JSON.stringify(selected),
+                            credentials: "same-origin"
+                          });
+                          const data = await res.json().catch(() => void 0);
+                          if (!res.ok) throw new Error(data?.error || "Failed to save");
+                          onSaved?.(data);
+                        }
+                      } catch (e) {
+                        console.error("Save selection failed", e);
+                        alert(e?.message || "Failed to save");
+                      } finally {
+                        setSavingKey(null);
+                      }
+                    }
+                  },
+                  disabled: savingKey === f.key,
+                  style: { padding: "6px 10px", background: "#2563eb", color: "#fff", border: "1px solid #1d4ed8", borderRadius: 6, opacity: savingKey === f.key ? 0.7 : 1 },
+                  children: savingKey === f.key ? "Saving\u2026" : "Use"
+                }
+              )
+            ] })
+          ]
+        },
+        f.key
+      )),
+      visible.length === 0 && /* @__PURE__ */ jsx2("li", { style: { fontSize: 12, color: "#666" }, children: "No files found" })
+    ] })
+  ] });
+};
 export {
+  ProjectFilesWidget,
   UpfilesClient,
   Uploader
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thetechfossil/upfiles",
-  "version": "0.1.1",
-  "description": "Lightweight client and React components to upload files to UpFiles API (presigned S3)",
+  "version": "0.3.0",
+  "description": "Lightweight client and React components for Upfiles Plugin API (presigned S3)",
   "license": "MIT",
   "author": "UpFiles",
   "repository": {
@@ -29,7 +29,7 @@
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "bun run build"
   },
   "peerDependencies": {
     "react": ">=18"