@thetechfossil/upfiles 0.5.0 → 1.0.0

package/README.md

@@ -1,414 +1,443 @@
-# @thetechfossil/upfiles
-
-Lightweight JavaScript client and React component to upload files via a presigned S3 flow. Similar to UploadThing-like DX.
-
-- 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
-
-```bash
-# Bun (recommended)
-bun add @thetechfossil/upfiles
-
-# npm
-npm install @thetechfossil/upfiles
-
-# pnpm
-pnpm add @thetechfossil/upfiles
-
-# yarn
-yarn add @thetechfossil/upfiles
-```
-
-## Server prerequisites
-
-Your Upfiles app must expose the Plugin API presign endpoint:
-
-- Method: `POST`
-- 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/plugin/upload/presigned-url/route.ts`.
-
-For plugins/packages calling across origins, authenticate using an API key header as documented below. CORS must allow your plugin origin.
-
-## Basic usage (React)
-
-```tsx
-import { Uploader } from '@thetechfossil/upfiles';
-
-export default function Page() {
-  return (
-    <Uploader
-      multiple
-      accept={["image/*", "application/pdf"]}
-      maxFileSize={100 * 1024 * 1024}
-      onComplete={(files) => {
-        console.log('uploaded:', files);
-      }}
-      onError={(err) => {
-        console.error(err);
-      }}
-      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'
-      // }}
-    />
-  );
-}
-```
-
-## Basic usage (vanilla JS)
-
-```ts
-import { UpfilesClient } from '@thetechfossil/upfiles';
-
-// Same-origin by default; only set these when needed:
-const client = new UpfilesClient({
-  // 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, // required
-    folderPath: 'my-plugin/uploads/',
-  });
-  const res = await client.uploadToS3(presignedUrl, file);
-  if (!res.ok) throw new Error('Upload failed');
-  return publicUrl;
-}
-```
-
-## API
-
-- `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/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/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)
-  - `multiple` (default true)
-  - `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; 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.
-  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
-
-## Full API Reference
-
-__UpfilesClient(options)__
-
-- __options.baseUrl?: string__
-  Base origin, for cross-origin Plugin API calls, e.g. `https://upfiles.example.com`. If omitted, requests are same-origin.
-- __options.presignPath?: string__
-  Relative path to the presign endpoint (default `/api/plugin/upload/presigned-url`). Used when `presignUrl` is not set.
-- __options.presignUrl?: string__
-  Full absolute URL. If provided, it overrides `baseUrl + presignPath`.
-- __options.headers?: Record<string,string>__
-  Extra headers to send with every request.
-- __options.withCredentials?: boolean__
-  If true, send cookies (useful for session-based routes). Plugin API typically uses API keys instead.
-- __options.apiKey?: string__
-  API key value (e.g., `upk_...`).
-- __options.apiKeyHeader?: 'authorization' | 'x-api-key' | 'x-up-api-key'__
-  Header to carry the API key. Default `'authorization'`. If set to `'authorization'` and the key starts with `upk_`, `Bearer ${key}` is auto-applied.
-- __options.thumbnailsPath?: string__
-  Relative path to thumbnails endpoint, default `/api/plugin/thumbnails`. Used to derive `/api/plugin/files`.
-
-Methods
-
-- __getPresignedUrl({ fileName, fileType, fileSize, projectId?, folderPath? }): Promise<PresignResponse>__
-  Validates inputs and POSTs to the presign endpoint. Returns `{ presignedUrl, fileKey, publicUrl, apiKeyId?, projectId? }`.
-- __uploadToS3(presignedUrl: string, file: File): Promise<Response>__
-  Executes the signed PUT request to S3. You are responsible for checking `res.ok`.
-- __upload(file: File, extras?: { projectId?, folderPath?, fetchThumbnails? }): Promise<UploadedFileResult>__
-  Convenience method: presign + PUT + optional thumbnails fetch. Returns `{ publicUrl, fileKey, fileName, fileType, fileSize, projectId?, apiKeyId?, thumbnails? }`.
-- __getThumbnails(fileKey: string): Promise<Thumbnail[]>__
-  Calls `GET /api/plugin/thumbnails?fileKey=...`.
-- __getProjectFiles({ folderPath? }?): Promise<FileListItem[]>__
-  Calls `GET /api/plugin/files?folderPath=...` (derived from `thumbnailsPath`). Returns metadata for each file.
-
-Types
-
-```ts
-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;
-};
-```
-
-## React Components
-
-__<Uploader />__ from `src/Uploader.tsx`
-
-- __clientOptions?: UpfilesClientOptions__
-  Supply `baseUrl`, `apiKey`, etc., only if doing cross-origin or custom auth.
-- __multiple?: boolean__ (default: true)
-- __accept?: string[]__
-  MIME patterns, default includes common image/video/audio/pdf/text/json.
-- __maxFileSize?: number__ (bytes; default: 100MB)
-- __maxFiles?: number__ (default: 10)
-- __projectId?: string__
-- __folderPath?: string__
-- __fetchThumbnails?: boolean__
-  After a successful upload, fetch thumbnails via Plugin API.
-- __onComplete?: (files: UploaderFile[]) => void__
-  Called with successful items.
-- __onError?: (error: Error) => void__
-- __className?, buttonClassName?, dropzoneClassName?__
-- __children?__: custom inner content for dropzone.
-
-Uploader item shape
-
-```ts
-type UploaderFile = {
-  id: string;
-  file: File;
-  name: string;
-  size: number;
-  type: string;
-  progress: number; // 0-100
-  status: 'pending' | 'uploading' | 'success' | 'error';
-  error?: string;
-  publicUrl?: string;
-  fileKey?: string;
-  projectId?: string;
-  apiKeyId?: string;
-  // thumbnails?: Thumbnail[] // added at runtime if fetchThumbnails
-};
-```
-
-Implementation notes
-
-- Uses `XMLHttpRequest` for the S3 PUT to expose upload progress.
-- Progress caps at 99% until completion; then sets to 100% on success.
-- Sets `Content-Type` header to file.type (or `application/octet-stream`).
-
-__<ProjectFilesWidget />__ from `src/ProjectFilesWidget.tsx`
-
-- __clientOptions: UpfilesClientOptions__
-  Provide `baseUrl` and `apiKey` (or `withCredentials`) for Plugin API.
-- __folderPath?: string__
-- __className?, listClassName?, itemClassName?__
-- __onSelect(file): void__
-  Receives `{ name, key, url, size, contentType }`.
-- __saveUrl?: string__
-  If set, the component will POST the selected file JSON to this URL (same-origin).
-- __onSave?: (file) => Promise<void> | void__
-- __onSaved?: (result?: any) => void__
-
-Behavior
-
-- Loads files via `client.getProjectFiles({ folderPath })` on mount and when refreshed.
-- Client-side search by filename.
-- Built-in "Use" action triggers `onSelect`, optional `onSave` and/or POST to `saveUrl`.
-
-## Configuration and Auth
-
-- __Same-origin__ usage needs no config. Ensure your app exposes the Plugin API routes documented above.
-- __Cross-origin plugins__ should:
-  - Set `baseUrl` to your Upfiles app origin.
-  - Provide `apiKey` and set `apiKeyHeader` as needed. If using `'authorization'` and key starts with `upk_`, `Bearer` is added automatically.
-  - Configure CORS on the Upfiles app to allow your plugin origin.
-- __Cookies with NextAuth or session routes__:
-  - Set `withCredentials: true` in `UpfilesClient` and allow credentials server-side. Plugin API is usually API-key based instead.
-
-## Error Handling
-
-- Network/API errors in `getPresignedUrl`, `getThumbnails`, `getProjectFiles` throw with a friendly message when possible.
-- In `<Uploader />`, per-file errors are surfaced via item `error` and `status: 'error'`, and the component continues uploading other files.
-- `uploadToS3` returns a Response; check `res.ok`. The convenience `upload()` will throw if the PUT fails.
-
-## Troubleshooting
-
-- __`Failed to get upload URL`__
-  - Check your presign route is reachable (correct `baseUrl`/`presignUrl`).
-  - Ensure `fileSize` is provided and > 0.
-  - Verify API key header and value; confirm CORS on the server.
-- __S3 PUT 403/SignatureDoesNotMatch__
-  - Do not modify headers other than `Content-Type`.
-  - Ensure the file name/type/size used for presign match the actual uploaded file.
-- __CORS errors__
-  - Allow your plugin origin on the Upfiles app for Plugin API paths and S3 bucket CORS for PUT/GET.
-- __Large files stall at 99%__
-  - Expected: progress caps at 99% until PUT resolves, then jumps to 100%.
-- __No files listed in ProjectFilesWidget__
-  - Confirm the API key belongs to a project with files.
-  - Ensure `thumbnailsPath` is correct so `/files` is derived properly.
-
-## FAQ
-
-- __Can I use it without React?__ Yes—use `UpfilesClient` directly (see vanilla example).
-- __How do I restrict uploads to a folder?__ Provide `folderPath` when presigning (`<Uploader folderPath="my-plugin/" />` or `client.upload(..., { folderPath })`).
-- __How do I associate uploads with a project?__ Provide `projectId` when presigning or via `client.upload(..., { projectId })`.
-- __Can I customize headers?__ Pass `headers` in `UpfilesClientOptions`.
-
-## Example: Minimal cross-origin plugin
-
-```tsx
-import { Uploader } from '@thetechfossil/upfiles';
-
-export default function Widget() {
-  return (
-    <Uploader
-      clientOptions={{
-        baseUrl: 'https://upfiles.example.com',
-        apiKey: process.env.NEXT_PUBLIC_UPFILES_API_KEY!,
-        apiKeyHeader: 'authorization',
-      }}
-      multiple
-      accept={['image/*']}
-      maxFileSize={20 * 1024 * 1024}
-      folderPath="my-plugin/"
-      fetchThumbnails
-      onComplete={(files) => console.log('Uploaded', files)}
-      onError={(e) => console.error(e)}
-    />
-  );
-}
-```
-
-## Development
-
-- Build: `bun run build`
-- Watch: `bun run dev`
-- Typecheck: `bun run typecheck`
-
-## License
-
-MIT UpFiles
+# @thetechfossil/upfiles
+
+Lightweight JavaScript client and React component to upload files via a presigned S3 flow. Similar to UploadThing-like DX.
+
+- 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
+
+```bash
+# Bun (recommended)
+bun add @thetechfossil/upfiles
+
+# npm
+npm install @thetechfossil/upfiles
+
+# pnpm
+pnpm add @thetechfossil/upfiles
+
+# yarn
+yarn add @thetechfossil/upfiles
+```
+
+## Quickstart
+
+```tsx
+import { Uploader, ConnectProjectDialog } from '@thetechfossil/upfiles';
+import { useState } from 'react';
+
+export default function Page() {
+  const [open, setOpen] = useState(false);
+  const [apiKey, setApiKey] = useState<string | null>(null);
+
+  return (
+    <div className="space-y-6">
+      <button className="px-3 py-2 rounded bg-blue-600 text-white" onClick={() => setOpen(true)}>
+        Connect to Upfiles
+      </button>
+
+      <Uploader
+        clientOptions={{
+          baseUrl: process.env.NEXT_PUBLIC_UPFILES_APP_URL!,
+          apiKey: apiKey ?? undefined, // set after connecting
+          apiKeyHeader: 'authorization',
+        }}
+        multiple
+        dropzoneClassName="border border-dashed rounded-md p-6 cursor-pointer"
+        buttonClassName="px-3 py-2 rounded bg-blue-600 text-white"
+      />
+
+      <ConnectProjectDialog
+        baseUrl={process.env.NEXT_PUBLIC_UPFILES_APP_URL!}
+        open={open}
+        onOpenChange={setOpen}
+        onConnected={(key) => setApiKey(key)}
+      />
+    </div>
+  );
+}
+```
+
+## Server prerequisites
+
+Your Upfiles app must expose the Plugin API presign endpoint:
+
+- Method: `POST`
+- 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/plugin/upload/presigned-url/route.ts`.
+
+For plugins/packages calling across origins, authenticate using an API key header as documented below. CORS must allow your plugin origin.
+
+## Basic usage (React)
+
+```tsx
+import { Uploader } from '@thetechfossil/upfiles';
+
+export default function Page() {
+  return (
+    <Uploader
+      multiple
+      accept={["image/*", "application/pdf"]}
+      maxFileSize={100 * 1024 * 1024}
+      onComplete={(files) => {
+        console.log('uploaded:', files);
+      }}
+      onError={(err) => {
+        console.error(err);
+      }}
+      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'
+      // }}
+    />
+  );
+}
+```
+
+## Basic usage (vanilla JS)
+
+```ts
+import { UpfilesClient } from '@thetechfossil/upfiles';
+
+// Same-origin by default; only set these when needed:
+const client = new UpfilesClient({
+  // 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, // required
+    folderPath: 'my-plugin/uploads/',
+  });
+  const res = await client.uploadToS3(presignedUrl, file);
+  if (!res.ok) throw new Error('Upload failed');
+  return publicUrl;
+}
+```
+
+## API
+
+- `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/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/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)
+  - `multiple` (default true)
+  - `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; 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.
+  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
+
+## Connect a project to get an API key
+
+This package ships a ready-made dialog built with Radix UI + Tailwind classes to help developers connect their project to your main Upfiles app and obtain an API key.
+
+### Install
+
+Your app must have Tailwind configured. The dialog uses Radix primitives (shadcn/ui compatible). Ensure the peer dependency is available in the host app:
+
+```bash
+bun add @thetechfossil/upfiles @radix-ui/react-dialog
+# or
+npm install @thetechfossil/upfiles @radix-ui/react-dialog
+```
+
+### `ConnectProjectDialog` (UI modal)
+
+Props:
+
+- `baseUrl`: your Upfiles app origin (e.g., `https://upfiles.example.com`).
+- `open`, `onOpenChange`: control the dialog.
+- `onConnected(apiKey, { projectId?, source })`: receives the plaintext API key and metadata.
+
+It presents three options:
+
+- Connect to existing project → lists projects via `GET /api/projects`, then creates a key via `POST /api/projects/:id/keys`.
+- Add API key manually → text input to paste an existing key.
+- Create new project → `POST /api/projects`, then `POST /api/projects/:id/keys`.
+
+```tsx
+import { useState } from 'react';
+import { ConnectProjectDialog } from '@thetechfossil/upfiles';
+
+export default function ConnectKeyButton() {
+  const [open, setOpen] = useState(false);
+  const [apiKey, setApiKey] = useState<string | null>(null);
+
+  return (
+    <div>
+      <button className="px-3 py-2 rounded bg-blue-600 text-white" onClick={() => setOpen(true)}>
+        Connect Upfiles
+      </button>
+
+      <ConnectProjectDialog
+        baseUrl={process.env.NEXT_PUBLIC_UPFILES_APP_URL!}
+        open={open}
+        onOpenChange={setOpen}
+        onConnected={(key, meta) => {
+          setApiKey(key);
+          // Persist the key in your own DB as needed (see below)
+          console.log('Connected via', meta.source, 'projectId', meta.projectId);
+        }}
+      />
+    </div>
+  );
+}
+```
+
+### Store the key in your own DB
+
+You control persistence. Example Next.js route handler to store an encrypted key for the current user:
+
+```ts
+// app/api/integrations/upfiles/key/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { prisma } from '@/lib/prisma';
+import { getServerSession } from 'next-auth';
+import { authOptions } from '@/lib/auth';
+
+export async function POST(req: NextRequest) {
+  const session = await getServerSession(authOptions as any);
+  const userId = (session as any)?.user?.id as string | undefined;
+  if (!userId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+
+  const { apiKey } = await req.json();
+  if (!apiKey) return NextResponse.json({ error: 'apiKey required' }, { status: 400 });
+
+  // TODO: encrypt before saving
+  await prisma.user.update({ where: { id: userId }, data: { upfilesApiKey: apiKey } });
+  return NextResponse.json({ ok: true });
+}
+```
+
+From `onConnected`, call this route to persist:
+
+```ts
+await fetch('/api/integrations/upfiles/key', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ apiKey })
+});
+```
+
+### Utility functions (no UI)
+
+If you prefer to build a custom UI, use the exported functions:
+
+```ts
+import {
+  listProjects,
+  createProject,
+  connectProject,
+  addApiKeyManually,
+  createClientWithKey,
+} from '@thetechfossil/upfiles';
+
+const baseUrl = 'https://upfiles.example.com';
+
+// 1) List existing projects (requires session cookie on baseUrl)
+const projects = await listProjects({ baseUrl });
+
+// 2) Create a new project and key
+const { apiKey, projectId } = await createProject({ baseUrl, name: 'My App' });
+
+// 3) Create a key for an existing project
+const key2 = await connectProject({ baseUrl, projectId: 'proj_123' });
+
+// 4) Manual
+const manual = addApiKeyManually('upk_...');
+
+// 5) Build an upload client with the key
+const client = createClientWithKey(baseUrl, apiKey);
+```
+
+### `<ImageManager />` props
+
+```ts
+type ImageManagerProps = {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  clientOptions: UpfilesClientOptions;
+  projectId?: string;
+  folderPath?: string;
+  title?: string;
+  description?: string;
+  className?: string;
+  gridClassName?: string;
+  onSelect: (image: {
+    url: string;
+    key: string;
+    originalName: string;
+    size: number;
+    contentType: string;
+    thumbnails?: { id: string; key: string; url: string; size: number; sizeType?: string }[];
+  }) => void;
+  onDelete?: (key: string) => Promise<void>;
+  deleteUrl?: string;
+  autoRecordToDb?: boolean;
+  fetchThumbnails?: boolean;
+  maxFileSize?: number;
+  maxFiles?: number;
+  mode?: 'full' | 'browse' | 'upload'; // default: 'full'
+  showDelete?: boolean; // default: true
+};
+```
+
+### Image picker modal (Browse Mode)
+
+You can use `ImageManager` in `browse` mode to let users select existing images without the upload tab:
+
+```tsx
+import { useState } from 'react';
+import { ImageManager } from '@thetechfossil/upfiles';
+
+export default function PickImage() {
+  const [open, setOpen] = useState(false);
+  return (
+    <div>
+      <button className="px-3 py-2 rounded bg-blue-600 text-white" onClick={() => setOpen(true)}>
+        Pick image
+      </button>
+      <ImageManager
+        open={open}
+        onOpenChange={setOpen}
+        mode="browse"
+        clientOptions={{
+          baseUrl: process.env.NEXT_PUBLIC_UPFILES_APP_URL!,
+          apiKey: process.env.NEXT_PUBLIC_UPFILES_API_KEY!,
+          apiKeyHeader: 'authorization',
+        }}
+        // folderPath="my-plugin/images/" // optional
+        onSelect={async (img) => {
+          // Persist original image URL in your DB
+          await fetch('/api/media/save', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ url: img.url, key: img.key }),
+          });
+        }}
+      />
+    </div>
+  );
+}
+```
+
+## Reusing across multiple Next.js projects
+
+- Install `@thetechfossil/upfiles` and `@radix-ui/react-dialog` in each project.
+- Set an environment variable like `NEXT_PUBLIC_UPFILES_APP_URL` to point all consumers to your main Upfiles app.
+- Each consumer stores its own copy of the API key in its DB, obtained via `ConnectProjectDialog`.
+
+## Troubleshooting
+
+- __401 Unauthorized when listing/creating projects__: The `projects` and `keys` endpoints require a signed-in session on the main app domain. Open the dialog from a page that can send cookies to `{baseUrl}` or run from the same origin; otherwise configure auth/CORS accordingly.
+- __CORS errors calling main app__: Ensure the main app allows your consumer origin in CORS and, if you use cookies, sets the correct `Access-Control-Allow-Credentials` headers and SameSite attributes.
+- __Uploads fail__: Verify S3 bucket CORS and that `POST /api/plugin/upload/presigned-url` is accessible from the consumer app.
+- __API key header__: Default is `Authorization: Bearer upk_...`. If your server expects a different header, set `apiKeyHeader: 'x-api-key' | 'x-up-api-key'` in `UpfilesClient` options.