One npm install. Full SaaS backend.

import { ApiVersion } from '@buildbase/sdk';
import { SaaSOSProvider } from '@buildbase/sdk/react';

export default function Providers({ children }) {
  return (
    <SaaSOSProvider
      serverUrl="https://api.yourapp.com"
      version={ApiVersion.V1}
      orgId="your-org-id"
      auth={{
        clientId: 'your-client-id',
        redirectUrl: 'http://localhost:3000',
      }}
      locale="en" // en, es, fr, de, ja, zh, hi, ar
    >
      {children}
    </SaaSOSProvider>
  );
}

import {
  useSaaSAuth,
  WhenAuthenticated,
  WhenUnauthenticated,
} from '@buildbase/sdk/react';

function App() {
  const { user, signIn, signOut, openWorkspaceSettings } = useSaaSAuth();

  return (
    <>
      <WhenUnauthenticated>
        <button onClick={() => signIn()}>Sign In</button>
      </WhenUnauthenticated>

      <WhenAuthenticated>
        <p>Welcome, {user?.name}</p>
        <button onClick={() => openWorkspaceSettings('subscription')}>
          Manage Plan
        </button>
        <button onClick={signOut}>Sign Out</button>
      </WhenAuthenticated>
    </>
  );
}

import {
  useSubscription,
  useTrialStatus,
  useCreateCheckoutSession,
  WhenTrialEnding,
  WhenNoSubscription,
  WhenSubscriptionToPlans,
} from '@buildbase/sdk/react';

function BillingPage({ workspaceId }) {
  const { subscription } = useSubscription(workspaceId);
  const { isTrialing, daysRemaining } = useTrialStatus();
  const { createCheckoutSession } = useCreateCheckoutSession(workspaceId);

  return (
    <>
      <WhenTrialEnding daysThreshold={3}>
        <Banner>{daysRemaining} days left in your trial.</Banner>
      </WhenTrialEnding>

      <WhenNoSubscription>
        <button onClick={() => createCheckoutSession({
          planVersionId: 'pro-v1',
          billingInterval: 'monthly',
        })}>
          Subscribe to Pro
        </button>
      </WhenNoSubscription>

      <WhenSubscriptionToPlans plans={['starter']}>
        <UpgradePrompt />
      </WhenSubscriptionToPlans>
    </>
  );
}

import {
  useCreditBalance,
  useConsumeCredits,
  useExpiringCredits,
  WhenCreditsExhausted,
  WhenCreditsLow,
} from '@buildbase/sdk/react';

function AIFeature({ workspaceId }) {
  const { balance } = useCreditBalance(workspaceId);
  const { consumeCredits } = useConsumeCredits(workspaceId);
  const { expiringCredits } = useExpiringCredits(workspaceId, 7);

  const handleGenerate = async () => {
    try {
      await consumeCredits({ amount: 10, description: 'AI generation' });
      // proceed with generation
    } catch (err) {
      if (err.code === 'INSUFFICIENT_CREDITS') {
        // err.available and err.requested are available
      }
    }
  };

  return (
    <>
      <p>Credits: {balance?.available}</p>
      {expiringCredits > 0 && <p>{expiringCredits} credits expire soon</p>}

      <WhenCreditsLow threshold={10}>
        <p>Running low — buy more credits.</p>
      </WhenCreditsLow>

      <WhenCreditsExhausted>
        <p>No credits left.</p>
      </WhenCreditsExhausted>

      <button onClick={handleGenerate}>Generate (10 credits)</button>
    </>
  );
}

import BuildBase from '@buildbase/sdk';

const bb = BuildBase({
  serverUrl: 'https://api.yourapp.com',
  orgId: 'your-org-id',
  getSessionId: async () => {
    const cookies = await getCookies();
    return cookies.get('bb-session')?.value ?? null;
  },
});

// API route — record usage and enforce quota
export async function POST(req) {
  const usage = await bb.usage.record(workspaceId, {
    quotaSlug: 'api-calls',
    quantity: 1,
    idempotencyKey: req.headers.get('x-request-id'),
  });

  if (usage.available <= 0) {
    return Response.json({ error: 'Quota exceeded' }, { status: 429 });
  }

  return Response.json({ remaining: usage.available });
}

// Background job — use withSession() for non-request contexts
const api = bb.withSession(serviceAccountSessionId);
await api.credits.consume(workspaceId, { amount: 50 });
await api.notification.send(workspaceId, 'job-completed');

import { parseWebhookEvent } from '@buildbase/sdk';

export async function POST(req) {
  const body = await req.text();

  // Verifies the signature and parses the payload — returns null on failure
  const parsed = parseWebhookEvent({
    body,
    signature: req.headers.get('x-buildbase-signature'),
    timestamp: req.headers.get('x-buildbase-timestamp'),
    secret: process.env.WEBHOOK_SECRET,
  });

  if (!parsed) {
    return Response.json({ error: 'Invalid signature' }, { status: 401 });
  }

  switch (parsed.event) {
    case 'subscription.upgraded':
      await enablePremiumFeatures(parsed.data.workspaceId);
      break;
    case 'credit.low_balance':
      await notifyTeam(parsed.data.workspaceId);
      break;
    case 'workspace.member_added':
      await syncToExternalCRM(parsed.data);
      break;
  }

  return Response.json({ received: true });
}