@billing-saas/usage-sdk

SDK TypeScript pour intégrer le PU Billing SaaS dans votre application Next.js.

Gérez vos plans, abonnements, checkout Stripe et feature gates en quelques lignes.

Installation

npm install @billing-saas/usage-sdk

Démarrage rapide

1. Créez votre compte tenant

Rendez-vous sur dev.billingsaas.187.124.95.146.sslip.io/tenant/register, créez votre espace et copiez votre clé API depuis l'onboarding.

2. Configurez .env.local

BILLING_API_URL=http://dev.billingsaas.187.124.95.146.sslip.io/api
BILLING_API_KEY=bsk_live_...
NEXT_PUBLIC_APP_URL=https://votre-app.com

⚠️ Ne jamais exposer BILLING_API_KEY côté client. Pas de NEXT_PUBLIC_.

3. Initialisez le client (serveur uniquement)

// src/lib/billing.ts
import { BillingClient } from '@billing-saas/usage-sdk'

export const billing = new BillingClient({
  apiKey:  process.env.BILLING_API_KEY!,
  baseUrl: process.env.BILLING_API_URL!,
})

4. Route API — plans

// src/app/api/billing/plans/route.ts
import { NextResponse } from 'next/server'
import { billing } from '@/lib/billing'

export async function GET() {
  const plans = await billing.plans.list()
  return NextResponse.json({ plans })
}

5. Route API — checkout Stripe

// src/app/api/billing/checkout/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { billing } from '@/lib/billing'

export async function POST(req: NextRequest) {
  const { planId, period = 'monthly' } = await req.json()
  const user = await getSession() // votre système d'auth

  const result = await billing.customers.checkout(user.id, {
    plan_id:     planId,
    period,
    success_url: `${process.env.NEXT_PUBLIC_APP_URL}/billing/success`,
    cancel_url:  `${process.env.NEXT_PUBLIC_APP_URL}/pricing`,
  })

  return NextResponse.json(result)
}

6. Abonnement actif

// src/app/api/billing/subscription/route.ts
import { NextResponse } from 'next/server'
import { billing } from '@/lib/billing'

export async function GET() {
  const user = await getSession()

  // Synchronise le customer (idempotent)
  await billing.customers.upsert({
    external_id: user.id,
    email:       user.email,
    name:        user.name,
  })

  const { subscription } = await billing.customers.subscription(user.id)
  return NextResponse.json({ subscription })
}

API

BillingClient

const billing = new BillingClient({ apiKey: string, baseUrl?: string })

Plans

| Méthode | Description | |---|---| | billing.plans.list() | Liste tous les plans disponibles | | billing.plans.get(id) | Récupère un plan par ID |

Customers

| Méthode | Description | |---|---| | billing.customers.upsert(input) | Crée ou met à jour un customer (idempotent) | | billing.customers.get(externalId) | Récupère un customer | | billing.customers.subscription(externalId) | Abonnement actif (null si aucun) | | billing.customers.checkout(externalId, input) | Crée une Stripe Checkout Session | | billing.customers.portal(externalId, returnUrl) | URL vers le Stripe Billing Portal | | billing.customers.invoices(externalId) | Historique des factures |

Types

interface SdkPlan {
  id: number
  name: string
  price_monthly: string
  price_yearly: string
  features: string[]
}

interface SdkSubscription {
  id: number
  status: 'active' | 'trialing' | 'past_due' | 'canceled'
  plan: SdkPlan
  current_period_end: string
}

interface CheckoutInput {
  plan_id: number
  period?: 'monthly' | 'yearly'
  success_url: string
  cancel_url: string
}

Licence

MIT