@baukit/notifications-core 0.7.2 → 0.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baukit/notifications-core",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Framework-free local notification planning: zoned occurrence resolution, horizon filtering, deterministic keep, cancel, and schedule sets, and owner-scoped replacement over a platform port.",
   "license": "MIT",
   "author": "Patrick Koss",
@@ -39,6 +39,7 @@
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "LICENSE"
   ],
@@ -56,6 +57,6 @@
     "vitest": "5.0.3"
   },
   "peerDependencies": {
-    "@baukit/localization-core": "^0.7.2"
+    "@baukit/localization-core": "^0.7.3"
   }
 }

package/src/errors.ts

@@ -0,0 +1,25 @@
+export type NotificationPlanErrorCode =
+  | 'invalid_civil_date'
+  | 'invalid_civil_time'
+  | 'invalid_time_zone'
+  | 'invalid_horizon'
+  | 'invalid_clock'
+  | 'invalid_namespace'
+  | 'invalid_logical_id'
+  | 'invalid_content_digest'
+  | 'invalid_instant'
+  | 'invalid_pending_limit'
+  | 'duplicate_logical_id'
+  | 'reserved_data_key';
+
+export class NotificationPlanError extends Error {
+  override readonly name = 'NotificationPlanError';
+  readonly code: NotificationPlanErrorCode;
+  readonly logicalId: string | undefined;
+
+  constructor(code: NotificationPlanErrorCode, logicalId?: string) {
+    super(logicalId === undefined ? code : `${code}: ${logicalId}`);
+    this.code = code;
+    this.logicalId = logicalId;
+  }
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+export { NotificationPlanError, type NotificationPlanErrorCode } from './errors.js';
+export {
+  InMemoryNotificationPlatform,
+  NotificationPlatformFaultState,
+  type NotificationPlatformFaults,
+  type StoredNotification,
+} from './memory.js';
+export {
+  resolveNotificationOccurrences,
+  type NotificationClock,
+  type NotificationOccurrence,
+  type NotificationOccurrenceInput,
+  type NotificationOccurrenceResolution,
+  type ResolvedNotification,
+  type SkippedOccurrence,
+  type SkippedOccurrenceReason,
+} from './occurrences.js';
+export {
+  decodeOwnedNotificationMarker,
+  encodeOwnedNotificationMarker,
+  isOwnedBy,
+  OWNED_NOTIFICATION_DATA_KEY,
+  OWNED_NOTIFICATION_MARKER_VERSION,
+  ownedNotificationIdentifier,
+  type OwnedNotificationMarker,
+} from './ownership.js';
+export {
+  planNotificationReplacement,
+  type NotificationReplacementOptions,
+  type NotificationReplacementPlan,
+} from './replacement-plan.js';
+export {
+  createOwnedNotificationScheduler,
+  type NotificationOwner,
+  type NotificationPermission,
+  type NotificationPlatform,
+  type OwnedNotification,
+  type OwnedNotificationFailure,
+  type OwnedNotificationFailureCode,
+  type OwnedNotificationReplacementOutcome,
+  type OwnedNotificationReplacementStatus,
+  type OwnedNotificationScheduler,
+  type OwnedNotificationSchedulerOptions,
+  type OwnedNotificationScheduleRequest,
+  type PendingNotification,
+} from './scheduler.js';
+export {
+  isValidContentDigest,
+  isValidLogicalId,
+  isValidNamespace,
+  MAX_CONTENT_DIGEST_LENGTH,
+  MAX_LOGICAL_ID_LENGTH,
+  MAX_NAMESPACE_LENGTH,
+  type PlannedNotification,
+} from './validation.js';

package/src/memory.ts

@@ -0,0 +1,148 @@
+import type {
+  NotificationPermission,
+  NotificationPlatform,
+  OwnedNotificationScheduleRequest,
+  PendingNotification,
+} from './scheduler.js';
+
+export interface NotificationPlatformFaults {
+  setPermission(permission: NotificationPermission): void;
+  failNextList(): void;
+  failNextPermission(): void;
+  failCancel(identifier: string): void;
+  failSchedule(identifier: string): void;
+  holdNextList(): () => void;
+  afterNextList(action: () => void): void;
+}
+
+export interface StoredNotification<TContent> extends PendingNotification {
+  readonly content: TContent | null;
+}
+
+export class NotificationPlatformFaultState implements NotificationPlatformFaults {
+  permission: NotificationPermission = 'granted';
+  private listFailures = 0;
+  private permissionFailures = 0;
+  private readonly cancelFailures = new Set<string>();
+  private readonly scheduleFailures = new Set<string>();
+  private readonly listHolds: Promise<void>[] = [];
+  private readonly listActions: (() => void)[] = [];
+
+  setPermission(permission: NotificationPermission): void {
+    this.permission = permission;
+  }
+
+  failNextList(): void {
+    this.listFailures += 1;
+  }
+
+  failNextPermission(): void {
+    this.permissionFailures += 1;
+  }
+
+  failCancel(identifier: string): void {
+    this.cancelFailures.add(identifier);
+  }
+
+  failSchedule(identifier: string): void {
+    this.scheduleFailures.add(identifier);
+  }
+
+  holdNextList(): () => void {
+    let release = (): void => undefined;
+    this.listHolds.push(
+      new Promise<void>((resolve) => {
+        release = resolve;
+      }),
+    );
+    return release;
+  }
+
+  afterNextList(action: () => void): void {
+    this.listActions.push(action);
+  }
+
+  async beforeList(): Promise<void> {
+    await this.listHolds.shift();
+    if (this.listFailures > 0) {
+      this.listFailures -= 1;
+      throw new Error('list failed');
+    }
+  }
+
+  afterList(): void {
+    this.listActions.shift()?.();
+  }
+
+  beforePermission(): void {
+    if (this.permissionFailures > 0) {
+      this.permissionFailures -= 1;
+      throw new Error('permission check failed');
+    }
+  }
+
+  beforeCancel(identifier: string): void {
+    if (this.cancelFailures.delete(identifier)) {
+      throw new Error('cancel failed');
+    }
+  }
+
+  beforeSchedule(identifier: string): void {
+    if (this.scheduleFailures.delete(identifier)) {
+      throw new Error('schedule failed');
+    }
+  }
+}
+
+export class InMemoryNotificationPlatform<TContent> implements NotificationPlatform<TContent> {
+  readonly faults = new NotificationPlatformFaultState();
+  private readonly requests = new Map<string, StoredNotification<TContent>>();
+
+  addUnrelated(identifier: string): void {
+    this.requests.set(identifier, { identifier, marker: null, content: null });
+  }
+
+  pending(): readonly StoredNotification<TContent>[] {
+    return [...this.requests.values()].sort((left, right) =>
+      left.identifier < right.identifier ? -1 : 1,
+    );
+  }
+
+  async list(): Promise<readonly PendingNotification[]> {
+    await this.faults.beforeList();
+    const snapshot = this.pending().map(({ identifier, marker }) => ({ identifier, marker }));
+    this.faults.afterList();
+    return snapshot;
+  }
+
+  cancel(identifier: string): Promise<void> {
+    return settle(() => {
+      this.faults.beforeCancel(identifier);
+      this.requests.delete(identifier);
+    });
+  }
+
+  permission(): Promise<NotificationPermission> {
+    return settle(() => {
+      this.faults.beforePermission();
+      return this.faults.permission;
+    });
+  }
+
+  schedule(request: OwnedNotificationScheduleRequest<TContent>): Promise<void> {
+    return settle(() => {
+      this.faults.beforeSchedule(request.identifier);
+      this.requests.set(request.identifier, {
+        identifier: request.identifier,
+        marker: request.marker,
+        content: request.content,
+      });
+    });
+  }
+}
+
+function settle<T>(action: () => T): Promise<T> {
+  return new Promise((resolve) => {
+    resolve(action());
+  });
+}

package/src/notifications-core.test.ts

@@ -0,0 +1,161 @@
+import { describe, expect, it } from 'vitest';
+
+import { NotificationPlanError } from './errors.js';
+import { InMemoryNotificationPlatform } from './memory.js';
+import { resolveNotificationOccurrences } from './occurrences.js';
+import {
+  decodeOwnedNotificationMarker,
+  encodeOwnedNotificationMarker,
+  isOwnedBy,
+  ownedNotificationIdentifier,
+  type OwnedNotificationMarker,
+} from './ownership.js';
+import { planNotificationReplacement } from './replacement-plan.js';
+import { createOwnedNotificationScheduler } from './scheduler.js';
+import { describeOwnedNotificationSchedulerContract } from './vitest.js';
+
+const NOW = Date.parse('2026-06-15T06:00:00Z');
+const MARKER: OwnedNotificationMarker = {
+  namespace: 'reminders',
+  logicalId: 'plan:2026-06-15',
+  epochMilliseconds: NOW,
+  contentDigest: 'sha256:abc',
+};
+
+const baseInput = {
+  timeZone: 'Europe/Berlin',
+  gap: 'reject',
+  fold: 'earlier',
+  clock: () => NOW,
+  horizonDays: 2,
+} as const;
+
+function markerJson(overrides: Record<string, unknown>): string {
+  return JSON.stringify({ version: 1, ...MARKER, ...overrides });
+}
+
+describe('resolveNotificationOccurrences', () => {
+  it('carries product fields through to the desired set', () => {
+    const resolution = resolveNotificationOccurrences({
+      ...baseInput,
+      occurrences: [
+        {
+          logicalId: 'a',
+          civilDate: '2026-06-15',
+          civilTime: '09:00',
+          contentDigest: 'v1',
+          title: 'kept',
+        },
+      ],
+    });
+    expect(resolution.desired).toEqual([
+      {
+        logicalId: 'a',
+        civilDate: '2026-06-15',
+        civilTime: '09:00',
+        contentDigest: 'v1',
+        title: 'kept',
+        epochMilliseconds: Date.parse('2026-06-15T07:00:00Z'),
+        transition: 'none',
+      },
+    ]);
+  });
+
+  it('rejects an unknown policy even without occurrences', () => {
+    expect(() =>
+      resolveNotificationOccurrences({
+        ...baseInput,
+        gap: 'skip' as 'reject',
+        occurrences: [],
+      }),
+    ).toThrow(RangeError);
+  });
+
+  it('returns the same result for repeated calls with the same clock', () => {
+    const input = {
+      ...baseInput,
+      occurrences: [
+        { logicalId: 'b', civilDate: '2026-06-16', civilTime: '09:00', contentDigest: 'v1' },
+        { logicalId: 'a', civilDate: '2026-06-15', civilTime: '09:00', contentDigest: 'v1' },
+      ],
+    };
+    expect(resolveNotificationOccurrences(input)).toEqual(resolveNotificationOccurrences(input));
+  });
+});
+
+describe('planNotificationReplacement', () => {
+  it('keeps an entry whose text changed under the same digest', () => {
+    const current = [{ logicalId: 'a', epochMilliseconds: NOW + 1, contentDigest: 'v1' }];
+    const desired = [
+      { logicalId: 'a', epochMilliseconds: NOW + 1, contentDigest: 'v1', text: 'new' },
+    ];
+    expect(planNotificationReplacement(current, desired)).toEqual({
+      keep: current,
+      cancel: [],
+      schedule: [],
+    });
+  });
+
+  it('rejects an instant that is not a safe integer', () => {
+    const desired = [{ logicalId: 'a', epochMilliseconds: 1.5, contentDigest: 'v1' }];
+    expect(() => planNotificationReplacement([], desired)).toThrow(
+      expect.objectContaining({ code: 'invalid_instant', logicalId: 'a' }),
+    );
+  });
+});
+
+describe('owned notification markers', () => {
+  it('round-trips a marker', () => {
+    expect(decodeOwnedNotificationMarker(encodeOwnedNotificationMarker(MARKER))).toEqual(MARKER);
+  });
+
+  it.each([
+    ['an object', { ...MARKER }],
+    ['malformed JSON', '{'],
+    ['JSON null', 'null'],
+    ['another version', markerJson({ version: 2 })],
+    ['an invalid namespace', markerJson({ namespace: 'Upper' })],
+    ['an empty logical ID', markerJson({ logicalId: '' })],
+    ['a string instant', markerJson({ epochMilliseconds: '1' })],
+    ['a missing digest', markerJson({ contentDigest: undefined })],
+  ])('ignores %s', (_label, value) => {
+    expect(decodeOwnedNotificationMarker(value)).toBeNull();
+  });
+
+  it('owns a request only when the identifier matches the marker', () => {
+    const identifier = ownedNotificationIdentifier(MARKER.namespace, MARKER.logicalId);
+    expect(identifier).toBe('baukit:reminders:plan:2026-06-15');
+    expect(isOwnedBy('reminders', identifier, MARKER)).toBe(true);
+    expect(isOwnedBy('reminders', 'forged', MARKER)).toBe(false);
+    expect(isOwnedBy('reminders-extra', identifier, MARKER)).toBe(false);
+    expect(isOwnedBy('reminders', identifier, null)).toBe(false);
+  });
+
+  it('rejects an invalid namespace in identifiers', () => {
+    expect(() => ownedNotificationIdentifier('a:b', 'x')).toThrow(NotificationPlanError);
+  });
+});
+
+describe('createOwnedNotificationScheduler', () => {
+  it.each([0, -1, 1.5, Number.NaN])('rejects a pending limit of %s', (pendingLimit) => {
+    const platform = new InMemoryNotificationPlatform<string>();
+    expect(() => createOwnedNotificationScheduler(platform, { pendingLimit })).toThrow(
+      expect.objectContaining({ code: 'invalid_pending_limit' }),
+    );
+  });
+});
+
+describe('InMemoryNotificationPlatform', () => {
+  describeOwnedNotificationSchedulerContract<string>((options) => {
+    const platform = new InMemoryNotificationPlatform<string>();
+    return {
+      scheduler: createOwnedNotificationScheduler(platform, options),
+      faults: platform.faults,
+      content: (_logicalId, text) => text,
+      addUnrelated: (identifier) => {
+        platform.addUnrelated(identifier);
+      },
+      pending: () => platform.pending(),
+    };
+  });
+});

package/src/occurrences.ts

@@ -0,0 +1,154 @@
+import {
+  addCivilDays,
+  civilDateForInstant,
+  compareCivilDates,
+  INVALID_TIME_ZONE_CODE,
+  NONEXISTENT_LOCAL_TIME_CODE,
+  resolveZonedLocalTime,
+  type FoldPolicy,
+  type GapPolicy,
+  type LocalTimeTransition,
+  type ZonedLocalTimeResult,
+} from '@baukit/localization-core';
+
+import { NotificationPlanError } from './errors.js';
+import { assertIdentity, compareByInstant, compareCodeUnits } from './validation.js';
+
+export interface NotificationOccurrence {
+  readonly logicalId: string;
+  readonly civilDate: string;
+  readonly civilTime: string;
+  readonly contentDigest: string;
+}
+
+export type NotificationClock = () => number;
+
+export interface NotificationOccurrenceInput<T extends NotificationOccurrence> {
+  readonly occurrences: readonly T[];
+  readonly timeZone: string;
+  readonly gap: GapPolicy;
+  readonly fold: FoldPolicy;
+  readonly clock: NotificationClock;
+  readonly horizonDays: number;
+}
+
+export type ResolvedNotification<T extends NotificationOccurrence = NotificationOccurrence> = T & {
+  readonly epochMilliseconds: number;
+  readonly transition: LocalTimeTransition;
+};
+
+export type SkippedOccurrenceReason = 'past' | 'outside_horizon' | 'nonexistent_local_time';
+
+export interface SkippedOccurrence {
+  readonly logicalId: string;
+  readonly reason: SkippedOccurrenceReason;
+}
+
+export interface NotificationOccurrenceResolution<T extends NotificationOccurrence> {
+  readonly now: number;
+  readonly firstCivilDate: string;
+  readonly lastCivilDate: string;
+  readonly desired: readonly ResolvedNotification<T>[];
+  readonly skipped: readonly SkippedOccurrence[];
+}
+
+interface HorizonWindow {
+  readonly now: number;
+  readonly firstCivilDate: string;
+  readonly lastCivilDate: string;
+}
+
+const TIME_ZONE_PROBE_DATE = '2000-01-01';
+const TIME_ZONE_PROBE_TIME = '12:00';
+
+export function resolveNotificationOccurrences<T extends NotificationOccurrence>(
+  input: NotificationOccurrenceInput<T>,
+): NotificationOccurrenceResolution<T> {
+  const window = horizonWindow(input);
+  const seen = new Set<string>();
+  const desired: ResolvedNotification<T>[] = [];
+  const skipped: SkippedOccurrence[] = [];
+
+  for (const occurrence of input.occurrences) {
+    assertIdentity(occurrence, seen);
+    const result = resolveZonedLocalTime({
+      civilDate: occurrence.civilDate,
+      civilTime: occurrence.civilTime,
+      timeZone: input.timeZone,
+      gap: input.gap,
+      fold: input.fold,
+    });
+    const reason = skipReason(occurrence, result, window);
+    if (reason !== null) {
+      skipped.push({ logicalId: occurrence.logicalId, reason });
+    } else if (result.ok) {
+      desired.push({
+        ...occurrence,
+        epochMilliseconds: result.epochMilliseconds,
+        transition: result.transition,
+      });
+    }
+  }
+
+  return {
+    ...window,
+    desired: desired.sort(compareByInstant),
+    skipped: skipped.sort((left, right) => compareCodeUnits(left.logicalId, right.logicalId)),
+  };
+}
+
+function horizonWindow(input: NotificationOccurrenceInput<NotificationOccurrence>): HorizonWindow {
+  assertTimeZoneAndPolicies(input);
+  if (!Number.isSafeInteger(input.horizonDays) || input.horizonDays < 1) {
+    throw new NotificationPlanError('invalid_horizon');
+  }
+  const now = input.clock();
+  if (!Number.isFinite(now) || Number.isNaN(new Date(now).getTime())) {
+    throw new NotificationPlanError('invalid_clock');
+  }
+  const firstCivilDate = civilDateForInstant(now, input.timeZone);
+  try {
+    return {
+      now,
+      firstCivilDate,
+      lastCivilDate: addCivilDays(firstCivilDate, input.horizonDays - 1),
+    };
+  } catch {
+    throw new NotificationPlanError('invalid_horizon');
+  }
+}
+
+function assertTimeZoneAndPolicies(
+  input: NotificationOccurrenceInput<NotificationOccurrence>,
+): void {
+  const probe = resolveZonedLocalTime({
+    civilDate: TIME_ZONE_PROBE_DATE,
+    civilTime: TIME_ZONE_PROBE_TIME,
+    timeZone: input.timeZone,
+    gap: input.gap,
+    fold: input.fold,
+  });
+  if (!probe.ok && probe.code === INVALID_TIME_ZONE_CODE) {
+    throw new NotificationPlanError('invalid_time_zone');
+  }
+}
+
+function skipReason(
+  occurrence: NotificationOccurrence,
+  result: ZonedLocalTimeResult,
+  window: HorizonWindow,
+): SkippedOccurrenceReason | null {
+  if (!result.ok && result.code !== NONEXISTENT_LOCAL_TIME_CODE) {
+    throw new NotificationPlanError(result.code, occurrence.logicalId);
+  }
+  if (
+    compareCivilDates(occurrence.civilDate, window.firstCivilDate) < 0 ||
+    compareCivilDates(occurrence.civilDate, window.lastCivilDate) > 0
+  ) {
+    return 'outside_horizon';
+  }
+  if (!result.ok) {
+    return 'nonexistent_local_time';
+  }
+  return result.epochMilliseconds <= window.now ? 'past' : null;
+}

package/src/ownership.ts

@@ -0,0 +1,72 @@
+import {
+  assertNamespace,
+  isValidContentDigest,
+  isValidInstant,
+  isValidLogicalId,
+  isValidNamespace,
+  type PlannedNotification,
+} from './validation.js';
+
+export const OWNED_NOTIFICATION_DATA_KEY = 'baukitNotification';
+export const OWNED_NOTIFICATION_MARKER_VERSION = 1;
+
+const IDENTIFIER_PREFIX = 'baukit';
+const IDENTIFIER_SEPARATOR = ':';
+
+export interface OwnedNotificationMarker extends PlannedNotification {
+  readonly namespace: string;
+}
+
+export function ownedNotificationIdentifier(namespace: string, logicalId: string): string {
+  assertNamespace(namespace);
+  return [IDENTIFIER_PREFIX, namespace, logicalId].join(IDENTIFIER_SEPARATOR);
+}
+
+export function encodeOwnedNotificationMarker(marker: OwnedNotificationMarker): string {
+  return JSON.stringify({
+    version: OWNED_NOTIFICATION_MARKER_VERSION,
+    namespace: marker.namespace,
+    logicalId: marker.logicalId,
+    epochMilliseconds: marker.epochMilliseconds,
+    contentDigest: marker.contentDigest,
+  });
+}
+
+export function decodeOwnedNotificationMarker(value: unknown): OwnedNotificationMarker | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== 'object' || parsed === null) {
+    return null;
+  }
+  const record = parsed as Record<string, unknown>;
+  const { namespace, logicalId, epochMilliseconds, contentDigest } = record;
+  if (
+    record['version'] !== OWNED_NOTIFICATION_MARKER_VERSION ||
+    !isValidNamespace(namespace) ||
+    !isValidLogicalId(logicalId) ||
+    !isValidInstant(epochMilliseconds) ||
+    !isValidContentDigest(contentDigest)
+  ) {
+    return null;
+  }
+  return { namespace, logicalId, epochMilliseconds, contentDigest };
+}
+
+export function isOwnedBy(
+  namespace: string,
+  identifier: string,
+  marker: OwnedNotificationMarker | null,
+): marker is OwnedNotificationMarker {
+  return (
+    marker !== null &&
+    marker.namespace === namespace &&
+    identifier === ownedNotificationIdentifier(namespace, marker.logicalId)
+  );
+}

package/src/plan-vectors.test.ts

@@ -0,0 +1,28 @@
+import { readFileSync } from 'node:fs';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  notificationPlanVectorChecks,
+  type NotificationPlanVectorFixture,
+} from './plan-vectors.js';
+
+const fixtureUrl = new URL(
+  '../../../../fixtures/notifications/plan-vectors-v1.json',
+  import.meta.url,
+);
+const readUtf8File = readFileSync as unknown as (path: URL, encoding: 'utf8') => string;
+const fixture = JSON.parse(readUtf8File(fixtureUrl, 'utf8')) as NotificationPlanVectorFixture;
+
+describe('notification plan vectors', () => {
+  it('reads version 1 of the shared vectors', () => {
+    expect(fixture.version).toBe(1);
+    const errorCases = fixture.cases.filter((entry) => 'error' in entry.expected);
+    expect(errorCases.length).toBeGreaterThan(0);
+    expect(errorCases.length).toBeLessThan(fixture.cases.length);
+  });
+
+  it.each(notificationPlanVectorChecks(fixture))('$label', ({ actual, expected }) => {
+    expect(actual()).toEqual(expected);
+  });
+});