@encorekit/web-sdk 1.1.21 → 2.0.0

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** - Churn intervention (the default) or post-action rewards — 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
@@ -102,6 +103,140 @@ Notes:
   verify entitlements/conversions server-side by user, never from the client).
   `show()` never rejects: failures resolve as `{ status: 'dismissed', reason }`.
 
+## Use Cases
+
+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.
+
+```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();
+
+if (result.status === 'claimed') {
+  // The user claimed an offer. Render your own confirmation.
+}
+```
+
+It is also a plain placement option, if you prefer that form:
+
+```typescript
+Encore.placement('milestone_reached', { useCase: 'post-action-reward' });
+```
+
+| 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. |
+
+### 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('post-action-reward')
+  .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' },
+});
+```
+
+> **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.
+
+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
+
+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
+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:
+
+```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
 
 - Chrome/Edge (last 2 versions)