@startsimpli/integrations 0.1.0 → 0.1.4

package/src/__tests__/connections.test.tsx

@@ -0,0 +1,453 @@
+/**
+ * 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, within } 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: [] }),
+    updateConnection: vi.fn().mockResolvedValue(CONNECTED.results[0]),
+    ...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);
+  });
+});
+
+// --------------------------------------------------------------------------
+//  the capability choice (bd startsim-768w.22.22)
+// --------------------------------------------------------------------------
+
+/**
+ * WHAT WENT WRONG ON PRODUCTION. An admin connected Granola on the `tandem`
+ * foundry through this very page. The card went green — `check()` really
+ * reached the vendor — and `capabilities_enabled` was stored as `[]`. With an
+ * empty list NO capability is enabled: not `poll`, not `action`, not
+ * `webhook_in`. So `poll_is_enabled()` answered false, no scheduled ingest leg
+ * was ever created, and the card sat there connected and completely inert.
+ *
+ * The server was not the liar. `POST /connections/` has accepted
+ * `capabilities_enabled[]` since the endpoint was designed, and
+ * `PATCH /connections/<id>/` has accepted edits to it and created the poll leg
+ * on the spot. THIS PAGE never sent either one — there was no control for it
+ * anywhere, at connect time or after — so the server received nothing, wrote
+ * nothing, and the admin had no way to say what they wanted.
+ *
+ * Both halves are asserted here: the choice is offered when connecting, and it
+ * stays changeable afterwards, because the connections that already exist
+ * cannot be fixed by anything the connect form does.
+ */
+describe('capabilities are the admin’s choice, and the page has to ask', () => {
+  /** The capability picker inside ONE card. Both surfaces render one. */
+  function picker(scope: HTMLElement, which: 'catalog' | 'connection') {
+    const group = scope.querySelector<HTMLElement>(`[data-capabilities="${which}"]`);
+    if (!group) throw new Error(`no ${which} capability picker rendered`);
+    return within(group);
+  }
+
+  async function openConnectForm() {
+    const api = stubApi();
+    const { container } = render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    // The catalog's available row. The unavailable one offers no button at all.
+    await userEvent.click(await screen.findByRole('button', { name: /^connect$/i }));
+    return { api, container };
+  }
+
+  it('offers every capability the connector declares, from the catalog row', async () => {
+    const { container } = await openConnectForm();
+    // The n8n fixture declares action + poll. Both are offered; nothing else is.
+    const boxes = picker(container, 'catalog').getAllByRole('checkbox');
+    expect(boxes.map((b) => b.getAttribute('value')).sort()).toEqual(['action', 'poll']);
+    for (const box of boxes) expect(box).toBeChecked();
+  });
+
+  it('SENDS the capability list on connect instead of leaving the card inert', async () => {
+    const { api } = await openConnectForm();
+    await userEvent.type(screen.getByLabelText(/Instance URL/i), 'https://n8n.example.com');
+    await userEvent.click(screen.getByRole('button', { name: /test and save/i }));
+
+    await waitFor(() => expect(api.connect).toHaveBeenCalled());
+    const sent = (api.connect as ReturnType<typeof vi.fn>).mock.calls[0][1];
+    expect(sent.capabilities_enabled).toEqual(['action', 'poll']);
+  });
+
+  it('honours an admin who unchecks one before saving', async () => {
+    const { api, container } = await openConnectForm();
+    await userEvent.type(screen.getByLabelText(/Instance URL/i), 'https://n8n.example.com');
+    await userEvent.click(picker(container, 'catalog').getByRole('checkbox', { name: /action/i }));
+    await userEvent.click(screen.getByRole('button', { name: /test and save/i }));
+
+    await waitFor(() => expect(api.connect).toHaveBeenCalled());
+    const sent = (api.connect as ReturnType<typeof vi.fn>).mock.calls[0][1];
+    expect(sent.capabilities_enabled).toEqual(['poll']);
+  });
+
+  it('will not let an admin save a connection that can do nothing', async () => {
+    const { container } = await openConnectForm();
+    await userEvent.type(screen.getByLabelText(/Instance URL/i), 'https://n8n.example.com');
+    for (const box of picker(container, 'catalog').getAllByRole('checkbox')) {
+      await userEvent.click(box);
+    }
+    // The server refuses an empty list with a 400 (bd startsim-768w.22.22);
+    // refusing it here means the admin finds out before a round trip.
+    expect(screen.getByRole('button', { name: /test and save/i })).toBeDisabled();
+  });
+
+  it('lets an admin turn a capability ON for a connection that already exists', async () => {
+    // THE UNBLOCK. The `tandem` Granola card is already there with an empty
+    // list; nothing the connect form does can reach it. `Ops n8n` here has only
+    // `action` enabled, and the connector declares `poll` too.
+    const api = stubApi();
+    const { container } = render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    await screen.findByText('Ops n8n');
+
+    const on = picker(container, 'connection');
+    const poll = on.getByRole('checkbox', { name: /poll/i });
+    expect(poll).not.toBeChecked();
+    await userEvent.click(poll);
+    await userEvent.click(on.getByRole('button', { name: /save/i }));
+
+    await waitFor(() => expect(api.updateConnection).toHaveBeenCalledWith('acme', 'c1', {
+      capabilities_enabled: ['action', 'poll'],
+    }));
+  });
+
+  it('shows the capability state read-only when manage is false', async () => {
+    const api = stubApi({
+      connections: vi.fn().mockResolvedValue({
+        ...CONNECTED,
+        permissions: { view: true, manage: false, issue_tokens: false },
+      }),
+    });
+    const { container } = render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    await screen.findByText('Ops n8n');
+
+    const on = picker(container, 'connection');
+    expect(on.queryByRole('button', { name: /save/i })).not.toBeInTheDocument();
+    for (const box of on.getAllByRole('checkbox')) expect(box).toBeDisabled();
+  });
+});
+
+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([]);
+  });
+});

package/src/components/CredentialSchemaForm.tsx

@@ -0,0 +1,196 @@
+/**
+ * ONE form for every vendor, rendered from the catalog's own field schema
+ * (bd startsim-768w.22.3.4).
+ *
+ * The backend already refuses to hardcode a vendor: the catalog is
+ * `DestinationProvider` rows and the field specs come off the connector class,
+ * so adding a vendor costs a row and a class. That is worth nothing if the
+ * browser answers with `if (connector === 'x')` — the duplication would just
+ * have moved to where nobody is looking. So this component knows about FIELDS
+ * and knows nothing about vendors, and the suite next door drives two different
+ * schemas through it to prove it.
+ *
+ * FORWARD COMPATIBILITY IS THE POINT. The catalog is data and will outrun the
+ * deployed bundle — a connector shipped today can declare a field type this
+ * build has never heard of. An unknown type degrades to a text input and every
+ * other field still renders, because a blank form is a support ticket and a
+ * text input is a usable answer.
+ */
+import * as React from 'react';
+
+import type { ConnectorFieldSpec, ConnectorSchemaLike } from './pages/types';
+
+export interface CredentialSchemaFormProps {
+  /** The catalog's own schema, rendered in DECLARED ORDER. */
+  fields: ConnectorFieldSpec[];
+  /** Current values, keyed by field key. Secrets are never read back from here. */
+  values: Record<string, string>;
+  onChange: (key: string, value: string) => void;
+  /** Per-field messages. A `pattern` miss WARNS; only `required` blocks submit. */
+  errors?: Record<string, string>;
+  warnings?: Record<string, string>;
+  idPrefix?: string;
+  classNames?: {
+    field?: string;
+    label?: string;
+    input?: string;
+    help?: string;
+    error?: string;
+    warning?: string;
+  };
+}
+
+/** Field types this build renders natively. Anything else becomes text. */
+const NATIVE_TYPES = new Set(['text', 'url', 'email', 'number', 'select', 'textarea']);
+
+/**
+ * Is this field a secret? `type: "secret"` is the server's spelling and
+ * `write_only` is the flag it enforces alongside it; `secret: true` is accepted
+ * for hand-built schemas. Any one of the three masks the field — asking the
+ * question in one place is what stops the three from disagreeing.
+ */
+export function isSecret(spec: ConnectorFieldSpec): boolean {
+  return spec.type === 'secret' || Boolean(spec.write_only) || Boolean(spec.secret);
+}
+
+/**
+ * The fields of a schema, whatever envelope it arrived in.
+ *
+ * The catalog ships `{version, fields[]}`; a caller composing a schema by hand
+ * passes a bare array. An UNRECOGNISED VERSION still renders its fields rather
+ * than blanking the form — the catalog is data and will outrun this bundle, and
+ * a blank connect form is a dead end with nothing to act on.
+ */
+export function schemaFields(schema: ConnectorSchemaLike): ConnectorFieldSpec[] {
+  if (!schema) return [];
+  if (Array.isArray(schema)) return schema;
+  return Array.isArray(schema.fields) ? schema.fields : [];
+}
+
+function inputType(spec: ConnectorFieldSpec): string {
+  if (isSecret(spec)) return 'password';
+  const declared = String(spec.type || 'text');
+  return NATIVE_TYPES.has(declared) ? declared : 'text';
+}
+
+export function CredentialSchemaForm({
+  fields,
+  values,
+  onChange,
+  errors = {},
+  warnings = {},
+  idPrefix = 'csf',
+  classNames = {},
+}: CredentialSchemaFormProps) {
+  return (
+    <div className="space-y-4">
+      {fields.map((spec) => {
+        const id = `${idPrefix}-${spec.key}`;
+        const type = inputType(spec);
+        // A SECRET IS NEVER RENDERED. Not "not fetched" — not rendered, even if
+        // a value for it somehow reached this component. A masked input holding
+        // the real key is one devtools panel away from being the leak the whole
+        // credential surface is built to prevent.
+        const value = isSecret(spec)
+          ? (values[`${spec.key}__draft`] ?? '')
+          : (values[spec.key] ?? spec.default ?? '');
+        const error = errors[spec.key];
+        const warning = warnings[spec.key];
+
+        return (
+          <div key={spec.key} data-field={spec.key} className={classNames.field}>
+            <label htmlFor={id} className={classNames.label ?? 'block text-sm font-medium text-gray-900'}>
+              {spec.label}
+              {spec.required ? <span aria-hidden="true"> *</span> : null}
+            </label>
+
+            {type === 'select' ? (
+              <select
+                id={id}
+                value={value}
+                required={Boolean(spec.required)}
+                onChange={(e) => onChange(spec.key, e.target.value)}
+                className={classNames.input ?? 'mt-1 w-full rounded-md border border-gray-300 px-3 py-2 text-sm'}
+              >
+                {(spec.options ?? []).map((option) => (
+                  <option key={option.value} value={option.value}>{option.label}</option>
+                ))}
+              </select>
+            ) : type === 'textarea' ? (
+              <textarea
+                id={id}
+                value={value}
+                required={Boolean(spec.required)}
+                placeholder={spec.placeholder || undefined}
+                onChange={(e) => onChange(spec.key, e.target.value)}
+                className={classNames.input ?? 'mt-1 w-full rounded-md border border-gray-300 px-3 py-2 text-sm'}
+              />
+            ) : (
+              <input
+                id={id}
+                type={type}
+                value={value}
+                required={Boolean(spec.required)}
+                placeholder={spec.placeholder || undefined}
+                autoComplete={isSecret(spec) ? 'new-password' : 'off'}
+                onChange={(e) => onChange(spec.key, e.target.value)}
+                className={classNames.input ?? 'mt-1 w-full rounded-md border border-gray-300 px-3 py-2 text-sm'}
+              />
+            )}
+
+            {spec.help ? (
+              <p className={classNames.help ?? 'mt-1 text-xs text-gray-500'}>{spec.help}</p>
+            ) : null}
+            {warning ? (
+              <p className={classNames.warning ?? 'mt-1 text-xs text-amber-600'}>{warning}</p>
+            ) : null}
+            {error ? (
+              <p className={classNames.error ?? 'mt-1 text-xs text-red-600'} role="alert">{error}</p>
+            ) : null}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+/**
+ * Which required fields are still empty. The ONLY client-side gate.
+ *
+ * A `pattern` miss deliberately does not block: the client never decides a
+ * credential is valid — `check()` does, against the vendor. A regex that
+ * refuses a legitimate key the vendor would have accepted is a support ticket
+ * nobody can work around.
+ */
+export function missingRequired(
+  fields: ConnectorFieldSpec[],
+  values: Record<string, string>,
+): string[] {
+  return fields
+    .filter((spec) => spec.required)
+    .filter((spec) => !String(values[isSecret(spec) ? `${spec.key}__draft` : spec.key] ?? '').trim())
+    .map((spec) => spec.key);
+}
+
+/** Fields whose value does not match a declared `pattern`. WARNS, never blocks. */
+export function patternWarnings(
+  fields: ConnectorFieldSpec[],
+  values: Record<string, string>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const spec of fields) {
+    if (!spec.pattern) continue;
+    const value = String(values[isSecret(spec) ? `${spec.key}__draft` : spec.key] ?? '');
+    if (!value) continue;
+    let ok = true;
+    try {
+      ok = new RegExp(spec.pattern).test(value);
+    } catch {
+      // A pattern this build cannot compile is the catalog outrunning the
+      // bundle again. Silence beats a false warning.
+      continue;
+    }
+    if (!ok) out[spec.key] = `This does not look like the expected format for ${spec.label}.`;
+  }
+  return out;
+}

package/src/components/index.ts

@@ -4,3 +4,23 @@ export * from './EmailList';
 export * from './EventList';
 export * from './EventListItem';
 export * from './ReconsentPromptCard';
+
+// The connections layer (bd startsim-768w.22.3.4): ONE schema-driven form and
+// ONE page composer for every connector in the DB-driven catalog. Ship the
+// composer, not only the primitives — otherwise the duplication just moves up
+// one level into each app.
+export * from './CredentialSchemaForm';
+export * from './pages/ConnectionsPage';
+export type {
+  ConnectionsApi,
+  ConnectorCatalogEntry,
+  ConnectorFieldSpec,
+  Connection as FoundryConnection,
+  ConnectionPermissions,
+  ConnectionChoice,
+  ConnectionChoicePage,
+  ConnectionTarget,
+  ConnectorAction,
+  ConnectionInvokeResult,
+  ConnectionRun,
+} from './pages/types';