@everystack/api

PostgREST-compatible HTTP handler and typed fetch client for Drizzle ORM.

Install

pnpm add @everystack/api drizzle-orm

Entry Points

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.

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

// 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

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 },
    },
  },

  // lifecycle: true tables, the one soft delete. deriveHandlerConfig(models) emits this list;
  // do not write it by hand. Restore is POST {basePath}/{table}/restore, client .restore(id).
  lifecycle: ['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) => {},
      // All models; veto from '@everystack/api/handler' rolls back the request:
      beforeDelete: (row, ctx) => (ctx.user ? undefined : veto('sign in to delete')), // in the transaction; veto -> 409
      afterDelete: async (rows, ctx) => {},  // after commit, once per request; ctx.batch is null
      afterRestore: async (rows, ctx) => {}, // after commit, ctx.batch and ctx.counts
    },
  },

  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).

Auth Refusal Codes

Authentication refusals keep their existing HTTP status and message. The JSON body adds a code:

Confirmation and password recovery token refusals have no refusal code. Wrong passwords, account suspension, validation errors, and service outages have no refusal code. A 401 without a recognized code does not identify an everystack session refusal.

The code key also carries other error values, including PostgreSQL SQLSTATEs on database errors and vetoed on a hook veto. Clients must match one of the four refusal values exactly, never just check whether code is present.

Custom auth servers can use the same response helper:

import { authRefusal, AUTH_REFUSAL_CODES, type AuthRefusalCode } from '@everystack/api/handler';

return authRefusal('token_refused', 'Invalid or expired token'); // status defaults to 401

authRefusal(code, message, status?) returns exactly { message, code } with Content-Type: application/json. It has no runtime dependencies. AuthRefusalCode is the union of the four entries in AUTH_REFUSAL_CODES.

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):

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.

import { createClient } from '@everystack/api/client';
import { session } from '@everystack/auth/api';

const api = createClient({
  baseUrl: '/api',
  session: session.forClient(),
  headers: { 'X-Custom': 'value' },
});

session takes precedence over the deprecated getToken, onTokenExpired and onAuthFailure callbacks. Use createSession from @everystack/auth/session for custom storage or auth. The API package accepts the structural ClientSession interface and does not import the auth package.

Querying Data

// 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

// 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:

// 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 session refreshes once on 401 token_refused, then the client retries once. Concurrent requests share refresh. A refused refresh or a retry with token_refused ends the session. auth_required, client_refused and foreign 401s never trigger refresh or Sign Out. A failed refresh keeps the session and returns status 503 with code refresh_unavailable. session.forClient({ whenRefreshFails: 'anonymous' }) retries without a bearer token instead. Sign Out always wins over a late refresh.

legacyRefusals defaults to true: exact old everystack refusal messages still work when code is absent. Set it to false after deploying a server that sends codes. This option goes away at the next breaking release. See the client guide and session guide.

Exported Types

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

Part of everystack — a self-hosted application stack for Expo apps on AWS.

License

AGPL-3.0-only © Scalable Technology, Inc.

A commercial license is available for organizations that cannot or do not wish to comply with the AGPL-3.0 terms. For commercial licensing, contact [email protected].