@startsimpli/integrations 0.2.21 → 0.2.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.21",
+  "version": "0.2.22",
   "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/components/index.ts

@@ -17,6 +17,7 @@ export type {
   ConnectorCatalogEntry,
   ConnectorFieldSpec,
   Connection as FoundryConnection,
+  MemberConnectionRow,
   ConnectionPermissions,
   ConnectionChoice,
   ConnectionChoicePage,

package/src/components/pages/ConnectionsPage.tsx

@@ -52,8 +52,10 @@ import type {
   ConnectorCatalogEntry,
   ConnectorFieldSpec,
   ConnectionsApi,
+  MemberConnectionRow,
   MemberConnectionsApi,
 } from './types';
+import { MemberConnectionRoster } from './MemberConnectionRoster';
 
 type ClassNames = Partial<Record<
   'root' | 'section' | 'heading' | 'card' | 'button' | 'muted' | 'error', string
@@ -119,6 +121,13 @@ interface BoundApi {
   invokeConnectionAction?(id: string, action: string, input: {
     destination_id: string; record_type?: string; records?: unknown[];
   }): 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`. */
+  setMemberConnectorPolicy?(connectorKey: string, allowed: boolean): Promise<unknown>;
+  memberConnections?(): Promise<{
+    results: MemberConnectionRow[]; permissions: ConnectionPermissions;
+  }>;
+  disconnectMemberConnection?(id: string): Promise<void>;
 }
 
 function bindApi(props: ConnectionsPageProps): BoundApi {
@@ -128,7 +137,24 @@ function bindApi(props: ConnectionsPageProps): BoundApi {
     return props.api;
   }
   const { api, foundrySlug: slug } = props;
+  // Bound only when the injected client HAS them, so `verb in api` stays the
+  // test the components run — a wrapper that always exists and throws inside
+  // would render the control and fail on click.
+  const memberPolicy = api.setMemberConnectorPolicy
+    ? { setMemberConnectorPolicy: (key: string, allowed: boolean) =>
+      api.setMemberConnectorPolicy!(slug, key, allowed) }
+    : {};
+  const roster = api.memberConnections
+    ? { memberConnections: () => api.memberConnections!(slug) }
+    : {};
+  const cutMember = api.disconnectMemberConnection
+    ? { disconnectMemberConnection: (id: string) =>
+      api.disconnectMemberConnection!(slug, id) }
+    : {};
   return {
+    ...memberPolicy,
+    ...roster,
+    ...cutMember,
     connectorCatalog: () => api.connectorCatalog(slug),
     connections: () => api.connections(slug),
     connect: (input) => api.connect(slug, input),
@@ -303,6 +329,10 @@ export function ConnectionsPage(props: ConnectionsPageProps) {
             api={api}
             personal={personal}
             entry={entry}
+            /* Refreshing the CATALOG is what makes a flipped toggle stick — the
+               allowed flag rides on the row, so re-reading connections alone
+               would leave the switch showing the value it was rendered with. */
+            onPolicyChanged={reload}
             // What ALREADY exists on this connector — in personal mode that is
             // the member's own cards and nobody else's, because `connections`
             // came back owner-scoped. A second vendor account is legitimate and
@@ -315,6 +345,24 @@ export function ConnectionsPage(props: ConnectionsPageProps) {
           />
         ))}
       </section>
+
+      {/* THE OTHER HALF OF THE ALLOWLIST (bd startsim-768w.22.25.8): who has
+          actually connected. Its own component, and deliberately not folded into
+          the two sections above — those render the viewer's own rows and this
+          one enumerates OTHER PEOPLE'S accounts, which is a different entity, a
+          different serializer and a different disclosure. Keeping "list every
+          member's connections" outside the component whose security property is
+          that personal and foundry rows never mix means one forgotten `personal`
+          guard cannot leak it. It renders in foundry mode only, and only when
+          the api has the verb. */}
+      {!personal && api.memberConnections ? (
+        <MemberConnectionRoster
+          list={api.memberConnections}
+          disconnect={api.disconnectMemberConnection}
+          canManage={permissions.manage}
+          classNames={cn}
+        />
+      ) : null}
     </div>
   );
 }
@@ -394,6 +442,7 @@ function orderCapabilities(declared: string[], selected: Iterable<string>): stri
 
 function CatalogCard({
   api, personal, entry, existing, canManage, classNames: cn, onConnected,
+  onPolicyChanged,
 }: {
   api: BoundApi;
   personal: boolean;
@@ -403,6 +452,8 @@ function CatalogCard({
   canManage: boolean;
   classNames: typeof DEFAULTS;
   onConnected: () => void;
+  /** Re-read the catalog after the member toggle is written. Foundry mode only. */
+  onPolicyChanged?: () => void;
 }) {
   const [open, setOpen] = React.useState(false);
   const [values, setValues] = React.useState<Record<string, unknown>>({});
@@ -482,6 +533,20 @@ function CatalogCard({
         ) : null}
       </div>
 
+      {/* On the card it governs, not on a settings list of its own — an admin
+          should not have to hold two lists of connectors in their head to know
+          which ones members can use. */}
+      {!personal && api.setMemberConnectorPolicy && entry.member_policy ? (
+        <MemberPolicyToggle
+          connectorKey={entry.key}
+          policy={entry.member_policy}
+          canManage={canManage}
+          write={api.setMemberConnectorPolicy}
+          classNames={cn}
+          onChanged={onPolicyChanged}
+        />
+      ) : null}
+
       {open ? (
         <div className="mt-4 space-y-3">
           {/* SAID BEFORE THE KEY IS PASTED, not after the server refuses.
@@ -551,6 +616,105 @@ function CatalogCard({
   );
 }
 
+// --------------------------------------------------------------------------
+//  who may connect their OWN account (bd startsim-768w.22.25.8)
+// --------------------------------------------------------------------------
+
+/**
+ * ONE CONNECTOR, ONE DECISION: may this foundry's members connect their own
+ * account on it?
+ *
+ * DEFAULT-DENY, and the copy has to carry that, because the switch is not a
+ * display preference. Turning it on means members send THEIR vendor data into
+ * this foundry, under their own credentials, for this foundry to store and
+ * process — an admin is agreeing to receive that, and is entitled to read it in
+ * those words before flipping anything.
+ *
+ * TURNING IT OFF IS NOT A KILL SWITCH, and saying so in the confirmation rather
+ * than in a docs page is the point. Off stops NEW personal connections
+ * immediately; every connection that already exists keeps running, with its
+ * credential and its scheduled fetches. Ending those is one explicit disconnect
+ * per person from the roster below — destructive, irreversible, and never a side
+ * effect of tightening a default. The wording here is the server's own, lifted
+ * from `apps/connectors/services/policy.py` so the two cannot drift apart.
+ *
+ * A connector that CANNOT be opened yet renders disabled WITH the server's
+ * reason instead of vanishing: an admin who cannot find Dropbox in this list
+ * would reasonably conclude the catalog is broken, when the real answer is that
+ * the member surface has no OAuth path yet.
+ *
+ * THE THIRD STATE IS THE ONE THAT MATTERS: already allowed, and no longer
+ * openable — a connector opened while it was an API key that has since moved to
+ * OAuth, or whose class stopped importing. The server answers `settable: true`
+ * with a `reason`, because the only move an ON switch offers is OFF and the
+ * write always accepts that. Disabling it on `reason` alone would draw a switch
+ * an admin cannot turn off, which is the exact opposite of what a governance
+ * control is for. It renders live, with the reason as a one-way warning.
+ */
+function MemberPolicyToggle({
+  connectorKey, policy, canManage, write, classNames: cn, onChanged,
+}: {
+  connectorKey: string;
+  policy: NonNullable<ConnectorCatalogEntry['member_policy']>;
+  canManage: boolean;
+  write: (connectorKey: string, allowed: boolean) => Promise<unknown>;
+  classNames: typeof DEFAULTS;
+  onChanged?: () => void;
+}) {
+  const [busy, setBusy] = React.useState(false);
+  const [error, setError] = React.useState('');
+  const id = `member-policy-${connectorKey}`;
+
+  async function set(allowed: boolean) {
+    setBusy(true);
+    setError('');
+    try {
+      await write(connectorKey, allowed);
+      onChanged?.();
+    } catch (err) {
+      setError((err as { message?: string })?.message || 'Could not save that.');
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <div className="mt-3 border-t border-gray-100 pt-3" data-member-policy={connectorKey}>
+      <label htmlFor={id} className="flex items-start gap-2 text-sm">
+        <input
+          id={id}
+          type="checkbox"
+          className="mt-0.5"
+          checked={policy.allowed}
+          disabled={busy || !canManage || !policy.settable}
+          onChange={(event) => void set(event.target.checked)}
+        />
+        <span>
+          <span className="text-gray-900">Members may connect their own account</span>
+          <span className={`block ${cn.muted}`}>
+            {policy.settable
+              ? 'Each member signs in with their own key, and sees only their own'
+                + ' data. Allowing this means their vendor data flows into this'
+                + ' foundry. Turning it off later stops new connections — the ones'
+                + ' already connected keep running until you disconnect them below.'
+              : policy.reason}
+          </span>
+          {/* Settable AND blocked: open today, unopenable tomorrow. Said next to
+              the switch rather than after the click, because the click is the
+              irreversible half. */}
+          {policy.settable && policy.reason ? (
+            <span className={`block ${cn.error}`} data-member-policy-oneway={connectorKey}>
+              This is on, but can no longer be turned back on once off:{' '}
+              {policy.reason}
+            </span>
+          ) : null}
+        </span>
+      </label>
+      {error ? <p className={cn.error} role="alert">{error}</p> : null}
+    </div>
+  );
+}
+
 // --------------------------------------------------------------------------
 //  replacing the key on a connection that already exists
 // --------------------------------------------------------------------------

package/src/components/pages/MemberConnectionRoster.tsx

@@ -0,0 +1,182 @@
+/**
+ * WHO IN THIS FOUNDRY HAS CONNECTED THEIR OWN ACCOUNT (bd startsim-768w.22.25.8).
+ *
+ * The other half of the allowlist. `MemberPolicyToggle` decides which connectors
+ * are open; this says who walked through the door, and gives an admin the one
+ * verb offboarding needs — cut a departing member's pipes.
+ *
+ * ITS OWN FILE, ON PURPOSE. `ConnectionsPage` renders two lists that belong to
+ * whoever is looking at it, and its whole security property is that the personal
+ * and foundry surfaces never see each other's rows. This list is the deliberate
+ * exception: it enumerates OTHER PEOPLE'S accounts, from a different endpoint,
+ * through a different serializer, behind a foundry permission. Keeping it out of
+ * the composer's own body means one forgotten `personal` guard in there cannot
+ * put somebody else's connections on a member's screen.
+ *
+ * METADATA ONLY, and there is nothing to widen. The server sends who, which
+ * vendor, whether it is working and when it was last checked; there is no
+ * credential, no masked hint, no config, and no verb here that reads into an
+ * account or replaces its key. Ending someone's access is governance and an
+ * admin needs it. Taking their account over is impersonation and no foundry
+ * permission grants it.
+ */
+import * as React from 'react';
+
+import type {
+  ConnectionPermissions,
+  MemberConnectionRow,
+} from './types';
+
+type ClassNames = {
+  section: string; heading: string; card: string; button: string;
+  muted: string; error: string;
+};
+
+export function MemberConnectionRoster({
+  list, disconnect, canManage, classNames: cn,
+}: {
+  list: () => Promise<{ results: MemberConnectionRow[]; permissions: ConnectionPermissions }>;
+  disconnect?: (id: string) => Promise<void>;
+  canManage: boolean;
+  classNames: ClassNames;
+}) {
+  const [rows, setRows] = React.useState<MemberConnectionRow[]>([]);
+  const [loading, setLoading] = React.useState(true);
+  const [error, setError] = React.useState('');
+
+  const reload = React.useCallback(async () => {
+    setLoading(true);
+    try {
+      const page = await list();
+      setRows(page.results ?? []);
+      setError('');
+    } catch (err) {
+      // A control plane that predates these endpoints answers 404. That is not
+      // an error an admin can act on, so the section reports nothing and shows
+      // nothing rather than putting a red bar under a working page.
+      const status = (err as { status?: number })?.status;
+      setError(status === 404 ? '' : ((err as { message?: string })?.message
+        || 'Could not load members’ connections.'));
+      setRows([]);
+    } finally {
+      setLoading(false);
+    }
+  }, [list]);
+
+  React.useEffect(() => { void reload(); }, [reload]);
+
+  return (
+    <section className={cn.section} data-member-roster>
+      <h2 className={cn.heading}>Members’ own connections</h2>
+      <p className={cn.muted}>
+        Accounts individual members connected with their own credentials. You can
+        see that they exist and whether they are working; you cannot see or
+        replace their keys. Disconnecting is permanent — it stops the account’s
+        scheduled fetches, revokes its tokens and deletes the stored key, and the
+        member has to reconnect with the vendor to come back.
+      </p>
+      {loading && rows.length === 0 ? <p className={cn.muted}>Loading…</p> : null}
+      {error ? <p className={cn.error} role="alert">{error}</p> : null}
+      {!loading && !error && rows.length === 0 ? (
+        <p className={cn.muted}>No member has connected their own account yet.</p>
+      ) : null}
+      {rows.map((row) => (
+        <MemberConnectionCard
+          key={row.id}
+          row={row}
+          canManage={canManage}
+          disconnect={disconnect}
+          classNames={cn}
+          onChanged={reload}
+        />
+      ))}
+    </section>
+  );
+}
+
+function MemberConnectionCard({
+  row, canManage, disconnect, classNames: cn, onChanged,
+}: {
+  row: MemberConnectionRow;
+  canManage: boolean;
+  disconnect?: (id: string) => Promise<void>;
+  classNames: ClassNames;
+  onChanged: () => void;
+}) {
+  const [confirming, setConfirming] = React.useState(false);
+  const [busy, setBusy] = React.useState(false);
+  const [error, setError] = React.useState('');
+  const who = row.owner?.email || row.owner?.name || 'Unknown member';
+
+  async function cut() {
+    if (!disconnect) return;
+    setBusy(true);
+    setError('');
+    try {
+      await disconnect(row.id);
+      setConfirming(false);
+      onChanged();
+    } catch (err) {
+      setError((err as { message?: string })?.message || 'Could not disconnect.');
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <div className={cn.card} data-member-connection={row.id}>
+      <div className="flex items-start justify-between gap-4">
+        <div>
+          <p className="font-medium text-gray-900">{who}</p>
+          <p className={cn.muted}>
+            {row.connector_name}
+            {row.account_label ? ` · ${row.account_label}` : ''}
+          </p>
+          <p className="mt-1 text-xs text-gray-400">
+            {row.status}
+            {row.health ? ` · ${row.health}` : ''}
+            {row.last_checked_at
+              ? ` · last checked ${new Date(row.last_checked_at).toLocaleString()}`
+              : ' · never checked'}
+          </p>
+          {/* The vendor's own failure text, which the server already scrubbed of
+              anything the member submitted. An admin deciding whether to cut a
+              pipe is entitled to know it is already broken. */}
+          {row.check_error ? <p className={cn.error}>{row.check_error}</p> : null}
+        </div>
+        {canManage && disconnect ? (
+          <button
+            type="button"
+            className={cn.button}
+            disabled={busy}
+            onClick={() => setConfirming((v) => !v)}
+          >
+            {confirming ? 'Cancel' : 'Disconnect'}
+          </button>
+        ) : null}
+      </div>
+      {confirming ? (
+        <div className="mt-3 space-y-2">
+          {/* NAMES THE PERSON, because the cost of this button falls on them and
+              not on the admin pressing it. A generic "are you sure?" over a list
+              of near-identical rows is how the wrong pipe gets cut. */}
+          <p className={cn.muted}>
+            Disconnect <strong className="text-gray-900">{who}</strong>’s{' '}
+            {row.connector_name} account? Their stored key is deleted and their
+            scheduled fetches stop. This cannot be undone — they would have to
+            connect again themselves.
+          </p>
+          {error ? <p className={cn.error} role="alert">{error}</p> : null}
+          <button
+            type="button"
+            className={cn.button}
+            disabled={busy}
+            onClick={() => void cut()}
+          >
+            {busy ? 'Disconnecting…' : 'Yes, disconnect'}
+          </button>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/pages/types.ts

@@ -61,6 +61,47 @@ export interface ConnectorCatalogEntry {
   supports_webhooks: boolean;
   /** A row whose class will not import says so here rather than vanishing. */
   availability: { available: boolean; reason: string };
+  /**
+   * MAY MEMBERS CONNECT THEIR OWN ACCOUNT ON THIS ONE (bd startsim-768w.22.25.8).
+   *
+   * Present on the FOUNDRY catalog only — the member catalog is already filtered
+   * to what is allowed, so the field would be a constant `true` there and a
+   * client could mistake it for a control the member has.
+   *
+   * Optional because an app may be running against a control plane that predates
+   * this field; the toggle renders when the catalog says so and the api has the
+   * verb, never on an assumption about either.
+   *
+   *   allowed   the stored answer — is this connector open to members today
+   *   settable  may it be CHANGED at all. `false` is not "you lack permission";
+   *             it is "this connector cannot be offered to members yet"
+   *   reason    why not, in an admin's words, when `settable` is false
+   */
+  member_policy?: { allowed: boolean; settable: boolean; reason: string };
+}
+
+/**
+ * One member's own connection, as the ADMIN roster sees it (bd
+ * startsim-768w.22.25.8).
+ *
+ * Note what is NOT here and cannot be added by widening a type: no credential,
+ * no masked hint, no config, no token. An admin governs which connectors are
+ * open and ends access when somebody leaves; neither act needs to see inside
+ * another person's account. The server serializes exactly these fields for the
+ * same reason.
+ */
+export interface MemberConnectionRow {
+  id: string;
+  owner: { id: string; email: string; name: string };
+  connector_key: string;
+  connector_name: string;
+  name: string;
+  account_label: string;
+  status: ConnectionStatus;
+  health: string;
+  last_checked_at?: string | null;
+  check_error?: string;
+  created_at?: string;
 }
 
 export type ConnectionStatus = 'connected' | 'needs_reauth' | 'error' | 'disabled';
@@ -219,6 +260,45 @@ export interface ConnectionsApi {
     destination_id: string; record_type?: string; records?: unknown[];
   }): Promise<ConnectionInvokeResult>;
   connectionRuns(slug: string, id: string): Promise<{ results: ConnectionRun[] }>;
+
+  /**
+   * GOVERNING PER-MEMBER CONNECTIONS (bd startsim-768w.22.25.8) — three verbs,
+   * all OPTIONAL, and the optionality is load-bearing rather than timidity.
+   *
+   * Apps consume `@startsimpli/*` as PUBLISHED packages, so a client pinned to
+   * an older `@startsimpli/api` is a normal state of the world, not a mistake.
+   * Required methods here would make that combination a type error in an app
+   * that never asked for this feature. Optional, the composer renders each
+   * control only when the verb behind it exists — the same rule `BoundApi`
+   * already uses to keep the personal surface from rendering foundry-only
+   * buttons.
+   */
+
+  /**
+   * Open or close ONE connector to this foundry's members.
+   *
+   * `allowed: true` is an agreement to RECEIVE member-owned vendor data into
+   * this foundry, under each member's own credential. `allowed: false` stops NEW
+   * personal connections immediately and leaves existing ones running — ending
+   * those is `disconnectMemberConnection`, per connection, deliberately.
+   */
+  setMemberConnectorPolicy?(slug: string, connectorKey: string, allowed: boolean):
+    Promise<{ connector_key: string; member_connect_allowed: boolean; changed: boolean }>;
+
+  /** The roster: every member-owned connection in the foundry. Metadata only. */
+  memberConnections?(slug: string): Promise<{
+    results: MemberConnectionRow[];
+    permissions: ConnectionPermissions;
+  }>;
+
+  /**
+   * END one member's connection — offboarding. The same irreversible disconnect
+   * an admin has on a shared connection: the poll stops, the push stops, issued
+   * tokens are revoked and the stored credential is deleted. There is no
+   * replace-key and no credential read beside it, and that is the design: ending
+   * access is governance, taking an account over is impersonation.
+   */
+  disconnectMemberConnection?(slug: string, id: string): Promise<void>;
 }
 
 /**