@reventlessdev/trait-notification 1.0.0-alpha.1

package/src/Notification_Conformance.res.mjs

@@ -0,0 +1,51 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Behavior_GWT$ReventlessGwt from "@reventlessdev/reventless-gwt/src/Behavior_GWT.res.mjs";
+
+function suiteName(host) {
+  return host + ` conforms to the notification trait`;
+}
+
+function Make(B) {
+  let $$let = B.Behavior;
+  let G = Behavior_GWT$ReventlessGwt.Make(B.Spec)({
+    initialState: $$let.initialState,
+    evolve: $$let.evolve,
+    decide: $$let.decide
+  });
+  let announced = B.created.concat([B.announcedC(B.addressA)]);
+  let register = () => G.describe(suiteName(B.Spec.name), () => {
+    G.test("an announced contact is recorded", () => G.thenEvent(G.whenCmd(G.givenEvents(B.created), B.announce(B.addressA)), B.announced(B.addressA)));
+    G.test("re-announcing the address already on file is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(announced), B.announce(B.addressA))));
+    G.test("a changed address is recorded", () => G.thenEvent(G.whenCmd(G.givenEvents(announced), B.announce(B.addressB)), B.announced(B.addressB)));
+    G.test("managing preferences for an unannounced recipient is refused", () => G.thenError(G.whenCmd(G.givenEvents(B.created), B.subscribe(B.optional, B.announcedChannel)), B.recipientUnknown));
+    G.test("opting in to a kind that is off by default is recorded", () => G.thenEvent(G.whenCmd(G.givenEvents(announced), B.subscribe(B.optional, B.announcedChannel)), B.subscribed(B.optional, B.announcedChannel)));
+    G.test("subscribing to a kind already on by posture is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(announced), B.subscribe(B.transactional, B.announcedChannel))));
+    G.test("opting out of a kind that is on is recorded", () => G.thenEvent(G.whenCmd(G.givenEvents(announced), B.unsubscribe(B.transactional, B.announcedChannel)), B.unsubscribed(B.transactional, B.announcedChannel)));
+    G.test("opting out of a kind already off is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(announced), B.unsubscribe(B.optional, B.announcedChannel))));
+    G.test("a transactional request goes out with no explicit subscription", () => G.thenEvent(G.whenCmd(G.givenEvents(announced), B.request(B.transactional, "ref-1")), B.requested(B.transactional, "ref-1", B.announcedChannel, B.addressA)));
+    G.test("the address on the request is the one currently on file", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([B.announcedC(B.addressB)])), B.request(B.transactional, "ref-1")), B.requested(B.transactional, "ref-1", B.announcedChannel, B.addressB)));
+    G.test("an optional request is suppressed with no explicit subscription", () => G.thenEvent(G.whenCmd(G.givenEvents(announced), B.request(B.optional, "ref-2")), B.suppressed(B.optional, "ref-2")));
+    G.test("a recipient who opted out is suppressed", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([B.unsubscribedC(B.transactional, B.announcedChannel)])), B.request(B.transactional, "ref-3")), B.suppressed(B.transactional, "ref-3")));
+    G.test("a request for a recipient nobody announced is undeliverable", () => G.thenEvent(G.whenCmd(G.givenEvents(B.created), B.request(B.transactional, "ref-4")), B.undeliverable(B.transactional, "ref-4")));
+    let channel = B.unreachableChannel;
+    if (channel !== undefined) {
+      return G.test("a channel with no address on file is undeliverable, not suppressed", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([
+        B.subscribedC(B.transactional, channel),
+        B.unsubscribedC(B.transactional, B.announcedChannel)
+      ])), B.request(B.transactional, "ref-5")), B.undeliverable(B.transactional, "ref-5")));
+    }
+  });
+  return {
+    G: G,
+    R: undefined,
+    announced: announced,
+    register: register
+  };
+}
+
+export {
+  suiteName,
+  Make,
+}
+/* Behavior_GWT-ReventlessGwt Not a pure module */

package/src/Notification_Rules.res

@@ -0,0 +1,173 @@
+/**
+The notification competency's rules, compiled once and called by every host: a
+recipient is reachable at an address per channel, subscribes to a *kind* of
+notification per channel, and a request to notify them resolves to an addressed
+message, a suppression, or a record that nobody could be reached.
+
+A host maps its own constructors onto `op` and `fact` and keeps the spec surface —
+the variants, their annotations, its refusals. Nothing here knows what an order
+is, or what a customer is. `Notification_Conformance` asserts these rules through
+a host.
+
+## The one thing this module cannot know
+
+Whether an unheard-from recipient should be notified is **per category and per
+host**: a confirmation is one the recipient asked for by ordering, and marketing
+is the opposite. So the fallback *rule* lives here — an absent choice defers to
+the posture — and the *table* is passed in as `~posture`. A trait that hard-coded
+either answer would be wrong for half its hosts.
+*/
+
+/** How a recipient is reached. Mirrors `Reventless.Messaging.channel`, which is
+    the platform capability's vocabulary; this one is the domain's, so it carries
+    a host's schema and travels on the wire. `Notification_Send` maps the two. */
+type channel =
+  | Email
+  | Sms
+  | Push
+
+let channels = [Email, Sms, Push]
+
+/** A selectable kind of notification, as its host spells it. A key rather than a
+    variant for the same reason the attachments trait's `ref` is a string: the
+    host's own `category` is a real variant with a schema, and wrapping it here
+    would only mean unwrapping it on every arm. What kinds exist is the host's
+    vocabulary — this module never enumerates them. */
+type category = string
+
+/** Refolded per decision, never stored — the host's slice state is. */
+type t = {
+  /** One address per channel. An array rather than a single address because the
+      channels differ in kind: an email is one address per person, a device token
+      is one per *install*. A host that only ever announces an inbox holds a
+      one-element list, and the shape does not have to change when it does not. */
+  contacts: array<(channel, string)>,
+  /** Only the cells a recipient has an opinion about; the rest is `~posture`. */
+  choices: array<(category, channel, bool)>,
+}
+
+let empty = {contacts: [], choices: []}
+
+/** What a host asks the competency to do. */
+type op =
+  | /** Relayed from whatever the host publishes when it learns where somebody is.
+        Not a client's command: a caller who could announce another person's
+        address would be redirecting their mail. */
+  Announce({channel: channel, address: string})
+  | Subscribe({category: category, channel: channel})
+  | Unsubscribe({category: category, channel: channel})
+  | /** Something worth telling them about happened. `reference` is the caller's
+        own key for it, echoed back on whichever outcome follows, so the relay
+        that asked can tell its work is finished. Opaque here on purpose. */
+  Request({category: category, reference: string})
+
+/** What the competency decided, for the host to name in its own events. */
+type fact =
+  | Announced({channel: channel, address: string})
+  | Subscribed({category: category, channel: channel})
+  | Unsubscribed({category: category, channel: channel})
+  | /** The addressed message. `address` is the snapshot delivery uses, which is
+        why it is on the fact and not looked up again later. */
+  Requested({category: category, reference: string, channel: channel, address: string})
+  | /** They are reachable and said no. */
+  Suppressed({category: category, reference: string})
+  | /** They want it and nobody can be reached — no address on file for any
+        channel they left enabled. A different fact from `Suppressed` on purpose:
+        one is the system working and the other is the system falling short, and
+        reporting both the same way hides every delivery gap behind a legitimate
+        preference. */
+  Undeliverable({category: category, reference: string})
+
+let addressFor = (t, channel) =>
+  t.contacts->Array.find(((c, _)) => c == channel)->Option.map(((_, address)) => address)
+
+/** Whether this cell is on: the recipient's own choice if they made one, else the
+    host's posture for that kind. */
+let enabled = (t, ~posture: (category, channel) => bool, category, channel) =>
+  switch t.choices->Array.find(((cat, ch, _)) => cat == category && ch == channel) {
+  | Some((_, _, isEnabled)) => isEnabled
+  | None => posture(category, channel)
+  }
+
+let withChoice = (t, category, channel, isEnabled) => {
+  ...t,
+  choices: Array.concat(
+    t.choices->Array.filter(((cat, ch, _)) => !(cat == category && ch == channel)),
+    [(category, channel, isEnabled)],
+  ),
+}
+
+let evolve = (t, fact) =>
+  switch fact {
+  | Announced({channel, address}) => {
+      ...t,
+      contacts: Array.concat(
+        t.contacts->Array.filter(((c, _)) => c != channel),
+        [(channel, address)],
+      ),
+    }
+  | Subscribed({category, channel}) => withChoice(t, category, channel, true)
+  | Unsubscribed({category, channel}) => withChoice(t, category, channel, false)
+  // Neither the outcome of a request nor a delivery report changes who somebody
+  // is or what they want, so the fold ignores them. What a host must NOT do is
+  // read them back as consumed events to make this state bigger — the directory
+  // is snapshotted, and a set of every reference ever seen would grow forever.
+  | Requested(_)
+  | Suppressed(_)
+  | Undeliverable(_) => t
+  }
+
+/** The whole competency, in one function.
+
+    `array<fact>` rather than `option<fact>`: a request can go out on more than
+    one channel, and each is its own message. An empty array is the no-op a
+    retried subscribe produces; a request never returns one, because the relay
+    upstream is waiting for an outcome and a silent path is a row that retries
+    until it is abandoned.
+
+    The one refusal is a client managing preferences for somebody the directory
+    has never heard of — a person is at the other end of that one and can be
+    told, unlike the relayed ops, which record a fact instead. */
+let decide = (t, op, ~posture: (category, channel) => bool): result<
+  array<fact>,
+  [#RecipientUnknown],
+> =>
+  switch op {
+  | Announce({channel, address}) =>
+    addressFor(t, channel) == Some(address) ? Ok([]) : Ok([Announced({channel, address})])
+
+  | Subscribe({category, channel}) =>
+    t.contacts->Array.length == 0
+      ? Error(#RecipientUnknown)
+      : enabled(t, ~posture, category, channel)
+      ? Ok([])
+      : Ok([Subscribed({category, channel})])
+
+  | Unsubscribe({category, channel}) =>
+    t.contacts->Array.length == 0
+      ? Error(#RecipientUnknown)
+      : enabled(t, ~posture, category, channel)
+      ? Ok([Unsubscribed({category, channel})])
+      : Ok([])
+
+  | Request({category, reference}) =>
+    let wanted = channels->Array.filter(channel => enabled(t, ~posture, category, channel))
+    let addressed =
+      wanted->Array.filterMap(channel =>
+        addressFor(t, channel)->Option.map(address => Requested({
+          category,
+          reference,
+          channel,
+          address,
+        }))
+      )
+    switch addressed {
+    | [] =>
+      // Wanted-but-unreachable and not-wanted are the two ways to send nothing,
+      // and telling them apart is the whole reason `Undeliverable` exists.
+      wanted->Array.length == 0
+        ? Ok([Suppressed({category, reference})])
+        : Ok([Undeliverable({category, reference})])
+    | facts => Ok(facts)
+    }
+  }

package/src/Notification_Rules.res.mjs

@@ -0,0 +1,187 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+
+let channels = [
+  "Email",
+  "Sms",
+  "Push"
+];
+
+let empty_contacts = [];
+
+let empty_choices = [];
+
+let empty = {
+  contacts: empty_contacts,
+  choices: empty_choices
+};
+
+function addressFor(t, channel) {
+  return Stdlib_Option.map(t.contacts.find(param => param[0] === channel), param => param[1]);
+}
+
+function enabled(t, posture, category, channel) {
+  let match = t.choices.find(param => {
+    if (param[0] === category) {
+      return param[1] === channel;
+    } else {
+      return false;
+    }
+  });
+  if (match !== undefined) {
+    return match[2];
+  } else {
+    return posture(category, channel);
+  }
+}
+
+function withChoice(t, category, channel, isEnabled) {
+  return {
+    contacts: t.contacts,
+    choices: t.choices.filter(param => param[0] !== category || param[1] !== channel).concat([[
+        category,
+        channel,
+        isEnabled
+      ]])
+  };
+}
+
+function evolve(t, fact) {
+  switch (fact.TAG) {
+    case "Announced" :
+      let channel = fact.channel;
+      return {
+        contacts: t.contacts.filter(param => param[0] !== channel).concat([[
+            channel,
+            fact.address
+          ]]),
+        choices: t.choices
+      };
+    case "Subscribed" :
+      return withChoice(t, fact.category, fact.channel, true);
+    case "Unsubscribed" :
+      return withChoice(t, fact.category, fact.channel, false);
+    default:
+      return t;
+  }
+}
+
+function decide(t, op, posture) {
+  switch (op.TAG) {
+    case "Announce" :
+      let address = op.address;
+      let channel = op.channel;
+      if (Primitive_object.equal(addressFor(t, channel), address)) {
+        return {
+          TAG: "Ok",
+          _0: []
+        };
+      } else {
+        return {
+          TAG: "Ok",
+          _0: [{
+              TAG: "Announced",
+              channel: channel,
+              address: address
+            }]
+        };
+      }
+    case "Subscribe" :
+      if (t.contacts.length === 0) {
+        return {
+          TAG: "Error",
+          _0: "RecipientUnknown"
+        };
+      }
+      let channel$1 = op.channel;
+      let category = op.category;
+      if (enabled(t, posture, category, channel$1)) {
+        return {
+          TAG: "Ok",
+          _0: []
+        };
+      } else {
+        return {
+          TAG: "Ok",
+          _0: [{
+              TAG: "Subscribed",
+              category: category,
+              channel: channel$1
+            }]
+        };
+      }
+    case "Unsubscribe" :
+      if (t.contacts.length === 0) {
+        return {
+          TAG: "Error",
+          _0: "RecipientUnknown"
+        };
+      }
+      let channel$2 = op.channel;
+      let category$1 = op.category;
+      if (enabled(t, posture, category$1, channel$2)) {
+        return {
+          TAG: "Ok",
+          _0: [{
+              TAG: "Unsubscribed",
+              category: category$1,
+              channel: channel$2
+            }]
+        };
+      } else {
+        return {
+          TAG: "Ok",
+          _0: []
+        };
+      }
+    case "Request" :
+      let reference = op.reference;
+      let category$2 = op.category;
+      let wanted = channels.filter(channel => enabled(t, posture, category$2, channel));
+      let addressed = Stdlib_Array.filterMap(wanted, channel => Stdlib_Option.map(addressFor(t, channel), address => ({
+        TAG: "Requested",
+        category: category$2,
+        reference: reference,
+        channel: channel,
+        address: address
+      })));
+      if (addressed.length !== 0) {
+        return {
+          TAG: "Ok",
+          _0: addressed
+        };
+      } else if (wanted.length === 0) {
+        return {
+          TAG: "Ok",
+          _0: [{
+              TAG: "Suppressed",
+              category: category$2,
+              reference: reference
+            }]
+        };
+      } else {
+        return {
+          TAG: "Ok",
+          _0: [{
+              TAG: "Undeliverable",
+              category: category$2,
+              reference: reference
+            }]
+        };
+      }
+  }
+}
+
+export {
+  channels,
+  empty,
+  addressFor,
+  enabled,
+  withChoice,
+  evolve,
+  decide,
+}
+/* No side effect */