@jitto/analyze-embed 0.0.0-stage → 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,324 @@
+/**
+ * The public contract of `@jitto/analyze-embed` v1: everything a host app passes to the SDK and everything
+ * the SDK passes back. Both wrappers, `mountJittoDashboard()` (plain JavaScript) and
+ * `<JittoDashboard>` (React), are typed from this file and nothing else, so they cannot drift apart.
+ *
+ * This file is reviewed like an API: a change here is a change to the contract.
+ * The wire format `fetchToken` receives from `POST /api/v1/embed-tokens` is the embed API's `EmbedToken`.
+ * `fetchToken` calls it with the signed-in user's own access token; no shared account is involved.
+ *
+ * Version policy: package major N targets embed API `/api/vN/`. The SDK sends no version header.
+ *
+ * Names here are Jitto's only. How a dashboard is rendered inside the frame is internal to Jitto and
+ * never appears in a type, an option, an event or a console message of a production build.
+ */
+/**
+ * What `fetchToken` resolves with, built from the answer of `POST /api/v1/embed-tokens`.
+ * Field names are the SDK's (camelCase); `fetchToken` maps `dashboard_id`, `embed_url`, `expires_in`.
+ */
+export interface EmbedTokenResponse {
+    /**
+     * The dashboard token. Opaque: not a readable JWT, and nothing in it, decoded, names an id, a filter or a
+     * claim. Like anything in a browser, the user can read it, so it holds nothing the user may not see. The SDK
+     * never decodes, logs or stores it; it times refreshes from `expiresIn` only. A missing or empty `token` is
+     * refused (`failed`, reason `token`).
+     */
+    token: string;
+    /** Must equal the `dashboardId` the SDK asked for, or the answer is refused (`failed`, reason `token`). */
+    dashboardId: string;
+    /**
+     * Where the dashboard is shown, unchanged from the API's `embed_url`: the tenant's own Jitto host followed by
+     * `/embed`. The SDK accepts it only when it is exactly `embedOrigin` + `/embed`: no user, password, other path,
+     * query or fragment. Any other value is refused before the token leaves the page (`failed`, reason `token`).
+     */
+    embedUrl: string;
+    /**
+     * Seconds the token lives. Absent means 300. The SDK refreshes at 80 % of it, and at most about 24.8 days after it
+     * arrived (the longest delay a browser timer holds). When present it must be a finite number above 0; `0`, a
+     * negative number, `null`, `NaN`, `Infinity` or a string is refused (`failed`, reason `token`, no retry).
+     */
+    expiresIn?: number;
+}
+/**
+ * Gets a dashboard token for the signed-in user. It calls `POST /api/v1/embed-tokens` with
+ * `Authorization: Bearer <the user's own access token>` and the body `{dashboard_id}` only, never a user,
+ * groups or claims. Called on mount and before every expiry. The SDK gives it a
+ * deadline (`tokenDeadlineMs`) and aborts `signal` when the deadline passes or the dashboard unmounts.
+ * Reject with a `TokenRequestError` to pass the API's HTTP status and problem `code` on. On success,
+ * resolve with the API's answer, field names mapped and values unchanged: the SDK checks `token`, `dashboardId` and `embedUrl` itself
+ * and refuses a wrong answer with reason `token`. Do not reject a malformed 200 yourself with its status:
+ * a status the SDK does not list maps to `network`.
+ */
+export type FetchToken = (dashboardId: string, signal: AbortSignal) => Promise<EmbedTokenResponse>;
+/** Optional detail a `FetchToken` may attach to its rejection, so `failed` can say why. */
+export interface TokenRequestError extends Error {
+    /** The HTTP status the embed API answered with, if any. */
+    status?: number;
+    /** The embed API's problem `code`, if any. */
+    code?: ProblemCode | string;
+    /** The embed API's `correlation_id`, if any. */
+    correlationId?: string;
+    /** The `Retry-After` the embed API sent with a 429, in seconds. The SDK waits at least this long before retrying. */
+    retryAfterSeconds?: number;
+}
+/**
+ * Theme tokens: colours, font and light or dark. Jitto keeps the layout; there is no CSS hook.
+ * Colours are CSS colour strings (`#1a73e8`, `rgb(...)`); anything else is ignored with a console warning.
+ */
+export interface ThemeTokens {
+    mode?: 'light' | 'dark';
+    /** Buttons, selected states, links. */
+    colorPrimary?: string;
+    /** The dashboard's page background. */
+    colorBackground?: string;
+    /** Chart and filter card background. */
+    colorSurface?: string;
+    /** Body text. */
+    colorText?: string;
+    /** Borders and dividers. */
+    colorBorder?: string;
+    /** A CSS `font-family` list. The font must already be loadable by the dashboard host. */
+    fontFamily?: string;
+}
+/** A date range, ISO 8601 dates (`2026-06-30`) or Jitto's relative forms (`Last week`). */
+export interface DateRange {
+    from: string;
+    to: string;
+}
+/** One filter's value. A list selects several values; `null` clears the filter. */
+export type FilterValue = string | number | boolean | ReadonlyArray<string | number> | DateRange | null;
+/**
+ * Filters by name, as the dashboard's filter bar names them (for example `Currency`, `Ccy`, `Report date`).
+ * A name matches only when it equals a filter-bar name of the dashboard definition exactly, case included.
+ * Filters narrow what the user sees. They are not a security boundary: the tenant's row rules are.
+ */
+export type Filters = Readonly<Record<string, FilterValue>>;
+/**
+ * Why the dashboard refused host filters:
+ * - `unknown_filter`: a name is not a filter-bar name of the dashboard.
+ * - `invalid_filter_value`: a value has the wrong kind for its filter (a `DateRange` for a value filter,
+ *   a plain value or list for a date filter, a list for a single-choice filter, anything but a list of exactly
+ *   two numbers or `null` for a numeric-range filter).
+ * A value that is the right kind but matches no row is not an error: the charts show zero rows.
+ */
+export declare const FILTER_ERROR_CODES: readonly ["unknown_filter", "invalid_filter_value"];
+export type FilterErrorCode = (typeof FILTER_ERROR_CODES)[number];
+/**
+ * What `setFilters` rejects with, and what `filterRejected` carries, when the dashboard refuses host
+ * filters. Nothing was applied: the filters in effect before the call stay in effect.
+ */
+export interface FilterError extends Error {
+    readonly name: 'FilterError';
+    readonly code: FilterErrorCode;
+    readonly dashboardId: string;
+    /**
+     * The names the host passed that caused the refusal, in the order the host passed them. When a call has
+     * both an unknown name and a wrong value, `code` is `unknown_filter` and this still lists every refused
+     * name of either reason; `knownFilterNames` tells them apart.
+     */
+    readonly filterNames: readonly string[];
+    /** Every filter-bar name the dashboard has, so the host can log or correct the call. */
+    readonly knownFilterNames: readonly string[];
+}
+/**
+ * Why a dashboard did not load, or stopped working. Every failure maps to one of these four, whether it
+ * came from the token request, the network, or the dashboard frame itself; the SDK never passes on an
+ * error message from inside the frame.
+ */
+export type FailureReason = 'token' | 'permission' | 'network' | 'not_found';
+/** The embed API's stable problem codes (openapi/embed.yaml `ProblemCode`). */
+export type ProblemCode = 'invalid_request' | 'unauthenticated' | 'not_permitted' | 'not_embeddable' | 'origin_not_allowed' | 'unknown_dashboard' | 'row_rules_incomplete' | 'rate_limited' | 'internal_error' | 'upstream_unavailable' | 'embedding_not_configured' | 'no_group';
+/**
+ * How a problem code becomes a failure reason. Exhaustive: adding a code to `ProblemCode` without a
+ * reason here fails the typecheck. A code the SDK does not know maps by HTTP status
+ * (`FAILURE_REASON_BY_STATUS`). Both maps must equal openapi/embed.yaml's `x-failure-reason` and
+ * `x-failure-reason-by-status`; `scripts/check-contract-sync.mjs` compares them.
+ */
+export declare const FAILURE_REASON_BY_CODE: {
+    readonly invalid_request: "network";
+    readonly unauthenticated: "token";
+    readonly not_permitted: "permission";
+    readonly not_embeddable: "permission";
+    readonly origin_not_allowed: "permission";
+    readonly unknown_dashboard: "not_found";
+    readonly row_rules_incomplete: "permission";
+    readonly rate_limited: "token";
+    readonly internal_error: "network";
+    readonly upstream_unavailable: "network";
+    readonly embedding_not_configured: "permission";
+    readonly no_group: "permission";
+};
+/**
+ * The fallback for a code the SDK does not know, by HTTP status. Any status not listed, and a rejection
+ * with no status (other than a deadline, which is `token`), maps to `default`.
+ */
+export declare const FAILURE_REASON_BY_STATUS: {
+    readonly 401: "token";
+    readonly 403: "permission";
+    readonly 404: "not_found";
+    readonly 429: "token";
+    readonly default: "network";
+};
+/**
+ * Token request outcomes the SDK retries: no answer within `tokenDeadlineMs`, a network failure, and HTTP
+ * 429, 500 and 502. Every other failure (400, 401, 403, 404, 422, 503, an answer without a token, a token
+ * for another dashboard, an `embedUrl` that is not `embedOrigin` + `/embed`) ends the mount at once with
+ * `failed`. A refresh never outlasts the current token: see `retryDelaysMs`.
+ */
+export declare const RETRYABLE_STATUSES: readonly [429, 500, 502];
+/** Each event's payload. */
+export interface EmbedEventMap {
+    /** The dashboard rendered for the first time after a mount. */
+    loaded: {
+        dashboardId: string;
+        durationMs: number;
+    };
+    /**
+     * The dashboard could not load, a token refresh failed for good, or a `setFilters` reload did not render
+     * within `loadDeadlineMs` (reason `network`). Fires at most once per mount, and
+     * after it the mount is finished: no more token requests or events. The SDK removes the frame and shows a
+     * short Jitto message in its place. The SDK never remounts on its own; the host may mount again.
+     */
+    failed: {
+        dashboardId: string;
+        reason: FailureReason;
+        message: string;
+        status?: number;
+        /**
+         * The embed API's problem code, or a `FilterErrorCode` when the mount's own `filters` were refused.
+         * `string & {}` keeps the named codes visible to editors and type checks; a bare `string` would absorb them.
+         */
+        code?: ProblemCode | FilterErrorCode | (string & {});
+        correlationId?: string;
+        /** With a `FilterErrorCode`: the names of the mount's `filters` that were refused. */
+        filterNames?: readonly string[];
+    };
+    /** The filters in effect changed, by the user in the filter bar or by `setFilters`. */
+    filterChanged: {
+        dashboardId: string;
+        filters: Filters;
+        source: 'user' | 'host';
+    };
+    /**
+     * Host filters set after mount (`setFilters`, or a changed `filters` prop in React) were refused. The
+     * previous filters stay in effect and the mount goes on. Fires once per refused call.
+     */
+    filterRejected: {
+        dashboardId: string;
+        error: FilterError;
+    };
+    /** The dashboard's content size changed; the host may resize its container. */
+    sizeChanged: {
+        dashboardId: string;
+        width: number;
+        height: number;
+    };
+}
+export type EmbedEventName = keyof EmbedEventMap;
+export type EmbedEventHandler<E extends EmbedEventName> = (payload: EmbedEventMap[E]) => void;
+export interface EmbedOptions {
+    /** The Jitto dashboard id, as the tenant administrator gave it. */
+    dashboardId: string;
+    /**
+     * The tenant's own Jitto host, as an origin, exactly as Jitto or the install's administrator gave it:
+     * `https://`, a host, an optional port, nothing else (`https://example-tenant.jittocloud.com`). The SDK frames
+     * only `embedOrigin` + `/embed` (the API's `embed_url`), sends messages only to this origin, and accepts
+     * messages only from it and from its own frame. Nothing in the SDK derives a host from a tenant name. A value of
+     * another shape ends the mount at once with `failed`, reason `token`, before any token is requested. Read once,
+     * when the dashboard mounts: changing it on the options object later changes nothing. To show another host,
+     * unmount and mount again (`<JittoDashboard>` remounts when this prop changes).
+     */
+    embedOrigin: string;
+    /** How to get a dashboard token for the signed-in user (see `FetchToken`). */
+    fetchToken: FetchToken;
+    /**
+     * Not available yet in this version: ignored, with a console warning. What follows is the specified behaviour.
+     *
+     * Filters applied before the first render, by filter-bar name. If any is refused (`FilterErrorCode`),
+     * no chart renders: `failed` fires with reason `not_found`, that `code` and the refused `filterNames`.
+     */
+    filters?: Filters;
+    /** Theme tokens applied before the first render. */
+    theme?: ThemeTokens;
+    /** Deadline for one `fetchToken` call. Default 20 000. */
+    tokenDeadlineMs?: number;
+    /**
+     * How long the frame may stay silent after it is created. When it has not answered by then (for example
+     * because the page's website is not on the tenant's allowed origins, so the browser blocked the frame),
+     * `failed` fires with reason `network`. Default 30 000. Also the deadline of each `setFilters` call.
+     */
+    loadDeadlineMs?: number;
+    /**
+     * Waits before each retry of a retryable token failure (`RETRYABLE_STATUSES`, deadline, network), on
+     * mount and on refresh alike. Default [2000, 5000, 15000]. A 429's `retryAfterSeconds` lengthens a
+     * wait, never shortens it. When the last retry fails, `failed` fires with the reason of the last
+     * failure (`FAILURE_REASON_BY_CODE`, else `FAILURE_REASON_BY_STATUS`; a deadline is `token`, a network
+     * failure `network`). A refresh ends by the current token's expiry: a call's deadline is cut to the time
+     * left, and a retry whose wait would end at or after expiry is not made; the last failure then gives the
+     * reason. An expired-token error from the frame during a refresh waits for the refresh's outcome. The
+     * first token on mount has no token to outlast, so its retries run in full.
+     */
+    retryDelaysMs?: readonly number[];
+}
+/** Event callbacks, the same names in both wrappers. */
+export interface EmbedCallbacks {
+    onLoaded?: EmbedEventHandler<'loaded'>;
+    onFailed?: EmbedEventHandler<'failed'>;
+    /** Not available yet in this version: never called. */
+    onFilterChanged?: EmbedEventHandler<'filterChanged'>;
+    /** Not available yet in this version: never called. */
+    onFilterRejected?: EmbedEventHandler<'filterRejected'>;
+    onSizeChanged?: EmbedEventHandler<'sizeChanged'>;
+}
+/** Why a `setFilters` promise rejected. */
+export type SetFiltersOutcome = 'deadline' | 'ended' | 'replaced';
+/** The rejection of `setFilters`. Not available yet in this version: `setFilters` always rejects with a plain `Error`. */
+export interface SetFiltersError extends Error {
+    name: 'SetFiltersError';
+    outcome: SetFiltersOutcome;
+}
+/** What `mountJittoDashboard` returns. */
+export interface JittoDashboardHandle {
+    readonly dashboardId: string;
+    /**
+     * Not available yet in this version: always rejects with a plain `Error`. What follows is the specified behaviour.
+     *
+     * Replace the host-set filters. Resolves once the dashboard applied them, then fires `filterChanged` with
+     * source `host`. Today this reloads the dashboard inside the frame with the current token (no `fetchToken`
+     * call, no second `loaded`; the user's own filter-bar changes and scroll position are lost). When the
+     * dashboard service can change filters in place, it does, with no change to this type.
+     *
+     * Always settles. Rejects with a `SetFiltersError`: `deadline` when the filters are not applied within
+     * `loadDeadlineMs` of the call (then `failed` fires with reason `network` and the mount ends; a token refresh
+     * does not extend the deadline), `ended` when the mount ends first or had already ended, `replaced` when a
+     * later `setFilters` call is made before this one is applied. Called before `loaded`, it sets the filters of
+     * the first render and resolves when `loaded` fires.
+     *
+     * All or nothing: if any name or value is refused, it rejects with a `FilterError` instead, fires
+     * `filterRejected`, applies nothing (the dashboard is not reloaded) and fires no `filterChanged`.
+     */
+    setFilters(filters: Filters): Promise<void>;
+    /** Replace the theme tokens in place: the frame is not reloaded. */
+    setTheme(theme: ThemeTokens): void;
+    /** Subscribe; returns an unsubscribe function. After it is called, the handler is not called again. */
+    on<E extends EmbedEventName>(event: E, handler: EmbedEventHandler<E>): () => void;
+    /** Remove the dashboard, cancel pending token requests and timers. Idempotent. */
+    unmount(): void;
+}
+export type MountJittoDashboard = (element: HTMLElement, options: EmbedOptions & EmbedCallbacks) => JittoDashboardHandle;
+/**
+ * Props of `<JittoDashboard>`. The same options and callbacks as `mountJittoDashboard`, plus the
+ * container's class and style. A ref gives the same `JittoDashboardHandle`.
+ *
+ * Prop changes:
+ * - `dashboardId` or `embedOrigin` changed (by value): remount.
+ * - `filters` or `theme`: compared with the previous value by value (deep equality), never by reference.
+ *   A different value is applied in place, as `setFilters` / `setTheme` would; an equal value does
+ *   nothing, so inline objects in the host's render are safe and fire no `filterChanged`.
+ * - Callbacks, `fetchToken`, `tokenDeadlineMs`, `loadDeadlineMs`, `retryDelaysMs`: read when used. A new function or value
+ *   takes effect from its next use, with no remount and no event.
+ */
+export interface JittoDashboardProps extends EmbedOptions, EmbedCallbacks {
+    className?: string;
+    style?: Readonly<Record<string, string | number>>;
+}

package/dist/types.js

@@ -0,0 +1,61 @@
+/**
+ * The public contract of `@jitto/analyze-embed` v1: everything a host app passes to the SDK and everything
+ * the SDK passes back. Both wrappers, `mountJittoDashboard()` (plain JavaScript) and
+ * `<JittoDashboard>` (React), are typed from this file and nothing else, so they cannot drift apart.
+ *
+ * This file is reviewed like an API: a change here is a change to the contract.
+ * The wire format `fetchToken` receives from `POST /api/v1/embed-tokens` is the embed API's `EmbedToken`.
+ * `fetchToken` calls it with the signed-in user's own access token; no shared account is involved.
+ *
+ * Version policy: package major N targets embed API `/api/vN/`. The SDK sends no version header.
+ *
+ * Names here are Jitto's only. How a dashboard is rendered inside the frame is internal to Jitto and
+ * never appears in a type, an option, an event or a console message of a production build.
+ */
+/**
+ * Why the dashboard refused host filters:
+ * - `unknown_filter`: a name is not a filter-bar name of the dashboard.
+ * - `invalid_filter_value`: a value has the wrong kind for its filter (a `DateRange` for a value filter,
+ *   a plain value or list for a date filter, a list for a single-choice filter, anything but a list of exactly
+ *   two numbers or `null` for a numeric-range filter).
+ * A value that is the right kind but matches no row is not an error: the charts show zero rows.
+ */
+export const FILTER_ERROR_CODES = ['unknown_filter', 'invalid_filter_value'];
+/**
+ * How a problem code becomes a failure reason. Exhaustive: adding a code to `ProblemCode` without a
+ * reason here fails the typecheck. A code the SDK does not know maps by HTTP status
+ * (`FAILURE_REASON_BY_STATUS`). Both maps must equal openapi/embed.yaml's `x-failure-reason` and
+ * `x-failure-reason-by-status`; `scripts/check-contract-sync.mjs` compares them.
+ */
+export const FAILURE_REASON_BY_CODE = {
+    invalid_request: 'network',
+    unauthenticated: 'token',
+    not_permitted: 'permission',
+    not_embeddable: 'permission',
+    origin_not_allowed: 'permission',
+    unknown_dashboard: 'not_found',
+    row_rules_incomplete: 'permission',
+    rate_limited: 'token',
+    internal_error: 'network',
+    upstream_unavailable: 'network',
+    embedding_not_configured: 'permission',
+    no_group: 'permission',
+};
+/**
+ * The fallback for a code the SDK does not know, by HTTP status. Any status not listed, and a rejection
+ * with no status (other than a deadline, which is `token`), maps to `default`.
+ */
+export const FAILURE_REASON_BY_STATUS = {
+    401: 'token',
+    403: 'permission',
+    404: 'not_found',
+    429: 'token',
+    default: 'network',
+};
+/**
+ * Token request outcomes the SDK retries: no answer within `tokenDeadlineMs`, a network failure, and HTTP
+ * 429, 500 and 502. Every other failure (400, 401, 403, 404, 422, 503, an answer without a token, a token
+ * for another dashboard, an `embedUrl` that is not `embedOrigin` + `/embed`) ends the mount at once with
+ * `failed`. A refresh never outlasts the current token: see `retryDelaysMs`.
+ */
+export const RETRYABLE_STATUSES = [429, 500, 502];

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@jitto/analyze-embed",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Embed Jitto dashboards in your web app, in React or plain JavaScript.",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "@types/react": ">=18.2.6"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "@types/react": { "optional": true }
+  },
+  "typesVersions": {
+    "*": {
+      "react": [
+        "dist/react.d.ts"
+      ]
+    }
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}