@startsimpli/integrations 0.2.27 → 0.2.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.27",
+  "version": "0.2.28",
   "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",

package/src/__tests__/corpus-source-strip.test.tsx

@@ -0,0 +1,243 @@
+/**
+ * THE LIBRARY'S SOURCE STRIP MUST LIST THE SOURCES A MEMBER ACTUALLY HAS
+ * (bd startsim-pg8na RED / startsim-bu04n GREEN).
+ *
+ * REPORTED ON THE LIVE TANDEM TENANT, 2026-08-26: the strip showed Granola
+ * ("Failing", 20 syncs in a row failed) and n8n, while the records listed below
+ * it were Fathom and Granola documents, and the member's own Fathom and Dropbox
+ * connections never appeared at all.
+ *
+ * WHERE THE ROWS COME FROM, which the original diagnosis got wrong and which
+ * decides what may be tested here. There is no tenant-local connections table.
+ * `tenant-starter/config/urls.py` routes `api/v1/connections/` to
+ * `ConnectionsView`, whose only job is to forward the caller's already-verified
+ * bearer to CENTRAL's `/api/v1/subtree/connections/` and return the page
+ * envelope untouched ("proxied from central so the call stays same-origin",
+ * bd startsim-768w.38.19). So `listSources()` is already reading central — it is
+ * reading central's SHARED-only surface, and the two facts line up exactly:
+ *
+ *     TENANT  GET /api/v1/connections/   -> granola, n8n
+ *     CENTRAL Connection rows for tandem -> dropbox(owner qosha),
+ *                                           fathom(owner qosha),
+ *                                           granola(SHARED), n8n(SHARED)
+ *
+ * `SubtreeConnectionsView` resolves through `Connection.objects.for_scope(...)`,
+ * which is `owner IS NULL`. Granola and n8n are not stale junk: they are the
+ * foundry's real shared connections, and Granola really is failing. The two
+ * missing cards are missing because the server was never asked for them.
+ *
+ * THE DIVISION OF LABOUR THIS FILE ASSUMES.
+ *
+ *   Server: a member's OWN rows reach this endpoint. That is a union of
+ *           `for_scope(orgs) | for_owner(orgs, request.user)` in central — the
+ *           remedy `SubtreeConnectionsView` names in its own source, bounded to
+ *           the requesting user so the disclosure bd startsim-768w.22.25.11
+ *           closed stays closed. It cannot be done from this package, and it
+ *           must not be done by merging in `/api/v1/connections/me/`: that
+ *           surface's serializer carries `last_checked_at` and NOTHING ELSE of
+ *           the three freshness facts (no `last_synced_at`, no
+ *           `last_attempt_at`, no `consecutive_failures` — see
+ *           `ConnectionSerializer.Meta.fields`), so every personal card built
+ *           from it would report a verified credential as delivered data. That
+ *           is precisely the lie bd startsim-1cow removed.
+ *
+ *   Client: what arrives is rendered honestly. A connection carries an owner or
+ *           it does not and the strip treats both alike; a connection the member
+ *           DISCONNECTED is not a source of the corpus and must stop appearing
+ *           as one.
+ *
+ * The second half is the part that fails today, and it is the "legacy ones
+ * masquerading as sources" the report describes: `disconnect()` deliberately
+ * keeps the card as `status: 'disabled'` ("DISCONNECT, not delete … the card
+ * survives as `disabled`, so the record that this vendor was connected is not
+ * thrown away"), and `listSources()` has no case for that status, so a vendor
+ * nobody is connected to any more falls through and renders next to the live
+ * ones. Not a denylist of connector keys — `status` is data the server writes.
+ */
+import { describe, expect, it } from 'vitest';
+import { render, screen, within } 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 AN_HOUR_AGO = ago(60 * 60_000);
+const TEN_MINUTES_AGO = ago(10 * 60_000);
+
+/** Every path this adapter asked for, so a widening read cannot pass unnoticed. */
+interface Recorder {
+  http: CorpusHttp;
+  calls: Array<{ path: string; params?: Record<string, unknown> }>;
+}
+
+/**
+ * The WIRE, not the contract — rows go in exactly as central serialises them.
+ * Same convention as `corpus-freshness.test.tsx`, for the same reason: a fixture
+ * must never be more generous than the server that feeds it.
+ */
+function recorderOver(rows: Array<Record<string, unknown>>): Recorder {
+  const calls: Array<{ path: string; params?: Record<string, unknown> }> = [];
+  return {
+    calls,
+    http: {
+      async get<T>(path: string, options?: { params?: Record<string, unknown> }): Promise<T> {
+        calls.push({ path, params: options?.params });
+        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>>) {
+  const { http } = recorderOver(rows);
+  return createCorpusApi({ http, scope: SCOPE }).listSources();
+}
+
+/** The foundry's shared Granola: real, connected, and genuinely failing. */
+const SHARED_GRANOLA = {
+  id: 'shared-granola',
+  connector_key: 'granola',
+  connector_name: 'Granola',
+  status: 'connected',
+  check_error: '',
+  last_synced_at: null,
+  last_attempt_at: TEN_MINUTES_AGO,
+  last_checked_at: null,
+  consecutive_failures: 20,
+};
+
+/**
+ * The member's OWN Fathom, as central serialises an owned row once the subtree
+ * read includes them. `owner` is the only structural difference, and the strip
+ * must not care: whose account it is decides who may SEE the row, server-side.
+ */
+const MY_FATHOM = {
+  id: 'my-fathom',
+  connector_key: 'fathom',
+  connector_name: 'Fathom',
+  owner: 'qosha@debugg.ai',
+  status: 'connected',
+  check_error: '',
+  last_synced_at: AN_HOUR_AGO,
+  last_attempt_at: AN_HOUR_AGO,
+  last_checked_at: AN_HOUR_AGO,
+  consecutive_failures: 0,
+};
+
+/** A vendor the member has DISCONNECTED. The card survives; the source does not. */
+const DISCONNECTED_DROPBOX = {
+  id: 'old-dropbox',
+  connector_key: 'dropbox',
+  connector_name: 'Dropbox',
+  owner: 'qosha@debugg.ai',
+  status: 'disabled',
+  check_error: '',
+  last_synced_at: null,
+  last_attempt_at: null,
+  last_checked_at: null,
+  consecutive_failures: 0,
+};
+
+describe('listSources — a personal connection is a source like any other', () => {
+  it('lists the member’s own connection alongside the foundry’s shared ones', async () => {
+    const sources = await sourcesFrom([SHARED_GRANOLA, MY_FATHOM]);
+
+    expect(sources.map((source) => source.source).sort()).toEqual(['fathom', 'granola']);
+  });
+
+  it('keeps a personal connection’s freshness intact rather than flattening it', async () => {
+    const [fathom] = await sourcesFrom([MY_FATHOM]);
+
+    // The whole reason a merge from `/api/v1/connections/me/` is refused: that
+    // payload has no `last_synced_at` at all, so a card built from it could only
+    // ever say "nothing yet" over data that arrived an hour ago.
+    expect(fathom.lastSyncedAt).toBe(AN_HOUR_AGO);
+    expect(fathom.status).toBe('ok');
+    expect(fathom.label).toBe('Fathom');
+  });
+
+  it('reads one connections endpoint and does not widen the read to reach them', async () => {
+    // A single source of truth, stated as a test so a future "just also fetch
+    // everybody's" cannot be added quietly. The bound that actually keeps
+    // bd startsim-768w.22.25.11 closed is server-side; this pins that the client
+    // never asks for more than the member-scoped page it is handed.
+    const recorder = recorderOver([SHARED_GRANOLA, MY_FATHOM]);
+    await createCorpusApi({ http: recorder.http, scope: SCOPE }).listSources();
+
+    const connectionReads = recorder.calls.filter((call) => call.path.includes('connections'));
+    expect(connectionReads).toHaveLength(1);
+    expect(connectionReads[0].path).toBe('api/v1/connections');
+    // No owner, no user, no "all" — nothing that names a principal other than
+    // the bearer the proxy already forwarded.
+    expect(connectionReads[0].params ?? {}).toEqual({});
+  });
+});
+
+describe('listSources — a disconnected vendor is not a source', () => {
+  it('drops a connection the member has disconnected', async () => {
+    const sources = await sourcesFrom([SHARED_GRANOLA, MY_FATHOM, DISCONNECTED_DROPBOX]);
+
+    expect(sources.map((source) => source.source).sort()).toEqual(['fathom', 'granola']);
+    expect(sources.some((source) => source.source === 'dropbox')).toBe(false);
+  });
+
+  it('never renders a disconnected vendor as healthy', async () => {
+    const [source] = await sourcesFrom([DISCONNECTED_DROPBOX]);
+
+    // If it is listed at all it must not read as a working source. Today it
+    // falls through every branch and comes back `never` — "Connected, but
+    // nothing has arrived yet" about an account that is not connected.
+    expect(source).toBeUndefined();
+  });
+
+  it('keeps a broken-but-live connection, which is a different thing entirely', async () => {
+    // `needs_reauth` and `error` are still connected accounts with a credential
+    // on file and a member who can fix them. Only the lifecycle-ended row goes.
+    const sources = await sourcesFrom([
+      { ...MY_FATHOM, status: 'needs_reauth', check_error: 'The vendor rejected this key (401).' },
+      SHARED_GRANOLA,
+    ]);
+
+    expect(sources.map((source) => source.source).sort()).toEqual(['fathom', 'granola']);
+    expect(sources.find((source) => source.source === 'fathom')?.status).toBe('error');
+  });
+});
+
+describe('the Library strip, rendered', () => {
+  it('draws a card for the member’s own source and none for the disconnected one', async () => {
+    const { http } = recorderOver([SHARED_GRANOLA, MY_FATHOM, DISCONNECTED_DROPBOX]);
+    const api = createCorpusApi({ http, scope: SCOPE });
+
+    render(<LibraryPage api={api} scope={SCOPE} />);
+
+    // Scoped to the strip itself: `listSources` also feeds the source filter's
+    // options, so an unscoped query would match the same vendor twice and say
+    // nothing about which surface it appeared on.
+    const strip = within(await screen.findByRole('region', { name: 'Source freshness' }));
+    expect(strip.getByText('Fathom')).toBeInTheDocument();
+    expect(strip.getByText('Granola')).toBeInTheDocument();
+    expect(strip.queryByText('Dropbox')).not.toBeInTheDocument();
+  });
+
+  it('does not blame a disconnected vendor in the empty state', async () => {
+    // `EmptyState` names every source whose status is `error`. A vendor nobody
+    // is connected to must not be reported as "failing to sync" — the action
+    // that sentence asks for (go fix the connection) is the wrong action.
+    const { http } = recorderOver([DISCONNECTED_DROPBOX]);
+    const api = createCorpusApi({ http, scope: SCOPE });
+
+    render(<LibraryPage api={api} scope={SCOPE} />);
+
+    expect(await screen.findByText(/Nothing has been pulled in yet/i)).toBeInTheDocument();
+    expect(screen.queryByText(/Dropbox/)).not.toBeInTheDocument();
+  });
+});

package/src/corpus/client.ts

@@ -292,6 +292,42 @@ function at(value: unknown): string | null {
   return typeof value === 'string' && value.trim() ? value : null;
 }
 
+/**
+ * Connection lifecycle states in which the account is NO LONGER CONNECTED
+ * (bd startsim-bu04n).
+ *
+ * `Connection.Status` is `connected | needs_reauth | error | disabled`, and only
+ * the last one has ended: the member disconnected it. Central's member surface
+ * documents what that leaves behind — "DISCONNECT, not delete. One transaction
+ * stops the scheduled fetches, revokes every token issued for the account and
+ * deletes the stored credential; the card survives as `disabled`, so the record
+ * that this vendor was connected is not thrown away."
+ *
+ * The card surviving is right for the connections screen, where a member manages
+ * it and may reconnect. It is wrong for the Library's source strip, whose whole
+ * question is "where is my corpus coming from, and is it current". A vendor with
+ * no credential and no schedule is not coming from anywhere, and it used to fall
+ * through every branch below to `never` — "Connected, but nothing has arrived
+ * yet" printed about an account that is not connected.
+ *
+ * A STATUS, NOT A VENDOR. This reads the lifecycle field central writes, so a
+ * connector added tomorrow is handled with no code change here. A list of
+ * connector keys would be exactly the per-vendor branch the DB-driven catalog
+ * exists to prevent, and the reported symptom ("it shows old, disconnected
+ * ones") is precisely the symptom such a list would paper over.
+ *
+ * AN UNRECOGNISED STATUS IS KEPT, deliberately. `needs_reauth` and `error` are
+ * live accounts with a credential on file and a member who can fix them; the
+ * failure mode of hiding one of those — a real source silently absent from the
+ * strip — is worse than the failure mode of showing a status this build has not
+ * heard of yet. A new terminal state is added here on purpose, not by default.
+ */
+const RETIRED_CONNECTION_STATUSES: ReadonlySet<string> = new Set(['disabled']);
+
+function isALiveSource(connection: Record<string, unknown>): boolean {
+  return !RETIRED_CONNECTION_STATUSES.has(String(connection.status ?? ''));
+}
+
 /** Rows written in parallel. Small enough not to look like a burst to the tenant. */
 const WRITE_CONCURRENCY = 6;
 
@@ -501,14 +537,6 @@ export function createCorpusApi(
       };
     },
 
-    /**
-     * Freshness per SOURCE, assembled from the connections the tenant has.
-     *
-     * It reads the connections API rather than the documents, because "Dropbox
-     * has not synced since Tuesday" is a true and useful statement even when
-     * Dropbox has contributed zero documents — and a count derived from the
-     * corpus alone can never say it.
-     */
     /**
      * The tracking surface's read (bd startsim-768w.38.25).
      *
@@ -612,6 +640,41 @@ export function createCorpusApi(
       return durable as ExtractionRun;
     },
 
+    /**
+     * Freshness per SOURCE, assembled from the connections behind this workspace.
+     *
+     * It reads the connections API rather than the documents, because "Dropbox
+     * has not synced since Tuesday" is a true and useful statement even when
+     * Dropbox has contributed zero documents — and a count derived from the
+     * corpus alone can never say it.
+     *
+     * WHERE THE ROWS ACTUALLY COME FROM (bd startsim-bu04n), because the name of
+     * the default path invites the wrong guess. `api/v1/connections` on a tenant
+     * fork is NOT a tenant table: `tenant-starter`'s `ConnectionsView` forwards
+     * the caller's already-verified bearer to central's
+     * `/api/v1/subtree/connections/` and returns the page envelope untouched
+     * (bd startsim-768w.38.19). This read is a central read wearing a
+     * same-origin path, which is why every field below is central's.
+     *
+     * WHICH CONNECTIONS THAT SURFACE HANDS BACK is central's decision and not
+     * this adapter's. `SubtreeConnectionsView` resolves through
+     * `Connection.objects.for_scope(...)` — the foundry's SHARED rows — and a
+     * member's own vendor accounts join the page only when central unions
+     * `for_owner(orgs, request.user)` in, bounded to the requesting user. That
+     * bound is what keeps a colleague's personal connection off this strip
+     * (bd startsim-768w.22.25.11), and it is the reason this adapter must not
+     * reach for `/api/v1/connections/me/` to fill the gap itself: besides
+     * splitting the answer across two servers, that serializer carries
+     * `last_checked_at` and NONE of the other freshness facts, so every personal
+     * card built from it would report a verified credential as delivered data —
+     * exactly the lie bd startsim-1cow removed. Rows are read from one endpoint,
+     * as handed.
+     *
+     * `documentCount` is whatever the connections payload says and is therefore
+     * `0` today: no connections endpoint sends `document_count`, and a per-source
+     * count from the corpus needs the `?source=` filter bd startsim-768w.38.12
+     * is still open on. Tracked as bd startsim-o0o6o.1.
+     */
     async listSources(): Promise<SourceFreshness[]> {
       const [connectionPage, documentPage] = await Promise.all([
         http
@@ -625,7 +688,7 @@ export function createCorpusApi(
       void documentPage; // total count is per-source below; kept for the empty-corpus case
 
       const now = Date.now();
-      return (connectionPage.results ?? []).map((connection) => {
+      return (connectionPage.results ?? []).filter(isALiveSource).map((connection) => {
         const key = String(connection.connector_key ?? connection.connectorKey ?? 'unknown');
         // THREE FACTS, READ SEPARATELY (bd startsim-1cow). This was one `??`
         // chain ending in `last_checked_at`, and central's own view says of that