@krizaka/notifications 0.0.0-stage → 0.2.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 [yyyy] [name of copyright owner]
+
+   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,38 @@
-# Temporary Holding Version
+# @krizaka/notifications
 
-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.
+The bell, the channels and the preferences for every Krizaka product. One `notify` writes the in-app item and appends one outbox message per enabled channel, respecting the account's matrix and a burst cap per category. No push or realtime import (the workers that deliver a channel are the product's), no database client, no wall clock.
+
+- **Channels.** `app` (the bell and the live event of the open pages, one switch), `push` (one message per registered device) and `email`. The outbox topics are `notifications.live`, `notifications.push` and `notifications.email`; the event is `evt.notification.requested.v1`, the name and the shape of Java's `krizaka-notifications-api` request (`channel`, `recipient`, `template`, `locale`, `variables`, plus the ids; `channel` is `EMAIL`, and `PUSH` / `LIVE` for the web). A product delivers e-mail with its own worker (`@krizaka/email` to render, `@krizaka/mail` to queue) or lets the Java service consume it.
+- **The product declares its categories** and their defaults (`notificationSettings(declared)` is the registry fragment); the admin tunes the default channels and the caps without a redeploy. A `locked` category (security, the account) cannot be switched off by anyone.
+- **Burst caps.** After `burstMax` notifications of one category to one account within `burstWindowSeconds`, the next ones are bell-only: the item is kept, no channel is used. The count and the insert run under a transaction-level advisory lock per account and category, so the cap holds under concurrency when `notify` gets the caller's `tx`.
+- **Idempotent.** `dedupeKey` makes one fact one notification; the outbox message ids derive from the item, so a retried append is a no-op.
+- **The bell.** `list` (newest first, cursor), `unreadCount`, `markRead` (the account's own items; the first `read_at` stays). An item whose `app` channel was off is kept for the history and the cap, never shown.
+- **Preferences.** `preferences` (every category by channel with its source: default, account, locked), `setPreference`, `setMatrix` (a preset applied).
+- **Devices.** `registerDevice` (a token belongs to one account; registering it again moves it), `revokeDevice` when the push service refuses it.
+- **Privacy.** The module holds no address (the product passes `email` per call); `erase(accountId)` removes the items, choices and devices; `purge` applies the retention.
+
+```ts
+import { createOutbox } from "@krizaka/outbox";
+import { createNotifications, dbNotificationStore } from "@krizaka/notifications";
+import { notificationSettings, readNotificationConfig } from "@krizaka/notifications/settings";
+
+const declared = {
+  messages: { defaults: { app: true, push: true, email: true }, burst: { max: 5, windowSeconds: 3600 } },
+  follows: { defaults: { app: true, push: false, email: false } },
+  account: { locked: true, defaults: { app: true, push: true, email: true } },
+};
+// settingsRegistry = { ...otherSettings, ...notificationSettings(declared) }
+
+const notifications = createNotifications({
+  clock,
+  outbox: createOutbox({ clock, settings: outboxSettings }),
+  config: () => readNotificationConfig(declared, (key) => settings.get(key)),
+});
+
+// in the use case's transaction
+await notifications.notify(tx, { accountId, category: "messages", template: "new-message", variables: { name }, locale: "fr", email, dedupeKey: `message:${messageId}` });
+```
+
+Tables (schema `notifications`, `notificationsSchema`): `item`, `preference`, `device`. `notificationStoreContract` (`@krizaka/notifications/testkit`) is the contract every store runs.
+
+Apache-2.0.

package/dist/chunk-2MH7PZDT.js

@@ -0,0 +1,88 @@
+import {
+  CHANNELS,
+  NOTIFICATION_CODE,
+  NotificationError
+} from "./chunk-FQYNUK64.js";
+
+// src/rules.ts
+import { createHash } from "crypto";
+var NOTIFICATION_BOUNDS = { burstMax: [1, 1e3], burstWindowSeconds: [1, 604800], retentionDays: [1, 3650] };
+var NOTIFICATION_DEFAULTS = { burstMax: 20, burstWindowSeconds: 3600, retentionDays: 180 };
+var CATEGORY_NAME = /^[a-z][a-zA-Z0-9]{0,39}$/;
+var TEMPLATE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+var LOCALE = /^[a-z]{2}(-[A-Za-z]{2,4})?$/;
+var MAX_PAYLOAD_BYTES = 8192;
+var MAX_KEY = 200;
+function uuidOf(seed) {
+  const h = createHash("sha256").update(`krizaka.notifications:${seed}`).digest();
+  h[6] = h[6] & 15 | 80;
+  h[8] = h[8] & 63 | 128;
+  const x = h.subarray(0, 16).toString("hex");
+  return `${x.slice(0, 8)}-${x.slice(8, 12)}-${x.slice(12, 16)}-${x.slice(16, 20)}-${x.slice(20, 32)}`;
+}
+var within = (n, [min, max]) => Number.isInteger(n) && n >= min && n <= max;
+function checkConfig(config) {
+  for (const [name, c] of Object.entries(config.categories)) {
+    if (!CATEGORY_NAME.test(name)) throw new NotificationError(NOTIFICATION_CODE.badConfig, `category \xAB ${name} \xBB must be a camel-case word`);
+    if (!within(c.burstMax, NOTIFICATION_BOUNDS.burstMax)) throw new NotificationError(NOTIFICATION_CODE.badConfig, `${name}.burstMax is out of bounds`);
+    if (!within(c.burstWindowSeconds, NOTIFICATION_BOUNDS.burstWindowSeconds)) throw new NotificationError(NOTIFICATION_CODE.badConfig, `${name}.burstWindowSeconds is out of bounds`);
+  }
+  if (!within(config.retentionDays, NOTIFICATION_BOUNDS.retentionDays)) throw new NotificationError(NOTIFICATION_CODE.badConfig, "retentionDays is out of bounds");
+  return config;
+}
+function categoryOf(config, name) {
+  const category = Object.hasOwn(config.categories, name) ? config.categories[name] : void 0;
+  if (!category) throw new NotificationError(NOTIFICATION_CODE.badCategory, `unknown category \xAB ${name} \xBB`);
+  return category;
+}
+function resolveChannels(category, chosen) {
+  const out = { ...category.defaults };
+  if (category.locked) return out;
+  for (const channel of CHANNELS) {
+    const choice = chosen.get(channel);
+    if (choice !== void 0) out[channel] = choice;
+  }
+  return out;
+}
+function viewOf(config, rows) {
+  return Object.entries(config.categories).map(([category, def]) => {
+    const chosen = new Map(rows.filter((r) => r.category === category).map((r) => [r.channel, r.enabled]));
+    const channels = Object.fromEntries(
+      CHANNELS.map((channel) => {
+        const source = def.locked ? "locked" : chosen.has(channel) ? "account" : "default";
+        return [channel, { enabled: def.locked ? def.defaults[channel] : chosen.get(channel) ?? def.defaults[channel], source }];
+      })
+    );
+    return { category, locked: def.locked, channels };
+  });
+}
+var NOT_IN_ADDRESS = /[\s<>]/;
+function isAddress(value) {
+  const at = value.indexOf("@");
+  if (at < 1 || at !== value.lastIndexOf("@") || NOT_IN_ADDRESS.test(value)) return false;
+  const labels = value.slice(at + 1).split(".");
+  return labels.length >= 2 && labels.every((label) => label !== "");
+}
+function checkInput(input) {
+  const bad = (why) => new NotificationError(NOTIFICATION_CODE.badInput, why);
+  if (typeof input.accountId !== "string" || input.accountId === "") throw bad("accountId is required");
+  if (!TEMPLATE.test(input.template)) throw bad("template is lower-case words joined by hyphens");
+  if (input.locale !== void 0 && !LOCALE.test(input.locale)) throw bad("locale is a language tag like fr or en-CA");
+  if (input.dedupeKey !== void 0 && (input.dedupeKey === "" || input.dedupeKey.length > MAX_KEY)) throw bad("dedupeKey is 1 to 200 characters");
+  if (input.email !== void 0 && !isAddress(input.email)) throw bad("email is not an address");
+  for (const [key, value] of Object.entries(input.variables ?? {})) if (typeof value !== "string") throw bad(`variable \xAB ${key} \xBB must be a string`);
+  if (Buffer.byteLength(JSON.stringify({ v: input.variables ?? {}, p: input.payload ?? {} })) > MAX_PAYLOAD_BYTES) throw bad("variables and payload are too big for a notification");
+}
+
+export {
+  NOTIFICATION_BOUNDS,
+  NOTIFICATION_DEFAULTS,
+  CATEGORY_NAME,
+  uuidOf,
+  checkConfig,
+  categoryOf,
+  resolveChannels,
+  viewOf,
+  checkInput
+};
+//# sourceMappingURL=chunk-2MH7PZDT.js.map

package/dist/chunk-2MH7PZDT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/rules.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\n\nimport { type CategoryDefaults, type Channel, CHANNELS, NOTIFICATION_CODE, type NotificationConfig, NotificationError } from \"./port\";\n\nexport const NOTIFICATION_BOUNDS = { burstMax: [1, 1000], burstWindowSeconds: [1, 604_800], retentionDays: [1, 3650] } as const;\nexport const NOTIFICATION_DEFAULTS = { burstMax: 20, burstWindowSeconds: 3600, retentionDays: 180 } as const;\n\n/** A category name: a camel-case word (it becomes part of a setting key). */\nexport const CATEGORY_NAME = /^[a-z][a-zA-Z0-9]{0,39}$/;\nconst TEMPLATE = /^[a-z0-9]+(-[a-z0-9]+)*$/;\nconst LOCALE = /^[a-z]{2}(-[A-Za-z]{2,4})?$/;\n// @fixed: a notification is a short event, not a document; a bigger payload belongs in the product's own tables\nconst MAX_PAYLOAD_BYTES = 8192;\nconst MAX_KEY = 200;\n\n/** A stable UUID (version 5 shaped) from a seed: the same fact appended twice is one outbox message. */\nexport function uuidOf(seed: string): string {\n  const h = createHash(\"sha256\").update(`krizaka.notifications:${seed}`).digest();\n  h[6] = (h[6]! & 0x0f) | 0x50;\n  h[8] = (h[8]! & 0x3f) | 0x80;\n  const x = h.subarray(0, 16).toString(\"hex\");\n  return `${x.slice(0, 8)}-${x.slice(8, 12)}-${x.slice(12, 16)}-${x.slice(16, 20)}-${x.slice(20, 32)}`;\n}\n\nconst within = (n: number, [min, max]: readonly [number, number]) => Number.isInteger(n) && n >= min && n <= max;\n\n/** @throws NotificationError when a category name, a burst cap or the retention is out of bounds. */\nexport function checkConfig(config: NotificationConfig): NotificationConfig {\n  for (const [name, c] of Object.entries(config.categories)) {\n    if (!CATEGORY_NAME.test(name)) throw new NotificationError(NOTIFICATION_CODE.badConfig, `category « ${name} » must be a camel-case word`);\n    if (!within(c.burstMax, NOTIFICATION_BOUNDS.burstMax)) throw new NotificationError(NOTIFICATION_CODE.badConfig, `${name}.burstMax is out of bounds`);\n    if (!within(c.burstWindowSeconds, NOTIFICATION_BOUNDS.burstWindowSeconds)) throw new NotificationError(NOTIFICATION_CODE.badConfig, `${name}.burstWindowSeconds is out of bounds`);\n  }\n  if (!within(config.retentionDays, NOTIFICATION_BOUNDS.retentionDays)) throw new NotificationError(NOTIFICATION_CODE.badConfig, \"retentionDays is out of bounds\");\n  return config;\n}\n\nexport function categoryOf(config: NotificationConfig, name: string): CategoryDefaults {\n  const category = Object.hasOwn(config.categories, name) ? config.categories[name] : undefined;\n  if (!category) throw new NotificationError(NOTIFICATION_CODE.badCategory, `unknown category « ${name} »`);\n  return category;\n}\n\n/** The channels on for an account: the category's defaults, overridden by the account's choices, unless the category is locked. */\nexport function resolveChannels(category: CategoryDefaults, chosen: ReadonlyMap<Channel, boolean>): Record<Channel, boolean> {\n  const out = { ...category.defaults };\n  if (category.locked) return out;\n  for (const channel of CHANNELS) {\n    const choice = chosen.get(channel);\n    if (choice !== undefined) out[channel] = choice;\n  }\n  return out;\n}\n\n/** What an account sees in its settings: every category, every channel, and why. */\nexport interface PreferenceView {\n  category: string;\n  locked: boolean;\n  channels: Record<Channel, { enabled: boolean; source: \"default\" | \"account\" | \"locked\" }>;\n}\n\nexport function viewOf(config: NotificationConfig, rows: readonly { category: string; channel: Channel; enabled: boolean }[]): PreferenceView[] {\n  return Object.entries(config.categories).map(([category, def]) => {\n    const chosen = new Map(rows.filter((r) => r.category === category).map((r) => [r.channel, r.enabled] as const));\n    const channels = Object.fromEntries(\n      CHANNELS.map((channel) => {\n        const source = def.locked ? \"locked\" : chosen.has(channel) ? \"account\" : \"default\";\n        return [channel, { enabled: def.locked ? def.defaults[channel] : (chosen.get(channel) ?? def.defaults[channel]), source }];\n      }),\n    ) as PreferenceView[\"channels\"];\n    return { category, locked: def.locked, channels };\n  });\n}\n\nexport interface NotifyInput {\n  accountId: string;\n  category: string;\n  /** The template the e-mail and the push are rendered from (`new-follower`): lower-case words joined by hyphens. */\n  template: string;\n  /** The words' variables: strings only, the shape of Java's `NotificationRequest`. Never a secret. */\n  variables?: Record<string, string>;\n  /** The recipient's language; only the language is used. */\n  locale?: string;\n  /** Where e-mail goes. Without it the e-mail channel is skipped (the product resolves the address, this module holds none). */\n  email?: string;\n  /** What the bell shows besides the template and variables (a link, an actor id): JSON, small. */\n  payload?: Record<string, unknown>;\n  /** One event notified twice is one notification: the same key for the same fact. */\n  dedupeKey?: string;\n}\n\nconst NOT_IN_ADDRESS = /[\\s<>]/;\n\n/** One `@`, a local part, and a domain of dot-separated non-empty parts: no backtracking pattern over library input. */\nfunction isAddress(value: string): boolean {\n  const at = value.indexOf(\"@\");\n  if (at < 1 || at !== value.lastIndexOf(\"@\") || NOT_IN_ADDRESS.test(value)) return false;\n  const labels = value.slice(at + 1).split(\".\");\n  return labels.length >= 2 && labels.every((label) => label !== \"\");\n}\n\n/** @throws NotificationError on the first thing wrong with an input. */\nexport function checkInput(input: NotifyInput): void {\n  const bad = (why: string) => new NotificationError(NOTIFICATION_CODE.badInput, why);\n  if (typeof input.accountId !== \"string\" || input.accountId === \"\") throw bad(\"accountId is required\");\n  if (!TEMPLATE.test(input.template)) throw bad(\"template is lower-case words joined by hyphens\");\n  if (input.locale !== undefined && !LOCALE.test(input.locale)) throw bad(\"locale is a language tag like fr or en-CA\");\n  if (input.dedupeKey !== undefined && (input.dedupeKey === \"\" || input.dedupeKey.length > MAX_KEY)) throw bad(\"dedupeKey is 1 to 200 characters\");\n  if (input.email !== undefined && !isAddress(input.email)) throw bad(\"email is not an address\");\n  for (const [key, value] of Object.entries(input.variables ?? {})) if (typeof value !== \"string\") throw bad(`variable « ${key} » must be a string`);\n  if (Buffer.byteLength(JSON.stringify({ v: input.variables ?? {}, p: input.payload ?? {} })) > MAX_PAYLOAD_BYTES) throw bad(\"variables and payload are too big for a notification\");\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-FQYNUK64.js

@@ -0,0 +1,29 @@
+// src/port.ts
+var CHANNEL = { app: "app", push: "push", email: "email" };
+var CHANNELS = [CHANNEL.app, CHANNEL.push, CHANNEL.email];
+var DELIVERY = { email: "EMAIL", push: "PUSH", live: "LIVE" };
+var PLATFORM = { ios: "ios", android: "android", web: "web" };
+var NOTIFICATION_CODE = {
+  badCategory: "NOTIFICATIONS_BAD_CATEGORY",
+  badInput: "NOTIFICATIONS_BAD_INPUT",
+  locked: "NOTIFICATIONS_LOCKED",
+  badConfig: "NOTIFICATIONS_BAD_CONFIG"
+};
+var NotificationError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "NotificationError";
+  }
+  code;
+};
+
+export {
+  CHANNEL,
+  CHANNELS,
+  DELIVERY,
+  PLATFORM,
+  NOTIFICATION_CODE,
+  NotificationError
+};
+//# sourceMappingURL=chunk-FQYNUK64.js.map

package/dist/chunk-FQYNUK64.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/port.ts"],"sourcesContent":["/**\n * The ports of « notifications »: the bell (an item per notification), the account's preferences (a matrix of categories by\n * channels), the phones registered for push, and one outbox message per enabled channel. Generic: no push or realtime import (the\n * workers that deliver a channel are the product's, or the Java service's for e-mail), no database client, no wall clock.\n */\nexport type { Clock, Query } from \"@krizaka/db\";\n\n/**\n * The channels an account switches. `app` is the bell and the live event of the open pages (one switch, like Orochia's matrix);\n * `push` goes to the account's registered phones; `email` to its address.\n */\nexport const CHANNEL = { app: \"app\", push: \"push\", email: \"email\" } as const;\nexport type Channel = (typeof CHANNEL)[keyof typeof CHANNEL];\nexport const CHANNELS: readonly Channel[] = [CHANNEL.app, CHANNEL.push, CHANNEL.email];\n\n/** What the outbox carries: the `channel` of Java's `evt.notification.requested.v1` (EMAIL) and two more for the web (PUSH, LIVE). */\nexport const DELIVERY = { email: \"EMAIL\", push: \"PUSH\", live: \"LIVE\" } as const;\nexport type Delivery = (typeof DELIVERY)[keyof typeof DELIVERY];\n\nexport const PLATFORM = { ios: \"ios\", android: \"android\", web: \"web\" } as const;\nexport type Platform = (typeof PLATFORM)[keyof typeof PLATFORM];\n\n/** A category as the product declares it. */\nexport interface CategoryDefaults {\n  /** Cannot be switched off (security, the account): its channels follow `defaults`, whatever the account chose. */\n  locked: boolean;\n  /** Which channels are on until the account chooses. */\n  defaults: Record<Channel, boolean>;\n  /** After `burstMax` notifications of this category to one account within `burstWindowSeconds`, the next ones are bell-only. */\n  burstMax: number;\n  burstWindowSeconds: number;\n}\n\n/** The categories (declared by the product, tuned by the admin) and the retention. Read from the settings at each call. */\nexport interface NotificationConfig {\n  categories: Record<string, CategoryDefaults>;\n  /** Days an item is kept before `purge`. */\n  retentionDays: number;\n}\n\n/** One line of the bell. */\nexport interface Item {\n  id: string;\n  accountId: string;\n  category: string;\n  template: string;\n  payload: Record<string, unknown>;\n  dedupeKey: string | null;\n  /** Shown in the bell. An item whose app channel was off is kept (the burst count and the history) but not shown. */\n  inBell: boolean;\n  createdAt: Date;\n  readAt: Date | null;\n}\n\nexport interface Device {\n  id: string;\n  accountId: string;\n  platform: Platform;\n  token: string;\n  createdAt: Date;\n  lastSeenAt: Date;\n}\n\n/** Where the state lives. Every adapter runs `notificationStoreContract` (`@krizaka/notifications/testkit`). */\nexport interface NotificationStore {\n  /**\n   * Writes the item and says whether it exceeds the burst cap, ATOMICALLY per account and category (the database serialises\n   * concurrent callers with a transaction-level advisory lock, so the cap holds under concurrency: pass the caller's `tx`).\n   * `duplicate` when the account already has an item with this `dedupeKey`: nothing is written.\n   */\n  record(item: Item, burst: { max: number; since: Date }): Promise<{ duplicate: boolean; capped: boolean }>;\n  /** The account's explicit choices. */\n  preferences(accountId: string): Promise<{ category: string; channel: Channel; enabled: boolean }[]>;\n  setPreference(accountId: string, category: string, channel: Channel, enabled: boolean, now: Date): Promise<void>;\n  /** Items shown in the bell, newest first; `before` is the cursor (the last item of the previous page). */\n  list(accountId: string, options: { unreadOnly: boolean; limit: number; before?: { createdAt: Date; id: string } }): Promise<Item[]>;\n  unreadCount(accountId: string): Promise<number>;\n  /** Marks read the account's own unread items among `ids` (all of them when `ids` is null). The first `read_at` stays. Returns how many. */\n  markRead(accountId: string, ids: readonly string[] | null, now: Date): Promise<number>;\n  /** A token belongs to one account: registering it again moves it, and brings back a revoked one. */\n  upsertDevice(device: Device): Promise<void>;\n  devices(accountId: string): Promise<Device[]>;\n  /** The push service said the token is dead. */\n  revokeDevice(token: string, now: Date): Promise<boolean>;\n  purgeBefore(before: Date): Promise<number>;\n  /** Removes everything held about the account. Returns how many rows. */\n  erase(accountId: string): Promise<number>;\n}\n\nexport const NOTIFICATION_CODE = {\n  badCategory: \"NOTIFICATIONS_BAD_CATEGORY\",\n  badInput: \"NOTIFICATIONS_BAD_INPUT\",\n  locked: \"NOTIFICATIONS_LOCKED\",\n  badConfig: \"NOTIFICATIONS_BAD_CONFIG\",\n} as const;\nexport type NotificationCode = (typeof NOTIFICATION_CODE)[keyof typeof NOTIFICATION_CODE];\n\nexport class NotificationError extends Error {\n  constructor(\n    readonly code: NotificationCode,\n    message: string,\n  ) {\n    super(message);\n    this.name = \"NotificationError\";\n  }\n}\n"],"mappings":";AAWO,IAAM,UAAU,EAAE,KAAK,OAAO,MAAM,QAAQ,OAAO,QAAQ;AAE3D,IAAM,WAA+B,CAAC,QAAQ,KAAK,QAAQ,MAAM,QAAQ,KAAK;AAG9E,IAAM,WAAW,EAAE,OAAO,SAAS,MAAM,QAAQ,MAAM,OAAO;AAG9D,IAAM,WAAW,EAAE,KAAK,OAAO,SAAS,WAAW,KAAK,MAAM;AAsE9D,IAAM,oBAAoB;AAAA,EAC/B,aAAa;AAAA,EACb,UAAU;AAAA,EACV,QAAQ;AAAA,EACR,WAAW;AACb;AAGO,IAAM,oBAAN,cAAgC,MAAM;AAAA,EAC3C,YACW,MACT,SACA;AACA,UAAM,OAAO;AAHJ;AAIT,SAAK,OAAO;AAAA,EACd;AAAA,EALW;AAMb;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,168 @@
+import { N as NotificationStore, C as Channel, a as NotificationConfig, b as CategoryDefaults, D as Delivery, P as Platform, I as Item, c as Device } from './port-DptCmYwy.js';
+export { d as CHANNEL, e as CHANNELS, f as DELIVERY, g as NOTIFICATION_CODE, h as NotificationCode, i as NotificationError, j as PLATFORM } from './port-DptCmYwy.js';
+import * as _krizaka_db from '@krizaka/db';
+import { Clock, Query } from '@krizaka/db';
+export { Clock, Query } from '@krizaka/db';
+
+/** An in-memory store, for unit tests and demos: the behaviour of the database's (the contract kit runs on both). `record` is one synchronous step, so it is atomic. */
+declare function memoryNotificationStore(): NotificationStore;
+
+declare const NOTIFICATION_BOUNDS: {
+    readonly burstMax: readonly [1, 1000];
+    readonly burstWindowSeconds: readonly [1, 604800];
+    readonly retentionDays: readonly [1, 3650];
+};
+declare const NOTIFICATION_DEFAULTS: {
+    readonly burstMax: 20;
+    readonly burstWindowSeconds: 3600;
+    readonly retentionDays: 180;
+};
+/** A stable UUID (version 5 shaped) from a seed: the same fact appended twice is one outbox message. */
+declare function uuidOf(seed: string): string;
+/** @throws NotificationError when a category name, a burst cap or the retention is out of bounds. */
+declare function checkConfig(config: NotificationConfig): NotificationConfig;
+declare function categoryOf(config: NotificationConfig, name: string): CategoryDefaults;
+/** The channels on for an account: the category's defaults, overridden by the account's choices, unless the category is locked. */
+declare function resolveChannels(category: CategoryDefaults, chosen: ReadonlyMap<Channel, boolean>): Record<Channel, boolean>;
+/** What an account sees in its settings: every category, every channel, and why. */
+interface PreferenceView {
+    category: string;
+    locked: boolean;
+    channels: Record<Channel, {
+        enabled: boolean;
+        source: "default" | "account" | "locked";
+    }>;
+}
+declare function viewOf(config: NotificationConfig, rows: readonly {
+    category: string;
+    channel: Channel;
+    enabled: boolean;
+}[]): PreferenceView[];
+interface NotifyInput {
+    accountId: string;
+    category: string;
+    /** The template the e-mail and the push are rendered from (`new-follower`): lower-case words joined by hyphens. */
+    template: string;
+    /** The words' variables: strings only, the shape of Java's `NotificationRequest`. Never a secret. */
+    variables?: Record<string, string>;
+    /** The recipient's language; only the language is used. */
+    locale?: string;
+    /** Where e-mail goes. Without it the e-mail channel is skipped (the product resolves the address, this module holds none). */
+    email?: string;
+    /** What the bell shows besides the template and variables (a link, an actor id): JSON, small. */
+    payload?: Record<string, unknown>;
+    /** One event notified twice is one notification: the same key for the same fact. */
+    dedupeKey?: string;
+}
+/** @throws NotificationError on the first thing wrong with an input. */
+declare function checkInput(input: NotifyInput): void;
+
+/** The event the outbox carries, the name Java's `krizaka-notifications-api` gives its request. */
+declare const NOTIFICATION_EVENT: {
+    readonly requested: "evt.notification.requested.v1";
+};
+/** One topic per delivery, so a worker claims only what it delivers (`notifications.email`, `notifications.push`, `notifications.live`). */
+declare const NOTIFICATION_TOPIC: Record<Delivery, string>;
+/** What the module needs of `@krizaka/outbox` (its `Outbox` satisfies it): append in the caller's transaction. */
+interface NotificationOutbox {
+    append(tx: Query, message: {
+        topic: string;
+        type: string;
+        payload: unknown;
+        id: string;
+    }): Promise<{
+        id: string;
+        appended: boolean;
+    }>;
+}
+interface NotificationDeps {
+    clock: Clock;
+    outbox: NotificationOutbox;
+    /** The categories and the retention, read at each call so the admin's change applies at once. */
+    config: NotificationConfig | (() => NotificationConfig | Promise<NotificationConfig>);
+    /** The store over a query (a transaction or a pool). Default: the PostgreSQL store on schema `notifications`. */
+    storeFor?: (query: Query) => NotificationStore;
+    /** The Postgres schema, when the product renamed the module's (used by the default store). */
+    schema?: string;
+}
+/** The request one delivery worker receives: Java's `NotificationRequest` (channel, recipient, template, locale, variables) plus the ids. */
+interface NotificationRequest {
+    channel: Delivery;
+    /** An e-mail address (EMAIL), a device token (PUSH) or an account id (LIVE). */
+    recipient: string;
+    template: string;
+    locale: string | null;
+    variables: Record<string, string>;
+    notificationId: string;
+    accountId: string;
+    category: string;
+    /** PUSH only. */
+    platform?: Platform;
+}
+interface Notified {
+    /** `null` for a duplicate (same `dedupeKey`): nothing was written or appended. */
+    notificationId: string | null;
+    duplicate: boolean;
+    /** Past the category's burst cap: the item is kept, the channels were not used. */
+    capped: boolean;
+    /** The channels that were used. */
+    channels: Delivery[];
+}
+interface Notifications {
+    /**
+     * Writes the bell item and appends one outbox message per enabled channel, in `tx` (use the caller's transaction: it is what makes
+     * the burst cap hold under concurrency, and the messages leave only if the work commits).
+     */
+    notify(tx: Query, input: NotifyInput): Promise<Notified>;
+    /** The bell, newest first. */
+    list(query: Query, accountId: string, options?: {
+        unreadOnly?: boolean;
+        limit?: number;
+        before?: {
+            createdAt: Date;
+            id: string;
+        };
+    }): Promise<Item[]>;
+    unreadCount(query: Query, accountId: string): Promise<number>;
+    /** Marks the account's own unread items read (those in `ids`, or all). Returns how many. */
+    markRead(query: Query, accountId: string, ids?: readonly string[]): Promise<number>;
+    /** The account's matrix: every category, every channel, and whether it is the default, the account's choice or locked. */
+    preferences(query: Query, accountId: string): Promise<PreferenceView[]>;
+    /** @throws NotificationError `NOTIFICATIONS_LOCKED` for a locked category, `NOTIFICATIONS_BAD_CATEGORY` for an unknown one. */
+    setPreference(query: Query, accountId: string, category: string, channel: Channel, enabled: boolean): Promise<void>;
+    /** The whole matrix at once (a preset applied): the locked categories are left as they are. */
+    setMatrix(query: Query, accountId: string, matrix: Record<string, Partial<Record<Channel, boolean>>>): Promise<void>;
+    registerDevice(query: Query, accountId: string, device: {
+        platform: Platform;
+        token: string;
+    }): Promise<void>;
+    /** The push service refused the token: it is never used again until registered anew. */
+    revokeDevice(query: Query, token: string): Promise<boolean>;
+    devices(query: Query, accountId: string): Promise<Device[]>;
+    /** Removes the items older than the retention. */
+    purge(query: Query): Promise<number>;
+    /** Erasure (Loi 25): everything held about the account. */
+    erase(query: Query, accountId: string): Promise<number>;
+}
+/**
+ * The notifications of a product.
+ * @param deps the clock, the outbox, the configuration, and optionally the store and schema
+ * @returns the notification functions
+ */
+declare function createNotifications(deps: NotificationDeps): Notifications;
+
+/**
+ * The PostgreSQL store of « notifications » over a `Query`, in schema `notifications` (or the one the product renamed it to).
+ * `record` takes a transaction-level advisory lock per account and category, so the burst cap holds under concurrency ONLY inside the
+ * caller's transaction: pass `tx`.
+ */
+declare function dbNotificationStore(query: Query, schema?: string): NotificationStore;
+
+/**
+ * The tables of « notifications », in their own Postgres schema: `item` (the bell, and the history the burst caps count), `preference`
+ * (the account's explicit choices: account by category by channel) and `device` (the push tokens). The one product table referenced is
+ * the owner (`owner`, the account table): a deleted account takes its rows with it. Version 1 is frozen once released: a change is version 2.
+ */
+declare const notificationsSchema: _krizaka_db.ModuleSchema;
+
+export { CategoryDefaults, Channel, Delivery, Device, Item, NOTIFICATION_BOUNDS, NOTIFICATION_DEFAULTS, NOTIFICATION_EVENT, NOTIFICATION_TOPIC, NotificationConfig, type NotificationDeps, type NotificationOutbox, type NotificationRequest, NotificationStore, type Notifications, type Notified, type NotifyInput, Platform, type PreferenceView, categoryOf, checkConfig, checkInput, createNotifications, dbNotificationStore, memoryNotificationStore, notificationsSchema, resolveChannels, uuidOf, viewOf };