expo-iap 3.0.7 → 3.1.0

package/src/utils/errorMapping.ts

@@ -1,9 +1,209 @@
 /**
- * Error mapping utilities for expo-iap
- * Provides helper functions for handling platform-specific errors
+ * Error mapping utilities for expo-iap.
+ * Provides helpers for working with platform-specific error codes
+ * and constructing structured purchase errors.
  */
 
-import {ErrorCode} from '../types';
+import {NATIVE_ERROR_CODES} from '../ExpoIapModule';
+import {ErrorCode, IapPlatform} from '../types';
+
+export interface PurchaseErrorProps {
+  message: string;
+  responseCode?: number;
+  debugMessage?: string;
+  code?: ErrorCode;
+  productId?: string;
+  platform?: IapPlatform;
+}
+
+type PlatformErrorData = {
+  code?: string | number;
+  message?: string;
+  responseCode?: number;
+  debugMessage?: string;
+  productId?: string;
+};
+
+export type PurchaseError = Error & PurchaseErrorProps;
+
+const toStandardizedCode = (errorCode: ErrorCode): string =>
+  errorCode.startsWith('E_') ? errorCode : `E_${errorCode}`;
+
+const normalizePlatform = (platform: IapPlatform): 'ios' | 'android' =>
+  typeof platform === 'string' && platform.toLowerCase() === 'ios'
+    ? 'ios'
+    : 'android';
+
+const COMMON_ERROR_CODE_MAP: Record<ErrorCode, string> = {
+  [ErrorCode.Unknown]: toStandardizedCode(ErrorCode.Unknown),
+  [ErrorCode.UserCancelled]: toStandardizedCode(ErrorCode.UserCancelled),
+  [ErrorCode.UserError]: toStandardizedCode(ErrorCode.UserError),
+  [ErrorCode.ItemUnavailable]: toStandardizedCode(ErrorCode.ItemUnavailable),
+  [ErrorCode.RemoteError]: toStandardizedCode(ErrorCode.RemoteError),
+  [ErrorCode.NetworkError]: toStandardizedCode(ErrorCode.NetworkError),
+  [ErrorCode.ServiceError]: toStandardizedCode(ErrorCode.ServiceError),
+  [ErrorCode.ReceiptFailed]: toStandardizedCode(ErrorCode.ReceiptFailed),
+  [ErrorCode.ReceiptFinished]: toStandardizedCode(ErrorCode.ReceiptFinished),
+  [ErrorCode.ReceiptFinishedFailed]: toStandardizedCode(
+    ErrorCode.ReceiptFinishedFailed,
+  ),
+  [ErrorCode.NotPrepared]: toStandardizedCode(ErrorCode.NotPrepared),
+  [ErrorCode.NotEnded]: toStandardizedCode(ErrorCode.NotEnded),
+  [ErrorCode.AlreadyOwned]: toStandardizedCode(ErrorCode.AlreadyOwned),
+  [ErrorCode.DeveloperError]: toStandardizedCode(ErrorCode.DeveloperError),
+  [ErrorCode.BillingResponseJsonParseError]: toStandardizedCode(
+    ErrorCode.BillingResponseJsonParseError,
+  ),
+  [ErrorCode.DeferredPayment]: toStandardizedCode(ErrorCode.DeferredPayment),
+  [ErrorCode.Interrupted]: toStandardizedCode(ErrorCode.Interrupted),
+  [ErrorCode.IapNotAvailable]: toStandardizedCode(ErrorCode.IapNotAvailable),
+  [ErrorCode.PurchaseError]: toStandardizedCode(ErrorCode.PurchaseError),
+  [ErrorCode.SyncError]: toStandardizedCode(ErrorCode.SyncError),
+  [ErrorCode.TransactionValidationFailed]: toStandardizedCode(
+    ErrorCode.TransactionValidationFailed,
+  ),
+  [ErrorCode.ActivityUnavailable]: toStandardizedCode(
+    ErrorCode.ActivityUnavailable,
+  ),
+  [ErrorCode.AlreadyPrepared]: toStandardizedCode(ErrorCode.AlreadyPrepared),
+  [ErrorCode.Pending]: toStandardizedCode(ErrorCode.Pending),
+  [ErrorCode.ConnectionClosed]: toStandardizedCode(ErrorCode.ConnectionClosed),
+  [ErrorCode.InitConnection]: toStandardizedCode(ErrorCode.InitConnection),
+  [ErrorCode.ServiceDisconnected]: toStandardizedCode(
+    ErrorCode.ServiceDisconnected,
+  ),
+  [ErrorCode.QueryProduct]: toStandardizedCode(ErrorCode.QueryProduct),
+  [ErrorCode.SkuNotFound]: toStandardizedCode(ErrorCode.SkuNotFound),
+  [ErrorCode.SkuOfferMismatch]: toStandardizedCode(ErrorCode.SkuOfferMismatch),
+  [ErrorCode.ItemNotOwned]: toStandardizedCode(ErrorCode.ItemNotOwned),
+  [ErrorCode.BillingUnavailable]: toStandardizedCode(
+    ErrorCode.BillingUnavailable,
+  ),
+  [ErrorCode.FeatureNotSupported]: toStandardizedCode(
+    ErrorCode.FeatureNotSupported,
+  ),
+  [ErrorCode.EmptySkuList]: toStandardizedCode(ErrorCode.EmptySkuList),
+};
+
+export const ErrorCodeMapping = {
+  ios: COMMON_ERROR_CODE_MAP,
+  android: COMMON_ERROR_CODE_MAP,
+} as const;
+
+const OPENIAP_ERROR_CODE_SET: Set<string> = new Set(
+  Object.values(ErrorCode).map((code) => toStandardizedCode(code)),
+);
+
+export const createPurchaseError = (
+  props: PurchaseErrorProps,
+): PurchaseError => {
+  const error = new Error(props.message) as PurchaseError;
+  error.name = '[expo-iap]: PurchaseError';
+  error.responseCode = props.responseCode;
+  error.debugMessage = props.debugMessage;
+  error.code = props.code;
+  error.productId = props.productId;
+  error.platform = props.platform;
+  return error;
+};
+
+export const createPurchaseErrorFromPlatform = (
+  errorData: PlatformErrorData,
+  platform: IapPlatform,
+): PurchaseError => {
+  const normalizedPlatform = normalizePlatform(platform);
+  const errorCode = errorData.code
+    ? ErrorCodeUtils.fromPlatformCode(errorData.code, normalizedPlatform)
+    : ErrorCode.Unknown;
+
+  return createPurchaseError({
+    message: errorData.message ?? 'Unknown error occurred',
+    responseCode: errorData.responseCode,
+    debugMessage: errorData.debugMessage,
+    code: errorCode,
+    productId: errorData.productId,
+    platform,
+  });
+};
+
+export const ErrorCodeUtils = {
+  getNativeErrorCode: (errorCode: ErrorCode): string => {
+    const standardized = toStandardizedCode(errorCode);
+    return (
+      (NATIVE_ERROR_CODES as Record<string, string | undefined>)[
+        standardized
+      ] ?? standardized
+    );
+  },
+  fromPlatformCode: (
+    platformCode: string | number,
+    _platform: IapPlatform,
+  ): ErrorCode => {
+    if (typeof platformCode === 'string' && platformCode.startsWith('E_')) {
+      if (OPENIAP_ERROR_CODE_SET.has(platformCode)) {
+        const match = Object.entries(COMMON_ERROR_CODE_MAP).find(
+          ([, value]) => value === platformCode,
+        );
+        if (match) {
+          return match[0] as ErrorCode;
+        }
+      }
+    }
+
+    for (const [standardized, nativeCode] of Object.entries(
+      (NATIVE_ERROR_CODES || {}) as Record<string, string | number>,
+    )) {
+      if (
+        nativeCode === platformCode &&
+        OPENIAP_ERROR_CODE_SET.has(standardized)
+      ) {
+        const match = Object.entries(COMMON_ERROR_CODE_MAP).find(
+          ([, mappedCode]) => mappedCode === standardized,
+        );
+        if (match) {
+          return match[0] as ErrorCode;
+        }
+      }
+    }
+
+    for (const [errorCode, mappedCode] of Object.entries(
+      COMMON_ERROR_CODE_MAP,
+    )) {
+      if (mappedCode === platformCode) {
+        return errorCode as ErrorCode;
+      }
+    }
+
+    return ErrorCode.Unknown;
+  },
+  toPlatformCode: (
+    errorCode: ErrorCode,
+    _platform: IapPlatform,
+  ): string | number => {
+    const standardized = toStandardizedCode(errorCode);
+    const native = (NATIVE_ERROR_CODES as Record<string, string | number>)[
+      standardized
+    ];
+    return native ?? COMMON_ERROR_CODE_MAP[errorCode] ?? 'E_UNKNOWN';
+  },
+  isValidForPlatform: (
+    errorCode: ErrorCode,
+    platform: IapPlatform,
+  ): boolean => {
+    const standardized = toStandardizedCode(errorCode);
+    if (
+      (NATIVE_ERROR_CODES as Record<string, unknown>)[standardized] !==
+      undefined
+    ) {
+      return true;
+    }
+    return standardized in ErrorCodeMapping[normalizePlatform(platform)];
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Convenience helpers for interpreting error objects
+// ---------------------------------------------------------------------------
 
 type ErrorLike = string | {code?: ErrorCode | string; message?: string};
 
@@ -40,20 +240,10 @@ function extractCode(error: unknown): string | undefined {
   return undefined;
 }
 
-/**
- * Checks if an error is a user cancellation
- * @param error Error object or error code
- * @returns True if the error represents user cancellation
- */
 export function isUserCancelledError(error: unknown): boolean {
   return extractCode(error) === ErrorCode.UserCancelled;
 }
 
-/**
- * Checks if an error is related to network connectivity
- * @param error Error object or error code
- * @returns True if the error is network-related
- */
 export function isNetworkError(error: unknown): boolean {
   const networkErrors: ErrorCode[] = [
     ErrorCode.NetworkError,
@@ -67,11 +257,6 @@ export function isNetworkError(error: unknown): boolean {
   return !!code && (networkErrors as string[]).includes(code);
 }
 
-/**
- * Checks if an error is recoverable (user can retry)
- * @param error Error object or error code
- * @returns True if the error is potentially recoverable
- */
 export function isRecoverableError(error: unknown): boolean {
   const recoverableErrors: ErrorCode[] = [
     ErrorCode.NetworkError,
@@ -88,11 +273,6 @@ export function isRecoverableError(error: unknown): boolean {
   return !!code && (recoverableErrors as string[]).includes(code);
 }
 
-/**
- * Gets a user-friendly error message for display
- * @param error Error object or error code
- * @returns User-friendly error message
- */
 export function getUserFriendlyErrorMessage(error: ErrorLike): string {
   const errorCode = extractCode(error);
 

package/.copilot-instructions.md

@@ -1,321 +0,0 @@
-# GitHub Copilot Instructions for expo-iap
-
-## Package Manager
-
-**IMPORTANT: This project uses Bun exclusively. Do not suggest npm, yarn, or pnpm commands.**
-
-- Install dependencies: `bun install`
-- Run scripts: `bun run <script>`
-- Run tests: `bun test`
-- Add packages: `bun add <package>`
-- Add dev dependencies: `bun add -d <package>`
-
-**NEVER suggest creating package-lock.json or yarn.lock files. Only bun.lock should exist.**
-
-## Platform-Specific Function Naming
-
-When suggesting code for expo-iap, follow these naming conventions:
-
-### Platform-Specific Functions
-
-Functions that only work on one platform MUST have platform suffixes:
-
-- iOS: `functionNameIOS()`
-- Android: `functionNameAndroid()`
-
-```typescript
-// Correct examples:
-export const getStorefrontIOS = async (): Promise<string> => { ... }
-export const consumeProductAndroid = async (token: string): Promise<void> => { ... }
-export const getAppTransactionIOS = async (): Promise<AppTransactionIOS | null> => { ... }
-```
-
-### Cross-Platform Functions
-
-Functions that abstract platform differences don't need suffixes:
-
-```typescript
-// Correct cross-platform example:
-export const getProducts = async (skus: string[]): Promise<Product[]> => {
-  return Platform.select({
-    ios: async () => {
-      /* iOS implementation */
-    },
-    android: async () => {
-      /* Android implementation */
-    },
-  })();
-};
-```
-
-## Project Overview
-
-This is the **expo-iap** library - a modern React Native/Expo module for handling in-app purchases across iOS and Android platforms. The library provides a unified, TypeScript-first API with automatic type inference and platform abstraction.
-
-## Key Principles
-
-### 🎯 Modern TypeScript-First API
-
-- **Automatic Type Inference**: No manual type casting required
-- **Unified Platform API**: Single API that works across iOS and Android
-- **Consistent Results**: Unified data structure regardless of platform
-- **Clean Error Handling**: Result pattern with detailed error information
-
-### 🚀 Primary API Pattern
-
-```typescript
-const result = await requestPurchase({
-  request: {sku: 'product.id'},
-  type: 'inapp',
-});
-
-if (result.success) {
-  console.log('Purchase successful:', result.transactionId);
-} else {
-  console.error('Purchase failed:', result.error.message);
-}
-```
-
-### 🏗️ Code Style Guidelines
-
-#### TypeScript Best Practices
-
-- **Explicit Type Definitions**: Always define types explicitly for public APIs
-- **Function Overloads**: Provide multiple signatures for better IntelliSense
-- **Discriminated Unions**: Use for platform-specific types and conditional returns
-- **Strict Type Safety**: No `any` types in production code
-
-#### Naming Conventions
-
-- **PascalCase**: Interfaces, types, enums, classes
-- **camelCase**: Functions, variables, methods, properties
-- **kebab-case**: File names (except for React components)
-- **Descriptive Names**: Avoid abbreviations, use clear intent-revealing names
-
-#### Error Handling Pattern
-
-```typescript
-type PurchaseResult<T = unknown> =
-  | {success: true; data: T; platform: 'ios' | 'android'}
-  | {success: false; error: PurchaseError; platform: 'ios' | 'android'};
-```
-
-## API Implementation Patterns
-
-### Core Purchase Functions
-
-```typescript
-export function requestPurchase(params: {
-  readonly request: {sku: string; quantity?: number};
-  readonly type: 'inapp';
-}): Promise<ProductPurchase | ProductPurchase[]>;
-
-export function requestSubscription(params: {
-  readonly request: {sku: string};
-}): Promise<SubscriptionPurchase | SubscriptionPurchase[]>;
-```
-
-### Platform Abstraction
-
-The library automatically handles platform differences:
-
-- **iOS**: Uses `sku` directly with StoreKit
-- **Android**: Converts to Google Play Billing format
-- **Unified Properties**: Both platforms return consistent data
-
-### Type Guards for Advanced Usage
-
-```typescript
-export const isPurchaseResult = (
-  result: unknown,
-): result is ProductPurchase | SubscriptionPurchase => {
-  return (
-    result !== null &&
-    typeof result === 'object' &&
-    'transactionId' in result &&
-    'productId' in result
-  );
-};
-```
-
-## File Organization
-
-```
-src/
-├── index.ts                    # Main exports
-├── ExpoIap.types.ts           # Core type definitions
-├── ExpoIapModule.ts           # Native module interface
-├── useIAP.ts                  # React hook (legacy support)
-├── modules/
-│   ├── android.ts             # Android-specific utilities
-│   └── ios.ts                 # iOS-specific utilities
-└── types/
-    ├── ExpoIapAndroid.types.ts # Android type definitions
-    └── ExpoIapIos.types.ts     # iOS type definitions
-```
-
-## Usage Examples
-
-### Simple Product Purchase
-
-```typescript
-import {requestPurchase} from 'expo-iap';
-
-const handlePurchase = async (productId: string) => {
-  const result = await requestPurchase({
-    request: {sku: productId},
-    type: 'inapp',
-  });
-
-  if (result.success) {
-    console.log('Purchase successful:', result.data);
-  } else {
-    console.error('Purchase failed:', result.error.message);
-  }
-};
-```
-
-### Subscription Purchase
-
-```typescript
-import {requestSubscription} from 'expo-iap';
-
-const handleSubscription = async (subscriptionId: string) => {
-  const result = await requestSubscription({
-    request: {sku: subscriptionId},
-  });
-
-  if (result.success) {
-    console.log('Subscription activated:', result.data);
-  } else {
-    console.error('Subscription failed:', result.error.message);
-  }
-};
-```
-
-## Type Naming
-
-- Platform-specific types: `ProductIOS`, `ProductAndroid`, `PurchaseErrorIOS`
-- Cross-platform types: `Product`, `Purchase`, `PurchaseError`
-
-## Code Suggestions
-
-When generating code:
-
-1. Check if the function is platform-specific
-2. Add appropriate suffix if it only works on one platform
-3. Use Platform.select() for cross-platform implementations
-4. Always use TypeScript
-5. Include proper error handling
-6. Add JSDoc comments for public APIs
-
-## Testing
-
-Suggest tests that:
-
-- Cover both iOS and Android paths
-- Use `bun test` commands
-- Include platform mocking when needed
-- Test error scenarios
-
-## Common Patterns
-
-### Platform Selection
-
-```typescript
-Platform.select({
-  ios: () => {
-    /* iOS code */
-  },
-  android: () => {
-    /* Android code */
-  },
-  default: () => {
-    /* Fallback */
-  },
-});
-```
-
-### Receipt Validation (Platform-specific parameters)
-
-```typescript
-// iOS only needs SKU
-await validateReceiptIos(sku);
-
-// Android needs additional parameters
-await validateReceiptAndroid({
-  packageName,
-  productToken,
-  accessToken,
-});
-```
-
-## Documentation Standards
-
-### Code Comments
-
-- **Document the "why"**, not just the "what"
-- **Explain platform differences** and how they're handled
-- **Provide usage examples** for complex APIs
-- **Use JSDoc format** for all public APIs
-
-### Example Documentation Pattern
-
-````typescript
-/**
- * Enhanced requestPurchase with unified API support
- *
- * This function automatically handles platform differences:
- * - iOS: Uses `sku` directly with StoreKit
- * - Android: Converts to Google Play Billing format
- *
- * @param params - Purchase request parameters
- * @param params.request - Request object with product details
- * @param params.type - Purchase type: 'inapp' for products
- *
- * @returns Promise resolving to purchase result
- *
- * @example
- * ```typescript
- * const result = await requestPurchase({
- *   request: { sku: 'com.example.premium' },
- *   type: 'inapp'
- * });
- * ```
- */
-````
-
-## Development Philosophy
-
-The expo-iap library provides a **world-class developer experience**:
-
-### ✅ Core Achievements
-
-- **🎯 Zero Manual Casting**: Automatic type inference
-- **🌍 Unified API**: Single codebase for iOS and Android
-- **⚡ Enhanced DX**: Better IntelliSense and error messages
-- **🛡️ Full Backward Compatibility**: Existing code continues to work
-- **📚 Modern Patterns**: TypeScript-first, result pattern error handling
-
-### 🎯 When Contributing, Always Consider:
-
-1. **Developer Experience First** - Eliminate manual work and reduce cognitive load
-2. **Platform Differences** - Handle iOS/Android disparities transparently
-3. **Type Safety** - Provide automatic inference with compile-time guarantees
-4. **Documentation Excellence** - Explain the "why" behind solutions
-5. **Backward Compatibility** - Never break existing code
-6. **Performance** - Optimize for common use cases
-7. **Testing** - Comprehensive coverage across platforms and scenarios
-
-### 🚀 Ultimate Goal
-
-Transform in-app purchases from a complex, error-prone process into something as simple as:
-
-```typescript
-const result = await requestPurchase({
-  request: {sku: 'premium.product'},
-  type: 'inapp',
-});
-```
-
-While maintaining full power and flexibility for advanced enterprise use cases.