@themodcraft/addon-paywall

Paywall helpers for UI gating.

Contains:

• Paywall provider
• Entitlement gate components
• License-aware fallback helpers

Install:

npm install @themodcraft/addon-paywall

This package publishes compiled output only.

API-backed product access

Plans can be mapped from active Store API offers, while entitlements come from the signed-in account. onCheckout is the integration point for creating a server checkout session; a plan does not need a hard-coded checkout URL.

import { PaywallGate, PaywallProvider } from "@themodcraft/addon-paywall";

<PaywallProvider
  plans={offers.map((offer) => ({
    entitlements: [offer.entitlementKey],
    id: offer.id,
    label: offer.name,
    priceLabel: offer.localizedPrice,
  }))}
  resolveEntitlements={async () => {
    const response = await fetch("/api/account/entitlements", { credentials: "include" });
    if (!response.ok) throw new Error("Could not refresh entitlements.");
    return (await response.json()).entitlements;
  }}
  onCheckout={async (plan) => {
    const response = await fetch("/api/store/checkout-sessions", {
      body: JSON.stringify({ offerId: plan?.id }),
      credentials: "include",
      headers: { "content-type": "application/json" },
      method: "POST",
    });
    if (!response.ok) throw new Error("Could not start checkout.");
    window.location.assign((await response.json()).checkoutUrl);
  }}
>
  <PaywallGate loadingFallback={<p>Checking access…</p>} required="product:tmc-oxide">
    <DownloadPanel />
  </PaywallGate>
</PaywallProvider>;

After the application verifies a checkout return with its API, call refreshEntitlements() from usePaywall() before showing protected downloads. The fallback renderer receives the current loading, error, or ready decision plus checkout/refresh actions; provider-specific pending and error copy can remain in the application.