@startsimpli/integrations 0.1.0 → 0.1.3

package/README.md

@@ -0,0 +1,178 @@
+# @startsimpli/integrations
+
+Provider-agnostic TypeScript client for the OAuth-backed **email** and **calendar** integrations that StartSimpli apps consume from the Django API. Ships:
+
+- **Typed API clients** wrapping `start-simpli-api`'s `/auth/oauth/*`, `/auth/oauth-accounts/`, `/calendar/events/`, and `/email/messages/` endpoints
+- **React Query hooks** for connected accounts, calendar events, and email messages — with built-in re-consent flow handling
+- **Headless React UI primitives** for connect cards, account status, event/email lists, and re-consent prompts
+- **Normalized error types** (`UnauthenticatedError`, `ReconsentRequiredError`, `ApiError`) so the UI can branch on auth failure modes without parsing payloads
+
+## The connections layer (foundries)
+
+Alongside the email/calendar clients above, this package ships the UI for the
+**connector framework** — the surface a foundry admin uses to connect a vendor
+account and wire it up:
+
+- **`CredentialSchemaForm`** — ONE renderer for every vendor, driven by the
+  catalog's own field schema (`{version, fields[]}`). It knows about FIELDS and
+  nothing about vendors: an unknown field type degrades to a text input, an
+  unrecognised schema version still renders its fields, and a field the server
+  marks `type: "secret"` / `write_only` is masked and never populated from a
+  read response.
+- **`ConnectionsPage`** — the page composer: connected accounts, the catalog,
+  and the wiring flow (**discover → wire → confirm → fire**). Injected api, no
+  React context and no app-local provider, so an app mounts it in ten lines:
+
+  ```tsx
+  <ConnectionsPage api={apiClient.foundry} foundrySlug={slug} />
+  ```
+
+**There are no per-vendor components, and a test enforces it** — it greps the
+component tree for vendor keys. The backend refuses to hardcode a vendor (the
+catalog is `DestinationProvider` rows and the field schemas come off the
+connector class); that is worth nothing if the browser answers with
+`if (key === 'n8n')`.
+
+**OAuth providers shipped in-box:** `google` and `microsoft`. The Django backend brokers the OAuth handshake — this package never touches client secrets or refresh tokens directly. Reference lifecycle: `email-cal-srcs-dests`.
+
+## Install
+
+Workspace-only:
+
+```jsonc
+"dependencies": {
+  "@startsimpli/integrations": "workspace:*"
+}
+```
+
+Peer deps (both optional, only needed for the hooks/components subpaths):
+
+- `react ^18 || ^19`
+- `@tanstack/react-query ^5`
+
+You can consume `@startsimpli/integrations/types` and `@startsimpli/integrations/api` from a non-React context (e.g. a Node server, an MSW handler) without pulling in React.
+
+## Public surface
+
+| Export | Type | Description |
+| --- | --- | --- |
+| `OAuthProvider` | `'google' \| 'microsoft'` | The two providers backed by Django |
+| `AccountStatus` | `'connected' \| 'disconnected' \| 'needs_reauth'` | Status union for `ConnectAccountCard` |
+| `ConnectedAccount` / `CalendarEvent` / `CalendarEventAttendee` / `CalendarEventStatus` / `EmailMessage` / `PaginatedResponse<T>` / `CalendarWindow` / `ApiErrorPayload` | types | DRF response shapes |
+| `ApiError` / `UnauthenticatedError` / `ReconsentRequiredError` | classes | Thrown by every API client; the UI uses `instanceof` to branch |
+| `connectProvider(provider, redirectUri?)` | `POST /auth/oauth/{provider}/initiate/` | Returns the upstream `authorization_url` to redirect to |
+| `revokeAccount(provider, oauthAccountId)` | `POST /auth/oauth/{provider}/revoke/` | Disconnects a connected account |
+| `listConnectedAccounts()` | `GET /auth/oauth-accounts/` | All accounts for the current user |
+| `listCalendarEvents({ from, to, provider?, calendar_id?, page?, page_size? })` | `GET /calendar/events/` | Paginated events in a window |
+| `listEmailMessages({ provider?, account_id?, since?, is_outbound?, page?, page_size? })` | `GET /email/messages/` | Paginated messages |
+| `setApiBase(url)` / `getApiBase()` | functions | Override the default `/api/v1` base URL |
+| `setAuthTokenProvider(fn)` | function | Wire up a token source — injected as `Authorization: Bearer <token>` |
+| `useConnectedAccounts(options?)` | hook | React Query wrapper around `listConnectedAccounts` (30 s `staleTime`) |
+| `useDisconnectAccount()` | hook | Returns a mutator that revokes + invalidates the accounts query |
+| `useCalendarEvents(window, options?)` | hook | Wraps `listCalendarEvents`; surfaces `events`, `reconsentUrl` |
+| `useEmailMessages(filter?, options?)` | hook | Wraps `listEmailMessages`; surfaces `messages`, `reconsentUrl` |
+| `useReconsent(error)` | hook | Extracts a `reconsent_url` from a thrown error + returns `openReconsent()` |
+| `CONNECTED_ACCOUNTS_KEY` | const tuple | Stable React Query key for invalidation |
+| `AccountStatusBadge` | component | "Connected / Needs re-auth / Disconnected" pill |
+| `ConnectAccountCard` | component | Per-provider connect/disconnect card |
+| `EmailList` / `EventList` / `EventListItem` | components | Headless list renderers |
+| `ReconsentPromptCard` | component | Re-consent CTA card driven by `useReconsent` |
+
+Subpath exports: `.`, `./types` (zero React), `./api` (zero React).
+
+### Adapters that ship today
+
+| Provider | OAuth | Mail | Calendar |
+| --- | :---: | :---: | :---: |
+| **Google** | yes (`gmail.readonly`, `calendar.readonly`) | yes | yes |
+| **Microsoft** | yes (`Mail.Read`, `Calendars.Read`) | yes | yes |
+
+No other adapters (Apollo, Hunter, Stripe, …) live in this package — those concerns belong in their own packages or directly in the Django backend. The single source of truth for available providers is `OAuthProvider` in `src/types/index.ts`.
+
+## Configuration
+
+This is a thin client over Django — all provider credentials (Google client ID/secret, Microsoft app registration, scopes, refresh-token vault) live in `start-simpli-api`. From the browser side, you only need to wire up:
+
+| Setup call | Why |
+| --- | --- |
+| `setApiBase('https://api.example.com/api/v1')` | Point at your Django host. Defaults to `/api/v1` (relative). |
+| `setAuthTokenProvider(() => getAccessToken())` | Provide a fresh JWT/session token for every request. Returning `null` falls back to cookie auth (the fetch wrapper uses `credentials: 'include'`). |
+
+Errors surfaced from the Django API are normalized:
+
+- **401** → `UnauthenticatedError`
+- **403** with `reconsent_url` in the payload → `ReconsentRequiredError` (drives the re-consent prompt)
+- All other non-2xx → `ApiError` with `status` + `payload`
+
+## Usage
+
+Real example from `raise-simpli/web-app/src/app/(dashboard)/settings/integrations/page.tsx`:
+
+```tsx
+'use client'
+import {
+  ConnectAccountCard,
+  useConnectedAccounts,
+  useDisconnectAccount,
+  type ConnectedAccount,
+  type OAuthProvider,
+} from '@startsimpli/integrations'
+
+const PROVIDERS: OAuthProvider[] = ['microsoft', 'google']
+
+export default function IntegrationsPage() {
+  const { data: accounts = [], isLoading, error } = useConnectedAccounts()
+  const disconnect = useDisconnectAccount()
+
+  const accountByProvider = (provider: OAuthProvider): ConnectedAccount | undefined =>
+    accounts.find((a) => a.provider === provider)
+
+  return (
+    <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+      {PROVIDERS.map((provider) => (
+        <ConnectAccountCard
+          key={provider}
+          provider={provider}
+          account={accountByProvider(provider)}
+          onDisconnect={(id) => disconnect(provider, id)}
+        />
+      ))}
+    </div>
+  )
+}
+```
+
+Calendar window with re-consent handling:
+
+```tsx
+const { events, reconsentUrl, isLoading } = useCalendarEvents({
+  from: startOfWeek,
+  to: endOfWeek,
+}, { provider: 'google', pageSize: 200 })
+
+if (reconsentUrl) return <ReconsentPromptCard href={reconsentUrl} />
+```
+
+App startup wiring (called once):
+
+```ts
+import { setApiBase, setAuthTokenProvider } from '@startsimpli/integrations'
+import { getAccessToken } from '@startsimpli/auth/client'
+
+setApiBase(process.env.NEXT_PUBLIC_API_BASE_URL!)
+setAuthTokenProvider(() => getAccessToken())
+```
+
+## Verification
+
+```bash
+cd packages/integrations
+pnpm vitest run
+pnpm tsc --noEmit
+```
+
+The test suite (`src/__tests__/api.test.ts`) ships **10 tests** covering the OAuth/calendar/email clients and the 401 / 403-with-reconsent / 5xx error normalisation paths against an MSW-mocked Django backend.
+
+## Shared-first
+
+Per CLAUDE.md **rule 9**, do **not** copy fetch helpers, types, or React Query hooks for calendar/email into an app's `src/`. The package guards this — `raise-simpli/web-app/src/__tests__/no_app_local_calendar_code.test.ts` exists to fail CI if app-local duplicates reappear. Extend `@startsimpli/integrations` instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Provider-agnostic types, API clients, hooks, and UI primitives for email + calendar integrations across StartSimpli apps.",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -16,27 +16,36 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "type-check": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "dependencies": {},
   "peerDependencies": {
     "react": ">=18.0.0",
     "@tanstack/react-query": ">=5.0.0"
   },
   "peerDependenciesMeta": {
-    "react": { "optional": true },
-    "@tanstack/react-query": { "optional": true }
+    "react": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.0.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@testing-library/user-event": "^14.5.2",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
+    "jsdom": "^29.0.0",
     "msw": "^2.0.0",
     "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "typescript": "^6.0.0",
     "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}

package/src/__tests__/connections.test.tsx

@@ -0,0 +1,338 @@
+/**
+ * The connections layer: a generic renderer and a page composer
+ * (bd startsim-768w.22.3.2 RED, startsim-768w.22.3.4 GREEN).
+ *
+ * THE ONE RULE THIS SUITE EXISTS TO ENFORCE: no per-vendor components, ever.
+ * The backend already refuses to hardcode a vendor — the catalog is
+ * `DestinationProvider` rows and the field schemas come off the connector class
+ * — and that is worth nothing if the browser answers with `if (key === 'n8n')`.
+ * So every assertion below drives TWO different schemas through ONE component
+ * and checks the output differs only in the way the DATA differs.
+ *
+ * The composer is injected, not contextual: `<ConnectionsPage api={...}
+ * foundrySlug="..." />`, the same shape as `TeamSettingsPage`. No React context,
+ * no app-local provider — an app mounts it in ten lines and owns nothing but
+ * theme classNames.
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import { CredentialSchemaForm, schemaFields } from '../components/CredentialSchemaForm';
+import { ConnectionsPage } from '../components/pages/ConnectionsPage';
+import type { ConnectionsApi } from '../components/pages/types';
+
+// --------------------------------------------------------------------------
+//  two schemas, one component
+// --------------------------------------------------------------------------
+
+/** Vendor A: a single secret. The Granola shape. */
+const ONE_SECRET = [
+  { key: 'api_key', label: 'API key', type: 'secret', write_only: true, required: true,
+    help: 'Starts with grn_' },
+];
+
+/** Vendor B: url + secret + select. The self-hosted n8n shape. */
+const URL_SECRET_SELECT = [
+  { key: 'base_url', label: 'Instance URL', type: 'url', required: true,
+    placeholder: 'https://n8n.example.com' },
+  { key: 'api_key', label: 'Public API key', type: 'secret', write_only: true, required: false },
+  {
+    key: 'environment',
+    label: 'Environment',
+    type: 'select',
+    required: false,
+    default: 'production',
+    options: [
+      { value: 'production', label: 'Production' },
+      { value: 'staging', label: 'Staging' },
+    ],
+  },
+];
+
+function renderForm(fields: unknown[], props: Record<string, unknown> = {}) {
+  const onChange = vi.fn();
+  const utils = render(
+    <CredentialSchemaForm
+      fields={fields as never}
+      values={{}}
+      onChange={onChange}
+      {...props}
+    />,
+  );
+  return { ...utils, onChange };
+}
+
+describe('CredentialSchemaForm — one renderer, every vendor', () => {
+  it('renders a one-secret schema from data alone', () => {
+    renderForm(ONE_SECRET);
+    expect(screen.getByLabelText(/API key/i)).toBeInTheDocument();
+    expect(screen.getByText(/Starts with grn_/i)).toBeInTheDocument();
+  });
+
+  it('renders a url+secret+select schema with the SAME component', () => {
+    renderForm(URL_SECRET_SELECT);
+    expect(screen.getByLabelText(/Instance URL/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/Public API key/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/Environment/i)).toBeInTheDocument();
+    expect(screen.getByRole('option', { name: 'Staging' })).toBeInTheDocument();
+  });
+
+  it('keeps the declared array order', () => {
+    const { container } = renderForm(URL_SECRET_SELECT);
+    const names = Array.from(container.querySelectorAll('[data-field]')).map(
+      (el) => el.getAttribute('data-field'),
+    );
+    expect(names).toEqual(['base_url', 'api_key', 'environment']);
+  });
+
+  it('honours placeholder and default', () => {
+    renderForm(URL_SECRET_SELECT);
+    expect(screen.getByPlaceholderText('https://n8n.example.com')).toBeInTheDocument();
+    expect((screen.getByLabelText(/Environment/i) as HTMLSelectElement).value)
+      .toBe('production');
+  });
+
+  it('masks a secret field', () => {
+    renderForm(ONE_SECRET);
+    expect(screen.getByLabelText(/API key/i)).toHaveAttribute('type', 'password');
+  });
+
+  it('NEVER populates a secret from a read response', () => {
+    // The read surface returns config, never credential values. If a `values`
+    // map ever carries one, the form still must not put it in the DOM — a
+    // masked input whose value is the real key is a copy-paste away from a leak.
+    renderForm(ONE_SECRET, { values: { api_key: 'grn_live_SHOULD_NOT_RENDER' } });
+    expect((screen.getByLabelText(/API key/i) as HTMLInputElement).value).toBe('');
+    expect(document.body.innerHTML).not.toContain('grn_live_SHOULD_NOT_RENDER');
+  });
+
+  it('degrades an unknown type to text and still renders its neighbours', () => {
+    renderForm([
+      { key: 'first', label: 'First' },
+      { key: 'exotic', label: 'Exotic', type: 'colour-wheel-from-the-future' },
+      { key: 'last', label: 'Last' },
+    ]);
+    expect(screen.getByLabelText(/Exotic/i)).toHaveAttribute('type', 'text');
+    expect(screen.getByLabelText(/First/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/Last/i)).toBeInTheDocument();
+  });
+
+  it('reports every edit through onChange', async () => {
+    const { onChange } = renderForm(ONE_SECRET);
+    await userEvent.type(screen.getByLabelText(/API key/i), 'grn_x');
+    expect(onChange).toHaveBeenCalled();
+    expect(onChange.mock.calls[0][0]).toBe('api_key');
+  });
+});
+
+// --------------------------------------------------------------------------
+//  the composer
+// --------------------------------------------------------------------------
+
+const CATALOG = {
+  results: [
+    {
+      key: 'n8n', name: 'n8n', description: 'Call a workflow', logo_url: '', docs_url: '',
+      capabilities: ['action', 'poll'], auth_mode: 'api_key',
+      credential_schema: { version: 1, fields: URL_SECRET_SELECT },
+      config_schema: { version: 1, fields: [] },
+      record_types: [], supports_webhooks: true,
+      availability: { available: true, reason: '' },
+    },
+    {
+      key: 'granola', name: 'Granola', description: 'Meeting notes', logo_url: '', docs_url: '',
+      capabilities: ['poll'], auth_mode: 'api_key',
+      credential_schema: { version: 1, fields: ONE_SECRET },
+      config_schema: { version: 1, fields: [] },
+      record_types: [], supports_webhooks: false,
+      availability: { available: false, reason: 'ImportError: no granola sdk' },
+    },
+  ],
+};
+
+const CONNECTED = {
+  results: [
+    {
+      id: 'c1', public_id: 'pub1', name: 'Ops n8n', connector_key: 'n8n', connector_name: 'n8n',
+      external_account_id: '', account_label: 'https://n8n.example.com',
+      capabilities_enabled: ['action'], config: {}, status: 'connected',
+      health: 'ok', auth_mode: 'api_key',
+    },
+  ],
+  permissions: { view: true, manage: true, issue_tokens: true },
+};
+
+function stubApi(overrides: Partial<ConnectionsApi> = {}): ConnectionsApi {
+  return {
+    connectorCatalog: vi.fn().mockResolvedValue(CATALOG),
+    connections: vi.fn().mockResolvedValue(CONNECTED),
+    connect: vi.fn().mockResolvedValue(CONNECTED.results[0]),
+    checkConnection: vi.fn().mockResolvedValue({ ok: true, account_label: '', detail: 'ok' }),
+    disconnect: vi.fn().mockResolvedValue(undefined),
+    connectionChoices: vi.fn().mockResolvedValue({
+      results: [
+        {
+          id: 'wf-1:node-a', label: 'Nightly digest — Webhook', kind: 'workflow',
+          selectable: true, reason: 'wirable', remediation: '', hidden_by_default: false,
+          detail: {},
+        },
+        {
+          id: 'wf-2', label: 'Schedule only', kind: 'workflow', selectable: false,
+          reason: 'not_wirable:schedule_only',
+          remediation: 'Add a Webhook trigger node.', hidden_by_default: false, detail: {},
+        },
+      ],
+      kind: 'workflow', cursor: null, has_more: false,
+    }),
+    wireTarget: vi.fn().mockResolvedValue({
+      id: 'd1', name: 'Nightly digest', provider_key: 'n8n', entity_type: 'contact',
+      is_active: true, verified: false,
+      destination_config: { webhook_url: 'https://n8n.example.com/webhook/nightly' },
+    }),
+    confirmTarget: vi.fn().mockResolvedValue({
+      id: 'd1', name: 'Nightly digest', provider_key: 'n8n', entity_type: 'contact',
+      is_active: true, verified: true,
+      destination_config: { webhook_url: 'https://n8n.example.com/webhook/nightly' },
+    }),
+    connectionActions: vi.fn().mockResolvedValue({
+      results: [{ name: 'trigger_workflow', label: 'Trigger a workflow', input_schema: {} }],
+    }),
+    invokeConnectionAction: vi.fn().mockResolvedValue({
+      ok: true, action: 'trigger_workflow', destination_id: 'd1', run_id: 'r1',
+      run_status: 'running', external_ref: null, output: {}, error: '',
+    }),
+    connectionRuns: vi.fn().mockResolvedValue({ results: [] }),
+    ...overrides,
+  } as ConnectionsApi;
+}
+
+describe('ConnectionsPage — injected, not contextual', () => {
+  it('renders the catalog and the connected list from the injected api', async () => {
+    const api = stubApi();
+    render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    expect(await screen.findByText('Ops n8n')).toBeInTheDocument();
+    expect(await screen.findByText('Granola')).toBeInTheDocument();
+    expect(api.connectorCatalog).toHaveBeenCalledWith('acme');
+    expect(api.connections).toHaveBeenCalledWith('acme');
+  });
+
+  it('shows an unavailable catalog row WITH its reason instead of hiding it', async () => {
+    render(<ConnectionsPage api={stubApi()} foundrySlug="acme" />);
+    expect(await screen.findByText(/no granola sdk/i)).toBeInTheDocument();
+  });
+
+  it('renders read-only when the permissions envelope says manage is false', async () => {
+    const api = stubApi({
+      connections: vi.fn().mockResolvedValue({
+        ...CONNECTED,
+        permissions: { view: true, manage: false, issue_tokens: false },
+      }),
+    });
+    render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    await screen.findByText('Ops n8n');
+    expect(screen.queryByRole('button', { name: /^connect$/i })).not.toBeInTheDocument();
+  });
+
+  it('surfaces a DENIED read as a reason, not an empty page', async () => {
+    const denied = Object.assign(new Error('forbidden'), { status: 403 });
+    const api = stubApi({ connections: vi.fn().mockRejectedValue(denied) });
+    render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    expect(await screen.findByText(/do not have access|not have permission/i)).toBeInTheDocument();
+  });
+
+  it('drives discovery -> wire -> confirm without anything hand-typed', async () => {
+    const api = stubApi();
+    render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    await userEvent.click(await screen.findByRole('button', { name: /workflows|discover/i }));
+
+    // Nothing is dropped: the unpickable row is present and says why.
+    expect(await screen.findByText(/Nightly digest/)).toBeInTheDocument();
+    expect(screen.getByText(/Add a Webhook trigger node\./)).toBeInTheDocument();
+
+    await userEvent.click(screen.getByRole('button', { name: /^wire$/i }));
+    await waitFor(() => expect(api.wireTarget).toHaveBeenCalledWith('acme', 'c1', {
+      choice_id: 'wf-1:node-a',
+    }));
+
+    await userEvent.click(await screen.findByRole('button', { name: /confirm/i }));
+    await waitFor(() => expect(api.confirmTarget).toHaveBeenCalledWith('acme', 'c1', 'd1'));
+  });
+
+  it('will not offer to wire an unpickable choice', async () => {
+    render(<ConnectionsPage api={stubApi()} foundrySlug="acme" />);
+    await userEvent.click(await screen.findByRole('button', { name: /workflows|discover/i }));
+    await screen.findByText(/Schedule only/);
+    // One selectable row -> exactly one wire button.
+    expect(screen.getAllByRole('button', { name: /^wire$/i })).toHaveLength(1);
+  });
+});
+
+describe('the catalog envelope, as the server actually ships it', () => {
+  // REGRESSION. The first browser drive of this page died on
+  // `(entry.credential_schema ?? []) is not iterable`, because these fixtures
+  // were invented as bare arrays while `schema_to_wire` ships
+  // `{version, fields[]}`. Unit tests cannot catch a fixture that lies about
+  // the wire — only driving the real API can — so the shape is pinned here now.
+  it('reads fields out of the {version, fields} envelope', () => {
+    renderForm(ONE_SECRET);
+    expect(screen.getByLabelText(/API key/i)).toBeInTheDocument();
+  });
+
+  it('renders a catalog row whose schema arrives in the envelope', async () => {
+    render(<ConnectionsPage api={stubApi()} foundrySlug="acme" />);
+    expect(await screen.findByText('n8n')).toBeInTheDocument();
+  });
+
+  it('does NOT blank the form on a schema version this build has never seen', () => {
+    const { container } = render(
+      <CredentialSchemaForm
+        fields={schemaFields({ version: 7, fields: ONE_SECRET } as never)}
+        values={{}}
+        onChange={() => {}}
+      />,
+    );
+    expect(container.querySelectorAll('[data-field]')).toHaveLength(1);
+  });
+
+  it('treats a missing or malformed schema as no fields, not a crash', () => {
+    expect(schemaFields(null)).toEqual([]);
+    expect(schemaFields(undefined)).toEqual([]);
+    expect(schemaFields({} as never)).toEqual([]);
+    expect(schemaFields({ version: 1 } as never)).toEqual([]);
+  });
+
+  it('masks on type:"secret" — the server spelling, not a boolean', () => {
+    renderForm([{ key: 'k', label: 'Key', type: 'secret' }]);
+    expect(screen.getByLabelText(/Key/i)).toHaveAttribute('type', 'password');
+  });
+});
+
+describe('no per-vendor components', () => {
+  it('the connections layer names no vendor', async () => {
+    // The guard, as an assertion rather than a code-review habit. A component
+    // file whose text contains a vendor key is the thing the DB-driven catalog
+    // exists to prevent; the fixtures above prove two vendors already render
+    // through one path, and this stops the third from arriving as a branch.
+    const fs = await import('node:fs/promises');
+    const path = await import('node:path');
+    const dir = path.resolve(__dirname, '../components');
+    const offenders: string[] = [];
+    const walk = async (d: string): Promise<void> => {
+      for (const entry of await fs.readdir(d, { withFileTypes: true })) {
+        const full = path.join(d, entry.name);
+        if (entry.isDirectory()) { await walk(full); continue; }
+        if (!/\.tsx?$/.test(entry.name)) continue;
+        const text = await fs.readFile(full, 'utf8');
+        for (const vendor of ['n8n', 'granola', 'stripe', 'soundcharts', 'companies_house']) {
+          // A vendor named in a COMMENT is fine — it is an example. A vendor in
+          // code is a branch.
+          const code = text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*/g, '');
+          if (code.toLowerCase().includes(vendor)) offenders.push(`${entry.name}: ${vendor}`);
+        }
+      }
+    };
+    await walk(dir);
+    expect(offenders).toEqual([]);
+  });
+});