Path Parameters

import { courier, defineGroup } from "@noverax/courier/define"

const { endpoint } = courier()

type User = { id: number; name: string }
type Comment = { id: number; body: string }

const users = defineGroup({
  prefix: "users",
  endpoints: {
    // GET /users/:id -> compiled to GET /users/5
    getById: endpoint.get(":id").variables<{ id: number }>().response<User>(),

    // GET /users/:userId/posts/:postId/comments/:commentId
    getComment: endpoint.get(":userId/posts/:postId/comments/:commentId").variables<{
      userId: number
      postId: number
      commentId: number
    }>().response<Comment>(),
  },
})

import { courier, defineGroup } from "@noverax/courier/define"

const { endpoint } = courier()

type Article = { id: number; title: string }

export const articles = defineGroup({
  prefix: "articles",
  endpoints: {
    // variables: { id: string | number }
    getById: endpoint.get(":id").response<Article>(),
    update: endpoint.put(":id").variables<{ id: number; title: string }>().response<Article>(),
    // @ts-expect-error — the variables do not name :id
    getBySlug: endpoint.get(":id").variables<{ slug: string }>().response<Article>(),
  },
})

// Path params are extracted from the variables object.
// Remaining variables go to query params (GET) or body (POST).

const users = defineGroup({
  prefix: "users",
  endpoints: {
    getById: endpoint.get(":id").variables<{ id: number }>().response<User>(),
    getWithDetails: endpoint.get(":id").variables<{ id: number; include?: string }>().response<User>(),
    updateAvatar: endpoint.post(":id/avatar").variables<{ id: number; name: string }>().response<void>(),
  },
})

// GET /users/5 — { id: 5 } consumed by :id
await caller.users.getById({ id: 5 })

// GET /users/5?include=posts — { id: 5 } consumed by :id, { include: "posts" } -> query param
await caller.users.getWithDetails({ id: 5, include: "posts" })

// POST /users/5/avatar — { id: 5 } consumed by :id, { name: "photo.jpg" } -> JSON body
await caller.users.updateAvatar({ id: 5, name: "photo.jpg" })

import { courier, defineApi, defineGroup } from "@noverax/courier/define"

const { endpoint } = courier()

type User = { id: number; name: string }

const users = defineGroup({
  prefix: "orgs/:orgId/users",
  endpoints: {
    getAll: endpoint.get("").response<User[]>(),
    getById: endpoint.get(":id").variables<{ id: number }>().response<User>(),
  },
})

const api = defineApi({
  baseURL: process.env.API_URL,
  groups: { users },
  // pathOptions provides values for path params that come from context,
  // not from the caller's variables
  pathOptions: async (req) => {
    const cookieHeader = req?.headers.get("cookie") ?? ""
    const orgId = cookieHeader.match(/orgId=([^;]+)/)?.[1]
    return { orgId }
  },
})

// Now every request automatically includes :orgId from the cookie:
// GET /orgs/42/users       — orgId from pathOptions
// GET /orgs/42/users/5     — orgId from pathOptions, id from variables

import { courier, defineGroup } from "@noverax/courier/define"

const { endpoint } = courier()

type Project = { id: number; name: string }
type Task = { id: number; title: string }

const projects = defineGroup({
  prefix: "workspaces/:workspaceId/projects",
  // Group-level pathOptions override source-level pathOptions
  pathOptions: async (req) => {
    // For this group, workspaceId comes from a header
    const workspaceId = req?.headers.get("x-workspace-id")
    return { workspaceId }
  },
  endpoints: {
    getAll: endpoint.get("").response<Project[]>(),
    getById: endpoint.get(":id").variables<{ id: number }>().response<Project>(),
  },
})

const tasks = defineGroup({
  // No group pathOptions — uses the source-level pathOptions if any
  prefix: "tasks",
  endpoints: {
    getAll: endpoint.get("").response<Task[]>(),
  },
})

// The flow of variables through path compilation:

// 1. pathOptions() is called -> returns { orgId: "42" }
// 2. variables from the caller fill the rest: { orgId: "42", id: 5, include: "posts" }
// 3. Path ":orgId/users/:id" consumes orgId and id
// 4. Remaining { include: "posts" } goes to query params (GET) or body (POST)
// 5. Final URL: GET /orgs/42/users/5?include=posts

// Group pathOptions override source pathOptions for the same key:
// Source pathOptions:  { orgId: "42" }
// Group pathOptions:   { orgId: "99" }
// Result:              { orgId: "99" }  <- group wins

// Path compilation functions are cached for performance.
// The first call to compile "/users/:id" creates and caches the regex.
// Subsequent calls reuse the cached function.

// This means paths like "/users/:id" are compiled once,
// no matter how many times they are called with different variables.