@startsimpli/integrations 0.2.30 → 0.2.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.30",
+  "version": "0.2.31",
   "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__/connections.test.tsx

@@ -813,9 +813,15 @@ describe('ConnectionCard — a connected account has settings', () => {
  *     — "there is no id here to substitute, no slug to swap". A client that
  *     takes a slug re-introduces, in the types, the exact affordance that URL
  *     space was designed not to have.
- *   * NO PATCH. `MyConnectionDetailView` serves GET and DELETE only, so the
- *     capability picker is informational and there is no Save beside it, and no
- *     settings form.
+ *   * NO GENERAL PATCH. `MyConnectionDetailView` still serves GET and DELETE
+ *     only, so a card's NAME and what it may DO stay the foundry's and the
+ *     capability picker is informational with no Save beside it. The one write
+ *     verb the member surface grew is `updateConnectionConfig` (bd
+ *     startsim-sfms2) — a personal connection's config is the member's own
+ *     privacy boundary — and it is a separate verb precisely so opening it does
+ *     not open the capability Save. This stub does not carry it, and this
+ *     connector declares no config fields, so no settings control renders here;
+ *     `member-connection-scope.test.tsx` drives the surface that does.
  *   * NO targets, choices, actions or tokens. Those are foundry-level and stay
  *     on the control-plane router, so the Workflows control is not rendered.
  *   * THE CATALOG IS THE SERVER'S ANSWER. `me/catalog/` returns only what the

package/src/__tests__/member-connection-scope.test.tsx

@@ -0,0 +1,314 @@
+/**
+ * RED: a member's own scope is theirs to set, on screen (bd startsim-sirp6).
+ *
+ * Quinn, 2026-08-27: "if people connect their dropbox, they will expect to be
+ * able to configure what they have access to. some may want root which would be
+ * everything, some may want to configure a subfolder. but our system should
+ * enable and enforce either / both."
+ *
+ * `connections.test.tsx` next door pins that personal mode has no PATCH, and
+ * that was right about what the router served. It is not right about a PERSONAL
+ * connection's config, which is not a pipeline setting: it decides which of the
+ * MEMBER's own files this platform reads. So the member surface grows exactly
+ * ONE write verb — `PATCH connections/me/<id>/config/`, beside `credential/`
+ * rather than on the detail route — and this file pins what that must look like
+ * from the browser.
+ *
+ * THREE THINGS IT IS EASY TO SHIP WITHOUT.
+ *
+ * 1. THE CONTROL HAS TO RENDER. `ConnectionCard` gates Settings on a verb
+ *    EXISTING on the bound api. A member write endpoint that the composer never
+ *    reaches is a change every backend test passes and no member can use, so the
+ *    first assertion here is positive: the control is on the card.
+ * 2. THE CAPABILITY SAVE MUST STAY ABSENT. The narrow verb is narrow. What a
+ *    member's account may DO is still the foundry's, and the picker stays
+ *    informational — which is why the composer must not gate both controls on
+ *    one verb.
+ * 3. THE MEMBER MUST BE TOLD THE WALK RESTARTS, and the SERVER must be what says
+ *    it. This composer refuses to name a vendor and cannot know which fields
+ *    bear the scope; only the connector knows. So the sentence arrives in the
+ *    response and is rendered verbatim.
+ */
+import * as React from 'react';
+import { render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ConnectionsPage } from '../components/pages/ConnectionsPage';
+import { CredentialSchemaForm } from '../components/CredentialSchemaForm';
+import type { MemberConnectionsApi } from '../components/pages/types';
+import { connectionsMe } from '../api/connections';
+import { setApiBase, setAuthTokenProvider } from '../api/_fetch';
+
+/**
+ * A connector whose config IS somebody's privacy boundary: a folder, a switch
+ * that widens it, and a claim on the widest setting of all.
+ *
+ * Not Dropbox. This composer knows about FIELDS and nothing about vendors, so a
+ * fixture that named one would be asserting Dropbox rather than the framework.
+ */
+const SCOPE_FIELDS = [
+  {
+    key: 'folder', label: 'Folder', type: 'string', required: false,
+    help: 'Leave blank for everything', placeholder: '', pattern: null, options: null,
+    default: '', write_only: false, mask: 'none', docs_url: '',
+  },
+  {
+    key: 'recursive', label: 'Include sub-folders', type: 'boolean', required: false,
+    help: 'Off by default', placeholder: '', pattern: null, options: null,
+    default: false, write_only: false, mask: 'none', docs_url: '',
+  },
+  {
+    key: 'whole_account_acknowledged_by', label: 'Whole-account read claimed by',
+    type: 'acknowledgement', required: false, help: 'Required to read everything',
+    placeholder: '', pattern: null, options: null, default: null,
+    write_only: false, mask: 'none', docs_url: '',
+  },
+];
+
+const MEMBER_CATALOG = {
+  results: [
+    {
+      key: 'filesvendor', name: 'File Vendor', description: 'Files', logo_url: '',
+      docs_url: '', capabilities: ['poll'], auth_mode: 'api_key',
+      credential_schema: {
+        version: 1,
+        fields: [{
+          key: 'api_key', label: 'API key', type: 'secret', required: true, help: '',
+          placeholder: '', pattern: null, options: null, default: null,
+          write_only: true, mask: 'last4', docs_url: '',
+        }],
+      },
+      config_schema: { version: 1, fields: SCOPE_FIELDS },
+      record_types: [], supports_webhooks: false,
+      availability: { available: true, reason: '' },
+    },
+  ],
+};
+
+const MY_CONNECTIONS = {
+  results: [
+    {
+      id: 'm1', public_id: 'mpub1', name: 'My files', connector_key: 'filesvendor',
+      connector_name: 'File Vendor', external_account_id: '',
+      account_label: 'me@example.com', capabilities_enabled: ['poll'],
+      config: { folder: '/Contracts', recursive: false }, status: 'connected',
+      health: 'ok', auth_mode: 'api_key',
+    },
+  ],
+  permissions: { view: true, manage: true, issue_tokens: false },
+};
+
+function stubMemberApi(overrides: Partial<MemberConnectionsApi> = {}): MemberConnectionsApi {
+  return {
+    connectorCatalog: vi.fn().mockResolvedValue(MEMBER_CATALOG),
+    connections: vi.fn().mockResolvedValue(MY_CONNECTIONS),
+    connect: vi.fn().mockResolvedValue(MY_CONNECTIONS.results[0]),
+    checkConnection: vi.fn().mockResolvedValue({ ok: true, account_label: '', detail: 'ok' }),
+    rotateCredential: vi.fn().mockResolvedValue(MY_CONNECTIONS.results[0]),
+    disconnect: vi.fn().mockResolvedValue(undefined),
+    connectionRuns: vi.fn().mockResolvedValue({ results: [] }),
+    updateConnectionConfig: vi.fn().mockResolvedValue(MY_CONNECTIONS.results[0]),
+    ...overrides,
+  } as MemberConnectionsApi;
+}
+
+async function myCard(api: MemberConnectionsApi = stubMemberApi()) {
+  render(<ConnectionsPage mode="personal" api={api} />);
+  const card = await screen.findByText('My files');
+  return (card.closest('div[data-connection]') ?? card.parentElement!) as HTMLElement;
+}
+
+// --------------------------------------------------------------------------
+//  the control exists, and it is the narrow one
+// --------------------------------------------------------------------------
+
+describe('the member card can change its own scope', () => {
+  it('offers Settings on a connector that declares config fields', async () => {
+    const section = await myCard();
+    expect(
+      within(section).getByRole('button', { name: /Settings/i }),
+    ).toBeInTheDocument();
+  });
+
+  it('still offers no Save beside the capability picker', async () => {
+    // The verb is narrow ON PURPOSE. What a member's account may DO stays the
+    // foundry's, so gating both controls on one verb would hand back exactly the
+    // decision this change did not make.
+    const section = await myCard();
+    expect(within(section).queryByRole('button', { name: /^Save$/i })).toBeNull();
+    expect(
+      within(section).getByText(/Ask an admin to change what this account may do/i),
+    ).toBeInTheDocument();
+  });
+
+  it('saves the fields the member changed, and nothing else', async () => {
+    const updateConnectionConfig = vi.fn().mockResolvedValue(MY_CONNECTIONS.results[0]);
+    const section = await myCard(stubMemberApi({ updateConnectionConfig }));
+
+    await userEvent.click(within(section).getByRole('button', { name: /Settings/i }));
+    await userEvent.clear(within(section).getByLabelText(/^Folder$/i));
+    await userEvent.type(within(section).getByLabelText(/^Folder$/i), '/Invoices');
+    await userEvent.click(within(section).getByRole('button', { name: /Save settings/i }));
+
+    await waitFor(() => expect(updateConnectionConfig).toHaveBeenCalled());
+    expect(updateConnectionConfig.mock.calls[0]).toEqual(['m1', { folder: '/Invoices' }]);
+  });
+
+  it('sends a real boolean when a switch is turned ON', async () => {
+    // `bool("false")` is `true`. A switch that travels as a string is the whole
+    // reason `type` exists on a field spec.
+    const updateConnectionConfig = vi.fn().mockResolvedValue(MY_CONNECTIONS.results[0]);
+    const section = await myCard(stubMemberApi({ updateConnectionConfig }));
+
+    await userEvent.click(within(section).getByRole('button', { name: /Settings/i }));
+    await userEvent.click(within(section).getByLabelText(/Include sub-folders/i));
+    await userEvent.click(within(section).getByRole('button', { name: /Save settings/i }));
+
+    await waitFor(() => expect(updateConnectionConfig).toHaveBeenCalled());
+    expect(updateConnectionConfig.mock.calls[0][1]).toEqual({ recursive: true });
+  });
+
+  it('sends a real boolean when a switch is turned OFF', async () => {
+    // Against a MERGING api, a client that drops falsy values makes the off
+    // position literally unreachable — for a scope switch that is the narrow
+    // setting nobody can get back to.
+    const updateConnectionConfig = vi.fn().mockResolvedValue(MY_CONNECTIONS.results[0]);
+    const api = stubMemberApi({
+      updateConnectionConfig,
+      connections: vi.fn().mockResolvedValue({
+        ...MY_CONNECTIONS,
+        results: [{
+          ...MY_CONNECTIONS.results[0],
+          config: { folder: '/Contracts', recursive: true },
+        }],
+      }),
+    });
+    const section = await myCard(api);
+
+    await userEvent.click(within(section).getByRole('button', { name: /Settings/i }));
+    await userEvent.click(within(section).getByLabelText(/Include sub-folders/i));
+    await userEvent.click(within(section).getByRole('button', { name: /Save settings/i }));
+
+    await waitFor(() => expect(updateConnectionConfig).toHaveBeenCalled());
+    expect(updateConnectionConfig.mock.calls[0][1]).toEqual({ recursive: false });
+  });
+});
+
+// --------------------------------------------------------------------------
+//  what the server says, the member reads
+// --------------------------------------------------------------------------
+
+describe('the member is told what the change costs', () => {
+  it('renders the notices the SERVER returned, verbatim', async () => {
+    const sentence =
+      'Changing what this connection covers restarts the walk: the next run '
+      + 're-reads this account from the beginning.';
+    const updateConnectionConfig = vi.fn().mockResolvedValue({
+      ...MY_CONNECTIONS.results[0], notices: [sentence],
+    });
+    const section = await myCard(stubMemberApi({ updateConnectionConfig }));
+
+    await userEvent.click(within(section).getByRole('button', { name: /Settings/i }));
+    await userEvent.click(within(section).getByLabelText(/Include sub-folders/i));
+    await userEvent.click(within(section).getByRole('button', { name: /Save settings/i }));
+
+    await waitFor(() => expect(screen.getByText(sentence)).toBeInTheDocument());
+  });
+
+  it('says nothing extra when the server said nothing', async () => {
+    const section = await myCard();
+    await userEvent.click(within(section).getByRole('button', { name: /Settings/i }));
+    await userEvent.click(within(section).getByLabelText(/Include sub-folders/i));
+    await userEvent.click(within(section).getByRole('button', { name: /Save settings/i }));
+    await waitFor(() =>
+      expect(within(section).getByText(/Settings saved/i)).toBeInTheDocument());
+    expect(within(section).queryByText(/from the beginning/i)).toBeNull();
+  });
+});
+
+// --------------------------------------------------------------------------
+//  an acknowledgement is a control, and it shows who claimed it
+// --------------------------------------------------------------------------
+
+describe('CredentialSchemaForm renders an acknowledgement as consent', () => {
+  function renderAck(stored: unknown, onChange = vi.fn()) {
+    render(
+      <CredentialSchemaForm
+        fields={SCOPE_FIELDS}
+        values={{ whole_account_acknowledged_by: stored }}
+        onChange={onChange}
+      />,
+    );
+    return onChange;
+  }
+
+  it('is a checkbox, not a box to type somebody’s name into', () => {
+    renderAck('');
+    const control = screen.getByLabelText(/Whole-account read claimed by/i);
+    expect(control).toHaveAttribute('type', 'checkbox');
+    expect((control as HTMLInputElement).checked).toBe(false);
+  });
+
+  it('emits a boolean, because the SERVER writes who and when', () => {
+    const onChange = renderAck('');
+    return userEvent.click(screen.getByLabelText(/Whole-account read claimed by/i)).then(() => {
+      expect(onChange).toHaveBeenCalledWith('whole_account_acknowledged_by', true);
+    });
+  });
+
+  it('shows the recorded attribution once somebody has claimed it', () => {
+    // A control that records nothing would be worse than the text box it
+    // replaced. The record has to be READABLE, or nobody can check it.
+    renderAck('dana.reed@example.com on 2026-08-27T09:00:00Z');
+    const control = screen.getByLabelText(/Whole-account read claimed by/i) as HTMLInputElement;
+    expect(control.checked).toBe(true);
+    expect(screen.getByText(/dana\.reed@example\.com/)).toBeInTheDocument();
+    expect(screen.getByText(/2026-08-27T09:00:00Z/)).toBeInTheDocument();
+  });
+});
+
+// --------------------------------------------------------------------------
+//  and the client lands on the narrow route
+// --------------------------------------------------------------------------
+
+describe('connectionsMe.updateConnectionConfig', () => {
+  interface Call { url: string; method: string; body: unknown }
+  let calls: Call[] = [];
+
+  beforeEach(() => {
+    calls = [];
+    setApiBase('/api/v1');
+    setAuthTokenProvider(null);
+    vi.stubGlobal('fetch', vi.fn(async (url: string, init: RequestInit = {}) => {
+      calls.push({
+        url: String(url),
+        method: init.method ?? 'GET',
+        body: init.body ? JSON.parse(String(init.body)) : undefined,
+      });
+      return new Response(JSON.stringify({ id: 'm1' }), {
+        status: 200, headers: { 'Content-Type': 'application/json' },
+      });
+    }));
+  });
+
+  afterEach(() => { vi.unstubAllGlobals(); });
+
+  it('PATCHes the CONFIG sub-route, not the detail route', async () => {
+    // Beside `credential/`, and for the same reason it is: a scope change has to
+    // pass the connector's own refusal before it replaces a working setting.
+    // The detail route keeps having no PATCH at all.
+    await connectionsMe.updateConnectionConfig!('abc', { folder: '/Invoices' });
+    expect(calls[0].url).toBe('/api/v1/connections/me/abc/config/');
+    expect(calls[0].method).toBe('PATCH');
+    expect(calls[0].body).toEqual({ config: { folder: '/Invoices' } });
+  });
+
+  it('names no slug, no foundry and no user', async () => {
+    await connectionsMe.updateConnectionConfig!('abc', { folder: '/Invoices' });
+    expect(calls[0].url.startsWith('/api/v1/connections/me/')).toBe(true);
+    expect(calls[0].url).not.toMatch(/[?&]/);
+    expect(JSON.stringify(calls[0].body)).not.toMatch(
+      /slug|foundry|tenant|company|owner|user_id/i);
+  });
+});

package/src/api/connections.ts

@@ -18,11 +18,18 @@
  * token in flight decides which foundry answers, and nothing here can override
  * that.
  *
- * WHAT IS ABSENT IS ALSO THE CONTRACT. There is no `updateConnection` because
- * `MyConnectionDetailView` serves GET and DELETE only; no choices, targets,
- * actions or `ConnectionToken`s because those are foundry-level and stay
- * owner-exclusive on the control-plane router. Adding one here would be a client
- * for a route that does not exist.
+ * WHAT IS ABSENT IS ALSO THE CONTRACT. There is still no `updateConnection`:
+ * `MyConnectionDetailView` serves GET and DELETE only, so a card's name and what
+ * it may DO stay with the foundry. No choices, targets, actions or
+ * `ConnectionToken`s either — those are foundry-level and owner-exclusive on the
+ * control-plane router. Adding one here would be a client for a route that does
+ * not exist.
+ *
+ * `updateConnectionConfig` is the ONE write verb that was added (bd
+ * startsim-sfms2), and it points at `me/<id>/config/` rather than at the detail
+ * route for the same reason `rotateCredential` points at `credential/`: a change
+ * that has to pass a gate gets its own route instead of a field on a general
+ * PATCH.
  *
  * WHERE IT POINTS. Through `request()`, so `setApiBase` and
  * `setAuthTokenProvider` apply: a tenant app points the base at its own
@@ -155,6 +162,37 @@ export const connectionsMe: MemberConnectionsApi = {
     });
   },
 
+  /**
+   * CHANGE THE SETTINGS OF MY OWN CARD (bd startsim-sfms2).
+   *
+   * The folder a Dropbox connection reads, and whether it recurses. On a
+   * personal connection that is not a pipeline setting — it is which of the
+   * member's own files this platform is allowed to see — so it is theirs to set,
+   * and the alternative was disconnect + re-consent, which throws a working
+   * token away to change a string.
+   *
+   * A SUB-ROUTE, not a PATCH on the detail view. `credential/` is the precedent
+   * one door down: rotation is not on PATCH either, because a new key has to
+   * pass `check()` before it replaces a working one. A scope change has the same
+   * shape — it must pass the connector's own refusal, and it restarts the walk.
+   *
+   * PARTIAL and MERGING, exactly like `rotateCredential`: send the fields that
+   * changed and the stored values fill in the rest. `null` unsets one. The server
+   * refuses any key the connector does not declare, and refuses any TOP-LEVEL key
+   * that is not `config` — a body naming `capabilities_enabled` is a 400 and not
+   * a silent no-op.
+   *
+   * The response may carry `notices`: sentences the server wrote about what the
+   * change costs. Rendered verbatim, never composed in the browser.
+   */
+  updateConnectionConfig(
+    id: string, config: Record<string, unknown>,
+  ): Promise<Connection> {
+    return request<Connection>(`${BASE}/${id}/config/`, {
+      method: 'PATCH', body: { config },
+    });
+  },
+
   /**
    * DISCONNECT, not delete. One transaction stops the scheduled fetches, revokes
    * every token issued for the account and deletes the stored credential; the

package/src/components/CredentialSchemaForm.tsx

@@ -51,6 +51,9 @@ export interface CredentialSchemaFormProps {
 /** Field types this build renders natively. Anything else becomes text. */
 const NATIVE_TYPES = new Set(['text', 'url', 'email', 'number', 'select', 'textarea']);
 
+/** The server's spelling for a consent record. See `isAcknowledgement`. */
+const ACKNOWLEDGEMENT = 'acknowledgement';
+
 /**
  * A boolean is a CHECKBOX, and this is not a cosmetic preference.
  *
@@ -61,12 +64,37 @@ const NATIVE_TYPES = new Set(['text', 'url', 'email', 'number', 'select', 'texta
  * conversations are stored, and in a text box the way you turn it off is to type
  * the word "false" — which `bool()` reads as ON.
  */
-const BOOLEAN_TYPES = new Set(['boolean', 'checkbox', 'bool']);
+const BOOLEAN_TYPES = new Set(['boolean', 'checkbox', 'bool', ACKNOWLEDGEMENT]);
 
 export function isBoolean(spec: ConnectorFieldSpec): boolean {
   return !isSecret(spec) && BOOLEAN_TYPES.has(String(spec.type || '').toLowerCase());
 }
 
+/**
+ * An ACKNOWLEDGEMENT is a consent record, not a setting (bd startsim-sfms2).
+ *
+ * It marks the fields that say a named human claimed a disclosure that is legal,
+ * large, and much bigger than most people mean — Dropbox's
+ * `whole_account_acknowledged_by`, which gates reading metadata for every file
+ * in somebody's account.
+ *
+ * Two things follow, and both are why it is not merely `boolean`. What the
+ * person DOES is tick a claim, so this emits `true`/`false` and the SERVER
+ * writes `<who> on <when>` from the authenticated caller — there is no box to
+ * type somebody else's name into, and no request body that can attribute a claim
+ * to anyone but its sender. And what the field HOLDS is that attribution, so it
+ * is rendered beside the control: a claim nobody can read is a record in name
+ * only, which is worse than the text box it replaced.
+ */
+export function isAcknowledgement(spec: ConnectorFieldSpec): boolean {
+  return !isSecret(spec) && String(spec.type || '').toLowerCase() === ACKNOWLEDGEMENT;
+}
+
+/** What the server wrote into an acknowledgement, or '' when nobody has claimed it. */
+export function acknowledgedBy(value: unknown): string {
+  return typeof value === 'string' && asBoolean(value) ? value.trim() : '';
+}
+
 /** The spellings of "off" that can arrive from a stored config or a form. */
 export function asBoolean(value: unknown): boolean {
   if (typeof value === 'string') {
@@ -185,6 +213,15 @@ export function CredentialSchemaForm({
               />
             )}
 
+            {/* THE RECORD, beside the control that made it. `who` and `when`
+                are written by the server; nothing here can author or edit them.
+                Rendered because a consent record nobody can read is not one. */}
+            {isAcknowledgement(spec) && acknowledgedBy(stored) ? (
+              <p className={classNames.help ?? 'mt-1 text-xs text-gray-500'}>
+                Claimed by {acknowledgedBy(stored)}
+              </p>
+            ) : null}
+
             {spec.help ? (
               <p className={classNames.help ?? 'mt-1 text-xs text-gray-500'}>{spec.help}</p>
             ) : null}

package/src/components/pages/ConnectionsPage.tsx

@@ -111,6 +111,20 @@ interface BoundApi {
   updateConnection?(id: string, input: {
     name?: string; capabilities_enabled?: string[]; config?: Record<string, unknown>;
   }): Promise<Connection>;
+  /**
+   * SETTINGS ALONE, and separate from `updateConnection` on purpose
+   * (bd startsim-sfms2).
+   *
+   * Both surfaces have it; only the control plane has `updateConnection`. A
+   * personal connection's config is the MEMBER's privacy boundary — which of
+   * their own files this platform reads — while its name and what it may DO are
+   * the foundry's. One verb carrying all three would have made the Settings
+   * control and the capability Save appear together, so opening the first would
+   * have opened the second by accident.
+   */
+  updateConnectionConfig?(
+    id: string, config: Record<string, unknown>,
+  ): Promise<Connection>;
   connectionChoices?(id: string, params?: { kind?: string; cursor?: string }):
     Promise<ConnectionChoicePage>;
   wireTarget?(id: string, input: {
@@ -177,6 +191,12 @@ function bindApi(props: ConnectionsPageProps): BoundApi {
     rotateCredential: (id, credentials) => api.rotateCredential(slug, id, credentials),
     disconnect: (id) => api.disconnect(slug, id),
     updateConnection: (id, input) => api.updateConnection(slug, id, input),
+    // The control plane reaches settings through the same PATCH it reaches
+    // everything else with; the narrow verb is a property of the MEMBER router,
+    // not of the form. Both modes therefore satisfy the same bound signature and
+    // the settings form never learns which surface it is on.
+    updateConnectionConfig: (id, config) =>
+      api.updateConnection(slug, id, { config }),
     connectionChoices: (id, params) => api.connectionChoices(slug, id, params),
     wireTarget: (id, input) => api.wireTarget(slug, id, input),
     confirmTarget: (id, destinationId) => api.confirmTarget(slug, id, destinationId),
@@ -971,7 +991,8 @@ function ConnectionSettingsForm({
   connection: Connection;
   fields: ConnectorFieldSpec[];
   classNames: typeof DEFAULTS;
-  onDone: () => void;
+  /** Handed whatever the SERVER said about the change, so the card can say it. */
+  onDone: (notices: string[]) => void;
 }) {
   const stored = React.useMemo(
     () => (connection.config ?? {}) as Record<string, unknown>,
@@ -1001,8 +1022,15 @@ function ConnectionSettingsForm({
             ? Number(value)
             : value;
       }
-      await api.updateConnection!(connection.id, { config });
-      onDone();
+      const saved = await api.updateConnectionConfig!(connection.id, config);
+      // WHAT THE SERVER WANTS THEM TO KNOW, handed up rather than rendered here.
+      // The live case is a scope change restarting the walk, and this file
+      // cannot work that out: it names no vendor and therefore cannot know which
+      // fields bear the scope. A heuristic on field names would be both a vendor
+      // branch and untestable at the level that matters. Handed to the CARD
+      // because saving closes this panel, and a sentence that unmounts with the
+      // form is one nobody reads.
+      onDone(saved?.notices ?? []);
     } catch (err) {
       setError((err as { message?: string })?.message || 'Those settings were not saved.');
     } finally {
@@ -1055,6 +1083,8 @@ function ConnectionCard({
   const [busy, setBusy] = React.useState('');
   const [error, setError] = React.useState('');
   const [notice, setNotice] = React.useState('');
+  /** Sentences the SERVER wrote about the last settings save. Never composed here. */
+  const [notices, setNotices] = React.useState<string[]>([]);
   const [replacing, setReplacing] = React.useState(false);
   const [settingsOpen, setSettingsOpen] = React.useState(false);
   const [confirmingDisconnect, setConfirmingDisconnect] = React.useState(false);
@@ -1164,8 +1194,16 @@ function ConnectionCard({
                 all, which for Granola means the switch deciding whether verbatim
                 recordings of people's conversations are stored was reachable
                 only by editing the database. `ReplaceKeyForm` already pointed at
-                "the connection's own settings" as if this existed. */}
-            {configFields.length && api.updateConnection ? (
+                "the connection's own settings" as if this existed.
+
+                GATED ON THE SETTINGS VERB, not on the general one (bd
+                startsim-sfms2). The member surface has `updateConnectionConfig`
+                and deliberately not `updateConnection`, because a personal
+                connection's config is the MEMBER's privacy boundary while its
+                name and what it may do stay the foundry's. One gate for both
+                would have made opening this control open the capability Save
+                beside it, which is a decision this change did not make. */}
+            {configFields.length && api.updateConnectionConfig ? (
               <button
                 type="button"
                 className={cn.button}
@@ -1202,7 +1240,12 @@ function ConnectionCard({
           connection={connection}
           fields={configFields}
           classNames={cn}
-          onDone={() => { setSettingsOpen(false); setNotice('Settings saved.'); onChanged(); }}
+          onDone={(said) => {
+            setSettingsOpen(false);
+            setNotice('Settings saved.');
+            setNotices(said);
+            onChanged();
+          }}
         />
       ) : null}
 
@@ -1308,6 +1351,11 @@ function ConnectionCard({
       </CapabilityPicker>
 
       {notice ? <p className={cn.muted}>{notice}</p> : null}
+      {/* WHAT THE CHANGE COSTS, in the server's words. Rendered verbatim: this
+          file names no vendor and cannot know which settings restart a walk. */}
+      {notices.map((said) => (
+        <p key={said} className={cn.muted}>{said}</p>
+      ))}
       {error ? <p className={cn.error} role="alert">{error}</p> : null}
 
       {choices ? (

package/src/components/pages/types.ts

@@ -29,7 +29,12 @@ export interface ConnectorFieldSpec {
   help?: string;
   placeholder?: string;
   options?: Array<{ value: string; label: string }> | null;
-  default?: string | null;
+  /**
+   * What happens if nobody touches this field. `unknown`, not `string`: a config
+   * schema declares booleans and numbers, and a `default: false` typed as a
+   * string is the same class of lie as a checkbox rendered as a text box.
+   */
+  default?: unknown;
   pattern?: string | null;
   docs_url?: string;
 }
@@ -148,6 +153,16 @@ export interface Connection {
   auth_mode: string;
   check_error?: string;
   last_checked_at?: string | null;
+  /**
+   * WHAT THE SERVER WANTS THE PERSON WHO JUST SAVED TO KNOW. Present on the
+   * response to a config write and NOWHERE else — never stored, never on a GET.
+   *
+   * The live case is a scope change: it restarts the walk, because the connector
+   * discards a sync cursor whose scope no longer matches. This composer refuses
+   * to name a vendor and cannot know which fields bear the scope; only the
+   * connector does, so only the server can say it. Rendered verbatim.
+   */
+  notices?: string[];
 }
 
 /** What to RENDER, never what to allow. The server refuses on its own. */
@@ -389,11 +404,37 @@ export interface MemberConnectionsApi {
     config?: Record<string, unknown>;
     /**
      * Chosen once, at connect time, and not editable afterwards on this
-     * surface — there is no PATCH. The picker on an existing card is therefore
-     * informational, and saying so is the honest rendering of both halves.
+     * surface — the detail route has no PATCH and `config/` accepts nothing
+     * else. The picker on an existing card is therefore informational, and
+     * saying so is the honest rendering of both halves.
      */
     capabilities_enabled?: string[];
   }): Promise<Connection>;
+  /**
+   * CHANGE THE SETTINGS OF A CONNECTION I OWN (bd startsim-sfms2).
+   *
+   * The one write verb this surface grew, and it is narrow on purpose. A
+   * personal connection's config is not a pipeline setting: it names the folder
+   * of somebody's own account this platform may read. Routing that through an
+   * admin makes another person the author of that member's privacy boundary,
+   * and the only re-scope available without it was disconnect + re-consent —
+   * throwing away a working token to change a string.
+   *
+   * NOT `updateConnection`, and the difference is load-bearing: the foundry
+   * verb of that name also carries `name` and `capabilities_enabled`, which stay
+   * the foundry's. A composer that gated both controls on one verb would hand
+   * back a decision this change did not make.
+   *
+   * PARTIAL and MERGING: send the fields that changed. `null` unsets one. The
+   * server refuses any key the connector does not declare.
+   *
+   * Optional so an app pinned to an older `@startsimpli/api` keeps
+   * type-checking; the card renders the Settings control only when the verb is
+   * present, so a stale client degrades to no control rather than a dead button.
+   */
+  updateConnectionConfig?(
+    id: string, config: Record<string, unknown>,
+  ): Promise<Connection>;
   checkConnection(id: string): Promise<{
     ok: boolean; account_label: string; detail: string;
   }>;