@stackone/hub 1.4.0 → 1.5.0

package/README.md

@@ -1,10 +1,6 @@
 # StackOne HUB
 
-> 👉 **BETA SOFTWARE** 
-> This project is currently in **beta stage**. It is evolving quickly, and new versions may include breaking changes.
-
 ![License](https://img.shields.io/badge/license-MIT-blue.svg)
-![Status](https://img.shields.io/badge/status-beta-blue.svg)
 ![Node Version](https://img.shields.io/badge/node-%3E%3D22.14.0-brightgreen.svg)
 
 StackOne HUB is a React-based integration component library that provides a web component wrapper for seamless integration into any web application. It enables developers to easily embed StackOne's integrations hub.
@@ -13,18 +9,20 @@ StackOne HUB is a React-based integration component library that provides a web
 
 - [StackOne HUB](#stackone-hub)
   - [📋 Table of Contents](#-table-of-contents)
-  - [⚠️ Beta Notice](#️-beta-notice)
   - [🚀 Quick Start](#-quick-start)
   - [📦 Installation](#-installation)
     - [Prerequisites](#prerequisites)
     - [Setup](#setup)
   - [🛠️ Development](#️-development)
     - [Environment Setup](#environment-setup)
+    - [Next.js SSR Sandbox](#nextjs-ssr-sandbox)
   - [🏗️ Build](#️-build)
     - [Build Output](#build-output)
   - [📖 Usage](#-usage)
     - [🌐 Web Component Integration](#-web-component-integration)
     - [⚛️ React Component Integration](#️-react-component-integration)
+    - [▲ Next.js (App Router) Integration](#-nextjs-app-router-integration)
+    - [⚠️ "Invalid hook call" — duplicate React](#️-invalid-hook-call--duplicate-react)
     - [💻 Local Development Usage](#-local-development-usage)
       - [Web Component (Local)](#web-component-local)
       - [React Component (Local)](#react-component-local)
@@ -34,16 +32,6 @@ StackOne HUB is a React-based integration component library that provides a web
     - [Getting Started](#getting-started)
   - [📄 License](#-license)
 
-## ⚠️ Beta Notice
-
-**This software is in active development and should be considered beta quality.** 
-
-- 🚧 **Breaking changes** may occur in any release
-- 📚 **Documentation** is updated regularly
-- 🔄 **APIs are subject to change** without prior notice
-
-Please report issues and provide feedback to help us improve!
-
 ## 🚀 Quick Start
 
 ```bash
@@ -98,7 +86,25 @@ npm run dev
    npm run dev
    ```
 
-The development server will start at [http://localhost:3000](http://localhost:3000) (default port).
+The Vite dev server starts at [http://localhost:3001](http://localhost:3001).
+
+### Next.js SSR Sandbox
+
+A second sandbox lives in `dev/nextjs/` and runs the hub inside a Next.js 15 + React 19 App Router app. Use it to verify server-side rendering behaviour.
+
+From the repo root:
+
+```bash
+# First time (builds the hub and installs sandbox deps)
+npm run dev:nextjs:setup
+
+# Subsequent runs
+npm run dev:nextjs
+```
+
+The Next.js sandbox runs at [http://localhost:3002](http://localhost:3002). Set `STACKONE_API_KEY` in `dev/nextjs/.env` (see `dev/nextjs/.env.example`) to have the page fetch a connect-session token server-side, or paste one into the input on the page.
+
+After editing hub source, rerun `npm run build` from the repo root — the sandbox is linked via `file:../..` so it picks up the new `dist/` automatically.
 
 ## 🏗️ Build
 
@@ -114,9 +120,10 @@ The build generates multiple bundles in the `dist/` directory:
 
 | File | Description | Use Case |
 |------|-------------|----------|
-| `StackOneHub.esm.js` | ES module bundle | Modern React applications |
-| `StackOneHub.cjs.js` | CommonJS module | Node.js/legacy environments |
-| `StackOneHub.web.js` | Web component bundle | Vanilla HTML/JS integration |
+| `dist/index.esm.js` | ES module bundle (with `'use client'` banner) | Modern React apps, Next.js, Vite |
+| `dist/index.js` | CommonJS module (with `'use client'` banner) | Node.js / legacy environments |
+| `dist/index.d.ts` | TypeScript declarations | Type-checking |
+| `dist/webcomponent.js` | Web component bundle (IIFE, React inlined) | Vanilla HTML/JS integration |
 
 ## 📖 Usage
 
@@ -131,24 +138,24 @@ For vanilla HTML/JavaScript applications:
     <title>StackOne HUB Integration</title>
 </head>
 <body>
-    <script src="<TBD>/StackOneHub.web.js"></script>
-    <my-component></my-component>
+    <script src="<TBD>/webcomponent.js"></script>
+    <stackone-hub token="..."></stackone-hub>
 </body>
 </html>
 ```
 
 ### ⚛️ React Component Integration
 
-For React applications:
+For React applications (CSR — Vite, CRA, etc.):
 
 ```tsx
-import StackOneHub from "@stackone/StackOneHub";
+import { StackOneHub } from "@stackone/hub";
 
 function App() {
   return (
     <div className="app">
       <h1>My Application</h1>
-      <StackOneHub />
+      <StackOneHub token={token} />
     </div>
   );
 }
@@ -156,20 +163,134 @@ function App() {
 export default App;
 ```
 
+`StackOneHub` is a client-side component — it ships with a `'use client'` directive and is safe to import directly in any framework that supports server-side rendering.
+
+### ▲ Next.js (App Router) Integration
+
+`StackOneHub` is annotated with `'use client'` so you can import it directly from any Server Component. The token can be created server-side (recommended — keeps your API key off the client and avoids the CORS-protected `/connect_sessions` endpoint), and passed as a prop to a small Client Component that renders the hub.
+
+**Important:** Add `suppressHydrationWarning` to the `<html>` tag in your root layout. The hub applies its theme CSS custom properties to `document.documentElement` after hydration, which would otherwise trigger a hydration warning on the `<html>` element (the warning only suppresses the `<html>` tag itself, not its children):
+
+```tsx
+// app/layout.tsx
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+**`app/page.tsx`** (Server Component):
+
+```tsx
+import HubWrapper from "./HubWrapper";
+
+export default async function Page() {
+  const res = await fetch("https://api.stackone.com/connect_sessions", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Basic ${Buffer.from(process.env.STACKONE_API_KEY!).toString("base64")}`,
+    },
+    body: JSON.stringify({
+      origin_owner_id: "your_customer_id",
+      origin_owner_name: "Your Customer",
+      origin_username: "your_username",
+    }),
+    cache: "no-store",
+  });
+  const { token } = await res.json();
+
+  return <HubWrapper token={token} />;
+}
+```
+
+**`app/HubWrapper.tsx`** (Client Component):
+
+```tsx
+"use client";
+
+import { StackOneHub } from "@stackone/hub";
+
+export default function HubWrapper({ token }: { token: string }) {
+  return (
+    <StackOneHub
+      token={token}
+      mode="integration-picker"
+      onSuccess={(account) => console.log("connected", account)}
+    />
+  );
+}
+```
+
+If you prefer to opt the hub out of SSR entirely (Pages Router, or to skip the server pre-render):
+
+```tsx
+import dynamic from "next/dynamic";
+
+const StackOneHub = dynamic(
+  () => import("@stackone/hub").then((m) => m.StackOneHub),
+  { ssr: false },
+);
+```
+
+A working example lives in [`dev/nextjs/`](./dev/nextjs).
+
+### ⚠️ "Invalid hook call" — duplicate React
+
+`@stackone/hub` declares `react` and `react-dom` as **peer dependencies** and the bundle imports them at runtime — your app's copy must be the only copy that ends up loaded. In a standard `npm install` your bundler will hoist React and you won't see this. But the following setups can leave you with **two copies of React** and trip the "Invalid hook call" error:
+
+- **Monorepos** (npm workspaces, Yarn workspaces, Turborepo) where multiple packages each have their own `node_modules/react`.
+- **pnpm** with strict isolation — a transitive copy can shadow the root copy.
+- **`file:` / `link:` dependencies** pointing at a directory that has its own `node_modules/react` (this is what bit our local Vite sandbox).
+
+Fixes by bundler:
+
+**Vite** — add `resolve.dedupe` to your config:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+    resolve: {
+        dedupe: ['react', 'react-dom', 'react-hook-form'],
+    },
+});
+```
+
+**Webpack / Next.js** — usually handled automatically. If not, alias `react` and `react-dom` to a single absolute path:
+
+```js
+// next.config.mjs
+import path from "node:path";
+export default {
+    webpack: (config) => {
+        config.resolve.alias["react"] = path.resolve("./node_modules/react");
+        config.resolve.alias["react-dom"] = path.resolve("./node_modules/react-dom");
+        return config;
+    },
+};
+```
+
+**pnpm** — set `public-hoist-pattern[]=react*` in `.npmrc`, or `shamefully-hoist=true`.
+
+To diagnose, run `npm ls react` (or `pnpm why react`) at your app's root — if you see more than one entry resolved to a different path, that's the cause.
+
 ### 💻 Local Development Usage
 
 #### Web Component (Local)
 ```html
-<script src="dist/StackOneHub.web.js"></script>
-<my-component></my-component>
+<script src="dist/webcomponent.js"></script>
+<stackone-hub token="..."></stackone-hub>
 ```
 
 #### React Component (Local)
 ```tsx
-import StackOneHub from "dist/StackOneHub.esm";
+import { StackOneHub } from "../dist/index.esm.js";
 
 function App() {
-  return <StackOneHub />;
+  return <StackOneHub token={token} />;
 }
 ```
 
@@ -198,9 +319,8 @@ DASHBOARD_URL=https://dashboard.stackone.com
 
 ## 🤝 Contributing
 
-Since this project is in beta, we welcome contributions and feedback! However, please keep in mind:
+We welcome contributions and feedback! Please keep in mind:
 
-- 🔄 **Frequent changes**: The codebase may change rapidly
 - 📋 **No formal process yet**: Contribution guidelines are still being established
 - 💬 **Communication is key**: Please open an issue before submitting large changes