@thetechfossil/upfiles 0.3.0-beta → 0.3.1-beta

package/README.md

@@ -22,6 +22,44 @@ pnpm add @thetechfossil/upfiles
 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:
@@ -196,3 +234,271 @@ 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
+
+## 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);
+```
+
+### Image picker modal (with thumbnails)
+
+`ImagePickerDialog` lets users browse images (with thumbnails) and returns the original image URL for storage in your DB.
+
+```tsx
+import { useState } from 'react';
+import { ImagePickerDialog } 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>
+      <ImagePickerDialog
+        open={open}
+        onOpenChange={setOpen}
+        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>
+  );
+}
+```
+
+### Headless files utilities
+
+If you want to build your own modal, these helpers fetch files and thumbnails:
+
+```ts
+import {
+  fetchProjectFiles,
+  fetchFileThumbnails,
+  fetchProjectImagesWithThumbs,
+} from '@thetechfossil/upfiles';
+
+const clientOptions = {
+  baseUrl: process.env.NEXT_PUBLIC_UPFILES_APP_URL!,
+  apiKey: process.env.NEXT_PUBLIC_UPFILES_API_KEY!,
+  apiKeyHeader: 'authorization',
+};
+
+const files = await fetchProjectFiles(clientOptions, 'optional/folder/');
+const thumbs = await fetchFileThumbnails(clientOptions, files[0].key);
+const images = await fetchProjectImagesWithThumbs(clientOptions, { folderPath: 'optional/folder/', limitConcurrent: 6 });
+```
+
+### Connect using API key
+
+If you already have an API key, use `connectUsingApiKey` to create an authenticated client:
+
+```ts
+import { connectUsingApiKey } from '@thetechfossil/upfiles';
+
+const { apiKey, client } = await connectUsingApiKey({
+  baseUrl: process.env.NEXT_PUBLIC_UPFILES_APP_URL!,
+  apiKey: process.env.NEXT_PUBLIC_UPFILES_API_KEY!,
+  apiKeyHeader: 'authorization',
+});
+```
+
+## API Reference
+
+### Functions
+
+- `listProjects({ baseUrl, fetch? }) => Promise<Project[]>`
+- `createProject({ baseUrl, name, keyName?, fetch? }) => Promise<{ apiKey: string; projectId: string }>`
+- `connectProject({ baseUrl, projectId, keyName?, fetch? }) => Promise<{ apiKey: string }>`
+- `addApiKeyManually(apiKey) => { apiKey: string }`
+- `createClientWithKey(baseUrl, apiKey) => UpfilesClient`
+- `connectUsingApiKey({ baseUrl, apiKey, apiKeyHeader? }) => { apiKey: string; client: UpfilesClient }`
+- `fetchProjectFiles(clientOptions, folderPath?) => Promise<FileListItem[]>`
+- `fetchFileThumbnails(clientOptions, fileKey) => Promise<Thumbnail[]>`
+- `fetchProjectImagesWithThumbs(clientOptions, { folderPath?, limitConcurrent? }) => Promise<(FileListItem & { thumbnails?: Thumbnail[] })[]>`
+
+Types:
+
+```ts
+type Project = { id: string; name: string; createdAt?: string };
+```
+
+### `<ConnectProjectDialog />` props
+
+```ts
+type ConnectProjectDialogProps = {
+  baseUrl: string;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  onConnected: (apiKey: string, meta: { projectId?: string; source: 'existing' | 'new' | 'manual' }) => void;
+  fetchImpl?: typeof fetch; // optional override (testing)
+  title?: string;
+  description?: string;
+  className?: string;
+};
+```
+
+### `<ImagePickerDialog />` props
+
+```ts
+type ImagePickerDialogProps = {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  clientOptions: UpfilesClientOptions; // baseUrl + apiKey
+  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;
+};
+```
+
+## 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.

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import React from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 type PresignResponse = {
     presignedUrl: string;
@@ -129,4 +130,91 @@ type ProjectFilesWidgetProps = {
 };
 declare const ProjectFilesWidget: React.FC<ProjectFilesWidgetProps>;
 
-export { type FileListItem, type PresignResponse, ProjectFilesWidget, type ProjectFilesWidgetProps, type Thumbnail, UpfilesClient, type UpfilesClientOptions, type UploadedFileResult, Uploader, type UploaderFile, type UploaderProps };
+type ConnectProjectDialogProps = {
+    baseUrl: string;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    onConnected: (apiKey: string, meta: {
+        projectId?: string;
+        source: 'existing' | 'new' | 'manual';
+    }) => void;
+    fetchImpl?: typeof fetch;
+    title?: string;
+    description?: string;
+    className?: string;
+};
+declare function ConnectProjectDialog(props: ConnectProjectDialogProps): react_jsx_runtime.JSX.Element;
+
+type ConnectOptions = {
+    baseUrl: string;
+    fetch?: typeof fetch;
+};
+type Project = {
+    id: string;
+    name: string;
+    createdAt?: string;
+};
+declare function listProjects(opts: ConnectOptions): Promise<Project[]>;
+declare function createProject(opts: ConnectOptions & {
+    name: string;
+    keyName?: string;
+}): Promise<{
+    apiKey: string;
+    projectId: string;
+}>;
+declare function connectProject(opts: ConnectOptions & {
+    projectId: string;
+    keyName?: string;
+}): Promise<{
+    apiKey: string;
+}>;
+declare function addApiKeyManually(apiKey: string): {
+    apiKey: string;
+};
+declare function createClientWithKey(baseUrl: string, apiKey: string): UpfilesClient;
+declare function connectUsingApiKey(opts: {
+    baseUrl: string;
+    apiKey: string;
+    apiKeyHeader?: 'authorization' | 'x-api-key' | 'x-up-api-key';
+}): {
+    apiKey: string;
+    client: UpfilesClient;
+};
+
+declare function fetchProjectFiles(clientOptions: UpfilesClientOptions, folderPath?: string): Promise<FileListItem[]>;
+declare function fetchFileThumbnails(clientOptions: UpfilesClientOptions, fileKey: string): Promise<Thumbnail[]>;
+type ImageWithThumbs = FileListItem & {
+    thumbnails?: Thumbnail[];
+};
+declare function fetchProjectImagesWithThumbs(clientOptions: UpfilesClientOptions, opts?: {
+    folderPath?: string;
+    limitConcurrent?: number;
+}): Promise<ImageWithThumbs[]>;
+
+type ImagePickerDialogProps = {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    clientOptions: UpfilesClientOptions;
+    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;
+};
+declare function ImagePickerDialog(props: ImagePickerDialogProps): react_jsx_runtime.JSX.Element;
+
+export { type ConnectOptions, ConnectProjectDialog, type ConnectProjectDialogProps, type FileListItem, ImagePickerDialog, type ImagePickerDialogProps, type ImageWithThumbs, type PresignResponse, type Project, ProjectFilesWidget, type ProjectFilesWidgetProps, type Thumbnail, UpfilesClient, type UpfilesClientOptions, type UploadedFileResult, Uploader, type UploaderFile, type UploaderProps, addApiKeyManually, connectProject, connectUsingApiKey, createClientWithKey, createProject, fetchFileThumbnails, fetchProjectFiles, fetchProjectImagesWithThumbs, listProjects };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import React from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 type PresignResponse = {
     presignedUrl: string;
@@ -129,4 +130,91 @@ type ProjectFilesWidgetProps = {
 };
 declare const ProjectFilesWidget: React.FC<ProjectFilesWidgetProps>;
 
-export { type FileListItem, type PresignResponse, ProjectFilesWidget, type ProjectFilesWidgetProps, type Thumbnail, UpfilesClient, type UpfilesClientOptions, type UploadedFileResult, Uploader, type UploaderFile, type UploaderProps };
+type ConnectProjectDialogProps = {
+    baseUrl: string;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    onConnected: (apiKey: string, meta: {
+        projectId?: string;
+        source: 'existing' | 'new' | 'manual';
+    }) => void;
+    fetchImpl?: typeof fetch;
+    title?: string;
+    description?: string;
+    className?: string;
+};
+declare function ConnectProjectDialog(props: ConnectProjectDialogProps): react_jsx_runtime.JSX.Element;
+
+type ConnectOptions = {
+    baseUrl: string;
+    fetch?: typeof fetch;
+};
+type Project = {
+    id: string;
+    name: string;
+    createdAt?: string;
+};
+declare function listProjects(opts: ConnectOptions): Promise<Project[]>;
+declare function createProject(opts: ConnectOptions & {
+    name: string;
+    keyName?: string;
+}): Promise<{
+    apiKey: string;
+    projectId: string;
+}>;
+declare function connectProject(opts: ConnectOptions & {
+    projectId: string;
+    keyName?: string;
+}): Promise<{
+    apiKey: string;
+}>;
+declare function addApiKeyManually(apiKey: string): {
+    apiKey: string;
+};
+declare function createClientWithKey(baseUrl: string, apiKey: string): UpfilesClient;
+declare function connectUsingApiKey(opts: {
+    baseUrl: string;
+    apiKey: string;
+    apiKeyHeader?: 'authorization' | 'x-api-key' | 'x-up-api-key';
+}): {
+    apiKey: string;
+    client: UpfilesClient;
+};
+
+declare function fetchProjectFiles(clientOptions: UpfilesClientOptions, folderPath?: string): Promise<FileListItem[]>;
+declare function fetchFileThumbnails(clientOptions: UpfilesClientOptions, fileKey: string): Promise<Thumbnail[]>;
+type ImageWithThumbs = FileListItem & {
+    thumbnails?: Thumbnail[];
+};
+declare function fetchProjectImagesWithThumbs(clientOptions: UpfilesClientOptions, opts?: {
+    folderPath?: string;
+    limitConcurrent?: number;
+}): Promise<ImageWithThumbs[]>;
+
+type ImagePickerDialogProps = {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    clientOptions: UpfilesClientOptions;
+    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;
+};
+declare function ImagePickerDialog(props: ImagePickerDialogProps): react_jsx_runtime.JSX.Element;
+
+export { type ConnectOptions, ConnectProjectDialog, type ConnectProjectDialogProps, type FileListItem, ImagePickerDialog, type ImagePickerDialogProps, type ImageWithThumbs, type PresignResponse, type Project, ProjectFilesWidget, type ProjectFilesWidgetProps, type Thumbnail, UpfilesClient, type UpfilesClientOptions, type UploadedFileResult, Uploader, type UploaderFile, type UploaderProps, addApiKeyManually, connectProject, connectUsingApiKey, createClientWithKey, createProject, fetchFileThumbnails, fetchProjectFiles, fetchProjectImagesWithThumbs, listProjects };