Add useStatus hook and status page API support (v0.1.3)

Add getPublicStatusOverview client method and useStatus hook that
fetches status page data and transforms it into StatusData format
for the StatusBoard component. Includes auto-refresh polling and
new status API types.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: nedimf

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appgram/react",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "React library for integrating Appgram portal features with pre-built UI components and headless hooks",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

src/client/AppgramClient.ts

@@ -28,6 +28,7 @@ import type {
   ContactForm,
   ContactFormSubmission,
   ContactFormSubmitInput,
+  StatusPageOverview,
 } from '../types'
 
 export interface AppgramClientConfig {
@@ -625,6 +626,19 @@ export class AppgramClient {
     )
   }
 
+  // ============================================================================
+  // Status Pages
+  // ============================================================================
+
+  /**
+   * Get public status page overview (services, active updates, overall status)
+   */
+  async getPublicStatusOverview(slug = 'status'): Promise<ApiResponse<StatusPageOverview>> {
+    return this.get<StatusPageOverview>(
+      `/api/v1/status-pages/public/${this.projectId}/${slug}/overview`
+    )
+  }
+
   // ============================================================================
   // Surveys
   // ============================================================================

src/hooks/index.ts

@@ -27,6 +27,7 @@ export {
   type UseHelpArticleResult,
 } from './useHelpCenter'
 export { useSupport, type UseSupportOptions, type UseSupportResult } from './useSupport'
+export { useStatus, type UseStatusOptions, type UseStatusResult } from './useStatus'
 export {
   useSurvey,
   useSurveySubmit,

src/hooks/useStatus.ts

@@ -0,0 +1,259 @@
+/**
+ * useStatus Hook
+ *
+ * Fetches status page data and transforms it for the StatusBoard component.
+ * Supports auto-refresh polling.
+ */
+
+import { useState, useCallback, useEffect, useRef } from 'react'
+import { useAppgramContext } from '../provider/context'
+import { getErrorMessage } from '../utils'
+import type {
+  StatusPageOverview,
+  StatusUpdate as ApiStatusUpdate,
+  StatusPageService,
+  StatusType,
+} from '../types'
+import type {
+  StatusData,
+  StatusComponent,
+  StatusIncident,
+  OverallStatus,
+  ComponentStatus,
+} from '../components/status/StatusBoard'
+
+export interface UseStatusOptions {
+  /**
+   * Status page slug
+   * @default 'status'
+   */
+  slug?: string
+
+  /**
+   * Whether to fetch immediately
+   * @default true
+   */
+  enabled?: boolean
+
+  /**
+   * Auto-refresh interval in milliseconds (0 to disable)
+   * @default 30000
+   */
+  refreshInterval?: number
+}
+
+export interface UseStatusResult {
+  /**
+   * Transformed status data ready for StatusBoard
+   */
+  status: StatusData | null
+
+  /**
+   * Raw API overview response
+   */
+  overview: StatusPageOverview | null
+
+  /**
+   * Loading state
+   */
+  isLoading: boolean
+
+  /**
+   * Error message
+   */
+  error: string | null
+
+  /**
+   * Manually refresh
+   */
+  refetch: () => Promise<void>
+}
+
+// Map API status types to the component's simpler types
+function mapOverallStatus(apiStatus: StatusType): OverallStatus {
+  switch (apiStatus) {
+    case 'operational':
+      return 'operational'
+    case 'degraded_performance':
+      return 'degraded'
+    case 'partial_outage':
+      return 'partial_outage'
+    case 'major_outage':
+      return 'major_outage'
+    case 'maintenance':
+      return 'degraded'
+    case 'incident':
+      return 'major_outage'
+    default:
+      return 'operational'
+  }
+}
+
+function mapComponentStatus(apiStatus: StatusType): ComponentStatus {
+  switch (apiStatus) {
+    case 'operational':
+      return 'operational'
+    case 'degraded_performance':
+      return 'degraded'
+    case 'partial_outage':
+      return 'partial_outage'
+    case 'major_outage':
+      return 'major_outage'
+    case 'maintenance':
+      return 'degraded'
+    case 'incident':
+      return 'major_outage'
+    default:
+      return 'operational'
+  }
+}
+
+function transformToStatusData(overview: StatusPageOverview): StatusData {
+  // Transform services into components
+  const components: StatusComponent[] = (overview.services || []).map(
+    (service: StatusPageService) => ({
+      id: service.id,
+      name: service.name,
+      description: service.description || undefined,
+      status: mapComponentStatus(
+        overview.services_status[service.name] ||
+          overview.services_status[service.id] ||
+          'operational'
+      ),
+      group: service.group_name || undefined,
+    })
+  )
+
+  // Transform active updates into incidents
+  const incidents: StatusIncident[] = (overview.active_updates || []).map(
+    (update: ApiStatusUpdate) => ({
+      id: update.id,
+      title: update.title,
+      status: update.state === 'resolved' ? 'resolved' as const : 'investigating' as const,
+      impact:
+        update.status_type === 'major_outage'
+          ? ('critical' as const)
+          : update.status_type === 'partial_outage' || update.status_type === 'incident'
+          ? ('major' as const)
+          : ('minor' as const),
+      created_at: update.created_at,
+      resolved_at: update.resolved_at,
+      updates: [
+        {
+          id: `${update.id}-initial`,
+          message: update.description,
+          status: update.state === 'resolved' ? 'resolved' as const : 'investigating' as const,
+          created_at: update.created_at,
+        },
+      ],
+      affected_components: update.affected_services,
+    })
+  )
+
+  // Also include recent resolved updates as past incidents
+  const resolvedIncidents: StatusIncident[] = (overview.recent_updates || [])
+    .filter((u: ApiStatusUpdate) => u.state === 'resolved')
+    .map((update: ApiStatusUpdate) => ({
+      id: update.id,
+      title: update.title,
+      status: 'resolved' as const,
+      impact:
+        update.status_type === 'major_outage'
+          ? ('critical' as const)
+          : update.status_type === 'partial_outage' || update.status_type === 'incident'
+          ? ('major' as const)
+          : ('minor' as const),
+      created_at: update.created_at,
+      resolved_at: update.resolved_at,
+      updates: [
+        {
+          id: `${update.id}-initial`,
+          message: update.description,
+          status: 'resolved' as const,
+          created_at: update.created_at,
+        },
+      ],
+      affected_components: update.affected_services,
+    }))
+
+  // Merge and deduplicate
+  const allIncidentIds = new Set(incidents.map((i) => i.id))
+  const mergedIncidents = [
+    ...incidents,
+    ...resolvedIncidents.filter((i) => !allIncidentIds.has(i.id)),
+  ]
+
+  return {
+    overall_status: mapOverallStatus(overview.current_status),
+    components,
+    incidents: mergedIncidents,
+    last_updated: new Date().toISOString(),
+  }
+}
+
+export function useStatus(options: UseStatusOptions = {}): UseStatusResult {
+  const { slug = 'status', enabled = true, refreshInterval = 30000 } = options
+  const { client } = useAppgramContext()
+  const [overview, setOverview] = useState<StatusPageOverview | null>(null)
+  const [status, setStatus] = useState<StatusData | null>(null)
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null)
+
+  const fetchStatus = useCallback(
+    async (skipLoading = false) => {
+      if (!skipLoading) {
+        setIsLoading(true)
+      }
+      setError(null)
+
+      try {
+        const response = await client.getPublicStatusOverview(slug)
+
+        if (response.success && response.data) {
+          setOverview(response.data)
+          setStatus(transformToStatusData(response.data))
+        } else {
+          setError(getErrorMessage(response.error, 'Failed to fetch status'))
+        }
+      } catch (err) {
+        setError(getErrorMessage(err, 'An error occurred'))
+      } finally {
+        if (!skipLoading) {
+          setIsLoading(false)
+        }
+      }
+    },
+    [client, slug]
+  )
+
+  // Initial fetch
+  useEffect(() => {
+    if (enabled) {
+      fetchStatus()
+    }
+  }, [enabled, fetchStatus])
+
+  // Auto-refresh
+  useEffect(() => {
+    if (!enabled || refreshInterval <= 0) return
+
+    intervalRef.current = setInterval(() => {
+      fetchStatus(true)
+    }, refreshInterval)
+
+    return () => {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current)
+      }
+    }
+  }, [enabled, refreshInterval, fetchStatus])
+
+  return {
+    status,
+    overview,
+    isLoading,
+    error,
+    refetch: () => fetchStatus(false),
+  }
+}

src/index.ts

@@ -34,6 +34,7 @@ export {
   useSurveySubmit,
   useContactForm,
   useContactFormSubmit,
+  useStatus,
   type UseWishesOptions,
   type UseWishesResult,
   type UseWishOptions,
@@ -64,6 +65,8 @@ export {
   type UseContactFormResult,
   type UseContactFormSubmitOptions,
   type UseContactFormSubmitResult,
+  type UseStatusOptions,
+  type UseStatusResult,
 } from './hooks'
 
 // Components
@@ -184,6 +187,13 @@ export type {
   ContactFormFieldValidation,
   ContactFormSubmission,
   ContactFormSubmitInput,
+  // Status API types
+  StatusPage,
+  StatusUpdate as StatusUpdateApi,
+  StatusPageService,
+  StatusPageOverview,
+  StatusType,
+  StatusState,
   // Customization types
   CustomColors,
   CustomTypography,

src/types/index.ts

@@ -12,6 +12,7 @@ export * from './support'
 export * from './customization'
 export * from './survey'
 export * from './form'
+export * from './status'
 
 /**
  * API Response wrapper