@heavybit/shared-lib 2.1.0 → 2.7.0

package/dist/types/config/index.d.ts

@@ -1,9 +1,5 @@
 import { z } from 'zod';
-/**
- * Environment building blocks. Services compose the pieces they need:
- *
- *   const env = loadEnv(serviceEnv.merge(databaseEnv).merge(messagingEnv).extend({ MY_VAR: z.string() }));
- */
+/** Service identity, logging, CORS and the gateway signing secret. */
 export declare const serviceEnv: z.ZodObject<{
     NODE_ENV: z.ZodDefault<z.ZodEnum<["development", "test", "staging", "production"]>>;
     PORT: z.ZodNumber;
@@ -12,29 +8,46 @@ export declare const serviceEnv: z.ZodObject<{
     APP_NAME: z.ZodDefault<z.ZodString>;
     LOG_LEVEL: z.ZodOptional<z.ZodEnum<["error", "warn", "info", "http", "debug"]>>;
     CORS_ORIGINS: z.ZodDefault<z.ZodString>;
-    /** Verifies gateway-signed identity headers. */
-    GATEWAY_SHARED_SECRET: z.ZodString;
-    /** Authenticates service-to-service `/internal/*` calls. */
-    INTERNAL_SERVICE_SECRET: z.ZodString;
+    /** Verifies gateway-signed identity headers (v2); at least 32 characters, same value on the gateway and every service. */
+    GATEWAY_SIGNING_SECRET: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    NODE_ENV: "production" | "test" | "development" | "staging";
+    NODE_ENV: "development" | "test" | "staging" | "production";
     PORT: number;
     SERVICE_NAME: string;
     APP_NAME: string;
     CORS_ORIGINS: string;
-    GATEWAY_SHARED_SECRET: string;
-    INTERNAL_SERVICE_SECRET: string;
-    LOG_LEVEL?: "info" | "debug" | "error" | "warn" | "http" | undefined;
+    GATEWAY_SIGNING_SECRET: string;
+    LOG_LEVEL?: "error" | "warn" | "info" | "http" | "debug" | undefined;
 }, {
     PORT: number;
     SERVICE_NAME: string;
-    GATEWAY_SHARED_SECRET: string;
-    INTERNAL_SERVICE_SECRET: string;
-    NODE_ENV?: "production" | "test" | "development" | "staging" | undefined;
-    LOG_LEVEL?: "info" | "debug" | "error" | "warn" | "http" | undefined;
+    GATEWAY_SIGNING_SECRET: string;
+    NODE_ENV?: "development" | "test" | "staging" | "production" | undefined;
     APP_NAME?: string | undefined;
+    LOG_LEVEL?: "error" | "warn" | "info" | "http" | "debug" | undefined;
     CORS_ORIGINS?: string | undefined;
 }>;
+/**
+ * Service-to-service credentials. Optional here because development may run without them;
+ * `assertInternalServiceAuthConfigured` enforces them in staging and production.
+ */
+export declare const internalServiceEnv: z.ZodObject<{
+    /** This service's own name (its compose service name), sent with every internal call. */
+    INTERNAL_SERVICE_NAME: z.ZodOptional<z.ZodString>;
+    /** This service's own secret (at least 32 characters), sent with every internal call. */
+    INTERNAL_SERVICE_CREDENTIAL: z.ZodOptional<z.ZodString>;
+    /** JSON map of caller name → secret this service accepts from that caller. */
+    INTERNAL_SERVICE_CREDENTIALS: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    INTERNAL_SERVICE_NAME?: string | undefined;
+    INTERNAL_SERVICE_CREDENTIAL?: string | undefined;
+    INTERNAL_SERVICE_CREDENTIALS?: string | undefined;
+}, {
+    INTERNAL_SERVICE_NAME?: string | undefined;
+    INTERNAL_SERVICE_CREDENTIAL?: string | undefined;
+    INTERNAL_SERVICE_CREDENTIALS?: string | undefined;
+}>;
+/** Database connection env vars (MySQL defaults). */
 export declare const databaseEnv: z.ZodObject<{
     DB_HOST: z.ZodDefault<z.ZodString>;
     DB_PORT: z.ZodDefault<z.ZodNumber>;
@@ -57,6 +70,7 @@ export declare const databaseEnv: z.ZodObject<{
     DB_PASSWORD?: string | undefined;
     DB_POOL_MAX?: number | undefined;
 }>;
+/** RabbitMQ connection and queue-prefix env vars. */
 export declare const messagingEnv: z.ZodObject<{
     RABBITMQ_URL: z.ZodOptional<z.ZodString>;
     RABBITMQ_HOST: z.ZodDefault<z.ZodString>;
@@ -86,30 +100,240 @@ export declare const messagingEnv: z.ZodObject<{
     QUEUE_PREFIX?: string | undefined;
     RABBITMQ_ENABLED?: "true" | "false" | undefined;
 }>;
+/** Redis connection env vars. Keys are prefixed by the keyspace (`createRedisKeyspace`), never by the client. */
 export declare const redisEnv: z.ZodObject<{
+    /** Full connection URL; overrides host/port/password when set. */
     REDIS_URL: z.ZodOptional<z.ZodString>;
+    REDIS_HOST: z.ZodDefault<z.ZodString>;
+    REDIS_PORT: z.ZodDefault<z.ZodNumber>;
+    REDIS_PASSWORD: z.ZodOptional<z.ZodString>;
     REDIS_DB: z.ZodDefault<z.ZodNumber>;
-    /** Key prefix, e.g. `app:dev:` — never share one between apps or environments. */
-    REDIS_PREFIX: z.ZodDefault<z.ZodString>;
+    /**
+     * Environment segment of every Redis key (`{app}:{env}:{service}:…`), e.g. `dev`, `staging`, `prod`.
+     * Required in staging and production; never share one between environments.
+     */
+    CACHE_KEY_PREFIX: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
+    REDIS_HOST: string;
+    REDIS_PORT: number;
     REDIS_DB: number;
-    REDIS_PREFIX: string;
     REDIS_URL?: string | undefined;
+    REDIS_PASSWORD?: string | undefined;
+    CACHE_KEY_PREFIX?: string | undefined;
 }, {
     REDIS_URL?: string | undefined;
+    REDIS_HOST?: string | undefined;
+    REDIS_PORT?: number | undefined;
+    REDIS_PASSWORD?: string | undefined;
     REDIS_DB?: number | undefined;
-    REDIS_PREFIX?: string | undefined;
+    CACHE_KEY_PREFIX?: string | undefined;
 }>;
-/** Builds an AMQP URL from discrete env vars (or returns RABBITMQ_URL when set). */
+/**
+ * Builds an AMQP URL from discrete env vars (or returns RABBITMQ_URL when set). User, password and vhost are URL-encoded.
+ *
+ * @param env Parsed {@link messagingEnv} values.
+ * @returns An `amqp://` URL.
+ * @example const url = amqpUrlFromEnv(parseEnv(messagingEnv));
+ */
 export declare function amqpUrlFromEnv(env: z.infer<typeof messagingEnv>): string;
-/** Reads `KEY=value` lines from a dotenv file into process.env without overriding set values. */
+/**
+ * Reads `KEY=value` lines from a dotenv file into process.env without overriding set values. Missing file is a no-op.
+ *
+ * @param path Dotenv file (default `./.env`).
+ * @example loadDotEnv(resolve(__dirname, '../.env.test'));
+ */
 export declare function loadDotEnv(path?: string): void;
+/** Thrown by the env loader when required variables are missing or invalid; lists every problem. */
 export declare class ConfigError extends Error {
 }
-/** Loads `.env` (if present) and validates process.env. Throws ConfigError listing every problem. */
-export declare function loadEnv<S extends z.ZodTypeAny>(schema: S, source?: NodeJS.ProcessEnv, options?: {
+/**
+ * The base environment every service validates: service identity, gateway secret, database, Redis,
+ * RabbitMQ and internal-service credentials. `loadEnv` merges a service's own schema onto it.
+ */
+export declare const baseEnv: z.ZodObject<{
+    NODE_ENV: z.ZodDefault<z.ZodEnum<["development", "test", "staging", "production"]>>;
+    PORT: z.ZodNumber;
+    SERVICE_NAME: z.ZodString;
+    /** Short app identifier used in exchange names and key prefixes (e.g. `myapp`). */
+    APP_NAME: z.ZodDefault<z.ZodString>;
+    LOG_LEVEL: z.ZodOptional<z.ZodEnum<["error", "warn", "info", "http", "debug"]>>;
+    CORS_ORIGINS: z.ZodDefault<z.ZodString>;
+    /** Verifies gateway-signed identity headers (v2); at least 32 characters, same value on the gateway and every service. */
+    GATEWAY_SIGNING_SECRET: z.ZodString;
+} & {
+    DB_HOST: z.ZodDefault<z.ZodString>;
+    DB_PORT: z.ZodDefault<z.ZodNumber>;
+    DB_USER: z.ZodDefault<z.ZodString>;
+    DB_PASSWORD: z.ZodDefault<z.ZodString>;
+    DB_NAME: z.ZodString;
+    DB_POOL_MAX: z.ZodDefault<z.ZodNumber>;
+} & {
+    /** Full connection URL; overrides host/port/password when set. */
+    REDIS_URL: z.ZodOptional<z.ZodString>;
+    REDIS_HOST: z.ZodDefault<z.ZodString>;
+    REDIS_PORT: z.ZodDefault<z.ZodNumber>;
+    REDIS_PASSWORD: z.ZodOptional<z.ZodString>;
+    REDIS_DB: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Environment segment of every Redis key (`{app}:{env}:{service}:…`), e.g. `dev`, `staging`, `prod`.
+     * Required in staging and production; never share one between environments.
+     */
+    CACHE_KEY_PREFIX: z.ZodOptional<z.ZodString>;
+} & {
+    RABBITMQ_URL: z.ZodOptional<z.ZodString>;
+    RABBITMQ_HOST: z.ZodDefault<z.ZodString>;
+    RABBITMQ_PORT: z.ZodDefault<z.ZodNumber>;
+    RABBITMQ_USER: z.ZodDefault<z.ZodString>;
+    RABBITMQ_PASSWORD: z.ZodDefault<z.ZodString>;
+    RABBITMQ_VHOST: z.ZodDefault<z.ZodString>;
+    /** Environment prefix for queue and exchange names (`dev`, `staging`, `prod`). */
+    QUEUE_PREFIX: z.ZodDefault<z.ZodString>;
+    RABBITMQ_ENABLED: z.ZodEffects<z.ZodDefault<z.ZodEnum<["true", "false"]>>, boolean, "true" | "false" | undefined>;
+} & {
+    /** This service's own name (its compose service name), sent with every internal call. */
+    INTERNAL_SERVICE_NAME: z.ZodOptional<z.ZodString>;
+    /** This service's own secret (at least 32 characters), sent with every internal call. */
+    INTERNAL_SERVICE_CREDENTIAL: z.ZodOptional<z.ZodString>;
+    /** JSON map of caller name → secret this service accepts from that caller. */
+    INTERNAL_SERVICE_CREDENTIALS: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    NODE_ENV: "development" | "test" | "staging" | "production";
+    PORT: number;
+    SERVICE_NAME: string;
+    APP_NAME: string;
+    CORS_ORIGINS: string;
+    GATEWAY_SIGNING_SECRET: string;
+    DB_HOST: string;
+    DB_PORT: number;
+    DB_USER: string;
+    DB_PASSWORD: string;
+    DB_NAME: string;
+    DB_POOL_MAX: number;
+    RABBITMQ_HOST: string;
+    RABBITMQ_PORT: number;
+    RABBITMQ_USER: string;
+    RABBITMQ_PASSWORD: string;
+    RABBITMQ_VHOST: string;
+    QUEUE_PREFIX: string;
+    RABBITMQ_ENABLED: boolean;
+    REDIS_HOST: string;
+    REDIS_PORT: number;
+    REDIS_DB: number;
+    LOG_LEVEL?: "error" | "warn" | "info" | "http" | "debug" | undefined;
+    INTERNAL_SERVICE_NAME?: string | undefined;
+    INTERNAL_SERVICE_CREDENTIAL?: string | undefined;
+    INTERNAL_SERVICE_CREDENTIALS?: string | undefined;
+    RABBITMQ_URL?: string | undefined;
+    REDIS_URL?: string | undefined;
+    REDIS_PASSWORD?: string | undefined;
+    CACHE_KEY_PREFIX?: string | undefined;
+}, {
+    PORT: number;
+    SERVICE_NAME: string;
+    GATEWAY_SIGNING_SECRET: string;
+    DB_NAME: string;
+    NODE_ENV?: "development" | "test" | "staging" | "production" | undefined;
+    APP_NAME?: string | undefined;
+    LOG_LEVEL?: "error" | "warn" | "info" | "http" | "debug" | undefined;
+    CORS_ORIGINS?: string | undefined;
+    INTERNAL_SERVICE_NAME?: string | undefined;
+    INTERNAL_SERVICE_CREDENTIAL?: string | undefined;
+    INTERNAL_SERVICE_CREDENTIALS?: string | undefined;
+    DB_HOST?: string | undefined;
+    DB_PORT?: number | undefined;
+    DB_USER?: string | undefined;
+    DB_PASSWORD?: string | undefined;
+    DB_POOL_MAX?: number | undefined;
+    RABBITMQ_URL?: string | undefined;
+    RABBITMQ_HOST?: string | undefined;
+    RABBITMQ_PORT?: number | undefined;
+    RABBITMQ_USER?: string | undefined;
+    RABBITMQ_PASSWORD?: string | undefined;
+    RABBITMQ_VHOST?: string | undefined;
+    QUEUE_PREFIX?: string | undefined;
+    RABBITMQ_ENABLED?: "true" | "false" | undefined;
+    REDIS_URL?: string | undefined;
+    REDIS_HOST?: string | undefined;
+    REDIS_PORT?: number | undefined;
+    REDIS_PASSWORD?: string | undefined;
+    REDIS_DB?: number | undefined;
+    CACHE_KEY_PREFIX?: string | undefined;
+}>;
+/** Variables that have a development default but must be set explicitly in staging and production. */
+export declare const DEPLOYED_REQUIRED_ENV: readonly string[];
+/**
+ * True for NODE_ENV values that must name their environments explicitly (staging, production).
+ *
+ * @param nodeEnv NODE_ENV value (default `process.env.NODE_ENV`).
+ * @returns Whether it is a deployed environment.
+ * @example isDeployedNodeEnv('production') // true
+ */
+export declare function isDeployedNodeEnv(nodeEnv?: string | undefined): boolean;
+/** One problem with one variable. Holds the variable name and kind of problem only, never its value. */
+export interface EnvProblem {
+    name: string;
+    problem: 'missing' | 'invalid';
+}
+type EnvSource = Record<string, string | undefined>;
+/**
+ * Formats problems as `NAME: missing|invalid` lines (names only — values are never printed, because
+ * Zod's own messages can echo them).
+ *
+ * @param problems Problems from validation.
+ * @returns A multi-line message.
+ * @example formatEnvProblems([{ name: 'DB_NAME', problem: 'missing' }]) // 'Invalid environment configuration:\n  DB_NAME: missing'
+ */
+export declare function formatEnvProblems(problems: EnvProblem[]): string;
+/** Options for {@link parseEnv}. */
+export interface ParseEnvOptions {
+    /** Read `./.env` first when `source` is `process.env` (default true). */
     dotenv?: boolean;
-}): z.infer<S>;
-/** Comma-separated env value → trimmed, non-empty list. */
+    /** Names that must be set when NODE_ENV is staging or production (default {@link DEPLOYED_REQUIRED_ENV}). */
+    deployedRequired?: readonly string[];
+}
+/**
+ * Validates `source` against `schema` without merging the base or exiting. Use for partial configs
+ * (scripts, tests) and wherever the caller handles the error.
+ *
+ * @param schema Any Zod schema over the env object.
+ * @param source Values to validate (default process.env).
+ * @param options Dotenv and deployed-environment checks.
+ * @returns The parsed, typed config.
+ * @throws ConfigError listing every missing or invalid variable by name (never its value).
+ * @example const env = parseEnv(databaseEnv, { DB_NAME: 'app_test' });
+ */
+export declare function parseEnv<S extends z.ZodTypeAny>(schema: S, source?: EnvSource, options?: ParseEnvOptions): z.infer<S>;
+/** Options for {@link loadEnv}: parse options plus source, base and injectable output/exit. */
+export interface LoadEnvOptions extends ParseEnvOptions {
+    /** Values to validate (default process.env). */
+    source?: EnvSource;
+    /** Base schema merged under the service schema (default {@link baseEnv}). */
+    base?: z.AnyZodObject;
+    /** Where the problem list is written (default stderr). */
+    write?: (text: string) => void;
+    /** Called with exit code 1 on failure (default `process.exit`). */
+    exit?: (code: number) => never;
+}
+/**
+ * Service startup config: merges the base env schema with the service's own, validates, and on
+ * failure prints the missing/invalid variable **names** (never values) and exits non-zero.
+ *
+ * @param schema The service's own variables (default none).
+ * @param options Source, base override and injectable write/exit for tests.
+ * @returns The parsed, typed config (base + service variables).
+ * @example
+ * export const config = loadEnv(z.object({ UPSTREAM_INTERNAL_URL: z.string().url() }));
+ */
+export declare function loadEnv<S extends z.AnyZodObject = z.ZodObject<Record<string, never>>, B extends z.AnyZodObject = typeof baseEnv>(schema?: S, options?: LoadEnvOptions & {
+    base?: B;
+}): z.infer<B> & z.infer<S>;
+/**
+ * Comma-separated env value → trimmed, non-empty list.
+ *
+ * @param value Raw env value.
+ * @returns The list (empty when unset).
+ * @example listFromEnv(' a, b ,,c') // ['a', 'b', 'c']
+ */
 export declare const listFromEnv: (value: string | undefined) => string[];
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/types/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/config/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;;IAIrB,mFAAmF;;;;IAInF,gDAAgD;;IAEhD,4DAA4D;;;;;;;;;;;;;;;;;;;;EAE5D,CAAC;AAEH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;EAOtB,CAAC;AAEH,eAAO,MAAM,YAAY;;;;;;;IAOvB,kFAAkF;;;;;;;;;;;;;;;;;;;;;EAGlF,CAAC;AAEH,eAAO,MAAM,QAAQ;;;IAGnB,kFAAkF;;;;;;;;;;EAElF,CAAC;AAEH,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,GAAG,MAAM,CAIxE;AAED,iGAAiG;AACjG,wBAAgB,UAAU,CAAC,IAAI,SAAiC,GAAG,IAAI,CAYtE;AAED,qBAAa,WAAY,SAAQ,KAAK;CAAG;AAEzC,qGAAqG;AACrG,wBAAgB,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAE,MAAM,CAAC,UAAwB,EAAE,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAQlJ;AAED,2DAA2D;AAC3D,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,MAAM,EAAmE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/config/index.ts"],"names":[],"mappings":"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"}

package/dist/types/contracts/notification-dispatch.d.ts

@@ -44,7 +44,7 @@ export type DispatchValue = z.infer<typeof dispatchValueSchema>;
  * Who receives a dispatch. `userId` is needed for per-user channels such as an in-app feed;
  * addresses with no account behind them carry only `email`.
  *
- * @example { email: 'wanjiru@example.com', name: 'Wanjiru', userId: '01J…', timezone: 'Africa/Nairobi' }
+ * @example { email: 'ada@example.com', name: 'Ada', userId: '01J…', timezone: 'Europe/Lisbon' }
  */
 export declare const dispatchRecipientSchema: z.ZodObject<{
     email: z.ZodString;
@@ -55,14 +55,14 @@ export declare const dispatchRecipientSchema: z.ZodObject<{
     timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     email: string;
-    userId?: string | null | undefined;
     name?: string | undefined;
+    userId?: string | null | undefined;
     locale?: string | null | undefined;
     timezone?: string | null | undefined;
 }, {
     email: string;
-    userId?: string | null | undefined;
     name?: string | undefined;
+    userId?: string | null | undefined;
     locale?: string | null | undefined;
     timezone?: string | null | undefined;
 }>;
@@ -116,14 +116,14 @@ export declare function createNotificationDispatchSchema<const C extends string,
         timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, "strip", z.ZodTypeAny, {
         email: string;
-        userId?: string | null | undefined;
         name?: string | undefined;
+        userId?: string | null | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
     }, {
         email: string;
-        userId?: string | null | undefined;
         name?: string | undefined;
+        userId?: string | null | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
     }>;
@@ -148,14 +148,14 @@ export declare function createNotificationDispatchSchema<const C extends string,
         timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, "strip", z.ZodTypeAny, {
         email: string;
-        userId?: string | null | undefined;
         name?: string | undefined;
+        userId?: string | null | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
     }, {
         email: string;
-        userId?: string | null | undefined;
         name?: string | undefined;
+        userId?: string | null | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
     }>;
@@ -180,14 +180,14 @@ export declare function createNotificationDispatchSchema<const C extends string,
         timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, "strip", z.ZodTypeAny, {
         email: string;
-        userId?: string | null | undefined;
         name?: string | undefined;
+        userId?: string | null | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
     }, {
         email: string;
-        userId?: string | null | undefined;
         name?: string | undefined;
+        userId?: string | null | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
     }>;
@@ -212,14 +212,14 @@ export declare function createNotificationDispatchSchema<const C extends string,
         timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, "strip", z.ZodTypeAny, {
         email: string;
-        userId?: string | null | undefined;
         name?: string | undefined;
+        userId?: string | null | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
     }, {
         email: string;
-        userId?: string | null | undefined;
         name?: string | undefined;
+        userId?: string | null | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
     }>;
@@ -244,14 +244,14 @@ export declare function createNotificationDispatchSchema<const C extends string,
         timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, "strip", z.ZodTypeAny, {
         email: string;
-        userId?: string | null | undefined;
         name?: string | undefined;
+        userId?: string | null | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
     }, {
         email: string;
-        userId?: string | null | undefined;
         name?: string | undefined;
+        userId?: string | null | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
     }>;

package/dist/types/database/db.d.ts

@@ -0,0 +1,46 @@
+import type { Knex } from 'knex';
+import { type MySql2Database } from 'drizzle-orm/mysql2';
+import type mysql from 'mysql2/promise';
+import type { databaseEnv } from '../config/index.js';
+import type { z } from 'zod';
+import { type MysqlConnectionOptions } from './pool.js';
+/** The `DB_*` variables of `baseEnv` (see `databaseEnv` in the config module). */
+export type DatabaseEnv = z.infer<typeof databaseEnv>;
+/** A Drizzle database over a mysql2 pool. */
+export type Database<TSchema extends Record<string, unknown> = Record<string, never>> = MySql2Database<TSchema>;
+/** The transaction handle passed to `db.transaction(async (tx) => …)`. */
+export type Tx<TSchema extends Record<string, unknown> = Record<string, never>> = Parameters<Parameters<Database<TSchema>['transaction']>[0]>[0];
+/** What {@link createDb} returns. The service container owns it and closes it on shutdown. */
+export interface DbHandle<TSchema extends Record<string, unknown>> {
+    db: Database<TSchema>;
+    /** Readiness probe (`SELECT 1`); rejects when the database is unreachable. */
+    ping(): Promise<void>;
+    /** Drains and closes the pool. */
+    close(): Promise<void>;
+}
+/** Options for {@link createDb}. */
+export interface CreateDbOptions<TSchema extends Record<string, unknown>> {
+    /** Validated env (`config` from `loadEnv`). */
+    env: DatabaseEnv;
+    /** The service's Drizzle schema (tables and relations). */
+    schema: TSchema;
+    /** Pre-built pool (tests). Default: a utf8mb4, UTC pool sized by `DB_POOL_MAX`. */
+    pool?: mysql.Pool;
+}
+/**
+ * Creates the service's Drizzle database. There is no module-level singleton: call it once in
+ * `container.ts` and inject `db` into repositories.
+ *
+ * @example const { db, ping, close } = createDb({ env: config, schema });
+ */
+export declare function createDb<TSchema extends Record<string, unknown>>(options: CreateDbOptions<TSchema>): DbHandle<TSchema>;
+/**
+ * Knex config for a service's `knexfile.js`. Knex runs **migrations and seeds only** (`.cjs` files
+ * in `./migrations` and `./seeds`); repositories use Drizzle.
+ *
+ * @example module.exports = knexConfig(config);
+ */
+export declare function knexConfig(env: DatabaseEnv): Knex.Config;
+/** Maps the validated `DB_*` env to connection options. */
+export declare function connectionOptions(env: DatabaseEnv): MysqlConnectionOptions;
+//# sourceMappingURL=db.d.ts.map

package/dist/types/database/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../../src/database/db.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,EAAW,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAgD,KAAK,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAEtG,kFAAkF;AAClF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,6CAA6C;AAC7C,MAAM,MAAM,QAAQ,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC;AAEhH,0EAA0E;AAC1E,MAAM,MAAM,EAAE,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEjJ,8FAA8F;AAC9F,MAAM,WAAW,QAAQ,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC/D,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IACtB,8EAA8E;IAC9E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,kCAAkC;IAClC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,oCAAoC;AACpC,MAAM,WAAW,eAAe,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACtE,+CAA+C;IAC/C,GAAG,EAAE,WAAW,CAAC;IACjB,2DAA2D;IAC3D,MAAM,EAAE,OAAO,CAAC;IAChB,mFAAmF;IACnF,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAStH;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC,MAAM,CAExD;AAED,2DAA2D;AAC3D,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,sBAAsB,CAE1E"}

package/dist/types/database/index.d.ts

@@ -1,25 +1,12 @@
-import type { Knex } from 'knex';
-import mysql from 'mysql2/promise';
-export interface MysqlConnectionOptions {
-    host: string;
-    port: number;
-    user: string;
-    password: string;
-    database: string;
-    poolMax?: number;
-}
 /**
- * mysql2 pool for Drizzle. Sessions run in UTC and utf8mb4 so timestamps and emoji round-trip
- * unchanged regardless of server defaults.
+ * `@heavybit/shared-lib/database`: Drizzle data access for services. Repositories use Drizzle
+ * through {@link ScopedRepository} and the scopes in `scopes.ts`; raw scoped queries and Knex in
+ * `src/` are forbidden. Knex is for migrations and seeds only (`knexConfig`, `@heavybit/shared-lib/knex`).
  */
-export declare function createMysqlPool(options: MysqlConnectionOptions): mysql.Pool;
-/** Knex config for migrations/seeds and query-builder use (same session settings as the pool). */
-export declare function createKnexConfig(options: MysqlConnectionOptions & {
-    migrationsDir?: string;
-    seedsDir?: string;
-}): Knex.Config;
-/** Readiness probe helper. */
-export declare function pingMysql(pool: mysql.Pool): Promise<void>;
-/** Escapes `%`, `_` and `\` for use inside a LIKE pattern. */
-export declare function escapeLike(value: string): string;
+export * from './pool.js';
+export * from './db.js';
+export * from './scopes.js';
+export * from './scoped-repository.js';
+export * from './pagination.js';
+export * from './tables.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/database/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/database/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,KAAK,MAAM,gBAAgB,CAAC;AAEnC,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,KAAK,CAAC,IAAI,CAe3E;AAED,kGAAkG;AAClG,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,sBAAsB,GAAG;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,MAAM,CAgB7H;AAED,8BAA8B;AAC9B,wBAAsB,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/D;AAED,8DAA8D;AAC9D,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/database/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}

package/dist/types/database/pagination.d.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import type { CursorPage } from '../types/index.js';
+/**
+ * Cursor (keyset) pagination (D6). Clients send `?cursor=&limit=`; the cursor is an opaque
+ * base64url token of `{ sortKey, id }` (the last row's sort value plus an id tie-breaker).
+ * Dependency-light: usable from controllers without the database subpath.
+ */
+/** Largest page size a client may ask for. */
+export declare const MAX_PAGE_LIMIT = 100;
+/** Page size when the client sends none. */
+export declare const DEFAULT_PAGE_LIMIT = 20;
+/** `{ cursor?, limit }` query schema: limit 1–100, default 20; unknown keys are stripped. */
+export declare const cursorQuerySchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    cursor?: string | undefined;
+}, {
+    limit?: number | undefined;
+    cursor?: string | undefined;
+}>;
+/** Parsed cursor query. */
+export type CursorQuery = z.infer<typeof cursorQuerySchema>;
+/** Sort values a cursor can carry. Dates are carried as ISO strings. */
+export type CursorSortKey = string | number | null;
+/** The decoded content of a cursor. */
+export interface DecodedCursor {
+    sortKey: CursorSortKey;
+    id: string;
+}
+/**
+ * Validates `{ cursor, limit }` from a query string.
+ *
+ * @throws ValidationError (422) with field errors when invalid.
+ * @example const { cursor, limit } = parseCursorQuery(req.query);
+ */
+export declare function parseCursorQuery(input: {
+    cursor?: unknown;
+    limit?: unknown;
+} | undefined): CursorQuery;
+/**
+ * Encodes a cursor. Date sort keys become ISO strings.
+ *
+ * @example encodeCursor({ sortKey: row.createdAt, id: row.id })
+ */
+export declare function encodeCursor(cursor: {
+    sortKey: CursorSortKey | Date;
+    id: string;
+}): string;
+/**
+ * Decodes a cursor produced by {@link encodeCursor}.
+ *
+ * @throws ValidationError (422, field `cursor`) for anything malformed or tampered with.
+ */
+export declare function decodeCursor(token: string): DecodedCursor;
+/**
+ * Builds a page from `limit + 1` fetched rows: the extra row only signals that more exist.
+ *
+ * @param rows Rows fetched with `limit + 1`.
+ * @param limit The page size.
+ * @param cursorOf Extracts `{ sortKey, id }` from a row for the next cursor.
+ */
+export declare function buildCursorPage<T>(rows: T[], limit: number, cursorOf: (row: T) => {
+    sortKey: CursorSortKey | Date;
+    id: string;
+}): CursorPage<T>;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/types/database/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../../src/database/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD;;;;GAIG;AAEH,8CAA8C;AAC9C,eAAO,MAAM,cAAc,MAAM,CAAC;AAClC,4CAA4C;AAC5C,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAGrC,6FAA6F;AAC7F,eAAO,MAAM,iBAAiB;;;;;;;;;EAG5B,CAAC;AAEH,2BAA2B;AAC3B,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,wEAAwE;AACxE,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAEnD,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,aAAa,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,GAAG,WAAW,CAItG;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAG1F;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAczD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK;IAAE,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CAAC,CAAC,CAAC,CAK/I"}

package/dist/types/database/pool.d.ts

@@ -0,0 +1,39 @@
+import type { Knex } from 'knex';
+import mysql from 'mysql2/promise';
+/** Connection settings for {@link createMysqlPool} and {@link createKnexConfig}. */
+export interface MysqlConnectionOptions {
+    /** Server host name. */
+    host: string;
+    /** Server port. */
+    port: number;
+    /** Database user. */
+    user: string;
+    /** Database password (never logged). */
+    password: string;
+    /** The service's own database. */
+    database: string;
+    /** Maximum pool connections (default 10). */
+    poolMax?: number;
+}
+/** Knex-only options for {@link createKnexConfig}. */
+export interface KnexConfigOptions extends MysqlConnectionOptions {
+    /** Migrations folder (default `./migrations`). */
+    migrationsDir?: string;
+    /** Seeds folder (default `./seeds`). */
+    seedsDir?: string;
+}
+/**
+ * mysql2 pool for Drizzle. Sessions run in UTC and utf8mb4 so timestamps and emoji round-trip
+ * unchanged regardless of server defaults.
+ */
+export declare function createMysqlPool(options: MysqlConnectionOptions): mysql.Pool;
+/**
+ * Knex config for migrations and seeds: mysql2, utf8mb4, UTC, `.cjs` files only. Services call it
+ * through `knexConfig(env)` in their `knexfile.js`.
+ */
+export declare function createKnexConfig(options: KnexConfigOptions): Knex.Config;
+/** Readiness probe helper. */
+export declare function pingMysql(pool: mysql.Pool): Promise<void>;
+/** Escapes `%`, `_` and `\` for use inside a LIKE pattern. */
+export declare function escapeLike(value: string): string;
+//# sourceMappingURL=pool.d.ts.map