@niledatabase/server 5.0.0-alpha.13 → 5.0.0-alpha.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -9,28 +9,25 @@ type Loggable = {
9
9
  };
10
10
  type LogReturn = (prefixes?: string | string[]) => Loggable;
11
11
 
12
+ type ConfigurablePaths = {
13
+ get: string[];
14
+ post: string[];
15
+ delete: string[];
16
+ put: string[];
17
+ };
18
+ type ExtensionReturns = void | Response | Request | ExtensionState;
12
19
  type ExtensionCtx = {
13
- handleOnRequest: (config: Config, _init: RequestInit & {
20
+ runExtensions: <T = ExtensionReturns>(toRun: ExtensionState, config: Config, params: any, _init?: RequestInit & {
14
21
  request: Request;
15
- }, params: RequestInit) => Promise<void>;
22
+ }) => Promise<T>;
16
23
  };
17
24
  type ConfigConstructor = NileConfig & {
18
25
  extensionCtx?: ExtensionCtx;
19
26
  };
20
27
  declare class Config {
21
28
  routes: Routes;
22
- handlers: {
23
- GET: (req: Request) => Promise<void | Response>;
24
- POST: (req: Request) => Promise<void | Response>;
25
- DELETE: (req: Request) => Promise<void | Response>;
26
- PUT: (req: Request) => Promise<void | Response>;
27
- };
28
- paths: {
29
- get: string[];
30
- post: string[];
31
- delete: string[];
32
- put: string[];
33
- };
29
+ handlers: RouteFunctions;
30
+ paths: ConfigurablePaths;
34
31
  extensionCtx: ExtensionCtx;
35
32
  extensions?: Extension[];
36
33
  logger: LogReturn;
@@ -521,25 +518,10 @@ declare function parseCallback(headers?: Headers): string | undefined;
521
518
  * Extract the session token cookie from a set of headers.
522
519
  */
523
520
  declare function parseToken(headers?: Headers): string | undefined;
524
-
525
- type CTXHandlerType = {
526
- GET: (req: Request) => Promise<{
527
- response: void | Response;
528
- nile: Server;
529
- }>;
530
- POST: (req: Request) => Promise<{
531
- response: void | Response;
532
- nile: Server;
533
- }>;
534
- DELETE: (req: Request) => Promise<{
535
- response: void | Response;
536
- nile: Server;
537
- }>;
538
- PUT: (req: Request) => Promise<{
539
- response: void | Response;
540
- nile: Server;
541
- }>;
542
- };
521
+ /**
522
+ * Internal helper for the password reset flow.
523
+ */
524
+ declare function parseResetToken(headers: Headers | void): string | void;
543
525
 
544
526
  declare class Server {
545
527
  #private;
@@ -550,23 +532,20 @@ declare class Server {
550
532
  get db(): pg.Pool & {
551
533
  clearConnections: () => void;
552
534
  };
535
+ get logger(): LogReturn;
536
+ get extensions(): {
537
+ remove: (id: string) => Promise<ExtensionResult[] | undefined>;
538
+ add: (extension: Extension) => void;
539
+ };
553
540
  /**
554
541
  * A convenience function that applies a config and ensures whatever was passed is set properly
555
542
  */
556
543
  getInstance<T = Request | Headers | Record<string, string>>(config: NileConfig, req?: T): Server;
557
- getPaths(): {
558
- get: string[];
559
- post: string[];
560
- delete: string[];
561
- put: string[];
562
- };
563
- get handlers(): {
564
- GET: (req: Request) => Promise<void | Response>;
565
- POST: (req: Request) => Promise<void | Response>;
566
- DELETE: (req: Request) => Promise<void | Response>;
567
- PUT: (req: Request) => Promise<void | Response>;
544
+ get handlers(): RouteFunctions & {
568
545
  withContext: CTXHandlerType;
569
546
  };
547
+ get paths(): ConfigurablePaths;
548
+ set paths(paths: ConfigurablePaths);
570
549
  /**
571
550
  * Allow the setting of headers from a req or header object.
572
551
  * Makes it possible to handle REST requests easily
@@ -574,10 +553,10 @@ declare class Server {
574
553
  * @param req
575
554
  * @returns undefined
576
555
  */
577
- setContext(req: Request | Headers | Record<string, string> | unknown | {
556
+ setContext: (req: Request | Headers | Record<string, string> | unknown | {
578
557
  tenantId?: string;
579
558
  userId?: string;
580
- }): void;
559
+ }, ...remaining: unknown[]) => void;
581
560
  getContext(): {
582
561
  headers: Headers | undefined;
583
562
  userId: string | null | undefined;
@@ -591,13 +570,21 @@ type Opts = {
591
570
  basePath?: string;
592
571
  fetch?: typeof fetch;
593
572
  };
594
- interface ExtensionResult {
595
- id?: string;
596
- [key: string]: unknown;
597
- onRequest?: (req: Request) => void | Promise<void | RequestInit>;
598
- onResponse?: (res: Response) => void | Promise<void>;
573
+ type Any = any;
574
+ type ExtensionResult = {
575
+ id: string;
576
+ onRequest?: (...params: Any) => void | Promise<void | RequestInit>;
577
+ onResponse?: (...params: Any) => void | Promise<void>;
578
+ onHandleRequest?: (...params: Any) => RouteReturn | Promise<RouteReturn>;
579
+ onConfigure?: (...params: Any) => void;
580
+ onSetContext?: (...params: Any) => void;
581
+ };
582
+ type Extension = (instance: Server) => ExtensionResult;
583
+ declare enum ExtensionState {
584
+ onHandleRequest = "onHandleRequest",
585
+ onRequest = "onRequest",
586
+ onResponse = "onResposne"
599
587
  }
600
- type Extension = (instance: Server) => ExtensionResult | Promise<ExtensionResult>;
601
588
  type NilePoolConfig = PoolConfig & {
602
589
  afterCreate?: AfterCreate;
603
590
  };
@@ -607,92 +594,93 @@ type LoggerType = {
607
594
  error: (args: unknown | unknown[]) => void;
608
595
  debug: (args: unknown | unknown[]) => void;
609
596
  };
597
+ /**
598
+ * Configuration options used by the {@link Server} class.
599
+ * Most values can be provided via environment variables if not set here.
600
+ */
610
601
  type NileConfig = {
611
602
  /**
612
- * The specific database id. Either passed in or figured out by NILEDB_API_URL
613
- * process.env.NILEDB_ID
603
+ * Unique ID of the database.
604
+ * If omitted, the value is derived from `NILEDB_API_URL`.
605
+ * Environment variable: `NILEDB_ID`.
614
606
  */
615
607
  databaseId?: string;
616
608
  /**
617
- * The user UUID to the database
618
- * process.env.NILEDB_USER
609
+ * Database user used for authentication.
610
+ * Environment variable: `NILEDB_USER`.
619
611
  */
620
612
  user?: string;
621
613
  /**
622
- * The password UUID to the database
623
- * process.env.NILEDB_PASSWORD
614
+ * Password for the configured user.
615
+ * Environment variable: `NILEDB_PASSWORD`.
624
616
  */
625
617
  password?: string;
626
618
  /**
627
- * The name of the database. Automatically obtained from NILEDB_POSTGRES_URL
628
- * process.env.NILEDB_NAME
619
+ * Database name. Defaults to the name parsed from
620
+ * `NILEDB_POSTGRES_URL` when not provided.
621
+ * Environment variable: `NILEDB_NAME`.
629
622
  */
630
623
  databaseName?: string;
631
624
  /**
632
- * A tenant id. Scopes requests to a specific tenant, both API and DB
633
- * process.env.NILEDB_TENANT
625
+ * Tenant context used for scoping API and DB calls.
626
+ * Environment variable: `NILEDB_TENANT`.
634
627
  */
635
628
  tenantId?: string | null | undefined;
636
629
  /**
637
- * A user id. Possibly not the logged in user, used for setting database context (nile.user_id)
638
- * Generally speaking, this wouldn't be used for authentication, and in some cases simply won't do anything on some endpoints
630
+ * Optional user identifier to apply when interacting with the database.
631
+ * In most cases nile-auth injects the logged in user automatically so this
632
+ * value rarely needs to be specified directly. It can be useful when
633
+ * performing administrative actions on behalf of another user.
639
634
  */
640
635
  userId?: string | null | undefined;
641
- /**
642
- * Shows a bunch of logging on the server side to see what's being done between the sdk and nile-auth
643
- */
636
+ /** Enable verbose logging of SDK behaviour. */
644
637
  debug?: boolean;
645
638
  /**
646
- * DB configuration overrides. Environment variables are the way to go, but maybe you need something more
639
+ * Optional Postgres connection configuration.
640
+ * Environment variables will be used for any values not set here.
647
641
  */
648
642
  db?: NilePoolConfig;
649
- /**
650
- * Some kind of logger if you want to send to an external service
651
- */
643
+ /** Custom logger implementation. */
652
644
  logger?: LogReturn;
653
645
  /**
654
- * The configuration value that maps to `NILEDB_API_URL` - its going to be nile-auth (or similar service)
646
+ * Base URL for nile-auth requests.
647
+ * Environment variable: `NILEDB_API_URL`.
655
648
  */
656
649
  apiUrl?: string | undefined;
657
650
  /**
658
- * Ignore client callbackUrls by setting this.
659
- * You can force the callback URL server side to be sure nile-auth redirects to whatever location.
651
+ * Override the client provided callback URL during authentication.
652
+ * Environment variable: `NILEDB_CALLBACK_URL`.
660
653
  */
661
654
  callbackUrl?: string | undefined;
662
- /**
663
- * Need to override some routes? Change it here
664
- */
655
+ /** Override default API routes. */
665
656
  routes?: Partial<Routes>;
666
- /**
667
- * don't like the default `/api`? change it here
668
- */
657
+ /** Prefix applied to all generated routes. */
669
658
  routePrefix?: string | undefined;
670
659
  /**
671
- * In some cases, you may want to force secure cookies.
672
- * The SDK handles this for you, but might be necessary in some firewall / internal cases
673
- * Defaults to true if you're in production
660
+ * Force usage of secure cookies when communicating with nile-auth.
661
+ * Defaults to `true` when `NODE_ENV` is `production`.
662
+ * Environment variable: `NILEDB_SECURECOOKIES`.
674
663
  */
675
664
  secureCookies?: boolean;
676
665
  /**
677
- * The origin for the requests.
678
- * Allows the setting of the callback origin to a random FE
679
- * eg FE localhost:3001 -> BE: localhost:5432 would set to localhost:3001 to be sure nile-auth uses that.
680
- * In full stack cases, will just be the `host` header of the incoming request, which is used by default
681
- * 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.
666
+ * Origin for requests made to nile-auth. This controls where users are
667
+ * redirected after authentication. For single-page apps running on a
668
+ * different port than the API, set this to the front-end origin
669
+ * (e.g. `http://localhost:3001`). In a full-stack setup the value defaults
670
+ * to the `host` header of the incoming request. When using secure cookies on
671
+ * server-to-server calls, explicitly setting the origin ensures nile-auth
672
+ * knows whether TLS is being used and which cookies to send.
682
673
  */
683
674
  origin?: null | undefined | string;
684
675
  /**
685
- * Set the headers to use in API requests.
686
- * The `cookie` would be expected if you are setting this, else most calls will be unauthorized
676
+ * Additional headers sent with every API request.
677
+ * Include a `cookie` header to forward session information.
687
678
  */
688
679
  headers?: null | Headers | Record<string, string>;
689
- /**
690
- * Functions to run at various points to make life easier
691
- */
680
+ /** Hooks executed before and after each request. */
692
681
  extensions?: Extension[];
693
682
  /**
694
- * In some cases, like when using REST context, we want to preserve the headers from the request,
695
- * regardless of what an extension might do
683
+ * Preserve incoming request headers when running extensions.
696
684
  */
697
685
  preserveHeaders?: boolean;
698
686
  };
@@ -787,10 +775,30 @@ interface APIError {
787
775
  statusCode: number;
788
776
  }
789
777
  type NileResponse<T> = Promise<T | NResponse<T & APIError>>;
778
+ type ExtensionConfig = {
779
+ disableExtensions: string[];
780
+ };
781
+ type RouteReturn = void | Request | Response | ExtensionState;
782
+ type RouteFunctions = {
783
+ GET: (req: Request, config?: ExtensionConfig, ...args: unknown[]) => Promise<RouteReturn>;
784
+ POST: (req: Request, config?: ExtensionConfig) => Promise<RouteReturn>;
785
+ DELETE: (req: Request, config?: ExtensionConfig) => Promise<RouteReturn>;
786
+ PUT: (req: Request, config?: ExtensionConfig) => Promise<RouteReturn>;
787
+ };
788
+ type ContextReturn = {
789
+ response: RouteReturn;
790
+ nile: Server;
791
+ };
792
+ type CTXHandlerType = {
793
+ GET: (req: Request) => Promise<ContextReturn>;
794
+ POST: (req: Request) => Promise<ContextReturn>;
795
+ DELETE: (req: Request) => Promise<ContextReturn>;
796
+ PUT: (req: Request) => Promise<ContextReturn>;
797
+ };
790
798
 
791
799
  declare const TENANT_COOKIE = "nile.tenant-id";
792
800
  declare const USER_COOKIE = "nile.user-id";
793
801
  declare const HEADER_ORIGIN = "nile-origin";
794
802
  declare const HEADER_SECURE_COOKIES = "nile-secure-cookies";
795
803
 
796
- 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 };
804
+ export { type APIError, APIErrorErrorCodeEnum, type ActiveSession, type AfterCreate, type CTXHandlerType, 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 NilePoolConfig, type NileRequest, type NileResponse, type Opts, type Providers, type RouteFunctions, type RouteReturn, Server, TENANT_COOKIE, type Tenant, USER_COOKIE, type User, parseCSRF, parseCallback, parseResetToken, parseToken };
package/dist/index.d.ts CHANGED
@@ -9,28 +9,25 @@ type Loggable = {
9
9
  };
10
10
  type LogReturn = (prefixes?: string | string[]) => Loggable;
11
11
 
12
+ type ConfigurablePaths = {
13
+ get: string[];
14
+ post: string[];
15
+ delete: string[];
16
+ put: string[];
17
+ };
18
+ type ExtensionReturns = void | Response | Request | ExtensionState;
12
19
  type ExtensionCtx = {
13
- handleOnRequest: (config: Config, _init: RequestInit & {
20
+ runExtensions: <T = ExtensionReturns>(toRun: ExtensionState, config: Config, params: any, _init?: RequestInit & {
14
21
  request: Request;
15
- }, params: RequestInit) => Promise<void>;
22
+ }) => Promise<T>;
16
23
  };
17
24
  type ConfigConstructor = NileConfig & {
18
25
  extensionCtx?: ExtensionCtx;
19
26
  };
20
27
  declare class Config {
21
28
  routes: Routes;
22
- handlers: {
23
- GET: (req: Request) => Promise<void | Response>;
24
- POST: (req: Request) => Promise<void | Response>;
25
- DELETE: (req: Request) => Promise<void | Response>;
26
- PUT: (req: Request) => Promise<void | Response>;
27
- };
28
- paths: {
29
- get: string[];
30
- post: string[];
31
- delete: string[];
32
- put: string[];
33
- };
29
+ handlers: RouteFunctions;
30
+ paths: ConfigurablePaths;
34
31
  extensionCtx: ExtensionCtx;
35
32
  extensions?: Extension[];
36
33
  logger: LogReturn;
@@ -521,25 +518,10 @@ declare function parseCallback(headers?: Headers): string | undefined;
521
518
  * Extract the session token cookie from a set of headers.
522
519
  */
523
520
  declare function parseToken(headers?: Headers): string | undefined;
524
-
525
- type CTXHandlerType = {
526
- GET: (req: Request) => Promise<{
527
- response: void | Response;
528
- nile: Server;
529
- }>;
530
- POST: (req: Request) => Promise<{
531
- response: void | Response;
532
- nile: Server;
533
- }>;
534
- DELETE: (req: Request) => Promise<{
535
- response: void | Response;
536
- nile: Server;
537
- }>;
538
- PUT: (req: Request) => Promise<{
539
- response: void | Response;
540
- nile: Server;
541
- }>;
542
- };
521
+ /**
522
+ * Internal helper for the password reset flow.
523
+ */
524
+ declare function parseResetToken(headers: Headers | void): string | void;
543
525
 
544
526
  declare class Server {
545
527
  #private;
@@ -550,23 +532,20 @@ declare class Server {
550
532
  get db(): pg.Pool & {
551
533
  clearConnections: () => void;
552
534
  };
535
+ get logger(): LogReturn;
536
+ get extensions(): {
537
+ remove: (id: string) => Promise<ExtensionResult[] | undefined>;
538
+ add: (extension: Extension) => void;
539
+ };
553
540
  /**
554
541
  * A convenience function that applies a config and ensures whatever was passed is set properly
555
542
  */
556
543
  getInstance<T = Request | Headers | Record<string, string>>(config: NileConfig, req?: T): Server;
557
- getPaths(): {
558
- get: string[];
559
- post: string[];
560
- delete: string[];
561
- put: string[];
562
- };
563
- get handlers(): {
564
- GET: (req: Request) => Promise<void | Response>;
565
- POST: (req: Request) => Promise<void | Response>;
566
- DELETE: (req: Request) => Promise<void | Response>;
567
- PUT: (req: Request) => Promise<void | Response>;
544
+ get handlers(): RouteFunctions & {
568
545
  withContext: CTXHandlerType;
569
546
  };
547
+ get paths(): ConfigurablePaths;
548
+ set paths(paths: ConfigurablePaths);
570
549
  /**
571
550
  * Allow the setting of headers from a req or header object.
572
551
  * Makes it possible to handle REST requests easily
@@ -574,10 +553,10 @@ declare class Server {
574
553
  * @param req
575
554
  * @returns undefined
576
555
  */
577
- setContext(req: Request | Headers | Record<string, string> | unknown | {
556
+ setContext: (req: Request | Headers | Record<string, string> | unknown | {
578
557
  tenantId?: string;
579
558
  userId?: string;
580
- }): void;
559
+ }, ...remaining: unknown[]) => void;
581
560
  getContext(): {
582
561
  headers: Headers | undefined;
583
562
  userId: string | null | undefined;
@@ -591,13 +570,21 @@ type Opts = {
591
570
  basePath?: string;
592
571
  fetch?: typeof fetch;
593
572
  };
594
- interface ExtensionResult {
595
- id?: string;
596
- [key: string]: unknown;
597
- onRequest?: (req: Request) => void | Promise<void | RequestInit>;
598
- onResponse?: (res: Response) => void | Promise<void>;
573
+ type Any = any;
574
+ type ExtensionResult = {
575
+ id: string;
576
+ onRequest?: (...params: Any) => void | Promise<void | RequestInit>;
577
+ onResponse?: (...params: Any) => void | Promise<void>;
578
+ onHandleRequest?: (...params: Any) => RouteReturn | Promise<RouteReturn>;
579
+ onConfigure?: (...params: Any) => void;
580
+ onSetContext?: (...params: Any) => void;
581
+ };
582
+ type Extension = (instance: Server) => ExtensionResult;
583
+ declare enum ExtensionState {
584
+ onHandleRequest = "onHandleRequest",
585
+ onRequest = "onRequest",
586
+ onResponse = "onResposne"
599
587
  }
600
- type Extension = (instance: Server) => ExtensionResult | Promise<ExtensionResult>;
601
588
  type NilePoolConfig = PoolConfig & {
602
589
  afterCreate?: AfterCreate;
603
590
  };
@@ -607,92 +594,93 @@ type LoggerType = {
607
594
  error: (args: unknown | unknown[]) => void;
608
595
  debug: (args: unknown | unknown[]) => void;
609
596
  };
597
+ /**
598
+ * Configuration options used by the {@link Server} class.
599
+ * Most values can be provided via environment variables if not set here.
600
+ */
610
601
  type NileConfig = {
611
602
  /**
612
- * The specific database id. Either passed in or figured out by NILEDB_API_URL
613
- * process.env.NILEDB_ID
603
+ * Unique ID of the database.
604
+ * If omitted, the value is derived from `NILEDB_API_URL`.
605
+ * Environment variable: `NILEDB_ID`.
614
606
  */
615
607
  databaseId?: string;
616
608
  /**
617
- * The user UUID to the database
618
- * process.env.NILEDB_USER
609
+ * Database user used for authentication.
610
+ * Environment variable: `NILEDB_USER`.
619
611
  */
620
612
  user?: string;
621
613
  /**
622
- * The password UUID to the database
623
- * process.env.NILEDB_PASSWORD
614
+ * Password for the configured user.
615
+ * Environment variable: `NILEDB_PASSWORD`.
624
616
  */
625
617
  password?: string;
626
618
  /**
627
- * The name of the database. Automatically obtained from NILEDB_POSTGRES_URL
628
- * process.env.NILEDB_NAME
619
+ * Database name. Defaults to the name parsed from
620
+ * `NILEDB_POSTGRES_URL` when not provided.
621
+ * Environment variable: `NILEDB_NAME`.
629
622
  */
630
623
  databaseName?: string;
631
624
  /**
632
- * A tenant id. Scopes requests to a specific tenant, both API and DB
633
- * process.env.NILEDB_TENANT
625
+ * Tenant context used for scoping API and DB calls.
626
+ * Environment variable: `NILEDB_TENANT`.
634
627
  */
635
628
  tenantId?: string | null | undefined;
636
629
  /**
637
- * A user id. Possibly not the logged in user, used for setting database context (nile.user_id)
638
- * Generally speaking, this wouldn't be used for authentication, and in some cases simply won't do anything on some endpoints
630
+ * Optional user identifier to apply when interacting with the database.
631
+ * In most cases nile-auth injects the logged in user automatically so this
632
+ * value rarely needs to be specified directly. It can be useful when
633
+ * performing administrative actions on behalf of another user.
639
634
  */
640
635
  userId?: string | null | undefined;
641
- /**
642
- * Shows a bunch of logging on the server side to see what's being done between the sdk and nile-auth
643
- */
636
+ /** Enable verbose logging of SDK behaviour. */
644
637
  debug?: boolean;
645
638
  /**
646
- * DB configuration overrides. Environment variables are the way to go, but maybe you need something more
639
+ * Optional Postgres connection configuration.
640
+ * Environment variables will be used for any values not set here.
647
641
  */
648
642
  db?: NilePoolConfig;
649
- /**
650
- * Some kind of logger if you want to send to an external service
651
- */
643
+ /** Custom logger implementation. */
652
644
  logger?: LogReturn;
653
645
  /**
654
- * The configuration value that maps to `NILEDB_API_URL` - its going to be nile-auth (or similar service)
646
+ * Base URL for nile-auth requests.
647
+ * Environment variable: `NILEDB_API_URL`.
655
648
  */
656
649
  apiUrl?: string | undefined;
657
650
  /**
658
- * Ignore client callbackUrls by setting this.
659
- * You can force the callback URL server side to be sure nile-auth redirects to whatever location.
651
+ * Override the client provided callback URL during authentication.
652
+ * Environment variable: `NILEDB_CALLBACK_URL`.
660
653
  */
661
654
  callbackUrl?: string | undefined;
662
- /**
663
- * Need to override some routes? Change it here
664
- */
655
+ /** Override default API routes. */
665
656
  routes?: Partial<Routes>;
666
- /**
667
- * don't like the default `/api`? change it here
668
- */
657
+ /** Prefix applied to all generated routes. */
669
658
  routePrefix?: string | undefined;
670
659
  /**
671
- * In some cases, you may want to force secure cookies.
672
- * The SDK handles this for you, but might be necessary in some firewall / internal cases
673
- * Defaults to true if you're in production
660
+ * Force usage of secure cookies when communicating with nile-auth.
661
+ * Defaults to `true` when `NODE_ENV` is `production`.
662
+ * Environment variable: `NILEDB_SECURECOOKIES`.
674
663
  */
675
664
  secureCookies?: boolean;
676
665
  /**
677
- * The origin for the requests.
678
- * Allows the setting of the callback origin to a random FE
679
- * eg FE localhost:3001 -> BE: localhost:5432 would set to localhost:3001 to be sure nile-auth uses that.
680
- * In full stack cases, will just be the `host` header of the incoming request, which is used by default
681
- * 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.
666
+ * Origin for requests made to nile-auth. This controls where users are
667
+ * redirected after authentication. For single-page apps running on a
668
+ * different port than the API, set this to the front-end origin
669
+ * (e.g. `http://localhost:3001`). In a full-stack setup the value defaults
670
+ * to the `host` header of the incoming request. When using secure cookies on
671
+ * server-to-server calls, explicitly setting the origin ensures nile-auth
672
+ * knows whether TLS is being used and which cookies to send.
682
673
  */
683
674
  origin?: null | undefined | string;
684
675
  /**
685
- * Set the headers to use in API requests.
686
- * The `cookie` would be expected if you are setting this, else most calls will be unauthorized
676
+ * Additional headers sent with every API request.
677
+ * Include a `cookie` header to forward session information.
687
678
  */
688
679
  headers?: null | Headers | Record<string, string>;
689
- /**
690
- * Functions to run at various points to make life easier
691
- */
680
+ /** Hooks executed before and after each request. */
692
681
  extensions?: Extension[];
693
682
  /**
694
- * In some cases, like when using REST context, we want to preserve the headers from the request,
695
- * regardless of what an extension might do
683
+ * Preserve incoming request headers when running extensions.
696
684
  */
697
685
  preserveHeaders?: boolean;
698
686
  };
@@ -787,10 +775,30 @@ interface APIError {
787
775
  statusCode: number;
788
776
  }
789
777
  type NileResponse<T> = Promise<T | NResponse<T & APIError>>;
778
+ type ExtensionConfig = {
779
+ disableExtensions: string[];
780
+ };
781
+ type RouteReturn = void | Request | Response | ExtensionState;
782
+ type RouteFunctions = {
783
+ GET: (req: Request, config?: ExtensionConfig, ...args: unknown[]) => Promise<RouteReturn>;
784
+ POST: (req: Request, config?: ExtensionConfig) => Promise<RouteReturn>;
785
+ DELETE: (req: Request, config?: ExtensionConfig) => Promise<RouteReturn>;
786
+ PUT: (req: Request, config?: ExtensionConfig) => Promise<RouteReturn>;
787
+ };
788
+ type ContextReturn = {
789
+ response: RouteReturn;
790
+ nile: Server;
791
+ };
792
+ type CTXHandlerType = {
793
+ GET: (req: Request) => Promise<ContextReturn>;
794
+ POST: (req: Request) => Promise<ContextReturn>;
795
+ DELETE: (req: Request) => Promise<ContextReturn>;
796
+ PUT: (req: Request) => Promise<ContextReturn>;
797
+ };
790
798
 
791
799
  declare const TENANT_COOKIE = "nile.tenant-id";
792
800
  declare const USER_COOKIE = "nile.user-id";
793
801
  declare const HEADER_ORIGIN = "nile-origin";
794
802
  declare const HEADER_SECURE_COOKIES = "nile-secure-cookies";
795
803
 
796
- 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 };
804
+ export { type APIError, APIErrorErrorCodeEnum, type ActiveSession, type AfterCreate, type CTXHandlerType, 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 NilePoolConfig, type NileRequest, type NileResponse, type Opts, type Providers, type RouteFunctions, type RouteReturn, Server, TENANT_COOKIE, type Tenant, USER_COOKIE, type User, parseCSRF, parseCallback, parseResetToken, parseToken };