npm - @mateosuarezdev/brpc - Versions diffs - 1.0.80 → 1.0.82 - Mend

@mateosuarezdev/brpc 1.0.80 → 1.0.82

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -1,744 +1,1312 @@
-# brpc
-A type-safe, batteries-included RPC framework for Bun. End-to-end type safety like tRPC, with built-in support for WebSocket subscriptions, file serving, media streaming, form uploads, server-side rendering, automatic image optimization, on the fly optimized image serving, robust and simple storage api to use with S3, Auth service with passord, OTP (email, phone), Oauth, Cookies management, Client side headers management, and much more.
-```
-npm install @mateosuarezdev/brpc zod
-```
----
-## Table of Contents
-- [Quick Start](#quick-start)
-- [Context](#context)
-- [Procedures](#procedures)
-  - [Query](#query)
-  - [Mutation](#mutation)
-  - [FormMutation](#formmutation)
-  - [File](#file)
-  - [FileStream](#filestream)
-  - [HTML](#html)
-  - [Subscription](#subscription)
-- [Middlewares](#middlewares)
-  - [createMiddleware](#createmiddleware)
-  - [Built-in Middlewares](#built-in-middlewares)
-- [Router](#router)
-- [Client](#client)
-  - [React](#react)
-- [Schemas](#schemas)
-- [Errors](#errors)
-- [Streaming Media](#streaming-media)
-- [Type Inference Utilities](#type-inference-utilities)
----
-## Quick Start
-```ts
-// context.ts
-import { createContext } from "@mateosuarezdev/brpc";
-import { db } from "./db";
-export const context = createContext(async (req) => ({
-  db,
-}));
-// procedure.ts
-import { createProcedure } from "@mateosuarezdev/brpc";
-import { context } from "./context";
-export const procedure = createProcedure(context);
-// routes.ts
-import { z } from "zod";
-import { procedure } from "./procedure";
-export const routes = {
-  hello: procedure
-    .input(z.object({ name: z.string() }))
-    .query(async ({ ctx, input }) => {
-      return `Hello, ${input.name}`;
-    }),
-};
-// index.ts
-import { createRouter } from "@mateosuarezdev/brpc";
-import { context } from "./context";
-import { routes } from "./routes";
-const router = createRouter({ context, routes });
-router.listen(3000, () => {
-  console.log("Server running on http://localhost:3000");
-});
-```
----
-## Context
-`createContext` defines what data is available in every procedure handler. Return only your app-specific data — `req`, `params`, `headers`, and `publishToProcedure` are always injected automatically by the router.
-```ts
-import { createContext } from "@mateosuarezdev/brpc";
-export const context = createContext(async (req) => ({
-  db: getDb(),
-  userId: getUserIdFromCookie(req),
-}));
-```
-If you need no custom data at all:
-```ts
-export const context = createContext(async (req) => {});
-```
-Every handler receives a fully typed `ctx` with:
-| Field                | Type                     | Description                              |
-| -------------------- | ------------------------ | ---------------------------------------- |
-| `req`                | `Request`                | The raw Bun request                      |
-| `params`             | `Record<string, string>` | URL path parameters                      |
-| `headers`            | `Headers`                | Response headers you can set             |
-| `publishToProcedure` | `fn`                     | Publish to a subscription procedure      |
-| _your fields_        | _inferred_               | Whatever you return from `createContext` |
----
-## Procedures
-`createProcedure(context)` creates a typed procedure builder. Pass your context to infer the full context type automatically.
-```ts
-import { createProcedure } from "@mateosuarezdev/brpc";
-import { context } from "./context";
-export const procedure = createProcedure(context);
-```
-Chain `.use(middleware)` to add middleware, `.input(schema)` for input validation, then a handler method.
-### Query
-GET request. Returns `{ data: result }`.
-```ts
-const getUser = procedure
-  .input(z.object({ id: z.string() }))
-  .query(async ({ ctx, input }) => {
-    return ctx.db.users.findById(input.id);
-  });
-```
-### Mutation
-POST request with a JSON body. Returns `{ data: result }`.
-```ts
-const createPost = procedure
-  .input(z.object({ title: z.string(), body: z.string() }))
-  .mutation(async ({ ctx, input }) => {
-    return ctx.db.posts.create(input);
-  });
-```
-### FormMutation
-POST with `multipart/form-data`. Useful for file uploads. Pair with `createFileSchema` for typed file validation.
-```ts
-import { createFileSchema } from "@mateosuarezdev/brpc";
-const uploadAvatar = procedure
-  .input(
-    z.object({
-      file: createFileSchema({ acceptedTypes: { image: "*" }, maxSize: 5 }),
-    }),
-  )
-  .formMutation(async ({ ctx, input }) => {
-    await saveFile(input.file);
-    return { success: true };
-  });
-```
-### File
-GET request that serves a file. brpc automatically sets appropriate `Content-Type` and `Cache-Control` headers.
-```ts
-const logo = procedure.file(async ({ ctx }) => {
-  return Bun.file("./assets/logo.png");
-});
-```
-You can also return a `Response` directly for full control.
-### FileStream
-GET request with HTTP Range support (206 Partial Content). Ideal for video and audio streaming.
-```ts
-import { streamMedia } from "@mateosuarezdev/brpc";
-const video = procedure.fileStream(async ({ ctx }) => {
-  return streamMedia(Bun.file("./videos/intro.mp4"), ctx.req, {
-    maxChunkSize: 2 * 1024 * 1024, // 2MB chunks
-    cacheMaxAge: 3600,
-    acceptedExtensions: [".mp4", ".webm"],
-  });
-});
-```
-### HTML
-GET request that returns a raw HTML string with `Content-Type: text/html`.
-```ts
-const page = procedure.html(async ({ ctx }) => {
-  return `<!DOCTYPE html><html><body>Hello</body></html>`;
-});
-```
-### Subscription
-WebSocket-based pub/sub. Clients subscribe to a topic and receive messages when your server publishes.
-```ts
-const messages = procedure
-  .input(z.object({ roomId: z.string(), text: z.string() }))
-  .subscription(async ({ ctx, input }) => {
-    await saveMessage(input);
-    return input; // returned value is broadcast to all subscribers
-  });
-```
-Publish from anywhere on the server:
-```ts
-router.publish(
-  messages,
-  { roomId: "general", text: "hello" },
-  { roomId: "general" },
-);
-```
-Parameters in the route path (e.g. `":roomId"`) scope the subscription topic — subscribers only receive messages matching their params.
----
-## Middlewares
-### createMiddleware
-Define reusable, typed middlewares outside of the procedure chain. Return an object to extend the context type — the returned fields are merged into `ctx` for the rest of the chain.
-```ts
-import { createMiddleware, BRPCError } from "@mateosuarezdev/brpc";
-import { context } from "./context";
-// Pass context for automatic type inference
-const authMiddleware = createMiddleware(context, async (ctx) => {
-  const session = await getSession(ctx.req);
-  if (!session)
-    throw new BRPCError({ code: "UNAUTHORIZED", message: "Not authenticated" });
-  return { session };
-});
-// Or use an explicit generic when no context reference is available
-const langMiddleware = createMiddleware<typeof context>(async (ctx) => {
-  const lang = ctx.req.headers.get("accept-language") ?? "en";
-  return { lang };
-});
-```
-Use middlewares on individual procedures:
-```ts
-const protectedProcedure = procedure.use(authMiddleware);
-const getProfile = protectedProcedure.query(async ({ ctx }) => {
-  ctx.session.userId; // fully typed
-});
-```
-Chain multiple middlewares — each one's return type accumulates into `ctx`:
-```ts
-const localizedProtectedProcedure = procedure
-  .use(authMiddleware) // ctx gains { session }
-  .use(langMiddleware); // ctx gains { lang }
-const getContent = localizedProtectedProcedure.query(async ({ ctx }) => {
-  ctx.session; // typed
-  ctx.lang; // typed
-});
-```
-Middlewares that only guard (no context extension) just don't return anything:
-```ts
-const adminMiddleware = createMiddleware(context, async (ctx) => {
-  if (ctx.session.role !== "admin") {
-    throw new BRPCError({ code: "FORBIDDEN", message: "Admins only" });
-  }
-  // no return — ctx type unchanged
-});
-```
-### Built-in Middlewares
-#### Rate Limiter
-```ts
-import { createRateLimiter } from "@mateosuarezdev/brpc";
-const rateLimiter = createRateLimiter({
-  windowMs: 60_000, // 1 minute window
-  maxRequests: 100, // max 100 requests per window
-  maxEntries: 10_000, // max IPs to track
-  message: "Too many requests",
-  statusCode: 429,
-  headerPrefix: "X-RateLimit",
-});
-```
-Sets `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers automatically.
-#### Path Blocker
-Blocks requests matching any of the given regex patterns with a 404.
-```ts
-import { createPathBlocker } from "@mateosuarezdev/brpc";
-const blocker = createPathBlocker({
-  paths: ["/wp-admin", "\\.env", "/\\.git"],
-});
-```
-#### Profanity Filter
-Scans request body, query params, and/or route params for profanity.
-```ts
-import { createProfanityMiddleware } from "@mateosuarezdev/brpc";
-const profanityFilter = createProfanityMiddleware({
-  languages: ["en", "es"],
-  checkBody: true,
-  checkQuery: true,
-  checkParams: false,
-  message: "Inappropriate content detected",
-  customLanguages: {
-    custom: { badWords: ["forbidden"], badPhrases: ["bad phrase"] },
-  },
-});
-```
----
-## Router
-```ts
-import { createRouter } from "@mateosuarezdev/brpc";
-const router = createRouter({
-  context,
-  routes,
-  // Optional
-  globalMiddlewares: [blocker, rateLimiter],
-  prefix: "/api",
-  debug: false,
-  autoFileCacheControl: true,
-  websocket: {
-    onOpen: (ws, ctx) => console.log("connected"),
-    onClose: (ws, code, reason, ctx) => console.log("disconnected"),
-  },
-  integrations: {
-    betterAuth: {
-      handler: auth.handler,
-    },
-    rawRoutes: {
-      "/health": async (req) => new Response("ok"),
-      "/webhook": {
-        POST: async (req) => handleWebhook(req),
-      },
-    },
-  },
-  onError: (error, { req, route }) => {
-    console.error(`Error on ${route}:`, error);
-  },
-});
-router.listen(3000);
-```
-### Global Middlewares and Context
-`globalMiddlewares` run before every request, in order. They receive and can mutate `ctx` at runtime exactly like procedure middlewares — returning an object merges it into `ctx`.
-However, because `C` is fixed at router creation time, TypeScript cannot widen the context type from a global middleware's return value. If a global middleware needs to add typed fields to `ctx`, declare them in `createContext` so they are part of `C` from the start:
-```ts
-// context.ts — declare fields that global middlewares will populate
-export const context = createContext(async (req) => ({
-  db: myDb,
-  session: null as Session | null, // global auth middleware fills this
-}));
-// router.ts
-createRouter({
-  context,
-  routes,
-  globalMiddlewares: [
-    async (ctx) => {
-      ctx.session = (await getSession(ctx.req)) ?? null; // typed, works fine
-    },
-  ],
-});
-```
-At runtime, returning an object from a global middleware also works and merges into `ctx`, but any extra fields added this way won't be reflected in the TypeScript type — use direct assignment on `ctx` instead for global middlewares.
-### RouterConfig Options
-| Option                    | Type               | Description                                                    |
-| ------------------------- | ------------------ | -------------------------------------------------------------- |
-| `context`                 | `fn`               | Context creator — receives `Request`, returns your custom data |
-| `routes`                  | `Routes`           | Nested route object                                            |
-| `globalMiddlewares`       | `Middleware[]`     | Run before every request                                       |
-| `prefix`                  | `string`           | Path prefix for all routes                                     |
-| `debug`                   | `boolean`          | Enable route debug logging                                     |
-| `autoFileCacheControl`    | `boolean`          | Auto-set cache headers for file procedures                     |
-| `websocket.onOpen`        | `fn`               | Called when a WebSocket connection opens                       |
-| `websocket.onClose`       | `fn`               | Called when a WebSocket connection closes                      |
-| `integrations.betterAuth` | `{ handler }`      | Delegate `better-auth` routes to its handler                   |
-| `integrations.rawRoutes`  | `Record<path, fn>` | Escape hatch for raw Bun routes                                |
-| `onError`                 | `fn`               | Global error handler                                           |
-### Dynamic Route Parameters
-Prefix a segment with `:` to capture it as a param:
-```ts
-const routes = {
-  users: {
-    ":id": procedure.query(async ({ ctx }) => {
-      ctx.params.id; // the captured value
-      return getUser(ctx.params.id);
-    }),
-  },
-};
-```
-### Per-Procedure Timeout
-Override the default 30s request timeout on any procedure:
-```ts
-const slowQuery = procedure
-  .input(z.object({ q: z.string() }))
-  .timeout(120_000) // 2 minutes
-  .query(async ({ ctx, input }) => heavyComputation(input.q));
-```
-### Testing Without a Server
-```ts
-const response = await router.testRequest(
-  new Request("http://localhost/hello?input=%7B%22name%22%3A%22world%22%7D"),
-);
-```
----
-## Client
-Import from `@mateosuarezdev/brpc/client`:
-```ts
-import { createBrpcClient } from "@mateosuarezdev/brpc/client";
-import type { AppRoutes } from "./routes";
-const client = createBrpcClient<AppRoutes>("https://api.example.com", {
-  headers: async () => ({
-    Authorization: `Bearer ${getToken()}`,
-  }),
-  prefix: "/api",
-  s3Endpoint: "https://cdn.example.com",
-  nodeEnv: "production",
-  debug: false,
-});
-// Query
-const user = await client.routes.users.getById.query({ id: "123" });
-// Mutation
-const post = await client.routes.posts.create.mutation({ title: "Hello" });
-// FormMutation
-const result = await client.routes.media.upload.formMutation({ file: myFile });
-// File/FileStream — returns a URL string
-const url = await client.routes.avatar.file();
-// HTML — returns raw HTML string
-const html = await client.routes.page.html();
-// Subscription
-const { unsubscribe, publish } = client.routes.messages[":roomId"].subscription(
-  (message) => console.log("received:", message),
-);
-publish({ roomId: "general", text: "hello" });
-unsubscribe();
-```
-### BrpcClientOptions
-| Option       | Type               | Description                                                           |
-| ------------ | ------------------ | --------------------------------------------------------------------- |
-| `headers`    | `fn \| Headers`    | Default headers for all requests                                      |
-| `fetch`      | `typeof fetch`     | Custom fetch implementation                                           |
-| `WebSocket`  | `typeof WebSocket` | Custom WebSocket implementation                                       |
-| `prefix`     | `string`           | API path prefix                                                       |
-| `apiPrefix`  | `string`           | Additional API prefix                                                 |
-| `s3Endpoint` | `string`           | **Required.** S3/CDN endpoint for resolving storage object URLs       |
-| `nodeEnv`    | `string`           | **Required.** Current environment (`"development"` \| `"production"`) |
-| `debug`      | `boolean`          | Enable client-side debug logging                                      |
-### Cache Keys
-Every procedure exposes helpers for use with query libraries like TanStack Query or `@mateosuarezdev/query`:
-```ts
-// String key
-client.routes.users.getById.getStringKey({ id: "123" });
-// → "users/getById?{"id":"123"}"
-// Array key — input from backend schema
-client.routes.users.getById.getArrayKey({ id: "123" });
-// → ["users/getById", "id", "123"]
-// Array key — no backend inputs
-client.routes.users.list.getArrayKey();
-// → ["users/list"]
-// No-inputs shorthand (always ignores any input)
-client.routes.users.list.getNoInputsArrayKey();
-// → ["users/list"]
-```
-#### Client-side context keys
-`getArrayKey` accepts an optional second `context` argument for keys that are meaningful on the client but not sent to the server — the most common case being scoping cached data by the current user so different users' data never overlaps in the same cache:
-```ts
-// Procedure has no backend input, but cache is scoped per user
-client.routes.workout.getSessions.getArrayKey(undefined, { userId });
-// → ["workout/getSessions", "userId", "abc123"]
-// Procedure has backend input AND needs user scoping
-client.routes.workout.getSession.getArrayKey({ sessionId }, { userId });
-// → ["workout/getSession", "sessionId", "42", "userId", "abc123"]
-```
-`context` keys are sorted and merged with input keys deterministically, so the resulting array is always stable. Invalidation works the same way:
-```ts
-// Invalidate all session queries for a specific user
-queryService.invalidateQueries(["workout/getSessions", "userId", userId]);
-```
-### Utilities
-```ts
-// Update WebSocket auth token (e.g. after token refresh)
-await client.utils.updateWsAuth();
-// Update headers at runtime
-await client.utils.setHeader("Authorization", `Bearer ${newToken}`);
-await client.utils.setHeaders({ "X-Custom": "value" });
-```
-### BrpcClientError
-```ts
-import { BrpcClientError } from "@mateosuarezdev/brpc/client";
-try {
-  await client.routes.auth.login.mutation({ email, password });
-} catch (err) {
-  if (err instanceof BrpcClientError) {
-    err.status; // HTTP status code
-    err.code; // BRPCErrorCode string
-    err.clientCode; // custom client code if set
-    err.isUnauthorized(); // status === 401
-    err.isForbidden(); // status === 403
-    err.isNotFound(); // status === 404
-    err.isValidationError(); // status === 400
-    err.isClientError("INVALID_CREDS"); // clientCode === "INVALID_CREDS"
-  }
-}
-```
-### React
-Import from `@mateosuarezdev/brpc/client/react`:
-```ts
-import { useSubscription } from "@mateosuarezdev/brpc/client/react";
-function ChatRoom({ roomId }: { roomId: string }) {
-  const [messages, setMessages] = useState<Message[]>([]);
-  const { publish } = useSubscription(
-    (callback) => client.routes.messages[":roomId"].subscription(callback),
-    (message) => setMessages((prev) => [...prev, message]),
-  );
-  return (
-    <button onClick={() => publish({ roomId, text: "hello" })}>
-      Send
-    </button>
-  );
-}
-```
----
-## Schemas
-### createFileSchema
-Validates `File` objects in `formMutation` inputs:
-```ts
-import { createFileSchema } from "@mateosuarezdev/brpc";
-z.object({
-  avatar: createFileSchema({
-    acceptedTypes: {
-      image: ["image/jpeg", "image/png"],
-    },
-    maxSize: 5, // MB
-    minSize: 0.1, // MB
-    messages: {
-      type: "Only JPEG and PNG are allowed",
-      maxSize: "File must be under 5MB",
-    },
-  }),
-  document: createFileSchema({
-    acceptedTypes: { document: "*" },
-    maxSize: 20,
-  }),
-  audio: createFileSchema({
-    acceptedTypes: { audio: "*" },
-  }),
-});
-```
-**Accepted type groups:** `image`, `video`, `audio`, `document`
-Pass `"*"` to accept all types in a group, or an array of specific MIME type strings.
----
-## Errors
-```ts
-import { BRPCError } from "@mateosuarezdev/brpc";
-// Constructor
-throw new BRPCError({
-  code: "UNAUTHORIZED",
-  message: "Token expired",
-  clientCode: "TOKEN_EXPIRED", // readable code for the client
-  data: { expiredAt: new Date() },
-});
-// Static factory shortcuts
-throw BRPCError.unauthorized("Token expired", "TOKEN_EXPIRED");
-throw BRPCError.badRequest("Invalid input", "INVALID_EMAIL");
-throw BRPCError.forbidden("Admins only");
-throw BRPCError.notFound("User not found");
-throw BRPCError.conflict("Email already in use", "EMAIL_TAKEN");
-throw BRPCError.tooManyRequests();
-throw BRPCError.internalServerError();
-```
-### Error Codes and HTTP Status Mapping
-| Code                    | Status |
-| ----------------------- | ------ |
-| `BAD_REQUEST`           | 400    |
-| `UNAUTHORIZED`          | 401    |
-| `FORBIDDEN`             | 403    |
-| `NOT_FOUND`             | 404    |
-| `CONFLICT`              | 409    |
-| `UNPROCESSABLE_CONTENT` | 422    |
-| `TOO_MANY_REQUESTS`     | 429    |
-| `INTERNAL_SERVER_ERROR` | 500    |
-| `SERVICE_UNAVAILABLE`   | 503    |
-Zod validation errors are automatically caught and returned as `BAD_REQUEST` (400) with field-level detail.
----
-## Streaming Media
-Use `streamMedia` inside a `fileStream` procedure to handle HTTP Range requests automatically:
-```ts
-import { streamMedia } from "@mateosuarezdev/brpc";
-const video = procedure.fileStream(async ({ ctx }) => {
-  const file = Bun.file(`./media/${ctx.params.filename}`);
-  return streamMedia(file, ctx.req, {
-    maxChunkSize: 2 * 1024 * 1024, // 2MB per chunk (default)
-    cacheMaxAge: 3600, // Cache-Control max-age in seconds
-    acceptedExtensions: [".mp4", ".webm", ".ogg"],
-  });
-});
-```
-Responds with `206 Partial Content` when the client sends a `Range` header, enabling native browser seek/scrub for `<video>` and `<audio>` elements.
----
-## Type Inference Utilities
-```ts
-import type {
-  InferProcedureInput,
-  InferProcedureOutput,
-  InferRouterOutput,
-} from "@mateosuarezdev/brpc";
-// Infer types from a procedure
-type CreatePostInput = InferProcedureInput<typeof routes.posts.create>;
-type CreatePostOutput = InferProcedureOutput<typeof routes.posts.create>;
-// Infer the full output shape of a routes object
-type AppOutput = InferRouterOutput<typeof routes>;
-type UserOutput = AppOutput["users"]["getById"];
-```
----
-## Environment Variables
-| Variable             | Default    | Description                            |
-| -------------------- | ---------- | -------------------------------------- |
-| `MAX_WS_CONNECTIONS` | `1000`     | Max simultaneous WebSocket connections |
-| `WS_TIMEOUT`         | `30000`    | WebSocket idle timeout in ms           |
-| `MAX_REQUEST_SIZE`   | `10485760` | Max request body size in bytes (10MB)  |
-| `REQUEST_TIMEOUT`    | `30000`    | Default procedure timeout in ms        |
-| `ROUTE_CACHE_SIZE`   | `1000`     | Route matcher cache size               |
+# brpc
+A type-safe, batteries-included RPC framework for Bun. End-to-end type safety like tRPC, with built-in support for WebSocket subscriptions, file serving, media streaming, form uploads, server-side rendering, automatic image optimization, on the fly optimized image serving, robust and simple storage api to use with S3, Auth service with password, OTP (email, phone), OAuth, Cookies management, Client side headers management, and much more.
+```
+npm install @mateosuarezdev/brpc zod
+```
+---
+## Table of Contents
+- [Quick Start](#quick-start)
+- [Context](#context)
+- [Procedures](#procedures)
+  - [Query](#query)
+  - [Mutation](#mutation)
+  - [FormMutation](#formmutation)
+  - [File](#file)
+  - [FileStream](#filestream)
+  - [HTML](#html)
+  - [Subscription](#subscription)
+- [Middlewares](#middlewares)
+  - [createMiddleware](#createmiddleware)
+  - [Built-in Middlewares](#built-in-middlewares)
+- [Router](#router)
+- [Client](#client)
+  - [React](#react)
+- [Schemas](#schemas)
+- [Errors](#errors)
+- [Streaming Media](#streaming-media)
+- [Storage](#storage)
+  - [S3](#s3)
+  - [Images](#images)
+  - [Local](#local)
+- [Auth](#auth)
+  - [Server Setup](#server-setup)
+  - [Auth Routes](#auth-routes)
+  - [Context Integration](#context-integration)
+  - [Client Side](#client-side-auth)
+- [Type Inference Utilities](#type-inference-utilities)
+---
+## Quick Start
+```ts
+// context.ts
+import { createContext } from "@mateosuarezdev/brpc";
+import { db } from "./db";
+export const context = createContext(async (req) => ({
+  db,
+}));
+// procedure.ts
+import { createProcedure } from "@mateosuarezdev/brpc";
+import type { CustomContext } from "./context";
+export const procedure = createProcedure<CustomContext>();
+// routes.ts
+import { z } from "zod";
+import { procedure } from "./procedure";
+export const routes = {
+  hello: procedure
+    .input(z.object({ name: z.string() }))
+    .query(async ({ ctx, input }) => {
+      return `Hello, ${input.name}`;
+    }),
+};
+// index.ts
+import { createRouter } from "@mateosuarezdev/brpc";
+import { context } from "./context";
+import { routes } from "./routes";
+const router = createRouter({ context, routes });
+router.listen(3000, () => {
+  console.log("Server running on http://localhost:3000");
+});
+```
+---
+## Context
+`createContext` defines what data is available in every procedure handler. Return your app-specific data plus a `headers` instance — the router preserves it so anything you set on it (cookies, custom response headers) flows into the final response.
+```ts
+import { createContext } from "@mateosuarezdev/brpc";
+export const context = createContext(async (req) => ({
+  db: getDb(),
+  userId: getUserIdFromCookie(req),
+  headers: new Headers(),
+}));
+```
+The `headers` object you return is the same one used for the response. Anything written to it in the context creator, middlewares, or handlers will be included — including `Set-Cookie` headers from token refreshes.
+Every handler receives a fully typed `ctx` with:
+| Field                | Type                     | Description                                        |
+| -------------------- | ------------------------ | -------------------------------------------------- |
+| `req`                | `Request`                | The raw Bun request                                |
+| `res`                | `Response`               | The response object                                |
+| `params`             | `Record<string, string>` | URL path parameters                                |
+| `headers`            | `Headers`                | Response headers — create in context, write anywhere |
+| `allowedOrigins`     | `string[] \| undefined`  | CORS origins for this request — override in middlewares |
+| `publishToProcedure` | `fn`                     | Publish to a subscription procedure                |
+| _your fields_        | _inferred_               | Whatever you return from `createContext`            |
+---
+## Procedures
+`createProcedure<YourContext>()` creates a typed procedure builder. Pass your context type as a generic to get full type inference.
+```ts
+import { createProcedure } from "@mateosuarezdev/brpc";
+import type { CustomContext } from "./context";
+export const procedure = createProcedure<CustomContext>();
+```
+Alternatively, pass the context creator function directly and brpc will infer the type:
+```ts
+import { context } from "./context";
+export const procedure = createProcedure(context);
+```
+Chain `.use(middleware)` to add middleware, `.input(schema)` for input validation, then a handler method.
+### Query
+GET request. Returns `{ data: result }`.
+```ts
+const getUser = procedure
+  .input(z.object({ id: z.string() }))
+  .query(async ({ ctx, input }) => {
+    return ctx.db.users.findById(input.id);
+  });
+```
+### Mutation
+POST request with a JSON body. Returns `{ data: result }`.
+```ts
+const createPost = procedure
+  .input(z.object({ title: z.string(), body: z.string() }))
+  .mutation(async ({ ctx, input }) => {
+    return ctx.db.posts.create(input);
+  });
+```
+### FormMutation
+POST with `multipart/form-data`. Useful for file uploads. Pair with `createFileSchema` for typed file validation.
+```ts
+import { createFileSchema } from "@mateosuarezdev/brpc";
+const uploadAvatar = procedure
+  .input(
+    z.object({
+      file: createFileSchema({ acceptedTypes: { image: "*" }, maxSize: 5 }),
+    }),
+  )
+  .formMutation(async ({ ctx, input }) => {
+    await saveFile(input.file);
+    return { success: true };
+  });
+```
+### File
+GET request that serves a file. Handler returns `BunFile` or a raw `Response`. When returning a `BunFile`, brpc automatically sets `Content-Type` and `Cache-Control`. When returning a `Response`, it is passed through untouched — giving you full control for streaming, SSE, HTML, downloads, or anything Bun's `Response` supports.
+```ts
+// Serve a static file — brpc sets Content-Type and Cache-Control
+const logo = procedure.file(async ({ ctx }) => {
+  return Bun.file("./assets/logo.png");
+});
+// Stream video/audio directly — Bun handles it natively
+const media = procedure.file(async ({ ctx }) => {
+  const file = Bun.file(`./media/${ctx.params.filename}`);
+  return new Response(file, {
+    headers: { "Content-Type": file.type },
+  });
+});
+// Server-Sent Events
+const events = procedure.file(async ({ ctx }) => {
+  const encoder = new TextEncoder();
+  const body = new ReadableStream({
+    start(controller) {
+      const send = (data: string) =>
+        controller.enqueue(encoder.encode(`data: ${data}\n\n`));
+      const interval = setInterval(() => send(JSON.stringify({ tick: Date.now() })), 1000);
+      setTimeout(() => { clearInterval(interval); controller.close(); }, 30_000);
+    },
+  });
+  return new Response(body, {
+    headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache" },
+  });
+});
+// File download with custom headers
+const report = procedure
+  .input(z.object({ id: z.string() }))
+  .file(async ({ ctx, input }) => {
+    const csv = await generateReport(input.id);
+    return new Response(csv, {
+      headers: {
+        "Content-Type": "text/csv",
+        "Content-Disposition": `attachment; filename="${input.id}.csv"`,
+      },
+    });
+  });
+```
+### FileStream
+GET request with HTTP Range support (206 Partial Content). Ideal for video and audio streaming.
+```ts
+import { streamMedia } from "@mateosuarezdev/brpc";
+const video = procedure.fileStream(async ({ ctx }) => {
+  return streamMedia(Bun.file("./videos/intro.mp4"), ctx.req, {
+    maxChunkSize: 2 * 1024 * 1024, // 2MB chunks
+    cacheMaxAge: 3600,
+    acceptedExtensions: [".mp4", ".webm"],
+  });
+});
+```
+### HTML
+GET request that returns a raw HTML string with `Content-Type: text/html`.
+```ts
+const page = procedure.html(async ({ ctx }) => {
+  return `<!DOCTYPE html><html><body>Hello</body></html>`;
+});
+```
+### Subscription
+WebSocket-based pub/sub. Clients subscribe to a topic and receive messages when your server publishes.
+```ts
+const messages = procedure
+  .input(z.object({ roomId: z.string(), text: z.string() }))
+  .subscription(async ({ ctx, input }) => {
+    await saveMessage(input);
+    return input; // returned value is broadcast to all subscribers
+  });
+```
+Publish from anywhere on the server:
+```ts
+router.publish(
+  messages,
+  { roomId: "general", text: "hello" },
+  { roomId: "general" },
+);
+```
+Parameters in the route path (e.g. `":roomId"`) scope the subscription topic — subscribers only receive messages matching their params.
+---
+## Middlewares
+### createMiddleware
+Define reusable, typed middlewares outside of the procedure chain. Return an object to extend the context type — the returned fields are merged into `ctx` for the rest of the chain.
+```ts
+import { createMiddleware, BRPCError } from "@mateosuarezdev/brpc";
+import type { CustomContext } from "./context";
+// Pass context creator for automatic type inference
+const authMiddleware = createMiddleware(context, async (ctx) => {
+  const session = await getSession(ctx.req);
+  if (!session)
+    throw new BRPCError({ code: "UNAUTHORIZED", message: "Not authenticated" });
+  return { session };
+});
+// Or use an explicit generic with your context type
+const langMiddleware = createMiddleware<CustomContext>(async (ctx) => {
+  const lang = ctx.req.headers.get("accept-language") ?? "en";
+  return { lang };
+});
+```
+Use middlewares on individual procedures:
+```ts
+const protectedProcedure = procedure.use(authMiddleware);
+const getProfile = protectedProcedure.query(async ({ ctx }) => {
+  ctx.session.userId; // fully typed
+});
+```
+Chain multiple middlewares — each one's return type accumulates into `ctx`:
+```ts
+const localizedProtectedProcedure = procedure
+  .use(authMiddleware) // ctx gains { session }
+  .use(langMiddleware); // ctx gains { lang }
+const getContent = localizedProtectedProcedure.query(async ({ ctx }) => {
+  ctx.session; // typed
+  ctx.lang; // typed
+});
+```
+Middlewares that only guard (no context extension) just don't return anything:
+```ts
+const adminMiddleware = createMiddleware(context, async (ctx) => {
+  if (ctx.session.role !== "admin") {
+    throw new BRPCError({ code: "FORBIDDEN", message: "Admins only" });
+  }
+  // no return — ctx type unchanged
+});
+```
+### Per-Procedure CORS
+By default the router uses `allowedOrigins` from the router config for every request. A middleware can override this for a specific procedure or group of procedures by setting `ctx.allowedOrigins`:
+```ts
+const mobileOnlyMiddleware = createMiddleware(context, async (ctx) => {
+  return { allowedOrigins: ["https://mobile.myapp.com"] };
+});
+const adminOnlyMiddleware = createMiddleware(context, async (ctx) => {
+  return { allowedOrigins: ["https://admin.myapp.com"] };
+});
+export const routes = {
+  // open to all configured origins
+  public: procedure.query(async () => "hello"),
+  // only reachable from the mobile app
+  mobileOnly: procedure
+    .use(mobileOnlyMiddleware)
+    .query(async ({ ctx }) => "mobile data"),
+  // only reachable from the admin dashboard
+  admin: {
+    stats: procedure
+      .use(adminOnlyMiddleware)
+      .query(async ({ ctx }) => getStats()),
+  },
+};
+```
+`ctx.allowedOrigins` takes priority over the global `allowedOrigins`. OPTIONS preflight always uses the global list since context and middlewares haven't run yet at that point.
+### Built-in Middlewares
+#### Rate Limiter
+```ts
+import { createRateLimiter } from "@mateosuarezdev/brpc";
+const rateLimiter = createRateLimiter({
+  windowMs: 60_000, // 1 minute window
+  maxRequests: 100, // max 100 requests per window
+  maxEntries: 10_000, // max IPs to track
+  message: "Too many requests",
+  statusCode: 429,
+  headerPrefix: "X-RateLimit",
+});
+```
+Sets `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers automatically.
+#### Path Blocker
+Blocks requests matching any of the given regex patterns with a 404.
+```ts
+import { createPathBlocker } from "@mateosuarezdev/brpc";
+const blocker = createPathBlocker({
+  paths: ["/wp-admin", "\\.env", "/\\.git"],
+});
+```
+#### Profanity Filter
+Scans request body, query params, and/or route params for profanity.
+```ts
+import { createProfanityMiddleware } from "@mateosuarezdev/brpc";
+const profanityFilter = createProfanityMiddleware({
+  languages: ["en", "es"],
+  checkBody: true,
+  checkQuery: true,
+  checkParams: false,
+  message: "Inappropriate content detected",
+  customLanguages: {
+    custom: { badWords: ["forbidden"], badPhrases: ["bad phrase"] },
+  },
+});
+```
+---
+## Router
+```ts
+import { createRouter } from "@mateosuarezdev/brpc";
+const router = createRouter({
+  context,
+  routes,
+  // Optional
+  globalMiddlewares: [blocker, rateLimiter],
+  prefix: "/api",
+  debug: false,
+  websocket: {
+    onOpen: (ws, ctx) => console.log("connected"),
+    onClose: (ws, code, reason, ctx) => console.log("disconnected"),
+  },
+  integrations: {
+    betterAuth: {
+      handler: auth.handler,
+    },
+    rawRoutes: {
+      "/health": async (req) => new Response("ok"),
+      "/webhook": {
+        POST: async (req) => handleWebhook(req),
+      },
+    },
+  },
+  onError: (error, { req, route }) => {
+    console.error(`Error on ${route}:`, error);
+  },
+});
+router.listen(3000);
+```
+### Global Middlewares and Context
+`globalMiddlewares` run before every request, in order. They receive and can mutate `ctx` at runtime exactly like procedure middlewares — returning an object merges it into `ctx`.
+However, because `C` is fixed at router creation time, TypeScript cannot widen the context type from a global middleware's return value. If a global middleware needs to add typed fields to `ctx`, declare them in `createContext` so they are part of `C` from the start:
+```ts
+// context.ts — declare fields that global middlewares will populate
+export const context = createContext(async (req) => ({
+  db: myDb,
+  session: null as Session | null, // global auth middleware fills this
+}));
+// router.ts
+createRouter({
+  context,
+  routes,
+  globalMiddlewares: [
+    async (ctx) => {
+      ctx.session = (await getSession(ctx.req)) ?? null; // typed, works fine
+    },
+  ],
+});
+```
+At runtime, returning an object from a global middleware also works and merges into `ctx`, but any extra fields added this way won't be reflected in the TypeScript type — use direct assignment on `ctx` instead for global middlewares.
+### RouterConfig Options
+| Option                    | Type               | Description                                                    |
+| ------------------------- | ------------------ | -------------------------------------------------------------- |
+| `context`                 | `fn`               | Context creator — receives `Request`, returns your custom data |
+| `routes`                  | `Routes`           | Nested route object                                            |
+| `globalMiddlewares`       | `Middleware[]`     | Run before every request                                       |
+| `prefix`                  | `string`           | Path prefix for all routes                                     |
+| `allowedOrigins`          | `string[]`         | Global CORS origin allowlist — empty allows all (dev default) |
+| `debug`                   | `boolean`          | Enable route debug logging                                     |
+| `websocket.onOpen`        | `fn`               | Called when a WebSocket connection opens                       |
+| `websocket.onClose`       | `fn`               | Called when a WebSocket connection closes                      |
+| `integrations.betterAuth` | `{ handler }`      | Delegate `better-auth` routes to its handler                   |
+| `integrations.rawRoutes`  | `Record<path, fn>` | Escape hatch for raw Bun routes                                |
+| `onError`                 | `fn`               | Global error handler                                           |
+### Dynamic Route Parameters
+Prefix a segment with `:` to capture it as a param:
+```ts
+const routes = {
+  users: {
+    ":id": procedure.query(async ({ ctx }) => {
+      ctx.params.id; // the captured value
+      return getUser(ctx.params.id);
+    }),
+  },
+};
+```
+### Per-Procedure Timeout
+Override the default 30s request timeout on any procedure:
+```ts
+const slowQuery = procedure
+  .input(z.object({ q: z.string() }))
+  .timeout(120_000) // 2 minutes
+  .query(async ({ ctx, input }) => heavyComputation(input.q));
+```
+### Testing Without a Server
+`router.testRequest()` executes a real HTTP request through the complete BRPC
+pipeline without opening a port: route matching, context creation, global and
+procedure middlewares, input validation, handlers, and BRPC error responses.
+It returns the standard `Response`, so tests can assert both status codes and
+response bodies with Bun's built-in test runner.
+```ts
+import { describe, expect, test } from "bun:test";
+import { createRouter } from "@mateosuarezdev/brpc";
+import { context } from "./context";
+import { routes } from "./routes";
+const router = createRouter({ context, routes });
+describe("posts.create", () => {
+  test("creates a post", async () => {
+    const response = await router.testRequest(
+      new Request("http://localhost/posts/create", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ title: "Hello", body: "World" }),
+      }),
+    );
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toEqual({
+      data: expect.objectContaining({ title: "Hello" }),
+    });
+  });
+});
+```
+Use ordinary `Request` objects. Queries read URL search parameters, mutations
+require a JSON `Content-Type`, and form mutations require `multipart/form-data`.
+```ts
+// Dynamic route parameters
+const response = await router.testRequest(
+  new Request("http://localhost/users/usr_123"),
+);
+expect(response.status).toBe(200);
+await expect(response.json()).resolves.toEqual({ data: expect.any(Object) });
+```
+Test failures through the router too. This confirms the externally visible
+status and BRPC error shape, rather than only testing an implementation detail.
+```ts
+const response = await router.testRequest(
+  new Request("http://localhost/posts/create", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ title: "" }),
+  }),
+);
+expect(response.status).toBe(400);
+await expect(response.json()).resolves.toMatchObject({
+  error: { code: "BAD_REQUEST" },
+});
+```
+For webhook tests, build a real signed `Request` in a test mock, then pass it
+to `router.testRequest()`. This tests the raw-body/signature middleware and the
+route together without starting a server.
+---
+## Client
+Import from `@mateosuarezdev/brpc/client`:
+```ts
+import { createBrpcClient } from "@mateosuarezdev/brpc/client";
+import type { AppRoutes } from "./routes";
+const client = createBrpcClient<AppRoutes>("https://api.example.com", {
+  headers: async () => ({
+    Authorization: `Bearer ${getToken()}`,
+  }),
+  prefix: "/api",
+  s3Endpoint: "https://cdn.example.com",
+  nodeEnv: "production",
+  debug: false,
+});
+// Query
+const user = await client.routes.users.getById.query({ id: "123" });
+// Mutation
+const post = await client.routes.posts.create.mutation({ title: "Hello" });
+// FormMutation
+const result = await client.routes.media.upload.formMutation({ file: myFile });
+// File/FileStream — returns a URL string
+const url = await client.routes.avatar.file();
+// HTML — returns raw HTML string
+const html = await client.routes.page.html();
+// Subscription
+const { unsubscribe, publish } = client.routes.messages[":roomId"].subscription(
+  (message) => console.log("received:", message),
+);
+publish({ roomId: "general", text: "hello" });
+unsubscribe();
+```
+### BrpcClientOptions
+| Option       | Type               | Description                                                           |
+| ------------ | ------------------ | --------------------------------------------------------------------- |
+| `headers`    | `fn \| Headers`    | Default headers for all requests                                      |
+| `fetch`      | `typeof fetch`     | Custom fetch implementation                                           |
+| `WebSocket`  | `typeof WebSocket` | Custom WebSocket implementation                                       |
+| `prefix`     | `string`           | API path prefix                                                       |
+| `apiPrefix`  | `string`           | Additional API prefix                                                 |
+| `s3Endpoint` | `string`           | **Required.** S3/CDN endpoint for resolving storage object URLs       |
+| `nodeEnv`    | `string`           | **Required.** Current environment (`"development"` \| `"production"`) |
+| `debug`      | `boolean`          | Enable client-side debug logging                                      |
+### Cache Keys
+Every procedure exposes helpers for use with query libraries like TanStack Query or `@mateosuarezdev/query`:
+```ts
+// String key
+client.routes.users.getById.getStringKey({ id: "123" });
+// → "users/getById?{"id":"123"}"
+// Array key — input from backend schema
+client.routes.users.getById.getArrayKey({ id: "123" });
+// → ["users/getById", "id", "123"]
+// Array key — no backend inputs
+client.routes.users.list.getArrayKey();
+// → ["users/list"]
+// No-inputs shorthand (always ignores any input)
+client.routes.users.list.getNoInputsArrayKey();
+// → ["users/list"]
+```
+#### Client-side context keys
+`getArrayKey` accepts an optional second `context` argument for keys that are meaningful on the client but not sent to the server — the most common case being scoping cached data by the current user so different users' data never overlaps in the same cache:
+```ts
+// Procedure has no backend input, but cache is scoped per user
+client.routes.workout.getSessions.getArrayKey(undefined, { userId });
+// → ["workout/getSessions", "userId", "abc123"]
+// Procedure has backend input AND needs user scoping
+client.routes.workout.getSession.getArrayKey({ sessionId }, { userId });
+// → ["workout/getSession", "sessionId", "42", "userId", "abc123"]
+```
+`context` keys are sorted and merged with input keys deterministically, so the resulting array is always stable. Invalidation works the same way:
+```ts
+// Invalidate all session queries for a specific user
+queryService.invalidateQueries(["workout/getSessions", "userId", userId]);
+```
+### Utilities
+```ts
+// Update WebSocket auth token (e.g. after token refresh)
+await client.utils.updateWsAuth();
+// Update headers at runtime
+await client.utils.setHeader("Authorization", `Bearer ${newToken}`);
+await client.utils.setHeaders({ "X-Custom": "value" });
+```
+### BrpcClientError
+```ts
+import { BrpcClientError } from "@mateosuarezdev/brpc/client";
+try {
+  await client.routes.auth.login.mutation({ email, password });
+} catch (err) {
+  if (err instanceof BrpcClientError) {
+    err.status; // HTTP status code
+    err.code; // BRPCErrorCode string
+    err.clientCode; // custom client code if set
+    err.isUnauthorized(); // status === 401
+    err.isForbidden(); // status === 403
+    err.isNotFound(); // status === 404
+    err.isValidationError(); // status === 400
+    err.isClientError("INVALID_CREDS"); // clientCode === "INVALID_CREDS"
+  }
+}
+```
+### React
+Import from `@mateosuarezdev/brpc/client/react`:
+```ts
+import { useSubscription } from "@mateosuarezdev/brpc/client/react";
+function ChatRoom({ roomId }: { roomId: string }) {
+  const [messages, setMessages] = useState<Message[]>([]);
+  const { publish } = useSubscription(
+    (callback) => client.routes.messages[":roomId"].subscription(callback),
+    (message) => setMessages((prev) => [...prev, message]),
+  );
+  return (
+    <button onClick={() => publish({ roomId, text: "hello" })}>
+      Send
+    </button>
+  );
+}
+```
+---
+## Schemas
+### createFileSchema
+Validates `File` objects in `formMutation` inputs:
+```ts
+import { createFileSchema } from "@mateosuarezdev/brpc";
+z.object({
+  avatar: createFileSchema({
+    acceptedTypes: {
+      image: ["image/jpeg", "image/png"],
+    },
+    maxSize: 5, // MB
+    minSize: 0.1, // MB
+    messages: {
+      type: "Only JPEG and PNG are allowed",
+      maxSize: "File must be under 5MB",
+    },
+  }),
+  document: createFileSchema({
+    acceptedTypes: { document: "*" },
+    maxSize: 20,
+  }),
+  audio: createFileSchema({
+    acceptedTypes: { audio: "*" },
+  }),
+});
+```
+**Accepted type groups:** `image`, `video`, `audio`, `document`
+Pass `"*"` to accept all types in a group, or an array of specific MIME type strings.
+---
+## Errors
+```ts
+import { BRPCError } from "@mateosuarezdev/brpc";
+// Constructor
+throw new BRPCError({
+  code: "UNAUTHORIZED",
+  message: "Token expired",
+  clientCode: "TOKEN_EXPIRED", // readable code for the client
+  data: { expiredAt: new Date() },
+});
+// Static factory shortcuts
+throw BRPCError.unauthorized("Token expired", "TOKEN_EXPIRED");
+throw BRPCError.badRequest("Invalid input", "INVALID_EMAIL");
+throw BRPCError.forbidden("Admins only");
+throw BRPCError.notFound("User not found");
+throw BRPCError.conflict("Email already in use", "EMAIL_TAKEN");
+throw BRPCError.tooManyRequests();
+throw BRPCError.internalServerError();
+```
+### Error Codes and HTTP Status Mapping
+| Code                    | Status |
+| ----------------------- | ------ |
+| `BAD_REQUEST`           | 400    |
+| `UNAUTHORIZED`          | 401    |
+| `FORBIDDEN`             | 403    |
+| `NOT_FOUND`             | 404    |
+| `CONFLICT`              | 409    |
+| `UNPROCESSABLE_CONTENT` | 422    |
+| `TOO_MANY_REQUESTS`     | 429    |
+| `INTERNAL_SERVER_ERROR` | 500    |
+| `SERVICE_UNAVAILABLE`   | 503    |
+Zod validation errors are automatically caught and returned as `BAD_REQUEST` (400) with field-level detail.
+---
+## Streaming Media
+Use `streamMedia` inside a `fileStream` procedure to handle HTTP Range requests automatically:
+```ts
+import { streamMedia } from "@mateosuarezdev/brpc";
+const video = procedure.fileStream(async ({ ctx }) => {
+  const file = Bun.file(`./media/${ctx.params.filename}`);
+  return streamMedia(file, ctx.req, {
+    maxChunkSize: 2 * 1024 * 1024, // 2MB per chunk (default)
+    cacheMaxAge: 3600, // Cache-Control max-age in seconds
+    acceptedExtensions: [".mp4", ".webm", ".ogg"],
+  });
+});
+```
+Responds with `206 Partial Content` when the client sends a `Range` header, enabling native browser seek/scrub for `<video>` and `<audio>` elements.
+---
+## Storage
+All storage utilities are exported from the main package:
+```ts
+import {
+  uploadOne,
+  uploadMany,
+  generateAndUploadImage,
+  uploadGeneratedVariants,
+  deleteOne,
+  deleteMany,
+  generateVariants,
+  getOptimizedImage,
+  getImageMetadata,
+  local,
+} from "@mateosuarezdev/brpc";
+```
+Requires Bun's S3 client to be configured via environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, `AWS_ENDPOINT`, `AWS_BUCKET`).
+### S3
+#### `uploadOne(path, file, opts?)`
+Uploads a single `File` or pre-built buffer object to S3. Returns a `RawUploadResult` with the key, metadata, and provider info ready to insert into the database.
+```ts
+// Plain file upload
+const result = await uploadOne("images/avatars", userFile);
+// With options
+const result = await uploadOne("images/avatars", userFile, {
+  acl: "private",
+  uploadedBy: ctx.session.sub,
+});
+// result.key     — S3 key
+// result.metadata — type, extension, size, dimensions (for images)
+// result.isPrivate
+```
+#### `uploadMany(path, files, opts?)`
+Uploads multiple files in parallel. Returns `{ data, errors }`.
+```ts
+const { data, errors } = await uploadMany("documents", files, {
+  acl: "public-read",
+  throwIf: "any", // "any" | "all" | "ignore"
+});
+```
+#### `generateAndUploadImage(path, file, opts?)`
+The main image upload function. Automatically generates optimized variants (original, compressed, thumbnail, etc.) and uploads them all to S3 in one call.
+```ts
+const uploadResult = await generateAndUploadImage("/exercises", imageFile, {
+  acl: "public-read",
+  uploadedBy: ctx.session.sub,
+  quality: 80,
+});
+// uploadResult.shared  — name, resolvedType, provider, acl, isPrivate
+// uploadResult.variants — keyed object with each variant's key, url, metadata
+```
+#### `uploadGeneratedVariants(path, generated, opts?)`
+Lower-level — uploads pre-generated variants returned by `generateVariants`. Use `generateAndUploadImage` unless you need to modify variants before uploading.
+#### `deleteOne(key, opts?)`
+Deletes a single S3 file by key. Returns `{ key, deleted, error }` — never throws, so caller decides how to handle failure.
+```ts
+const { deleted, error } = await deleteOne("images/avatars/abc.webp");
+if (!deleted) console.error("Failed to delete:", error);
+```
+#### `deleteMany(keys, opts?)`
+Deletes multiple keys in parallel. Returns a per-key result array.
+```ts
+const results = await deleteMany(variantKeys);
+```
+### Images
+#### `generateVariants(file, opts?)`
+Generates optimized image variants from a `File`, `BunFile`, or local path using `sharp`. Returns a `GeneratedImageVariants` object with each variant as an `UploadableObjectBuffer`.
+```ts
+const generated = await generateVariants(imageFile, {
+  quality: 80,
+  acl: "public-read",
+});
+// Pass to uploadGeneratedVariants or inspect variants directly
+```
+#### `getImageMetadata(buffer)`
+Extracts metadata from an image buffer using `sharp`.
+```ts
+const meta = await getImageMetadata(buffer);
+// meta.width, meta.height, meta.aspectRatio, meta.aspectRatioStr
+// meta.type, meta.extension, meta.size
+```
+#### `getOptimizedImage(options)`
+Returns a cached optimized version of an image, creating one on the fly if not yet cached. Useful for serving resized images without re-processing on every request.
+```ts
+const file = await getOptimizedImage({
+  key: "images/photo.jpg",
+  width: 800,
+  quality: 75,
+});
+if (!file) throw BRPCError.notFound();
+return file;
+```
+### Local
+The `local` object provides a filesystem storage backend that mirrors the S3 API. Files are stored under `./buckets/`.
+```ts
+// Upload
+const { data, error } = await local.uploadOne("public/avatars", file);
+if (error) throw BRPCError.internalServerError();
+// data.key, data.bytesWritten
+// Upload many
+const results = await local.uploadMany("public/photos", files);
+// Get
+const file = await local.getOne("public/avatars/abc.jpg");
+if (!file) throw BRPCError.notFound();
+// Delete
+const deleted = await local.deleteOne("public/avatars/abc.jpg");
+```
+---
+## Auth
+Built-in auth service for SurrealDB. Supports email/phone sign-up and sign-in with password or OTP (passwordless), JWT sessions with refresh tokens, and cookie management.
+Import from the `auth` subpath:
+```ts
+import { createAuth, setAuthCookies, clearAuthCookies, parseCookies, COOKIE_NAMES } from "@mateosuarezdev/brpc/auth";
+```
+Requires the `0000_initial.surql` migration to be applied (sets up `users`, `user_identities`, `sessions`, `otp_codes` tables).
+### Server Setup
+```ts
+// services/auth/index.ts
+import { createAuth } from "@mateosuarezdev/brpc/auth";
+import { CacheService } from "@mateosuarezdev/brpc/cache";
+import { db } from "../db";
+export const auth = createAuth({
+  db,
+  secrets: {
+    jwt: process.env.JWT_SECRET!,
+    jwtRefresh: process.env.JWT_REFRESH_SECRET!,
+  },
+  defaultSignupRoles: ["user"],
+  isProd: process.env.NODE_ENV === "production",
+  debug: process.env.NODE_ENV === "development",
+  cache: CacheService, // in-memory session cache
+  otpProvider: {
+    sendEmailOTP: async ({ email, code }) => {
+      await mailer.send({ to: email, subject: "Your code", text: code });
+    },
+    sendSMSOTP: async ({ phone, code }) => {
+      await sms.send({ to: phone, body: code });
+    },
+  },
+});
+```
+#### `createAuth` Config
+| Option                | Type            | Description                                              |
+| --------------------- | --------------- | -------------------------------------------------------- |
+| `db`                  | `Surreal`       | Connected SurrealDB instance                             |
+| `secrets.jwt`         | `string`        | JWT signing secret for access tokens                     |
+| `secrets.jwtRefresh`  | `string`        | JWT signing secret for refresh tokens                    |
+| `defaultSignupRoles`  | `string[]`      | Roles assigned to new users on sign-up                   |
+| `cache`               | `CacheService`  | Optional in-memory session cache to reduce DB reads      |
+| `otpProvider`         | `OTPProvider`   | Callbacks for delivering OTP codes                       |
+| `accessTokenExpiry`   | `string`        | JWT expiry string (default: `"15m"`)                     |
+| `isProd`              | `boolean`       | Enables `Secure` flag on cookies                         |
+| `debug`               | `boolean`       | Logs auth events                                         |
+| `disableCleanupCron`  | `boolean`       | Disables the automatic expired-session cleanup job       |
+### Auth Routes
+```ts
+// routes/auth.ts
+import { auth } from "../services/auth";
+export const authRoutes = {
+  signUpEmail: apiProcedure
+    .input(z.object({
+      email: z.email(),
+      password: z.string().optional(),
+      passwordless: z.boolean().optional(),
+      userMetadata: z.object({ name: z.string().nullable() }).optional(),
+    }))
+    .mutation(async ({ input, ctx }) => {
+      // Returns AuthResponse on password sign-up, OTPResponse on passwordless
+      return auth.signUp({ type: "email", ...input }, ctx.req);
+    }),
+  signInEmail: apiProcedure
+    .input(z.object({
+      email: z.string(),
+      password: z.string().optional(),
+      passwordless: z.boolean().optional(),
+    }))
+    .mutation(async ({ input, ctx }) => {
+      return auth.signIn({ type: "email", ...input }, ctx.req);
+    }),
+  signUpPhone: apiProcedure
+    .input(z.object({ phone: z.string(), passwordless: z.boolean().optional() }))
+    .mutation(async ({ input, ctx }) => {
+      return auth.signUp({ type: "phone", ...input }, ctx.req);
+    }),
+  signInPhone: apiProcedure
+    .input(z.object({ phone: z.string(), passwordless: z.boolean().optional() }))
+    .mutation(async ({ input, ctx }) => {
+      return auth.signIn({ type: "phone", ...input }, ctx.req);
+    }),
+  verifyOTP: apiProcedure
+    .input(z.object({ otpId: z.string(), code: z.string().length(6) }))
+    .mutation(async ({ input, ctx }) => {
+      // Always returns AuthResponse — OTP verification always completes sign-in
+      return auth.verifyOTP(input.otpId, input.code, ctx.req);
+    }),
+  signOut: apiUserProcedure.mutation(async ({ ctx }) => {
+    await auth.signOut(ctx.session!.sessionId);
+    return { success: true };
+  }),
+  refreshToken: apiProcedure
+    .input(z.object({ refreshToken: z.string() }))
+    .mutation(async ({ input }) => {
+      return auth.refreshTokens(input.refreshToken);
+    }),
+};
+```
+### Context Integration
+Verify sessions in context so `ctx.session` is available to all procedures:
+```ts
+// router/context/index.ts
+import { createAuth } from "@mateosuarezdev/brpc/auth";
+import {
+  parseCookies,
+  COOKIE_NAMES,
+  setAuthCookies,
+} from "@mateosuarezdev/brpc/auth";
+import { auth } from "../services/auth";
+export const context = createContext(async (req) => {
+  const authHeader = req.headers.get("authorization");
+  const cookieHeader = req.headers.get("cookie");
+  const headers = new Headers();
+  let session = null;
+  // Header-based auth (API / mobile clients)
+  if (authHeader) {
+    session = auth.getCachedSession(authHeader)
+      ?? await auth.fastVerifyToken(authHeader);
+    if (session) auth.cacheSession(authHeader, session);
+  }
+  // Cookie-based auth (SSR / web clients)
+  else if (cookieHeader) {
+    const cookies = parseCookies(cookieHeader);
+    const accessToken = cookies[COOKIE_NAMES.ACCESS_TOKEN];
+    if (accessToken) {
+      const bearer = `Bearer ${accessToken}`;
+      session = auth.getCachedSession(bearer)
+        ?? await auth.fastVerifyToken(bearer);
+      if (session) auth.cacheSession(bearer, session);
+      // Refresh if near expiry
+      if (session && auth.isTokenNearExpiry(session.exp)) {
+        const refresh = cookies[COOKIE_NAMES.REFRESH_TOKEN];
+        if (refresh) {
+          try {
+            const result = await auth.refreshTokens(refresh);
+            auth.invalidateCachedSession(bearer);
+            setAuthCookies(headers, result, isProd);
+            const newBearer = `Bearer ${result.accessToken}`;
+            session = await auth.fastVerifyToken(newBearer);
+            if (session) auth.cacheSession(newBearer, session);
+          } catch {}
+        }
+      }
+    }
+  }
+  return { session, headers };
+});
+```
+#### Session Type (`DecodedJWT`)
+| Field          | Type           | Description                       |
+| -------------- | -------------- | --------------------------------- |
+| `sub`          | `string`       | User ID                           |
+| `sessionId`    | `string`       | Session record ID                 |
+| `appMetadata`  | `AppMetadata`  | Roles and custom app metadata     |
+| `userMetadata` | `UserMetadata` | Name, theme, preferred language   |
+| `exp`          | `number`       | Token expiry (Unix timestamp)     |
+#### Cookie Helpers
+```ts
+import { setAuthCookies, clearAuthCookies, parseCookies, COOKIE_NAMES } from "@mateosuarezdev/brpc/auth";
+// Set auth cookies on the response (after sign-in)
+setAuthCookies(headers, { accessToken, refreshToken, sessionId }, isProd);
+// Clear auth cookies (on sign-out)
+clearAuthCookies(headers, isProd);
+// Parse cookie header into a plain object
+const cookies = parseCookies(req.headers.get("cookie"));
+const token = cookies[COOKIE_NAMES.ACCESS_TOKEN];
+// Cookie names
+COOKIE_NAMES.ACCESS_TOKEN  // "access_token"
+COOKIE_NAMES.REFRESH_TOKEN // "refresh_token"
+COOKIE_NAMES.SESSION_ID    // "session_id"
+```
+### Client-Side Auth
+For React Native / React apps, wrap your app in `AuthProvider` and use the `useAuth` hook.
+```ts
+// auth/provider.tsx
+import { AuthProvider } from "./provider";
+export default function App() {
+  return (
+    <AuthProvider debug={__DEV__}>
+      <RootNavigator />
+    </AuthProvider>
+  );
+}
+```
+```ts
+// Anywhere inside the tree
+import { useAuth } from "./auth/context";
+function ProfileScreen() {
+  const { session, signOut, checkUserRoles } = useAuth();
+  const isAdmin = checkUserRoles("admin");
+  return (
+    <View>
+      <Text>{session?.user.userMetadata.name}</Text>
+      {isAdmin && <AdminPanel />}
+      <Button onPress={signOut} title="Sign out" />
+    </View>
+  );
+}
+```
+#### `AuthProvider` manages:
+- Restoring session from `AsyncStorage` on app start
+- Proactive token refresh (checked every 5 minutes and on app init)
+- Setting the `Authorization` header on the brpc client after sign-in/refresh
+- Clearing local session and headers on sign-out
+#### `useAuth()` returns:
+| Field            | Type                                | Description                                   |
+| ---------------- | ----------------------------------- | --------------------------------------------- |
+| `status`         | `"pending" \| "settled" \| "error"` | Auth initialization state                     |
+| `session`        | `AuthResponse \| null`              | Current session including user and tokens     |
+| `otpResponse`    | `OTPResponse \| null`               | Pending OTP state (set after passwordless req) |
+| `signUpEmailOTP` | `fn`                                | Start email passwordless sign-up              |
+| `signInEmailOTP` | `fn`                                | Start email passwordless sign-in              |
+| `verifyOTP`      | `fn`                                | Complete OTP flow with 6-digit code           |
+| `signOut`        | `fn`                                | Sign out and clear local session              |
+| `checkUserRoles` | `fn`                                | Check if current user has required roles      |
+#### `checkUserRoles(roles, options?)`
+```ts
+checkUserRoles("admin"); // single role
+checkUserRoles(["admin", "staff"]); // any of these (default)
+checkUserRoles(["admin", "staff"], { requireAll: true }); // must have all
+checkUserRoles("editor", { adminBypass: false }); // admins not auto-allowed
+```
+---
+## Type Inference Utilities
+```ts
+import type {
+  InferProcedureInput,
+  InferProcedureOutput,
+  InferRouterOutput,
+} from "@mateosuarezdev/brpc";
+// Infer types from a procedure
+type CreatePostInput = InferProcedureInput<typeof routes.posts.create>;
+type CreatePostOutput = InferProcedureOutput<typeof routes.posts.create>;
+// Infer the full output shape of a routes object
+type AppOutput = InferRouterOutput<typeof routes>;
+type UserOutput = AppOutput["users"]["getById"];
+```
+---
+## Environment Variables
+| Variable             | Default    | Description                            |
+| -------------------- | ---------- | -------------------------------------- |
+| `MAX_WS_CONNECTIONS` | `1000`     | Max simultaneous WebSocket connections |
+| `WS_TIMEOUT`         | `30000`    | WebSocket idle timeout in ms           |
+| `MAX_REQUEST_SIZE`   | `10485760` | Max request body size in bytes (10MB)  |
+| `REQUEST_TIMEOUT`    | `30000`    | Default procedure timeout in ms        |
+| `ROUTE_CACHE_SIZE`   | `1000`     | Route matcher cache size               |