pyric 0.0.1 → 0.1.0-alpha.10

package/dist/messaging/broker/broker.js

@@ -0,0 +1,400 @@
+import { emitSandboxEvent, makeServiceMutationEvent } from '../../sandbox/internal/sandbox-impl.js';
+import { BrokerSendError, unregisteredTokenEnvelope, invalidTopicNameEnvelope } from './envelopes.js';
+import { mintToken } from './tokens.js';
+import { validateMessage, isValidTopicName, canonicalTopicName, TOKEN_SHAPE_RE } from './validate.js';
+/** Default project id for sandbox-minted message resource names. */
+export const DEFAULT_PROJECT_ID = 'pyric-sandbox';
+/**
+ * Default sender id (the `from` value on delivered payloads). A fixed
+ * 12-digit numeric string in the project-number shape production uses;
+ * `fromEqualsSenderId` is pinned by the receive-plane captures.
+ */
+export const DEFAULT_SENDER_ID = '999999999999';
+/** The id the mirrors use for the single simulated window client. */
+export const DEFAULT_CLIENT_ID = 'window-default';
+/** Ops run on the admin/send plane or the SDK control plane — never a rules identity. */
+const ADMIN_AUTH = null;
+export class MessagingBroker {
+    projectId;
+    senderId;
+    sandbox;
+    /** registrationId → active token (stability per registration is the captured contract). */
+    registrations = new Map();
+    /** token → record. Deleted tokens stay, flipped to `unregistered`, so dead sends 404. */
+    tokens = new Map();
+    /** topic → subscribed tokens. */
+    subscriptions = new Map();
+    /** Window clients and their visibility — THE routing input (never focus). */
+    clients = new Map();
+    foregroundHandlers = new Set();
+    backgroundHandlers = new Set();
+    numericIdCounter = 0;
+    constructor(options = {}) {
+        this.projectId = options.projectId ?? DEFAULT_PROJECT_ID;
+        this.senderId = options.senderId ?? DEFAULT_SENDER_ID;
+        this.sandbox = options.sandbox;
+    }
+    // ── Token lifecycle ───────────────────────────────────────────────────────
+    /**
+     * Return the registration's token, minting on first call. Stable across
+     * calls for the same registration (oracle: `messaging-web-token-stability`);
+     * shape class per `mintToken` (oracle: `messaging-web-token-shape`).
+     */
+    getTokenFor(registrationId) {
+        const existing = this.registrations.get(registrationId);
+        if (existing !== undefined)
+            return existing;
+        const token = mintToken();
+        this.registrations.set(registrationId, token);
+        this.tokens.set(token, { registrationId, state: 'active' });
+        this.emit('token_minted', { path: token, detail: { registrationId } });
+        return token;
+    }
+    /**
+     * Invalidate the registration's token. Resolves truthy whether or not a
+     * token existed (oracle: `messaging-web-deletetoken-unregistered`
+     * `deleteTokenResolvedTruthy`). After deletion the token routes NO client
+     * delivery and the send plane answers with the captured UNREGISTERED
+     * envelope. Deliberate divergence from production's TIMING nuance: prod
+     * propagates unregistration asynchronously (a first send after delete was
+     * observed accepted once); the broker is deterministic — dead is dead
+     * immediately. The observation pins that nuance as environment-dependent
+     * and NOT contractual.
+     */
+    deleteTokenFor(registrationId) {
+        const token = this.registrations.get(registrationId);
+        if (token === undefined)
+            return true;
+        this.registrations.delete(registrationId);
+        const record = this.tokens.get(token);
+        if (record !== undefined)
+            record.state = 'unregistered';
+        this.emit('token_deleted', { path: token, detail: { registrationId } });
+        return true;
+    }
+    /** `active` | `unregistered` (minted then deleted) | `unknown` (never minted here). */
+    tokenState(token) {
+        return this.tokens.get(token)?.state ?? 'unknown';
+    }
+    // ── Topic / condition subscriptions ──────────────────────────────────────
+    /**
+     * Subscribe tokens to a topic. Topic names validate against the captured
+     * `[a-zA-Z0-9-_.~%]` charset (a `/topics/` prefix is accepted and
+     * stripped, mirroring the admin SDK). Per-token outcomes:
+     *   - shape-invalid token       → error entry `invalid-token`
+     *   - minted-then-deleted token → error entry `unregistered-token`
+     *   - well-formed unknown token → SUCCESS (UNOBSERVED: production accepts
+     *     tokens it did not mint in this project only until IID rejects them;
+     *     the broker accepts them so cross-sandbox fixtures compose. Probe
+     *     candidate.)
+     */
+    subscribeToTopic(tokens, topic) {
+        return this.mutateSubscriptions(tokens, topic, 'subscribe');
+    }
+    /** Unsubscribe tokens from a topic. Same validation/outcome model as subscribe. */
+    unsubscribeFromTopic(tokens, topic) {
+        return this.mutateSubscriptions(tokens, topic, 'unsubscribe');
+    }
+    mutateSubscriptions(tokens, topic, action) {
+        if (!isValidTopicName(topic)) {
+            throw new BrokerSendError(invalidTopicNameEnvelope());
+        }
+        const name = canonicalTopicName(topic);
+        const set = this.subscriptions.get(name) ?? new Set();
+        this.subscriptions.set(name, set);
+        const outcome = { successCount: 0, failureCount: 0, errors: [] };
+        tokens.forEach((token, index) => {
+            if (!TOKEN_SHAPE_RE.test(token)) {
+                outcome.failureCount++;
+                outcome.errors.push({ index, reason: 'invalid-token' });
+                return;
+            }
+            if (this.tokenState(token) === 'unregistered') {
+                outcome.failureCount++;
+                outcome.errors.push({ index, reason: 'unregistered-token' });
+                return;
+            }
+            if (action === 'subscribe')
+                set.add(token);
+            else
+                set.delete(token);
+            outcome.successCount++;
+        });
+        this.emit('subscription_changed', {
+            path: name,
+            detail: {
+                action,
+                tokenCount: tokens.length,
+                successCount: outcome.successCount,
+                failureCount: outcome.failureCount,
+            },
+        });
+        return outcome;
+    }
+    /** Topics an active token is currently subscribed to (routing input). */
+    topicsOf(token) {
+        const topics = new Set();
+        for (const [topic, set] of this.subscriptions) {
+            if (set.has(token))
+                topics.add(topic);
+        }
+        return topics;
+    }
+    // ── Message intake (the admin mirror / future op-channel entry point) ────
+    /**
+     * Validate and accept a message — the send plane. Throws
+     * {@link BrokerSendError} with the exact captured envelope on every
+     * rejection; resolves an {@link AcceptedSend} whose `name` is the FCM
+     * resource name (`projects/<projectId>/messages/<id>`, numeric id for
+     * topic/condition targets, UUID-form for token targets).
+     *
+     * `validateOnly` (the admin SDK's `dryRun`) runs the IDENTICAL validation
+     * path and returns the SAME shape with a fake id (captured:
+     * `dryRunSameShapeAsReal` on every accept observation,
+     * `realSendEnvelopeIdentical` on every rejection observation). It skips
+     * only the delivery side effects.
+     */
+    send(message, options = {}) {
+        const validateOnly = options.validateOnly === true;
+        let target;
+        try {
+            target = validateMessage(message);
+            // A well-formed token that is dead (deleted) or foreign (never minted
+            // here) answers with the captured UNREGISTERED envelope. Parity: the
+            // dryRun path rejects identically (validate_only parity is pinned).
+            if (target.kind === 'token' && this.tokenState(target.token) !== 'active') {
+                throw new BrokerSendError(unregisteredTokenEnvelope());
+            }
+        }
+        catch (error) {
+            if (error instanceof BrokerSendError) {
+                this.emit('message_rejected', {
+                    detail: {
+                        status: error.envelope.status,
+                        errorStatus: error.envelope.error.status,
+                        errorCode: error.errorCode,
+                        message: error.envelope.error.message,
+                        validateOnly,
+                    },
+                });
+            }
+            throw error;
+        }
+        const messageId = target.kind === 'token' ? crypto.randomUUID() : this.mintNumericId();
+        const accepted = {
+            name: `projects/${this.projectId}/messages/${messageId}`,
+            messageId,
+            target,
+            validateOnly,
+        };
+        this.emit('message_accepted', {
+            path: targetPath(target),
+            detail: { target: target.kind, name: accepted.name, messageId, validateOnly },
+        });
+        if (!validateOnly && this.matchesAnyRecipient(target)) {
+            this.route(this.toPayload(message, messageId));
+        }
+        return accepted;
+    }
+    /** Numeric message-id mint for topic/condition targets (prod shape: long numeric string). */
+    mintNumericId() {
+        this.numericIdCounter = (this.numericIdCounter + 1) % 1_000_000;
+        return `${Date.now()}${String(this.numericIdCounter).padStart(6, '0')}`;
+    }
+    matchesAnyRecipient(target) {
+        if (target.kind === 'token')
+            return this.tokenState(target.token) === 'active';
+        if (target.kind === 'topic') {
+            const set = this.subscriptions.get(target.topic);
+            if (set === undefined)
+                return false;
+            for (const token of set)
+                if (this.tokenState(token) === 'active')
+                    return true;
+            return false;
+        }
+        // Condition: re-evaluate the parsed expression per active token's topic set.
+        for (const [token, record] of this.tokens) {
+            if (record.state !== 'active')
+                continue;
+            if (evaluateCondition(target.condition, this.topicsOf(token)))
+                return true;
+        }
+        return false;
+    }
+    toPayload(message, messageId) {
+        const payload = { from: this.senderId, messageId };
+        if (message.data !== undefined)
+            payload.data = { ...message.data };
+        if (message.notification !== undefined) {
+            const { title, body, imageUrl } = message.notification;
+            payload.notification = {
+                ...(title !== undefined ? { title } : {}),
+                ...(body !== undefined ? { body } : {}),
+                ...(imageUrl !== undefined ? { image: imageUrl } : {}),
+            };
+        }
+        return payload;
+    }
+    // ── Client plane: visibility state + handler registration + routing ──────
+    /**
+     * Record a window client's visibility. Mirrors set this (per tab later,
+     * one simulated client in the degenerate case) so headless tests can
+     * drive both routes.
+     */
+    setClientVisibility(clientId, state) {
+        this.clients.set(clientId, state);
+    }
+    removeClient(clientId) {
+        this.clients.delete(clientId);
+    }
+    /** Foreground (`onMessage`) handler. Returns an unsubscribe function. */
+    onForegroundMessage(handler) {
+        this.foregroundHandlers.add(handler);
+        return () => this.foregroundHandlers.delete(handler);
+    }
+    /** Background (`onBackgroundMessage`) handler. Returns an unsubscribe function. */
+    onBackgroundMessage(handler) {
+        this.backgroundHandlers.add(handler);
+        return () => this.backgroundHandlers.delete(handler);
+    }
+    /**
+     * Inject a delivery directly into the client plane (the mirrors'
+     * `sandbox.deliver` driver; later the host's `messaging.deliver` op).
+     * Builds the captured envelope shape — top-level keys exactly
+     * `data`/`from`/`messageId` (+ `notification` unless data-only) — and
+     * routes it by the visibility rule.
+     */
+    deliver(spec) {
+        const payload = {
+            from: spec.from ?? this.senderId,
+            messageId: spec.messageId ?? crypto.randomUUID(),
+        };
+        if (spec.data !== undefined)
+            payload.data = { ...spec.data };
+        if (spec.notification !== undefined)
+            payload.notification = { ...spec.notification };
+        return this.route(payload);
+    }
+    /**
+     * THE captured routing rule (oracle: `messaging-web-visibility-routing`):
+     * foreground handlers iff ANY window client reports `visible`; otherwise
+     * background handlers. Visibility, never focus. Routing is exclusive —
+     * one route per delivery.
+     */
+    route(payload) {
+        let anyVisible = false;
+        for (const state of this.clients.values()) {
+            if (state === 'visible') {
+                anyVisible = true;
+                break;
+            }
+        }
+        const route = anyVisible ? 'foreground' : 'background';
+        const handlers = route === 'foreground' ? this.foregroundHandlers : this.backgroundHandlers;
+        this.emit('delivery_routed', {
+            detail: { route, visibleClient: anyVisible, messageId: payload.messageId },
+        });
+        let handlerCount = 0;
+        for (const handler of [...handlers]) {
+            handlerCount++;
+            // Each handler gets its own copy so a mutating consumer can't corrupt
+            // its siblings' view of the captured envelope. A throwing handler must
+            // not block its siblings — same isolation contract as the auth
+            // listener fan-out (test/auth/sandbox-listeners.test.ts).
+            try {
+                handler(structuredClone(payload));
+            }
+            catch {
+                // Handler errors are the consumer's problem, never the broker's.
+            }
+        }
+        this.emit('message_delivered', {
+            detail: { route, handlerCount, messageId: payload.messageId },
+        });
+        return { route, handlerCount, payload };
+    }
+    // ── Event emission (Studio stream consumer seam) ──────────────────────────
+    /**
+     * Land a broker operation on the sandbox's unified event stream.
+     * Best-effort, storage-precedent: a throw from the emit path must never
+     * fail the messaging operation the caller just completed.
+     */
+    emit(op, fields) {
+        if (this.sandbox === undefined)
+            return;
+        try {
+            emitSandboxEvent(this.sandbox, makeServiceMutationEvent({ service: 'messaging', op, auth: ADMIN_AUTH, ...fields }), { service: 'messaging' });
+        }
+        catch {
+            // Observational — never let event emission break a messaging op.
+        }
+    }
+}
+function targetPath(target) {
+    if (target.kind === 'token')
+        return target.token;
+    if (target.kind === 'topic')
+        return target.topic;
+    return target.condition;
+}
+/**
+ * Evaluate a (pre-validated) condition against a token's topic set. Re-uses
+ * the same grammar as `parseCondition`; kept here because evaluation is a
+ * routing concern, not a validation concern.
+ */
+export function evaluateCondition(condition, topics) {
+    const src = condition;
+    let pos = 0;
+    function ws() {
+        while (pos < src.length && /\s/.test(src[pos]))
+            pos++;
+    }
+    function lit(s) {
+        ws();
+        if (src.startsWith(s, pos)) {
+            pos += s.length;
+            return true;
+        }
+        return false;
+    }
+    function primary() {
+        ws();
+        if (lit('!'))
+            return !primary();
+        if (lit('(')) {
+            const v = expr();
+            lit(')');
+            return v;
+        }
+        ws();
+        pos++; // opening quote (validated upstream)
+        const start = pos;
+        while (pos < src.length && src[pos] !== "'")
+            pos++;
+        const name = src.slice(start, pos);
+        pos++; // closing quote
+        lit('in');
+        lit('topics');
+        return topics.has(name);
+    }
+    function expr() {
+        let value = primary();
+        for (;;) {
+            ws();
+            if (lit('&&')) {
+                const rhs = primary();
+                value = value && rhs;
+                continue;
+            }
+            if (lit('||')) {
+                const rhs = primary();
+                value = value || rhs;
+                continue;
+            }
+            return value;
+        }
+    }
+    return expr();
+}
+//# sourceMappingURL=broker.js.map

package/dist/messaging/broker/broker.js.map

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

package/dist/messaging/broker/envelopes.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Captured FCM v1 error envelopes — the send plane's rejection contract.
+ *
+ * Every constructor here reproduces a committed oracle observation
+ * byte-for-byte (`packages/conformance/observations/messaging-admin/messaging-send-*.json`),
+ * INCLUDING the per-case ordering of the `details` array. Detail order
+ * differs across cases in production and "is not a contract"
+ * (`messaging-send-no-target-error-envelope.json` description) — but the
+ * broker mirrors each captured case exactly so the conformance suite can
+ * deep-equal against the pinned envelope rather than a normalized shape.
+ *
+ * Per-case detail ordering, as captured:
+ *   - no-target:        BadRequest, FcmError
+ *   - invalid token:    FcmError, BadRequest   ← the one flipped case
+ *   - invalid topic:    BadRequest, FcmError
+ *   - oversized:        BadRequest (NO fieldViolations key), FcmError
+ *   - webpush bad TTL:  BadRequest, FcmError
+ *   - invalid condition: NO details at all (the "bare" envelope)
+ *   - unregistered:     FcmError only (404 / NOT_FOUND)
+ */
+/** `type.googleapis.com/google.rpc.BadRequest` detail. */
+export interface BadRequestDetail {
+    '@type': 'type.googleapis.com/google.rpc.BadRequest';
+    fieldViolations?: Array<{
+        field: string;
+        description: string;
+    }>;
+}
+/** `type.googleapis.com/google.firebase.fcm.v1.FcmError` detail. */
+export interface FcmErrorDetail {
+    '@type': 'type.googleapis.com/google.firebase.fcm.v1.FcmError';
+    errorCode: string;
+}
+export type ErrorDetail = BadRequestDetail | FcmErrorDetail;
+/**
+ * The `google.rpc` error envelope FCM's REST plane returns, as the broker
+ * models it: HTTP status + the `error` object. `details` is absent (not
+ * empty) on the bare invalid-condition case, matching the capture.
+ */
+export interface FcmErrorEnvelope {
+    status: number;
+    error: {
+        code: number;
+        message: string;
+        status: string;
+        details?: ErrorDetail[];
+    };
+}
+/** oracle: `messaging-send-no-target-error-envelope` (details: BadRequest, FcmError). */
+export declare function noTargetEnvelope(): FcmErrorEnvelope;
+/**
+ * Multiple targets set at once. UNOBSERVED: production was only captured for
+ * the zero-target case; the multi-target message text below is stated from
+ * firebase-admin's own validator, not a wire capture — a probe candidate.
+ * The envelope shape mirrors the no-target case (same fault family).
+ */
+export declare function multipleTargetsEnvelope(): FcmErrorEnvelope;
+/** oracle: `messaging-send-invalid-token-error-envelope` (details: FcmError, BadRequest — the flipped order). */
+export declare function invalidTokenEnvelope(): FcmErrorEnvelope;
+/** oracle: `messaging-send-invalid-topic-name-error-envelope` (details: BadRequest, FcmError). */
+export declare function invalidTopicNameEnvelope(): FcmErrorEnvelope;
+/**
+ * oracle: `messaging-send-invalid-condition-error-envelope` — the BARE
+ * envelope: no `details` key at all, only code/message/status.
+ */
+export declare function invalidConditionEnvelope(): FcmErrorEnvelope;
+/**
+ * oracle: `messaging-send-oversized-payload-error-envelope` — the BadRequest
+ * detail carries NO `fieldViolations` key (captured exactly so).
+ */
+export declare function oversizedPayloadEnvelope(): FcmErrorEnvelope;
+/** oracle: `messaging-send-webpush-invalid-ttl-error-envelope` (details: BadRequest, FcmError). */
+export declare function invalidWebpushTtlEnvelope(): FcmErrorEnvelope;
+/**
+ * oracle: `messaging-web-deletetoken-unregistered` — the send plane's
+ * eventual answer for a deleted (or never-registered, well-formed) token:
+ * HTTP 404, status NOT_FOUND, a single FcmError detail with errorCode
+ * UNREGISTERED. The observation pins the message as *present* but drops its
+ * text as prod noise; the text below is production's standard NOT_FOUND
+ * message, stated at documentation strength.
+ */
+export declare function unregisteredTokenEnvelope(): FcmErrorEnvelope;
+/** Pull the FcmError errorCode out of an envelope (mirror of the suite's helper). */
+export declare function fcmErrorCodeOf(envelope: FcmErrorEnvelope): string | undefined;
+/**
+ * A rejected broker operation. Carries the full captured-shape envelope so
+ * admin mirrors (and, later, worker-host op handlers) can re-wrap it into
+ * their own error surface without losing wire fidelity.
+ */
+export declare class BrokerSendError extends Error {
+    readonly envelope: FcmErrorEnvelope;
+    /** The FcmError errorCode when the envelope carries one (`INVALID_ARGUMENT`, `UNREGISTERED`, …). */
+    readonly errorCode: string | undefined;
+    constructor(envelope: FcmErrorEnvelope);
+}
+//# sourceMappingURL=envelopes.d.ts.map

package/dist/messaging/broker/envelopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelopes.d.ts","sourceRoot":"","sources":["../../../src/messaging/broker/envelopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,2CAA2C,CAAC;IACrD,eAAe,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;AAED,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,qDAAqD,CAAC;IAC/D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG,cAAc,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;KACzB,CAAC;CACH;AAoBD,yFAAyF;AACzF,wBAAgB,gBAAgB,IAAI,gBAAgB,CAGnD;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,gBAAgB,CAG1D;AAED,iHAAiH;AACjH,wBAAgB,oBAAoB,IAAI,gBAAgB,CAGvD;AAED,kGAAkG;AAClG,wBAAgB,wBAAwB,IAAI,gBAAgB,CAG3D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,gBAAgB,CAS3D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,gBAAgB,CAK3D;AAED,mGAAmG;AACnG,wBAAgB,yBAAyB,IAAI,gBAAgB,CAM5D;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,IAAI,gBAAgB,CAU5D;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAK7E;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,oGAAoG;IACpG,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE3B,QAAQ,EAAE,gBAAgB;CAMvC"}

package/dist/messaging/broker/envelopes.js

@@ -0,0 +1,132 @@
+/**
+ * Captured FCM v1 error envelopes — the send plane's rejection contract.
+ *
+ * Every constructor here reproduces a committed oracle observation
+ * byte-for-byte (`packages/conformance/observations/messaging-admin/messaging-send-*.json`),
+ * INCLUDING the per-case ordering of the `details` array. Detail order
+ * differs across cases in production and "is not a contract"
+ * (`messaging-send-no-target-error-envelope.json` description) — but the
+ * broker mirrors each captured case exactly so the conformance suite can
+ * deep-equal against the pinned envelope rather than a normalized shape.
+ *
+ * Per-case detail ordering, as captured:
+ *   - no-target:        BadRequest, FcmError
+ *   - invalid token:    FcmError, BadRequest   ← the one flipped case
+ *   - invalid topic:    BadRequest, FcmError
+ *   - oversized:        BadRequest (NO fieldViolations key), FcmError
+ *   - webpush bad TTL:  BadRequest, FcmError
+ *   - invalid condition: NO details at all (the "bare" envelope)
+ *   - unregistered:     FcmError only (404 / NOT_FOUND)
+ */
+const BAD_REQUEST = 'type.googleapis.com/google.rpc.BadRequest';
+const FCM_ERROR = 'type.googleapis.com/google.firebase.fcm.v1.FcmError';
+function badRequest(field, description) {
+    return { '@type': BAD_REQUEST, fieldViolations: [{ field, description }] };
+}
+function fcmError(errorCode) {
+    return { '@type': FCM_ERROR, errorCode };
+}
+function invalidArgument(message, details) {
+    return {
+        status: 400,
+        error: { code: 400, message, status: 'INVALID_ARGUMENT', details },
+    };
+}
+/** oracle: `messaging-send-no-target-error-envelope` (details: BadRequest, FcmError). */
+export function noTargetEnvelope() {
+    const message = 'Recipient of the message is not set.';
+    return invalidArgument(message, [badRequest('message', message), fcmError('INVALID_ARGUMENT')]);
+}
+/**
+ * Multiple targets set at once. UNOBSERVED: production was only captured for
+ * the zero-target case; the multi-target message text below is stated from
+ * firebase-admin's own validator, not a wire capture — a probe candidate.
+ * The envelope shape mirrors the no-target case (same fault family).
+ */
+export function multipleTargetsEnvelope() {
+    const message = 'Exactly one of token, topic or condition is required.';
+    return invalidArgument(message, [badRequest('message', message), fcmError('INVALID_ARGUMENT')]);
+}
+/** oracle: `messaging-send-invalid-token-error-envelope` (details: FcmError, BadRequest — the flipped order). */
+export function invalidTokenEnvelope() {
+    const message = 'The registration token is not a valid FCM registration token';
+    return invalidArgument(message, [fcmError('INVALID_ARGUMENT'), badRequest('message.token', message)]);
+}
+/** oracle: `messaging-send-invalid-topic-name-error-envelope` (details: BadRequest, FcmError). */
+export function invalidTopicNameEnvelope() {
+    const message = 'Topic name contains invalid characters.';
+    return invalidArgument(message, [badRequest('message', message), fcmError('INVALID_ARGUMENT')]);
+}
+/**
+ * oracle: `messaging-send-invalid-condition-error-envelope` — the BARE
+ * envelope: no `details` key at all, only code/message/status.
+ */
+export function invalidConditionEnvelope() {
+    return {
+        status: 400,
+        error: {
+            code: 400,
+            message: 'Request contains an invalid argument.',
+            status: 'INVALID_ARGUMENT',
+        },
+    };
+}
+/**
+ * oracle: `messaging-send-oversized-payload-error-envelope` — the BadRequest
+ * detail carries NO `fieldViolations` key (captured exactly so).
+ */
+export function oversizedPayloadEnvelope() {
+    return invalidArgument('Message is too large. The maximum is 4K (4096 bytes).', [
+        { '@type': BAD_REQUEST },
+        fcmError('INVALID_ARGUMENT'),
+    ]);
+}
+/** oracle: `messaging-send-webpush-invalid-ttl-error-envelope` (details: BadRequest, FcmError). */
+export function invalidWebpushTtlEnvelope() {
+    const message = 'TTL must be a non-negative integer.';
+    return invalidArgument(message, [
+        badRequest('message.webpush.headers.TTL', message),
+        fcmError('INVALID_ARGUMENT'),
+    ]);
+}
+/**
+ * oracle: `messaging-web-deletetoken-unregistered` — the send plane's
+ * eventual answer for a deleted (or never-registered, well-formed) token:
+ * HTTP 404, status NOT_FOUND, a single FcmError detail with errorCode
+ * UNREGISTERED. The observation pins the message as *present* but drops its
+ * text as prod noise; the text below is production's standard NOT_FOUND
+ * message, stated at documentation strength.
+ */
+export function unregisteredTokenEnvelope() {
+    return {
+        status: 404,
+        error: {
+            code: 404,
+            message: 'Requested entity was not found.',
+            status: 'NOT_FOUND',
+            details: [fcmError('UNREGISTERED')],
+        },
+    };
+}
+/** Pull the FcmError errorCode out of an envelope (mirror of the suite's helper). */
+export function fcmErrorCodeOf(envelope) {
+    const detail = envelope.error.details?.find((d) => d['@type'] === FCM_ERROR);
+    return detail?.errorCode;
+}
+/**
+ * A rejected broker operation. Carries the full captured-shape envelope so
+ * admin mirrors (and, later, worker-host op handlers) can re-wrap it into
+ * their own error surface without losing wire fidelity.
+ */
+export class BrokerSendError extends Error {
+    envelope;
+    /** The FcmError errorCode when the envelope carries one (`INVALID_ARGUMENT`, `UNREGISTERED`, …). */
+    errorCode;
+    constructor(envelope) {
+        super(envelope.error.message);
+        this.name = 'BrokerSendError';
+        this.envelope = envelope;
+        this.errorCode = fcmErrorCodeOf(envelope);
+    }
+}
+//# sourceMappingURL=envelopes.js.map

package/dist/messaging/broker/envelopes.js.map

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