@everystack/mcp 0.2.3 → 0.3.0

package/dist/handler-options.md

@@ -0,0 +1,114 @@
+# Handler Options Reference
+
+> Complete reference for `createHandler(db, schema, options)` from `@everystack/api/handler`.
+
+## When to Use
+Read this when configuring the PostgREST handler for a V2+ app. Every option is optional -- start minimal and add as needed.
+
+## Setup
+
+```typescript
+import { createHandler } from '@everystack/api/handler';
+import * as schema from '../db/schema';
+
+const handler = createHandler(db, schema, {
+  basePath: '/api',  // Strip this prefix from incoming URLs
+  // ... options below
+});
+```
+
+Returns `(request: Request) => Promise<Response>`.
+
+## Options
+
+### auth
+```typescript
+auth: {
+  verifyToken: async (token: string) => payload | null,  // Required for auth
+  publicRoutes: ['GET'],       // Methods that skip token verification
+  publicRpc: ['health'],       // RPC functions that skip all auth (token + client)
+  roleHierarchy: ['public', 'authenticated', 'admin'],  // For RPC role gates
+  roleField: 'role',           // JWT field containing user's role
+  onAuthenticated: (user) => {},  // Callback after successful auth
+  // Client credentials (two-tier auth)
+  verifyClient: async (clientId, clientSecret, referer?) => client | null,
+  clientHeaders: { id: 'X-Client-Id', secret: 'X-Client-Secret' },
+  onClientAuthenticated: (client) => {},
+}
+```
+
+### pgSettings (RLS)
+```typescript
+pgSettings: (user, client) => ({
+  role: user?.role === 'admin' ? 'admin' : user ? 'authenticated' : 'anon',
+  'request.jwt.claims': JSON.stringify(user || { role: 'anon' }),
+  'app.user_id': String(user?.sub || ''),
+})
+```
+The `role` key triggers `SET LOCAL ROLE`. All other keys use `set_config(key, value, true)`. Everything is LOCAL scope (resets when transaction ends).
+
+### relations
+```typescript
+relations: {
+  posts: {
+    author: { table: 'users', from: 'authorId', to: 'id' },         // many-to-one
+    comments: { table: 'comments', from: 'id', to: 'postId', many: true },  // one-to-many
+  },
+}
+```
+Enables `?select=*,author(*)` embedding. Resolved via batched `WHERE IN` (no N+1).
+
+### rpc
+```typescript
+rpc: {
+  health: async (body) => ({ status: 'ok' }),                    // Function syntax
+  timeline: { fn: async (body, user) => {}, role: 'authenticated' },  // Object + role
+  admin_stats: { fn: async (body, user) => {}, role: 'admin' },
+}
+```
+Function syntax uses publicRpc/publicRoutes rules. Object syntax enforces role requirement.
+
+### hooks
+```typescript
+hooks: {
+  posts: {
+    beforeCreate: async (body, user, client) => ({ ...body, authorId: user?.sub }),
+    afterCreate: async (row, user, client) => {},
+    beforeUpdate: async (body, user, client) => body,
+    afterUpdate: async (rows, user, client) => {},
+    beforeDelete: async (user, client) => {},
+    afterDelete: async (rows, user, client) => {},
+  },
+}
+```
+`beforeCreate`/`beforeUpdate` can modify the body by returning a new object.
+
+### Access Control
+```typescript
+exposedTables: ['posts', 'profiles'],          // 404 for unlisted tables
+hiddenColumns: { users: ['passwordHash'] },     // Strip from all responses
+protectedFields: { profiles: ['role'] },        // Strip from incoming writes
+rowOwnership: { posts: { column: 'authorId', userField: 'sub' } },  // Scope writes to owner
+```
+
+### Safety Limits
+```typescript
+maxEmbedDepth: 3,     // Max relation nesting depth (default: 3)
+maxLimit: 1000,        // Max ?limit= value (default: 10000)
+```
+
+### Other
+```typescript
+softDelete: { column: 'deletedAt', tables: ['posts'] },  // DELETE -> UPDATE SET deletedAt
+naming: 'snake_case',  // Response key format ('camelCase' default)
+```
+
+## Gotchas
+
+- `pgSettings` wraps every query in a transaction. Without it, queries execute directly (no RLS).
+- `hiddenColumns` strips AFTER query execution. Columns are still in the SQL result, just removed from JSON.
+- `protectedFields` strips BEFORE hooks run. Hooks never see protected fields.
+- `exposedTables` doesn't affect RPC endpoints.
+- `rowOwnership` only affects PATCH and DELETE. Reads are governed by RLS.
+- The `role` value in pgSettings is validated against `^[a-zA-Z_][a-zA-Z0-9_]*$`.
+- DELETE without filters returns 400 (safety). Always include at least one filter.

package/dist/images.md

@@ -0,0 +1,93 @@
+# Image Processing
+
+> On-demand Sharp image processing on Lambda. Import from `@everystack/images`.
+
+## When to Use
+Read this when adding image resizing, format conversion, or variant generation (V3).
+
+## Setup
+
+```typescript
+// server/image.ts
+import { createImageHandler } from '@everystack/server/image';
+
+export const handler = createImageHandler({
+  bucket: Resource.Media.name,
+  pathPrefix: '/media/',
+});
+```
+
+## URL-based Processing
+
+Images are processed on-the-fly via query parameters:
+
+```
+/media/photo.jpg?w=400&h=300&fit=cover&fm=webp&q=80
+```
+
+| Parameter | Description | Values |
+|-----------|-------------|--------|
+| `w` | Width | pixels |
+| `h` | Height | pixels |
+| `fit` | Resize mode | `cover`, `contain`, `fill`, `inside`, `outside` |
+| `fm` | Output format | `webp`, `avif`, `jpeg`, `png` |
+| `q` | Quality | 1-100 |
+
+## Variant Generation
+
+Pre-generate variants via background jobs:
+
+```typescript
+import { generateVariants } from '@everystack/images/jobs';
+
+await publishJob('image:process', {
+  key: 'uploads/photo.jpg',
+  variants: [
+    { name: 'thumb', width: 150, height: 150, fit: 'cover' },
+    { name: 'large', width: 1200, format: 'webp', quality: 85 },
+  ],
+});
+```
+
+## EXIF Extraction
+
+```typescript
+import { extractExif } from '@everystack/images';
+
+const exif = await extractExif(buffer);
+// { width, height, orientation, gps, camera, ... }
+```
+
+## Schema
+
+```typescript
+import { imagesSchema } from '@everystack/images/schema';
+// Adds: image_variants table tracking generated variants
+```
+
+## S3 Origin Cache
+
+CloudFront caches are per-region. Enable `s3Cache` to persist rendered images to S3 so the first Sharp render is the last, globally:
+
+```typescript
+export const handler = createImageHandler({
+  bucket: Resource.Media.name,
+  s3Cache: { enabled: true },
+});
+```
+
+Cache keys are deterministic from parsed params. Add a 30-day lifecycle rule on the `cache/` prefix to auto-expire stale renders. To clean up immediately when an original is deleted:
+
+```typescript
+import { deleteImageCache } from '@everystack/server/image';
+await deleteImageCache(bucket, 'uploads/photo.jpg');
+```
+
+See `docs/caching.md` for full setup.
+
+## Gotchas
+
+- Sharp runs on Lambda ARM64 (uses Lambda layer or bundled binary)
+- First request for a variant is slow (processing), subsequent are cached by CloudFront and S3
+- With `s3Cache` enabled, Sharp runs once per variant globally (not once per CloudFront region)
+- AVIF encoding is slower than WebP but produces smaller files