@butinapp/sdk 0.1.0

package/dist/presets/billing.js

@@ -0,0 +1,209 @@
+import { capabilityResult, record, table } from '../data/builders.js';
+import { resolveTableFiles } from '../data/view.js';
+import { round2 } from '../util/money.js';
+import { creditsRecord, paymentMethodRecord } from './blocks.js';
+import { isAccrualBasis } from './mtd-basis.js';
+// The fileTable spec for the default `invoiceDownload: true`: the host GETs each row's pdfUrl and saves it
+// named from the row's `name` column. A plugin can pass an explicit TableFiles descriptor to override.
+const DEFAULT_INVOICE_FILES = {
+    title: 'Invoices',
+    name: 'name',
+    source: { url: 'pdfUrl' },
+    ext: 'pdf',
+    category: 'Invoices'
+};
+// Bucket invoice amounts by calendar month (ascending) → the monthly-spend series both the Summary chart
+// and the cross-service Overview spark read. Rounded once per month to avoid IEEE-754 drift (0.1+0.2≠0.3).
+// Undated invoices can't bucket onto the monthly axis, so they're skipped.
+export const monthlySpend = (invoices) => {
+    const byMonth = new Map();
+    for (const inv of invoices) {
+        if (!inv.date) {
+            continue;
+        }
+        const month = inv.date.slice(0, 7);
+        byMonth.set(month, (byMonth.get(month) ?? 0) + inv.amount);
+    }
+    return [...byMonth.entries()]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([month, amount]) => ({ month, amount: round2(amount) }));
+};
+// The change from the previous period, in the same money unit (positive = spending more). The baseline depends
+// on what currentMtd measures: an invoiced/last-invoice figure IS the latest month in the series, so it's
+// compared against the prior month; a live figure (accrued/upcoming/flat) is compared against the last full
+// month (the latest series entry). undefined when there's no currentMtd or no baseline month to compare against.
+const monthOverMonthDelta = (months, currentMtd, basis) => {
+    if (currentMtd == null) {
+        return undefined;
+    }
+    const baseline = isAccrualBasis(basis) ? months.at(-1) : months.at(-2);
+    return baseline ? round2(currentMtd - baseline.amount) : undefined;
+};
+const monthlyTable = (months, currency) => table({
+    id: 'monthly',
+    columns: [
+        { key: 'month', label: 'Month', role: 'timestamp' },
+        { key: 'amount', label: 'Spend', role: 'money', currency }
+    ],
+    rows: months,
+    key: 'month'
+});
+// The Summary preset: a headline `account` stat (currentMtd + optional plan + caller
+// stats) + the monthly-spend chart (the Overview spark) + the spend.mtd summary. Deliberately carries NO
+// invoices table — that's the thinner detail ('invoicing') tab. So a billing plugin's Summary collect() is
+// `return billingSummaryResult({...})`, and its detail tab builds the invoices table (+ any extras).
+export const billingSummaryResult = (input) => {
+    const label = input.currentMtdLabel ?? 'This month';
+    const fields = [{ key: 'currentMtd', label, role: 'money', currency: input.currency }];
+    const value = { currentMtd: input.currentMtd };
+    // Parallel to `fields`: each field's stat-card presentation (denominator/unit/caption/tone). A bare key
+    // renders plain; a spec adds the rich layers. Order tracks `fields` so cards render in the declared order.
+    const statFields = [
+        input.currentMtdCaption ? { key: 'currentMtd', caption: input.currentMtdCaption } : 'currentMtd'
+    ];
+    if (input.baseFee !== undefined) {
+        fields.push({ key: 'baseFee', label: 'Base', role: 'money', currency: input.currency });
+        value.baseFee = input.baseFee;
+        statFields.push('baseFee');
+    }
+    if (input.meteredMtd !== undefined) {
+        fields.push({ key: 'meteredMtd', label: 'Overage', role: 'money', currency: input.currency });
+        value.meteredMtd = input.meteredMtd;
+        statFields.push('meteredMtd');
+    }
+    if (input.plan !== undefined) {
+        fields.push({ key: 'plan', label: 'Plan', role: 'label' });
+        value.plan = input.plan ?? null;
+        statFields.push('plan');
+    }
+    const months = monthlySpend(input.invoices);
+    const delta = input.showDelta === false ? undefined : monthOverMonthDelta(months, input.currentMtd, input.mtdBasis);
+    if (delta !== undefined) {
+        fields.push({ key: 'momDelta', label: 'Δ vs last month', role: 'money', currency: input.currency });
+        value.momDelta = delta;
+        // Spending less than the baseline is the good direction → green; more → red.
+        statFields.push({ key: 'momDelta', tone: delta < 0 ? 'positive' : delta > 0 ? 'negative' : 'muted' });
+    }
+    for (const stat of input.stats ?? []) {
+        fields.push({ key: stat.key, label: stat.label, role: stat.role, currency: stat.currency, badges: stat.badges });
+        value[stat.key] = stat.value;
+        statFields.push(stat.max != null || stat.unit != null || stat.caption != null || stat.tone != null
+            ? { key: stat.key, max: stat.max, unit: stat.unit, caption: stat.caption, tone: stat.tone }
+            : stat.key);
+    }
+    const account = record.fromColumns({ id: 'account', fields, value });
+    const monthly = monthlyTable(months, input.currency);
+    const s = input.currentMtd != null
+        ? monthly.summary({
+            section: 'spend',
+            label,
+            value: input.currentMtd,
+            currency: input.currency,
+            basis: input.mtdBasis ?? 'invoiced',
+            x: 'month',
+            y: 'amount'
+        })
+        : undefined;
+    return capabilityResult({
+        sections: [
+            account.stat({ fields: statFields }),
+            monthly.timeseries({
+                x: 'month',
+                y: 'amount',
+                granularity: 'monthly',
+                title: input.monthlyTitle ?? 'Monthly spend'
+            })
+        ],
+        summaries: s ? [s] : undefined
+    });
+};
+// The billing preset: build the role-tagged datasets, the default views, and the spend.mtd summary,
+// so a single-tab billing plugin's whole collect() is `return billingResult({...})`. (Plugins that split
+// into Summary + detail tabs use billingSummaryResult + their own invoices table instead.)
+export const billingResult = (input) => {
+    const invoices = table({
+        id: 'invoices',
+        columns: [
+            { key: 'date', label: 'Date', role: 'timestamp' },
+            { key: 'amount', label: 'Amount', role: 'money', currency: input.currency },
+            { key: 'status', label: 'Status', role: 'status', badges: input.statusTones },
+            { key: 'pdfUrl', label: 'PDF', role: 'url' },
+            { key: 'id', role: 'identifier', hidden: true },
+            { key: 'name', role: 'label', hidden: true }
+        ],
+        rows: input.invoices.map((i) => ({
+            // `id` (provider id, else a date+amount fallback) keys the dataset so invoices accumulate past the window.
+            id: i.id ?? `${i.date ?? 'undated'}:${i.amount}`,
+            date: i.date ?? null,
+            amount: i.amount,
+            status: i.status,
+            pdfUrl: i.pdfUrl ?? i.hostedUrl ?? null,
+            // The download host names each file from this column; absent it falls back to the row index.
+            name: `Invoice ${i.date ?? 'unknown'}`
+        })),
+        key: 'id'
+    });
+    const invoicesSection = input.invoiceDownload === true
+        ? invoices.fileTable(DEFAULT_INVOICE_FILES)
+        : input.invoiceDownload
+            ? invoices.fileTable(fileTableFromOverride(input.invoiceDownload))
+            : invoices.table({ title: 'Invoices' });
+    const accountFields = [{ key: 'currentMtd', label: 'This month', role: 'money', currency: input.currency }];
+    const accountValue = { currentMtd: input.currentMtd };
+    if (input.baseFee !== undefined) {
+        accountFields.push({ key: 'baseFee', label: 'Base', role: 'money', currency: input.currency });
+        accountValue.baseFee = input.baseFee;
+    }
+    if (input.meteredMtd !== undefined) {
+        accountFields.push({ key: 'meteredMtd', label: 'Overage', role: 'money', currency: input.currency });
+        accountValue.meteredMtd = input.meteredMtd;
+    }
+    const months = monthlySpend(input.invoices);
+    const delta = monthOverMonthDelta(months, input.currentMtd, input.mtdBasis);
+    if (delta !== undefined) {
+        accountFields.push({ key: 'momDelta', label: 'Δ vs last month', role: 'money', currency: input.currency });
+        accountValue.momDelta = delta;
+    }
+    accountFields.push({ key: 'plan', label: 'Plan', role: 'label' });
+    accountValue.plan = input.plan ?? null;
+    const account = record.fromColumns({ id: 'account', fields: accountFields, value: accountValue });
+    const monthly = monthlyTable(months, input.currency);
+    const pm = input.paymentMethod ? paymentMethodRecord(input.paymentMethod) : undefined;
+    const credits = input.credits
+        ? creditsRecord({ ...input.credits, currency: input.credits.currency ?? input.currency })
+        : undefined;
+    const s = input.currentMtd != null
+        ? monthly.summary({
+            section: 'spend',
+            label: 'This month',
+            value: input.currentMtd,
+            currency: input.currency,
+            basis: input.mtdBasis ?? 'invoiced',
+            x: 'month',
+            y: 'amount'
+        })
+        : undefined;
+    return capabilityResult({
+        sections: [
+            account.stat(),
+            pm,
+            credits,
+            monthly.timeseries({ x: 'month', y: 'amount', granularity: 'monthly', title: 'Monthly spend' }),
+            invoicesSection
+        ],
+        summaries: s ? [s] : undefined
+    });
+};
+// Normalize an explicit TableFiles override (`source`/`name`/`folder`) into a fileTable spec, defaulting the
+// same wiring as `invoiceDownload: true`.
+const fileTableFromOverride = (override) => {
+    const { urlKey, nameKey, folderKey, ext, category, useFetch } = resolveTableFiles(override);
+    return {
+        title: 'Invoices',
+        name: (nameKey ?? 'name'),
+        source: useFetch ? { fetch: true } : { url: (urlKey ?? 'pdfUrl') },
+        ext,
+        category: category ?? 'Invoices',
+        folder: folderKey
+    };
+};

package/dist/presets/blocks.d.ts

@@ -0,0 +1,43 @@
+import { type ViewSpec } from '../data/builders.js';
+export declare const overageOf: (total: number | null | undefined, base: number | null | undefined) => number | null;
+export interface TrendPoint {
+    date: string;
+    cost?: number;
+    value?: number;
+}
+export declare const dailySeries: (id: string, rows: TrendPoint[], opts?: {
+    title?: string;
+    currency?: string;
+    valueLabel?: string;
+}) => ViewSpec;
+export interface CreditsInput {
+    granted?: number;
+    balance?: number;
+    used?: number;
+    netSpend?: number;
+    currency?: string;
+}
+export declare const creditsRecord: (input: CreditsInput, opts?: {
+    id?: string;
+    title?: string;
+}) => ViewSpec;
+export interface SubscriptionInput {
+    plan?: string;
+    status?: string;
+    seats?: number;
+    unitPrice?: number;
+    periodStart?: string;
+    periodEnd?: string;
+    currency?: string;
+    title?: string;
+}
+export declare const subscriptionRecord: (input: SubscriptionInput) => ViewSpec;
+export interface PaymentMethodInput {
+    brand: string;
+    last4: string;
+    title?: string;
+}
+export declare const paymentMethodRecord: (input: PaymentMethodInput, opts?: {
+    id?: string;
+    title?: string;
+}) => ViewSpec;

package/dist/presets/blocks.js

@@ -0,0 +1,99 @@
+import { record, table } from '../data/builders.js';
+import { round2 } from '../util/money.js';
+// Composable building blocks for collect() results. Each returns a `ViewSpec` a plugin mixes into any
+// CapabilityResult — the lego layer under the opinionated presets (billingResult/usageResult), for rich
+// tabs that outgrow a single preset call. Pure data; fixture-tested in blocks.test.ts.
+// The metered overage above a plan's base fee = max(0, total − base), rounded to cents. null when either side
+// is unknown, so the Overage cell shows an em-dash rather than a misleading 0. Negative deltas (a base fee not
+// yet invoiced this period) clamp to 0, never a negative overage.
+export const overageOf = (total, base) => total != null && base != null ? round2(Math.max(0, total - base)) : null;
+export const dailySeries = (id, rows, opts = {}) => {
+    const isCost = rows.some((r) => r.cost != null);
+    const yLabel = opts.valueLabel ?? (isCost ? 'Cost' : 'Usage');
+    // Keyed on the day so each date accumulates as its own row — the full daily history outlives a rolling window.
+    if (isCost) {
+        const t = table({
+            id,
+            columns: [
+                { key: 'date', label: 'Date', role: 'timestamp' },
+                { key: 'cost', label: yLabel, role: 'money', currency: opts.currency }
+            ],
+            rows: rows.map((r) => ({ date: r.date, cost: r.cost ?? 0 })),
+            key: 'date'
+        });
+        return t.timeseries({ x: 'date', y: 'cost', granularity: 'daily', title: opts.title ?? 'Daily cost' });
+    }
+    const t = table({
+        id,
+        columns: [
+            { key: 'date', label: 'Date', role: 'timestamp' },
+            { key: 'value', label: yLabel, role: 'count' }
+        ],
+        rows: rows.map((r) => ({ date: r.date, value: r.value ?? 0 })),
+        key: 'date'
+    });
+    return t.timeseries({ x: 'date', y: 'value', granularity: 'daily', title: opts.title ?? 'Daily usage' });
+};
+const CREDIT_FIELDS = [
+    { key: 'netSpend', label: 'Net spend' },
+    { key: 'used', label: 'Credits used' },
+    { key: 'balance', label: 'Credit balance' },
+    { key: 'granted', label: 'Credit granted' }
+];
+export const creditsRecord = (input, opts = {}) => {
+    const id = opts.id ?? 'credits';
+    const fields = [];
+    const value = {};
+    for (const f of CREDIT_FIELDS) {
+        if (input[f.key] != null) {
+            fields.push({ key: f.key, label: f.label, role: 'money', currency: input.currency });
+            value[f.key] = input[f.key];
+        }
+    }
+    return record.fromColumns({ id, fields, value }).keyvalue({
+        title: opts.title ?? 'Credits & spend'
+    });
+};
+export const subscriptionRecord = (input) => {
+    const fields = [];
+    const value = {};
+    if (input.plan != null) {
+        fields.push({ key: 'plan', label: 'Plan', role: 'label' });
+        value.plan = input.plan;
+    }
+    if (input.status != null) {
+        fields.push({ key: 'status', label: 'Status', role: 'label' });
+        value.status = input.status;
+    }
+    if (input.seats != null) {
+        fields.push({ key: 'seats', label: 'Seats', role: 'count' });
+        value.seats = input.seats;
+    }
+    if (input.unitPrice != null) {
+        fields.push({ key: 'unitPrice', label: 'Unit price', role: 'money', currency: input.currency });
+        value.unitPrice = input.unitPrice;
+    }
+    const period = [input.periodStart, input.periodEnd].filter(Boolean).join(' → ');
+    if (period) {
+        fields.push({ key: 'period', label: 'Period', role: 'text' });
+        value.period = period;
+    }
+    return record.fromColumns({ id: 'subscription', fields, value }).keyvalue({
+        title: input.title ?? 'Subscription'
+    });
+};
+export const paymentMethodRecord = (input, opts = {}) => {
+    const id = opts.id ?? 'paymentMethod';
+    const fields = [
+        { key: 'brand', label: 'Card', role: 'label' },
+        { key: 'last4', label: 'Last 4', role: 'label' }
+    ];
+    const value = { brand: input.brand, last4: input.last4 };
+    if (input.title) {
+        fields.push({ key: 'title', label: 'Title', role: 'label' });
+        value.title = input.title;
+    }
+    return record.fromColumns({ id, fields, value }).keyvalue({
+        title: opts.title ?? 'Payment method'
+    });
+};

package/dist/presets/index.d.ts

@@ -0,0 +1,38 @@
+export declare const billing: {
+    result: (input: import("./billing.js").BillingInput) => import("../data/result.js").CapabilityResult;
+    summary: (input: import("./billing.js").BillingSummaryInput) => import("../data/result.js").CapabilityResult;
+    monthlySpend: (invoices: import("./billing.js").BillingInvoiceInput[]) => import("../data/series.js").MonthPoint[];
+};
+export declare const usage: {
+    result: (input: import("./usage.js").UsageInput) => import("../data/result.js").CapabilityResult;
+};
+export declare const keys: {
+    result: (input: import("./apikeys.js").ApiKeysInput) => import("../data/result.js").CapabilityResult;
+};
+export declare const members: {
+    result: (input: import("./members.js").MembersInput) => import("../data/result.js").CapabilityResult;
+};
+export declare const blocks: {
+    credits: (input: import("./blocks.js").CreditsInput, opts?: {
+        id?: string;
+        title?: string;
+    }) => import("../data/builders.js").ViewSpec;
+    paymentMethod: (input: import("./blocks.js").PaymentMethodInput, opts?: {
+        id?: string;
+        title?: string;
+    }) => import("../data/builders.js").ViewSpec;
+    subscription: (input: import("./blocks.js").SubscriptionInput) => import("../data/builders.js").ViewSpec;
+    daily: (id: string, rows: import("./blocks.js").TrendPoint[], opts?: {
+        title?: string;
+        currency?: string;
+        valueLabel?: string;
+    }) => import("../data/builders.js").ViewSpec;
+    overageOf: (total: number | null | undefined, base: number | null | undefined) => number | null;
+};
+export type { BillingInput, BillingInvoiceInput, BillingStat, BillingSummaryInput } from './billing.js';
+export type { UsageInput, UsageMetricInput } from './usage.js';
+export type { ApiKeyInput, ApiKeysInput } from './apikeys.js';
+export type { MemberInput, MembersInput } from './members.js';
+export type { CreditsInput, PaymentMethodInput, SubscriptionInput, TrendPoint } from './blocks.js';
+export type { MtdBasis } from './mtd-basis.js';
+export { MtdBasisSchema, MTD_BASIS_LABELS, isAccrualBasis } from './mtd-basis.js';

package/dist/presets/index.js

@@ -0,0 +1,22 @@
+// @butinapp/sdk/presets — the high-altitude result builders, grouped by domain so a dotted prefix says the
+// tier: `billing.summary(...)` / `billing.result(...)`, `usage.result(...)`, `keys.result(...)`,
+// `members.result(...)`. `blocks.*` are the reusable sub-panels a result composes. Badge coloring is the
+// renderer's job — a status column auto-tones, a category column auto-colors — so there's no tone palette
+// here. The pure raw→CapabilityResult normalizers underneath stay fixture-tested in their own modules.
+import { apiKeysResult } from './apikeys.js';
+import { billingResult, billingSummaryResult, monthlySpend } from './billing.js';
+import { creditsRecord, dailySeries, overageOf, paymentMethodRecord, subscriptionRecord } from './blocks.js';
+import { membersResult } from './members.js';
+import { usageResult } from './usage.js';
+export const billing = { result: billingResult, summary: billingSummaryResult, monthlySpend };
+export const usage = { result: usageResult };
+export const keys = { result: apiKeysResult };
+export const members = { result: membersResult };
+export const blocks = {
+    credits: creditsRecord,
+    paymentMethod: paymentMethodRecord,
+    subscription: subscriptionRecord,
+    daily: dailySeries,
+    overageOf
+};
+export { MtdBasisSchema, MTD_BASIS_LABELS, isAccrualBasis } from './mtd-basis.js';

package/dist/presets/members.d.ts

@@ -0,0 +1,11 @@
+import type { CapabilityResult } from '../data/result.js';
+export interface MemberInput {
+    id: string;
+    name?: string;
+    email?: string;
+    role?: string;
+}
+export interface MembersInput {
+    members: MemberInput[];
+}
+export declare const membersResult: (input: MembersInput) => CapabilityResult;

package/dist/presets/members.js

@@ -0,0 +1,15 @@
+import { capabilityResult, table } from '../data/builders.js';
+// The members preset: who has access. One table (name / email / role). No summary.
+export const membersResult = (input) => {
+    const members = table({
+        id: 'members',
+        columns: [
+            { key: 'name', role: 'label', label: 'Name' },
+            { key: 'email', role: 'identifier', label: 'Email' },
+            { key: 'role', role: 'category', label: 'Role' }
+        ],
+        rows: input.members.map((m) => ({ id: m.id, name: m.name ?? null, email: m.email ?? null, role: m.role ?? null })),
+        key: 'id'
+    });
+    return capabilityResult({ sections: [members.table({ title: 'Members' })] });
+};

package/dist/presets/mtd-basis.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+export declare const MtdBasisSchema: z.ZodEnum<{
+    accrued: "accrued";
+    flat: "flat";
+    invoiced: "invoiced";
+    lastInvoice: "lastInvoice";
+    upcoming: "upcoming";
+}>;
+export type MtdBasis = z.infer<typeof MtdBasisSchema>;
+export declare const MTD_BASIS_LABELS: Record<MtdBasis, string>;
+export declare const isAccrualBasis: (basis: MtdBasis | undefined) => boolean;

package/dist/presets/mtd-basis.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+// What a `spend.mtd` figure measures — so the Overview groups/labels like with like instead of blind-summing
+// a flat fee, an accruing usage total, and a last-month invoice into one meaningless number.
+export const MtdBasisSchema = z.enum(['accrued', 'invoiced', 'flat', 'upcoming', 'lastInvoice']);
+export const MTD_BASIS_LABELS = {
+    accrued: 'accrued so far',
+    invoiced: 'invoiced this month',
+    flat: 'fixed monthly fee',
+    upcoming: 'upcoming invoice',
+    lastInvoice: 'last invoice'
+};
+// A basis whose current-month figure is a LIVE open-period accrual that grows through the month (or a fixed
+// recurring fee), as opposed to a settled figure keyed to a past invoice. Only an accrual basis may seed the
+// current-month bar: its captured peak is a real estimate of the month's spend, whereas an 'invoiced'/'lastInvoice'
+// value is a prior bill that would synthesize a phantom bar if projected onto a month with no invoice yet.
+export const isAccrualBasis = (basis) => basis === 'accrued' || basis === 'upcoming' || basis === 'flat';

package/dist/presets/usage.d.ts

@@ -0,0 +1,17 @@
+import type { CapabilityResult } from '../data/result.js';
+import { type TrendPoint } from './blocks.js';
+export interface UsageMetricInput {
+    label: string;
+    value: number;
+    unit?: string;
+    limit?: number | null;
+    cost?: number | null;
+}
+export interface UsageInput {
+    periodStart?: string;
+    periodEnd?: string;
+    metrics: UsageMetricInput[];
+    daily?: TrendPoint[];
+    dailyTitle?: string;
+}
+export declare const usageResult: (input: UsageInput) => CapabilityResult;

package/dist/presets/usage.js

@@ -0,0 +1,61 @@
+import { capabilityResult, record, table } from '../data/builders.js';
+import { round2 } from '../util/money.js';
+import { dailySeries } from './blocks.js';
+// The usage preset: a per-metric table + an 'other'-section money summary when any metric carries a cost (shown
+// per-service on the Overview, never summed into the spend total). A headline record (on-demand spend, period)
+// precedes the table only when there's a spend or period to show — a bare metric COUNT would just echo the
+// table's own row count, so it's never surfaced.
+export const usageResult = (input) => {
+    const totalCost = input.metrics.reduce((sum, m) => sum + (m.cost ?? 0), 0);
+    const hasCost = input.metrics.some((m) => m.cost != null);
+    const period = [input.periodStart, input.periodEnd].filter(Boolean).join(' → ');
+    const headFields = [];
+    const headValue = {};
+    if (hasCost) {
+        headFields.push({ key: 'spend', role: 'money', label: 'On-demand spend' });
+        headValue.spend = round2(totalCost);
+    }
+    if (period) {
+        headFields.push({ key: 'period', role: 'text', label: 'Period' });
+        headValue.period = period;
+    }
+    const usage = headFields.length
+        ? record.fromColumns({ id: 'usage', fields: headFields, value: headValue }).stat()
+        : undefined;
+    const metrics = table({
+        id: 'metrics',
+        columns: [
+            { key: 'label', role: 'label', label: 'Metric' },
+            { key: 'value', role: 'count', label: 'Used' },
+            { key: 'unit', role: 'label', label: 'Unit' },
+            { key: 'limit', role: 'count', label: 'Limit' },
+            { key: 'cost', role: 'money', label: 'Cost' }
+        ],
+        rows: input.metrics.map((m) => ({
+            label: m.label,
+            value: m.value,
+            unit: m.unit ?? null,
+            limit: m.limit ?? null,
+            cost: m.cost ?? null
+        }))
+    });
+    // The daily trend renders between the stat and the per-metric table (stat → chart → table).
+    const daily = input.daily?.length
+        ? dailySeries('daily', input.daily, { title: input.dailyTitle ?? 'Daily cost' })
+        : undefined;
+    const summary = hasCost
+        ? {
+            section: 'other',
+            label: 'On-demand spend',
+            value: round2(totalCost),
+            role: 'money',
+            ...(input.daily?.length
+                ? { spark: { dataset: 'daily', x: 'date', y: input.daily.some((d) => d.cost != null) ? 'cost' : 'value' } }
+                : {})
+        }
+        : undefined;
+    return capabilityResult({
+        sections: [usage, daily, metrics.table({ title: 'Usage' })],
+        summaries: summary ? [summary] : undefined
+    });
+};

package/dist/schema.d.ts

@@ -0,0 +1,2 @@
+export { MonthPointSchema } from './data/series.js';
+export { SummarySchema, SectionSchema } from './data/summary.js';

package/dist/schema.js

@@ -0,0 +1,6 @@
+// @butinapp/sdk/schema — the runtime zod schemas the HOST composes into the export-bundle / Overview wire
+// schema (@butinapp/shapes). NOT the author surface: a plugin author annotates the data-view TYPES on
+// @butinapp/sdk/data (`Summary`, `MonthPoint`, …) and never imports these schema objects. Kept off /data
+// precisely so the author's autocomplete there carries only what a plugin declares.
+export { MonthPointSchema } from './data/series.js';
+export { SummarySchema, SectionSchema } from './data/summary.js';

package/dist/testing/index.d.ts

@@ -0,0 +1,2 @@
+export { createSampleGen, resolveSampleConfig } from './synthetic.js';
+export type { SamplePerson, SampleConfig, SampleSize, SampleDay, SampleMonth, SampleGen, SampleGenerator } from './synthetic.js';

package/dist/testing/index.js

@@ -0,0 +1,6 @@
+// @butinapp/sdk/testing — the seeded synthetic-sample toolkit a plugin reaches for when authoring a
+// capability's `sample`. `createSampleGen` builds a deterministic generator (a shared cast of fake people +
+// synthetic primitives — emails are always `@example.invalid`, so a generated raw can NEVER carry real PII);
+// `resolveSampleConfig` turns the size knobs into a concrete `SampleConfig`. Kept off `/util` (which is the
+// runtime edge-normalizer surface) because this is demo/seed tooling, not request-path code.
+export { createSampleGen, resolveSampleConfig } from './synthetic.js';

package/dist/testing/synthetic.d.ts

@@ -0,0 +1,65 @@
+export interface SamplePerson {
+    id: string;
+    firstName: string;
+    lastName: string;
+    name: string;
+    email: string;
+}
+export interface SampleConfig {
+    users: number;
+    documents: number;
+    days: number;
+    window: number;
+}
+export type SampleSize = 'small' | 'medium' | 'large' | 'xlarge';
+export interface SampleDay {
+    date: string;
+    iso: string;
+    epochMs: number;
+    epochSec: number;
+    yearMonth: string;
+}
+export interface SampleMonth {
+    yearMonth: string;
+    ym: string;
+    startEpochMs: number;
+    startEpochSec: number;
+    label: string;
+}
+export interface SampleGen {
+    person: (i?: number) => SamplePerson;
+    people: (n: number) => SamplePerson[];
+    company: () => string;
+    orgSlug: () => string;
+    id: (prefix?: string) => string;
+    int: (min: number, max: number) => number;
+    float: (min: number, max: number, decimals?: number) => number;
+    bool: (p?: number) => boolean;
+    pick: <T>(items: readonly T[]) => T;
+    maybe: <T>(value: T, p?: number) => T | undefined;
+    money: (min: number, max: number) => number;
+    amountCents: (min: number, max: number) => number;
+    pastDate: (maxDaysAgo: number) => string;
+    dayString: (maxDaysAgo: number) => string;
+    words: (n: number) => string;
+    sentence: () => string;
+    maskedKey: () => string;
+    last4: () => string;
+    phone: () => string;
+    postal: () => string;
+    address: () => string;
+    day: (maxDaysAgo: number) => SampleDay;
+    midnightIso: (maxDaysAgo: number) => string;
+    pastEpochMs: (maxDaysAgo: number) => number;
+    pastEpochSec: (maxDaysAgo: number) => number;
+    monthsAgo: (n: number) => SampleMonth;
+    url: (segment: string, id?: string | number) => string;
+    moneyStr: (min: number, max: number, decimals?: number) => string;
+    seqId: (prefix: string, n: number, width?: number) => string;
+    repeat: <T>(n: number, fn: (i: number, g: SampleGen) => T) => T[];
+}
+export type SampleGenerator<TRaw> = (g: SampleGen, config: SampleConfig) => TRaw;
+export declare const createSampleGen: (seed: string) => SampleGen;
+export declare const resolveSampleConfig: (input?: Partial<SampleConfig> & {
+    size?: SampleSize;
+}) => SampleConfig;