@chipmobilesdk/rn-notification 0.5.0 → 0.7.0

package/lib/module/recurrence/expand.js

@@ -0,0 +1,248 @@
+"use strict";
+
+/**
+ * Recurrence expansion.
+ *
+ * Written first-party rather than delegated to an RFC 5545 library, because the
+ * daylight-saving rules here are specified behaviour (FR-008) rather than a
+ * dependency's opinion, and because expansion must be provable with no device.
+ *
+ * Determinism is the hard requirement: the same rule, anchoring mode, zone, and
+ * evaluation moment must produce exactly the same occurrences in the same order
+ * on every run and on both platforms. Without that, reconciliation could not be
+ * idempotent over a recurring series.
+ */
+
+import { DIAGNOSTIC_CODES, NotificationError } from "../contract/errors.js";
+import { instantForParts, partsInZone } from "../schedule/anchor.js";
+const pad = (value, width) => String(value).padStart(width, '0');
+
+/**
+ * The calendar slot of an occurrence: the date and clock time the rule asked
+ * for, in the frame the series is anchored in. Fixed-width, so comparing two
+ * keys as strings compares them in time.
+ */
+export function occurrenceKey(parts) {
+  return `${pad(parts.year, 4)}${pad(parts.month, 2)}${pad(parts.day, 2)}T${pad(parts.hour, 2)}${pad(parts.minute, 2)}`;
+}
+
+/**
+ * Occurrence identity.
+ *
+ * Derived from the series and the calendar slot, not the instant. Re-expanding
+ * the same series produces the same identifiers, which is what lets a refresh
+ * recognize an occurrence it already scheduled. Until 0.4.0 the instant was
+ * used, so after a time-zone change re-anchoring kept the old identifier while
+ * the window refresh derived a new one, and the occurrence was scheduled twice.
+ */
+export function occurrenceId(seriesId, slot) {
+  return `${seriesId}#${typeof slot === 'string' ? slot : occurrenceKey(slot)}`;
+}
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+function validatePattern(pattern) {
+  const {
+    hour,
+    minute
+  } = pattern;
+  if (!Number.isInteger(hour) || hour < 0 || hour > 23) {
+    throw new NotificationError(DIAGNOSTIC_CODES.INVALID_RECURRENCE, 'Recurrence hour must be an integer from 0 to 23.', {
+      hour
+    });
+  }
+  if (!Number.isInteger(minute) || minute < 0 || minute > 59) {
+    throw new NotificationError(DIAGNOSTIC_CODES.INVALID_RECURRENCE, 'Recurrence minute must be an integer from 0 to 59.', {
+      minute
+    });
+  }
+  const interval = pattern.interval ?? 1;
+  if (!Number.isInteger(interval) || interval < 1) {
+    throw new NotificationError(DIAGNOSTIC_CODES.INVALID_RECURRENCE, 'Recurrence interval must be a positive integer.', {
+      interval
+    });
+  }
+  if (pattern.kind === 'weekly') {
+    if (pattern.weekdays.length === 0) {
+      throw new NotificationError(DIAGNOSTIC_CODES.INVALID_RECURRENCE, 'A weekly recurrence must name at least one weekday.');
+    }
+    for (const day of pattern.weekdays) {
+      if (!Number.isInteger(day) || day < 0 || day > 6) {
+        throw new NotificationError(DIAGNOSTIC_CODES.INVALID_RECURRENCE, 'Weekdays must be integers from 0 (Sunday) to 6 (Saturday).', {
+          day
+        });
+      }
+    }
+  }
+  if (pattern.kind === 'monthlyByDay') {
+    if (!Number.isInteger(pattern.dayOfMonth) || pattern.dayOfMonth < 1 || pattern.dayOfMonth > 31) {
+      throw new NotificationError(DIAGNOSTIC_CODES.INVALID_RECURRENCE, 'Day of month must be an integer from 1 to 31.', {
+        dayOfMonth: pattern.dayOfMonth
+      });
+    }
+  }
+}
+
+/** Calendar date in the anchoring zone, carrying the pattern's clock time. */
+function partsFor(date, pattern) {
+  return {
+    year: date.year,
+    month: date.month,
+    day: date.day,
+    hour: pattern.hour,
+    minute: pattern.minute,
+    second: 0
+  };
+}
+function addDays(parts, days) {
+  const shifted = new Date(Date.UTC(parts.year, parts.month - 1, parts.day) + days * MS_PER_DAY);
+  return {
+    year: shifted.getUTCFullYear(),
+    month: shifted.getUTCMonth() + 1,
+    day: shifted.getUTCDate(),
+    hour: parts.hour,
+    minute: parts.minute,
+    second: 0
+  };
+}
+function weekdayOf(parts) {
+  return new Date(Date.UTC(parts.year, parts.month - 1, parts.day)).getUTCDay();
+}
+function daysInMonth(year, month) {
+  return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+/**
+ * Expands a rule inside the lookahead window.
+ *
+ * Bounded by both a duration and a count, because either alone fails: a
+ * duration alone lets a frequent series exhaust the platform ceiling, and a
+ * count alone leaves an annual series scheduled a decade out.
+ */
+export function expand(input) {
+  const {
+    rule,
+    from,
+    lookahead,
+    timeZone
+  } = input;
+  validatePattern(rule.pattern);
+  const anchoring = rule.anchoring ?? 'wallClock';
+  const horizon = from + lookahead.days * MS_PER_DAY;
+  const start = Math.max(rule.startAt ?? from, from);
+  const {
+    lastEmittedKey
+  } = input;
+  const occurrences = [];
+  let cursor = partsFor(partsInZone(start, timeZone), rule.pattern);
+  // Position of the next not-yet-counted occurrence, for count-limited rules.
+  let index = input.alreadyEmitted ?? 0;
+  let exhausted = false;
+
+  // Bounded independently of the emit conditions so a pattern that matches
+  // nothing (e.g. day 31 in February) can never spin forever.
+  const maxIterations = lookahead.days * 2 + 400;
+  for (let iteration = 0; iteration < maxIterations; iteration += 1) {
+    if (occurrences.length >= lookahead.occurrencesPerSeries) break;
+    const candidate = nextCandidate(cursor, rule.pattern, iteration === 0);
+    if (candidate === undefined) break;
+    cursor = candidate;
+    const at = anchoring === 'absolute' ? Date.UTC(cursor.year, cursor.month - 1, cursor.day, cursor.hour, cursor.minute, 0) : instantForParts(cursor, timeZone);
+    if (at > horizon) break;
+    if (at > start) {
+      if (rule.end.kind === 'untilDate' && at > rule.end.until) {
+        exhausted = true;
+        break;
+      }
+      const key = occurrenceKey(cursor);
+      const previouslyEmitted = lastEmittedKey !== undefined && key <= lastEmittedKey;
+      if (!previouslyEmitted && rule.end.kind === 'count' && index >= rule.end.count) {
+        exhausted = true;
+        break;
+      }
+      occurrences.push({
+        id: occurrenceId(rule.id, key),
+        key,
+        seriesId: rule.id,
+        at,
+        anchoring,
+        previouslyEmitted
+      });
+      if (!previouslyEmitted) index += 1;
+    }
+    cursor = advance(cursor, rule.pattern);
+  }
+  return {
+    occurrences,
+    expandedThrough: horizon,
+    exhausted
+  };
+}
+
+/** Moves the cursor onto the first date the pattern actually matches. */
+function nextCandidate(cursor, pattern, isFirst) {
+  if (pattern.kind === 'daily') return cursor;
+  if (pattern.kind === 'weekly') {
+    const wanted = new Set(pattern.weekdays);
+    let candidate = cursor;
+    for (let step = 0; step < 14; step += 1) {
+      if (wanted.has(weekdayOf(candidate))) return candidate;
+      candidate = addDays(candidate, 1);
+    }
+    return undefined;
+  }
+  const monthly = pattern;
+  let candidate = cursor;
+  // Months shorter than the requested day are skipped rather than clamped: a
+  // caller asking for the 31st means the 31st, and inventing the 28th would be
+  // the package deciding something it was not asked to decide.
+  for (let step = 0; step < 48; step += 1) {
+    if (daysInMonth(candidate.year, candidate.month) >= monthly.dayOfMonth) {
+      const onDay = {
+        ...candidate,
+        day: monthly.dayOfMonth
+      };
+      if (isFirst || onDay.day >= candidate.day || step > 0) return onDay;
+    }
+    candidate = firstOfNextMonth(candidate);
+  }
+  return undefined;
+}
+function firstOfNextMonth(parts) {
+  const month = parts.month === 12 ? 1 : parts.month + 1;
+  const year = parts.month === 12 ? parts.year + 1 : parts.year;
+  return {
+    ...parts,
+    year,
+    month,
+    day: 1
+  };
+}
+
+/** Steps the cursor past the occurrence just produced. */
+function advance(cursor, pattern) {
+  const interval = pattern.interval ?? 1;
+  if (pattern.kind === 'daily') {
+    return addDays(cursor, pattern.interval ?? 1);
+  }
+  if (pattern.kind === 'weekly') {
+    const wanted = [...new Set(pattern.weekdays)].sort((a, b) => a - b);
+    const current = weekdayOf(cursor);
+    const next = wanted.find(day => day > current);
+
+    // Wrapping into a new week is where the interval applies — stepping day by
+    // day within the week would multiply the interval by the weekday count.
+    return next === undefined ? addDays(cursor, 7 * interval - current + wanted[0]) : addDays(cursor, next - current);
+  }
+  const monthly = pattern;
+  let year = cursor.year;
+  let month = cursor.month + interval;
+  while (month > 12) {
+    month -= 12;
+    year += 1;
+  }
+  return {
+    ...cursor,
+    year,
+    month,
+    day: Math.min(monthly.dayOfMonth, daysInMonth(year, month))
+  };
+}
+//# sourceMappingURL=expand.js.map

package/lib/module/recurrence/expand.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DIAGNOSTIC_CODES","NotificationError","instantForParts","partsInZone","pad","value","width","String","padStart","occurrenceKey","parts","year","month","day","hour","minute","occurrenceId","seriesId","slot","MS_PER_DAY","validatePattern","pattern","Number","isInteger","INVALID_RECURRENCE","interval","kind","weekdays","length","dayOfMonth","partsFor","date","second","addDays","days","shifted","Date","UTC","getUTCFullYear","getUTCMonth","getUTCDate","weekdayOf","getUTCDay","daysInMonth","expand","input","rule","from","lookahead","timeZone","anchoring","horizon","start","Math","max","startAt","lastEmittedKey","occurrences","cursor","index","alreadyEmitted","exhausted","maxIterations","iteration","occurrencesPerSeries","candidate","nextCandidate","undefined","at","end","until","key","previouslyEmitted","count","push","id","advance","expandedThrough","isFirst","wanted","Set","step","has","monthly","onDay","firstOfNextMonth","sort","a","b","current","next","find","min"],"sourceRoot":"../../../src","sources":["recurrence/expand.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/recurrence/index.js

@@ -0,0 +1,208 @@
+"use strict";
+
+/**
+ * Series registration and the lookahead window.
+ *
+ * A caller declares a rule once. The package expands it inside a finite window
+ * and refreshes that window on its own, because only it knows when the horizon
+ * has moved — that is the one piece of recurrence knowledge the consumer does
+ * not have.
+ *
+ * Occurrences carry derived identifiers, so re-expanding a series recognises
+ * what it already scheduled instead of creating duplicates. That is what makes
+ * a window refresh with nothing to do cost zero platform operations.
+ *
+ * Occurrences are written through the shared `ScheduleWriter`, like every other
+ * consumer notification, so a repeating tone gets its stop marker and the
+ * platform ceiling is respected here too.
+ */
+
+import { partsInZone } from "../schedule/anchor.js";
+import { validateIdentifier } from "../schedule/validate-identifier.js";
+import { validateRequest } from "../schedule/index.js";
+import { createScheduleWriter } from "../schedule/writer.js";
+import { DIAGNOSTIC_CODES, NotificationError } from "../contract/errors.js";
+import { expand, occurrenceKey } from "./expand.js";
+import { guardAgainstClockChange } from "./clock-guard.js";
+import { listSeries as readLedger, readSeries, removeSeries, upsertSeries } from "../state/series-ledger.js";
+/** Builds the request for one occurrence from the series template. */
+function toRequest(rule, occurrence) {
+  return {
+    id: occurrence.id,
+    content: rule.template.content,
+    tone: rule.template.tone,
+    moment: {
+      at: occurrence.at,
+      anchoring: occurrence.anchoring
+    },
+    routing: rule.template.routing,
+    actions: rule.template.actions,
+    ownerTag: rule.template.ownerTag,
+    groupTag: rule.template.groupTag
+  };
+}
+const belongsTo = (entry, seriesId) => entry.seriesId === seriesId || entry.id.startsWith(`${seriesId}#`);
+
+/**
+ * The latest occurrence a ledger entry written before 0.4.0 had emitted. Those
+ * entries kept no key, so it is read back off the device: the last occurrence
+ * still pending is the last one emitted.
+ */
+function recoverLastEmittedKey(pending, anchoring, zone) {
+  if (pending.length === 0) return undefined;
+  const latest = Math.max(...pending.map(entry => entry.resolvedAt));
+  return occurrenceKey(partsInZone(latest, anchoring === 'absolute' ? 'UTC' : zone));
+}
+export function createRecurrence(deps) {
+  const emit = deps.emit ?? (() => {});
+  const writer = createScheduleWriter(deps.engine);
+
+  /**
+   * Validates the template as the request every occurrence will be, once, so
+   * a series is refused at registration for exactly what a direct schedule
+   * would be refused for — an undeclared tone, too many actions, an oversized
+   * routing payload — rather than failing later inside maintenance.
+   */
+  const validateTemplate = rule => validateRequest({
+    id: rule.id,
+    content: rule.template.content,
+    tone: rule.template.tone,
+    moment: {
+      at: deps.now(),
+      anchoring: rule.anchoring ?? 'wallClock'
+    },
+    routing: rule.template.routing,
+    actions: rule.template.actions,
+    ownerTag: rule.template.ownerTag,
+    groupTag: rule.template.groupTag
+  }, deps.resolveTone);
+  const toneFor = rule => {
+    const tone = deps.resolveTone(rule.template.tone);
+    if (tone === undefined) {
+      throw new NotificationError(DIAGNOSTIC_CODES.UNDECLARED_TONE, `Tone "${rule.template.tone}" was never declared in the package configuration.`, {
+        toneId: rule.template.tone,
+        seriesId: rule.id
+      });
+    }
+    return tone;
+  };
+
+  /** Expands and registers, scheduling only occurrences the device lacks. */
+  const materialize = async (rule, tone) => {
+    const now = deps.now();
+    const zone = deps.timeZone();
+    const previous = readSeries(deps.state, rule.id);
+    const pending = await deps.engine.getPending();
+    const ofSeries = pending.filter(entry => belongsTo(entry, rule.id));
+    const expansion = expand({
+      rule,
+      from: now,
+      lookahead: deps.lookahead,
+      timeZone: zone,
+      alreadyEmitted: previous?.emittedCount ?? 0,
+      lastEmittedKey: previous?.lastEmittedKey ?? (previous !== undefined ? recoverLastEmittedKey(ofSeries, rule.anchoring, zone) : undefined)
+    });
+    const guarded = guardAgainstClockChange({
+      occurrences: expansion.occurrences,
+      previousHorizon: previous?.expandedThrough,
+      now,
+      previousNow: previous?.at
+    });
+    if (guarded.discontinuity !== 'none') {
+      emit('CLOCK_DISCONTINUITY', `Device clock moved ${guarded.discontinuity}; ${guarded.suppressed} already-handled occurrence(s) were suppressed rather than re-delivered.`, {
+        direction: guarded.discontinuity,
+        suppressed: guarded.suppressed,
+        seriesId: rule.id
+      });
+    }
+    const wanted = new Set(guarded.occurrences.map(occurrence => occurrence.id));
+
+    // Upcoming entries of this series the expansion no longer produces: ones
+    // written under the instant-based identity before 0.4.0, or ones whose slot
+    // the rule no longer has. Left in place, each would fire beside its
+    // replacement. Entries already due are left alone — they may be firing now.
+    const stale = ofSeries.filter(entry => !wanted.has(entry.id) && entry.resolvedAt > now);
+    for (const entry of stale) {
+      await writer.cancel(entry.id);
+    }
+    const onDevice = new Set(ofSeries.filter(entry => !stale.includes(entry)).map(entry => entry.id));
+    const missing = guarded.occurrences.filter(occurrence => !onDevice.has(occurrence.id));
+
+    // The same ceiling reconciliation respects: soonest first, the rest
+    // registered by a later refresh once they move into range.
+    const room = Math.max(0, (await writer.capacity()) - (pending.length - stale.length));
+    const toSchedule = missing.slice(0, room);
+    if (toSchedule.length < missing.length) {
+      emit(DIAGNOSTIC_CODES.TRUNCATED_OVER_CEILING, `Series "${rule.id}" has ${missing.length - toSchedule.length} occurrence(s) beyond the platform ceiling; they are registered by a later window refresh.`, {
+        seriesId: rule.id,
+        dropped: missing.length - toSchedule.length
+      });
+    }
+    const approximate = !deps.canScheduleExactly();
+    for (const occurrence of toSchedule) {
+      await writer.write({
+        request: toRequest(rule, occurrence),
+        resolvedAt: occurrence.at,
+        tone,
+        // The zone the series was expanded against; absent for absolute series.
+        anchoringGeneration: occurrence.anchoring === 'absolute' ? undefined : zone,
+        approximate,
+        seriesId: rule.id
+      });
+    }
+
+    // Counted once, when first emitted — whether or not the ceiling let it on
+    // the device yet. Occurrences re-produced from an earlier expansion are not
+    // counted again.
+    const newlyEmitted = guarded.occurrences.filter(occurrence => !occurrence.previouslyEmitted);
+    const lastEmittedKey = newlyEmitted.length > 0 ? newlyEmitted[newlyEmitted.length - 1].key : previous?.lastEmittedKey;
+    upsertSeries(deps.state, rule, {
+      expandedThrough: expansion.expandedThrough,
+      emittedCount: (previous?.emittedCount ?? 0) + newlyEmitted.length,
+      exhausted: expansion.exhausted,
+      lastEmittedKey
+    }, now);
+    return {
+      seriesId: rule.id,
+      scheduled: toSchedule.length,
+      expandedThrough: expansion.expandedThrough,
+      exhausted: expansion.exhausted,
+      cancelled: stale.map(entry => entry.id)
+    };
+  };
+  return {
+    async registerSeries(rule) {
+      validateIdentifier(rule.id, 'seriesId');
+      return materialize(rule, validateTemplate(rule));
+    },
+    /** Re-expands a tracked series. Called by the window-refresh maintenance step. */
+    async refreshSeries(rule) {
+      return materialize(rule, toneFor(rule));
+    },
+    async cancelSeries(seriesId) {
+      validateIdentifier(seriesId, 'seriesId');
+
+      // Every occurrence already scheduled from this series goes, identified by
+      // its derived prefix rather than by a list the ledger would have to keep
+      // in sync with the device.
+      const pending = await deps.engine.getPending();
+      const ids = pending.filter(entry => belongsTo(entry, seriesId)).map(entry => entry.id);
+      await deps.engine.cancelMany(ids);
+      const pass = writer.pass();
+      for (const id of ids) await pass.releaseStop(id);
+      removeSeries(deps.state, seriesId);
+      return ids;
+    },
+    async listSeries() {
+      const pending = await deps.engine.getPending();
+      return readLedger(deps.state).map(entry => ({
+        seriesId: entry.seriesId,
+        anchoring: entry.anchoring,
+        expandedThrough: entry.expandedThrough,
+        pendingOccurrences: pending.filter(p => belongsTo(p, entry.seriesId)).length,
+        exhausted: entry.exhausted
+      }));
+    }
+  };
+}
+//# sourceMappingURL=index.js.map

package/lib/module/recurrence/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["partsInZone","validateIdentifier","validateRequest","createScheduleWriter","DIAGNOSTIC_CODES","NotificationError","expand","occurrenceKey","guardAgainstClockChange","listSeries","readLedger","readSeries","removeSeries","upsertSeries","toRequest","rule","occurrence","id","content","template","tone","moment","at","anchoring","routing","actions","ownerTag","groupTag","belongsTo","entry","seriesId","startsWith","recoverLastEmittedKey","pending","zone","length","undefined","latest","Math","max","map","resolvedAt","createRecurrence","deps","emit","writer","engine","validateTemplate","now","resolveTone","toneFor","UNDECLARED_TONE","toneId","materialize","timeZone","previous","state","getPending","ofSeries","filter","expansion","from","lookahead","alreadyEmitted","emittedCount","lastEmittedKey","guarded","occurrences","previousHorizon","expandedThrough","previousNow","discontinuity","suppressed","direction","wanted","Set","stale","has","cancel","onDevice","includes","missing","room","capacity","toSchedule","slice","TRUNCATED_OVER_CEILING","dropped","approximate","canScheduleExactly","write","request","anchoringGeneration","newlyEmitted","previouslyEmitted","key","exhausted","scheduled","cancelled","registerSeries","refreshSeries","cancelSeries","ids","cancelMany","pass","releaseStop","pendingOccurrences","p"],"sourceRoot":"../../../src","sources":["recurrence/index.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/repeat/expiry.js

@@ -0,0 +1,37 @@
+"use strict";
+
+/**
+ * Repeat expiry.
+ *
+ * When a stop marker is delivered, the alert it guards has run its declared
+ * course. This handler ends the sound and leaves the notification exactly where
+ * it is, then removes the marker.
+ *
+ * Nothing here imports the engine. It talks to the port, which is what lets the
+ * whole mechanism be proven on a virtual clock with no device.
+ */
+
+import { createStopPlacement } from "./place.js";
+export function createRepeatExpiryHandler(deps) {
+  return {
+    async handle(event) {
+      const stop = event.repeatStop;
+      if (stop === undefined) return;
+
+      // Order matters. Silence first, remove the marker second: if the
+      // process dies between the two, a marker left behind is harmless
+      // noise, whereas a device left sounding is the failure this exists to
+      // prevent.
+      //
+      // `silenceDelivered` returning false is the ordinary case, not an
+      // error — it means the user already handled the notification. Checking
+      // the tray rather than racing to cancel the marker on interaction is
+      // what makes early handling correct by construction: even if the marker
+      // fires, there is nothing left to act on.
+      await deps.engine.silenceDelivered(stop.targetId);
+      await deps.engine.cancel(stop.markerId);
+    },
+    release: targetId => createStopPlacement(deps.engine).release(targetId)
+  };
+}
+//# sourceMappingURL=expiry.js.map

package/lib/module/repeat/expiry.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createStopPlacement","createRepeatExpiryHandler","deps","handle","event","stop","repeatStop","undefined","engine","silenceDelivered","targetId","cancel","markerId","release"],"sourceRoot":"../../../src","sources":["repeat/expiry.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA,SAASA,mBAAmB,QAAQ,YAAS;AAc7C,OAAO,SAASC,yBAAyBA,CAACC,IAA8B,EAAuB;EAC9F,OAAO;IACN,MAAMC,MAAMA,CAACC,KAAoB,EAAiB;MACjD,MAAMC,IAAI,GAAGD,KAAK,CAACE,UAAU;MAC7B,IAAID,IAAI,KAAKE,SAAS,EAAE;;MAExB;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MACA,MAAML,IAAI,CAACM,MAAM,CAACC,gBAAgB,CAACJ,IAAI,CAACK,QAAQ,CAAC;MACjD,MAAMR,IAAI,CAACM,MAAM,CAACG,MAAM,CAACN,IAAI,CAACO,QAAQ,CAAC;IACxC,CAAC;IAEDC,OAAO,EAAEH,QAAQ,IAAIV,mBAAmB,CAACE,IAAI,CAACM,MAAM,CAAC,CAACK,OAAO,CAACH,QAAQ;EACvE,CAAC;AACF","ignoreList":[]}

package/lib/module/repeat/index.js

@@ -0,0 +1,67 @@
+"use strict";
+
+/**
+ * Repeat expiry — bounding an alert that repeats until it is handled.
+ *
+ * The one piece of this package a consumer has to wire up themselves. The
+ * engine registers its background task at module scope, outside the React tree,
+ * and no library can perform that registration on an app's behalf.
+ *
+ * An app that declares no repeating tone needs none of this.
+ */
+
+import { buffer } from "../state/interaction-buffer.js";
+import { StateManager } from "../state/record.js";
+import { createRepeatExpiryHandler } from "./expiry.js";
+export { createRepeatExpiryHandler } from "./expiry.js";
+export { REPEAT_STOP_PREFIX, isRepeatStopId, markerIdFor, repeatStopFor } from "./marker.js";
+/**
+ * Registers the handler that ends a repeating alert while the app is dead.
+ *
+ * Call this at module scope in `index.js`, beside the app registration — not
+ * inside a component, and not inside an effect. By the time a component mounts,
+ * the process that needed this handler has already been asked to run it.
+ *
+ * Without it a repeating alert still starts and still stops when the user
+ * handles it, but nothing ends it on a device left face-down on a table. That
+ * is the whole reason the feature exists, so `apply()` reports its absence
+ * rather than letting anyone find out the hard way.
+ */
+export function registerBackgroundNotificationHandler(registration) {
+  const handler = createRepeatExpiryHandler(registration);
+  const keep = event => {
+    if (registration.store === undefined) return;
+    // A manager of its own: this runs in a process with no runtime, and the
+    // runtime created later loads what is written here.
+    buffer(new StateManager({
+      store: registration.store,
+      now: registration.now ?? (() => Date.now())
+    }), event);
+  };
+  registration.engine.registerBackgroundDeliveryHandler(event => handler.handle(event), async event => {
+    if (registration.onInteraction === undefined) {
+      keep(event);
+      return;
+    }
+    try {
+      await registration.onInteraction(event);
+    } catch {
+      // The app's handler failed; the interaction is kept rather than lost.
+      keep(event);
+    }
+  });
+
+  // Both paths, not just the background one. The engine routes a delivery to
+  // the foreground listener while the app is alive and to the headless task
+  // only when it is not — so registering only the latter leaves the alert
+  // sounding for anyone holding the phone when the window runs out, which is
+  // the one case they would certainly notice.
+  registration.engine.subscribeToDeliveries(event => {
+    // Deliberately not awaited: the engine's foreground listener is
+    // synchronous, and a rejection here must not take the subscription down
+    // with it — a handler that stopped listening would leave every later
+    // alarm unbounded.
+    handler.handle(event).catch(() => {});
+  });
+}
+//# sourceMappingURL=index.js.map

package/lib/module/repeat/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["buffer","StateManager","createRepeatExpiryHandler","REPEAT_STOP_PREFIX","isRepeatStopId","markerIdFor","repeatStopFor","registerBackgroundNotificationHandler","registration","handler","keep","event","store","undefined","now","Date","engine","registerBackgroundDeliveryHandler","handle","onInteraction","subscribeToDeliveries","catch"],"sourceRoot":"../../../src","sources":["repeat/index.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAIA,SAASA,MAAM,QAAQ,gCAA6B;AACpD,SAASC,YAAY,QAAQ,oBAAiB;AAE9C,SAASC,yBAAyB,QAAQ,aAAU;AAEpD,SAASA,yBAAyB,QAAQ,aAAU;AAEpD,SAASC,kBAAkB,EAAEC,cAAc,EAAEC,WAAW,EAAEC,aAAa,QAAQ,aAAU;AAuBzF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,qCAAqCA,CACpDC,YAA2C,EACpC;EACP,MAAMC,OAAO,GAAGP,yBAAyB,CAACM,YAAY,CAAC;EAEvD,MAAME,IAAI,GAAIC,KAAuB,IAAW;IAC/C,IAAIH,YAAY,CAACI,KAAK,KAAKC,SAAS,EAAE;IACtC;IACA;IACAb,MAAM,CACL,IAAIC,YAAY,CAAC;MAAEW,KAAK,EAAEJ,YAAY,CAACI,KAAK;MAAEE,GAAG,EAAEN,YAAY,CAACM,GAAG,KAAK,MAAMC,IAAI,CAACD,GAAG,CAAC,CAAC;IAAE,CAAC,CAAC,EAC5FH,KACD,CAAC;EACF,CAAC;EAEDH,YAAY,CAACQ,MAAM,CAACC,iCAAiC,CACpDN,KAAK,IAAIF,OAAO,CAACS,MAAM,CAACP,KAAK,CAAC,EAC9B,MAAMA,KAAK,IAAI;IACd,IAAIH,YAAY,CAACW,aAAa,KAAKN,SAAS,EAAE;MAC7CH,IAAI,CAACC,KAAK,CAAC;MACX;IACD;IACA,IAAI;MACH,MAAMH,YAAY,CAACW,aAAa,CAACR,KAAK,CAAC;IACxC,CAAC,CAAC,MAAM;MACP;MACAD,IAAI,CAACC,KAAK,CAAC;IACZ;EACD,CACD,CAAC;;EAED;EACA;EACA;EACA;EACA;EACAH,YAAY,CAACQ,MAAM,CAACI,qBAAqB,CAACT,KAAK,IAAI;IAClD;IACA;IACA;IACA;IACAF,OAAO,CAACS,MAAM,CAACP,KAAK,CAAC,CAACU,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;EACtC,CAAC,CAAC;AACH","ignoreList":[]}

package/lib/module/repeat/marker.js

@@ -0,0 +1,51 @@
+"use strict";
+
+/**
+ * Stop-marker identity.
+ *
+ * A repeating alert has to end without the app being alive, and no platform
+ * offers "stop the sound at time T but keep the notification". So the package
+ * schedules its own notification at T and reacts to its delivery. That
+ * notification is a *marker*: it exists to be delivered and immediately
+ * removed, never to be read.
+ *
+ * The marker's identifier is derived from the target's by hashing rather than by
+ * concatenation. Concatenation would overflow the package's 128-character
+ * identifier limit for any target already near it, and would make the marker's
+ * identity a function of a value the consumer controls — which is how a
+ * consumer identifier ends up colliding with an internal one.
+ */
+
+import { fnv1a, hex8 } from "../contract/hash.js";
+/**
+ * Reserved identifier namespace.
+ *
+ * Rejected as a consumer identifier prefix. A consumer id colliding with a
+ * marker would not merely confuse a listing: the expiry handler cancels
+ * markers, so the collision would delete a real notification.
+ */
+export const REPEAT_STOP_PREFIX = 'cms.stop:';
+
+/**
+ * The marker identifier for a target notification.
+ *
+ * Two independent hashes rather than one: a single 32-bit hash collides often
+ * enough to matter once a device holds a handful of alarms, and a collision here
+ * means one alarm's marker silences the other alarm and never silences its own.
+ */
+export function markerIdFor(targetId) {
+  return `${REPEAT_STOP_PREFIX}${hex8(fnv1a(targetId, 0x811c9dc5))}${hex8(fnv1a(targetId, 0x9e3779b9))}`;
+}
+export function isRepeatStopId(id) {
+  return id.startsWith(REPEAT_STOP_PREFIX);
+}
+
+/** Describes the stop for a target whose alert must end at a known instant. */
+export function repeatStopFor(targetId, deliveredAt, forMs) {
+  return {
+    markerId: markerIdFor(targetId),
+    targetId,
+    dueAt: deliveredAt + forMs
+  };
+}
+//# sourceMappingURL=marker.js.map