@niledatabase/server 5.0.0-alpha.3 → 5.0.0-alpha.30

package/dist/index.d.mts

@@ -1,32 +1,38 @@
 import pg, { PoolConfig, PoolClient } from 'pg';
 
+type LogFunction = (message: string | unknown, meta?: Record<string, unknown>) => void;
+type Loggable = {
+    info: LogFunction;
+    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 = {
+    runExtensions: <T = ExtensionReturns>(toRun: ExtensionState, config: Config, params?: any, _init?: RequestInit & {
+        request: Request;
+    }) => 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[];
-    };
-    logger?: LoggerType;
-    /**
-     * 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;
+    handlers: RouteFunctions;
+    paths: ConfigurablePaths;
+    extensionCtx: ExtensionCtx;
+    extensions?: Extension[];
+    logger: LogReturn;
+    context: PartialContext;
     /**
      * The nile-auth url
      */
@@ -47,7 +53,7 @@ declare class Config {
      */
     routePrefix: string;
     db: NilePoolConfig;
-    constructor(config?: NileConfig, logger?: string);
+    constructor(config?: ConfigConstructor);
 }
 
 type Routes = {
@@ -70,193 +76,10 @@ type Routes = {
     PASSWORD_RESET: string;
     LOG: string;
     VERIFY_EMAIL: string;
+    INVITES: string;
+    INVITE: string;
 };
 
-type Opts = {
-    basePath?: string;
-    fetch?: typeof fetch;
-};
-type NilePoolConfig = PoolConfig & {
-    afterCreate?: AfterCreate;
-};
-type LoggerType = {
-    info?: (args: unknown | unknown[]) => void;
-    warn?: (args: unknown | unknown[]) => void;
-    error?: (args: unknown | unknown[]) => void;
-    debug?: (args: unknown | unknown[]) => void;
-};
-type NileConfig = {
-    /**
-     * The specific database id. Either passed in or figured out by NILEDB_API_URL
-     * process.env.NILEDB_ID
-     */
-    databaseId?: string;
-    /**
-     * The user UUID to the database
-     * process.env.NILEDB_USER
-     */
-    user?: string;
-    /**
-     * The password UUID to the database
-     * process.env.NILEDB_PASSWORD
-     */
-    password?: string;
-    /**
-     * The name of the database. Automatically obtained from NILEDB_POSTGRES_URL
-     * process.env.NILEDB_NAME
-     */
-    databaseName?: string;
-    /**
-     * A tenant id. Scopes requests to a specific tenant, both API and DB
-     * process.env.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
-     */
-    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
-     */
-    debug?: boolean;
-    /**
-     * DB configuration overrides. Environment variables are the way to go, but maybe you need something more
-     */
-    db?: NilePoolConfig;
-    /**
-     * Some kind of logger if you want to send to an external service
-     */
-    logger?: LoggerType;
-    /**
-     * The configuration value that maps to `NILEDB_API_URL` - its going to be nile-auth (or similar service)
-     */
-    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.
-     */
-    callbackUrl?: string | undefined;
-    /**
-     * Need to override some routes? Change it here
-     */
-    routes?: Partial<Routes>;
-    /**
-     * don't like the default `/api`? change it here
-     */
-    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
-     */
-    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?: 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
-     */
-    headers?: null | Headers | Record<string, string>;
-};
-type NileDb = NilePoolConfig & {
-    tenantId?: string;
-};
-type AfterCreate = (conn: PoolClient, done: (err: null | Error, conn: PoolClient) => void) => void;
-interface NileBody<R, B> {
-    readonly body: ReadableStream<Uint8Array> | null | B;
-    readonly bodyUsed: boolean;
-    arrayBuffer(): Promise<ArrayBuffer>;
-    blob(): Promise<Blob>;
-    formData(): Promise<FormData>;
-    json(): Promise<R>;
-    text(): Promise<string>;
-}
-interface NResponse<T> extends NileBody<T, any> {
-    readonly headers: Headers;
-    readonly ok: boolean;
-    readonly redirected: boolean;
-    readonly status: number;
-    readonly statusText: string;
-    readonly type: ResponseType;
-    readonly url: string;
-    clone(): Response;
-}
-interface NRequest<T> extends NileBody<any, T> {
-    /** Returns the cache mode associated with request, which is a string indicating how the request will interact with the browser's cache when fetching. */
-    readonly cache: RequestCache;
-    /** Returns the credentials mode associated with request, which is a string indicating whether credentials will be sent with the request always, never, or only when sent to a same-origin URL. */
-    readonly credentials: RequestCredentials;
-    /** Returns the kind of resource requested by request, e.g., "document" or "script". */
-    readonly destination: RequestDestination;
-    /** Returns a Headers object consisting of the headers associated with request. Note that headers added in the network layer by the user agent will not be accounted for in this object, e.g., the "Host" header. */
-    readonly headers: Headers;
-    /** Returns request's subresource integrity metadata, which is a cryptographic hash of the resource being fetched. Its value consists of multiple hashes separated by whitespace. [SRI] */
-    readonly integrity: string;
-    /** Returns a boolean indicating whether or not request can outlive the global in which it was created. */
-    readonly keepalive: boolean;
-    /** Returns request's HTTP method, which is "GET" by default. */
-    readonly method: string;
-    /** Returns the mode associated with request, which is a string indicating whether the request will use CORS, or will be restricted to same-origin URLs. */
-    readonly mode: RequestMode;
-    /** Returns the redirect mode associated with request, which is a string indicating how redirects for the request will be handled during fetching. A request will follow redirects by default. */
-    readonly redirect: RequestRedirect;
-    /** Returns the referrer of request. Its value can be a same-origin URL if explicitly set in init, the empty string to indicate no referrer, and "about:client" when defaulting to the global's default. This is used during fetching to determine the value of the `Referer` header of the request being made. */
-    readonly referrer: string;
-    /** Returns the referrer policy associated with request. This is used during fetching to compute the value of the request's referrer. */
-    readonly referrerPolicy: ReferrerPolicy;
-    /** Returns the signal associated with request, which is an AbortSignal object indicating whether or not request has been aborted, and its abort event handler. */
-    readonly signal: AbortSignal;
-    /** Returns the URL of request as a string. */
-    readonly url: string;
-    clone(): Request;
-}
-type NileRequest<T> = NRequest<T> | T;
-declare const APIErrorErrorCodeEnum: {
-    readonly InternalError: "internal_error";
-    readonly BadRequest: "bad_request";
-    readonly EntityNotFound: "entity_not_found";
-    readonly DuplicateEntity: "duplicate_entity";
-    readonly InvalidCredentials: "invalid_credentials";
-    readonly UnknownOidcProvider: "unknown_oidc_provider";
-    readonly ProviderAlreadyExists: "provider_already_exists";
-    readonly ProviderConfigError: "provider_config_error";
-    readonly ProviderMismatch: "provider_mismatch";
-    readonly ProviderUpdateError: "provider_update_error";
-    readonly SessionStateMissing: "session_state_missing";
-    readonly SessionStateMismatch: "session_state_mismatch";
-    readonly OidcCodeMissing: "oidc_code_missing";
-};
-type APIErrorErrorCodeEnum = (typeof APIErrorErrorCodeEnum)[keyof typeof APIErrorErrorCodeEnum];
-interface APIError {
-    [key: string]: any | any;
-    /**
-     *
-     * @type {string}
-     * @memberof APIError
-     */
-    errorCode: APIErrorErrorCodeEnum;
-    /**
-     *
-     * @type {string}
-     * @memberof APIError
-     */
-    message: string;
-    /**
-     *
-     * @type {number}
-     * @memberof APIError
-     */
-    statusCode: number;
-}
-type NileResponse<T> = Promise<T | NResponse<T & APIError>>;
-
 interface CreateBasicUserRequest {
     email: string;
     password: string;
@@ -304,56 +127,90 @@ interface User {
     tenants: string[];
 }
 
-type Tenant = {
-    id: string;
-    name: string;
-};
-
-type ProviderName = 'discord' | 'github' | 'google' | 'hubspot' | 'linkedin' | 'slack' | 'twitter' | 'email' | 'credentials' | 'azure';
-type Providers = {
-    [providerName in ProviderName]: Provider;
-};
-type Provider = {
-    id: string;
-    name: string;
-    type: string;
-    signinUrl: string;
-    callbackUrl: string;
-};
-type JWT = {
-    email: string;
-    sub: string;
-    id: string;
-    iat: number;
-    exp: number;
-    jti: string;
-};
-type ActiveSession = {
-    id: string;
-    email: string;
-    expires: string;
-    user?: {
-        id: string;
-        name: string;
-        image: string;
-        email: string;
-        emailVerified: void | Date;
-    };
-};
-
+/**
+ * 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>;
-    verifySelf<T = Response | void>(): Promise<T>;
-    verifySelf(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: {
+        bypassEmail?: boolean;
+        callbackUrl?: string;
+    }, rawResponse?: true): Promise<T>;
 }
 
+type Tenant = {
+    id: string;
+    name: string;
+};
+type Invite = {
+    id: string;
+    tenant_id: string;
+    token: string;
+    identifier: string;
+    roles: null | string;
+    created_by: string;
+    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;
@@ -364,106 +221,301 @@ type JoinTenantRequest = string | ReqContext | {
 declare class Tenants {
     #private;
     constructor(config: Config);
+    create(name: string, rawResponse: true): Promise<Response>;
     create<T = Tenant | Response>(name: string, rawResponse?: boolean): Promise<T>;
     create<T = Tenant | Response>(payload: {
         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>;
+    get<T = Tenant | Response>(): Promise<T>;
     get<T = Tenant | Response>(id: string, rawResponse?: boolean): Promise<T>;
     get(rawResponse: true): Promise<Response>;
     get<T = Tenant | Response>(payload: {
         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;
+        redirectUrl?: string;
+    }, rawResponse?: boolean): Promise<T>;
+    invite(req: string | {
+        email: string;
+        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;
+        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>;
 }
 
+type ProviderName = 'discord' | 'github' | 'google' | 'hubspot' | 'linkedin' | 'slack' | 'twitter' | 'email' | 'credentials' | 'azure';
+type Providers = {
+    [providerName in ProviderName]: Provider;
+};
+type Provider = {
+    id: string;
+    name: string;
+    type: string;
+    signinUrl: string;
+    callbackUrl: string;
+};
+type JWT = {
+    email: string;
+    sub: string;
+    id: string;
+    iat: number;
+    exp: number;
+    jti: string;
+};
+type ActiveSession = {
+    id: string;
+    email: string;
+    expires: string;
+    user?: {
+        id: string;
+        name: string;
+        image: string;
+        email: string;
+        emailVerified: void | Date;
+    };
+};
+
 type SignUpPayload = {
     email: string;
     password: string;
     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;
@@ -474,40 +526,292 @@ declare class Server {
     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);
+    /** Allows setting of context outside of the request lifecycle
+     * Basically means you want to disregard cookies and do everything manually
+     * If we elect to DDL, we don't want to use tenant id or user id, so remove those.
+     */
+    withContext(context?: PartialContext): Promise<this>;
+    withContext<T>(context: PartialContext, fn: (sdk: this) => Promise<T>): Promise<T>;
     /**
-     * A convenience function that applies a config and ensures whatever was passed is set properly
+     * Creates a context without a user id and a tenant id, but keeps the headers around for auth at least.
      */
-    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;
-    };
+    noContext(): Promise<this>;
+    noContext<T>(fn: (sdk: this) => Promise<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
+     *
+     * @returns the last used (basically global) context object, useful for debugging or making your own context
      */
-    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;
+    getContext(): Context;
+}
+declare function create<T = Server>(config?: NileConfig): T;
+
+type Opts = {
+    basePath?: string;
+    fetch?: typeof fetch;
+};
+type Context = {
+    headers: Headers;
+    tenantId: string | undefined | null;
+    userId: string | undefined | null;
+    preserveHeaders: boolean;
+};
+type PartialContext = {
+    headers?: null | Headers;
+    tenantId?: string | undefined | null;
+    userId?: string | undefined | null;
+    preserveHeaders?: 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;
+    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"
 }
-declare function create(config?: NileConfig): Server;
+type NilePoolConfig = PoolConfig & {
+    afterCreate?: AfterCreate;
+};
+type LoggerType = {
+    info: (args: unknown | unknown[]) => void;
+    warn: (args: unknown | unknown[]) => void;
+    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 = {
+    /**
+     * Unique ID of the database.
+     * If omitted, the value is derived from `NILEDB_API_URL`.
+     * Environment variable: `NILEDB_ID`.
+     */
+    databaseId?: string;
+    /**
+     * Database user used for authentication.
+     * Environment variable: `NILEDB_USER`.
+     */
+    user?: string;
+    /**
+     * Password for the configured user.
+     * Environment variable: `NILEDB_PASSWORD`.
+     */
+    password?: string;
+    /**
+     * Database name. Defaults to the name parsed from
+     * `NILEDB_POSTGRES_URL` when not provided.
+     * Environment variable: `NILEDB_NAME`.
+     */
+    databaseName?: string;
+    /**
+     * Tenant context used for scoping API and DB calls.
+     * Environment variable: `NILEDB_TENANT`.
+     */
+    tenantId?: string | null | undefined;
+    /**
+     * 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;
+    /** Enable verbose logging of SDK behaviour. */
+    debug?: boolean;
+    /**
+     * Optional Postgres connection configuration.
+     * Environment variables will be used for any values not set here.
+     */
+    db?: NilePoolConfig;
+    /** Custom logger implementation. */
+    logger?: LogReturn;
+    /**
+     * Base URL for nile-auth requests.
+     * Environment variable: `NILEDB_API_URL`.
+     */
+    apiUrl?: string | undefined;
+    /**
+     * Override the client provided callback URL during authentication.
+     * Environment variable: `NILEDB_CALLBACK_URL`.
+     */
+    callbackUrl?: string | undefined;
+    /** Override default API routes. */
+    routes?: Partial<Routes>;
+    /** Prefix applied to all generated routes. */
+    routePrefix?: string | undefined;
+    /**
+     * Force usage of secure cookies when communicating with nile-auth.
+     * Defaults to `true` when `NODE_ENV` is `production`.
+     * Environment variable: `NILEDB_SECURECOOKIES`.
+     */
+    secureCookies?: boolean;
+    /**
+     * 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;
+    /**
+     * Additional headers sent with every API request.
+     * Include a `cookie` header to forward session information.
+     */
+    headers?: null | Headers | Record<string, string>;
+    /** Hooks executed before and after each request. */
+    extensions?: Extension[];
+    /**
+     * Preserve incoming request headers when running extensions.
+     */
+    preserveHeaders?: boolean;
+};
+type NileDb = NilePoolConfig & {
+    tenantId?: string;
+};
+type AfterCreate = (conn: PoolClient, done: (err: null | Error, conn: PoolClient) => void) => void;
+interface NileBody<R, B> {
+    readonly body: ReadableStream<Uint8Array> | null | B;
+    readonly bodyUsed: boolean;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    blob(): Promise<Blob>;
+    formData(): Promise<FormData>;
+    json(): Promise<R>;
+    text(): Promise<string>;
+}
+interface NResponse<T> extends NileBody<T, any> {
+    readonly headers: Headers;
+    readonly ok: boolean;
+    readonly redirected: boolean;
+    readonly status: number;
+    readonly statusText: string;
+    readonly type: ResponseType;
+    readonly url: string;
+    clone(): Response;
+}
+interface NRequest<T> extends NileBody<any, T> {
+    /** Returns the cache mode associated with request, which is a string indicating how the request will interact with the browser's cache when fetching. */
+    readonly cache: RequestCache;
+    /** Returns the credentials mode associated with request, which is a string indicating whether credentials will be sent with the request always, never, or only when sent to a same-origin URL. */
+    readonly credentials: RequestCredentials;
+    /** Returns the kind of resource requested by request, e.g., "document" or "script". */
+    readonly destination: RequestDestination;
+    /** Returns a Headers object consisting of the headers associated with request. Note that headers added in the network layer by the user agent will not be accounted for in this object, e.g., the "Host" header. */
+    readonly headers: Headers;
+    /** Returns request's subresource integrity metadata, which is a cryptographic hash of the resource being fetched. Its value consists of multiple hashes separated by whitespace. [SRI] */
+    readonly integrity: string;
+    /** Returns a boolean indicating whether or not request can outlive the global in which it was created. */
+    readonly keepalive: boolean;
+    /** Returns request's HTTP method, which is "GET" by default. */
+    readonly method: string;
+    /** Returns the mode associated with request, which is a string indicating whether the request will use CORS, or will be restricted to same-origin URLs. */
+    readonly mode: RequestMode;
+    /** Returns the redirect mode associated with request, which is a string indicating how redirects for the request will be handled during fetching. A request will follow redirects by default. */
+    readonly redirect: RequestRedirect;
+    /** Returns the referrer of request. Its value can be a same-origin URL if explicitly set in init, the empty string to indicate no referrer, and "about:client" when defaulting to the global's default. This is used during fetching to determine the value of the `Referer` header of the request being made. */
+    readonly referrer: string;
+    /** Returns the referrer policy associated with request. This is used during fetching to compute the value of the request's referrer. */
+    readonly referrerPolicy: ReferrerPolicy;
+    /** Returns the signal associated with request, which is an AbortSignal object indicating whether or not request has been aborted, and its abort event handler. */
+    readonly signal: AbortSignal;
+    /** Returns the URL of request as a string. */
+    readonly url: string;
+    clone(): Request;
+}
+type NileRequest<T> = NRequest<T> | T;
+declare const APIErrorErrorCodeEnum: {
+    readonly InternalError: "internal_error";
+    readonly BadRequest: "bad_request";
+    readonly EntityNotFound: "entity_not_found";
+    readonly DuplicateEntity: "duplicate_entity";
+    readonly InvalidCredentials: "invalid_credentials";
+    readonly UnknownOidcProvider: "unknown_oidc_provider";
+    readonly ProviderAlreadyExists: "provider_already_exists";
+    readonly ProviderConfigError: "provider_config_error";
+    readonly ProviderMismatch: "provider_mismatch";
+    readonly ProviderUpdateError: "provider_update_error";
+    readonly SessionStateMissing: "session_state_missing";
+    readonly SessionStateMismatch: "session_state_mismatch";
+    readonly OidcCodeMissing: "oidc_code_missing";
+};
+type APIErrorErrorCodeEnum = (typeof APIErrorErrorCodeEnum)[keyof typeof APIErrorErrorCodeEnum];
+interface APIError {
+    [key: string]: any | any;
+    /**
+     *
+     * @type {string}
+     * @memberof APIError
+     */
+    errorCode: APIErrorErrorCodeEnum;
+    /**
+     *
+     * @type {string}
+     * @memberof APIError
+     */
+    message: string;
+    /**
+     *
+     * @type {number}
+     * @memberof 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 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, type Tenant, 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 };