@butinapp/shapes 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yann Allard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,8 @@
+# @butinapp/shapes
+
+Host-layer data shapes for [Butin](https://butin.app), built on the `@butinapp/sdk` data-view contract. Not the plugin-authoring contract (that's `@butinapp/sdk`).
+
+- `@butinapp/shapes` — the cross-service Overview input, the persisted ledger, the presentation manifest, per-day spend derivation
+- `@butinapp/shapes/bundle` — the portable, versioned export-bundle wire format (what a snapshot-fed dashboard consumes)
+
+MIT licensed.

package/dist/bundle.d.ts

@@ -0,0 +1,2 @@
+export * from './export-bundle.js';
+export type { OverviewPlugin } from './overview.js';

package/dist/bundle.js

@@ -0,0 +1,7 @@
+// @butinapp/shapes/bundle — the portable export bundle: Butin's normalized data lifted into ONE
+// self-contained, versioned JSON blob. The system's most boundary-crossing object — produced by core
+// (buildExportBundle), optionally merged by a gateway, consumed by a separately-deployed viewer — so it
+// carries its own EXPORT_BUNDLE_FORMAT_VERSION and a parseExportBundle that gates an untrusted blob on that
+// version. Kept on its own subpath (not on the host-layer root) because it's the stable wire contract a
+// consumer depends on exactly — nothing else.
+export * from './export-bundle.js';

package/dist/daily.d.ts

@@ -0,0 +1,18 @@
+import type { ResetPeriod } from '@butinapp/sdk/data';
+import { z } from 'zod';
+export declare const DailyPointSchema: z.ZodObject<{
+    date: z.ZodString;
+    value: z.ZodNumber;
+    estimated: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type DailyPoint = z.infer<typeof DailyPointSchema>;
+export type DailySource = {
+    date: string;
+    capturedAt: string;
+    section: string;
+    value: number;
+};
+export declare const latestPerDay: <T>(points: T[], dayOf: (p: T) => string, instant: (p: T) => string) => T[];
+export declare const deriveDailySpend: (points: DailySource[], resetPeriod?: ResetPeriod) => DailyPoint[];
+export declare const deriveDailyByRow: (readingsByRow: Record<string, DailySource[]>, resetPeriod?: ResetPeriod) => Record<string, DailyPoint[]>;
+export declare const combineDailySpend: (series: DailyPoint[][]) => DailyPoint[];

package/dist/daily.js

@@ -0,0 +1,73 @@
+// Pure per-day spend derivation from a cumulative metric series. Shared by core (derives from a capability's
+// ledger series) and the UI chart — no Electron, no IO.
+import { groupBy, maxBy, sortBy } from 'lodash-es';
+import { DateTime } from 'luxon';
+import { z } from 'zod';
+// A derived per-day spend value. `estimated` flags days inferred across a gap (no snapshot that day).
+export const DailyPointSchema = z.object({ date: z.string(), value: z.number(), estimated: z.boolean().optional() });
+const ym = (date) => date.slice(0, 7);
+// Collapse many captures (across times of day, and across people) to one reading per day: the one with the
+// latest `instant` — the closest reading to that day's end — sorted chronologically. `dayOf` buckets a point
+// to its calendar day; `instant` is the full ISO timestamp that picks the winner and orders the result (ISO
+// timestamps sort chronologically, and one-per-day means instant order equals day order).
+export const latestPerDay = (points, dayOf, instant) => sortBy(Object.values(groupBy(points, dayOf)).map((perDay) => maxBy(perDay, instant)), instant);
+const endOfDayPerDay = (points) => latestPerDay(points, (p) => p.date, (p) => p.capturedAt);
+// Calendar days strictly after `from` up to and including `to`.
+const daysBetween = (from, to) => {
+    const out = [];
+    const end = DateTime.fromISO(to, { zone: 'utc' });
+    for (let d = DateTime.fromISO(from, { zone: 'utc' }).plus({ days: 1 }); d <= end; d = d.plus({ days: 1 })) {
+        out.push(d.toISODate());
+    }
+    return out;
+};
+// Derive per-day spend from a cumulative series. A monthly-resetting counter (MTD) attributes a month
+// rollover's new value as-is instead of a negative diff. `resetPeriod` states this explicitly; absent, it
+// falls back to sniffing the 'spend' section. Gaps spread evenly, flagged estimated.
+export const deriveDailySpend = (points, resetPeriod) => {
+    const sorted = endOfDayPerDay(points);
+    const resetsMonthly = resetPeriod ? resetPeriod === 'monthly' : sorted[0]?.section === 'spend';
+    const out = [];
+    for (let i = 0; i < sorted.length; i++) {
+        const cur = sorted[i];
+        const prev = sorted[i - 1];
+        if (!prev) {
+            // A lone first-of-month point: MTD on day 1 IS that day's spend. Otherwise we can't diff.
+            if (resetsMonthly && cur.date.endsWith('-01')) {
+                out.push({ date: cur.date, value: cur.value });
+            }
+            continue;
+        }
+        if (resetsMonthly && ym(cur.date) !== ym(prev.date)) {
+            out.push({ date: cur.date, value: cur.value });
+            continue;
+        }
+        const gap = daysBetween(prev.date, cur.date);
+        const delta = cur.value - prev.value;
+        if (gap.length <= 1) {
+            out.push({ date: cur.date, value: delta });
+            continue;
+        }
+        const per = delta / gap.length;
+        for (const date of gap) {
+            out.push({ date, value: per, estimated: true });
+        }
+    }
+    return out;
+};
+// Derive a per-day series for each row of a keyed cumulative column: differences that row's reading series
+// independently. The row id keys both the input and the output.
+export const deriveDailyByRow = (readingsByRow, resetPeriod) => {
+    const out = {};
+    for (const [rowId, points] of Object.entries(readingsByRow)) {
+        out[rowId] = deriveDailySpend(points, resetPeriod);
+    }
+    return out;
+};
+// Sum several services' per-day series into one combined series, keyed by date. A day is `estimated` in the
+// combined series if ANY contributing service estimated it (the total carries that day's uncertainty).
+export const combineDailySpend = (series) => sortBy(Object.values(groupBy(series.flat(), (p) => p.date)).map((perDate) => ({
+    date: perDate[0].date,
+    value: perDate.reduce((sum, p) => sum + p.value, 0),
+    estimated: perDate.some((p) => p.estimated) || undefined
+})), (p) => p.date);

package/dist/export-bundle.d.ts

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+export declare const EXPORT_BUNDLE_FORMAT_VERSION = 1;
+export declare const ExportBundleCapabilitySchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    result: z.ZodOptional<z.ZodUnknown>;
+    lastRunAt: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ExportBundleCapability = z.infer<typeof ExportBundleCapabilitySchema>;
+export declare const ExportPluginProvenanceSchema: z.ZodObject<{
+    contributedBy: z.ZodArray<z.ZodObject<{
+        contributorId: z.ZodString;
+        label: z.ZodString;
+        capturedAt: z.ZodString;
+    }, z.core.$strip>>;
+    coveredBy: z.ZodNumber;
+}, z.core.$strip>;
+export type ExportPluginProvenance = z.infer<typeof ExportPluginProvenanceSchema>;
+export declare const ExportPluginSchema: z.ZodObject<{
+    meta: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        vendor: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
+        icon: z.ZodOptional<z.ZodString>;
+        dashboardUrl: z.ZodOptional<z.ZodString>;
+        capabilities: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    capabilities: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        result: z.ZodOptional<z.ZodUnknown>;
+        lastRunAt: z.ZodOptional<z.ZodString>;
+        error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    provenance: z.ZodOptional<z.ZodObject<{
+        contributedBy: z.ZodArray<z.ZodObject<{
+            contributorId: z.ZodString;
+            label: z.ZodString;
+            capturedAt: z.ZodString;
+        }, z.core.$strip>>;
+        coveredBy: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ExportPlugin = z.infer<typeof ExportPluginSchema>;
+export declare const ExportBundleSchema: z.ZodObject<{
+    formatVersion: z.ZodLiteral<1>;
+    generatedAt: z.ZodString;
+    butinVersion: z.ZodOptional<z.ZodString>;
+    profileName: z.ZodOptional<z.ZodString>;
+    plugins: z.ZodArray<z.ZodObject<{
+        meta: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            vendor: z.ZodOptional<z.ZodString>;
+            category: z.ZodOptional<z.ZodString>;
+            color: z.ZodOptional<z.ZodString>;
+            icon: z.ZodOptional<z.ZodString>;
+            dashboardUrl: z.ZodOptional<z.ZodString>;
+            capabilities: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        capabilities: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            result: z.ZodOptional<z.ZodUnknown>;
+            lastRunAt: z.ZodOptional<z.ZodString>;
+            error: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        provenance: z.ZodOptional<z.ZodObject<{
+            contributedBy: z.ZodArray<z.ZodObject<{
+                contributorId: z.ZodString;
+                label: z.ZodString;
+                capturedAt: z.ZodString;
+            }, z.core.$strip>>;
+            coveredBy: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    overview: z.ZodArray<z.ZodObject<{
+        pluginId: z.ZodString;
+        pluginName: z.ZodString;
+        color: z.ZodOptional<z.ZodString>;
+        icon: z.ZodOptional<z.ZodString>;
+        monthly: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            month: z.ZodString;
+            amount: z.ZodNumber;
+        }, z.core.$strip>>>;
+        daily: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            date: z.ZodString;
+            value: z.ZodNumber;
+            estimated: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+        currentMonthAccrual: z.ZodOptional<z.ZodNumber>;
+        currency: z.ZodOptional<z.ZodString>;
+        balance: z.ZodOptional<z.ZodNumber>;
+        itemCount: z.ZodOptional<z.ZodNumber>;
+        lastRunAt: z.ZodOptional<z.ZodString>;
+        state: z.ZodOptional<z.ZodEnum<{
+            connected: "connected";
+            disconnected: "disconnected";
+        }>>;
+        summaries: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            section: z.ZodEnum<{
+                balance: "balance";
+                other: "other";
+                spend: "spend";
+            }>;
+            label: z.ZodString;
+            value: z.ZodNumber;
+            role: z.ZodEnum<{
+                count: "count";
+                money: "money";
+                percent: "percent";
+            }>;
+            currency: z.ZodOptional<z.ZodString>;
+            basis: z.ZodOptional<z.ZodEnum<{
+                accrued: "accrued";
+                flat: "flat";
+                invoiced: "invoiced";
+                lastInvoice: "lastInvoice";
+                upcoming: "upcoming";
+            }>>;
+            spark: z.ZodOptional<z.ZodObject<{
+                dataset: z.ZodString;
+                x: z.ZodString;
+                y: z.ZodString;
+            }, z.core.$strip>>;
+            headline: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ExportBundle = z.infer<typeof ExportBundleSchema>;
+export type ParseBundleResult = {
+    ok: true;
+    bundle: ExportBundle;
+} | {
+    ok: false;
+    errors: string[];
+};
+export declare const parseExportBundle: (raw: unknown) => ParseBundleResult;

package/dist/export-bundle.js

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { OverviewPluginSchema } from './overview.js';
+// The portable export artifact — Butin's normalized data lifted out as ONE self-contained JSON blob, so a
+// cloud page can render it through @butinapp/ui with zero recompute. Producer = core (buildExportBundle);
+// consumer = @butinapp/viewer.
+//
+// Versioned + zod-validated: the bundle is the most boundary-crossing object in the system — produced by one
+// version of Butin, possibly merged by a gateway, consumed by a separately-deployed viewer. A consumer runs
+// `parseExportBundle` to gate on `formatVersion` (refusing a bundle from a NEWER Butin) and to reject a
+// malformed blob rather than mis-rendering it. Bump the version only on a breaking shape change.
+export const EXPORT_BUNDLE_FORMAT_VERSION = 1;
+// One capability's cached state at export time. `result` is the stored CapabilityResult (datasets/views/
+// summary) — whatever the generic renderer received live. `error` carries a failed last run so the viewer
+// can surface it instead of an empty tab.
+export const ExportBundleCapabilitySchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    result: z.unknown().optional(),
+    lastRunAt: z.string().optional(),
+    error: z.string().optional()
+});
+// Who contributed a service in a MERGED bundle (produced by @butinapp/gateway). Additive + optional, so it is
+// formatVersion-safe: the single-instance export omits it and the current viewer ignores it.
+export const ExportPluginProvenanceSchema = z.object({
+    contributedBy: z.array(z.object({ contributorId: z.string(), label: z.string(), capturedAt: z.string() })),
+    coveredBy: z.number()
+});
+// One service's identity + its capabilities' cached data. `meta.icon` (a self-contained data-URI) is
+// optional — the viewer renders a brand-colored letter monogram from `name` + `color` when it's absent.
+export const ExportPluginSchema = z.object({
+    meta: z.object({
+        id: z.string(),
+        name: z.string(),
+        vendor: z.string().optional(),
+        category: z.string().optional(),
+        color: z.string().optional(),
+        icon: z.string().optional(),
+        dashboardUrl: z.string().optional(),
+        capabilities: z.array(z.object({ id: z.string(), label: z.string() }))
+    }),
+    capabilities: z.array(ExportBundleCapabilitySchema),
+    // Present only on a gateway-merged bundle; absent on a single-instance export.
+    provenance: ExportPluginProvenanceSchema.optional()
+});
+export const ExportBundleSchema = z.object({
+    formatVersion: z.literal(EXPORT_BUNDLE_FORMAT_VERSION),
+    generatedAt: z.string(), // ISO
+    butinVersion: z.string().optional(),
+    profileName: z.string().optional(), // display-only label
+    plugins: z.array(ExportPluginSchema),
+    // The exact input @butinapp/ui's <Overview> consumes — precomputed by the producer so the viewer is a pure
+    // renderer ("the cloud is dumb on purpose").
+    overview: z.array(OverviewPluginSchema)
+});
+export const parseExportBundle = (raw) => {
+    const version = raw?.formatVersion;
+    if (typeof version === 'number' && version > EXPORT_BUNDLE_FORMAT_VERSION) {
+        return {
+            ok: false,
+            errors: [`bundle formatVersion ${version} is newer than this viewer supports (${EXPORT_BUNDLE_FORMAT_VERSION})`]
+        };
+    }
+    const parsed = ExportBundleSchema.safeParse(raw);
+    if (!parsed.success) {
+        return { ok: false, errors: parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`) };
+    }
+    return { ok: true, bundle: parsed.data };
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './overview.js';
+export * from './ledger.js';
+export * from './manifest.js';
+export * from './daily.js';
+export type * from './plugin-view.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+// @butinapp/shapes — the host-layer data shapes the app + viewer share, built ON TOP of the SDK's data-view
+// contract (@butinapp/sdk/data): the cross-service Overview input, the persisted ledger, the presentation
+// manifest, and per-day spend derivation. NOT the plugin-authoring contract (that's @butinapp/sdk) and NOT
+// the portable export wire format (that's @butinapp/shapes/bundle, which the out-of-repo viewer consumes).
+// Producer = core; consumers = core, @butinapp/ui, and the embed viewer.
+export * from './overview.js';
+export * from './ledger.js';
+export * from './manifest.js';
+export * from './daily.js';

package/dist/ledger.d.ts

@@ -0,0 +1,55 @@
+import type { SemanticRole, Section } from '@butinapp/sdk/data';
+import type { MtdBasis } from '@butinapp/sdk/presets';
+export declare const SCHEMA_VERSION = 1;
+export interface StoredColumn {
+    key: string;
+    role: SemanticRole;
+    currency?: string;
+    accrual?: 'cumulative' | 'incremental';
+    resetPeriod?: 'monthly' | 'none';
+}
+export interface StoredDataset {
+    id: string;
+    shape: 'table' | 'record';
+    columns: StoredColumn[];
+    rows: Record<string, unknown>[];
+    key?: string | string[];
+}
+export interface StoredSummary {
+    section: Section;
+    value: number;
+    role: 'money' | 'count' | 'percent';
+    currency?: string;
+    basis?: MtdBasis;
+}
+export interface RowVersion {
+    from: string;
+    to?: string;
+    data: Record<string, unknown>;
+}
+export interface LedgerRow {
+    id: string;
+    firstSeen: string;
+    seenTo: string;
+    versions: RowVersion[];
+}
+export interface DatasetLog {
+    id: string;
+    key?: string | string[];
+    columns: StoredColumn[];
+    rows: LedgerRow[];
+}
+export interface SectionPoint {
+    capturedAt: string;
+    value: number;
+    currency?: string;
+}
+export interface SectionSeries {
+    section: Section;
+    points: SectionPoint[];
+}
+export interface Ledger {
+    schemaVersion: number;
+    datasets: DatasetLog[];
+    series: SectionSeries[];
+}

package/dist/ledger.js

@@ -0,0 +1,3 @@
+// Bumped on any change to roles/sections/ledger semantics. Stamped on each ledger + bundle; gateway reads it to
+// pick an ingest parser. There is no on-disk migrator (history is erased on the cutover that introduces this).
+export const SCHEMA_VERSION = 1;

package/dist/manifest.d.ts

@@ -0,0 +1,27 @@
+import type { BadgeTone, CapabilityResult, View } from '@butinapp/sdk/data';
+import type { StoredDataset, StoredSummary } from './ledger.js';
+export interface ColumnPresentation {
+    label?: string;
+    badges?: Record<string, BadgeTone>;
+    hidden?: boolean;
+    truncate?: boolean;
+}
+export interface SummaryPresentation {
+    label?: string;
+    spark?: {
+        dataset: string;
+        x: string;
+        y: string;
+    };
+}
+export interface PresentationManifest {
+    views: View[];
+    columns?: Record<string, Record<string, ColumnPresentation>>;
+    summaries?: Record<string, SummaryPresentation>;
+}
+export declare const splitResult: (result: CapabilityResult) => {
+    datasets: StoredDataset[];
+    summaries: StoredSummary[];
+    manifest: PresentationManifest;
+};
+export declare const toDisplayResult: (datasets: StoredDataset[], summaries: StoredSummary[], manifest: PresentationManifest) => CapabilityResult;

package/dist/manifest.js

@@ -0,0 +1,97 @@
+import { omitUndef } from '@butinapp/sdk/util';
+const storedColumn = (c) => omitUndef({ key: c.key, role: c.role, currency: c.currency, accrual: c.accrual, resetPeriod: c.resetPeriod });
+const columnPresentation = (c) => {
+    const p = omitUndef({ label: c.label, badges: c.badges, hidden: c.hidden, truncate: c.truncate });
+    return Object.keys(p).length > 0 ? p : undefined;
+};
+const storedDataset = (ds) => {
+    if (ds.shape === 'table') {
+        const out = { id: ds.id, shape: 'table', columns: ds.columns.map(storedColumn), rows: ds.rows };
+        if (ds.key !== undefined) {
+            out.key = ds.key;
+        }
+        return out;
+    }
+    return { id: ds.id, shape: 'record', columns: ds.fields.map(storedColumn), rows: [ds.value] };
+};
+const storedSummary = (s) => omitUndef({ section: s.section, value: s.value, role: s.role, currency: s.currency, basis: s.basis });
+// Separate a CapabilityResult into the data-first records + summaries that land in the ledger, and the
+// presentation manifest that's re-derived at render. Pure.
+export const splitResult = (result) => {
+    const columns = {};
+    for (const ds of result.datasets) {
+        const cols = ds.shape === 'table' ? ds.columns : ds.fields;
+        const byKey = {};
+        for (const c of cols) {
+            const p = columnPresentation(c);
+            if (p) {
+                byKey[c.key] = p;
+            }
+        }
+        if (Object.keys(byKey).length > 0) {
+            columns[ds.id] = byKey;
+        }
+    }
+    const summaryMap = {};
+    for (const s of result.summaries ?? []) {
+        summaryMap[s.section] = omitUndef({ label: s.label, spark: s.spark });
+    }
+    return {
+        datasets: result.datasets.map(storedDataset),
+        summaries: (result.summaries ?? []).map(storedSummary),
+        manifest: omitUndef({
+            views: result.views ?? [],
+            columns: Object.keys(columns).length > 0 ? columns : undefined,
+            summaries: Object.keys(summaryMap).length > 0 ? summaryMap : undefined
+        })
+    };
+};
+const displayColumn = (c, pres) => omitUndef({
+    key: c.key,
+    label: pres?.label ?? c.key,
+    role: c.role,
+    currency: c.currency,
+    accrual: c.accrual,
+    resetPeriod: c.resetPeriod,
+    badges: pres?.badges,
+    hidden: pres?.hidden,
+    truncate: pres?.truncate
+});
+// Rebuild a full CapabilityResult from the stored data-first records + the presentation manifest. The inverse
+// of splitResult: column labels/badges/hidden and summary label/spark come back from the manifest; views are
+// the manifest's. A column with no manifest entry falls back to its key as the label.
+export const toDisplayResult = (datasets, summaries, manifest) => {
+    const displayDatasets = datasets.map((ds) => {
+        const pres = manifest.columns?.[ds.id] ?? {};
+        const cols = ds.columns.map((c) => displayColumn(c, pres[c.key]));
+        if (ds.shape === 'table') {
+            const t = {
+                id: ds.id,
+                shape: 'table',
+                columns: cols,
+                rows: ds.rows,
+                ...(ds.key !== undefined ? { key: ds.key } : {})
+            };
+            return t;
+        }
+        const r = { id: ds.id, shape: 'record', fields: cols, value: ds.rows[0] ?? {} };
+        return r;
+    });
+    const displaySummaries = summaries.map((s) => {
+        const pres = manifest.summaries?.[s.section];
+        return omitUndef({
+            section: s.section,
+            label: pres?.label ?? s.section,
+            value: s.value,
+            role: s.role,
+            currency: s.currency,
+            basis: s.basis,
+            spark: pres?.spark
+        });
+    });
+    return omitUndef({
+        datasets: displayDatasets,
+        views: manifest.views,
+        summaries: displaySummaries.length > 0 ? displaySummaries : undefined
+    });
+};

package/dist/overview.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+export declare const OverviewPluginSchema: z.ZodObject<{
+    pluginId: z.ZodString;
+    pluginName: z.ZodString;
+    color: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+    monthly: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        month: z.ZodString;
+        amount: z.ZodNumber;
+    }, z.core.$strip>>>;
+    daily: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        date: z.ZodString;
+        value: z.ZodNumber;
+        estimated: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    currentMonthAccrual: z.ZodOptional<z.ZodNumber>;
+    currency: z.ZodOptional<z.ZodString>;
+    balance: z.ZodOptional<z.ZodNumber>;
+    itemCount: z.ZodOptional<z.ZodNumber>;
+    lastRunAt: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodEnum<{
+        connected: "connected";
+        disconnected: "disconnected";
+    }>>;
+    summaries: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        section: z.ZodEnum<{
+            balance: "balance";
+            other: "other";
+            spend: "spend";
+        }>;
+        label: z.ZodString;
+        value: z.ZodNumber;
+        role: z.ZodEnum<{
+            count: "count";
+            money: "money";
+            percent: "percent";
+        }>;
+        currency: z.ZodOptional<z.ZodString>;
+        basis: z.ZodOptional<z.ZodEnum<{
+            accrued: "accrued";
+            flat: "flat";
+            invoiced: "invoiced";
+            lastInvoice: "lastInvoice";
+            upcoming: "upcoming";
+        }>>;
+        spark: z.ZodOptional<z.ZodObject<{
+            dataset: z.ZodString;
+            x: z.ZodString;
+            y: z.ZodString;
+        }, z.core.$strip>>;
+        headline: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type OverviewPlugin = z.infer<typeof OverviewPluginSchema>;

package/dist/overview.js

@@ -0,0 +1,35 @@
+import { MonthPointSchema, SummarySchema } from '@butinapp/sdk/schema';
+import { z } from 'zod';
+import { DailyPointSchema } from './daily.js';
+// The pure INPUT view-model for the cross-service Overview. Lives here (not in @butinapp/ui) so both the
+// producer (core's overview assembler / the export bundle) and the consumer (@butinapp/ui's derivation, the
+// embed viewer) share one type. @butinapp/ui re-exports it and owns the DERIVATION (combinedMonthly, movers,
+// byServiceRows, …) — this module is types only, no Electron, no React. Schema-defined so the export-bundle
+// validator can reuse it at the cross-version boundary.
+export const OverviewPluginSchema = z.object({
+    pluginId: z.string(),
+    pluginName: z.string(),
+    color: z.string().optional(),
+    icon: z.string().optional(),
+    monthly: z.array(MonthPointSchema).optional(),
+    // Pre-derived per-day spend (from this plugin's billing capture series), summed across services for the
+    // combined chart's Daily mode.
+    daily: z.array(DailyPointSchema).optional(),
+    // Peak spend reading captured this (reporting-zone) month — the rollup's fallback THIS MO for an arrears
+    // service whose just-closed month has no invoice bar yet and whose live open-period figure has reset.
+    currentMonthAccrual: z.number().optional(),
+    // The currency this plugin's monthly/daily spend series + balance are denominated in (its reportingCurrency).
+    // Optional: a never-fetched / non-money plugin omits it. The Overview derivation converts from it to baseCurrency.
+    currency: z.string().optional(),
+    // Partition inputs: a service appears in every section its summaries report; balance feeds the Balances
+    // rollup; itemCount + lastRunAt + state feed the Activity tiles. All optional — a never-fetched plugin
+    // still gets a tile.
+    balance: z.number().optional(),
+    itemCount: z.number().optional(),
+    lastRunAt: z.string().optional(),
+    state: z.enum(['connected', 'disconnected']).optional(),
+    // Every summary this service reports (deduped by section, first-wins). Drives the section partition + the
+    // cross-service rollup so a bundle-fed Overview (via @butinapp/viewer) sees every section a service emits.
+    // Absent when a tile has no summaries.
+    summaries: z.array(SummarySchema).optional()
+});

package/dist/plugin-view.d.ts

@@ -0,0 +1,42 @@
+import type { ConfigFieldCondition } from '@butinapp/sdk';
+export type CapabilityView = {
+    id: string;
+    label: string;
+    incremental?: boolean;
+};
+export type ConfigFieldView = {
+    key: string;
+    label: string;
+    kind: 'text' | 'secret' | 'select' | 'combobox';
+    required?: boolean;
+    placeholder?: string;
+    help?: string;
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    showWhen?: ConfigFieldCondition;
+};
+export type PluginView = {
+    id: string;
+    name: string;
+    vendor?: string;
+    version?: string;
+    description?: string;
+    category?: string;
+    color?: string;
+    icon?: string;
+    dashboardUrl?: string;
+    hasCookie: boolean;
+    connected: boolean;
+    sessionless: boolean;
+    installed?: boolean;
+    onboardedAt?: number;
+    troubleshooting?: Partial<Record<string, {
+        hint: string;
+        docUrl?: string;
+    }>>;
+    configFields: ConfigFieldView[];
+    config: Record<string, string>;
+    capabilities: CapabilityView[];
+};

package/dist/plugin-view.js

@@ -0,0 +1,7 @@
+// The plugin view-model the renderer draws — the ONE definition core's IPC DTO and @butinapp/ui both build
+// on, so they can't drift. Lives here (the neutral host-shapes package, below both core and ui) rather than
+// in either consumer: core's `PluginSummary` is `PluginView & { …transport-only extras }` and @butinapp/ui
+// re-exports these for embedders, so an embed feeds the same components from a published snapshot and the
+// Electron app from live IPC. No Electron, no React, no IPC — types only. The config-field shapes reuse the
+// SDK's `ConfigFieldCondition` so the settings form and the SDK agree by construction.
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@butinapp/shapes",
+  "version": "0.1.0",
+  "description": "Butin's host-layer data shapes built on the @butinapp/sdk data-view contract: the cross-service Overview input, the persisted ledger, the presentation manifest, and the portable export-bundle wire format.",
+  "homepage": "https://butin.app",
+  "bugs": "https://github.com/butinapp/butin/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/butinapp/butin.git",
+    "directory": "packages/shapes"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./bundle": {
+      "types": "./dist/bundle.d.ts",
+      "import": "./dist/bundle.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@types/lodash-es": "^4.17.12",
+    "@types/luxon": "^3.7.1",
+    "lodash-es": "^4.18.1",
+    "luxon": "^3.7.2",
+    "zod": "^4.3.6",
+    "@butinapp/sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.7"
+  },
+  "scripts": {
+    "build": "tsgo -p tsconfig.build.json",
+    "typecheck": "tsgo --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  }
+}