@heavybit/shared-lib 1.3.2 → 2.7.0

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

@@ -1,33 +1,51 @@
+/**
+ * Notification dispatch: a generic command contract (shared plumbing, no app vocabulary).
+ *
+ * Services never send email, SMS or push themselves. They stage one dispatch command (default
+ * `notification:dispatch`) through their outbox, and the app's notification-service renders a seeded
+ * template and delivers it. Both sides build their schema from {@link createNotificationDispatchSchema},
+ * so producers and the consumer cannot drift.
+ *
+ * App-specific parts are parameters: the app passes its own categories (e.g. `security`, `order`) and
+ * channels (e.g. `email`, `sms`, `in_app`). Template slugs and their variables also belong to the app
+ * (keep a table next to the notification-service seeds and test both sides against it).
+ */
 import { z } from 'zod';
 /**
- * `notification:dispatch` — the one command every Showbiz service stages (through its outbox) to have
- * notification-service render a seeded template and deliver it by email and/or the in-app feed. No
- * other service sends email itself. One contract for both sides: producers type their payload with it
- * and notification-service validates against it, so the two cannot drift.
+ * Default command name for a dispatch. An app may use another name and pass it to its producers.
+ *
+ * @example await outbox.command(tx, NOTIFICATION_DISPATCH, dispatch, { correlationId });
  */
 export declare const NOTIFICATION_DISPATCH = "notification:dispatch";
-/** Channels a dispatch may ask for. `in_app` needs a recipient `userId` (the bell feed is per user). */
-export declare const DISPATCH_CHANNELS: readonly ["email", "in_app"];
-export type DispatchChannel = (typeof DISPATCH_CHANNELS)[number];
 /**
- * What a dispatch is about. Account mail (`security`, `account`, `team`, `marketing`) goes to a user;
- * `staff` is an operational alert to a configured staff address.
+ * Size limits that keep a dispatch small enough for a queue message and safe to render.
+ *
+ * @example z.string().max(DISPATCH_LIMITS.template)
  */
-export declare const NOTIFICATION_CATEGORIES: readonly ["security", "account", "team", "marketing", "staff"];
-export type NotificationCategory = (typeof NOTIFICATION_CATEGORIES)[number];
 export declare const DISPATCH_LIMITS: {
     readonly template: 100;
     readonly email: 254;
     readonly name: 200;
+    readonly userId: 36;
     readonly dataKeys: 40;
     readonly dataKey: 64;
     readonly dataValue: 2000;
     readonly secretKeys: 10;
     readonly permission: 100;
 };
-/** Template variables are flat scalars: they are printed into the copy, never serialised objects. */
+/**
+ * Template variables are flat scalars: they are printed into the copy, never serialised objects.
+ *
+ * @example dispatchValueSchema.parse('1250.00')
+ */
 export declare const dispatchValueSchema: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
 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: 'ada@example.com', name: 'Ada', userId: '01J…', timezone: 'Europe/Lisbon' }
+ */
 export declare const dispatchRecipientSchema: z.ZodObject<{
     email: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
@@ -49,10 +67,46 @@ export declare const dispatchRecipientSchema: z.ZodObject<{
     timezone?: string | null | undefined;
 }>;
 export type DispatchRecipient = z.infer<typeof dispatchRecipientSchema>;
-export declare const notificationDispatchSchema: z.ZodEffects<z.ZodObject<{
-    /** Seeded `notification_templates.slug`. */
+/**
+ * A template variable name the renderer can match.
+ *
+ * @example dispatchDataKeySchema.parse('expiresInMinutes')
+ */
+export declare const dispatchDataKeySchema: z.ZodString;
+/**
+ * The app's vocabulary: which categories and channels a dispatch may name.
+ *
+ * @example { categories: ['security', 'order', 'staff'], channels: ['email', 'sms'] }
+ */
+export interface DispatchVocabulary<C extends string, Ch extends string> {
+    /** What a dispatch is about, e.g. `['security', 'account', 'order', 'staff']`. */
+    categories: readonly [C, ...C[]];
+    /** Delivery channels the notification-service supports, e.g. `['email', 'sms', 'in_app']`. */
+    channels: readonly [Ch, ...Ch[]];
+}
+/**
+ * Build the dispatch schema for an app's categories and channels. Producers type their payload with it;
+ * the notification-service validates incoming commands with the same schema.
+ *
+ * Rules every app gets: a seeded `template` slug; one or more distinct channels; at most 40 flat-scalar `data`
+ * variables with renderer-safe names; `secretKeys` (one-time codes, reset links) must be keys of `data`;
+ * the consumer must use them only to render, never store them or show them in a feed.
+ *
+ * @typeParam C The app's categories (inferred as literals).
+ * @typeParam Ch The app's channels (inferred as literals).
+ * @param vocabulary The app's categories and channels.
+ * @returns A Zod schema; `data` defaults to `{}` and `secretKeys` to `[]`.
+ * @example
+ * export const dispatchSchema = createNotificationDispatchSchema({
+ *   categories: ['security', 'account', 'order', 'staff'],
+ *   channels: ['email', 'sms'],
+ * });
+ * export type Dispatch = z.input<typeof dispatchSchema>;
+ */
+export declare function createNotificationDispatchSchema<const C extends string, const Ch extends string>(vocabulary: DispatchVocabulary<C, Ch>): z.ZodEffects<z.ZodObject<{
+    /** Seeded template slug in the notification-service. */
     template: z.ZodString;
-    category: z.ZodEnum<["security", "account", "team", "marketing", "staff"]>;
+    category: z.ZodEnum<[C, ...C[]]>;
     recipient: z.ZodObject<{
         email: z.ZodString;
         name: z.ZodOptional<z.ZodString>;
@@ -73,103 +127,167 @@ export declare const notificationDispatchSchema: z.ZodEffects<z.ZodObject<{
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
     }>;
-    channels: z.ZodArray<z.ZodEnum<["email", "in_app"]>, "many">;
+    channels: z.ZodEffects<z.ZodArray<z.ZodEnum<[Ch, ...Ch[]]>, "many">, Ch[], Ch[]>;
     data: z.ZodEffects<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>, Record<string, string | number | boolean | null>, Record<string, string | number | boolean | null> | undefined>;
-    /**
-     * Keys of `data` holding a one-time secret (a sign-in code, a reset or confirm link). They are used to
-     * render the email and nothing else: notification-service never stores them and never puts them in the
-     * in-app feed, and email-service masks them in what it keeps.
-     */
+    /** Keys of `data` holding a one-time secret: used to render, never stored or shown in a feed. */
     secretKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    /** Security and staff alerts are always delivered, whatever the recipient's preferences. */
+    /** Deliver whatever the recipient's notification preferences say (for mail the recipient cannot opt out of). */
     bypassPreferences: z.ZodOptional<z.ZodBoolean>;
-    /** The permission staff recipients hold; informational until recipients are resolved by permission. */
+    /** The permission the recipients were resolved by, when they were (traceability only). */
     targetPermission: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    data: Record<string, string | number | boolean | null>;
-    category: "security" | "account" | "team" | "marketing" | "staff";
-    template: string;
-    recipient: {
+}, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    /** Seeded template slug in the notification-service. */
+    template: z.ZodString;
+    category: z.ZodEnum<[C, ...C[]]>;
+    recipient: z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        userId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        locale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** IANA zone; time variables are rendered in it. */
+        timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
         email: string;
         name?: string | undefined;
         userId?: string | null | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
-    };
-    channels: ("email" | "in_app")[];
-    secretKeys: string[];
-    bypassPreferences?: boolean | undefined;
-    targetPermission?: string | undefined;
-}, {
-    category: "security" | "account" | "team" | "marketing" | "staff";
-    template: string;
-    recipient: {
+    }, {
         email: string;
         name?: string | undefined;
         userId?: string | null | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
-    };
-    channels: ("email" | "in_app")[];
-    data?: Record<string, string | number | boolean | null> | undefined;
-    secretKeys?: string[] | undefined;
-    bypassPreferences?: boolean | undefined;
-    targetPermission?: string | undefined;
-}>, {
-    data: Record<string, string | number | boolean | null>;
-    category: "security" | "account" | "team" | "marketing" | "staff";
-    template: string;
-    recipient: {
+    }>;
+    channels: z.ZodEffects<z.ZodArray<z.ZodEnum<[Ch, ...Ch[]]>, "many">, Ch[], Ch[]>;
+    data: z.ZodEffects<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>, Record<string, string | number | boolean | null>, Record<string, string | number | boolean | null> | undefined>;
+    /** Keys of `data` holding a one-time secret: used to render, never stored or shown in a feed. */
+    secretKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Deliver whatever the recipient's notification preferences say (for mail the recipient cannot opt out of). */
+    bypassPreferences: z.ZodOptional<z.ZodBoolean>;
+    /** The permission the recipients were resolved by, when they were (traceability only). */
+    targetPermission: z.ZodOptional<z.ZodString>;
+}>, any> extends infer T ? { [k in keyof T]: T[k]; } : never, z.baseObjectInputType<{
+    /** Seeded template slug in the notification-service. */
+    template: z.ZodString;
+    category: z.ZodEnum<[C, ...C[]]>;
+    recipient: z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        userId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        locale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** IANA zone; time variables are rendered in it. */
+        timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
         email: string;
         name?: string | undefined;
         userId?: string | null | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
-    };
-    channels: ("email" | "in_app")[];
-    secretKeys: string[];
-    bypassPreferences?: boolean | undefined;
-    targetPermission?: string | undefined;
-}, {
-    category: "security" | "account" | "team" | "marketing" | "staff";
-    template: string;
-    recipient: {
+    }, {
         email: string;
         name?: string | undefined;
         userId?: string | null | undefined;
         locale?: string | null | undefined;
         timezone?: string | null | undefined;
-    };
-    channels: ("email" | "in_app")[];
-    data?: Record<string, string | number | boolean | null> | undefined;
-    secretKeys?: string[] | undefined;
-    bypassPreferences?: boolean | undefined;
-    targetPermission?: string | undefined;
-}>;
+    }>;
+    channels: z.ZodEffects<z.ZodArray<z.ZodEnum<[Ch, ...Ch[]]>, "many">, Ch[], Ch[]>;
+    data: z.ZodEffects<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>, Record<string, string | number | boolean | null>, Record<string, string | number | boolean | null> | undefined>;
+    /** Keys of `data` holding a one-time secret: used to render, never stored or shown in a feed. */
+    secretKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Deliver whatever the recipient's notification preferences say (for mail the recipient cannot opt out of). */
+    bypassPreferences: z.ZodOptional<z.ZodBoolean>;
+    /** The permission the recipients were resolved by, when they were (traceability only). */
+    targetPermission: z.ZodOptional<z.ZodString>;
+}> extends infer T_1 ? { [k_1 in keyof T_1]: T_1[k_1]; } : never>, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    /** Seeded template slug in the notification-service. */
+    template: z.ZodString;
+    category: z.ZodEnum<[C, ...C[]]>;
+    recipient: z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        userId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        locale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** IANA zone; time variables are rendered in it. */
+        timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        email: string;
+        name?: string | undefined;
+        userId?: string | null | undefined;
+        locale?: string | null | undefined;
+        timezone?: string | null | undefined;
+    }, {
+        email: string;
+        name?: string | undefined;
+        userId?: string | null | undefined;
+        locale?: string | null | undefined;
+        timezone?: string | null | undefined;
+    }>;
+    channels: z.ZodEffects<z.ZodArray<z.ZodEnum<[Ch, ...Ch[]]>, "many">, Ch[], Ch[]>;
+    data: z.ZodEffects<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>, Record<string, string | number | boolean | null>, Record<string, string | number | boolean | null> | undefined>;
+    /** Keys of `data` holding a one-time secret: used to render, never stored or shown in a feed. */
+    secretKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Deliver whatever the recipient's notification preferences say (for mail the recipient cannot opt out of). */
+    bypassPreferences: z.ZodOptional<z.ZodBoolean>;
+    /** The permission the recipients were resolved by, when they were (traceability only). */
+    targetPermission: z.ZodOptional<z.ZodString>;
+}>, any> extends infer T_2 ? { [k in keyof T_2]: T_2[k]; } : never, z.baseObjectInputType<{
+    /** Seeded template slug in the notification-service. */
+    template: z.ZodString;
+    category: z.ZodEnum<[C, ...C[]]>;
+    recipient: z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        userId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        locale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** IANA zone; time variables are rendered in it. */
+        timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        email: string;
+        name?: string | undefined;
+        userId?: string | null | undefined;
+        locale?: string | null | undefined;
+        timezone?: string | null | undefined;
+    }, {
+        email: string;
+        name?: string | undefined;
+        userId?: string | null | undefined;
+        locale?: string | null | undefined;
+        timezone?: string | null | undefined;
+    }>;
+    channels: z.ZodEffects<z.ZodArray<z.ZodEnum<[Ch, ...Ch[]]>, "many">, Ch[], Ch[]>;
+    data: z.ZodEffects<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>, Record<string, string | number | boolean | null>, Record<string, string | number | boolean | null> | undefined>;
+    /** Keys of `data` holding a one-time secret: used to render, never stored or shown in a feed. */
+    secretKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Deliver whatever the recipient's notification preferences say (for mail the recipient cannot opt out of). */
+    bypassPreferences: z.ZodOptional<z.ZodBoolean>;
+    /** The permission the recipients were resolved by, when they were (traceability only). */
+    targetPermission: z.ZodOptional<z.ZodString>;
+}> extends infer T_3 ? { [k_1 in keyof T_3]: T_3[k_1]; } : never>;
 /**
- * The seeded templates Showbiz services dispatch, with the variables (`data` keys) each dispatch carries.
- * Producers send exactly these keys; a seeded template may use any subset (notification-service dead-letters
- * a dispatch missing a variable its template uses). Both sides test against this table.
+ * What a producer stages, as a plain type (usable while categories/channels are still generic, e.g. in
+ * shared helpers). Equivalent to {@link NotificationDispatchInput} for a concrete vocabulary.
+ *
+ * @example
+ * const dispatch: NotificationDispatchPayload<'security', 'email'> = {
+ *   template: 'login-otp', category: 'security', recipient: { email }, channels: ['email'],
+ *   data: { code }, secretKeys: ['code'], bypassPreferences: true,
+ * };
  */
-export declare const DISPATCH_TEMPLATE_VARIABLES: {
-    readonly 'account-activation': readonly ["name", "code", "expiresInHours"];
-    readonly 'login-otp': readonly ["name", "code", "expiresInMinutes", "device"];
-    readonly 'password-reset': readonly ["name", "resetUrl", "expiresInMinutes"];
-    readonly 'staff-invitation': readonly ["name", "resetUrl", "expiresInMinutes"];
-    readonly 'password-changed': readonly ["name", "changedAt"];
-    readonly 'new-device-login': readonly ["name", "device", "ip", "country", "occurredAt", "confirmUrl", "disputeUrl"];
-    readonly 'team-member-added': readonly ["name", "profileName", "role", "invitedBy"];
-    readonly 'account-suspended': readonly ["name", "reason"];
-    readonly 'welcome-listener': readonly ["name"];
-    readonly 'welcome-creator': readonly ["name"];
-    readonly ai_budget_threshold: readonly ["requester", "period", "threshold_pct", "spent_usd", "limit_usd"];
-    readonly newswire_source_unhealthy: readonly ["source_name", "source_slug", "consecutive_failures", "last_error", "last_success_at"];
-    readonly newswire_block_rate_high: readonly ["blocked", "total", "block_rate_pct", "window_hours"];
-    readonly autopublish_audit_alert: readonly ["problem_rate_pct", "problem_count", "sample_count", "window_days", "action_taken"];
-};
-export type DispatchTemplate = keyof typeof DISPATCH_TEMPLATE_VARIABLES;
+export interface NotificationDispatchPayload<C extends string = string, Ch extends string = string> {
+    template: string;
+    category: C;
+    recipient: DispatchRecipient;
+    channels: Ch[];
+    data?: Record<string, DispatchValue>;
+    secretKeys?: string[];
+    bypassPreferences?: boolean;
+    targetPermission?: string;
+}
+/** The schema type for a given vocabulary. */
+export type NotificationDispatchSchema<C extends string, Ch extends string> = ReturnType<typeof createNotificationDispatchSchema<C, Ch>>;
 /** The validated command (defaults applied). */
-export type NotificationDispatch = z.infer<typeof notificationDispatchSchema>;
+export type NotificationDispatch<C extends string = string, Ch extends string = string> = z.output<NotificationDispatchSchema<C, Ch>>;
 /** What a producer stages: `data` and `secretKeys` may be omitted. */
-export type NotificationDispatchInput = z.input<typeof notificationDispatchSchema>;
+export type NotificationDispatchInput<C extends string = string, Ch extends string = string> = z.input<NotificationDispatchSchema<C, Ch>>;
 //# sourceMappingURL=notification-dispatch.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"notification-dispatch.d.ts","sourceRoot":"","sources":["../../../src/contracts/notification-dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D,wGAAwG;AACxG,eAAO,MAAM,iBAAiB,8BAA+B,CAAC;AAC9D,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,uBAAuB,gEAAiE,CAAC;AACtG,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,eAAO,MAAM,eAAe;;;;;;;;;CASlB,CAAC;AAEX,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,iEAAmG,CAAC;AACpI,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,uBAAuB;;;;;IAKlC,oDAAoD;;;;;;;;;;;;;;EAEpD,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAIxE,eAAO,MAAM,0BAA0B;IAEnC,4CAA4C;;;;;;;;QAT9C,oDAAoD;;;;;;;;;;;;;;;;;IAkBlD;;;;OAIG;;IAEH,4FAA4F;;IAE5F,uGAAuG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASvG,CAAC;AAEL;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;CAiBc,CAAC;AACvD,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,2BAA2B,CAAC;AAExE,gDAAgD;AAChD,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,sEAAsE;AACtE,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC"}
+{"version":3,"file":"notification-dispatch.d.ts","sourceRoot":"","sources":["../../../src/contracts/notification-dispatch.ts"],"names":[],"mappings":"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"}

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../../src/database/pool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,KAAK,MAAM,gBAAgB,CAAC;AAEnC,oFAAoF;AACpF,MAAM,WAAW,sBAAsB;IACrC,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,sDAAsD;AACtD,MAAM,WAAW,iBAAkB,SAAQ,sBAAsB;IAC/D,kDAAkD;IAClD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,KAAK,CAAC,IAAI,CAe3E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC,MAAM,CAgBxE;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"}