@idealyst/live-activity 1.2.114

package/src/activity/activity.native.ts

@@ -0,0 +1,198 @@
+// ============================================================================
+// Native Live Activity Implementation
+// Bridges to the IdealystLiveActivity TurboModule (iOS: ActivityKit, Android: ProgressStyle).
+// ============================================================================
+
+import { NativeEventEmitter, Platform } from 'react-native';
+import type {
+  LiveActivityEventHandler,
+  LiveActivityEvent,
+} from '../types';
+import { createLiveActivityError, normalizeLiveActivityError } from '../errors';
+import { LIVE_ACTIVITY_EVENT } from '../constants';
+import NativeLiveActivity from '../NativeLiveActivitySpec';
+
+function assertNativeModule(): void {
+  if (!NativeLiveActivity) {
+    throw createLiveActivityError(
+      'not_available',
+      '@idealyst/live-activity native module is not linked. Ensure the package is installed and your project is rebuilt.',
+    );
+  }
+}
+
+// ============================================================================
+// Availability
+// ============================================================================
+
+export async function checkAvailability(): Promise<{
+  supported: boolean;
+  enabled: boolean;
+}> {
+  if (!NativeLiveActivity) {
+    return { supported: false, enabled: false };
+  }
+
+  try {
+    const supported = NativeLiveActivity.isSupported();
+    const enabled = supported ? await NativeLiveActivity.isEnabled() : false;
+    return { supported, enabled };
+  } catch {
+    return { supported: false, enabled: false };
+  }
+}
+
+// ============================================================================
+// Lifecycle
+// ============================================================================
+
+export async function start(
+  templateType: string,
+  attributesJson: string,
+  contentStateJson: string,
+  optionsJson: string,
+): Promise<string> {
+  assertNativeModule();
+
+  try {
+    return await NativeLiveActivity.startActivity(
+      templateType,
+      attributesJson,
+      contentStateJson,
+      optionsJson,
+    );
+  } catch (error) {
+    throw normalizeLiveActivityError(error);
+  }
+}
+
+export async function update(
+  activityId: string,
+  contentStateJson: string,
+  alertConfigJson: string | null,
+): Promise<void> {
+  assertNativeModule();
+
+  try {
+    await NativeLiveActivity.updateActivity(
+      activityId,
+      contentStateJson,
+      alertConfigJson,
+    );
+  } catch (error) {
+    throw normalizeLiveActivityError(error);
+  }
+}
+
+export async function end(
+  activityId: string,
+  finalContentStateJson: string | null,
+  dismissalPolicy: string,
+  dismissAfter: number | null,
+): Promise<void> {
+  assertNativeModule();
+
+  try {
+    await NativeLiveActivity.endActivity(
+      activityId,
+      finalContentStateJson,
+      dismissalPolicy,
+      // TurboModule codegen requires non-optional number — use -1 as sentinel
+      dismissAfter ?? -1,
+    );
+  } catch (error) {
+    throw normalizeLiveActivityError(error);
+  }
+}
+
+export async function endAll(
+  dismissalPolicy: string,
+  dismissAfter: number | null,
+): Promise<void> {
+  assertNativeModule();
+
+  try {
+    await NativeLiveActivity.endAllActivities(
+      dismissalPolicy,
+      dismissAfter ?? -1,
+    );
+  } catch (error) {
+    throw normalizeLiveActivityError(error);
+  }
+}
+
+// ============================================================================
+// Queries
+// ============================================================================
+
+export async function getActivity(
+  activityId: string,
+): Promise<string | null> {
+  assertNativeModule();
+
+  try {
+    return await NativeLiveActivity.getActivity(activityId);
+  } catch {
+    return null;
+  }
+}
+
+export async function listActivities(): Promise<string> {
+  assertNativeModule();
+
+  try {
+    return await NativeLiveActivity.listActivities();
+  } catch {
+    return '[]';
+  }
+}
+
+export async function getPushToken(
+  activityId: string,
+): Promise<string | null> {
+  assertNativeModule();
+
+  try {
+    return await NativeLiveActivity.getPushToken(activityId);
+  } catch {
+    return null;
+  }
+}
+
+// ============================================================================
+// Events
+// ============================================================================
+
+let emitter: NativeEventEmitter | null = null;
+
+function getEmitter(): NativeEventEmitter {
+  if (!emitter) {
+    emitter = new NativeEventEmitter(NativeLiveActivity as any);
+  }
+  return emitter;
+}
+
+export function addEventListener(
+  handler: LiveActivityEventHandler,
+): () => void {
+  if (!NativeLiveActivity) {
+    return () => {};
+  }
+
+  const subscription = getEmitter().addListener(
+    LIVE_ACTIVITY_EVENT,
+    (rawEvent: unknown) => {
+      try {
+        const event =
+          typeof rawEvent === 'string'
+            ? (JSON.parse(rawEvent) as LiveActivityEvent)
+            : (rawEvent as LiveActivityEvent);
+        handler(event);
+      } catch {
+        // Malformed event — ignore
+      }
+    },
+  );
+
+  return () => subscription.remove();
+}

package/src/activity/activity.web.ts

@@ -0,0 +1,78 @@
+// ============================================================================
+// Web Stub Implementation
+// Live Activities are not supported on web — all functions return graceful defaults.
+// ============================================================================
+
+import type {
+  LiveActivityEventHandler,
+  LiveActivityEvent,
+} from '../types';
+import { createLiveActivityError } from '../errors';
+
+const NOT_SUPPORTED_ERROR = createLiveActivityError(
+  'not_supported',
+  'Live Activities are not supported on web',
+);
+
+export async function checkAvailability(): Promise<{
+  supported: boolean;
+  enabled: boolean;
+}> {
+  return { supported: false, enabled: false };
+}
+
+export async function start(
+  _templateType: string,
+  _attributesJson: string,
+  _contentStateJson: string,
+  _optionsJson: string,
+): Promise<string> {
+  throw NOT_SUPPORTED_ERROR;
+}
+
+export async function update(
+  _activityId: string,
+  _contentStateJson: string,
+  _alertConfigJson: string | null,
+): Promise<void> {
+  throw NOT_SUPPORTED_ERROR;
+}
+
+export async function end(
+  _activityId: string,
+  _finalContentStateJson: string | null,
+  _dismissalPolicy: string,
+  _dismissAfter: number | null,
+): Promise<void> {
+  throw NOT_SUPPORTED_ERROR;
+}
+
+export async function endAll(
+  _dismissalPolicy: string,
+  _dismissAfter: number | null,
+): Promise<void> {
+  throw NOT_SUPPORTED_ERROR;
+}
+
+export async function getActivity(
+  _activityId: string,
+): Promise<string | null> {
+  return null;
+}
+
+export async function listActivities(): Promise<string> {
+  return '[]';
+}
+
+export async function getPushToken(
+  _activityId: string,
+): Promise<string | null> {
+  return null;
+}
+
+export function addEventListener(
+  _handler: LiveActivityEventHandler,
+): () => void {
+  // No-op on web
+  return () => {};
+}

package/src/activity/useLiveActivity.ts

@@ -0,0 +1,267 @@
+import { useState, useCallback, useEffect, useRef } from 'react';
+import type {
+  UseLiveActivityOptions,
+  UseLiveActivityResult,
+  LiveActivityInfo,
+  LiveActivityError,
+  LiveActivityToken,
+  LiveActivityDeps,
+  StartActivityOptions,
+  UpdateActivityOptions,
+  EndActivityOptions,
+  TemplateType,
+} from '../types';
+import { normalizeLiveActivityError } from '../errors';
+
+/**
+ * Factory that creates a useLiveActivity hook bound to platform-specific functions.
+ * Each platform entry point calls this with the correct implementations.
+ */
+export function createUseLiveActivityHook(fns: LiveActivityDeps) {
+  return function useLiveActivity(
+    options: UseLiveActivityOptions = {},
+  ): UseLiveActivityResult {
+    const { autoCheckAvailability = false, onEvent } = options;
+
+    const [isSupported, setIsSupported] = useState(false);
+    const [isEnabled, setIsEnabled] = useState<boolean | null>(null);
+    const [activities, setActivities] = useState<LiveActivityInfo[]>([]);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState<LiveActivityError | null>(null);
+    const mountedRef = useRef(true);
+    const initializedRef = useRef(false);
+
+    const currentActivity = activities.length > 0 ? activities[0] : null;
+
+    const checkAvailability = useCallback(async (): Promise<{
+      supported: boolean;
+      enabled: boolean;
+    }> => {
+      try {
+        const result = await fns.checkAvailability();
+        if (mountedRef.current) {
+          setIsSupported(result.supported);
+          setIsEnabled(result.enabled);
+        }
+        return result;
+      } catch (err) {
+        const liveError = normalizeLiveActivityError(err);
+        if (mountedRef.current) setError(liveError);
+        return { supported: false, enabled: false };
+      }
+    }, []);
+
+    const refreshActivities = useCallback(async () => {
+      try {
+        const json = await fns.listActivities();
+        const list: LiveActivityInfo[] = JSON.parse(json);
+        if (mountedRef.current) {
+          setActivities(list);
+        }
+      } catch {
+        // Best-effort refresh
+      }
+    }, []);
+
+    const start = useCallback(
+      async <T extends TemplateType>(
+        opts: StartActivityOptions<T>,
+      ): Promise<LiveActivityInfo> => {
+        setIsLoading(true);
+        setError(null);
+        try {
+          const resultJson = await fns.start(
+            opts.templateType,
+            JSON.stringify(opts.attributes),
+            JSON.stringify(opts.contentState),
+            JSON.stringify({
+              enablePushUpdates: opts.enablePushUpdates,
+              ios: opts.ios,
+              android: opts.android,
+            }),
+          );
+          const info: LiveActivityInfo = JSON.parse(resultJson);
+          if (mountedRef.current) {
+            setActivities((prev) => [info, ...prev]);
+          }
+          return info;
+        } catch (err) {
+          const liveError = normalizeLiveActivityError(err);
+          if (mountedRef.current) setError(liveError);
+          throw liveError;
+        } finally {
+          if (mountedRef.current) setIsLoading(false);
+        }
+      },
+      [],
+    );
+
+    const update = useCallback(
+      async <T extends TemplateType>(
+        activityId: string,
+        opts: UpdateActivityOptions<T>,
+      ): Promise<void> => {
+        setError(null);
+        try {
+          await fns.update(
+            activityId,
+            JSON.stringify(opts.contentState),
+            opts.alert ? JSON.stringify(opts.alert) : null,
+          );
+          await refreshActivities();
+        } catch (err) {
+          const liveError = normalizeLiveActivityError(err);
+          if (mountedRef.current) setError(liveError);
+          throw liveError;
+        }
+      },
+      [refreshActivities],
+    );
+
+    const endActivity = useCallback(
+      async (activityId: string, opts?: EndActivityOptions): Promise<void> => {
+        setError(null);
+        try {
+          await fns.end(
+            activityId,
+            opts?.finalContentState
+              ? JSON.stringify(opts.finalContentState)
+              : null,
+            opts?.dismissalPolicy ?? 'default',
+            opts?.dismissAfter ?? null,
+          );
+          if (mountedRef.current) {
+            setActivities((prev) =>
+              prev.filter((a) => a.id !== activityId),
+            );
+          }
+        } catch (err) {
+          const liveError = normalizeLiveActivityError(err);
+          if (mountedRef.current) setError(liveError);
+          throw liveError;
+        }
+      },
+      [],
+    );
+
+    const endAllActivities = useCallback(
+      async (opts?: EndActivityOptions): Promise<void> => {
+        setError(null);
+        try {
+          await fns.endAll(
+            opts?.dismissalPolicy ?? 'default',
+            opts?.dismissAfter ?? null,
+          );
+          if (mountedRef.current) {
+            setActivities([]);
+          }
+        } catch (err) {
+          const liveError = normalizeLiveActivityError(err);
+          if (mountedRef.current) setError(liveError);
+          throw liveError;
+        }
+      },
+      [],
+    );
+
+    const getActivity = useCallback(
+      async (activityId: string): Promise<LiveActivityInfo | null> => {
+        try {
+          const json = await fns.getActivity(activityId);
+          if (!json) return null;
+          return JSON.parse(json) as LiveActivityInfo;
+        } catch {
+          return null;
+        }
+      },
+      [],
+    );
+
+    const listAllActivities = useCallback(async (): Promise<
+      LiveActivityInfo[]
+    > => {
+      try {
+        const json = await fns.listActivities();
+        const list: LiveActivityInfo[] = JSON.parse(json);
+        if (mountedRef.current) {
+          setActivities(list);
+        }
+        return list;
+      } catch {
+        return [];
+      }
+    }, []);
+
+    const getPushToken = useCallback(
+      async (activityId: string): Promise<LiveActivityToken | null> => {
+        try {
+          const json = await fns.getPushToken(activityId);
+          if (!json) return null;
+          return JSON.parse(json) as LiveActivityToken;
+        } catch {
+          return null;
+        }
+      },
+      [],
+    );
+
+    const clearError = useCallback(() => setError(null), []);
+
+    // Subscribe to native events
+    useEffect(() => {
+      mountedRef.current = true;
+
+      const unsubscribe = fns.addEventListener((event) => {
+        if (!mountedRef.current) return;
+
+        // Update local state based on event
+        if (event.type === 'ended') {
+          setActivities((prev) =>
+            prev.filter((a) => a.id !== event.activityId),
+          );
+        } else if (event.type === 'stale') {
+          setActivities((prev) =>
+            prev.map((a) =>
+              a.id === event.activityId ? { ...a, state: 'stale' } : a,
+            ),
+          );
+        } else if (event.type === 'error' && event.payload?.error) {
+          setError(event.payload.error);
+        }
+
+        // Forward to user's handler
+        onEvent?.(event);
+      });
+
+      // Auto-check availability on mount
+      if (autoCheckAvailability && !initializedRef.current) {
+        initializedRef.current = true;
+        checkAvailability();
+        refreshActivities();
+      }
+
+      return () => {
+        mountedRef.current = false;
+        unsubscribe();
+      };
+    }, [autoCheckAvailability, onEvent, checkAvailability, refreshActivities]);
+
+    return {
+      isSupported,
+      isEnabled,
+      currentActivity,
+      activities,
+      isLoading,
+      error,
+      checkAvailability,
+      start,
+      update,
+      end: endActivity,
+      endAll: endAllActivities,
+      getActivity,
+      listActivities: listAllActivities,
+      getPushToken,
+      clearError,
+    };
+  };
+}

package/src/constants.ts

@@ -0,0 +1,39 @@
+import type { TemplateType } from './types';
+
+// ============================================================================
+// Template Identifiers
+// ============================================================================
+
+/** Mapping of template types to their native identifiers. */
+export const TEMPLATE_IDS: Record<TemplateType, string> = {
+  delivery: 'IdealystDeliveryActivity',
+  timer: 'IdealystTimerActivity',
+  media: 'IdealystMediaActivity',
+  progress: 'IdealystProgressActivity',
+  custom: 'custom',
+};
+
+// ============================================================================
+// Android Notification Defaults
+// ============================================================================
+
+export const DEFAULT_CHANNEL_ID = 'idealyst_live_activity';
+export const DEFAULT_CHANNEL_NAME = 'Live Activities';
+export const DEFAULT_CHANNEL_DESCRIPTION = 'Real-time activity updates';
+export const DEFAULT_SMALL_ICON = 'ic_notification';
+
+// ============================================================================
+// Limits
+// ============================================================================
+
+/** iOS allows a maximum of 5 concurrent Live Activities per app. */
+export const MAX_CONCURRENT_ACTIVITIES_IOS = 5;
+
+/** Android has no hard limit, but we enforce a reasonable default. */
+export const MAX_CONCURRENT_ACTIVITIES_ANDROID = 10;
+
+// ============================================================================
+// Event Names
+// ============================================================================
+
+export const LIVE_ACTIVITY_EVENT = 'IdealystLiveActivityEvent';

package/src/errors.ts

@@ -0,0 +1,57 @@
+import type { LiveActivityError, LiveActivityErrorCode } from './types';
+
+export function createLiveActivityError(
+  code: LiveActivityErrorCode,
+  message: string,
+  originalError?: unknown,
+): LiveActivityError {
+  return { code, message, originalError };
+}
+
+/**
+ * Normalize an unknown error into a LiveActivityError.
+ */
+export function normalizeLiveActivityError(error: unknown): LiveActivityError {
+  if (
+    error &&
+    typeof error === 'object' &&
+    'code' in error &&
+    'message' in error
+  ) {
+    const typed = error as { code?: string; message?: string };
+    const code = isLiveActivityErrorCode(typed.code)
+      ? typed.code
+      : 'unknown';
+    return createLiveActivityError(
+      code,
+      typed.message || 'An unknown Live Activity error occurred',
+      error,
+    );
+  }
+
+  if (error instanceof Error) {
+    return createLiveActivityError('unknown', error.message, error);
+  }
+
+  return createLiveActivityError('unknown', String(error), error);
+}
+
+const VALID_CODES: LiveActivityErrorCode[] = [
+  'not_available',
+  'not_supported',
+  'permission_denied',
+  'start_failed',
+  'update_failed',
+  'end_failed',
+  'activity_not_found',
+  'template_not_found',
+  'invalid_attributes',
+  'too_many_activities',
+  'unknown',
+];
+
+function isLiveActivityErrorCode(
+  value: unknown,
+): value is LiveActivityErrorCode {
+  return typeof value === 'string' && VALID_CODES.includes(value as LiveActivityErrorCode);
+}

package/src/index.native.ts

@@ -0,0 +1,59 @@
+export * from './types';
+export {
+  TEMPLATE_IDS,
+  DEFAULT_CHANNEL_ID,
+  DEFAULT_CHANNEL_NAME,
+  DEFAULT_CHANNEL_DESCRIPTION,
+  DEFAULT_SMALL_ICON,
+  MAX_CONCURRENT_ACTIVITIES_IOS,
+  MAX_CONCURRENT_ACTIVITIES_ANDROID,
+  LIVE_ACTIVITY_EVENT,
+} from './constants';
+export { createLiveActivityError, normalizeLiveActivityError } from './errors';
+
+// Template presets
+export {
+  deliveryActivity,
+  timerActivity,
+  mediaActivity,
+  progressActivity,
+} from './templates/presets';
+
+// Activity functions — native implementations
+export {
+  checkAvailability,
+  start,
+  update,
+  end,
+  endAll,
+  getActivity,
+  listActivities,
+  getPushToken,
+  addEventListener,
+} from './activity/activity.native';
+
+// Hook — bound to native implementations
+import { createUseLiveActivityHook } from './activity/useLiveActivity';
+import {
+  checkAvailability,
+  start,
+  update,
+  end,
+  endAll,
+  getActivity,
+  listActivities,
+  getPushToken,
+  addEventListener,
+} from './activity/activity.native';
+
+export const useLiveActivity = createUseLiveActivityHook({
+  checkAvailability,
+  start,
+  update,
+  end,
+  endAll,
+  getActivity,
+  listActivities,
+  getPushToken,
+  addEventListener,
+});