Feature gating guide

import { useFlag, useFlags, useEntitlement } from "@arcenpay/react";

function Dashboard() {
  const analyticsEnabled = useFlag("analytics_export");
  const flags = useFlags(["scan", "export_pdf", "priority_support"]);
  const entitlement = useEntitlement(walletAddress, "analytics_export");

  return (
    <div>
      {analyticsEnabled && <AnalyticsPanel />}
      {flags.scan && <ScanButton />}

      <p>
        {entitlement.usage} of {entitlement.limit} exports used
      </p>
    </div>
  );
}

import { ArcenClient } from "@arcenpay/node";

const client = new ArcenClient({
  apiKey: process.env.ARCENPAY_API_KEY!,
});

async function handleExport(companyId: string) {
  const entitlement = await client.checkEntitlement("export_pdf", { id: companyId });

  if (!entitlement.enabled) {
    throw new Error("Export is not available on your plan");
  }

  // Perform the export...
}

// Server-side — authoritative
const result = await client.consumeEntitlement({
  featureKey: "scan",
  company: { id: companyId },
  idempotencyKey: `scan-${requestId}`,
});

if (result.exceeded) {
  return Response.json({ error: "Limit exceeded" }, { status: 402 });
}

// Client-side — convenient
import { useConsumeEntitlement } from "@arcenpay/react";

function ScanButton() {
  const { consume } = useConsumeEntitlement();

  async function handleScan() {
    const result = await consume("scan");
    if (result.exceeded) {
      alert("Scan limit reached. Upgrade to continue.");
    }
  }

  return <button onClick={handleScan}>Scan</button>;
}

await client.track({
  event: "onboarding_complete",
  company: { id: "company_123" },
  properties: { step: "final" },
});

// 1. Server-side: check access in API route
export async function GET(request: Request) {
  const { companyId } = auth(request);
  const access = await client.checkEntitlement("analytics_export", { id: companyId });
  if (!access.enabled) return Response.json({ error: "Upgrade required" }, { status: 402 });
  return Response.json({ data: await getAnalytics() });
}

// 2. Client-side: gate UI and handle upgrade prompt
function AnalyticsPage() {
  const hasAccess = useFlag("analytics_export");

  if (!hasAccess) {
    return (
      <UpgradeCard>
        <p>Analytics export is available on the Pro plan.</p>
        <ArcenEmbed mode="modal" initialView="checkout" />
      </UpgradeCard>
    );
  }

  return <AnalyticsData />;
}