@butinapp/sdk 0.1.0

package/dist/data/result.d.ts

@@ -0,0 +1,163 @@
+import { z } from 'zod';
+export declare const CapabilityResultSchema: z.ZodObject<{
+    datasets: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        shape: z.ZodLiteral<"table">;
+        columns: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            role: z.ZodEnum<{
+                category: "category";
+                count: "count";
+                identifier: "identifier";
+                label: "label";
+                money: "money";
+                percent: "percent";
+                status: "status";
+                text: "text";
+                timestamp: "timestamp";
+                url: "url";
+            }>;
+            currency: z.ZodOptional<z.ZodString>;
+            badges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+                danger: "danger";
+                info: "info";
+                neutral: "neutral";
+                success: "success";
+                warning: "warning";
+            }>>>;
+            accrual: z.ZodOptional<z.ZodEnum<{
+                cumulative: "cumulative";
+                incremental: "incremental";
+            }>>;
+            resetPeriod: z.ZodOptional<z.ZodEnum<{
+                monthly: "monthly";
+                none: "none";
+            }>>;
+            truncate: z.ZodOptional<z.ZodBoolean>;
+            hidden: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        key: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        shape: z.ZodLiteral<"record">;
+        fields: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            role: z.ZodEnum<{
+                category: "category";
+                count: "count";
+                identifier: "identifier";
+                label: "label";
+                money: "money";
+                percent: "percent";
+                status: "status";
+                text: "text";
+                timestamp: "timestamp";
+                url: "url";
+            }>;
+            currency: z.ZodOptional<z.ZodString>;
+            badges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+                danger: "danger";
+                info: "info";
+                neutral: "neutral";
+                success: "success";
+                warning: "warning";
+            }>>>;
+            accrual: z.ZodOptional<z.ZodEnum<{
+                cumulative: "cumulative";
+                incremental: "incremental";
+            }>>;
+            resetPeriod: z.ZodOptional<z.ZodEnum<{
+                monthly: "monthly";
+                none: "none";
+            }>>;
+            truncate: z.ZodOptional<z.ZodBoolean>;
+            hidden: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        value: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>], "shape">>;
+    views: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"stat">;
+        dataset: z.ZodString;
+        fields: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            key: z.ZodString;
+            max: z.ZodOptional<z.ZodNumber>;
+            unit: z.ZodOptional<z.ZodString>;
+            caption: z.ZodOptional<z.ZodString>;
+            tone: z.ZodOptional<z.ZodEnum<{
+                muted: "muted";
+                negative: "negative";
+                positive: "positive";
+            }>>;
+        }, z.core.$strip>]>>>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"timeseries">;
+        dataset: z.ZodString;
+        x: z.ZodString;
+        y: z.ZodString;
+        granularity: z.ZodOptional<z.ZodEnum<{
+            daily: "daily";
+            monthly: "monthly";
+        }>>;
+        stackBy: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"table">;
+        dataset: z.ZodString;
+        columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        title: z.ZodOptional<z.ZodString>;
+        groupBy: z.ZodOptional<z.ZodString>;
+        files: z.ZodOptional<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            source: z.ZodUnion<readonly [z.ZodObject<{
+                url: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                fetch: z.ZodLiteral<true>;
+            }, z.core.$strip>]>;
+            ext: z.ZodOptional<z.ZodString>;
+            category: z.ZodOptional<z.ZodString>;
+            folder: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        detail: z.ZodOptional<z.ZodObject<{
+            dataset: z.ZodString;
+            on: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"keyvalue">;
+        dataset: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "type">>>;
+    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 CapabilityResult = z.infer<typeof CapabilityResultSchema>;
+export declare const validateCapabilityResult: (result: unknown) => string[];

package/dist/data/result.js

@@ -0,0 +1,171 @@
+import { z } from 'zod';
+import { DatasetSchema } from './dataset.js';
+import { SummarySchema } from './summary.js';
+import { ViewSchema } from './view.js';
+// collect() returns this. views/summaries omitted → a preset supplies defaults (see presets/). Each entry in
+// `summaries` headlines one metric tagged by `section` (spend·balance·other); at most one `spend` summary per
+// result (it's the only section that sums across services).
+export const CapabilityResultSchema = z.object({
+    datasets: z.array(DatasetSchema),
+    views: z.array(ViewSchema).optional(),
+    summaries: z.array(SummarySchema).optional()
+});
+const roleOf = (ds, key) => {
+    const cols = ds.shape === 'table' ? ds.columns : ds.fields;
+    return cols.find((c) => c.key === key)?.role;
+};
+// Whether `key` is addressable on a table's rows: a declared column, or a hidden row-identity field carried on
+// every row (the same rule the accumulation `key` check uses). An empty table can't disprove a hidden field.
+const isFieldOf = (ds, key) => {
+    if (ds.shape !== 'table') {
+        return false;
+    }
+    if (ds.columns.some((c) => c.key === key)) {
+        return true;
+    }
+    return ds.rows.length > 0 && ds.rows.every((r) => key in r);
+};
+// Referential checks zod can't express ergonomically: refs resolve, view shape fits dataset shape,
+// chart x/y point at compatible roles.
+const crossRefErrors = (result) => {
+    const errors = [];
+    const byId = new Map();
+    for (const ds of result.datasets) {
+        if (byId.has(ds.id)) {
+            // keep the FIRST dataset for an id so later shape checks don't run against a clashing duplicate
+            errors.push(`duplicate dataset id '${ds.id}'`);
+            continue;
+        }
+        byId.set(ds.id, ds);
+    }
+    // Accumulation contract: a `key` must name real column(s); a cumulative column needs a key to hang its
+    // per-row daily series on.
+    for (const ds of result.datasets) {
+        if (ds.shape !== 'table') {
+            continue;
+        }
+        const colKeys = new Set(ds.columns.map((c) => c.key));
+        const keyParts = ds.key === undefined ? [] : Array.isArray(ds.key) ? ds.key : [ds.key];
+        // A key part is a column or a hidden row-identity field (members/invoice id). Only flag a part that is
+        // neither — and only when there are rows to judge against (an empty table can't disprove a hidden field).
+        for (const k of keyParts) {
+            if (!colKeys.has(k) && ds.rows.length > 0 && !ds.rows.every((r) => k in r)) {
+                errors.push(`key '${k}' is not a column or row field of '${ds.id}'`);
+            }
+        }
+        if (keyParts.length === 0) {
+            for (const c of ds.columns) {
+                if (c.accrual === 'cumulative') {
+                    errors.push(`cumulative column '${c.key}' needs a keyed table (table '${ds.id}' is unkeyed)`);
+                }
+            }
+        }
+        // Every money value must name a currency (resolveCurrencies fills the plugin default first; an
+        // explicit per-value currency overrides it). A money value with no currency is unrenderable + unrollable.
+        for (const c of ds.columns) {
+            if (c.role === 'money' && !c.currency) {
+                errors.push(`money column '${c.key}' in '${ds.id}' has no currency`);
+            }
+        }
+    }
+    // Money-currency rule applies to record fields too (record datasets are skipped by the table-only loop above).
+    for (const ds of result.datasets) {
+        if (ds.shape !== 'record') {
+            continue;
+        }
+        for (const c of ds.fields) {
+            if (c.role === 'money' && !c.currency) {
+                errors.push(`money column '${c.key}' in '${ds.id}' has no currency`);
+            }
+        }
+    }
+    const need = (ref, where) => {
+        const ds = byId.get(ref);
+        if (!ds) {
+            errors.push(`${where} references unknown dataset '${ref}'`);
+        }
+        return ds;
+    };
+    const requireSpark = (ds, x, y, where) => {
+        if (roleOf(ds, x) !== 'timestamp') {
+            errors.push(`${where} x '${x}' must be a timestamp column`);
+        }
+        const yRole = roleOf(ds, y);
+        if (yRole !== 'money' && yRole !== 'count') {
+            errors.push(`${where} y '${y}' must be a money|count column`);
+        }
+    };
+    for (const v of result.views ?? []) {
+        const ds = need(v.dataset, `view '${v.type}'`);
+        if (!ds) {
+            continue;
+        }
+        if (v.type === 'timeseries') {
+            requireSpark(ds, v.x, v.y, 'timeseries');
+        }
+        if ((v.type === 'stat' || v.type === 'keyvalue') && ds.shape !== 'record') {
+            errors.push(`view '${v.type}' needs a record dataset; '${ds.id}' is a ${ds.shape}`);
+        }
+        if (v.type === 'table' && ds.shape !== 'table') {
+            errors.push(`view 'table' needs a table dataset; '${ds.id}' is a ${ds.shape}`);
+        }
+        // groupBy must point at a real column; the files source url / name / folder are row fields (may be hidden,
+        // not necessarily columns), so they aren't checked here — the "files needs a byte source" rule lives in
+        // core's download path (the only place the capability's fetchFile is visible).
+        if (v.type === 'table' && v.groupBy && roleOf(ds, v.groupBy) === undefined) {
+            errors.push(`table groupBy '${v.groupBy}' is not a column of '${ds.id}'`);
+        }
+        // A row-detail binding: the child resolves to a table, and the join field is a field (column or hidden row
+        // field) of BOTH the parent and the child — else the nested rows can't be matched to their parent.
+        if (v.type === 'table' && v.detail) {
+            const child = need(v.detail.dataset, `table detail`);
+            if (child && child.shape !== 'table') {
+                errors.push(`table detail '${v.detail.dataset}' must be a table dataset; it is a ${child.shape}`);
+            }
+            if (child && child.shape === 'table') {
+                for (const [where, target] of [
+                    ['parent', ds],
+                    ['child', child]
+                ]) {
+                    if (!isFieldOf(target, v.detail.on)) {
+                        errors.push(`table detail 'on' field '${v.detail.on}' is not a field of the ${where} table '${target.id}'`);
+                    }
+                }
+            }
+        }
+    }
+    let spendCount = 0;
+    for (const s of result.summaries ?? []) {
+        if (s.section === 'spend') {
+            spendCount += 1;
+        }
+        if (s.role === 'money' && !s.currency) {
+            errors.push(`money summary '${s.label}' has no currency`);
+        }
+        // A spend summary headlines the Overview's monthly chart + previous-month total, both read off its spark's
+        // monthly series. With no spark it silently contributes nothing there — require one (presence, not rows, so a
+        // brand-new account with an empty monthly table is still fine).
+        if (s.section === 'spend' && !s.spark) {
+            errors.push(`spend summary '${s.label}' needs a spark (the monthly series the Overview reads)`);
+        }
+        if (s.spark) {
+            const ds = need(s.spark.dataset, `summary '${s.label}' spark`);
+            if (ds) {
+                requireSpark(ds, s.spark.x, s.spark.y, `summary '${s.label}' spark`);
+            }
+        }
+    }
+    if (spendCount > 1) {
+        errors.push('more than one spend summary in a result');
+    }
+    return errors;
+};
+// Returns a list of human-readable contract errors; [] = valid. Structural errors come from zod,
+// referential errors from crossRefErrors. Distinct from a collect() fetch failure.
+export const validateCapabilityResult = (result) => {
+    const parsed = CapabilityResultSchema.safeParse(result);
+    if (!parsed.success) {
+        return parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`);
+    }
+    return crossRefErrors(parsed.data);
+};

package/dist/data/roles.d.ts

@@ -0,0 +1,17 @@
+import type { SemanticRole } from './dataset.js';
+type RoleValueMap = {
+    money: number | null;
+    count: number | null;
+    percent: number | null;
+    timestamp: string | null;
+    status: string | null;
+    category: string | null;
+    label: string | null;
+    identifier: string | null;
+    url: string | null;
+    text: string | null;
+};
+export type RolesFor<V> = {
+    [R in SemanticRole]: V | null extends RoleValueMap[R] ? R : never;
+}[SemanticRole];
+export {};

package/dist/data/roles.js

@@ -0,0 +1,3 @@
+const _rolesCovered = true;
+void _rolesCovered;
+export {};

package/dist/data/series.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+export declare const MonthPointSchema: z.ZodObject<{
+    month: z.ZodString;
+    amount: z.ZodNumber;
+}, z.core.$strip>;
+export type MonthPoint = z.infer<typeof MonthPointSchema>;

package/dist/data/series.js

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+// A point on a monthly money axis ('YYYY-MM' → amount in major units). The shared shape the billing presets
+// emit (monthlySpend) and the cross-service Overview rollup consumes, so the two can't drift. Schema-defined
+// so the export-bundle validator can reuse it at the cross-version boundary.
+export const MonthPointSchema = z.object({ month: z.string(), amount: z.number() });

package/dist/data/summary.d.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+export declare const SectionSchema: z.ZodEnum<{
+    balance: "balance";
+    other: "other";
+    spend: "spend";
+}>;
+export type Section = z.infer<typeof SectionSchema>;
+export declare const SummarySchema: 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>;
+export type Summary = z.infer<typeof SummarySchema>;

package/dist/data/summary.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { MtdBasisSchema } from '../presets/mtd-basis.js';
+// Which Overview section a summary feeds. Only 'spend' sums across services (the combined spend total + chart);
+// 'balance' and 'other' are shown per-service, never summed. Additive: a future summing band (e.g. 'revenue')
+// is a new enum value plus a one-line rollup rule.
+export const SectionSchema = z.enum(['spend', 'balance', 'other']);
+export const SummarySchema = z.object({
+    section: SectionSchema,
+    label: z.string(),
+    value: z.number(),
+    role: z.enum(['money', 'count', 'percent']),
+    currency: z.string().optional(),
+    // What a spend figure measures (accrued / invoiced / flat / upcoming / lastInvoice) — a display label.
+    basis: MtdBasisSchema.optional(),
+    spark: z.object({ dataset: z.string(), x: z.string(), y: z.string() }).optional(),
+    // Force this summary to be the service's headline (overrides the spend > balance > other default).
+    headline: z.boolean().optional()
+});

package/dist/data/view.d.ts

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+export declare const FileSourceSchema: z.ZodUnion<readonly [z.ZodObject<{
+    url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    fetch: z.ZodLiteral<true>;
+}, z.core.$strip>]>;
+export type FileSource = z.infer<typeof FileSourceSchema>;
+export declare const TableFilesSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    source: z.ZodUnion<readonly [z.ZodObject<{
+        url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        fetch: z.ZodLiteral<true>;
+    }, z.core.$strip>]>;
+    ext: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    folder: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TableFiles = z.infer<typeof TableFilesSchema>;
+export declare const resolveTableFiles: (f: TableFiles) => {
+    urlKey?: string;
+    nameKey?: string;
+    folderKey?: string;
+    ext?: string;
+    category?: string;
+    useFetch: boolean;
+};
+export type StatTone = 'positive' | 'negative' | 'muted';
+export declare const StatFieldSchema: z.ZodObject<{
+    key: z.ZodString;
+    max: z.ZodOptional<z.ZodNumber>;
+    unit: z.ZodOptional<z.ZodString>;
+    caption: z.ZodOptional<z.ZodString>;
+    tone: z.ZodOptional<z.ZodEnum<{
+        muted: "muted";
+        negative: "negative";
+        positive: "positive";
+    }>>;
+}, z.core.$strip>;
+export type StatField = z.infer<typeof StatFieldSchema>;
+export declare const ViewSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"stat">;
+    dataset: z.ZodString;
+    fields: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        key: z.ZodString;
+        max: z.ZodOptional<z.ZodNumber>;
+        unit: z.ZodOptional<z.ZodString>;
+        caption: z.ZodOptional<z.ZodString>;
+        tone: z.ZodOptional<z.ZodEnum<{
+            muted: "muted";
+            negative: "negative";
+            positive: "positive";
+        }>>;
+    }, z.core.$strip>]>>>;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"timeseries">;
+    dataset: z.ZodString;
+    x: z.ZodString;
+    y: z.ZodString;
+    granularity: z.ZodOptional<z.ZodEnum<{
+        daily: "daily";
+        monthly: "monthly";
+    }>>;
+    stackBy: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"table">;
+    dataset: z.ZodString;
+    columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    title: z.ZodOptional<z.ZodString>;
+    groupBy: z.ZodOptional<z.ZodString>;
+    files: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        source: z.ZodUnion<readonly [z.ZodObject<{
+            url: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            fetch: z.ZodLiteral<true>;
+        }, z.core.$strip>]>;
+        ext: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        folder: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    detail: z.ZodOptional<z.ZodObject<{
+        dataset: z.ZodString;
+        on: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"keyvalue">;
+    dataset: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+export type View = z.infer<typeof ViewSchema>;

package/dist/data/view.js

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+// Byte source for a downloadable table's rows: a per-row url column (the host GETs it) OR the capability's
+// fetchFile(ctx,row) hook (POST/multi-step downloads). Exactly one.
+export const FileSourceSchema = z.union([z.object({ url: z.string() }), z.object({ fetch: z.literal(true) })]);
+// Marks a table's rows as downloadable files. Presentation only — the renderer adds selection + a Size column
+// + per-row View/Open. Download-transport knobs (referer/concurrency) live on the plugin's transport download
+// config, not here.
+export const TableFilesSchema = z.object({
+    name: z.string().optional(), // row field naming each file
+    source: FileSourceSchema,
+    ext: z.string().optional(),
+    category: z.string().optional(), // literal subfolder for all of the table's files
+    folder: z.string().optional() // per-row subfolder column (overrides category)
+});
+// Normalize a TableFiles descriptor (`source`/`name`/`folder`) to the flat accessor keys the renderer + the
+// download path read. `useFetch` true means the byte source is the capability's fetchFile hook (no url column).
+export const resolveTableFiles = (f) => ({
+    urlKey: 'url' in f.source ? f.source.url : undefined,
+    nameKey: f.name,
+    folderKey: f.folder,
+    ext: f.ext,
+    category: f.category,
+    useFetch: 'fetch' in f.source
+});
+const STAT_TONES = ['positive', 'negative', 'muted'];
+// Per-field presentation for a stat card, beyond the bare value the column's role formats. All optional and
+// all literals (collect() runs per fetch with live data, and the view round-trips through the manifest), so a
+// plugin computes them at build time. `max` renders `value / max` + a progress bar (value/max); `unit` is a
+// muted suffix (e.g. '/mo'); `caption` is a subtext/breakdown line; `tone` tints the value.
+export const StatFieldSchema = z.object({
+    key: z.string(),
+    max: z.number().optional(),
+    unit: z.string().optional(),
+    caption: z.string().optional(),
+    tone: z.enum(STAT_TONES).optional()
+});
+// A view binds a dataset (by id) to a generic renderer. Adding a view = adding a descriptor.
+export const ViewSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('stat'),
+        dataset: z.string(),
+        // A bare key shows the field's value as-is; a StatField adds denominator/progress, caption, unit, or tone.
+        fields: z.array(z.union([z.string(), StatFieldSchema])).optional(),
+        title: z.string().optional()
+    }),
+    z.object({
+        type: z.literal('timeseries'),
+        dataset: z.string(),
+        x: z.string(),
+        y: z.string(),
+        // Declared cadence of the series, so the renderer picks the chart (monthly spend vs daily trend) from
+        // intent rather than sniffing the x-axis label format.
+        granularity: z.enum(['monthly', 'daily']).optional(),
+        // A category column → a stacked breakdown chart: rows are long-format (each carries x, this category, and
+        // y), one stacked series per distinct category, with a legend. Absent → a single-series chart.
+        stackBy: z.string().optional(),
+        title: z.string().optional()
+    }),
+    z.object({
+        type: z.literal('table'),
+        dataset: z.string(),
+        columns: z.array(z.string()).optional(),
+        title: z.string().optional(),
+        // A column key → collapsible grouped sections (per-group select-all + Download).
+        groupBy: z.string().optional(),
+        files: TableFilesSchema.optional(),
+        // Expand each row into a nested table drawn from another (table) dataset in the result, joined on a field
+        // present on both sides: a parent row R shows the child rows where child[on] === R[on]. The child renders
+        // with its own column roles. This is the static-child-table expansion — distinct from the built-in daily
+        // drilldown a cumulative column derives; when both could apply, `detail` wins.
+        detail: z.object({ dataset: z.string(), on: z.string() }).optional()
+    }),
+    z.object({ type: z.literal('keyvalue'), dataset: z.string(), title: z.string().optional() })
+]);

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export type { PluginCategory, TroubleshootingCause, TroubleshootingAction, Troubleshooting, PluginMeta } from './plugin/meta.js';
+export type { LocalStorageToken, ManualField, SessionSource } from './plugin/session.js';
+export type { CredentialStore, AuthContext, AuthAttachment, AuthResolveHook, AuthStrategy, AuthKind, SpaBearerAuth } from './plugin/auth.js';
+export type { TransportEngine, DownloadTransport, TransportConfig, HttpMethod, RequestOptions, ButinResponse, ButinClient } from './plugin/transport.js';
+export type { BrowserFetchInit, BrowserContext, BrowserPage, BrowserSession } from './plugin/browser.js';
+export { configValuesSchema, defineConfigSchema } from './plugin/config.js';
+export type { ConfigFieldKind, ConfigOption, ConfigFieldCondition, ConfigField, PluginConfigSchema, ConfigValues, ConfigOf } from './plugin/config.js';
+export { defineCapability } from './plugin/capability.js';
+export type { CollectContext, Capability, IncrementalSpec, IncrementalCapability } from './plugin/capability.js';
+export type { DocumentBytes } from './plugin/documents.js';
+export { definePlugin } from './plugin/plugin.js';
+export type { ButinPlugin, PluginBackend } from './plugin/plugin.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+// @butinapp/sdk — the plugin-authoring contract: everything needed to DECLARE a plugin — the descriptor
+// (meta · session · auth · transport · browser · config · capability · documents · plugin) and the define*
+// helpers. The separate "what a capability returns" tier — the data-view contract (datasets · views ·
+// summary · result) + the typed builders (table · record · capabilityResult) — is '@butinapp/sdk/data'. The
+// high-altitude preset builders live on '@butinapp/sdk/presets'; shared third-party mechanics on
+// '@butinapp/sdk/integrations'; edge normalizers on '@butinapp/sdk/util'; the synthetic sample toolkit on
+// '@butinapp/sdk/testing'; lodash + luxon on '@butinapp/sdk/libs'. The host-layer rollup/wire shapes core +
+// the viewer consume are NOT here — they live in '@butinapp/shapes' (and the wire format on
+// '@butinapp/shapes/bundle'), so the author SDK stays purely the plugin-authoring contract.
+//
+// This barrel is an explicit allowlist, not a wildcard: a symbol is public only when it's named here.
+export { configValuesSchema, defineConfigSchema } from './plugin/config.js';
+export { defineCapability } from './plugin/capability.js';
+export { definePlugin } from './plugin/plugin.js';

package/dist/integrations/index.d.ts

@@ -0,0 +1 @@
+export * from './stripe.js';

package/dist/integrations/index.js

@@ -0,0 +1,4 @@
+// @butinapp/sdk/integrations — shared mechanics for third-party providers that more than one service proxies
+// to. Not part of the universal plugin contract (a plugin that doesn't touch the provider never sees these),
+// so they live off the root barrel. Today: Stripe's hosted billing-portal walk + hosted-invoice PDF download.
+export * from './stripe.js';