@startsimpli/integrations 0.2.32 → 0.2.34

package/src/__tests__/library-failure-reason.test.tsx

@@ -0,0 +1,178 @@
+/**
+ * A CARD THAT COUNTS TWENTY FAILURES AND NAMES NONE (bd startsim-ei8gm.2).
+ *
+ * THE SIXTEEN DAYS. The Tandem Library's Granola card read *"Failing — 20 syncs
+ * in a row failed, synced 16d ago"* from 2026-08-12 to 2026-08-27 and nothing a
+ * human could open said why. It was our own 256 KiB egress cap: the per-note
+ * detail response peaked at 351 KB. Diagnosable in minutes by anyone who could
+ * read the error text; sixteen days for someone who could not.
+ *
+ * `#375` fixed the SERVER half. `SubtreeConnectionsView` now derives the newest
+ * failed run's reason and sends it as `last_error`, and `surface.recent_runs`
+ * answers a real `error_message` for source runs instead of the `""` that a
+ * `getattr` default had returned for every source run ever recorded. Both
+ * facts are on prod. Nothing renders either of them, which is this bead.
+ *
+ * WHY `check_error` COULD NEVER HAVE ANSWERED IT, which is what makes this a
+ * missing field rather than a missing render. `listSources` composes its
+ * `detail` from `check_error` alone, and `check_error` is empty BY
+ * CONSTRUCTION for this class of failure: `check()` and `poll()` are different
+ * requests. Granola's check asks for `page_size=1` and passes; its poll asks
+ * for thirty notes with transcripts and aborts. The credential was fine the
+ * whole time, which is exactly why a reader re-entered a key that was never the
+ * problem.
+ *
+ * BOTH SPELLINGS, and not as a courtesy. `@startsimpli/api` camelCases response
+ * keys in the browser while a plain server-side fetch does not — the trap the
+ * three timestamps in this adapter already carry a comment about, and one that
+ * is invisible until somebody's Library quietly lies.
+ */
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+
+import { LibraryPage } from '../components/pages/LibraryPage';
+import { createCorpusApi } from '../corpus/client';
+import type { CorpusHttp } from '../corpus/client';
+import { FIXTURE_ORG } from '../corpus/fixtures';
+
+const SCOPE = { orgId: FIXTURE_ORG };
+const EMPTY_PAGE = { count: 0, next: null, previous: null, results: [] };
+
+const NOW = Date.now();
+const ago = (ms: number) => new Date(NOW - ms).toISOString();
+const SIXTEEN_DAYS_AGO = ago(16 * 24 * 60 * 60_000);
+const TEN_MINUTES_AGO = ago(10 * 60_000);
+
+/** What production held, verbatim: the connector taxonomy's own code and text. */
+const THE_REAL_REASON =
+  'connector_granola poll failed on page 1: [config_error] the response '
+  + 'exceeded the 262144-byte cap and was aborted [granola]';
+
+/**
+ * The WIRE, not the contract — rows go in exactly as central serialises them,
+ * the same convention `corpus-source-strip.test.tsx` keeps and for the same
+ * reason: a fixture must never be more generous than the server that feeds it.
+ */
+function httpOver(rows: Array<Record<string, unknown>>): CorpusHttp {
+  return {
+    async get<T>(path: string): Promise<T> {
+      if (path.includes('connections')) {
+        return { count: rows.length, next: null, previous: null, results: rows } as T;
+      }
+      return EMPTY_PAGE as T;
+    },
+  };
+}
+
+const sourcesFrom = (rows: Array<Record<string, unknown>>) =>
+  createCorpusApi({ http: httpOver(rows), scope: SCOPE }).listSources();
+
+/**
+ * THE LIVE ROW, as `/api/v1/subtree/connections/` served it on 2026-08-27.
+ * `check_error` empty, `status` connected, twenty failures counted, and — since
+ * #375 — a reason.
+ */
+const TANDEM_GRANOLA = {
+  id: 'shared-granola',
+  connector_key: 'granola',
+  connector_name: 'Granola',
+  status: 'connected',
+  check_error: '',
+  last_synced_at: SIXTEEN_DAYS_AGO,
+  last_attempt_at: TEN_MINUTES_AGO,
+  last_checked_at: TEN_MINUTES_AGO,
+  consecutive_failures: 20,
+  last_error: THE_REAL_REASON,
+};
+
+describe('listSources — the strip carries the reason central sends', () => {
+  it('reads last_error onto the card', async () => {
+    const [granola] = await sourcesFrom([TANDEM_GRANOLA]);
+
+    expect(granola.lastError).toBe(THE_REAL_REASON);
+  });
+
+  it('reads it in the camelCase spelling the browser sees', async () => {
+    const [granola] = await sourcesFrom([
+      { ...TANDEM_GRANOLA, last_error: undefined, lastError: THE_REAL_REASON },
+    ]);
+
+    expect(granola.lastError).toBe(THE_REAL_REASON);
+  });
+
+  it('says WHY rather than only how many times', async () => {
+    const [granola] = await sourcesFrom([TANDEM_GRANOLA]);
+
+    expect(granola.status).toBe('error');
+    // The count survives — "one blip" and "sixteen days" are different
+    // problems — but it is no longer the whole sentence.
+    expect(granola.detail).toMatch(/20 syncs in a row failed/);
+    expect(granola.detail).toContain('262144-byte cap');
+  });
+
+  it('still counts alone when the server sent no reason', async () => {
+    const [granola] = await sourcesFrom([{ ...TANDEM_GRANOLA, last_error: '' }]);
+
+    expect(granola.status).toBe('error');
+    expect(granola.detail).toMatch(/20 syncs in a row failed/);
+    expect(granola.lastError).toBeUndefined();
+  });
+
+  it('calls a source failing when its newest run failed, even at a zero streak', async () => {
+    // `consecutive_failures` and `last_error` have different writers: the
+    // counter lives on the connection and the reason is derived from the newest
+    // RUN. Central sends `last_error` only while that newest run is the failed
+    // one, so a reason with no streak behind it is still a failing source —
+    // and the old branch, which turned only on the counter, called it `stale`.
+    const [granola] = await sourcesFrom([
+      { ...TANDEM_GRANOLA, consecutive_failures: 0 },
+    ]);
+
+    expect(granola.status).toBe('error');
+    expect(granola.detail).toContain('262144-byte cap');
+  });
+
+  it('leaves the credential’s own verdict in charge when there is one', async () => {
+    // Two different facts and never substitutes (bd startsim-1cow). A rejected
+    // key is what the reader must act on; the run reason is the sentence for
+    // when the key is FINE and the data still is not arriving.
+    const [granola] = await sourcesFrom([
+      {
+        ...TANDEM_GRANOLA,
+        status: 'needs_reauth',
+        check_error: 'The vendor rejected this key (401). Reconnect Granola.',
+      },
+    ]);
+
+    expect(granola.detail).toBe('The vendor rejected this key (401). Reconnect Granola.');
+  });
+
+  it('never reports a reason on a source that is fine', async () => {
+    const [granola] = await sourcesFrom([
+      {
+        ...TANDEM_GRANOLA,
+        last_synced_at: ago(60_000),
+        consecutive_failures: 0,
+        last_error: '',
+      },
+    ]);
+
+    expect(granola.status).toBe('ok');
+    expect(granola.detail).toBeUndefined();
+  });
+});
+
+describe('the Library strip, rendered', () => {
+  it('prints the reason next to the corpus it was supposed to fill', async () => {
+    // The bug was VISIBLE, so the assertion is made where the reader would have
+    // seen it — not on the adapter's return value alone.
+    render(
+      <LibraryPage
+        api={createCorpusApi({ http: httpOver([TANDEM_GRANOLA]), scope: SCOPE })}
+        scope={SCOPE}
+      />,
+    );
+
+    expect(await screen.findByText(/262144-byte cap/)).toBeInTheDocument();
+  });
+});

package/src/components/pages/ConnectionsPage.tsx

@@ -47,6 +47,7 @@ import type {
   ConnectionChoicePage,
   ConnectionInvokeResult,
   ConnectionPermissions,
+  ConnectionRun,
   ConnectionTarget,
   ConnectorAction,
   ConnectorCatalogEntry,
@@ -135,6 +136,16 @@ interface BoundApi {
   invokeConnectionAction?(id: string, action: string, input: {
     destination_id: string; record_type?: string; records?: unknown[];
   }): Promise<ConnectionInvokeResult>;
+  /**
+   * RECENT ACTIVITY on both legs (bd startsim-ei8gm.2). Required on both
+   * injected interfaces and, until this bead, called by nothing — so the reason
+   * a run failed reached the payload and never a pixel.
+   *
+   * Optional HERE for the reason every other verb on this type is: an app
+   * pinned to an older `@startsimpli/api` keeps type-checking, and the card
+   * renders no control rather than a button whose handler is `undefined`.
+   */
+  connectionRuns?(id: string): Promise<{ results: ConnectionRun[] }>;
   /** Per-member governance (bd startsim-768w.22.25.8). Foundry mode only, and
       absent on an api that predates the endpoints — see `ConnectionsApi`. */
   /** The OAuth hand-off (bd startsim-768w.22.25.14/.23). Optional: an app on an
@@ -179,7 +190,16 @@ function bindApi(props: ConnectionsPageProps): BoundApi {
     ? { disconnectMemberConnection: (id: string) =>
       api.disconnectMemberConnection!(slug, id) }
     : {};
+  // Bound only when the injected client HAS it, even though `ConnectionsApi`
+  // declares it required: apps consume `@startsimpli/*` as PUBLISHED packages,
+  // so a runtime object that predates the verb is a real state the TYPE cannot
+  // see (bd startsim-ei8gm.2). Same rule as the four above — a wrapper that
+  // always exists and throws inside would render the control and fail on click.
+  const runs = api.connectionRuns
+    ? { connectionRuns: (id: string) => api.connectionRuns(slug, id) }
+    : {};
   return {
+    ...runs,
     ...memberPolicy,
     ...oauth,
     ...roster,
@@ -216,6 +236,21 @@ const DEFAULTS = {
   error: 'text-sm text-red-600',
 };
 
+/**
+ * WHICH LEG A RUN BELONGS TO, in a reader's words (bd startsim-ei8gm.2).
+ *
+ * The card merges three tables — `SourceRun`, `DestinationRun` and
+ * `DestinationWebhookEvent` — into one list, and "failed" means a different
+ * thing and needs a different action on each. Data with a fall-through to the
+ * raw key, the same rule `CAPABILITY_COPY` below states: a `kind` this bundle
+ * has never heard of renders as itself rather than vanishing from the list.
+ */
+const RUN_KIND_COPY: Record<string, string> = {
+  source_run: 'Fetched in',
+  destination_run: 'Sent out',
+  webhook_event: 'Received',
+};
+
 /**
  * WHAT AN ADMIN IS AGREEING TO, in their words rather than the wire's.
  *
@@ -1088,6 +1123,10 @@ function ConnectionCard({
   const [replacing, setReplacing] = React.useState(false);
   const [settingsOpen, setSettingsOpen] = React.useState(false);
   const [confirmingDisconnect, setConfirmingDisconnect] = React.useState(false);
+  const [activityOpen, setActivityOpen] = React.useState(false);
+  /** `null` is NOT LOADED YET, which reads differently from a connection that
+      has never run — the distinction the empty state below turns on. */
+  const [runs, setRuns] = React.useState<ConnectionRun[] | null>(null);
 
   const declared = entry?.capabilities;
   const enabled = React.useMemo(
@@ -1138,102 +1177,169 @@ function ConnectionCard({
             <p className={cn.error}>{connection.check_error}</p>
           ) : null}
         </div>
-        {canManage ? (
-          <div className="flex flex-wrap justify-end gap-2">
-            <button
-              type="button"
-              className={cn.button}
-              disabled={Boolean(busy)}
-              onClick={() => void guard('check', async () => {
-                const res = await api.checkConnection(connection.id);
-                setNotice(res.detail || (res.ok ? 'Connection is healthy.' : ''));
-                onChanged();
-              })}
-            >
-              Test
-            </button>
-            {/* THE CONTROL THIS PAGE WAS MISSING. A vendor key gets rotated —
-                that is normal operations, not an exception — and the only place
-                to put the new one was a form that creates a second account. */}
+        <div className="flex flex-wrap justify-end gap-2">
+          {/* ACTIVITY IS OUTSIDE THE MANAGE GATE, and deliberately. Reading the
+              run ledger needs `view_connections` server-side, which is what put
+              this card on the screen at all — and the person who most needs to
+              know WHY a connection is failing is often the one who cannot fix
+              it themselves. Gating the answer behind the permission to act
+              would leave them with the word "Failing" and nothing else, which
+              is the sixteen days this bead is about. */}
+          {api.connectionRuns ? (
             <button
               type="button"
               className={cn.button}
               disabled={Boolean(busy)}
               onClick={() => {
-                setConfirmingDisconnect(false);
-                setError('');
-                setReplacing((v) => !v);
+                const opening = !activityOpen;
+                setActivityOpen(opening);
+                if (!opening) return;
+                void guard('activity', async () => {
+                  const page = await api.connectionRuns!(connection.id);
+                  setRuns(page.results ?? []);
+                });
               }}
             >
-              {replacing ? 'Cancel' : 'Replace key'}
+              {activityOpen ? 'Hide activity' : 'Activity'}
             </button>
-            {/* DISCOVER -> WIRE -> FIRE is foundry-level and stays there. The
-                member router serves no choices, targets or actions at all, so
-                the control is gated on the verb EXISTING rather than on a mode
-                flag — there is no way to render a button here whose handler is
-                undefined. */}
-            {api.connectionChoices && api.connectionActions ? (
+          ) : null}
+          {canManage ? (
+            <>
               <button
                 type="button"
                 className={cn.button}
                 disabled={Boolean(busy)}
-                onClick={() => void guard('discover', async () => {
-                  const page = await api.connectionChoices!(connection.id);
-                  setChoices(page.results ?? []);
-                  const available = await api.connectionActions!(connection.id);
-                  setActions(available.results ?? []);
+                onClick={() => void guard('check', async () => {
+                  const res = await api.checkConnection(connection.id);
+                  setNotice(res.detail || (res.ok ? 'Connection is healthy.' : ''));
+                  onChanged();
                 })}
               >
-                {busy === 'discover' ? 'Loading…' : 'Workflows'}
+                Test
               </button>
-            ) : null}
-            {/* SETTINGS, which this card has never had. A connector's
-                `config_schema` ships on every catalog row and was rendered
-                exactly once — on the connect form, before the account existed.
-                After that a setting could not be changed from the product at
-                all, which for Granola means the switch deciding whether verbatim
-                recordings of people's conversations are stored was reachable
-                only by editing the database. `ReplaceKeyForm` already pointed at
-                "the connection's own settings" as if this existed.
+              {/* THE CONTROL THIS PAGE WAS MISSING. A vendor key gets rotated —
+                  that is normal operations, not an exception — and the only place
+                  to put the new one was a form that creates a second account. */}
+              <button
+                type="button"
+                className={cn.button}
+                disabled={Boolean(busy)}
+                onClick={() => {
+                  setConfirmingDisconnect(false);
+                  setError('');
+                  setReplacing((v) => !v);
+                }}
+              >
+                {replacing ? 'Cancel' : 'Replace key'}
+              </button>
+              {/* DISCOVER -> WIRE -> FIRE is foundry-level and stays there. The
+                  member router serves no choices, targets or actions at all, so
+                  the control is gated on the verb EXISTING rather than on a mode
+                  flag — there is no way to render a button here whose handler is
+                  undefined. */}
+              {api.connectionChoices && api.connectionActions ? (
+                <button
+                  type="button"
+                  className={cn.button}
+                  disabled={Boolean(busy)}
+                  onClick={() => void guard('discover', async () => {
+                    const page = await api.connectionChoices!(connection.id);
+                    setChoices(page.results ?? []);
+                    const available = await api.connectionActions!(connection.id);
+                    setActions(available.results ?? []);
+                  })}
+                >
+                  {busy === 'discover' ? 'Loading…' : 'Workflows'}
+                </button>
+              ) : null}
+              {/* SETTINGS, which this card has never had. A connector's
+                  `config_schema` ships on every catalog row and was rendered
+                  exactly once — on the connect form, before the account existed.
+                  After that a setting could not be changed from the product at
+                  all, which for Granola means the switch deciding whether verbatim
+                  recordings of people's conversations are stored was reachable
+                  only by editing the database. `ReplaceKeyForm` already pointed at
+                  "the connection's own settings" as if this existed.
 
-                GATED ON THE SETTINGS VERB, not on the general one (bd
-                startsim-sfms2). The member surface has `updateConnectionConfig`
-                and deliberately not `updateConnection`, because a personal
-                connection's config is the MEMBER's privacy boundary while its
-                name and what it may do stay the foundry's. One gate for both
-                would have made opening this control open the capability Save
-                beside it, which is a decision this change did not make. */}
-            {configFields.length && api.updateConnectionConfig ? (
+                  GATED ON THE SETTINGS VERB, not on the general one (bd
+                  startsim-sfms2). The member surface has `updateConnectionConfig`
+                  and deliberately not `updateConnection`, because a personal
+                  connection's config is the MEMBER's privacy boundary while its
+                  name and what it may do stay the foundry's. One gate for both
+                  would have made opening this control open the capability Save
+                  beside it, which is a decision this change did not make. */}
+              {configFields.length && api.updateConnectionConfig ? (
+                <button
+                  type="button"
+                  className={cn.button}
+                  disabled={Boolean(busy) || confirmingDisconnect}
+                  onClick={() => {
+                    setReplacing(false);
+                    setError('');
+                    setSettingsOpen((v) => !v);
+                  }}
+                >
+                  {settingsOpen ? 'Close settings' : 'Settings'}
+                </button>
+              ) : null}
               <button
                 type="button"
                 className={cn.button}
                 disabled={Boolean(busy) || confirmingDisconnect}
                 onClick={() => {
                   setReplacing(false);
+                  setSettingsOpen(false);
                   setError('');
-                  setSettingsOpen((v) => !v);
+                  setConfirmingDisconnect(true);
                 }}
               >
-                {settingsOpen ? 'Close settings' : 'Settings'}
+                Disconnect
               </button>
-            ) : null}
-            <button
-              type="button"
-              className={cn.button}
-              disabled={Boolean(busy) || confirmingDisconnect}
-              onClick={() => {
-                setReplacing(false);
-                setSettingsOpen(false);
-                setError('');
-                setConfirmingDisconnect(true);
-              }}
-            >
-              Disconnect
-            </button>
-          </div>
-        ) : null}
+            </>
+          ) : null}
+        </div>
       </div>
 
+      {activityOpen ? (
+        <div className="mt-3 space-y-2 border-t pt-3" role="group"
+             aria-label="Recent activity">
+          {/* THE FIELD NOTHING HAS EVER READ. `ConnectionRun.error_message` has
+              been declared in this package's types since the endpoint existed;
+              until #375 the server answered `""` for every source run ever
+              recorded, and even after it did not, no component asked. A failed
+              run rendered as a status word, which is a fact the reader already
+              had from the card above it.
+
+              RENDERED AS THE SERVER WROTE IT. The text is scrubbed against this
+              connection's stored credential and the platform app_secret before
+              it leaves Django (`surface.py::_reason_reader`), and a reason that
+              could not be scrubbed arrives as a sentence saying so. There is
+              one redaction path in this estate and it is not in the browser —
+              which does not hold the secrets to run it. */}
+          {busy === 'activity' && runs === null ? (
+            <p className={cn.muted}>Loading recent activity…</p>
+          ) : null}
+          {runs !== null && runs.length === 0 ? (
+            <p className={cn.muted}>No runs yet for this connection.</p>
+          ) : null}
+          {(runs ?? []).map((run) => (
+            <div key={run.id} data-run={run.id}>
+              <p className={cn.muted}>
+                <span className="font-medium text-gray-900">
+                  {RUN_KIND_COPY[run.kind] ?? run.kind}
+                </span>
+                {run.name ? ` · ${run.name}` : ''}
+                {` · ${run.status}`}
+                {run.occurred_at ? ` · ${new Date(run.occurred_at).toLocaleString()}` : ''}
+              </p>
+              {run.error_message ? (
+                <p className={cn.error}>{run.error_message}</p>
+              ) : null}
+            </div>
+          ))}
+        </div>
+      ) : null}
+
       {settingsOpen ? (
         <ConnectionSettingsForm
           api={api}