@startsimpli/integrations 0.2.20 → 0.2.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.20",
+  "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/__tests__/connections-me-client.test.ts

@@ -0,0 +1,122 @@
+/**
+ * The member connector client (bd startsim-768w.22.25.6).
+ *
+ * WHAT THIS SUITE IS FOR, and it is one thing: the URLs. Every method on
+ * `connectionsMe` must land under `/connections/me/`, and NOTHING it sends may
+ * name a foundry, a slug, or a user. The member router's guarantee — "there is
+ * no id here to substitute, no slug to swap" — is a property of the URL space,
+ * and a client is exactly where that guarantee gets quietly given back.
+ *
+ * So each assertion below reads the URL that actually reached `fetch`, not the
+ * arguments the caller passed.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { connectionsMe } from '../api/connections';
+import { setApiBase, setAuthTokenProvider } from '../api/_fetch';
+
+interface Call { url: string; method: string; body: unknown }
+
+let calls: Call[] = [];
+
+function jsonOnce(payload: unknown, status = 200) {
+  return new Response(JSON.stringify(payload), {
+    status, headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+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 jsonOnce({ results: [], permissions: {} });
+  }));
+});
+
+afterEach(() => { vi.unstubAllGlobals(); });
+
+describe('connectionsMe — every route is /connections/me/', () => {
+  it('reads the ALLOWED catalog, not the global one', async () => {
+    await connectionsMe.connectorCatalog();
+    expect(calls[0].url).toBe('/api/v1/connections/me/catalog/');
+    expect(calls[0].method).toBe('GET');
+  });
+
+  it('lists my connections with no query string at all', async () => {
+    await connectionsMe.connections();
+    // No `?owner=`, no `?foundry=`. A parameter that scopes the list is a
+    // parameter someone can change.
+    expect(calls[0].url).toBe('/api/v1/connections/me/');
+  });
+
+  it('connects by POSTing the input as the body, unwrapped', async () => {
+    await connectionsMe.connect({
+      connector_key: 'granola', name: 'Mine',
+      credentials: { api_key: 'grn_x' }, capabilities_enabled: ['poll'],
+    });
+    expect(calls[0].url).toBe('/api/v1/connections/me/');
+    expect(calls[0].method).toBe('POST');
+    expect(calls[0].body).toEqual({
+      connector_key: 'granola', name: 'Mine',
+      credentials: { api_key: 'grn_x' }, capabilities_enabled: ['poll'],
+    });
+  });
+
+  it('tests against the STORED credential, sending no key', async () => {
+    await connectionsMe.checkConnection('abc');
+    expect(calls[0].url).toBe('/api/v1/connections/me/abc/check/');
+    expect(calls[0].method).toBe('POST');
+    // Deliberately empty: a check that accepts a pasted key is a second connect
+    // path, and the router does not read this body.
+    expect(calls[0].body).toEqual({});
+  });
+
+  it('rotates through the credential route, wrapping the map the way the API expects', async () => {
+    await connectionsMe.rotateCredential('abc', { api_key: 'grn_new' });
+    expect(calls[0].url).toBe('/api/v1/connections/me/abc/credential/');
+    expect(calls[0].body).toEqual({ credentials: { api_key: 'grn_new' } });
+  });
+
+  it('disconnects with DELETE on the detail route', async () => {
+    await connectionsMe.disconnect('abc');
+    expect(calls[0].url).toBe('/api/v1/connections/me/abc/');
+    expect(calls[0].method).toBe('DELETE');
+  });
+
+  it('reads runs off the connection it belongs to', async () => {
+    await connectionsMe.connectionRuns('abc');
+    expect(calls[0].url).toBe('/api/v1/connections/me/abc/runs/');
+  });
+
+  it('carries no slug, tenant or user anywhere in any request it makes', async () => {
+    await connectionsMe.connectorCatalog();
+    await connectionsMe.connections();
+    await connectionsMe.connect({ connector_key: 'granola' });
+    await connectionsMe.checkConnection('abc');
+    await connectionsMe.rotateCredential('abc', { api_key: 'x' });
+    await connectionsMe.disconnect('abc');
+    await connectionsMe.connectionRuns('abc');
+
+    for (const call of calls) {
+      expect(call.url.startsWith('/api/v1/connections/me/')).toBe(true);
+      expect(call.url).not.toMatch(/[?&]/);
+      const serialised = JSON.stringify(call.body ?? {});
+      expect(serialised).not.toMatch(/slug|foundry|tenant|company|owner|user_id/i);
+    }
+  });
+
+  it('follows setApiBase, which is how a tenant app proxies same-origin', async () => {
+    // bd startsim-768w.22.25.7: the tenant serves `/central-api` from its own
+    // origin. If this client ignored the base, the browser would talk to central
+    // cross-origin with a bearer token attached.
+    setApiBase('/central-api/v1');
+    await connectionsMe.connections();
+    expect(calls[0].url).toBe('/central-api/v1/connections/me/');
+  });
+});

package/src/__tests__/connections.test.tsx

@@ -20,7 +20,7 @@ import userEvent from '@testing-library/user-event';
 
 import { CredentialSchemaForm, schemaFields } from '../components/CredentialSchemaForm';
 import { ConnectionsPage } from '../components/pages/ConnectionsPage';
-import type { ConnectionsApi } from '../components/pages/types';
+import type { ConnectionsApi, MemberConnectionsApi } from '../components/pages/types';
 
 // --------------------------------------------------------------------------
 //  two schemas, one component
@@ -792,3 +792,208 @@ describe('ConnectionCard — a connected account has settings', () => {
     expect(await within(section).findByText(/keeping verbatim meeting speech forever/i)).toBeInTheDocument();
   });
 });
+
+// --------------------------------------------------------------------------
+//  personal mode (bd startsim-768w.22.25.6)
+// --------------------------------------------------------------------------
+
+/**
+ * THE SAME COMPOSER, POINTED AT THE MEMBER SURFACE.
+ *
+ * A member of a foundry sets THEIR OWN key on a connector, from inside their
+ * tenant app, and the page they use is this one — `mode="personal"`. There is no
+ * second component, because a second component is a second place for the
+ * capability picker, the rotation form and the disconnect confirmation to drift.
+ *
+ * What differs is not cosmetic, and every difference below is forced by
+ * `backend/apps/connectors/member_urls.py`:
+ *
+ *   * NO SLUG anywhere in the member client's signatures. The member endpoints
+ *     are `connections/me/...` and the foundry is named by the token's audience
+ *     — "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 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
+ *     foundry has allowed members to connect. Filtering client-side would ship
+ *     the disallowed vendors in the bundle.
+ */
+const MEMBER_CATALOG = {
+  // Only Granola. The foundry allowed one connector to its members; n8n is in
+  // the foundry-wide catalog and must not appear on this surface at all.
+  results: [
+    {
+      ...CATALOG.results[1],
+      availability: { available: true, reason: '' },
+    },
+  ],
+};
+
+const MY_CONNECTIONS = {
+  results: [
+    {
+      id: 'm1', public_id: 'mpub1', name: 'My Granola', connector_key: 'granola',
+      connector_name: 'Granola', external_account_id: '', account_label: 'me@example.com',
+      capabilities_enabled: ['poll'], config: {}, 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: [] }),
+    ...overrides,
+  } as MemberConnectionsApi;
+}
+
+async function myCard(api: MemberConnectionsApi = stubMemberApi()) {
+  render(<ConnectionsPage mode="personal" api={api} />);
+  const card = await screen.findByText('My Granola');
+  return (card.closest('div[data-connection]') ?? card.parentElement!) as HTMLElement;
+}
+
+describe('ConnectionsPage — personal mode speaks to the member surface', () => {
+  it('calls the member endpoints with NO slug argument', async () => {
+    const api = stubMemberApi();
+    render(<ConnectionsPage mode="personal" api={api} />);
+    expect(await screen.findByText('My Granola')).toBeInTheDocument();
+    // Not `toHaveBeenCalledWith(undefined)` — called with nothing. A slug
+    // parameter that happens to be undefined is still a slug parameter.
+    expect((api.connectorCatalog as ReturnType<typeof vi.fn>).mock.calls[0]).toEqual([]);
+    expect((api.connections as ReturnType<typeof vi.fn>).mock.calls[0]).toEqual([]);
+  });
+
+  it('renders EXACTLY the catalog the server returned — no client-side filter', async () => {
+    // The foundry-wide catalog holds n8n. The member catalog does not. If this
+    // page ever merges the two, or filters a full list in the browser, the
+    // vendor the foundry deliberately withheld ships in the bundle anyway.
+    render(<ConnectionsPage mode="personal" api={stubMemberApi()} />);
+    expect(await screen.findByText('Granola')).toBeInTheDocument();
+    expect(screen.queryByText('n8n')).toBeNull();
+  });
+
+  it('offers the controls a member actually has: Test, Replace key, Disconnect', async () => {
+    const section = await myCard();
+    expect(within(section).getByRole('button', { name: /^Test$/i })).toBeInTheDocument();
+    expect(within(section).getByRole('button', { name: /Replace key/i })).toBeInTheDocument();
+    expect(within(section).getByRole('button', { name: /Disconnect/i })).toBeInTheDocument();
+  });
+
+  it('does NOT offer Workflows — choices, targets and actions are foundry-level', async () => {
+    const section = await myCard();
+    expect(within(section).queryByRole('button', { name: /Workflows/i })).toBeNull();
+  });
+
+  it('shows the capabilities but offers no Save, because there is no PATCH', async () => {
+    const section = await myCard();
+    // Informational, not hidden: a member chose these at connect time and is
+    // entitled to see what their account is doing.
+    expect(within(section).getByText(/Fetch new records on a schedule/i)).toBeInTheDocument();
+    expect(within(section).queryByRole('button', { name: /^Save$/i })).toBeNull();
+    expect(within(section).queryByRole('button', { name: /Settings/i })).toBeNull();
+  });
+
+  it('connects with no slug, sending credentials and capabilities', async () => {
+    const connect = vi.fn().mockResolvedValue(MY_CONNECTIONS.results[0]);
+    const api = stubMemberApi({ connect, connections: vi.fn().mockResolvedValue({
+      ...MY_CONNECTIONS, results: [],
+    }) });
+    render(<ConnectionsPage mode="personal" api={api} />);
+    await userEvent.click(await screen.findByRole('button', { name: /^Connect$/i }));
+    await userEvent.type(screen.getByLabelText(/API key/i), 'grn_mine');
+    await userEvent.click(screen.getByRole('button', { name: /Test and save/i }));
+
+    await waitFor(() => expect(connect).toHaveBeenCalled());
+    const [payload, ...rest] = connect.mock.calls[0];
+    expect(rest).toEqual([]);
+    expect(payload.connector_key).toBe('granola');
+    expect(payload.credentials).toEqual({ api_key: 'grn_mine' });
+    expect(payload.capabilities_enabled).toEqual(['poll']);
+  });
+
+  it('rotates and disconnects through the slugless member client', async () => {
+    const rotateCredential = vi.fn().mockResolvedValue(MY_CONNECTIONS.results[0]);
+    const disconnect = vi.fn().mockResolvedValue(undefined);
+    const section = await myCard(stubMemberApi({ rotateCredential, disconnect }));
+
+    await userEvent.click(within(section).getByRole('button', { name: /Replace key/i }));
+    await userEvent.type(within(section).getByLabelText(/API key/i), 'grn_rotated');
+    await userEvent.click(within(section).getByRole('button', { name: /Test and replace/i }));
+    await waitFor(() => expect(rotateCredential).toHaveBeenCalled());
+    expect(rotateCredential.mock.calls[0]).toEqual(['m1', { api_key: 'grn_rotated' }]);
+
+    await userEvent.click(within(section).getByRole('button', { name: /^Disconnect$/i }));
+    await userEvent.click(within(section).getByRole('button', { name: /Yes, disconnect/i }));
+    await waitFor(() => expect(disconnect).toHaveBeenCalled());
+    expect(disconnect.mock.calls[0]).toEqual(['m1']);
+  });
+
+  it('says the account is YOURS, never the foundry’s', async () => {
+    render(<ConnectionsPage mode="personal" api={stubMemberApi()} />);
+    expect(await screen.findByText(/Your connected accounts/i)).toBeInTheDocument();
+  });
+
+  it('reads a 403 on load as “you have no seat here”, not “ask for permission”', async () => {
+    // The ONLY 403 either load GET can produce is `IsSeatedMember` denying — the
+    // catalog answers a foundry that has allowed nothing with an empty 200, and
+    // the list runs no per-connector policy. So this copy must name the seat.
+    // Blaming the allowlist would send someone whose membership has ended to ask
+    // an admin to allow a connector, which cannot fix them.
+    const api = stubMemberApi({
+      connections: vi.fn().mockRejectedValue(Object.assign(new Error('nope'), { status: 403 })),
+    });
+    render(<ConnectionsPage mode="personal" api={api} />);
+    const alert = await screen.findByRole('alert');
+    expect(alert.textContent).toMatch(/not a member of this foundry/i);
+    expect(alert.textContent).not.toMatch(/connections permission/i);
+  });
+
+  it('renders the SERVER’s allowlist refusal when connecting is what was refused', async () => {
+    // `_NOT_ALLOWED` is raised by the POST, not the load, and it lands in the
+    // catalog card's own catch. That is the one place the allowlist wording
+    // belongs, and it comes from the server verbatim rather than being guessed
+    // at here — the server knows which connector was refused.
+    const refusal = 'your foundry has not allowed members to connect their own account on this connector.';
+    const api = stubMemberApi({
+      connect: vi.fn().mockRejectedValue(Object.assign(new Error(refusal), { status: 403 })),
+      connections: vi.fn().mockResolvedValue({ ...MY_CONNECTIONS, results: [] }),
+    });
+    render(<ConnectionsPage mode="personal" api={api} />);
+
+    await userEvent.click(await screen.findByRole('button', { name: /^Connect$/i }));
+    await userEvent.type(screen.getByLabelText(/API key/i), 'grn_live');
+    await userEvent.click(screen.getByRole('button', { name: /Test and save/i }));
+
+    await waitFor(() => expect(screen.getByText(refusal)).toBeInTheDocument());
+  });
+});
+
+describe('ConnectionsPage — foundry mode is untouched by personal mode', () => {
+  it('still defaults to foundry mode and still passes the slug', async () => {
+    const api = stubApi();
+    render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    expect(await screen.findByText('Ops n8n')).toBeInTheDocument();
+    expect(api.connectorCatalog).toHaveBeenCalledWith('acme');
+    expect(screen.getByText('Connected accounts')).toBeInTheDocument();
+  });
+
+  it('still offers Workflows and the capability Save in foundry mode', async () => {
+    render(<ConnectionsPage api={stubApi()} foundrySlug="acme" />);
+    const card = await screen.findByText('Ops n8n');
+    const section = (card.closest('div[data-connection]') ?? card.parentElement!) as HTMLElement;
+    expect(within(section).getByRole('button', { name: /Workflows/i })).toBeInTheDocument();
+    expect(within(section).getByRole('button', { name: /^Save$/i })).toBeInTheDocument();
+  });
+});

package/src/api/connections.ts

@@ -0,0 +1,129 @@
+/**
+ * `/api/v1/connections/me/` — a member's OWN vendor accounts
+ * (bd startsim-768w.22.25.6).
+ *
+ * The client half of the member connector surface. An app inside a foundry's
+ * tenant mounts `<ConnectionsPage mode="personal" api={connectionsMe} />` and
+ * owns nothing else: this object satisfies `MemberConnectionsApi`, so the same
+ * composer the command center uses renders a member's own keys.
+ *
+ * NO SLUG. Not on any method, not as an ignored parameter, not as an optional
+ * one — and that is the point rather than a convenience. The member router
+ * (`backend/apps/connectors/member_urls.py`) names the foundry through the
+ * TOKEN'S AUDIENCE, and says why in its own words: "there is no id here to
+ * substitute, no slug to swap, and therefore nothing in the URL space that names
+ * anybody else." A client whose signatures take a slug hands that affordance
+ * straight back at the type level and reads, to whoever maintains it next, as a
+ * client that scopes by slug. A member of two foundries holds two tokens; the
+ * 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.
+ *
+ * WHERE IT POINTS. Through `request()`, so `setApiBase` and
+ * `setAuthTokenProvider` apply: a tenant app points the base at its own
+ * same-origin proxy (bd startsim-768w.22.25.7) and the browser never makes a
+ * cross-origin call to central with a bearer token on it.
+ */
+import type {
+  Connection,
+  ConnectionPermissions,
+  ConnectionRun,
+  ConnectorCatalogEntry,
+  MemberConnectionsApi,
+} from '../components/pages/types';
+import { request } from './_fetch';
+
+/** Mounted at `/api/v1/connections/` (`config/urls.py`), so this rides the base. */
+const BASE = '/connections/me';
+
+export const connectionsMe: MemberConnectionsApi = {
+  /**
+   * The connectors THIS foundry has opened to its members — not the global
+   * catalog. The narrowing is `policy_service.member_connectable`, server-side,
+   * default-deny per connector per foundry. Rendered as handed: filtering in the
+   * browser would mean shipping the withheld vendors to be filtered out of.
+   */
+  connectorCatalog(): Promise<{ results: ConnectorCatalogEntry[] }> {
+    return request<{ results: ConnectorCatalogEntry[] }>(`${BASE}/catalog/`);
+  },
+
+  /**
+   * MY cards. Already owner-scoped by `Connection.objects.for_owner(foundry,
+   * user)` — there is no query parameter that widens this and no id to swap.
+   *
+   * `permissions` comes back with `issue_tokens: false` because the router has
+   * no such route, not because of anything about the caller.
+   */
+  connections(): Promise<{ results: Connection[]; permissions: ConnectionPermissions }> {
+    return request<{ results: Connection[]; permissions: ConnectionPermissions }>(`${BASE}/`);
+  },
+
+  /**
+   * Connect my own account. BLOCKING: the server runs `check()` against the
+   * vendor before storing anything, so a key that has not been proven to work is
+   * never saved as connected.
+   *
+   * `capabilities_enabled` is chosen HERE and only here — there is no PATCH on
+   * this surface, so this request is the one place a member says what their
+   * account may do.
+   *
+   * A 403 back from this is not "you lack a permission": it is the foundry not
+   * having allowed members to connect their own account on this connector. The
+   * server re-checks that here rather than trusting that the catalog it rendered
+   * earlier is what the browser actually sent.
+   */
+  connect(input: {
+    connector_key: string;
+    name?: string;
+    credentials?: Record<string, unknown>;
+    config?: Record<string, unknown>;
+    capabilities_enabled?: string[];
+  }): Promise<Connection> {
+    return request<Connection>(`${BASE}/`, { method: 'POST', body: input });
+  },
+
+  /**
+   * 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
+   * path, and the router does not read this body at all.
+   */
+  checkConnection(id: string): Promise<{ ok: boolean; account_label: string; detail: string }> {
+    return request<{ ok: boolean; account_label: string; detail: string }>(
+      `${BASE}/${id}/check/`, { method: 'POST', body: {} },
+    );
+  },
+
+  /**
+   * Rotate MY key. The old one stays live until the new one passes `check()`,
+   * so a bad paste changes nothing. A PARTIAL map is legal and normal: send the
+   * one field being replaced and the stored values fill in the rest.
+   */
+  rotateCredential(id: string, credentials: Record<string, unknown>): Promise<Connection> {
+    return request<Connection>(`${BASE}/${id}/credential/`, {
+      method: 'POST', body: { credentials },
+    });
+  },
+
+  /**
+   * DISCONNECT, not delete. One transaction stops the scheduled fetches, revokes
+   * every token issued for the account and deletes the stored credential; the
+   * card survives as `disabled`, so the record that this vendor was connected is
+   * not thrown away.
+   *
+   * A card that is not mine answers 404 rather than 403 — on this surface
+   * existence is itself the payload.
+   */
+  disconnect(id: string): Promise<void> {
+    return request<void>(`${BASE}/${id}/`, { method: 'DELETE' });
+  },
+
+  /** Recent activity on my card: a merge over the run tables it owns. */
+  connectionRuns(id: string): Promise<{ results: ConnectionRun[] }> {
+    return request<{ results: ConnectionRun[] }>(`${BASE}/${id}/runs/`);
+  },
+};

package/src/api/index.ts

@@ -2,4 +2,5 @@ export * from './oauth';
 export * from './calendar';
 export * from './email';
 export * from './accounts';
+export * from './connections';
 export { setApiBase, getApiBase, setAuthTokenProvider } from './_fetch';

package/src/components/index.ts

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