@revenuecat/purchases-js 0.0.12 → 0.0.14

package/README.md

@@ -151,7 +151,7 @@ You built your paywall, and your user just clicked on the offer they want to sub
 ```tsx
 const purchases = new Purchases("your RC_PUBLISHABLE_API_KEY");
 // You can retrieve the package from the offerings through `getOfferings`:
-const rcBillingPackage = offerings.current.packages[0];
+const rcBillingPackage = offerings.current.availablePackages[0];
 const appUserId =
   "the unique id of the user that wants to subscribe to your product";
 const entitlementIdToCheck =
@@ -193,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,68 +1,140 @@
-declare enum BackendErrorCode {
-    BackendInvalidPlatform = 7000,
-    BackendStoreProblem = 7101,
-    BackendCannotTransferPurchase = 7102,
-    BackendInvalidReceiptToken = 7103,
-    BackendInvalidAppStoreSharedSecret = 7104,
-    BackendInvalidPaymentModeOrIntroPriceNotProvided = 7105,
-    BackendProductIdForGoogleReceiptNotProvided = 7106,
-    BackendInvalidPlayStoreCredentials = 7107,
-    BackendInternalServerError = 7110,
-    BackendEmptyAppUserId = 7220,
-    BackendInvalidAuthToken = 7224,
-    BackendInvalidAPIKey = 7225,
-    BackendBadRequest = 7226,
-    BackendPlayStoreQuotaExceeded = 7229,
-    BackendPlayStoreInvalidPackageName = 7230,
-    BackendPlayStoreGenericError = 7231,
-    BackendUserIneligibleForPromoOffer = 7232,
-    BackendInvalidAppleSubscriptionKey = 7234,
-    BackendInvalidSubscriberAttributes = 7263,
-    BackendInvalidSubscriberAttributesBody = 7264,
-    BackendProductIDsMalformed = 7662
-}
-
-export declare type CustomerInfo = CustomerInfo_2;
-
-declare interface CustomerInfo_2 {
+/**
+ * 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 {
+    /**
+     * 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 {
+    /**
+     * Map of all {@link EntitlementInfo} objects (active and inactive) keyed by
+     * entitlement identifier.
+     */
     readonly all: {
         [entitlementId: string]: EntitlementInfo;
     };
+    /**
+     * Dictionary of active {@link EntitlementInfo} keyed by entitlement identifier.
+     */
     readonly active: {
         [entitlementId: string]: EntitlementInfo;
     };
 }
 
+/**
+ * Error codes for the Purchases SDK.
+ * @public
+ */
 export declare enum ErrorCode {
     UnknownError = 0,
     UserCancelledError = 1,
@@ -93,115 +165,295 @@ export declare enum ErrorCode {
     SignatureVerificationError = 36
 }
 
-export declare type Offering = Offering_2;
-
-declare interface Offering_2 {
-    readonly id: string;
+/**
+ * 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;
-    readonly displayName: string;
+    /**
+     * Offering description defined in RevenueCat dashboard.
+     */
+    readonly serverDescription: string;
+    /**
+     * Offering metadata defined in RevenueCat dashboard.
+     */
     readonly metadata: {
         [key: string]: unknown;
     } | null;
-    readonly packages: {
-        [key: string]: Package_2;
+    /**
+     * A map of all the packages available for purchase keyed by package ID.
+     */
+    readonly packagesById: {
+        [key: string]: Package;
     };
-    readonly lifetimePackage: Package_2 | null;
-    readonly annualPackage: Package_2 | null;
-    readonly sixMonthPackage: Package_2 | null;
-    readonly threeMonthPackage: Package_2 | null;
-    readonly twoMonthPackage: Package_2 | null;
-    readonly monthlyPackage: Package_2 | null;
-    readonly weeklyPackage: Package_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 lifetime: Package | null;
+    /**
+     * Annual package type configured in the RevenueCat dashboard, if available.
+     */
+    readonly annual: Package | null;
+    /**
+     * Six month package type configured in the RevenueCat dashboard, if available.
+     */
+    readonly sixMonth: Package | null;
+    /**
+     * Three month package type configured in the RevenueCat dashboard, if available.
+     */
+    readonly threeMonth: Package | null;
+    /**
+     * Two month package type configured in the RevenueCat dashboard, if available.
+     */
+    readonly twoMonth: Package | null;
+    /**
+     * Monthly package type configured in the RevenueCat dashboard, if available.
+     */
+    readonly monthly: Package | null;
+    /**
+     * Weekly package type configured in the RevenueCat dashboard, if available.
+     */
+    readonly weekly: Package | null;
 }
 
-export declare type Offerings = Offerings_2;
-
-declare interface Offerings_2 {
+/**
+ * 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_2;
+        [offeringId: string]: Offering;
     };
-    readonly current: Offering_2 | null;
+    /**
+     * Current offering configured in the RevenueCat dashboard.
+     */
+    readonly current: Offering | null;
 }
 
-export declare type Package = Package_2;
-
-declare interface Package_2 {
-    readonly id: string;
+/**
+ * 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 enum PackageType {
+/**
+ * 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"
 }
 
+/**
+ * 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 {
+/**
+ * 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 {
-    readonly id: string;
-    readonly displayName: string;
+/**
+ * Represents product's listing details.
+ * @public
+ */
+export declare interface Product {
+    /**
+     * The product ID.
+     */
     readonly identifier: string;
-    readonly currentPrice: Price | null;
+    /**
+     * 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;
 }
 
-declare class PurchaseFlowError extends Error {
-    readonly errorCode: PurchaseFlowErrorCode;
-    readonly underlyingErrorMessage?: string | null | undefined;
-    constructor(errorCode: PurchaseFlowErrorCode, message?: string, underlyingErrorMessage?: string | null | undefined);
-}
-
-declare enum PurchaseFlowErrorCode {
-    ErrorSettingUpPurchase = 0,
-    ErrorChargingPayment = 1,
-    UnknownError = 2,
-    NetworkError = 3,
-    StripeError = 4,
-    MissingEmailError = 5
-}
-
+/**
+ * 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 {
-    private readonly backend;
-    private readonly purchaseOperationHelper;
+    /**
+     * Constructor for Purchases.
+     * @param apiKey - RevenueCat API Key. Can be obtained from the RevenueCat dashboard.
+     */
     constructor(apiKey: string);
-    private toOfferings;
+    /**
+     * 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, { customerEmail, htmlTarget, }?: {
-        customerEmail?: string;
-        htmlTarget?: HTMLElement;
-    }): Promise<{
-        customerInfo: CustomerInfo;
-    }>;
-    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;
+      }
 
-export declare class PurchasesError extends Error {
-    readonly errorCode: ErrorCode;
-    readonly underlyingErrorMessage?: string | null | undefined;
-    static getForBackendError(backendErrorCode: BackendErrorCode, backendErrorMessage: string | null): PurchasesError;
-    static getForPurchasesFlowError(purchasesFlowError: PurchaseFlowError): PurchasesError;
-    constructor(errorCode: ErrorCode, message?: string, underlyingErrorMessage?: string | null | undefined);
-    toString: () => string;
-}
+      /**
+       * 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;
+      }
 
-export declare type Store = "app_store" | "mac_app_store" | "play_store" | "amazon" | "stripe" | "rc_billing" | "promotional" | "unknown";
+      /**
+       * 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 { }