@butinapp/shapes 0.1.0 → 0.1.2

package/dist/export-bundle.d.ts

@@ -140,6 +140,7 @@ export type ExportBundle = z.infer<typeof ExportBundleSchema>;
 export type ParseBundleResult = {
     ok: true;
     bundle: ExportBundle;
+    warnings: string[];
 } | {
     ok: false;
     errors: string[];

package/dist/export-bundle.js

@@ -52,6 +52,50 @@ export const ExportBundleSchema = z.object({
     // renderer ("the cloud is dumb on purpose").
     overview: z.array(OverviewPluginSchema)
 });
+// The bundle envelope with its two service arrays left unvalidated (validated per-entry so one bad entry
+// doesn't reject the whole blob). Scalar top-level fields still fail hard.
+const ExportBundleEnvelopeSchema = ExportBundleSchema.extend({
+    plugins: z.array(z.unknown()),
+    overview: z.array(z.unknown())
+});
+// Walk a value along a zod issue path, returning what the issue points at (undefined if the path runs off a
+// null/absent branch) — lets us tell an absent field apart from a present-but-wrong one.
+const valueAtPath = (value, path) => path.reduce((acc, key) => (acc == null ? undefined : acc[key]), value);
+const serviceOf = (kind, item) => {
+    if (kind === 'overview') {
+        const o = item;
+        return o?.pluginId ?? o?.pluginName;
+    }
+    return item?.meta?.id;
+};
+// Validate one array's entries independently: keep the ones that parse, and turn each failure into a warning
+// that names the service and flags absent fields (which usually mean the entry predates a schema addition).
+const salvageEntries = (schema, items, kind) => {
+    const kept = [];
+    const warnings = [];
+    items.forEach((item, index) => {
+        const parsed = schema.safeParse(item);
+        if (parsed.success) {
+            kept.push(parsed.data);
+            return;
+        }
+        const service = serviceOf(kind, item);
+        const label = `${kind}[${index}]${service ? ` (service '${service}')` : ''}`;
+        let anyAbsent = false;
+        const detail = parsed.error.issues
+            .map((i) => {
+            const absent = valueAtPath(item, i.path) === undefined;
+            anyAbsent ||= absent;
+            return `${i.path.join('.') || '(value)'}: ${i.message}`;
+        })
+            .join('; ');
+        const hint = anyAbsent
+            ? " — a field is absent (this service's cached data predates it); refresh it and re-export"
+            : '';
+        warnings.push(`dropped ${label}: ${detail}${hint}`);
+    });
+    return { kept, warnings };
+};
 export const parseExportBundle = (raw) => {
     const version = raw?.formatVersion;
     if (typeof version === 'number' && version > EXPORT_BUNDLE_FORMAT_VERSION) {
@@ -60,9 +104,15 @@ export const parseExportBundle = (raw) => {
             errors: [`bundle formatVersion ${version} is newer than this viewer supports (${EXPORT_BUNDLE_FORMAT_VERSION})`]
         };
     }
-    const parsed = ExportBundleSchema.safeParse(raw);
-    if (!parsed.success) {
-        return { ok: false, errors: parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`) };
+    const envelope = ExportBundleEnvelopeSchema.safeParse(raw);
+    if (!envelope.success) {
+        return { ok: false, errors: envelope.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`) };
     }
-    return { ok: true, bundle: parsed.data };
+    const plugins = salvageEntries(ExportPluginSchema, envelope.data.plugins, 'plugins');
+    const overview = salvageEntries(OverviewPluginSchema, envelope.data.overview, 'overview');
+    return {
+        ok: true,
+        bundle: { ...envelope.data, plugins: plugins.kept, overview: overview.kept },
+        warnings: [...plugins.warnings, ...overview.warnings]
+    };
 };

package/dist/index.d.ts

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

package/dist/index.js

@@ -7,3 +7,4 @@ export * from './overview.js';
 export * from './ledger.js';
 export * from './manifest.js';
 export * from './daily.js';
+export * from './people.js';

package/dist/people.d.ts

@@ -0,0 +1,41 @@
+import { type CapabilityResult, type TableDataset } from '@butinapp/sdk/data';
+export type ServiceMembers = {
+    pluginId: string;
+    serviceName: string;
+    asOf?: string;
+    rows: Record<string, unknown>[];
+};
+export type PersonRow = {
+    personId: string;
+    name: string | null;
+    email: string | null;
+    services: number;
+};
+export type AccessRow = {
+    personId: string;
+    service: string;
+    role: string | null;
+    asOf: string | null;
+};
+export type MergedPeople = {
+    people: PersonRow[];
+    access: AccessRow[];
+};
+export declare const mergePeople: (inputs: ServiceMembers[]) => MergedPeople;
+export declare const membersDataset: (result: CapabilityResult | null) => TableDataset | null;
+export type ServiceCapResult = {
+    id: string;
+    result: CapabilityResult | null;
+    asOf?: string;
+};
+export declare const serviceMembersFrom: (source: {
+    pluginId: string;
+    serviceName: string;
+    caps: ServiceCapResult[];
+}) => ServiceMembers | null;
+export declare const buildPeopleResult: (merged: MergedPeople) => CapabilityResult;
+export declare const buildPeopleData: (inputs: ServiceMembers[]) => {
+    result: CapabilityResult;
+    people: number;
+    services: number;
+} | null;

package/dist/people.js

@@ -0,0 +1,110 @@
+import { capabilityResult, table } from '@butinapp/sdk/data';
+const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
+// The most common non-null name a person appears under; first-seen wins a tie so the pick is stable.
+const majorityName = (names) => {
+    let best = null;
+    let bestCount = 0;
+    const counts = new Map();
+    for (const name of names) {
+        const count = (counts.get(name) ?? 0) + 1;
+        counts.set(name, count);
+        if (count > bestCount) {
+            best = name;
+            bestCount = count;
+        }
+    }
+    return best;
+};
+// Merge every service's member roster into people. Rows sharing a case-insensitive email are one person;
+// a row without an email stays its own entry (keyed by service + row id) so name-only rows never falsely
+// merge. Access rows carry the raw per-service role plus the report's fetch time.
+export const mergePeople = (inputs) => {
+    const byId = new Map();
+    for (const svc of inputs) {
+        svc.rows.forEach((row, index) => {
+            const email = str(row.email);
+            const name = str(row.name);
+            // A row with neither a name nor an email identifies nobody (a service/placeholder account some rosters
+            // carry) — drop it rather than showing a blank "— / —" person in the audit.
+            if (!email && !name) {
+                return;
+            }
+            const rowId = str(row.id) ?? String(index);
+            const personId = email ? email.trim().toLowerCase() : `${svc.pluginId}:${rowId}`;
+            let acc = byId.get(personId);
+            if (!acc) {
+                acc = { personId, email, names: [], pluginIds: new Set(), access: [] };
+                byId.set(personId, acc);
+            }
+            if (name) {
+                acc.names.push(name);
+            }
+            acc.pluginIds.add(svc.pluginId);
+            acc.access.push({ personId, service: svc.serviceName, role: str(row.role), asOf: svc.asOf ?? null });
+        });
+    }
+    const accs = [...byId.values()];
+    const people = accs.map((a) => ({
+        personId: a.personId,
+        name: majorityName(a.names),
+        email: a.email,
+        services: a.pluginIds.size
+    }));
+    const label = (p) => p.name ?? p.email ?? p.personId;
+    people.sort((x, y) => y.services - x.services || label(x).localeCompare(label(y)));
+    const access = accs.flatMap((a) => a.access);
+    access.sort((x, y) => x.service.localeCompare(y.service));
+    return { people, access };
+};
+// The standard roster the members.result preset emits: a table with id 'members' that declares an email
+// column. The email-column requirement excludes members-shaped usage breakdowns that reuse the id with
+// different fields (per-member spend tables carry no email).
+export const membersDataset = (result) => result?.datasets.find((d) => d.shape === 'table' && d.id === 'members' && d.columns.some((c) => c.key === 'email')) ?? null;
+// Pick a service's roster from its capability results: prefer the `members` capability, else the first result
+// carrying a members dataset. Returns null when the service reports no roster. The winning capability's fetch
+// time becomes the contribution's `asOf`.
+export const serviceMembersFrom = (source) => {
+    const ordered = [...source.caps].sort((a, b) => Number(b.id === 'members') - Number(a.id === 'members'));
+    for (const cap of ordered) {
+        const ds = membersDataset(cap.result);
+        if (ds) {
+            return { pluginId: source.pluginId, serviceName: source.serviceName, asOf: cap.asOf, rows: ds.rows };
+        }
+    }
+    return null;
+};
+// Shape the merged rollup into the one renderable result the People page draws: a people table whose rows
+// expand into that person's per-service access, joined on the hidden personId.
+export const buildPeopleResult = (merged) => {
+    const people = table({
+        id: 'people',
+        columns: [
+            { key: 'name', role: 'label', label: 'Name' },
+            { key: 'email', role: 'identifier', label: 'Email' },
+            { key: 'services', role: 'count', label: 'Services' },
+            { key: 'personId', role: 'identifier', hidden: true }
+        ],
+        rows: merged.people,
+        key: 'personId'
+    });
+    const access = table({
+        id: 'access',
+        columns: [
+            { key: 'service', role: 'label', label: 'Service' },
+            { key: 'role', role: 'category', label: 'Role' },
+            { key: 'asOf', role: 'timestamp', label: 'As of' },
+            { key: 'personId', role: 'identifier', hidden: true }
+        ],
+        rows: merged.access
+    });
+    return capabilityResult({ sections: [people.table({ title: 'People', detail: { rows: access, on: 'personId' } })] });
+};
+// Assemble the People payload from every service's roster contributions: merge, shape, and count. Returns null
+// when no service reports a roster.
+export const buildPeopleData = (inputs) => {
+    if (inputs.length === 0) {
+        return null;
+    }
+    const merged = mergePeople(inputs);
+    return { result: buildPeopleResult(merged), people: merged.people.length, services: inputs.length };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@butinapp/shapes",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Butin's host-layer data shapes built on the @butinapp/sdk data-view contract: the cross-service Overview input, the persisted ledger, the presentation manifest, and the portable export-bundle wire format.",
   "homepage": "https://butin.app",
   "bugs": "https://github.com/butinapp/butin/issues",
@@ -37,7 +37,7 @@
     "lodash-es": "^4.18.1",
     "luxon": "^3.7.2",
     "zod": "^4.3.6",
-    "@butinapp/sdk": "0.1.0"
+    "@butinapp/sdk": "0.1.2"
   },
   "devDependencies": {
     "vitest": "^4.1.7"