@virex-tech/paywallo-sdk 2.2.1 → 2.2.3

package/README.md

@@ -96,6 +96,105 @@ const isActive = await PaywalloClient.hasActiveSubscription();
 | `isRestoring` | `boolean` | Restore in progress |
 | `error` | `PurchaseError \| null` | Last error |
 
+## Plans & Offerings
+
+An offering is a group of products configured in the dashboard that you display together on a paywall. You can swap the active offering in the dashboard without shipping a new app version.
+
+### useOfferings()
+
+```tsx
+import { useOfferings, useOfferingPurchase } from "@virex-tech/paywallo-sdk";
+
+// Fetch specific offerings by identifier
+const { offerings } = useOfferings(["mensal", "anual", "lifetime"]);
+
+// Fetch all offerings
+const { offerings } = useOfferings();
+
+// Purchase
+const { purchase } = useOfferingPurchase();
+purchase(offering.product.productId);
+```
+
+| Property | Type | Description |
+|---|---|---|
+| `offerings` | `Offering[]` | List of offerings |
+| `isLoading` | `boolean` | Loading state |
+
+### useOfferingPurchase()
+
+| Property | Type | Description |
+|---|---|---|
+| `purchase(productId)` | `Promise<PurchaseOutcome>` | Purchase a product from the offering |
+| `isPurchasing` | `boolean` | Purchase in progress |
+
+### Offering type
+
+```tsx
+interface Offering {
+  id: string;
+  name: string;
+  identifier: string;
+  isCurrent: boolean;
+  product: OfferingProduct;
+}
+
+interface OfferingProduct {
+  id: string;
+  name: string;
+  productId: string;           // App Store / Play Store identifier
+  priceUsd: number;
+  billingPeriod: string;       // "monthly" | "annual" | "lifetime" | ...
+  trialDays: number | null;
+
+  // Intro offer (synced automatically from Apple/Google)
+  introOfferMode: "FREE_TRIAL" | "PAY_AS_YOU_GO" | "PAY_UP_FRONT" | null;
+  introOfferPrice: number | null;
+  introOfferCurrency: string | null;
+  introOfferCycles: number | null;
+}
+```
+
+### Example
+
+```tsx
+import { useOfferings, useOfferingPurchase } from "@virex-tech/paywallo-sdk";
+
+function Paywall() {
+  const { offerings, isLoading } = useOfferings(["mensal", "anual"]);
+  const { purchase, isPurchasing } = useOfferingPurchase();
+
+  if (isLoading) return null;
+
+  return offerings.map(offering => (
+    <View key={offering.id}>
+      <Text>{offering.product.name} — ${offering.product.priceUsd}</Text>
+
+      {offering.product.introOfferMode === "FREE_TRIAL" && (
+        <Text>{offering.product.trialDays}-day free trial</Text>
+      )}
+      {offering.product.introOfferMode === "PAY_AS_YOU_GO" && (
+        <Text>
+          {offering.product.introOfferCurrency} {offering.product.introOfferPrice}/period
+          for {offering.product.introOfferCycles} cycles
+        </Text>
+      )}
+
+      <Button
+        onPress={() => purchase(offering.product.productId)}
+        disabled={isPurchasing}
+      >
+        Subscribe
+      </Button>
+    </View>
+  ));
+}
+```
+
+Intro offers are synced automatically from App Store Connect and Google Play — no manual setup needed.
+
+---
+
 ## Imperative API
 
 For use outside React components: