@everystack/api 0.1.0

package/README.md

@@ -0,0 +1,333 @@
+# @everystack/api
+
+PostgREST-compatible HTTP handler and typed fetch client for Drizzle ORM.
+
+## Install
+
+```bash
+pnpm add @everystack/api drizzle-orm
+```
+
+## Entry Points
+
+| Import | Description |
+|--------|-------------|
+| `@everystack/api/handler` | Server-side PostgREST handler |
+| `@everystack/api/client` | Client-side typed fetch client |
+
+## Handler
+
+Creates a Web Standard `(Request) => Promise<Response>` handler from a Drizzle database instance and schema. Works with Expo Router API routes, Cloudflare Workers, Bun, Deno, or any platform supporting the Request/Response interface.
+
+```typescript
+import { createHandler } from '@everystack/api/handler';
+import { db } from './db';
+import * as schema from './db/schema';
+
+const handler = createHandler(db, schema);
+```
+
+### Mounting as an Expo Router API Route
+
+```typescript
+// app/api/[...path]+api.ts
+import { createHandler } from '@everystack/api/handler';
+import { db } from '../../db';
+import * as schema from '../../db/schema';
+
+const handler = createHandler(db, schema, { basePath: '/api' });
+
+export function GET(request: Request) { return handler(request); }
+export function POST(request: Request) { return handler(request); }
+export function PATCH(request: Request) { return handler(request); }
+export function DELETE(request: Request) { return handler(request); }
+```
+
+### Handler Options
+
+```typescript
+createHandler(db, schema, {
+  basePath: '/api',
+
+  auth: {
+    verifyToken: async (token) => verifyJWT(token),
+    publicRoutes: ['GET'],
+    publicRpc: ['health', 'search'],
+    onAuthenticated: (user) => {},
+
+    // Role-based access control
+    roles: {
+      posts: { read: 'public', write: 'authenticated' },
+      admin_logs: { read: 'admin', write: 'admin' },
+      '*': { read: 'authenticated', write: 'authenticated' },
+    },
+    roleHierarchy: ['public', 'authenticated', 'moderator', 'admin'],
+    roleField: 'role',
+
+    // Client credentials (two-tier auth)
+    verifyClient: async (clientId, clientSecret) => lookupClient(clientId, clientSecret),
+    clientHeaders: { id: 'X-Client-Id', secret: 'X-Client-Secret' },
+    onClientAuthenticated: (client) => {},
+  },
+
+  rpc: {
+    async timeline(body, user, client) {
+      return db.query.posts.findMany({ limit: 20 });
+    },
+  },
+
+  relations: {
+    posts: {
+      author: { table: 'users', from: 'authorId', to: 'id' },
+      comments: { table: 'comments', from: 'id', to: 'postId', many: true },
+    },
+  },
+
+  softDelete: {
+    column: 'deletedAt',
+    tables: ['posts', 'comments'],
+  },
+
+  pgSettings: (user, client) => ({
+    'request.jwt.claims': JSON.stringify(user || { role: 'anon' }),
+    'app.user_id': String(user?.sub || ''),
+  }),
+
+  hooks: {
+    posts: {
+      beforeCreate: async (body, user, client) => ({ ...body, authorId: user?.sub }),
+      afterCreate: async (row, user, client) => { /* notify */ },
+      beforeUpdate: async (body, user, client) => body,
+      afterUpdate: async (rows, user, client) => {},
+      beforeDelete: async (user, client) => {},
+      afterDelete: async (rows, user, client) => {},
+    },
+  },
+
+  naming: 'snake_case', // or 'camelCase' (default)
+});
+```
+
+### Row-Level Security (pgSettings)
+
+When `pgSettings` is provided, every CRUD query is wrapped in a PostgreSQL transaction with `set_config()` calls. This injects session variables that RLS policies can reference via `current_setting()`. The values are LOCAL to the transaction — they never leak across pooled connections. When not provided, queries execute directly without wrapper.
+
+### Role-Based Access Control (RBAC)
+
+When `auth.roles` is configured, each table route checks the user's role against the required role for that HTTP method. Resolution: `roles[tableName]` → `roles['*']` → `null` (falls back to `publicRoutes`). Special roles: `'public'` (no token needed), `'authenticated'` (any valid JWT). Error codes: 401 (no/invalid token), 403 (insufficient role).
+
+### Naming Convention
+
+The `naming` option controls how keys are transformed at the API boundary:
+- `'snake_case'`: Accept snake_case inbound, return snake_case outbound. POST/PATCH bodies map snake_case → camelCase for Drizzle.
+- `'camelCase'` or omitted: Use Drizzle property names as-is.
+
+Column resolution is bidirectional: `?author_id=eq.5` resolves to `authorId` automatically, even without the `naming` option.
+
+### Query Protocol
+
+The handler implements the PostgREST query protocol:
+
+**Filters** (`?column=operator.value`):
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `eq` | Equals | `?status=eq.published` |
+| `neq` | Not equals | `?role=neq.admin` |
+| `gt` / `gte` | Greater than | `?age=gt.18` |
+| `lt` / `lte` | Less than | `?price=lt.100` |
+| `like` | Pattern match | `?name=like.*smith*` |
+| `ilike` | Case-insensitive pattern | `?email=ilike.*@gmail.com` |
+| `in` | In set | `?id=in.(1,2,3)` |
+| `is` | Null check | `?deletedAt=is.null` |
+
+**Negation** (`not.` prefix): `?status=not.eq.draft`, `?tags=not.in.(a,b)`, `?deletedAt=not.is.null`
+
+**Logical groups**:
+- `?or=(status.eq.draft,status.eq.pending)` — OR conditions
+- `?and=(price.gte.10,price.lte.100)` — explicit AND group
+- Combine with regular filters: `?category=eq.electronics&or=(status.eq.draft,status.eq.pending)`
+
+**Aggregates** (PostgREST `column.function()` syntax):
+- `?select=count()` — count all rows
+- `?select=platform,total:amount.sum()` — GROUP BY with alias
+- Supported: `count()`, `sum()`, `avg()`, `min()`, `max()`
+
+**JSON path filtering**: `?metadata->>theme=eq.dark`, `?data->settings->>mode=eq.compact`
+
+**Column selection**: `?select=id,title,author(name,email)`
+
+**Relation embedding**: `?select=*,author(*),comments(body)`
+
+**Ordering**: `?order=createdAt.desc`
+
+**Pagination**: `?limit=10&offset=20`
+
+**Exact count**: Send `Prefer: count=exact` header to get `Content-Range: 0-9/42`
+
+**Mutations**:
+- `POST /table` — Insert (returns created row, 201)
+- `PATCH /table?id=eq.1` — Update matching rows (200)
+- `DELETE /table?id=eq.1` — Delete matching rows (requires filter, 200)
+
+**RPC**: `POST /rpc/function_name` with JSON body
+
+## Client
+
+Pure fetch client with zero React dependency. Works in any JavaScript runtime.
+
+```typescript
+import { createClient } from '@everystack/api/client';
+
+const api = createClient({
+  baseUrl: 'https://myapp.com/api',
+  headers: { 'X-Custom': 'value' },
+  getToken: () => localStorage.getItem('token'),
+  onTokenExpired: async () => {
+    const { token } = await refreshToken();
+    return token;
+  },
+  clientCredentials: {
+    id: 'my-app-id',
+    secret: 'my-app-secret',
+  },
+});
+```
+
+### Querying Data
+
+```typescript
+// List with filters
+const { data, error } = await api
+  .from('posts')
+  .eq('status', 'published')
+  .order('createdAt', 'desc')
+  .limit(10)
+  .execute();
+
+// Single record
+const { data: post } = await api
+  .from('posts')
+  .eq('id', '123')
+  .single();
+
+// With exact count
+const { data: posts, total } = await api
+  .from('posts')
+  .limit(20)
+  .executeWithCount();
+
+// Column selection + relation embedding
+const { data } = await api
+  .from('posts')
+  .select('id,title,author(name)')
+  .execute();
+
+// Negation
+const { data } = await api
+  .from('posts')
+  .notEq('status', 'draft')
+  .notIn('category', ['spam', 'archived'])
+  .execute();
+
+// Logical groups
+const { data } = await api
+  .from('posts')
+  .eq('active', 'true')
+  .or('status.eq.draft,status.eq.pending')
+  .execute();
+
+// Aggregates
+const { data } = await api
+  .from('transactions')
+  .select('platform,total:amount.sum()')
+  .execute();
+```
+
+### Mutations
+
+```typescript
+// Insert
+const { data } = await api.from('posts').insert({
+  title: 'Hello',
+  content: 'World',
+});
+
+// Update
+const { data } = await api
+  .from('posts')
+  .eq('id', '123')
+  .update({ title: 'Updated' });
+
+// Delete
+const { data } = await api
+  .from('posts')
+  .eq('id', '123')
+  .remove();
+```
+
+### Filter Methods
+
+All filter methods return the builder for chaining:
+
+```typescript
+// Standard operators
+.eq(column, value)      // Equals
+.neq(column, value)     // Not equals
+.gt(column, value)      // Greater than
+.gte(column, value)     // Greater or equal
+.lt(column, value)      // Less than
+.lte(column, value)     // Less or equal
+.like(column, value)    // LIKE pattern
+.ilike(column, value)   // Case-insensitive LIKE
+.is(column, value)      // IS NULL check
+.in(column, values[])   // IN array
+
+// Negation operators
+.notEq(column, value)   // NOT equal
+.notNeq(column, value)  // NOT not-equal
+.notGt(column, value)   // NOT greater than
+.notGte(column, value)  // NOT greater or equal
+.notLt(column, value)   // NOT less than
+.notLte(column, value)  // NOT less or equal
+.notLike(column, value) // NOT LIKE
+.notIlike(column, value)// NOT ILIKE
+.notIs(column, value)   // IS NOT NULL
+.notIn(column, values[])// NOT IN array
+
+// Logical groups
+.or(expression)         // OR group: .or('status.eq.draft,status.eq.pending')
+.and(expression)        // AND group: .and('price.gte.10,price.lte.100')
+```
+
+### Token Refresh
+
+The client automatically retries on 401 responses using `onTokenExpired`. Concurrent 401s are deduplicated — only one refresh runs at a time.
+
+## Exported Types
+
+```typescript
+import type {
+  AuthConfig, RoleConfig, RelationConfig, SoftDeleteConfig,
+  MutationEvent, HookConfig, HandlerOptions,
+} from '@everystack/api/handler';
+
+import type {
+  ClientOptions, ClientError, ClientResponse,
+  CountResponse, QueryBuilder, Client,
+} from '@everystack/api/client';
+```
+
+## Peer Dependencies
+
+| Package | Version |
+|---------|---------|
+| `drizzle-orm` | `>=0.35.0` |
+
+---
+
+Part of [everystack](https://github.com/scalable-technology/everystack) — a self-hosted application stack for Expo apps on AWS.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@everystack/api",
+  "version": "0.1.0",
+  "description": "PostgREST-compatible HTTP handler + typed fetch client for Drizzle ORM",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    "./handler": {
+      "types": "./src/handler/index.ts",
+      "default": "./src/handler/index.ts"
+    },
+    "./client": {
+      "types": "./src/client/index.ts",
+      "default": "./src/client/index.ts"
+    }
+  },
+  "peerDependencies": {
+    "drizzle-orm": ">=0.35.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.0.0",
+    "drizzle-orm": "^0.41.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.3.0",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "build": "tsc --build",
+    "lint": "tsc --noEmit"
+  }
+}