@astronomer-app/signals

TypeScript client for Astronomer Signal Stream.

Signal Stream delivers live signal events while a listener is running. The SDK polls a short-lived JSON endpoint with a cursor, so it works reliably on serverless hosting while still exposing a simple listen() API. A new process starts from the latest signal cursor and does not replay historical events.

Install

npm install @astronomer-app/signals

Listen For Signals

import { AstronomerSignals } from '@astronomer-app/signals';

const client = new AstronomerSignals({
  apiKey: process.env.ASTRONOMER_SIGNAL_STREAM_KEY!,
});

const listener = client.signals.listen({
  onSignal(signal) {
    console.log('New signal:', signal);
  },
  onError(error) {
    console.error(error);
  },
});

// later
await listener.close();

Signal Shape

onSignal receives a SignalEvent:

interface SignalEvent {
  type: 'signal.created';
  createdAt: string;
  signal: {
    id: string;
    symbol: string;
    optionType: 'C' | 'P';
    strikePrice: number;
    expirationDate: string; // ISO date, e.g. "2026-06-18"
  };
}

{
  "type": "signal.created",
  "createdAt": "2026-06-18T11:00:00",
  "signal": {
    "id": "209",
    "symbol": "SPY",
    "optionType": "C",
    "strikePrice": 746,
    "expirationDate": "2026-06-18"
  }
}

The symbol, optionType, strikePrice, and expirationDate fields fully specify a single option contract.

Signal Stream is active during the live signal window from 9:30 AM to 3:00 PM Eastern Time, Monday through Friday.

Local Example

After building the package, run the listener example with a Signal Stream key:

ASTRONOMER_SIGNAL_STREAM_KEY=ast_live_... npm --workspace @astronomer-app/signals run example:listen

For local app testing, pass a custom base URL:

ASTRONOMER_SIGNAL_STREAM_KEY=ast_live_... \
ASTRONOMER_SIGNAL_STREAM_BASE_URL=http://localhost:4200 \
npm --workspace @astronomer-app/signals run example:listen