@hifilabs/pixel 0.2.0 → 0.3.0

package/dist/index.esm.d.ts

@@ -1,6 +1,110 @@
+/**
+ * BALANCE Pixel - TypeScript Type Definitions
+ * @hifilabs/pixel
+ */
+
+import * as React from 'react';
+
+// ============================================
+// Core Types
+// ============================================
+
+/**
+ * Consent preferences structure
+ */
+export interface ConsentPreferences {
+  analytics: boolean;
+  marketing: boolean;
+  personalization: boolean;
+  timestamp: string;
+  ip_address?: string;
+  user_agent?: string;
+}
+
+/**
+ * Attribution data from URL parameters
+ */
+export interface Attribution {
+  utm_source?: string;
+  utm_medium?: string;
+  utm_campaign?: string;
+  utm_content?: string;
+  utm_term?: string;
+  referrer?: string;
+  landing_page?: string;
+  [key: string]: string | undefined;
+}
+
+// ============================================
+// Balance Provider & Context
+// ============================================
+
+/**
+ * Balance Context Value - all methods and state
+ */
+export interface BalanceContextValue {
+  track: (event: string, properties?: Record<string, unknown>) => void;
+  identify: (email: string, traits?: Record<string, unknown>) => void;
+  page: (options?: { title?: string; url?: string }) => void;
+  purchase: (amount: number, currency?: string, properties?: Record<string, unknown>) => void;
+  getSessionId: () => string | null;
+  getFanIdHash: () => string | null;
+  getAttribution: () => Attribution;
+  setConsent: (preferences: ConsentPreferences) => void;
+  getConsent: () => ConsentPreferences | null;
+  hasConsent: (type: 'analytics' | 'marketing' | 'personalization') => boolean;
+  isReady: boolean;
+  artistId: string;
+  projectId?: string;
+  endpoint?: string;
+  debug: boolean;
+}
+
+/**
+ * Balance Provider Props
+ */
+export interface BalanceProviderProps {
+  artistId: string;
+  projectId?: string;
+  debug?: boolean;
+  scriptUrl?: string;
+  endpoint?: string;
+  gtmId?: string;
+  useEmulator?: boolean;
+  children: React.ReactNode;
+}
+
+export declare const BalanceContext: React.Context<BalanceContextValue>;
+export declare function BalanceProvider(props: BalanceProviderProps): JSX.Element;
+
+// ============================================
+// Primary Hooks
+// ============================================
+
+export declare function useBalance(): BalanceContextValue;
+export declare function useBalanceOptional(): BalanceContextValue | null;
+export declare function useBalanceReady(): boolean;
+
+export interface UseBalanceConsentReturn {
+  consent: ConsentPreferences | null;
+  setConsent: (preferences: ConsentPreferences) => void;
+  hasConsent: (type: 'analytics' | 'marketing' | 'personalization') => boolean;
+  acceptAll: () => void;
+  declineAll: () => void;
+}
+
+export declare function useBalanceConsent(): UseBalanceConsentReturn;
+
+// ============================================
+// Components
+// ============================================
+
 export declare function BalanceAnalytics(): null;
 
-// SSR-safe wrapper function type declarations
+// ============================================
+// SSR-safe Wrapper Functions
+// ============================================
+
 export declare const track: (eventName: string, properties?: Record<string, any>) => void;
 export declare const identify: (email: string, traits?: Record<string, any>) => Promise<void>;
 export declare const page: (options?: { title?: string; url?: string }) => void;
@@ -8,18 +112,14 @@ export declare const purchase: (revenue: number, currency?: string, properties?:
 export declare const getSessionId: () => string | null;
 export declare const getFanIdHash: () => string | null;
 export declare const getAttribution: () => Record<string, string>;
-export declare const setConsent: (preferences: {
-  analytics: boolean;
-  marketing: boolean;
-  personalization: boolean;
-  timestamp: string;
-  ip_address?: string;
-  user_agent?: string;
-}) => void;
-export declare const getConsent: () => any;
+export declare const setConsent: (preferences: ConsentPreferences) => void;
+export declare const getConsent: () => ConsentPreferences | null;
 export declare const hasConsent: (type: 'analytics' | 'marketing' | 'personalization') => boolean;
 
-// GTM Integration Types
+// ============================================
+// GTM Integration
+// ============================================
+
 export type GTMConsentState = 'granted' | 'denied';
 
 export interface GTMConsentConfig {
@@ -31,7 +131,6 @@ export interface GTMConsentConfig {
 
 export declare const DEFAULT_GTM_CONSENT: GTMConsentConfig;
 
-// GTMProvider Component
 export interface GTMProviderProps {
   gtmId?: string;
   children: React.ReactNode;
@@ -40,10 +139,10 @@ export interface GTMProviderProps {
 
 export declare function GTMProvider(props: GTMProviderProps): JSX.Element;
 
-// useGTMConsent Hook
 export interface UseGTMConsentOptions {
   pollInterval?: number;
   debug?: boolean;
+  enabled?: boolean;
 }
 
 export declare function useGTMConsent(options?: UseGTMConsentOptions): {
@@ -51,23 +150,19 @@ export declare function useGTMConsent(options?: UseGTMConsentOptions): {
   getConsentConfig: () => GTMConsentConfig;
 };
 
-// useBalanceIdentify hook - consent-aware identify wrapper
+// ============================================
+// useBalanceIdentify Hook
+// ============================================
+
 export declare function useBalanceIdentify(): {
-  /**
-   * Identify a user with BALANCE pixel.
-   * Handles consent checks, queuing, and storage tier automatically.
-   * @param email - User's email address
-   * @param traits - Optional additional user traits
-   * @returns true if identify was called immediately, false if queued or blocked
-   */
   identify: (email: string, traits?: Record<string, unknown>) => boolean;
-  /**
-   * Check if analytics consent is currently granted
-   */
   hasAnalyticsConsent: () => boolean;
 };
 
-// Storage types
+// ============================================
+// Storage Manager
+// ============================================
+
 export type StorageTier = 'session' | 'local';
 
 export interface StorageConfig {
@@ -75,7 +170,6 @@ export interface StorageConfig {
   tier: StorageTier;
 }
 
-// StorageManager class for tiered storage
 export declare class StorageManager {
   constructor(config?: Partial<StorageConfig>);
   getTier(): StorageTier;
@@ -90,3 +184,395 @@ export declare class StorageManager {
 
 export declare function getStorageManager(): StorageManager;
 export declare function initStorageWithConsent(hasAnalyticsConsent: boolean): StorageManager;
+
+// ============================================
+// useBalanceEcommerce Hook
+// ============================================
+
+export interface EcommerceProduct {
+  id: string;
+  name: string;
+  price: number;
+  currency?: string;
+  category?: string;
+  variant?: string;
+  quantity?: number;
+  brand?: string;
+}
+
+export interface CartItem extends EcommerceProduct {
+  quantity: number;
+}
+
+export interface UseBalanceEcommerceReturn {
+  viewProduct: (product: EcommerceProduct, listName?: string, position?: number) => void;
+  addToCart: (product: CartItem, cartTotal?: number) => void;
+  removeFromCart: (product: CartItem, cartTotal?: number) => void;
+  updateCart: (items: CartItem[], cartTotal: number) => void;
+  viewCart: (items: CartItem[], cartTotal: number) => void;
+  beginCheckout: (items: CartItem[], cartTotal: number, couponCode?: string) => void;
+  addPaymentInfo: (paymentMethod: string, cartTotal: number) => void;
+  addShippingInfo: (shippingMethod: string, cartTotal: number) => void;
+  completePurchase: (orderId: string, items: CartItem[], revenue: number, currency?: string, tax?: number, shipping?: number) => void;
+  refund: (orderId: string, amount: number, reason?: string) => void;
+  applyCoupon: (couponCode: string, discountAmount?: number) => void;
+  removeCoupon: (couponCode: string) => void;
+  getStats: () => { productsViewed: number; cartActions: number; checkoutsStarted: number; purchasesCompleted: number; totalRevenue: number };
+  reset: () => void;
+}
+
+export declare function useBalanceEcommerce(): UseBalanceEcommerceReturn;
+
+// ============================================
+// useBalanceMedia Hook
+// ============================================
+
+export interface MediaItem {
+  id: string;
+  title: string;
+  artist?: string;
+  album?: string;
+  genre?: string;
+  duration?: number;
+  type?: 'audio' | 'video';
+}
+
+export interface UseBalanceMediaReturn {
+  play: (item: MediaItem, position?: number) => void;
+  pause: (mediaId: string, position: number) => void;
+  resume: (mediaId: string, position: number) => void;
+  stop: (mediaId: string, position: number, completed?: boolean) => void;
+  seek: (mediaId: string, fromPosition: number, toPosition: number) => void;
+  progress: (mediaId: string, position: number, duration: number) => void;
+  complete: (mediaId: string) => void;
+  skip: (mediaId: string, position: number, direction: 'forward' | 'backward') => void;
+  rateChange: (mediaId: string, rate: number) => void;
+  volumeChange: (mediaId: string, volume: number, muted: boolean) => void;
+  qualityChange: (mediaId: string, quality: string) => void;
+  error: (mediaId: string, errorCode: string, errorMessage?: string) => void;
+  getStats: () => { totalPlays: number; totalListenTime: number; completions: number; currentMediaId: string | null };
+  reset: () => void;
+}
+
+export declare function useBalanceMedia(): UseBalanceMediaReturn;
+
+// ============================================
+// useBalanceEngagement Hook
+// ============================================
+
+export interface UseBalanceEngagementReturn {
+  share: (platform: string, contentType?: string) => void;
+  like: (contentType?: string) => void;
+  unlike: (contentType?: string) => void;
+  comment: (commentLength: number) => void;
+  save: (contentType?: string) => void;
+  trackScrollDepth: (scrollPercent: number) => void;
+  trackTimeOnPage: () => void;
+  getTimeOnPage: () => number;
+  click: (elementType: string, elementId?: string) => void;
+  copy: (textLength: number) => void;
+  download: (fileName: string, fileType: string) => void;
+  expand: (sectionName: string) => void;
+  reset: () => void;
+}
+
+export declare function useBalanceEngagement(contentId: string, contentTitle?: string): UseBalanceEngagementReturn;
+
+// ============================================
+// useBalanceForm Hook
+// ============================================
+
+export interface UseBalanceFormReturn {
+  startForm: () => void;
+  fieldFocus: (fieldName: string, fieldType?: string) => void;
+  fieldBlur: (fieldName: string, hasValue: boolean, isValid?: boolean) => void;
+  fieldChange: (fieldName: string, hasValue: boolean) => void;
+  fieldError: (fieldName: string, errorMessage: string) => void;
+  stepChange: (stepNumber: number, stepName?: string) => void;
+  submit: (success: boolean, errorMessage?: string) => void;
+  abandon: (lastFieldInteracted?: string) => void;
+  getStats: () => { fieldsInteracted: number; errorsEncountered: number; timeSpentSeconds: number; currentStep: number };
+  reset: () => void;
+}
+
+export declare function useBalanceForm(formId: string, formName?: string): UseBalanceFormReturn;
+
+// ============================================
+// useBalanceSearch Hook
+// ============================================
+
+export interface SearchResult {
+  id: string;
+  title: string;
+  type?: string;
+  position?: number;
+}
+
+export interface SearchFilter {
+  name: string;
+  value: string | number | boolean;
+}
+
+export interface UseBalanceSearchReturn {
+  search: (query: string, filters?: SearchFilter[]) => void;
+  searchResults: (query: string, resultCount: number, results?: SearchResult[]) => void;
+  searchNoResults: (query: string, filters?: SearchFilter[]) => void;
+  resultClick: (query: string, result: SearchResult) => void;
+  filterApply: (filterName: string, filterValue: string | number | boolean) => void;
+  filterRemove: (filterName: string) => void;
+  sortChange: (sortField: string, sortDirection: 'asc' | 'desc') => void;
+  pagination: (page: number, pageSize: number, totalResults: number) => void;
+  autocomplete: (partialQuery: string, suggestions: string[]) => void;
+  suggestionClick: (suggestion: string, position: number) => void;
+  searchRefine: (originalQuery: string, refinedQuery: string) => void;
+  getStats: () => { searches: number; resultsClicked: number; noResultSearches: number; avgResultsPerSearch: number };
+  reset: () => void;
+}
+
+export declare function useBalanceSearch(): UseBalanceSearchReturn;
+
+// ============================================
+// useBalanceNotification Hook
+// ============================================
+
+export type NotificationChannel = 'push' | 'email' | 'sms' | 'in_app' | 'web_push';
+
+export interface NotificationPreference {
+  channel: NotificationChannel;
+  enabled: boolean;
+  frequency?: 'instant' | 'daily' | 'weekly';
+}
+
+export interface UseBalanceNotificationReturn {
+  permissionRequest: (channel: NotificationChannel) => void;
+  permissionGranted: (channel: NotificationChannel) => void;
+  permissionDenied: (channel: NotificationChannel, reason?: string) => void;
+  delivered: (notificationId: string, channel: NotificationChannel, campaignId?: string) => void;
+  opened: (notificationId: string, channel: NotificationChannel, campaignId?: string) => void;
+  clicked: (notificationId: string, channel: NotificationChannel, actionId?: string) => void;
+  dismissed: (notificationId: string, channel: NotificationChannel) => void;
+  preferencesUpdated: (preferences: NotificationPreference[]) => void;
+  unsubscribe: (channel: NotificationChannel, reason?: string) => void;
+  tokenRefresh: (channel: NotificationChannel, tokenType?: string) => void;
+  getStats: () => { delivered: number; opened: number; clicked: number; dismissed: number; openRate: number };
+  reset: () => void;
+}
+
+export declare function useBalanceNotification(): UseBalanceNotificationReturn;
+
+// ============================================
+// useBalanceSocial Hook
+// ============================================
+
+export type SocialEntityType = 'user' | 'artist' | 'playlist' | 'album' | 'post' | 'comment' | 'group' | 'event';
+export type SocialActionType = 'follow' | 'unfollow' | 'block' | 'mute' | 'report';
+
+export interface UseBalanceSocialReturn {
+  follow: (entityId: string, entityType: SocialEntityType, entityName?: string) => void;
+  unfollow: (entityId: string, entityType: SocialEntityType, reason?: string) => void;
+  block: (userId: string, reason?: string) => void;
+  unblock: (userId: string) => void;
+  mute: (entityId: string, entityType: SocialEntityType, duration?: number) => void;
+  unmute: (entityId: string, entityType: SocialEntityType) => void;
+  report: (entityId: string, entityType: SocialEntityType, reason: string, details?: string) => void;
+  share: (contentId: string, contentType: string, platform: string, method?: 'link' | 'embed' | 'native') => void;
+  invite: (method: 'email' | 'sms' | 'link' | 'social', recipientCount?: number) => void;
+  inviteAccepted: (inviteId: string, inviterId?: string) => void;
+  mention: (mentionedUserId: string, context: 'post' | 'comment' | 'message') => void;
+  tag: (taggedUserId: string, contentId: string, contentType: string) => void;
+  reaction: (contentId: string, contentType: string, reactionType: string) => void;
+  removeReaction: (contentId: string, contentType: string, reactionType: string) => void;
+  joinGroup: (groupId: string, groupName?: string, isPrivate?: boolean) => void;
+  leaveGroup: (groupId: string, reason?: string) => void;
+  createGroup: (groupId: string, groupName: string, isPrivate?: boolean) => void;
+  directMessage: (recipientId: string, hasMedia?: boolean) => void;
+  getStats: () => { follows: number; unfollows: number; shares: number; reactions: number; messages: number };
+  reset: () => void;
+}
+
+export declare function useBalanceSocial(): UseBalanceSocialReturn;
+
+// ============================================
+// useBalanceAuth Hook
+// ============================================
+
+export type AuthMethod = 'email' | 'password' | 'magic_link' | 'oauth_google' | 'oauth_apple' | 'oauth_facebook' | 'oauth_twitter' | 'oauth_spotify' | 'passkey' | 'biometric' | 'sms' | 'totp';
+
+export interface UseBalanceAuthReturn {
+  loginStart: (method: AuthMethod) => void;
+  loginSuccess: (method: AuthMethod, isNewUser?: boolean, userId?: string) => void;
+  loginFailure: (method: AuthMethod, errorCode: string, errorMessage?: string) => void;
+  signupStart: (method: AuthMethod, source?: string) => void;
+  signupSuccess: (method: AuthMethod, userId?: string) => void;
+  signupFailure: (method: AuthMethod, errorCode: string, errorMessage?: string) => void;
+  logout: (reason?: 'user' | 'session_expired' | 'forced' | 'security') => void;
+  passwordResetRequest: (method: 'email' | 'sms') => void;
+  passwordResetComplete: (success: boolean) => void;
+  mfaChallenge: (method: 'sms' | 'totp' | 'email' | 'passkey') => void;
+  mfaSuccess: (method: 'sms' | 'totp' | 'email' | 'passkey') => void;
+  mfaFailure: (method: 'sms' | 'totp' | 'email' | 'passkey', reason?: string) => void;
+  mfaEnroll: (method: 'sms' | 'totp' | 'passkey') => void;
+  sessionRefresh: (success: boolean) => void;
+  accountLink: (provider: AuthMethod, success: boolean) => void;
+  accountUnlink: (provider: AuthMethod) => void;
+  profileUpdate: (fieldsUpdated: string[]) => void;
+  accountDelete: (reason?: string) => void;
+  getStats: () => { logins: number; signups: number; failures: number; mfaChallenges: number };
+  reset: () => void;
+}
+
+export declare function useBalanceAuth(): UseBalanceAuthReturn;
+
+// ============================================
+// useBalanceError Hook
+// ============================================
+
+export type ErrorSeverity = 'debug' | 'info' | 'warning' | 'error' | 'critical';
+
+export type PerformanceMetricType =
+  | 'page_load'
+  | 'api_response'
+  | 'component_render'
+  | 'interaction'
+  | 'resource_load'
+  | 'long_task'
+  | 'first_paint'
+  | 'first_contentful_paint'
+  | 'largest_contentful_paint'
+  | 'first_input_delay'
+  | 'cumulative_layout_shift'
+  | 'time_to_interactive';
+
+export interface ApiErrorDetails {
+  statusCode?: number;
+  url: string;
+  method?: string;
+  responseBody?: string;
+  durationMs?: number;
+}
+
+export interface UseBalanceErrorReturn {
+  captureError: (error: Error, context?: Record<string, unknown>, severity?: ErrorSeverity) => void;
+  captureApiError: (details: ApiErrorDetails, context?: Record<string, unknown>) => void;
+  captureUserReport: (category: string, description: string, metadata?: Record<string, unknown>) => void;
+  trackPerformance: (metricType: PerformanceMetricType, valueMs: number, context?: Record<string, unknown>) => void;
+  trackWebVitals: (vitals: { lcp?: number; fid?: number; cls?: number; fcp?: number; ttfb?: number }) => void;
+  captureComponentError: (error: Error, componentName: string, componentStack?: string) => void;
+  captureUnhandledRejection: (reason: unknown, promiseInfo?: string) => void;
+  captureResourceError: (resourceUrl: string, resourceType: 'script' | 'stylesheet' | 'image' | 'font' | 'other', details?: Record<string, unknown>) => void;
+  trackSlowInteraction: (interactionType: string, durationMs: number, targetElement?: string) => void;
+  startMeasure: (measureName: string) => void;
+  endMeasure: (measureName: string, metricType?: PerformanceMetricType) => number | null;
+  getStats: () => { errors: number; apiErrors: number; userReports: number; avgPageLoad: number | null };
+  reset: () => void;
+}
+
+export declare function useBalanceError(): UseBalanceErrorReturn;
+
+// ============================================
+// useBalanceAB Hook
+// ============================================
+
+export type ExperimentVariant = 'control' | 'A' | 'B' | 'C' | 'D' | string;
+export type ExperimentStatus = 'active' | 'paused' | 'completed' | 'draft';
+
+export interface ExperimentConfig {
+  id: string;
+  name: string;
+  variants: ExperimentVariant[];
+  trafficAllocation?: number;
+  audience?: string;
+}
+
+export interface FeatureFlag {
+  key: string;
+  enabled: boolean;
+  variant?: string;
+  source?: string;
+}
+
+export interface UseBalanceABReturn {
+  trackExposure: (experimentId: string, variant: ExperimentVariant, context?: Record<string, unknown>) => void;
+  trackConversion: (experimentId: string, variant: ExperimentVariant, conversionData?: Record<string, unknown>) => void;
+  trackInteraction: (experimentId: string, variant: ExperimentVariant, interactionType: string, details?: Record<string, unknown>) => void;
+  enrollUser: (experimentId: string, variant: ExperimentVariant, source?: 'random' | 'targeted' | 'override') => void;
+  exitExperiment: (experimentId: string, reason?: 'completed' | 'abandoned' | 'error' | 'excluded') => void;
+  trackFeatureFlag: (flag: FeatureFlag) => void;
+  trackFeatureFlagToggle: (flagKey: string, newValue: boolean, previousValue: boolean) => void;
+  trackGoal: (experimentId: string, goalName: string, value?: number, context?: Record<string, unknown>) => void;
+  trackSegment: (segmentId: string, segmentName: string, criteria?: Record<string, unknown>) => void;
+  getVariant: (experimentId: string) => ExperimentVariant | null;
+  setVariant: (experimentId: string, variant: ExperimentVariant) => void;
+  getActiveExperiments: () => Map<string, ExperimentVariant>;
+  getStats: () => { exposures: number; conversions: number; activeExperiments: number; conversionRate: number };
+  reset: () => void;
+}
+
+export declare function useBalanceAB(): UseBalanceABReturn;
+
+// ============================================
+// useBalanceLive Hook
+// ============================================
+
+export type StreamType = 'video' | 'audio' | 'hybrid' | 'podcast' | 'radio';
+export type StreamQuality = 'auto' | '360p' | '480p' | '720p' | '1080p' | '4k' | 'audio_only';
+export type ViewerInteraction = 'chat' | 'reaction' | 'tip' | 'share' | 'follow' | 'subscribe' | 'gift' | 'poll_vote' | 'question';
+
+export interface UseBalanceLiveReturn {
+  joinStream: (streamId: string, streamTitle: string, artistId?: string, metadata?: Record<string, unknown>) => void;
+  leaveStream: (streamId: string, reason?: 'user' | 'ended' | 'error' | 'network') => void;
+  playbackStarted: (streamId: string, quality?: StreamQuality, latencyMs?: number) => void;
+  buffering: (streamId: string, durationMs: number, reason?: string) => void;
+  qualityChanged: (streamId: string, previousQuality: StreamQuality, newQuality: StreamQuality, isAutomatic: boolean) => void;
+  sendChat: (streamId: string, messageLength: number, hasEmoji?: boolean) => void;
+  react: (streamId: string, reactionType: string) => void;
+  tip: (streamId: string, amount: number, currency: string, message?: string) => void;
+  gift: (streamId: string, giftType: string, recipientId?: string, value?: number) => void;
+  pollVote: (streamId: string, pollId: string, optionId: string) => void;
+  submitQuestion: (streamId: string, questionId: string, isAnonymous?: boolean) => void;
+  share: (streamId: string, platform: string) => void;
+  captureClip: (streamId: string, clipDurationSeconds: number) => void;
+  toggleFullscreen: (streamId: string, isFullscreen: boolean) => void;
+  togglePiP: (streamId: string, isPiP: boolean) => void;
+  volumeChanged: (streamId: string, volume: number, isMuted: boolean) => void;
+  streamError: (streamId: string, errorCode: string, errorMessage?: string) => void;
+  viewerMilestone: (streamId: string, minutesWatched: number) => void;
+  getStats: () => { totalWatchTimeSeconds: number; messagesent: number; reactions: number; tips: number; currentStreamId: string | null };
+  reset: () => void;
+}
+
+export declare function useBalanceLive(): UseBalanceLiveReturn;
+
+// ============================================
+// useBalanceSubscription Hook
+// ============================================
+
+export type BillingInterval = 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly' | 'lifetime';
+export type SubscriptionStatus = 'active' | 'trialing' | 'past_due' | 'paused' | 'canceled' | 'expired';
+export type PaymentMethod = 'card' | 'paypal' | 'apple_pay' | 'google_pay' | 'bank_transfer' | 'crypto' | 'carrier_billing';
+export type CancellationReason = 'too_expensive' | 'not_using' | 'missing_features' | 'found_alternative' | 'technical_issues' | 'other';
+
+export interface UseBalanceSubscriptionReturn {
+  subscribe: (planId: string, planName: string, price: number, currency: string, interval: BillingInterval, paymentMethod?: PaymentMethod, trialDays?: number) => void;
+  startTrial: (planId: string, planName: string, trialDays: number, requiredPaymentMethod?: boolean) => void;
+  trialConverted: (planId: string, price: number, currency: string) => void;
+  trialExpired: (planId: string, converted: boolean) => void;
+  upgrade: (fromPlanId: string, toPlanId: string, priceDifference: number, currency: string, immediate?: boolean) => void;
+  downgrade: (fromPlanId: string, toPlanId: string, priceDifference: number, effectiveDate?: string) => void;
+  cancel: (planId: string, reason?: CancellationReason, feedback?: string, immediate?: boolean) => void;
+  pause: (planId: string, pauseDurationDays?: number, reason?: string) => void;
+  resume: (planId: string, pausedDays?: number) => void;
+  renewal: (planId: string, price: number, currency: string, success: boolean, failureReason?: string) => void;
+  paymentFailed: (planId: string, amount: number, currency: string, errorCode: string, retryCount?: number) => void;
+  paymentMethodUpdate: (planId: string, method: PaymentMethod, success: boolean) => void;
+  priceChange: (planId: string, oldPrice: number, newPrice: number, currency: string, effectiveDate: string) => void;
+  featureUsage: (planId: string, featureName: string, usageCount?: number, usageLimit?: number) => void;
+  usageLimitReached: (planId: string, featureName: string, limit: number) => void;
+  upsellShown: (currentPlanId: string, suggestedPlanId: string, trigger: string) => void;
+  upsellClicked: (currentPlanId: string, suggestedPlanId: string) => void;
+  upsellConverted: (fromPlanId: string, toPlanId: string, price: number, currency: string) => void;
+  getStats: () => { subscriptions: number; trials: number; upgrades: number; cancellations: number; totalRevenue: number };
+  reset: () => void;
+}
+
+export declare function useBalanceSubscription(): UseBalanceSubscriptionReturn;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hifilabs/pixel",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "BALANCE Pixel - Lightweight browser tracking script for artist fan analytics",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",