@startsimpli/integrations 0.2.23 → 0.2.24

package/package.json

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