@haatlabs-core/nest-common 0.0.0-stage → 0.10.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Haatlabs
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @haatlabs-core/nest-common
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+What every app's NestJS API shares, below authentication.
+
+- **Tokens** (`CONFIG`, `LOGGER`, `APP_DB`, `SYSTEM_DB`, `REDIS`, `RATE_LIMITER`, `METRICS`,
+  `PLAIN_FETCH`, `FETCH`, `MAILER`, `TOKEN_CIPHER`, `STORE_TOKENS`): registered symbols, so
+  two installed copies name the same provider. An app's `infra/tokens.ts` re-exports them
+  beside its own.
+- `AppExceptionFilter`: every error as `{ error: { code, message, requestId } }`; a fault of
+  ours is INTERNAL, logged without SQL or bound values, and never shown.
+- `HtmlProblemFilter` with the provider `HTML_PROBLEM_OPTIONS`: a page, not JSON, for a
+  refusal a person's browser was sent to.
+- `ZodPipe`, `Public` / `OptionalAuth` (the auth mode nest-auth's guard reads).
+- `MAILER` is bound by the app to `@haatlabs-core/mailer`'s `mailerFromConfig(config.mail)`.
+- `requireFeature` / `requireFeatureFor` over a `FeatureSource`, with `FEATURE_ERRORS`
+  (spread into `defineErrors` by an app with plans).
+- `HealthController` (`/health/live`, `/health/ready`) over the provider `HEALTH_CHECKS`,
+  with `postgresCheck` and `redisCheck`; a check may be `advisory` and cached (`cacheMs`).
+- `createFastifyApp(module, options)`: request IDs, a span per request, metrics by route
+  pattern, helmet, cookies, CORS and the OpenAPI document. `installShutdown` and
+  `warnAuthMisconfig` for the app's main. `oneMonthAfter`. `observeHttp` is given before the
+  app exists, so an app makes its metrics in `main` (with `@haatlabs-core/observability/metrics`)
+  and hands the same object to its module as `METRICS`.
+
+Every `@nestjs/*` package, `fastify`, `ioredis`, `drizzle-orm` and `zod` are peers.
+
+## Install
+
+    pnpm add @haatlabs-core/nest-common
+
+It leaves these packages to your app, so the app holds one copy: `@fastify/cookie`, `@fastify/helmet`, `@nestjs/common`, `@nestjs/core`, `@nestjs/platform-fastify`, `@nestjs/swagger`, `drizzle-orm`, `fastify`, `ioredis`, `reflect-metadata`, `rxjs`, `zod`.

package/dist/auth-metadata.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether a route needs a signed-in principal. Kept here, below the auth package, so that
+ * shared controllers (health) can be public; nest-auth's guard reads the same key.
+ */
+export declare const AUTH_MODE = "auth:mode";
+export type AuthMode = 'required' | 'optional' | 'public';
+/** No authentication is attempted (login, OAuth callback, webhooks, health). */
+export declare const Public: () => MethodDecorator & ClassDecorator;
+/** Authenticates when credentials are present but allows anonymous requests. */
+export declare const OptionalAuth: () => MethodDecorator & ClassDecorator;

package/dist/auth-metadata.js

@@ -0,0 +1,11 @@
+import { SetMetadata } from '@nestjs/common';
+/**
+ * Whether a route needs a signed-in principal. Kept here, below the auth package, so that
+ * shared controllers (health) can be public; nest-auth's guard reads the same key.
+ */
+export const AUTH_MODE = 'auth:mode';
+/** No authentication is attempted (login, OAuth callback, webhooks, health). */
+export const Public = () => SetMetadata(AUTH_MODE, 'public');
+/** Authenticates when credentials are present but allows anonymous requests. */
+export const OptionalAuth = () => SetMetadata(AUTH_MODE, 'optional');
+//# sourceMappingURL=auth-metadata.js.map

package/dist/auth-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-metadata.js","sourceRoot":"","sources":["../src/auth-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAC;AAGrC,gFAAgF;AAChF,MAAM,CAAC,MAAM,MAAM,GAAG,GAAqC,EAAE,CAC3D,WAAW,CAAC,SAAS,EAAE,QAA2B,CAAC,CAAC;AACtD,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAG,GAAqC,EAAE,CACjE,WAAW,CAAC,SAAS,EAAE,UAA6B,CAAC,CAAC"}

package/dist/cjs/auth-metadata.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether a route needs a signed-in principal. Kept here, below the auth package, so that
+ * shared controllers (health) can be public; nest-auth's guard reads the same key.
+ */
+export declare const AUTH_MODE = "auth:mode";
+export type AuthMode = 'required' | 'optional' | 'public';
+/** No authentication is attempted (login, OAuth callback, webhooks, health). */
+export declare const Public: () => MethodDecorator & ClassDecorator;
+/** Authenticates when credentials are present but allows anonymous requests. */
+export declare const OptionalAuth: () => MethodDecorator & ClassDecorator;

package/dist/cjs/auth-metadata.js

@@ -0,0 +1,34 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var auth_metadata_exports = {};
+__export(auth_metadata_exports, {
+  AUTH_MODE: () => AUTH_MODE,
+  OptionalAuth: () => OptionalAuth,
+  Public: () => Public
+});
+module.exports = __toCommonJS(auth_metadata_exports);
+var import_common = require("@nestjs/common");
+const AUTH_MODE = "auth:mode";
+const Public = () => (0, import_common.SetMetadata)(AUTH_MODE, "public");
+const OptionalAuth = () => (0, import_common.SetMetadata)(AUTH_MODE, "optional");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AUTH_MODE,
+  OptionalAuth,
+  Public
+});

package/dist/cjs/error.filter.d.ts

@@ -0,0 +1,20 @@
+import type { ArgumentsHost, ExceptionFilter } from '@nestjs/common';
+import type { Logger } from '@haatlabs-core/logger';
+/** The body of every error answer. */
+export interface ErrorEnvelope {
+    error: {
+        code: string;
+        message: string;
+        requestId: string;
+    };
+}
+/**
+ * Every error an app's API answers, as `{ error: { code, message, requestId } }`. An
+ * AppError keeps its code and status; a fault of ours is INTERNAL, logged without SQL or
+ * bound values, and never shown.
+ */
+export declare class AppExceptionFilter implements ExceptionFilter {
+    private readonly logger;
+    constructor(logger: Logger);
+    catch(exception: unknown, host: ArgumentsHost): void;
+}

package/dist/cjs/error.filter.js

@@ -0,0 +1,111 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var error_filter_exports = {};
+__export(error_filter_exports, {
+  AppExceptionFilter: () => AppExceptionFilter
+});
+module.exports = __toCommonJS(error_filter_exports);
+var import_common = require("@nestjs/common");
+var import_errors = require("@haatlabs-core/errors");
+var import_tokens = require("./tokens.js");
+var __decorate = function(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = function(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+};
+const MS_PER_SECOND = 1e3;
+const SERVER_ERROR_MIN = 500;
+const CLIENT_ERROR_MIN = 400;
+const HTTP_ERROR_MAX = 599;
+const INTERNAL_STATUS = 500;
+const HTTP_STATUS_CODES = {
+  400: "VALIDATION_FAILED",
+  401: "UNAUTHENTICATED",
+  403: "FORBIDDEN",
+  404: "NOT_FOUND",
+  409: "CONFLICT",
+  413: "VALIDATION_FAILED",
+  429: "RATE_LIMITED"
+};
+const isHttpErrorStatus = (status) => Number.isInteger(status) && status >= CLIENT_ERROR_MIN && status <= HTTP_ERROR_MAX;
+const codeForStatus = (status) => status >= SERVER_ERROR_MIN ? "INTERNAL" : HTTP_STATUS_CODES[status] ?? "VALIDATION_FAILED";
+function isFastifyClientError(exception) {
+  if (typeof exception !== "object" || exception === null)
+    return false;
+  const { code, statusCode } = exception;
+  return typeof code === "string" && code.startsWith("FST_") && typeof statusCode === "number" && Number.isInteger(statusCode) && statusCode >= CLIENT_ERROR_MIN && statusCode < SERVER_ERROR_MIN;
+}
+let AppExceptionFilter = class AppExceptionFilter2 {
+  logger;
+  constructor(logger) {
+    this.logger = logger;
+  }
+  catch(exception, host) {
+    const http = host.switchToHttp();
+    const request = http.getRequest();
+    const reply = http.getResponse();
+    const requestId = String(request.id);
+    let status = INTERNAL_STATUS;
+    let code = "INTERNAL";
+    let message = "Internal server error";
+    if (exception instanceof import_errors.AppError) {
+      status = exception.httpStatus;
+      code = exception.code;
+      if (status !== INTERNAL_STATUS)
+        message = exception.message;
+      if (exception.retryAfterMs !== void 0)
+        reply.header("Retry-After", Math.ceil(exception.retryAfterMs / MS_PER_SECOND));
+    } else if (exception instanceof import_common.HttpException) {
+      const httpStatus = exception.getStatus();
+      if (isHttpErrorStatus(httpStatus)) {
+        status = httpStatus;
+        code = codeForStatus(status);
+        if (status < SERVER_ERROR_MIN)
+          message = exception.message;
+      }
+    } else if (isFastifyClientError(exception)) {
+      status = exception.statusCode;
+      code = codeForStatus(status);
+      message = "Request could not be processed";
+    }
+    if (status >= SERVER_ERROR_MIN) {
+      const safeMessage = (0, import_errors.safeErrorMessage)(exception);
+      const isQueryFailure = exception instanceof Error && safeMessage !== exception.message;
+      this.logger.error({
+        requestId,
+        err: exception instanceof Error ? { message: safeMessage, ...isQueryFailure ? {} : { stack: exception.stack } } : safeMessage
+      }, "Unhandled error");
+    }
+    const body = { error: { code, message, requestId } };
+    void reply.status(status).send(body);
+  }
+};
+AppExceptionFilter = __decorate([
+  (0, import_common.Catch)(),
+  __param(0, (0, import_common.Inject)(import_tokens.LOGGER))
+], AppExceptionFilter);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AppExceptionFilter
+});

package/dist/cjs/fastify-app.d.ts

@@ -0,0 +1,16 @@
+import 'reflect-metadata';
+import type { DynamicModule, Type } from '@nestjs/common';
+import type { NestFastifyApplication } from '@nestjs/platform-fastify';
+export interface FastifyAppOptions {
+    /** Reverse proxies whose X-Forwarded-For is trusted; 0 trusts none. */
+    trustProxyHops: number;
+    corsOrigins: string[];
+    bodyLimit?: number;
+    /** The longest a path parameter may be; a longer one is answered 414. Fastify's 100 by default. */
+    maxParamLength?: number;
+    /** The OpenAPI document served at `/api/docs`; none when not given. */
+    openApi?: () => object;
+    /** Called once per response, with the route's pattern (never the address asked for). */
+    observeHttp?: (method: string, route: string, status: number, seconds: number) => void;
+}
+export declare function createFastifyApp(module: Type<unknown> | DynamicModule, options: FastifyAppOptions): Promise<NestFastifyApplication>;

package/dist/cjs/fastify-app.js

@@ -0,0 +1,109 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var fastify_app_exports = {};
+__export(fastify_app_exports, {
+  createFastifyApp: () => createFastifyApp
+});
+module.exports = __toCommonJS(fastify_app_exports);
+var import_reflect_metadata = require("reflect-metadata");
+var import_node_crypto = require("node:crypto");
+var import_cookie = __toESM(require("@fastify/cookie"));
+var import_helmet = __toESM(require("@fastify/helmet"));
+var import_core = require("@nestjs/core");
+var import_platform_fastify = require("@nestjs/platform-fastify");
+var import_swagger = require("@nestjs/swagger");
+var import_observability = require("@haatlabs-core/observability");
+const DEFAULT_BODY_LIMIT_BYTES = 1024 * 1024;
+const DEFAULT_MAX_PARAM_LENGTH = 100;
+const BAD_REQUEST = 400;
+const URI_TOO_LONG = 414;
+const TOO_LONG_MESSAGE = "The address is too long.";
+const BAD_ADDRESS_MESSAGE = "The address is not valid.";
+const MS_PER_SECOND = 1e3;
+const REQUEST_ID_HEADER = "x-request-id";
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+const HTTP_SPAN = Symbol("haatlabs.httpSpan");
+async function createFastifyApp(module2, options) {
+  const adapter = new import_platform_fastify.FastifyAdapter({
+    // Only as many X-Forwarded-For hops as are configured; a direct client cannot forge request.ip.
+    // Fastify 5 treats a numeric trustProxy as "trust nothing", so the hop count is a function.
+    trustProxy: options.trustProxyHops === 0 ? false : (_address, hop) => hop < options.trustProxyHops,
+    bodyLimit: options.bodyLimit ?? DEFAULT_BODY_LIMIT_BYTES,
+    maxParamLength: options.maxParamLength ?? DEFAULT_MAX_PARAM_LENGTH,
+    // What the router refuses before any hook or filter runs (an address it cannot decode, a
+    // parameter over maxParamLength) is answered in the platform's envelope too, with its ID.
+    frameworkErrors: (error, request, reply) => {
+      const status = typeof error.statusCode === "number" && error.statusCode >= BAD_REQUEST ? error.statusCode : BAD_REQUEST;
+      const requestId = String(request.id);
+      void reply.code(status).header(REQUEST_ID_HEADER, requestId).send({
+        error: {
+          code: "VALIDATION_FAILED",
+          message: status === URI_TOO_LONG ? TOO_LONG_MESSAGE : BAD_ADDRESS_MESSAGE,
+          requestId
+        }
+      });
+    },
+    // An inbound ID is reused only if it is safe to write to logs and headers.
+    genReqId: (request) => {
+      const inbound = request.headers[REQUEST_ID_HEADER];
+      return typeof inbound === "string" && REQUEST_ID_PATTERN.test(inbound) ? inbound : (0, import_node_crypto.randomUUID)();
+    }
+  });
+  const app = await import_core.NestFactory.create(module2, adapter, {
+    rawBody: true,
+    logger: false
+  });
+  const fastify = app.getHttpAdapter().getInstance();
+  fastify.addHook("onRequest", async (request, reply) => {
+    reply.header(REQUEST_ID_HEADER, String(request.id));
+  });
+  fastify.decorateRequest(HTTP_SPAN, null);
+  fastify.addHook("onRequest", (request, _reply, done) => {
+    const span = (0, import_observability.startHttpSpan)(request.method, { requestId: String(request.id) });
+    request[HTTP_SPAN] = span;
+    span.run(done);
+  });
+  fastify.addHook("onResponse", async (request, reply) => {
+    const route = request.is404 ? "" : request.routeOptions.url ?? "";
+    options.observeHttp?.(request.method, route, reply.statusCode, reply.elapsedTime / MS_PER_SECOND);
+    request[HTTP_SPAN]?.end(route, reply.statusCode);
+  });
+  await app.register(import_helmet.default, { contentSecurityPolicy: false });
+  await app.register(import_cookie.default);
+  app.enableCors({ origin: options.corsOrigins, credentials: true });
+  if (options.openApi) {
+    import_swagger.SwaggerModule.setup("api/docs", app, options.openApi());
+  }
+  await app.init();
+  await fastify.ready();
+  return app;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createFastifyApp
+});

package/dist/cjs/feature-gate.d.ts

@@ -0,0 +1,28 @@
+import type { TenantContext } from '@haatlabs-core/db-core';
+/** The code a feature gate refuses with: an app with plans spreads it into defineErrors. */
+export declare const FEATURE_ERRORS: {
+    readonly FEATURE_DISABLED: {
+        readonly httpStatus: 403;
+        readonly transient: false;
+    };
+};
+/** Shown when the plan, not an administrator, is why something is not available. */
+export declare const NOT_IN_PLAN_MESSAGE = "Your plan does not include this. See the plans to add it.";
+/** Shown to a merchant whenever a feature that is off stops something. */
+export declare const FEATURE_OFF_MESSAGE = "This is not available for your account. Contact support to have it turned on.";
+/** Where an app's feature switches are read from: its plans and an administrator's overrides. */
+export interface FeatureSource<F extends string = string> {
+    detail(ctx: TenantContext): Promise<{
+        features: Record<F, boolean>;
+        overridden: F[];
+    }>;
+}
+/**
+ * Stops new work of a kind the organization may not start. Only for routes that start
+ * something: reviewing, applying and rolling back what there is must stay open.
+ */
+export declare function requireFeature<F extends string>(source: FeatureSource<F>, principal: {
+    organizationId: string;
+}, feature: F): Promise<void>;
+/** The same, where there is an organization and no principal yet (an API key being checked). */
+export declare function requireFeatureFor<F extends string>(source: FeatureSource<F>, ctx: TenantContext, feature: F): Promise<void>;

package/dist/cjs/feature-gate.js

@@ -0,0 +1,50 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var feature_gate_exports = {};
+__export(feature_gate_exports, {
+  FEATURE_ERRORS: () => FEATURE_ERRORS,
+  FEATURE_OFF_MESSAGE: () => FEATURE_OFF_MESSAGE,
+  NOT_IN_PLAN_MESSAGE: () => NOT_IN_PLAN_MESSAGE,
+  requireFeature: () => requireFeature,
+  requireFeatureFor: () => requireFeatureFor
+});
+module.exports = __toCommonJS(feature_gate_exports);
+var import_errors = require("@haatlabs-core/errors");
+const FEATURE_ERRORS = {
+  FEATURE_DISABLED: { httpStatus: 403, transient: false }
+};
+const featureErrors = (0, import_errors.domainErrors)(FEATURE_ERRORS);
+const NOT_IN_PLAN_MESSAGE = "Your plan does not include this. See the plans to add it.";
+const FEATURE_OFF_MESSAGE = "This is not available for your account. Contact support to have it turned on.";
+async function requireFeature(source, principal, feature) {
+  await requireFeatureFor(source, { organizationId: principal.organizationId }, feature);
+}
+async function requireFeatureFor(source, ctx, feature) {
+  const { features: on, overridden } = await source.detail(ctx);
+  if (on[feature])
+    return;
+  throw featureErrors.create("FEATURE_DISABLED", overridden.includes(feature) ? FEATURE_OFF_MESSAGE : NOT_IN_PLAN_MESSAGE);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FEATURE_ERRORS,
+  FEATURE_OFF_MESSAGE,
+  NOT_IN_PLAN_MESSAGE,
+  requireFeature,
+  requireFeatureFor
+});