@astronomer-app/signals 0.0.0

package/README.md

@@ -0,0 +1,55 @@
+# @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
+
+```bash
+npm install @astronomer-app/signals
+```
+
+## Listen For Signals
+
+```ts
+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 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:
+
+```bash
+ASTRONOMER_SIGNAL_STREAM_KEY=ast_live_... npm --workspace @astronomer-app/signals run example:listen
+```
+
+For local app testing, pass a custom base URL:
+
+```bash
+ASTRONOMER_SIGNAL_STREAM_KEY=ast_live_... \
+ASTRONOMER_SIGNAL_STREAM_BASE_URL=http://localhost:4200 \
+npm --workspace @astronomer-app/signals run example:listen
+```

package/dist/client.d.ts

@@ -0,0 +1,12 @@
+import { AstronomerSignalsOptions, ListenOptions, SignalListener } from './types.js';
+export declare class AstronomerSignals {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: AstronomerSignalsOptions);
+    signals: {
+        listen: (options: ListenOptions) => SignalListener;
+    };
+    private listenToSignals;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,aAAa,EAEb,cAAc,EACf,MAAM,YAAY,CAAC;AA4BpB,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,EAAE,wBAAwB;IAc7C,OAAO;0BACa,aAAa,KAAG,cAAc;MAEhD;IAEF,OAAO,CAAC,eAAe;CAkCxB"}

package/dist/client.js

@@ -0,0 +1,217 @@
+const DEFAULT_BASE_URL = 'https://www.astronomerapp.com';
+const DEFAULT_POLL_INTERVAL_MS = 15000;
+const MAX_RECONNECT_DELAY_MS = 30000;
+const MIN_RECONNECT_DELAY_MS = 1000;
+const STREAM_PATH = '/api/v1/signals/stream';
+class SignalStreamRequestError extends Error {
+    constructor(message, retryAfterMs) {
+        super(message);
+        this.name = 'SignalStreamRequestError';
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+export class AstronomerSignals {
+    constructor(options) {
+        this.signals = {
+            listen: (options) => this.listenToSignals(options),
+        };
+        if (!options.apiKey) {
+            throw new Error('AstronomerSignals requires an apiKey');
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        if (!this.fetchImpl) {
+            throw new Error('AstronomerSignals requires a fetch implementation');
+        }
+    }
+    listenToSignals(options) {
+        const controller = new AbortController();
+        const abortSignals = [controller.signal, options.signal].filter(Boolean);
+        let closed = false;
+        let closePromise = null;
+        const close = async () => {
+            if (closed)
+                return;
+            closed = true;
+            controller.abort();
+        };
+        closePromise = runSignalPoller({
+            apiKey: this.apiKey,
+            baseUrl: this.baseUrl,
+            fetchImpl: this.fetchImpl,
+            isClosed: () => closed,
+            options,
+            signal: mergeAbortSignals(abortSignals),
+        }).finally(() => {
+            closed = true;
+            options.onClose?.();
+        });
+        return {
+            async close() {
+                await close();
+                await closePromise;
+            },
+        };
+    }
+}
+async function runSignalPoller({ apiKey, baseUrl, fetchImpl, isClosed, options, signal, }) {
+    // The first request asks the API for the latest queue cursor without emitting
+    // historical rows. After that, each request asks for events after the cursor.
+    let cursor = 'latest';
+    let hasOpened = false;
+    let reconnectAttempt = 0;
+    while (!isClosed() && !signal.aborted) {
+        try {
+            const response = await pollOnce({
+                apiKey,
+                baseUrl,
+                cursor,
+                fetchImpl,
+                signal,
+            });
+            if (!hasOpened) {
+                hasOpened = true;
+                options.onOpen?.();
+            }
+            for (const event of response.events) {
+                options.onSignal(event);
+            }
+            cursor = response.nextCursor ?? cursor;
+            reconnectAttempt = 0;
+            await delay(getNextPollDelay(response, options), signal);
+        }
+        catch (error) {
+            if (isClosed() || signal.aborted) {
+                return;
+            }
+            options.onError?.(error);
+            await delay(getErrorRetryDelay(error, reconnectAttempt), signal);
+            reconnectAttempt += 1;
+        }
+    }
+}
+async function pollOnce({ apiKey, baseUrl, cursor, fetchImpl, signal, }) {
+    const url = new URL(STREAM_PATH, baseUrl);
+    if (cursor) {
+        url.searchParams.set('cursor', cursor);
+    }
+    const response = await fetchImpl(url, {
+        headers: {
+            Accept: 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+        },
+        signal,
+    });
+    if (!response.ok) {
+        throw new SignalStreamRequestError(`Signal Stream request failed with status ${response.status}`, getRetryAfterMs(response));
+    }
+    return parsePollResponse(await response.json());
+}
+function parsePollResponse(data) {
+    if (!isRecord(data) || !Array.isArray(data.events)) {
+        throw new Error('Received malformed Signal Stream response');
+    }
+    const events = data.events.map(parseSignalEvent);
+    const nextCursor = typeof data.nextCursor === 'string' || data.nextCursor === null
+        ? data.nextCursor
+        : null;
+    const retryAfterMs = typeof data.retryAfterMs === 'number' && data.retryAfterMs > 0
+        ? data.retryAfterMs
+        : undefined;
+    const window = isRecord(data.window)
+        ? {
+            open: data.window.open === true,
+            message: typeof data.window.message === 'string'
+                ? data.window.message
+                : undefined,
+        }
+        : undefined;
+    return {
+        events,
+        nextCursor,
+        retryAfterMs,
+        window,
+    };
+}
+function getNextPollDelay(response, options) {
+    if (response.window?.open === false && response.retryAfterMs) {
+        return response.retryAfterMs;
+    }
+    return (options.pollIntervalMs ?? response.retryAfterMs ?? DEFAULT_POLL_INTERVAL_MS);
+}
+function getErrorRetryDelay(error, attempt) {
+    if (error instanceof SignalStreamRequestError &&
+        typeof error.retryAfterMs === 'number') {
+        return error.retryAfterMs;
+    }
+    return getReconnectDelay(attempt);
+}
+function getRetryAfterMs(response) {
+    const retryAfter = response.headers.get('retry-after');
+    if (!retryAfter) {
+        return undefined;
+    }
+    const retryAfterSeconds = Number.parseInt(retryAfter, 10);
+    return Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
+        ? retryAfterSeconds * 1000
+        : undefined;
+}
+function parseSignalEvent(data) {
+    if (!isRecord(data)) {
+        throw new Error('Received malformed Signal Stream event');
+    }
+    const signal = data.signal;
+    if (data.type !== 'signal.created' ||
+        typeof data.id !== 'string' ||
+        typeof data.createdAt !== 'string' ||
+        !isRecord(signal) ||
+        typeof signal.id !== 'string' ||
+        typeof signal.symbol !== 'string' ||
+        (signal.optionType !== 'C' && signal.optionType !== 'P') ||
+        typeof signal.strikePrice !== 'number') {
+        throw new Error('Received malformed Signal Stream event');
+    }
+    return data;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function getReconnectDelay(attempt) {
+    return Math.min(MAX_RECONNECT_DELAY_MS, MIN_RECONNECT_DELAY_MS * 2 ** attempt);
+}
+function delay(durationMs, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const timeout = setTimeout(resolve, durationMs);
+        signal.addEventListener('abort', () => {
+            clearTimeout(timeout);
+            reject(signal.reason);
+        }, { once: true });
+    });
+}
+function mergeAbortSignals(signals) {
+    if (signals.length === 1) {
+        return signals[0];
+    }
+    const controller = new AbortController();
+    const abort = (signal) => {
+        if (!controller.signal.aborted) {
+            controller.abort(signal.reason);
+        }
+    };
+    for (const signal of signals) {
+        if (signal.aborted) {
+            abort(signal);
+            break;
+        }
+        signal.addEventListener('abort', () => abort(signal), { once: true });
+    }
+    return controller.signal;
+}
+function normalizeBaseUrl(baseUrl) {
+    return baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { AstronomerSignals } from './client.js';
+export type { AstronomerSignalsOptions, ListenOptions, SignalEvent, SignalEventType, SignalListener, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EACV,wBAAwB,EACxB,aAAa,EACb,WAAW,EACX,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { AstronomerSignals } from './client.js';

package/dist/types.d.ts

@@ -0,0 +1,31 @@
+export type SignalEventType = 'signal.created';
+export interface SignalEvent {
+    id: string;
+    type: SignalEventType;
+    createdAt: string;
+    signal: {
+        id: string;
+        symbol: string;
+        optionType: 'C' | 'P';
+        strikePrice: number;
+        openedAt?: string;
+        priceAtOpen?: number;
+    };
+}
+export interface AstronomerSignalsOptions {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+export interface ListenOptions {
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+    onSignal(event: SignalEvent): void;
+    onError?(error: unknown): void;
+    onOpen?(): void;
+    onClose?(): void;
+}
+export interface SignalListener {
+    close(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,gBAAgB,CAAC;AAE/C,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,eAAe,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE;QACN,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,GAAG,GAAG,GAAG,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,OAAO,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,MAAM,CAAC,IAAI,IAAI,CAAC;IAChB,OAAO,CAAC,IAAI,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@astronomer-app/signals",
+  "version": "0.0.0",
+  "description": "TypeScript client for Astronomer Signal Stream.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "example:listen": "npm run build && node examples/listen.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "keywords": [
+    "astronomer",
+    "signals",
+    "polling",
+    "trading"
+  ],
+  "license": "UNLICENSED",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  }
+}