@data360/chart-payload-normalize 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Chart URLs may return either a Charts API envelope `{ spec, title, ... }`
+ * or a raw Vega-Lite spec object (e.g. Data360 MCP static JSON).
+ */
+export type NormalizedChartPayload = {
+    spec: Record<string, unknown>;
+    /** Main headline (matches Vega-Lite `title` string or `title.text`). */
+    title: string;
+    /**
+     * Vega-Lite compound title subtitle (geography · years · unit), when present.
+     * Prefer this for UI over tool `strategy`/`reason` metadata.
+     */
+    subtitle?: string;
+};
+/** Vega-Lite `{ title: { text, subtitle } }` → second line for chart cards. */
+export declare function subtitleFromSpec(spec: Record<string, unknown>): string | undefined;
+/**
+ * @throws Error if the JSON is not a supported chart payload
+ */
+export declare function normalizeChartPayloadFromJson(data: unknown): NormalizedChartPayload;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAyCF,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAUlF;AAMD;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,OAAO,GACZ,sBAAsB,CAyDxB"}

package/dist/index.js

@@ -0,0 +1,106 @@
+/**
+ * Chart URLs may return either a Charts API envelope `{ spec, title, ... }`
+ * or a raw Vega-Lite spec object (e.g. Data360 MCP static JSON).
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function looksLikeVegaLiteSpec(obj) {
+    if (typeof obj.$schema === "string" && /\bvega\b/i.test(obj.$schema)) {
+        return true;
+    }
+    if ("mark" in obj) {
+        return true;
+    }
+    if ("encoding" in obj && isRecord(obj.encoding)) {
+        return true;
+    }
+    // Composite / faceted specs (no top-level mark)
+    if ("layer" in obj) {
+        return true;
+    }
+    if ("concat" in obj || "hconcat" in obj || "vconcat" in obj) {
+        return true;
+    }
+    if ("facet" in obj || "repeat" in obj) {
+        return true;
+    }
+    // Note: do not treat bare `{ spec: ... }` as VL — that pattern is also Charts API envelopes.
+    return false;
+}
+function titleFromSpec(spec) {
+    const raw = spec.title;
+    if (typeof raw === "string") {
+        return raw;
+    }
+    if (isRecord(raw) && typeof raw.text === "string") {
+        return raw.text;
+    }
+    return "Chart";
+}
+/** Vega-Lite `{ title: { text, subtitle } }` → second line for chart cards. */
+export function subtitleFromSpec(spec) {
+    const raw = spec.title;
+    if (!isRecord(raw)) {
+        return undefined;
+    }
+    const sub = raw.subtitle;
+    if (typeof sub === "string" && sub.trim()) {
+        return sub.trim();
+    }
+    return undefined;
+}
+function isLikelyChartsApiEnvelope(data) {
+    return typeof data.id === "string" || typeof data.createdAt === "string";
+}
+/**
+ * @throws Error if the JSON is not a supported chart payload
+ */
+export function normalizeChartPayloadFromJson(data) {
+    if (!isRecord(data)) {
+        throw new Error("Chart JSON must be an object");
+    }
+    const nested = data.spec;
+    // Charts API: explicit metadata — unwrap nested `spec` only.
+    if (isRecord(nested) && isLikelyChartsApiEnvelope(data)) {
+        const title = typeof data.title === "string" && data.title.trim()
+            ? data.title
+            : titleFromSpec(nested);
+        return {
+            spec: nested,
+            title,
+            subtitle: subtitleFromSpec(nested),
+        };
+    }
+    // Raw Vega-Lite document at root (MCP static JSON, facet, layer, concat, …).
+    if (looksLikeVegaLiteSpec(data)) {
+        return {
+            spec: data,
+            title: titleFromSpec(data),
+            subtitle: subtitleFromSpec(data),
+        };
+    }
+    // Charts-style `{ title, spec }` without id/createdAt (unwrap nested VL only).
+    if (isRecord(nested) &&
+        typeof data.title === "string" &&
+        data.title.trim() &&
+        looksLikeVegaLiteSpec(nested)) {
+        return {
+            spec: nested,
+            title: data.title.trim(),
+            subtitle: subtitleFromSpec(nested),
+        };
+    }
+    // Nested `spec` that is clearly VL (legacy / loose envelopes).
+    if (isRecord(nested) && looksLikeVegaLiteSpec(nested)) {
+        const title = typeof data.title === "string" && data.title.trim()
+            ? data.title.trim()
+            : titleFromSpec(nested);
+        return {
+            spec: nested,
+            title,
+            subtitle: subtitleFromSpec(nested),
+        };
+    }
+    throw new Error("Chart JSON did not contain a Vega-Lite spec");
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@data360/chart-payload-normalize",
+  "version": "0.0.1",
+  "description": "Normalize Charts API envelopes and raw Vega-Lite JSON into spec + title for Data360 charts.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
+  "keywords": [
+    "data360",
+    "vega-lite",
+    "world-bank"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/worldbank/data360-mcp"
+  }
+}