@butinapp/sdk 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,63 @@
+# `@butinapp/sdk`
+
+The plugin contract for [Butin](../../README.md). A plugin connects one service: you sign in once so Butin
+captures your session, then it fetches from that service headless and brings the data home, normalized. This
+package is **pure data + types** — no Electron, no React. Core runs your descriptor; one generic renderer in
+`@butinapp/ui` draws whatever a capability returns.
+
+## A plugin in one object
+
+```ts
+import { definePlugin } from '@butinapp/sdk'
+import { billing } from '@butinapp/sdk/presets'
+
+export const acmePlugin = definePlugin({
+  meta: { id: 'acme', name: 'Acme', color: '#3b82f6' },
+  session: { loginUrl: 'https://acme.com/login', dashboardMarkers: ['/dashboard'], cookieDomains: ['acme.com'] },
+  auth: { kind: 'cookie' }, // replay the stored cookie verbatim
+  capabilities: [
+    { id: 'billing', label: 'Billing', collect: async (ctx) => billing.result(await fetchAcmeBilling(ctx)) }
+  ]
+})
+```
+
+`collect(ctx)` gets an authed `ctx.client` (auth + transport pre-applied) and returns a **`CapabilityResult`**
+(`{ datasets, views?, summary? }`). Prefer the **presets** on `@butinapp/sdk/presets` (`billing.result` ·
+`billing.summary` · `usage.result` · `keys.result` · `members.result`) over hand-building datasets/views —
+they map normalized input onto the renderer for you.
+
+## Every service is three declarative axes
+
+| Axis             | Where              | Options                                                                                                                         |
+| ---------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| **Transport**    | `transport.engine` | `node` (axios) · `electron` (real browser identity, for sites that need the browser engine — set `requiresBrowserEngine: true`) |
+| **Auth**         | `auth.kind`        | `cookie` · `bearer-token` · `external` · `api-key` · `cookie-csrf` · `minted-jwt` · `rotating-refresh` · `spa-bearer`           |
+| **Render shape** | inside `collect()` | JSON · GraphQL · tRPC · Remix/RSC · HTML scrape · gRPC-web — parse however the service needs                                    |
+
+The source files are the reference, each documented inline: `meta.ts` · `session.ts` · `auth.ts` ·
+`transport.ts` · `config.ts` · `capability.ts` · the data-view contract (`dataset.ts` · `view.ts` ·
+`summary.ts` · `result.ts` · `presets/*`).
+
+## Typed settings
+
+Declare a plugin's settings once with `defineConfigSchema`; `definePlugin` infers `ctx.config`'s type from it — no
+explicit generic, no annotation:
+
+```ts
+const acmeConfig = defineConfigSchema([{ key: 'orgId', label: 'Organization', kind: 'text', required: true }])
+type AcmeConfig = ConfigOf<typeof acmeConfig> // { orgId: string }
+
+export const acmePlugin = definePlugin({ config: acmeConfig /* ctx.config is AcmeConfig in every collect() */ })
+```
+
+## Authoring a plugin
+
+1. Scaffold: `pnpm new-plugin <id>` (no `pnpm install` — a plugin is a folder in the existing
+   `@butinapp/plugins` package, auto-discovered, no registration).
+2. Put everything in `src/main.ts`: the `definePlugin`, the `collect()` bodies, and the pure `build*()`
+   transforms (raw payload → `CapabilityResult`).
+3. Test the **pure `build*()`** against a redacted fixture and assert with `validateCapabilityResult` — that's
+   where coverage lives. See `plugins/serper/` for the canonical example.
+
+The repo root `CONTRIBUTING.md` and `packages/website` (user docs) have the full guide. `@butinapp/*` packages are
+bundled into the app, not published to npm.

package/dist/data/builders.d.ts

@@ -0,0 +1,111 @@
+import { type Accrual, type BadgeTone, type Column, type Dataset, type RecordDataset, type ResetPeriod, type TableDataset } from './dataset.js';
+import type { CapabilityResult } from './result.js';
+import type { RolesFor } from './roles.js';
+import type { Section, Summary } from './summary.js';
+import type { View } from './view.js';
+export type ViewSpec = {
+    view: View;
+    dataset: Dataset;
+    extraDatasets?: Dataset[];
+};
+type TypedColumn<Row, K extends keyof Row> = {
+    key: K;
+    role: RolesFor<Exclude<Row[K], undefined>>;
+    label?: string;
+    currency?: string;
+    badges?: Record<string, BadgeTone>;
+    accrual?: Accrual;
+    resetPeriod?: ResetPeriod;
+    truncate?: boolean;
+    hidden?: boolean;
+};
+export type RowColumn<Row> = {
+    [K in keyof Row]-?: TypedColumn<Row, K>;
+}[keyof Row];
+type Key<Row> = keyof Row & string;
+type FileSource<Row> = {
+    url: Key<Row>;
+} | {
+    fetch: true;
+};
+export type FileTableSpec<Row> = {
+    title?: string;
+    name: Key<Row>;
+    source: FileSource<Row>;
+    ext?: string;
+    category?: string;
+    folder?: Key<Row>;
+    columns?: Key<Row>[];
+    groupBy?: Key<Row>;
+};
+type SummarySpec<Row> = {
+    section: Section;
+    label: string;
+    value: number;
+    role?: 'money' | 'count' | 'percent';
+    currency?: string;
+    basis?: Summary['basis'];
+    x?: Key<Row>;
+    y?: Key<Row>;
+};
+export type RowDetailSpec<Row> = {
+    rows: TableHandle<unknown>;
+    on: Key<Row>;
+};
+export interface TableHandle<Row> {
+    dataset: TableDataset;
+    table(opts?: {
+        title?: string;
+        columns?: Key<Row>[];
+        groupBy?: Key<Row>;
+        detail?: RowDetailSpec<Row>;
+    }): ViewSpec;
+    fileTable(opts: FileTableSpec<Row>): ViewSpec;
+    timeseries(opts: {
+        x: Key<Row>;
+        y: Key<Row>;
+        granularity?: 'monthly' | 'daily';
+        stackBy?: Key<Row>;
+        title?: string;
+    }): ViewSpec;
+    summary(opts: SummarySpec<Row>): Summary;
+}
+export type StatFieldSpec<Row> = {
+    key: Key<Row>;
+    max?: number;
+    unit?: string;
+    caption?: string;
+    tone?: 'positive' | 'negative' | 'muted';
+};
+export interface RecordHandle<Row> {
+    dataset: RecordDataset;
+    stat(opts?: {
+        fields?: (Key<Row> | StatFieldSpec<Row>)[];
+        title?: string;
+    }): ViewSpec;
+    keyvalue(opts?: {
+        title?: string;
+    }): ViewSpec;
+}
+export declare const table: <Row extends object>(spec: {
+    id: string;
+    columns: RowColumn<Row>[];
+    rows: Row[];
+    key?: Key<Row> | Key<Row>[];
+}) => TableHandle<Row>;
+export declare const record: (<Row extends object>(spec: {
+    id: string;
+    fields: RowColumn<Row>[];
+    value: Row;
+}) => RecordHandle<Row>) & {
+    fromColumns: (spec: {
+        id: string;
+        fields: Column[];
+        value: Record<string, unknown>;
+    }) => RecordHandle<Record<string, unknown>>;
+};
+export declare const capabilityResult: (spec: {
+    sections: (ViewSpec | null | undefined | false)[];
+    summaries?: Summary[];
+}) => CapabilityResult;
+export {};

package/dist/data/builders.js

@@ -0,0 +1,103 @@
+import { uniqBy } from 'lodash-es';
+import { omitUndef } from '../util/object.js';
+import { rawRecord, rawTable } from './dataset.js';
+// `Row extends object` (not `Record<string, unknown>`) so an `interface` row type is accepted: TS interfaces
+// lack an implicit index signature, so they fail the Record constraint even though their fields are known.
+export const table = (spec) => {
+    // The typed builder is the only public way to construct a dataset; it delegates the wire-object shape to
+    // the low-level rawTable so there's a single place that knows the TableDataset layout.
+    const dataset = rawTable(spec.id, spec.columns, spec.rows, spec.key);
+    // Each method annotates its view against the matching View union variant before omitUndef strips the
+    // undefined keys — the annotation structurally checks the builder's field set, so a drift between what the
+    // builder emits and the wire schema fails to compile rather than slipping through a cast.
+    return {
+        dataset,
+        table: (opts = {}) => {
+            const view = {
+                type: 'table',
+                dataset: spec.id,
+                title: opts.title,
+                columns: opts.columns,
+                groupBy: opts.groupBy,
+                detail: opts.detail ? { dataset: opts.detail.rows.dataset.id, on: opts.detail.on } : undefined
+            };
+            return {
+                dataset,
+                view: omitUndef(view),
+                ...(opts.detail ? { extraDatasets: [opts.detail.rows.dataset] } : {})
+            };
+        },
+        fileTable: (opts) => {
+            const view = {
+                type: 'table',
+                dataset: spec.id,
+                title: opts.title,
+                columns: opts.columns,
+                groupBy: opts.groupBy,
+                files: omitUndef({
+                    name: opts.name,
+                    source: opts.source,
+                    ext: opts.ext,
+                    category: opts.category,
+                    folder: opts.folder
+                })
+            };
+            return { dataset, view: omitUndef(view) };
+        },
+        timeseries: (opts) => {
+            const view = {
+                type: 'timeseries',
+                dataset: spec.id,
+                x: opts.x,
+                y: opts.y,
+                granularity: opts.granularity,
+                stackBy: opts.stackBy,
+                title: opts.title
+            };
+            return { dataset, view: omitUndef(view) };
+        },
+        summary: (opts) => {
+            const summary = {
+                section: opts.section,
+                label: opts.label,
+                value: opts.value,
+                role: opts.role ?? 'money',
+                currency: opts.currency,
+                basis: opts.basis,
+                spark: opts.x && opts.y ? { dataset: spec.id, x: opts.x, y: opts.y } : undefined
+            };
+            return omitUndef(summary);
+        }
+    };
+};
+// The stat/keyvalue handle off an already-built record dataset — shared by the typed `record` and the
+// dynamic `record.fromColumns`.
+const recordHandle = (dataset) => ({
+    dataset,
+    stat: (opts = {}) => {
+        const fields = opts.fields?.map((f) => (typeof f === 'string' ? f : omitUndef(f)));
+        const view = { type: 'stat', dataset: dataset.id, fields, title: opts.title };
+        return { dataset, view: omitUndef(view) };
+    },
+    keyvalue: (opts = {}) => {
+        const view = { type: 'keyvalue', dataset: dataset.id, title: opts.title };
+        return { dataset, view: omitUndef(view) };
+    }
+});
+// A record dataset. `record({ id, fields, value })` types the columns against a statically-known row.
+// `record.fromColumns({ id, fields, value })` is the dynamic form for a runtime-assembled `Column[]` + value
+// object (a preset building an account/credits/payment-method record from optional fields) — no per-row
+// generic, no cast at the call site.
+export const record = Object.assign((spec) => recordHandle(rawRecord(spec.id, spec.fields, spec.value)), {
+    fromColumns: (spec) => recordHandle(rawRecord(spec.id, spec.fields, spec.value))
+});
+// Assemble a CapabilityResult from view-specs: collect each section's dataset (de-duped by id, first wins),
+// drop falsy sections (conditional panels), and attach optional summaries. Section order is literal array order.
+export const capabilityResult = (spec) => {
+    const sections = spec.sections.filter((s) => Boolean(s));
+    return {
+        datasets: uniqBy(sections.flatMap((s) => [s.dataset, ...(s.extraDatasets ?? [])]), (d) => d.id),
+        views: sections.map((s) => s.view),
+        ...(spec.summaries?.length ? { summaries: spec.summaries } : {})
+    };
+};

package/dist/data/currency.d.ts

@@ -0,0 +1,3 @@
+import type { CapabilityResult } from './result.js';
+export type CurrencyCode = 'USD' | 'CAD' | 'EUR' | 'GBP' | 'AUD' | 'NZD' | 'JPY' | 'CHF' | 'CNY' | 'INR' | 'BRL' | 'MXN' | 'SEK' | 'NOK' | 'DKK' | 'SGD' | 'HKD' | 'ZAR' | 'PLN';
+export declare const resolveCurrencies: (result: CapabilityResult, reportingCurrency: CurrencyCode) => CapabilityResult;

package/dist/data/currency.js

@@ -0,0 +1,11 @@
+// Fill the concrete currency onto every money value that did not declare one, so the persisted report is
+// self-describing and nothing downstream falls back to a guessed default. A money value's own `currency`
+// (a per-value override) always wins; non-money roles are never touched.
+const stampColumns = (cols, reportingCurrency) => cols.map((c) => (c.role === 'money' && !c.currency ? { ...c, currency: reportingCurrency } : c));
+export const resolveCurrencies = (result, reportingCurrency) => {
+    const datasets = result.datasets.map((ds) => ds.shape === 'table'
+        ? { ...ds, columns: stampColumns(ds.columns, reportingCurrency) }
+        : { ...ds, fields: stampColumns(ds.fields, reportingCurrency) });
+    const summaries = result.summaries?.map((s) => s.role === 'money' && !s.currency ? { ...s, currency: reportingCurrency } : s);
+    return { ...result, datasets, ...(summaries?.length ? { summaries } : {}) };
+};

package/dist/data/dataset.d.ts

@@ -0,0 +1,229 @@
+import { z } from 'zod';
+export declare const SemanticRoleSchema: z.ZodEnum<{
+    category: "category";
+    count: "count";
+    identifier: "identifier";
+    label: "label";
+    money: "money";
+    percent: "percent";
+    status: "status";
+    text: "text";
+    timestamp: "timestamp";
+    url: "url";
+}>;
+export type SemanticRole = z.infer<typeof SemanticRoleSchema>;
+export declare const BadgeToneSchema: z.ZodEnum<{
+    danger: "danger";
+    info: "info";
+    neutral: "neutral";
+    success: "success";
+    warning: "warning";
+}>;
+export type BadgeTone = z.infer<typeof BadgeToneSchema>;
+export declare const AccrualSchema: z.ZodEnum<{
+    cumulative: "cumulative";
+    incremental: "incremental";
+}>;
+export type Accrual = z.infer<typeof AccrualSchema>;
+export declare const ResetPeriodSchema: z.ZodEnum<{
+    monthly: "monthly";
+    none: "none";
+}>;
+export type ResetPeriod = z.infer<typeof ResetPeriodSchema>;
+export declare const ColumnSchema: 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>;
+export type Column = z.infer<typeof ColumnSchema>;
+export declare const TableDatasetSchema: 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>;
+export type TableDataset = z.infer<typeof TableDatasetSchema>;
+export declare const RecordDatasetSchema: 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>;
+export type RecordDataset = z.infer<typeof RecordDatasetSchema>;
+export declare const DatasetSchema: 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">;
+export type Dataset = z.infer<typeof DatasetSchema>;
+export declare const rawTable: (id: string, columns: Column[], rows: Record<string, unknown>[], key?: string | string[]) => TableDataset;
+export declare const rawRecord: (id: string, fields: Column[], value: Record<string, unknown>) => RecordDataset;

package/dist/data/dataset.js

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+// The semantic role tells the renderer what a column MEANS (money → formatUsd, timestamp → chart axis,
+// status → sentiment badge, category → distinct-hue badge, url → link) and lets cross-service rollups find
+// comparable fields. The two badge roles split by intent: `status` carries SENTIMENT (active is good, failed
+// is bad) — the renderer auto-tones a known vocabulary; `category` carries NO sentiment (a member role, a
+// seat tier) — the renderer assigns each value a stable distinct hue. `label` is plain text.
+export const SemanticRoleSchema = z.enum([
+    'money',
+    'count',
+    'percent',
+    'timestamp',
+    'status',
+    'category',
+    'label',
+    'identifier',
+    'url',
+    'text'
+]);
+// The sentiment a status value carries. This is MEANING, not color — the renderer maps each to a themed
+// badge variant. A plugin declares a tone only to override or extend what the renderer already infers from a
+// status value (categorical coloring for role:'category' values is automatic — the plugin picks no color).
+export const BadgeToneSchema = z.enum(['neutral', 'success', 'warning', 'danger', 'info']);
+// How a column's value accrues over time. 'cumulative' is a counter that resets each `resetPeriod` (an MTD
+// total) — core keeps a per-row daily reading series and differences it into a daily breakdown. 'incremental'
+// (the default) is a point-in-time/period amount kept verbatim.
+export const AccrualSchema = z.enum(['cumulative', 'incremental']);
+export const ResetPeriodSchema = z.enum(['monthly', 'none']);
+export const ColumnSchema = z.object({
+    key: z.string(),
+    label: z.string().optional(),
+    role: SemanticRoleSchema,
+    currency: z.string().optional(),
+    // value (matched case-insensitively) → sentiment tone, OVERRIDING the renderer's inferred tone for a
+    // role:'status' column. Only needed for values the renderer can't infer (service-specific or non-English
+    // statuses); common ones (active/paid/failed/…) auto-tone with no map. Ignored for other roles.
+    badges: z.record(z.string(), BadgeToneSchema).optional(),
+    accrual: AccrualSchema.optional(),
+    resetPeriod: ResetPeriodSchema.optional(),
+    // Cap a long free-text column to one ellipsized line so it stops absorbing the row's slack and squashing
+    // its neighbours. The full value stays reachable: a hover peek (native title) plus a click-to-open popover
+    // with the selectable, copyable text. Opt-in per column; only meaningful for free-text roles (label/text).
+    truncate: z.boolean().optional(),
+    // Declared but not for display: a row field the table carries for machinery (accumulation key, download
+    // filename, fetchFile payload) rather than for showing in the table body.
+    hidden: z.boolean().optional()
+});
+export const TableDatasetSchema = z.object({
+    id: z.string(),
+    shape: z.literal('table'),
+    columns: z.array(ColumnSchema),
+    rows: z.array(z.record(z.string(), z.unknown())),
+    // Column(s) forming a row's stable identity across fetches. Its presence opts the table into accumulation
+    // (rows merge into a kept union instead of overwriting); an array is a composite key. Absent → latest-only.
+    key: z.union([z.string(), z.array(z.string())]).optional()
+});
+export const RecordDatasetSchema = z.object({
+    id: z.string(),
+    shape: z.literal('record'),
+    fields: z.array(ColumnSchema),
+    value: z.record(z.string(), z.unknown())
+});
+// Two structural primitives; a series is a table with a timestamp column, a stat is a record field.
+export const DatasetSchema = z.discriminatedUnion('shape', [TableDatasetSchema, RecordDatasetSchema]);
+export const rawTable = (id, columns, rows, key) => ({ id, shape: 'table', columns, rows, ...(key ? { key } : {}) });
+export const rawRecord = (id, fields, value) => ({
+    id,
+    shape: 'record',
+    fields,
+    value
+});

package/dist/data/index.d.ts

@@ -0,0 +1,13 @@
+export { rawTable, rawRecord } from './dataset.js';
+export type { SemanticRole, BadgeTone, Accrual, ResetPeriod, Column, TableDataset, RecordDataset, Dataset } from './dataset.js';
+export type { MonthPoint } from './series.js';
+export type { RolesFor } from './roles.js';
+export { table, record, capabilityResult } from './builders.js';
+export type { ViewSpec, RowColumn, FileTableSpec, TableHandle, StatFieldSpec, RecordHandle } from './builders.js';
+export { resolveTableFiles } from './view.js';
+export type { FileSource, TableFiles, StatTone, StatField, View } from './view.js';
+export type { Section, Summary } from './summary.js';
+export { validateCapabilityResult } from './result.js';
+export type { CapabilityResult } from './result.js';
+export { resolveCurrencies } from './currency.js';
+export type { CurrencyCode } from './currency.js';

package/dist/data/index.js

@@ -0,0 +1,11 @@
+// @butinapp/sdk/data — the data-view contract a capability's collect()/build() emits: datasets (table ·
+// record with semantic-role columns), views, summaries, the typed builders (table · record ·
+// capabilityResult), and the currency/role/series shapes they compose. The plugin DESCRIPTOR (definePlugin ·
+// defineCapability · meta/session/auth/transport/config) is the root '@butinapp/sdk' — this is the separate
+// "what a capability returns" tier. Prefer the high-altitude presets ('@butinapp/sdk/presets') over
+// hand-building datasets/views. The internal zod *Schema objects stay off this surface — annotate the TYPES.
+export { rawTable, rawRecord } from './dataset.js';
+export { table, record, capabilityResult } from './builders.js';
+export { resolveTableFiles } from './view.js';
+export { validateCapabilityResult } from './result.js';
+export { resolveCurrencies } from './currency.js';