API reference: pyric/messaging

Interfaces

DeliverSpec

Properties

Property	Type	Description
`data?`	`Record`<`string`, `string`>	-
`from?`	`string`	-
`messageId?`	`string`	-
`notification?`	{ `body?`: `string`; `image?`: `string`; `title?`: `string`; }	-
`notification.body?`	`string`	-
`notification.image?`	`string`	-
`notification.title?`	`string`	-
`visibilityState?`	`"visible"` \| `"hidden"`	Simulated visibility of the (single) window client at delivery time.

DeliveryResult

Properties

Property	Type	Description
`handlerCount`	`number`	Handlers actually invoked on the chosen route.
`payload`	`DeliveredPayload`	-
`route`	`DeliveryRoute`	-

FcmOptions

Options carried on a client MessagePayload.

Properties

Property	Type
`analyticsLabel?`	`string`
`link?`	`string`

GetTokenOptions

Options for getToken.

Properties

Property	Type	Description
`serviceWorkerRegistration?`	`object`	A (simulated) service-worker registration; token stability keys on its identity.
`vapidKey?`	`string`	-

MessagePayload

Received message envelope delivered to onMessage / onBackgroundMessage. from / collapseKey / messageId are typed required (upstream parity); captured production deliveries carry top-level keys data / from / messageId (+ notification) — collapseKey was not observed on the wire and the sandbox likewise omits it at runtime.

Properties

Property	Type
`collapseKey`	`string`
`data?`	{ [`key`: `string`]: `string`; }
`fcmOptions?`	`FcmOptions`
`from`	`string`
`messageId`	`string`
`notification?`	`NotificationPayload`

Messaging

The FCM Messaging instance mirror — exposes the bound app as app (upstream @firebase/messaging public-types parity).

Properties

Property	Modifier	Type
`app`	`readonly`	`FirebaseApp`

NotificationPayload

Display-notification block inside a MessagePayload.

Properties

Property	Type
`body?`	`string`
`icon?`	`string`
`image?`	`string`
`title?`	`string`

Observer

Type Parameters

Type Parameter
`T`

Properties

Property	Type
`complete`	() => `void`
`error`	(`error`: `Error`) => `void`
`next`	`NextFn`<`T`>

SimulatedServiceWorkerRegistration

Minimal structural stand-in for a ServiceWorkerRegistration in the headless sandbox (bun has no DOM lib). Identity is what matters: token stability is keyed per registration object.

Properties

Property	Modifier	Type
`active`	`readonly`	{ `state`: `"activated"`; }
`active.state`	`readonly`	`"activated"`
`scope`	`readonly`	`string`

Type Aliases

NextFn()

type NextFn<T> = (value: T) => void;

Callback / observer / teardown shapes — structurally identical to the @firebase/util types the upstream entry re-exports (declared locally because @firebase/util is not a direct dependency of pyric; the tier-2 assignability census closes exact type parity).

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`value`	`T`

Returns

void

Unsubscribe()

type Unsubscribe = () => void;

Returns

void

Variables

sandbox

const sandbox: {
  deliver: Promise<DeliveryResult>;
  registration: SimulatedServiceWorkerRegistration;
};

Type Declaration

deliver()

deliver(messaging: Messaging, spec: DeliverSpec): Promise<DeliveryResult>;

Inject a delivery into the client plane, optionally setting the simulated window client’s visibility first. Routes through the broker’s captured visibility rule, so a visible spec lands on onMessage handlers and a hidden spec on onBackgroundMessage handlers.

Parameters

Parameter	Type
`messaging`	`Messaging`
`spec`	`DeliverSpec`

Returns

Promise<DeliveryResult>

registration()

registration(): SimulatedServiceWorkerRegistration;

The module-default simulated service-worker registration.

Returns

SimulatedServiceWorkerRegistration

Functions

deleteToken()

function deleteToken(messaging: Messaging): Promise<boolean>;

Delete the active registration token. Resolves truthy; afterwards no message reaches the client on either route and a send to the dead token surfaces the captured UNREGISTERED envelope on the send plane (oracle: messaging-web-deletetoken-unregistered).

Parameters

Parameter	Type
`messaging`	`Messaging`

Returns

Promise<boolean>

getMessaging()

function getMessaging(app?: FirebaseApp): Messaging;

Return the FCM Messaging instance for the given (or default) app — window-client plane (upstream component name messaging).

Parameters

Parameter	Type
`app?`	`FirebaseApp`

Returns

Messaging

getToken()

function getToken(messaging: Messaging, options?: GetTokenOptions): Promise<string>;

Subscribe the instance to push and resolve its registration token. Sandbox semantics per the captured contract: the minted token matches the production shape class (142 chars, colon-separated, URL-safe, APA91b suffix class) and is STABLE across repeated calls on the same (simulated) service-worker registration — no per-call rotation. Notification permission is modeled as granted in the sandbox.

Parameters

Parameter	Type
`messaging`	`Messaging`
`options?`	`GetTokenOptions`

Returns

Promise<string>

isSupported()

function isSupported(): Promise<boolean>;

Whether every API FCM requires exists here — always true in the sandbox.

Returns

Promise<boolean>

onMessage()

function onMessage(messaging: Messaging, nextOrObserver:
  | NextFn<MessagePayload>
  | Observer<MessagePayload>): Unsubscribe;

Listen for messages delivered while a window client is VISIBLE — routing keys on visibility, never focus (oracle: messaging-web-visibility-routing).

Parameters

Parameter	Type
`messaging`	`Messaging`
`nextOrObserver`	\| `NextFn`<`MessagePayload`> \| `Observer`<`MessagePayload`>

Returns

Unsubscribe