@butinapp/sdk 0.1.0

package/dist/integrations/stripe.d.ts

@@ -0,0 +1,45 @@
+import type { ButinClient } from '../plugin/transport.js';
+export declare const STRIPE_PORTAL_VERSION = "2025-06-30.basil";
+export interface StripePortalSession {
+    bps: string;
+    ek: string;
+    account: string;
+}
+export declare const extractStripePortalTokens: (html: string) => StripePortalSession;
+export declare const openStripePortal: (client: ButinClient, portalUrl: string) => Promise<StripePortalSession>;
+export declare const openStripePortalViaRedirect: (client: ButinClient, redirectUrl: string) => Promise<StripePortalSession>;
+export declare const fetchStripePortalResource: <T>(client: ButinClient, session: StripePortalSession, resource: string, params?: Record<string, number>) => Promise<T>;
+export interface RawStripeLine {
+    amount?: number;
+    description?: string;
+    short_description?: string;
+    price_details?: {
+        product?: {
+            name?: string;
+        };
+    };
+}
+export interface RawStripeInvoice {
+    id?: string;
+    number?: string;
+    status?: string;
+    total?: number;
+    amount_due?: number;
+    amount_paid?: number;
+    currency?: string;
+    effective_at?: number;
+    finalized_at?: number;
+    created?: number;
+    due_date?: number;
+    hosted_invoice_url?: string;
+    invoice_pdf?: string;
+    lines?: {
+        data?: RawStripeLine[];
+    };
+}
+export interface RawStripeInvoiceList {
+    data?: RawStripeInvoice[];
+    has_more?: boolean;
+}
+export declare const stripePdfFileUrlEndpoint: (hosted?: string | null) => string | null;
+export declare const fetchStripeHostedInvoicePdf: (client: ButinClient, hosted?: string | null) => Promise<Uint8Array>;

package/dist/integrations/stripe.js

@@ -0,0 +1,102 @@
+// Stripe billing mechanics shared by every plugin that proxies billing to Stripe. Two reusable shapes live
+// here: the hosted billing-portal walk (services with no invoice API of their own — depot, novu, posthog) and
+// the hosted-invoice → PDF download (services that expose only the Stripe-hosted invoice page — screenshotapi).
+// Pure relative to a ButinClient: each helper takes the authed client and does the cross-origin Stripe calls,
+// so a plugin only supplies how it ACQUIRES the one-time portal URL (a 302 from its own endpoint, a JSON
+// field, or a value already in hand) and how it normalizes the result.
+// ── hosted billing portal ────────────────────────────────────────────────────────────────
+// The Stripe API version the hosted billing portal pins its ephemeral-key calls to. Stripe shifts response
+// shapes across versions, so the portal-session calls send the same one the portal page does.
+export const STRIPE_PORTAL_VERSION = '2025-06-30.basil';
+const STRIPE_BILLING_ORIGIN = 'https://billing.stripe.com';
+// Stripe's hosted portal page embeds the session id, an ephemeral key, and the account id in its bootstrap
+// markup. The three tokens carry distinctive, stable prefixes, so a prefix regex survives surrounding-markup
+// drift. Exported so the scrape is fixture-tested.
+export const extractStripePortalTokens = (html) => {
+    const ek = html.match(/ek_live_[A-Za-z0-9_]+/)?.[0];
+    const bps = html.match(/bps_[A-Za-z0-9]+/)?.[0];
+    const account = html.match(/acct_[A-Za-z0-9]+/)?.[0];
+    if (!ek || !bps || !account) {
+        throw new Error('Stripe billing-portal session not found on the portal page (session expired?).');
+    }
+    return { bps, ek, account };
+};
+// Fetch a one-time Stripe portal-session page and scrape its tokens. `portalUrl` is the
+// `billing.stripe.com/p/session/…` URL the plugin already holds (e.g. a JSON field). The page rides on
+// Stripe's own ephemeral-key auth, so this hop carries neither the service's session cookie nor any Bearer.
+export const openStripePortal = async (client, portalUrl) => {
+    if (!portalUrl.includes('/p/session/')) {
+        throw new Error('Stripe billing-portal URL is not a portal session (session expired?).');
+    }
+    const page = await client.request({
+        url: portalUrl,
+        responseType: 'text',
+        sendAuth: false,
+        sendCookie: false,
+        headers: { Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8' }
+    });
+    return extractStripePortalTokens(page.data);
+};
+// Open a Stripe portal session reached through a service endpoint that 302s to it (the common shape — the
+// service mints the session server-side with its own secret key and hands back only the client redirect).
+// The redirect hop keeps the service's session (cookie + any Bearer) to be authorized; the portal-page hop
+// drops it. `maxRedirects: 0` reads the Location instead of chasing it cross-origin.
+export const openStripePortalViaRedirect = async (client, redirectUrl) => {
+    const redirect = await client.request({ url: redirectUrl, maxRedirects: 0 });
+    const location = redirect.headers.location;
+    if (!location) {
+        throw new Error('Stripe billing-portal endpoint did not redirect to a portal session (session expired?).');
+    }
+    return openStripePortal(client, location);
+};
+// GET a portal-session resource (`invoices`, `subscriptions`, …), authorized by the ephemeral key — the same
+// captcha-free calls the portal UI makes (hCaptcha only gates payment-method mutations). Cross-origin to
+// Stripe, so it carries the Bearer/account/version headers and drops the service's session cookie.
+export const fetchStripePortalResource = async (client, session, resource, params = {}) => {
+    const query = new URLSearchParams(Object.entries(params).map(([k, v]) => [k, String(v)])).toString();
+    const res = await client.request({
+        url: `${STRIPE_BILLING_ORIGIN}/v1/billing_portal/sessions/${session.bps}/${resource}${query ? `?${query}` : ''}`,
+        sendAuth: false,
+        sendCookie: false,
+        headers: {
+            Accept: 'application/json',
+            Authorization: `Bearer ${session.ek}`,
+            'stripe-account': session.account,
+            'stripe-version': STRIPE_PORTAL_VERSION,
+            Origin: STRIPE_BILLING_ORIGIN,
+            Referer: `${STRIPE_BILLING_ORIGIN}/`
+        }
+    });
+    return res.data;
+};
+// ── hosted-invoice PDF download ────────────────────────────────────────────────────────────
+// A Stripe hosted-invoice URL (https://invoice.stripe.com/i/<acct>/<liveId>?s=ap) serves an SPA shell, NOT a
+// PDF. The real PDF is two hops away: GET invoicedata.stripe.com/invoice_pdf_file_url/<acct>/<liveId> for a
+// JSON `{ file_url }` (a short-lived signed S3 link), then GET that. This derives the first-hop endpoint from
+// the hosted URL (same acct + liveId, no query). Exported so the parse is fixture-tested.
+const STRIPE_HOSTED_INVOICE_RE = /invoice\.stripe\.com\/i\/(acct_[^/]+)\/(live_[^/?]+)/;
+export const stripePdfFileUrlEndpoint = (hosted) => {
+    const m = hosted ? STRIPE_HOSTED_INVOICE_RE.exec(hosted) : null;
+    return m ? `https://invoicedata.stripe.com/invoice_pdf_file_url/${m[1]}/${m[2]}` : null;
+};
+// Download the PDF behind a Stripe hosted-invoice URL via the two-hop file-url handoff — a drop-in `fetchFile`
+// body for a `files` table whose rows carry the hosted URL. Both hops are public (the S3 link is signed), so
+// neither carries the service's session cookie or Bearer.
+export const fetchStripeHostedInvoicePdf = async (client, hosted) => {
+    const endpoint = stripePdfFileUrlEndpoint(hosted);
+    if (!endpoint) {
+        throw new Error('Stripe hosted-invoice URL is not in the expected invoice.stripe.com/i/<acct>/<live> shape.');
+    }
+    const meta = await client.request({ url: endpoint, sendAuth: false, sendCookie: false });
+    const fileUrl = meta.data?.file_url;
+    if (!fileUrl) {
+        throw new Error('Stripe invoice_pdf_file_url returned no PDF link (the hosted invoice link may have expired).');
+    }
+    const pdf = await client.request({
+        url: fileUrl,
+        responseType: 'arraybuffer',
+        sendAuth: false,
+        sendCookie: false
+    });
+    return new Uint8Array(pdf.data);
+};

package/dist/libs.d.ts

@@ -0,0 +1,2 @@
+export * from 'lodash-es';
+export { DateTime, Duration, Interval } from 'luxon';

package/dist/libs.js

@@ -0,0 +1,6 @@
+// Re-export of the vendored third-party utility libs. A plugin depends ONLY on `@butinapp/sdk`, so it reaches
+// luxon + lodash through here instead of declaring (and version-pinning) those deps itself — the SDK owns them.
+// Kept on its own subpath, NOT in `/main`, so lodash's broad named surface can't collide with the SDK's own
+// exports. Tree-shaken at the consumer's bundle, so re-exporting the whole toolkit costs nothing unused.
+export * from 'lodash-es';
+export { DateTime, Duration, Interval } from 'luxon';

package/dist/plugin/auth.d.ts

@@ -0,0 +1,49 @@
+import type { ButinClient } from './transport.js';
+export type CredentialStore = {
+    get: (field?: string) => string | undefined;
+    set: (field: string, value: string) => void;
+};
+export type AuthContext = {
+    client: ButinClient;
+    creds: CredentialStore;
+    config: Record<string, unknown>;
+};
+export type AuthAttachment = {
+    headers?: Record<string, string>;
+    cookie?: string;
+};
+export type AuthResolveHook = (ctx: AuthContext) => Promise<AuthAttachment>;
+type AuthBase = {
+    clearOnStatuses?: number[];
+};
+export type AuthStrategy = (AuthBase & {
+    kind: 'cookie';
+}) | (AuthBase & {
+    kind: 'bearer-token';
+    tokenField?: string;
+}) | (AuthBase & {
+    kind: 'external';
+}) | (AuthBase & {
+    kind: 'api-key';
+    resolve?: AuthResolveHook;
+}) | (AuthBase & {
+    kind: 'cookie-csrf';
+    resolve?: AuthResolveHook;
+}) | (AuthBase & {
+    kind: 'minted-jwt';
+    resolve: AuthResolveHook;
+}) | (AuthBase & {
+    kind: 'rotating-refresh';
+    resolve: AuthResolveHook;
+}) | (AuthBase & {
+    kind: 'spa-bearer';
+    bootUrl: string;
+    authCaptureUrlPatterns: string[];
+    sessionStorageKeyPrefix?: string;
+    bootTimeoutMs?: number;
+});
+export type AuthKind = AuthStrategy['kind'];
+export type SpaBearerAuth = Extract<AuthStrategy, {
+    kind: 'spa-bearer';
+}>;
+export {};

package/dist/plugin/auth.js

@@ -0,0 +1 @@
+export {};

package/dist/plugin/browser.d.ts

@@ -0,0 +1,26 @@
+export type BrowserFetchInit = {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+};
+export type BrowserContext = {
+    html: () => Promise<string>;
+    fetchText: (url: string, init?: BrowserFetchInit) => Promise<{
+        status: number;
+        text: string;
+    }>;
+    fetchBytes: (url: string, init?: BrowserFetchInit) => Promise<{
+        status: number;
+        bytes: Uint8Array;
+    }>;
+};
+export type BrowserPage = BrowserContext & {
+    navigate: (url: string) => Promise<void>;
+    loadFrame: (url: string) => Promise<BrowserContext>;
+    download: (url: string, init?: {
+        referer?: string;
+    }) => Promise<Uint8Array>;
+};
+export type BrowserSession = {
+    open: <T>(url: string, use: (page: BrowserPage) => Promise<T>) => Promise<T>;
+};

package/dist/plugin/browser.js

@@ -0,0 +1,8 @@
+// A live, authenticated BROWSER session a collector can drive — for services whose session can't be
+// replayed with a bare headless request. Some legacy backends keep a short-lived, server-side session that
+// a real browser tab holds open but a one-shot `net.request` finds already torn down (it auto-logs-out).
+// `BrowserSession.open` navigates an OFFSCREEN window — on the plugin's captured partition — to a URL (a
+// real navigation: carries Sec-Fetch-*, runs the page's JS, keeps that session warm), hands the collector a
+// `BrowserPage`, then tears the window down. Electron-backed in core; absent in embeds and off-Electron tests
+// (so a collector that needs it should guard `if (!ctx.browser) …`).
+export {};

package/dist/plugin/capability.d.ts

@@ -0,0 +1,54 @@
+import type { CapabilityResult } from '../data/result.js';
+import { type SampleConfig, type SampleGenerator } from '../testing/synthetic.js';
+import type { CredentialStore } from './auth.js';
+import type { BrowserSession } from './browser.js';
+import type { DocumentBytes } from './documents.js';
+import type { ButinClient } from './transport.js';
+export type CollectContext<TConfig = Record<string, unknown>> = {
+    client: ButinClient;
+    clientFor: (backendKey: string) => ButinClient;
+    creds: CredentialStore;
+    config: TConfig;
+    browser?: BrowserSession;
+    since?: string;
+    log: (message: string, extra?: Record<string, unknown>) => void;
+};
+export type IncrementalSpec = {
+    id: string;
+    timestamp: string;
+    window?: {
+        days: number;
+    };
+};
+export type IncrementalCapability = IncrementalSpec & {
+    fetch: (ctx: CollectContext) => Promise<Record<string, unknown>[]>;
+    build: (rows: Record<string, unknown>[]) => CapabilityResult;
+};
+export type Capability<TConfig = Record<string, unknown>> = {
+    id: string;
+    label: string;
+    collect: (ctx: CollectContext<TConfig>) => Promise<CapabilityResult>;
+    incremental?: IncrementalCapability;
+    sample?: (opts?: {
+        config?: SampleConfig;
+        seed?: string;
+    }) => CapabilityResult;
+    fetchFile?: (ctx: CollectContext<TConfig>, row: Record<string, unknown>) => Promise<DocumentBytes>;
+};
+type RowOf<TRaw> = TRaw extends readonly (infer R)[] ? R : never;
+export declare const defineCapability: <TRaw, TConfig = Record<string, unknown>>(spec: {
+    id: string;
+    label: string;
+    fetch: (ctx: CollectContext<TConfig>) => Promise<TRaw>;
+    build: (raw: TRaw) => CapabilityResult;
+    sample: SampleGenerator<TRaw>;
+    fetchFile?: (ctx: CollectContext<TConfig>, row: Record<string, unknown>) => Promise<DocumentBytes>;
+    incremental?: {
+        id: keyof RowOf<TRaw> & string;
+        timestamp: keyof RowOf<TRaw> & string;
+        window?: {
+            days: number;
+        };
+    };
+}) => Capability<TConfig>;
+export {};

package/dist/plugin/capability.js

@@ -0,0 +1,19 @@
+import { createSampleGen, resolveSampleConfig } from '../testing/synthetic.js';
+export const defineCapability = (spec) => ({
+    id: spec.id,
+    label: spec.label,
+    collect: async (ctx) => spec.build(await spec.fetch(ctx)),
+    sample: (opts) => spec.build(spec.sample(createSampleGen(opts?.seed ?? spec.id), resolveSampleConfig(opts?.config))),
+    ...(spec.fetchFile ? { fetchFile: spec.fetchFile } : {}),
+    ...(spec.incremental
+        ? {
+            incremental: {
+                id: spec.incremental.id,
+                timestamp: spec.incremental.timestamp,
+                ...(spec.incremental.window ? { window: spec.incremental.window } : {}),
+                fetch: spec.fetch,
+                build: spec.build
+            }
+        }
+        : {})
+});

package/dist/plugin/config.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import type { CollectContext } from './capability.js';
+export type ConfigFieldKind = 'text' | 'secret' | 'select' | 'combobox';
+export interface ConfigOption {
+    value: string;
+    label: string;
+    description?: string;
+    recommended?: boolean;
+}
+export interface ConfigFieldCondition {
+    field: string;
+    equals: string;
+}
+export interface ConfigField {
+    key: string;
+    label: string;
+    kind: ConfigFieldKind;
+    required?: boolean;
+    placeholder?: string;
+    help?: string;
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    showWhen?: ConfigFieldCondition;
+    loadOptions?: (ctx: CollectContext) => Promise<ConfigOption[]>;
+}
+export interface PluginConfigSchema<TValues = Record<string, unknown>> {
+    fields: ConfigField[];
+    readonly __values?: TValues;
+}
+type FieldShape = {
+    readonly key: string;
+    readonly required?: boolean;
+    readonly options?: readonly {
+        readonly value: string;
+    }[];
+};
+type FieldValue<F extends FieldShape> = F extends {
+    readonly options: readonly {
+        readonly value: infer V;
+    }[];
+} ? V : string;
+type RequiredKey<F extends readonly FieldShape[]> = Extract<F[number], {
+    readonly required: true;
+}>['key'];
+export type ConfigValues<F extends readonly FieldShape[]> = {
+    [K in F[number] as K['key'] extends RequiredKey<F> ? K['key'] : never]: FieldValue<K>;
+} & {
+    [K in F[number] as K['key'] extends RequiredKey<F> ? never : K['key']]?: FieldValue<K>;
+};
+export declare const configValuesSchema: (fields: readonly ConfigField[]) => z.ZodType<Record<string, unknown>>;
+type ConfigFieldInput = Omit<ConfigField, 'options'> & {
+    readonly options?: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+};
+export declare const defineConfigSchema: <const F extends readonly ConfigFieldInput[]>(fields: F) => PluginConfigSchema<ConfigValues<F>>;
+export type ConfigOf<S> = S extends PluginConfigSchema<infer V> ? V : never;
+export {};

package/dist/plugin/config.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+// Build a zod validator for stored config values from the field list. Used by core to validate (best-effort)
+// what it reads off disk: a `select` value must be one of its options, every value must be a string. Kept
+// LENIENT on presence (all-optional) — enforcing `required` is the form's job at save time, not the
+// collector's at read time, so an unconfigured plugin doesn't spam validation errors.
+export const configValuesSchema = (fields) => {
+    const shape = {};
+    for (const field of fields) {
+        const values = field.options?.map((o) => o.value);
+        const base = values && values.length > 0 ? z.enum(values) : z.string();
+        shape[field.key] = base.optional();
+    }
+    return z.object(shape).passthrough();
+};
+// THE recommended way to declare typed settings: pass the fields once and get back a config schema that carries
+// the derived value type. `definePlugin` infers its `TConfig` from it (so `ctx.config` is typed with no generic
+// and no per-collect annotation), and the runtime `fields` it produces is what the settings form renders.
+// Name the value type with `ConfigOf`:
+//   const myConfig = defineConfigSchema([{ key: 'region', label: 'Region', kind: 'text', required: true }])
+//   type MyConfig = ConfigOf<typeof myConfig>          // { region: string }
+//   export const myPlugin = definePlugin({ config: myConfig, capabilities: [...] })  // ctx.config: MyConfig
+export const defineConfigSchema = (fields) => ({ fields: fields });

package/dist/plugin/documents.d.ts

@@ -0,0 +1,5 @@
+export type DocumentBytes = Uint8Array | {
+    data: Uint8Array;
+    filename?: string;
+    mime?: string;
+};

package/dist/plugin/documents.js

@@ -0,0 +1 @@
+export {};

package/dist/plugin/meta.d.ts

@@ -0,0 +1,21 @@
+export type PluginCategory = 'finance' | 'cloud' | 'ai' | 'devtools' | 'productivity' | 'rental' | 'other';
+export type TroubleshootingCause = 'session-not-captured' | 'session-expired' | 'config-missing' | 'config-invalid' | 'verification-required' | 'permission' | 'network' | 'data-invalid' | 'unknown';
+export type TroubleshootingAction = 'retry' | 'reconnect' | 'edit-settings' | 'open-dashboard' | 'open-docs';
+export type Troubleshooting = Partial<Record<TroubleshootingCause, {
+    hint: string;
+    docUrl?: string;
+}>>;
+export type PluginMeta = {
+    id: string;
+    name: string;
+    vendor?: string;
+    category?: PluginCategory;
+    description?: string;
+    version?: string;
+    color?: string;
+    icon?: string;
+    homepage?: string;
+    dashboardUrl?: string;
+    messages?: Record<string, Record<string, string>>;
+    troubleshooting?: Troubleshooting;
+};

package/dist/plugin/meta.js

@@ -0,0 +1 @@
+export {};

package/dist/plugin/plugin.d.ts

@@ -0,0 +1,26 @@
+import type { CurrencyCode } from '../data/currency.js';
+import type { AuthStrategy } from './auth.js';
+import type { Capability, CollectContext } from './capability.js';
+import type { PluginConfigSchema } from './config.js';
+import type { PluginMeta } from './meta.js';
+import type { SessionSource } from './session.js';
+import type { ButinClient, TransportConfig } from './transport.js';
+export type ButinPlugin<TConfig = Record<string, unknown>> = {
+    meta: PluginMeta;
+    reportingCurrency: CurrencyCode;
+    session?: SessionSource;
+    auth: AuthStrategy;
+    transport?: TransportConfig;
+    backends?: Record<string, PluginBackend>;
+    config?: PluginConfigSchema<TConfig>;
+    capabilities: Capability<TConfig>[];
+    probe: (ctx: CollectContext<TConfig>) => Promise<void>;
+};
+export type PluginBackend = {
+    transport?: TransportConfig;
+    auth: AuthStrategy;
+    session?: SessionSource;
+    label?: string;
+    probe?: (client: ButinClient) => Promise<void>;
+};
+export declare const definePlugin: <TConfig = Record<string, unknown>>(plugin: ButinPlugin<TConfig>) => ButinPlugin<TConfig>;

package/dist/plugin/plugin.js

@@ -0,0 +1 @@
+export const definePlugin = (plugin) => plugin;

package/dist/plugin/session.d.ts

@@ -0,0 +1,33 @@
+export type LocalStorageToken = {
+    key?: string;
+    keyIncludes?: string[];
+    jsonPath?: string;
+    storeAs: string;
+};
+export type ManualField = {
+    label: string;
+    key: string;
+    placeholder?: string;
+    required?: boolean;
+};
+export type SessionSource = {
+    loginUrl: string;
+    partition?: string;
+    dashboardMarkers: string[];
+    cookieDomains: string[];
+    requiredCookie?: string;
+    localStorageTokens?: LocalStorageToken[];
+    clearCookiesBeforeCapture?: string[];
+    persistCookies?: boolean;
+    manualFields?: ManualField[];
+    manualCaptureOnly?: boolean;
+    captureFromUrl?: Array<{
+        pattern: string;
+        storeAs: string;
+    }>;
+    captureFromHeader?: Array<{
+        header: string;
+        storeAs: string;
+        on?: 'request' | 'response';
+    }>;
+};

package/dist/plugin/session.js

@@ -0,0 +1,5 @@
+// Magic Login — declarative capture config. The core opens `loginUrl` in a persistent partition,
+// you log in by hand (MFA, SSO, magic link — anything), and once the page settles on an
+// authenticated marker the core grabs the session and stores it encrypted. The capture is declarative —
+// every plugin describes it as data, not per-service code.
+export {};

package/dist/plugin/transport.d.ts

@@ -0,0 +1,42 @@
+export type TransportEngine = 'node' | 'electron';
+export type DownloadTransport = {
+    referer?: string;
+    concurrency?: number;
+};
+export type TransportConfig = {
+    engine?: TransportEngine;
+    requiresBrowserEngine?: boolean;
+    baseUrl?: string;
+    userAgent?: string;
+    defaultHeaders?: Record<string, string>;
+    sendCookie?: boolean;
+    nativeBrowserHeaders?: boolean;
+    download?: DownloadTransport;
+};
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type RequestOptions = {
+    url: string;
+    method?: HttpMethod;
+    headers?: Record<string, string>;
+    body?: unknown;
+    responseType?: 'json' | 'text' | 'arraybuffer';
+    referer?: string;
+    sendAuth?: boolean;
+    sendCookie?: boolean;
+    maxRedirects?: number;
+    cache?: boolean;
+    pace?: boolean;
+    timeout?: number;
+};
+export type ButinResponse<T = unknown> = {
+    status: number;
+    headers: Record<string, string>;
+    data: T;
+};
+export type ButinClient = {
+    request: <T = unknown>(opts: RequestOptions) => Promise<ButinResponse<T>>;
+    get: <T = unknown>(url: string, headers?: Record<string, string>) => Promise<T>;
+    post: <T = unknown>(url: string, body?: unknown, headers?: Record<string, string>) => Promise<T>;
+    graphql: <T = unknown>(url: string, query: string, variables?: Record<string, unknown>) => Promise<T>;
+    getText: (url: string, headers?: Record<string, string>) => Promise<string>;
+};

package/dist/plugin/transport.js

@@ -0,0 +1 @@
+export {};

package/dist/presets/apikeys.d.ts

@@ -0,0 +1,13 @@
+import type { CapabilityResult } from '../data/result.js';
+export interface ApiKeyInput {
+    id: string;
+    name?: string;
+    masked?: string;
+    createdAt?: string;
+    lastUsedAt?: string;
+    revoked?: boolean;
+}
+export interface ApiKeysInput {
+    keys: ApiKeyInput[];
+}
+export declare const apiKeysResult: (input: ApiKeysInput) => CapabilityResult;

package/dist/presets/apikeys.js

@@ -0,0 +1,24 @@
+import { capabilityResult, table } from '../data/builders.js';
+const day = (ts) => (ts ? ts.slice(0, 10) : null);
+// The apiKeys preset: a single inventory table (name / key / created / last used / status). No summary —
+// a key count isn't a meaningful cross-service rollup.
+export const apiKeysResult = (input) => {
+    const keys = table({
+        id: 'keys',
+        columns: [
+            { key: 'name', role: 'label', label: 'Name' },
+            { key: 'masked', role: 'label', label: 'Key' },
+            { key: 'createdAt', role: 'timestamp', label: 'Created' },
+            { key: 'lastUsedAt', role: 'timestamp', label: 'Last used' },
+            { key: 'status', role: 'status', label: 'Status' }
+        ],
+        rows: input.keys.map((k) => ({
+            name: k.name ?? null,
+            masked: k.masked ?? null,
+            createdAt: day(k.createdAt),
+            lastUsedAt: day(k.lastUsedAt),
+            status: k.revoked ? 'revoked' : 'active'
+        }))
+    });
+    return capabilityResult({ sections: [keys.table({ title: 'API keys' })] });
+};

package/dist/presets/billing.d.ts

@@ -0,0 +1,56 @@
+import type { BadgeTone, SemanticRole } from '../data/dataset.js';
+import type { CapabilityResult } from '../data/result.js';
+import type { MonthPoint } from '../data/series.js';
+import { type TableFiles } from '../data/view.js';
+import { type CreditsInput, type PaymentMethodInput } from './blocks.js';
+import { type MtdBasis } from './mtd-basis.js';
+export interface BillingInvoiceInput {
+    id?: string;
+    date?: string;
+    status: string;
+    amount: number;
+    hostedUrl?: string | null;
+    pdfUrl?: string | null;
+}
+export interface BillingInput {
+    currentMtd: number | null;
+    baseFee?: number | null;
+    meteredMtd?: number | null;
+    mtdBasis?: MtdBasis;
+    plan?: string;
+    currency?: string;
+    invoices: BillingInvoiceInput[];
+    statusTones?: Record<string, BadgeTone>;
+    credits?: CreditsInput;
+    paymentMethod?: PaymentMethodInput;
+    invoiceDownload?: TableFiles | true;
+}
+export declare const monthlySpend: (invoices: BillingInvoiceInput[]) => MonthPoint[];
+export interface BillingStat {
+    key: string;
+    label: string;
+    role: SemanticRole;
+    value: unknown;
+    currency?: string;
+    badges?: Record<string, BadgeTone>;
+    max?: number;
+    unit?: string;
+    caption?: string;
+    tone?: 'positive' | 'negative' | 'muted';
+}
+export interface BillingSummaryInput {
+    currentMtd: number | null;
+    currentMtdLabel?: string;
+    currentMtdCaption?: string;
+    baseFee?: number | null;
+    meteredMtd?: number | null;
+    mtdBasis?: MtdBasis;
+    currency?: string;
+    plan?: string;
+    invoices: BillingInvoiceInput[];
+    stats?: BillingStat[];
+    monthlyTitle?: string;
+    showDelta?: boolean;
+}
+export declare const billingSummaryResult: (input: BillingSummaryInput) => CapabilityResult;
+export declare const billingResult: (input: BillingInput) => CapabilityResult;