@chipmobilesdk/rn-notification 0.5.0 → 0.7.0

package/lib/typescript/module/schedule/anchor.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Time-zone anchoring and re-anchoring.
+ *
+ * Wall-clock is the default because reminders are wall-clock things: an 08:00
+ * reminder should stay 08:00 after the user crosses a time zone, and a caller
+ * who does not choose should get what their users expect rather than a silent
+ * shift.
+ *
+ * The cost is re-anchoring. When the device zone changes, every scheduled
+ * wall-clock entry must be rewritten to preserve the clock time it named, and
+ * every absolute entry must be left completely alone.
+ *
+ * The limit this cannot fix is stated rather than hidden: a wall-clock
+ * notification whose moment arrives while the app has not run since the zone
+ * changed fires at the previously anchored instant. The anchoring generation on
+ * each entry is what makes that detectable instead of invisible.
+ */
+import type { AnchoringMode, PendingEntry } from '../contract/notification.js';
+/** Reads the platform time zone. Injected so the pure logic needs no native module. */
+export type TimeZoneReader = () => string;
+/**
+ * Resolves the platform zone via `react-native-localize`.
+ *
+ * Pure JavaScript is not sufficient here: `Intl.DateTimeFormat().resolvedOptions().timeZone`
+ * is documented in React Native as not reliably updating when the device zone
+ * changes, so it cannot back re-anchoring. Falls back to `Intl` only when the
+ * module is absent, which is better than failing outright.
+ */
+export declare function createPlatformTimeZoneReader(): TimeZoneReader;
+/** The calendar fields a wall-clock moment actually names. */
+export interface WallClockParts {
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+    readonly hour: number;
+    readonly minute: number;
+    readonly second: number;
+}
+/**
+ * Whether a zone name is one the runtime can actually format against.
+ *
+ * Hermes throws a hard `JSRangeErrorException: Invalid timezone name!` for a
+ * bad zone, which kills the JavaScript thread rather than returning an error.
+ * A stored anchoring generation is data that can be wrong — a corrupted record,
+ * an entry written by an older build, or a defect like the one that stored a
+ * tone id here — so it must be checked before it reaches `Intl`.
+ */
+export declare function isValidTimeZone(timeZone: string): boolean;
+/**
+ * Decomposes an instant into the clock reading it produces in a given zone.
+ *
+ * Falls back to UTC for an unusable zone rather than throwing: a bad stored
+ * value should degrade one entry's anchoring, not crash the app.
+ */
+export declare function partsInZone(instant: number, timeZone: string): WallClockParts;
+/**
+ * Finds the instant at which a zone shows the given clock reading.
+ *
+ * Two passes, because the offset itself depends on the instant: the first guess
+ * uses the offset at the naive UTC interpretation, the second corrects for a
+ * daylight-saving boundary crossed by that guess.
+ *
+ * Daylight-saving resolution, per the documented rule:
+ * - a clock time that does not exist resolves **forward** to the next valid instant;
+ * - a clock time that occurs twice resolves to its **first** occurrence, so
+ *   exactly one notification results rather than two.
+ */
+export declare function instantForParts(parts: WallClockParts, timeZone: string): number;
+export interface AnchorInput {
+    readonly at: number;
+    readonly anchoring?: AnchoringMode;
+}
+export interface AnchoredMoment {
+    readonly resolvedAt: number;
+    readonly anchoring: AnchoringMode;
+    /** The zone this was anchored against. Absent for absolute-instant moments. */
+    readonly generation?: string;
+}
+/**
+ * Resolves a caller-supplied moment into a firing instant.
+ *
+ * An absolute moment passes through untouched — that is the entire distinction.
+ */
+export declare function anchorMoment(input: AnchorInput, timeZone: string): AnchoredMoment;
+export interface ReAnchorPlan {
+    /** Entries whose firing instant must be rewritten, with their new instant. */
+    readonly rewrites: readonly {
+        readonly entry: PendingEntry;
+        readonly resolvedAt: number;
+    }[];
+    readonly fromZone: string | undefined;
+    readonly toZone: string;
+    readonly zoneChanged: boolean;
+    /**
+     * Entries carrying an anchoring generation the runtime cannot interpret.
+     *
+     * Left alone rather than re-anchored against a guess. Reported so a corrupted
+     * or older-build record is visible instead of quietly producing wrong firing
+     * instants.
+     */
+    readonly unreadableGeneration: readonly string[];
+}
+/**
+ * Computes what a zone change requires.
+ *
+ * Returns an empty plan when the zone has not moved, which is what makes
+ * re-anchoring idempotent: the no-change check costs one comparison per entry
+ * and issues zero platform operations.
+ */
+export declare function planReAnchor(pending: readonly PendingEntry[], currentZone: string): ReAnchorPlan;
+/**
+ * True when an entry was anchored against a zone the device has since left.
+ *
+ * This is the FR-007c condition: the entry will fire at its old instant, and a
+ * consumer can detect and explain that rather than being told nothing happened.
+ */
+export declare function isStaleAnchor(entry: PendingEntry, currentZone: string): boolean;
+//# sourceMappingURL=anchor.d.ts.map

package/lib/typescript/module/schedule/anchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../../../../src/schedule/anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,6BAA0B,CAAC;AAG5E,uFAAuF;AACvF,MAAM,MAAM,cAAc,GAAG,MAAM,MAAM,CAAC;AAW1C;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,IAAI,cAAc,CAc7D;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIzD;AAaD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,CAsB7E;AAgBD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAkC/E;AAED,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,CAQjF;AAED,MAAM,WAAW,YAAY;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5F,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;CACjD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,YAAY,CAsChG;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAM/E"}

package/lib/typescript/module/schedule/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The scheduling operations.
+ *
+ * Validation runs in a fixed order and completes entirely before any platform
+ * call: identifier, tags, content, moment shape, tone, actions, routing size.
+ * A caller therefore never sees a native-level error surface through the
+ * package, and a rejected request leaves the device untouched.
+ *
+ * Scheduling an identifier that already has a notification **replaces** it.
+ * That is the defined semantic rather than a side effect, which is what lets a
+ * caller stop tracking whether it has already scheduled something.
+ */
+import type { NotificationRequest, PendingEntry, ScheduleResult } from '../contract/notification.js';
+import type { ResolvedTone } from '../contract/channel.js';
+import type { NotificationEngineAdapter } from '../engine/adapter.js';
+import { type TimeZoneReader } from './anchor.js';
+export interface ScheduleDependencies {
+    readonly engine: NotificationEngineAdapter;
+    readonly resolveTone: (toneId: string) => ResolvedTone | undefined;
+    readonly timeZone: TimeZoneReader;
+    readonly now: () => number;
+    /** False when exact-alarm capability is unavailable, forcing approximate mode. */
+    readonly canScheduleExactly: () => boolean;
+    readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+/** Validates a request completely, before the engine is touched at all. */
+export declare function validateRequest(request: NotificationRequest, resolveTone: (toneId: string) => ResolvedTone | undefined): ResolvedTone;
+export declare function createScheduler(deps: ScheduleDependencies): {
+    schedule: (request: NotificationRequest, options?: {
+        readonly seriesId?: string;
+        readonly pushCreated?: boolean;
+    }) => Promise<ScheduleResult>;
+    cancel(id: string): Promise<void>;
+    cancelByGroup(groupTag: string): Promise<readonly string[]>;
+    cancelByOwner(ownerTag: string): Promise<readonly string[]>;
+    cancelAll(): Promise<void>;
+    getPending(): Promise<readonly PendingEntry[]>;
+};
+export type Scheduler = ReturnType<typeof createScheduler>;
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/schedule/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/schedule/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,6BAA0B,CAAC;AAClG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,sBAAmB,CAAC;AAMnE,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,aAAU,CAAC;AAI7D,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAC;IAC3C,QAAQ,CAAC,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,YAAY,GAAG,SAAS,CAAC;IACnE,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,kBAAkB,EAAE,MAAM,OAAO,CAAC;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAC3F;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAC9B,OAAO,EAAE,mBAAmB,EAC5B,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,YAAY,GAAG,SAAS,GACvD,YAAY,CA2Cd;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,oBAAoB;wBAM/C,mBAAmB,YACnB;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,KACrE,OAAO,CAAC,cAAc,CAAC;eAmDR,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;4BAQT,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC;4BASnC,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC;iBAS9C,OAAO,CAAC,IAAI,CAAC;kBAIZ,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC;EAIrD;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/lib/typescript/module/schedule/partition.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Owner-tag and group-tag partitioning.
+ *
+ * A tag is an opaque label the caller supplies and the package never
+ * interprets. That is deliberate: modelling identity would mean acquiring an
+ * opinion about it, and this package is forbidden from knowing anything about
+ * accounts, tenants, or users.
+ *
+ * What the tag buys is one call — "clear this account's notifications" — on a
+ * shared device, without the package ever learning what an account is.
+ */
+import type { PendingEntry } from '../contract/notification.js';
+export type PartitionKind = 'owner' | 'group';
+/** Selects entries carrying a tag. Comparison is exact; nothing is normalized. */
+export declare function selectByTag(entries: readonly PendingEntry[], kind: PartitionKind, tag: string): readonly PendingEntry[];
+/** Identifiers to cancel for a tag. */
+export declare function idsForTag(entries: readonly PendingEntry[], kind: PartitionKind, tag: string): readonly string[];
+/**
+ * Groups entries by a tag, keeping untagged entries under a distinct bucket.
+ *
+ * Untagged is not the same as any tag: an entry with no owner belongs to no
+ * account, and folding it into one would make a sign-out delete notifications
+ * that were never that account's.
+ */
+export declare function partition(entries: readonly PendingEntry[], kind: PartitionKind): {
+    readonly tagged: ReadonlyMap<string, readonly PendingEntry[]>;
+    readonly untagged: readonly PendingEntry[];
+};
+//# sourceMappingURL=partition.d.ts.map

package/lib/typescript/module/schedule/partition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"partition.d.ts","sourceRoot":"","sources":["../../../../src/schedule/partition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA0B,CAAC;AAE7D,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,CAAC;AAE9C,kFAAkF;AAClF,wBAAgB,WAAW,CAC1B,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,IAAI,EAAE,aAAa,EACnB,GAAG,EAAE,MAAM,GACT,SAAS,YAAY,EAAE,CAIzB;AAED,uCAAuC;AACvC,wBAAgB,SAAS,CACxB,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,IAAI,EAAE,aAAa,EACnB,GAAG,EAAE,MAAM,GACT,SAAS,MAAM,EAAE,CAEnB;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACxB,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,IAAI,EAAE,aAAa,GACjB;IACF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC,CAAC;IAC9D,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C,CAmBA"}

package/lib/typescript/module/schedule/resolve-moment.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Delivery moment resolution.
+ *
+ * Two rules, and they are two sides of one decision rather than a threshold:
+ * a moment more than the tolerance in the past is a caller error and is
+ * refused; a moment a few seconds in the past is a processing delay and is
+ * delivered promptly. Both outcomes are reported, so a caller never has to
+ * guess which happened.
+ *
+ * Sixty seconds is long enough to absorb reconciling a large desired set, cold
+ * start work, and clock skew, and short enough that a genuinely stale schedule
+ * is still caught rather than fired at the user minutes late with no
+ * explanation.
+ */
+import type { DeliveryMoment } from '../contract/notification.js';
+export declare const PAST_TOLERANCE_MS = 60000;
+export type MomentResolution = {
+    readonly kind: 'future';
+    readonly at: number;
+} | {
+    readonly kind: 'immediate';
+    readonly at: number;
+    readonly lateBy: number;
+};
+/**
+ * Classifies a resolved instant against now.
+ *
+ * Takes an already-anchored instant: anchoring decides *which* instant a moment
+ * means, and this decides whether that instant is usable. Keeping them separate
+ * is what lets each be tested without the other.
+ */
+export declare function resolveMoment(resolvedAt: number, now: number): MomentResolution;
+/** Validates the shape of a caller-supplied moment before anchoring resolves it. */
+export declare function validateMoment(moment: DeliveryMoment): void;
+//# sourceMappingURL=resolve-moment.d.ts.map

package/lib/typescript/module/schedule/resolve-moment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-moment.d.ts","sourceRoot":"","sources":["../../../../src/schedule/resolve-moment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA0B,CAAC;AAE/D,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAExC,MAAM,MAAM,gBAAgB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhF;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAyB/E;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAoB3D"}

package/lib/typescript/module/schedule/validate-content.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Content validation.
+ *
+ * The package passes content through **unchanged** and never truncates it.
+ * Display truncation is the platform's decision and differs between them; a
+ * library that pre-truncated would be guessing at a rule it does not own, and
+ * would corrupt content that would have displayed fine.
+ *
+ * What it does refuse is content over the platform's hard payload limit, where
+ * the alternative is not a shortened notification but a failed or undefined
+ * delivery. That is a real error and is reported as one, before any platform
+ * call.
+ */
+import type { NotificationContent } from '../contract/notification.js';
+/**
+ * Hard payload ceilings.
+ *
+ * These are *not* display limits. A title longer than a phone shows is fine and
+ * is passed through; the README documents where each platform visually
+ * truncates so a caller can decide for itself.
+ *
+ * The total is deliberately lower than the sum of the parts, so it actually
+ * binds — a per-field check that can never be exceeded in aggregate would be
+ * dead code. It sits under the 4 KB payload budget both platforms enforce,
+ * leaving headroom for the routing payload that shares it.
+ */
+export declare const CONTENT_LIMITS: {
+    readonly maxTitleBytes: 512;
+    readonly maxBodyBytes: 3072;
+    readonly maxSubtitleBytes: 512;
+    readonly maxTotalBytes: 3584;
+};
+/** UTF-8 byte length — the unit the platforms actually bound. */
+export declare function byteLength(value: string): number;
+/**
+ * Validates content and returns it **byte-identical**.
+ *
+ * The return value is the same object reference where possible, so nothing
+ * downstream can mistake this for a transformation step.
+ */
+export declare function validateContent(content: NotificationContent): NotificationContent;
+//# sourceMappingURL=validate-content.d.ts.map

package/lib/typescript/module/schedule/validate-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-content.d.ts","sourceRoot":"","sources":["../../../../src/schedule/validate-content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA0B,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC;AAEX,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUhD;AAaD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,mBAAmB,CA4CjF"}

package/lib/typescript/module/schedule/validate-identifier.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Identifier validation.
+ *
+ * Identity is the caller's contract: only the caller can derive an identifier
+ * reproducibly from its own data, so the package never generates one.
+ *
+ * The charset is composite-friendly because real derived keys are hierarchical
+ * — `task:1234:reminder:2`. A charset that forced encoding of natural keys
+ * would work against caller-supplied identity being readable and reproducible,
+ * which is most of its value.
+ *
+ * Nothing is normalized, trimmed, case-folded, or hashed. Two identifiers
+ * differing in any character are different identifiers, and the value visible
+ * at the platform boundary is exactly what the caller supplied — which is what
+ * lets a notification be traced back to the data that produced it.
+ */
+export declare const MAX_IDENTIFIER_LENGTH = 128;
+export type IdentifierKind = 'id' | 'ownerTag' | 'groupTag' | 'seriesId' | 'actionId';
+/**
+ * Throws a typed error naming the violated rule.
+ *
+ * The offending character and its position are reported; the value itself never
+ * is, because an identifier can carry user data a caller derived it from.
+ */
+export declare function validateIdentifier(value: unknown, kind?: IdentifierKind): string;
+/** Non-throwing form, for validating a batch without unwinding on the first failure. */
+export declare function isValidIdentifier(value: unknown): value is string;
+/** Validates an optional tag, returning undefined when absent rather than failing. */
+export declare function validateOptionalTag(value: string | undefined, kind: Extract<IdentifierKind, 'ownerTag' | 'groupTag'>): string | undefined;
+//# sourceMappingURL=validate-identifier.d.ts.map

package/lib/typescript/module/schedule/validate-identifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-identifier.d.ts","sourceRoot":"","sources":["../../../../src/schedule/validate-identifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAgBzC,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;AA0BtF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,cAAqB,GAAG,MAAM,CAsCtF;AAED,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CASjE;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,IAAI,EAAE,OAAO,CAAC,cAAc,EAAE,UAAU,GAAG,UAAU,CAAC,GACpD,MAAM,GAAG,SAAS,CAGpB"}

package/lib/typescript/module/schedule/writer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The one door every consumer notification goes through to reach the engine.
+ *
+ * Scheduler, reconciler, recurrence, re-anchoring and channel re-homing all
+ * write notifications. Each used to call `engine.schedule` itself, and the
+ * guarantees attached to a write — a repeating alert gets its stop marker, and
+ * that marker moves when the notification moves — existed only on the paths
+ * that remembered them. A recurring alarm never stopped, and a re-anchored one
+ * stopped at the old instant.
+ *
+ * Validation stays with each caller, because each has its own failure policy:
+ * the scheduler throws, reconciliation rejects one entry and carries on, and
+ * recurrence validates its template once at registration.
+ */
+import type { NotificationEngineAdapter, EngineScheduleRequest } from '../engine/adapter.js';
+export interface ScheduleWriter {
+    /** Writes one notification and brings its stop marker in line with it. */
+    write(input: EngineScheduleRequest): Promise<void>;
+    /** Cancels one notification and the marker guarding it. */
+    cancel(id: string): Promise<void>;
+    /** Drops the marker for a notification already cancelled some other way. */
+    releaseStop(targetId: string): Promise<void>;
+    /**
+     * Platform slots consumer notifications can actually use: stop markers hold
+     * real capacity, so the usable ceiling is the platform's minus theirs.
+     */
+    capacity(): Promise<number>;
+    /**
+     * A writer for one pass of many writes (NOT-08): it reads the outstanding stop
+     * markers once and keeps that view current, instead of a full read of every
+     * pending trigger per operation.
+     */
+    pass(): ScheduleWriter;
+}
+export declare function createScheduleWriter(engine: NotificationEngineAdapter): ScheduleWriter;
+//# sourceMappingURL=writer.d.ts.map

package/lib/typescript/module/schedule/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../../../src/schedule/writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,sBAAmB,CAAC;AAG1F,MAAM,WAAW,cAAc;IAC9B,0EAA0E;IAC1E,KAAK,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,2DAA2D;IAC3D,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,4EAA4E;IAC5E,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C;;;OAGG;IACH,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B;;;;OAIG;IACH,IAAI,IAAI,cAAc,CAAC;CACvB;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,yBAAyB,GAAG,cAAc,CAEtF"}

package/lib/typescript/module/state/caps.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Caps and eviction for the persisted collections.
+ *
+ * No collection may grow without bound. Eviction is oldest-first and always
+ * observable — a silent eviction would turn a bounded guarantee into an
+ * unexplained one.
+ */
+/** Every persisted collection with a size or age bound. */
+export declare const COLLECTION_CAPS: {
+    readonly dedupLedger: {
+        readonly maxEntries: 500;
+        readonly retentionMs: number;
+    };
+    readonly interactionBuffer: {
+        readonly maxEntries: 50;
+        readonly retentionMs: number;
+    };
+    readonly migrationLedger: {
+        readonly maxEntries: 20;
+        readonly retentionMs: number;
+    };
+    readonly seriesLedger: {
+        readonly maxEntries: 32;
+        readonly retentionMs: number;
+    };
+    readonly permissionHistory: {
+        readonly maxEntries: 64;
+        readonly retentionMs: number;
+    };
+};
+export type CollectionName = keyof typeof COLLECTION_CAPS;
+/** Anything stored with a timestamp, which is everything that can age out. */
+export interface Timestamped {
+    readonly at: number;
+}
+export interface EvictionOutcome<T> {
+    readonly kept: readonly T[];
+    readonly evicted: readonly T[];
+    readonly reason: 'none' | 'cap' | 'retention' | 'cap+retention';
+    /** Entries kept beyond the cap because none of them may be evicted (NOT-16). */
+    readonly overCap: number;
+}
+/**
+ * Applies retention first, then the size cap.
+ *
+ * Order matters: expiring stale entries before trimming means a burst of new
+ * entries does not evict fresh ones while stale ones sit protected by
+ * recency ordering.
+ */
+export declare function evict<T extends Timestamped>(entries: readonly T[], collection: CollectionName, now: number): EvictionOutcome<T>;
+//# sourceMappingURL=caps.d.ts.map

package/lib/typescript/module/state/caps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caps.d.ts","sourceRoot":"","sources":["../../../../src/state/caps.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,2DAA2D;AAC3D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;CAMlB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,eAAe,CAAC;AAE1D,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,WAAW,GAAG,eAAe,CAAC;IAChE,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAaD;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,WAAW,EAC1C,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,UAAU,EAAE,cAAc,EAC1B,GAAG,EAAE,MAAM,GACT,eAAe,CAAC,CAAC,CAAC,CAyCpB"}

package/lib/typescript/module/state/dedup-ledger.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The push deduplication ledger.
+ *
+ * Providers redeliver. The redelivery typically arrives in a **fresh process**,
+ * which is precisely why this is persisted rather than held in memory — an
+ * in-memory set would forget exactly when it matters.
+ *
+ * Bounded by cap and retention. A payload redelivered after its entry has aged
+ * out is treated as new: that is the documented bound of the guarantee, not a
+ * defect.
+ */
+import type { StateManager } from './record.js';
+export declare function isDuplicate(state: StateManager, dedupId: string): boolean;
+/**
+ * Records a payload as seen.
+ *
+ * Returns true when it was already known, so a caller can branch on the same
+ * read that records it rather than checking twice.
+ */
+export declare function recordSeen(state: StateManager, dedupId: string, now: number, ownerTag?: string): boolean;
+//# sourceMappingURL=dedup-ledger.d.ts.map

package/lib/typescript/module/state/dedup-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup-ledger.d.ts","sourceRoot":"","sources":["../../../../src/state/dedup-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAU,CAAC;AAE7C,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACzB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,MAAM,GACf,OAAO,CAKT"}

package/lib/typescript/module/state/interaction-buffer.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The durable interaction buffer.
+ *
+ * A cold-start tap arrives before any handler exists. Holding it in memory
+ * would be enough if the process always survived — but the process is exactly
+ * what does not survive a cold start, so the buffer is persisted.
+ *
+ * This is the one content-bearing thing the package stores: an interaction
+ * cannot be delivered without its routing payload. It is evicted the moment it
+ * is delivered, and time-limited regardless, so an event nobody ever collects
+ * cannot sit on disk forever.
+ *
+ * Text the user typed into a reply action is never written to disk (NOT-14): it
+ * is free text, and the store is not encrypted. It is held in memory beside the
+ * buffer, so a handler registered later in the same process still receives it;
+ * if the process dies first, the event is delivered without `inputText`.
+ */
+import type { StateManager } from './record.js';
+import type { InteractionEvent } from '../contract/interaction.js';
+export declare function buffer(state: StateManager, event: InteractionEvent): void;
+/**
+ * Takes every buffered event in occurrence order and clears them.
+ *
+ * Draining and clearing together is deliberate: delivering an event twice is
+ * worse than the alternative, because a consumer that acts on an interaction
+ * (marking a task done, sending a reply) would act twice.
+ */
+export declare function drain(state: StateManager): readonly InteractionEvent[];
+export declare function bufferedCount(state: StateManager): number;
+//# sourceMappingURL=interaction-buffer.d.ts.map

package/lib/typescript/module/state/interaction-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction-buffer.d.ts","sourceRoot":"","sources":["../../../../src/state/interaction-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,aAAU,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAAyB,CAAC;AAmBhE,wBAAgB,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAoBzE;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,gBAAgB,EAAE,CAuBtE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAEzD"}

package/lib/typescript/module/state/mmkv-store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * MMKV-backed state store.
+ *
+ * Every MMKV import is confined to this file, so the rest of the package stays
+ * testable without a native module.
+ *
+ * Backup exclusion is achieved by *where* the data lives rather than by setting
+ * a file attribute: on iOS the instance is rooted under `Library/Caches`, which
+ * the platform excludes from iCloud and iTunes backup by design. The OS may
+ * purge that directory under storage pressure — acceptable here precisely
+ * because discarding and rebuilding this record is already a specified,
+ * non-blocking condition.
+ *
+ * On Android, backup exclusion is declared in the consuming app's
+ * `data_extraction_rules.xml` and `full_backup_content`, documented in the
+ * README. It is the app's manifest, so it is the app's declaration to make.
+ */
+import type { StateStore } from './store.js';
+export interface MmkvStoreOptions {
+    /** Told once, with the reason, when the store falls back to memory. */
+    readonly onDegraded?: (cause: unknown) => void;
+}
+/**
+ * Creates the persistent store, falling back to memory when MMKV is absent.
+ *
+ * The fallback is deliberate: a missing optional native module degrades
+ * deduplication and cold-start buffering to session scope, which is a
+ * documented degradation. It must never stop notifications being delivered, and
+ * it is never silent (NOT-15): it reports `STATE_STORE_DEGRADED` to the app's SDK
+ * sinks and to `onDegraded`, and the store reports `durable: false`.
+ */
+export declare function createMmkvStore(options?: MmkvStoreOptions): StateStore;
+//# sourceMappingURL=mmkv-store.d.ts.map

package/lib/typescript/module/state/mmkv-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mmkv-store.d.ts","sourceRoot":"","sources":["../../../../src/state/mmkv-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAWH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAS,CAAC;AAiB1C,MAAM,WAAW,gBAAgB;IAChC,uEAAuE;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC/C;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,UAAU,CAiC1E"}

package/lib/typescript/module/state/permission-history.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Permission-request history.
+ *
+ * The platform cannot tell you whether you have already asked. On both
+ * platforms a second request after a denial is silently a no-op, so an app that
+ * does not remember will keep "asking" and keep appearing to be refused.
+ *
+ * Keyed by owner tag so a multi-account device can clear one account's history
+ * on sign-out without forgetting what it asked the others.
+ */
+import type { StateManager } from './record.js';
+import type { PermissionKind } from '../contract/permission.js';
+export declare function hasRequested(state: StateManager, kind: PermissionKind, ownerTag?: string): boolean;
+export declare function recordRequested(state: StateManager, kind: PermissionKind, now: number, ownerTag?: string): void;
+/** How many requests for `kind` the user has refused on this device. */
+export declare function denialCount(state: StateManager, kind: PermissionKind): number;
+export declare function recordDenial(state: StateManager, kind: PermissionKind, now: number): void;
+/** Forgets refusals once the permission is seen granted: the next refusal starts over. */
+export declare function clearDenials(state: StateManager, kind: PermissionKind): void;
+//# sourceMappingURL=permission-history.d.ts.map

package/lib/typescript/module/state/permission-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-history.d.ts","sourceRoot":"","sources":["../../../../src/state/permission-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAAwB,CAAC;AAM7D,wBAAgB,YAAY,CAC3B,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,cAAc,EACpB,QAAQ,CAAC,EAAE,MAAM,GACf,OAAO,CAGT;AAED,wBAAgB,eAAe,CAC9B,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,cAAc,EACpB,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,MAAM,GACf,IAAI,CAQN;AAKD,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,GAAG,MAAM,CAG7E;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAOzF;AAED,0FAA0F;AAC1F,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAI5E"}