@thetechfossil/upfiles 0.6.0 → 1.0.2

package/README.md

@@ -1,122 +1,449 @@
-# Upfiles Packages Plugin
+# @thetechfossil/upfiles
 
-A comprehensive package solution for managing projects and API keys in Upfiles applications.
+Lightweight JavaScript client and React component to upload files via a presigned S3 flow. Similar to UploadThing-like DX.
 
-## Overview
+## Documentation
 
-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.
+📚 **Full documentation available at:** [https://ttf-upfiles-docs.netlify.app/](https://ttf-upfiles-docs.netlify.app/)
 
-## Features
+For detailed API reference, guides, examples, and more information, visit the documentation site.
 
-- 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
+- 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
 ```
 
-## API Routes
+## 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);
 
-### Projects
+  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>
+  );
+}
+```
 
-- `GET /api/packages/projects` - List all projects for the current user
-- `POST /api/packages/projects` - Create a new project for the current user
+## Server prerequisites
 
-### API Keys
+Your Upfiles app must expose the Plugin API presign endpoint:
 
-- `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
+- 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? }`
 
-## Package Components
+This repository already provides a Next.js route at `src/app/api/plugin/upload/presigned-url/route.ts`.
 
-### 1. Dialog Component
+For plugins/packages calling across origins, authenticate using an API key header as documented below. CORS must allow your plugin origin.
 
-The `ProjectKeyDialog` component provides a complete UI for managing projects and API keys:
+## Basic usage (React)
 
 ```tsx
-import ProjectKeyDialog from "@thetechfossil/upfiles/packages/dialog/ProjectKeyDialog";
+import { Uploader } from '@thetechfossil/upfiles';
 
-function MyComponent() {
+export default function Page() {
   return (
-    <ProjectKeyDialog
-      userId="user-123"
-      onProjectSelected={(projectId) => {
-        // Handle project selection
+    <Uploader
+      multiple
+      accept={["image/*", "application/pdf"]}
+      maxFileSize={100 * 1024 * 1024}
+      onComplete={(files) => {
+        console.log('uploaded:', files);
       }}
-      onApiKeySaved={(apiKey) => {
-        // Handle API key creation
+      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'
+      // }}
     />
   );
 }
 ```
 
-### 2. Reusable Functions
+## Basic usage (vanilla JS)
 
-#### Project Management
+```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
-import {
-  listProjects,
-  createProject,
-  updateProject,
-  deleteProject,
-} from "@thetechfossil/upfiles/packages/projectManager";
+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
 
-// List projects
-const { projects } = await listProjects("user-123");
+- `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
 
-// Create project
-const newProject = await createProject("user-123", { name: "My Project" });
+## 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
 ```
 
-#### API Key Management
+### `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
-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",
+// 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 })
 });
 ```
 
-## Usage Examples
+### 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' });
 
-See `packages/examples/usageExample.ts` for detailed usage examples.
+// 3) Create a key for an existing project
+const key2 = await connectProject({ baseUrl, projectId: 'proj_123' });
 
-## Comprehensive Package Documentation
+// 4) Manual
+const manual = addApiKeyManually('upk_...');
 
-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)
+// 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
+};
+```
 
-## Integration
+### Image picker modal (Browse Mode)
 
-The package can be integrated into existing applications by:
+You can use `ImageManager` in `browse` mode to let users select existing images without the upload tab:
 
-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
+```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>
+  );
+}
+```
 
-## Security Notes
+## Reusing across multiple Next.js projects
 
-- 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
+- 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`.
 
-## License
+## Troubleshooting
 
-MIT
+- __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.