@jitto/analyze-embed 0.0.0-stage → 0.2.0

package/dist/core/mount.js

@@ -0,0 +1,226 @@
+/**
+ * `mountJittoDashboard`: the plain JavaScript embed, on which the React wrapper sits. One package gives a React and a
+ * plain-JavaScript embed on one core.
+ *
+ * Not yet in this version: `setFilters` and the `filters` option. The dashboard's filters cannot yet be set by name
+ * from outside its frame; `setFilters` rejects and `filters` is ignored with a console warning. `setTheme` is
+ * applied in place, best effort.
+ */
+import { isCanonicalHttpsOrigin } from "./embed-target.js";
+import { DashboardFrame } from "./frame.js";
+import { timerDelay } from "./timer.js";
+import { DEFAULT_RETRY_DELAYS_MS, DEFAULT_TOKEN_DEADLINE_MS, requestToken, TokenFailure, } from "./token.js";
+const DEFAULT_LOAD_DEADLINE_MS = 30_000;
+const SIZE_POLL_MS = 500;
+const REFRESH_AT = 0.8;
+const FAILED_TEXT = 'This dashboard could not be loaded.';
+const CALLBACK_BY_EVENT = {
+    loaded: 'onLoaded',
+    failed: 'onFailed',
+    filterChanged: 'onFilterChanged',
+    filterRejected: 'onFilterRejected',
+    sizeChanged: 'onSizeChanged',
+};
+/** Theme tokens to the frame's own names. Colours that are not CSS colours are dropped with a warning. */
+function themeTokens(theme) {
+    const names = [
+        ['colorPrimary', 'colorPrimary'],
+        ['colorBackground', 'colorBgLayout'],
+        ['colorSurface', 'colorBgContainer'],
+        ['colorText', 'colorText'],
+        ['colorBorder', 'colorBorder'],
+    ];
+    const out = {};
+    for (const [ours, theirs] of names) {
+        const value = theme[ours];
+        if (value === undefined)
+            continue;
+        if (typeof value === 'string' && typeof CSS !== 'undefined' && CSS.supports('color', value))
+            out[theirs] = value;
+        else
+            console.warn(`Jitto: theme ${ours} is not a CSS colour and is ignored.`);
+    }
+    if (typeof theme.fontFamily === 'string' && theme.fontFamily)
+        out.fontFamily = theme.fontFamily;
+    return out;
+}
+export const mountJittoDashboard = (element, options) => {
+    const opts = options;
+    const dashboardId = opts.dashboardId;
+    // Read once: the frame posts only to the origin it was built for, so every token, the refreshed ones included, is
+    // checked against that same origin. A host that changes `embedOrigin` on its options object later must mount again.
+    const embedOrigin = opts.embedOrigin;
+    const started = Date.now();
+    const abort = new AbortController();
+    const listeners = new Map();
+    let ended = false;
+    let loaded = false;
+    let frame = null;
+    let current = null;
+    let lastSize = null;
+    const timers = new Set();
+    const box = document.createElement('div');
+    box.style.width = '100%';
+    box.style.height = '100%';
+    element.appendChild(box);
+    function later(fn, ms) {
+        const t = setTimeout(() => {
+            timers.delete(t);
+            fn();
+        }, timerDelay(ms));
+        timers.add(t);
+    }
+    function emit(event, payload) {
+        if (ended && event !== 'failed')
+            return;
+        const callback = opts[CALLBACK_BY_EVENT[event]];
+        try {
+            callback?.(payload);
+        }
+        catch (err) {
+            console.error(err);
+        }
+        for (const handler of [...(listeners.get(event) ?? [])]) {
+            try {
+                handler(payload);
+            }
+            catch (err) {
+                console.error(err);
+            }
+        }
+    }
+    function stop() {
+        ended = true;
+        abort.abort();
+        for (const t of timers)
+            clearTimeout(t);
+        timers.clear();
+        frame?.remove();
+        frame = null;
+    }
+    function fail(failure) {
+        if (ended)
+            return;
+        stop();
+        box.textContent = FAILED_TEXT;
+        box.style.display = 'flex';
+        box.style.alignItems = 'center';
+        box.style.justifyContent = 'center';
+        box.style.color = '#666';
+        box.style.fontFamily = 'sans-serif';
+        const payload = { dashboardId, reason: failure.reason, message: failure.message };
+        if (failure.status !== undefined)
+            payload.status = failure.status;
+        if (failure.code !== undefined)
+            payload.code = failure.code;
+        if (failure.correlationId !== undefined)
+            payload.correlationId = failure.correlationId;
+        emit('failed', payload);
+    }
+    async function watchSize() {
+        if (ended || !frame)
+            return;
+        const size = await frame.size(SIZE_POLL_MS * 4);
+        if (ended)
+            return;
+        if (size && size.height > 0) {
+            if (!loaded) {
+                loaded = true;
+                emit('loaded', { dashboardId, durationMs: Date.now() - started });
+            }
+            if (!lastSize || lastSize.width !== size.width || lastSize.height !== size.height) {
+                lastSize = size;
+                emit('sizeChanged', { dashboardId, width: size.width, height: size.height });
+            }
+        }
+        later(() => void watchSize(), SIZE_POLL_MS);
+    }
+    function scheduleRefresh(token) {
+        later(() => void refresh(), Math.max(1000, token.expiresInSeconds * 1000 * REFRESH_AT));
+    }
+    async function refresh() {
+        if (ended || !current)
+            return;
+        try {
+            const next = await requestToken({
+                fetchToken: opts.fetchToken,
+                dashboardId,
+                embedOrigin,
+                deadlineMs: opts.tokenDeadlineMs ?? DEFAULT_TOKEN_DEADLINE_MS,
+                retryDelaysMs: opts.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS,
+                signal: abort.signal,
+                validUntil: current.expiresAt,
+            });
+            if (!next || ended)
+                return;
+            current = next;
+            await frame?.giveToken(next.token);
+            scheduleRefresh(next);
+        }
+        catch (err) {
+            fail(err instanceof TokenFailure ? err : new TokenFailure('network', 'The dashboard stopped working.'));
+        }
+    }
+    async function start() {
+        if (!isCanonicalHttpsOrigin(embedOrigin)) {
+            fail(new TokenFailure('token', 'The dashboard host is not a valid origin.'));
+            return;
+        }
+        if (opts.filters && Object.keys(opts.filters).length > 0) {
+            console.warn('Jitto: filters cannot be set from the page in this version and are ignored.');
+        }
+        try {
+            const first = await requestToken({
+                fetchToken: opts.fetchToken,
+                dashboardId,
+                embedOrigin,
+                deadlineMs: opts.tokenDeadlineMs ?? DEFAULT_TOKEN_DEADLINE_MS,
+                retryDelaysMs: opts.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS,
+                signal: abort.signal,
+            });
+            if (!first || ended)
+                return;
+            current = first;
+            frame = new DashboardFrame(box, first.embedUrl, dashboardId, embedOrigin);
+            later(() => {
+                if (!loaded)
+                    fail(new TokenFailure('network', 'The dashboard did not answer in time.'));
+            }, opts.loadDeadlineMs ?? DEFAULT_LOAD_DEADLINE_MS);
+            await frame.giveToken(first.token);
+            if (opts.theme)
+                await frame.applyTheme(themeTokens(opts.theme), opts.theme.mode);
+            scheduleRefresh(first);
+            void watchSize();
+        }
+        catch (err) {
+            fail(err instanceof TokenFailure ? err : new TokenFailure('network', 'The dashboard could not be loaded.'));
+        }
+    }
+    void start();
+    const handle = {
+        dashboardId,
+        setFilters(_filters) {
+            return Promise.reject(new Error('Jitto: setFilters is not available in this version.'));
+        },
+        setTheme(theme) {
+            if (ended)
+                return;
+            void frame?.applyTheme(themeTokens(theme), theme.mode);
+        },
+        on(event, handler) {
+            const set = listeners.get(event) ?? new Set();
+            set.add(handler);
+            listeners.set(event, set);
+            return () => {
+                set.delete(handler);
+            };
+        },
+        unmount() {
+            if (!ended)
+                stop();
+            listeners.clear();
+            box.remove();
+        },
+    };
+    return handle;
+};

package/dist/core/timer.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Delays the SDK may hand to `setTimeout`. Browsers and Node keep a timer's delay in a signed 32-bit integer: a longer
+ * delay (about 24.8 days) runs at once, so a long token lifetime, `Retry-After` or deadline would turn into a tight
+ * loop of token requests. Every timer in the core goes through `timerDelay`.
+ */
+/** The longest delay `setTimeout` honours: 2^31 - 1 ms. */
+export declare const MAX_TIMER_MS = 2147483647;
+/** `ms` as a delay `setTimeout` honours: never below 0 or above `MAX_TIMER_MS`; `NaN` is 0. */
+export declare function timerDelay(ms: number): number;

package/dist/core/timer.js

@@ -0,0 +1,13 @@
+/**
+ * Delays the SDK may hand to `setTimeout`. Browsers and Node keep a timer's delay in a signed 32-bit integer: a longer
+ * delay (about 24.8 days) runs at once, so a long token lifetime, `Retry-After` or deadline would turn into a tight
+ * loop of token requests. Every timer in the core goes through `timerDelay`.
+ */
+/** The longest delay `setTimeout` honours: 2^31 - 1 ms. */
+export const MAX_TIMER_MS = 2_147_483_647;
+/** `ms` as a delay `setTimeout` honours: never below 0 or above `MAX_TIMER_MS`; `NaN` is 0. */
+export function timerDelay(ms) {
+    if (Number.isNaN(ms))
+        return 0;
+    return Math.min(Math.max(ms, 0), MAX_TIMER_MS);
+}

package/dist/core/token.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The token procedure: tokens are fetched with a deadline, retried only when a retry can help, and refreshed in
+ * place. One call of the host's `fetchToken` with a deadline, retries for a deadline, a
+ * network failure and 429/500/502 only, a refresh never outlasting the current token, and every answer checked
+ * before its token is used. The SDK never decodes, logs or stores a token.
+ */
+import type { FailureReason, FetchToken, TokenRequestError } from '../types.ts';
+export declare const DEFAULT_EXPIRES_IN_SECONDS = 300;
+export declare const DEFAULT_TOKEN_DEADLINE_MS = 20000;
+export declare const DEFAULT_RETRY_DELAYS_MS: readonly number[];
+/** A token the SDK accepted, with the time it stops being valid. */
+export interface AcceptedToken {
+    token: string;
+    embedUrl: string;
+    expiresInSeconds: number;
+    expiresAt: number;
+}
+/** Why the procedure gave up: the `failed` payload's fields. */
+export declare class TokenFailure extends Error {
+    readonly reason: FailureReason;
+    readonly status: number | undefined;
+    readonly code: string | undefined;
+    readonly correlationId: string | undefined;
+    constructor(reason: FailureReason, message: string, detail?: Partial<TokenRequestError>);
+}
+/**
+ * Get a token, with retries. `validUntil` is the current token's expiry on a refresh (each call's deadline is cut to
+ * the time left, and a retry whose wait would end at or after it is not made), or `undefined` on mount.
+ * Throws `TokenFailure` with the last failure's reason; aborting `signal` ends it quietly with `null`.
+ */
+export declare function requestToken(opts: {
+    fetchToken: FetchToken;
+    dashboardId: string;
+    embedOrigin: string;
+    deadlineMs: number;
+    retryDelaysMs: readonly number[];
+    signal: AbortSignal;
+    validUntil?: number;
+}): Promise<AcceptedToken | null>;

package/dist/core/token.js

@@ -0,0 +1,142 @@
+/**
+ * The token procedure: tokens are fetched with a deadline, retried only when a retry can help, and refreshed in
+ * place. One call of the host's `fetchToken` with a deadline, retries for a deadline, a
+ * network failure and 429/500/502 only, a refresh never outlasting the current token, and every answer checked
+ * before its token is used. The SDK never decodes, logs or stores a token.
+ */
+import { FAILURE_REASON_BY_CODE, FAILURE_REASON_BY_STATUS, RETRYABLE_STATUSES } from "../types.js";
+import { isExpectedEmbedTarget } from "./embed-target.js";
+import { timerDelay } from "./timer.js";
+export const DEFAULT_EXPIRES_IN_SECONDS = 300;
+export const DEFAULT_TOKEN_DEADLINE_MS = 20_000;
+export const DEFAULT_RETRY_DELAYS_MS = [2000, 5000, 15000];
+/** Why the procedure gave up: the `failed` payload's fields. */
+export class TokenFailure extends Error {
+    reason;
+    status;
+    code;
+    correlationId;
+    constructor(reason, message, detail = {}) {
+        super(message);
+        this.name = 'TokenFailure';
+        this.reason = reason;
+        this.status = detail.status;
+        this.code = detail.code;
+        this.correlationId = detail.correlationId;
+    }
+}
+function reasonFor(err) {
+    const code = err.code;
+    if (code && Object.prototype.hasOwnProperty.call(FAILURE_REASON_BY_CODE, code)) {
+        return FAILURE_REASON_BY_CODE[code];
+    }
+    const byStatus = FAILURE_REASON_BY_STATUS;
+    if (err.status !== undefined && byStatus[String(err.status)])
+        return byStatus[String(err.status)];
+    return FAILURE_REASON_BY_STATUS.default;
+}
+/** The answer, checked; or why it is refused (reason `token`, never retried). */
+function accept(answer, dashboardId, embedOrigin, now) {
+    if (typeof answer !== 'object' || answer === null)
+        return new TokenFailure('token', 'The dashboard token answer was not usable.');
+    const a = answer;
+    if (typeof a.token !== 'string' || a.token === '')
+        return new TokenFailure('token', 'The dashboard token was missing.');
+    if (a.dashboardId !== dashboardId)
+        return new TokenFailure('token', 'The dashboard token was for another dashboard.');
+    if (typeof a.embedUrl !== 'string' || !isExpectedEmbedTarget(a.embedUrl, embedOrigin)) {
+        return new TokenFailure('token', 'The dashboard token named an unexpected host.');
+    }
+    let seconds = DEFAULT_EXPIRES_IN_SECONDS;
+    if (a.expiresIn !== undefined) {
+        if (typeof a.expiresIn !== 'number' || !Number.isFinite(a.expiresIn) || a.expiresIn <= 0) {
+            return new TokenFailure('token', 'The dashboard token had no usable lifetime.');
+        }
+        seconds = a.expiresIn;
+    }
+    return { token: a.token, embedUrl: a.embedUrl, expiresInSeconds: seconds, expiresAt: now + seconds * 1000 };
+}
+async function attempt(fetchToken, dashboardId, embedOrigin, deadlineMs, outer) {
+    const controller = new AbortController();
+    let onOuterAbort = () => { };
+    let timer;
+    // The deadline, or the mount ending: either one stops the wait at once, so an unmount leaves no timer behind even
+    // when the host's fetchToken ignores its signal.
+    const stop = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            resolve('deadline');
+        }, timerDelay(deadlineMs));
+        onOuterAbort = () => {
+            controller.abort();
+            resolve('ended');
+        };
+    });
+    outer.addEventListener('abort', onOuterAbort, { once: true });
+    try {
+        const result = await Promise.race([fetchToken(dashboardId, controller.signal), stop]);
+        if (result === 'ended') {
+            return { ok: false, failure: new TokenFailure('network', 'The dashboard was removed.'), retry: false, retryAfterMs: 0 };
+        }
+        if (result === 'deadline') {
+            return { ok: false, failure: new TokenFailure('token', 'The dashboard token did not arrive in time.'), retry: true, retryAfterMs: 0 };
+        }
+        const checked = accept(result, dashboardId, embedOrigin, Date.now());
+        if (checked instanceof TokenFailure)
+            return { ok: false, failure: checked, retry: false, retryAfterMs: 0 };
+        return { ok: true, value: checked };
+    }
+    catch (raw) {
+        const err = (raw ?? {});
+        const status = typeof err.status === 'number' ? err.status : undefined;
+        if (status === undefined) {
+            // No HTTP answer at all: the network failed. Retried.
+            const failure = new TokenFailure('network', 'The dashboard token could not be requested.', err);
+            return { ok: false, failure, retry: true, retryAfterMs: 0 };
+        }
+        const failure = new TokenFailure(reasonFor(err), 'The dashboard token was refused.', err);
+        const retry = RETRYABLE_STATUSES.includes(status);
+        const retryAfterMs = typeof err.retryAfterSeconds === 'number' ? err.retryAfterSeconds * 1000 : 0;
+        return { ok: false, failure, retry, retryAfterMs };
+    }
+    finally {
+        clearTimeout(timer);
+        outer.removeEventListener('abort', onOuterAbort);
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        const t = setTimeout(resolve, timerDelay(ms));
+        signal.addEventListener('abort', () => { clearTimeout(t); resolve(); }, { once: true });
+    });
+}
+/**
+ * Get a token, with retries. `validUntil` is the current token's expiry on a refresh (each call's deadline is cut to
+ * the time left, and a retry whose wait would end at or after it is not made), or `undefined` on mount.
+ * Throws `TokenFailure` with the last failure's reason; aborting `signal` ends it quietly with `null`.
+ */
+export async function requestToken(opts) {
+    let last;
+    for (let i = 0; i <= opts.retryDelaysMs.length; i += 1) {
+        if (opts.signal.aborted)
+            return null;
+        let deadline = opts.deadlineMs;
+        if (opts.validUntil !== undefined)
+            deadline = Math.min(deadline, Math.max(0, opts.validUntil - Date.now()));
+        if (deadline <= 0)
+            break;
+        const outcome = await attempt(opts.fetchToken, opts.dashboardId, opts.embedOrigin, deadline, opts.signal);
+        if (opts.signal.aborted)
+            return null;
+        if (outcome.ok)
+            return outcome.value;
+        last = outcome.failure;
+        if (!outcome.retry || i === opts.retryDelaysMs.length)
+            break;
+        const wait = Math.max(opts.retryDelaysMs[i] ?? 0, outcome.retryAfterMs);
+        if (opts.validUntil !== undefined && Date.now() + wait >= opts.validUntil)
+            break;
+        await sleep(wait, opts.signal);
+    }
+    throw last ?? new TokenFailure('token', 'The dashboard token expired before a new one arrived.');
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+/** `@jitto/analyze-embed`: one way to embed Jitto dashboards. Plain JavaScript; the React wrapper is `@jitto/analyze-embed/react`. */
+export { mountJittoDashboard } from './core/mount.ts';
+export { FAILURE_REASON_BY_CODE, FAILURE_REASON_BY_STATUS, RETRYABLE_STATUSES } from './types.ts';
+export type { DateRange, EmbedCallbacks, EmbedEventHandler, EmbedEventMap, EmbedEventName, EmbedOptions, EmbedTokenResponse, FailureReason, FetchToken, Filters, FilterValue, JittoDashboardHandle, JittoDashboardProps, MountJittoDashboard, ProblemCode, SetFiltersError, SetFiltersOutcome, ThemeTokens, TokenRequestError, } from './types.ts';

package/dist/index.js

@@ -0,0 +1,3 @@
+/** `@jitto/analyze-embed`: one way to embed Jitto dashboards. Plain JavaScript; the React wrapper is `@jitto/analyze-embed/react`. */
+export { mountJittoDashboard } from "./core/mount.js";
+export { FAILURE_REASON_BY_CODE, FAILURE_REASON_BY_STATUS, RETRYABLE_STATUSES } from "./types.js";

package/dist/react.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `<JittoDashboard>`: the React wrapper over `mountJittoDashboard`. It reacts to prop changes by value.
+ * `dashboardId` or `embedOrigin` changing remounts; `theme` changing by value is applied in place; callbacks,
+ * `fetchToken` and the timing options are read when used, so new functions take effect with no remount. A ref
+ * gives the same `JittoDashboardHandle`.
+ */
+import type { JittoDashboardHandle, JittoDashboardProps } from './types.ts';
+export declare const JittoDashboard: import("react").ForwardRefExoticComponent<JittoDashboardProps & import("react").RefAttributes<JittoDashboardHandle>>;

package/dist/react.js

@@ -0,0 +1,69 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * `<JittoDashboard>`: the React wrapper over `mountJittoDashboard`. It reacts to prop changes by value.
+ * `dashboardId` or `embedOrigin` changing remounts; `theme` changing by value is applied in place; callbacks,
+ * `fetchToken` and the timing options are read when used, so new functions take effect with no remount. A ref
+ * gives the same `JittoDashboardHandle`.
+ */
+import { forwardRef, useEffect, useImperativeHandle, useLayoutEffect, useRef } from 'react';
+import { mountJittoDashboard } from "./core/mount.js";
+// A layout effect on the client; on the server React 18 warns about useLayoutEffect, and nothing needs to run there.
+const useIsomorphicLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+function sameValue(a, b) {
+    return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+function JittoDashboardInner(props, ref) {
+    const container = useRef(null);
+    const handle = useRef(null);
+    // The live options: the core keeps this one object for the whole mount and reads callbacks and fetchToken from it
+    // when it uses them. So it is updated in place (a new object per render would never reach the core), and a prop that
+    // is dropped or undefined is deleted, so a dropped callback is no longer called. It is synced in a layout effect,
+    // declared before the mount, and not during render: a render React discards must not change what the core reads.
+    const live = useRef({ ...props });
+    useIsomorphicLayoutEffect(() => {
+        const target = live.current;
+        const next = props;
+        for (const key of Object.keys(target))
+            if (next[key] === undefined)
+                delete target[key];
+        for (const key of Object.keys(next))
+            if (next[key] !== undefined)
+                target[key] = next[key];
+    });
+    const lastTheme = useRef(props.theme);
+    const lastFilters = useRef(props.filters);
+    // A layout effect, declared before useImperativeHandle: that hook runs in the same phase and reads handle.current,
+    // so the mount must have set it first, or the ref stays null (and after a dashboardId change points at the old handle).
+    useIsomorphicLayoutEffect(() => {
+        if (!container.current)
+            return undefined;
+        handle.current = mountJittoDashboard(container.current, live.current);
+        lastTheme.current = props.theme;
+        return () => {
+            handle.current?.unmount();
+            handle.current = null;
+        };
+        // Remount on these two only; everything else is read live or applied in place.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [props.dashboardId, props.embedOrigin]);
+    // `filters` is not available yet: a change after the mount is ignored, and the console says so, as the mount does.
+    useEffect(() => {
+        if (sameValue(lastFilters.current, props.filters))
+            return;
+        lastFilters.current = props.filters;
+        if (props.filters && Object.keys(props.filters).length > 0) {
+            console.warn('Jitto: filters cannot be set from the page in this version and are ignored.');
+        }
+    }, [props.filters]);
+    useEffect(() => {
+        if (!handle.current || sameValue(lastTheme.current, props.theme))
+            return;
+        lastTheme.current = props.theme;
+        if (props.theme)
+            handle.current.setTheme(props.theme);
+    }, [props.theme]);
+    useImperativeHandle(ref, () => handle.current, [props.dashboardId, props.embedOrigin]);
+    return _jsx("div", { ref: container, className: props.className, style: props.style });
+}
+export const JittoDashboard = forwardRef(JittoDashboardInner);
+JittoDashboard.displayName = 'JittoDashboard';