@vocoweb/meter

Production-ready usage tracking and limits for B2B SaaS.

Overview

@vocoweb/meter is the "Meter" module that makes usage-based pricing simple. Track usage, enforce limits, and display beautiful progress bars—all with a single function call.

Key Features:

• 📊 Usage Tracking - Track any metric (API calls, PDFs, storage, etc.)
• 🎯 Limit Enforcement - Automatic 402 errors when limits exceeded
• 🔄 Auto Reset - Monthly/daily/weekly reset periods
• 📈 Usage UI - Pre-built progress bar component
• ⚡ High Performance - Built on Supabase with row-level security

Installation

npm install @vocoweb/meter

Quick Start

Server-Side

import { meter } from '@vocoweb/meter';

// Increment usage
export async function POST(request: Request) {
  const user = await auth.requireUser(request);
  
  // Check limit before generating
  await meter.checkLimit(user.id, 'pdf_generated');
  
  // Generate PDF
  const pdf = await generatePDF(data);
  
  // Increment counter
  await meter.increment(user.id, 'pdf_generated', 1);
  
  return Response.json({ pdf });
}

// Get current usage
export async function GET(request: Request) {
  const user = await auth.requireUser(request);
  const usage = await meter.getUsage(user.id, 'pdf_generated');
  
  return Response.json({
    used: usage.current,
    limit: usage.limit,
    percentage: (usage.current / usage.limit) * 100,
  });
}

Client-Side (React)

import { VocoUsageBar } from '@vocoweb/meter/react';

export default function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1>
      
      <VocoUsageBar 
        metric="pdf_generated" 
        label="PDFs Generated This Month"
      />
      
      <VocoUsageBar 
        metric="api_calls" 
        label="API Calls"
        color="blue"
      />
    </div>
  );
}

API Reference

Server Methods

• increment(userId, metric, amount) - Increment usage counter
• checkLimit(userId, metric) - Check if within limit (throws 402 if exceeded)
• getUsage(userId, metric) - Get current usage statistics
• resetUsage(userId, metric) - Reset usage counter
• setLimit(userId, metric, limit) - Update user's limit

React Components

• <VocoUsageBar metric="name" label="Label" /> - Usage progress bar

Configuration Example

// vocoweb.config.ts
export const config = {
  limits: {
    pdf_generated: { 
      free: 10, 
      pro: 100, 
      enterprise: 1000 
    },
    api_calls: { 
      free: 1000, 
      pro: 10000, 
      enterprise: 100000 
    },
  },
  resetPeriod: 'monthly', // 'daily', 'weekly', 'monthly'
};

Environment Variables

# Supabase (Required)
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

Database Schema

CREATE TABLE usage_metrics (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
  metric TEXT NOT NULL,
  current_usage INTEGER DEFAULT 0,
  limit_value INTEGER NOT NULL,
  reset_at TIMESTAMPTZ NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(user_id, metric)
);

License

MIT © VocoWeb

Support

• Email: [email protected]
• Documentation: GitHub Wiki

Built with care by VocoWeb