@startsimpli/integrations 0.2.23 → 0.2.25

package/package.json

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

@@ -1107,3 +1107,134 @@ describe('MemberConnectionRoster — Disconnect is not offered twice', () => {
       expect(api.disconnectMemberConnection).toHaveBeenCalledWith('acme', 'm-live'));
   });
 });
+
+// --------------------------------------------------------------------------
+//  auth_mode: the OAuth branch (bd startsim-768w.22.25.14 / .23)
+// --------------------------------------------------------------------------
+
+/**
+ * `schema.auth_mode_for`'s own docstring calls `auth_mode` "the ONLY thing the
+ * connect card branches on", and until this suite existed the card never
+ * branched: `fields = [...credential_schema, ...config_schema]` and one
+ * unconditional `CredentialSchemaForm`. On the admin catalog that rendered
+ * Dropbox's `access_token` / `refresh_token` / `expires_at` as text inputs —
+ * the product asking a human to go and mint a refresh token by hand.
+ */
+const OAUTH_ENTRY = {
+  key: 'dropbox',
+  name: 'Dropbox',
+  description: 'Poll file metadata',
+  logo_url: '',
+  docs_url: '',
+  capabilities: ['poll'],
+  auth_mode: 'oauth',
+  credential_schema: {
+    version: 1,
+    fields: [
+      { key: 'access_token', label: 'Access token', type: 'secret', required: true },
+      { key: 'refresh_token', label: 'Refresh token', type: 'secret', required: false },
+    ],
+  },
+  config_schema: {
+    version: 1,
+    fields: [{ key: 'path', label: 'Folder', type: 'string', required: false }],
+  },
+  record_types: [],
+  supports_webhooks: true,
+  availability: { available: true, reason: '' },
+};
+
+const START = {
+  authorization_url:
+    'https://www.dropbox.com/oauth2/authorize?client_id=abc&response_type=code'
+    + '&token_access_type=offline&redirect_uri=https%3A%2F%2Fapi.example%2Fcb%2F&state=signed',
+  state: 'signed',
+  redirect_uri: 'https://api.example/cb/',
+};
+
+function oauthApi(overrides: Partial<ConnectionsApi> = {}): ConnectionsApi {
+  return stubApi({
+    connectorCatalog: vi.fn().mockResolvedValue({ results: [OAUTH_ENTRY] }),
+    startOAuth: vi.fn().mockResolvedValue(START),
+    ...overrides,
+  });
+}
+
+async function openOAuthCard(api: ConnectionsApi) {
+  render(<ConnectionsPage api={api} foundrySlug="acme" />);
+  await screen.findByText('Dropbox');
+  await userEvent.click(screen.getByRole('button', { name: /^connect$/i }));
+}
+
+describe('an OAuth connector is never a form asking for token material', () => {
+  it('renders NO credential inputs for an oauth connector', async () => {
+    await openOAuthCard(oauthApi());
+    expect(screen.queryByLabelText(/access token/i)).not.toBeInTheDocument();
+    expect(screen.queryByLabelText(/refresh token/i)).not.toBeInTheDocument();
+  });
+
+  it('still asks for config, which is not a secret', async () => {
+    await openOAuthCard(oauthApi());
+    expect(screen.getByLabelText(/folder/i)).toBeInTheDocument();
+  });
+
+  it('offers a hand-off to the vendor instead of Test and save', async () => {
+    await openOAuthCard(oauthApi());
+    expect(screen.getByRole('button', { name: /continue to dropbox/i })).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: /test and save/i })).not.toBeInTheDocument();
+  });
+
+  it('an api_key connector is untouched by the branch', async () => {
+    render(<ConnectionsPage api={stubApi()} foundrySlug="acme" />);
+    await screen.findByText('n8n');
+    await userEvent.click(screen.getAllByRole('button', { name: /^connect$/i })[0]);
+    expect(screen.getByRole('button', { name: /test and save/i })).toBeInTheDocument();
+  });
+});
+
+describe('the hand-off sends the browser to the consent URL', () => {
+  it('starts the round trip with the connector key and the gathered config', async () => {
+    const api = oauthApi();
+    await openOAuthCard(api);
+    await userEvent.type(screen.getByLabelText(/folder/i), '/Reports');
+    await userEvent.click(screen.getByRole('button', { name: /continue to dropbox/i }));
+    await waitFor(() => expect(api.startOAuth).toHaveBeenCalled());
+    const [slug, input] = (api.startOAuth as ReturnType<typeof vi.fn>).mock.calls[0];
+    expect(slug).toBe('acme');
+    expect(input.connector_key).toBe('dropbox');
+    expect(input.config).toEqual({ path: '/Reports' });
+  });
+
+  it('opens the URL VERBATIM — the client adds no parameters of its own', async () => {
+    const assign = vi.fn();
+    const original = window.location;
+    Object.defineProperty(window, 'location', {
+      configurable: true, value: { ...original, href: 'https://app.example/c', assign },
+    });
+    try {
+      const api = oauthApi();
+      await openOAuthCard(api);
+      await userEvent.click(screen.getByRole('button', { name: /continue to dropbox/i }));
+      await waitFor(() => expect(assign).toHaveBeenCalledWith(START.authorization_url));
+    } finally {
+      Object.defineProperty(window, 'location', { configurable: true, value: original });
+    }
+  });
+
+  it('surfaces a refusal instead of navigating', async () => {
+    const api = oauthApi({
+      startOAuth: vi.fn().mockRejectedValue(new Error('no app registration')),
+    });
+    await openOAuthCard(api);
+    await userEvent.click(screen.getByRole('button', { name: /continue to dropbox/i }));
+    expect(await screen.findByRole('alert')).toHaveTextContent(/no app registration/i);
+  });
+
+  it('a client without the verb says so rather than offering a dead button', async () => {
+    const api = oauthApi();
+    delete (api as { startOAuth?: unknown }).startOAuth;
+    await openOAuthCard(api);
+    expect(screen.getByText(/cannot start a dropbox sign-in yet/i)).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /continue to dropbox/i })).toBeDisabled();
+  });
+});

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/api/connections.ts

@@ -31,10 +31,12 @@
  */
 import type {
   Connection,
+  ConnectionInstructions,
   ConnectionPermissions,
   ConnectionRun,
   ConnectorCatalogEntry,
   MemberConnectionsApi,
+  OAuthStart,
 } from '../components/pages/types';
 import { request } from './_fetch';
 
@@ -87,6 +89,50 @@ export const connectionsMe: MemberConnectionsApi = {
     return request<Connection>(`${BASE}/`, { method: 'POST', body: input });
   },
 
+  /**
+   * START a consent round trip on an OAuth connector (bd startsim-768w.22.25.21).
+   *
+   * ONE call, not create-then-initiate. The two halves have no independent
+   * meaning — a shell card with no consent URL is an orphan the member cannot
+   * act on, and a consent URL with no card has nowhere to put the token — so a
+   * refusal here leaves nothing behind.
+   *
+   * Takes `connector_key` rather than an id because the row does not exist yet;
+   * that is the whole bug this closes. The caller opens `authorization_url` and
+   * does nothing else: it is already complete, and the client has no `client_id`
+   * of its own to add to it.
+   *
+   * `return_to` is where the browser should land afterwards. It is VALIDATED
+   * server-side against this tenant's own recorded origins and folded into the
+   * signed state — the callback is an anonymous browser mid-redirect from the
+   * vendor and cannot be allowed to name its own destination.
+   */
+  startOAuth(input: {
+    connector_key: string;
+    name?: string;
+    config?: Record<string, unknown>;
+    capabilities_enabled?: string[];
+    return_to?: string;
+  }): Promise<OAuthStart> {
+    return request<OAuthStart>(`${BASE}/oauth/start/`, { method: 'POST', body: input });
+  },
+
+  /**
+   * RE-consent an existing card whose grant the vendor stopped accepting. The
+   * first connect is `startOAuth`; this one takes an id because the card is
+   * already there and must not be duplicated.
+   */
+  oauthInitiate(id: string, input?: { return_to?: string }): Promise<OAuthStart> {
+    return request<OAuthStart>(`${BASE}/${id}/oauth/initiate/`, {
+      method: 'POST', body: input ?? {},
+    });
+  },
+
+  /** Vendor-side setup steps, as DATA written by the connector in Python. */
+  connectionInstructions(id: string): Promise<ConnectionInstructions> {
+    return request<ConnectionInstructions>(`${BASE}/${id}/instructions/`);
+  },
+
   /**
    * Test it now, against the STORED credential. The body is deliberately empty:
    * a "test connection" button that accepts a pasted key is a second connect

package/src/components/pages/ConnectionsPage.tsx

@@ -123,6 +123,16 @@ interface BoundApi {
   }): Promise<ConnectionInvokeResult>;
   /** 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
+      older client keeps type-checking, and the card renders the connector as
+      not-connectable-here rather than offering a button that cannot fire. */
+  startOAuth?(input: {
+    connector_key: string;
+    name?: string;
+    config?: Record<string, unknown>;
+    capabilities_enabled?: string[];
+    return_to?: string;
+  }): Promise<{ authorization_url: string; state: string; redirect_uri: string }>;
   setMemberConnectorPolicy?(connectorKey: string, allowed: boolean): Promise<unknown>;
   memberConnections?(): Promise<{
     results: MemberConnectionRow[]; permissions: ConnectionPermissions;
@@ -144,6 +154,10 @@ function bindApi(props: ConnectionsPageProps): BoundApi {
     ? { setMemberConnectorPolicy: (key: string, allowed: boolean) =>
       api.setMemberConnectorPolicy!(slug, key, allowed) }
     : {};
+  const oauth = api.startOAuth
+    ? { startOAuth: (input: Parameters<NonNullable<BoundApi['startOAuth']>>[0]) =>
+      api.startOAuth!(slug, input) }
+    : {};
   const roster = api.memberConnections
     ? { memberConnections: () => api.memberConnections!(slug) }
     : {};
@@ -153,6 +167,7 @@ function bindApi(props: ConnectionsPageProps): BoundApi {
     : {};
   return {
     ...memberPolicy,
+    ...oauth,
     ...roster,
     ...cutMember,
     connectorCatalog: () => api.connectorCatalog(slug),
@@ -467,12 +482,76 @@ function CatalogCard({
   // transcript bytes at all) and is unaffected by this box.
   const [capabilities, setCapabilities] = React.useState<string[]>(entry.capabilities);
 
-  const credentialFields = schemaFields(entry.credential_schema);
+  // THE ONE THING THIS CARD BRANCHES ON (bd startsim-768w.22.25.14/.23).
+  // `schema.auth_mode_for` derives it server-side and its docstring says so;
+  // this component had no reference to it at all, so an OAuth connector got the
+  // same credential form as everything else — which on the admin catalog meant
+  // the product asking a human to paste a refresh token, the exact thing
+  // `auth_mode` exists to prevent.
+  const isOAuth = entry.auth_mode === 'oauth';
+  // A stale client is not a dead button. The verb is optional on both api
+  // shapes, so an app pinned to an older `@startsimpli/api` says the connector
+  // cannot be connected from here instead of rendering a hand-off that throws.
+  const canHandOff = isOAuth && typeof api.startOAuth === 'function';
+
+  // NO credential fields in OAuth mode. Not hidden — never collected: the whole
+  // point is that the token comes back from the vendor, and a form that
+  // "helpfully" accepted one would keep the paste-a-refresh-token path alive
+  // beside the consent flow that replaced it.
+  const credentialFields = isOAuth ? [] : schemaFields(entry.credential_schema);
+  // Config IS still asked for, in both modes. It is the folder a Dropbox card
+  // will poll, it is not a secret, and dropping it here would mean asking for it
+  // again after the round trip.
   const configFields = schemaFields(entry.config_schema);
   const fields = [...credentialFields, ...configFields];
   const warnings = patternWarnings(fields, values);
   const missing = missingRequired(fields, values);
 
+  /** Collect the config fields the form did gather. Shared by both submits. */
+  function collectConfig(): Record<string, unknown> {
+    const config: Record<string, unknown> = {};
+    for (const spec of configFields) {
+      const v = values[isSecret(spec) ? `${spec.key}__draft` : spec.key];
+      if (typeof v === 'boolean' || typeof v === 'number' || v) config[spec.key] = v;
+    }
+    return config;
+  }
+
+  /**
+   * Hand the browser to the vendor (bd startsim-768w.22.25.21/.22).
+   *
+   * ONE call: the server writes the shell card AND returns the consent URL,
+   * because neither half is usable alone. The URL is opened VERBATIM — it is
+   * already complete, and this client has no `client_id` to add to it and must
+   * not have one to choose.
+   *
+   * `return_to` is where the member should land afterwards. It is sent, not
+   * trusted: the server validates it against this tenant's own recorded origins
+   * before folding it into the signed state, because the callback is an
+   * anonymous browser mid-redirect from the vendor's domain.
+   *
+   * `location.assign`, not a new tab. A vendor consent screen that opens in a
+   * popup is the one an ad blocker eats, and the whole point of the round trip
+   * is that the browser comes BACK here.
+   */
+  async function handOff() {
+    setBusy(true);
+    setError('');
+    try {
+      const { authorization_url: url } = await api.startOAuth!({
+        connector_key: entry.key,
+        name: entry.name,
+        config: collectConfig(),
+        capabilities_enabled: orderCapabilities(entry.capabilities, capabilities),
+        return_to: typeof window !== 'undefined' ? window.location.href : undefined,
+      });
+      if (typeof window !== 'undefined') window.location.assign(url);
+    } catch (err) {
+      setError((err as { message?: string })?.message || 'Could not start sign-in.');
+      setBusy(false);
+    }
+  }
+
   async function submit() {
     setBusy(true);
     setError('');
@@ -566,18 +645,56 @@ function CatalogCard({
               Connecting here adds a SECOND account.
             </p>
           ) : null}
-          <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,
-              }));
-            }}
-          />
+          {/* SIGN IN AT THE VENDOR — never a form asking for token material.
+              `auth_mode: oauth` means the credential schema is `access_token` /
+              `refresh_token` / `expires_at`, and rendering those as inputs asks
+              a human to go and mint a refresh token by hand. That is what this
+              card did to every admin who opened Dropbox. */}
+          {isOAuth ? (
+            <div className="space-y-2" data-oauth-connect={entry.key}>
+              <p className={cn.muted}>
+                {entry.name} signs you in on its own site. You will be sent there
+                to approve access and returned here — no keys to copy, and
+                StartSimpli never sees your password.
+              </p>
+              {!canHandOff ? (
+                <p className={cn.error}>
+                  This app cannot start a {entry.name} sign-in yet. Update it, or
+                  connect {entry.name} from the foundry control plane.
+                </p>
+              ) : null}
+            </div>
+          ) : (
+            <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,
+                }));
+              }}
+            />
+          )}
+          {/* Config is asked for in BOTH modes — it is not a secret, and it is
+              the folder this card will poll. Rendered separately in OAuth mode
+              because the credential half of the same form is gone. */}
+          {isOAuth && configFields.length > 0 ? (
+            <CredentialSchemaForm
+              fields={configFields}
+              values={values}
+              warnings={warnings}
+              idPrefix={`connect-${entry.key}`}
+              onChange={(key, value) => {
+                const spec = configFields.find((f) => f.key === key);
+                setValues((prev) => ({
+                  ...prev, [spec && isSecret(spec) ? `${key}__draft` : key]: value,
+                }));
+              }}
+            />
+          ) : null}
           <CapabilityPicker
             scope="catalog"
             declared={entry.capabilities}
@@ -603,12 +720,19 @@ function CatalogCard({
             className={cn.button}
             disabled={
               busy
+              // `missing` counts only the fields this mode actually collects.
+              // In OAuth mode that is config alone — gating the hand-off on a
+              // required `access_token` would disable the very button whose job
+              // is to go and get one.
               || missing.length > 0
+              || (isOAuth && !canHandOff)
               || (entry.capabilities.length > 0 && capabilities.length === 0)
             }
-            onClick={() => void submit()}
+            onClick={() => void (isOAuth ? handOff() : submit())}
           >
-            {busy ? 'Testing…' : 'Test and save'}
+            {isOAuth
+              ? (busy ? 'Redirecting…' : `Continue to ${entry.name}`)
+              : (busy ? 'Testing…' : 'Test and save')}
           </button>
         </div>
       ) : null}

package/src/components/pages/types.ts

@@ -47,6 +47,33 @@ export interface ConnectorSchema {
 
 export type ConnectorSchemaLike = ConnectorSchema | ConnectorFieldSpec[] | null | undefined;
 
+/**
+ * What `startOAuth`/`oauthInitiate` hand back (bd startsim-768w.22.25.22).
+ *
+ * `authorization_url` is COMPLETE — endpoint, `client_id`, `response_type`,
+ * `redirect_uri`, `state`, and whatever else the connector's own
+ * `authorization_params()` decided the vendor needs (Dropbox's includes
+ * `token_access_type=offline`, which is what makes the grant durable). The
+ * client opens it and adds nothing: it has no `client_id` of its own and must
+ * not have one to choose.
+ *
+ * `state` is opaque and signed. It is echoed by the vendor to the callback and
+ * is the only thing tying the redirect back to a connection; nothing in the
+ * browser needs to read it.
+ */
+export interface OAuthStart {
+  authorization_url: string;
+  state: string;
+  redirect_uri: string;
+}
+
+/** Vendor-side setup steps, written by the connector in Python. */
+export interface ConnectionInstructions {
+  steps?: string[];
+  headers?: Record<string, string>;
+  [key: string]: unknown;
+}
+
 export interface ConnectorCatalogEntry {
   key: string;
   name: string;
@@ -285,6 +312,22 @@ export interface ConnectionsApi {
   setMemberConnectorPolicy?(slug: string, connectorKey: string, allowed: boolean):
     Promise<{ connector_key: string; member_connect_allowed: boolean; changed: boolean }>;
 
+  /**
+   * START a consent round trip on an OAuth connector (bd startsim-768w.22.25.23).
+   *
+   * Optional so an app pinned to an older `@startsimpli/api` keeps compiling.
+   * The card branches on `auth_mode` AND on this verb being present, so a stale
+   * client renders the connector as not connectable from this screen rather
+   * than a button that cannot fire.
+   */
+  startOAuth?(slug: string, input: {
+    connector_key: string;
+    name?: string;
+    config?: Record<string, unknown>;
+    capabilities_enabled?: string[];
+    return_to?: string;
+  }): Promise<OAuthStart>;
+
   /** The roster: every member-owned connection in the foundry. Metadata only. */
   memberConnections?(slug: string): Promise<{
     results: MemberConnectionRow[];
@@ -357,4 +400,20 @@ export interface MemberConnectionsApi {
   rotateCredential(id: string, credentials: Record<string, unknown>): Promise<Connection>;
   disconnect(id: string): Promise<void>;
   connectionRuns(id: string): Promise<{ results: ConnectionRun[] }>;
+  /**
+   * The OAuth half of the surface (bd startsim-768w.22.25.14/.21). Optional so
+   * an app pinned to an older `@startsimpli/api` still type-checks; the card
+   * branches on `auth_mode` and renders the hand-off only when both the mode
+   * says oauth AND the verb is present, so a stale client degrades to saying
+   * the connector cannot be connected here rather than to a dead button.
+   */
+  startOAuth?(input: {
+    connector_key: string;
+    name?: string;
+    config?: Record<string, unknown>;
+    capabilities_enabled?: string[];
+    return_to?: string;
+  }): Promise<OAuthStart>;
+  oauthInitiate?(id: string, input?: { return_to?: string }): Promise<OAuthStart>;
+  connectionInstructions?(id: string): Promise<ConnectionInstructions>;
 }

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.