@startsimpli/integrations 0.1.0 → 0.1.3

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';

package/src/components/pages/ConnectionsPage.tsx

@@ -0,0 +1,426 @@
+/**
+ * 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',
+};
+
+/** 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}
+            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>
+  );
+}
+
+// --------------------------------------------------------------------------
+//  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('');
+
+  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,
+      });
+      setOpen(false);
+      setValues({});
+      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,
+              }));
+            }}
+          />
+          {error ? <p className={cn.error} role="alert">{error}</p> : null}
+          <button
+            type="button"
+            className={cn.button}
+            disabled={busy || missing.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, canManage, classNames: cn, onChanged,
+}: {
+  api: ConnectionsApi;
+  foundrySlug: string;
+  connection: Connection;
+  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('');
+
+  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>
+
+      {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>
+  );
+}