@encorekit/web-sdk 1.1.21 → 2.0.1

package/README.md

@@ -5,6 +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** - `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
@@ -15,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:
@@ -24,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
@@ -42,65 +61,190 @@ 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' },
-});
+})
+  .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'
+);
+```
+
+`Encore.show()`'s first argument is **callbacks only** — `onGranted`,
+`onNotGranted`, `onError`. Every other option is a placement option.
+
+### `PlacementOptions`
+
+| 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. |
+
+### The result
+
+`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. |
+
+`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.
 
-// 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' } });
+## 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: 'rewardUsers' });
+Encore.placement('milestone_reached').useCase('rewardUsers');
+```
+
+> **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
+
+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: 'rewardUsers',
+  headline: 'Nice work, Sam!',
+  subheadline: 'That is your fifth week running',
+}).show();
 ```
 
-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 }`.
+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.
+
+> **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 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.
+
+### `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
+`'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.
+
+### 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 surface. `show()` still
+never rejects — it resolves:
+
+```typescript
+{ status: 'dismissed', reason: { type: 'error', error: { code: 'INVALID_REQUEST', … } } }
+```
+
+If you call `Encore.show({ onError, onNotGranted }, { useCase })`, both callbacks
+fire. Via `Encore.placement(...)` only the builder's `.onNotGranted()` exists —
+there is no `.onError()` on the builder — so read the returned `reason.error`.
+
+### Enablement affects SPEED, not availability
+
+Requesting a use case is all it takes to be served it. There is no setup call,
+and you do not need Encore to switch anything on first:
+
+| Your app | What happens |
+|:---------|:-------------|
+| Enabled for the use case | Its config arrives with the one `/config` fetch at `configure()` — the first presentation is **instant** |
+| Not enabled | The SDK fetches that one surface on the **first** present, then caches it — **slower once**, instant thereafter |
+
+When the second row applies the SDK logs a one-off `[INTEGRATION]` notice saying
+the surface was not prefetched. It is a **speed hint, not an error** — nothing has
+failed. Ask Encore to enable the use case for your app to remove the first-present
+round trip.
+
+> **Encore can still switch a surface off.** An explicit kill switch is the one
+> thing that blocks serving, and it is deliberate — it is how a live surface is
+> stopped without a deploy. A switched-off surface no-ops exactly as below.
+
+### When nothing presents
+
+A use case that cannot be served resolves `{ status: 'unavailable' }`, reports
+`sdk_offer_presentation_failed` with reason `no_template`, and **never** falls back
+to another use case's offers or copy. It does not throw.
+
+`unavailable` is the same result you get when there are simply no eligible offers,
+and it has several causes — so do not read it as "not enabled":
+
+- Encore has switched the surface off, or no variant was eligible for it;
+- the `/config` response had not arrived within ~2.5s of the call, or failed;
+- the on-demand fetch for the surface failed.
+
+> ⚠️ **This is silent by default.** The explanatory log is emitted at `info`, and
+> every log level is gated behind `logLevel: 'debug'` — which is not the default.
+> When integrating a reward placement, configure `logLevel: 'debug'` and confirm
+> you see an actual presentation. A clean console is not evidence that it worked.
+
+See [the use-case serving model](https://github.com/EncoreKit/web-sdk/blob/main/docs/architecture/use-case-serving.md)
+for the full design note.
 
 ## Browser Support