@axcode/axcloud-sdk 0.1.7-dev.87ea138 → 0.1.7-dev.cc5cc69

package/README.md

@@ -1,6 +1,8 @@
 # @axcode/axcloud-sdk
 
-SDK for building websites with AxCloud CMS and member management.
+SDK for building websites with AxCloud CMS and member management. AxCloud is
+headless: it owns content, publication, access control and delivery APIs, while
+the consuming application owns markup, layout and design.
 
 ## Installation
 
@@ -12,109 +14,116 @@ 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:**
+**Recommended production setup:**
 
-```json
-// Production project (package.json)
-{
-  "dependencies": {
-    "@axcode/axcloud-sdk": "^0.1.0"
-  }
-}
+Resolve `latest` deliberately, then commit the exact version and lockfile:
+
+```bash
+npm install --save-exact @axcode/axcloud-sdk@latest
+```
 
-// Development/Staging project (package.json)
+```json
 {
   "dependencies": {
-    "@axcode/axcloud-sdk": "next"
+    "@axcode/axcloud-sdk": "0.1.6"
   }
 }
 ```
 
-This allows you to test new SDK features in your staging environment before they reach production.
+Do not install a moving tag in CI or during deployment. Test a specific `next`
+version in a branch when needed, then promote and pin the stable release.
 
 ## Quick Start
 
 ### 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>
-  )
+  );
 }
 ```
 
-> **Content visibility:** When the user is authenticated, `useNews`, `useContent('pages')`, and `useContent('events')` automatically fetch **public + internal + members-only** content based on the user's organization membership. For anonymous users, only public content is returned.
+> **Content delivery:** These hooks return only published snapshots. When the
+> user is authenticated, access to internal, member and section content is
+> derived from the verified token. Anonymous users receive only public content.
+> Client-supplied status or section identifiers never grant broader access.
 
 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 +136,7 @@ function Header() {
         <LoginButton>Sign In</LoginButton>
       )}
     </header>
-  )
+  );
 }
 
 function MemberArea() {
@@ -135,87 +144,150 @@ 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
+### 4b. Section-scoped content
 
 ```tsx
-import { useNews, useMySection } from '@axcode/axcloud-sdk'
+import { useNews, useMySection } from '@axcode/axcloud-sdk';
 
 function SectionNews() {
-  const { sectionId } = useMySection()
-
-  // Fetch news for user's section only
-  const { data: sectionNews } = useNews({ sectionId })
-
-  // Or fetch all organization news
-  const { data: allNews } = useNews()
+  const { section } = useMySection();
+  // AxCloud derives the allowed sections from the authenticated membership.
+  const { data: visibleNews } = useNews();
 
   return (
     <div>
       <h2>Section News</h2>
-      {sectionNews.map(item => <NewsCard key={item.id} item={item} />)}
-
-      <h2>All Organization News</h2>
-      {allNews.map(item => <NewsCard key={item.id} item={item} />)}
+      {visibleNews.map((item) => (
+        <NewsCard key={item.id} item={item} />
+      ))}
+      {!section && <p>You are not assigned to a section.</p>}
     </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 +296,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 +324,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 +339,7 @@ function Dashboard() {
 
       {hasModule('ai') && <AIChatWidget />}
     </div>
-  )
+  );
 }
 ```
 
@@ -275,85 +347,134 @@ 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 the normalized user and verified organization membership                               |
+| `useUpdateMyProfile()`            | Update the signed-in user's name, phone, and address                                          |
+| `useOrg()`                        | Fetch organization info and check modules                                                    |
+| `useNews(options?)`               | Fetch the published news collection visible to the current visitor                           |
+| `useContent(type, options?)`      | Fetch a published `news`, `pages`, or `events` collection                                    |
+| `useContentItem(type, id, opts?)` | Fetch one published item directly by ID or slug                                              |
+| `usePageContent(slug, options?)`  | Fetch a page and read structured template slots                                              |
+| `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                                                         |
+
+Profile self-service is deliberately limited to personal contact fields. Organization title,
+email, roles, status, organization, and section assignments remain administrator-managed.
+
+`useUser()` normalizes the API response to camelCase. Organization-specific values always come
+from the membership for the provider's `orgId`:
+
+```tsx
+const {
+  user,
+  roleInOrg,
+  title,
+  section,       // { id, name, role } | null
+  sections,      // all verified section memberships
+  sectionId,
+  sectionIds,
+  memberSince,   // normalized from joined_at
+} = useUser();
+
+return <p>{section?.name ?? 'No section'} · member since {memberSince}</p>;
+```
+
+```tsx
+import { useUpdateMyProfile } from '@axcode/axcloud-sdk';
+
+function ProfileForm() {
+  const updateProfile = useUpdateMyProfile();
+
+  const save = () => updateProfile.mutateAsync({
+    firstName: 'Anna',
+    lastName: 'Pilot',
+    phone: '+46701234567',
+    address: 'Flyggatan 1',
+  });
+
+  return <button onClick={save} disabled={updateProfile.isPending}>Save profile</button>;
+}
+```
 
 ### 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)
+  search?: string; // Search in title/content
+  sortBy?: 'publishedAt' | 'createdAt' | 'updatedAt' | 'title';
+  sortOrder?: 'asc' | 'desc';
+  tags?: string[];
+  lang?: string; // Return translated title/slug/blocks when available
+  publicOnly?: boolean; // Force public endpoint even when authenticated
 }
 ```
 
+Collection hooks return `data`, `count`, `total`, `page`, `pageSize`,
+`hasMore`, `nextCursor`, `isLoading`, `isFetching`, `isError`, `error` and
+`refetch`. During Auth0's initial session check, member-capable hooks wait
+instead of briefly requesting public content. Member caches are isolated per
+Auth0 subject and removed on logout or account change.
+All other identity-bound AxCloud query data is removed at the same boundary.
+
+Structured slots are untrusted CMS input. Prefer `text()`, `list()` and
+`image()`. `unsafeHtml()` (and the deprecated `html()` alias) must be sanitized
+before use with `dangerouslySetInnerHTML`.
+
 ### 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 +483,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} />;
 }
 ```