@thetechfossil/upfiles 0.4.0 → 0.6.0

package/README.md

@@ -1,198 +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 />`
+## Usage Examples
 
-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.
+See `packages/examples/usageExample.ts` for detailed usage examples.
 
-```tsx
-import { ProjectFilesWidget } from '@thetechfossil/upfiles';
+## Comprehensive Package Documentation
 
-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/"
+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)
 
-      onSelect={(f) => {
-        // { name, key, url, size, contentType }
-        console.log('Selected:', f.name, f.key);
-      }}
+## Integration
 
-      // 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)}
-    />
-  );
-}
-```
+The package can be integrated into existing applications by:
+
+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
 
-## Notes
+## Security 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.
+- 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
 
-### Plugin endpoints provided by this repo
+## License
 
-- `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
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thetechfossil/upfiles",
-  "version": "0.4.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"