@startsimpli/integrations 0.2.22 → 0.2.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.22",
+  "version": "0.2.24",
   "description": "Provider-agnostic types, API clients, hooks, and UI primitives for email + calendar integrations across StartSimpli apps.",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -48,7 +48,7 @@
     "react-dom": "^19.0.0",
     "typescript": "^6.0.0",
     "vitest": "^3.0.0",
-    "@startsimpli/llm": "0.4.16"
+    "@startsimpli/llm": "0.4.18"
   },
   "scripts": {
     "type-check": "tsc --noEmit",

package/src/__tests__/connections.test.tsx

@@ -997,3 +997,113 @@ describe('ConnectionsPage — foundry mode is untouched by personal mode', () =>
     expect(within(section).getByRole('button', { name: /^Save$/i })).toBeInTheDocument();
   });
 });
+
+// --------------------------------------------------------------------------
+//  the members' roster: a verb only where it still does something
+//  (bd startsim-768w.22.25.19)
+// --------------------------------------------------------------------------
+
+/**
+ * One row per status, because the whole defect was a button that never read
+ * the status. `disabled` is the row AFTER a disconnect — key deleted, tokens
+ * revoked, fetches stopped. `error` and `needs_reauth` still hold a stored
+ * credential and a live poll leg, and they are the rows an admin offboarding
+ * somebody most needs to cut, so the suppression has to be narrow enough to
+ * leave them alone.
+ */
+const MEMBER_ROWS = [
+  {
+    id: 'm-live', owner: { id: 'u1', email: 'ana@acme.test', name: 'Ana' },
+    connector_key: 'n8n', connector_name: 'n8n', name: 'Ana n8n',
+    account_label: 'ana@acme.test', status: 'connected', health: 'ok',
+  },
+  {
+    id: 'm-broken', owner: { id: 'u2', email: 'bo@acme.test', name: 'Bo' },
+    connector_key: 'granola', connector_name: 'Granola', name: 'Bo Granola',
+    account_label: 'bo@acme.test', status: 'error', health: 'failing',
+    check_error: 'Vendor said 401',
+  },
+  {
+    id: 'm-stale', owner: { id: 'u3', email: 'cy@acme.test', name: 'Cy' },
+    connector_key: 'granola', connector_name: 'Granola', name: 'Cy Granola',
+    account_label: 'cy@acme.test', status: 'needs_reauth', health: 'expired',
+  },
+  {
+    id: 'm-gone', owner: { id: 'u4', email: 'di@acme.test', name: 'Di' },
+    connector_key: 'n8n', connector_name: 'n8n', name: 'Di n8n',
+    account_label: 'di@acme.test', status: 'disabled', health: 'disconnected',
+  },
+];
+
+function rosterApi(overrides: Partial<ConnectionsApi> = {}): ConnectionsApi {
+  return stubApi({
+    memberConnections: vi.fn().mockResolvedValue({
+      results: MEMBER_ROWS,
+      permissions: { view: true, manage: true, issue_tokens: false },
+    }),
+    disconnectMemberConnection: vi.fn().mockResolvedValue(undefined),
+    ...overrides,
+  } as Partial<ConnectionsApi>);
+}
+
+/** The card element for one member row, by the id the roster stamps on it. */
+async function memberCard(id: string): Promise<HTMLElement> {
+  return waitFor(() => {
+    const el = document.querySelector<HTMLElement>(`div[data-member-connection="${id}"]`);
+    if (!el) throw new Error(`no member row rendered for ${id}`);
+    return el;
+  });
+}
+
+describe('MemberConnectionRoster — Disconnect is not offered twice', () => {
+  it('does NOT offer Disconnect on a row that is already disconnected', async () => {
+    render(<ConnectionsPage api={rosterApi()} foundrySlug="acme" />);
+    const gone = await memberCard('m-gone');
+    expect(within(gone).queryByRole('button', { name: /Disconnect/i })).toBeNull();
+  });
+
+  it('says the account is gone and that only the member can bring it back', async () => {
+    // The row STAYS. Who used to hold a pipe into this foundry is the answer an
+    // offboarding review is looking for; hiding it would lose that.
+    render(<ConnectionsPage api={rosterApi()} foundrySlug="acme" />);
+    const gone = await memberCard('m-gone');
+    const note = gone.querySelector('[data-member-connection-disconnected]');
+    expect(note).not.toBeNull();
+    expect(note!.textContent).toMatch(/Disconnected\./);
+    expect(note!.textContent).toMatch(/di@acme\.test has to connect with n8n again/);
+  });
+
+  it('never claims a deleted key "cannot be undone"', async () => {
+    // The exact copy the bead objects to, over a key that is already gone.
+    render(<ConnectionsPage api={rosterApi()} foundrySlug="acme" />);
+    const gone = await memberCard('m-gone');
+    expect(within(gone).queryByText(/cannot be undone/i)).toBeNull();
+    expect(within(gone).queryByText(/stored key is deleted and their/i)).toBeNull();
+  });
+
+  it('KEEPS Disconnect on a failing row, whose key is still stored', async () => {
+    render(<ConnectionsPage api={rosterApi()} foundrySlug="acme" />);
+    const broken = await memberCard('m-broken');
+    expect(within(broken).getByRole('button', { name: /^Disconnect$/i }))
+      .toBeInTheDocument();
+  });
+
+  it('KEEPS Disconnect on a needs_reauth row, whose poll leg is still live', async () => {
+    render(<ConnectionsPage api={rosterApi()} foundrySlug="acme" />);
+    const stale = await memberCard('m-stale');
+    expect(within(stale).getByRole('button', { name: /^Disconnect$/i }))
+      .toBeInTheDocument();
+  });
+
+  it('still cuts a connected row, naming the person before it does', async () => {
+    const api = rosterApi();
+    render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    const live = await memberCard('m-live');
+    await userEvent.click(within(live).getByRole('button', { name: /^Disconnect$/i }));
+    const prompt = within(live).getByText(/cannot be undone/i);
+    expect(prompt.textContent).toContain('ana@acme.test');
+    await userEvent.click(within(live).getByRole('button', { name: /Yes, disconnect/i }));
+    await waitFor(() =>
+      expect(api.disconnectMemberConnection).toHaveBeenCalledWith('acme', 'm-live'));
+  });
+});

package/src/__tests__/corpus-freshness.test.tsx

@@ -0,0 +1,243 @@
+/**
+ * THREE FACTS, NOT ONE (bd startsim-1cow).
+ *
+ * `SubtreeConnectionsView` in central annotates its rows with three deliberately
+ * distinct timestamps and says so in the source:
+ *
+ *   last_synced_at   the last run that actually brought data in
+ *   last_attempt_at  the last run of ANY outcome — so "it tried ten minutes ago
+ *                    and failed" is expressible, and a card cannot read
+ *                    "nothing yet" while it is in fact failing on a schedule
+ *   last_checked_at  when the CREDENTIAL was last verified, "a far more
+ *                    optimistic fact than either and never used as a stand-in"
+ *
+ * `listSources()` used to coalesce all three with `??`. Central sends
+ * `last_synced_at: null` for a connection that has never delivered a record, so
+ * the chain fell straight through to `last_checked_at` and a connection whose
+ * KEY was verified five minutes ago rendered as data that ARRIVED five minutes
+ * ago. That is the one thing a freshness promise may not do.
+ *
+ * The tenant proxies this endpoint VERBATIM — `tenant-starter`'s
+ * `ConnectionsView` returns `SubtreeClient.connections()` untouched, and that
+ * client is a plain `json.loads` of the central body — so every field asserted
+ * below really is on the wire this adapter reads, in the snake_case central
+ * wrote it. `@startsimpli/api`'s fetch wrapper camelCases response keys in the
+ * browser and not from a server-side fetch, which is why every field is read in
+ * BOTH spellings and both spellings are exercised here.
+ */
+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: [] };
+
+// Anchored on the real clock so the staleness window is decided by the offset
+// and never by what day the suite happens to run.
+const NOW = Date.now();
+const ago = (ms: number) => new Date(NOW - ms).toISOString();
+const FIVE_MINUTES_AGO = ago(5 * 60_000);
+const TEN_MINUTES_AGO = ago(10 * 60_000);
+const AN_HOUR_AGO = ago(60 * 60_000);
+const A_WEEK_AGO = ago(7 * 24 * 60 * 60_000);
+
+/**
+ * The WIRE, not the contract. Rows go in exactly as central serialises them so a
+ * fixture can 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;
+    },
+  };
+}
+
+function sourcesFrom(rows: Array<Record<string, unknown>>, staleAfterHours = 26) {
+  const api = createCorpusApi({ http: httpOver(rows), scope: SCOPE, staleAfterHours });
+  return api.listSources();
+}
+
+/** A connected row with nothing wrong with it and nothing delivered by it. */
+const CONNECTED = {
+  id: 'c1',
+  connector_key: 'granola',
+  connector_name: 'Granola',
+  status: 'connected',
+  check_error: '',
+  last_synced_at: null,
+  last_attempt_at: null,
+  last_checked_at: null,
+  consecutive_failures: 0,
+};
+
+describe('listSources — a verified credential is not delivered data', () => {
+  it('reports never for a connection whose key checked out but which has never synced', async () => {
+    const [source] = await sourcesFrom([
+      { ...CONNECTED, last_checked_at: FIVE_MINUTES_AGO },
+    ]);
+
+    expect(source.status).toBe('never');
+    // The stand-in central forbids: `last_checked_at` may not become the sync
+    // time. Asserting the status alone would let the timestamp keep leaking into
+    // the visible "synced 5 min ago" line.
+    expect(source.lastSyncedAt).toBeNull();
+    expect(source.lastCheckedAt).toBe(FIVE_MINUTES_AGO);
+    expect(source.detail).toMatch(/nothing has arrived/i);
+  });
+
+  it('reports never in the camelCase spelling too, which is what the browser sees', async () => {
+    const [source] = await sourcesFrom([
+      {
+        id: 'c1',
+        connectorKey: 'granola',
+        connectorName: 'Granola',
+        status: 'connected',
+        checkError: '',
+        lastSyncedAt: null,
+        lastAttemptAt: null,
+        lastCheckedAt: FIVE_MINUTES_AGO,
+        consecutiveFailures: 0,
+      },
+    ]);
+
+    expect(source.status).toBe('never');
+    expect(source.lastSyncedAt).toBeNull();
+    expect(source.lastCheckedAt).toBe(FIVE_MINUTES_AGO);
+  });
+
+  it('keeps the three facts apart when all three are present and different', async () => {
+    const [source] = await sourcesFrom([
+      {
+        ...CONNECTED,
+        last_synced_at: AN_HOUR_AGO,
+        last_attempt_at: AN_HOUR_AGO,
+        last_checked_at: FIVE_MINUTES_AGO,
+      },
+    ]);
+
+    expect(source.lastSyncedAt).toBe(AN_HOUR_AGO);
+    expect(source.lastAttemptAt).toBe(AN_HOUR_AGO);
+    expect(source.lastCheckedAt).toBe(FIVE_MINUTES_AGO);
+    expect(source.status).toBe('ok');
+  });
+
+  it('measures staleness against the SYNC, never against the credential check', async () => {
+    const [source] = await sourcesFrom([
+      {
+        ...CONNECTED,
+        last_synced_at: A_WEEK_AGO,
+        last_attempt_at: A_WEEK_AGO,
+        // Checked minutes ago and still a week stale — the credential being fine
+        // is exactly why nobody noticed.
+        last_checked_at: FIVE_MINUTES_AGO,
+      },
+    ]);
+
+    expect(source.status).toBe('stale');
+    expect(source.lastSyncedAt).toBe(A_WEEK_AGO);
+  });
+});
+
+describe('listSources — it tried and it failed', () => {
+  it('does not say "nothing yet" for a connection that is failing on a schedule', async () => {
+    const [source] = await sourcesFrom([
+      {
+        ...CONNECTED,
+        last_synced_at: null,
+        // A run FINISHED ten minutes ago and none has ever finished well, which
+        // is exactly how central expresses a failed run.
+        last_attempt_at: TEN_MINUTES_AGO,
+        last_checked_at: FIVE_MINUTES_AGO,
+      },
+    ]);
+
+    expect(source.status).toBe('error');
+    expect(source.lastSyncedAt).toBeNull();
+    expect(source.lastAttemptAt).toBe(TEN_MINUTES_AGO);
+    expect(source.detail).toMatch(/sync/i);
+  });
+
+  it('calls a run of consecutive failures failing even after a good sync', async () => {
+    const [source] = await sourcesFrom([
+      {
+        ...CONNECTED,
+        last_synced_at: AN_HOUR_AGO,
+        last_attempt_at: TEN_MINUTES_AGO,
+        consecutive_failures: 3,
+      },
+    ]);
+
+    expect(source.status).toBe('error');
+    expect(source.lastSyncedAt).toBe(AN_HOUR_AGO);
+    expect(source.consecutiveFailures).toBe(3);
+    expect(source.detail).toMatch(/3/);
+  });
+
+  it('reads the failure counter in the camelCase spelling as well', async () => {
+    const [source] = await sourcesFrom([
+      {
+        id: 'c1',
+        connectorKey: 'granola',
+        connectorName: 'Granola',
+        status: 'connected',
+        lastSyncedAt: AN_HOUR_AGO,
+        lastAttemptAt: TEN_MINUTES_AGO,
+        consecutiveFailures: 2,
+      },
+    ]);
+
+    expect(source.status).toBe('error');
+    expect(source.consecutiveFailures).toBe(2);
+  });
+
+  it('still lets the server’s own error text win, in the words the server used', async () => {
+    const [source] = await sourcesFrom([
+      {
+        ...CONNECTED,
+        status: 'needs_reauth',
+        check_error: 'The vendor rejected this key (401). Reconnect Granola.',
+        last_attempt_at: TEN_MINUTES_AGO,
+        consecutive_failures: 4,
+      },
+    ]);
+
+    expect(source.status).toBe('error');
+    expect(source.detail).toBe('The vendor rejected this key (401). Reconnect Granola.');
+  });
+
+  it('says nothing has arrived when nothing has ever even been tried', async () => {
+    const [source] = await sourcesFrom([{ ...CONNECTED }]);
+
+    expect(source.status).toBe('never');
+    expect(source.lastSyncedAt).toBeNull();
+    expect(source.lastAttemptAt).toBeNull();
+    expect(source.detail).toBe('Connected, but nothing has arrived yet.');
+  });
+});
+
+describe('the Library strip, rendered', () => {
+  /**
+   * The bug was VISIBLE, so one assertion is made where the reader would have
+   * seen it: the strip prints `synced {relative(lastSyncedAt)}`, and a
+   * never-synced connection with a freshly verified key used to render "synced
+   * 5 min ago" over an empty corpus.
+   */
+  it('does not report a never-synced source as recently synced', async () => {
+    const http = httpOver([{ ...CONNECTED, last_checked_at: FIVE_MINUTES_AGO }]);
+    const api = createCorpusApi({ http, scope: SCOPE });
+
+    render(<LibraryPage api={api} scope={SCOPE} />);
+
+    expect(await screen.findByText('Nothing yet')).toBeInTheDocument();
+    expect(screen.getByText(/synced never/)).toBeInTheDocument();
+    expect(screen.queryByText(/synced (just now|\d)/)).not.toBeInTheDocument();
+  });
+});

package/src/components/pages/MemberConnectionRoster.tsx

@@ -108,6 +108,19 @@ function MemberConnectionCard({
   const [error, setError] = React.useState('');
   const who = row.owner?.email || row.owner?.name || 'Unknown member';
 
+  /**
+   * ALREADY CUT (bd startsim-768w.22.25.19). `disabled` is the status a row
+   * carries AFTER a disconnect: the key is deleted, the tokens are revoked and
+   * the scheduled fetches are stopped. There is nothing left for this verb to
+   * do, so offering it — and then confirming with "this cannot be undone" over
+   * a key that is already gone — describes an action the server would refuse.
+   *
+   * ONLY `disabled`. `error` and `needs_reauth` still hold a stored credential
+   * and a live poll leg; they are exactly the rows an admin offboarding someone
+   * most needs to cut, so the test for this asserts they keep the button.
+   */
+  const alreadyDisconnected = row.status === 'disabled';
+
   async function cut() {
     if (!disconnect) return;
     setBusy(true);
@@ -143,8 +156,18 @@ function MemberConnectionCard({
               anything the member submitted. An admin deciding whether to cut a
               pipe is entitled to know it is already broken. */}
           {row.check_error ? <p className={cn.error}>{row.check_error}</p> : null}
+          {/* THE ROW STAYS. Who USED to have a pipe into this foundry is the
+              answer an offboarding review is looking for, so a disconnected
+              account is not hidden — it is labelled, and its verb is gone. */}
+          {alreadyDisconnected ? (
+            <p className={cn.muted} data-member-connection-disconnected>
+              Disconnected. This account’s key was deleted and its scheduled
+              fetches stopped. Nothing here can bring it back —{' '}
+              {who} has to connect with {row.connector_name} again themselves.
+            </p>
+          ) : null}
         </div>
-        {canManage && disconnect ? (
+        {canManage && disconnect && !alreadyDisconnected ? (
           <button
             type="button"
             className={cn.button}
@@ -155,7 +178,11 @@ function MemberConnectionCard({
           </button>
         ) : null}
       </div>
-      {confirming ? (
+      {/* `alreadyDisconnected` again, not because the button can open this today
+          but because a reload can flip the row to `disabled` under an open
+          prompt — and the one thing this prompt must never do is warn that an
+          action "cannot be undone" about a key that is already gone. */}
+      {confirming && !alreadyDisconnected ? (
         <div className="mt-3 space-y-2">
           {/* NAMES THE PERSON, because the cost of this button falls on them and
               not on the admin pressing it. A generic "are you sure?" over a list

package/src/corpus/client.ts

@@ -221,6 +221,18 @@ function reportedFilters(query: CommitmentQuery, applied: string[]): string[] {
 
 const EMPTY_PAGE = { count: 0, next: null, previous: null, results: [] };
 
+/**
+ * One wire timestamp, or `null`.
+ *
+ * ABSENT AND EMPTY BOTH MEAN NULL, and nothing else is coerced: a freshness fact
+ * that arrives as `""` from a serializer that stringifies its nulls must not
+ * become the string `""` and then a `NaN` date that reads as 1970. Everything
+ * that is not a non-empty string is simply "we were not told".
+ */
+function at(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value : null;
+}
+
 /** Rows written in parallel. Small enough not to look like a burst to the tenant. */
 const WRITE_CONCURRENCY = 6;
 
@@ -501,12 +513,25 @@ export function createCorpusApi(
       const now = Date.now();
       return (connectionPage.results ?? []).map((connection) => {
         const key = String(connection.connector_key ?? connection.connectorKey ?? 'unknown');
-        const lastSyncedAt =
-          (connection.last_synced_at as string) ??
-          (connection.lastSyncedAt as string) ??
-          (connection.last_checked_at as string) ??
-          (connection.lastCheckedAt as string) ??
-          null;
+        // THREE FACTS, READ SEPARATELY (bd startsim-1cow). This was one `??`
+        // chain ending in `last_checked_at`, and central's own view says of that
+        // column that it "is a far more optimistic fact than either and is never
+        // used as a stand-in". Central sends `last_synced_at: null` for a
+        // connection that has never delivered, so the chain fell straight
+        // through and a connection whose CREDENTIAL was verified five minutes
+        // ago rendered as data that ARRIVED five minutes ago — over an empty
+        // corpus. Each fact is now read into its own variable and only
+        // `lastSyncedAt` may answer "is my data current".
+        //
+        // BOTH SPELLINGS, for the same reason `ServerFilterReport` reads both:
+        // `@startsimpli/api` camelCases response keys in the browser and a plain
+        // server-side fetch does not, and getting this wrong on the timestamps
+        // is invisible until somebody's Library quietly lies.
+        const lastSyncedAt = at(connection.last_synced_at ?? connection.lastSyncedAt);
+        const lastAttemptAt = at(connection.last_attempt_at ?? connection.lastAttemptAt);
+        const lastCheckedAt = at(connection.last_checked_at ?? connection.lastCheckedAt);
+        const failures =
+          Number(connection.consecutive_failures ?? connection.consecutiveFailures ?? 0) || 0;
         const documentCount = Number(connection.document_count ?? connection.documentCount ?? 0);
         const error = String(connection.check_error ?? connection.checkError ?? '');
         const status = connection.status ?? '';
@@ -516,10 +541,27 @@ export function createCorpusApi(
         if (error || status === 'error' || status === 'needs_reauth') {
           health = 'error';
           detail = error || `Connection status is ${String(status)}.`;
+        } else if (failures > 0 || (lastAttemptAt && !lastSyncedAt)) {
+          // IT TRIED AND IT FAILED. Central's view exists partly so that "a card
+          // cannot read 'nothing yet' while it is in fact failing on a
+          // schedule" — a run that FINISHED while nothing has ever finished well
+          // is a failed run, and a non-zero failure streak says so outright even
+          // when an older sync did land. Note what does NOT appear in this
+          // condition: `lastCheckedAt`. A verified key is not a delivered
+          // record, in either direction.
+          health = 'error';
+          detail =
+            failures > 0
+              ? `${failures} sync${failures === 1 ? '' : 's'} in a row failed` +
+                `${lastSyncedAt ? '' : ' and nothing has arrived yet'}.`
+              : 'A sync ran but nothing arrived.';
         } else if (!lastSyncedAt) {
+          // `never` regardless of `lastCheckedAt`, which is the whole bead.
           health = 'never';
           detail = 'Connected, but nothing has arrived yet.';
         } else if (now - Date.parse(lastSyncedAt) > staleAfterHours * 3_600_000) {
+          // Measured against the SYNC. A credential re-checked this morning is
+          // exactly why a week-old corpus goes unnoticed.
           health = 'stale';
           detail = `Last sync was more than ${staleAfterHours} hours ago.`;
         }
@@ -529,6 +571,9 @@ export function createCorpusApi(
           label: String(connection.connector_name ?? connection.connectorName ?? sourceLabels[key] ?? key),
           documentCount,
           lastSyncedAt,
+          lastAttemptAt,
+          lastCheckedAt,
+          consecutiveFailures: failures,
           status: health,
           ...(detail ? { detail } : {}),
         };

package/src/corpus/types.ts

@@ -174,7 +174,31 @@ export interface SourceFreshness {
   label: string;
   /** How many documents this source has contributed to the corpus. */
   documentCount: number;
+  /**
+   * THREE FACTS, AND CONFLATING ANY TWO OF THEM IS HOW A FRESHNESS STRIP LIES
+   * (bd startsim-1cow). Central's `SubtreeConnectionsView` computes them
+   * separately and says in its own source that the third "is never used as a
+   * stand-in"; this contract keeps them separate for the same reason.
+   *
+   * The last run that actually BROUGHT DATA IN. `null` means nothing ever has,
+   * and it stays `null` — a connection whose credential merely checked out is
+   * not a connection whose data arrived.
+   */
   lastSyncedAt: string | null;
+  /**
+   * The last run of ANY outcome. Present with a `null` `lastSyncedAt` means it
+   * TRIED AND FAILED, which is a different thing to say than "nothing yet" and
+   * needs a different action from the reader.
+   */
+  lastAttemptAt?: string | null;
+  /**
+   * When the CREDENTIAL was last verified — far more optimistic than either of
+   * the above and never a substitute for them. Surfaced so a screen can say
+   * "the key is fine, the data is not", which is the useful sentence.
+   */
+  lastCheckedAt?: string | null;
+  /** How many syncs in a row have failed. `0` (or absent) means none. */
+  consecutiveFailures?: number;
   /**
    * `ok` — synced recently and cleanly.
    * `stale` — the last sync succeeded but was long enough ago to matter.