@startsimpli/integrations 0.1.0 → 0.1.4

package/src/components/pages/ConnectionsPage.tsx

@@ -0,0 +1,610 @@
+/**
+ * The connections surface, as one composer (bd startsim-768w.22.3.4).
+ *
+ * `<ConnectionsPage api={apiClient.foundry} foundrySlug={slug} />` is the whole
+ * integration. An app owns theme classNames and a ten-line wrapper and nothing
+ * else — no context, no provider, no per-app copy of this logic. Same shape as
+ * `TeamSettingsPage`, and for the same reason: shipping primitives without the
+ * page-level composer just moves the duplication up one level.
+ *
+ * WHAT IT RENDERS, in the order the job actually happens:
+ *
+ *   1. connected accounts, each saying what it is and whether it is healthy
+ *   2. the catalog — everything connectable, including rows that cannot load
+ *   3. per connection: DISCOVER what the credential reaches -> WIRE a choice ->
+ *      CONFIRM the derived config -> FIRE it, and the run history of both legs
+ *
+ * Step 3 is the product. A pasted webhook URL is the thing discovery replaces,
+ * and the CONFIRM step exists because a derived URL is a guess about the
+ * vendor's own settings until a human agrees with it.
+ *
+ * NOTHING HERE NAMES A VENDOR. Every difference between two vendors arrives as
+ * data — the field schema, the capability list, the choice rows and their
+ * reasons. A `if (connector === ...)` in this file would undo the DB-driven
+ * catalog the backend was rebuilt around.
+ */
+import * as React from 'react';
+
+import {
+  CredentialSchemaForm,
+  isSecret,
+  missingRequired,
+  patternWarnings,
+  schemaFields,
+} from '../CredentialSchemaForm';
+import type {
+  Connection,
+  ConnectionChoice,
+  ConnectionPermissions,
+  ConnectionTarget,
+  ConnectorAction,
+  ConnectorCatalogEntry,
+  ConnectionsApi,
+} from './types';
+
+export interface ConnectionsPageProps {
+  api: ConnectionsApi;
+  foundrySlug: string;
+  classNames?: Partial<Record<
+    'root' | 'section' | 'heading' | 'card' | 'button' | 'muted' | 'error', string
+  >>;
+}
+
+const DEFAULTS = {
+  root: 'space-y-8',
+  section: 'space-y-3',
+  heading: 'text-lg font-semibold text-gray-900',
+  card: 'rounded-lg border border-gray-200 p-4',
+  button: 'rounded-md bg-gray-900 px-3 py-1.5 text-sm font-medium text-white disabled:opacity-50',
+  muted: 'text-sm text-gray-500',
+  error: 'text-sm text-red-600',
+};
+
+/**
+ * WHAT AN ADMIN IS AGREEING TO, in their words rather than the wire's.
+ *
+ * Data, not a branch: an unknown key falls through to the key itself, because
+ * the capability vocabulary lives in the connector package and will outrun this
+ * bundle exactly the way the credential schema does. A capability this build has
+ * never heard of must render as a choice, not vanish from the list.
+ */
+const CAPABILITY_COPY: Record<string, string> = {
+  poll: 'Fetch new records on a schedule',
+  webhook_in: 'Receive events pushed to us',
+  action: 'Let us run actions in this account',
+  writeback_credential: 'Issue a token this vendor uses to call us',
+};
+
+/** A refusal must read as a refusal, not as an empty page. */
+function readFailureMessage(err: unknown): string {
+  const status = (err as { status?: number })?.status;
+  if (status === 403) {
+    return 'You do not have access to this foundry’s connections. Ask an admin for the connections permission.';
+  }
+  if (status === 401) return 'Your session has expired. Sign in again.';
+  const message = (err as { message?: string })?.message;
+  return message || 'Could not load connections.';
+}
+
+export function ConnectionsPage({ api, foundrySlug, classNames = {} }: ConnectionsPageProps) {
+  const cn = { ...DEFAULTS, ...classNames };
+
+  const [catalog, setCatalog] = React.useState<ConnectorCatalogEntry[]>([]);
+  const [connections, setConnections] = React.useState<Connection[]>([]);
+  const [permissions, setPermissions] = React.useState<ConnectionPermissions>({
+    view: true, manage: false, issue_tokens: false,
+  });
+  const [loadError, setLoadError] = React.useState<string>('');
+  const [loading, setLoading] = React.useState(true);
+
+  const reload = React.useCallback(async () => {
+    setLoading(true);
+    try {
+      const [cat, conns] = await Promise.all([
+        api.connectorCatalog(foundrySlug),
+        api.connections(foundrySlug),
+      ]);
+      setCatalog(cat.results ?? []);
+      setConnections(conns.results ?? []);
+      setPermissions(conns.permissions ?? { view: true, manage: false, issue_tokens: false });
+      setLoadError('');
+    } catch (err) {
+      setLoadError(readFailureMessage(err));
+    } finally {
+      setLoading(false);
+    }
+  }, [api, foundrySlug]);
+
+  React.useEffect(() => { void reload(); }, [reload]);
+
+  if (loadError) {
+    return <p className={cn.error} role="alert">{loadError}</p>;
+  }
+
+  return (
+    <div className={cn.root}>
+      <section className={cn.section}>
+        <h2 className={cn.heading}>Connected accounts</h2>
+        {loading && connections.length === 0 ? <p className={cn.muted}>Loading…</p> : null}
+        {!loading && connections.length === 0 ? (
+          <p className={cn.muted}>Nothing connected yet.</p>
+        ) : null}
+        {connections.map((connection) => (
+          <ConnectionCard
+            key={connection.id}
+            api={api}
+            foundrySlug={foundrySlug}
+            connection={connection}
+            // What the CONNECTOR declares, so the card can offer a capability
+            // this connection does not have yet — which is the only way an
+            // account connected before the picker existed ever gets one.
+            declared={
+              catalog.find((entry) => entry.key === connection.connector_key)?.capabilities
+            }
+            canManage={permissions.manage}
+            classNames={cn}
+            onChanged={reload}
+          />
+        ))}
+      </section>
+
+      <section className={cn.section}>
+        <h2 className={cn.heading}>Available connectors</h2>
+        {catalog.map((entry) => (
+          <CatalogCard
+            key={entry.key}
+            api={api}
+            foundrySlug={foundrySlug}
+            entry={entry}
+            canManage={permissions.manage}
+            classNames={cn}
+            onConnected={reload}
+          />
+        ))}
+      </section>
+    </div>
+  );
+}
+
+// --------------------------------------------------------------------------
+//  the capability choice (bd startsim-768w.22.22)
+// --------------------------------------------------------------------------
+
+/**
+ * WHICH VERBS THIS ACCOUNT IS ALLOWED — the control this page did not have.
+ *
+ * `POST /connections/` and `PATCH /connections/<id>/` have both accepted
+ * `capabilities_enabled[]` since the endpoints were designed. Nothing here ever
+ * sent one, so every connection made through the product was stored with an
+ * EMPTY list, and an empty list enables nothing: the card goes green on a real
+ * `check()` and can then do none of the things it advertises. That is how a
+ * connected Granola account on a live foundry ingested nothing forever.
+ *
+ * Rendered from `entry.capabilities` — the connector's own declaration, off the
+ * catalog row — so a new vendor's verbs appear here with no code change, and a
+ * verb this build has never heard of still renders.
+ */
+function CapabilityPicker({
+  scope, declared, selected, disabled, idPrefix, onToggle, classNames: cn, children,
+}: {
+  scope: 'catalog' | 'connection';
+  declared: string[];
+  selected: string[];
+  disabled: boolean;
+  idPrefix: string;
+  onToggle: (capability: string, on: boolean) => void;
+  classNames: typeof DEFAULTS;
+  /** Whatever COMMITS the choice — inline, so the control and the thing that
+      saves it are one region for a screen reader and for a test. */
+  children?: React.ReactNode;
+}) {
+  if (declared.length === 0) return null;
+  return (
+    <fieldset data-capabilities={scope} className="mt-3 space-y-1 border-0 p-0">
+      <legend className="text-sm font-medium text-gray-900">What this account may do</legend>
+      {declared.map((capability) => {
+        const id = `${idPrefix}-cap-${capability}`;
+        return (
+          <label key={capability} htmlFor={id} className="flex items-start gap-2 text-sm">
+            <input
+              id={id}
+              type="checkbox"
+              value={capability}
+              className="mt-0.5"
+              checked={selected.includes(capability)}
+              disabled={disabled}
+              onChange={(event) => onToggle(capability, event.target.checked)}
+            />
+            <span>
+              <span className="text-gray-900">{capability}</span>
+              <span className={`ml-2 ${cn.muted}`}>
+                {CAPABILITY_COPY[capability] ?? ''}
+              </span>
+            </span>
+          </label>
+        );
+      })}
+      {children}
+    </fieldset>
+  );
+}
+
+/** Declaration order is the render order, and the wire order. */
+function orderCapabilities(declared: string[], selected: Iterable<string>): string[] {
+  const set = new Set(selected);
+  return declared.filter((capability) => set.has(capability));
+}
+
+// --------------------------------------------------------------------------
+//  catalog
+// --------------------------------------------------------------------------
+
+function CatalogCard({
+  api, foundrySlug, entry, canManage, classNames: cn, onConnected,
+}: {
+  api: ConnectionsApi;
+  foundrySlug: string;
+  entry: ConnectorCatalogEntry;
+  canManage: boolean;
+  classNames: typeof DEFAULTS;
+  onConnected: () => void;
+}) {
+  const [open, setOpen] = React.useState(false);
+  const [values, setValues] = React.useState<Record<string, string>>({});
+  const [busy, setBusy] = React.useState(false);
+  const [error, setError] = React.useState('');
+  // Every declared capability starts ON. Not because "on" is a safe default in
+  // general, but because the alternative here is a connection that can do
+  // nothing — and the list is right there, unchecked with one click, before
+  // anything is saved. The privacy control that is genuinely opt-in lives one
+  // level down (a connector's own config, e.g. whether a poll fetches meeting
+  // transcript bytes at all) and is unaffected by this box.
+  const [capabilities, setCapabilities] = React.useState<string[]>(entry.capabilities);
+
+  const credentialFields = schemaFields(entry.credential_schema);
+  const configFields = schemaFields(entry.config_schema);
+  const fields = [...credentialFields, ...configFields];
+  const warnings = patternWarnings(fields, values);
+  const missing = missingRequired(fields, values);
+
+  async function submit() {
+    setBusy(true);
+    setError('');
+    try {
+      const credentials: Record<string, unknown> = {};
+      const config: Record<string, unknown> = {};
+      for (const spec of credentialFields) {
+        const v = values[isSecret(spec) ? `${spec.key}__draft` : spec.key];
+        if (v) credentials[spec.key] = v;
+      }
+      for (const spec of configFields) {
+        const v = values[isSecret(spec) ? `${spec.key}__draft` : spec.key];
+        if (v) config[spec.key] = v;
+      }
+      await api.connect(foundrySlug, {
+        connector_key: entry.key, name: entry.name, credentials, config,
+        // Always sent. Leaving it off is what wrote the inert cards.
+        capabilities_enabled: orderCapabilities(entry.capabilities, capabilities),
+      });
+      setOpen(false);
+      setValues({});
+      setCapabilities(entry.capabilities);
+      onConnected();
+    } catch (err) {
+      // The server's typed answer, verbatim. It already scrubbed itself of the
+      // values just submitted, and it knows things the client cannot guess —
+      // "the vendor rejected this key" is not "the network failed".
+      setError((err as { message?: string })?.message || 'Could not connect.');
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <div className={cn.card}>
+      <div className="flex items-start justify-between gap-4">
+        <div>
+          <p className="font-medium text-gray-900">{entry.name}</p>
+          <p className={cn.muted}>{entry.description}</p>
+          {entry.capabilities.length ? (
+            <p className="mt-1 text-xs text-gray-400">{entry.capabilities.join(' · ')}</p>
+          ) : null}
+          {/* A row whose class will not load says WHY and stays visible. The
+              catalog is data and outruns deployed bundles; blanking the menu
+              because one vendor's module moved is the failure this prevents. */}
+          {!entry.availability.available ? (
+            <p className={cn.error}>Unavailable: {entry.availability.reason}</p>
+          ) : null}
+        </div>
+        {canManage && entry.availability.available ? (
+          <button type="button" className={cn.button} onClick={() => setOpen((v) => !v)}>
+            {open ? 'Cancel' : 'Connect'}
+          </button>
+        ) : null}
+      </div>
+
+      {open ? (
+        <div className="mt-4 space-y-3">
+          <CredentialSchemaForm
+            fields={fields}
+            values={values}
+            warnings={warnings}
+            idPrefix={`connect-${entry.key}`}
+            onChange={(key, value) => {
+              const spec = fields.find((f) => f.key === key);
+              setValues((prev) => ({
+                ...prev, [spec && isSecret(spec) ? `${key}__draft` : key]: value,
+              }));
+            }}
+          />
+          <CapabilityPicker
+            scope="catalog"
+            declared={entry.capabilities}
+            selected={capabilities}
+            disabled={busy}
+            idPrefix={`connect-${entry.key}`}
+            onToggle={(capability, on) => setCapabilities((prev) => (
+              on ? [...prev, capability] : prev.filter((c) => c !== capability)
+            ))}
+            classNames={cn}
+          />
+          {/* The server refuses an empty list with a 400 rather than storing a
+              card that can do nothing. Saying so here costs the admin a round
+              trip instead of a confusing error. */}
+          {entry.capabilities.length > 0 && capabilities.length === 0 ? (
+            <p className={cn.error}>
+              Enable at least one — a connection with nothing enabled can do nothing.
+            </p>
+          ) : null}
+          {error ? <p className={cn.error} role="alert">{error}</p> : null}
+          <button
+            type="button"
+            className={cn.button}
+            disabled={
+              busy
+              || missing.length > 0
+              || (entry.capabilities.length > 0 && capabilities.length === 0)
+            }
+            onClick={() => void submit()}
+          >
+            {busy ? 'Testing…' : 'Test and save'}
+          </button>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+// --------------------------------------------------------------------------
+//  a connected account: discover -> wire -> confirm -> fire
+// --------------------------------------------------------------------------
+
+function ConnectionCard({
+  api, foundrySlug, connection, declared, canManage, classNames: cn, onChanged,
+}: {
+  api: ConnectionsApi;
+  foundrySlug: string;
+  connection: Connection;
+  declared?: string[];
+  canManage: boolean;
+  classNames: typeof DEFAULTS;
+  onChanged: () => void;
+}) {
+  const [choices, setChoices] = React.useState<ConnectionChoice[] | null>(null);
+  const [target, setTarget] = React.useState<ConnectionTarget | null>(null);
+  const [actions, setActions] = React.useState<ConnectorAction[]>([]);
+  const [busy, setBusy] = React.useState('');
+  const [error, setError] = React.useState('');
+  const [notice, setNotice] = React.useState('');
+
+  const enabled = React.useMemo(
+    () => connection.capabilities_enabled ?? [], [connection.capabilities_enabled]);
+  // The catalog's declaration first, then anything this connection holds that
+  // the catalog no longer offers. A capability an admin cannot SEE is one they
+  // cannot turn off, and a catalog row that will not load must not blank the
+  // card's own state.
+  const offered = React.useMemo(() => {
+    const seen = new Set<string>();
+    return [...(declared ?? []), ...enabled].filter((capability) => {
+      if (seen.has(capability)) return false;
+      seen.add(capability);
+      return true;
+    });
+  }, [declared, enabled]);
+  const [selected, setSelected] = React.useState<string[]>(enabled);
+  React.useEffect(() => { setSelected(enabled); }, [enabled]);
+
+  const pending = orderCapabilities(offered, selected);
+  const dirty = pending.join(',') !== orderCapabilities(offered, enabled).join(',');
+
+  async function guard(label: string, run: () => Promise<void>) {
+    setBusy(label);
+    setError('');
+    try {
+      await run();
+    } catch (err) {
+      setError((err as { message?: string })?.message || 'That did not work.');
+    } finally {
+      setBusy('');
+    }
+  }
+
+  return (
+    <div className={cn.card}>
+      <div className="flex items-start justify-between gap-4">
+        <div>
+          <p className="font-medium text-gray-900">{connection.name}</p>
+          <p className={cn.muted}>
+            {connection.connector_name}
+            {connection.account_label ? ` · ${connection.account_label}` : ''}
+          </p>
+          <p className="mt-1 text-xs text-gray-400">{connection.status}</p>
+          {connection.check_error ? (
+            <p className={cn.error}>{connection.check_error}</p>
+          ) : null}
+        </div>
+        {canManage ? (
+          <div className="flex gap-2">
+            <button
+              type="button"
+              className={cn.button}
+              disabled={Boolean(busy)}
+              onClick={() => void guard('check', async () => {
+                const res = await api.checkConnection(foundrySlug, connection.id);
+                setNotice(res.detail || (res.ok ? 'Connection is healthy.' : ''));
+                onChanged();
+              })}
+            >
+              Test
+            </button>
+            <button
+              type="button"
+              className={cn.button}
+              disabled={Boolean(busy)}
+              onClick={() => void guard('discover', async () => {
+                const page = await api.connectionChoices(foundrySlug, connection.id);
+                setChoices(page.results ?? []);
+                const available = await api.connectionActions(foundrySlug, connection.id);
+                setActions(available.results ?? []);
+              })}
+            >
+              {busy === 'discover' ? 'Loading…' : 'Workflows'}
+            </button>
+          </div>
+        ) : null}
+      </div>
+
+      {/* THE FIX FOR THE CARDS THAT ALREADY EXIST. A connection written before
+          the connect form asked holds an empty list and can do nothing; the
+          connect form can never reach it. Turning `poll` on here is what makes
+          the server create the scheduled ingest leg. */}
+      <CapabilityPicker
+        scope="connection"
+        declared={offered}
+        selected={selected}
+        disabled={!canManage || Boolean(busy)}
+        idPrefix={`connection-${connection.id}`}
+        onToggle={(capability, on) => setSelected((prev) => (
+          on ? [...prev, capability] : prev.filter((c) => c !== capability)
+        ))}
+        classNames={cn}
+      >
+        {canManage ? (
+          <div className="mt-2 flex items-center gap-3">
+            <button
+              type="button"
+              className={cn.button}
+              disabled={!dirty || pending.length === 0 || Boolean(busy)}
+              onClick={() => void guard('capabilities', async () => {
+                await api.updateConnection(foundrySlug, connection.id, {
+                  capabilities_enabled: pending,
+                });
+                setNotice('Saved.');
+                onChanged();
+              })}
+            >
+              {busy === 'capabilities' ? 'Saving…' : 'Save'}
+            </button>
+            {pending.length === 0 ? (
+              <span className={cn.error}>
+                Enable at least one, or disconnect the account.
+              </span>
+            ) : null}
+          </div>
+        ) : null}
+      </CapabilityPicker>
+
+      {notice ? <p className={cn.muted}>{notice}</p> : null}
+      {error ? <p className={cn.error} role="alert">{error}</p> : null}
+
+      {choices ? (
+        <div className="mt-4 space-y-2">
+          <p className="text-sm font-medium text-gray-900">What this account can reach</p>
+          {choices.length === 0 ? <p className={cn.muted}>Nothing to wire yet.</p> : null}
+          {choices.map((choice) => (
+            <div key={choice.id} className="flex items-start justify-between gap-3 border-t pt-2">
+              <div>
+                <p className={choice.selectable ? 'text-sm text-gray-900' : 'text-sm text-gray-400'}>
+                  {choice.label}
+                </p>
+                {/* An unpickable row is GREYED and says why — never dropped. A
+                    picker that hides them looks broken with no way to tell. */}
+                {!choice.selectable ? (
+                  <p className="text-xs text-gray-500">
+                    {choice.reason}
+                    {choice.remediation ? ` — ${choice.remediation}` : ''}
+                  </p>
+                ) : null}
+              </div>
+              {choice.selectable ? (
+                <button
+                  type="button"
+                  className={cn.button}
+                  disabled={Boolean(busy)}
+                  onClick={() => void guard('wire', async () => {
+                    setTarget(await api.wireTarget(foundrySlug, connection.id, {
+                      choice_id: choice.id,
+                    }));
+                  })}
+                >
+                  Wire
+                </button>
+              ) : null}
+            </div>
+          ))}
+        </div>
+      ) : null}
+
+      {target ? (
+        <div className="mt-4 space-y-2 border-t pt-3">
+          <p className="text-sm font-medium text-gray-900">{target.name}</p>
+          {/* The admin CONFIRMS what discovery proposed. Showing the derived
+              config is not a detail — nobody can confirm a URL they were never
+              shown, and a confidently wrong one only fails at 3am. */}
+          <pre className="overflow-x-auto rounded bg-gray-50 p-2 text-xs text-gray-700">
+            {JSON.stringify(target.destination_config, null, 2)}
+          </pre>
+          {!target.verified ? (
+            <button
+              type="button"
+              className={cn.button}
+              disabled={Boolean(busy)}
+              onClick={() => void guard('confirm', async () => {
+                setTarget(await api.confirmTarget(foundrySlug, connection.id, target.id));
+              })}
+            >
+              Confirm this target
+            </button>
+          ) : (
+            <div className="flex flex-wrap gap-2">
+              <p className={cn.muted}>Confirmed.</p>
+              {actions.map((available) => (
+                <button
+                  key={available.name}
+                  type="button"
+                  className={cn.button}
+                  disabled={Boolean(busy)}
+                  onClick={() => void guard('invoke', async () => {
+                    const result = await api.invokeConnectionAction(
+                      foundrySlug, connection.id, available.name,
+                      { destination_id: target.id, records: [] },
+                    );
+                    // `accepted` is not `completed`. Saying "done" here would
+                    // render a success the vendor never reported.
+                    setNotice(
+                      result.run_status === 'completed'
+                        ? 'Finished.'
+                        : `Accepted — run is ${result.run_status}.`,
+                    );
+                  })}
+                >
+                  {available.label}
+                </button>
+              ))}
+            </div>
+          )}
+        </div>
+      ) : null}
+    </div>
+  );
+}