@nosslabs/iap 7.0.0 → 7.1.0

package/dist/index.d.cts

@@ -950,6 +950,39 @@ interface RestoreResult<TEntitlement extends EntitlementBase = EntitlementBase>
     entitlements: TEntitlement[];
 }
 
+/**
+ * The user's App Store / Google Play storefront — i.e. the country their
+ * store account is registered to, which is the platform-blessed signal for
+ * region-dependent decisions (regional pricing/offers, and gating
+ * external-payment links whose eligibility the OS itself keys to storefront
+ * country, *not* device locale).
+ *
+ * `countryCode` is normalized to **ISO 3166-1 alpha-2** across platforms so
+ * consumers compare one consistent value (Apple's native code is alpha-3,
+ * Google's is alpha-2). The raw native code is preserved in `countryCodeRaw`.
+ *
+ * Treat the value as a **UX / targeting hint** and read it live (never cache):
+ * for compliance- or entitlement-sensitive enforcement, trust the server-side
+ * signed storefront (App Store Server API `storefront` / Play Developer API
+ * `regionCode`) instead, since the client value can be unreliable (TestFlight
+ * historically reports `"USA"`) or empty (EU alternative distribution).
+ */
+interface Storefront {
+    /**
+     * ISO 3166-1 alpha-2 country code (normalized), e.g. `'US'`. In the rare
+     * case the native value can't be normalized (an unrecognized code), this
+     * falls back to the uppercased raw value — compare against `countryCodeRaw`
+     * if you need certainty about the format.
+     */
+    countryCode: string;
+    /** Raw native value (whitespace-trimmed): alpha-3 on iOS (`'USA'`), alpha-2 on Android (`'US'`). */
+    countryCodeRaw: string;
+    /** Apple-defined storefront identifier (iOS only); `undefined` on Android. */
+    storefrontId?: string;
+    /** Store the value came from. */
+    platform: Platform;
+}
+
 interface IAP<TEntitlement extends EntitlementBase = EntitlementBase> {
     initialize(): Promise<void>;
     /**
@@ -1030,6 +1063,25 @@ interface IAP<TEntitlement extends EntitlementBase = EntitlementBase> {
      * yet ingested by the store are silently skipped (no error).
      */
     getProducts(): Promise<Product[]>;
+    /**
+     * Read the current storefront — the country the user's App Store / Google
+     * Play account is registered to. Use it to drive region-dependent UI:
+     * regional offers/pricing, and gating external-payment links whose
+     * eligibility the platform itself keys to storefront country (not device
+     * locale).
+     *
+     * `countryCode` is normalized to ISO 3166-1 alpha-2 across platforms (raw
+     * native code preserved on `countryCodeRaw`). Resolves `null` when no
+     * storefront is available — on web, when the installed
+     * `@capgo/native-purchases` doesn't register the native method, when the
+     * native call fails, or when the store reports an empty country (e.g. EU
+     * alternative distribution).
+     *
+     * Read live — do not cache. Treat the value as a UX/targeting hint; for
+     * compliance- or entitlement-sensitive enforcement, trust the server-side
+     * signed storefront from your backend instead.
+     */
+    getStorefront(): Promise<Storefront | null>;
     hasEntitlement(key: string): boolean;
     /** Returns a defensive shallow copy. Each entitlement is frozen. */
     getEntitlements(): TEntitlement[];
@@ -1214,4 +1266,4 @@ declare class HttpBackendAdapter<TEntitlement extends EntitlementBase = Entitlem
     listProducts(): Promise<ConfiguredProduct[]>;
 }
 
-export { type AppUserId, type AppUserIdFetcherContext, type BackendAdapter, type BackendConfig, type BackendConfigInput, type ConfiguredProduct, DEFAULT_PERMANENT_ERROR_CODES, type DefaultEntitlement, type EntitlementBase, type EventMap, type EventName, type EventPayload, HttpBackendAdapter, HttpClient, type HttpRequest, type IAP, type IAPConfig, type IAPConfigInput, IAPError, IAPErrorCode, type LogLevel, type Logger, type NativeTransaction, type OptionsConfig, type Platform, type Product, type ProductType, type PurchaseOptions, type PurchaseResult, type RestoreRequest, type RestoreRequestTransaction, type RestoreResponse, type RestoreResult, type StorageConfig, type Unsubscribe, VERSION, type VerifiedTransaction, type VerifyAppleRequest, type VerifyGoogleRequest, type VerifyResponse, createIAP, errorHint, isIAPError };
+export { type AppUserId, type AppUserIdFetcherContext, type BackendAdapter, type BackendConfig, type BackendConfigInput, type ConfiguredProduct, DEFAULT_PERMANENT_ERROR_CODES, type DefaultEntitlement, type EntitlementBase, type EventMap, type EventName, type EventPayload, HttpBackendAdapter, HttpClient, type HttpRequest, type IAP, type IAPConfig, type IAPConfigInput, IAPError, IAPErrorCode, type LogLevel, type Logger, type NativeTransaction, type OptionsConfig, type Platform, type Product, type ProductType, type PurchaseOptions, type PurchaseResult, type RestoreRequest, type RestoreRequestTransaction, type RestoreResponse, type RestoreResult, type StorageConfig, type Storefront, type Unsubscribe, VERSION, type VerifiedTransaction, type VerifyAppleRequest, type VerifyGoogleRequest, type VerifyResponse, createIAP, errorHint, isIAPError };

package/dist/index.d.ts

@@ -950,6 +950,39 @@ interface RestoreResult<TEntitlement extends EntitlementBase = EntitlementBase>
     entitlements: TEntitlement[];
 }
 
+/**
+ * The user's App Store / Google Play storefront — i.e. the country their
+ * store account is registered to, which is the platform-blessed signal for
+ * region-dependent decisions (regional pricing/offers, and gating
+ * external-payment links whose eligibility the OS itself keys to storefront
+ * country, *not* device locale).
+ *
+ * `countryCode` is normalized to **ISO 3166-1 alpha-2** across platforms so
+ * consumers compare one consistent value (Apple's native code is alpha-3,
+ * Google's is alpha-2). The raw native code is preserved in `countryCodeRaw`.
+ *
+ * Treat the value as a **UX / targeting hint** and read it live (never cache):
+ * for compliance- or entitlement-sensitive enforcement, trust the server-side
+ * signed storefront (App Store Server API `storefront` / Play Developer API
+ * `regionCode`) instead, since the client value can be unreliable (TestFlight
+ * historically reports `"USA"`) or empty (EU alternative distribution).
+ */
+interface Storefront {
+    /**
+     * ISO 3166-1 alpha-2 country code (normalized), e.g. `'US'`. In the rare
+     * case the native value can't be normalized (an unrecognized code), this
+     * falls back to the uppercased raw value — compare against `countryCodeRaw`
+     * if you need certainty about the format.
+     */
+    countryCode: string;
+    /** Raw native value (whitespace-trimmed): alpha-3 on iOS (`'USA'`), alpha-2 on Android (`'US'`). */
+    countryCodeRaw: string;
+    /** Apple-defined storefront identifier (iOS only); `undefined` on Android. */
+    storefrontId?: string;
+    /** Store the value came from. */
+    platform: Platform;
+}
+
 interface IAP<TEntitlement extends EntitlementBase = EntitlementBase> {
     initialize(): Promise<void>;
     /**
@@ -1030,6 +1063,25 @@ interface IAP<TEntitlement extends EntitlementBase = EntitlementBase> {
      * yet ingested by the store are silently skipped (no error).
      */
     getProducts(): Promise<Product[]>;
+    /**
+     * Read the current storefront — the country the user's App Store / Google
+     * Play account is registered to. Use it to drive region-dependent UI:
+     * regional offers/pricing, and gating external-payment links whose
+     * eligibility the platform itself keys to storefront country (not device
+     * locale).
+     *
+     * `countryCode` is normalized to ISO 3166-1 alpha-2 across platforms (raw
+     * native code preserved on `countryCodeRaw`). Resolves `null` when no
+     * storefront is available — on web, when the installed
+     * `@capgo/native-purchases` doesn't register the native method, when the
+     * native call fails, or when the store reports an empty country (e.g. EU
+     * alternative distribution).
+     *
+     * Read live — do not cache. Treat the value as a UX/targeting hint; for
+     * compliance- or entitlement-sensitive enforcement, trust the server-side
+     * signed storefront from your backend instead.
+     */
+    getStorefront(): Promise<Storefront | null>;
     hasEntitlement(key: string): boolean;
     /** Returns a defensive shallow copy. Each entitlement is frozen. */
     getEntitlements(): TEntitlement[];
@@ -1214,4 +1266,4 @@ declare class HttpBackendAdapter<TEntitlement extends EntitlementBase = Entitlem
     listProducts(): Promise<ConfiguredProduct[]>;
 }
 
-export { type AppUserId, type AppUserIdFetcherContext, type BackendAdapter, type BackendConfig, type BackendConfigInput, type ConfiguredProduct, DEFAULT_PERMANENT_ERROR_CODES, type DefaultEntitlement, type EntitlementBase, type EventMap, type EventName, type EventPayload, HttpBackendAdapter, HttpClient, type HttpRequest, type IAP, type IAPConfig, type IAPConfigInput, IAPError, IAPErrorCode, type LogLevel, type Logger, type NativeTransaction, type OptionsConfig, type Platform, type Product, type ProductType, type PurchaseOptions, type PurchaseResult, type RestoreRequest, type RestoreRequestTransaction, type RestoreResponse, type RestoreResult, type StorageConfig, type Unsubscribe, VERSION, type VerifiedTransaction, type VerifyAppleRequest, type VerifyGoogleRequest, type VerifyResponse, createIAP, errorHint, isIAPError };
+export { type AppUserId, type AppUserIdFetcherContext, type BackendAdapter, type BackendConfig, type BackendConfigInput, type ConfiguredProduct, DEFAULT_PERMANENT_ERROR_CODES, type DefaultEntitlement, type EntitlementBase, type EventMap, type EventName, type EventPayload, HttpBackendAdapter, HttpClient, type HttpRequest, type IAP, type IAPConfig, type IAPConfigInput, IAPError, IAPErrorCode, type LogLevel, type Logger, type NativeTransaction, type OptionsConfig, type Platform, type Product, type ProductType, type PurchaseOptions, type PurchaseResult, type RestoreRequest, type RestoreRequestTransaction, type RestoreResponse, type RestoreResult, type StorageConfig, type Storefront, type Unsubscribe, VERSION, type VerifiedTransaction, type VerifyAppleRequest, type VerifyGoogleRequest, type VerifyResponse, createIAP, errorHint, isIAPError };

package/dist/index.js

@@ -137,11 +137,293 @@ var init_platform = __esm({
   }
 });
 
+// src/lib/iso-country.ts
+function toAlpha2(code) {
+  if (!code) return null;
+  const normalized = code.trim().toUpperCase();
+  if (normalized.length === 2) return normalized;
+  if (normalized.length === 3) return ALPHA3_TO_ALPHA2[normalized] ?? null;
+  return null;
+}
+var ALPHA3_TO_ALPHA2;
+var init_iso_country = __esm({
+  "src/lib/iso-country.ts"() {
+    ALPHA3_TO_ALPHA2 = {
+      ABW: "AW",
+      AFG: "AF",
+      AGO: "AO",
+      AIA: "AI",
+      ALA: "AX",
+      ALB: "AL",
+      AND: "AD",
+      ARE: "AE",
+      ARG: "AR",
+      ARM: "AM",
+      ASM: "AS",
+      ATA: "AQ",
+      ATF: "TF",
+      ATG: "AG",
+      AUS: "AU",
+      AUT: "AT",
+      AZE: "AZ",
+      BDI: "BI",
+      BEL: "BE",
+      BEN: "BJ",
+      BES: "BQ",
+      BFA: "BF",
+      BGD: "BD",
+      BGR: "BG",
+      BHR: "BH",
+      BHS: "BS",
+      BIH: "BA",
+      BLM: "BL",
+      BLR: "BY",
+      BLZ: "BZ",
+      BMU: "BM",
+      BOL: "BO",
+      BRA: "BR",
+      BRB: "BB",
+      BRN: "BN",
+      BTN: "BT",
+      BVT: "BV",
+      BWA: "BW",
+      CAF: "CF",
+      CAN: "CA",
+      CCK: "CC",
+      CHE: "CH",
+      CHL: "CL",
+      CHN: "CN",
+      CIV: "CI",
+      CMR: "CM",
+      COD: "CD",
+      COG: "CG",
+      COK: "CK",
+      COL: "CO",
+      COM: "KM",
+      CPV: "CV",
+      CRI: "CR",
+      CUB: "CU",
+      CUW: "CW",
+      CXR: "CX",
+      CYM: "KY",
+      CYP: "CY",
+      CZE: "CZ",
+      DEU: "DE",
+      DJI: "DJ",
+      DMA: "DM",
+      DNK: "DK",
+      DOM: "DO",
+      DZA: "DZ",
+      ECU: "EC",
+      EGY: "EG",
+      ERI: "ER",
+      ESH: "EH",
+      ESP: "ES",
+      EST: "EE",
+      ETH: "ET",
+      FIN: "FI",
+      FJI: "FJ",
+      FLK: "FK",
+      FRA: "FR",
+      FRO: "FO",
+      FSM: "FM",
+      GAB: "GA",
+      GBR: "GB",
+      GEO: "GE",
+      GGY: "GG",
+      GHA: "GH",
+      GIB: "GI",
+      GIN: "GN",
+      GLP: "GP",
+      GMB: "GM",
+      GNB: "GW",
+      GNQ: "GQ",
+      GRC: "GR",
+      GRD: "GD",
+      GRL: "GL",
+      GTM: "GT",
+      GUF: "GF",
+      GUM: "GU",
+      GUY: "GY",
+      HKG: "HK",
+      HMD: "HM",
+      HND: "HN",
+      HRV: "HR",
+      HTI: "HT",
+      HUN: "HU",
+      IDN: "ID",
+      IMN: "IM",
+      IND: "IN",
+      IOT: "IO",
+      IRL: "IE",
+      IRN: "IR",
+      IRQ: "IQ",
+      ISL: "IS",
+      ISR: "IL",
+      ITA: "IT",
+      JAM: "JM",
+      JEY: "JE",
+      JOR: "JO",
+      JPN: "JP",
+      KAZ: "KZ",
+      KEN: "KE",
+      KGZ: "KG",
+      KHM: "KH",
+      KIR: "KI",
+      KNA: "KN",
+      KOR: "KR",
+      KWT: "KW",
+      LAO: "LA",
+      LBN: "LB",
+      LBR: "LR",
+      LBY: "LY",
+      LCA: "LC",
+      LIE: "LI",
+      LKA: "LK",
+      LSO: "LS",
+      LTU: "LT",
+      LUX: "LU",
+      LVA: "LV",
+      MAC: "MO",
+      MAF: "MF",
+      MAR: "MA",
+      MCO: "MC",
+      MDA: "MD",
+      MDG: "MG",
+      MDV: "MV",
+      MEX: "MX",
+      MHL: "MH",
+      MKD: "MK",
+      MLI: "ML",
+      MLT: "MT",
+      MMR: "MM",
+      MNE: "ME",
+      MNG: "MN",
+      MNP: "MP",
+      MOZ: "MZ",
+      MRT: "MR",
+      MSR: "MS",
+      MTQ: "MQ",
+      MUS: "MU",
+      MWI: "MW",
+      MYS: "MY",
+      MYT: "YT",
+      NAM: "NA",
+      NCL: "NC",
+      NER: "NE",
+      NFK: "NF",
+      NGA: "NG",
+      NIC: "NI",
+      NIU: "NU",
+      NLD: "NL",
+      NOR: "NO",
+      NPL: "NP",
+      NRU: "NR",
+      NZL: "NZ",
+      OMN: "OM",
+      PAK: "PK",
+      PAN: "PA",
+      PCN: "PN",
+      PER: "PE",
+      PHL: "PH",
+      PLW: "PW",
+      PNG: "PG",
+      POL: "PL",
+      PRI: "PR",
+      PRK: "KP",
+      PRT: "PT",
+      PRY: "PY",
+      PSE: "PS",
+      PYF: "PF",
+      QAT: "QA",
+      REU: "RE",
+      ROU: "RO",
+      RUS: "RU",
+      RWA: "RW",
+      SAU: "SA",
+      SDN: "SD",
+      SEN: "SN",
+      SGP: "SG",
+      SGS: "GS",
+      SHN: "SH",
+      SJM: "SJ",
+      SLB: "SB",
+      SLE: "SL",
+      SLV: "SV",
+      SMR: "SM",
+      SOM: "SO",
+      SPM: "PM",
+      SRB: "RS",
+      SSD: "SS",
+      STP: "ST",
+      SUR: "SR",
+      SVK: "SK",
+      SVN: "SI",
+      SWE: "SE",
+      SWZ: "SZ",
+      SXM: "SX",
+      SYC: "SC",
+      SYR: "SY",
+      TCA: "TC",
+      TCD: "TD",
+      TGO: "TG",
+      THA: "TH",
+      TJK: "TJ",
+      TKL: "TK",
+      TKM: "TM",
+      TLS: "TL",
+      TON: "TO",
+      TTO: "TT",
+      TUN: "TN",
+      TUR: "TR",
+      TUV: "TV",
+      TWN: "TW",
+      TZA: "TZ",
+      UGA: "UG",
+      UKR: "UA",
+      UMI: "UM",
+      URY: "UY",
+      USA: "US",
+      UZB: "UZ",
+      VAT: "VA",
+      VCT: "VC",
+      VEN: "VE",
+      VGB: "VG",
+      VIR: "VI",
+      VNM: "VN",
+      VUT: "VU",
+      WLF: "WF",
+      WSM: "WS",
+      YEM: "YE",
+      ZAF: "ZA",
+      ZMB: "ZM",
+      ZWE: "ZW"
+    };
+  }
+});
+
 // src/adapters/native/capgo/native-adapter.ts
 var native_adapter_exports = {};
 __export(native_adapter_exports, {
   CapgoNativeAdapter: () => CapgoNativeAdapter
 });
+function nativeStorefrontRegistered() {
+  const headers = Capacitor.PluginHeaders;
+  return headers?.find((h) => h.name === "NativePurchases")?.methods?.some((m) => m.name === "getStorefront") ?? false;
+}
+function normalizeStorefront(raw) {
+  const code = raw?.countryCode?.trim();
+  if (!code) return null;
+  const platform = getPlatform() === "android" ? "google" : "apple";
+  return {
+    // alpha-2 when recognized; otherwise the uppercased raw code as a
+    // best-effort fallback (see `Storefront.countryCode`).
+    countryCode: toAlpha2(code) ?? code.toUpperCase(),
+    countryCodeRaw: code,
+    storefrontId: raw.storefrontId,
+    platform
+  };
+}
 function normalizeProduct(p, type) {
   const priceMicros = Math.round(p.price * 1e6).toString();
   return {
@@ -217,6 +499,7 @@ var CapgoNativeAdapter;
 var init_native_adapter = __esm({
   "src/adapters/native/capgo/native-adapter.ts"() {
     init_errors();
+    init_iso_country();
     init_platform();
     CapgoNativeAdapter = class {
       async isAvailable() {
@@ -300,6 +583,24 @@ var init_native_adapter = __esm({
           });
         }
       }
+      /**
+       * Read the current storefront from the native plugin — which is expected to
+       * source it from StoreKit 2 `Storefront.current` on iOS (alpha-3) and
+       * `getBillingConfigAsync()` on Android (alpha-2) — normalizing `countryCode`
+       * to alpha-2. Silent like {@link CapgoNativeAdapter.isAvailable}: any
+       * unavailability — older plugin (no native method registered), native
+       * rejection, or empty country — resolves to `null` rather than throwing.
+       */
+      async getStorefront() {
+        if (!nativeStorefrontRegistered()) return null;
+        const np = NativePurchases;
+        try {
+          const raw = await np.getStorefront?.();
+          return raw ? normalizeStorefront(raw) : null;
+        } catch {
+          return null;
+        }
+      }
       async dispose() {
       }
     };
@@ -830,6 +1131,9 @@ var WebStubAdapter = class {
       message: "Subscription management is not supported on the web platform."
     });
   }
+  async getStorefront() {
+    return null;
+  }
 };
 
 // src/adapters/native/index.ts
@@ -1931,6 +2235,10 @@ function createIAP(input) {
       }
       return state.adapter.getProducts(state.products.map((p) => ({ id: p.id, type: p.type })));
     },
+    async getStorefront() {
+      requireInitialized(state);
+      return state.adapter?.getStorefront?.() ?? null;
+    },
     hasEntitlement(key) {
       return state.entitlements.some((e) => e.key === key);
     },