@axcode/axcloud-sdk 0.2.0-dev.03fb26c → 0.2.0-dev.85285e0

package/README.md

@@ -40,6 +40,50 @@ version in a branch when needed, then promote and pin the stable release.
 
 ## Quick Start
 
+### Anonymous public sites (no Auth0)
+
+Public product sites that do not have member login should import the dedicated
+provider. It mounts the SDK client, React Query cache and privacy-safe analytics
+without importing or initializing Auth0:
+
+```tsx
+import { AxCloudPublicProvider } from '@axcode/axcloud-sdk/public';
+
+<AxCloudPublicProvider
+  orgId="barnsport"
+  apiUrl="https://api.axcloud.app"
+  stage="prod"
+  apiKey="pk_live_barnsport_read_submit"
+>
+  <App />
+</AxCloudPublicProvider>;
+```
+
+Use a browser-safe key restricted to the public scopes needed by the site. Do
+not use `AxCloudPublicProvider` for member or administrator features. Existing
+authenticated applications continue to use `AxCloudProvider` unchanged.
+
+### Barnsport product client and hooks
+
+Barnsport types, the core client and React hooks are available from a separate
+entrypoint so other products do not load Barnsport code:
+
+```tsx
+import {
+  useBarnsportProviderSearch,
+  useBarnsportProvider,
+  useSubmitBarnsportReview,
+  useTrackBarnsportEvent,
+} from '@axcode/axcloud-sdk/barnsport';
+
+const providers = useBarnsportProviderSearch({ q: searchText, limit: 5 });
+const provider = useBarnsportProvider(providerSlug);
+```
+
+Provider reviews and product events remain Barnsport domain data. The SDK
+routes them through the AxCloud Barnsport proxy; it does not store them in the
+generic Content service.
+
 ### 1. Wrap your app with AxCloudProvider
 
 ```tsx

package/dist/analytics-BOxmSWNt.d.ts

@@ -0,0 +1,432 @@
+import { A as AxCloudClient } from './client-FOpKwe3e.js';
+
+type AnalyticsEventValue = string | number | boolean;
+type AnalyticsEventData = Record<string, AnalyticsEventValue>;
+interface AxCloudAnalyticsOptions {
+    /** Site key configured in AxCloud, for example "public-web". */
+    siteKey: string;
+    /** Analytics is opt-in and disabled unless this is true. */
+    enabled?: boolean;
+    /** Allow local collection for explicit development tests. */
+    trackLocalhost?: boolean;
+    /** Override path normalization. Return null to skip a pageview. */
+    normalizePath?: (pathname: string) => string | null;
+}
+interface AnalyticsPublicConfig {
+    enabled: boolean;
+    provider?: 'umami';
+    websiteId?: string;
+    scriptUrl?: string;
+    hostUrl?: string;
+    domains?: string[];
+    autoTrack?: boolean;
+    respectDoNotTrack?: boolean;
+    excludeSearch?: boolean;
+    excludeHash?: boolean;
+    allowedEvents?: string[];
+}
+interface AnalyticsRuntime {
+    enabled: boolean;
+    ready: boolean;
+    track: (eventName: string, data?: AnalyticsEventData) => boolean;
+    trackPageView: (pathname?: string) => boolean;
+}
+declare function isLocalAnalyticsHostname(hostname: string): boolean;
+declare function sanitizeAnalyticsPath(pathname: string, customNormalizer?: (pathname: string) => string | null): string | null;
+declare function sanitizeAnalyticsEventData(data: AnalyticsEventData | undefined): AnalyticsEventData | undefined;
+declare function isAllowedAnalyticsEvent(eventName: string, allowedEvents: string[] | undefined): boolean;
+declare function fetchAnalyticsPublicConfig(input: {
+    apiUrl: string;
+    orgId: string;
+    siteKey: string;
+    stage: string;
+    hostname: string;
+    signal?: AbortSignal;
+}): Promise<AnalyticsPublicConfig>;
+
+/**
+ * AxCloud SDK Types
+ *
+ * Note: In the future, these types should be auto-generated from the OpenAPI spec.
+ * For now, they are manually defined based on the AxCloud API.
+ */
+
+type AxCloudModule = 'content' | 'members' | 'sections' | 'training' | 'ai' | 'documents' | 'voting';
+type SystemRole = 'super_admin' | 'org_admin' | 'section_admin' | 'member' | 'viewer';
+type UserRole = SystemRole | 'superadmin' | 'admin' | 'editor';
+type BaseRole = 'org_admin' | 'section_admin' | 'member' | 'viewer';
+/**
+ * Custom role definition
+ */
+interface CustomRole {
+    role_id: string;
+    org_id: string;
+    name: string;
+    description?: string;
+    baseRole: BaseRole;
+    permissions?: string[];
+    deniedPermissions?: string[];
+    effectivePermissions?: string[];
+    color?: string;
+    icon?: string;
+    hierarchy: number;
+    isSystem: false;
+    isActive: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Organization {
+    id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    modules: AxCloudModule[];
+    settings?: OrganizationSettings;
+    createdAt: string;
+    updatedAt: string;
+}
+interface OrganizationSettings {
+    allowPublicSignup?: boolean;
+    requireEmailVerification?: boolean;
+    defaultUserRole?: UserRole;
+    theme?: {
+        primaryColor?: string;
+        logo?: string;
+    };
+}
+interface Section {
+    id: string;
+    organizationId: string;
+    name: string;
+    description?: string;
+    slug: string;
+    parentId?: string;
+    permissions?: SectionPermissions;
+    createdAt: string;
+    updatedAt: string;
+}
+interface SectionPermissions {
+    canViewMembers?: boolean;
+    canEditContent?: boolean;
+    canManageMembers?: boolean;
+}
+interface User {
+    id: string;
+    email: string;
+    name: string;
+    firstName?: string;
+    lastName?: string;
+    /** Organization-specific title/position. Managed by organization administrators. */
+    title?: string | null;
+    phone?: string | null;
+    address?: string | null;
+    avatar?: string;
+    organizationId: string;
+    sectionId?: string;
+    role: UserRole;
+    customRole?: CustomRole;
+    permissions?: string[];
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Check if user has a specific permission
+ */
+declare function userHasPermission(user: User, permission: string): boolean;
+/**
+ * Check if user has any of the specified permissions
+ */
+declare function userHasAnyPermission(user: User, permissions: string[]): boolean;
+/**
+ * Check if user has all of the specified permissions
+ */
+declare function userHasAllPermissions(user: User, permissions: string[]): boolean;
+interface Membership {
+    userId: string;
+    organizationId: string;
+    sectionId?: string;
+    section?: Section;
+    role: UserRole;
+    /** Organization-specific title/position, separate from the access role. */
+    title?: string | null;
+    status: 'active' | 'pending' | 'suspended' | 'expired';
+    joinedAt: string;
+    expiresAt?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ContentBlock {
+    id: string;
+    type: string;
+    content?: string;
+    url?: string;
+    alt?: string;
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    items?: unknown[];
+    language?: string;
+    caption?: string;
+    attributes?: Record<string, unknown>;
+    ordered?: boolean;
+    author?: string;
+}
+interface ContentTranslation {
+    title: string;
+    slug: string;
+    description?: string;
+    blocks: ContentBlock[];
+    /** Structured website/template fields for this language. */
+    fields?: Record<string, unknown>;
+    metaTitle?: string;
+    metaDescription?: string;
+    keywords?: string[];
+}
+type ContentPublicationState = 'draft' | 'published' | 'archived';
+type ContentAudience = 'public' | 'internal' | 'members' | 'section';
+interface ContentItem {
+    id: string;
+    /** Present when a consumer needs to distinguish organizations outside its configured provider. */
+    organizationId?: string;
+    type: string;
+    title: string;
+    slug: string;
+    /** Legacy string content. New AxCloud content uses `blocks`. */
+    content?: string;
+    description?: string;
+    blocks?: ContentBlock[];
+    /** Template identifier used by websites, e.g. "home" or "landing". */
+    template?: string;
+    /** Structured website/template fields. Frontends own layout and read these values by key. */
+    fields?: Record<string, unknown>;
+    excerpt?: string;
+    author?: {
+        id: string;
+        name: string;
+    };
+    status?: ContentPublicationState;
+    visibility?: ContentPublicationState;
+    /** @deprecated Delivery access is derived from publication metadata and the verified visitor. */
+    audience?: ContentAudience;
+    sectionId?: string;
+    tags?: string[];
+    lang?: string;
+    featuredImage?: string;
+    metaTitle?: string;
+    metaDescription?: string;
+    keywords?: string[];
+    translations?: Record<string, ContentTranslation>;
+    currentLanguage?: string;
+    availableLanguages?: string[];
+    seo?: {
+        canonical: string;
+        hreflang: Array<{
+            lang: string;
+            href: string;
+        }>;
+    };
+    publishedAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface NewsItem extends ContentItem {
+    type: 'news';
+    featuredImage?: string;
+    category?: string;
+    tags?: string[];
+}
+interface Page extends ContentItem {
+    type: 'page';
+    template?: string;
+    order?: number;
+}
+interface ContentListResponse<T> {
+    items: T[];
+    count: number;
+    total: number;
+    page: number;
+    pageSize: number;
+    hasMore: boolean;
+    nextCursor?: string;
+}
+/** @deprecated Use ContentListResponse. */
+type PaginatedResponse<T> = ContentListResponse<T>;
+type ContentCollectionType = 'news' | 'pages' | 'events';
+type ContentDetailType = 'news' | 'page' | 'event';
+interface AxCloudConfig {
+    orgId: string;
+    apiUrl: string;
+    /** API stage - defaults to 'dev'. Use 'prod' for production. */
+    stage: string;
+    /** API key for public content endpoints (optional - required for public API access) */
+    apiKey?: string;
+    /** Optional privacy-safe web analytics collection. */
+    analytics?: AxCloudAnalyticsOptions;
+    auth0: {
+        domain: string;
+        clientId: string;
+        redirectUri: string;
+        audience?: string;
+        /** Auth0 Organization ID. Use this for invite-only member sites. */
+        organization?: string;
+        /** Database connection name for password operations. Defaults to 'Username-Password-Authentication' */
+        connection?: string;
+    };
+}
+interface ContentQueryOptions {
+    page?: number;
+    pageSize?: number;
+    /** @deprecated Delivery endpoints always return the published snapshot. */
+    status?: ContentPublicationState;
+    /** @deprecated Delivery endpoints always return the published snapshot. */
+    visibility?: ContentPublicationState;
+    audience?: ContentAudience;
+    /** @deprecated Member section access is derived from the verified token. */
+    sectionId?: string;
+    search?: string;
+    sortBy?: 'publishedAt' | 'createdAt' | 'updatedAt' | 'title';
+    sortOrder?: 'asc' | 'desc';
+    tags?: string[];
+    /** Return the requested translation when content has language variants. */
+    lang?: string;
+    /** Force public endpoint even when authenticated (for public pages) */
+    publicOnly?: boolean;
+}
+/**
+ * Organization branding information
+ */
+interface OrganizationBranding {
+    organizationId: string;
+    name: string;
+    branding: {
+        /** Signed URL for logo (expires in 1 hour) */
+        logoUrl: string | null;
+        /** Seconds until logoUrl expires */
+        logoExpiresIn: number | null;
+        /** Primary brand color (hex) */
+        primaryColor: string | null;
+        /** Secondary brand color (hex) */
+        secondaryColor: string | null;
+    };
+}
+/**
+ * Signed URL response for media assets
+ */
+interface SignedMediaUrl {
+    /** Signed S3 URL (expires in 1 hour) */
+    url: string;
+    /** Seconds until URL expires */
+    expiresIn: number;
+    /** S3 bucket name */
+    bucket: string;
+    /** S3 object key */
+    key: string;
+}
+/**
+ * Media list item
+ */
+interface MediaItem {
+    /** File key (filename) */
+    key: string;
+    /** File size in bytes */
+    size: number;
+    /** Last modified timestamp */
+    lastModified: string;
+}
+/**
+ * Media list response
+ */
+interface MediaListResponse {
+    items: MediaItem[];
+    count: number;
+    bucket: string;
+    prefix: string;
+}
+type DocumentStatus = 'draft' | 'published' | 'archived';
+type DocumentAudience = 'public' | 'members' | 'section' | 'internal';
+type DocumentSourceProvider = 'upload' | 'sharepoint';
+/**
+ * Public document metadata exposed through the AxCloud SDK.
+ */
+interface DocumentItem {
+    document_id: string;
+    org_id: string;
+    title: string;
+    description?: string;
+    filename: string;
+    mime_type: string;
+    size: number;
+    status: DocumentStatus;
+    audience: DocumentAudience;
+    tags: string[];
+    source_provider: DocumentSourceProvider;
+    created_at: string;
+    updated_at: string;
+    published_at?: string;
+    /** Section IDs this document is scoped to (member endpoint only). */
+    section_ids?: string[];
+    /** Display name of the member who uploaded the document (member endpoint only). */
+    uploaded_by_name?: string;
+    /** Folder IDs this document belongs to (member endpoint only). */
+    folder_ids?: string[];
+}
+interface DocumentListResponse {
+    items: DocumentItem[];
+    count: number;
+}
+/**
+ * A document folder the current member is allowed to see.
+ *
+ * Members receive folders for their own sections plus org-level folders
+ * (`section_id === null`). Returned by the member document-folders endpoint.
+ */
+interface DocumentFolder {
+    id: string;
+    /** Section this folder belongs to, or `null` for org-level folders. */
+    section_id: string | null;
+    /** Parent folder for nesting, or `null` for a top-level folder. */
+    parent_folder_id: string | null;
+    name: string;
+    sort_order: number;
+}
+interface DocumentFolderListResponse {
+    folders: DocumentFolder[];
+}
+interface SignedDocumentUrl {
+    documentId: string;
+    url: string;
+    expiresIn: number;
+    filename: string;
+    mimeType: string;
+}
+interface DocumentQueryOptions {
+    search?: string;
+    tags?: string[];
+    limit?: number;
+    /** Restrict results to documents belonging to this folder (member endpoint only). */
+    folderId?: string;
+}
+
+interface AxCloudContextValue {
+    config: AxCloudConfig;
+    client: AxCloudClient;
+    orgId: string;
+    /** API stage (e.g., 'dev', 'prod') */
+    stage: string;
+    /** Whether using public API mode (API key, no auth) */
+    isPublicMode: boolean;
+    /** Auth0 has completed its initial session check. */
+    isAuthLoading?: boolean;
+    /** Whether the current browser session is authenticated. */
+    isAuthenticated?: boolean;
+    /** Auth0 subject used to isolate member-only query caches. */
+    authSubject?: string;
+    /** Remove identity-bound AxCloud query data before logout or account changes. */
+    clearContentCache?: () => void;
+    analytics: AnalyticsRuntime;
+}
+declare function useAxCloudContext(): AxCloudContextValue;
+
+type AnalyticsRuntimeConfig = Pick<AxCloudConfig, 'analytics' | 'apiUrl' | 'orgId' | 'stage'>;
+declare function useAnalyticsRuntime(config: AnalyticsRuntimeConfig): AnalyticsRuntime;
+declare function useAnalytics(): AnalyticsRuntime;
+
+export { type AxCloudAnalyticsOptions as A, type BaseRole as B, type ContentItem as C, type DocumentQueryOptions as D, type PaginatedResponse as E, type SectionPermissions as F, type SystemRole as G, fetchAnalyticsPublicConfig as H, isAllowedAnalyticsEvent as I, isLocalAnalyticsHostname as J, sanitizeAnalyticsEventData as K, sanitizeAnalyticsPath as L, type MediaItem as M, type NewsItem as N, type Organization as O, type Page as P, useAnalytics as Q, useAnalyticsRuntime as R, type Section as S, useAxCloudContext as T, type User as U, userHasAllPermissions as V, userHasAnyPermission as W, userHasPermission as X, type UserRole as a, type AxCloudModule as b, type ContentQueryOptions as c, type ContentListResponse as d, type SignedMediaUrl as e, type OrganizationBranding as f, type MediaListResponse as g, type SignedDocumentUrl as h, type DocumentItem as i, type DocumentListResponse as j, type DocumentFolder as k, type DocumentFolderListResponse as l, type AnalyticsEventData as m, type AnalyticsEventValue as n, type AnalyticsPublicConfig as o, type AnalyticsRuntime as p, type AnalyticsRuntimeConfig as q, type AxCloudConfig as r, type ContentCollectionType as s, type ContentDetailType as t, type CustomRole as u, type DocumentAudience as v, type DocumentSourceProvider as w, type DocumentStatus as x, type Membership as y, type OrganizationSettings as z };