Skip to content

Commit fbc9af4

Browse files
hyochanhyochan
committed
chore: merge main
1 parent 0d01008 commit fbc9af4

60 files changed

Lines changed: 12027 additions & 3737 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/guides/01-overview.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# OpenIAP Project Overview
2+
3+
OpenIAP is an open specification that standardizes in-app purchase implementations across platforms.
4+
5+
## Monorepo Structure
6+
7+
```text
8+
openiap/
9+
├── packages/
10+
│ ├── apple/ # iOS/macOS library (Swift, StoreKit 2)
11+
│ ├── google/ # Android library (Kotlin, Play Billing)
12+
│ ├── gql/ # GraphQL schema & type generation
13+
│ └── docs/ # Documentation site (React/Vite)
14+
├── scripts/ # Monorepo-wide automation
15+
├── .github/workflows/ # CI/CD workflows
16+
├── CLAUDE.md # Main agent guidelines
17+
└── openiap-versions.json # Version management
18+
```
19+
20+
## Package Responsibilities
21+
22+
| Package | Purpose | Language | Output |
23+
| -------- | ----------------------------- | ---------------- | ----------------------------- |
24+
| `apple` | iOS/macOS IAP implementation | Swift | CocoaPods, SPM |
25+
| `google` | Android IAP implementation | Kotlin | Maven Central |
26+
| `gql` | Type definitions & generation | TypeScript | Swift, Kotlin, Dart, TS types |
27+
| `docs` | Documentation website | React/TypeScript | Vercel deployment |
28+
29+
## Version Management
30+
31+
All versions are tracked in `openiap-versions.json`:
32+
33+
```json
34+
{
35+
"apple": "1.2.x",
36+
"google": "1.2.x",
37+
"gql": "1.2.x"
38+
}
39+
```
40+
41+
## Key Principles
42+
43+
1. **Unified API**: Same function names across all platforms
44+
2. **Platform suffixes**: `IOS` for iOS-only, `Android` for Android-only
45+
3. **Type safety**: Generated types from GraphQL schema
46+
4. **Deprecation over removal**: Keep deprecated APIs, add new ones

‎.claude/guides/02-api-naming.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# API Naming Conventions
2+
3+
## Platform Suffix Rules
4+
5+
### iOS-Specific Functions (IOS suffix)
6+
7+
Functions only available on iOS/macOS must end with `IOS`:
8+
9+
```text
10+
clearTransactionIOS
11+
getStorefrontIOS
12+
getPromotedProductIOS
13+
getPendingTransactionsIOS
14+
isEligibleForIntroOfferIOS
15+
subscriptionStatusIOS
16+
currentEntitlementIOS
17+
latestTransactionIOS
18+
showManageSubscriptionsIOS
19+
beginRefundRequestIOS
20+
isTransactionVerifiedIOS
21+
getTransactionJwsIOS
22+
getReceiptDataIOS
23+
syncIOS
24+
presentCodeRedemptionSheetIOS
25+
getAppTransactionIOS
26+
```
27+
28+
### Android-Specific Functions (Android suffix)
29+
30+
Functions only available on Android must end with `Android`:
31+
32+
```text
33+
acknowledgePurchaseAndroid
34+
consumePurchaseAndroid
35+
getPackageNameAndroid
36+
```
37+
38+
### Cross-Platform Functions (No suffix)
39+
40+
Functions available on both platforms have no suffix:
41+
42+
```text
43+
initConnection
44+
endConnection
45+
fetchProducts
46+
requestPurchase
47+
getAvailablePurchases
48+
finishTransaction
49+
verifyPurchase
50+
getActiveSubscriptions
51+
hasActiveSubscriptions
52+
deepLinkToSubscriptions
53+
getStorefront
54+
restorePurchases
55+
```
56+
57+
## Action Prefix Rules
58+
59+
| Prefix | Usage | Example |
60+
| -------------- | -------------------- | ---------------------------- |
61+
| `get` | Retrieve data | `getPromotedProductIOS` |
62+
| `fetch` | Async data retrieval | `fetchProducts` |
63+
| `request` | Initiate action | `requestPurchase` |
64+
| `clear` | Remove/reset | `clearTransactionIOS` |
65+
| `is/has` | Boolean checks | `isEligibleForIntroOfferIOS` |
66+
| `show/present` | Display UI | `showManageSubscriptionsIOS` |
67+
| `begin` | Start process | `beginRefundRequestIOS` |
68+
| `finish/end` | Complete process | `finishTransaction` |
69+
70+
## URL Anchor Format
71+
72+
Use kebab-case for URL anchors:
73+
74+
- `fetchProducts` → `#fetch-products`
75+
- `getAppTransactionIOS` → `#get-app-transaction-ios`
76+
- `verifyPurchase` → `#verify-purchase`
77+
78+
## Package-Specific Rules
79+
80+
### In `packages/google` (Android-only package)
81+
82+
**DO NOT** add `Android` suffix to internal functions:
83+
84+
```kotlin
85+
// Correct - inside Android package
86+
fun acknowledgePurchase()
87+
fun consumePurchase()
88+
89+
// Wrong - don't add Android suffix
90+
fun acknowledgePurchaseAndroid()
91+
```
92+
93+
### In `packages/apple` (iOS-only package)
94+
95+
iOS-specific functions still need `IOS` suffix for cross-platform API consistency:
96+
97+
```swift
98+
// Correct
99+
func presentCodeRedemptionSheetIOS()
100+
func syncIOS()
101+
102+
// Cross-platform (no suffix)
103+
func verifyPurchase()
104+
```

‎.claude/guides/03-deprecations.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Deprecated APIs and Migration
2+
3+
## Current Deprecations
4+
5+
### validateReceipt → verifyPurchase
6+
7+
**Deprecated in**: openiap v1.2.6
8+
9+
| Old API | New API | Notes |
10+
| -------------------- | ---------------- | ----------------------- |
11+
| `validateReceipt` | `verifyPurchase` | Cross-platform |
12+
| `validateReceiptIOS` | `verifyPurchase` | iOS-specific deprecated |
13+
14+
**Migration**:
15+
16+
```typescript
17+
// Before
18+
const result = await validateReceipt({ sku: "product_id" });
19+
20+
// After
21+
const result = await verifyPurchase({ sku: "product_id" });
22+
```
23+
24+
```swift
25+
// Before
26+
let result = try await store.validateReceipt(sku: "product_id")
27+
28+
// After
29+
let result = try await store.verifyPurchase(sku: "product_id")
30+
```
31+
32+
```kotlin
33+
// Before
34+
val result = store.validateReceipt(props)
35+
36+
// After
37+
val result = store.verifyPurchase(props)
38+
```
39+
40+
### Other Deprecated APIs
41+
42+
| Old | New | Package |
43+
| -------------------------- | ------------------------------------- | ------- |
44+
| `buy-promoted-product-ios` | `requestPurchaseOnPromotedProductIOS` | All |
45+
| `requestProducts` | `fetchProducts` | All |
46+
| `get-storefront-ios` | `getStorefront` | All |
47+
48+
## Deprecation Guidelines
49+
50+
When deprecating APIs:
51+
52+
1. **Keep the old function** - Don't remove, mark as deprecated
53+
2. **Delegate to new API** - Old function should call new one internally
54+
3. **Add deprecation annotation**:
55+
56+
```swift
57+
@available(*, deprecated, message: "Use verifyPurchase")
58+
public func validateReceipt(_ props: ReceiptValidationProps) async throws -> ReceiptValidationResult {
59+
try await verifyPurchase(props)
60+
}
61+
```
62+
63+
```kotlin
64+
@Deprecated("Use verifyPurchase")
65+
override val validateReceipt: MutationValidateReceiptHandler = { props ->
66+
verifyPurchase(props)
67+
}
68+
```
69+
70+
4. **Update documentation** - Add migration guide in `docs/updates/notes.tsx`
71+
5. **Update CLAUDE.md** - Add to deprecated functions list

‎.claude/guides/04-apple-package.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Apple Package Guide
2+
3+
Location: `packages/apple/`
4+
5+
## Overview
6+
7+
iOS/macOS in-app purchase library using StoreKit 2.
8+
9+
## Directory Structure
10+
11+
```text
12+
packages/apple/
13+
├── Sources/
14+
│ ├── OpenIapModule.swift # Core implementation
15+
│ ├── OpenIapStore.swift # SwiftUI-friendly store
16+
│ ├── OpenIapProtocol.swift # API interface definitions
17+
│ ├── Models/
18+
│ │ ├── Types.swift # AUTO-GENERATED - DO NOT EDIT
19+
│ │ ├── Product.swift # ProductIOS type
20+
│ │ ├── Purchase.swift # PurchaseIOS type
21+
│ │ └── ActiveSubscription.swift
22+
│ └── Helpers/
23+
│ ├── ProductManager.swift # Thread-safe product caching
24+
│ └── IapStatus.swift # UI status for SwiftUI
25+
├── Tests/
26+
├── scripts/
27+
│ └── generate-types.sh # Type generation script
28+
└── openiap-versions.json # Version management
29+
```
30+
31+
## Key Files
32+
33+
### OpenIapProtocol.swift
34+
35+
Defines the public API interface:
36+
37+
```swift
38+
public protocol OpenIapModuleProtocol {
39+
func initConnection() async throws -> Bool
40+
func fetchProducts(_ params: ProductRequest) async throws -> FetchProductsResult
41+
func requestPurchase(_ params: RequestPurchaseProps) async throws -> RequestPurchaseResult?
42+
func finishTransaction(purchase: PurchaseInput, isConsumable: Bool?) async throws -> Void
43+
func verifyPurchase(_ props: ReceiptValidationProps) async throws -> ReceiptValidationResult
44+
// ... more methods
45+
}
46+
```
47+
48+
### OpenIapModule.swift
49+
50+
Main implementation with StoreKit 2 integration.
51+
52+
### OpenIapStore.swift
53+
54+
SwiftUI-compatible wrapper with `@Observable` pattern.
55+
56+
## Type Generation
57+
58+
Types.swift is auto-generated from GraphQL schema.
59+
60+
**Never edit Types.swift directly!**
61+
62+
```bash
63+
# Generate types
64+
./scripts/generate-types.sh
65+
66+
# Or with specific version
67+
OPENIAP_GQL_VERSION=1.0.10 ./scripts/generate-types.sh
68+
```
69+
70+
## Version Management
71+
72+
```bash
73+
# Bump version
74+
./scripts/bump-version.sh patch # 1.2.5 → 1.2.6
75+
./scripts/bump-version.sh minor # 1.2.5 → 1.3.0
76+
./scripts/bump-version.sh 1.3.0 # Set specific version
77+
```
78+
79+
## Testing
80+
81+
```bash
82+
swift test
83+
swift build
84+
```
85+
86+
## Deployment
87+
88+
Via GitHub Actions "Apple Release" workflow:
89+
90+
- Creates Git tag `apple-vX.X.X`
91+
- Publishes to CocoaPods
92+
- SPM uses Git tags automatically

‎.claude/guides/05-google-package.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Google Package Guide
2+
3+
Location: `packages/google/`
4+
5+
## Overview
6+
7+
Android in-app purchase library supporting:
8+
9+
- Google Play Billing (play variant)
10+
- Horizon Store (horizon variant)
11+
12+
## Directory Structure
13+
14+
```text
15+
packages/google/
16+
├── openiap/
17+
│ └── src/
18+
│ ├── main/java/dev/hyo/openiap/
19+
│ │ ├── Types.kt # AUTO-GENERATED - DO NOT EDIT
20+
│ │ ├── OpenIapProtocol.kt # API interface
21+
│ │ ├── OpenIapStore.kt # Main store class
22+
│ │ ├── listener/ # Event listeners
23+
│ │ └── utils/ # Helper utilities
24+
│ ├── play/java/dev/hyo/openiap/
25+
│ │ └── OpenIapModule.kt # Play Store implementation
26+
│ └── horizon/java/dev/hyo/openiap/
27+
│ └── OpenIapModule.kt # Horizon implementation
28+
├── Example/ # Sample app
29+
├── scripts/
30+
│ └── generate-types.sh
31+
└── openiap-versions.json
32+
```
33+
34+
## Build Variants
35+
36+
| Variant | Purpose | Billing Library |
37+
| --------- | ------------------ | ---------------- |
38+
| `play` | Google Play Store | Play Billing 8.x |
39+
| `horizon` | Meta Horizon Store | Horizon SDK |
40+
41+
## Type Generation
42+
43+
Types.kt is auto-generated. **Never edit directly!**
44+
45+
```bash
46+
./scripts/generate-types.sh
47+
```
48+
49+
## Building
50+
51+
```bash
52+
# Compile library
53+
./gradlew :openiap:compilePlayDebugKotlin
54+
./gradlew :openiap:compileHorizonDebugKotlin
55+
56+
# Run tests
57+
./gradlew :openiap:testPlayDebugUnitTest
58+
./gradlew :openiap:testHorizonDebugUnitTest
59+
60+
# Build Example app
61+
./gradlew :Example:assemblePlayDebug
62+
```
63+
64+
## Naming Convention
65+
66+
Inside this Android-only package, **do not** add `Android` suffix:
67+
68+
```kotlin
69+
// Correct
70+
fun acknowledgePurchase()
71+
fun consumePurchase()
72+
73+
// Wrong
74+
fun acknowledgePurchaseAndroid()
75+
```
76+
77+
## Deployment
78+
79+
Via GitHub Actions "Google Release" workflow → Maven Central

0 commit comments

Comments
 (0)