From 4b778cbea75042019b580fa689ed0e10e274a04a Mon Sep 17 00:00:00 2001 From: Faisal Reza Date: Mon, 28 Sep 2026 12:40:51 +0100 Subject: [PATCH 1/4] fix(SOL-418): stackone-connect - update stale docs links and hub guidance - point to embed/account-linking, connect-session, auth-link, handle-account-events - add llms.txt + hub README fallback, web component - drop hub-reference.md (duplicated docs) - skill version 2.1 Co-Authored-By: Claude Opus 5.5 --- .../skills/stackone-connect/SKILL.md | 95 ++++++++++--------- .../references/hub-reference.md | 57 ----------- 2 files changed, 51 insertions(+), 101 deletions(-) delete mode 100644 plugins/integrations/stackone-connect/skills/stackone-connect/references/hub-reference.md diff --git a/plugins/integrations/stackone-connect/skills/stackone-connect/SKILL.md b/plugins/integrations/stackone-connect/skills/stackone-connect/SKILL.md index abce478..6d43dfa 100644 --- a/plugins/integrations/stackone-connect/skills/stackone-connect/SKILL.md +++ b/plugins/integrations/stackone-connect/skills/stackone-connect/SKILL.md @@ -1,11 +1,11 @@ --- name: stackone-connect -description: Implement account linking using StackOne Connect Sessions and the Hub React component. Use when user asks to "connect a provider", "embed the integration picker", "add BambooHR to my app", "create a connect session", "set up auth links", or "handle account webhooks". Covers the full flow from session creation to webhook handling. Do NOT use for making API calls after linking (use stackone-platform) or building AI agents (use stackone-agents). +description: Implement account linking using StackOne Connect Sessions and the StackOne Hub. Use when user asks to "connect a provider", "embed the integration picker", "add BambooHR to my app", "create a connect session", "set up auth links", or "handle account webhooks". Covers the full flow from session creation to webhook handling. Do NOT use for making API calls after linking (use stackone-platform) or building AI agents (use stackone-agents). license: MIT compatibility: Requires network access to fetch live documentation from docs.stackone.com metadata: author: stackone - version: "2.0" + version: "2.1" --- # StackOne Connect — Account Linking @@ -13,10 +13,16 @@ metadata: ## Important Before writing code, fetch the latest documentation: -1. Fetch `https://docs.stackone.com/guides/connect-tools-overview` for the current connection flow -2. Fetch `https://www.npmjs.com/package/@stackone/hub` for the latest Hub component API +1. Fetch `https://docs.stackone.com/embed/account-linking/overview.md` for the current linking flow and the ways to embed the Hub +2. Fetch `https://docs.stackone.com/embed/account-linking/stackone-hub.md` for the current `` props and theming -The Hub component is in active beta — props and peer dependencies change between versions. +The Hub component changes between versions. Take props, peer dependencies and link expiry from the docs, not from this skill. + +When fetching any `docs.stackone.com` page, append `.md` to the URL to get it as markdown. + +**If any URL in this skill returns 404, or a page doesn't cover what you need** (StackOne reorganizes its docs from time to time): +- Fetch `https://docs.stackone.com/llms.txt`, which indexes every docs page by title and description. Search the "Embed" section for the page's topic (e.g. "Connect Session", "Account Linking", "Auth Link", "Handle Account Events") and use the URL listed there. +- For the Hub package itself, the repository README is the fallback: `https://raw.githubusercontent.com/StackOneHQ/hub/main/README.md`. ## Instructions @@ -24,15 +30,17 @@ The Hub component is in active beta — props and peer dependencies change betwe | Method | When to use | |--------|-------------| -| **Embedded Hub** | In-app integration picker — users stay in your app | -| **Auth Link** | Email onboarding or external flows — standalone URL, valid 5 days | -| **Dashboard** | Internal testing only — never for production | +| **Embedded Hub** | In-app integration picker, users stay in your app. React apps use `@stackone/hub`; other frameworks use the `` web component | +| **Auth Link** | Email onboarding, sales-led onboarding or demos. A StackOne-hosted page with the Hub already embedded, no frontend work | +| **Dashboard** | Internal tools, or linking an account on a customer's behalf | If unsure, recommend the Embedded Hub. It provides the best user experience. +The overview page compares the methods and links to each one's guide. + ### Step 2: Create a Connect Session (backend) -Your backend creates a session token that the frontend uses to initialize the Hub: +Your backend creates a session token that the frontend uses to initialize the Hub. Fetch `https://docs.stackone.com/embed/connect-session.md` for the required fields, filtering and connector profile targeting. ```bash curl -X POST https://api.stackone.com/connect_sessions \ @@ -46,26 +54,23 @@ curl -X POST https://api.stackone.com/connect_sessions \ The response includes a `token` field. Pass this to the frontend. -To filter which providers appear in the Hub: -```json -{ - "origin_owner_id": "customer-123", - "origin_owner_name": "Acme Inc", - "provider": "bamboohr", - "categories": ["hris"] -} -``` +Always set `origin_owner_id` on the server. Never take it from a client request, or one customer could claim another customer's linked accounts. + +To control which providers appear in the Hub, pass `provider` (opens that connector directly) or `categories` (e.g. `["hris"]`). The Connect Session page also covers `account_id`, `multiple` and `connector_profile_id`. -Fetch `https://docs.stackone.com/platform/api-reference/connect-sessions/create-connect-session` for the full request/response schema. +Fetch `https://docs.stackone.com/platform/api-reference/connect-sessions/create-connect-session.md` for the full request/response schema. ### Step 3: Initialize the Hub (frontend) +For React, fetch `https://docs.stackone.com/embed/account-linking/stackone-hub.md` and follow its quick start: + ```bash npm install @stackone/hub ``` ```tsx import { StackOneHub } from "@stackone/hub"; +import { useEffect, useState } from "react"; function ConnectorPage() { const [token, setToken] = useState(); @@ -90,7 +95,11 @@ function ConnectorPage() { } ``` -For the full props API and theming options, consult `references/hub-reference.md`. +For the full props list and theming options, use the Properties and Theming sections of that page. + +For other frameworks, fetch `https://docs.stackone.com/embed/account-linking/stackone-hub-web-component.md`. + +For an Auth Link instead of an embedded Hub, fetch `https://docs.stackone.com/embed/account-linking/auth-link.md`. It covers generating the link from the dashboard or from the Connect Session response, and setting its expiry. ### Step 4: Set up webhook listeners @@ -99,21 +108,16 @@ Webhooks are required for Auth Links (no frontend callbacks) and recommended for | Event | When it fires | |-------|---------------| | `account.created` | New account linked | -| `account.updated` | Credentials refreshed | +| `account.updated` | Account changed, e.g. credentials refreshed | | `account.deleted` | Account disconnected | -Fetch `https://docs.stackone.com/guides/webhooks` for the webhook payload format and setup instructions. +Fetch `https://docs.stackone.com/embed/handle-account-events.md` for subscribing to these events, verifying the signature and handling the payload. For webhook management in general (retries, secret rotation), fetch `https://docs.stackone.com/connect/webhooks.md`. ### Step 5: Verify the connection -After receiving `onSuccess` or the `account.created` webhook, make a test API call: - -```bash -curl https://api.stackone.com/accounts/{account_id} \ - -H "Authorization: Basic $(echo -n 'YOUR_API_KEY:' | base64)" -``` +After receiving `onSuccess` or the `account.created` webhook, fetch the account and check its `status`. Fetch `https://docs.stackone.com/platform/api-reference/v2/accounts/get-an-account.md` for the endpoint and the status values. -A `200` response with `status: "active"` confirms the connection is working. +An `active` status confirms the connection is working. ## Examples @@ -122,32 +126,34 @@ A `200` response with `status: "active"` confirms the connection is working. User says: "I want to let my customers connect their BambooHR account" Actions: -1. Create a backend endpoint that calls `POST /connect_sessions` with `provider: "bamboohr"` -2. Return the session token to the frontend -3. Install `@stackone/hub` and render `` -4. Handle `onSuccess` to store the account ID -5. Set up a webhook endpoint for `account.created` as a backup +1. Fetch the Connect Session and StackOne Hub (React) pages +2. Create a backend endpoint that calls `POST /connect_sessions` with `provider: "bamboohr"` +3. Return the session token to the frontend +4. Install `@stackone/hub` and render `` +5. Handle `onSuccess` to store the account ID +6. Set up a webhook endpoint for `account.created` as a backup -Result: Working integration picker that filters to BambooHR only. +Result: Working integration picker that opens straight to BambooHR. ### Example 2: User wants to send connection links via email User says: "I need to onboard customers by email, not in-app" Actions: -1. Create a Connect Session with `origin_owner_id` set to the customer -2. Generate an auth link from the session (fetch auth link docs) -3. Set up webhook listeners — auth links have no frontend callbacks -4. Send the link via email (valid for 5 days) +1. Fetch the Auth Link page +2. Create a Connect Session with `origin_owner_id` set to the customer, and the expiry the page describes +3. Read the auth link URL from the response, as the page describes +4. Set up webhook listeners — auth links have no frontend callbacks +5. Send the link via email Result: Customer clicks link, authenticates, webhook fires with account details. ## Troubleshooting ### Hub component doesn't render -**Cause**: Missing peer dependencies. -- `@stackone/hub` requires: `react`, `react-dom`, `react-hook-form`, `@hookform/resolvers`, `zod` -- Check that versions match — fetch the NPM page for exact version constraints +**Cause**: Missing or mismatched peer dependencies. +- Check the peer dependencies of the installed `@stackone/hub` version with `npm view @stackone/hub peerDependencies` +- For "Invalid hook call" errors, check for a duplicate React copy. The Hub README has a section on it - Verify the session token is valid and not expired ### Connect Session token expired @@ -157,12 +163,13 @@ Result: Customer clicks link, authenticates, webhook fires with account details. ### onSuccess fires but account status is "error" **Cause**: Provider-side authentication succeeded but StackOne couldn't sync data. -- Check the account details in the dashboard for the specific error +- Check the account's `status_reasons`, or the account details in the dashboard, for the specific error - Common cause: insufficient permissions on the provider side - The provider may require additional OAuth scopes ### Webhooks not arriving **Cause**: Webhook endpoint configuration issue. - Verify the endpoint URL is publicly accessible (not localhost) +- Check the account events are selected on the webhook itself, not on a connector profile - Check the webhook signing secret matches -- Fetch `https://docs.stackone.com/guides/webhooks` for the verification process +- Fetch `https://docs.stackone.com/embed/handle-account-events.md` for the verification process diff --git a/plugins/integrations/stackone-connect/skills/stackone-connect/references/hub-reference.md b/plugins/integrations/stackone-connect/skills/stackone-connect/references/hub-reference.md deleted file mode 100644 index 9eff844..0000000 --- a/plugins/integrations/stackone-connect/skills/stackone-connect/references/hub-reference.md +++ /dev/null @@ -1,57 +0,0 @@ -# StackOne Hub Component Reference - -**IMPORTANT**: This reference may be outdated. Always fetch the latest from: -- NPM: `https://www.npmjs.com/package/@stackone/hub` -- Docs: `https://docs.stackone.com/guides/embedding-stackone-hub` - -## New Hub (beta) — `@stackone/hub` - -### Props - -| Prop | Type | Default | Description | -|------|------|---------|-------------| -| `token` | string | required | Connect session token from your backend | -| `mode` | `'integration-picker' \| 'csv-importer'` | `'integration-picker'` | Hub operation mode | -| `accountId` | string | — | Pre-select an account for editing/re-auth | -| `baseUrl` | string | `'https://api.stackone.com'` | API endpoint override | -| `height` | string | `'500px'` | Component height | -| `theme` | `'light' \| 'dark' \| PartialMalachiteTheme` | `'light'` | Visual styling | -| `onSuccess` | `(account) => void` | — | Fires when account is linked | -| `onCancel` | `() => void` | — | Fires when user cancels | -| `onClose` | `() => void` | — | Fires when Hub is closed | - -### Peer Dependencies - -```json -{ - "react": "18.3.1", - "react-dom": "18.3.1", - "react-hook-form": "7.60.0", - "@hookform/resolvers": "^5.2.2", - "zod": "^4.1.12" -} -``` - -### Custom Theming - -```tsx - -``` - -## Legacy Hub (v1) — `@stackone/react-hub` - -The older iframe-based approach. Use only if maintaining existing v1 implementations. - -```bash -npm install @stackone/react-hub -``` - -Fetch `https://docs.stackone.com/guides/embedding-stackone-hub` for v1 usage patterns. From 5fdd5efe905420d19542e36b58733b80d15b9d38 Mon Sep 17 00:00:00 2001 From: Faisal Reza Date: Mon, 28 Sep 2026 15:46:07 +0100 Subject: [PATCH 2/4] fix(SOL-418): scope .md rule to urls not ending in .md Co-Authored-By: Claude Opus 5.5 --- .../stackone-connect/skills/stackone-connect/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/integrations/stackone-connect/skills/stackone-connect/SKILL.md b/plugins/integrations/stackone-connect/skills/stackone-connect/SKILL.md index 6d43dfa..06a7dd4 100644 --- a/plugins/integrations/stackone-connect/skills/stackone-connect/SKILL.md +++ b/plugins/integrations/stackone-connect/skills/stackone-connect/SKILL.md @@ -18,7 +18,7 @@ Before writing code, fetch the latest documentation: The Hub component changes between versions. Take props, peer dependencies and link expiry from the docs, not from this skill. -When fetching any `docs.stackone.com` page, append `.md` to the URL to get it as markdown. +When fetching a `docs.stackone.com` page whose URL doesn't already end in `.md`, append `.md` to get it as markdown. `llms.txt` is already plain text, so fetch it as is. **If any URL in this skill returns 404, or a page doesn't cover what you need** (StackOne reorganizes its docs from time to time): - Fetch `https://docs.stackone.com/llms.txt`, which indexes every docs page by title and description. Search the "Embed" section for the page's topic (e.g. "Connect Session", "Account Linking", "Auth Link", "Handle Account Events") and use the URL listed there. From ca2b4f1a16d92726e313655aa6493c7020b0abb7 Mon Sep 17 00:00:00 2001 From: Faisal Reza Date: Mon, 28 Sep 2026 15:53:53 +0100 Subject: [PATCH 3/4] fix(SOL-418): contact support when docs do not cover it Co-Authored-By: Claude Opus 5.5 --- .../stackone-connect/skills/stackone-connect/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/plugins/integrations/stackone-connect/skills/stackone-connect/SKILL.md b/plugins/integrations/stackone-connect/skills/stackone-connect/SKILL.md index 06a7dd4..c603803 100644 --- a/plugins/integrations/stackone-connect/skills/stackone-connect/SKILL.md +++ b/plugins/integrations/stackone-connect/skills/stackone-connect/SKILL.md @@ -23,6 +23,7 @@ When fetching a `docs.stackone.com` page whose URL doesn't already end in `.md`, **If any URL in this skill returns 404, or a page doesn't cover what you need** (StackOne reorganizes its docs from time to time): - Fetch `https://docs.stackone.com/llms.txt`, which indexes every docs page by title and description. Search the "Embed" section for the page's topic (e.g. "Connect Session", "Account Linking", "Auth Link", "Handle Account Events") and use the URL listed there. - For the Hub package itself, the repository README is the fallback: `https://raw.githubusercontent.com/StackOneHQ/hub/main/README.md`. +- If the docs don't cover the question, say so and suggest contacting StackOne support. Don't invent an answer. ## Instructions From f959a0cb00da233eb2c444305950dadc97bb0fc8 Mon Sep 17 00:00:00 2001 From: Faisal Reza Date: Tue, 29 Sep 2026 17:04:02 +0100 Subject: [PATCH 4/4] fix(SOL-418): point to account events docs instead of copying the table - platform events reference covers each event and payload Co-Authored-By: Claude Opus 5.5 --- .../stackone-connect/skills/stackone-connect/SKILL.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/plugins/integrations/stackone-connect/skills/stackone-connect/SKILL.md b/plugins/integrations/stackone-connect/skills/stackone-connect/SKILL.md index c603803..457ed7d 100644 --- a/plugins/integrations/stackone-connect/skills/stackone-connect/SKILL.md +++ b/plugins/integrations/stackone-connect/skills/stackone-connect/SKILL.md @@ -104,15 +104,9 @@ For an Auth Link instead of an embedded Hub, fetch `https://docs.stackone.com/em ### Step 4: Set up webhook listeners -Webhooks are required for Auth Links (no frontend callbacks) and recommended for the Embedded Hub: +Webhooks are required for Auth Links (no frontend callbacks) and recommended for the Embedded Hub. -| Event | When it fires | -|-------|---------------| -| `account.created` | New account linked | -| `account.updated` | Account changed, e.g. credentials refreshed | -| `account.deleted` | Account disconnected | - -Fetch `https://docs.stackone.com/embed/handle-account-events.md` for subscribing to these events, verifying the signature and handling the payload. For webhook management in general (retries, secret rotation), fetch `https://docs.stackone.com/connect/webhooks.md`. +Fetch `https://docs.stackone.com/embed/handle-account-events.md` for subscribing to the account events, verifying the signature and handling the payload, and `https://docs.stackone.com/platform-api/platform-events.md` for each event and its payload. For webhook management in general (retries, secret rotation), fetch `https://docs.stackone.com/connect/webhooks.md`. ### Step 5: Verify the connection