@niledatabase/server 5.0.0-alpha.12 → 5.0.0-alpha.14

package/dist/index.d.mts

@@ -140,15 +140,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>;
+    /**
+     * 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>(): 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 +218,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 +240,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 +260,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 +322,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;
     }, 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>;
@@ -496,92 +607,93 @@ 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
+     * Preserve incoming request headers when running extensions.
      */
     preserveHeaders?: boolean;
 };

package/dist/index.d.ts

@@ -140,15 +140,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>;
+    /**
+     * 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>(): 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 +218,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 +240,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 +260,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 +322,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;
     }, 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>;
@@ -496,92 +607,93 @@ 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
+     * Preserve incoming request headers when running extensions.
      */
     preserveHeaders?: boolean;
 };