@thetechfossil/upfiles 0.5.0 → 0.6.0

package/README.md

@@ -1,414 +1,122 @@
-# @thetechfossil/upfiles
+# Upfiles Packages Plugin
 
-Lightweight JavaScript client and React component to upload files via a presigned S3 flow. Similar to UploadThing-like DX.
+A comprehensive package solution for managing projects and API keys in Upfiles applications.
 
-- 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
+## Overview
+
+This package provides both a user-friendly dialog interface and reusable functions for managing projects and API keys. It allows developers to either use the pre-built dialog component or integrate the underlying logic directly into their applications.
+
+## Features
+
+- Multi-functional dialog for managing projects and API keys
+- Reusable functions for programmatic integration
+- Full CRUD operations for projects and API keys
+- Authentication-aware API interactions
+- TypeScript support with comprehensive type definitions
 
 ## Installation
 
 ```bash
-# Bun (recommended)
-bun add @thetechfossil/upfiles
-
-# npm
 npm install @thetechfossil/upfiles
+```
 
-# pnpm
-pnpm add @thetechfossil/upfiles
+## API Routes
 
-# yarn
-yarn add @thetechfossil/upfiles
-```
+### Projects
 
-## Server prerequisites
+- `GET /api/packages/projects` - List all projects for the current user
+- `POST /api/packages/projects` - Create a new project for the current user
 
-Your Upfiles app must expose the Plugin API presign endpoint:
+### API Keys
 
-- 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? }`
+- `GET /api/packages/projects/{projectId}/keys` - List API keys for a project
+- `POST /api/packages/projects/{projectId}/keys` - Create a new API key for a project
+- `DELETE /api/packages/projects/{projectId}/keys` - Revoke an API key
 
-This repository already provides a Next.js route at `src/app/api/plugin/upload/presigned-url/route.ts`.
+## Package Components
 
-For plugins/packages calling across origins, authenticate using an API key header as documented below. CORS must allow your plugin origin.
+### 1. Dialog Component
 
-## Basic usage (React)
+The `ProjectKeyDialog` component provides a complete UI for managing projects and API keys:
 
 ```tsx
-import { Uploader } from '@thetechfossil/upfiles';
+import ProjectKeyDialog from "@thetechfossil/upfiles/packages/dialog/ProjectKeyDialog";
 
-export default function Page() {
+function MyComponent() {
   return (
-    <Uploader
-      multiple
-      accept={["image/*", "application/pdf"]}
-      maxFileSize={100 * 1024 * 1024}
-      onComplete={(files) => {
-        console.log('uploaded:', files);
+    <ProjectKeyDialog
+      userId="user-123"
+      onProjectSelected={(projectId) => {
+        // Handle project selection
       }}
-      onError={(err) => {
-        console.error(err);
+      onApiKeySaved={(apiKey) => {
+        // Handle API key creation
       }}
-      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;
-}
-```
+### 2. Reusable Functions
 
-## 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`:
+#### Project Management
 
 ```ts
-const result = await client.upload(file, { folderPath: 'my-plugin/', fetchThumbnails: true });
-console.log(result.thumbnails);
+import {
+  listProjects,
+  createProject,
+  updateProject,
+  deleteProject,
+} from "@thetechfossil/upfiles/packages/projectManager";
+
+// List projects
+const { projects } = await listProjects("user-123");
+
+// Create project
+const newProject = await createProject("user-123", { name: "My Project" });
 ```
 
-### 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`:
+#### API Key Management
 
 ```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
+import {
+  listApiKeys,
+  createApiKey,
+  revokeApiKey,
+} from "@thetechfossil/upfiles/packages/apiKeyManager";
+
+// List API keys
+const { keys } = await listApiKeys("project-456");
+
+// Create API key
+const { key } = await createApiKey({
+  projectId: "project-456",
+  name: "CI Pipeline Key",
 });
-
-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
+## Usage Examples
 
-```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;
-};
-```
+See `packages/examples/usageExample.ts` for detailed usage examples.
 
-## 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
+## Comprehensive Package Documentation
 
-```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
-};
-```
+For detailed package documentation including installation instructions, configuration options, usage examples, available methods and functions, parameter specifications, return value descriptions, troubleshooting guides, best practices, and detailed explanations of all package features and capabilities, see: [`docs/PACKAGE_DOCUMENTATION.md`](docs/PACKAGE_DOCUMENTATION.md)
 
-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
+## Integration
 
-```tsx
-import { Uploader } from '@thetechfossil/upfiles';
+The package can be integrated into existing applications by:
 
-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)}
-    />
-  );
-}
-```
+1. Using the dialog component for user-facing interfaces
+2. Calling the reusable functions for programmatic operations
+3. Implementing custom UI components that use the same underlying logic
 
-## Development
+## Security Notes
 
-- Build: `bun run build`
-- Watch: `bun run dev`
-- Typecheck: `bun run typecheck`
+- API keys are only returned once during creation (plaintext version)
+- All operations are authenticated and scoped to the current user
+- Revoked keys are marked as inactive but remain in the database
 
 ## License
 
-MIT UpFiles
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thetechfossil/upfiles",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Lightweight client and React components for Upfiles Plugin API (presigned S3)",
   "license": "MIT",
   "author": "UpFiles",
@@ -28,7 +28,10 @@
     "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": "bun run build"
+    "prepublishOnly": "bun run build",
+    "todo:list": "node scripts/todo-manager.js list",
+    "todo:complete": "node scripts/todo-manager.js complete",
+    "todo:add": "node scripts/todo-manager.js add"
   },
   "peerDependencies": {
     "react": ">=18"