@axcode/axcloud-sdk 0.1.7-dev.580a922 → 0.1.7-dev.bf490b9

package/README.md

@@ -12,10 +12,10 @@ npm install @axcode/axcloud-sdk
 
 The SDK is published with two tags for different environments:
 
-| Tag | Purpose | Stability | Install |
-|-----|---------|-----------|---------|
-| `latest` | Production | Stable, tested | `npm install @axcode/axcloud-sdk` |
-| `next` | Development/Staging | Preview, may have breaking changes | `npm install @axcode/axcloud-sdk@next` |
+| Tag      | Purpose             | Stability                          | Install                                |
+| -------- | ------------------- | ---------------------------------- | -------------------------------------- |
+| `latest` | Production          | Stable, tested                     | `npm install @axcode/axcloud-sdk`      |
+| `next`   | Development/Staging | Preview, may have breaking changes | `npm install @axcode/axcloud-sdk@next` |
 
 **Recommended setup:**
 
@@ -42,46 +42,51 @@ This allows you to test new SDK features in your staging environment before they
 ### 1. Wrap your app with AxCloudProvider
 
 ```tsx
-import { AxCloudProvider } from '@axcode/axcloud-sdk'
+import { AxCloudProvider } from '@axcode/axcloud-sdk';
 
 function App() {
   return (
     <AxCloudProvider
-      orgId="org_ba81807b"  // Your organization ID
+      orgId="org_ba81807b" // Your organization ID
       apiUrl="https://api.axcloud.app"
-      apiKey="pk_live_..."  // Public API key from Settings → API Keys
+      apiKey="pk_live_..." // Public API key from Settings → API Keys
       auth0={{
-        domain: "auth.axcloud.app",
-        clientId: "your-client-id",
-        redirectUri: window.location.origin
+        domain: 'auth.axcloud.app',
+        clientId: 'your-client-id',
+        redirectUri: window.location.origin,
+        organization: 'org_auth0_...', // Optional Auth0 Organization ID for invite-only member sites
       }}
     >
       <Router>
         <Routes />
       </Router>
     </AxCloudProvider>
-  )
+  );
 }
 ```
 
+`orgId` is the AxCloud organization ID used by CMS APIs, for example `org_ba81807b`.
+`auth0.organization` is the Auth0 Organization ID used during login, for example `org_o960yILn77d4vY6u`.
+Set `auth0.organization` for invite-only customer member sites so Universal Login is scoped to that customer organization.
+
 ### 2. Fetch content
 
 ```tsx
-import { useNews } from '@axcode/axcloud-sdk'
+import { useNews } from '@axcode/axcloud-sdk';
 
 function NewsPage() {
-  const { data: news, isLoading, isError } = useNews()
+  const { data: news, isLoading, isError } = useNews();
 
-  if (isLoading) return <Spinner />
-  if (isError) return <Error />
+  if (isLoading) return <Spinner />;
+  if (isError) return <Error />;
 
   return (
     <ul>
-      {news.map(item => (
+      {news.map((item) => (
         <li key={item.id}>{item.title}</li>
       ))}
     </ul>
-  )
+  );
 }
 ```
 
@@ -90,31 +95,31 @@ function NewsPage() {
 Pages and news can be stored once in AxCloud with translations and requested per language:
 
 ```tsx
-import { useContentItem, useNews } from '@axcode/axcloud-sdk'
+import { useContentItem, useNews } from '@axcode/axcloud-sdk';
 
 function AboutPage({ locale }: { locale: 'sv' | 'en' }) {
   const { data: page } = useContentItem('pages', 'about-us', {
     lang: locale,
     publicOnly: true,
-  })
+  });
 
-  return <h1>{page?.title}</h1>
+  return <h1>{page?.title}</h1>;
 }
 
 function NewsList({ locale }: { locale: 'sv' | 'en' }) {
-  const { data: news } = useNews({ lang: locale })
+  const { data: news } = useNews({ lang: locale });
 
-  return news.map(item => <article key={item.id}>{item.title}</article>)
+  return news.map((item) => <article key={item.id}>{item.title}</article>);
 }
 ```
 
 ### 3. Add authentication
 
 ```tsx
-import { useAuth, LoginButton, LogoutButton, ProtectedRoute } from '@axcode/axcloud-sdk'
+import { useAuth, LoginButton, LogoutButton, ProtectedRoute } from '@axcode/axcloud-sdk';
 
 function Header() {
-  const { isAuthenticated, user } = useAuth()
+  const { isAuthenticated, user } = useAuth();
 
   return (
     <header>
@@ -127,7 +132,7 @@ function Header() {
         <LoginButton>Sign In</LoginButton>
       )}
     </header>
-  )
+  );
 }
 
 function MemberArea() {
@@ -135,87 +140,158 @@ function MemberArea() {
     <ProtectedRoute>
       <MemberContent />
     </ProtectedRoute>
-  )
+  );
 }
 ```
 
+The SDK keeps verification UI inside the product site. Render your own branded
+notice when `needsEmailVerification` is true:
+
+```tsx
+const { needsEmailVerification, requestEmailVerification, refreshUser } = useAuth();
+
+if (needsEmailVerification) {
+  // Render the product's own verification notice.
+}
+
+await requestEmailVerification({ returnTo: window.location.href });
+await refreshUser();
+```
+
+The API resolves the recipient and organization from the authenticated token.
+Return URLs are restricted to the organization's configured member site.
+
+### 3b. Add privacy-safe analytics
+
+Analytics is optional and provider-independent. AxCloud resolves the public
+tracker configuration from the organization, site key, deployment stage, and
+current hostname. SDK consumers never receive the Umami API key.
+
+```tsx
+import { AxCloudProvider, useAnalytics } from '@axcode/axcloud-sdk';
+
+<AxCloudProvider
+  orgId="org_ba81807b"
+  apiUrl="https://api.axcloud.app"
+  stage="prod"
+  analytics={{
+    enabled: analyticsConsent === 'accepted',
+    siteKey: 'member-site',
+    normalizePath: (path) => path.replace(/^\/member\/news\/[^/]+/, '/member/news/:id'),
+  }}
+  auth0={auth0Config}
+>
+  <App />
+</AxCloudProvider>;
+```
+
+The SDK tracks SPA page changes after the tracker is ready. Query strings and
+fragments are removed, common opaque IDs are replaced with `:id`, Do Not Track
+is honored, and localhost collection is disabled unless `trackLocalhost: true`
+is explicitly set.
+
+Custom events must be allowlisted in the AxCloud analytics site configuration:
+
+```tsx
+function NewsArticle() {
+  const analytics = useAnalytics();
+
+  const handleOpen = () => {
+    analytics.track('news_opened', { surface: 'member_news' });
+  };
+}
+```
+
+Only send coarse enums, booleans, and counts. The SDK rejects sensitive
+property names and email-like values, but applications remain responsible for
+never supplying names, email addresses, user IDs, document titles, search text,
+chat text, or other personal/content data. Production trackers should only be
+enabled after the product's privacy notice and Content Security Policy have
+been reviewed.
+
 ### 4. Use sections
 
 ```tsx
-import { useMySection } from '@axcode/axcloud-sdk'
+import { useMySection } from '@axcode/axcloud-sdk';
 
 function MySectionPage() {
-  const { section, members, isLoading } = useMySection()
+  const { section, members, isLoading } = useMySection();
 
-  if (isLoading) return <Spinner />
-  if (!section) return <p>You are not assigned to a section</p>
+  if (isLoading) return <Spinner />;
+  if (!section) return <p>You are not assigned to a section</p>;
 
   return (
     <div>
       <h1>{section.name}</h1>
       <h2>Members ({members.length})</h2>
       <ul>
-        {members.map(m => <li key={m.id}>{m.name}</li>)}
+        {members.map((m) => (
+          <li key={m.id}>{m.name}</li>
+        ))}
       </ul>
     </div>
-  )
+  );
 }
 ```
 
 ### 4b. Filter content by section
 
 ```tsx
-import { useNews, useMySection } from '@axcode/axcloud-sdk'
+import { useNews, useMySection } from '@axcode/axcloud-sdk';
 
 function SectionNews() {
-  const { sectionId } = useMySection()
+  const { sectionId } = useMySection();
 
   // Fetch news for user's section only
-  const { data: sectionNews } = useNews({ sectionId })
+  const { data: sectionNews } = useNews({ sectionId });
 
   // Or fetch all organization news
-  const { data: allNews } = useNews()
+  const { data: allNews } = useNews();
 
   return (
     <div>
       <h2>Section News</h2>
-      {sectionNews.map(item => <NewsCard key={item.id} item={item} />)}
+      {sectionNews.map((item) => (
+        <NewsCard key={item.id} item={item} />
+      ))}
 
       <h2>All Organization News</h2>
-      {allNews.map(item => <NewsCard key={item.id} item={item} />)}
+      {allNews.map((item) => (
+        <NewsCard key={item.id} item={item} />
+      ))}
     </div>
-  )
+  );
 }
 ```
 
 ### 5. Fetch organization branding and media
 
 ```tsx
-import { useBranding, useLogo, useMedia } from '@axcode/axcloud-sdk'
+import { useBranding, useLogo, useMedia } from '@axcode/axcloud-sdk';
 
 function Header() {
-  const { logoUrl, branding, organizationName } = useBranding()
+  const { logoUrl, branding, organizationName } = useBranding();
 
   return (
     <header style={{ backgroundColor: branding?.primaryColor }}>
       {logoUrl && <img src={logoUrl} alt={organizationName} />}
       <h1>{organizationName}</h1>
     </header>
-  )
+  );
 }
 
 // Or just the logo
 function Logo() {
-  const { logoUrl, isLoading } = useLogo()
+  const { logoUrl, isLoading } = useLogo();
 
-  if (isLoading) return <Skeleton />
-  return logoUrl ? <img src={logoUrl} alt="Logo" /> : <DefaultLogo />
+  if (isLoading) return <Skeleton />;
+  return logoUrl ? <img src={logoUrl} alt="Logo" /> : <DefaultLogo />;
 }
 
 // Fetch specific media file
 function HeroImage() {
-  const { mediaUrl } = useMedia('hero-banner.jpg')
-  return mediaUrl ? <img src={mediaUrl} alt="Hero" /> : null
+  const { mediaUrl } = useMedia('hero-banner.jpg');
+  return mediaUrl ? <img src={mediaUrl} alt="Hero" /> : null;
 }
 ```
 
@@ -224,26 +300,26 @@ function HeroImage() {
 ### 6. Fetch public documents
 
 ```tsx
-import { useDocuments, useDocumentDownload } from '@axcode/axcloud-sdk'
+import { useDocuments, useDocumentDownload } from '@axcode/axcloud-sdk';
 
 function PublicDocuments() {
-  const { documents, isLoading } = useDocuments({ tags: ['handbook'], limit: 20 })
+  const { documents, isLoading } = useDocuments({ tags: ['handbook'], limit: 20 });
 
-  if (isLoading) return <Skeleton />
+  if (isLoading) return <Skeleton />;
   return (
     <ul>
-      {documents.map(doc => (
+      {documents.map((doc) => (
         <li key={doc.document_id}>
           <DocumentLink documentId={doc.document_id} title={doc.title} />
         </li>
       ))}
     </ul>
-  )
+  );
 }
 
 function DocumentLink({ documentId, title }: { documentId: string; title: string }) {
-  const { documentUrl } = useDocumentDownload(documentId)
-  return documentUrl ? <a href={documentUrl}>{title}</a> : <span>{title}</span>
+  const { documentUrl } = useDocumentDownload(documentId);
+  return documentUrl ? <a href={documentUrl}>{title}</a> : <span>{title}</span>;
 }
 ```
 
@@ -252,10 +328,10 @@ Only documents with `status: "published"` and `audience: "public"` are exposed t
 ### 7. Gate features by module
 
 ```tsx
-import { ModuleGate, useOrg } from '@axcode/axcloud-sdk'
+import { ModuleGate, useOrg } from '@axcode/axcloud-sdk';
 
 function Dashboard() {
-  const { hasModule } = useOrg()
+  const { hasModule } = useOrg();
 
   return (
     <div>
@@ -267,7 +343,7 @@ function Dashboard() {
 
       {hasModule('ai') && <AIChatWidget />}
     </div>
-  )
+  );
 }
 ```
 
@@ -275,85 +351,85 @@ function Dashboard() {
 
 ### Provider
 
-| Component | Description |
-|-----------|-------------|
+| Component         | Description                                                     |
+| ----------------- | --------------------------------------------------------------- |
 | `AxCloudProvider` | Main provider that combines Auth0, React Query, and SDK context |
 
 ### Hooks
 
-| Hook | Description |
-|------|-------------|
-| `useAuth()` | Login/logout with Auth0 Universal Login |
-| `useUser()` | Fetch current user with role and permissions |
-| `useOrg()` | Fetch organization info and check modules |
-| `useNews(options?)` | Fetch news articles. Returns public + internal + members content when authenticated. |
-| `useContent(type, options?)` | Fetch any content type. For `pages` and `events`, returns member content when authenticated. |
-| `useMySection()` | Fetch current user's section with members |
-| `useSections()` | Fetch all organization sections |
-| `useBranding()` | Fetch organization branding (logo, colors) |
-| `useLogo()` | Fetch organization logo URL |
-| `useMedia(mediaId)` | Fetch specific media file URL |
-| `useAvatar(userId)` | Fetch user avatar URL |
-| `useMediaList(type)` | List media files |
-| `useDocuments(options?)` | List published public documents |
-| `useDocumentDownload(documentId)` | Fetch a signed document download URL |
+| Hook                              | Description                                                                                  |
+| --------------------------------- | -------------------------------------------------------------------------------------------- |
+| `useAuth()`                       | Login/logout, email-verification state, resend, and profile refresh                          |
+| `useUser()`                       | Fetch current user with role and permissions                                                 |
+| `useOrg()`                        | Fetch organization info and check modules                                                    |
+| `useNews(options?)`               | Fetch news articles. Returns public + internal + members content when authenticated.         |
+| `useContent(type, options?)`      | Fetch any content type. For `pages` and `events`, returns member content when authenticated. |
+| `useMySection()`                  | Fetch current user's section with members                                                    |
+| `useSections()`                   | Fetch all organization sections                                                              |
+| `useBranding()`                   | Fetch organization branding (logo, colors)                                                   |
+| `useLogo()`                       | Fetch organization logo URL                                                                  |
+| `useMedia(mediaId)`               | Fetch specific media file URL                                                                |
+| `useAvatar(userId)`               | Fetch user avatar URL                                                                        |
+| `useMediaList(type)`              | List media files                                                                             |
+| `useDocuments(options?)`          | List published public documents                                                              |
+| `useDocumentDownload(documentId)` | Fetch a signed document download URL                                                         |
 
 ### Content Query Options
 
 ```typescript
 interface ContentQueryOptions {
-  page?: number           // Page number (default: 1)
-  pageSize?: number       // Items per page (default: 20)
-  status?: 'draft' | 'published' | 'archived'
-  visibility?: 'draft' | 'published' | 'archived'
-  audience?: 'public' | 'internal' | 'members' | 'section'
-  sectionId?: string      // Filter by specific section
-  search?: string         // Search in title/content
-  sortBy?: string         // Sort field (default: 'createdAt')
-  sortOrder?: 'asc' | 'desc'
-  lang?: string           // Return translated title/slug/blocks when available
-  publicOnly?: boolean    // Force public endpoint even when authenticated
+  page?: number; // Page number (default: 1)
+  pageSize?: number; // Items per page (default: 20)
+  status?: 'draft' | 'published' | 'archived';
+  visibility?: 'draft' | 'published' | 'archived';
+  audience?: 'public' | 'internal' | 'members' | 'section';
+  sectionId?: string; // Filter by specific section
+  search?: string; // Search in title/content
+  sortBy?: string; // Sort field (default: 'createdAt')
+  sortOrder?: 'asc' | 'desc';
+  lang?: string; // Return translated title/slug/blocks when available
+  publicOnly?: boolean; // Force public endpoint even when authenticated
 }
 ```
 
 ### Components
 
-| Component | Description |
-|-----------|-------------|
-| `<LoginButton>` | Trigger Auth0 login |
-| `<LogoutButton>` | Trigger logout |
-| `<ProtectedRoute>` | Require authentication to view content |
-| `<ModuleGate>` | Conditionally render based on enabled modules |
+| Component          | Description                                   |
+| ------------------ | --------------------------------------------- |
+| `<LoginButton>`    | Trigger Auth0 login                           |
+| `<LogoutButton>`   | Trigger logout                                |
+| `<ProtectedRoute>` | Require authentication to view content        |
+| `<ModuleGate>`     | Conditionally render based on enabled modules |
 
 ## Advanced Usage
 
 ### Custom API calls
 
 ```tsx
-import { useAuth } from '@axcode/axcloud-sdk'
+import { useAuth } from '@axcode/axcloud-sdk';
 
 function MyComponent() {
-  const { getAccessToken } = useAuth()
+  const { getAccessToken } = useAuth();
 
   const fetchCustomData = async () => {
-    const token = await getAccessToken()
+    const token = await getAccessToken();
     const response = await fetch('/api/custom', {
-      headers: { Authorization: `Bearer ${token}` }
-    })
-    return response.json()
-  }
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    return response.json();
+  };
 }
 ```
 
 ### Access the underlying Auth0 client
 
 ```tsx
-const { getAuth0Client } = useAuth()
-const auth0 = getAuth0Client()
+const { getAuth0Client } = useAuth();
+const auth0 = getAuth0Client();
 
 // Full Auth0 API available
-await auth0.getAccessTokenSilently()
-await auth0.getIdTokenClaims()
+await auth0.getAccessTokenSilently();
+await auth0.getIdTokenClaims();
 ```
 
 ## Security Model
@@ -362,58 +438,58 @@ await auth0.getIdTokenClaims()
 
 The SDK uses two types of credentials:
 
-1. **API Key** (`apiKey` prop): A *public identifier* for your organization
+1. **API Key** (`apiKey` prop): A _public identifier_ for your organization
    - Safe to include in client-side code
    - Used for public content endpoints
    - Backend validates and rate-limits based on API key
    - Without a valid API key, requests return 401
 
-2. **Authentication Token** (via Auth0): A *secret* JWT token
+2. **Authentication Token** (via Auth0): A _secret_ JWT token
    - Automatically managed by the SDK
    - Required for member-only content and user data
    - Never exposed in client code
 
 ### What the API Key Protects
 
-| Without API Key | With API Key | With Auth Token |
-|-----------------|--------------|-----------------|
-| Nothing | Public news/content | Member content |
-| | Organization branding | User profile |
-| | Public media | Linked accounts |
-| | | Admin functions |
+| Without API Key | With API Key          | With Auth Token |
+| --------------- | --------------------- | --------------- |
+| Nothing         | Public news/content   | Member content  |
+|                 | Organization branding | User profile    |
+|                 | Public media          | Linked accounts |
+|                 |                       | Admin functions |
 
 ### Endpoint Security
 
-| Endpoint Type | Authentication | Example |
-|--------------|---------------|---------|
-| Public content | API key (x-api-key header) | `/content/public/{orgId}/news` |
-| Member content | JWT Bearer token | `/content/members/{orgId}/news` |
-| User data | JWT Bearer token | `/api/users/me` |
-| Admin | JWT Bearer token + role | `/api/admin/forms/submissions` |
+| Endpoint Type  | Authentication             | Example                         |
+| -------------- | -------------------------- | ------------------------------- |
+| Public content | API key (x-api-key header) | `/content/public/{orgId}/news`  |
+| Member content | JWT Bearer token           | `/content/members/{orgId}/news` |
+| User data      | JWT Bearer token           | `/api/users/me`                 |
+| Admin          | JWT Bearer token + role    | `/api/admin/forms/submissions`  |
 
 ## Error Handling
 
 ```tsx
-import { useNews, isAxCloudError } from '@axcode/axcloud-sdk'
+import { useNews, isAxCloudError } from '@axcode/axcloud-sdk';
 
 function NewsPage() {
-  const { data, error, isError } = useNews()
+  const { data, error, isError } = useNews();
 
   if (isError) {
     if (isAxCloudError(error)) {
       switch (error.code) {
         case 'UNAUTHORIZED':
-          return <LoginPrompt />
+          return <LoginPrompt />;
         case 'NOT_FOUND':
-          return <NotFound />
+          return <NotFound />;
         default:
-          return <Error message={error.message} />
+          return <Error message={error.message} />;
       }
     }
-    return <Error message="Something went wrong" />
+    return <Error message="Something went wrong" />;
   }
 
-  return <NewsList items={data} />
+  return <NewsList items={data} />;
 }
 ```