@startsimpli/integrations 0.2.24 → 0.2.25

package/package.json

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

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/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>;
 }