feat: add standardized DiscountOffer and SubscriptionOffer types (#63)

- Add new cross-platform types: DiscountOffer, SubscriptionOffer,
DiscountOfferType, PaymentMode, SubscriptionPeriod,
SubscriptionPeriodUnit
- Use flat structure with platform-specific suffixes (offerTokenAndroid,
keyIdentifierIOS, etc.)
- Deprecate old platform-specific types for migration path
- Update Android BillingConverters to populate new standardized fields
- Update iOS StoreKitTypesBridge to convert StoreKit offers to
standardized types
- Add Horizon flavor support with null/empty defaults
- Add comprehensive unit tests for both platforms
- Update example apps to use new standardized offer types
- Add documentation page for offer types

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Introduced standardized cross-platform DiscountOffer and
SubscriptionOffer types and surfaced them across product/subscription
APIs; subscription UI now displays intro/promotional badges (e.g., "Free
Trial").

* **Documentation**
* Added Offer Types docs, migration guidance, updated platform type
pages/TLDRs, and comprehensive per-platform sync/workflow guides.

* **Deprecations**
* Marked platform-specific offer types/fields as deprecated in favor of
standardized types.

* **Tests**
* Expanded unit tests covering new offer types, enums,
period/serialization, and integration with product models.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: hyochan

.claude/commands/sync-all-platforms.md

@@ -0,0 +1,296 @@
+# Sync Changes to expo-iap
+
+Synchronize OpenIAP changes to the [expo-iap](https://github.com/hyochan/expo-iap) repository.
+
+**Target Repository:** `$IAP_REPOS_HOME/expo-iap`
+
+> **Note:** Set `IAP_REPOS_HOME` environment variable (see [sync-all-platforms.md](./sync-all-platforms.md#environment-setup))
+
+## Project Overview
+
+- **Package Manager:** Bun
+- **Framework:** Expo Module (React Native)
+- **Current Version:** Check `package.json`
+- **OpenIAP Version Tracking:** `openiap-versions.json`
+
+## Key Files
+
+| File | Purpose | Auto-Generated |
+|------|---------|----------------|
+| `src/types.ts` | TypeScript types from OpenIAP | YES |
+| `src/index.ts` | Main API exports | NO |
+| `src/useIAP.ts` | React Hook for IAP | NO |
+| `src/modules/ios.ts` | iOS-specific functions | NO |
+| `src/modules/android.ts` | Android-specific functions | NO |
+| `openiap-versions.json` | Version tracking | NO |
+
+## Sync Steps
+
+### 0. Pull Latest (REQUIRED)
+
+**Always pull the latest code before starting any sync work:**
+
+```bash
+cd $IAP_REPOS_HOME/expo-iap
+git pull
+```
+
+### 1. Sync openiap-versions.json (REQUIRED)
+
+**IMPORTANT:** Before generating types, sync version numbers from openiap monorepo.
+
+```bash
+cd $IAP_REPOS_HOME/expo-iap
+
+# Check current versions in openiap monorepo
+cat $OPENIAP_HOME/openiap/openiap-versions.json
+
+# Update expo-iap's openiap-versions.json to match:
+# - "gql": should match openiap's "gql" version
+# - "apple": should match openiap's "apple" version
+# - "google": should match openiap's "google" version
+```
+
+**Version fields to sync:**
+| Field | Source | Purpose |
+|-------|--------|---------|
+| `gql` | `$OPENIAP_HOME/openiap/openiap-versions.json` | TypeScript types version |
+| `apple` | `$OPENIAP_HOME/openiap/openiap-versions.json` | iOS native SDK version |
+| `google` | `$OPENIAP_HOME/openiap/openiap-versions.json` | Android native SDK version |
+
+### 2. Type Synchronization
+
+```bash
+cd $IAP_REPOS_HOME/expo-iap
+
+# Download and regenerate types (uses versions from openiap-versions.json)
+bun run generate:types
+
+# Verify types
+bun run typecheck
+```
+
+### 3. Native Code Modifications
+
+#### iOS Native Code
+
+**Location:** `ios/`
+
+Key files to update:
+- `ios/ExpoIapModule.swift` - Main Expo module implementation
+- `ios/ExpoIap.podspec` - CocoaPods spec (update `apple` version dependency)
+
+**When to modify:**
+- New iOS-specific API methods added to OpenIAP
+- Type conversion changes needed
+- StoreKit 2 API changes
+
+**Update workflow:**
+```bash
+cd $IAP_REPOS_HOME/expo-iap
+
+# 1. Update apple version in openiap-versions.json
+# 2. Review openiap/packages/apple/Sources/ for changes
+# 3. Update ios/ExpoIapModule.swift accordingly
+
+# Install updated pod
+cd example/ios && pod install --repo-update
+```
+
+#### Android Native Code
+
+**Location:** `android/src/main/java/`
+
+Key files to update:
+- `ExpoIapModule.kt` - Main Expo module implementation
+- `build.gradle` - Dependencies (auto-reads `google` version)
+
+**When to modify:**
+- New Android-specific API methods added to OpenIAP
+- Type conversion changes needed
+- Play Billing API changes
+
+**Update workflow:**
+```bash
+cd $IAP_REPOS_HOME/expo-iap
+
+# 1. Update google version in openiap-versions.json
+# 2. Review openiap/packages/google/openiap/src/main/ for changes
+# 3. Update android/src/main/java/ accordingly
+
+# Gradle auto-syncs on build
+```
+
+### 4. Build & Test Native Code
+
+#### iOS Build Test
+
+```bash
+cd $IAP_REPOS_HOME/expo-iap/example
+
+# Clean and prebuild
+npx expo prebuild --clean --platform ios
+
+# Install pods
+cd ios && pod install --repo-update && cd ..
+
+# Build for simulator
+npx expo run:ios --device "iPhone 15 Pro"
+
+# Or build via Xcode
+open ios/expoiapexample.xcworkspace
+# Build: Cmd+B, Run: Cmd+R
+```
+
+#### Android Build Test
+
+```bash
+cd $IAP_REPOS_HOME/expo-iap/example
+
+# Clean and prebuild
+npx expo prebuild --clean --platform android
+
+# Build debug APK
+npx expo run:android
+
+# Or build via Android Studio
+# Open android/ folder in Android Studio
+# Build > Make Project
+```
+
+#### Android Horizon Build (Meta Quest)
+
+```bash
+cd $IAP_REPOS_HOME/expo-iap/example
+
+# Enable Horizon flavor in gradle.properties
+echo "horizonEnabled=true" >> android/gradle.properties
+
+# Prebuild and build with Horizon
+npx expo prebuild --clean --platform android
+npx expo run:android
+
+# Revert for Play Store builds
+sed -i '' '/horizonEnabled=true/d' android/gradle.properties
+```
+
+#### Full Build Matrix
+
+```bash
+cd $IAP_REPOS_HOME/expo-iap
+
+# TypeScript build
+bun run build
+
+# iOS build
+cd example && npx expo run:ios
+
+# Android build (Play Store)
+cd example && npx expo run:android
+
+# Android build (Horizon)
+cd example && echo "horizonEnabled=true" >> android/gradle.properties && npx expo run:android
+
+# All tests
+bun run test
+cd example && bun run test
+```
+
+### 5. Update Example Code
+
+**Location:** `example/app/`
+
+Key example screens:
+- `index.tsx` - Home/Overview
+- `purchase-flow.tsx` - Purchase flow demo
+- `subscription-flow.tsx` - Subscription demo
+- `alternative-billing.tsx` - Android alt billing
+- `offer-code.tsx` - Promo code redemption
+
+### 6. Update Tests
+
+**Library Tests:** `src/__tests__/`
+**Example Tests:** `example/__tests__/`
+
+```bash
+# Run all tests
+bun run test
+
+# Run example tests
+cd example && bun run test
+```
+
+### 7. Update Documentation
+
+**Location:** `docs/`
+- `docs/api/` - API reference
+- `docs/guides/` - Usage guides
+- `docs/examples/` - Code examples
+
+### 8. Update llms.txt Files
+
+**Location:** `docs/static/`
+
+Update AI-friendly documentation files when APIs or types change:
+
+- `docs/static/llms.txt` - Quick reference for AI assistants
+- `docs/static/llms-full.txt` - Detailed AI reference
+
+**When to update:**
+- New API functions added
+- Function signatures changed
+- New types or enums added
+- Usage patterns updated
+- Error codes changed
+
+**Content to sync:**
+1. Installation commands
+2. Core API reference (useIAP hook, direct functions)
+3. Key types (Product, Purchase, ErrorCode)
+4. Common usage patterns
+5. Platform-specific APIs (iOS/Android suffixes)
+6. Error handling examples
+
+### 9. Pre-commit Checklist
+
+```bash
+bun run lint           # ESLint
+bun run typecheck      # TypeScript
+bun run test           # Jest
+cd example && bun run test  # Example app tests
+```
+
+## Naming Conventions
+
+- **iOS-only:** `functionNameIOS` (e.g., `syncIOS`, `getPromotedProductIOS`)
+- **Android-only:** `functionNameAndroid` (e.g., `validateReceiptAndroid`)
+- **Cross-platform:** No suffix (e.g., `fetchProducts`, `requestPurchase`)
+- **Error codes:** kebab-case (e.g., `'user-cancelled'`)
+
+## Deprecation Check
+
+Search for deprecated patterns:
+```bash
+cd $IAP_REPOS_HOME/expo-iap
+grep -r "@deprecated" src/
+grep -r "DEPRECATED" src/
+```
+
+Known deprecated functions:
+- `requestProducts` -> Use `fetchProducts`
+- `validateReceipt` -> Use `verifyPurchase`
+- `validateReceiptIOS` -> Use `verifyPurchase`
+
+## Commit Message Format
+
+```text
+feat: add discount offer support
+fix: resolve iOS purchase verification
+docs: update subscription flow guide
+```
+
+## References
+
+- **CLAUDE.md:** `$IAP_REPOS_HOME/expo-iap/CLAUDE.md`
+- **OpenIAP Docs:** [openiap.dev/docs](https://openiap.dev/docs)
+- **expo-iap Docs:** [expo-iap.vercel.app](https://expo-iap.vercel.app)