EnglishPolski
Brak wyników.

Pay-per-use Metering

Śledź custom features (API calls, storage, minutes) i automatycznie naliczaj overage.

Pay-per-use Metering

Apki które billują za użycie — API calls, storage GB, processed jobs, minuty, AI tokeny — rejestrują eventy w API meteringu WolfieAuth. Platforma agreguje per (orgId, clientId, featureKey, miesiąc) a miesięczny billing job stack-uje overage do subskrypcji Stripe klienta.

To DODATEK do per-seat / flat-rate pricingu z Plany & Billing — możesz mieszać. Plan “Pro” może mieć JEDNOCZEŚNIE bazowe $99/mies, 50 included seatów ORAZ 100k included API calls z $0.20/1k overage.

Architektura

┌────────────────┐  POST /api/mgmt/v1/usage/record    ┌──────────────────┐
│   Twoja apka   │ ──────────────────────────────▶    │  WolfieAuth      │
│  (każdy event) │  X-Wolfie-App-Key: wmk_...          │  UsageCounter    │
│                │  { featureKey, quantity }           │  upsert (mc)     │
└────────────────┘ ◀────────────────────────────────── └──────────────────┘
                    { used, included, overage }                  │
                                                                 │
                                                       koniec miesiąca
                                                                 │
                                                                 ▼
                                                    ┌─────────────────────┐
                                                    │  Aggregator job:    │
                                                    │  overage = max(0,   │
                                                    │    used - included) │
                                                    │  cents = overage ×  │
                                                    │    cents_per_unit   │
                                                    │  Stack jako Stripe  │
                                                    │  invoice item       │
                                                    └─────────────────────┘

Zdefiniuj limity na planie

Limity planu żyją w MembershipPlan.limits JSON — free-form, sam wybierasz klucze. Przykład CRM z meteringiem API + storage:

{
  "max_apps": 5,
  "included_seats": 10,
  "api_calls": {
    "included": 100000,
    "overage_cents_per_unit": 1
  },
  "storage_bytes": {
    "included": 5368709120,
    "overage_cents_per_unit_per_gb": 50
  },
  "ai_tokens": {
    "included": 1000000,
    "overage_cents_per_unit": 0.001
  }
}

Klucze są Twoje. Wybierz konwencję czytelną w panelu admin i pasującą do tego co raportuje Twój kod.

Zmintuj API key

W /admin/organizations/<id>#integrations → API Keys → + Add key:

Name:        myapp-prod-billing
Permissions: (puste = pełen dostęp — fine dla meteringu)

Token pokazany raz: wmk_<64 hex>. Zapisz w env Twojej apki:

WOLFIEAUTH_APP_KEY=wmk_...

Rejestruj eventy z apki

TypeScript / JavaScript

import { recordUsage } from "@wolfieauth/sdk-core/usage";

await recordUsage({
  issuer:     process.env.WOLFIEAUTH_ISSUER!,
  appKey:     process.env.WOLFIEAUTH_APP_KEY!,
  clientId:   "acme-myapi",        // opcjonalny gdy Twoja org ma jedną apkę
  featureKey: "api_calls",
  quantity:   1,
});
// → { ok: true, used: 12347, included: 100000, overage: 0 }

Express middleware billujący 1 unit per request:

import { recordUsage } from "@wolfieauth/sdk-core/usage";

app.use(async (req, _res, next) => {
  // Fire-and-forget — nie blokuj requesta na metering call.
  recordUsage({
    issuer:     process.env.WOLFIEAUTH_ISSUER!,
    appKey:     process.env.WOLFIEAUTH_APP_KEY!,
    featureKey: "api_calls",
  }).catch(() => { /* drop cicho */ });
  next();
});

Direct HTTP (dowolny język)

curl -X POST https://auth.wolfieguard.com/api/mgmt/v1/usage/record \
  -H "X-Wolfie-App-Key: wmk_..." \
  -H "Content-Type: application/json" \
  -d '{"clientId":"acme-myapi","featureKey":"api_calls","quantity":1}'

Response:

{
  "ok":         true,
  "featureKey": "api_calls",
  "clientId":   "acme-myapi",
  "year":       2026,
  "month":      5,
  "used":       12347,
  "included":   100000,
  "overage":    0
}

Quantity > 1

Dla batch operations (np. upload 5MB liczony jako 5_242_880 storage_bytes):

await recordUsage({
  issuer, appKey,
  featureKey: "storage_bytes",
  quantity:   fileSize,
});

Czytaj bieżące usage

import { listUsage } from "@wolfieauth/sdk-core/usage";

const u = await listUsage({ issuer, appKey });
// → { year: 2026, month: 5, rows: [
//      { featureKey: "api_calls", used: 12347, included: 100000, overage: 0, ... },
//      { featureKey: "storage_bytes", used: 4_111_222_333, included: 5_368_709_120, overage: 0, ... },
//   ] }

Soft limits + overage billing

recordUsage zwraca 200 nawet gdy usage przekracza included quota — counter dalej tyka a overage niesie running excess. Job billingu na koniec miesiąca mnoży overage × overage_cents_per_unit i stack-uje to do subskrypcji Stripe klienta jako invoice item.

To intencjonalne: kontrakt to “metering + billing”, NIE “rate limiter + metering”. Jeśli Twoja apka chce hard cutoffs, gateuj na polu overage zwróconym przez recordUsage:

const r = await recordUsage({ issuer, appKey, featureKey: "api_calls" });
if (r.ok && r.included && r.used > r.included * 1.5) {
  return res.status(429).json({ error: "soft_quota_exceeded" });
}

Auto-charge przez Stripe

Klienci z aktywną subskrypcją Stripe dostają overage charge’owany automatycznie — miesięczny aggregator tworzy Stripe invoice item przeciwko ich subskrypcji, Stripe charge-uje kartę na następnym odnowieniu. Pieniądze płyną na connected account klienta; WolfieAuth bierze swoje 5% platform fee, fakturowane przez KSeF miesięcznie przez wolfiecrm.

Dla klientów BEZ Stripe subskrypcji (np. legacy bank-transfer), aggregator falls back na wolfiecrm Billing API i wystawia fakturę KSeF z overage line items. Księgowość klienta obsługuje to jak każdą inną fakturę.

Patterns

Metering per-user

Wstaw sub user-a do featureKey: featureKey: "api_calls__userX". Note: to może rozdmuchać liczbę counter rows przy wielu userach — działa dla tysięcy, nie milionów. Dla high-cardinality user-level tracking, agreguj w swoim DB i raportuj top-line numbers do WolfieAuth.

Batchowanie burst-tolerant

Buforuj eventy client-side ~1s i submit-uj batched. Oszczędza request overhead kosztem małego okna accuracy:

let pending = 0;
let timer: NodeJS.Timeout | null = null;

function meterApiCall() {
  pending++;
  if (timer) return;
  timer = setTimeout(() => {
    const q = pending;
    pending = 0;
    timer = null;
    recordUsage({ issuer, appKey, featureKey: "api_calls", quantity: q }).catch(() => {});
  }, 1000);
}

Czytaj dalej

Ostatnia aktualizacja: