@idealyst/payments 1.2.108 → 1.2.109

package/src/payments.web.ts

@@ -1,91 +1,70 @@
 // ============================================================================
-// Web Payment Stub
+// Web IAP Stub
 //
-// Native payment sheets (Apple Pay, Google Pay) are mobile-only concepts.
-// On web, use Stripe Elements (@stripe/react-stripe-js) or Stripe Checkout.
-//
-// This stub initializes and reports availability so the hook works,
-// but payment operations throw descriptive errors with guidance.
+// In-App Purchases are a native-only concept (StoreKit / Google Play Billing).
+// This stub allows the hook and types to be imported on web without errors,
+// but all operations throw descriptive errors.
 // ============================================================================
 
 import type {
-  PaymentConfig,
-  PaymentProviderStatus,
-  PaymentMethodAvailability,
-  PaymentSheetRequest,
-  PaymentResult,
+  IAPConfig,
+  IAPProviderStatus,
+  IAPProduct,
+  IAPSubscription,
+  IAPPurchase,
 } from './types';
 import { INITIAL_PROVIDER_STATUS } from './constants';
-import { createPaymentError } from './errors';
-
-const WEB_NOT_SUPPORTED_MESSAGE =
-  '@idealyst/payments does not provide a web payment UI. ' +
-  'Use Stripe Elements (@stripe/react-stripe-js) or Stripe Checkout for web payments.';
+import { createIAPError } from './errors';
 
-const WEB_UNAVAILABLE_METHODS: PaymentMethodAvailability[] = [
-  {
-    type: 'apple_pay',
-    isAvailable: false,
-    unavailableReason: 'Apple Pay requires native iOS integration',
-  },
-  {
-    type: 'google_pay',
-    isAvailable: false,
-    unavailableReason: 'Google Pay requires native Android integration',
-  },
-  {
-    type: 'card',
-    isAvailable: false,
-    unavailableReason:
-      'Use Stripe Elements (@stripe/react-stripe-js) for web card payments',
-  },
-];
+const NOT_SUPPORTED_MESSAGE =
+  'In-App Purchases are only available on native iOS and Android platforms. ' +
+  'For web payments, use a payment processor like Stripe directly.';
 
-let _status: PaymentProviderStatus = { ...INITIAL_PROVIDER_STATUS };
+let _status: IAPProviderStatus = { ...INITIAL_PROVIDER_STATUS };
 
-/**
- * Get the current payment provider status.
- */
-export function getPaymentStatus(): PaymentProviderStatus {
+export function getIAPStatus(): IAPProviderStatus {
   return { ..._status };
 }
 
-/**
- * Initialize — succeeds on web but reports all methods as unavailable.
- */
-export async function initializePayments(
-  _config: PaymentConfig,
-): Promise<void> {
+export async function initializeIAP(_config?: IAPConfig): Promise<void> {
   _status = {
     state: 'ready',
-    availablePaymentMethods: WEB_UNAVAILABLE_METHODS,
-    isPaymentAvailable: false,
+    isStoreAvailable: false,
   };
 }
 
-/**
- * Check availability — all methods are unavailable on web.
- */
-export async function checkPaymentAvailability(): Promise<
-  PaymentMethodAvailability[]
-> {
-  return WEB_UNAVAILABLE_METHODS;
+export async function getProducts(_skus: string[]): Promise<IAPProduct[]> {
+  return [];
+}
+
+export async function getSubscriptions(
+  _skus: string[],
+): Promise<IAPSubscription[]> {
+  return [];
+}
+
+export async function purchaseProduct(_sku: string): Promise<IAPPurchase> {
+  throw createIAPError('not_supported', NOT_SUPPORTED_MESSAGE);
+}
+
+export async function purchaseSubscription(
+  _sku: string,
+  _offerToken?: string,
+): Promise<IAPPurchase> {
+  throw createIAPError('not_supported', NOT_SUPPORTED_MESSAGE);
+}
+
+export async function finishTransaction(
+  _purchase: IAPPurchase,
+  _isConsumable?: boolean,
+): Promise<void> {
+  throw createIAPError('not_supported', NOT_SUPPORTED_MESSAGE);
 }
 
-/**
- * Not supported on web — throws with guidance to use Stripe Elements.
- */
-export async function confirmPayment(
-  _request: PaymentSheetRequest,
-): Promise<PaymentResult> {
-  throw createPaymentError('not_supported', WEB_NOT_SUPPORTED_MESSAGE);
+export async function restorePurchases(): Promise<IAPPurchase[]> {
+  return [];
 }
 
-/**
- * Not supported on web — throws with guidance to use Stripe Elements.
- */
-export async function createPaymentMethod(
-  _request: PaymentSheetRequest,
-): Promise<PaymentResult> {
-  throw createPaymentError('not_supported', WEB_NOT_SUPPORTED_MESSAGE);
+export async function endConnection(): Promise<void> {
+  _status = { ...INITIAL_PROVIDER_STATUS };
 }

package/src/types.ts

@@ -1,179 +1,193 @@
 // ============================================================================
-// Payment Method Types
+// Product Types
 // ============================================================================
 
-export type PaymentMethodType = 'apple_pay' | 'google_pay' | 'card';
-
-export interface PaymentMethodAvailability {
-  /** The payment method type. */
-  type: PaymentMethodType;
-  /** Whether this method is available on the current device. */
-  isAvailable: boolean;
-  /** Reason if unavailable. */
-  unavailableReason?: string;
+export type ProductType = 'iap' | 'sub';
+
+export type ProductPlatform = 'ios' | 'android';
+
+export interface IAPProduct {
+  /** Store-specific product identifier (SKU). */
+  sku: string;
+  /** Product title from the store. */
+  title: string;
+  /** Product description from the store. */
+  description: string;
+  /** Price as a number (e.g., 4.99). */
+  price: number;
+  /** Localized price string (e.g., "$4.99"). */
+  priceFormatted: string;
+  /** ISO 4217 currency code (e.g., "USD"). */
+  currency: string;
+  /** Product type: one-time purchase or subscription. */
+  type: ProductType;
+  /** Platform this product was fetched from. */
+  platform: ProductPlatform;
 }
 
 // ============================================================================
-// Configuration
+// Subscription Types
 // ============================================================================
 
-export interface PaymentConfig {
-  /** Stripe publishable key (pk_test_xxx or pk_live_xxx). */
-  publishableKey: string;
-
-  /**
-   * Apple Pay merchant identifier (e.g., "merchant.com.yourapp").
-   * Required for Apple Pay on iOS.
-   */
-  merchantIdentifier?: string;
-
-  /** Merchant display name shown on the payment sheet. */
-  merchantName: string;
+export type SubscriptionPeriodUnit = 'day' | 'week' | 'month' | 'year';
 
-  /** ISO 3166-1 alpha-2 country code (e.g., "US", "GB"). */
-  merchantCountryCode: string;
+export interface SubscriptionPeriod {
+  /** Time unit. */
+  unit: SubscriptionPeriodUnit;
+  /** Number of units per period (e.g., 1 month, 3 months). */
+  numberOfUnits: number;
+}
 
-  /**
-   * URL scheme for 3D Secure redirects (e.g., "com.yourapp").
-   * Required on native for 3D Secure / bank redirect flows.
-   */
-  urlScheme?: string;
+export type DiscountPaymentMode = 'freeTrial' | 'payAsYouGo' | 'payUpFront';
+export type DiscountType = 'introductory' | 'promotional';
+
+export interface SubscriptionDiscount {
+  /** Discount identifier (promotional only). */
+  identifier?: string;
+  /** Discounted price as a number. */
+  price: number;
+  /** Localized discounted price string. */
+  priceFormatted: string;
+  /** Discount billing period. */
+  period: SubscriptionPeriod;
+  /** How the discount is applied. */
+  paymentMode: DiscountPaymentMode;
+  /** Whether this is introductory or promotional. */
+  type: DiscountType;
+}
 
-  /** Use test environment for Google Pay. Default: false. */
-  testEnvironment?: boolean;
+export interface IAPSubscription extends IAPProduct {
+  /** Subscription billing period. */
+  subscriptionPeriod: SubscriptionPeriod;
+  /** Introductory offer, if any. */
+  introductoryPrice?: SubscriptionDiscount;
+  /** Promotional discounts (iOS). */
+  discounts?: SubscriptionDiscount[];
 }
 
 // ============================================================================
-// Payment Request
+// Purchase Types
 // ============================================================================
 
-export interface PaymentAmount {
-  /** Amount in the smallest currency unit (e.g., cents for USD). */
-  amount: number;
-  /** ISO 4217 currency code (e.g., "usd", "eur"). */
-  currencyCode: string;
+export type PurchaseState = 'purchased' | 'pending' | 'restored';
+
+export interface IAPPurchase {
+  /** Product SKU. */
+  sku: string;
+  /** Store transaction ID. */
+  transactionId: string;
+  /** Transaction timestamp (ms since epoch). */
+  transactionDate: number;
+  /** Receipt data (base64 on iOS, JSON string on Android). */
+  transactionReceipt: string;
+  /** Google Play purchase token (Android only). */
+  purchaseToken?: string;
+  /** Whether the purchase has been acknowledged (Android only). */
+  isAcknowledged?: boolean;
+  /** Current purchase state. */
+  purchaseState: PurchaseState;
 }
 
-export interface PaymentLineItem {
-  /** Label displayed on the payment sheet (e.g., "Subtotal", "Tax"). */
-  label: string;
-  /** Amount in the smallest currency unit. */
-  amount: number;
-}
-
-export interface BillingAddressConfig {
-  /** Whether billing address is required. */
-  isRequired?: boolean;
-  /** Whether phone number is required. */
-  isPhoneNumberRequired?: boolean;
-  /** Address format: 'MIN' for name+postal, 'FULL' for complete address. */
-  format?: 'MIN' | 'FULL';
-}
+// ============================================================================
+// Configuration
+// ============================================================================
 
-export interface PaymentSheetRequest {
+export interface IAPConfig {
   /**
-   * PaymentIntent client secret from your server.
-   * Required for confirmPayment(), not needed for createPaymentMethod().
+   * If true, transactions are automatically finished after purchase.
+   * Default: false.
+   *
+   * WARNING: Set to false in production so you can validate receipts
+   * on your server before finishing transactions.
    */
-  clientSecret?: string;
-
-  /** Total payment amount. Used for display and for createPaymentMethod flow. */
-  amount: PaymentAmount;
-
-  /** Line items displayed on the payment sheet. */
-  lineItems?: PaymentLineItem[];
-
-  /** Billing address requirements. */
-  billingAddress?: BillingAddressConfig;
-
-  /** Preferred payment methods. If empty, all available methods are shown. */
-  allowedPaymentMethods?: PaymentMethodType[];
+  autoFinishTransactions?: boolean;
 }
 
 // ============================================================================
-// Payment Result
+// Provider State
 // ============================================================================
 
-export interface PaymentResult {
-  /** The payment method type that was used. */
-  paymentMethodType: PaymentMethodType;
-
-  /** Stripe payment method ID (pm_xxx). Present for createPaymentMethod flow. */
-  paymentMethodId?: string;
-
-  /** Stripe PaymentIntent ID (pi_xxx). Present for confirmPayment flow. */
-  paymentIntentId?: string;
+export type IAPProviderState =
+  | 'uninitialized'
+  | 'initializing'
+  | 'ready'
+  | 'error';
 
-  /** PaymentIntent status (e.g., 'succeeded', 'requires_capture'). */
-  status?: string;
+export interface IAPProviderStatus {
+  /** Current state of the IAP connection. */
+  state: IAPProviderState;
+  /** Whether the native store is available and connected. */
+  isStoreAvailable: boolean;
+  /** Error if state is 'error'. */
+  error?: IAPError;
 }
 
 // ============================================================================
 // Error Types
 // ============================================================================
 
-export type PaymentErrorCode =
+export type IAPErrorCode =
   | 'not_initialized'
   | 'not_available'
   | 'not_supported'
   | 'user_cancelled'
-  | 'payment_failed'
+  | 'already_owned'
+  | 'purchase_pending'
+  | 'item_unavailable'
   | 'network_error'
-  | 'invalid_config'
-  | 'invalid_request'
-  | 'provider_error'
+  | 'store_error'
   | 'unknown';
 
-export interface PaymentError {
-  code: PaymentErrorCode;
+export interface IAPError {
+  code: IAPErrorCode;
   message: string;
-  /** Original error from the underlying provider. */
+  /** Original error from react-native-iap. */
   originalError?: unknown;
 }
 
-// ============================================================================
-// Provider State
-// ============================================================================
-
-export type PaymentProviderState =
-  | 'uninitialized'
-  | 'initializing'
-  | 'ready'
-  | 'error';
-
-export interface PaymentProviderStatus {
-  state: PaymentProviderState;
-  availablePaymentMethods: PaymentMethodAvailability[];
-  isPaymentAvailable: boolean;
-  error?: PaymentError;
-}
-
 // ============================================================================
 // Hook Types
 // ============================================================================
 
-export interface UsePaymentsOptions {
-  /** If provided, auto-initializes the payment provider. */
-  config?: PaymentConfig;
-  /** Automatically check availability after init. Default: true. */
-  autoCheckAvailability?: boolean;
+export interface UseIAPOptions {
+  /** If provided, auto-initializes the IAP connection. */
+  config?: IAPConfig;
+  /** Product SKUs to auto-fetch after initialization. */
+  productSkus?: string[];
+  /** Subscription SKUs to auto-fetch after initialization. */
+  subscriptionSkus?: string[];
 }
 
-export interface UsePaymentsResult {
+export interface UseIAPResult {
   // State
-  status: PaymentProviderStatus;
+  /** Whether the IAP connection is ready. */
   isReady: boolean;
+  /** Whether a purchase or fetch is in progress. */
   isProcessing: boolean;
-  availablePaymentMethods: PaymentMethodAvailability[];
-  isApplePayAvailable: boolean;
-  isGooglePayAvailable: boolean;
-  isPaymentAvailable: boolean;
-  error: PaymentError | null;
+  /** Current error, if any. */
+  error: IAPError | null;
+  /** Fetched products. */
+  products: IAPProduct[];
+  /** Fetched subscriptions. */
+  subscriptions: IAPSubscription[];
+  /** The most recent purchase (useful for handling post-purchase flows). */
+  currentPurchase: IAPPurchase | null;
 
   // Actions
-  initialize: (config: PaymentConfig) => Promise<void>;
-  checkAvailability: () => Promise<PaymentMethodAvailability[]>;
-  confirmPayment: (request: PaymentSheetRequest) => Promise<PaymentResult>;
-  createPaymentMethod: (request: PaymentSheetRequest) => Promise<PaymentResult>;
+  /** Initialize the IAP connection. */
+  initialize: (config?: IAPConfig) => Promise<void>;
+  /** Fetch products by SKU. */
+  getProducts: (skus: string[]) => Promise<IAPProduct[]>;
+  /** Fetch subscriptions by SKU. */
+  getSubscriptions: (skus: string[]) => Promise<IAPSubscription[]>;
+  /** Purchase a one-time product. */
+  purchaseProduct: (sku: string) => Promise<IAPPurchase>;
+  /** Purchase a subscription. */
+  purchaseSubscription: (sku: string, offerToken?: string) => Promise<IAPPurchase>;
+  /** Finish a transaction (call after server-side validation). */
+  finishTransaction: (purchase: IAPPurchase, isConsumable?: boolean) => Promise<void>;
+  /** Restore previous purchases. */
+  restorePurchases: () => Promise<IAPPurchase[]>;
+  /** Clear the current error. */
   clearError: () => void;
 }