@de-otio/trellis 0.10.11 → 0.12.0

package/dist/lib/realtime/channel.js

@@ -0,0 +1,100 @@
+// CONTRACT: stable — coordinate changes. See types.ts banner.
+//
+// Channel naming + the subscription authorization boundary. Per §2.1/§2.2 of
+// the frozen contract, the canonical path is produced ONLY by `channelName()`
+// and parsed ONLY by `parseChannel()`; `authorizeSubscription()` is THE
+// security boundary — identity comes from a VerifiedIdentity (Cognito claims),
+// never an ambient Session and never a client-asserted path.
+/** Canonical path grammar: /{kind}/{tenantId}/{scopeType}/{scopeId}. */
+const VALID_KINDS = new Set([
+    "wakeup",
+    "setting_sync",
+    "safety",
+    "message",
+    "thread",
+]);
+const VALID_SCOPE_TYPES = new Set([
+    "user",
+    "conversation",
+    "thread",
+]);
+/** A path segment may not be empty and may not contain a path separator. */
+function isValidSegment(s) {
+    return s.length > 0 && !s.includes("/");
+}
+/**
+ * Produce the canonical channel path. This is the ONLY way a channel string is
+ * minted server-side; the Skybber `@skybber/realtime-channels` parser must
+ * round-trip this output.
+ */
+export function channelName(c) {
+    if (!VALID_KINDS.has(c.kind)) {
+        throw new Error(`channelName: invalid kind "${String(c.kind)}"`);
+    }
+    if (!VALID_SCOPE_TYPES.has(c.scopeType)) {
+        throw new Error(`channelName: invalid scopeType "${String(c.scopeType)}"`);
+    }
+    if (!isValidSegment(c.tenantId) || !isValidSegment(c.scopeId)) {
+        throw new Error("channelName: tenantId/scopeId must be non-empty, no slash");
+    }
+    return `/${c.kind}/${c.tenantId}/${c.scopeType}/${c.scopeId}`;
+}
+/**
+ * Parse a canonical channel path. Returns `null` on ANY malformed input — a
+ * leading-slash-less path, wrong arity, unknown kind/scopeType, or an empty
+ * segment.
+ */
+export function parseChannel(path) {
+    if (typeof path !== "string" || !path.startsWith("/"))
+        return null;
+    // Drop the leading "" produced by the leading slash; require exactly 4 parts.
+    const parts = path.split("/");
+    if (parts.length !== 5 || parts[0] !== "")
+        return null;
+    const [, kind, tenantId, scopeType, scopeId] = parts;
+    if (!VALID_KINDS.has(kind))
+        return null;
+    if (!VALID_SCOPE_TYPES.has(scopeType))
+        return null;
+    if (!isValidSegment(tenantId) || !isValidSegment(scopeId))
+        return null;
+    return {
+        kind: kind,
+        tenantId,
+        scopeType: scopeType,
+        scopeId,
+    };
+}
+/**
+ * Build a user-scoped channel (v1: the only scope). `kind` is constrained to
+ * the v1 user-scoped kinds; `message`/`thread` are deferred and excluded.
+ */
+export function channelFor(kind, scope) {
+    return {
+        kind,
+        tenantId: scope.tenantId,
+        scopeType: "user",
+        scopeId: scope.userId,
+    };
+}
+/**
+ * THE security boundary. The channel is a client *assertion* this checks
+ * against a server-verified identity.
+ *
+ * ALLOW iff `c.tenantId === id.tenantId` AND
+ *   scopeType "user"             -> `c.scopeId === id.userId`
+ *   scopeType conversation/thread -> membership(id.userId, c.scopeId) [v1: false]
+ *
+ * End-user PUBLISH is ALWAYS denied elsewhere (publish is server-only via IAM);
+ * this function governs SUBSCRIBE only.
+ */
+export function authorizeSubscription(id, c) {
+    if (c.tenantId !== id.tenantId)
+        return false;
+    if (c.scopeType === "user") {
+        return c.scopeId === id.userId;
+    }
+    // conversation / thread membership — DEFERRED in v1, deny.
+    return false;
+}
+//# sourceMappingURL=channel.js.map

package/dist/lib/realtime/channel.js.map

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

package/dist/lib/realtime/delivery-policy.d.ts

@@ -0,0 +1,51 @@
+import type { DeliveryContext, DeliveryDecision, DeliveryPolicyResolver } from "./types.js";
+import type { NotificationType } from "@prisma/client";
+/**
+ * Notification types that ALWAYS deliver — they bypass user preference and
+ * quiet hours. Migrated verbatim from `notification-handler.ts`'s
+ * `ALWAYS_DELIVER_TYPES`. This is the critical-always floor.
+ */
+export declare const ALWAYS_DELIVER_TYPES: ReadonlySet<NotificationType>;
+/**
+ * Track D runtime config for the floor. The minor-protection rule needs the set
+ * of "manipulative re-engagement" NotificationTypes to deny to non-adults. Per
+ * the threshold-secrecy invariant (CLAUDE.md rule 8) this list is RUNTIME CONFIG
+ * — passed in here, never a compiled-in constant sprinkled at a call site.
+ * v1 ships it EMPTY (no such type exists yet); a deployment populates it via env.
+ */
+export interface DeliveryFloorConfig {
+    /** NotificationTypes that re-engage and are denied to non-adult recipients. */
+    reengagementTypes?: ReadonlySet<NotificationType>;
+}
+/**
+ * The WS1 + Track D default resolver. Pure and synchronous over `DeliveryContext`
+ * (the caller does any async lookups and passes resolved signals in):
+ *
+ *  1. ALWAYS_DELIVER_TYPES (SAFETY_ALERT, PARENTAL_LINK) bypass everything ->
+ *     `{ deliver: true }`. Safety must NOT be over-blocked: this wins over the
+ *     blocked-sender and minor-protection floor below.
+ *  2. Non-configurable FLOOR (checked only when the caller supplies the input):
+ *       - blocked sender: the caller resolves block-set membership async (via
+ *         BlockStore) and populates `ctx.senderUserId` ONLY when the sender is
+ *         blocked — so presence of `senderUserId` == "in the recipient's block
+ *         set". The decision is a hard drop no preference can override.
+ *       - minor-protection: a non-adult recipient (`recipientAgeTier` CHILD/TEEN)
+ *         targeted by a configured re-engagement type is dropped.
+ *  3. Else honor preference (caller pre-resolves `deliver:false`/`preference`)
+ *     and quiet hours.
+ *
+ * Note on preference: in the existing handler the type-preference check happens
+ * BEFORE creating the row (preference-off => no row at all), which is a
+ * different outcome from quiet-hours (row created with deliveredAt=null). The
+ * caller maps the decision reasons accordingly. To keep the resolver pure and
+ * total it accepts the preference outcome via `ctx` indirectly: the caller only
+ * invokes the resolver's quiet-hours path once preference has passed. For a
+ * single source of truth the resolver still exposes the full decision so a
+ * push-only caller (WS4) can gate solely on it.
+ */
+export declare class CalmDeliveryResolver implements DeliveryPolicyResolver {
+    private readonly reengagementTypes;
+    constructor(config?: DeliveryFloorConfig);
+    decide(ctx: DeliveryContext): DeliveryDecision;
+}
+//# sourceMappingURL=delivery-policy.d.ts.map

package/dist/lib/realtime/delivery-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-policy.d.ts","sourceRoot":"","sources":["../../../src/lib/realtime/delivery-policy.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,gBAAgB,CAE3B,CAAC;AA8BrC;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,WAAW,CAAC,gBAAgB,CAAC,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,oBAAqB,YAAW,sBAAsB;IACjE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAgC;gBAEtD,MAAM,GAAE,mBAAwB;IAK5C,MAAM,CAAC,GAAG,EAAE,eAAe,GAAG,gBAAgB;CAgC/C"}

package/dist/lib/realtime/delivery-policy.js

@@ -0,0 +1,98 @@
+// CONTRACT: stable — coordinate changes. See types.ts banner.
+//
+// The DeliveryPolicyResolver port and the CalmDeliveryResolver default. Per §3
+// of the frozen contract, WS1 (not WS4) owns migrating the existing hardcoded
+// notification floor into CalmDeliveryResolver, under a golden test that pins
+// byte-identical behavior. The same resolver decision drives BOTH the
+// persistence `deliveredAt` choice AND the (default-off) push hand-off.
+/**
+ * Notification types that ALWAYS deliver — they bypass user preference and
+ * quiet hours. Migrated verbatim from `notification-handler.ts`'s
+ * `ALWAYS_DELIVER_TYPES`. This is the critical-always floor.
+ */
+export const ALWAYS_DELIVER_TYPES = new Set(["SAFETY_ALERT", "PARENTAL_LINK"]);
+/**
+ * Reproduce the existing `notification-handler.ts` quiet-hours check exactly.
+ *
+ * The core encodes `User.quietHoursStart/End` (minutes-since-midnight integers)
+ * as decimal strings in `QuietHoursConfig.start/end`, and derives the current
+ * minute from `ctx.now` (rather than an ambient `new Date()`), so the decision
+ * is deterministic. The wrap-around / same-day arithmetic mirrors
+ * `NotificationHandler.isInQuietHours`.
+ */
+function isInQuietHours(quietHours, now) {
+    if (!quietHours || !quietHours.enabled)
+        return false;
+    const start = Number.parseInt(quietHours.start, 10);
+    const end = Number.parseInt(quietHours.end, 10);
+    if (!Number.isFinite(start) || !Number.isFinite(end))
+        return false;
+    const minutesSinceMidnight = now.getHours() * 60 + now.getMinutes();
+    // Overnight window (e.g. 22:00 -> 07:00).
+    if (start > end) {
+        return minutesSinceMidnight >= start || minutesSinceMidnight < end;
+    }
+    // Same-day window (e.g. 13:00 -> 15:00).
+    return minutesSinceMidnight >= start && minutesSinceMidnight < end;
+}
+/**
+ * The WS1 + Track D default resolver. Pure and synchronous over `DeliveryContext`
+ * (the caller does any async lookups and passes resolved signals in):
+ *
+ *  1. ALWAYS_DELIVER_TYPES (SAFETY_ALERT, PARENTAL_LINK) bypass everything ->
+ *     `{ deliver: true }`. Safety must NOT be over-blocked: this wins over the
+ *     blocked-sender and minor-protection floor below.
+ *  2. Non-configurable FLOOR (checked only when the caller supplies the input):
+ *       - blocked sender: the caller resolves block-set membership async (via
+ *         BlockStore) and populates `ctx.senderUserId` ONLY when the sender is
+ *         blocked — so presence of `senderUserId` == "in the recipient's block
+ *         set". The decision is a hard drop no preference can override.
+ *       - minor-protection: a non-adult recipient (`recipientAgeTier` CHILD/TEEN)
+ *         targeted by a configured re-engagement type is dropped.
+ *  3. Else honor preference (caller pre-resolves `deliver:false`/`preference`)
+ *     and quiet hours.
+ *
+ * Note on preference: in the existing handler the type-preference check happens
+ * BEFORE creating the row (preference-off => no row at all), which is a
+ * different outcome from quiet-hours (row created with deliveredAt=null). The
+ * caller maps the decision reasons accordingly. To keep the resolver pure and
+ * total it accepts the preference outcome via `ctx` indirectly: the caller only
+ * invokes the resolver's quiet-hours path once preference has passed. For a
+ * single source of truth the resolver still exposes the full decision so a
+ * push-only caller (WS4) can gate solely on it.
+ */
+export class CalmDeliveryResolver {
+    reengagementTypes;
+    constructor(config = {}) {
+        this.reengagementTypes =
+            config.reengagementTypes ?? new Set();
+    }
+    decide(ctx) {
+        // 1. Critical-always bypass — wins over the floor so safety is never
+        //    over-blocked (a blocked sender or a minor still gets SAFETY_ALERT /
+        //    PARENTAL_LINK).
+        if (ALWAYS_DELIVER_TYPES.has(ctx.type)) {
+            return { deliver: true };
+        }
+        // 2. Non-configurable floor.
+        //    2a. Blocked sender. The caller has already resolved block-set
+        //        membership and only sets `senderUserId` when the sender IS blocked,
+        //        so its presence is the deny signal. Hard drop, no override.
+        if (ctx.senderUserId !== undefined) {
+            return { deliver: false, reason: "blocked_sender" };
+        }
+        //    2b. Minor protection. A non-adult recipient targeted by a configured
+        //        manipulative re-engagement type is dropped (FLOOR, not preference).
+        if (ctx.recipientAgeTier !== undefined &&
+            ctx.recipientAgeTier !== "ADULT" &&
+            this.reengagementTypes.has(ctx.type)) {
+            return { deliver: false, reason: "floor" };
+        }
+        // 3. Quiet hours (preference is handled by the caller; see class doc).
+        if (isInQuietHours(ctx.quietHours, ctx.now)) {
+            return { deliver: false, reason: "quiet_hours" };
+        }
+        return { deliver: true };
+    }
+}
+//# sourceMappingURL=delivery-policy.js.map

package/dist/lib/realtime/delivery-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-policy.js","sourceRoot":"","sources":["../../../src/lib/realtime/delivery-policy.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,8EAA8E;AAC9E,sEAAsE;AACtE,wEAAwE;AASxE;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAkC,IAAI,GAAG,CAExE,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC,CAAC;AAErC;;;;;;;;GAQG;AACH,SAAS,cAAc,CACrB,UAAyC,EACzC,GAAS;IAET,IAAI,CAAC,UAAU,IAAI,CAAC,UAAU,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IACrD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACpD,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAEnE,MAAM,oBAAoB,GAAG,GAAG,CAAC,QAAQ,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC,UAAU,EAAE,CAAC;IAEpE,0CAA0C;IAC1C,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;QAChB,OAAO,oBAAoB,IAAI,KAAK,IAAI,oBAAoB,GAAG,GAAG,CAAC;IACrE,CAAC;IACD,yCAAyC;IACzC,OAAO,oBAAoB,IAAI,KAAK,IAAI,oBAAoB,GAAG,GAAG,CAAC;AACrE,CAAC;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,oBAAoB;IACd,iBAAiB,CAAgC;IAElE,YAAY,SAA8B,EAAE;QAC1C,IAAI,CAAC,iBAAiB;YACpB,MAAM,CAAC,iBAAiB,IAAI,IAAI,GAAG,EAAoB,CAAC;IAC5D,CAAC;IAED,MAAM,CAAC,GAAoB;QACzB,qEAAqE;QACrE,yEAAyE;QACzE,qBAAqB;QACrB,IAAI,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC3B,CAAC;QAED,6BAA6B;QAC7B,mEAAmE;QACnE,6EAA6E;QAC7E,qEAAqE;QACrE,IAAI,GAAG,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACnC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;QACtD,CAAC;QACD,0EAA0E;QAC1E,6EAA6E;QAC7E,IACE,GAAG,CAAC,gBAAgB,KAAK,SAAS;YAClC,GAAG,CAAC,gBAAgB,KAAK,OAAO;YAChC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EACpC,CAAC;YACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QAC7C,CAAC;QAED,uEAAuE;QACvE,IAAI,cAAc,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;QACnD,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;CACF"}

package/dist/lib/realtime/index.d.ts

@@ -0,0 +1,21 @@
+export type { Channel, ChannelKind, ScopeType, VerifiedIdentity, DeliveryTarget, DeliveryResult, DeliveryContext, DeliveryDecision, QuietHoursConfig, WakeupEnvelope, EncryptedBlob, PutResult, SettingStore, ChangedSettingMeta, ChangeCursorStore, RealtimeTransport, DeliveryPolicyResolver, } from "./types.js";
+export { encodeWakeup, decodeWakeup, supportsChangeCursor } from "./types.js";
+export { channelName, parseChannel, channelFor, authorizeSubscription, } from "./channel.js";
+export { CalmDeliveryResolver, ALWAYS_DELIVER_TYPES, } from "./delivery-policy.js";
+export { InMemorySettingStore } from "./setting-store.js";
+export { PollTransport } from "./poll-transport.js";
+export { NoopRealtimeTransport } from "./no-op-transport.js";
+import type { RealtimeTransport } from "./types.js";
+/**
+ * Consuming app (Skybber) calls this at startup with its concrete transport
+ * (e.g. AppSyncEventsTransport). MUST run before buildEnv-consumers serve.
+ */
+export declare function setRealtimeProvider(transport: RealtimeTransport): void;
+/**
+ * Returns the injected transport if a provider was registered, else the
+ * supplied fallback. `buildEnv` calls this with the default Poll/Noop transport.
+ */
+export declare function resolveRealtimeTransport(fallback: RealtimeTransport): RealtimeTransport;
+/** Test-only: clear the injected provider so tests don't leak across cases. */
+export declare function __resetRealtimeProviderForTests(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/realtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/realtime/index.ts"],"names":[],"mappings":"AAQA,YAAY,EAEV,OAAO,EACP,WAAW,EACX,SAAS,EAET,gBAAgB,EAEhB,cAAc,EACd,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAEhB,cAAc,EAEd,aAAa,EACb,SAAS,EACT,YAAY,EAEZ,kBAAkB,EAClB,iBAAiB,EAEjB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE9E,OAAO,EACL,WAAW,EACX,YAAY,EACZ,UAAU,EACV,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAWpD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAEtE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,iBAAiB,GAC1B,iBAAiB,CAEnB;AAED,+EAA+E;AAC/E,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD"}

package/dist/lib/realtime/index.js

@@ -0,0 +1,39 @@
+// CONTRACT: stable — coordinate changes. See types.ts banner.
+//
+// Public barrel for the RealtimeTransport seam — the ONLY import path consumers
+// use (published as `@de-otio/trellis/realtime`). Re-exports the frozen types,
+// the channel helpers, the ports + defaults, the two in-core transports, and
+// the provider-injection hook a consuming app (Skybber) uses to plug in its
+// AppSyncEventsTransport WITHOUT core importing any AWS SDK.
+export { encodeWakeup, decodeWakeup, supportsChangeCursor } from "./types.js";
+export { channelName, parseChannel, channelFor, authorizeSubscription, } from "./channel.js";
+export { CalmDeliveryResolver, ALWAYS_DELIVER_TYPES, } from "./delivery-policy.js";
+export { InMemorySettingStore } from "./setting-store.js";
+export { PollTransport } from "./poll-transport.js";
+export { NoopRealtimeTransport } from "./no-op-transport.js";
+// ---------------------------------------------------------------------------
+// Provider-injection hook (mirrors registerExtension). A consuming app calls
+// setRealtimeProvider() at startup, BEFORE buildEnv-consumers serve, with its
+// concrete transport. resolveRealtimeTransport() returns the injected transport
+// if present, else the supplied fallback (the core Poll/Noop default).
+// ---------------------------------------------------------------------------
+let injected;
+/**
+ * Consuming app (Skybber) calls this at startup with its concrete transport
+ * (e.g. AppSyncEventsTransport). MUST run before buildEnv-consumers serve.
+ */
+export function setRealtimeProvider(transport) {
+    injected = transport;
+}
+/**
+ * Returns the injected transport if a provider was registered, else the
+ * supplied fallback. `buildEnv` calls this with the default Poll/Noop transport.
+ */
+export function resolveRealtimeTransport(fallback) {
+    return injected ?? fallback;
+}
+/** Test-only: clear the injected provider so tests don't leak across cases. */
+export function __resetRealtimeProviderForTests() {
+    injected = undefined;
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/realtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/realtime/index.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,6EAA6E;AAC7E,4EAA4E;AAC5E,6DAA6D;AA6B7D,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE9E,OAAO,EACL,WAAW,EACX,YAAY,EACZ,UAAU,EACV,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAI7D,8EAA8E;AAC9E,6EAA6E;AAC7E,8EAA8E;AAC9E,gFAAgF;AAChF,uEAAuE;AACvE,8EAA8E;AAE9E,IAAI,QAAuC,CAAC;AAE5C;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAA4B;IAC9D,QAAQ,GAAG,SAAS,CAAC;AACvB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAA2B;IAE3B,OAAO,QAAQ,IAAI,QAAQ,CAAC;AAC9B,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,+BAA+B;IAC7C,QAAQ,GAAG,SAAS,CAAC;AACvB,CAAC"}

package/dist/lib/realtime/no-op-transport.d.ts

@@ -0,0 +1,10 @@
+import type { Channel, DeliveryPolicyResolver, DeliveryResult, DeliveryTarget, EncryptedBlob, PutResult, RealtimeTransport } from "./types.js";
+export declare class NoopRealtimeTransport implements RealtimeTransport {
+    private readonly policy;
+    readonly kind: "noop";
+    constructor(policy: DeliveryPolicyResolver);
+    deliver(target: DeliveryTarget, channel: Channel, _payload: Uint8Array): Promise<DeliveryResult>;
+    getSetting(_userId: string, _namespace: string): Promise<EncryptedBlob | null>;
+    putSetting(_userId: string, _namespace: string, _blob: EncryptedBlob, _expectVersion: number): Promise<PutResult>;
+}
+//# sourceMappingURL=no-op-transport.d.ts.map

package/dist/lib/realtime/no-op-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-op-transport.d.ts","sourceRoot":"","sources":["../../../src/lib/realtime/no-op-transport.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,OAAO,EAEP,sBAAsB,EACtB,cAAc,EACd,cAAc,EACd,aAAa,EACb,SAAS,EACT,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAepB,qBAAa,qBAAsB,YAAW,iBAAiB;IAGjD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;gBAEH,MAAM,EAAE,sBAAsB;IAErD,OAAO,CACX,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,UAAU,GACnB,OAAO,CAAC,cAAc,CAAC;IAepB,UAAU,CACd,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAI1B,UAAU,CACd,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,aAAa,EACpB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,SAAS,CAAC;CAGtB"}

package/dist/lib/realtime/no-op-transport.js

@@ -0,0 +1,44 @@
+// CONTRACT-adjacent — the CI transport. See types.ts banner.
+//
+// NoopRealtimeTransport: the same shape as PollTransport but with NO store and
+// NO wire. It still runs the policy fence inside deliver() (so the fence-runs-
+// on-every-transport invariant holds), then drops. getSetting/putSetting are
+// inert (no store). Used in tests/CI where neither a store nor a socket exists.
+function fenceContextFor(target, channel) {
+    const type = channel.kind === "safety" ? "SAFETY_ALERT" : "SYSTEM";
+    return {
+        type,
+        recipientUserId: target.userId,
+        tenantId: target.tenantId,
+        now: new Date(),
+    };
+}
+export class NoopRealtimeTransport {
+    policy;
+    kind = "noop";
+    constructor(policy) {
+        this.policy = policy;
+    }
+    async deliver(target, channel, _payload) {
+        // Best-effort: a transport-internal fault (e.g. a throwing resolver) is
+        // caught and surfaced as transport_error, never a reject that could roll
+        // back a persisted write (frozen contract §2.3).
+        try {
+            const decision = this.policy.decide(fenceContextFor(target, channel));
+            if (!decision.deliver) {
+                return { delivered: false, reason: "policy_denied" };
+            }
+            return { delivered: false, reason: "no_transport" };
+        }
+        catch {
+            return { delivered: false, reason: "transport_error" };
+        }
+    }
+    async getSetting(_userId, _namespace) {
+        return null;
+    }
+    async putSetting(_userId, _namespace, _blob, _expectVersion) {
+        return { ok: false, reason: "not_found", current: null };
+    }
+}
+//# sourceMappingURL=no-op-transport.js.map

package/dist/lib/realtime/no-op-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-op-transport.js","sourceRoot":"","sources":["../../../src/lib/realtime/no-op-transport.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,6EAA6E;AAC7E,gFAAgF;AAahF,SAAS,eAAe,CACtB,MAAsB,EACtB,OAAgB;IAEhB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC;IACnE,OAAO;QACL,IAAI;QACJ,eAAe,EAAE,MAAM,CAAC,MAAM;QAC9B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,GAAG,EAAE,IAAI,IAAI,EAAE;KAChB,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,qBAAqB;IAGH;IAFpB,IAAI,GAAG,MAAe,CAAC;IAEhC,YAA6B,MAA8B;QAA9B,WAAM,GAAN,MAAM,CAAwB;IAAG,CAAC;IAE/D,KAAK,CAAC,OAAO,CACX,MAAsB,EACtB,OAAgB,EAChB,QAAoB;QAEpB,wEAAwE;QACxE,yEAAyE;QACzE,iDAAiD;QACjD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;YACtE,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;gBACtB,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;YACvD,CAAC;YACD,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QACtD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;QACzD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,UAAU,CACd,OAAe,EACf,UAAkB;QAElB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,UAAU,CACd,OAAe,EACf,UAAkB,EAClB,KAAoB,EACpB,cAAsB;QAEtB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3D,CAAC;CACF"}

package/dist/lib/realtime/poll-transport.d.ts

@@ -0,0 +1,11 @@
+import type { Channel, DeliveryPolicyResolver, DeliveryResult, DeliveryTarget, EncryptedBlob, PutResult, RealtimeTransport, SettingStore } from "./types.js";
+export declare class PollTransport implements RealtimeTransport {
+    private readonly store;
+    private readonly policy;
+    readonly kind: "poll";
+    constructor(store: SettingStore, policy: DeliveryPolicyResolver);
+    deliver(target: DeliveryTarget, channel: Channel, _payload: Uint8Array): Promise<DeliveryResult>;
+    getSetting(userId: string, namespace: string): Promise<EncryptedBlob | null>;
+    putSetting(userId: string, namespace: string, blob: EncryptedBlob, expectVersion: number): Promise<PutResult>;
+}
+//# sourceMappingURL=poll-transport.d.ts.map

package/dist/lib/realtime/poll-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll-transport.d.ts","sourceRoot":"","sources":["../../../src/lib/realtime/poll-transport.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,OAAO,EAEP,sBAAsB,EACtB,cAAc,EACd,cAAc,EACd,aAAa,EACb,SAAS,EACT,iBAAiB,EACjB,YAAY,EACb,MAAM,YAAY,CAAC;AA0BpB,qBAAa,aAAc,YAAW,iBAAiB;IAInD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJzB,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;gBAGb,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,sBAAsB;IAG3C,OAAO,CACX,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,UAAU,GACnB,OAAO,CAAC,cAAc,CAAC;IAmB1B,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAI5E,UAAU,CACR,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,aAAa,EACnB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,SAAS,CAAC;CAGtB"}

package/dist/lib/realtime/poll-transport.js

@@ -0,0 +1,68 @@
+// CONTRACT-adjacent — the default transport. See types.ts banner.
+//
+// PollTransport makes core runnable and testable with NO realtime infra. It is
+// a correctness default, explicitly NOT the scale answer.
+//
+//   deliver()  -> runs the policy fence, then NO-OPs the wire send and returns
+//                 { delivered: false, reason: "no_transport" } (clients poll;
+//                 the side-effecting persistence — the Notification row / the
+//                 setting version bump — is what the next poll observes). The
+//                 fence still runs so swapping in AppSync changes the pipe, not
+//                 a single call site.
+//   getSetting / putSetting -> delegate to the injected SettingStore (the real
+//                 REST-backed sync path).
+/**
+ * Build the `DeliveryContext` the policy fence needs from a `deliver()` call.
+ * PollTransport has no notification metadata at the wire boundary (the floor
+ * decision was already made by the caller for persistence), so it constructs a
+ * minimal, fence-running context. The interface keeps payloads opaque, so the
+ * transport derives only routing-level inputs.
+ */
+function fenceContextFor(target, channel) {
+    // Map the channel kind back onto a NotificationType-shaped floor input: the
+    // "safety" kind is critical-always, everything else is best-effort. We do not
+    // have the original NotificationType here, so we synthesize the floor-relevant
+    // signal: a "safety" channel must never be suppressed.
+    const type = channel.kind === "safety" ? "SAFETY_ALERT" : "SYSTEM";
+    return {
+        type,
+        recipientUserId: target.userId,
+        tenantId: target.tenantId,
+        now: new Date(),
+    };
+}
+export class PollTransport {
+    store;
+    policy;
+    kind = "poll";
+    constructor(store, policy) {
+        this.store = store;
+        this.policy = policy;
+    }
+    async deliver(target, channel, _payload) {
+        // deliver() is BEST-EFFORT: it MUST NOT reject in a way that could roll back
+        // a persisted write upstream. Any internal fault (e.g. a throwing resolver)
+        // is caught and surfaced as transport_error (frozen contract §2.3 + the
+        // realtime-transport.ts binding rules).
+        try {
+            // The policy fence runs on EVERY transport, even the no-op one.
+            const decision = this.policy.decide(fenceContextFor(target, channel));
+            if (!decision.deliver) {
+                return { delivered: false, reason: "policy_denied" };
+            }
+            // Poll model: there is no socket. The client learns of the change on its
+            // next poll, so the wire send is a deliberate no-op.
+            return { delivered: false, reason: "no_transport" };
+        }
+        catch {
+            return { delivered: false, reason: "transport_error" };
+        }
+    }
+    getSetting(userId, namespace) {
+        return this.store.get(userId, namespace);
+    }
+    putSetting(userId, namespace, blob, expectVersion) {
+        return this.store.put(userId, namespace, blob, expectVersion);
+    }
+}
+//# sourceMappingURL=poll-transport.js.map

package/dist/lib/realtime/poll-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll-transport.js","sourceRoot":"","sources":["../../../src/lib/realtime/poll-transport.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,+EAA+E;AAC/E,0DAA0D;AAC1D,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,8EAA8E;AAC9E,8EAA8E;AAC9E,gFAAgF;AAChF,sCAAsC;AACtC,+EAA+E;AAC/E,0CAA0C;AAc1C;;;;;;GAMG;AACH,SAAS,eAAe,CACtB,MAAsB,EACtB,OAAgB;IAEhB,4EAA4E;IAC5E,8EAA8E;IAC9E,+EAA+E;IAC/E,uDAAuD;IACvD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC;IACnE,OAAO;QACL,IAAI;QACJ,eAAe,EAAE,MAAM,CAAC,MAAM;QAC9B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,GAAG,EAAE,IAAI,IAAI,EAAE;KAChB,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,aAAa;IAIL;IACA;IAJV,IAAI,GAAG,MAAe,CAAC;IAEhC,YACmB,KAAmB,EACnB,MAA8B;QAD9B,UAAK,GAAL,KAAK,CAAc;QACnB,WAAM,GAAN,MAAM,CAAwB;IAC9C,CAAC;IAEJ,KAAK,CAAC,OAAO,CACX,MAAsB,EACtB,OAAgB,EAChB,QAAoB;QAEpB,6EAA6E;QAC7E,4EAA4E;QAC5E,wEAAwE;QACxE,wCAAwC;QACxC,IAAI,CAAC;YACH,gEAAgE;YAChE,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;YACtE,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;gBACtB,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;YACvD,CAAC;YACD,yEAAyE;YACzE,qDAAqD;YACrD,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QACtD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;QACzD,CAAC;IACH,CAAC;IAED,UAAU,CAAC,MAAc,EAAE,SAAiB;QAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC3C,CAAC;IAED,UAAU,CACR,MAAc,EACd,SAAiB,EACjB,IAAmB,EACnB,aAAqB;QAErB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;IAChE,CAAC;CACF"}

package/dist/lib/realtime/push-notifier.d.ts

@@ -0,0 +1,39 @@
+import type { Logger } from "../logger.js";
+import type { ChannelKind, RealtimeTransport } from "./types.js";
+/** The kinds WS4 routes a content-free notification wakeup onto. */
+export type WakeupKind = Extract<ChannelKind, "wakeup" | "safety">;
+export interface PushNotifierInput {
+    /** Server-resolved recipient. */
+    target: {
+        userId: string;
+        tenantId: string;
+    };
+    /**
+     * Channel kind: ALWAYS_DELIVER notifications route to "safety" (the floor
+     * channel), everything else to "wakeup". Constrained to the two content-free
+     * kinds WS4 owns — there is no overload that accepts "message"/"thread".
+     */
+    kind: WakeupKind;
+}
+/**
+ * Build the content-free wakeup payload for a notification. The envelope is the
+ * frozen WS1 `WakeupEnvelope` and carries NO notification content — only the
+ * envelope version and the channel kind. There is deliberately no `changeToken`
+ * for notification wakeups (that field is the setting_sync version pointer); a
+ * notification wakeup says only "something changed on this surface; refetch".
+ */
+export declare function buildNotificationWakeup(kind: WakeupKind): Uint8Array;
+/**
+ * Relay a content-free wakeup over the realtime transport, best-effort.
+ *
+ * Resolves to `true` if the transport reported a delivery, `false` otherwise
+ * (policy-denied, no transport, transport error, or a thrown transport). NEVER
+ * throws — the caller's persisted write is durable regardless.
+ */
+export declare class PushNotifier {
+    private readonly transport;
+    private readonly logger;
+    constructor(transport: RealtimeTransport, logger: Logger);
+    notify(input: PushNotifierInput): Promise<boolean>;
+}
+//# sourceMappingURL=push-notifier.d.ts.map

package/dist/lib/realtime/push-notifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-notifier.d.ts","sourceRoot":"","sources":["../../../src/lib/realtime/push-notifier.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAkB,MAAM,YAAY,CAAC;AAEjF,oEAAoE;AACpE,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC;AAEnE,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C;;;;OAIG;IACH,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAGpE;AAED;;;;;;GAMG;AACH,qBAAa,YAAY;IAErB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,SAAS,EAAE,iBAAiB,EAC5B,MAAM,EAAE,MAAM;IAG3B,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;CA8BzD"}

package/dist/lib/realtime/push-notifier.js

@@ -0,0 +1,76 @@
+// WS4 — content-free push consumer.
+//
+// PushNotifier is the ONE place that turns a "deliver" decision into a wire
+// wakeup. It exists so `notification-handler.ts` stays slim and so the
+// content-free guarantee is structural, not a per-call-site discipline:
+//
+//   1. The payload is built ONLY via `encodeWakeup()` (the frozen WS1 envelope).
+//      WS4 is FORBIDDEN by the contract from constructing arbitrary Uint8Array
+//      for wakeup/setting_sync/safety kinds — there is no code path here that
+//      can put a title/body/data on the wire (types.ts §2.4).
+//   2. The channel is built ONLY via `channelFor()` — tenant- and user-scoped,
+//      server-resolved, never client-asserted.
+//   3. `transport.deliver()` is BEST-EFFORT: a transport throw is caught and
+//      logged, NEVER rethrown, so it can never roll back the already-persisted
+//      Notification row. Polling remains the floor.
+//
+// The policy fence (CalmDeliveryResolver floor) runs in TWO places by design:
+// the caller gates on its decision (so a deferred/blocked/preference-off
+// notification never reaches here), AND the transport re-runs the fence inside
+// `deliver()`. PushNotifier itself does not re-decide — it relays the decision
+// the caller already made onto the correct channel kind.
+import { channelFor } from "./channel.js";
+import { encodeWakeup } from "./types.js";
+/**
+ * Build the content-free wakeup payload for a notification. The envelope is the
+ * frozen WS1 `WakeupEnvelope` and carries NO notification content — only the
+ * envelope version and the channel kind. There is deliberately no `changeToken`
+ * for notification wakeups (that field is the setting_sync version pointer); a
+ * notification wakeup says only "something changed on this surface; refetch".
+ */
+export function buildNotificationWakeup(kind) {
+    const envelope = { v: 1, kind };
+    return encodeWakeup(envelope);
+}
+/**
+ * Relay a content-free wakeup over the realtime transport, best-effort.
+ *
+ * Resolves to `true` if the transport reported a delivery, `false` otherwise
+ * (policy-denied, no transport, transport error, or a thrown transport). NEVER
+ * throws — the caller's persisted write is durable regardless.
+ */
+export class PushNotifier {
+    transport;
+    logger;
+    constructor(transport, logger) {
+        this.transport = transport;
+        this.logger = logger;
+    }
+    async notify(input) {
+        const { target, kind } = input;
+        const channel = channelFor(kind, {
+            tenantId: target.tenantId,
+            userId: target.userId,
+        });
+        const payload = buildNotificationWakeup(kind);
+        try {
+            const result = await this.transport.deliver({ userId: target.userId, tenantId: target.tenantId }, channel, payload);
+            if (!result.delivered) {
+                // Not an error — poll/no-transport/policy are normal outcomes. Logged
+                // at debug so the absence of a push is observable without noise.
+                this.logger.debug("realtime wakeup not delivered", {
+                    reason: result.reason,
+                    kind,
+                });
+            }
+            return result.delivered;
+        }
+        catch (err) {
+            // BEST-EFFORT: a transport hiccup must never surface to the caller. The
+            // notification row is already persisted; the next poll delivers it.
+            this.logger.warn("realtime wakeup deliver threw (non-fatal)", err);
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=push-notifier.js.map

package/dist/lib/realtime/push-notifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-notifier.js","sourceRoot":"","sources":["../../../src/lib/realtime/push-notifier.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,EAAE;AACF,4EAA4E;AAC5E,uEAAuE;AACvE,wEAAwE;AACxE,EAAE;AACF,iFAAiF;AACjF,+EAA+E;AAC/E,8EAA8E;AAC9E,8DAA8D;AAC9D,+EAA+E;AAC/E,+CAA+C;AAC/C,6EAA6E;AAC7E,+EAA+E;AAC/E,oDAAoD;AACpD,EAAE;AACF,8EAA8E;AAC9E,yEAAyE;AACzE,+EAA+E;AAC/E,+EAA+E;AAC/E,yDAAyD;AAGzD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAiB1C;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAgB;IACtD,MAAM,QAAQ,GAAmB,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC;IAChD,OAAO,YAAY,CAAC,QAAQ,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IAEJ;IACA;IAFnB,YACmB,SAA4B,EAC5B,MAAc;QADd,cAAS,GAAT,SAAS,CAAmB;QAC5B,WAAM,GAAN,MAAM,CAAQ;IAC9B,CAAC;IAEJ,KAAK,CAAC,MAAM,CAAC,KAAwB;QACnC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;QAC/B,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE;YAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC;QAE9C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CACzC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,EACpD,OAAO,EACP,OAAO,CACR,CAAC;YACF,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;gBACtB,sEAAsE;gBACtE,iEAAiE;gBACjE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,+BAA+B,EAAE;oBACjD,MAAM,EAAE,MAAM,CAAC,MAAM;oBACrB,IAAI;iBACL,CAAC,CAAC;YACL,CAAC;YACD,OAAO,MAAM,CAAC,SAAS,CAAC;QAC1B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,wEAAwE;YACxE,oEAAoE;YACpE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,2CAA2C,EAAE,GAAG,CAAC,CAAC;YACnE,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}

package/dist/lib/realtime/realtime-transport.d.ts

@@ -0,0 +1,2 @@
+export type { RealtimeTransport, DeliveryPolicyResolver, DeliveryTarget, DeliveryResult, Channel, EncryptedBlob, PutResult, SettingStore, } from "./types.js";
+//# sourceMappingURL=realtime-transport.d.ts.map

package/dist/lib/realtime/realtime-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-transport.d.ts","sourceRoot":"","sources":["../../../src/lib/realtime/realtime-transport.ts"],"names":[],"mappings":"AAsBA,YAAY,EACV,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,EACd,cAAc,EACd,OAAO,EACP,aAAa,EACb,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC"}