@chipmobilesdk/rn-notification 0.6.0 → 0.7.0

package/lib/module/channel/migrate.js

@@ -0,0 +1,242 @@
+"use strict";
+
+/**
+ * Channel declaration and migration.
+ *
+ * Android channels are immutable once created: declaring a channel whose id
+ * already exists silently keeps the original configuration. That single fact is
+ * why changing a tone is a **migration** rather than an assignment, and why
+ * this package keeps its own ledger — the platform will not tell you which
+ * version of a channel a device already holds.
+ *
+ * Migration creates the new channel, re-homes notifications still pointing at
+ * the old one, and only then retires it. That order matters: retiring first
+ * would leave live notifications attached to a channel that no longer exists.
+ */
+
+import { DIAGNOSTIC_CODES } from "../contract/errors.js";
+import { channelIdFor, resolveTone, toneLabelFingerprint } from "./tone-map.js";
+import { validateToneDeclarations } from "./validate-tone.js";
+import { createScheduleWriter } from "../schedule/writer.js";
+function ledgerFor(state, toneId) {
+  return state.read().migrationLedger.find(entry => entry.toneId === toneId && !entry.retired);
+}
+function recordApplied(state, tone, now, retiredChannelId, labelFingerprint) {
+  state.update('migrationLedger', current => {
+    const withoutTone = current.filter(entry => entry.toneId !== tone.id);
+    const retired = retiredChannelId === undefined ? [] : [{
+      at: now,
+      toneId: tone.id,
+      appliedVersion: 0,
+      channelId: retiredChannelId,
+      retired: true
+    }];
+    return [...withoutTone, ...retired, {
+      at: now,
+      toneId: tone.id,
+      appliedVersion: tone.version,
+      channelId: channelIdFor(tone.id, tone.version),
+      retired: false,
+      labelFingerprint
+    }];
+  });
+}
+export function createChannels(deps) {
+  const emit = deps.emit ?? (() => {});
+  // Re-homing re-writes each notification on the new channel; its stop marker
+  // has to follow, or it would retire with the old channel.
+  const writer = createScheduleWriter(deps.engine);
+  const applyTones = async (tones, groups) => {
+    // Validation completes before the first engine call, so a rejected
+    // declaration leaves the device exactly as it was — the same order the
+    // scheduler has always used.
+    validateToneDeclarations(tones);
+    const now = deps.now();
+    const created = [];
+    const migrated = [];
+    const labelsRefreshed = [];
+    const retired = [];
+    const reHomed = [];
+    const cancelled = [];
+    const bypassUnavailable = [];
+    const repeatUnavailable = [];
+    const unchanged = [];
+    if (groups.length > 0) {
+      await deps.engine.declareGroups(groups);
+    }
+    const capabilities = await deps.engine.getCapabilities();
+    for (const tone of tones) {
+      const previous = ledgerFor(deps.state, tone.id);
+      const resolved = resolveTone(tone);
+      const fingerprint = toneLabelFingerprint(tone);
+
+      // Refusals are reported for every tone that asked, whether or not
+      // anything else about it moved. A platform declining an attribute
+      // says nothing about whether the channel is new.
+      if (tone.bypassDoNotDisturb === true && !capabilities.supportsDoNotDisturbBypass) {
+        // Reported honestly rather than silently dropped — a consumer that
+        // asked for a bypass deserves to know the platform refused.
+        bypassUnavailable.push(tone.id);
+        emit(DIAGNOSTIC_CODES.DND_BYPASS_UNAVAILABLE, `Tone "${tone.id}" requested a Do Not Disturb bypass, which this platform does not permit.`, {
+          toneId: tone.id
+        });
+      }
+      if (tone.repeatAlert !== undefined) {
+        if (!capabilities.supportsRepeatingAlert) {
+          repeatUnavailable.push(tone.id);
+          emit(DIAGNOSTIC_CODES.REPEAT_ALERT_UNAVAILABLE, `Tone "${tone.id}" requested a repeating alert, which this platform does not offer. The notification still delivers and still sounds once.`, {
+            toneId: tone.id
+          });
+        } else if (!deps.engine.hasBackgroundDeliveryHandler()) {
+          // Said out loud at declaration time, because the alternative is a
+          // user meeting it as a phone that will not stop ringing.
+          emit(DIAGNOSTIC_CODES.REPEAT_STOP_HANDLER_MISSING, `Tone "${tone.id}" declares a repeating alert, but no background notification handler is registered. Its alert will not stop on its own while the app is not running. Call registerBackgroundNotificationHandler at module scope in index.js.`, {
+            toneId: tone.id
+          });
+        }
+      }
+      const versionMoved = previous !== undefined && previous.appliedVersion !== tone.version;
+      if (previous !== undefined && !versionMoved) {
+        // The version is the same, so nothing the platform freezes has
+        // changed. Only the labels can still be stale — and correcting
+        // those must cost the user nothing, so the platform is touched
+        // only when the fingerprint actually moved.
+        if (previous.labelFingerprint === fingerprint) {
+          unchanged.push(tone.id);
+          continue;
+        }
+        const outcome = await deps.engine.declareTone(resolved);
+        if (outcome === 'created') {
+          // The channel was gone — deleted by the user, or lost with the
+          // app's data — so this is a first declaration rather than a
+          // refresh, whatever our ledger believed.
+          created.push(resolved.android.channelId);
+        } else if (outcome === 'labelsRefreshed') {
+          labelsRefreshed.push(tone.id);
+          emit(DIAGNOSTIC_CODES.TONE_LABELS_REFRESHED, `Tone "${tone.id}" had its name and description updated in place. No channel was recreated, so every setting the user adjusted on it is untouched.`, {
+            toneId: tone.id
+          });
+        } else {
+          unchanged.push(tone.id);
+        }
+        recordApplied(deps.state, tone, now, undefined, fingerprint);
+        continue;
+      }
+      const outcome = await deps.engine.declareTone(resolved);
+      if (outcome === 'created') {
+        created.push(resolved.android.channelId);
+      }
+      if (previous === undefined) {
+        recordApplied(deps.state, tone, now, undefined, fingerprint);
+        continue;
+      }
+
+      // A version moved, so this is a migration rather than a first
+      // declaration. Re-home before retiring: the reverse order would leave
+      // live notifications attached to a channel that no longer exists.
+      emit(DIAGNOSTIC_CODES.CHANNEL_MIGRATION_REQUIRED, `Tone "${tone.id}" moved from version ${previous.appliedVersion} to ${tone.version}. Android channels are immutable, so a new channel was created and the old one is being retired.`, {
+        toneId: tone.id,
+        from: previous.appliedVersion,
+        to: tone.version
+      });
+      const pending = await deps.engine.getPending();
+      const affected = pending.filter(entry => entry.tone === tone.id);
+      for (const entry of affected) {
+        await writer.write({
+          request: {
+            id: entry.id,
+            content: entry.content,
+            tone: entry.tone,
+            moment: {
+              at: entry.resolvedAt,
+              anchoring: entry.anchoring
+            },
+            routing: entry.routing,
+            actions: entry.actions,
+            ownerTag: entry.ownerTag,
+            groupTag: entry.groupTag
+          },
+          resolvedAt: entry.resolvedAt,
+          tone: resolved,
+          // Re-homing changes the channel, not the anchoring — preserve it.
+          anchoringGeneration: entry.anchoringGeneration,
+          approximate: entry.mayBeDelayed,
+          seriesId: entry.seriesId,
+          pushCreated: entry.pushCreated
+        });
+        reHomed.push(entry.id);
+      }
+      const didRetire = await deps.engine.retireTone(previous.channelId);
+      if (didRetire) {
+        retired.push(previous.channelId);
+      }
+
+      // A version move outranks a label change: the new channel simply
+      // carries the new labels, and reporting it as a refresh would hide a
+      // migration the consumer needs to know about.
+      migrated.push({
+        toneId: tone.id,
+        from: previous.appliedVersion,
+        to: tone.version
+      });
+      recordApplied(deps.state, tone, now, previous.channelId, fingerprint);
+    }
+
+    // Anything left on a retired channel would be an orphan — a notification
+    // the user can no longer control from system settings.
+    const orphans = await findOrphans(deps, tones);
+    if (orphans.length > 0) {
+      await deps.engine.cancelMany(orphans);
+      cancelled.push(...orphans);
+      emit(DIAGNOSTIC_CODES.CHANNEL_ORPHANS_FOUND, `${orphans.length} notification(s) remained on a retired channel and were cancelled, rather than left uncontrollable from system settings.`, {
+        count: orphans.length
+      });
+    }
+    return {
+      created,
+      migrated,
+      labelsRefreshed,
+      retired,
+      reHomed,
+      cancelled,
+      bypassUnavailable,
+      repeatUnavailable,
+      unchanged
+    };
+  };
+  return {
+    /**
+     * Applies a tone configuration, migrating any tone whose version moved.
+     *
+     * Applying an unchanged configuration performs no work at all: no channel
+     * is recreated and no migration is triggered.
+     */
+    apply(tones, groups = []) {
+      // The declared channels are read once for the whole apply rather than once
+      // per tone, when the engine can hold them (NOT-08).
+      const run = () => applyTones(tones, groups);
+      return deps.engine.withChannelSnapshot ? deps.engine.withChannelSnapshot(run) : run();
+    },
+    /** Which version of each tone this device actually holds. */
+    appliedVersions() {
+      return deps.state.read().migrationLedger.filter(entry => !entry.retired).map(entry => ({
+        toneId: entry.toneId,
+        appliedVersion: entry.appliedVersion
+      }));
+    }
+  };
+}
+
+/** Notifications whose tone is no longer declared at all. */
+async function findOrphans(deps, tones) {
+  const declared = new Set(tones.map(tone => tone.id));
+  // Only tones this package once applied can leave orphans (NOT-05). An entry
+  // with no tone metadata was scheduled by other code through the same engine,
+  // and a tone the ledger has never seen is not ours to judge either: cancelling
+  // on "not in this call's list" silently deleted other libraries' notifications,
+  // and a feature module's own when it applied only its subset of tones.
+  const onceApplied = new Set(deps.state.read().migrationLedger.map(entry => entry.toneId));
+  const pending = await deps.engine.getPending();
+  return pending.filter(entry => entry.tone !== '' && onceApplied.has(entry.tone) && !declared.has(entry.tone)).map(entry => entry.id);
+}
+//# sourceMappingURL=migrate.js.map

package/lib/module/channel/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DIAGNOSTIC_CODES","channelIdFor","resolveTone","toneLabelFingerprint","validateToneDeclarations","createScheduleWriter","ledgerFor","state","toneId","read","migrationLedger","find","entry","retired","recordApplied","tone","now","retiredChannelId","labelFingerprint","update","current","withoutTone","filter","id","undefined","at","appliedVersion","channelId","version","createChannels","deps","emit","writer","engine","applyTones","tones","groups","created","migrated","labelsRefreshed","reHomed","cancelled","bypassUnavailable","repeatUnavailable","unchanged","length","declareGroups","capabilities","getCapabilities","previous","resolved","fingerprint","bypassDoNotDisturb","supportsDoNotDisturbBypass","push","DND_BYPASS_UNAVAILABLE","repeatAlert","supportsRepeatingAlert","REPEAT_ALERT_UNAVAILABLE","hasBackgroundDeliveryHandler","REPEAT_STOP_HANDLER_MISSING","versionMoved","outcome","declareTone","android","TONE_LABELS_REFRESHED","CHANNEL_MIGRATION_REQUIRED","from","to","pending","getPending","affected","write","request","content","moment","resolvedAt","anchoring","routing","actions","ownerTag","groupTag","anchoringGeneration","approximate","mayBeDelayed","seriesId","pushCreated","didRetire","retireTone","orphans","findOrphans","cancelMany","CHANNEL_ORPHANS_FOUND","count","apply","run","withChannelSnapshot","appliedVersions","map","declared","Set","onceApplied","has"],"sourceRoot":"../../../src","sources":["channel/migrate.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/channel/tone-map.js

@@ -0,0 +1,112 @@
+"use strict";
+
+/**
+ * Tone-to-platform mapping.
+ *
+ * A tone is declared once and realized on each platform here, so consumer code
+ * contains zero platform branches. The two platforms model urgency differently
+ * — Android by channel importance, iOS by interruption level — and reconciling
+ * that difference is exactly the work this package exists to absorb.
+ *
+ * The channel id carries the tone version. Android channels are immutable once
+ * created and re-declaration is silently ignored, so a configuration change has
+ * to produce a *new* channel or it will never reach a device that already holds
+ * the old one.
+ */
+
+import { fnv1a, hex8 } from "../contract/hash.js";
+const ANDROID_IMPORTANCE = {
+  min: 'min',
+  low: 'low',
+  default: 'default',
+  high: 'high',
+  // Android has no level above `high`; max urgency is expressed by the DND
+  // bypass rather than by a distinct importance.
+  max: 'high'
+};
+const IOS_INTERRUPTION = {
+  min: 'passive',
+  low: 'passive',
+  default: 'active',
+  high: 'active',
+  // `timeSensitive` is the highest level available without the Critical Alerts
+  // entitlement, which is out of scope for v1.
+  max: 'timeSensitive'
+};
+
+/** Channel id for a tone at a given version. Stable, derived, never random. */
+export function channelIdFor(toneId, version) {
+  return `${toneId}.v${version}`;
+}
+
+/** Extracts the tone and version encoded in a channel id, if it is one of ours. */
+export function parseChannelId(channelId) {
+  const separator = channelId.lastIndexOf('.v');
+  if (separator === -1) return undefined;
+  const version = Number.parseInt(channelId.slice(separator + 2), 10);
+  if (!Number.isInteger(version) || version < 1) return undefined;
+  return {
+    toneId: channelId.slice(0, separator),
+    version
+  };
+}
+export function resolveTone(tone) {
+  const silent = tone.sound?.enabled === false;
+  const repeats = tone.repeatAlert !== undefined;
+  return {
+    toneId: tone.id,
+    version: tone.version,
+    android: {
+      channelId: channelIdFor(tone.id, tone.version),
+      // The declared label, not the identifier. Passing the identifier here
+      // is what put a technical string on the one screen these exist for.
+      name: tone.name,
+      description: tone.description,
+      importance: ANDROID_IMPORTANCE[tone.urgency],
+      sound: silent ? undefined : tone.sound?.name,
+      vibration: tone.vibration ?? false,
+      badge: tone.badge ?? false,
+      bypassDnd: tone.bypassDoNotDisturb ?? false,
+      groupId: tone.groupId,
+      // Both are per-notification rather than channel configuration, which
+      // is precisely why neither obliges a consumer to bump `version`.
+      loopSound: repeats,
+      alarmCategory: tone.timeSensitive ?? false,
+      repeatForMs: tone.repeatAlert?.forMs
+    },
+    ios: {
+      // iOS categories are not versioned: they carry actions rather than
+      // user-adjustable settings, so re-declaring one is harmless.
+      categoryId: tone.id,
+      interruptionLevel: tone.timeSensitive === true ? 'timeSensitive' : IOS_INTERRUPTION[tone.urgency],
+      sound: silent ? undefined : tone.sound?.name,
+      badge: tone.badge ?? false,
+      // iOS exposes no looping-sound API at all. Recorded as data so the
+      // refusal can be reported rather than discovered.
+      repeatRefused: repeats
+    }
+  };
+}
+
+/**
+ * A stable fingerprint of a tone's user-visible labels.
+ *
+ * Lets an unchanged configuration skip the platform entirely, which is what
+ * keeps "re-applying changes nothing" literally true rather than merely
+ * approximately true. A hash rather than the labels themselves, so persisted
+ * state continues to hold no consumer-supplied text.
+ */
+export function toneLabelFingerprint(tone) {
+  // The separator matters: without it, a name of "ab" with description "c" and
+  // a name of "a" with description "bc" would fingerprint identically, and one
+  // of the two would never get its correction.
+  const source = `${tone.name}\u0000${tone.description ?? ''}`;
+  return hex8(fnv1a(source));
+}
+
+/** Builds a lookup over a declared configuration. */
+export function createToneResolver(tones) {
+  const resolved = new Map(tones.map(tone => [tone.id, resolveTone(tone)]));
+  return toneId => resolved.get(toneId);
+}
+//# sourceMappingURL=tone-map.js.map

package/lib/module/channel/tone-map.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["fnv1a","hex8","ANDROID_IMPORTANCE","min","low","default","high","max","IOS_INTERRUPTION","channelIdFor","toneId","version","parseChannelId","channelId","separator","lastIndexOf","undefined","Number","parseInt","slice","isInteger","resolveTone","tone","silent","sound","enabled","repeats","repeatAlert","id","android","name","description","importance","urgency","vibration","badge","bypassDnd","bypassDoNotDisturb","groupId","loopSound","alarmCategory","timeSensitive","repeatForMs","forMs","ios","categoryId","interruptionLevel","repeatRefused","toneLabelFingerprint","source","createToneResolver","tones","resolved","Map","map","get"],"sourceRoot":"../../../src","sources":["channel/tone-map.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/channel/validate-tone.js

@@ -0,0 +1,57 @@
+"use strict";
+
+/**
+ * Tone declaration validation.
+ *
+ * Runs before the first engine call, like every other validation in this
+ * package: a rejected declaration must leave the device exactly as it was.
+ *
+ * Only the new alert attributes are checked here. The rest of a tone has always
+ * been validated by the platform's own charset and shape rules, and duplicating
+ * those would create two sources of truth for the same constraint.
+ */
+
+import { REPEAT_ALERT_BOUNDS } from "../contract/channel.js";
+import { DIAGNOSTIC_CODES, NotificationError } from "../contract/errors.js";
+
+/**
+ * Throws when a tone's repeating alert is unusable.
+ *
+ * The type already forbids a repeat without a duration. What it cannot forbid
+ * is a duration of zero, a fractional millisecond, or an hour and a half — and
+ * an alert that repeats for an unchecked span is the failure this whole feature
+ * exists to prevent.
+ */
+export function validateToneDeclaration(tone) {
+  const repeat = tone.repeatAlert;
+  if (repeat === undefined) return;
+  if (!Number.isInteger(repeat.forMs)) {
+    throw new NotificationError(DIAGNOSTIC_CODES.INVALID_TONE_REPEAT, `Tone "${tone.id}" declared a repeating alert whose duration is not a whole number of milliseconds.`, {
+      toneId: tone.id,
+      forMs: repeat.forMs
+    });
+  }
+  if (repeat.forMs < REPEAT_ALERT_BOUNDS.minMs || repeat.forMs > REPEAT_ALERT_BOUNDS.maxMs) {
+    throw new NotificationError(DIAGNOSTIC_CODES.INVALID_TONE_REPEAT, `Tone "${tone.id}" declared a repeating alert of ${repeat.forMs}ms, outside the permitted ${REPEAT_ALERT_BOUNDS.minMs}–${REPEAT_ALERT_BOUNDS.maxMs}ms range. A shorter repeat is indistinguishable from a single chime; a longer one outlasts anyone's willingness to respond.`, {
+      toneId: tone.id,
+      forMs: repeat.forMs,
+      ...REPEAT_ALERT_BOUNDS
+    });
+  }
+  if (tone.sound?.enabled === false) {
+    // Two instructions that cannot both be honoured. Picking one silently
+    // would ship whichever the reader did not expect, and the consumer would
+    // discover it on a device rather than here.
+    throw new NotificationError(DIAGNOSTIC_CODES.INVALID_TONE_REPEAT, `Tone "${tone.id}" declares both a repeating alert and a silent sound. Repeating silence is not a behaviour; drop one of the two.`, {
+      toneId: tone.id
+    });
+  }
+}
+
+/** Validates a whole configuration before any of it is applied. */
+export function validateToneDeclarations(tones) {
+  for (const tone of tones) {
+    validateToneDeclaration(tone);
+  }
+}
+//# sourceMappingURL=validate-tone.js.map

package/lib/module/channel/validate-tone.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["REPEAT_ALERT_BOUNDS","DIAGNOSTIC_CODES","NotificationError","validateToneDeclaration","tone","repeat","repeatAlert","undefined","Number","isInteger","forMs","INVALID_TONE_REPEAT","id","toneId","minMs","maxMs","sound","enabled","validateToneDeclarations","tones"],"sourceRoot":"../../../src","sources":["channel/validate-tone.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA,SAASA,mBAAmB,QAAQ,wBAAqB;AACzD,SAASC,gBAAgB,EAAEC,iBAAiB,QAAQ,uBAAoB;;AAExE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,uBAAuBA,CAACC,IAAqB,EAAQ;EACpE,MAAMC,MAAM,GAAGD,IAAI,CAACE,WAAW;EAC/B,IAAID,MAAM,KAAKE,SAAS,EAAE;EAE1B,IAAI,CAACC,MAAM,CAACC,SAAS,CAACJ,MAAM,CAACK,KAAK,CAAC,EAAE;IACpC,MAAM,IAAIR,iBAAiB,CAC1BD,gBAAgB,CAACU,mBAAmB,EACpC,SAASP,IAAI,CAACQ,EAAE,oFAAoF,EACpG;MAAEC,MAAM,EAAET,IAAI,CAACQ,EAAE;MAAEF,KAAK,EAAEL,MAAM,CAACK;IAAM,CACxC,CAAC;EACF;EAEA,IAAIL,MAAM,CAACK,KAAK,GAAGV,mBAAmB,CAACc,KAAK,IAAIT,MAAM,CAACK,KAAK,GAAGV,mBAAmB,CAACe,KAAK,EAAE;IACzF,MAAM,IAAIb,iBAAiB,CAC1BD,gBAAgB,CAACU,mBAAmB,EACpC,SAASP,IAAI,CAACQ,EAAE,mCAAmCP,MAAM,CAACK,KAAK,6BAA6BV,mBAAmB,CAACc,KAAK,IAAId,mBAAmB,CAACe,KAAK,6HAA6H,EAC/Q;MAAEF,MAAM,EAAET,IAAI,CAACQ,EAAE;MAAEF,KAAK,EAAEL,MAAM,CAACK,KAAK;MAAE,GAAGV;IAAoB,CAChE,CAAC;EACF;EAEA,IAAII,IAAI,CAACY,KAAK,EAAEC,OAAO,KAAK,KAAK,EAAE;IAClC;IACA;IACA;IACA,MAAM,IAAIf,iBAAiB,CAC1BD,gBAAgB,CAACU,mBAAmB,EACpC,SAASP,IAAI,CAACQ,EAAE,kHAAkH,EAClI;MAAEC,MAAM,EAAET,IAAI,CAACQ;IAAG,CACnB,CAAC;EACF;AACD;;AAEA;AACA,OAAO,SAASM,wBAAwBA,CAACC,KAAiC,EAAQ;EACjF,KAAK,MAAMf,IAAI,IAAIe,KAAK,EAAE;IACzBhB,uBAAuB,CAACC,IAAI,CAAC;EAC9B;AACD","ignoreList":[]}

package/lib/module/contract/channel.js

@@ -0,0 +1,48 @@
+"use strict";
+
+/**
+ * Channel, category, and tone declaration types.
+ *
+ * A tone is declared once and mapped by the package to each platform's
+ * equivalent concepts, so consumer code contains no platform branches.
+ *
+ * Two tones must never be merged into one: channel configuration belongs to
+ * the user, and collapsing two tones collapses two independent user choices.
+ */
+
+/** How insistently a notification asks for attention. */
+
+/**
+ * A repeating alert and the bound on how long it may repeat.
+ *
+ * The two are one object rather than two fields because an unbounded repeating
+ * alert must be *unrepresentable*, not merely discouraged. A boolean `repeat`
+ * beside an optional duration would make the dangerous state the easiest one to
+ * write, and the dangerous state here is a phone that keeps sounding until its
+ * owner comes home to it.
+ */
+
+/**
+ * The declarable range for a repeating alert.
+ *
+ * The floor exists because a repeat shorter than a minute is indistinguishable
+ * from a single chime and buys nothing for the complexity it costs. The ceiling
+ * exists because an hour is already past the point where a person who has not
+ * responded is going to.
+ */
+export const REPEAT_ALERT_BOUNDS = {
+  minMs: 60_000,
+  maxMs: 3_600_000
+};
+
+/** What a tone resolves to on each platform. Internal to the engine adapter. */
+
+/**
+ * Outcome of applying a channel configuration, including any migration performed.
+ *
+ * A tone appears in exactly one of `created`, `migrated`, `labelsRefreshed`, and
+ * `unchanged`. The `*Unavailable` arrays are orthogonal and may accompany any of
+ * them: a platform refusing an attribute says nothing about whether the tone was
+ * newly created.
+ */
+//# sourceMappingURL=channel.js.map

package/lib/module/contract/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["REPEAT_ALERT_BOUNDS","minMs","maxMs"],"sourceRoot":"../../../src","sources":["contract/channel.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;;AAUA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAWA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMA,mBAAmB,GAAG;EAClCC,KAAK,EAAE,MAAM;EACbC,KAAK,EAAE;AACR,CAAU;;AA6DV;;AAgDA;AACA;AACA;AACA;AACA;AACA;AACA;AACA","ignoreList":[]}

package/lib/module/contract/diagnostics.js

@@ -0,0 +1,21 @@
+"use strict";
+
+/**
+ * Diagnostics and configuration types.
+ *
+ * The package's stated purpose is to make invisible notification failures
+ * diagnosable, so every lifecycle transition emits a structured event with a
+ * stable identifier — and none of those events carries content by default.
+ */
+
+/** Health of one persisted collection against its cap. */
+
+/** The readable answer to "why didn't it arrive". */
+
+/** Abnormal notification volume. Reported, never acted upon. */
+
+export const DEFAULT_BURST_THRESHOLD = {
+  perMinute: 10,
+  perHour: 60
+};
+//# sourceMappingURL=diagnostics.js.map

package/lib/module/contract/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DEFAULT_BURST_THRESHOLD","perMinute","perHour"],"sourceRoot":"../../../src","sources":["contract/diagnostics.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;;AAyBA;;AAgBA;;AAgBA;;AAMA,OAAO,MAAMA,uBAAuC,GAAG;EACtDC,SAAS,EAAE,EAAE;EACbC,OAAO,EAAE;AACV,CAAC","ignoreList":[]}

package/lib/module/contract/errors.js

@@ -0,0 +1,119 @@
+"use strict";
+
+/**
+ * Typed error taxonomy and stable diagnostic identifiers.
+ *
+ * Every failure condition carries its own identifier. None collapses into a
+ * generic failure — an error that says only "scheduling failed" reproduces the
+ * problem this package exists to solve.
+ *
+ * Identifiers are stable across releases and safe to switch on. Adding new ones
+ * is an additive minor change.
+ *
+ * See `specs/009-rn-notification-package/contracts/errors.md`.
+ */
+
+import { SdkError } from '@chipmobilesdk/rn-core';
+import { redactContext } from "../diagnostics/redact.js";
+export const DIAGNOSTIC_CODES = {
+  // --- Validation: raised before any platform call -------------------------
+  INVALID_ID_EMPTY: 'INVALID_ID_EMPTY',
+  INVALID_ID_LENGTH: 'INVALID_ID_LENGTH',
+  INVALID_ID_CHARSET: 'INVALID_ID_CHARSET',
+  INVALID_OWNER_TAG: 'INVALID_OWNER_TAG',
+  INVALID_GROUP_TAG: 'INVALID_GROUP_TAG',
+  MOMENT_IN_PAST: 'MOMENT_IN_PAST',
+  UNDECLARED_TONE: 'UNDECLARED_TONE',
+  ROUTING_PAYLOAD_TOO_LARGE: 'ROUTING_PAYLOAD_TOO_LARGE',
+  CONTENT_TOO_LARGE: 'CONTENT_TOO_LARGE',
+  TOO_MANY_ACTIONS: 'TOO_MANY_ACTIONS',
+  INVALID_RECURRENCE: 'INVALID_RECURRENCE',
+  INVALID_TONE_REPEAT: 'INVALID_TONE_REPEAT',
+  // --- Reconciliation ------------------------------------------------------
+  DUPLICATE_IDENTIFIER: 'DUPLICATE_IDENTIFIER',
+  TRUNCATED_OVER_CEILING: 'TRUNCATED_OVER_CEILING',
+  RECONCILE_INTERRUPTED: 'RECONCILE_INTERRUPTED',
+  PENDING_SET_DISCREPANCY: 'PENDING_SET_DISCREPANCY',
+  // --- Permissions ---------------------------------------------------------
+  DISPLAY_PERMISSION_DENIED: 'DISPLAY_PERMISSION_DENIED',
+  DISPLAY_PERMISSION_PERMANENT: 'DISPLAY_PERMISSION_PERMANENT',
+  EXACT_ALARM_UNAVAILABLE: 'EXACT_ALARM_UNAVAILABLE',
+  SETTINGS_UNAVAILABLE: 'SETTINGS_UNAVAILABLE',
+  BACKGROUND_RESTRICTED: 'BACKGROUND_RESTRICTED',
+  BACKGROUND_RESTRICTION_UNKNOWN: 'BACKGROUND_RESTRICTION_UNKNOWN',
+  // --- Channels ------------------------------------------------------------
+  CHANNEL_MIGRATION_REQUIRED: 'CHANNEL_MIGRATION_REQUIRED',
+  CHANNEL_MIGRATION_FAILED: 'CHANNEL_MIGRATION_FAILED',
+  CHANNEL_ORPHANS_FOUND: 'CHANNEL_ORPHANS_FOUND',
+  DND_BYPASS_UNAVAILABLE: 'DND_BYPASS_UNAVAILABLE',
+  TONE_LABELS_REFRESHED: 'TONE_LABELS_REFRESHED',
+  REPEAT_ALERT_UNAVAILABLE: 'REPEAT_ALERT_UNAVAILABLE',
+  REPEAT_STOP_HANDLER_MISSING: 'REPEAT_STOP_HANDLER_MISSING',
+  // --- Interaction ---------------------------------------------------------
+  TARGET_MISSING: 'TARGET_MISSING',
+  INTERACTION_BUFFER_EVICTED: 'INTERACTION_BUFFER_EVICTED',
+  BACKGROUND_WINDOW_EXCEEDED: 'BACKGROUND_WINDOW_EXCEEDED',
+  // --- Push ----------------------------------------------------------------
+  PUSH_UNAVAILABLE: 'PUSH_UNAVAILABLE',
+  TOKEN_UNAVAILABLE: 'TOKEN_UNAVAILABLE',
+  TOKEN_INVALIDATION_FAILED: 'TOKEN_INVALIDATION_FAILED',
+  PAYLOAD_MALFORMED: 'PAYLOAD_MALFORMED',
+  PAYLOAD_VERSION_SKEW: 'PAYLOAD_VERSION_SKEW',
+  PAYLOAD_DUPLICATE: 'PAYLOAD_DUPLICATE',
+  PUSH_UNDELIVERABLE: 'PUSH_UNDELIVERABLE',
+  // --- Persisted state -----------------------------------------------------
+  STATE_CORRUPT_REBUILT: 'STATE_CORRUPT_REBUILT',
+  STATE_WRITE_FAILED: 'STATE_WRITE_FAILED',
+  /** The durable store could not open; state lasts for this session only. */
+  STATE_STORE_DEGRADED: 'STATE_STORE_DEGRADED',
+  STATE_CAP_EVICTED: 'STATE_CAP_EVICTED',
+  /**
+   * A ledger holds more live entries than its cap (0.6.0). They are all kept:
+   * dropping a live series or channel record would lose a migration or reset a
+   * series count. Reported so the cap can be raised or the app's use reviewed.
+   */
+  STATE_CAP_EXCEEDED: 'STATE_CAP_EXCEEDED',
+  // --- Volume --------------------------------------------------------------
+  BURST_THRESHOLD_EXCEEDED: 'BURST_THRESHOLD_EXCEEDED',
+  // --- Maintenance (0.4.0) -------------------------------------------------
+  /** An automatic maintenance cycle threw. Reported here because no caller awaits it. */
+  MAINTENANCE_FAILED: 'MAINTENANCE_FAILED'
+};
+/** Every identifier, for exhaustiveness tests and the documentation table. */
+export const ALL_DIAGNOSTIC_CODES = Object.freeze(Object.values(DIAGNOSTIC_CODES));
+
+/**
+ * A typed package failure.
+ *
+ * Carries enough context to choose a recovery, and never carries notification
+ * body text, routing payload values, or token material. Where a value violated
+ * a rule, the *shape* of the violation is reported — a length, a character
+ * position — rather than the value itself.
+ */
+export class NotificationError extends SdkError {
+  constructor(code, message, context) {
+    super('rn-notification', code, {
+      message
+    });
+    this.name = 'NotificationError';
+    // Redacted on the way in: an error object reaches crash reporters, which
+    // never run with verbose diagnostics.
+    const redacted = redactContext(context, false);
+    if (redacted !== undefined) {
+      this.context = redacted;
+    }
+  }
+}
+export function isNotificationError(value) {
+  return value instanceof NotificationError;
+}
+
+/**
+ * Conditions that are reported outcomes rather than failures: the operation
+ * succeeded, and something the caller needs to know happened alongside it.
+ */
+export const NON_FAILURE_CODES = Object.freeze([DIAGNOSTIC_CODES.TRUNCATED_OVER_CEILING, DIAGNOSTIC_CODES.PENDING_SET_DISCREPANCY, DIAGNOSTIC_CODES.EXACT_ALARM_UNAVAILABLE, DIAGNOSTIC_CODES.TARGET_MISSING, DIAGNOSTIC_CODES.BURST_THRESHOLD_EXCEEDED, DIAGNOSTIC_CODES.PAYLOAD_VERSION_SKEW, DIAGNOSTIC_CODES.PAYLOAD_DUPLICATE, DIAGNOSTIC_CODES.STATE_CAP_EVICTED, DIAGNOSTIC_CODES.STATE_CAP_EXCEEDED, DIAGNOSTIC_CODES.STATE_CORRUPT_REBUILT, DIAGNOSTIC_CODES.BACKGROUND_RESTRICTION_UNKNOWN, DIAGNOSTIC_CODES.DND_BYPASS_UNAVAILABLE, DIAGNOSTIC_CODES.TONE_LABELS_REFRESHED, DIAGNOSTIC_CODES.REPEAT_ALERT_UNAVAILABLE, DIAGNOSTIC_CODES.REPEAT_STOP_HANDLER_MISSING]);
+export function isNonFailure(code) {
+  return NON_FAILURE_CODES.includes(code);
+}
+//# sourceMappingURL=errors.js.map

package/lib/module/contract/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["SdkError","redactContext","DIAGNOSTIC_CODES","INVALID_ID_EMPTY","INVALID_ID_LENGTH","INVALID_ID_CHARSET","INVALID_OWNER_TAG","INVALID_GROUP_TAG","MOMENT_IN_PAST","UNDECLARED_TONE","ROUTING_PAYLOAD_TOO_LARGE","CONTENT_TOO_LARGE","TOO_MANY_ACTIONS","INVALID_RECURRENCE","INVALID_TONE_REPEAT","DUPLICATE_IDENTIFIER","TRUNCATED_OVER_CEILING","RECONCILE_INTERRUPTED","PENDING_SET_DISCREPANCY","DISPLAY_PERMISSION_DENIED","DISPLAY_PERMISSION_PERMANENT","EXACT_ALARM_UNAVAILABLE","SETTINGS_UNAVAILABLE","BACKGROUND_RESTRICTED","BACKGROUND_RESTRICTION_UNKNOWN","CHANNEL_MIGRATION_REQUIRED","CHANNEL_MIGRATION_FAILED","CHANNEL_ORPHANS_FOUND","DND_BYPASS_UNAVAILABLE","TONE_LABELS_REFRESHED","REPEAT_ALERT_UNAVAILABLE","REPEAT_STOP_HANDLER_MISSING","TARGET_MISSING","INTERACTION_BUFFER_EVICTED","BACKGROUND_WINDOW_EXCEEDED","PUSH_UNAVAILABLE","TOKEN_UNAVAILABLE","TOKEN_INVALIDATION_FAILED","PAYLOAD_MALFORMED","PAYLOAD_VERSION_SKEW","PAYLOAD_DUPLICATE","PUSH_UNDELIVERABLE","STATE_CORRUPT_REBUILT","STATE_WRITE_FAILED","STATE_STORE_DEGRADED","STATE_CAP_EVICTED","STATE_CAP_EXCEEDED","BURST_THRESHOLD_EXCEEDED","MAINTENANCE_FAILED","ALL_DIAGNOSTIC_CODES","Object","freeze","values","NotificationError","constructor","code","message","context","name","redacted","undefined","isNotificationError","value","NON_FAILURE_CODES","isNonFailure","includes"],"sourceRoot":"../../../src","sources":["contract/errors.ts"],"mappings":"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","ignoreList":[]}