@revenuecat/purchases-js 0.0.11 → 0.0.13

package/README.md

@@ -55,9 +55,10 @@ By downloading the current Offerings you can easily build a Paywall page using t
 associated `rcBillingProduct` and price.
 
 ```typescript
+const appUserId = "the unique id of the user in your systems";
 const purchases = new Purchases("your RC_PUBLISHABLE_API_KEY");
 
-purchases.getOfferings().then((offerings) => {
+purchases.getOfferings(appUserId).then((offerings) => {
   // Get current offering
   console.log(offerings.current);
   // Or a dictionary of all offerings
@@ -127,6 +128,17 @@ const App = () => (
 );
 ```
 
+If you need further information about the user's entitlements, you can use the `getCustomerInfo` method:
+
+```ts
+const customerInfo = await purchases.getCustomerInfo(appUserId);
+```
+
+### Important note
+
+Please be aware that the information about the entitlements can be manipulated by malicious actors, so make sure
+you protect your apps against attacks that modify the entitlements by validating access through your servers.
+
 ## Subscribe a User to an entitlement and allow payment with Stripe
 
 RCBilling allows you to use your payment gateway for payments.
@@ -136,88 +148,28 @@ In this example we will show Stripe, more will be supported soon!
 
 You built your paywall, and your user just clicked on the offer they want to subscribe to.
 
-### 1. Call the .subscribe method to initialise the process
-
 ```tsx
 const purchases = new Purchases("your RC_PUBLISHABLE_API_KEY");
-// You can retrieve this from the offerings you downloaded, as example:
-// offerings.current.packages[0].rcBillingProduct.identifier
-const rcBillingProductIndentifier =
-  "the Product Identifier the user wants to buy";
+// You can retrieve the package from the offerings through `getOfferings`:
+const rcBillingPackage = offerings.current.availablePackages[0];
 const appUserId =
   "the unique id of the user that wants to subscribe to your product";
+const entitlementIdToCheck =
+  "the entitlementId you set up in RC for your product"; // TODO: remove once this is not needed
 
-purchase.subscribe(appUserId, rcBillingProductIndentifier).then((response) => {
-  if (response.nextAction === "collect_payment_info") {
-    // Use the clientSecret to show the StripeElements payment components
-    showStripeElements({
-      setupIntentClientSecret: response.data.clientSecret,
-    });
+purchase.purchasePackage(appUserId, rcBillingPackage).then((response) => {
+  const isEntitled =
+    entitlementIdToCheck in response.customerInfo.entitlements.active;
+  if (isEntitled == true) {
+    console.log(`User ${appUserID} is entitled to ${entitlementId}`);
   } else {
-    // No need to collect payment info, just wait for the entitlement to be granted
+    console.log(
+      `User ${appUserID} is not entitled to ${entitlementId}, even after ${numberOfAttempts} attempts`,
+    );
   }
 });
 ```
 
-### 2. [If nextAction === 'collect_payment_info'] Show the Stripe Elements to collect payment
-
-```tsx
-// Set up stripe as shown in their docs
-const stripePromise = loadStripe(
-  import.meta.env.VITE_RC_STRIPE_PK_KEY as string,
-  { stripeAccount: import.meta.env.VITE_RC_STRIPE_ACCOUNT_ID as string },
-);
-
-// Use the clientSecret obtained in the step 1. Call the .subscribe method to initialise the process
-const PaymentForm = ({ clientSecret }) => {
-  const handleSubmit = async (e: SyntheticEvent) => {
-    e.preventDefault();
-    stripe
-      .confirmSetup({
-        elements,
-        clientSecret,
-        confirmParams: {
-          return_url: `${window.location.origin}/success`,
-        },
-        redirect: "if_required",
-      })
-      .then((response) => {
-        // All is done you can now wait for the entitlement to be granted.
-      });
-  };
-
-  return (
-    <form id="payment-form" onSubmit={handleSubmit}>
-      <PaymentElement id="payment-element" options={paymentElementOptions} />
-    </form>
-  );
-};
-```
-
-### 3. Wait for the entitlement to be granted
-
-You can use the `.waitForEntitlement` method.
-
-```tsx
-const appUserId = "the unique id of the user in your systems";
-const entitlementId = "the entitlementId you set up in RC";
-
-const purchases = new Purchases("your RC_PUBLISHABLE_API_KEY");
-const numberOfAttempts = 10;
-
-purchases
-  .waitForEntitlement(appUserId, entitlementId, numberOfAttempts)
-  .then((isEntitled) => {
-    if (isEntitled == true) {
-      console.log(`User ${appUserID} is entitled to ${entitlementId}`);
-    } else {
-      console.log(
-        `User ${appUserID} is not entitled to ${entitlementId}, even after ${numberOfAttempts} attempts`,
-      );
-    }
-  });
-```
-
 # Development
 
 ## Install the library in a local project
@@ -241,9 +193,38 @@ npm i /path/to/rcbilling-js
 ## Running tests
 
 ```bash
-npm test
+npm run test
+```
+
+## Running linters
+
+```bash
+npm run test:typeCheck
+npm run svelte-check
+npm run prettier
+npm run lint
 ```
 
+## Update API specs
+
+```bash
+npm run extract-api
+```
+
+This will update the files in `api-report` with the latest public API.
+If it has uncommited changes, CI tests will fail. Run this command and commit the changes if
+they are expected.
+
+## Update reference docs
+
+```bash
+npm run generate-docs
+```
+
+This will update the reference docs in the `docs` folder with the latest public API docs.
+If it has uncommited changes, CI tests will fail. Run this command and commit the changes if
+they are expected.
+
 # Publishing a new version
 
 - Update the version in `package.json`

package/dist/Purchases.es.d.ts

@@ -1,93 +1,459 @@
-export declare type CustomerInfo = CustomerInfo_2;
-
-declare interface CustomerInfo_2 {
-    entitlements: EntitlementInfos;
-    managementURL: string | null;
-    requestDate: Date;
-    firstSeenDate: Date;
-    originalPurchaseDate: Date | null;
+/**
+ * Type containing all information regarding the customer.
+ * @public
+ */
+export declare interface CustomerInfo {
+    /**
+     * Entitlements attached to this customer info.
+     */
+    readonly entitlements: EntitlementInfos;
+    /**
+     * Map of productIds to expiration dates.
+     */
+    readonly allExpirationDatesByProduct: {
+        [productIdentifier: string]: Date | null;
+    };
+    /**
+     * Map of productIds to purchase dates.
+     */
+    readonly allPurchaseDatesByProduct: {
+        [productIdentifier: string]: Date;
+    };
+    /**
+     * Set of active subscription product identifiers.
+     */
+    readonly activeSubscriptions: Set<string>;
+    /**
+     * URL to manage the active subscription of the user.
+     * If this user has an active RC Billing subscription, a link to the management page.
+     * If this user has an active iOS subscription, this will point to the App Store.
+     * If the user has an active Play Store subscription it will point there.
+     * If there are no active subscriptions it will be null.
+     */
+    readonly managementURL: string | null;
+    /**
+     * Date when this info was requested.
+     */
+    readonly requestDate: Date;
+    /**
+     * The date this user was first seen in RevenueCat.
+     */
+    readonly firstSeenDate: Date;
+    /**
+     * The purchase date for the version of the application when the user bought the app.
+     * Use this for grandfathering users when migrating to subscriptions. This can be null.
+     */
+    readonly originalPurchaseDate: Date | null;
+    /**
+     * The original App User Id recorded for this user.
+     */
+    readonly originalAppUserId: string;
 }
 
+/**
+ * This object gives you access to all the information about the status
+ * of a user's entitlements.
+ * @public
+ */
 export declare interface EntitlementInfo {
-    identifier: string;
-    isActive: boolean;
-    originalPurchaseDate: Date;
-    expirationDate: Date;
-    productIdentifier: string;
+    /**
+     * The entitlement identifier configured in the RevenueCat dashboard.
+     */
+    readonly identifier: string;
+    /**
+     * True if the user has access to the entitlement.
+     */
+    readonly isActive: boolean;
+    /**
+     * True if the underlying subscription is set to renew at the end of the
+     * billing period (expirationDate). Will always be True if entitlement is
+     * for lifetime access.
+     */
+    readonly willRenew: boolean;
+    /**
+     * The store where this entitlement was unlocked from.
+     */
+    readonly store: Store;
+    /**
+     * The first date this entitlement was purchased.
+     */
+    readonly originalPurchaseDate: Date;
+    /**
+     * The expiration date for the entitlement, can be `null` for lifetime
+     * access. If the {@link EntitlementInfo.periodType} is `trial`, this is the trial
+     * expiration date.
+     */
+    readonly expirationDate: Date | null;
+    /**
+     * The product identifier that unlocked this entitlement.
+     */
+    readonly productIdentifier: string;
+    /**
+     * The date an unsubscribe was detected. Can be `null`.
+     * Note: Entitlement may still be active even if user has unsubscribed.
+     * Check the {@link EntitlementInfo.isActive} property.
+     */
+    readonly unsubscribeDetectedAt: Date | null;
+    /**
+     * The date a billing issue was detected. Can be `null` if there is
+     * no billing issue or an issue has been resolved. Note: Entitlement may
+     * still be active even if there is a billing issue.
+     * Check the `isActive` property.
+     */
+    readonly billingIssueDetectedAt: Date | null;
+    /**
+     * False if this entitlement is unlocked via a production purchase.
+     */
+    readonly isSandbox: boolean;
+    /**
+     * The last period type this entitlement was in.
+     */
+    readonly periodType: PeriodType;
 }
 
+/**
+ * Contains all the entitlements associated to the user.
+ * @public
+ */
 export declare interface EntitlementInfos {
-    all: {
+    /**
+     * Map of all {@link EntitlementInfo} objects (active and inactive) keyed by
+     * entitlement identifier.
+     */
+    readonly all: {
         [entitlementId: string]: EntitlementInfo;
     };
-    active: {
+    /**
+     * Dictionary of active {@link EntitlementInfo} keyed by entitlement identifier.
+     */
+    readonly active: {
         [entitlementId: string]: EntitlementInfo;
     };
 }
 
-export declare type Offering = Offering_2;
-
-declare interface Offering_2 {
-    id: string;
-    identifier: string;
-    displayName: string;
-    packages: Package_2[];
+/**
+ * Error codes for the Purchases SDK.
+ * @public
+ */
+export declare enum ErrorCode {
+    UnknownError = 0,
+    UserCancelledError = 1,
+    StoreProblemError = 2,
+    PurchaseNotAllowedError = 3,
+    PurchaseInvalidError = 4,
+    ProductNotAvailableForPurchaseError = 5,
+    ProductAlreadyPurchasedError = 6,
+    ReceiptAlreadyInUseError = 7,
+    InvalidReceiptError = 8,
+    MissingReceiptFileError = 9,
+    NetworkError = 10,
+    InvalidCredentialsError = 11,
+    UnexpectedBackendResponseError = 12,
+    InvalidAppUserIdError = 14,
+    OperationAlreadyInProgressError = 15,
+    UnknownBackendError = 16,
+    InvalidAppleSubscriptionKeyError = 17,
+    IneligibleError = 18,
+    InsufficientPermissionsError = 19,
+    PaymentPendingError = 20,
+    InvalidSubscriberAttributesError = 21,
+    LogOutWithAnonymousUserError = 22,
+    ConfigurationError = 23,
+    UnsupportedError = 24,
+    EmptySubscriberAttributesError = 25,
+    CustomerInfoError = 28,
+    SignatureVerificationError = 36
 }
 
-export declare type Offerings = Offerings_2;
-
-declare interface Offerings_2 {
-    all: {
-        [offeringId: string]: Offering_2;
+/**
+ * An offering is a collection of {@link Package} available for the user to purchase.
+ * For more info see https://docs.revenuecat.com/docs/entitlements
+ * @public
+ */
+export declare interface Offering {
+    /**
+     * Unique identifier defined in RevenueCat dashboard.
+     */
+    readonly identifier: string;
+    /**
+     * Offering description defined in RevenueCat dashboard.
+     */
+    readonly serverDescription: string;
+    /**
+     * Offering metadata defined in RevenueCat dashboard.
+     */
+    readonly metadata: {
+        [key: string]: unknown;
+    } | null;
+    /**
+     * A map of all the packages available for purchase keyed by package ID.
+     */
+    readonly packagesById: {
+        [key: string]: Package;
     };
-    current: Offering_2 | null;
+    /**
+     * A list of all the packages available for purchase.
+     */
+    readonly availablePackages: Package[];
+    /**
+     * Lifetime package type configured in the RevenueCat dashboard, if available.
+     */
+    readonly lifetimePackage: Package | null;
+    /**
+     * Annual package type configured in the RevenueCat dashboard, if available.
+     */
+    readonly annualPackage: Package | null;
+    /**
+     * Six month package type configured in the RevenueCat dashboard, if available.
+     */
+    readonly sixMonthPackage: Package | null;
+    /**
+     * Three month package type configured in the RevenueCat dashboard, if available.
+     */
+    readonly threeMonthPackage: Package | null;
+    /**
+     * Two month package type configured in the RevenueCat dashboard, if available.
+     */
+    readonly twoMonthPackage: Package | null;
+    /**
+     * Monthly package type configured in the RevenueCat dashboard, if available.
+     */
+    readonly monthlyPackage: Package | null;
+    /**
+     * Weekly package type configured in the RevenueCat dashboard, if available.
+     */
+    readonly weeklyPackage: Package | null;
 }
 
-export declare type Package = Package_2;
-
-declare interface Package_2 {
-    id: string;
-    identifier: string;
-    rcBillingProduct: Product;
+/**
+ * This class contains all the offerings configured in RevenueCat dashboard.
+ * For more info see https://docs.revenuecat.com/docs/entitlements
+ * @public
+ */
+export declare interface Offerings {
+    /**
+     * Dictionary of all {@link Offering} objects keyed by their identifier.
+     */
+    readonly all: {
+        [offeringId: string]: Offering;
+    };
+    /**
+     * Current offering configured in the RevenueCat dashboard.
+     */
+    readonly current: Offering | null;
 }
 
-declare type PaymentProvider = "stripe";
+/**
+ * Contains information about the product available for the user to purchase.
+ * For more info see https://docs.revenuecat.com/docs/entitlements
+ * @public
+ */
+export declare interface Package {
+    /**
+     * Unique identifier for this package. Can be one a predefined package type or a custom one.
+     */
+    readonly identifier: string;
+    /**
+     * The {@link Product} assigned to this package.
+     */
+    readonly rcBillingProduct: Product;
+    /**
+     * The type of package.
+     */
+    readonly packageType: PackageType;
+}
 
-declare type PaymentProviderConfigModels = {
-    stripe?: {
-        publishableKey: string;
-        accountId: string;
-    };
-};
+/**
+ * Enumeration of all possible Package types.
+ * @public
+ */
+export declare enum PackageType {
+    /**
+     * A package that was defined with an unrecognized RC identifier.
+     */
+    Unknown = "unknown",
+    /**
+     * A package that was defined with a custom identifier.
+     */
+    Custom = "custom",
+    /**
+     * A package configured with the predefined lifetime identifier.
+     */
+    Lifetime = "$rc_lifetime",
+    /**
+     * A package configured with the predefined annual identifier.
+     */
+    Annual = "$rc_annual",
+    /**
+     * A package configured with the predefined six month identifier.
+     */
+    SixMonth = "$rc_six_month",
+    /**
+     * A package configured with the predefined three month identifier.
+     */
+    ThreeMonth = "$rc_three_month",
+    /**
+     * A package configured with the predefined two month identifier.
+     */
+    TwoMonth = "$rc_two_month",
+    /**
+     * A package configured with the predefined monthly identifier.
+     */
+    Monthly = "$rc_monthly",
+    /**
+     * A package configured with the predefined weekly identifier.
+     */
+    Weekly = "$rc_weekly"
+}
 
-declare type PaymentProviderSettings = Record<PaymentProvider, PaymentProviderConfigModels[PaymentProvider]>;
+/**
+ * Supported period types for an entitlement.
+ * - "normal" If the entitlement is not under an introductory or trial period.
+ * - "intro" If the entitlement is under an introductory period.
+ * - "trial" If the entitlement is under a trial period.
+ * @public
+ */
+export declare type PeriodType = "normal" | "intro" | "trial";
 
-declare interface Price {
-    amount: number;
-    currency: string;
+/**
+ * Price information for a product.
+ * @public
+ */
+export declare interface Price {
+    /**
+     * Price in full units of the currency.
+     */
+    readonly amount: number;
+    /**
+     * Returns ISO 4217 currency code for price.
+     * For example, if price is specified in British pounds sterling,
+     * currency is "GBP".
+     * If currency code cannot be determined, currency symbol is returned.
+     */
+    readonly currency: string;
 }
 
-declare interface Product {
-    id: string;
-    displayName: string;
-    identifier: string;
-    currentPrice: Price | null;
-    normalPeriodDuration: string | null;
+/**
+ * Represents product's listing details.
+ * @public
+ */
+export declare interface Product {
+    /**
+     * The product ID.
+     */
+    readonly identifier: string;
+    /**
+     * Name of the product.
+     */
+    readonly displayName: string;
+    /**
+     * Price of the product.
+     */
+    readonly currentPrice: Price;
+    /**
+     * The period duration for a subscription product.
+     */
+    readonly normalPeriodDuration: string | null;
+    /**
+     * The offering ID used to obtain this product.
+     */
+    readonly presentedOfferingIdentifier: string;
 }
 
+/**
+ * Entry point for Purchases SDK. It should be instantiated as soon as your
+ * app is started. Only one instance of Purchases should be instantiated
+ * at a time!
+ * @public
+ */
 export declare class Purchases {
-    constructor(apiKey: string, paymentProviderSettings: PaymentProviderSettings);
-    private toOfferings;
+    /**
+     * Constructor for Purchases.
+     * @param apiKey - RevenueCat API Key. Can be obtained from the RevenueCat dashboard.
+     */
+    constructor(apiKey: string);
+    /**
+     * Fetch the configured offerings for this user. You can configure these
+     * in the RevenueCat dashboard.
+     * @param appUserId - Your app's user id in your system.
+     */
     getOfferings(appUserId: string): Promise<Offerings>;
-    isEntitledTo(appUserId: string, entitlementIdentifier: string): Promise<boolean>;
-    purchasePackage(appUserId: string, rcPackage: Package, entitlementId: string, // TODO: Remove this parameter once we don't have to poll for entitlements
-        { customerEmail, htmlTarget, }?: {
-        customerEmail?: string;
-        htmlTarget?: HTMLElement;
-    }): Promise<boolean>;
-    getCustomerInfo(appUserId: string): Promise<CustomerInfo>;
-    private logMissingProductIds;
-    isSandbox(): boolean;
-}
+    /**
+     * Convenience method to check whether a user is entitled to a specific
+     * entitlement. This will use {@link Purchases.getCustomerInfo} under the hood.
+     * @param appUserId - Your app's user id in your system.
+     * @param entitlementIdentifier - The entitlement identifier you want to check.
+     * @returns Whether the user is entitled to the specified entitlement
+     * @throws {@link PurchasesError} if there is an error while fetching the customer info.
+         * @see {@link Purchases.getCustomerInfo}
+         */
+     isEntitledTo(appUserId: string, entitlementIdentifier: string): Promise<boolean>;
+     /**
+      * Method to perform a purchase for a given package. You can obtain the
+      * package from {@link Purchases.getOfferings}. This method will present the purchase
+      * form on your site, using the given HTML element as the mount point, if
+      * provided, or as a modal if not.
+      * @param appUserId - Your app's user id in your system.
+      * @param rcPackage - The package you want to purchase. Obtained from {@link Purchases.getOfferings}.
+      * @param customerEmail - The email of the user. If null, RevenueCat will ask the customer for their email.
+      * @param htmlTarget - The HTML element where the billing view should be added. If null, a new div will be created at the root of the page and appended to the body.
+      * @returns The customer info after the purchase is completed successfuly.
+      * @throws {@link PurchasesError} if there is an error while performing the purchase. If the {@link PurchasesError.errorCode} is {@link ErrorCode.UserCancelledError}, the user cancelled the purchase.
+          */
+      purchasePackage(appUserId: string, rcPackage: Package, customerEmail?: string, htmlTarget?: HTMLElement): Promise<{
+          customerInfo: CustomerInfo;
+      }>;
+      /**
+       * Gets latest available {@link CustomerInfo}.
+       * @param appUserId - Your app's user id in your system.
+       * @returns The latest {@link CustomerInfo}.
+       * @throws {@link PurchasesError} if there is an error while fetching the customer info.
+           */
+       getCustomerInfo(appUserId: string): Promise<CustomerInfo>;
+       /**
+        * @returns Whether the SDK is using a sandbox API Key.
+        */
+       isSandbox(): boolean;
+      }
+
+      /**
+       * Error class for Purchases SDK. You should handle these errors and react
+       * accordingly in your app.
+       * @public
+       */
+      export declare class PurchasesError extends Error {
+          /**
+           * Error code for the error. This is useful to appropriately react to
+           * different error situations.
+           */
+          readonly errorCode: ErrorCode;
+          /**
+           * Underlying error message. This provides more details on the error and
+           * can be useful for debugging and logging.
+           */
+          readonly underlyingErrorMessage?: string | null | undefined;
+          constructor(
+          /**
+           * Error code for the error. This is useful to appropriately react to
+           * different error situations.
+           */
+          errorCode: ErrorCode, 
+          /**
+           * Message for the error. This is useful for debugging and logging.
+           */
+          message?: string, 
+          /**
+           * Underlying error message. This provides more details on the error and
+           * can be useful for debugging and logging.
+           */
+          underlyingErrorMessage?: string | null | undefined);
+          toString: () => string;
+      }
+
+      /**
+       * The store where the user originally subscribed.
+       * @public
+       */
+      export declare type Store = "app_store" | "mac_app_store" | "play_store" | "amazon" | "stripe" | "rc_billing" | "promotional" | "unknown";
 
-export { }
+      export { }