@thetechfossil/upfiles 0.6.0 → 1.0.0

package/README.md

@@ -1,122 +1,443 @@
-# Upfiles Packages Plugin
-
-A comprehensive package solution for managing projects and API keys in Upfiles applications.
-
-## 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
-npm install @thetechfossil/upfiles
-```
-
-## API Routes
-
-### Projects
-
-- `GET /api/packages/projects` - List all projects for the current user
-- `POST /api/packages/projects` - Create a new project for the current user
-
-### API Keys
-
-- `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
-
-## Package Components
-
-### 1. Dialog Component
-
-The `ProjectKeyDialog` component provides a complete UI for managing projects and API keys:
-
-```tsx
-import ProjectKeyDialog from "@thetechfossil/upfiles/packages/dialog/ProjectKeyDialog";
-
-function MyComponent() {
-  return (
-    <ProjectKeyDialog
-      userId="user-123"
-      onProjectSelected={(projectId) => {
-        // Handle project selection
-      }}
-      onApiKeySaved={(apiKey) => {
-        // Handle API key creation
-      }}
-    />
-  );
-}
-```
-
-### 2. Reusable Functions
-
-#### Project Management
-
-```ts
-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" });
-```
-
-#### API Key Management
-
-```ts
-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",
-});
-```
-
-## Usage Examples
-
-See `packages/examples/usageExample.ts` for detailed usage examples.
-
-## Comprehensive Package Documentation
-
-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)
-
-## Integration
-
-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
-
-## Security Notes
-
-- 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
+# @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.