@idealyst/live-activity 1.2.114

package/src/index.ts

@@ -0,0 +1,61 @@
+// Default entry — re-exports web implementation.
+// Platform-specific entry points (index.native.ts, index.web.ts) are resolved by bundlers.
+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 — web stubs
+export {
+  checkAvailability,
+  start,
+  update,
+  end,
+  endAll,
+  getActivity,
+  listActivities,
+  getPushToken,
+  addEventListener,
+} from './activity/activity.web';
+
+// Hook — bound to web implementations
+import { createUseLiveActivityHook } from './activity/useLiveActivity';
+import {
+  checkAvailability,
+  start,
+  update,
+  end,
+  endAll,
+  getActivity,
+  listActivities,
+  getPushToken,
+  addEventListener,
+} from './activity/activity.web';
+
+export const useLiveActivity = createUseLiveActivityHook({
+  checkAvailability,
+  start,
+  update,
+  end,
+  endAll,
+  getActivity,
+  listActivities,
+  getPushToken,
+  addEventListener,
+});

package/src/index.web.ts

@@ -0,0 +1,2 @@
+// Web entry — identical to index.ts.
+export * from './index';

package/src/templates/presets.ts

@@ -0,0 +1,91 @@
+import type {
+  StartActivityOptions,
+  DeliveryAttributes,
+  DeliveryContentState,
+  TimerAttributes,
+  TimerContentState,
+  MediaAttributes,
+  MediaContentState,
+  ProgressAttributes,
+  ProgressContentState,
+} from '../types';
+
+/**
+ * Create a delivery/rideshare Live Activity with sensible defaults.
+ */
+export function deliveryActivity(
+  attributes: DeliveryAttributes,
+  contentState: DeliveryContentState,
+  options?: Partial<Omit<StartActivityOptions<'delivery'>, 'templateType' | 'attributes' | 'contentState'>>,
+): StartActivityOptions<'delivery'> {
+  return {
+    templateType: 'delivery',
+    attributes: {
+      accentColor: '#FF5722',
+      ...attributes,
+    },
+    contentState: {
+      ...contentState,
+      progress: contentState.progress ?? 0,
+    },
+    ...options,
+  };
+}
+
+/**
+ * Create a timer/countdown Live Activity with sensible defaults.
+ */
+export function timerActivity(
+  attributes: TimerAttributes,
+  contentState: TimerContentState,
+  options?: Partial<Omit<StartActivityOptions<'timer'>, 'templateType' | 'attributes' | 'contentState'>>,
+): StartActivityOptions<'timer'> {
+  return {
+    templateType: 'timer',
+    attributes: {
+      showElapsed: false,
+      ...attributes,
+    },
+    contentState,
+    ...options,
+  };
+}
+
+/**
+ * Create a media playback Live Activity with sensible defaults.
+ */
+export function mediaActivity(
+  attributes: MediaAttributes,
+  contentState: MediaContentState,
+  options?: Partial<Omit<StartActivityOptions<'media'>, 'templateType' | 'attributes' | 'contentState'>>,
+): StartActivityOptions<'media'> {
+  return {
+    templateType: 'media',
+    attributes,
+    contentState: {
+      ...contentState,
+      isPlaying: contentState.isPlaying ?? false,
+    },
+    ...options,
+  };
+}
+
+/**
+ * Create a generic progress Live Activity with sensible defaults.
+ */
+export function progressActivity(
+  attributes: ProgressAttributes,
+  contentState: ProgressContentState,
+  options?: Partial<Omit<StartActivityOptions<'progress'>, 'templateType' | 'attributes' | 'contentState'>>,
+): StartActivityOptions<'progress'> {
+  return {
+    templateType: 'progress',
+    attributes,
+    contentState: {
+      ...contentState,
+      progress: contentState.progress ?? 0,
+      indeterminate: contentState.indeterminate ?? false,
+    },
+    ...options,
+  };
+}

package/src/templates/types.ts

@@ -0,0 +1,14 @@
+// Re-export template-specific types for convenience.
+export type {
+  TemplateType,
+  DeliveryAttributes,
+  DeliveryContentState,
+  TimerAttributes,
+  TimerContentState,
+  MediaAttributes,
+  MediaContentState,
+  ProgressAttributes,
+  ProgressContentState,
+  TemplateAttributesMap,
+  TemplateContentStateMap,
+} from '../types';

package/src/types.ts

@@ -0,0 +1,343 @@
+// ============================================================================
+// Core Types
+// ============================================================================
+
+export type LiveActivityState =
+  | 'idle'
+  | 'starting'
+  | 'active'
+  | 'updating'
+  | 'ending'
+  | 'ended'
+  | 'stale';
+
+export type LiveActivityDismissalPolicy =
+  | 'immediate'
+  | 'default'
+  | 'afterDate';
+
+export interface LiveActivityToken {
+  /** The push token for remote updates (base64 string). */
+  token: string;
+  /** Platform: 'ios' (APNs) or 'android' (FCM). */
+  platform: 'ios' | 'android';
+  /** Activity ID this token is associated with. */
+  activityId: string;
+}
+
+export interface LiveActivityInfo {
+  /** Unique activity identifier. */
+  id: string;
+  /** Current state. */
+  state: LiveActivityState;
+  /** Push token for remote updates (if available). */
+  pushToken?: LiveActivityToken;
+  /** Timestamp when activity was started (ms since epoch). */
+  startedAt: number;
+  /** Template type used. */
+  templateType: TemplateType;
+  /** Static attributes. */
+  attributes: Record<string, unknown>;
+  /** Current content state. */
+  contentState: Record<string, unknown>;
+}
+
+// ============================================================================
+// Template Types
+// ============================================================================
+
+export type TemplateType =
+  | 'delivery'
+  | 'timer'
+  | 'media'
+  | 'progress'
+  | 'custom';
+
+export interface DeliveryAttributes {
+  /** Starting point label. */
+  startLabel: string;
+  /** Ending point label. */
+  endLabel: string;
+  /** Icon name or asset URI. */
+  icon?: string;
+  /** Accent color (hex). */
+  accentColor?: string;
+}
+
+export interface DeliveryContentState {
+  /** Progress value 0-1. */
+  progress: number;
+  /** Current status text. */
+  status: string;
+  /** ETA timestamp (ms since epoch). */
+  eta?: number;
+  /** Driver/courier name. */
+  driverName?: string;
+  /** Additional info line. */
+  subtitle?: string;
+}
+
+export interface TimerAttributes {
+  /** Activity title. */
+  title: string;
+  /** Icon name or asset URI. */
+  icon?: string;
+  /** Accent color (hex). */
+  accentColor?: string;
+  /** Whether to show elapsed time instead of countdown. */
+  showElapsed?: boolean;
+}
+
+export interface TimerContentState {
+  /** Target end time (ms since epoch). */
+  endTime: number;
+  /** Whether timer is paused. */
+  isPaused?: boolean;
+  /** Subtitle text. */
+  subtitle?: string;
+}
+
+export interface MediaAttributes {
+  /** Album or playlist title. */
+  title: string;
+  /** Album art URI. */
+  artworkUri?: string;
+  /** Accent color (hex). */
+  accentColor?: string;
+}
+
+export interface MediaContentState {
+  /** Track title. */
+  trackTitle: string;
+  /** Artist name. */
+  artist?: string;
+  /** Is currently playing. */
+  isPlaying: boolean;
+  /** Progress 0-1. */
+  progress?: number;
+  /** Total duration in seconds. */
+  duration?: number;
+  /** Current position in seconds. */
+  position?: number;
+}
+
+export interface ProgressAttributes {
+  /** Activity title. */
+  title: string;
+  /** Icon name or asset URI. */
+  icon?: string;
+  /** Accent color (hex). */
+  accentColor?: string;
+}
+
+export interface ProgressContentState {
+  /** Progress value 0-1. */
+  progress: number;
+  /** Status text. */
+  status: string;
+  /** Subtitle text. */
+  subtitle?: string;
+  /** Whether progress is indeterminate. */
+  indeterminate?: boolean;
+}
+
+/** Maps template type to its static attributes interface. */
+export interface TemplateAttributesMap {
+  delivery: DeliveryAttributes;
+  timer: TimerAttributes;
+  media: MediaAttributes;
+  progress: ProgressAttributes;
+  custom: Record<string, unknown>;
+}
+
+/** Maps template type to its content state interface. */
+export interface TemplateContentStateMap {
+  delivery: DeliveryContentState;
+  timer: TimerContentState;
+  media: MediaContentState;
+  progress: ProgressContentState;
+  custom: Record<string, unknown>;
+}
+
+// ============================================================================
+// Options Types
+// ============================================================================
+
+export interface StartActivityOptions<T extends TemplateType = TemplateType> {
+  /** Template type to use. */
+  templateType: T;
+  /** Static attributes (don't change during activity). */
+  attributes: TemplateAttributesMap[T];
+  /** Initial content state (can be updated). */
+  contentState: TemplateContentStateMap[T];
+  /** Enable push token generation for remote updates. */
+  enablePushUpdates?: boolean;
+  /** iOS-specific options. */
+  ios?: {
+    /** Relevance score 0-100 (affects Dynamic Island priority). */
+    relevanceScore?: number;
+    /** Stale date (ms since epoch) — system marks activity stale after this. */
+    staleDate?: number;
+  };
+  /** Android-specific options. */
+  android?: {
+    /** Notification channel ID. */
+    channelId?: string;
+    /** Notification ID (auto-generated if omitted). */
+    notificationId?: number;
+    /** Small icon resource name. */
+    smallIcon?: string;
+    /** Deep link URL when notification is tapped. */
+    deepLinkUrl?: string;
+  };
+}
+
+export interface UpdateActivityOptions<T extends TemplateType = TemplateType> {
+  /** New content state (partial — merged with existing). */
+  contentState: Partial<TemplateContentStateMap[T]>;
+  /** iOS: alert configuration for this update. */
+  alert?: {
+    title?: string;
+    body?: string;
+    sound?: boolean;
+  };
+}
+
+export interface EndActivityOptions {
+  /** Final content state to display before dismissal. */
+  finalContentState?: Record<string, unknown>;
+  /** Dismissal policy. Default: 'default'. */
+  dismissalPolicy?: LiveActivityDismissalPolicy;
+  /** For 'afterDate' policy: timestamp when to dismiss (ms since epoch). */
+  dismissAfter?: number;
+}
+
+// ============================================================================
+// Event Types
+// ============================================================================
+
+export type LiveActivityEventType =
+  | 'started'
+  | 'updated'
+  | 'ended'
+  | 'tokenUpdated'
+  | 'stale'
+  | 'error';
+
+export interface LiveActivityEvent {
+  /** Event type. */
+  type: LiveActivityEventType;
+  /** Activity this event relates to. */
+  activityId: string;
+  /** Timestamp of the event (ms since epoch). */
+  timestamp: number;
+  /** Event-specific payload. */
+  payload?: {
+    state?: LiveActivityState;
+    token?: LiveActivityToken;
+    error?: LiveActivityError;
+  };
+}
+
+export type LiveActivityEventHandler = (event: LiveActivityEvent) => void;
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+export type 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';
+
+export interface LiveActivityError {
+  code: LiveActivityErrorCode;
+  message: string;
+  originalError?: unknown;
+}
+
+// ============================================================================
+// Hook Types
+// ============================================================================
+
+export interface UseLiveActivityOptions {
+  /** Auto-check availability on mount. */
+  autoCheckAvailability?: boolean;
+  /** Event handler for activity state changes. */
+  onEvent?: LiveActivityEventHandler;
+}
+
+export interface UseLiveActivityResult {
+  /** Whether Live Activities are supported on this device. */
+  isSupported: boolean;
+  /** Whether Live Activities are enabled by the user (iOS settings). */
+  isEnabled: boolean | null;
+  /** Currently active activity info (most recent). */
+  currentActivity: LiveActivityInfo | null;
+  /** All active activities. */
+  activities: LiveActivityInfo[];
+  /** Loading state. */
+  isLoading: boolean;
+  /** Current error. */
+  error: LiveActivityError | null;
+
+  /** Check if Live Activities are available. */
+  checkAvailability: () => Promise<{ supported: boolean; enabled: boolean }>;
+  /** Start a new Live Activity. */
+  start: <T extends TemplateType>(options: StartActivityOptions<T>) => Promise<LiveActivityInfo>;
+  /** Update an existing activity. */
+  update: <T extends TemplateType>(activityId: string, options: UpdateActivityOptions<T>) => Promise<void>;
+  /** End an activity. */
+  end: (activityId: string, options?: EndActivityOptions) => Promise<void>;
+  /** End all activities. */
+  endAll: (options?: EndActivityOptions) => Promise<void>;
+  /** Get activity by ID. */
+  getActivity: (activityId: string) => Promise<LiveActivityInfo | null>;
+  /** List all current activities. */
+  listActivities: () => Promise<LiveActivityInfo[]>;
+  /** Get push token for an activity. */
+  getPushToken: (activityId: string) => Promise<LiveActivityToken | null>;
+  /** Clear error state. */
+  clearError: () => void;
+}
+
+// ============================================================================
+// Internal: Platform Implementation Dependencies
+// ============================================================================
+
+export interface LiveActivityDeps {
+  checkAvailability: () => Promise<{ supported: boolean; enabled: boolean }>;
+  start: (
+    templateType: string,
+    attributesJson: string,
+    contentStateJson: string,
+    optionsJson: string,
+  ) => Promise<string>;
+  update: (
+    activityId: string,
+    contentStateJson: string,
+    alertConfigJson: string | null,
+  ) => Promise<void>;
+  end: (
+    activityId: string,
+    finalContentStateJson: string | null,
+    dismissalPolicy: string,
+    dismissAfter: number | null,
+  ) => Promise<void>;
+  endAll: (
+    dismissalPolicy: string,
+    dismissAfter: number | null,
+  ) => Promise<void>;
+  getActivity: (activityId: string) => Promise<string | null>;
+  listActivities: () => Promise<string>;
+  getPushToken: (activityId: string) => Promise<string | null>;
+  addEventListener: (handler: LiveActivityEventHandler) => () => void;
+}