@thetechfossil/upfiles 0.4.0 → 0.5.0

package/README.md

@@ -196,3 +196,219 @@ export default function PickFile() {
 - `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thetechfossil/upfiles",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Lightweight client and React components for Upfiles Plugin API (presigned S3)",
   "license": "MIT",
   "author": "UpFiles",