@hub-kit/core 0.3.0

package/README.md

@@ -0,0 +1,125 @@
+# Hub Kit
+
+One package that powers every Hub project. Pages, components and the theme system live
+here; each project supplies its data adapters, its dictionary, and one theme file.
+
+Rules for working in this repo: see `CLAUDE.md`. The full plan: see `docs/plan.md`.
+
+## Install in a project
+
+```bash
+npm install @hub-kit/core
+```
+
+In the project's `styles.css`:
+
+```css
+@import "@hub-kit/core/themes/default.css";
+@source "../node_modules/@hub-kit/core/dist";
+```
+
+## Use a component
+
+```tsx
+import { QueueKpiRow } from "@hub-kit/core/invoice-queue";
+import { NotificationBell, AlertList } from "@hub-kit/core/notifications";
+import { Button, Table } from "@hub-kit/core/ui";
+```
+
+## Use a page
+
+A page needs one adapter the project implements, and takes optional labels for
+translation. English works out of the box.
+
+```tsx
+import { ProcessingLogPage } from "@hub-kit/core/pages";
+import { processingLogAdapter } from "../adapters/processing-log";
+
+export function ActivityLog() {
+  return <ProcessingLogPage adapter={processingLogAdapter} />;
+}
+```
+
+The adapter interfaces are in `hub-kit/adapters`. Query hooks return a plain
+`QueryResult` shape, so the project implements them with React Query and Supabase;
+mutations are plain functions returning promises, so the project wraps its own writes
+and cache invalidation.
+
+## Set up a new project
+
+```bash
+npx hub-kit init
+```
+
+This creates `hub.config.mjs`, `src/hub/registry.tsx` and a starter adapter, then prints
+the two CSS lines to add. Nothing is overwritten if the files already exist.
+
+## Add a guided tour
+
+Tours are plain data the project owns. One object per page, keyed by the project's own
+route path:
+
+```tsx
+import { TourProvider, TourButton, type TourDefinition } from "@hub-kit/core/tour";
+
+const overviewTour: TourDefinition = {
+  id: "overview",
+  steps: [
+    {
+      target: "overview-money-cards",
+      title: "Your figures at a glance",
+      content: [{ kind: "paragraph", text: "Incoming and outgoing invoices for the period." }],
+      showPlaceholderData: true,
+    },
+  ],
+};
+
+<TourProvider tours={{ "/overview": overviewTour }}>
+  <Shell headerActions={<TourButton />} ...rest />
+</TourProvider>
+```
+
+A tour opens by itself the first time a user lands on the page. Once it is skipped or
+finished it never opens by itself again; the Tour button always reopens it. Pages with no
+tour show no button. Target names are listed in `docs/tour-guide.md`.
+
+Steps carry typed content blocks: `paragraph`, `list`, `image`, `video`, `link`,
+`keyValueList` and `callout`. The array order is the order on the card. Styling comes from
+the theme, so a project supplies content only.
+
+A step with `showPlaceholderData` fills an empty page with sample values while the tour is
+open. Sample values come from a separate read-only adapter, so real data is never read
+through or written to.
+
+Full instructions, including the target names each kit page offers: `docs/tour-guide.md`.
+
+## Generate route files
+
+`hub.config.mjs` in the project root names the enabled pages:
+
+```js
+export default {
+  registryImport: "@/hub/registry",
+  pages: [
+    { component: "TeamPage", path: "/team" },
+    { component: "NotificationsPage", path: "/benachrichtigungen" },
+    { component: "ActivityLogPage", path: "/protokoll" },
+  ],
+};
+```
+
+Then:
+
+```bash
+npx hub-kit sync
+```
+
+This writes one thin route file per page. The project's `src/hub/registry.tsx` binds
+each kit page to its adapters and dictionary once.
+
+## Build this package
+
+```bash
+npm run build   # compiles src/ to dist/ with type declarations
+npm run check   # type check only
+```

package/cli/hub-kit.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const command = process.argv[2];
+
+if (command === "init") {
+  await runInit();
+} else if (command === "sync") {
+  await runSync();
+} else {
+  console.log("Usage: hub-kit <init|sync>");
+  console.log("  init  Creates hub.config.mjs, a registry file and a starter adapter.");
+  console.log("  sync  Reads hub.config.mjs and writes one route file per enabled page.");
+  process.exit(command ? 1 : 0);
+}
+
+async function runInit() {
+  const configTemplate = `export default {
+  registryImport: "@/hub/registry",
+  pages: [
+    { component: "ActivityLogPage", path: "/activity-log" },
+  ],
+};
+`;
+
+  const registryTemplate = `import { ProcessingLogPage } from "@hub-kit/core/pages";
+
+import { processingLogAdapter } from "./adapters/processing-log";
+
+export function ActivityLogPage() {
+  return <ProcessingLogPage adapter={processingLogAdapter} />;
+}
+`;
+
+  const adapterTemplate = `import type { ProcessingLogAdapter } from "@hub-kit/core/adapters";
+
+export const processingLogAdapter: ProcessingLogAdapter = {
+  // Implement each member with your project's data layer.
+};
+`;
+
+  writeFileIfMissing(resolve(process.cwd(), "hub.config.mjs"), configTemplate);
+  writeFileIfMissing(resolve(process.cwd(), "src/hub/registry.tsx"), registryTemplate);
+  writeFileIfMissing(resolve(process.cwd(), "src/hub/adapters/processing-log.ts"), adapterTemplate);
+
+  console.log("");
+  console.log("Add these two lines to your main CSS file:");
+  console.log('  @import "@hub-kit/core/themes/default.css";');
+  console.log('  @source "../node_modules/@hub-kit/core/dist";');
+  console.log("");
+  console.log("Next steps:");
+  console.log("  1. Fill in src/hub/adapters/processing-log.ts with your data layer.");
+  console.log("  2. Add your pages to hub.config.mjs and bind them in src/hub/registry.tsx.");
+  console.log("  3. Run: npx hub-kit sync");
+}
+
+function writeFileIfMissing(filePath, content) {
+  if (existsSync(filePath)) {
+    console.log(`kept ${filePath} (already exists)`);
+    return;
+  }
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, content);
+  console.log(`wrote ${filePath}`);
+}
+
+async function runSync() {
+  const configPath = resolve(process.cwd(), "hub.config.mjs");
+  if (!existsSync(configPath)) {
+    console.error("No hub.config.mjs found in this folder. Run: npx hub-kit init");
+    process.exit(1);
+  }
+
+  const config = (await import(pathToFileURL(configPath).href)).default;
+
+  if (!Array.isArray(config?.pages)) {
+    console.error("hub.config.mjs must export default { pages: [...] }.");
+    process.exit(1);
+  }
+
+  const routesFolder = resolve(process.cwd(), config.routesFolder ?? "src/routes");
+  const registryImport = config.registryImport ?? "@/hub/registry";
+
+  for (const page of config.pages) {
+    if (!page.component || !page.path) {
+      console.error(`Every page needs a component and a path. Got: ${JSON.stringify(page)}`);
+      process.exit(1);
+    }
+    const routePath = page.path.endsWith("/") ? page.path : `${page.path}/`;
+    const fileFolder = resolve(routesFolder, ...routePath.split("/").filter(Boolean));
+    const filePath = resolve(fileFolder, "index.tsx");
+    const depth = routePath.split("/").filter(Boolean).length;
+
+    const fileContent = `// Generated by "hub-kit sync". Edit hub.config.mjs instead of this file.
+import { createFileRoute } from "@tanstack/react-router";
+
+import { ${page.component} } from "${registryImport}";
+
+export const Route = createFileRoute("${routePath.slice(0, -1)}/")({
+  component: ${page.component},
+});
+`;
+
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, fileContent);
+    console.log(`wrote ${filePath} (depth ${depth})`);
+  }
+
+  console.log(`Done: ${config.pages.length} route file(s).`);
+}

package/dist/adapters/bank-reconciliation.d.ts

@@ -0,0 +1,100 @@
+import type { NormalizedRow } from "../lib/bank-import/types";
+export interface BankAccountRecord {
+    id: string;
+    account_name: string | null;
+    company_code: string | null;
+    iban: string | null;
+    bic: string | null;
+    bank_name: string | null;
+    product_type: string | null;
+    currency: string | null;
+    balance: number | null;
+    balance_date: string | null;
+    is_own_account: boolean;
+    excluded_at: string | null;
+}
+export interface BankTransactionRecord {
+    id: string;
+    account_id: string;
+    booking_date: string | null;
+    value_date: string | null;
+    amount: number;
+    currency: string | null;
+    counterparty_holder: string | null;
+    counterparty_iban: string | null;
+    payment_reference: string | null;
+    booking_text: string | null;
+    direction: string | null;
+    transaction_type: string | null;
+    matching_status: string;
+    no_receipt_reason: string | null;
+}
+export interface BankMatchCandidate {
+    invoiceId: string;
+    issuer: string | null;
+    invoiceNumber: string | null;
+    amount: number | null;
+    documentDate: string | null;
+    score: number | null;
+    reasons?: string[] | null;
+}
+export interface BankInvoiceSearchResult {
+    id: string;
+    issuer: string | null;
+    invoiceNumber: string | null;
+    amount: number | null;
+    documentDate: string | null;
+}
+export interface BankReconciliationAdapter {
+    useAccounts(): {
+        data: BankAccountRecord[];
+        loading: boolean;
+        error: unknown;
+    };
+    useTransactions(): {
+        data: BankTransactionRecord[];
+        loading: boolean;
+        error: unknown;
+    };
+    useCompanyOptions?(): {
+        data: {
+            code: string;
+            name: string;
+        }[];
+        loading: boolean;
+    };
+    useCandidates(transactionId: string): {
+        data: BankMatchCandidate[];
+        loading: boolean;
+    };
+    confirmMatch(transactionId: string, invoiceId: string): Promise<void>;
+    rejectMatch(transactionId: string, invoiceId: string): Promise<void>;
+    noReceipt?: {
+        mark(transactionId: string, reason: string): Promise<void>;
+        clear(transactionId: string): Promise<void>;
+        reasons: {
+            value: string;
+            label: string;
+        }[];
+    };
+    manualSearch?: {
+        search(query: string): Promise<BankInvoiceSearchResult[]>;
+    };
+    openInvoice: (invoiceId: string) => void;
+    formatMoney: (value: number | null) => string;
+    formatDate: (iso: string | null) => string;
+    import?: {
+        useAccountOptions(): {
+            data: {
+                id: string;
+                label: string;
+            }[];
+            loading: boolean;
+        };
+        importRows(accountId: string, filename: string, rows: NormalizedRow[]): Promise<{
+            imported: number;
+            skipped: number;
+            duplicates: number;
+        }>;
+    };
+}

package/dist/adapters/bank-reconciliation.js

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

package/dist/adapters/bank-sync-log.d.ts

@@ -0,0 +1,46 @@
+export interface SyncLogRow {
+    id: string;
+    createdAt: string;
+    event: string;
+    level: string;
+    connectionId: string | null;
+    message: string | null;
+    counts: Record<string, unknown> | null;
+}
+export interface SyncLogFilter {
+    event?: string;
+    level?: string;
+    connectionId?: string;
+    from?: string;
+    to?: string;
+    page: number;
+    pageSize: number;
+    refreshMs: number;
+}
+export interface SyncLogAdapter {
+    useLogsPage(filter: SyncLogFilter): {
+        data: {
+            rows: SyncLogRow[];
+            total: number;
+        } | undefined;
+        isFetching: boolean;
+        dataUpdatedAt: number;
+        error: unknown;
+        refetch: () => void;
+    };
+    useFacets(): {
+        data: {
+            events: string[];
+            levels: string[];
+        } | undefined;
+    };
+    useConnections(): {
+        data: {
+            id: string;
+            label: string;
+        }[];
+    };
+    formatDateTime: (iso: string) => string;
+    eventLabel: (event: string) => string;
+    countLabel: (key: string) => string;
+}

package/dist/adapters/bank-sync-log.js

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

package/dist/adapters/category-rules.d.ts

@@ -0,0 +1,94 @@
+export type BwaBlock = "revenue" | "cost_of_goods" | "costs" | "neutral" | "taxes" | "special_case";
+export type CategoryDirection = "incoming" | "outgoing";
+export interface CategoryRecord {
+    id: string;
+    code: string;
+    name: string;
+    parentId: string | null;
+    bwaBlock: BwaBlock;
+    bwaLine: string;
+    direction: CategoryDirection;
+    sortOrder: number;
+    isCatchall: boolean;
+    isExcludedFromPnl: boolean;
+    isActive: boolean;
+    note: string | null;
+}
+export interface NewCategory {
+    code: string;
+    name: string;
+    parentId: string | null;
+    bwaBlock: BwaBlock;
+    bwaLine: string;
+    direction: CategoryDirection;
+    note: string | null;
+}
+export interface AssignmentRuleScopeChip {
+    label: string;
+    value: string;
+}
+export interface AssignmentRuleRow {
+    id: string;
+    categoryLabel: string;
+    scopeChips: AssignmentRuleScopeChip[];
+    isActive: boolean;
+    note: string | null;
+    createdAt: string;
+}
+export interface NewAssignmentRule {
+    categoryId: string;
+    supplierId: string | null;
+    propertyId: string | null;
+    companyId: string | null;
+    referencePattern: string | null;
+    note: string | null;
+}
+export interface CategoryRulesAdapter {
+    useCategories(): {
+        data: CategoryRecord[];
+        loading: boolean;
+        error: unknown;
+    };
+    createCategory(input: NewCategory): Promise<void>;
+    updateCategory(id: string, input: Partial<NewCategory>): Promise<void>;
+    archiveCategory(id: string): Promise<void>;
+    moveCategory(id: string, direction: "up" | "down"): Promise<void>;
+    useRules(): {
+        data: AssignmentRuleRow[];
+        loading: boolean;
+        error: unknown;
+    };
+    useCategoryOptions(): {
+        data: {
+            id: string;
+            label: string;
+        }[];
+        loading: boolean;
+    };
+    useSupplierOptions(): {
+        data: {
+            id: string;
+            name: string;
+        }[];
+        loading: boolean;
+    };
+    usePropertyOptions(): {
+        data: {
+            id: string;
+            code: string;
+            name: string | null;
+        }[];
+        loading: boolean;
+    };
+    useCompanyOptions(): {
+        data: {
+            id: string;
+            code: string;
+            name: string;
+        }[];
+        loading: boolean;
+    };
+    createRule(input: NewAssignmentRule): Promise<void>;
+    setRuleActive(id: string, active: boolean): Promise<void>;
+    deleteRule(id: string): Promise<void>;
+}

package/dist/adapters/category-rules.js

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

package/dist/adapters/companies.d.ts

@@ -0,0 +1,85 @@
+import type { QueryResult } from "../lib/query-result";
+import type { StatusTone } from "./processing-log";
+export interface Company {
+    id: string;
+    code: string;
+    name: string;
+    area: string | null;
+    archivedAt: string | null;
+    archiveReason: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+}
+export interface CompanyInvoiceTotals {
+    totalAmount: number;
+    invoiceCount: number;
+}
+export interface CompanyInvoice {
+    id: string;
+    invoiceNumber: string | null;
+    propertyCode: string | null;
+    documentDate: string | null;
+    amountGross: number | null;
+    status: string | null;
+}
+export interface CompanyProperty {
+    id: string;
+    code: string;
+    name: string | null;
+}
+export interface PropertyCompanyLink {
+    propertyId: string;
+    companyId: string;
+}
+export interface CompanyAlias {
+    id: string;
+    alias: string;
+    isActive: boolean;
+}
+export interface CompanyChanges {
+    code?: string;
+    name?: string;
+    area?: string | null;
+}
+export declare const aliasClaimedByAnotherEntityError = "ALIAS_CLAIMED";
+export declare const aliasAlreadyExistsError = "ALIAS_EXISTS";
+export interface CompaniesAdapter {
+    useCompanies(query: {
+        includeArchived: boolean;
+    }): QueryResult<Company[]>;
+    useCompanyInvoiceTotals(): QueryResult<Map<string, CompanyInvoiceTotals>>;
+    useCompany(companyId: string): QueryResult<Company | null>;
+    useInvoicesForCompany(companyId: string, companyCode: string | undefined): QueryResult<CompanyInvoice[]>;
+    useProperties(): QueryResult<CompanyProperty[]>;
+    usePropertyCompanyLinks(): QueryResult<PropertyCompanyLink[]>;
+    useCompanyAliases(companyCode: string): QueryResult<CompanyAlias[]>;
+    createCompany(input: {
+        code: string;
+        name: string;
+    }): Promise<void>;
+    updateCompany(input: {
+        companyId: string;
+        changes: CompanyChanges;
+    }): Promise<void>;
+    archiveCompany(input: {
+        companyId: string;
+        reason: string;
+    }): Promise<void>;
+    restoreCompany(input: {
+        companyId: string;
+    }): Promise<void>;
+    addCompanyAlias(input: {
+        companyCode: string;
+        alias: string;
+    }): Promise<void>;
+    removeCompanyAlias(input: {
+        aliasId: string;
+    }): Promise<void>;
+    /** Selectable area-of-responsibility values; empty when the project has none. */
+    areaOptions: string[];
+    invoiceStatusTone: Record<string, StatusTone>;
+    openCompany(companyId: string): void;
+    openCompanyList(): void;
+    openProperty(propertyCode: string): void;
+    openInvoice(invoiceId: string): void;
+}

package/dist/adapters/companies.js

@@ -0,0 +1,3 @@
+// addCompanyAlias rejects with these exact messages so the page can pick the right toast.
+export const aliasClaimedByAnotherEntityError = "ALIAS_CLAIMED";
+export const aliasAlreadyExistsError = "ALIAS_EXISTS";

package/dist/adapters/customers.d.ts

@@ -0,0 +1,71 @@
+import type { QueryResult } from "../lib/query-result";
+export interface Customer {
+    id: string;
+    companyId: string;
+    isCompany: boolean;
+    name: string;
+    contactPerson: string | null;
+    email: string | null;
+    phone: string | null;
+    addressStreet: string | null;
+    addressZip: string | null;
+    addressCity: string | null;
+    vatId: string | null;
+    customerNumber: string | null;
+    updatedAt: string;
+}
+export interface CustomerCompany {
+    id: string;
+    code: string;
+    name: string;
+}
+export type CustomerInvoiceStatus = "draft" | "open" | "paid" | "voided";
+export interface CustomerInvoice {
+    id: string;
+    invoiceNumber: string | null;
+    invoiceDate: string | null;
+    dueDate: string | null;
+    amountGross: number | null;
+    status: CustomerInvoiceStatus;
+}
+export interface CustomerInvoiceTotals {
+    invoiceCount: number;
+    totalAmount: number;
+    overdueCount: number;
+}
+export interface NewCustomerInput {
+    companyId: string;
+    isCompany: boolean;
+    name: string;
+    contactPerson: string | null;
+    email: string | null;
+    phone: string | null;
+    addressStreet: string | null;
+    addressZip: string | null;
+    addressCity: string | null;
+    vatId: string | null;
+}
+export interface CustomerUpdateInput {
+    name: string;
+    contactPerson: string | null;
+    email: string | null;
+    phone: string | null;
+    addressStreet: string | null;
+    addressZip: string | null;
+    addressCity: string | null;
+    vatId: string | null;
+    customerNumber: string | null;
+}
+export interface CustomersAdapter {
+    useCustomers(): QueryResult<Customer[]>;
+    useCustomer(customerId: string): QueryResult<Customer | null>;
+    useCompanies(): QueryResult<CustomerCompany[]>;
+    /** Pre-aggregated invoice totals for the list, keyed by customer id. */
+    useInvoiceTotalsByCustomer(): QueryResult<Record<string, CustomerInvoiceTotals>>;
+    useCustomerInvoices(customerId: string): QueryResult<CustomerInvoice[]>;
+    createCustomer(input: NewCustomerInput): Promise<void>;
+    updateCustomer(customerId: string, input: CustomerUpdateInput): Promise<void>;
+    deleteCustomer(customerId: string, reason: string): Promise<void>;
+    openCustomer(customerId: string): void;
+    openCustomerList(): void;
+}

package/dist/adapters/customers.js

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

package/dist/adapters/exclusion-rules.d.ts

@@ -0,0 +1,34 @@
+import type { QueryResult } from "../lib/query-result";
+export declare const EXCLUSION_SCOPES_BEFORE_READING: readonly ["sender", "subject", "filename", "envelope"];
+export declare const EXCLUSION_SCOPES_AFTER_READING: readonly ["party", "supplier", "body", "company", "property"];
+export type ExclusionScope = (typeof EXCLUSION_SCOPES_BEFORE_READING)[number] | (typeof EXCLUSION_SCOPES_AFTER_READING)[number];
+export interface ExclusionRule {
+    id: string;
+    scope: ExclusionScope;
+    term: string;
+    note: string | null;
+    isActive: boolean;
+}
+export interface ExclusionImpact {
+    supported: boolean;
+    matchCount: number;
+    totalCount: number;
+}
+export interface ExclusionRulesAdapter {
+    useExclusionRules(): QueryResult<ExclusionRule[]>;
+    useExclusionImpact(query: {
+        scope: ExclusionScope;
+        term: string;
+        enabled: boolean;
+    }): QueryResult<ExclusionImpact>;
+    createExclusionRule(input: {
+        scope: ExclusionScope;
+        term: string;
+        note: string;
+    }): Promise<void>;
+    setExclusionRuleActive(input: {
+        id: string;
+        isActive: boolean;
+    }): Promise<void>;
+    deleteExclusionRule(id: string): Promise<void>;
+}