@sudobility/subscription_lib

Cross-platform subscription management library that abstracts RevenueCat SDK differences between web and React Native behind a unified adapter interface.

Installation

bun add @sudobility/subscription_lib

Peer Dependencies

• react ^18.0.0 || ^19.0.0
• @sudobility/types ^1.9.53
• @revenuecat/purchases-js ^1.0.0 (web only, optional)
• react-native-purchases >= 7.0.0 (React Native only, optional)

Usage

import {
  initializeSubscription,
  configureRevenueCatAdapter,
  createRevenueCatAdapter,
  useSubscriptions,
  useUserSubscription,
  useSubscribable,
} from '@sudobility/subscription_lib';

// App startup
configureRevenueCatAdapter(REVENUECAT_API_KEY);
initializeSubscription({
  adapter: createRevenueCatAdapter(),
  freeTier: { packageId: 'free', displayName: 'Free' },
});

// React hooks
const { offer, isLoading } = useSubscriptions('default');
const { subscription } = useUserSubscription();
const { subscribablePackageIds } = useSubscribable('default');

API

Core Singleton

| Function | Description | |----------|-------------| | initializeSubscription(config) | Initialize with adapter + free tier config | | setSubscriptionUserId(id, email?) | Set current user, triggers reload | | refreshSubscription() | Reload offerings + customer info | | getSubscriptionInstance() | Get the SubscriptionService singleton |

Hooks

| Hook | Description | |------|-------------| | useSubscriptions(offerId) | Fetch offer/product catalog (cached) | | useUserSubscription() | Current user subscription status | | useSubscriptionPeriods(offerId) | Available billing periods, sorted | | useSubscriptionForPeriod(offerId, period) | Packages for a period, sorted by price | | useSubscribable(offerId) | Upgrade-eligible package IDs |

Built-in Adapters

• Web: configureRevenueCatAdapter, createRevenueCatAdapter, setRevenueCatUser, clearRevenueCatUser
• React Native: configureRevenueCatRNAdapter, createRevenueCatRNAdapter, setRevenueCatRNUser, clearRevenueCatRNUser

Utilities

parseISO8601Period, getPeriodRank, comparePeriods, calculatePackageLevels, findUpgradeablePackages

Key Types

SubscriptionAdapter, SubscriptionOffer, SubscriptionPackage, CurrentSubscription, FreeTierConfig, SubscriptionPeriod

Development

bun run build        # Compile TS to dist/
bun run dev          # Watch mode (tsc --watch)
bun test             # Run tests (vitest run)
bun run typecheck    # TypeScript check
bun run lint         # ESLint
bun run format       # Prettier

Pre-commit:

bun run typecheck && bun run lint && bun test && bun run build

License

BUSL-1.1