@happyvertical/smrt-messages 0.60.10 → 0.60.12

package/dist/manifest.json

@@ -2,7 +2,7 @@
   "version": "1.0.0",
   "timestamp": 0,
   "packageName": "@happyvertical/smrt-messages",
-  "packageVersion": "0.60.10",
+  "packageVersion": "0.60.12",
   "objects": {
     "@happyvertical/smrt-messages:AccountCollection": {
       "name": "accountcollection",
@@ -3759,6 +3759,136 @@
       },
       "importPath": "@happyvertical/smrt-messages"
     },
+    "@happyvertical/smrt-messages:NotificationOptOutCollection": {
+      "name": "notificationoptoutcollection",
+      "className": "NotificationOptOutCollection",
+      "qualifiedName": "@happyvertical/smrt-messages:NotificationOptOutCollection",
+      "collection": "notificationoptouts",
+      "filePath": "/home/runner/work/smrt/smrt/packages/messages/src/collections/NotificationOptOutCollection.ts",
+      "packageName": "@happyvertical/smrt-messages",
+      "fields": {},
+      "methods": {},
+      "decoratorConfig": {
+        "tableName": "notification_opt_outs",
+        "api": false,
+        "mcp": false,
+        "cli": false
+      },
+      "extends": "SmrtCollection",
+      "extendsTypeArg": "NotificationOptOut",
+      "exportName": "NotificationOptOutCollection",
+      "collectionExportName": "NotificationOptOutCollectionCollection",
+      "collectionOf": "@happyvertical/smrt-messages:NotificationOptOut",
+      "inheritedExposure": [
+        "api",
+        "mcp",
+        "cli"
+      ],
+      "schema": {
+        "tableName": "notification_opt_outs",
+        "ddl": "CREATE TABLE IF NOT EXISTS \"notification_opt_outs\" (\n  \"_sync_origin_device_id\" TEXT,\n  \"_sync_revision\" INTEGER,\n  \"id\" UUID PRIMARY KEY NOT NULL,\n  \"slug\" TEXT NOT NULL,\n  \"context\" TEXT NOT NULL DEFAULT '',\n  \"created_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"updated_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"tenant_id\" UUID NOT NULL,\n  \"recipient_user_id\" UUID NOT NULL,\n  \"channel\" TEXT NOT NULL DEFAULT 'email',\n  \"scope\" TEXT NOT NULL,\n  \"opted_out_at\" TIMESTAMP,\n  \"updated_by\" TEXT\n);",
+        "columns": {
+          "_sync_origin_device_id": {
+            "type": "TEXT"
+          },
+          "_sync_revision": {
+            "type": "INTEGER"
+          },
+          "id": {
+            "type": "UUID",
+            "primaryKey": true,
+            "referenceKind": "id",
+            "notNull": true
+          },
+          "slug": {
+            "type": "TEXT",
+            "notNull": true
+          },
+          "context": {
+            "type": "TEXT",
+            "notNull": true,
+            "default": ""
+          },
+          "created_at": {
+            "type": "TIMESTAMP",
+            "notNull": true,
+            "default": "current_timestamp"
+          },
+          "updated_at": {
+            "type": "TIMESTAMP",
+            "notNull": true,
+            "default": "current_timestamp"
+          },
+          "tenant_id": {
+            "type": "UUID",
+            "referenceKind": "tenantId",
+            "notNull": true,
+            "unique": false
+          },
+          "recipient_user_id": {
+            "type": "UUID",
+            "referenceKind": "crossPackageRef",
+            "notNull": true,
+            "unique": false
+          },
+          "channel": {
+            "type": "TEXT",
+            "notNull": true,
+            "unique": false,
+            "default": "email"
+          },
+          "scope": {
+            "type": "TEXT",
+            "notNull": true,
+            "unique": false
+          },
+          "opted_out_at": {
+            "type": "TIMESTAMP",
+            "notNull": false,
+            "unique": false
+          },
+          "updated_by": {
+            "type": "TEXT",
+            "notNull": false,
+            "unique": false
+          }
+        },
+        "indexes": [
+          {
+            "name": "notification_opt_outs_tenant_id_recipient_user_id_idx",
+            "columns": [
+              "tenant_id",
+              "recipient_user_id",
+              "channel",
+              "scope"
+            ],
+            "unique": true
+          },
+          {
+            "name": "notification_opt_outs_slug_context_idx",
+            "columns": [
+              "slug",
+              "context"
+            ]
+          },
+          {
+            "name": "notification_opt_outs_tenant_id_created_at_idx",
+            "columns": [
+              "tenant_id",
+              "created_at"
+            ]
+          },
+          {
+            "name": "notification_opt_outs_recipient_user_id_idx",
+            "columns": [
+              "recipient_user_id"
+            ]
+          }
+        ],
+        "version": "a13e93c1"
+      },
+      "importPath": "@happyvertical/smrt-messages"
+    },
     "@happyvertical/smrt-messages:PersonaMessageRouteCollection": {
       "name": "personamessageroutecollection",
       "className": "PersonaMessageRouteCollection",
@@ -8975,6 +9105,205 @@
       },
       "importPath": "@happyvertical/smrt-messages"
     },
+    "@happyvertical/smrt-messages:NotificationOptOut": {
+      "name": "notificationoptout",
+      "className": "NotificationOptOut",
+      "qualifiedName": "@happyvertical/smrt-messages:NotificationOptOut",
+      "collection": "notificationoptouts",
+      "description": "One person's opt-out of one notification channel for one scope, in one tenant: the preference store behind the outbox's isSuppressed hook.",
+      "filePath": "/home/runner/work/smrt/smrt/packages/messages/src/models/NotificationOptOut.ts",
+      "packageName": "@happyvertical/smrt-messages",
+      "fields": {
+        "tenantId": {
+          "type": "text",
+          "required": true,
+          "_meta": {
+            "sqlType": "UUID",
+            "__tenancy": {
+              "isTenantIdField": true,
+              "autoFilter": true,
+              "required": true,
+              "autoPopulate": true,
+              "nullable": false,
+              "mode": "required",
+              "field": "tenantId",
+              "allowSuperAdminBypass": false
+            }
+          }
+        },
+        "recipientUserId": {
+          "type": "crossPackageRef",
+          "required": true,
+          "related": "@happyvertical/smrt-users:User"
+        },
+        "channel": {
+          "type": "text",
+          "required": true,
+          "default": "email",
+          "_meta": {
+            "required": true
+          },
+          "enum": [
+            "email"
+          ]
+        },
+        "scope": {
+          "type": "text",
+          "required": true,
+          "_meta": {
+            "required": true
+          }
+        },
+        "optedOutAt": {
+          "type": "datetime",
+          "required": false
+        },
+        "updatedBy": {
+          "type": "text",
+          "required": false
+        }
+      },
+      "methods": {},
+      "decoratorConfig": {
+        "tableName": "notification_opt_outs",
+        "api": false,
+        "mcp": false,
+        "cli": false,
+        "conflictColumns": [
+          "tenant_id",
+          "recipient_user_id",
+          "channel",
+          "scope"
+        ],
+        "tenantScoped": {
+          "mode": "required"
+        }
+      },
+      "extends": "SmrtObject",
+      "exportName": "NotificationOptOut",
+      "collectionExportName": "NotificationOptOutCollection",
+      "validationRules": [
+        {
+          "field": "recipientUserId",
+          "rule": "required",
+          "fieldType": "crossPackageRef"
+        },
+        {
+          "field": "channel",
+          "rule": "required",
+          "fieldType": "text"
+        },
+        {
+          "field": "scope",
+          "rule": "required",
+          "fieldType": "text"
+        }
+      ],
+      "schema": {
+        "tableName": "notification_opt_outs",
+        "ddl": "CREATE TABLE IF NOT EXISTS \"notification_opt_outs\" (\n  \"_sync_origin_device_id\" TEXT,\n  \"_sync_revision\" INTEGER,\n  \"id\" UUID PRIMARY KEY NOT NULL,\n  \"slug\" TEXT NOT NULL,\n  \"context\" TEXT NOT NULL DEFAULT '',\n  \"created_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"updated_at\" TIMESTAMP NOT NULL DEFAULT current_timestamp,\n  \"tenant_id\" UUID NOT NULL,\n  \"recipient_user_id\" UUID NOT NULL,\n  \"channel\" TEXT NOT NULL DEFAULT 'email',\n  \"scope\" TEXT NOT NULL,\n  \"opted_out_at\" TIMESTAMP,\n  \"updated_by\" TEXT\n);",
+        "columns": {
+          "_sync_origin_device_id": {
+            "type": "TEXT"
+          },
+          "_sync_revision": {
+            "type": "INTEGER"
+          },
+          "id": {
+            "type": "UUID",
+            "primaryKey": true,
+            "referenceKind": "id",
+            "notNull": true
+          },
+          "slug": {
+            "type": "TEXT",
+            "notNull": true
+          },
+          "context": {
+            "type": "TEXT",
+            "notNull": true,
+            "default": ""
+          },
+          "created_at": {
+            "type": "TIMESTAMP",
+            "notNull": true,
+            "default": "current_timestamp"
+          },
+          "updated_at": {
+            "type": "TIMESTAMP",
+            "notNull": true,
+            "default": "current_timestamp"
+          },
+          "tenant_id": {
+            "type": "UUID",
+            "referenceKind": "tenantId",
+            "notNull": true,
+            "unique": false
+          },
+          "recipient_user_id": {
+            "type": "UUID",
+            "referenceKind": "crossPackageRef",
+            "notNull": true,
+            "unique": false
+          },
+          "channel": {
+            "type": "TEXT",
+            "notNull": true,
+            "unique": false,
+            "default": "email"
+          },
+          "scope": {
+            "type": "TEXT",
+            "notNull": true,
+            "unique": false
+          },
+          "opted_out_at": {
+            "type": "TIMESTAMP",
+            "notNull": false,
+            "unique": false
+          },
+          "updated_by": {
+            "type": "TEXT",
+            "notNull": false,
+            "unique": false
+          }
+        },
+        "indexes": [
+          {
+            "name": "notification_opt_outs_tenant_id_recipient_user_id_idx",
+            "columns": [
+              "tenant_id",
+              "recipient_user_id",
+              "channel",
+              "scope"
+            ],
+            "unique": true
+          },
+          {
+            "name": "notification_opt_outs_slug_context_idx",
+            "columns": [
+              "slug",
+              "context"
+            ]
+          },
+          {
+            "name": "notification_opt_outs_tenant_id_created_at_idx",
+            "columns": [
+              "tenant_id",
+              "created_at"
+            ]
+          },
+          {
+            "name": "notification_opt_outs_recipient_user_id_idx",
+            "columns": [
+              "recipient_user_id"
+            ]
+          }
+        ],
+        "version": "a13e93c1"
+      },
+      "importPath": "@happyvertical/smrt-messages"
+    },
     "@happyvertical/smrt-messages:PersonaMessageRoute": {
       "name": "personamessageroute",
       "className": "PersonaMessageRoute",

package/dist/models/NotificationOptOut.d.ts

@@ -0,0 +1,44 @@
+import type { SmrtObjectOptions } from '@happyvertical/smrt-core';
+import '../__smrt-register__.js';
+import { SmrtObject } from '@happyvertical/smrt-core';
+import type { NotificationDeliveryChannel } from './NotificationDelivery.js';
+/** `*` (everything in the tenant) or a host key such as `project:<uuid>`. */
+export declare const NOTIFICATION_OPT_OUT_SCOPE_PATTERN: RegExp;
+/** The scope that matches every notification of the channel in the tenant. */
+export declare const NOTIFICATION_OPT_OUT_ALL_SCOPE = "*";
+export declare function isValidNotificationOptOutScope(scope: unknown): scope is string;
+export interface NotificationOptOutOptions extends SmrtObjectOptions {
+    tenantId?: string;
+    recipientUserId?: string;
+    channel?: NotificationDeliveryChannel;
+    scope?: string;
+    optedOutAt?: Date | null;
+    updatedBy?: string;
+}
+/**
+ * One person's opt-out of one notification channel for one scope, in one
+ * tenant: the preference store behind the outbox's `isSuppressed` hook.
+ *
+ * Identity is `(tenant, recipient, channel, scope)` (the conflict identity).
+ * `optedOutAt` is set while the person is opted out and cleared by an opt-in,
+ * so the row keeps its history. `scope` is a host-defined key validated by
+ * {@link NOTIFICATION_OPT_OUT_SCOPE_PATTERN}. Read and change rows through
+ * `NotificationOptOutService`; the generated REST/MCP/CLI are off because the
+ * service is the authorization boundary.
+ */
+export declare class NotificationOptOut extends SmrtObject {
+    tenantId: string;
+    /** The person who opted out (`smrt-users:User`, uuid). */
+    recipientUserId: string;
+    /** Channel opted out of; only `email` today. */
+    channel: NotificationDeliveryChannel;
+    /** `*` or a host key such as `project:<uuid>`. */
+    scope: string;
+    /** When the opt-out took effect; null once the person opted back in. */
+    optedOutAt: Date | null;
+    /** Who last changed the row: the person's user id, or `system` for host code. */
+    updatedBy: string;
+    constructor(options?: NotificationOptOutOptions);
+    get isOptedOut(): boolean;
+}
+//# sourceMappingURL=NotificationOptOut.d.ts.map

package/dist/models/NotificationOptOut.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationOptOut.d.ts","sourceRoot":"","sources":["../../src/models/NotificationOptOut.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,OAAO,yBAAyB,CAAC;AACjC,OAAO,EAGL,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAE7E,6EAA6E;AAC7E,eAAO,MAAM,kCAAkC,QACI,CAAC;AAEpD,8EAA8E;AAC9E,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAElD,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,MAAM,CAIjB;AAED,MAAM,WAAW,yBAA0B,SAAQ,iBAAiB;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,2BAA2B,CAAC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,qBAQa,kBAAmB,SAAQ,UAAU;IAEhD,QAAQ,SAAM;IAEd,0DAA0D;IAE1D,eAAe,SAAM;IAErB,gDAAgD;IAEhD,OAAO,EAAE,2BAA2B,CAAW;IAE/C,kDAAkD;IAElD,KAAK,SAAM;IAEX,wEAAwE;IACxE,UAAU,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE/B,iFAAiF;IACjF,SAAS,SAAM;gBAEH,OAAO,GAAE,yBAA8B;IAWnD,IAAI,UAAU,IAAI,OAAO,CAExB;CACF"}

package/dist/services/NotificationOptOutService.d.ts

@@ -0,0 +1,80 @@
+import { type SmrtClassOptions } from '@happyvertical/smrt-core';
+import { type NotificationDeliveryChannel } from '../models/NotificationDelivery.js';
+import { NotificationOptOut } from '../models/NotificationOptOut.js';
+import type { NotificationSuppressionRequest } from './NotificationOutboxService.js';
+/** The signed-in person making a request, as the host authenticated them. */
+export interface NotificationOptOutPrincipal {
+    userId: string;
+    /**
+     * The tenant the principal is authenticated in. Required and must equal the
+     * request's tenant: a principal never acts in another tenant. A host whose
+     * recipient is authenticated elsewhere (e.g. a member of a child tenant)
+     * authorizes the recipient itself and makes a trusted call without a
+     * principal instead.
+     */
+    tenantId: string;
+}
+export interface NotificationOptOutKey {
+    tenantId: string;
+    recipientUserId: string;
+    channel: NotificationDeliveryChannel;
+    /** `*` or a host key such as `project:<uuid>`. */
+    scope: string;
+}
+export interface NotificationOptOutChange extends NotificationOptOutKey {
+    /**
+     * The signed-in person, authenticated in this tenant. When present only the
+     * recipient themself may change the row, and only in the principal's own
+     * tenant; when omitted the call is trusted host code that has already
+     * authenticated the recipient (e.g. a signed unsubscribe link, or a host
+     * route whose member belongs to a child tenant of the delivery tenant).
+     */
+    principal?: NotificationOptOutPrincipal;
+}
+export interface NotificationOptOutListRequest {
+    tenantId: string;
+    recipientUserId: string;
+    principal: NotificationOptOutPrincipal;
+}
+export type NotificationOptOutDenialReason = 'principal' | 'tenant';
+/** Thrown when a principal tries to read or change another person's opt-out. */
+export declare class NotificationOptOutDeniedError extends Error {
+    readonly reason: NotificationOptOutDenialReason;
+    constructor(reason: NotificationOptOutDenialReason, message: string);
+}
+/**
+ * The per-recipient opt-out ledger behind the outbox's `isSuppressed` hook.
+ *
+ * Writes are idempotent and, with a `principal`, limited to the recipient's
+ * own rows. {@link isOptedOut} is a trusted read for suppression: it runs
+ * where the recipient is not the caller (a manager enqueues, a worker
+ * dispatches) and is always scoped to the given tenant.
+ */
+export declare class NotificationOptOutService {
+    private readonly options;
+    constructor(options: {
+        db: SmrtClassOptions['db'];
+    });
+    private collection;
+    /** Opt the recipient out of `scope`; a repeat leaves the row untouched. */
+    optOut(change: NotificationOptOutChange): Promise<NotificationOptOut>;
+    /** Clear an opt-out; a repeat, or no row at all, is a no-op. */
+    optIn(change: NotificationOptOutChange): Promise<NotificationOptOut>;
+    /**
+     * Whether the recipient has opted out of `scope` (a `*` row matches every
+     * scope). Trusted read: no principal, always under the tenant's scope.
+     */
+    isOptedOut(key: NotificationOptOutKey): Promise<boolean>;
+    /** The recipient's own active opt-outs, in one tenant. */
+    listForRecipient(request: NotificationOptOutListRequest): Promise<NotificationOptOut[]>;
+    private change;
+}
+/**
+ * Build an `isSuppressed` function for `NotificationOutboxOptions` from the
+ * ledger. `scopeOf` maps a notification to the scope a recipient can opt out
+ * of (e.g. `project:<uuid>` from its `sourceRef`), or null when the
+ * notification is not opt-out-able. A `*` opt-out suppresses any notification
+ * `scopeOf` maps to a scope; returning `'*'` checks only the tenant-wide row.
+ */
+export declare function optOutSuppression(service: Pick<NotificationOptOutService, 'isOptedOut'>, scopeOf: (request: NotificationSuppressionRequest) => string | null | Promise<string | null>): (request: NotificationSuppressionRequest) => Promise<boolean>;
+//# sourceMappingURL=NotificationOptOutService.d.ts.map

package/dist/services/NotificationOptOutService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationOptOutService.d.ts","sourceRoot":"","sources":["../../src/services/NotificationOptOutService.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAGL,kBAAkB,EACnB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAC;AAErF,6EAA6E;AAC7E,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,2BAA2B,CAAC;IACrC,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,wBAAyB,SAAQ,qBAAqB;IACrE;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,2BAA2B,CAAC;CACzC;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,2BAA2B,CAAC;CACxC;AAED,MAAM,MAAM,8BAA8B,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEpE,gFAAgF;AAChF,qBAAa,6BAA8B,SAAQ,KAAK;IAEpD,QAAQ,CAAC,MAAM,EAAE,8BAA8B;gBAAtC,MAAM,EAAE,8BAA8B,EAC/C,OAAO,EAAE,MAAM;CAKlB;AA+CD;;;;;;;GAOG;AACH,qBAAa,yBAAyB;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE;QAAE,EAAE,EAAE,gBAAgB,CAAC,IAAI,CAAC,CAAA;KAAE;IAEpE,OAAO,CAAC,UAAU;IAIlB,2EAA2E;IACrE,MAAM,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAI3E,gEAAgE;IAC1D,KAAK,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAI1E;;;OAGG;IACG,UAAU,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,OAAO,CAAC;IAc9D,0DAA0D;IACpD,gBAAgB,CACpB,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,kBAAkB,EAAE,CAAC;YAmBlB,MAAM;CA6DrB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,IAAI,CAAC,yBAAyB,EAAE,YAAY,CAAC,EACtD,OAAO,EAAE,CACP,OAAO,EAAE,8BAA8B,KACpC,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAC1C,CAAC,OAAO,EAAE,8BAA8B,KAAK,OAAO,CAAC,OAAO,CAAC,CAW/D"}