@niledatabase/server 5.0.0-alpha.9 → 5.0.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import pg, { PoolConfig, PoolClient } from 'pg';
+import pg, { Pool, PoolConfig, PoolClient } from 'pg';
 
 type LogFunction = (message: string | unknown, meta?: Record<string, unknown>) => void;
 type Loggable = {
@@ -6,46 +6,33 @@ type Loggable = {
     debug: LogFunction;
     warn: LogFunction;
     error: LogFunction;
+    silly: LogFunction;
 };
 type LogReturn = (prefixes?: string | string[]) => Loggable;
 
+type ConfigurablePaths = {
+    get: string[];
+    post: string[];
+    delete: string[];
+    put: string[];
+};
+type ExtensionReturns = void | Response | Request | ExtensionState;
 type ExtensionCtx = {
-    handleOnRequest: (config: Config, _init: RequestInit & {
+    runExtensions: <T = ExtensionReturns>(toRun: ExtensionState, config: Config, params?: any, _init?: RequestInit & {
         request: Request;
-    }, params: RequestInit) => Promise<void>;
+    }) => Promise<T>;
 };
 type ConfigConstructor = NileConfig & {
     extensionCtx?: ExtensionCtx;
 };
 declare class Config {
     routes: Routes;
-    handlers: {
-        GET: (req: Request) => Promise<void | Response>;
-        POST: (req: Request) => Promise<void | Response>;
-        DELETE: (req: Request) => Promise<void | Response>;
-        PUT: (req: Request) => Promise<void | Response>;
-    };
-    paths: {
-        get: string[];
-        post: string[];
-        delete: string[];
-        put: string[];
-    };
+    handlers: RouteFunctions;
+    paths: ConfigurablePaths;
     extensionCtx: ExtensionCtx;
     extensions?: Extension[];
     logger: LogReturn;
-    /**
-     * Stores the set tenant id from Server for use in sub classes
-     */
-    tenantId: string | null | undefined;
-    /**
-     * Stores the set user id from Server for use in sub classes
-     */
-    userId: string | null | undefined;
-    /**
-     * Stores the headers to be used in `fetch` calls
-     */
-    headers: Headers;
+    context: PartialContext;
     /**
      * The nile-auth url
      */
@@ -140,15 +127,62 @@ interface User {
     tenants: string[];
 }
 
+/**
+ * Convenience wrapper around the user endpoints.
+ *
+ * Requests are issued via {@link fetchMe} against `/api/me`. The Swagger
+ * definitions for these APIs live in
+ * `packages/server/src/api/routes/me/index.ts`.
+ */
 declare class Users {
     #private;
+    /**
+     * Create a new Users helper.
+     * @param config - The configuration used for requests.
+     */
     constructor(config: Config);
+    /**
+     * Update the current user via `PUT /api/me`.
+     *
+     * The OpenAPI description for this endpoint can be found in
+     * `packages/server/src/api/routes/me/index.ts` under `updateSelf`.
+     *
+     * @param req - Partial user fields to send.
+     * @param [rawResponse] - When `true`, return the raw {@link Response}.
+     */
     updateSelf<T = User[] | Response>(req: Partial<Omit<User, 'email' | 'tenants' | 'created' | 'updated' | 'emailVerified'> & {
         emailVerified: boolean;
     }>, rawResponse?: boolean): Promise<T>;
+    /**
+     * Remove the current user using `DELETE /api/me`.
+     *
+     * After the request the authentication headers are cleared with
+     * {@link updateHeaders}. The OpenAPI docs for this route are in
+     * `packages/server/src/api/routes/me/index.ts` under `removeSelf`.
+     */
     removeSelf(): Promise<Response>;
-    getSelf<T = User | Response>(): Promise<T>;
-    getSelf(rawResponse?: true): Promise<Response>;
+    /**
+     * Retrieve the current user with `GET /api/me`.
+     *
+     * OpenAPI for this endpoint resides in
+     * `packages/server/src/api/routes/me/index.ts` (`getSelf`).
+     *
+     * @param [rawResponse] - When `true` return the raw {@link Response}.
+     */
+    getSelf<T = User | Response>(rawResponse?: false): Promise<T>;
+    getSelf(rawResponse: true): Promise<Response>;
+    /**
+     * Initiate an email verification flow.
+     *
+     * The current user is fetched and then `/auth/verify-email` is called.
+     * In development or when `bypassEmail` is set, the user's
+     * `emailVerified` field is updated instead of sending an email.
+     * See `packages/server/src/api/routes/auth/verify-email.ts` for the
+     * underlying request.
+     *
+     * @param [options] - Flags controlling bypass behaviour and callback URL.
+     * @param [rawResponse] - When `true` return the raw {@link Response}.
+     */
     verifySelf<T = void>(): Promise<T>;
     verifySelf(rawResponse: true): Promise<Response>;
     verifySelf<T = Response | User>(options: {
@@ -171,6 +205,12 @@ type Invite = {
     expires: Date;
 };
 
+/**
+ * Convenience wrapper around the tenant endpoints. These methods call
+ * the `fetch*` helpers in `packages/server/src/api/routes/tenants` which
+ * in turn hit routes such as `/api/tenants` and `/api/tenants/{tenantId}`.
+ * See those files for the Swagger definitions.
+ */
 type ReqContext = {
     userId?: string;
     tenantId?: string;
@@ -187,7 +227,16 @@ declare class Tenants {
         name: string;
         id?: string;
     }, rawResponse?: boolean): Promise<T>;
+    /**
+     * Delete a tenant using `DELETE /api/tenants/{tenantId}`.
+     * The OpenAPI operation is defined in
+     * `packages/server/src/api/routes/tenants/[tenantId]/DELETE.ts`.
+     */
     delete<T = Response>(id?: string): Promise<T>;
+    /**
+     * Delete a tenant using `DELETE /api/tenants/{tenantId}`.
+     * See `packages/server/src/api/routes/tenants/[tenantId]/DELETE.ts`.
+     */
     delete<T = Response>(payload: {
         id: string;
     }): Promise<T>;
@@ -198,20 +247,58 @@ declare class Tenants {
         id: string;
     }, rawResponse?: boolean): Promise<T>;
     update(req: Partial<Tenant>, rawResponse: true): Promise<Response>;
+    /**
+     * Modify a tenant using `PUT /api/tenants/{tenantId}`.
+     *
+     * @param req - Tenant data to update. Can include an id.
+     * @param [rawResponse] - When true, return the raw {@link Response}.
+     */
     update<T = Tenant | Response | undefined>(req: Partial<Tenant>, rawResponse?: boolean): Promise<T>;
     list<T = Tenant[] | Response>(): Promise<T>;
     list(rawResponse: true): Promise<Response>;
+    /**
+     * Leave the current tenant using `DELETE /api/tenants/{tenantId}/users/{userId}`.
+     *
+     * @param [req] - Optionally specify the tenant id to leave.
+     */
     leaveTenant<T = Response>(req?: string | {
         tenantId: string;
     }): Promise<T>;
     addMember(req: JoinTenantRequest, rawResponse: true): Promise<Response>;
+    /**
+     * Add a user to a tenant via `PUT /api/tenants/{tenantId}/users/{userId}`.
+     *
+     * @param req - User and tenant identifiers or context.
+     * @param [rawResponse] - When true, return the raw {@link Response}.
+     */
     addMember<T = User | Response>(req: JoinTenantRequest, rawResponse?: boolean): Promise<T>;
+    /**
+     * Remove a user from a tenant with `DELETE /api/tenants/{tenantId}/users/{userId}`.
+     *
+     * @param req - User and tenant identifiers or context.
+     * @param [rawResponse] - When true, return the raw {@link Response}.
+     */
     removeMember(req: JoinTenantRequest, rawResponse?: boolean): Promise<Response>;
+    /**
+     * List users for a tenant via `GET /api/tenants/{tenantId}/users`.
+     *
+     * @param [req] - Tenant identifier or context.
+     * @param [rawResponse] - When true, return the raw {@link Response}.
+     */
     users<T = User[] | Response>(req?: boolean | {
         tenantId?: string;
     }, rawResponse?: boolean): Promise<T>;
     users(req: true): Promise<Response>;
+    /**
+     * List invites for the current tenant via `GET /api/tenants/{tenantId}/invites`.
+     */
     invites<T = Invite[] | Response>(): Promise<T>;
+    /**
+     * Send an invitation via `POST /api/tenants/{tenantId}/invite`.
+     *
+     * @param req - Email and optional callback/redirect URLs.
+     * @param [rawResponse] - When true, return the raw {@link Response}.
+     */
     invite<T = Response | Invite>(req: string | {
         email: string;
         callbackUrl?: string;
@@ -222,11 +309,22 @@ declare class Tenants {
         callbackUrl?: string;
         redirectUrl?: string;
     }, rawResponse: true): Promise<Response>;
+    /**
+     * Accept an invite using `PUT /api/tenants/{tenantId}/invite`.
+     *
+     * @param req - Identifier and token from the invite email.
+     * @param [rawResponse] - When true, return the raw {@link Response}.
+     */
     acceptInvite<T = Response>(req?: {
         identifier: string;
         token: string;
-        redirectUrl?: string;
+        callbackUrl?: string;
     }, rawResponse?: boolean): Promise<T>;
+    /**
+     * Delete a pending invite using `DELETE /api/tenants/{tenantId}/invite/{inviteId}`.
+     *
+     * @param req - Identifier of the invite to remove.
+     */
     deleteInvite<T = Response>(req: string | {
         id: string;
     }): Promise<T>;
@@ -270,70 +368,154 @@ type SignUpPayload = {
     tenantId?: string;
     newTenantName?: string;
 };
+/**
+ * Utility class that wraps the server side authentication endpoints.
+ *
+ * The methods in this class call the `fetch*` helpers which are generated
+ * from the OpenAPI specification. Those helpers interact with routes under
+ * the `/api/auth` prefix such as `/session`, `/signin`, `/signout` and others.
+ * By reusing them here we provide a higher level interface for frameworks to
+ * manage user authentication.
+ */
 declare class Auth {
     #private;
+    /**
+     * Create an Auth helper.
+     *
+     * @param config - runtime configuration used by the underlying fetch helpers
+     *   such as `serverOrigin`, `routePrefix` and default headers.
+     */
     constructor(config: Config);
+    /**
+     * Retrieve the currently active session from the API.
+     *
+     * Internally this issues a `GET` request to `/api/auth/session` via
+     * {@link fetchSession}. If `rawResponse` is `true` the raw {@link Response}
+     * object is returned instead of the parsed JSON.
+     *
+     * @template T Return type for the parsed session.
+     * @param rawResponse - set to `true` to get the raw {@link Response} object.
+     */
     getSession<T = JWT | ActiveSession | undefined>(rawResponse?: false): Promise<T>;
     getSession(rawResponse: true): Promise<Response>;
+    /**
+     * Acquire a CSRF token for subsequent authenticated requests.
+     *
+     * Issues a `GET` to `/api/auth/csrf` via {@link obtainCsrf}. When the call
+     * succeeds the returned headers are merged into the current configuration so
+     * future requests include the appropriate cookies.
+     *
+     * @param rawResponse - when `true`, skip JSON parsing and return the raw
+     *   {@link Response}.
+     */
     getCsrf<T = Response | JSON>(rawResponse?: false): Promise<T>;
     getCsrf(rawResponse: true): Promise<Response>;
+    /**
+     * List all configured authentication providers.
+     *
+     * This calls `/api/auth/providers` using {@link fetchProviders} to retrieve
+     * the available provider configuration. Providers are returned as an object
+     * keyed by provider name.
+     *
+     * @param rawResponse - when true, return the {@link Response} instead of the
+     *   parsed JSON.
+     */
     listProviders(rawResponse: true): Promise<Response>;
     listProviders<T = {
         [key: string]: Provider;
     }>(rawResponse?: false): Promise<T>;
+    /**
+     * Sign the current user out by calling `/api/auth/signout`.
+     *
+     * The CSRF token is fetched automatically and the stored cookies are cleared
+     * from the internal configuration once the request completes.
+     */
     signOut(): Promise<Response>;
     /**
-     * signUp only works with email + password
-     * @param payload
-     * @param rawResponse
+     * Create a new user account and start a session.
+     *
+     * This method posts to the `/api/signup` endpoint using
+     * {@link fetchSignUp}. Only the credential provider is supported; a valid
+     * email and password must be supplied. On success the returned session token
+     * is stored in the headers used for subsequent requests.
+     *
+     * @param payload - email and password along with optional tenant
+     *   information.
+     * @param rawResponse - when `true` return the raw {@link Response} rather
+     *   than the parsed {@link User} object.
      */
     signUp(payload: SignUpPayload, rawResponse: true): Promise<Response>;
     signUp<T = User | Response>(payload: SignUpPayload): Promise<T>;
+    /**
+     * Request a password reset email.
+     *
+     * Sends a `POST` to `/api/auth/password-reset` with the provided email and
+     * optional callback information. The endpoint responds with a redirect URL
+     * which is returned as a {@link Response} object.
+     */
     forgotPassword(req: {
         email: string;
         callbackUrl?: string;
         redirectUrl?: string;
     }): Promise<Response>;
+    /**
+     * Complete a password reset.
+     *
+     * This workflow expects a token obtained from {@link forgotPassword}. The
+     * function performs a POST/GET/PUT sequence against
+     * `/api/auth/password-reset` as described in the OpenAPI specification.
+     *
+     * @param req - either a {@link Request} with a JSON body or an object
+     *   containing the necessary fields.
+     */
     resetPassword(req: Request | {
         email: string;
         password: string;
         callbackUrl?: string;
         redirectUrl?: string;
     }): Promise<Response>;
+    /**
+     * Low level helper used by {@link signIn} to complete provider flows.
+     *
+     * Depending on the provider this issues either a GET or POST request to
+     * `/api/auth/callback/{provider}` via {@link fetchCallback}.
+     */
     callback(provider: ProviderName, body?: string | Request): Promise<Response>;
     /**
-     * The return value from this will be a redirect for the client
-     * In most cases, you should forward the response directly to the client
-     * @param payload
-     * @param rawResponse
+     * Sign a user in with one of the configured providers.
+     *
+     * Internally this posts to `/api/auth/signin/{provider}` and follows the
+     * provider callback flow as documented in the OpenAPI spec. When using the
+     * credential provider an email and password must be supplied.
+     *
+     * @param payload - request body or credential object
+     * @param rawResponse - return the raw {@link Response} instead of parsed JSON
      */
     signIn<T = Response>(provider: ProviderName, payload?: Request | {
         email: string;
         password: string;
     }, rawResponse?: true): Promise<T>;
 }
+/**
+ * Extract the CSRF cookie from a set of headers.
+ */
 declare function parseCSRF(headers?: Headers): string | undefined;
+/**
+ * Extract the callback cookie from a set of headers.
+ */
 declare function parseCallback(headers?: Headers): string | undefined;
+/**
+ * Extract the session token cookie from a set of headers.
+ */
 declare function parseToken(headers?: Headers): string | undefined;
-
-type CTXHandlerType = {
-    GET: (req: Request) => Promise<{
-        response: void | Response;
-        nile: Server;
-    }>;
-    POST: (req: Request) => Promise<{
-        response: void | Response;
-        nile: Server;
-    }>;
-    DELETE: (req: Request) => Promise<{
-        response: void | Response;
-        nile: Server;
-    }>;
-    PUT: (req: Request) => Promise<{
-        response: void | Response;
-        nile: Server;
-    }>;
-};
+/**
+ * Internal helper for the password reset flow.
+ */
+declare function parseResetToken(headers: Headers | void): string | void;
+/**
+ * Extract the tenantId cookie from a set of headers.
+ */
+declare function parseTenantId(headers?: Headers): string | null | undefined;
 
 declare class Server {
     #private;
@@ -341,57 +523,94 @@ declare class Server {
     tenants: Tenants;
     auth: Auth;
     constructor(config?: NileConfig);
+    /**
+     * Query the database with the current context
+     */
+    query: Pool['query'];
+    /**
+     * Return a db object that can be used to talk to the database
+     * Does not have a context by default
+     */
     get db(): pg.Pool & {
         clearConnections: () => void;
     };
+    get logger(): LogReturn;
+    get extensions(): {
+        remove: (id: string) => Promise<ExtensionResult<any>[] | undefined>;
+        add: (extension: Extension) => void;
+    };
+    get handlers(): NileHandlers;
+    get paths(): ConfigurablePaths;
+    set paths(paths: ConfigurablePaths);
     /**
-     * A convenience function that applies a config and ensures whatever was passed is set properly
+     * Sets the context for a particular set of requests or db calls to be sure the context is fully managed for the entire lifecycle
      */
-    getInstance<T = Request | Headers | Record<string, string>>(config: NileConfig, req?: T): Server;
-    getPaths(): {
-        get: string[];
-        post: string[];
-        delete: string[];
-        put: string[];
-    };
-    get handlers(): {
-        GET: (req: Request) => Promise<void | Response>;
-        POST: (req: Request) => Promise<void | Response>;
-        DELETE: (req: Request) => Promise<void | Response>;
-        PUT: (req: Request) => Promise<void | Response>;
-        withContext: CTXHandlerType;
-    };
+    withContext(): Promise<this>;
+    withContext<T>(context: PartialContext, fn: AsyncCallback<this, T>): Promise<T>;
+    withContext(context: PartialContext): Promise<this>;
+    withContext<T>(fn: AsyncCallback<this, T>): Promise<T>;
     /**
-     * Allow the setting of headers from a req or header object.
-     * Makes it possible to handle REST requests easily
-     * Also makes it easy to set user + tenant in some way
-     * @param req
-     * @returns undefined
+     * Creates a context without a user id and a tenant id, but keeps the headers around for auth at least.
+     * This is useful for DDL/DML, since most extensions will set the context by default
      */
-    setContext(req: Request | Headers | Record<string, string> | unknown | {
-        tenantId?: string;
-        userId?: string;
-    }): void;
-    getContext(): {
-        headers: Headers | undefined;
-        userId: string | null | undefined;
-        tenantId: string | null | undefined;
-        preserveHeaders: boolean;
-    };
+    noContext(): Promise<this>;
+    noContext<T>(fn: (sdk: this) => Promise<T>): Promise<T>;
+    /**
+     *
+     * @returns the last used (basically global) context object, useful for debugging or making your own context
+     */
+    getContext(): Context;
 }
-declare function create(config?: NileConfig): Server;
+declare function create<T = Server>(config?: NileConfig): T;
+type AsyncCallback<TInstance, TResult> = (sdk: TInstance) => Promise<TResult>;
 
 type Opts = {
     basePath?: string;
     fetch?: typeof fetch;
 };
-interface ExtensionResult {
-    id?: string;
-    [key: string]: unknown;
-    onRequest?: (req: Request) => void | Promise<void | RequestInit>;
-    onResponse?: (res: Response) => void | Promise<void>;
+type Context = {
+    headers: Headers;
+    tenantId: string | undefined | null;
+    userId: string | undefined | null;
+};
+type PartialContext = {
+    headers?: null | Headers;
+    tenantId?: string | undefined | null;
+    userId?: string | undefined | null;
+    useLastContext?: boolean;
+};
+type CTX = {
+    run: <T>(ctx: Partial<Context>, fn: () => T) => T;
+    get: () => Context;
+    set: (partial: Partial<PartialContext>) => void;
+    getLastUsed: () => Context;
+};
+type Any = any;
+type ExtensionResult<TParams> = {
+    id: string;
+    withContext?: (ctx: CTX) => Promise<void>;
+    onRequest?: (params: TParams, ctx: CTX) => void | Promise<void | RequestInit>;
+    onResponse?: (params: TParams, ctx: CTX) => void | Promise<void>;
+    onHandleRequest?: (params?: TParams) => RouteReturn | Promise<RouteReturn>;
+    onConfigure?: (params?: TParams) => void;
+    withUserId?: () => string;
+    withTenantId?: () => string;
+    replace?: {
+        handlers: (handlers: NileHandlers) => Any;
+    };
+};
+type NileHandlers = RouteFunctions & {
+    withContext: CTXHandlerType;
+};
+type Extension<TParams = Any> = (instance: Server) => ExtensionResult<TParams>;
+declare enum ExtensionState {
+    onHandleRequest = "onHandleRequest",
+    onRequest = "onRequest",
+    onResponse = "onResponse",
+    withContext = "withContext",
+    withTenantId = "withTenantId",
+    withUserId = "withUserId"
 }
-type Extension = (instance: Server) => ExtensionResult | Promise<ExtensionResult>;
 type NilePoolConfig = PoolConfig & {
     afterCreate?: AfterCreate;
 };
@@ -401,94 +620,95 @@ type LoggerType = {
     error: (args: unknown | unknown[]) => void;
     debug: (args: unknown | unknown[]) => void;
 };
+/**
+ * Configuration options used by the {@link Server} class.
+ * Most values can be provided via environment variables if not set here.
+ */
 type NileConfig = {
     /**
-     * The specific database id. Either passed in or figured out by NILEDB_API_URL
-     * process.env.NILEDB_ID
+     * Unique ID of the database.
+     * If omitted, the value is derived from `NILEDB_API_URL`.
+     * Environment variable: `NILEDB_ID`.
      */
     databaseId?: string;
     /**
-     * The user UUID to the database
-     * process.env.NILEDB_USER
+     * Database user used for authentication.
+     * Environment variable: `NILEDB_USER`.
      */
     user?: string;
     /**
-     * The password UUID to the database
-     * process.env.NILEDB_PASSWORD
+     * Password for the configured user.
+     * Environment variable: `NILEDB_PASSWORD`.
      */
     password?: string;
     /**
-     * The name of the database. Automatically obtained from NILEDB_POSTGRES_URL
-     * process.env.NILEDB_NAME
+     * Database name. Defaults to the name parsed from
+     * `NILEDB_POSTGRES_URL` when not provided.
+     * Environment variable: `NILEDB_NAME`.
      */
     databaseName?: string;
     /**
-     * A tenant id. Scopes requests to a specific tenant, both API and DB
-     * process.env.NILEDB_TENANT
+     * Tenant context used for scoping API and DB calls.
+     * Environment variable: `NILEDB_TENANT`.
      */
     tenantId?: string | null | undefined;
     /**
-     * A user id. Possibly not the logged in user, used for setting database context (nile.user_id)
-     * Generally speaking, this wouldn't be used for authentication, and in some cases simply won't do anything on some endpoints
+     * Optional user identifier to apply when interacting with the database.
+     * In most cases nile-auth injects the logged in user automatically so this
+     * value rarely needs to be specified directly. It can be useful when
+     * performing administrative actions on behalf of another user.
      */
     userId?: string | null | undefined;
-    /**
-     * Shows a bunch of logging on the server side to see what's being done between the sdk and nile-auth
-     */
+    /** Enable verbose logging of SDK behaviour. */
     debug?: boolean;
     /**
-     * DB configuration overrides. Environment variables are the way to go, but maybe you need something more
+     * Optional Postgres connection configuration.
+     * Environment variables will be used for any values not set here.
      */
     db?: NilePoolConfig;
-    /**
-     * Some kind of logger if you want to send to an external service
-     */
+    /** Custom logger implementation. */
     logger?: LogReturn;
     /**
-     * The configuration value that maps to `NILEDB_API_URL` - its going to be nile-auth (or similar service)
+     * Base URL for nile-auth requests.
+     * Environment variable: `NILEDB_API_URL`.
      */
     apiUrl?: string | undefined;
     /**
-     * Ignore client callbackUrls by setting this.
-     * You can force the callback URL server side to be sure nile-auth redirects to whatever location.
+     * Override the client provided callback URL during authentication.
+     * Environment variable: `NILEDB_CALLBACK_URL`.
      */
     callbackUrl?: string | undefined;
-    /**
-     * Need to override some routes? Change it here
-     */
+    /** Override default API routes. */
     routes?: Partial<Routes>;
-    /**
-     * don't like the default `/api`? change it here
-     */
+    /** Prefix applied to all generated routes. */
     routePrefix?: string | undefined;
     /**
-     * In some cases, you may want to force secure cookies.
-     * The SDK handles this for you, but might be necessary in some firewall / internal cases
-     * Defaults to true if you're in production
+     * Force usage of secure cookies when communicating with nile-auth.
+     * Defaults to `true` when `NODE_ENV` is `production`.
+     * Environment variable: `NILEDB_SECURECOOKIES`.
      */
     secureCookies?: boolean;
     /**
-     * The origin for the requests.
-     * Allows the setting of the callback origin to a random FE
-     * eg FE localhost:3001 -> BE: localhost:5432 would set to localhost:3001 to be sure nile-auth uses that.
-     * In full stack cases, will just be the `host` header of the incoming request, which is used by default
-     * It is also important to set this when dealing with secure cookies. Calling via server side needs to know if TLS is being used so that nile-auth knows which cookies to be sent.
+     * Origin for requests made to nile-auth. This controls where users are
+     * redirected after authentication. For single-page apps running on a
+     * different port than the API, set this to the front-end origin
+     * (e.g. `http://localhost:3001`). In a full-stack setup the value defaults
+     * to the `host` header of the incoming request. When using secure cookies on
+     * server-to-server calls, explicitly setting the origin ensures nile-auth
+     * knows whether TLS is being used and which cookies to send.
      */
     origin?: null | undefined | string;
     /**
-     * Set the headers to use in API requests.
-     * The `cookie` would be expected if you are setting this, else most calls will be unauthorized
+     * Additional headers sent with every API request.
+     * Include a `cookie` header to forward session information.
      */
     headers?: null | Headers | Record<string, string>;
-    /**
-     * Functions to run at various points to make life easier
-     */
+    /** Hooks executed before and after each request. */
     extensions?: Extension[];
     /**
-     * In some cases, like when using REST context, we want to preserve the headers from the request,
-     * regardless of what an extension might do
+     * Re-use the last set context
      */
-    preserveHeaders?: boolean;
+    useLastContext?: boolean;
 };
 type NileDb = NilePoolConfig & {
     tenantId?: string;
@@ -581,10 +801,31 @@ interface APIError {
     statusCode: number;
 }
 type NileResponse<T> = Promise<T | NResponse<T & APIError>>;
+type ExtensionConfig = {
+    disableExtensions: string[];
+};
+type DefaultRouteReturn = Request | Response | ExtensionState;
+type RouteReturn<T = unknown> = void | T | Promise<void | T>;
+type RouteFunctions<T = DefaultRouteReturn> = {
+    GET: (req: Request, config?: ExtensionConfig, ...args: unknown[]) => RouteReturn<T>;
+    POST: (req: Request, config?: ExtensionConfig, ...args: unknown[]) => RouteReturn<T>;
+    DELETE: (req: Request, config?: ExtensionConfig, ...args: unknown[]) => RouteReturn<T>;
+    PUT: (req: Request, config?: ExtensionConfig, ...args: unknown[]) => RouteReturn<T>;
+};
+type ContextReturn<T = Response> = {
+    response: T;
+    nile: Server;
+};
+type CTXHandlerType = {
+    GET: <T = Response>(req: Request) => Promise<ContextReturn<T>>;
+    POST: <T = Response>(req: Request) => Promise<ContextReturn<T>>;
+    DELETE: <T = Response>(req: Request) => Promise<ContextReturn<T>>;
+    PUT: <T = Response>(req: Request) => Promise<ContextReturn<T>>;
+};
 
 declare const TENANT_COOKIE = "nile.tenant-id";
 declare const USER_COOKIE = "nile.user-id";
 declare const HEADER_ORIGIN = "nile-origin";
 declare const HEADER_SECURE_COOKIES = "nile-secure-cookies";
 
-export { type APIError, APIErrorErrorCodeEnum, type ActiveSession, type AfterCreate, type CreateBasicUserRequest, type CreateTenantUserRequest, type Extension, type ExtensionResult, HEADER_ORIGIN, HEADER_SECURE_COOKIES, type Invite, type JWT, type LoggerType, type LoginUserResponse, type LoginUserResponseToken, LoginUserResponseTokenTypeEnum, create as Nile, type NileConfig, type NileDb, type NilePoolConfig, type NileRequest, type NileResponse, type Opts, type Providers, Server, TENANT_COOKIE, type Tenant, USER_COOKIE, type User, parseCSRF, parseCallback, parseToken };
+export { type APIError, APIErrorErrorCodeEnum, type ActiveSession, type AfterCreate, type CTX, type CTXHandlerType, type Context, type ContextReturn, type CreateBasicUserRequest, type CreateTenantUserRequest, type Extension, type ExtensionResult, ExtensionState, HEADER_ORIGIN, HEADER_SECURE_COOKIES, type Invite, type JWT, type LoggerType, type LoginUserResponse, type LoginUserResponseToken, LoginUserResponseTokenTypeEnum, create as Nile, type NileConfig, type NileDb, type NileHandlers, type NilePoolConfig, type NileRequest, type NileResponse, type Opts, type PartialContext, type Providers, type RouteFunctions, type RouteReturn, Server, TENANT_COOKIE, type Tenant, USER_COOKIE, type User, parseCSRF, parseCallback, parseResetToken, parseTenantId, parseToken };