@encorekit/web-sdk 2.0.0 → 2.0.2

package/README.md

@@ -5,7 +5,7 @@ A JavaScript/TypeScript SDK that enables web applications to display targeted of
 ## Features
 
 - 🎯 **Targeted Offer Presentation** - Display offers at critical moments (cancellation flows, paywalls, onboarding)
-- 🎁 **Use Cases** - Churn intervention (the default) or post-action rewards — see [Use Cases](#use-cases)
+- 🎁 **Use Cases** - `reduceChurn` (the default) or `rewardUsers` — see [Use Cases](#use-cases)
 - 🔐 **Entitlement Management** - Two-tier system (provisional + verified) for instant UX and reliable billing
 - 📱 **Framework Agnostic** - Works with React, Vue, Angular, Svelte, vanilla JavaScript, or any web framework
 - 🎨 **Responsive UI** - Beautiful, accessible modal interface that works on desktop and mobile
@@ -16,7 +16,7 @@ A JavaScript/TypeScript SDK that enables web applications to display targeted of
 ## Installation
 
 ```bash
-npm install @encorekit/web-sdk
+npm install @encorekit/web-sdk@3.0.0
 ```
 
 Or via CDN:
@@ -25,6 +25,24 @@ Or via CDN:
 <script src="https://encorekit.com/encore.min.js"></script>
 ```
 
+## Upgrading to 3.0.0
+
+3.0.0 removes the deferred redemption flow and the layout system. Claiming an
+offer now always redirects to the advertiser immediately, and the composition is
+derived from the placement's use case.
+
+| Removed | Replacement |
+|:--------|:------------|
+| `redemptionMode` — on `configure()` and on placement options | None. Redirect-on-claim is the only flow. |
+| `Encore.redeem()`, `placement(id).redeem()`, `getPendingTransaction()`, `RedeemOptions`, `RedeemResult` | None. There is no pending transaction to redeem. |
+| `layout: 'list' \| 'thankYou'` | `useCase` — `'reduceChurn'` renders the offer carousel, `'rewardUsers'` the reward composition. |
+| `header.title`, `header.subtitle` | `headline` / `subheadline` on `PlacementOptions`. |
+| `header.icon` | `statusIcon` on `PlacementOptions` — **the default flips from `'success'` to `'none'`**, so the check no longer renders unless you ask for it. |
+| `offerContext`, `footer`, `receipt` / `ShowOptions`, `Receipt` | None. Render any other copy yourself. |
+| `display` / `HostDisplay` | None. It only ever fed the deferred-flow screens; on the immediate path it resolved to nothing. |
+| `.headline()` / `.subheadline()` builder steps | The flat `headline` / `subheadline` options. `.useCase()` stays. |
+| `'churn-intervention'` / `'post-action-reward'` | `'reduceChurn'` / `'rewardUsers'` — a rename of the TypeScript symbols only; the values sent over HTTP are unchanged. |
+
 ## Quick Start
 
 ```typescript
@@ -43,93 +61,97 @@ Encore.identify('user-123', {
   subscriptionTier: 'free'
 });
 
-// Present an offer
-const result = await Encore.presentOffer();
-if (result.granted) {
-  console.log('User granted entitlement:', result.entitlement);
-  console.log('Offer granted:', result.entitlement);
-  // Handle user completed Encore offer
+// Present a placement — defaults to the 'reduceChurn' use case
+const result = await Encore.show();
+if (result.status === 'claimed') {
+  // The user claimed an offer and the advertiser opened in a new tab.
+  // Keep result.transactionId — it is how the conversion is traced back to
+  // this user and app, and what waitForVerification() / didGrant() take.
+  // The SDK renders nothing after a claim — show your own confirmation here.
 } else {
-  console.log('User declined:', result.reason);
+  // 'dismissed' (with an optional reason) or 'unavailable' — nothing was claimed.
+  console.log('Nothing claimed:', result);
 }
 
 // Check entitlement on YOUR server (not client-side)
 // See: https://docs.encorekit.com/server-side-validation
 ```
 
-## Layout Templates
+## Placements
 
-`show()` renders the default `'list'` layout. For post-purchase surfaces (a payment
-success page), use the `'thankYou'` layout — a complete success view: status check,
-your payment copy, the offer carousel, and an optional trust footer.
+A **placement** is one presentation of offers. There are two call forms, and they
+take the same options:
 
 ```typescript
-const placement = Encore.placement('post-purchase', {
-  layout: 'thankYou',
+// Builder form
+const result = await Encore.placement('milestone_reached', {
+  headline: 'Nice work, Sam!',
+  subheadline: 'That is your fifth week running',
   appearance: { accentColor: '#0A6' },
-  header: { title: 'Payment Successful' },   // constants — plain strings
-  offerContext: { title: 'A little thank you, just for you.' },
-  footer: { text: '🔒 Secured by Acme' },
-});
-
-// Per transaction, pass the typed receipt — the SDK renders
-// "You paid $9.99 for Pro Plan" under the header:
-await placement.show({ receipt: { amount: '$9.99', purpose: 'Pro Plan' } });
+})
+  .useCase('rewardUsers')
+  .onNotGranted((reason) => console.log('closed without a claim', reason))
+  .onLoadingStateChange((isLoading) => setSpinner(isLoading))
+  .show();                       // takes no arguments
+
+// Flat form — callbacks first, then the same options, then the placement id
+await Encore.show(
+  { onGranted, onNotGranted, onError },
+  { useCase: 'rewardUsers', headline: 'Nice work, Sam!' },
+  'milestone_reached'
+);
 ```
 
-Notes:
-
-- `header` is the sheet's top heading block in EVERY layout — the modal
-  title/subtitle in `'list'` (a local override of the remote copy) and the
-  payment-status block in `'thankYou'`. One name, one meaning.
-- `receipt` values are rendered verbatim as plain text (pre-format currency yourself),
-  never sent to Encore servers, and override `header.subtitle` when provided.
-- `offerContext` is `'thankYou'`-only priming copy ABOVE the offers (why they're
-  being shown), not any offer's own copy — `'list'` ignores it. When the active
-  offer's campaign carries a `perk` line (e.g. "Enjoy 30 days of Apple Music free")
-  the perk takes the subtitle slot and follows the carousel as it pages;
-  `offerContext.subtitle` is the static fallback.
-- Need a custom confirmation line? Skip `receipt` and pass your own pre-built string as
-  `header.subtitle` — placement options are per-call.
-- Unknown `layout` values warn and fall back to `'list'`, so older SDK versions degrade
-  gracefully when layout selection later moves to remote config.
-- In `'thankYou'` the carousel pages one card per view at every breakpoint, with round
-  chevron navigation bubbles when there is more than one offer (hidden for a single offer).
-- Pair with `redemptionMode: 'immediate'` for post-purchase: Claim opens the advertiser
-  in a new tab within the tap gesture and `show()` resolves `{ status: 'claimed' }` —
-  the SDK renders nothing after a claim. The host owns that moment: render your own
-  confirmation if you want one, keyed off the result. The result deliberately makes no
-  claim about advertiser conversion (it is asynchronous and server-authoritative —
-  verify entitlements/conversions server-side by user, never from the client).
-  `show()` never rejects: failures resolve as `{ status: 'dismissed', reason }`.
+`Encore.show()`'s first argument is **callbacks only** — `onGranted`,
+`onNotGranted`, `onError`. Every other option is a placement option.
 
-## Use Cases
+### `PlacementOptions`
 
-A placement's **use case** says *why* it presents. It defaults to
-`'churn-intervention'` — the behaviour every caller already had before this
-dimension existed — so existing integrations need no change.
+| Option | Type | Meaning |
+|:-------|:-----|:--------|
+| `useCase` | `'reduceChurn' \| 'rewardUsers'` | Why the placement presents, and which composition it renders. Defaults to `'reduceChurn'`. |
+| `headline` | `string` | Per-call override of the sheet's primary heading. |
+| `subheadline` | `string` | Per-call override of the line under it. |
+| `appearance` | `{ backgroundColor?, textColor?, accentColor? }` | Colour overrides for the sheet. |
+| `statusIcon` | `'success' \| 'none'` | Status icon above the headline. Defaults to `'none'` — nothing renders unless you ask for `'success'`, which draws a green-circle check. Only `'rewardUsers'` has a status block; `'reduceChurn'` ignores it. The default matches iOS and Android, whose reward variant renders no checkmark. |
 
-```typescript
-// Reward a user for something they just did. No entitlement is granted.
-const result = await Encore.placement('milestone_reached')
-  .useCase('post-action-reward')
-  .show();
+### The result
 
-if (result.status === 'claimed') {
-  // The user claimed an offer. Render your own confirmation.
-}
-```
+`show()` **never rejects**. It resolves one of three statuses:
+
+| Status | Meaning |
+|:-------|:--------|
+| `{ status: 'claimed', offerId, campaignId, advertiserName, transactionId? }` | The user claimed an offer. The advertiser opened in a new tab inside the tap gesture and the SDK renders nothing afterwards — the host owns that moment, so render your own confirmation if you want one. The payload mirrors iOS's and Android's `ClaimedOffer` field-for-field. **`transactionId` carries the attribution** — it is how a completion that lands days later is traced back to this user and app, and it is the argument `didGrant()` and `waitForVerification()` take. It is optional because the transaction write can fail while the claim genuinely happened; the SDK logs a warning when that occurs. |
+| `{ status: 'dismissed', reason? }` | The sheet closed without a claim. Failures land here too, carrying `reason.error`. |
+| `{ status: 'unavailable' }` | Nothing was presented — no eligible offers, or the surface did not resolve. |
 
-It is also a plain placement option, if you prefer that form:
+`claimed` deliberately makes no assertion about advertiser conversion: that is
+asynchronous and server-authoritative. Verify entitlements and conversions
+server-side, by user, never from the client.
+
+## Use Cases
+
+A placement's **use case** says *why* it presents — and it is what selects the
+composition. It defaults to `'reduceChurn'`.
+
+| Value | Composition | Meaning |
+|:------|:------------|:--------|
+| `'reduceChurn'` | Offer carousel | The default. A user is cancelling or downgrading; the offer is an alternative to leaving. |
+| `'rewardUsers'` | Reward composition | The user completed something worth celebrating — a purchase, a milestone, a streak, a level. The offer is a gift. |
+
+It is both a plain placement option and a builder step — use whichever reads
+better:
 
 ```typescript
-Encore.placement('milestone_reached', { useCase: 'post-action-reward' });
+Encore.placement('milestone_reached', { useCase: 'rewardUsers' });
+Encore.placement('milestone_reached').useCase('rewardUsers');
 ```
 
-| Value | Meaning |
-|:------|:--------|
-| `'churn-intervention'` | The default. A user is cancelling or downgrading; the offer is an alternative to leaving. |
-| `'post-action-reward'` | The user completed something worth celebrating — a purchase, a milestone, a streak, a level. The offer is a gift. |
+> **The wire values are unchanged.** `reduceChurn` / `rewardUsers` are the
+> TypeScript symbols. Over HTTP the SDK still sends `churn-intervention` /
+> `post-action-reward` (`GET /config?useCase=`, `POST /transactions`, and the
+> `use_case` analytics property), so existing dashboards and attribution are
+> unaffected by the rename.
 
 ### Supplying your own headline and subheadline
 
@@ -137,57 +159,44 @@ Pass your copy at presentation time. This is the intended way to set it — you
 know what the user just did, so you can name it:
 
 ```typescript
-await Encore.placement('milestone_reached')
-  .useCase('post-action-reward')
-  .headline('Nice work, Sam!')
-  .subheadline('That is your fifth week running')
-  .show();
+await Encore.placement('milestone_reached', {
+  useCase: 'rewardUsers',
+  headline: 'Nice work, Sam!',
+  subheadline: 'That is your fifth week running',
+}).show();
 ```
 
 Both are **per-call overrides**: they beat whatever copy Encore resolved for the
-surface, and they work on either use case. `.headline()` fills the sheet's
-primary heading and `.subheadline()` the line under it.
-
-They are also available as a plain option, if you are already passing others:
-
-```typescript
-await Encore.show(undefined, {
-  useCase: 'post-action-reward',
-  header: { title: 'Nice work, Sam!', subtitle: 'That is your fifth week running' },
-});
-```
+surface, and they work on either use case. `headline` fills the sheet's primary
+heading and `subheadline` the line under it.
 
 > **Blank falls through — it does not clear the copy.** A blank or
 > whitespace-only value is treated as "not supplied" and falls through to the
 > copy Encore resolved, so passing `''` is never a way to blank the sheet. Omit
-> the call instead. This keeps a value that is empty because an interpolation
-> came back empty (`.headline(\`Nice work, ${name}!\`)` with no `name`) from
-> rendering a headless sheet.
+> the option instead. This keeps a value that is empty because an interpolation
+> came back empty — a `headline` built from a template literal whose `name` was
+> undefined — from rendering a headless sheet.
 
 If you supply neither, the sheet falls back to Encore's resolved copy for the
 surface, and finally to a built-in string, so the heading is never empty.
 
-### `post-action-reward` grants no entitlement
+### `rewardUsers` grants no entitlement
 
 A reward claim is a gift the brand funds directly, not a subscription unlock. So
 `show()` resolves `{ status: 'claimed' }` and **no entitlement is granted** — on
 this path the SDK skips the automatic provisional grant it performs for
-`'churn-intervention'`, so no grant signal reaches Encore. Nothing was promised,
-so nothing is unlocked. (Reward activation is confirmed server-side via the
+`'reduceChurn'`, so no grant signal reaches Encore. Nothing was promised, so
+nothing is unlocked. (Reward activation is confirmed server-side via the
 offer-completed webhook, an entirely separate mechanism.)
 
 This is why `claimed` is its own result and not folded into `dismissed`: a user
 who successfully claimed a reward must never run your "user declined" branch.
 
-> That guarantee is on `show()`'s `ShowResult`. The deprecated `presentOffer()`
-> predates it and still reports a **deferred** claim as `granted: false`, so use
-> `show()` for any reward placement.
-
 ### Unrecognised values fail closed
 
 Anything that is not one of the two values above is rejected before anything is
-presented, rather than quietly falling back to the churn-intervention surface.
-`show()` still never rejects — it resolves:
+presented, rather than quietly falling back to the churn surface. `show()` still
+never rejects — it resolves:
 
 ```typescript
 { status: 'dismissed', reason: { type: 'error', error: { code: 'INVALID_REQUEST', … } } }