@invezgo/sdk 2.0.1 → 2.2.0

package/dist/realtime.d.ts

@@ -0,0 +1,137 @@
+import { InvezgoError } from './errors';
+export declare const DEFAULT_REALTIME_URL = "wss://api.invezgo.com/ws";
+/** One running-trade row. */
+export interface RealtimeTrade {
+    /** Exchange trade id (string: exceeds the JS safe integer range). */
+    id: string;
+    /** `HHMMSS` (WIB). */
+    time: string;
+    code: string;
+    price: number;
+    lot: number;
+    /** Rupiah: `price * lot * 100`. */
+    value: number;
+    change: number;
+    side: 'buy' | 'sell';
+}
+export interface ConnectedMessage {
+    type: 'connected';
+}
+export interface PongMessage {
+    type: 'pong';
+}
+export interface SubscribedMessage {
+    type: 'subscribed';
+    channel: 'trades' | 'orderbook';
+    /** `"*"` when subscribed to every stock. */
+    codes: string[] | '*';
+    min_lot?: number;
+    min_value?: number;
+}
+export interface ErrorMessage {
+    type: 'error';
+    message: string;
+}
+export interface LaggedMessage {
+    type: 'lagged';
+    missed: number;
+}
+export interface TradesMessage {
+    type: 'trades';
+    /** Server send time, Unix milliseconds. */
+    ts: number;
+    data: RealtimeTrade[];
+}
+export interface OrderbookMessage {
+    type: 'orderbook';
+    code: string;
+    side: 'bid' | 'offer';
+    /** Every price level of this side (shape not documented). */
+    levels: unknown[];
+    seq: number | null;
+}
+/** Any server message; unknown `type`s are delivered as-is. */
+export type RealtimeMessage = ConnectedMessage | PongMessage | SubscribedMessage | ErrorMessage | LaggedMessage | TradesMessage | OrderbookMessage | {
+    type: string;
+    [key: string]: unknown;
+};
+/** Event name → listener payload. */
+export interface RealtimeEvents {
+    connected: ConnectedMessage;
+    subscribed: SubscribedMessage;
+    trades: TradesMessage;
+    orderbook: OrderbookMessage;
+    pong: PongMessage;
+    lagged: LaggedMessage;
+    /** Every server message, including unknown types. */
+    message: RealtimeMessage;
+    /** Handshake/connection failures and server `error` messages (as `ValidationError`). */
+    error: InvezgoError;
+    close: {
+        code: number;
+        reason: string;
+    };
+    /** A reconnect is scheduled in `delay` seconds; backfill via REST after the next `connected`. */
+    reconnect: {
+        attempt: number;
+        delay: number;
+    };
+}
+/** Minimal WebSocket shape used by the client (WHATWG `WebSocket` or the `ws` package). */
+export interface WebSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((ev: any) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((ev: any) => void) | null;
+    onclose: ((ev: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+}
+export type WebSocketConstructor = new (url: string, options: {
+    headers: Record<string, string>;
+}) => WebSocketLike;
+export interface RealtimeOptions {
+    /** API key of an account with an active Elite plan. */
+    apiKey: string;
+    /** Default `wss://api.invezgo.com/ws`. */
+    url?: string;
+    /** Reconnect with backoff (1, 2, 4 … 30 s) after a drop. Default `true`. */
+    reconnect?: boolean;
+    /**
+     * WebSocket implementation accepting `new WebSocket(url, { headers })`, e.g. `require('ws')`.
+     * Defaults to the global `WebSocket` on Node >= 22.
+     */
+    WebSocket?: WebSocketConstructor;
+}
+export interface TradesFilter {
+    /** Only trades with `lot >= minLot` (`0` clears). */
+    minLot?: number;
+    /** Only trades with `value >= minValue` Rupiah (`0` clears). */
+    minValue?: number;
+}
+/**
+ * Real-time running trade and order book stream (`wss://api.invezgo.com/ws`, Elite plan).
+ * Connects on construction; subscriptions are queued until `connected` and replayed after every reconnect.
+ */
+export declare class InvezgoRealtime {
+    #private;
+    constructor(options: RealtimeOptions);
+    on<K extends keyof RealtimeEvents>(event: K, fn: (payload: RealtimeEvents[K]) => void): this;
+    off<K extends keyof RealtimeEvents>(event: K, fn: (payload: RealtimeEvents[K]) => void): this;
+    /** Running trades for `codes`, or every stock when `codes` is omitted. */
+    subscribeTrades(codes?: string[], filter?: TradesFilter): void;
+    /** Order book for `codes` (1 to 20 codes per connection). */
+    subscribeOrderbook(codes: string[]): void;
+    /** Stop `codes` on `channel`, or the whole channel (and trade filters) when `codes` is omitted. */
+    unsubscribe(channel: 'trades' | 'orderbook', codes?: string[]): void;
+    /** Server answers with a `pong` event. */
+    ping(): void;
+    /** Close for good (no reconnect). */
+    close(): void;
+}
+//# sourceMappingURL=realtime.d.ts.map

package/dist/realtime.d.ts.map

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

package/dist/webhook.d.ts

@@ -0,0 +1,90 @@
+/** Why a webhook delivery was rejected. */
+export type WebhookVerificationReason = 'timestamp' | 'signature' | 'payload';
+/** Thrown by {@link verifyWebhook} / {@link parseWebhook}. Not an HTTP API error. */
+export declare class WebhookVerificationError extends Error {
+    readonly reason: WebhookVerificationReason;
+    constructor(reason: WebhookVerificationReason, message: string, cause?: unknown);
+}
+/** `data` of every `update.*` event. */
+export interface WebhookUpdateData {
+    /** `YYYY-MM-DD` (`YYYY-MM-DD HH:mm:ss` WIB for `update.news`). */
+    date: string;
+    /** API endpoints whose data changed. */
+    path: string[];
+    code?: string;
+    title?: string;
+}
+export interface WebhookAlertStock {
+    code: string;
+    price: number;
+}
+/** `data` of `alert.triggered`. */
+export interface WebhookAlertTriggeredData {
+    alert_id: string;
+    alert_name: string;
+    stocks_in: WebhookAlertStock[];
+    stocks_out: WebhookAlertStock[];
+}
+/** `data` of `alert.disabled`. */
+export interface WebhookAlertDisabledData {
+    alert_id: string;
+    alert_name: string;
+    reason: string;
+}
+/** `data` of `test.ping`. */
+export interface WebhookTestPingData {
+    message: string;
+}
+/** `data` of `quota.low` / `quota.exhausted`. */
+export interface WebhookQuotaData {
+    plan: string;
+    limit: number;
+    used: number;
+    remaining: number;
+    /** Unix seconds. */
+    reset_at: number | null;
+}
+type UpdateType = 'summary' | 'notation' | 'news' | 'disclosure' | 'financial' | 'five' | 'one' | 'classification' | 'ksei' | 'hsc' | 'shareholder' | 'insider' | 'uma' | 'suspend' | 'calendar';
+/** Documented event name (`{domain}.{type}`) → `data` type. */
+export type WebhookEventMap = {
+    [K in `update.${UpdateType}`]: WebhookUpdateData;
+} & {
+    'alert.triggered': WebhookAlertTriggeredData;
+    'alert.disabled': WebhookAlertDisabledData;
+    'test.ping': WebhookTestPingData;
+    'quota.low': WebhookQuotaData;
+    'quota.exhausted': WebhookQuotaData;
+};
+/** A webhook delivery. `domain`/`type` are plain strings so new events never break decoding. */
+export interface WebhookEvent<D = Record<string, unknown>> {
+    /** Delivery id (same as `X-Invezgo-Delivery`); stable across retries, use it to deduplicate. */
+    id: string;
+    domain: string;
+    type: string;
+    /** Unix seconds. */
+    created_at: number;
+    data: D;
+    /** `"{domain}.{type}"`, e.g. `update.summary`. */
+    event: string;
+}
+/** Narrow an event to a documented event name so `data` gets its typed shape. */
+export declare function isWebhookEvent<K extends keyof WebhookEventMap>(event: WebhookEvent<unknown>, name: K): event is WebhookEvent<WebhookEventMap[K]>;
+/** Request headers: a `Headers` instance, Node's `req.headers`, or `{ signature, timestamp }`. */
+export type WebhookHeaders = Headers | Record<string, string | string[] | undefined>;
+export interface VerifyWebhookOptions {
+    /** Maximum age/skew of `X-Invezgo-Timestamp` in seconds. Default `300`. */
+    tolerance?: number;
+    /** Current Unix time in seconds (for tests). Default `Date.now() / 1000`. */
+    now?: number;
+}
+/** Decode a webhook body without verifying it (tests or already-verified bodies). */
+export declare function parseWebhook<D = Record<string, unknown>>(rawBody: string | Uint8Array): WebhookEvent<D>;
+/**
+ * Verify the `X-Invezgo-Signature` of a webhook delivery and decode it.
+ *
+ * `rawBody` must be the exact bytes/string received, before any JSON parsing.
+ * Throws {@link WebhookVerificationError} with `reason` `timestamp`, `signature` or `payload`.
+ */
+export declare function verifyWebhook<D = Record<string, unknown>>(rawBody: string | Uint8Array, headers: WebhookHeaders, secret: string, options?: VerifyWebhookOptions): Promise<WebhookEvent<D>>;
+export {};
+//# sourceMappingURL=webhook.d.ts.map

package/dist/webhook.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invezgo/sdk",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "Official Invezgo API SDK for JavaScript & TypeScript: fully typed access to Indonesia Stock Exchange (IDX/BEI) data with built-in LRU caching and API key rotation",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -25,7 +25,7 @@
     "generate": "python ../codegen/generate.py ts",
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && rollup -c rollup.config.mjs && tsc --emitDeclarationOnly --outDir dist",
     "typecheck": "tsc --noEmit && tsc --noEmit -p examples",
-    "test": "npm run build && node --test test/client.test.mjs",
+    "test": "npm run build && node --test test/client.test.mjs test/webhook.test.mjs test/realtime.test.mjs",
     "prepublishOnly": "npm run typecheck && npm test"
   },
   "keywords": [