@runflow-ai/sdk 1.1.10 → 1.1.11

package/dist/_runflow-shared/constants/index.d.ts

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

package/dist/_runflow-shared/constants/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/_runflow-shared/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './utils';
+export * from './constants';

package/dist/_runflow-shared/index.js

@@ -0,0 +1,21 @@
+"use strict";
+// Shared types, utils, and constants for Runflow platform
+// Export everything from subdirectories
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./utils"), exports);
+__exportStar(require("./constants"), exports);

package/dist/_runflow-shared/types/dashboard-cards.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Dashboard Cards — single source of truth for card types, configs, tabs and
+ * grid layout. Used by:
+ *   - Portal UI (apps/portal)
+ *   - API DTOs (apps/api-portal)
+ *   - CLI metrics.json schema (packages/cli)
+ *   - SDK `runflow.metrics.defineCard()` (packages/sdk)
+ *   - MCP tools (apps/api-portal/src/modules/mcp/tools)
+ *
+ * Any change here must be coordinated across all five surfaces.
+ */
+export declare const ALL_CARD_TYPES: readonly ["number", "rate", "line", "bar", "pie", "table", "funnel", "gauge"];
+export type CardType = (typeof ALL_CARD_TYPES)[number];
+/** Legacy DTO allowlist — kept for one minor version with deprecation header. */
+export declare const LEGACY_V1_CARD_TYPES: readonly ["number", "rate", "line", "bar", "pie"];
+export type Aggregation = "count" | "rate" | "sum" | "avg" | "distinct_count" | "group_by";
+export type DateGrouping = "hour" | "day" | "week" | "month";
+export type CardFormat = "number" | "percentage" | "currency" | "duration";
+export type FilterOperator = "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "contains" | "in";
+export interface BaseCardConfig {
+    /** Event from observability stream. Required for KPI/chart cards. */
+    eventName?: string;
+    aggregation?: Aggregation;
+    propertyKey?: string;
+    propertyValue?: string;
+    /** For line/bar charts. */
+    dateGrouping?: DateGrouping;
+    format?: CardFormat;
+    color?: string;
+    /** Free-form icon slug (UI-defined). */
+    icon?: string;
+}
+export type TableColumnFormat = "number" | "percentage" | "currency" | "duration" | "text";
+export interface TableColumnConfig {
+    key: string;
+    label?: string;
+    format?: TableColumnFormat;
+    width?: number;
+}
+export interface TableMetric {
+    /** Aggregation accepts the full union; conditional formatting may narrow it. */
+    aggregation: Aggregation;
+    propertyKey?: string;
+    alias?: string;
+}
+export interface TableFilter {
+    /** Key on the property being filtered (e.g. "status", "amount"). */
+    key: string;
+    operator: FilterOperator;
+    /** Allow scalar or array for `in`/multi-value comparisons. */
+    value: unknown;
+}
+/** Per-rule conditional formatting (colors/badges on table cells). */
+export interface TableConditionRule {
+    operator: Exclude<FilterOperator, "in" | "contains">;
+    value: string;
+    color: string;
+    label?: string;
+}
+export interface TableCondition {
+    columnKey: string;
+    type: "color" | "badge";
+    rules: TableConditionRule[];
+}
+export interface TablePagination {
+    limit: number;
+    offset: number;
+}
+export interface TableCardConfig extends BaseCardConfig {
+    mode: "raw" | "aggregate";
+    /**
+     * Column descriptors. Old portal versions used `string[]`; both shapes are
+     * accepted by the API (the normalizer keeps them as-is).
+     */
+    columns?: Array<string | TableColumnConfig>;
+    groupByKey?: string;
+    metrics?: TableMetric[];
+    /** Server-side saved filters that ship with the card. */
+    filters?: TableFilter[];
+    /** UI-side conditional formatting (colors/badges per column rule). */
+    conditions?: TableCondition[];
+    sortBy?: string;
+    sortOrder?: "asc" | "desc";
+    pagination?: TablePagination;
+    /** Convenience knob from the UI builder. */
+    rowsPerPage?: number;
+}
+export interface FunnelStep {
+    eventName: string;
+    label?: string;
+}
+export interface FunnelStepValue {
+    value: string;
+    label?: string;
+}
+export interface FunnelCardConfig extends BaseCardConfig {
+    funnelMode: "multi_event" | "single_event";
+    layout?: "vertical" | "horizontal";
+    /** Required when funnelMode === "multi_event". */
+    steps?: FunnelStep[];
+    /** Required when funnelMode === "single_event" (alongside eventName + propertyKey). */
+    stepValues?: FunnelStepValue[];
+}
+export interface GaugeThresholds {
+    v1: number;
+    v2: number;
+}
+export interface GaugeZoneColors {
+    low: string;
+    mid: string;
+    high: string;
+}
+export interface GaugeCardConfig extends BaseCardConfig {
+    min: number;
+    max: number;
+    target?: number;
+    thresholds: GaugeThresholds;
+    zoneColors?: GaugeZoneColors;
+    unit?: string;
+}
+/**
+ * Discriminated union over `cardType` is enforced at the {@link DashboardCard}
+ * level. This wider type is convenient for normalization helpers and stores.
+ */
+export type DashboardCardConfig = BaseCardConfig | TableCardConfig | FunnelCardConfig | GaugeCardConfig;
+export interface GridLayoutItem {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Constraints applied by the UI's drag-and-drop grid. */
+export declare const GRID_CONSTRAINTS: Record<CardType, {
+    minW: number;
+    minH: number;
+    maxW: number;
+    maxH: number;
+}>;
+/**
+ * Returns true when the provided grid item satisfies the constraints for the
+ * card type. UI uses this same helper at drop-time; API DTOs use it on
+ * validation.
+ */
+export declare function isValidGridLayout(cardType: CardType, layout: GridLayoutItem): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface DashboardCard {
+    id: string;
+    tenantId: string;
+    agentId: string;
+    tabId?: string | null;
+    title: string;
+    cardType: CardType;
+    config: DashboardCardConfig;
+    gridLayout?: GridLayoutItem;
+    sortOrder?: number;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface DashboardTab {
+    id: string;
+    tenantId: string;
+    agentId: string;
+    name: string;
+    sortOrder: number;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface ReorderCardEntry {
+    id: string;
+    sortOrder: number;
+    gridLayout?: GridLayoutItem;
+    tabId?: string | null;
+}
+export interface ReorderCardsInput {
+    cards: ReorderCardEntry[];
+}
+export interface ReorderTabEntry {
+    id: string;
+    sortOrder: number;
+}
+export interface ReorderTabsInput {
+    tabs: ReorderTabEntry[];
+}
+export interface CreateDashboardCardInput {
+    agentId: string;
+    title: string;
+    cardType: CardType;
+    config: DashboardCardConfig;
+    tabId?: string | null;
+    gridLayout?: GridLayoutItem;
+    sortOrder?: number;
+    /** Caller-supplied idempotency key. When absent, server derives one. */
+    idempotencyKey?: string;
+}
+export interface UpdateDashboardCardInput {
+    title?: string;
+    config?: DashboardCardConfig;
+    tabId?: string | null;
+    gridLayout?: GridLayoutItem;
+    sortOrder?: number;
+}
+export interface CreateDashboardTabInput {
+    agentId: string;
+    name: string;
+    sortOrder?: number;
+}
+export interface UpdateDashboardTabInput {
+    name?: string;
+    sortOrder?: number;
+}
+export interface DefineCardInput<T extends CardType = CardType> {
+    title: string;
+    cardType: T;
+    config: T extends "table" ? TableCardConfig : T extends "funnel" ? FunnelCardConfig : T extends "gauge" ? GaugeCardConfig : BaseCardConfig;
+    tab?: string;
+    gridLayout?: GridLayoutItem;
+    sortOrder?: number;
+}
+export interface DefineTabInput {
+    name: string;
+    sortOrder?: number;
+}

package/dist/_runflow-shared/types/dashboard-cards.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Dashboard Cards — single source of truth for card types, configs, tabs and
+ * grid layout. Used by:
+ *   - Portal UI (apps/portal)
+ *   - API DTOs (apps/api-portal)
+ *   - CLI metrics.json schema (packages/cli)
+ *   - SDK `runflow.metrics.defineCard()` (packages/sdk)
+ *   - MCP tools (apps/api-portal/src/modules/mcp/tools)
+ *
+ * Any change here must be coordinated across all five surfaces.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GRID_CONSTRAINTS = exports.LEGACY_V1_CARD_TYPES = exports.ALL_CARD_TYPES = void 0;
+exports.isValidGridLayout = isValidGridLayout;
+// -----------------------------------------------------------------------------
+// Card type taxonomy
+// -----------------------------------------------------------------------------
+exports.ALL_CARD_TYPES = [
+    "number",
+    "rate",
+    "line",
+    "bar",
+    "pie",
+    "table",
+    "funnel",
+    "gauge",
+];
+/** Legacy DTO allowlist — kept for one minor version with deprecation header. */
+exports.LEGACY_V1_CARD_TYPES = ["number", "rate", "line", "bar", "pie"];
+/** Constraints applied by the UI's drag-and-drop grid. */
+exports.GRID_CONSTRAINTS = {
+    number: { minW: 2, minH: 2, maxW: 6, maxH: 4 },
+    rate: { minW: 2, minH: 2, maxW: 6, maxH: 4 },
+    gauge: { minW: 2, minH: 3, maxW: 6, maxH: 6 },
+    line: { minW: 4, minH: 3, maxW: 12, maxH: 8 },
+    bar: { minW: 4, minH: 3, maxW: 12, maxH: 8 },
+    pie: { minW: 3, minH: 3, maxW: 8, maxH: 8 },
+    table: { minW: 4, minH: 3, maxW: 12, maxH: 12 },
+    funnel: { minW: 4, minH: 4, maxW: 12, maxH: 12 },
+};
+/**
+ * Returns true when the provided grid item satisfies the constraints for the
+ * card type. UI uses this same helper at drop-time; API DTOs use it on
+ * validation.
+ */
+function isValidGridLayout(cardType, layout) {
+    const c = exports.GRID_CONSTRAINTS[cardType];
+    if (!c)
+        return { ok: false, reason: `unknown cardType: ${cardType}` };
+    if (layout.x < 0 || layout.y < 0)
+        return { ok: false, reason: "x/y must be >= 0" };
+    if (layout.w < c.minW)
+        return { ok: false, reason: `w must be >= ${c.minW} for ${cardType}` };
+    if (layout.h < c.minH)
+        return { ok: false, reason: `h must be >= ${c.minH} for ${cardType}` };
+    if (layout.w > c.maxW)
+        return { ok: false, reason: `w must be <= ${c.maxW} for ${cardType}` };
+    if (layout.h > c.maxH)
+        return { ok: false, reason: `h must be <= ${c.maxH} for ${cardType}` };
+    return { ok: true };
+}

package/dist/_runflow-shared/types/dashboard-cards.normalize.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Tolerant normalizer for `DashboardCard.config`.
+ *
+ * Maps known legacy aliases used by older portal/CLI/SDK versions into the
+ * canonical shape defined in `dashboard-cards.ts`. The helper is intentionally
+ * permissive: unknown keys are preserved, missing required keys are NOT
+ * filled in (validation is the caller's responsibility — see
+ * `dashboard-cards.zod.ts`).
+ *
+ * Used by:
+ *   - apps/api-portal/src/modules/observability/events.service.ts
+ *     (upsertDashboardCard, queryEvents, funnelQuery)
+ *   - apps/api-portal/scripts/normalize-dashboard-cards.ts (one-off backfill)
+ *   - packages/cli (pre-sync sanitation)
+ *   - packages/sdk (defineCard runtime check, soft mode)
+ *
+ * Every transformation increments a counter so callers can emit telemetry
+ * (`legacy_card_alias_used`) and eventually flip `STRICT_DASHBOARD_VALIDATION`.
+ */
+import type { CardType, DashboardCardConfig } from "./dashboard-cards";
+export type LegacyAlias = "table.tableMode->mode" | "funnel.funnelSteps->steps" | "funnel.stepEvents->steps" | "funnel.missingFunnelMode->multi_event" | "gauge.thresholdsArray->object" | "gauge.zoneColorsArray->object" | "gauge.colorsArray->zoneColors" | "gauge.range->minMax" | "card.gridPosition->gridLayout" | "card.layout->gridLayout";
+export interface NormalizeResult {
+    config: DashboardCardConfig;
+    aliasesApplied: LegacyAlias[];
+}
+/**
+ * Normalize a card config to the canonical shape. Pure function, never throws.
+ *
+ * @param cardType  Discriminator that decides which shape to coerce into.
+ * @param raw       Anything that came off the wire / out of the DB.
+ */
+export declare function normalizeCardConfig(cardType: CardType, raw: unknown): NormalizeResult;
+export declare function normalizeGridLayout(raw: unknown): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+} | undefined;

package/dist/_runflow-shared/types/dashboard-cards.normalize.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * Tolerant normalizer for `DashboardCard.config`.
+ *
+ * Maps known legacy aliases used by older portal/CLI/SDK versions into the
+ * canonical shape defined in `dashboard-cards.ts`. The helper is intentionally
+ * permissive: unknown keys are preserved, missing required keys are NOT
+ * filled in (validation is the caller's responsibility — see
+ * `dashboard-cards.zod.ts`).
+ *
+ * Used by:
+ *   - apps/api-portal/src/modules/observability/events.service.ts
+ *     (upsertDashboardCard, queryEvents, funnelQuery)
+ *   - apps/api-portal/scripts/normalize-dashboard-cards.ts (one-off backfill)
+ *   - packages/cli (pre-sync sanitation)
+ *   - packages/sdk (defineCard runtime check, soft mode)
+ *
+ * Every transformation increments a counter so callers can emit telemetry
+ * (`legacy_card_alias_used`) and eventually flip `STRICT_DASHBOARD_VALIDATION`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeCardConfig = normalizeCardConfig;
+exports.normalizeGridLayout = normalizeGridLayout;
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const num = (v) => typeof v === "number" && Number.isFinite(v) ? v : undefined;
+const str = (v) => typeof v === "string" && v.length > 0 ? v : undefined;
+/**
+ * Normalize a card config to the canonical shape. Pure function, never throws.
+ *
+ * @param cardType  Discriminator that decides which shape to coerce into.
+ * @param raw       Anything that came off the wire / out of the DB.
+ */
+function normalizeCardConfig(cardType, raw) {
+    const aliasesApplied = [];
+    const src = isObject(raw) ? { ...raw } : {};
+    switch (cardType) {
+        case "table":
+            return normalizeTable(src, aliasesApplied);
+        case "funnel":
+            return normalizeFunnel(src, aliasesApplied);
+        case "gauge":
+            return normalizeGauge(src, aliasesApplied);
+        default:
+            // KPI / chart cards — pass through with a few generic cleanups.
+            return { config: src, aliasesApplied };
+    }
+}
+// -----------------------------------------------------------------------------
+// Per-type normalizers
+// -----------------------------------------------------------------------------
+function normalizeTable(src, applied) {
+    if (src.mode === undefined && typeof src.tableMode === "string") {
+        src.mode = src.tableMode;
+        delete src.tableMode;
+        applied.push("table.tableMode->mode");
+    }
+    // Permissive cast — required fields (mode) may still be missing; validation
+    // is the caller's responsibility via the zod schema.
+    return {
+        config: src,
+        aliasesApplied: applied,
+    };
+}
+function normalizeFunnel(src, applied) {
+    if (src.steps === undefined) {
+        if (Array.isArray(src.funnelSteps)) {
+            src.steps = src.funnelSteps;
+            delete src.funnelSteps;
+            applied.push("funnel.funnelSteps->steps");
+        }
+        else if (Array.isArray(src.stepEvents)) {
+            src.steps = src.stepEvents;
+            delete src.stepEvents;
+            applied.push("funnel.stepEvents->steps");
+        }
+    }
+    if (typeof src.funnelMode !== "string") {
+        src.funnelMode = "multi_event";
+        applied.push("funnel.missingFunnelMode->multi_event");
+    }
+    return {
+        config: src,
+        aliasesApplied: applied,
+    };
+}
+function normalizeGauge(src, applied) {
+    // thresholds: [v1, v2]  →  { v1, v2 }
+    if (Array.isArray(src.thresholds) && src.thresholds.length === 2) {
+        const [v1, v2] = src.thresholds;
+        if (num(v1) !== undefined && num(v2) !== undefined) {
+            src.thresholds = { v1: v1, v2: v2 };
+            applied.push("gauge.thresholdsArray->object");
+        }
+    }
+    // zoneColors: [low, mid, high]  →  { low, mid, high }
+    if (Array.isArray(src.zoneColors) && src.zoneColors.length === 3) {
+        const [low, mid, high] = src.zoneColors;
+        if (str(low) && str(mid) && str(high)) {
+            src.zoneColors = {
+                low: low,
+                mid: mid,
+                high: high,
+            };
+            applied.push("gauge.zoneColorsArray->object");
+        }
+    }
+    // Older builds used `colors: [...]` for zone colors.
+    if (src.zoneColors === undefined && Array.isArray(src.colors)) {
+        const [low, mid, high] = src.colors;
+        if (str(low) && str(mid) && str(high)) {
+            src.zoneColors = {
+                low: low,
+                mid: mid,
+                high: high,
+            };
+            delete src.colors;
+            applied.push("gauge.colorsArray->zoneColors");
+        }
+    }
+    // Some legacy rows stored `range: { from, to }` instead of min/max.
+    if ((src.min === undefined || src.max === undefined) &&
+        isObject(src.range)) {
+        const range = src.range;
+        if (num(range.from) !== undefined && src.min === undefined) {
+            src.min = range.from;
+        }
+        if (num(range.to) !== undefined && src.max === undefined) {
+            src.max = range.to;
+        }
+        delete src.range;
+        applied.push("gauge.range->minMax");
+    }
+    return {
+        config: src,
+        aliasesApplied: applied,
+    };
+}
+// -----------------------------------------------------------------------------
+// gridLayout normalizer — accepts a few legacy shapes for the card-level field
+// (not the config). Returns undefined if input is unrecognizable.
+// -----------------------------------------------------------------------------
+function normalizeGridLayout(raw) {
+    if (!isObject(raw))
+        return undefined;
+    const x = num(raw.x) ?? num(raw.X);
+    const y = num(raw.y) ?? num(raw.Y);
+    const w = num(raw.w) ?? num(raw.width);
+    const h = num(raw.h) ?? num(raw.height);
+    if (x === undefined || y === undefined || w === undefined || h === undefined)
+        return undefined;
+    return { x, y, w, h };
+}