@virex-tech/paywallo-sdk 2.5.1 → 2.5.2

package/README.md

@@ -233,6 +233,27 @@ const onStateChange = usePaywalloScreenTracking();
 
 Works with React Navigation v6/v7 (no extra peer dependency).
 
+## Identify users
+
+Call `identify` after login (and on every logged-in app launch) to link the device to your user:
+
+```tsx
+await PaywalloClient.identify({
+  email: user.email,             // optional — improves ad-platform matching (CAPI)
+  firstName: user.firstName,     // optional
+  properties: {
+    userId: user.id,             // REQUIRED for per-user features — your backend's user id
+  },
+});
+```
+
+Key rules:
+
+- **`properties.userId` is what links the user.** It becomes `external_user_id` server-side and is the value you pass as `recipients` in `POST /v1/notifications/trigger`. Calling `identify({ email })` alone does **not** link the user — push tokens stay anonymous and per-user sends silently target zero devices (`skippedReason: "no_active_tokens"`).
+- **Order doesn't matter.** The link is retroactive: tokens registered before `identify` (e.g. during onboarding, pre-login) are linked when `identify` runs.
+- **Call it on every logged-in launch, not just once.** `identify` is idempotent and queued durably (offline-safe), so repeating it is cheap — and it self-heals devices that missed a previous attempt.
+- **`reset()` unlinks the device.** It regenerates the anonymous id (use it on logout/account switch). After the next login, call `identify` again or new tokens stay anonymous.
+
 ## Imperative API
 
 For use outside React components:
@@ -240,9 +261,9 @@ For use outside React components:
 ```tsx
 import { PaywalloClient } from '@virex-tech/paywallo-sdk';
 
-// Identify the user (optional — attribution works without it).
+// Identify user (see "Identify users" above — properties.userId is what links the user).
 // Model fields: email, firstName, lastName, dateOfBirth, gender, phone, properties.
-await PaywalloClient.identify({ email: 'user@example.com', firstName: 'Ana' });
+await PaywalloClient.identify({ email: 'user@example.com', properties: { userId: 'user-123' } });
 
 // Custom events
 await PaywalloClient.track('my_event', { properties: { plan: 'premium' } });

package/android/src/main/AndroidManifest.xml

@@ -8,6 +8,14 @@
     -->
     <uses-permission android:name="com.android.vending.BILLING" />
 
+    <!--
+        POST_NOTIFICATIONS (Android 13+) — required to display push notifications.
+        PaywalloNotificationsModule requests it at runtime, but the request only
+        surfaces a system prompt if the permission is declared in the merged
+        manifest. Declaring it here means the host app gets it for free.
+    -->
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
     <application>
         <!--
             PaywalloFirebaseMessagingService handles FCM token refresh and message delivery.

package/android/src/main/java/com/paywallo/sdk/PaywalloStoreKitModule.kt

@@ -233,7 +233,11 @@ class PaywalloStoreKitModule(private val reactContext: ReactApplicationContext)
                     listOf(productDetailsParams.build())
                 )
 
-                if (!appAccountToken.isNullOrBlank()) {
+                // Google Play rejects obfuscated account IDs longer than 64 chars
+                // with an IllegalArgumentException that aborts launchBillingFlow.
+                // A UUID is well under the limit; guard so an oversized id degrades
+                // to "no account id" instead of failing the whole purchase.
+                if (!appAccountToken.isNullOrBlank() && appAccountToken.length <= 64) {
                     flowParamsBuilder.setObfuscatedAccountId(appAccountToken)
                 }
 
@@ -391,9 +395,17 @@ class PaywalloStoreKitModule(private val reactContext: ReactApplicationContext)
                         .setProductType(BillingClient.ProductType.SUBS)
                         .build()
                 )
+                // INAPP covers non-consumables (lifetime unlocks). iOS restores
+                // these via Transaction.currentEntitlements, so querying only SUBS
+                // here would silently drop non-consumables from restore on Android.
+                val inappResult = client.queryPurchasesAsync(
+                    QueryPurchasesParams.newBuilder()
+                        .setProductType(BillingClient.ProductType.INAPP)
+                        .build()
+                )
 
                 val seenTokens = mutableSetOf<String>()
-                for (purchase in subsResult.purchasesList) {
+                for (purchase in subsResult.purchasesList + inappResult.purchasesList) {
                     if (purchase.purchaseState == Purchase.PurchaseState.PURCHASED) {
                         seenTokens.add(purchase.purchaseToken)
                         val map = WritableNativeMap()

package/dist/index.d.mts

@@ -922,6 +922,8 @@ interface AttributionCapture {
     readonly capturedAt: string;
 }
 type AttributionInput = Omit<AttributionCapture, "capturedAt">;
+/** Listener notified when `capture()` performs its first real write. */
+type AttributionCaptureListener = (capture: AttributionCapture) => void;
 /**
  * Attribution module — first-write-wins persistence of UTM / click-ID data.
  *
@@ -935,6 +937,7 @@ type AttributionInput = Omit<AttributionCapture, "capturedAt">;
 declare class AttributionTracker {
     private cache;
     private captureInProgress;
+    private readonly listeners;
     private readonly storage;
     constructor(debug?: boolean);
     /**
@@ -949,6 +952,14 @@ declare class AttributionTracker {
      * @param data - Attribution fields without `capturedAt` (generated internally).
      */
     capture(data: AttributionInput): Promise<void>;
+    /**
+     * Subscribes to the first real attribution write (first-write-wins — no-op
+     * captures never fire). Useful for late enrichment consumers (e.g. re-push
+     * of Superwall attributes when a warm deep link / deferred match lands after
+     * init). Returns an unsubscribe function.
+     */
+    onCapture(listener: AttributionCaptureListener): () => void;
+    private notifyListeners;
     /**
      * Returns the persisted attribution capture, or `null` if none exists.
      * Synchronous — reads from in-memory cache (populated via `loadFromStorage()`).
@@ -1877,6 +1888,35 @@ interface UsePlanPurchaseResult {
 }
 declare function usePlanPurchase(): UsePlanPurchaseResult;
 
+/**
+ * Extracts the name of the currently active leaf route from a react-navigation
+ * NavigationState. Descends into nested navigators recursively.
+ *
+ * Does NOT import react-navigation — accepts `state: unknown` and uses
+ * structural duck-typing, so it works with v6, v7, and future versions alike.
+ *
+ * @returns the active route name string, or null if the shape is unexpected.
+ */
+declare function getActiveRouteName(state: unknown): string | null;
+/**
+ * Returns a stable `onStateChange` callback ready to be passed directly to
+ * `<NavigationContainer onStateChange={onStateChange}>`.
+ *
+ * Emits a `screen_view` event via the PaywalloClient pipeline each time the
+ * active route changes. Consecutive calls with the same screen are no-ops
+ * (deduplication by name). If the SDK is not yet initialized, calls are
+ * silently ignored.
+ *
+ * @example
+ * ```tsx
+ * const onStateChange = usePaywalloScreenTracking();
+ * <NavigationContainer onStateChange={onStateChange}>
+ *   {children}
+ * </NavigationContainer>
+ * ```
+ */
+declare function usePaywalloScreenTracking(): (state: unknown) => void;
+
 interface UsePlansResult {
     currentPlan: Plan | null;
     allPlans: Plan[];
@@ -1934,35 +1974,6 @@ interface UseSubscriptionResult {
 }
 declare function useSubscription(): UseSubscriptionResult;
 
-/**
- * Extracts the name of the currently active leaf route from a react-navigation
- * NavigationState. Descends into nested navigators recursively.
- *
- * Does NOT import react-navigation — accepts `state: unknown` and uses
- * structural duck-typing, so it works with v6, v7, and future versions alike.
- *
- * @returns the active route name string, or null if the shape is unexpected.
- */
-declare function getActiveRouteName(state: unknown): string | null;
-/**
- * Returns a stable `onStateChange` callback ready to be passed directly to
- * `<NavigationContainer onStateChange={onStateChange}>`.
- *
- * Emits a `screen_view` event via the PaywalloClient pipeline each time the
- * active route changes. Consecutive calls with the same screen are no-ops
- * (deduplication by name). If the SDK is not yet initialized, calls are
- * silently ignored.
- *
- * @example
- * ```tsx
- * const onStateChange = usePaywalloScreenTracking();
- * <NavigationContainer onStateChange={onStateChange}>
- *   {children}
- * </NavigationContainer>
- * ```
- */
-declare function usePaywalloScreenTracking(): (state: unknown) => void;
-
 interface PaywalloProviderProps {
     children: React__default.ReactNode;
     config: PaywalloConfig;

package/dist/index.d.ts

@@ -922,6 +922,8 @@ interface AttributionCapture {
     readonly capturedAt: string;
 }
 type AttributionInput = Omit<AttributionCapture, "capturedAt">;
+/** Listener notified when `capture()` performs its first real write. */
+type AttributionCaptureListener = (capture: AttributionCapture) => void;
 /**
  * Attribution module — first-write-wins persistence of UTM / click-ID data.
  *
@@ -935,6 +937,7 @@ type AttributionInput = Omit<AttributionCapture, "capturedAt">;
 declare class AttributionTracker {
     private cache;
     private captureInProgress;
+    private readonly listeners;
     private readonly storage;
     constructor(debug?: boolean);
     /**
@@ -949,6 +952,14 @@ declare class AttributionTracker {
      * @param data - Attribution fields without `capturedAt` (generated internally).
      */
     capture(data: AttributionInput): Promise<void>;
+    /**
+     * Subscribes to the first real attribution write (first-write-wins — no-op
+     * captures never fire). Useful for late enrichment consumers (e.g. re-push
+     * of Superwall attributes when a warm deep link / deferred match lands after
+     * init). Returns an unsubscribe function.
+     */
+    onCapture(listener: AttributionCaptureListener): () => void;
+    private notifyListeners;
     /**
      * Returns the persisted attribution capture, or `null` if none exists.
      * Synchronous — reads from in-memory cache (populated via `loadFromStorage()`).
@@ -1877,6 +1888,35 @@ interface UsePlanPurchaseResult {
 }
 declare function usePlanPurchase(): UsePlanPurchaseResult;
 
+/**
+ * Extracts the name of the currently active leaf route from a react-navigation
+ * NavigationState. Descends into nested navigators recursively.
+ *
+ * Does NOT import react-navigation — accepts `state: unknown` and uses
+ * structural duck-typing, so it works with v6, v7, and future versions alike.
+ *
+ * @returns the active route name string, or null if the shape is unexpected.
+ */
+declare function getActiveRouteName(state: unknown): string | null;
+/**
+ * Returns a stable `onStateChange` callback ready to be passed directly to
+ * `<NavigationContainer onStateChange={onStateChange}>`.
+ *
+ * Emits a `screen_view` event via the PaywalloClient pipeline each time the
+ * active route changes. Consecutive calls with the same screen are no-ops
+ * (deduplication by name). If the SDK is not yet initialized, calls are
+ * silently ignored.
+ *
+ * @example
+ * ```tsx
+ * const onStateChange = usePaywalloScreenTracking();
+ * <NavigationContainer onStateChange={onStateChange}>
+ *   {children}
+ * </NavigationContainer>
+ * ```
+ */
+declare function usePaywalloScreenTracking(): (state: unknown) => void;
+
 interface UsePlansResult {
     currentPlan: Plan | null;
     allPlans: Plan[];
@@ -1934,35 +1974,6 @@ interface UseSubscriptionResult {
 }
 declare function useSubscription(): UseSubscriptionResult;
 
-/**
- * Extracts the name of the currently active leaf route from a react-navigation
- * NavigationState. Descends into nested navigators recursively.
- *
- * Does NOT import react-navigation — accepts `state: unknown` and uses
- * structural duck-typing, so it works with v6, v7, and future versions alike.
- *
- * @returns the active route name string, or null if the shape is unexpected.
- */
-declare function getActiveRouteName(state: unknown): string | null;
-/**
- * Returns a stable `onStateChange` callback ready to be passed directly to
- * `<NavigationContainer onStateChange={onStateChange}>`.
- *
- * Emits a `screen_view` event via the PaywalloClient pipeline each time the
- * active route changes. Consecutive calls with the same screen are no-ops
- * (deduplication by name). If the SDK is not yet initialized, calls are
- * silently ignored.
- *
- * @example
- * ```tsx
- * const onStateChange = usePaywalloScreenTracking();
- * <NavigationContainer onStateChange={onStateChange}>
- *   {children}
- * </NavigationContainer>
- * ```
- */
-declare function usePaywalloScreenTracking(): (state: unknown) => void;
-
 interface PaywalloProviderProps {
     children: React__default.ReactNode;
     config: PaywalloConfig;