iap-apple 2.0.5 → 3.0.1

package/README.md

@@ -1,6 +1,6 @@
 | Statements                  | Branches                | Functions                 | Lines             |
 | --------------------------- | ----------------------- | ------------------------- | ----------------- |
-| ![Statements](https://img.shields.io/badge/statements-76.97%25-red.svg?style=flat) | ![Branches](https://img.shields.io/badge/branches-47.96%25-red.svg?style=flat) | ![Functions](https://img.shields.io/badge/functions-75%25-red.svg?style=flat) | ![Lines](https://img.shields.io/badge/lines-75%25-red.svg?style=flat) |
+| ![Statements](https://img.shields.io/badge/statements-93.54%25-brightgreen.svg?style=flat) | ![Branches](https://img.shields.io/badge/branches-82.92%25-yellow.svg?style=flat) | ![Functions](https://img.shields.io/badge/functions-93.75%25-brightgreen.svg?style=flat) | ![Lines](https://img.shields.io/badge/lines-93.16%25-brightgreen.svg?style=flat) |
 
 # iap-apple
 
@@ -8,173 +8,183 @@
 ![https://img.shields.io/github/issues-raw/ssbarbee/iap-apple](https://img.shields.io/github/issues-raw/ssbarbee/iap-apple)
 ![https://img.shields.io/npm/dw/iap-apple](https://img.shields.io/npm/dw/iap-apple)
 
-📦🚀 Integration of Apples  **validation service** for App Store Receipts, written in Typescript, available for NodeJS environments.
+Integration of Apple's **validation service** for App Store Receipts, written in TypeScript, available for Node.js environments.
 
-A NodeJS module for in-app purchase (in-app billing) and subscription for Apple.
+A Node.js module for in-app purchase (in-app billing) and subscription validation for Apple.
 
-## Overview 🧐
+## Requirements
 
-Create a Typescript package for validation of [App Store Receipts](https://developer.apple.com/documentation/appstorereceipts).  
-This package is meant to be used server side to validate receipts from the App Store by talking to Apples servers.
+- **Node.js 22+** (uses native `fetch`, zero runtime dependencies)
 
-## Installation 📦
+## Overview
+
+Server-side validation of [App Store Receipts](https://developer.apple.com/documentation/appstorereceipts) by communicating with Apple's verifyReceipt endpoints.
+
+## Installation
+
+### pnpm
+
+```bash
+pnpm add iap-apple
+```
 
 ### npm
 
-```npm install iap-apple```
+```bash
+npm install iap-apple
+```
 
 ### yarn
 
-```yarn add iap-apple```
+```bash
+yarn add iap-apple
+```
 
-## API documentation 📚
+## API Documentation
 
-### verify 🧪
+### verify
 
-API used to verify receipt data received during an App Store purchase.
-Requires **appSharedSecret** to be passed as part of the configuration.
-See example for more details.
+Validates a receipt against Apple's verifyReceipt endpoint. Attempts production first, falls back to sandbox if needed.
 
 ```typescript
-
 import { verify, IAPAppleError, IVerifyReceiptResponseBody } from 'iap-apple';
 
 async function verifyAppleReceipt(receipt: string) {
-    try {
-        const verifyReceiptResponse = await verify(receipt, { 
-            /*
-              Your app's shared secret, which is a hexadecimal string. For more information about the shared secret.
-              https://help.apple.com/app-store-connect/#/devf341c0f01
-            */
-            appSharedSecret, 
-            /*
-              To exclude old transaction, set this to true. 
-              Default is false.
-            */
-            excludeOldTransactions: false,
-            /*
-              Force validation against Apple Sandbox only.
-              In effect this means that the validation against Apple Production endpoint won't be used.
-              Default is false.
-            */
-            test: false,
-            /* 
-              Optional can be omitted, pass logger object if you want to debug.
-              Default is null object.
-            */
-            logger: console,
-        });
-        console.log('verifyReceiptResponse', verifyReceiptResponse);
-    } catch(error) {
-        const iapAppleError = error as IAPAppleError;
-        const rejectionMessage: string = error.rejectionMessage;
-        const errorData: IVerifyReceiptResponseBody | null = error.data;
-        console.error('Error happened', rejectionMessage);
-        console.error('Details', errorData);
-    }
+  try {
+    const verifyReceiptResponse = await verify(receipt, {
+      // Required: Your app's shared secret (hexadecimal string)
+      // https://help.apple.com/app-store-connect/#/devf341c0f01
+      appSharedSecret: 'your-shared-secret',
+
+      // Optional: Exclude old transactions (default: false)
+      appleExcludeOldTransactions: false,
+
+      // Optional: Force sandbox-only validation (default: false)
+      test: false,
+
+      // Optional: Logger for debugging (default: null)
+      logger: console,
+    });
+    console.log('verifyReceiptResponse', verifyReceiptResponse);
+  } catch (error) {
+    const iapAppleError = error as IAPAppleError;
+    console.error('Error:', iapAppleError.rejectionMessage);
+    console.error('Details:', iapAppleError.data);
+  }
 }
 ```
 
-### isVerifiedReceipt 🧪
+### isVerifiedReceipt
 
-API used to verify if response returned by `verify` is verified.
-Requires the output of `verify` to be passed.
-See example for more details.
+Checks if the response from `verify` indicates a successful validation.
 
 ```typescript
-
 import { verify, isVerifiedReceipt, IIAPAppleConfig } from 'iap-apple';
 
-async function isVerifiedAppleReceipt(receipt: string, config: IIAPAppleConfig) {
-    try {
-        const verifyReceiptResponse = await verify(receipt, config);
-        const isVerifiedReceipt = isVerifiedReceipt(verifyReceiptResponse);
-    } catch(error) {
-        const iapAppleError = error as IAPAppleError;
-        const rejectionMessage: string = error.rejectionMessage;
-        const errorData: IVerifyReceiptResponseBody | null = error.data;
-        console.error('Error happened', rejectionMessage);
-        console.error('Details', errorData);
+async function checkReceipt(receipt: string, config: IIAPAppleConfig) {
+  try {
+    const response = await verify(receipt, config);
+    if (isVerifiedReceipt(response)) {
+      console.log('Receipt is valid');
     }
+  } catch (error) {
+    console.error('Validation failed:', (error as IAPAppleError).rejectionMessage);
+  }
 }
 ```
 
-### getPurchasedItems 🧪
+### getPurchasedItems
 
-API used to get an array of PurchasedItem objects from the Apple App Store response,
-sort by their purchase date descending.
-Usually what we are interested in is the first item of the purchase.
-Requires the output of `verify` to be passed.
-See example for more details.
+Extracts purchased items from the validated receipt, sorted by purchase date (newest first), deduplicated by `original_transaction_id`.
 
 ```typescript
-
 import { verify, getPurchasedItems, IIAPAppleConfig } from 'iap-apple';
 
-async function isVerifiedAppleReceipt(receipt: string, config: IIAPAppleConfig) {
-    try {
-        const verifyReceiptResponse = await verify(receipt, config);
-        const purchasedItems = getPurchasedItems(verifyReceiptResponse);
-        const latestPurchase = purchasedItems[0];
-    } catch(error) {
-        const iapAppleError = error as IAPAppleError;
-        const rejectionMessage: string = error.rejectionMessage;
-        const errorData: IVerifyReceiptResponseBody | null = error.data;
-        console.error('Error happened', rejectionMessage);
-        console.error('Details', errorData);
-    }
+async function getLatestPurchase(receipt: string, config: IIAPAppleConfig) {
+  try {
+    const response = await verify(receipt, config);
+    const purchasedItems = getPurchasedItems(response);
+    const latestPurchase = purchasedItems[0];
+    console.log('Latest purchase:', latestPurchase);
+  } catch (error) {
+    console.error('Error:', (error as IAPAppleError).rejectionMessage);
+  }
 }
 ```
 
-### isPurchasedItemCanceled 🧪
+### isPurchasedItemCanceled
 
-API used to check if a purchased item is canceled.
-Requires the output of `getPurchasedItems` to be passed.
-See example for more details.
+Checks if a purchased item has been canceled.
 
 ```typescript
-
 import { verify, getPurchasedItems, isPurchasedItemCanceled, IIAPAppleConfig } from 'iap-apple';
 
-async function isVerifiedAppleReceipt(receipt: string, config: IIAPAppleConfig) {
-    try {
-        const verifyReceiptResponse = await verify(receipt, config);
-        const purchasedItems = getPurchasedItems(verifyReceiptResponse);
-        const latestPurchase = purchasedItems[0];
-        const isCanceled = isPurchasedItemCanceled(latestPurchase);
-    } catch(error) {
-        const iapAppleError = error as IAPAppleError;
-        const rejectionMessage: string = error.rejectionMessage;
-        const errorData: IVerifyReceiptResponseBody | null = error.data;
-        console.error('Error happened', rejectionMessage);
-        console.error('Details', errorData);
+async function checkCancellation(receipt: string, config: IIAPAppleConfig) {
+  try {
+    const response = await verify(receipt, config);
+    const purchasedItems = getPurchasedItems(response);
+    const latestPurchase = purchasedItems[0];
+    if (isPurchasedItemCanceled(latestPurchase)) {
+      console.log('Purchase was canceled');
     }
+  } catch (error) {
+    console.error('Error:', (error as IAPAppleError).rejectionMessage);
+  }
 }
 ```
 
+### isPurchasedItemExpired
 
-### isPurchasedItemExpired 🧪
-
-API used to check if a purchased item is expired.
-Requires the output of `getPurchasedItems` to be passed.
-See example for more details.
+Checks if a purchased item has expired (canceled or past expiration date).
 
 ```typescript
-
 import { verify, getPurchasedItems, isPurchasedItemExpired, IIAPAppleConfig } from 'iap-apple';
 
-async function isVerifiedAppleReceipt(receipt: string, config: IIAPAppleConfig) {
-    try {
-        const verifyReceiptResponse = await verify(receipt, config);
-        const purchasedItems = getPurchasedItems(verifyReceiptResponse);
-        const latestPurchase = purchasedItems[0];
-        const isExpired = isPurchasedItemExpired(latestPurchase);
-    } catch(error) {
-        const iapAppleError = error as IAPAppleError;
-        const rejectionMessage: string = error.rejectionMessage;
-        const errorData: IVerifyReceiptResponseBody | null = error.data;
-        console.error('Error happened', rejectionMessage);
-        console.error('Details', errorData);
+async function checkExpiration(receipt: string, config: IIAPAppleConfig) {
+  try {
+    const response = await verify(receipt, config);
+    const purchasedItems = getPurchasedItems(response);
+    const latestPurchase = purchasedItems[0];
+    if (isPurchasedItemExpired(latestPurchase)) {
+      console.log('Purchase has expired');
     }
+  } catch (error) {
+    console.error('Error:', (error as IAPAppleError).rejectionMessage);
+  }
 }
-```
+```
+
+## Types
+
+### PurchasedItem
+
+```typescript
+interface PurchasedItem {
+  bundleId: string;
+  appItemId: string;
+  originalTransactionId?: string;
+  transactionId: string;
+  productId: string;
+  originalPurchaseDateMS?: number;
+  expirationDateMS?: number;
+  purchaseDateMS: number;
+  isTrialPeriod: boolean;
+  cancellationDateMS?: number;
+  quantity: number;
+}
+```
+
+### IIAPAppleConfig
+
+```typescript
+interface IIAPAppleConfig {
+  appSharedSecret: string;
+  appleExcludeOldTransactions?: boolean;
+  test?: boolean;
+  logger?: ILogger | null;
+}
+```
+
+## License
+
+ISC

package/dist/index.d.mts

@@ -0,0 +1,146 @@
+declare enum RECEIPT_STATUS_ENUM {
+    SUCCESS = 0,
+    VALID_NO_PURCHASE = 2,
+    CANNOT_READ_JSON = 21000,
+    DATA_MALFORMED = 21002,
+    RECEIPT_NOT_AUTHENTICATED = 21003,
+    SHARED_SECRET_DOESNT_MATCH = 21004,
+    SERVER_NOT_AVAILABLE = 21005,
+    SUBSCRIPTION_EXPIRED = 21006,
+    TEST_ENV_RECEIPT_DETECTED = 21007,
+    PRODUCTION_ENV_RECEIPT_DETECTED = 21008,
+    INTERNAL_DATA_ACCESS_ERROR = 21009,
+    USER_ACCOUNT_DELETED = 21010
+}
+
+interface IPendingRenewalInfo {
+    auto_renew_product_id: string;
+    auto_renew_status: '0' | '1';
+    original_transaction_id: string;
+    product_id: string;
+    expiration_intent?: '1' | '2' | '3' | '4' | '5';
+    grace_period_expires_date_ms?: string;
+    is_in_billing_retry_period?: '0' | '1';
+    offer_code_ref_name?: string;
+    price_consent_status?: '0' | '1';
+    promotional_offer_id?: string;
+}
+interface IReceiptInAppItem {
+    quantity: string;
+    product_id: string;
+    transaction_id: string;
+    original_transaction_id: string;
+    purchase_date: string;
+    purchase_date_ms: string;
+    original_purchase_date: string;
+    original_purchase_date_ms: string;
+    expires_date?: string;
+    expires_date_ms?: string;
+    expiration_intent?: '1' | '2' | '3' | '4' | '5';
+    is_trial_period: string;
+    cancellation_date?: string;
+    cancellation_date_ms?: string;
+    cancellation_reason?: '0' | '1';
+    app_item_id: string;
+    web_order_line_item_id?: string;
+    is_in_intro_offer_period?: string;
+    promotional_offer_id?: string;
+    offer_code_ref_name?: string;
+    in_app_ownership_type?: 'FAMILY_SHARED' | 'PURCHASED';
+}
+
+interface ILogger {
+    log: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+}
+interface IIAPAppleConfig {
+    appleExcludeOldTransactions?: boolean;
+    appSharedSecret: string;
+    test?: boolean | undefined;
+    logger?: ILogger | null;
+}
+interface PurchasedItem {
+    bundleId: string;
+    appItemId: string;
+    originalTransactionId?: string;
+    transactionId: string;
+    productId: string;
+    originalPurchaseDateMS?: number;
+    expirationDateMS?: number;
+    purchaseDateMS: number;
+    isTrialPeriod: boolean;
+    cancellationDateMS?: number;
+    quantity: number;
+}
+interface IAPAppleError {
+    rejectionMessage: string;
+    data?: IVerifyReceiptResponseBody | null;
+}
+interface IVerifyReceiptResponseBody {
+    status: RECEIPT_STATUS_ENUM;
+    environment: 'Sandbox' | 'Production';
+    receipt: IReceipt;
+    latest_receipt: string;
+    latest_receipt_info: IReceiptInAppItem[];
+    'is-retryable'?: boolean;
+    pending_renewal_info?: IPendingRenewalInfo[];
+}
+interface IReceipt {
+    bundle_id: string;
+    application_version: string;
+    in_app: IReceiptInAppItem[];
+    latest_receipt_info: IReceiptInAppItem[];
+    original_application_version: string;
+    receipt_creation_date_ms: string;
+    expiration_date_ms: string;
+    original_purchase_date: string;
+    app_item_id: string;
+    version_external_identifier: string;
+    expires_date_ms?: string;
+}
+
+/**
+ * Validates an Apple App Store receipt against Apple's verifyReceipt endpoint.
+ * Attempts production endpoint first, falls back to sandbox if needed.
+ *
+ * @param receipt - Base64-encoded receipt data from the App Store
+ * @param config - Configuration including shared secret and optional settings
+ * @returns Validated receipt response from Apple
+ * @throws {IAPAppleError} When validation fails or receipt is invalid
+ */
+declare function verify(receipt: string, config: IIAPAppleConfig): Promise<IVerifyReceiptResponseBody>;
+/**
+ * Checks whether the receipt validation was successful.
+ *
+ * @param verifyReceiptResponse - Response from Apple's verifyReceipt endpoint
+ * @returns True if the receipt status indicates success
+ */
+declare const isVerifiedReceipt: (verifyReceiptResponse: IVerifyReceiptResponseBody | null) => boolean;
+/**
+ * Determines if a purchased item has expired (cancelled or past expiration date).
+ *
+ * @param purchasedItem - The purchased item to check
+ * @returns True if the item has been cancelled or its expiration date has passed
+ * @throws {Error} If purchasedItem is invalid or missing transactionId
+ */
+declare const isPurchasedItemExpired: (purchasedItem: PurchasedItem | null) => boolean;
+/**
+ * Checks if a purchased item has been cancelled.
+ *
+ * @param purchasedItem - The purchased item to check
+ * @returns True if the item has a cancellation date
+ * @throws {Error} If purchasedItem is invalid or missing transactionId
+ */
+declare const isPurchasedItemCanceled: (purchasedItem: PurchasedItem) => boolean;
+/**
+ * Extracts purchased items from a validated receipt response.
+ * Combines in_app and latest_receipt_info, deduplicates by original_transaction_id,
+ * and returns items sorted by purchase date (newest first).
+ *
+ * @param verifyReceiptResponse - Response from Apple's verifyReceipt endpoint
+ * @returns Array of purchased items, deduplicated and sorted by purchase date descending
+ */
+declare const getPurchasedItems: (verifyReceiptResponse: IVerifyReceiptResponseBody | null) => PurchasedItem[];
+
+export { type IAPAppleError, type IIAPAppleConfig, type ILogger, type IPendingRenewalInfo, type IReceiptInAppItem, type IVerifyReceiptResponseBody, type PurchasedItem, RECEIPT_STATUS_ENUM, getPurchasedItems, isPurchasedItemCanceled, isPurchasedItemExpired, isVerifiedReceipt, verify };

package/dist/index.d.ts

@@ -0,0 +1,146 @@
+declare enum RECEIPT_STATUS_ENUM {
+    SUCCESS = 0,
+    VALID_NO_PURCHASE = 2,
+    CANNOT_READ_JSON = 21000,
+    DATA_MALFORMED = 21002,
+    RECEIPT_NOT_AUTHENTICATED = 21003,
+    SHARED_SECRET_DOESNT_MATCH = 21004,
+    SERVER_NOT_AVAILABLE = 21005,
+    SUBSCRIPTION_EXPIRED = 21006,
+    TEST_ENV_RECEIPT_DETECTED = 21007,
+    PRODUCTION_ENV_RECEIPT_DETECTED = 21008,
+    INTERNAL_DATA_ACCESS_ERROR = 21009,
+    USER_ACCOUNT_DELETED = 21010
+}
+
+interface IPendingRenewalInfo {
+    auto_renew_product_id: string;
+    auto_renew_status: '0' | '1';
+    original_transaction_id: string;
+    product_id: string;
+    expiration_intent?: '1' | '2' | '3' | '4' | '5';
+    grace_period_expires_date_ms?: string;
+    is_in_billing_retry_period?: '0' | '1';
+    offer_code_ref_name?: string;
+    price_consent_status?: '0' | '1';
+    promotional_offer_id?: string;
+}
+interface IReceiptInAppItem {
+    quantity: string;
+    product_id: string;
+    transaction_id: string;
+    original_transaction_id: string;
+    purchase_date: string;
+    purchase_date_ms: string;
+    original_purchase_date: string;
+    original_purchase_date_ms: string;
+    expires_date?: string;
+    expires_date_ms?: string;
+    expiration_intent?: '1' | '2' | '3' | '4' | '5';
+    is_trial_period: string;
+    cancellation_date?: string;
+    cancellation_date_ms?: string;
+    cancellation_reason?: '0' | '1';
+    app_item_id: string;
+    web_order_line_item_id?: string;
+    is_in_intro_offer_period?: string;
+    promotional_offer_id?: string;
+    offer_code_ref_name?: string;
+    in_app_ownership_type?: 'FAMILY_SHARED' | 'PURCHASED';
+}
+
+interface ILogger {
+    log: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+}
+interface IIAPAppleConfig {
+    appleExcludeOldTransactions?: boolean;
+    appSharedSecret: string;
+    test?: boolean | undefined;
+    logger?: ILogger | null;
+}
+interface PurchasedItem {
+    bundleId: string;
+    appItemId: string;
+    originalTransactionId?: string;
+    transactionId: string;
+    productId: string;
+    originalPurchaseDateMS?: number;
+    expirationDateMS?: number;
+    purchaseDateMS: number;
+    isTrialPeriod: boolean;
+    cancellationDateMS?: number;
+    quantity: number;
+}
+interface IAPAppleError {
+    rejectionMessage: string;
+    data?: IVerifyReceiptResponseBody | null;
+}
+interface IVerifyReceiptResponseBody {
+    status: RECEIPT_STATUS_ENUM;
+    environment: 'Sandbox' | 'Production';
+    receipt: IReceipt;
+    latest_receipt: string;
+    latest_receipt_info: IReceiptInAppItem[];
+    'is-retryable'?: boolean;
+    pending_renewal_info?: IPendingRenewalInfo[];
+}
+interface IReceipt {
+    bundle_id: string;
+    application_version: string;
+    in_app: IReceiptInAppItem[];
+    latest_receipt_info: IReceiptInAppItem[];
+    original_application_version: string;
+    receipt_creation_date_ms: string;
+    expiration_date_ms: string;
+    original_purchase_date: string;
+    app_item_id: string;
+    version_external_identifier: string;
+    expires_date_ms?: string;
+}
+
+/**
+ * Validates an Apple App Store receipt against Apple's verifyReceipt endpoint.
+ * Attempts production endpoint first, falls back to sandbox if needed.
+ *
+ * @param receipt - Base64-encoded receipt data from the App Store
+ * @param config - Configuration including shared secret and optional settings
+ * @returns Validated receipt response from Apple
+ * @throws {IAPAppleError} When validation fails or receipt is invalid
+ */
+declare function verify(receipt: string, config: IIAPAppleConfig): Promise<IVerifyReceiptResponseBody>;
+/**
+ * Checks whether the receipt validation was successful.
+ *
+ * @param verifyReceiptResponse - Response from Apple's verifyReceipt endpoint
+ * @returns True if the receipt status indicates success
+ */
+declare const isVerifiedReceipt: (verifyReceiptResponse: IVerifyReceiptResponseBody | null) => boolean;
+/**
+ * Determines if a purchased item has expired (cancelled or past expiration date).
+ *
+ * @param purchasedItem - The purchased item to check
+ * @returns True if the item has been cancelled or its expiration date has passed
+ * @throws {Error} If purchasedItem is invalid or missing transactionId
+ */
+declare const isPurchasedItemExpired: (purchasedItem: PurchasedItem | null) => boolean;
+/**
+ * Checks if a purchased item has been cancelled.
+ *
+ * @param purchasedItem - The purchased item to check
+ * @returns True if the item has a cancellation date
+ * @throws {Error} If purchasedItem is invalid or missing transactionId
+ */
+declare const isPurchasedItemCanceled: (purchasedItem: PurchasedItem) => boolean;
+/**
+ * Extracts purchased items from a validated receipt response.
+ * Combines in_app and latest_receipt_info, deduplicates by original_transaction_id,
+ * and returns items sorted by purchase date (newest first).
+ *
+ * @param verifyReceiptResponse - Response from Apple's verifyReceipt endpoint
+ * @returns Array of purchased items, deduplicated and sorted by purchase date descending
+ */
+declare const getPurchasedItems: (verifyReceiptResponse: IVerifyReceiptResponseBody | null) => PurchasedItem[];
+
+export { type IAPAppleError, type IIAPAppleConfig, type ILogger, type IPendingRenewalInfo, type IReceiptInAppItem, type IVerifyReceiptResponseBody, type PurchasedItem, RECEIPT_STATUS_ENUM, getPurchasedItems, isPurchasedItemCanceled, isPurchasedItemExpired, isVerifiedReceipt, verify };