@axcode/axcloud-sdk 0.1.5 → 0.1.7-dev.3a3be6d

package/README.md

@@ -87,10 +87,10 @@ function NewsPage() {
 
 > **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.
 
-Pages can be stored once in AxCloud with translations and requested per language:
+Pages and news can be stored once in AxCloud with translations and requested per language:
 
 ```tsx
-import { useContentItem } from '@axcode/axcloud-sdk'
+import { useContentItem, useNews } from '@axcode/axcloud-sdk'
 
 function AboutPage({ locale }: { locale: 'sv' | 'en' }) {
   const { data: page } = useContentItem('pages', 'about-us', {
@@ -100,6 +100,12 @@ function AboutPage({ locale }: { locale: 'sv' | 'en' }) {
 
   return <h1>{page?.title}</h1>
 }
+
+function NewsList({ locale }: { locale: 'sv' | 'en' }) {
+  const { data: news } = useNews({ lang: locale })
+
+  return news.map(item => <article key={item.id}>{item.title}</article>)
+}
 ```
 
 ### 3. Add authentication
@@ -215,7 +221,35 @@ function HeroImage() {
 
 > **Note:** Media URLs are signed S3 URLs that expire after 1 hour. The SDK automatically refreshes them before expiry (staleTime: 30 min).
 
-### 6. Gate features by module
+### 6. Fetch public documents
+
+```tsx
+import { useDocuments, useDocumentDownload } from '@axcode/axcloud-sdk'
+
+function PublicDocuments() {
+  const { documents, isLoading } = useDocuments({ tags: ['handbook'], limit: 20 })
+
+  if (isLoading) return <Skeleton />
+  return (
+    <ul>
+      {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>
+}
+```
+
+Only documents with `status: "published"` and `audience: "public"` are exposed through SDK document hooks.
+
+### 7. Gate features by module
 
 ```tsx
 import { ModuleGate, useOrg } from '@axcode/axcloud-sdk'
@@ -261,6 +295,8 @@ function Dashboard() {
 | `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
 

package/dist/index.d.mts

@@ -216,6 +216,8 @@ interface ContentTranslation {
     slug: string;
     description?: string;
     blocks: ContentBlock[];
+    /** Structured website/template fields for this language. */
+    fields?: Record<string, unknown>;
     metaTitle?: string;
     metaDescription?: string;
     keywords?: string[];
@@ -232,6 +234,10 @@ interface ContentItem {
     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;
@@ -360,6 +366,222 @@ interface MediaListResponse {
     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;
+}
+interface DocumentListResponse {
+    items: DocumentItem[];
+    count: number;
+}
+interface SignedDocumentUrl {
+    documentId: string;
+    url: string;
+    expiresIn: number;
+    filename: string;
+    mimeType: string;
+}
+interface DocumentQueryOptions {
+    search?: string;
+    tags?: string[];
+    limit?: number;
+}
+
+interface BarnsportMunicipality {
+    id: string;
+    slug: string;
+    name: string;
+    county?: string;
+    geo?: {
+        lat: number;
+        lng: number;
+        bounds?: [number, number, number, number];
+    };
+}
+interface BarnsportSport {
+    id: string;
+    slug: string;
+    name: string;
+    icon?: string;
+    color?: string;
+}
+interface BarnsportActivitySchedule {
+    weekday?: number;
+    starts_at?: string;
+    ends_at?: string;
+    label?: string;
+    season?: string;
+}
+interface BarnsportActivityLocation {
+    name?: string;
+    address?: string;
+    lat?: number;
+    lng?: number;
+}
+interface BarnsportRegistrationMethod {
+    type: 'url' | 'email' | 'phone' | 'form' | 'external';
+    label?: string;
+    value: string;
+    instructions?: string;
+    preferred?: boolean;
+}
+interface BarnsportActivityListItem {
+    id: string;
+    slug: string;
+    title: string;
+    summary?: string;
+    sport: {
+        id: string;
+        slug: string;
+        name?: string;
+        icon?: string;
+    };
+    municipality: {
+        id: string;
+        slug: string;
+        name?: string;
+    };
+    club: {
+        id: string;
+        slug: string;
+        name?: string;
+    };
+    birthYears?: number[];
+    minBirthYear?: number;
+    maxBirthYear?: number;
+    ageLabel?: string;
+    schedule: BarnsportActivitySchedule[];
+    location?: BarnsportActivityLocation;
+    registrationSummary?: string;
+    updatedAt: string;
+}
+interface BarnsportActivity {
+    activity_id: string;
+    org_id: string;
+    slug: string;
+    title: string;
+    summary?: string;
+    description?: string;
+    sport_id: string;
+    sport_slug: string;
+    sport_name?: string;
+    sport_icon?: string;
+    municipality_id: string;
+    municipality_slug: string;
+    municipality_name?: string;
+    club_id: string;
+    club_slug: string;
+    club_name?: string;
+    club_website_url?: string;
+    birth_years?: number[];
+    min_birth_year?: number;
+    max_birth_year?: number;
+    age_label?: string;
+    schedule: BarnsportActivitySchedule[];
+    location?: BarnsportActivityLocation;
+    registration: {
+        methods: BarnsportRegistrationMethod[];
+        deadline?: string;
+        price_label?: string;
+    };
+    seo?: {
+        title?: string;
+        description?: string;
+        image_media_id?: string;
+    };
+    published_at?: string;
+    updated_at: string;
+}
+interface BarnsportActivitiesFilter {
+    municipality?: string;
+    sport?: string;
+    birthYear?: number;
+    q?: string;
+    search?: string;
+    sort?: 'updated' | 'name' | 'relevance';
+    cursor?: string;
+    limit?: number;
+}
+interface BarnsportListResponse<T> {
+    items: T[];
+    count: number;
+    nextCursor?: string | null;
+}
+interface BarnsportActivityResponse {
+    activity: BarnsportActivity;
+}
+interface BarnsportSitemapUrl {
+    loc: string;
+    lastmod?: string;
+    changefreq?: string;
+    priority?: number;
+}
+interface BarnsportSitemapResponse {
+    baseUrl: string;
+    updatedAt: string;
+    urls: BarnsportSitemapUrl[];
+}
+interface BarnsportInterestSubmissionRequest {
+    activitySlug: string;
+    guardianName: string;
+    guardianEmail: string;
+    guardianPhone?: string;
+    childName?: string;
+    childBirthYear?: number;
+    message?: string;
+    consent: {
+        contact: boolean;
+        privacyVersion: string;
+    };
+    honeypot?: string;
+    source?: {
+        site?: string;
+        pageUrl?: string;
+        utm?: Record<string, string>;
+    };
+}
+interface BarnsportInterestSubmissionResponse {
+    success: boolean;
+    submissionId?: string;
+    duplicate?: boolean;
+    message: string;
+}
+
+type ContentSlotValue = string | number | boolean | null | undefined | string[] | Record<string, unknown> | unknown[];
+type ContentSlotMap = Record<string, ContentSlotValue>;
+interface ContentSlotImage {
+    url: string;
+    alt?: string;
+    caption?: string;
+}
+interface ContentSlotReader {
+    fields: ContentSlotMap;
+    value<T = ContentSlotValue>(key: string, fallback?: T): ContentSlotValue | T;
+    text(key: string, fallback?: string): string;
+    html(key: string, fallback?: string): string;
+    list(key: string, fallback?: string[]): string[];
+    image(key: string, fallback?: ContentSlotImage): ContentSlotImage | undefined;
+}
+declare function getContentSlotMap(content?: Pick<ContentItem, 'fields' | 'blocks'> | null): ContentSlotMap;
+declare function createContentSlotReader(content?: Pick<ContentItem, 'fields' | 'blocks'> | null): ContentSlotReader;
 
 /**
  * AxCloud Forms Module
@@ -529,6 +751,128 @@ declare function createFormHelper(config: {
     submit: (formType: "waitlist" | "contact" | "membership", email: string, data?: Record<string, unknown>) => Promise<FormSubmissionResponse>;
 };
 
+/**
+ * AxCloud Voting Module
+ *
+ * Functions for embedding voting/elections on a customer site (e.g. spf.se).
+ *
+ * Two channels:
+ *  - PUBLIC (code): no login — the personal one-time code is the credential.
+ *    Use {@link checkVotingCode}, {@link castVoteWithCode}, {@link getVotingReceipt}.
+ *  - AUTHED (Auth0): a logged-in member votes with their access token.
+ *    Use {@link getBallot}, {@link checkEligibility}, {@link castVote}.
+ *
+ * `votingApiUrl` is the Voting API base, e.g. 'https://api.axcloud.app/voting'.
+ */
+interface BallotSeat {
+    seat_id: string;
+    label_sv: string;
+    label_en?: string;
+    term?: string;
+    count: number;
+    order?: number;
+}
+interface BallotCandidate {
+    candidate_id: string;
+    name: string;
+    bio_sv?: string;
+    bio_en?: string;
+    presentation_media_id?: string;
+    photo_media_id?: string;
+}
+interface BallotOption {
+    option_id: string;
+    text: string;
+    description?: string;
+}
+interface Ballot {
+    poll_id: string;
+    poll_type: 'single_choice' | 'multiple_choice' | 'ranking' | 'election';
+    title: string;
+    title_en?: string;
+    description?: string;
+    description_en?: string;
+    seats?: BallotSeat[];
+    max_selections?: number;
+    min_selections?: number;
+    ends_at?: string;
+    options?: BallotOption[];
+    candidates?: BallotCandidate[];
+}
+interface CodeEligibility {
+    eligible: boolean;
+    has_voted: boolean;
+    reason?: string;
+    ballot?: Ballot;
+}
+interface VoteReceipt {
+    has_voted: boolean;
+    voted_at?: string;
+    selected_option_ids?: string[];
+    selection?: string[];
+}
+interface CastVoteResult {
+    success: boolean;
+    voted_at?: string;
+    message?: string;
+}
+/**
+ * Validate a personal code and, if valid, return the ballot to render.
+ */
+declare function checkVotingCode(votingApiUrl: string, params: {
+    orgId: string;
+    pollId: string;
+    code: string;
+}): Promise<CodeEligibility>;
+/**
+ * Cast a vote using a personal code.
+ */
+declare function castVoteWithCode(votingApiUrl: string, params: {
+    orgId: string;
+    pollId: string;
+    code: string;
+    selectedOptions: string[];
+    rankings?: Record<string, number>;
+}): Promise<CastVoteResult>;
+/**
+ * After voting, re-check a code to retrieve the voter's own selection.
+ */
+declare function getVotingReceipt(votingApiUrl: string, params: {
+    orgId: string;
+    pollId: string;
+    code: string;
+}): Promise<VoteReceipt>;
+/**
+ * Load a ballot (poll + candidates) for a logged-in member.
+ */
+declare function getBallot(votingApiUrl: string, params: {
+    orgId: string;
+    pollId: string;
+    accessToken: string;
+}): Promise<Ballot>;
+/**
+ * Check whether the logged-in member is eligible to vote / has already voted.
+ */
+declare function checkEligibility(votingApiUrl: string, params: {
+    orgId: string;
+    pollId: string;
+    accessToken: string;
+}): Promise<{
+    eligible: boolean;
+    has_voted: boolean;
+    reason?: string;
+}>;
+/**
+ * Cast a vote as a logged-in member.
+ */
+declare function castVote(votingApiUrl: string, params: {
+    orgId: string;
+    pollId: string;
+    accessToken: string;
+    selectedOptions: string[];
+    rankings?: Record<string, number>;
+}): Promise<CastVoteResult>;
+
 interface AxCloudProviderProps {
     children: React.ReactNode;
     orgId: string;
@@ -896,6 +1240,22 @@ declare function useContentItem<T extends ContentItem = ContentItem>(contentType
     error: Error | null;
     refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_tanstack_react_query.NoInfer<T>, Error>>;
 };
+interface PageContentState<T extends ContentItem = ContentItem> extends ContentSlotReader {
+    page: T | null;
+    data: T | null;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error | null;
+    refetch: () => unknown;
+}
+/**
+ * usePageContent - Fetch a website page and expose structured template fields.
+ *
+ * Use `page.content`/`page.blocks` for article-like rich text pages. Use
+ * `text('hero.title')`, `list('benefits.items')`, etc. for designed website templates
+ * where the frontend owns layout and AxCloud owns content.
+ */
+declare function usePageContent<T extends ContentItem = ContentItem>(slug: string, options?: ContentItemOptions): PageContentState<T>;
 
 interface SectionWithMembers extends Section {
     members?: User[];
@@ -1092,6 +1452,25 @@ declare function useUpdateFormSubmission(): _tanstack_react_query.UseMutationRes
     notes?: string;
 }, unknown>;
 
+type CodeBallotStage = 'enter_code' | 'ballot' | 'submitted' | 'already_voted';
+interface UseCodeBallotOptions {
+    pollId: string;
+    /** Override the Voting API base URL. Defaults to `${config.apiUrl}/voting`. */
+    votingApiUrl?: string;
+}
+declare function useCodeBallot({ pollId, votingApiUrl }: UseCodeBallotOptions): {
+    stage: CodeBallotStage;
+    code: string;
+    ballot: Ballot | null;
+    receipt: VoteReceipt | null;
+    reason: string | undefined;
+    loading: boolean;
+    error: string | null;
+    validateCode: (inputCode: string) => Promise<CodeEligibility | null>;
+    submitVote: (selectedOptions: string[], rankings?: Record<string, number>) => Promise<boolean>;
+    reset: () => void;
+};
+
 /**
  * useLinkedAccounts Hook
  *
@@ -1304,6 +1683,77 @@ declare function useMedia(mediaId: string): {
     refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<SignedMediaUrl, Error>>;
 };
 
+/**
+ * List documents that have been explicitly published for public SDK access.
+ *
+ * Documents with members/internal/section audience stay inside AxCloud.
+ */
+declare function useDocuments(options?: DocumentQueryOptions): {
+    documents: DocumentItem[];
+    items: DocumentItem[];
+    count: number;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error | null;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<DocumentListResponse, Error>>;
+};
+/**
+ * Fetch a short-lived signed download URL for a public document.
+ */
+declare function useDocumentDownload(documentId: string | undefined): {
+    url: string | null;
+    documentUrl: string | null;
+    filename: string | null;
+    mimeType: string | null;
+    expiresIn: number | null;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error | null;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<SignedDocumentUrl, Error>>;
+};
+
+declare function useBarnsportMunicipalities(): {
+    municipalities: BarnsportMunicipality[];
+    count: number;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error | null;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<BarnsportListResponse<BarnsportMunicipality>, Error>>;
+};
+declare function useBarnsportSports(): {
+    sports: BarnsportSport[];
+    count: number;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error | null;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<BarnsportListResponse<BarnsportSport>, Error>>;
+};
+declare function useBarnsportActivities(filters?: BarnsportActivitiesFilter): {
+    activities: BarnsportActivityListItem[];
+    count: number;
+    nextCursor: string | null;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error | null;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<BarnsportListResponse<BarnsportActivityListItem>, Error>>;
+};
+declare function useBarnsportActivity(slug: string | undefined): {
+    activity: BarnsportActivity | null;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error | null;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<BarnsportActivityResponse, Error>>;
+};
+declare function useBarnsportSitemap(baseUrl?: string): {
+    sitemap: BarnsportSitemapResponse | null;
+    urls: BarnsportSitemapUrl[];
+    isLoading: boolean;
+    isError: boolean;
+    error: Error | null;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<BarnsportSitemapResponse, Error>>;
+};
+declare function useSubmitBarnsportInterest(): _tanstack_react_query.UseMutationResult<BarnsportInterestSubmissionResponse, Error, BarnsportInterestSubmissionRequest, unknown>;
+
 interface LoginButtonProps {
     /**
      * Button text when not authenticated
@@ -1529,4 +1979,4 @@ interface LinkedAccountsListProps {
  */
 declare function LinkedAccountsList({ providers, showConnectButtons, className, onUnlink, onLinkInitiated, renderIdentity, renderAvailableProvider, }: LinkedAccountsListProps): react_jsx_runtime.JSX.Element;
 
-export { type AvailableProvider, AxCloudClient, type AxCloudConfig, AxCloudError, type AxCloudErrorCode, type AxCloudModule, AxCloudProvider, type BaseRole, type ContentItem, type ContentQueryOptions, type CustomRole, type FormStatsResponse, type FormSubmission, type FormSubmissionRecord, type FormSubmissionResponse, type FormSubmissionsResponse, LinkedAccountsList, type LinkedAccountsListProps, type LinkedIdentity, LoginButton, LogoutButton, type MediaItem, type MediaListResponse, type Membership, ModuleGate, type NewsItem, type Organization, type OrganizationBranding, type OrganizationSettings, type Page, type PaginatedResponse, ProtectedRoute, type Section, type SectionPermissions, type SignedMediaUrl, type SystemRole, type UseLinkedAccountsReturn, type User, type UserRole, createClient, createFormHelper, getClient, isAxCloudError, submitForm, useAuth, useAvatar, useAxCloudContext, useBranding, useContent, useContentItem, useFormStats, useForms, useLinkedAccounts, useLogo, useMedia, useMediaList, useModuleAccess, useMySection, useNews, useOrg, useSections, useUpdateFormSubmission, useUser, userHasAllPermissions, userHasAnyPermission, userHasPermission };
+export { type AvailableProvider, AxCloudClient, type AxCloudConfig, AxCloudError, type AxCloudErrorCode, type AxCloudModule, AxCloudProvider, type Ballot, type BallotCandidate, type BallotOption, type BallotSeat, type BarnsportActivitiesFilter, type BarnsportActivity, type BarnsportActivityListItem, type BarnsportActivityLocation, type BarnsportActivityResponse, type BarnsportActivitySchedule, type BarnsportInterestSubmissionRequest, type BarnsportInterestSubmissionResponse, type BarnsportListResponse, type BarnsportMunicipality, type BarnsportRegistrationMethod, type BarnsportSitemapResponse, type BarnsportSitemapUrl, type BarnsportSport, type BaseRole, type CastVoteResult, type CodeEligibility, type ContentItem, type ContentQueryOptions, type ContentSlotImage, type ContentSlotMap, type ContentSlotReader, type ContentSlotValue, type CustomRole, type DocumentAudience, type DocumentItem, type DocumentListResponse, type DocumentQueryOptions, type DocumentSourceProvider, type DocumentStatus, type FormStatsResponse, type FormSubmission, type FormSubmissionRecord, type FormSubmissionResponse, type FormSubmissionsResponse, LinkedAccountsList, type LinkedAccountsListProps, type LinkedIdentity, LoginButton, LogoutButton, type MediaItem, type MediaListResponse, type Membership, ModuleGate, type NewsItem, type Organization, type OrganizationBranding, type OrganizationSettings, type Page, type PageContentState, type PaginatedResponse, ProtectedRoute, type Section, type SectionPermissions, type SignedDocumentUrl, type SignedMediaUrl, type SystemRole, type UseLinkedAccountsReturn, type User, type UserRole, type VoteReceipt, castVote, castVoteWithCode, checkEligibility, checkVotingCode, createClient, createContentSlotReader, createFormHelper, getBallot, getClient, getContentSlotMap, getVotingReceipt, isAxCloudError, submitForm, useAuth, useAvatar, useAxCloudContext, useBarnsportActivities, useBarnsportActivity, useBarnsportMunicipalities, useBarnsportSitemap, useBarnsportSports, useBranding, useCodeBallot, useContent, useContentItem, useDocumentDownload, useDocuments, useFormStats, useForms, useLinkedAccounts, useLogo, useMedia, useMediaList, useModuleAccess, useMySection, useNews, useOrg, usePageContent, useSections, useSubmitBarnsportInterest, useUpdateFormSubmission, useUser, userHasAllPermissions, userHasAnyPermission, userHasPermission };