Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.photon.codes/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Custom events

Platform providers can emit events beyond messages — typing indicators, read receipts, delivery status, whatever the provider chooses to surface. Spectrum exposes each event as a flat async iterable on the app instance: 
for await (const event of app.typing) {
  console.log(`${event.platform}: typing event received`);
}
The property name matches the event name the provider declared. Events are merged across every provider that emits them, and each payload is annotated with a platform field so you know the source.

​
Lazy streams

Event streams are created lazily on first access. Accessing app.typing once kicks off the underlying listener; subsequent iterations share the same source.

​
Per-platform access

The same events are available on a narrowed platform instance, scoped to that platform only: 
import { imessage } from "spectrum-ts/providers/imessage";

const im = imessage(app);
for await (const event of im.typing) {
  // iMessage-only typing events
}
Use the flat form on app when you want a merged feed across platforms; use the narrowed form when you only care about one.

​
Lifecycle

​
Graceful shutdown

await app.stop();
This closes the merged message stream, drains and disposes every custom event stream, tears down every platform client via its lifecycle.destroyClient hook (if one is defined), and flushes any pending telemetry data when telemetry is enabled. It’s idempotent — calling stop() twice is safe.

​
Signal handling

Spectrum registers SIGINT and SIGTERM handlers on startup. When a signal fires:
  1. stop() is invoked with a 3-second timeout.
  2. If cleanup completes in time, the process exits with code 0.
  3. If not, the process exits with code 1.
You don’t need to wire this up yourself — running your app in a container with docker stop or hitting Ctrl-C in a terminal will drain cleanly.

​
When to call stop() manually

  • You’re embedding Spectrum in a longer-running process and want to tear it down without exiting.
  • You’re writing tests that create and dispose an app per case.
  • You want deterministic cleanup before re-initializing with a different provider set.