@billdog.io/react-native 1.0.0-beta.2

package/src/index.ts

@@ -0,0 +1,245 @@
+/**
+ * BillDog React Native Paywalls SDK
+ * 
+ * Usage:
+ * import { PaywallView } from '@billdog.io/react-native';
+ * 
+ * <PaywallView
+ *   paywallIdentifier="premium_offer"
+ *   onButtonPress={(id, action) => console.log('Button pressed', id, action)}
+ * />
+ */
+
+export { PaywallView } from './PaywallView';
+export { ComponentRenderer } from './ComponentRenderer';
+export { PaywallStateManager, paywallStateManager } from './PaywallStateManager';
+export type { StateListener, Unsubscribe } from './PaywallStateManager';
+// Optional WebView-based paywall — alternative to the native PaywallView
+// that loads the unified renderer bundle iOS/Android/Flutter use.
+// Requires react-native-webview peer dep (already listed). See
+// docs/webview-implementation/04-react-native-implementation.md.
+export { WebViewPaywall } from './WebViewPaywall';
+export type { WebViewPaywallProps } from './WebViewPaywall';
+// Option 2 inline path: embeds the NATIVE paywall view via the `BDPaywallView`
+// native component (BillDogPaywallViewManager on iOS/Android).
+export {
+  NativePaywallView,
+  isNativePaywallAvailable,
+} from './NativePaywallView';
+export type { NativePaywallViewProps } from './NativePaywallView';
+export { ProgressLoaderComponent } from './components/ProgressLoaderComponent';
+export { ChartCurveComponent } from './components/ChartCurveComponent';
+export { SingleChoiceGridComponent } from './components/SingleChoiceGridComponent';
+export { MultiChoiceGridComponent } from './components/MultiChoiceGridComponent';
+export { DrawerModalComponent } from './components/DrawerModalComponent';
+export { TimelineComponent } from './components/TimelineComponent';
+export { TextInputComponent } from './components/TextInputComponent';
+export { StarRatingInputComponent } from './components/StarRatingInputComponent';
+export { NPSScaleComponent } from './components/NPSScaleComponent';
+export { OAuthButtonComponent } from './components/OAuthButtonComponent';
+export { ProgressStepperComponent } from './components/ProgressStepperComponent';
+export { ShareCodeComponent } from './components/ShareCodeComponent';
+export { ShareButtonsComponent } from './components/ShareButtonsComponent';
+export { LayoutEngine } from './LayoutEngine';
+export { usePaywall } from './hooks/usePaywall';
+export { useOfferings } from './hooks/useOfferings';
+export { usePlacement } from './hooks/usePlacement';
+
+// Configuration
+export { BillDog } from './BillDog';
+// Custom purchase / PurchaseController surface (PUR-363/364) — the types a host
+// app needs to implement a controller and define non-store products.
+export type { PurchaseController } from './BillDog';
+export type { CustomProduct } from './models/CustomProduct';
+export type { PurchaseResult } from './models/PurchaseResult';
+export type { RestoreResult } from './models/RestoreResult';
+export { BillDogConfiguration, DEFAULT_API_BASE_URL } from './BillDogConfiguration';
+export type { BillDogConfig } from './BillDogConfiguration';
+
+// Export cache classes
+export { PaywallCache } from './PaywallCache';
+export { AdvancedPaywallCache } from './AdvancedPaywallCache';
+
+// Export device detection and configuration resolver
+export { detectDeviceCategory, getDeviceInfo, isTablet } from './utils/deviceDetection';
+export { resolveConfiguration, findNearestConfig } from './utils/configurationResolver';
+
+// Export haptic feedback
+export { triggerHaptic, isHapticAvailable } from './utils/hapticFeedback';
+
+// Export review functionality
+export { 
+  requestReview, 
+  canRequestReview,
+  initializeReviewTiming,
+  recordReviewSession,
+  recordSignificantEvent,
+  shouldRequestReview,
+} from './review/ReviewManager';
+export { ReviewAnalytics } from './review/ReviewAnalytics';
+export type { ReviewAnalyticsEvent } from './review/ReviewAnalytics';
+export { ReviewTimingManager } from './review/ReviewTimingManager';
+export type { ReviewTimingConfig } from './review/ReviewTimingManager';
+
+export type {
+  PaywallComponent,
+  PaywallConfiguration,
+  ComponentType,
+  Layout,
+  Appearance,
+  Size,
+  Position,
+  LayoutType,
+  Product,
+  OfferingPackage,
+} from './types';
+
+// Export Variable and Localization Resolvers
+export { VariableResolver } from './VariableResolver';
+export type { DeviceInfo } from './VariableResolver';
+export { LocalizationResolver } from './LocalizationResolver';
+
+// Re-export locale override API for convenience
+export const setLocaleOverride = (locale: string | undefined) => {
+  BillDogConfiguration.setLocaleOverride(locale);
+};
+export const getLocaleOverride = (): string | undefined => {
+  return BillDogConfiguration.getLocaleOverride();
+};
+
+// Import for re-export
+import { BillDogConfiguration } from './BillDogConfiguration';
+
+export * from './utils/priceFormatting';
+
+// Export CSS conversion and gradient utilities
+export { 
+  convertCSSToReactNative, 
+  validateCSSForNative,
+  angleToGradientPoints,
+} from './utils/CSSConverter';
+export type { 
+  CSSConversionResult, 
+  GradientConfig, 
+  GradientStop 
+} from './utils/CSSConverter';
+
+// Export GradientView component
+export { 
+  GradientView, 
+  isGradientSupported, 
+  getGradientStyleOrFallback 
+} from './components/GradientView';
+export type { GradientViewProps } from './components/GradientView';
+
+// Export hook types for better TypeScript support
+export type { UseOfferingsOptions, UseOfferingsResult } from './hooks/useOfferings';
+export type { UsePaywallOptions, UsePaywallResult } from './hooks/usePaywall';
+export type { UsePlacementResult } from './hooks/usePlacement';
+
+// Export cache types
+export type { AdvancedCacheConfig } from './AdvancedPaywallCache';
+export type { CacheConfig } from './PaywallCache';
+
+// Export device detection types
+export type { DeviceCategory, DeviceCategoryInfo } from './utils/deviceDetection';
+export type { MultiPaywallConfig } from './utils/configurationResolver';
+
+// Notification utilities
+export {
+  NotificationScheduler,
+  requestNotificationPermissions,
+  checkNotificationPermissions,
+  scheduleTrialNotification,
+  cancelTrialNotification,
+  getScheduledNotifications,
+} from './notifications/NotificationScheduler';
+export type { NotificationConfig, Subscription } from './notifications/NotificationScheduler';
+export { useDeviceToken, registerDeviceToken } from './notifications/useDeviceToken';
+export { PurchaseNotificationHandler } from './notifications/PurchaseNotificationHandler';
+export type { PurchaseNotificationConfig, PurchaseDetails } from './notifications/PurchaseNotificationHandler';
+
+export {
+  requestNotificationPermission,
+  checkNotificationPermission,
+  isNotificationSupported,
+} from './utils/notificationPermissions';
+export type { NotificationPermissionStatus } from './utils/notificationPermissions';
+
+// Export share sheet utilities
+export { share, isShareSupported } from './utils/shareSheet';
+export type { ShareData, ShareResult } from './utils/shareSheet';
+
+// Export calendar integration utilities
+export {
+  requestCalendarPermission,
+  checkCalendarPermission,
+  addCalendarEvent,
+  isCalendarSupported,
+} from './utils/calendarIntegration';
+export type {
+  CalendarEvent,
+  CalendarPermissionStatus,
+  CalendarResult,
+} from './utils/calendarIntegration';
+
+// Export Live Activities (iOS 16.1+)
+export { LiveActivitiesManager, liveActivities } from './notifications/LiveActivitiesManager';
+export { useLiveActivity } from './notifications/useLiveActivity';
+export type { 
+  LiveActivityConfig, 
+  LiveActivityUpdate 
+} from './notifications/LiveActivitiesManager';
+export type { 
+  UseLiveActivityOptions, 
+  UseLiveActivityReturn 
+} from './notifications/useLiveActivity';
+
+// Export subscription upgrade utilities
+export { useSubscription } from './hooks/useSubscription';
+export type { UseSubscriptionOptions, UseSubscriptionReturn } from './hooks/useSubscription';
+export {
+  previewSubscriptionUpgrade,
+  upgradeSubscription,
+  downgradeSubscription,
+} from './utils/subscriptionUpgrade';
+export type {
+  SubscriptionUpgradeOptions,
+  ProrationPreview,
+  SubscriptionUpgradeResult,
+  ProrationBehavior,
+  BillingCycleAnchor,
+} from './utils/subscriptionUpgrade';
+
+// Modules — Analytics, A/B Testing, Survey, Virtual Currency
+export { AnalyticsManager } from './modules/Analytics';
+export type { AnalyticsEvent, RevenueEvent, UserProperties, UserPropertyOperation } from './modules/Analytics';
+
+export { ABTestManager } from './modules/ABTest';
+export type { ExperimentAssignment } from './modules/ABTest';
+
+export { SurveyManager } from './modules/Survey';
+export type {
+  Survey,
+  SurveyPage,
+  SurveyQuestion,
+  SurveyChoice,
+  SurveyAnswer,
+  SurveyResponse,
+  SurveyPresentationOptions,
+} from './modules/Survey';
+
+export { VirtualCurrencyManager } from './modules/VirtualCurrency';
+export type {
+  VirtualCurrency,
+  VirtualCurrencyTransaction,
+  ExchangeResult,
+  VirtualCurrencyConfig,
+} from './modules/VirtualCurrency';
+
+// Internal components are rendered by ComponentRenderer and intentionally NOT exported:
+// AccoladeCpsComponent, AccordionComponent, AnimatedWrapper, CarouselComponent,
+// CheckboxComponent, ConfettiComponent, CountdownComponent, DelayedXComponent,
+// HorizontalProductsComponent, NavigationComponent, SegmentedPickerComponent,
+// SliderComponent, StickerCompositeComponent, TabsComponent, ToggleComponent,
+// VerticalProductsComponent

package/src/models/BillDogError.ts

@@ -0,0 +1,24 @@
+/**
+ * BillDogError — canonical typed error model (RN mirror).
+ *
+ * Spec:     PUR-200, PUR-201, PUR-202 (.lovable/purchase-conformance-spec.md)
+ * Standard: mem://architecture/purchase-authoritative-standard
+ *
+ * Discriminated union; raw strings are NEVER surfaced across the public
+ * boundary. `category` is stable for analytics / logs.
+ */
+
+export type BillDogError =
+  | { category: 'network'; message: string }
+  | { category: 'store'; message: string; code?: number }
+  | { category: 'storeUnavailable'; message: string }
+  | { category: 'configuration'; message: string }
+  | { category: 'productNotFound'; message: string; productId: string }
+  | { category: 'receiptValidation'; message: string }
+  | { category: 'userCancelled'; message: string }
+  | { category: 'unknown'; message: string };
+
+/**
+ * PUR-262: SDK-wide log levels. Canonical 5-level set, parity with iOS/Android.
+ */
+export type BillDogLogLevel = 'verbose' | 'debug' | 'info' | 'warn' | 'error';

package/src/models/CacheFetchPolicy.ts

@@ -0,0 +1,13 @@
+/**
+ * Fetch policy for CustomerInfo — canonical 4 cases (PUR-140).
+ *
+ * Spec: `.lovable/purchase-conformance-spec.md`
+ * Default: `CACHED_OR_FETCHED` (PUR-141).
+ */
+export type CacheFetchPolicy =
+  | 'FROM_CACHE_ONLY'
+  | 'FETCH_CURRENT'
+  | 'CACHED_OR_FETCHED'
+  | 'NOT_STALE_CACHED_OR_CURRENT';
+
+export const DEFAULT_CACHE_FETCH_POLICY: CacheFetchPolicy = 'CACHED_OR_FETCHED';

package/src/models/CustomProduct.ts

@@ -0,0 +1,33 @@
+/**
+ * CustomProduct — Superwall-style non-StoreKit / non-Play product.
+ *
+ * Spec:     PUR-363, PUR-364
+ *
+ * Used to describe products that don't live in the App Store or Play Console
+ * (Stripe SKUs, Paddle plans, in-house entitlements). Routing is **only**
+ * dispatched through a host-provided PurchaseController; the bundled internal
+ * controller will reject custom products.
+ *
+ * Field names are kept identical to the native iOS (CustomProduct.swift) and
+ * Android (CustomProduct.kt) models so the contract is the same across SDKs.
+ */
+
+export interface CustomProduct {
+  /** Stable BillDog-side identifier for this product. */
+  id: string;
+  displayName: string;
+  /** Localized, ready-to-render price, e.g. "$89.99". */
+  priceString: string;
+  /** Numeric price in `currency`. */
+  price: number;
+  /** ISO 4217 currency code, e.g. "USD". */
+  currency: string;
+  /** External billing provider, e.g. "stripe", "paddle", "in_house". */
+  provider: string;
+  /** The id your PurchaseController charges (e.g. a Stripe price id). */
+  providerProductId: string;
+  /** Optional ISO 8601 duration (e.g. "P1M", "P1Y") for subscription products. */
+  period?: string;
+  /** Free-form metadata forwarded to your PurchaseController. */
+  metadata?: Record<string, string>;
+}

package/src/models/CustomerInfo.ts

@@ -0,0 +1,26 @@
+import type { EntitlementInfo } from './EntitlementInfo';
+
+/**
+ * Server-authoritative CustomerInfo (PUR-120, PUR-121, PUR-123).
+ */
+export interface CustomerInfo {
+  userId: string;
+  entitlements: EntitlementInfo[];
+  activeSubscriptions: string[];
+  originalAppUserId?: string;
+  isInTrial?: boolean;
+  isInGracePeriod?: boolean;
+  hasExpiredSubscription?: boolean;
+  /** PUR-121: instant local resolution before backend confirms. */
+  productEntitlementMapping: Record<string, string[]>;
+}
+
+/** PUR-121: resolve entitlements unlocked by a product ID without a server hop. */
+export function entitlementsByProductId(
+  info: CustomerInfo,
+  productId: string,
+): EntitlementInfo[] {
+  const ids = info.productEntitlementMapping?.[productId];
+  if (!ids || ids.length === 0) return [];
+  return info.entitlements.filter((e) => ids.includes(e.identifier));
+}

package/src/models/Delegate.ts

@@ -0,0 +1,22 @@
+/**
+ * BillDogDelegate — typed lifecycle callbacks (Android parity:
+ * `BillDog.delegate` at BillDog.kt:71, BillDogDelegate interface).
+ *
+ * Consumers set a delegate via `BillDog.setDelegate(d)`. All callbacks are
+ * optional; the SDK fires the ones that are defined. The contract is
+ * intentionally flat so each platform can implement it as a class, plain
+ * object, or function set as the host conventions dictate.
+ */
+
+import type { SkipReason } from './Placement';
+
+export interface BillDogDelegate {
+  onPaywallPresented?: (paywallId: string) => void;
+  onPaywallDismissed?: (paywallId: string) => void;
+  onPaywallSkipped?: (placementId: string, reason: SkipReason) => void;
+  onPurchaseStarted?: (productId: string) => void;
+  onPurchaseCompleted?: (productId: string) => void;
+  onPurchaseFailed?: (productId: string, error: string) => void;
+  onRestoreCompleted?: (itemCount: number) => void;
+  onSubscriptionStatusChanged?: (status: string) => void;
+}

package/src/models/EntitlementInfo.ts

@@ -0,0 +1,27 @@
+/**
+ * Entitlement lifecycle state — 6 canonical cases (PUR-122).
+ */
+export type EntitlementState =
+  | 'ACTIVE'
+  | 'TRIAL'
+  | 'GRACE_PERIOD'
+  | 'BILLING_RETRY'
+  | 'EXPIRED'
+  | 'REVOKED'
+  | 'UNKNOWN';
+
+export interface EntitlementInfo {
+  identifier: string;
+  isActive: boolean;
+  expiresAt?: string;
+  store?: string;
+  grantedAt?: string;
+  displayName?: string;
+  willRenew?: boolean;
+  isLifetime?: boolean;
+  state?: EntitlementState;
+  productIds?: string[];
+  startsAt?: string;
+  renewedAt?: string;
+  latestProductId?: string;
+}

package/src/models/Placement.ts

@@ -0,0 +1,50 @@
+/**
+ * Placement-registration types — Android parity contract.
+ *
+ * Reference: native-sdks/android/billdog-core/src/main/java/com/billdog/core/BillDog.kt
+ *  - register() at line 981 / 990
+ *  - hasAccessForPlacement() at line 1024
+ *  - getPresentationResult() at line 1938
+ *  - PlacementResult sealed class (PlacementManager.kt)
+ *  - PaywallPresentationHandler (PaywallPresentationHandler.kt)
+ *  - PresentationResult sealed class (BillDog.kt:2059)
+ *  - SkipReason enum (BillDogDelegate.kt)
+ *  - PaywallLoadingState enum
+ */
+
+/** Outcome of a placement registration call. */
+export type PlacementResult =
+  | { type: 'entitled' }
+  | { type: 'purchased'; productId: string }
+  | { type: 'dismissed' }
+  | { type: 'restored' }
+  | { type: 'error'; message: string };
+
+/** Synchronous "what would happen if I registered this placement?" answer. */
+export type PresentationResult =
+  | { type: 'paywall' }
+  | { type: 'userSubscribed' }
+  | { type: 'noPaywall'; reason: string }
+  | { type: 'holdout' }
+  | { type: 'error'; message: string };
+
+export type PaywallLoadingState = 'loading' | 'ready' | 'failed';
+
+export type SkipReason =
+  | 'user_has_entitlement'
+  | 'holdout'
+  | 'no_paywall_configured'
+  | 'error';
+
+export type PostPurchaseBehavior = 'close' | 'keep_open';
+
+/** Optional lifecycle callbacks for `register()`. All callbacks are optional. */
+export interface PaywallPresentationHandler {
+  onPresent?: (paywallId: string) => void;
+  onDismiss?: (paywallId: string) => void;
+  onError?: (error: Error) => void;
+  onSkip?: (reason: SkipReason) => void;
+  onPurchaseSuccess?: (productId: string) => PostPurchaseBehavior | void;
+  onFinish?: (paywallId: string, shouldDismiss: boolean) => boolean;
+  onLoadingStateChange?: (state: PaywallLoadingState) => void;
+}

package/src/models/PurchaseParams.ts

@@ -0,0 +1,81 @@
+/**
+ * PurchaseParams — RN bridge mirror of iOS/Android `PurchaseParams.Builder`.
+ *
+ * Spec:     PUR-314, PUR-350, PUR-364
+ * Standard: mem://architecture/purchase-conformance-standard
+ *
+ * Cross-platform typed parameters for `BillDog.purchase(params)`. All fields
+ * other than `productId` are optional. Use the static `builder()` for fluent
+ * construction matching the native SDKs.
+ */
+
+export type GoogleReplacementMode =
+  | 'WITH_TIME_PRORATION'
+  | 'CHARGE_PRORATED_PRICE'
+  | 'WITHOUT_PRORATION'
+  | 'CHARGE_FULL_PRICE'
+  | 'DEFERRED';
+
+export interface PurchaseParams {
+  productId: string;
+  offerToken?: string;
+  promoOfferId?: string;
+  winBackOfferId?: string;
+  appAccountToken?: string;
+  obfuscatedProfileId?: string;
+  quantity?: number;
+  isPersonalizedOffer?: boolean;
+  replacementMode?: GoogleReplacementMode;
+}
+
+export class PurchaseParamsBuilder {
+  private params: PurchaseParams;
+
+  constructor(productId: string) {
+    this.params = { productId, quantity: 1 };
+  }
+
+  offerToken(value: string | undefined): this {
+    this.params.offerToken = value;
+    return this;
+  }
+  promoOfferId(value: string | undefined): this {
+    this.params.promoOfferId = value;
+    return this;
+  }
+  winBackOfferId(value: string | undefined): this {
+    this.params.winBackOfferId = value;
+    return this;
+  }
+  appAccountToken(value: string | undefined): this {
+    this.params.appAccountToken = value;
+    return this;
+  }
+  obfuscatedProfileId(value: string | undefined): this {
+    this.params.obfuscatedProfileId = value;
+    return this;
+  }
+  quantity(value: number): this {
+    this.params.quantity = value < 1 ? 1 : value;
+    return this;
+  }
+  isPersonalizedOffer(value: boolean | undefined): this {
+    this.params.isPersonalizedOffer = value;
+    return this;
+  }
+  replacementMode(value: GoogleReplacementMode | undefined): this {
+    this.params.replacementMode = value;
+    return this;
+  }
+
+  build(): PurchaseParams {
+    return { ...this.params };
+  }
+}
+
+export const PurchaseParams = {
+  /** Fluent builder — mirrors RevenueCat 5.x `PurchaseParams.Builder`. */
+  builder(productId: string): PurchaseParamsBuilder {
+    return new PurchaseParamsBuilder(productId);
+  },
+};

package/src/models/PurchaseResult.ts

@@ -0,0 +1,32 @@
+/**
+ * PurchaseResult — canonical 5-case discriminated union for any purchase op.
+ *
+ * Spec:     PUR-180, PUR-181, PUR-182, PUR-058, PUR-059, PUR-364
+ * Standard: mem://architecture/purchase-authoritative-standard
+ *
+ * Mirrored byte-identically with iOS/Android. User cancellation MUST surface
+ * as `cancelled` (never `failed`); Ask-to-Buy / Android PENDING MUST surface
+ * as `pending`.
+ */
+
+import type { BillDogError } from './BillDogError';
+
+export type PurchaseResult =
+  | {
+      type: 'purchased';
+      transactionId: string;
+      productId: string;
+      originalTransactionId?: string;
+    }
+  | { type: 'cancelled' }
+  | { type: 'pending' }
+  | { type: 'failed'; error: BillDogError }
+  | {
+      type: 'restored';
+      transactionId: string;
+      productId: string;
+      originalTransactionId?: string;
+    };
+
+export const isSuccess = (r: PurchaseResult): boolean =>
+  r.type === 'purchased' || r.type === 'restored';

package/src/models/RestoreResult.ts

@@ -0,0 +1,27 @@
+/**
+ * Canonical RestoreResult — 2-case discriminated union for restore operations.
+ *
+ * Spec:     PUR-080, PUR-081, PUR-082 (.lovable/purchase-conformance-spec.md)
+ * Standard: mem://architecture/purchase-authoritative-standard
+ *           mem://architecture/react-native/sdk-unified-standard
+ *
+ * Mirrored byte-identically across iOS/Android/Flutter.
+ *
+ *  - `restored` : restore succeeded; `items` MAY be empty (= nothing
+ *                 to restore, PUR-080). Callers MUST NOT treat empty
+ *                 as failure.
+ *  - `failed`   : global failure (network, store sync threw).
+ *                 Per-transaction failures live in `RestoredItem.status`,
+ *                 never here.
+ */
+
+import type { BillDogError } from './BillDogError';
+import type { RestoredItem } from './RestoredItem';
+
+export type RestoreResult =
+  | { type: 'restored'; items: RestoredItem[] }
+  | { type: 'failed'; error: BillDogError };
+
+/** Convenience: was the restore globally successful? */
+export const isRestoreOk = (r: RestoreResult): r is { type: 'restored'; items: RestoredItem[] } =>
+  r.type === 'restored';

package/src/models/RestoredItem.ts

@@ -0,0 +1,25 @@
+/**
+ * RestoredItem & RestoreItemStatus — canonical per-transaction restore record.
+ *
+ * Spec:     PUR-081, PUR-082 (.lovable/purchase-conformance-spec.md)
+ * Standard: mem://architecture/purchase-authoritative-standard
+ *           mem://architecture/react-native/sdk-unified-standard
+ *
+ * Mirrored byte-identically across iOS/Android/Flutter. Per-transaction
+ * failure MUST be reported in `status` — never collapsed into a global
+ * `RestoreResult.failed`.
+ */
+
+import type { BillDogError } from './BillDogError';
+
+export type RestoreItemStatus =
+  | { type: 'restored' }
+  | { type: 'expired' }
+  | { type: 'failed'; error: BillDogError };
+
+export interface RestoredItem {
+  productId: string;
+  transactionId: string;
+  originalTransactionId?: string;
+  status: RestoreItemStatus;
+}