@yoyomq/ije-core 0.1.0

package/README.md

@@ -0,0 +1,30 @@
+<p align="center">
+  <img src="../../assets/yoyo.svg" width="56" height="56" alt="Yoyo" />
+</p>
+
+<h1 align="center">@yoyomq/ije-core</h1>
+
+<p align="center">Runtime core for the Ije SDK by <strong>Yoyo</strong>.</p>
+
+---
+
+This package exposes the `Ije` singleton — the runtime that powers every Ije
+widget. It handles initialization, theming, the real-time MQTT connection, and the
+insights/chat API.
+
+```ts
+import { Ije } from '@yoyomq/ije-core';
+
+await Ije.init({ apiKey: 'YOUR_YOYO_API_KEY', theme: { primaryColor: '#8A2BE2' } });
+
+// Natural-language insights
+const res = await Ije.chat.ask('How many devices reported in the last hour?');
+
+// Raw real-time streams (the UI widgets use these for you)
+Ije.mqtt.subscribe('device/truck-001/telemetry', (p) => console.log(p.speed));
+```
+
+It's usually paired with [`@yoyomq/ije-ui`](../ui) for the drop-in `<ije-*>`
+components.
+
+📖 **Full documentation:** see the [Ije SDK README](../../README.md).

package/dist/chatClient.d.ts

@@ -0,0 +1,22 @@
+import type { SdkConfig } from './index';
+export interface ChatChartSpec {
+    chart_type: 'bar' | 'line' | 'pie' | 'scatter' | 'table';
+    title: string;
+    labels: string[];
+    datasets: Array<{
+        label: string;
+        data: number[];
+    }>;
+}
+export interface ChatResponse {
+    session_id: string;
+    answer: string;
+    chart?: ChatChartSpec;
+}
+export declare class IjeChatClient {
+    private sessionId;
+    private http;
+    _setConfig(config: SdkConfig): void;
+    ask(question: string): Promise<ChatResponse>;
+    resetSession(): void;
+}

package/dist/chatClient.js

@@ -0,0 +1,16 @@
+import { IjeHttpClient } from './httpClient';
+export class IjeChatClient {
+    sessionId = null;
+    http = new IjeHttpClient();
+    _setConfig(config) {
+        this.http._setConfig(config);
+    }
+    async ask(question) {
+        const data = await this.http.post('/public/api/v1/apigateway/mimir/insights/query', { session_id: this.sessionId, question });
+        this.sessionId = data.session_id;
+        return data;
+    }
+    resetSession() {
+        this.sessionId = null;
+    }
+}

package/dist/httpClient.d.ts

@@ -0,0 +1,18 @@
+import type { SdkConfig } from './index';
+type ScalarParam = string | number | boolean | undefined | null;
+interface GetOptions {
+    params?: Record<string, ScalarParam>;
+    arrayParams?: Record<string, (string | number)[]>;
+}
+interface PostOptions {
+}
+export declare class IjeHttpClient {
+    private config;
+    _setConfig(config: SdkConfig): void;
+    get<T>(path: string, options?: GetOptions): Promise<T>;
+    post<T>(path: string, body: unknown, _options?: PostOptions): Promise<T>;
+    private buildUrl;
+    private buildHeaders;
+    private parseResponse;
+}
+export {};

package/dist/httpClient.js

@@ -0,0 +1,55 @@
+export class IjeHttpClient {
+    config = null;
+    _setConfig(config) {
+        this.config = config;
+    }
+    async get(path, options = {}) {
+        const url = this.buildUrl(path, options.params, options.arrayParams);
+        const response = await fetch(url, {
+            headers: this.buildHeaders(),
+        });
+        return this.parseResponse(response);
+    }
+    async post(path, body, _options = {}) {
+        const url = this.buildUrl(path);
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...this.buildHeaders(),
+            },
+            body: JSON.stringify(body),
+        });
+        return this.parseResponse(response);
+    }
+    buildUrl(path, params, arrayParams) {
+        if (!this.config)
+            throw new Error('[Yoyo ije] SDK must be initialized before making requests.');
+        const url = new URL(`${this.config.apiUrl}${path}`);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                if (value != null)
+                    url.searchParams.append(key, String(value));
+            }
+        }
+        if (arrayParams) {
+            for (const [key, values] of Object.entries(arrayParams)) {
+                for (const value of values)
+                    url.searchParams.append(key, String(value));
+            }
+        }
+        return url.toString();
+    }
+    buildHeaders() {
+        if (!this.config)
+            throw new Error('[Yoyo ije] SDK must be initialized before making requests.');
+        return { YOYO_API_KEY: this.config.apiKey };
+    }
+    async parseResponse(response) {
+        if (!response.ok) {
+            const body = await response.text().catch(() => '');
+            throw new Error(`[Yoyo ije] Request failed: ${response.status} ${body}`);
+        }
+        return response.json();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import { IjeMqttManager } from './mqttManager';
+import { IjeChatClient } from './chatClient';
+import { IjeTripsClient } from './tripsClient';
+import { IjeHttpClient } from './httpClient';
+export type { ChatChartSpec, ChatResponse } from './chatClient';
+export type { IjeTrigger, IjeDevice, IjeAggregatedEvent, IjeAggregatedEventDetail, IjeDeviceDataPoint, IjeTriggersResponse, IjeDevicesResponse, IjeAggregatedEventsResponse, IjeDeviceDataResponse, ListAggregatedEventsParams, GetDeviceDataParams, } from './tripsClient';
+export { IjeTripsClient } from './tripsClient';
+export { IjeHttpClient } from './httpClient';
+export interface SdkConfig {
+    /**
+     * Your Yoyo API key. Used as the `YOYO_API_KEY` header for all API calls
+     * and as the MQTT credential for live data streams.
+     * Get one from https://yoyomq.com → Settings → API Keys.
+     */
+    apiKey: string;
+    /**
+     * Organization UUID used to build MQTT subscription topics.
+     * Populated automatically by init() via GET /public/api/v1/context;
+     * override only if you need to bypass that fetch.
+     */
+    organizationId?: string;
+    theme?: {
+        primaryColor?: string;
+        fontFamily?: string;
+        borderRadius?: string;
+    };
+    apiUrl?: string;
+    mqttUrl?: string;
+    /** When true, the SDK logs every incoming MQTT message and coordinate parse result to the console. */
+    debug?: boolean;
+}
+export declare class IjeSDK {
+    private static instance;
+    config: SdkConfig | null;
+    isInitialized: boolean;
+    mqtt: IjeMqttManager;
+    chat: IjeChatClient;
+    trips: IjeTripsClient;
+    http: IjeHttpClient;
+    private constructor();
+    static getInstance(): IjeSDK;
+    init(config: SdkConfig): Promise<void>;
+}
+/**
+ * Access the Ije SDK by Yoyo
+ */
+export declare const Ije: IjeSDK;

package/dist/index.js

@@ -0,0 +1,75 @@
+import { IjeMqttManager } from './mqttManager';
+import { IjeChatClient } from './chatClient';
+import { IjeTripsClient } from './tripsClient';
+import { IjeHttpClient } from './httpClient';
+export { IjeTripsClient } from './tripsClient';
+export { IjeHttpClient } from './httpClient';
+export class IjeSDK {
+    static instance;
+    config = null;
+    isInitialized = false;
+    mqtt;
+    chat;
+    trips;
+    http;
+    constructor() {
+        this.mqtt = new IjeMqttManager();
+        this.chat = new IjeChatClient();
+        this.trips = new IjeTripsClient();
+        this.http = new IjeHttpClient();
+    }
+    static getInstance() {
+        if (!IjeSDK.instance) {
+            IjeSDK.instance = new IjeSDK();
+        }
+        return IjeSDK.instance;
+    }
+    async init(config) {
+        if (this.isInitialized) {
+            console.warn('[Yoyo ije] SDK is already initialized');
+            return;
+        }
+        this.config = {
+            apiUrl: 'https://api.yoyomq.com',
+            mqttUrl: 'wss://mqtt.yoyomq.com',
+            // Strip undefined values so callers passing `mqttUrl: undefined` (e.g.
+            // when an env var isn't set) don't silently clobber built-in defaults.
+            ...Object.fromEntries(Object.entries(config).filter(([, v]) => v !== undefined)),
+        };
+        this.chat._setConfig(this.config);
+        this.trips._setConfig(this.config);
+        this.http._setConfig(this.config);
+        // Resolve the organization UUID so UI widgets can build correct MQTT topics.
+        // Non-fatal: widgets fall back to legacy topic format when not available.
+        if (!this.config.organizationId) {
+            try {
+                const ctx = await this.http.get('/public/api/v1/context');
+                if (ctx.organization_id) {
+                    this.config.organizationId = ctx.organization_id;
+                }
+            }
+            catch {
+                console.warn('[Yoyo ije] Could not resolve organization ID; live tracking topic may not match');
+            }
+        }
+        this.mqtt.setDebug(this.config.debug ?? false);
+        // Open the real-time MQTT connection that backs the tracking/telemetry
+        // widgets. Non-fatal: connection failures retry in the background so a
+        // broker hiccup never breaks init() or the rest of the dashboard.
+        if (this.config.mqttUrl) {
+            this.mqtt.connect(this.config.mqttUrl, this.config.apiKey);
+        }
+        if (this.config.theme && typeof document !== 'undefined') {
+            const root = document.documentElement;
+            if (this.config.theme.primaryColor) {
+                root.style.setProperty('--yoyo-primary', this.config.theme.primaryColor);
+            }
+        }
+        this.isInitialized = true;
+        console.log('[Yoyo ije] SDK initialized');
+    }
+}
+/**
+ * Access the Ije SDK by Yoyo
+ */
+export const Ije = IjeSDK.getInstance();

package/dist/mqttManager.d.ts

@@ -0,0 +1,15 @@
+type MessageHandler = (payload: Record<string, any>) => void;
+export declare class IjeMqttManager {
+    readonly subscriptions: Map<string, Set<MessageHandler>>;
+    private client;
+    private debug;
+    setDebug(enabled: boolean): void;
+    subscribe(topic: string, handler: MessageHandler): void;
+    unsubscribe(topic: string, handler: MessageHandler): void;
+    dispatch(topic: string, payload: Record<string, any>): void;
+    connect(url: string, token: string): void;
+    disconnect(): void;
+    private brokerSubscribe;
+    private parsePayload;
+}
+export {};

package/dist/mqttManager.js

@@ -0,0 +1,133 @@
+import mqtt from 'mqtt';
+export class IjeMqttManager {
+    // Keyed by topic — components subscribe/unsubscribe via these Sets
+    subscriptions = new Map();
+    client = null;
+    debug = false;
+    setDebug(enabled) {
+        this.debug = enabled;
+    }
+    subscribe(topic, handler) {
+        let handlers = this.subscriptions.get(topic);
+        const isNewTopic = !handlers;
+        if (!handlers) {
+            handlers = new Set();
+            this.subscriptions.set(topic, handlers);
+        }
+        handlers.add(handler);
+        // Components routinely subscribe before connect() runs (custom elements
+        // upgrade on page load, init() happens later). When that's the case we only
+        // register locally here — the 'connect' handler resubscribes every known
+        // topic at the broker. If we're already live, subscribe the new topic now.
+        if (isNewTopic && this.client?.connected) {
+            this.brokerSubscribe(topic);
+        }
+    }
+    unsubscribe(topic, handler) {
+        const handlers = this.subscriptions.get(topic);
+        if (!handlers)
+            return;
+        handlers.delete(handler);
+        // Once nothing on the page cares about a topic, stop receiving it.
+        if (handlers.size === 0) {
+            this.subscriptions.delete(topic);
+            this.client?.unsubscribe(topic);
+        }
+    }
+    // Dispatches a message to all subscribers of a topic — used by the real MQTT
+    // client (see the 'message' handler in connect) and by the demo mock loop to
+    // inject synthetic payloads.
+    dispatch(topic, payload) {
+        if (this.debug) {
+            const count = this.subscriptions.get(topic)?.size ?? 0;
+            console.log(`[Yoyo ije][MQTT dispatch] ${topic} → ${count} handler(s)`);
+        }
+        this.subscriptions.get(topic)?.forEach(h => h(payload));
+    }
+    connect(url, token) {
+        // Idempotent — init() may run more than once and components must not each
+        // open their own socket.
+        if (this.client)
+            return;
+        const options = {
+            // Matches the production frontend connect path (yoyo-frontend
+            // lib/mqtt/mqtt.service.ts): the session JWT is sent as the MQTT
+            // username and the password is the static string 'any'.
+            username: token,
+            password: 'any',
+            // Intentionally do not force protocolVersion — the broker negotiates it.
+            // The proven frontend path leaves this unset (mqtt.js default 3.1.1);
+            // forcing v5 risks rejected connections on a 3.1.1-configured broker.
+            reconnectPeriod: 1000,
+            connectTimeout: 30_000,
+            clean: true,
+        };
+        let client;
+        try {
+            client = mqtt.connect(url, options);
+        }
+        catch (err) {
+            console.error('[Yoyo ije] MQTT connection failed to start:', err);
+            return;
+        }
+        this.client = client;
+        client.on('connect', () => {
+            console.log(`[Yoyo ije] MQTT connected (${url})`);
+            // (Re)subscribe to every topic a component has registered interest in.
+            // Covers both the initial connect and any reconnect after a drop.
+            for (const topic of this.subscriptions.keys()) {
+                this.brokerSubscribe(topic);
+            }
+        });
+        client.on('message', (topic, message) => {
+            const payload = this.parsePayload(message);
+            if (this.debug) {
+                console.log('[Yoyo ije][MQTT]', topic, payload ?? `<unparseable: ${new TextDecoder().decode(message)}>`);
+            }
+            if (payload)
+                this.dispatch(topic, payload);
+        });
+        client.on('error', err => console.error('[Yoyo ije] MQTT error:', err.message));
+        client.on('offline', () => console.warn('[Yoyo ije] MQTT offline — will retry'));
+    }
+    disconnect() {
+        this.client?.end(true);
+        this.client = null;
+    }
+    brokerSubscribe(topic) {
+        this.client?.subscribe(topic, { qos: 0 }, err => {
+            if (err) {
+                console.error(`[Yoyo ije] Failed to subscribe to ${topic}:`, err.message);
+            }
+            else if (this.debug) {
+                console.log(`[Yoyo ije][MQTT] subscribed ✓ ${topic}`);
+            }
+        });
+    }
+    // Device payloads are JSON. The backend wraps device data in a single-element
+    // array ([{...}]); unwrap it so widgets always receive a plain object.
+    parsePayload(message) {
+        let text;
+        try {
+            text = new TextDecoder().decode(message);
+        }
+        catch {
+            return null;
+        }
+        if (!text)
+            return null;
+        try {
+            const parsed = JSON.parse(text);
+            const obj = Array.isArray(parsed) ? parsed[0] : parsed;
+            if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+                return obj;
+            }
+            console.warn('[Yoyo ije] Ignoring non-object MQTT payload');
+            return null;
+        }
+        catch {
+            console.warn('[Yoyo ije] Ignoring malformed MQTT payload');
+            return null;
+        }
+    }
+}

package/dist/src/chatClient.d.ts

@@ -0,0 +1,22 @@
+import type { SdkConfig } from './index';
+export interface ChatChartSpec {
+    chart_type: 'bar' | 'line' | 'pie' | 'scatter' | 'table';
+    title: string;
+    labels: string[];
+    datasets: Array<{
+        label: string;
+        data: number[];
+    }>;
+}
+export interface ChatResponse {
+    session_id: string;
+    answer: string;
+    chart?: ChatChartSpec;
+}
+export declare class IjeChatClient {
+    private sessionId;
+    private config;
+    _setConfig(config: SdkConfig): void;
+    ask(question: string): Promise<ChatResponse>;
+    resetSession(): void;
+}

package/dist/src/chatClient.js

@@ -0,0 +1,32 @@
+export class IjeChatClient {
+    sessionId = null;
+    config = null;
+    _setConfig(config) {
+        this.config = config;
+    }
+    async ask(question) {
+        if (!this.config) {
+            throw new Error('[Yoyo ije] SDK must be initialized before using chat.');
+        }
+        const response = await fetch(`${this.config.apiUrl}/api/v1/apigateway/mimir/insights/query`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.config.token}`,
+            },
+            body: JSON.stringify({
+                session_id: this.sessionId,
+                question,
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`[Yoyo ije] Chat query failed: ${response.status}`);
+        }
+        const data = await response.json();
+        this.sessionId = data.session_id;
+        return data;
+    }
+    resetSession() {
+        this.sessionId = null;
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,27 @@
+import { IjeMqttManager } from './mqttManager';
+import { IjeChatClient } from './chatClient';
+export type { ChatChartSpec, ChatResponse } from './chatClient';
+export interface SdkConfig {
+    token: string;
+    theme?: {
+        primaryColor?: string;
+        fontFamily?: string;
+        borderRadius?: string;
+    };
+    apiUrl?: string;
+    mqttUrl?: string;
+}
+export declare class IjeSDK {
+    private static instance;
+    config: SdkConfig | null;
+    isInitialized: boolean;
+    mqtt: IjeMqttManager;
+    chat: IjeChatClient;
+    private constructor();
+    static getInstance(): IjeSDK;
+    init(config: SdkConfig): Promise<void>;
+}
+/**
+ * Access the Ije SDK by Yoyo
+ */
+export declare const Ije: IjeSDK;

package/dist/src/index.js

@@ -0,0 +1,59 @@
+import { IjeMqttManager } from './mqttManager';
+import { IjeChatClient } from './chatClient';
+export class IjeSDK {
+    static instance;
+    config = null;
+    isInitialized = false;
+    mqtt;
+    chat;
+    constructor() {
+        this.mqtt = new IjeMqttManager();
+        this.chat = new IjeChatClient();
+    }
+    static getInstance() {
+        if (!IjeSDK.instance) {
+            IjeSDK.instance = new IjeSDK();
+        }
+        return IjeSDK.instance;
+    }
+    async init(config) {
+        if (this.isInitialized) {
+            console.warn('[Yoyo ije] SDK is already initialized');
+            return;
+        }
+        this.config = {
+            apiUrl: 'https://api.yoyomq.com',
+            mqttUrl: 'wss://mqtt.yoyomq.com',
+            ...config,
+        };
+        this.chat._setConfig(this.config);
+        try {
+            const response = await fetch(`${this.config.apiUrl}/api/v1/sdk/authenticate`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${config.token}`,
+                },
+            });
+            if (response.ok) {
+                const data = await response.json();
+                this.mqtt.connect(this.config.mqttUrl, data.mqttToken);
+            }
+        }
+        catch {
+            // MQTT is best-effort — insights chat works without it.
+        }
+        if (this.config.theme && typeof document !== 'undefined') {
+            const root = document.documentElement;
+            if (this.config.theme.primaryColor) {
+                root.style.setProperty('--yoyo-primary', this.config.theme.primaryColor);
+            }
+        }
+        this.isInitialized = true;
+        console.log('[Yoyo ije] SDK initialized');
+    }
+}
+/**
+ * Access the Ije SDK by Yoyo
+ */
+export const Ije = IjeSDK.getInstance();

package/dist/src/mqttManager.d.ts

@@ -0,0 +1,9 @@
+type MessageHandler = (payload: Record<string, any>) => void;
+export declare class IjeMqttManager {
+    readonly subscriptions: Map<string, Set<MessageHandler>>;
+    subscribe(topic: string, handler: MessageHandler): void;
+    unsubscribe(topic: string, handler: MessageHandler): void;
+    dispatch(topic: string, payload: Record<string, any>): void;
+    connect(url: string, token: string): void;
+}
+export {};

package/dist/src/mqttManager.js

@@ -0,0 +1,22 @@
+export class IjeMqttManager {
+    // Keyed by topic — components subscribe/unsubscribe via these Sets
+    subscriptions = new Map();
+    subscribe(topic, handler) {
+        if (!this.subscriptions.has(topic)) {
+            this.subscriptions.set(topic, new Set());
+        }
+        this.subscriptions.get(topic).add(handler);
+    }
+    unsubscribe(topic, handler) {
+        this.subscriptions.get(topic)?.delete(handler);
+    }
+    // Dispatches a message to all subscribers of a topic — used by the real MQTT
+    // client and by the demo mock loop to inject synthetic payloads.
+    dispatch(topic, payload) {
+        this.subscriptions.get(topic)?.forEach(h => h(payload));
+    }
+    connect(url, token) {
+        // Real MQTT-over-WebSocket connection — to be implemented
+        console.log(`[Yoyo ije] MQTT ready (${url})`);
+    }
+}

package/dist/tripsClient.d.ts

@@ -0,0 +1,118 @@
+import type { SdkConfig } from './index';
+/** A user-created Trigger and what it aggregates (public view). */
+export interface IjeTrigger {
+    id: number;
+    uuid: string;
+    name: string;
+    status: boolean;
+    events: string[];
+    aggregators: {
+        key: string;
+        data_key: string | null;
+    }[];
+    created_at: string;
+    updated_at: string;
+}
+/** A Device the API key's Organization owns (only the fields the SDK relies on are typed). */
+export interface IjeDevice {
+    device_id: number;
+    name: string;
+    identifier: string;
+    [key: string]: unknown;
+}
+/** Lightweight aggregated-event list item: identity + window + whether it carries a route. */
+export interface IjeAggregatedEvent {
+    id: number;
+    event_group_id: number;
+    device_id: number;
+    trigger_id: number;
+    msg_start_time: string;
+    msg_end_time: string;
+    has_route: boolean;
+}
+/** One aggregated event with its full message_content. */
+export interface IjeAggregatedEventDetail {
+    id: number;
+    event_group_id: number;
+    device_id: number;
+    trigger_id: number;
+    msg_start_time: string;
+    msg_end_time: string;
+    message_content: Record<string, unknown>;
+}
+/** One raw telemetry row. `data` holds the device payload (lat/lng live here). */
+export interface IjeDeviceDataPoint {
+    id: number;
+    device_id: number;
+    message_timestamp: string;
+    server_timestamp: string;
+    data: Record<string, any>;
+    created_at: string;
+}
+export interface IjeTriggersResponse {
+    triggers: IjeTrigger[];
+    total: number;
+}
+export interface IjeDevicesResponse {
+    devices: IjeDevice[];
+    total: number;
+}
+export interface IjeAggregatedEventsResponse {
+    aggregated_events: IjeAggregatedEvent[];
+    total: number;
+}
+export interface IjeDeviceDataResponse {
+    data: IjeDeviceDataPoint[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+export interface ListAggregatedEventsParams {
+    triggerId: number;
+    deviceIds?: number[];
+    /** Window start, Unix seconds (filters msg_start_time). */
+    startsAt?: number;
+    /** Window end, Unix seconds (filters msg_start_time). */
+    endsAt?: number;
+    hasRoute?: boolean;
+    sortOrder?: 'ASC' | 'DESC';
+    limit?: number;
+    offset?: number;
+}
+export interface GetDeviceDataParams {
+    deviceIds?: number[];
+    /** JSONB expression for filtering the data field (e.g. "timestamp >= 1764234113000 AND timestamp <= 1764236012000"). Timestamps must be in milliseconds. */
+    partialQueryExpression?: string;
+    order?: 'ASC' | 'DESC';
+    limit?: number;
+    offset?: number;
+}
+export declare class IjeTripsClient {
+    private http;
+    private config;
+    _setConfig(config: SdkConfig): void;
+    listTriggers(params?: {
+        searchText?: string;
+        limit?: number;
+        offset?: number;
+        deviceId?: number;
+    }): Promise<IjeTriggersResponse>;
+    listDevices(params?: {
+        searchText?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<IjeDevicesResponse>;
+    listAggregatedEvents(params: ListAggregatedEventsParams): Promise<IjeAggregatedEventsResponse>;
+    getAggregatedEvent(id: number): Promise<IjeAggregatedEventDetail>;
+    getDeviceData(params: GetDeviceDataParams): Promise<IjeDeviceDataResponse>;
+    /**
+     * Fetches all telemetry for a window by paging through device_data and returns
+     * chronological [lng, lat] pairs ready for maplibre.
+     * startsAt and endsAt are Unix milliseconds.
+     */
+    getTripPath(params: {
+        deviceIds: number[];
+        startsAt: number;
+        endsAt: number;
+    }): Promise<[number, number][]>;
+}

package/dist/tripsClient.js

@@ -0,0 +1,97 @@
+import { IjeHttpClient } from './httpClient';
+export class IjeTripsClient {
+    http = new IjeHttpClient();
+    config = null;
+    _setConfig(config) {
+        this.config = config;
+        this.http._setConfig(config);
+    }
+    listTriggers(params = {}) {
+        return this.http.get('/public/api/v1/triggers', {
+            params: { searchText: params.searchText, limit: params.limit, offset: params.offset, deviceId: params.deviceId },
+        });
+    }
+    listDevices(params = {}) {
+        return this.http.get('/public/api/v1/devices', {
+            params: { searchText: params.searchText, limit: params.limit, offset: params.offset },
+        });
+    }
+    listAggregatedEvents(params) {
+        return this.http.get('/public/api/v1/aggregated_events', {
+            params: {
+                trigger_id: params.triggerId,
+                starts_at: params.startsAt,
+                ends_at: params.endsAt,
+                has_route: params.hasRoute,
+                sort_order: params.sortOrder,
+                limit: params.limit,
+                offset: params.offset,
+            },
+            arrayParams: params.deviceIds?.length ? { 'device_ids[]': params.deviceIds } : undefined,
+        });
+    }
+    getAggregatedEvent(id) {
+        return this.http.get(`/public/api/v1/aggregated_events/${id}`);
+    }
+    getDeviceData(params) {
+        return this.http.get('/public/api/v1/device_data', {
+            params: {
+                partial_query_expression: params.partialQueryExpression,
+                order: params.order,
+                limit: params.limit,
+                offset: params.offset,
+            },
+            arrayParams: params.deviceIds?.length ? { 'device_ids[]': params.deviceIds } : undefined,
+        });
+    }
+    /**
+     * Fetches all telemetry for a window by paging through device_data and returns
+     * chronological [lng, lat] pairs ready for maplibre.
+     * startsAt and endsAt are Unix milliseconds.
+     */
+    async getTripPath(params) {
+        const debug = this.config?.debug;
+        const pageSize = 500;
+        const path = [];
+        const partialQueryExpression = `timestamp >= ${params.startsAt} AND timestamp <= ${params.endsAt}`;
+        let totalRows = 0;
+        let validCoords = 0;
+        for (let offset = 0;; offset += pageSize) {
+            const page = await this.getDeviceData({
+                deviceIds: params.deviceIds,
+                partialQueryExpression,
+                order: 'ASC',
+                limit: pageSize,
+                offset,
+            });
+            totalRows += page.data.length;
+            if (debug && offset === 0 && page.data.length > 0) {
+                console.log('[Yoyo ije][TripPath] first row data sample:', page.data[0].data);
+            }
+            for (const point of page.data) {
+                const coordinate = extractLngLat(point);
+                if (coordinate) {
+                    path.push(coordinate);
+                    validCoords++;
+                }
+            }
+            if (page.data.length < pageSize)
+                break;
+        }
+        if (debug) {
+            console.log(`[Yoyo ije][TripPath] fetched ${totalRows} rows → ${validCoords} valid coords → path length ${path.length}`, { partialQueryExpression });
+        }
+        return path;
+    }
+}
+/** Reads a [lng, lat] pair from a telemetry row, tolerating common field name variants. */
+function extractLngLat(point) {
+    const data = point?.data ?? {};
+    const lat = Number(data.lat ?? data.latitude ?? data.Lat ?? data.Latitude);
+    const lng = Number(data.lng ?? data.lon ?? data.longitude ?? data.Lng ?? data.Lon ?? data.Longitude);
+    if (!Number.isFinite(lat) || !Number.isFinite(lng))
+        return null;
+    if (lat < -90 || lat > 90 || lng < -180 || lng > 180)
+        return null;
+    return [lng, lat];
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@yoyomq/ije-core",
+  "version": "0.1.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "mqtt": "^5.14.0"
+  },
+  "devDependencies": {
+    "typescript": "latest"
+  },
+  "scripts": {
+    "build": "node_modules/.bin/tsc",
+    "dev": "node_modules/.bin/tsc --watch"
+  }
+}