@chipmobilesdk/rn-notification 0.6.0 → 0.7.0

package/lib/typescript/commonjs/contract/diagnostics.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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.
+ */
+import type { PermissionReport, RestrictionReport } from './permission';
+import type { PendingDiscrepancy, MaintenanceResult, ReconcileResult } from './reconcile';
+import type { ToneDeclaration, ChannelGroup } from './channel';
+import type { LookaheadConfig } from './recurrence';
+import type { PendingEntry } from './notification';
+export type DiagnosticSeverity = 'debug' | 'info' | 'warn' | 'error';
+export interface DiagnosticEvent {
+    /** Stable identifier, safe to switch on. See contracts/errors.md. */
+    readonly code: string;
+    readonly severity: DiagnosticSeverity;
+    readonly message: string;
+    readonly at: number;
+    /**
+     * Structured context. Never contains notification body text, routing payload
+     * values, or push tokens unless verbose diagnostics is explicitly enabled.
+     */
+    readonly context?: Readonly<Record<string, unknown>>;
+}
+export type EventSink = (event: DiagnosticEvent) => void;
+/** Health of one persisted collection against its cap. */
+export interface CollectionHealth {
+    readonly name: string;
+    readonly size: number;
+    readonly cap: number;
+    readonly oldestEntryAt?: number;
+}
+export interface StateHealth {
+    readonly readable: boolean;
+    /** True when the record was discarded and rebuilt, e.g. after corruption. */
+    readonly rebuilt: boolean;
+    readonly collections: readonly CollectionHealth[];
+    readonly approximateBytes: number;
+}
+/** The readable answer to "why didn't it arrive". */
+export interface StateSnapshot {
+    readonly permissions: PermissionReport;
+    readonly restrictions: RestrictionReport;
+    readonly tones: readonly {
+        readonly id: string;
+        readonly appliedVersion: number;
+    }[];
+    readonly pendingCount: number;
+    readonly pending: readonly PendingEntry[];
+    readonly lastReconcile?: ReconcileResult;
+    readonly lastMaintenance?: MaintenanceResult;
+    readonly discrepancy?: PendingDiscrepancy;
+    readonly stateHealth: StateHealth;
+    /** Presence only. The token value is never exposed here or anywhere else. */
+    readonly pushTokenPresent: boolean;
+    readonly capturedAt: number;
+}
+/** Abnormal notification volume. Reported, never acted upon. */
+export interface BurstThreshold {
+    readonly perMinute: number;
+    readonly perHour: number;
+}
+export declare const DEFAULT_BURST_THRESHOLD: BurstThreshold;
+export interface NotificationConfig {
+    /** Every tone, category, and channel in one place. */
+    readonly tones: readonly ToneDeclaration[];
+    readonly channelGroups?: readonly ChannelGroup[];
+    readonly lookahead?: Partial<LookaheadConfig>;
+    /**
+     * Automatic maintenance covers only what the package alone can know:
+     * window refresh, expansion, re-anchoring, verification, permission re-read.
+     * Full desired-set reconciliation is never automatic. Defaults to true.
+     */
+    readonly automaticMaintenance?: boolean;
+    readonly burstThreshold?: BurstThreshold;
+    /** With no sink supplied the package emits nothing rather than writing to a console. */
+    readonly eventSink?: EventSink;
+    /**
+     * Includes content values in diagnostics. Documented as unsuitable for
+     * production, and off by default.
+     */
+    readonly verboseDiagnostics?: boolean;
+}
+export interface InitializeResult {
+    readonly tonesApplied: number;
+    readonly migrationsRun: number;
+    readonly stateRebuilt: boolean;
+    readonly automaticMaintenance: boolean;
+    readonly durationMs: number;
+}
+//# sourceMappingURL=diagnostics.d.ts.map

package/lib/typescript/commonjs/contract/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../../src/contract/diagnostics.ts"],"names":[],"mappings":"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"}

package/lib/typescript/commonjs/contract/errors.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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';
+export declare const DIAGNOSTIC_CODES: {
+    readonly INVALID_ID_EMPTY: "INVALID_ID_EMPTY";
+    readonly INVALID_ID_LENGTH: "INVALID_ID_LENGTH";
+    readonly INVALID_ID_CHARSET: "INVALID_ID_CHARSET";
+    readonly INVALID_OWNER_TAG: "INVALID_OWNER_TAG";
+    readonly INVALID_GROUP_TAG: "INVALID_GROUP_TAG";
+    readonly MOMENT_IN_PAST: "MOMENT_IN_PAST";
+    readonly UNDECLARED_TONE: "UNDECLARED_TONE";
+    readonly ROUTING_PAYLOAD_TOO_LARGE: "ROUTING_PAYLOAD_TOO_LARGE";
+    readonly CONTENT_TOO_LARGE: "CONTENT_TOO_LARGE";
+    readonly TOO_MANY_ACTIONS: "TOO_MANY_ACTIONS";
+    readonly INVALID_RECURRENCE: "INVALID_RECURRENCE";
+    readonly INVALID_TONE_REPEAT: "INVALID_TONE_REPEAT";
+    readonly DUPLICATE_IDENTIFIER: "DUPLICATE_IDENTIFIER";
+    readonly TRUNCATED_OVER_CEILING: "TRUNCATED_OVER_CEILING";
+    readonly RECONCILE_INTERRUPTED: "RECONCILE_INTERRUPTED";
+    readonly PENDING_SET_DISCREPANCY: "PENDING_SET_DISCREPANCY";
+    readonly DISPLAY_PERMISSION_DENIED: "DISPLAY_PERMISSION_DENIED";
+    readonly DISPLAY_PERMISSION_PERMANENT: "DISPLAY_PERMISSION_PERMANENT";
+    readonly EXACT_ALARM_UNAVAILABLE: "EXACT_ALARM_UNAVAILABLE";
+    readonly SETTINGS_UNAVAILABLE: "SETTINGS_UNAVAILABLE";
+    readonly BACKGROUND_RESTRICTED: "BACKGROUND_RESTRICTED";
+    readonly BACKGROUND_RESTRICTION_UNKNOWN: "BACKGROUND_RESTRICTION_UNKNOWN";
+    readonly CHANNEL_MIGRATION_REQUIRED: "CHANNEL_MIGRATION_REQUIRED";
+    readonly CHANNEL_MIGRATION_FAILED: "CHANNEL_MIGRATION_FAILED";
+    readonly CHANNEL_ORPHANS_FOUND: "CHANNEL_ORPHANS_FOUND";
+    readonly DND_BYPASS_UNAVAILABLE: "DND_BYPASS_UNAVAILABLE";
+    readonly TONE_LABELS_REFRESHED: "TONE_LABELS_REFRESHED";
+    readonly REPEAT_ALERT_UNAVAILABLE: "REPEAT_ALERT_UNAVAILABLE";
+    readonly REPEAT_STOP_HANDLER_MISSING: "REPEAT_STOP_HANDLER_MISSING";
+    readonly TARGET_MISSING: "TARGET_MISSING";
+    readonly INTERACTION_BUFFER_EVICTED: "INTERACTION_BUFFER_EVICTED";
+    readonly BACKGROUND_WINDOW_EXCEEDED: "BACKGROUND_WINDOW_EXCEEDED";
+    readonly PUSH_UNAVAILABLE: "PUSH_UNAVAILABLE";
+    readonly TOKEN_UNAVAILABLE: "TOKEN_UNAVAILABLE";
+    readonly TOKEN_INVALIDATION_FAILED: "TOKEN_INVALIDATION_FAILED";
+    readonly PAYLOAD_MALFORMED: "PAYLOAD_MALFORMED";
+    readonly PAYLOAD_VERSION_SKEW: "PAYLOAD_VERSION_SKEW";
+    readonly PAYLOAD_DUPLICATE: "PAYLOAD_DUPLICATE";
+    readonly PUSH_UNDELIVERABLE: "PUSH_UNDELIVERABLE";
+    readonly STATE_CORRUPT_REBUILT: "STATE_CORRUPT_REBUILT";
+    readonly STATE_WRITE_FAILED: "STATE_WRITE_FAILED";
+    /** The durable store could not open; state lasts for this session only. */
+    readonly STATE_STORE_DEGRADED: "STATE_STORE_DEGRADED";
+    readonly 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.
+     */
+    readonly STATE_CAP_EXCEEDED: "STATE_CAP_EXCEEDED";
+    readonly BURST_THRESHOLD_EXCEEDED: "BURST_THRESHOLD_EXCEEDED";
+    /** An automatic maintenance cycle threw. Reported here because no caller awaits it. */
+    readonly MAINTENANCE_FAILED: "MAINTENANCE_FAILED";
+};
+export type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[keyof typeof DIAGNOSTIC_CODES];
+/** Every identifier, for exhaustiveness tests and the documentation table. */
+export declare const ALL_DIAGNOSTIC_CODES: readonly DiagnosticCode[];
+/**
+ * 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 declare class NotificationError extends SdkError<DiagnosticCode> {
+    readonly context?: Readonly<Record<string, unknown>>;
+    constructor(code: DiagnosticCode, message: string, context?: Readonly<Record<string, unknown>>);
+}
+export declare function isNotificationError(value: unknown): value is NotificationError;
+/**
+ * Conditions that are reported outcomes rather than failures: the operation
+ * succeeded, and something the caller needs to know happened alongside it.
+ */
+export declare const NON_FAILURE_CODES: readonly DiagnosticCode[];
+export declare function isNonFailure(code: DiagnosticCode): boolean;
+//# sourceMappingURL=errors.d.ts.map

package/lib/typescript/commonjs/contract/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/contract/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAIlD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAuD5B,2EAA2E;;;IAG3E;;;;OAIG;;;IAOH,uFAAuF;;CAE9E,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAEtF,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,EAAE,SAAS,cAAc,EAEzD,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ,CAAC,cAAc,CAAC;IAC9D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;gBAEzC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAU9F;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAE9E;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAgBrD,CAAC;AAEH,wBAAgB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAE1D"}

package/lib/typescript/commonjs/contract/hash.d.ts

@@ -0,0 +1,14 @@
+/**
+ * FNV-1a, 32-bit: the package's one hash (NOT-19). Deterministic,
+ * dependency-free, and stable across releases.
+ *
+ * Bitwise operators are the algorithm, not a micro-optimisation: arithmetic
+ * equivalents would not wrap to 32 bits. Stability matters: a marker id or a
+ * label fingerprint that changed between releases would orphan every marker
+ * already scheduled, or refresh every channel label once more.
+ */
+export declare const FNV_OFFSET_BASIS = 2166136261;
+export declare function fnv1a(value: string, basis?: number): number;
+/** Eight lowercase hex digits. */
+export declare function hex8(value: number): string;
+//# sourceMappingURL=hash.d.ts.map

package/lib/typescript/commonjs/contract/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../../../src/contract/hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,aAAa,CAAC;AAG3C,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAyB,GAAG,MAAM,CAO7E;AAGD,kCAAkC;AAClC,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1C"}

package/lib/typescript/commonjs/contract/index.d.ts

@@ -0,0 +1,10 @@
+/** Public contract types. Types only — no logic lives in this layer. */
+export * from './notification';
+export * from './recurrence';
+export * from './reconcile';
+export * from './permission';
+export * from './channel';
+export * from './interaction';
+export * from './diagnostics';
+export * from './errors';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/commonjs/contract/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/contract/index.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAExE,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC"}

package/lib/typescript/commonjs/contract/interaction.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Interaction types.
+ *
+ * One event shape covers foreground, background, and cold start, so a consumer
+ * writes one handler. Events that occur before a handler registers are buffered
+ * durably and delivered on registration — the cold-start case is the one most
+ * integrations quietly get wrong.
+ */
+import type { RoutingPayload } from './notification';
+export type InteractionKind = 'tap' | 'action' | 'dismiss';
+/** Which app state the interaction arrived in. Informational; the shape never varies. */
+export type AppStateAtInteraction = 'foreground' | 'background' | 'coldStart';
+export interface InteractionEvent {
+    readonly kind: InteractionKind;
+    readonly notificationId: string;
+    /** Present when `kind` is `action`. */
+    readonly actionId?: string;
+    /** Present when the action accepted typed input. */
+    readonly inputText?: string;
+    /** Round-trips unchanged from schedule time. */
+    readonly routing?: RoutingPayload;
+    readonly ownerTag?: string;
+    readonly occurredAt: number;
+    readonly appState: AppStateAtInteraction;
+    /**
+     * True when the event was held in the durable buffer before a handler
+     * existed to receive it — including across a process death.
+     */
+    readonly wasBuffered: boolean;
+}
+/**
+ * Signals the routing target no longer exists.
+ *
+ * The consumer chooses its own fallback screen. A platform error is never
+ * shown to the user for this — a notification pointing at deleted data is an
+ * ordinary condition, not a crash.
+ */
+export interface TargetMissingSignal {
+    readonly notificationId: string;
+    readonly routing?: RoutingPayload;
+}
+export type InteractionHandler = (event: InteractionEvent) => void | Promise<void>;
+export type Unsubscribe = () => void;
+/** Limits on the durable interaction buffer, so it can never grow without bound. */
+export declare const INTERACTION_BUFFER_LIMITS: {
+    readonly maxEntries: 50;
+    readonly retentionMs: number;
+};
+/** Maximum size of a routing payload, validated at schedule time rather than discovered at tap time. */
+export declare const MAX_ROUTING_PAYLOAD_BYTES: number;
+/** Maximum action buttons on one notification. */
+export declare const MAX_ACTIONS_PER_NOTIFICATION = 10;
+//# sourceMappingURL=interaction.d.ts.map

package/lib/typescript/commonjs/contract/interaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction.d.ts","sourceRoot":"","sources":["../../../../src/contract/interaction.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE3D,yFAAyF;AACzF,MAAM,MAAM,qBAAqB,GAAG,YAAY,GAAG,YAAY,GAAG,WAAW,CAAC;AAE9E,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;CAClC;AAED,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnF,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC,oFAAoF;AACpF,eAAO,MAAM,yBAAyB;;;CAG5B,CAAC;AAEX,wGAAwG;AACxG,eAAO,MAAM,yBAAyB,QAAW,CAAC;AAElD,kDAAkD;AAClD,eAAO,MAAM,4BAA4B,KAAK,CAAC"}

package/lib/typescript/commonjs/contract/notification.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Core notification request types.
+ *
+ * Nothing here carries business meaning. The package accepts fully-described
+ * requests and is responsible only for delivering them at the right moment.
+ */
+/**
+ * How a delivery moment is pinned to the passage of time.
+ *
+ * - `wallClock` — the local clock time named. An 08:00 reminder stays 08:00
+ *   after the user crosses a time zone. This is the default, because reminders
+ *   are wall-clock things and a caller who does not choose should get what
+ *   their users expect.
+ * - `absolute` — one fixed instant worldwide, unaffected by zone changes.
+ */
+export type AnchoringMode = 'wallClock' | 'absolute';
+export declare const DEFAULT_ANCHORING_MODE: AnchoringMode;
+/** When a notification should be presented, and how that moment is anchored. */
+export interface DeliveryMoment {
+    /** Epoch milliseconds. Interpreted per {@link DeliveryMoment.anchoring}. */
+    readonly at: number;
+    /** Defaults to `wallClock` when omitted. */
+    readonly anchoring?: AnchoringMode;
+}
+/**
+ * Resolved display strings. The package performs no translation, formatting,
+ * or locale resolution — only the consuming app knows its content model.
+ */
+export interface NotificationContent {
+    readonly title: string;
+    readonly body: string;
+    /** Optional short text shown in collapsed form on some platforms. */
+    readonly subtitle?: string;
+}
+/** Structured data carried to the interaction handler, unchanged. */
+export type RoutingPayload = Readonly<Record<string, unknown>>;
+/** A button on a notification. */
+export interface Action {
+    /** Stable action identifier, subject to the same charset rules as a notification id. */
+    readonly id: string;
+    readonly title: string;
+    /**
+     * `foreground` brings the app up; `background` is handled without opening it,
+     * inside the platform's bounded execution window.
+     */
+    readonly mode: 'foreground' | 'background';
+    /** When present, the action accepts short typed input. */
+    readonly input?: {
+        readonly placeholder?: string;
+        readonly submitLabel?: string;
+    };
+}
+/** The complete, self-contained description of one notification. */
+export interface NotificationRequest {
+    /**
+     * Caller-supplied, stable, derived from the caller's own data.
+     * The package never generates, normalizes, or hashes it.
+     */
+    readonly id: string;
+    readonly content: NotificationContent;
+    /** Must reference a tone declared in the package configuration. */
+    readonly tone: string;
+    readonly moment: DeliveryMoment;
+    readonly routing?: RoutingPayload;
+    readonly actions?: readonly Action[];
+    /** Opaque partition label. Never interpreted by the package. */
+    readonly ownerTag?: string;
+    /** Opaque cancellation group. Never interpreted by the package. */
+    readonly groupTag?: string;
+}
+/** One entry the platform is currently holding, in enough detail to diff against intent. */
+export interface PendingEntry {
+    readonly id: string;
+    /** The instant the platform will actually fire, after anchoring resolution. */
+    readonly resolvedAt: number;
+    readonly anchoring: AnchoringMode;
+    /**
+     * The IANA zone this entry was last anchored against.
+     * `undefined` for absolute-instant entries, which are never anchored.
+     *
+     * Exists so the one case re-anchoring cannot fix — a zone change while the
+     * app never ran — is detectable rather than invisible.
+     */
+    readonly anchoringGeneration?: string;
+    readonly content: NotificationContent;
+    readonly tone: string;
+    readonly routing?: RoutingPayload;
+    readonly actions?: readonly Action[];
+    readonly ownerTag?: string;
+    readonly groupTag?: string;
+    /** Present when this entry was expanded from a recurrence series. */
+    readonly seriesId?: string;
+    /** True when scheduled without exact-alarm capability; delivery may be late. */
+    readonly mayBeDelayed: boolean;
+    /** True when created by a push instruction rather than by app code. */
+    readonly pushCreated: boolean;
+}
+/** Outcome of a single schedule call. */
+export interface ScheduleResult {
+    readonly id: string;
+    readonly resolvedAt: number;
+    readonly anchoring: AnchoringMode;
+    /** True when an existing notification under this identifier was replaced. */
+    readonly replaced: boolean;
+    /** True when the moment had just passed and was delivered inside the tolerance window. */
+    readonly deliveredImmediately: boolean;
+    /** True when scheduled in approximate mode for want of exact-alarm capability. */
+    readonly mayBeDelayed: boolean;
+}
+//# sourceMappingURL=notification.d.ts.map

package/lib/typescript/commonjs/contract/notification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification.d.ts","sourceRoot":"","sources":["../../../../src/contract/notification.ts"],"names":[],"mappings":"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"}

package/lib/typescript/commonjs/contract/permission.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Permission types.
+ *
+ * Display permission and exact-alarm permission are different things serving
+ * different purposes, so they are requested and reported independently. State
+ * is always readable without triggering a dialog.
+ */
+export type PermissionKind = 'display' | 'exactAlarm';
+/**
+ * Six states, never collapsed into one another.
+ *
+ * - `notAsked` — distinguishable from `denied`, which is the whole point of
+ *   being able to read state without prompting.
+ * - `provisional` — iOS quiet delivery. Neither granted nor denied.
+ * - `notRequired` — the running platform version has no such concept. Never
+ *   reported as `denied`, which would imply a refusal that never happened.
+ */
+export type PermissionState = 'notAsked' | 'granted' | 'denied' | 'permanentlyDenied' | 'provisional' | 'notRequired';
+export interface PermissionReport {
+    readonly display: PermissionState;
+    readonly exactAlarm: PermissionState;
+    readonly readAt: number;
+}
+/** Whether a manufacturer-level restriction is in force, where it can be known. */
+export type RestrictionStatus = 'unrestricted' | 'restricted' | 'unknown';
+/**
+ * Manufacturer background restrictions, reported for information only.
+ *
+ * `unknown` is a first-class answer: some vendors stop apps in ways with no
+ * standard detection API, and guessing would be worse than admitting it.
+ * The package never changes any of these settings on the user's behalf.
+ */
+export interface RestrictionReport {
+    readonly batteryOptimization: RestrictionStatus;
+    readonly autoStart: RestrictionStatus;
+    readonly manufacturer?: string;
+    readonly readAt: number;
+}
+/** Whether a permission request can even be presented on this platform version. */
+export interface PermissionCapability {
+    readonly kind: PermissionKind;
+    readonly supported: boolean;
+    /**
+     * True when the platform grants this only through system settings rather
+     * than an in-app dialog.
+     */
+    readonly settingsOnly: boolean;
+}
+//# sourceMappingURL=permission.d.ts.map

package/lib/typescript/commonjs/contract/permission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.d.ts","sourceRoot":"","sources":["../../../../src/contract/permission.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,YAAY,CAAC;AAEtD;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAC1B,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,mBAAmB,GAAG,aAAa,GAAG,aAAa,CAAC;AAEzF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,mFAAmF;AACnF,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG,YAAY,GAAG,SAAS,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,mBAAmB,EAAE,iBAAiB,CAAC;IAChD,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,mFAAmF;AACnF,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAC/B"}

package/lib/typescript/commonjs/contract/reconcile.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Reconciliation types.
+ *
+ * A caller hands over the complete set its data currently implies; the package
+ * computes the minimal operation set that makes the device match. Running it
+ * twice with unchanged input performs zero platform operations — that
+ * idempotence is the package's central testable promise.
+ */
+import type { NotificationRequest } from './notification';
+export interface ReconcileInput {
+    /**
+     * Bounds what may be cancelled. Notifications outside this domain are never
+     * touched, including those scheduled by other parts of the app or by other
+     * libraries.
+     */
+    readonly domain: string;
+    readonly desired: readonly NotificationRequest[];
+    /**
+     * When false (the default), push-created notifications are left alone rather
+     * than cancelled for being absent from a locally-computed desired set.
+     */
+    readonly includePushCreated?: boolean;
+}
+/** Why a desired entry was refused rather than applied. */
+export interface RejectedEntry {
+    readonly id: string;
+    readonly code: string;
+    readonly reason: string;
+    /** How many times this identifier appeared in the desired set. */
+    readonly occurrences: number;
+    /**
+     * True when a notification already scheduled under this identifier was left
+     * in place. Stated explicitly so a rejection is never misread as a
+     * cancellation.
+     */
+    readonly existingLeftInPlace: boolean;
+}
+/** What was dropped for exceeding the platform's pending ceiling. */
+export interface TruncationReport {
+    readonly ceiling: number;
+    readonly droppedCount: number;
+    readonly droppedIds: readonly string[];
+    /**
+     * Dropped entries are not lost — they are re-evaluated at each window
+     * refresh as nearer entries deliver.
+     */
+    readonly reEvaluatedOnNextRefresh: true;
+}
+export interface ReconcileResult {
+    readonly domain: string;
+    readonly created: readonly string[];
+    readonly replaced: readonly string[];
+    readonly cancelled: readonly string[];
+    readonly unchanged: readonly string[];
+    readonly rejected: readonly RejectedEntry[];
+    readonly truncated?: TruncationReport;
+    /** Total platform operations issued. Zero on a no-change pass. */
+    readonly operationCount: number;
+    readonly durationMs: number;
+}
+/** A discrepancy between what the package expects and what the platform holds. */
+export interface PendingDiscrepancy {
+    /** Expected from the series ledger or last reconciliation, but absent. */
+    readonly missing: readonly string[];
+    /** Present on the platform but not recognized by the package. */
+    readonly unrecognized: readonly string[];
+    readonly detectedAt: number;
+}
+/** Outcome of one automatic maintenance cycle. */
+export interface MaintenanceResult {
+    readonly ranAt: number;
+    readonly windowRefreshed: boolean;
+    readonly occurrencesScheduled: number;
+    readonly reAnchored: number;
+    readonly timeZoneChanged: boolean;
+    readonly permissionChanged: boolean;
+    /** Detected and reported only — never repaired. */
+    readonly discrepancy?: PendingDiscrepancy;
+    readonly operationCount: number;
+    readonly durationMs: number;
+}
+//# sourceMappingURL=reconcile.d.ts.map

package/lib/typescript/commonjs/contract/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../../../src/contract/reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACtC;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;CACtC;AAED,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,wBAAwB,EAAE,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IACtC,kEAAkE;IAClE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAED,kFAAkF;AAClF,MAAM,WAAW,kBAAkB;IAClC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAED,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,mDAAmD;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAC1C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B"}