Protect a feature

Suppose exporting a report requires a paid plan. The user clicks Export; your app checks access, opens an upgrade offer if needed, refreshes access after checkout, and lets the server make the final decision about the export.

1. Prepare the offer and access check

1. Publish an upgrade offer with the slug upgrade. Test its price and checkout flow.
2. In your own authenticated app, expose a read endpoint such as /api/access/export that returns { "canExport": true } or { "canExport": false } for the current user. That route is your application code, not a Plandalf endpoint.
3. Protect the actual export endpoint on your server. It must check the current customer's entitlement even if the browser says access is allowed. Arrange for confirmed purchases to update that entitlement record.

The examples below assume your access endpoint and purchase handoff are working. Replace https://your-org.plandalf.dev with your organization host.

2. Connect the feature button

<script defer src="https://your-org.plandalf.dev/js/plandalf-sdk.js"></script>
<button data-plandalf-present="upgrade">
  Unlock export
</button>

import { Plandalf } from '@plandalf/sdk'

async function readAccess() {
  const response = await fetch('/api/access/export')
  if (!response.ok) throw new Error('Could not check export access')
  return response.json()
}

const sdk = new Plandalf({ apiBase: 'https://your-org.plandalf.dev' })
let current = await readAccess()
sdk.addGate('export', 'upgrade', (fresh) =>
  fresh?.canExport ?? current.canExport,
)

document.querySelector('#export').addEventListener('click', async () => {
  const result = await sdk.gate('export', async () => {
    current = await readAccess()
    return current
  })

  if (result.access) {
    // Call your protected export endpoint; it checks access again.
  } else if (result.status === 'error') {
    // Show a retry or pending message, not the protected file.
  }
})

<button id="export">Export report</button>

import { useCallback } from 'react'
import { PlandalfProvider, useGate } from '@plandalf/react'

async function readAccess() {
  const response = await fetch('/api/access/export')
  if (!response.ok) throw new Error('Could not check export access')
  return response.json() as Promise<{ canExport: boolean }>
}

function ExportButton() {
  const check = useCallback(async (fresh?: { canExport: boolean }) =>
    fresh?.canExport ?? (await readAccess()).canExport, [])
  const { access, checking, trigger } = useGate('export', 'upgrade', check)

  async function exportReport() {
    const result = await trigger(readAccess)
    if (result.access) {
      // Call your protected export endpoint; it checks access again.
    }
  }

  return <button disabled={checking} onClick={exportReport}>
    {access ? 'Export report' : 'Unlock export'}
  </button>
}

export function ExportFeature() {
  return <PlandalfProvider apiBase="https://your-org.plandalf.dev">
    <ExportButton />
  </PlandalfProvider>
}

3. Verify denied, dismissed, and paid states

1. As a user without access, click Export. The upgrade checkout should open. Dismiss it: export stays blocked.
2. After confirming that the offer and integration are explicitly configured for sandbox use, complete a provider-supported test checkout. A mode: 'test' override can fall back to live for public visitors. If your confirmed-purchase handoff has not yet updated entitlement, keep access pending; do not hand over the report because checkout returned complete.
3. After your server records access, click again. The gate should allow the action without reopening checkout, and the export endpoint must independently allow it.
4. Test a failed access request. It should deny the action and show an error or retry state.

The checked-out SDK source reruns the gate check after sync; verify the installed package version before relying on that client behavior. The server authorization check is still required. A denied gate has already opened its fallback offer, so do not call present() again. See the complete feature example, gate(), and GateResult for the exact outcomes.