@billing-saas/usage-sdk 0.1.0

package/README.md

@@ -0,0 +1,152 @@
+# @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
+
+```bash
+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](http://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`
+
+```env
+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)
+
+```ts
+// 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
+
+```ts
+// 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
+
+```ts
+// 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
+
+```ts
+// 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`
+
+```ts
+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
+
+```ts
+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

package/dist/index.d.mts

@@ -0,0 +1,281 @@
+interface UsageEventInput {
+    metric: string;
+    quantity: number;
+    /** Clé unique pour déduplication. Générée automatiquement si absente. */
+    idempotencyKey?: string;
+    recordedAt?: Date | string;
+    metadata?: Record<string, unknown>;
+}
+interface UsageEventResponse {
+    id: number;
+    user_id: number;
+    subscription_id: number | null;
+    org_id: string | null;
+    metric: string;
+    quantity: string;
+    idempotency_key: string;
+    recorded_at: string;
+    billed_at: string | null;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+    updated_at: string;
+}
+interface BatchResult {
+    created: number;
+    duplicate: number;
+    keys: {
+        created: string[];
+        duplicate: string[];
+    };
+}
+interface UsageSummary {
+    period_start: string;
+    period_end: string;
+    usage: Record<string, {
+        metric: string;
+        total: string;
+        events: number;
+    }>;
+}
+interface QuotaMetric {
+    used: number;
+    limit: number | null;
+    pct: number | null;
+    status: 'ok' | 'warning' | 'critical' | 'exceeded' | 'unlimited';
+}
+type QuotaStatus = Record<string, QuotaMetric>;
+interface UsageClientOptions {
+    baseUrl: string;
+    apiToken: string;
+    /** Timeout en ms (défaut : 10 000) */
+    timeout?: number;
+}
+
+declare class UsageError extends Error {
+    readonly statusCode: number;
+    readonly body: unknown;
+    constructor(message: string, statusCode: number, body: unknown);
+}
+interface UsageClientAdvancedOptions extends UsageClientOptions {
+    /** Active le buffering automatique (défaut: false) */
+    autoQueue?: boolean;
+    /** Taille max du buffer avant flush forcé (défaut: 50) */
+    queueMaxSize?: number;
+    /** Intervalle de flush en ms (défaut: 5000) */
+    flushInterval?: number;
+    /** Nombre de tentatives en cas d'erreur 5xx (défaut: 3) */
+    maxRetries?: number;
+    /** Délai initial entre retries en ms (défaut: 300) */
+    retryDelay?: number;
+    /** Callback appelé avant chaque envoi (enrichissement, logging) */
+    beforeSend?: (event: UsageEventInput) => UsageEventInput | null;
+}
+/**
+ * Client TypeScript pour l'API Usage de Billing SaaS.
+ *
+ * @example
+ * // Mode direct
+ * const client = new UsageClient({ baseUrl: '...', apiToken: '...' })
+ * await client.record({ metric: 'api_calls', quantity: 1 })
+ *
+ * @example
+ * // Mode queue (batch automatique)
+ * const client = new UsageClient({ baseUrl: '...', apiToken: '...', autoQueue: true })
+ * client.track({ metric: 'page_view', quantity: 1 })  // non-bloquant
+ */
+declare class UsageClient {
+    private readonly baseUrl;
+    private readonly apiToken;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly retryDelay;
+    private readonly beforeSend?;
+    private queue;
+    constructor(opts: UsageClientAdvancedOptions);
+    /**
+     * Enregistre un événement de façon synchrone (direct API call).
+     */
+    record(event: UsageEventInput): Promise<UsageEventResponse>;
+    /**
+     * Ajoute un événement dans le buffer (non-bloquant).
+     * Nécessite `autoQueue: true` à la construction.
+     */
+    track(event: UsageEventInput): void;
+    /**
+     * Vide le buffer immédiatement (utile avant navigations SPA).
+     */
+    flush(): Promise<void>;
+    /**
+     * Enregistre jusqu'à 100 événements en une seule requête.
+     */
+    batch(events: UsageEventInput[]): Promise<BatchResult>;
+    summary(): Promise<UsageSummary>;
+    quota(): Promise<QuotaStatus>;
+    /** Libère les ressources (timer de la queue). */
+    destroy(): void;
+    private applyBeforeSend;
+    private normalizeEvent;
+    private generateKey;
+    private post;
+    private get;
+    private request;
+}
+
+interface QueueOptions {
+    maxSize?: number;
+    flushInterval?: number;
+    onFlush: (events: UsageEventInput[]) => Promise<void>;
+    onError?: (err: unknown, events: UsageEventInput[]) => void;
+}
+/**
+ * Buffer d'événements avec flush automatique par intervalle ou par taille.
+ * Permet d'envoyer les événements en lot sans bloquer l'appelant.
+ */
+declare class EventQueue {
+    private queue;
+    private timer;
+    private readonly maxSize;
+    private readonly onFlush;
+    private readonly onError;
+    constructor({ maxSize, flushInterval, onFlush, onError }: QueueOptions);
+    push(event: UsageEventInput): void;
+    flush(): Promise<void>;
+    destroy(): void;
+}
+
+interface BillingClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+interface SdkCustomer {
+    id: number;
+    external_id: string;
+    email: string | null;
+    name: string | null;
+    stripe_customer_id: string | null;
+    metadata: Record<string, unknown> | null;
+    tenant_id: number;
+    active_subscription: SdkSubscription | null;
+    created_at: string;
+    updated_at: string;
+}
+interface SdkSubscription {
+    id: number;
+    status: 'active' | 'trialing' | 'past_due' | 'canceled' | 'paused';
+    billing_period: 'monthly' | 'yearly';
+    current_period_start: string | null;
+    current_period_end: string | null;
+    trial_ends_at: string | null;
+    canceled_at: string | null;
+    ends_at: string | null;
+    plan: SdkPlan;
+}
+interface SdkPlan {
+    id: number;
+    name: string;
+    slug: string;
+    type: string;
+    price_monthly: string;
+    price_yearly: string;
+    currency: string;
+    trial_days: number;
+    features: Record<string, boolean>;
+    max_users: number | null;
+    max_api_calls_per_month: number | null;
+    max_storage_bytes: number | null;
+}
+interface CheckoutResult {
+    checkout_url: string;
+    session_id: string;
+}
+interface PortalResult {
+    portal_url: string;
+}
+interface UpsertCustomerInput {
+    external_id: string;
+    email?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CheckoutInput {
+    plan_id: number;
+    period?: 'monthly' | 'yearly';
+    success_url: string;
+    cancel_url: string;
+    coupon?: string;
+}
+
+declare class BillingError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+/**
+ * Client SDK pour intégrer Billing SaaS dans votre application.
+ *
+ * @example
+ * ```ts
+ * import { BillingClient } from '@billing-saas/js'
+ *
+ * const billing = new BillingClient({ apiKey: 'bsk_live_...' })
+ *
+ * // Crée ou retrouve un customer
+ * const { customer } = await billing.customers.upsert({
+ *   external_id: 'user_123',
+ *   email: 'alice@example.com',
+ * })
+ *
+ * // Lance le checkout Stripe
+ * const { checkout_url } = await billing.customers.checkout('user_123', {
+ *   plan_id: 2,
+ *   success_url: 'https://yourapp.com/success',
+ *   cancel_url: 'https://yourapp.com/cancel',
+ * })
+ *
+ * window.location.href = checkout_url
+ * ```
+ */
+declare class BillingClient {
+    private readonly baseUrl;
+    private readonly headers;
+    constructor(options: BillingClientOptions);
+    readonly plans: {
+        list: () => Promise<SdkPlan[]>;
+        get: (id: number) => Promise<SdkPlan>;
+    };
+    readonly customers: {
+        /**
+         * Crée ou met à jour un customer (idempotent sur external_id).
+         */
+        upsert: (input: UpsertCustomerInput) => Promise<{
+            customer: SdkCustomer;
+        }>;
+        get: (externalId: string) => Promise<{
+            customer: SdkCustomer;
+        }>;
+        delete: (externalId: string) => Promise<{
+            message: string;
+        }>;
+        /**
+         * Subscription active du customer (null si aucune).
+         */
+        subscription: (externalId: string) => Promise<{
+            subscription: SdkSubscription | null;
+        }>;
+        /**
+         * Crée une Stripe Checkout Session — redirigez l'utilisateur vers checkout_url.
+         */
+        checkout: (externalId: string, input: CheckoutInput) => Promise<CheckoutResult>;
+        /**
+         * URL vers le Stripe Billing Portal (gestion CB, annulation, etc.).
+         */
+        portal: (externalId: string, returnUrl: string) => Promise<PortalResult>;
+        invoices: (externalId: string) => Promise<unknown>;
+    };
+    private get;
+    private post;
+    private delete;
+    private request;
+}
+
+export { type BatchResult, BillingClient, type BillingClientOptions, BillingError, type CheckoutInput, type CheckoutResult, EventQueue, type PortalResult, type QuotaMetric, type QuotaStatus, type SdkCustomer, type SdkPlan, type SdkSubscription, type UpsertCustomerInput, UsageClient, type UsageClientOptions, UsageError, type UsageEventInput, type UsageEventResponse, type UsageSummary };

package/dist/index.d.ts

@@ -0,0 +1,281 @@
+interface UsageEventInput {
+    metric: string;
+    quantity: number;
+    /** Clé unique pour déduplication. Générée automatiquement si absente. */
+    idempotencyKey?: string;
+    recordedAt?: Date | string;
+    metadata?: Record<string, unknown>;
+}
+interface UsageEventResponse {
+    id: number;
+    user_id: number;
+    subscription_id: number | null;
+    org_id: string | null;
+    metric: string;
+    quantity: string;
+    idempotency_key: string;
+    recorded_at: string;
+    billed_at: string | null;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+    updated_at: string;
+}
+interface BatchResult {
+    created: number;
+    duplicate: number;
+    keys: {
+        created: string[];
+        duplicate: string[];
+    };
+}
+interface UsageSummary {
+    period_start: string;
+    period_end: string;
+    usage: Record<string, {
+        metric: string;
+        total: string;
+        events: number;
+    }>;
+}
+interface QuotaMetric {
+    used: number;
+    limit: number | null;
+    pct: number | null;
+    status: 'ok' | 'warning' | 'critical' | 'exceeded' | 'unlimited';
+}
+type QuotaStatus = Record<string, QuotaMetric>;
+interface UsageClientOptions {
+    baseUrl: string;
+    apiToken: string;
+    /** Timeout en ms (défaut : 10 000) */
+    timeout?: number;
+}
+
+declare class UsageError extends Error {
+    readonly statusCode: number;
+    readonly body: unknown;
+    constructor(message: string, statusCode: number, body: unknown);
+}
+interface UsageClientAdvancedOptions extends UsageClientOptions {
+    /** Active le buffering automatique (défaut: false) */
+    autoQueue?: boolean;
+    /** Taille max du buffer avant flush forcé (défaut: 50) */
+    queueMaxSize?: number;
+    /** Intervalle de flush en ms (défaut: 5000) */
+    flushInterval?: number;
+    /** Nombre de tentatives en cas d'erreur 5xx (défaut: 3) */
+    maxRetries?: number;
+    /** Délai initial entre retries en ms (défaut: 300) */
+    retryDelay?: number;
+    /** Callback appelé avant chaque envoi (enrichissement, logging) */
+    beforeSend?: (event: UsageEventInput) => UsageEventInput | null;
+}
+/**
+ * Client TypeScript pour l'API Usage de Billing SaaS.
+ *
+ * @example
+ * // Mode direct
+ * const client = new UsageClient({ baseUrl: '...', apiToken: '...' })
+ * await client.record({ metric: 'api_calls', quantity: 1 })
+ *
+ * @example
+ * // Mode queue (batch automatique)
+ * const client = new UsageClient({ baseUrl: '...', apiToken: '...', autoQueue: true })
+ * client.track({ metric: 'page_view', quantity: 1 })  // non-bloquant
+ */
+declare class UsageClient {
+    private readonly baseUrl;
+    private readonly apiToken;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly retryDelay;
+    private readonly beforeSend?;
+    private queue;
+    constructor(opts: UsageClientAdvancedOptions);
+    /**
+     * Enregistre un événement de façon synchrone (direct API call).
+     */
+    record(event: UsageEventInput): Promise<UsageEventResponse>;
+    /**
+     * Ajoute un événement dans le buffer (non-bloquant).
+     * Nécessite `autoQueue: true` à la construction.
+     */
+    track(event: UsageEventInput): void;
+    /**
+     * Vide le buffer immédiatement (utile avant navigations SPA).
+     */
+    flush(): Promise<void>;
+    /**
+     * Enregistre jusqu'à 100 événements en une seule requête.
+     */
+    batch(events: UsageEventInput[]): Promise<BatchResult>;
+    summary(): Promise<UsageSummary>;
+    quota(): Promise<QuotaStatus>;
+    /** Libère les ressources (timer de la queue). */
+    destroy(): void;
+    private applyBeforeSend;
+    private normalizeEvent;
+    private generateKey;
+    private post;
+    private get;
+    private request;
+}
+
+interface QueueOptions {
+    maxSize?: number;
+    flushInterval?: number;
+    onFlush: (events: UsageEventInput[]) => Promise<void>;
+    onError?: (err: unknown, events: UsageEventInput[]) => void;
+}
+/**
+ * Buffer d'événements avec flush automatique par intervalle ou par taille.
+ * Permet d'envoyer les événements en lot sans bloquer l'appelant.
+ */
+declare class EventQueue {
+    private queue;
+    private timer;
+    private readonly maxSize;
+    private readonly onFlush;
+    private readonly onError;
+    constructor({ maxSize, flushInterval, onFlush, onError }: QueueOptions);
+    push(event: UsageEventInput): void;
+    flush(): Promise<void>;
+    destroy(): void;
+}
+
+interface BillingClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+interface SdkCustomer {
+    id: number;
+    external_id: string;
+    email: string | null;
+    name: string | null;
+    stripe_customer_id: string | null;
+    metadata: Record<string, unknown> | null;
+    tenant_id: number;
+    active_subscription: SdkSubscription | null;
+    created_at: string;
+    updated_at: string;
+}
+interface SdkSubscription {
+    id: number;
+    status: 'active' | 'trialing' | 'past_due' | 'canceled' | 'paused';
+    billing_period: 'monthly' | 'yearly';
+    current_period_start: string | null;
+    current_period_end: string | null;
+    trial_ends_at: string | null;
+    canceled_at: string | null;
+    ends_at: string | null;
+    plan: SdkPlan;
+}
+interface SdkPlan {
+    id: number;
+    name: string;
+    slug: string;
+    type: string;
+    price_monthly: string;
+    price_yearly: string;
+    currency: string;
+    trial_days: number;
+    features: Record<string, boolean>;
+    max_users: number | null;
+    max_api_calls_per_month: number | null;
+    max_storage_bytes: number | null;
+}
+interface CheckoutResult {
+    checkout_url: string;
+    session_id: string;
+}
+interface PortalResult {
+    portal_url: string;
+}
+interface UpsertCustomerInput {
+    external_id: string;
+    email?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CheckoutInput {
+    plan_id: number;
+    period?: 'monthly' | 'yearly';
+    success_url: string;
+    cancel_url: string;
+    coupon?: string;
+}
+
+declare class BillingError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+/**
+ * Client SDK pour intégrer Billing SaaS dans votre application.
+ *
+ * @example
+ * ```ts
+ * import { BillingClient } from '@billing-saas/js'
+ *
+ * const billing = new BillingClient({ apiKey: 'bsk_live_...' })
+ *
+ * // Crée ou retrouve un customer
+ * const { customer } = await billing.customers.upsert({
+ *   external_id: 'user_123',
+ *   email: 'alice@example.com',
+ * })
+ *
+ * // Lance le checkout Stripe
+ * const { checkout_url } = await billing.customers.checkout('user_123', {
+ *   plan_id: 2,
+ *   success_url: 'https://yourapp.com/success',
+ *   cancel_url: 'https://yourapp.com/cancel',
+ * })
+ *
+ * window.location.href = checkout_url
+ * ```
+ */
+declare class BillingClient {
+    private readonly baseUrl;
+    private readonly headers;
+    constructor(options: BillingClientOptions);
+    readonly plans: {
+        list: () => Promise<SdkPlan[]>;
+        get: (id: number) => Promise<SdkPlan>;
+    };
+    readonly customers: {
+        /**
+         * Crée ou met à jour un customer (idempotent sur external_id).
+         */
+        upsert: (input: UpsertCustomerInput) => Promise<{
+            customer: SdkCustomer;
+        }>;
+        get: (externalId: string) => Promise<{
+            customer: SdkCustomer;
+        }>;
+        delete: (externalId: string) => Promise<{
+            message: string;
+        }>;
+        /**
+         * Subscription active du customer (null si aucune).
+         */
+        subscription: (externalId: string) => Promise<{
+            subscription: SdkSubscription | null;
+        }>;
+        /**
+         * Crée une Stripe Checkout Session — redirigez l'utilisateur vers checkout_url.
+         */
+        checkout: (externalId: string, input: CheckoutInput) => Promise<CheckoutResult>;
+        /**
+         * URL vers le Stripe Billing Portal (gestion CB, annulation, etc.).
+         */
+        portal: (externalId: string, returnUrl: string) => Promise<PortalResult>;
+        invoices: (externalId: string) => Promise<unknown>;
+    };
+    private get;
+    private post;
+    private delete;
+    private request;
+}
+
+export { type BatchResult, BillingClient, type BillingClientOptions, BillingError, type CheckoutInput, type CheckoutResult, EventQueue, type PortalResult, type QuotaMetric, type QuotaStatus, type SdkCustomer, type SdkPlan, type SdkSubscription, type UpsertCustomerInput, UsageClient, type UsageClientOptions, UsageError, type UsageEventInput, type UsageEventResponse, type UsageSummary };

package/dist/index.js

@@ -0,0 +1,308 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BillingClient: () => BillingClient,
+  BillingError: () => BillingError,
+  EventQueue: () => EventQueue,
+  UsageClient: () => UsageClient,
+  UsageError: () => UsageError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/EventQueue.ts
+var EventQueue = class {
+  queue = [];
+  timer = null;
+  maxSize;
+  onFlush;
+  onError;
+  constructor({ maxSize = 50, flushInterval = 5e3, onFlush, onError }) {
+    this.maxSize = maxSize;
+    this.onFlush = onFlush;
+    this.onError = onError ?? ((err) => console.error("[UsageQueue]", err));
+    if (flushInterval > 0 && typeof setInterval !== "undefined") {
+      this.timer = setInterval(() => void this.flush(), flushInterval);
+    }
+    if (typeof window !== "undefined") {
+      window.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "hidden") void this.flush();
+      });
+    }
+  }
+  push(event) {
+    this.queue.push(event);
+    if (this.queue.length >= this.maxSize) {
+      void this.flush();
+    }
+  }
+  async flush() {
+    if (this.queue.length === 0) return;
+    const batch = this.queue.splice(0, this.queue.length);
+    try {
+      await this.onFlush(batch);
+    } catch (err) {
+      this.onError(err, batch);
+    }
+  }
+  destroy() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+};
+
+// src/UsageClient.ts
+var UsageError = class extends Error {
+  constructor(message, statusCode, body) {
+    super(message);
+    this.statusCode = statusCode;
+    this.body = body;
+    this.name = "UsageError";
+  }
+  statusCode;
+  body;
+};
+var UsageClient = class {
+  baseUrl;
+  apiToken;
+  timeout;
+  maxRetries;
+  retryDelay;
+  beforeSend;
+  queue = null;
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+    this.apiToken = opts.apiToken;
+    this.timeout = opts.timeout ?? 1e4;
+    this.maxRetries = opts.maxRetries ?? 3;
+    this.retryDelay = opts.retryDelay ?? 300;
+    this.beforeSend = opts.beforeSend;
+    if (opts.autoQueue) {
+      this.queue = new EventQueue({
+        maxSize: opts.queueMaxSize ?? 50,
+        flushInterval: opts.flushInterval ?? 5e3,
+        onFlush: (events) => this.batch(events).then(() => void 0),
+        onError: (err) => console.error("[UsageClient:queue]", err)
+      });
+    }
+  }
+  /**
+   * Enregistre un événement de façon synchrone (direct API call).
+   */
+  async record(event) {
+    const payload = this.applyBeforeSend(this.normalizeEvent(event));
+    if (!payload) return Promise.reject(new Error("beforeSend filtered event"));
+    return this.post("/v1/usage/events", payload);
+  }
+  /**
+   * Ajoute un événement dans le buffer (non-bloquant).
+   * Nécessite `autoQueue: true` à la construction.
+   */
+  track(event) {
+    if (!this.queue) {
+      throw new Error("autoQueue est d\xE9sactiv\xE9. Passez autoQueue:true ou utilisez record().");
+    }
+    const normalized = this.applyBeforeSend(this.normalizeEvent(event));
+    if (normalized) this.queue.push(normalized);
+  }
+  /**
+   * Vide le buffer immédiatement (utile avant navigations SPA).
+   */
+  async flush() {
+    var _a;
+    await ((_a = this.queue) == null ? void 0 : _a.flush());
+  }
+  /**
+   * Enregistre jusqu'à 100 événements en une seule requête.
+   */
+  async batch(events) {
+    if (events.length === 0) {
+      return { created: 0, duplicate: 0, keys: { created: [], duplicate: [] } };
+    }
+    if (events.length > 100) {
+      throw new RangeError("Le lot ne peut pas d\xE9passer 100 \xE9v\xE9nements.");
+    }
+    return this.post("/v1/usage/batch", {
+      events: events.map((e) => this.normalizeEvent(e))
+    });
+  }
+  async summary() {
+    return this.get("/v1/usage/summary");
+  }
+  async quota() {
+    return this.get("/v1/usage/quota");
+  }
+  /** Libère les ressources (timer de la queue). */
+  destroy() {
+    var _a;
+    (_a = this.queue) == null ? void 0 : _a.destroy();
+  }
+  // ── Helpers ────────────────────────────────────────────────────────────────
+  applyBeforeSend(event) {
+    return this.beforeSend ? this.beforeSend(event) : event;
+  }
+  normalizeEvent(event) {
+    return {
+      ...event,
+      idempotencyKey: event.idempotencyKey ?? this.generateKey(event.metric)
+    };
+  }
+  generateKey(metric) {
+    const rand = Math.random().toString(36).slice(2);
+    return `${metric}:${Date.now()}:${rand}`;
+  }
+  async post(path, body) {
+    return this.request("POST", path, body);
+  }
+  async get(path, params) {
+    const url = params ? `${path}?${new URLSearchParams(params)}` : path;
+    return this.request("GET", url);
+  }
+  async request(method, path, body) {
+    let lastError;
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+          const resp = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+              Authorization: `Bearer ${this.apiToken}`,
+              "Content-Type": "application/json",
+              Accept: "application/json"
+            },
+            body: body != null ? JSON.stringify(body) : void 0,
+            signal: controller.signal
+          });
+          const data = await resp.json().catch(() => ({}));
+          if (!resp.ok) {
+            const message = data["message"] ?? `HTTP ${resp.status}`;
+            const err = new UsageError(message, resp.status, data);
+            if (resp.status >= 400 && resp.status < 500) throw err;
+            lastError = err;
+          } else {
+            return data;
+          }
+        } finally {
+          clearTimeout(timer);
+        }
+      } catch (err) {
+        if (err instanceof UsageError && err.statusCode >= 400 && err.statusCode < 500) {
+          throw err;
+        }
+        lastError = err;
+      }
+      if (attempt < this.maxRetries - 1) {
+        await sleep(this.retryDelay * 2 ** attempt);
+      }
+    }
+    throw lastError;
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/BillingClient.ts
+var BillingError = class extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "BillingError";
+  }
+  status;
+  body;
+};
+var BillingClient = class {
+  baseUrl;
+  headers;
+  constructor(options) {
+    this.baseUrl = (options.baseUrl ?? "http://localhost:8000/api").replace(/\/$/, "");
+    this.headers = {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${options.apiKey}`
+    };
+  }
+  // ─── Plans ────────────────────────────────────────────────────────────────
+  plans = {
+    list: () => this.get("/v1/sdk/plans"),
+    get: (id) => this.get(`/v1/sdk/plans/${id}`)
+  };
+  // ─── Customers ────────────────────────────────────────────────────────────
+  customers = {
+    /**
+     * Crée ou met à jour un customer (idempotent sur external_id).
+     */
+    upsert: (input) => this.post("/v1/sdk/customers", input),
+    get: (externalId) => this.get(`/v1/sdk/customers/${encodeURIComponent(externalId)}`),
+    delete: (externalId) => this.delete(`/v1/sdk/customers/${encodeURIComponent(externalId)}`),
+    /**
+     * Subscription active du customer (null si aucune).
+     */
+    subscription: (externalId) => this.get(`/v1/sdk/customers/${encodeURIComponent(externalId)}/subscription`),
+    /**
+     * Crée une Stripe Checkout Session — redirigez l'utilisateur vers checkout_url.
+     */
+    checkout: (externalId, input) => this.post(`/v1/sdk/customers/${encodeURIComponent(externalId)}/checkout`, input),
+    /**
+     * URL vers le Stripe Billing Portal (gestion CB, annulation, etc.).
+     */
+    portal: (externalId, returnUrl) => this.post(`/v1/sdk/customers/${encodeURIComponent(externalId)}/portal`, { return_url: returnUrl }),
+    invoices: (externalId) => this.get(`/v1/sdk/customers/${encodeURIComponent(externalId)}/invoices`)
+  };
+  // ─── HTTP helpers ─────────────────────────────────────────────────────────
+  async get(path) {
+    return this.request("GET", path);
+  }
+  async post(path, body) {
+    return this.request("POST", path, body);
+  }
+  async delete(path) {
+    return this.request("DELETE", path);
+  }
+  async request(method, path, body) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: this.headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+      throw new BillingError(
+        (data == null ? void 0 : data.message) ?? `HTTP ${res.status}`,
+        res.status,
+        data
+      );
+    }
+    return data;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BillingClient,
+  BillingError,
+  EventQueue,
+  UsageClient,
+  UsageError
+});

package/dist/index.mjs

@@ -0,0 +1,278 @@
+// src/EventQueue.ts
+var EventQueue = class {
+  queue = [];
+  timer = null;
+  maxSize;
+  onFlush;
+  onError;
+  constructor({ maxSize = 50, flushInterval = 5e3, onFlush, onError }) {
+    this.maxSize = maxSize;
+    this.onFlush = onFlush;
+    this.onError = onError ?? ((err) => console.error("[UsageQueue]", err));
+    if (flushInterval > 0 && typeof setInterval !== "undefined") {
+      this.timer = setInterval(() => void this.flush(), flushInterval);
+    }
+    if (typeof window !== "undefined") {
+      window.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "hidden") void this.flush();
+      });
+    }
+  }
+  push(event) {
+    this.queue.push(event);
+    if (this.queue.length >= this.maxSize) {
+      void this.flush();
+    }
+  }
+  async flush() {
+    if (this.queue.length === 0) return;
+    const batch = this.queue.splice(0, this.queue.length);
+    try {
+      await this.onFlush(batch);
+    } catch (err) {
+      this.onError(err, batch);
+    }
+  }
+  destroy() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+};
+
+// src/UsageClient.ts
+var UsageError = class extends Error {
+  constructor(message, statusCode, body) {
+    super(message);
+    this.statusCode = statusCode;
+    this.body = body;
+    this.name = "UsageError";
+  }
+  statusCode;
+  body;
+};
+var UsageClient = class {
+  baseUrl;
+  apiToken;
+  timeout;
+  maxRetries;
+  retryDelay;
+  beforeSend;
+  queue = null;
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+    this.apiToken = opts.apiToken;
+    this.timeout = opts.timeout ?? 1e4;
+    this.maxRetries = opts.maxRetries ?? 3;
+    this.retryDelay = opts.retryDelay ?? 300;
+    this.beforeSend = opts.beforeSend;
+    if (opts.autoQueue) {
+      this.queue = new EventQueue({
+        maxSize: opts.queueMaxSize ?? 50,
+        flushInterval: opts.flushInterval ?? 5e3,
+        onFlush: (events) => this.batch(events).then(() => void 0),
+        onError: (err) => console.error("[UsageClient:queue]", err)
+      });
+    }
+  }
+  /**
+   * Enregistre un événement de façon synchrone (direct API call).
+   */
+  async record(event) {
+    const payload = this.applyBeforeSend(this.normalizeEvent(event));
+    if (!payload) return Promise.reject(new Error("beforeSend filtered event"));
+    return this.post("/v1/usage/events", payload);
+  }
+  /**
+   * Ajoute un événement dans le buffer (non-bloquant).
+   * Nécessite `autoQueue: true` à la construction.
+   */
+  track(event) {
+    if (!this.queue) {
+      throw new Error("autoQueue est d\xE9sactiv\xE9. Passez autoQueue:true ou utilisez record().");
+    }
+    const normalized = this.applyBeforeSend(this.normalizeEvent(event));
+    if (normalized) this.queue.push(normalized);
+  }
+  /**
+   * Vide le buffer immédiatement (utile avant navigations SPA).
+   */
+  async flush() {
+    var _a;
+    await ((_a = this.queue) == null ? void 0 : _a.flush());
+  }
+  /**
+   * Enregistre jusqu'à 100 événements en une seule requête.
+   */
+  async batch(events) {
+    if (events.length === 0) {
+      return { created: 0, duplicate: 0, keys: { created: [], duplicate: [] } };
+    }
+    if (events.length > 100) {
+      throw new RangeError("Le lot ne peut pas d\xE9passer 100 \xE9v\xE9nements.");
+    }
+    return this.post("/v1/usage/batch", {
+      events: events.map((e) => this.normalizeEvent(e))
+    });
+  }
+  async summary() {
+    return this.get("/v1/usage/summary");
+  }
+  async quota() {
+    return this.get("/v1/usage/quota");
+  }
+  /** Libère les ressources (timer de la queue). */
+  destroy() {
+    var _a;
+    (_a = this.queue) == null ? void 0 : _a.destroy();
+  }
+  // ── Helpers ────────────────────────────────────────────────────────────────
+  applyBeforeSend(event) {
+    return this.beforeSend ? this.beforeSend(event) : event;
+  }
+  normalizeEvent(event) {
+    return {
+      ...event,
+      idempotencyKey: event.idempotencyKey ?? this.generateKey(event.metric)
+    };
+  }
+  generateKey(metric) {
+    const rand = Math.random().toString(36).slice(2);
+    return `${metric}:${Date.now()}:${rand}`;
+  }
+  async post(path, body) {
+    return this.request("POST", path, body);
+  }
+  async get(path, params) {
+    const url = params ? `${path}?${new URLSearchParams(params)}` : path;
+    return this.request("GET", url);
+  }
+  async request(method, path, body) {
+    let lastError;
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+          const resp = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+              Authorization: `Bearer ${this.apiToken}`,
+              "Content-Type": "application/json",
+              Accept: "application/json"
+            },
+            body: body != null ? JSON.stringify(body) : void 0,
+            signal: controller.signal
+          });
+          const data = await resp.json().catch(() => ({}));
+          if (!resp.ok) {
+            const message = data["message"] ?? `HTTP ${resp.status}`;
+            const err = new UsageError(message, resp.status, data);
+            if (resp.status >= 400 && resp.status < 500) throw err;
+            lastError = err;
+          } else {
+            return data;
+          }
+        } finally {
+          clearTimeout(timer);
+        }
+      } catch (err) {
+        if (err instanceof UsageError && err.statusCode >= 400 && err.statusCode < 500) {
+          throw err;
+        }
+        lastError = err;
+      }
+      if (attempt < this.maxRetries - 1) {
+        await sleep(this.retryDelay * 2 ** attempt);
+      }
+    }
+    throw lastError;
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/BillingClient.ts
+var BillingError = class extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "BillingError";
+  }
+  status;
+  body;
+};
+var BillingClient = class {
+  baseUrl;
+  headers;
+  constructor(options) {
+    this.baseUrl = (options.baseUrl ?? "http://localhost:8000/api").replace(/\/$/, "");
+    this.headers = {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${options.apiKey}`
+    };
+  }
+  // ─── Plans ────────────────────────────────────────────────────────────────
+  plans = {
+    list: () => this.get("/v1/sdk/plans"),
+    get: (id) => this.get(`/v1/sdk/plans/${id}`)
+  };
+  // ─── Customers ────────────────────────────────────────────────────────────
+  customers = {
+    /**
+     * Crée ou met à jour un customer (idempotent sur external_id).
+     */
+    upsert: (input) => this.post("/v1/sdk/customers", input),
+    get: (externalId) => this.get(`/v1/sdk/customers/${encodeURIComponent(externalId)}`),
+    delete: (externalId) => this.delete(`/v1/sdk/customers/${encodeURIComponent(externalId)}`),
+    /**
+     * Subscription active du customer (null si aucune).
+     */
+    subscription: (externalId) => this.get(`/v1/sdk/customers/${encodeURIComponent(externalId)}/subscription`),
+    /**
+     * Crée une Stripe Checkout Session — redirigez l'utilisateur vers checkout_url.
+     */
+    checkout: (externalId, input) => this.post(`/v1/sdk/customers/${encodeURIComponent(externalId)}/checkout`, input),
+    /**
+     * URL vers le Stripe Billing Portal (gestion CB, annulation, etc.).
+     */
+    portal: (externalId, returnUrl) => this.post(`/v1/sdk/customers/${encodeURIComponent(externalId)}/portal`, { return_url: returnUrl }),
+    invoices: (externalId) => this.get(`/v1/sdk/customers/${encodeURIComponent(externalId)}/invoices`)
+  };
+  // ─── HTTP helpers ─────────────────────────────────────────────────────────
+  async get(path) {
+    return this.request("GET", path);
+  }
+  async post(path, body) {
+    return this.request("POST", path, body);
+  }
+  async delete(path) {
+    return this.request("DELETE", path);
+  }
+  async request(method, path, body) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: this.headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+      throw new BillingError(
+        (data == null ? void 0 : data.message) ?? `HTTP ${res.status}`,
+        res.status,
+        data
+      );
+    }
+    return data;
+  }
+};
+export {
+  BillingClient,
+  BillingError,
+  EventQueue,
+  UsageClient,
+  UsageError
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@billing-saas/usage-sdk",
+  "version": "0.1.0",
+  "description": "SDK TypeScript pour intégrer le PU Billing SaaS dans votre application Next.js — gestion des plans, checkout Stripe, abonnements et feature gates.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "billing",
+    "saas",
+    "subscription",
+    "stripe",
+    "payments",
+    "nextjs",
+    "sdk"
+  ],
+  "author": "Billing SaaS",
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}