Optimization

.gitignore

@@ -1,2 +1,11 @@
 node_modules
 dist
+.next
+
+*.lock
+package-lock.json
+bun.lockb
+
+**.DS_Store
+
+**.claude

README.md

@@ -1,93 +1,129 @@
 # @eggermarc/better-auth-usage
 
-**⚠️ Warning!** This package is a **work in progress**! Expect breaking changes and functionality changes.
+**Warning!** This package is a **work in progress**! Expect breaking changes and functionality changes.
 
 Feature and usage-based authorization plugin for [BetterAuth](https://www.better-auth.com/). Provides a way to define **features**, **track usage**, apply **per-plan limits**, and integrate with external systems (Stripe, custom hooks, etc).
 
 ## Roadmap
-Below are the action items to fix known limitations of this plugin. Namely, customer management and consumption indepotency.
+Below are the action items to fix known limitations of this plugin. Namely, customer management and consumption idempotency.
 - [x] Customer table
-- [ ] Customer to feature table (for customer limits)
-    - [ ] Feature 
-    - [ ] Follow slowly changing dimensions model
 - [x] Consumption adapter as transaction
-- [ ] Non blocking syncUsage
+- [x] Redis caching with Lua-based atomic increments
+- [x] Real-time WebSocket updates (optional)
+- [x] Integration test suite (DB-only + cached)
+- [x] Comprehensive E2E and unit test coverage (284 tests)
 - [ ] Customer provider (Optional - considering leaving this to dev)
     - [ ] `useCustomer(referenceId)`
+- [ ] Per-customer feature limits (`featureLimits`)
+- [ ] Consumption idempotency keys
 
 
 ## Features
 
 - Define features with maxLimit, minLimit, reset strategies, and metadata.
-- Apply customer-specific overrides (e.g. different limits per customer).
+- Apply plan-specific overrides (e.g. different limits per plan).
 - Hook into usage events (before and after).
 - Add custom authorization logic with authorizeReference.
+- Optional Redis caching with atomic Lua-based increments.
+- Optional real-time usage tracking via WebSocket (Socket.IO).
 
 ### Installation
 ```bash
 npm add @eggermarc/better-auth-usage
+# or
+bun add @eggermarc/better-auth-usage
+# or
+pnpm add @eggermarc/better-auth-usage
 ```
 
 ### Usage
 #### Server
 ```typescript
-// server
+import { betterAuth } from "better-auth";
+import { usage } from "@eggermarc/better-auth-usage";
+
 export const auth = betterAuth({
     plugins: [usage({
         features: {
             "token-feature": {
                 key: "token-feature",
                 maxLimit: 1000,
                 reset: "monthly",
+                resetValue: 0,
                 details: ["Number of tokens per month"],
             }
         },
         overrides: {
             "starter-plan": {
-                "token-feature":{ 
-                    maxLimit: 10_000,
-                    hooks: {
-                    after: async ({ usage, customer, feature }) => {
-                        console.log(
-                        `[AFTER HOOK] ${customer.referenceId} used ${usage.amount} of ${feature.key}`
-                        );
+                features: {
+                    "token-feature": {
+                        maxLimit: 10_000,
+                        stripeId: "price_xxx", // Can declare extra fields
+                        hooks: {
+                            after: async ({ usage, customer, feature }) => {
+                                console.log(
+                                    `[AFTER HOOK] ${customer.referenceId} used ${usage.amount} of ${feature.key}`
+                                );
+                            },
+                        },
                     },
-                    stripeId: env.TOKEN_STARTER_ID // Can declare new fields
                 },
             },
             "pro-plan": {
-                "token-features": {
-                    maxLimit: 1_000_000,
-                    hooks: {
-                        after: async ({ usage, customer, feature }) => {
-                            console.log(
-                            `[AFTER HOOK] ${customer.referenceId} used ${usage.amount} of ${feature.key}`
-                            );
-                        },
+                features: {
+                    "token-feature": {
+                        maxLimit: 1_000_000,
                     },
-                }
+                },
             },
-        }
+        },
+        // Optional: enable Redis caching
+        // cacheOptions: {
+        //     redisUrl: process.env.REDIS_URL!,
+        //     enableRealtime: true,  // optional WebSocket support
+        //     port: 3001,            // required if enableRealtime is true
+        // },
     })]
 })
 ```
+
 #### Client
 ```ts
-// client.ts
 import { createAuthClient } from "better-auth/client";
 import { usageClient } from "@eggermarc/better-auth-usage/client";
 
 export const client = createAuthClient({
   plugins: [usageClient()],
 });
+```
+
+### Customer Registration
 
-// Example: consume usage, in your app
+**Important:** A customer must be registered before consuming usage. The consume endpoint requires the customer to exist.
+
+```ts
+// Register a customer first
+await client.usage.upsertCustomer({
+  referenceId: "123",
+  referenceType: "user",
+  name: "John Doe",
+  email: "john@example.com",
+});
+
+// Then consume usage
 await client.usage.consume({
   featureKey: "token-feature",
   overrideKey: "starter-plan",
   referenceId: "123",
   amount: 1,
 });
+
+// Check current usage and limits
+const status = await client.usage.check({
+  featureKey: "token-feature",
+  referenceId: "123",
+});
+// => { status: "in-limit", currentAmount: 1, maxLimit: 1000, minLimit: undefined }
 ```
 
 ### Goals
@@ -98,17 +134,14 @@ Why customer registration and not per user / organization query?
 #### Examples
 ##### Team based
 ```ts
-const teamLimits = getTeamLimits(teamId, "token-feature") 
-
-const customer: Customer = {
-    referenceId: teamId, // Team ID,
+const customer = {
+    referenceId: teamId,
     referenceType: "team",
-    email: session.user.email, // User in team email
+    email: session.user.email,
     name: `${session.user.name}@${teamName}`,
-    // WIP featureLimits: new Record("token-feature", teamLimits)
 }
 
-await client.usage.registerCustomer(customer)
+await client.usage.upsertCustomer(customer)
 
 await client.usage.consume({
     featureKey: "token-feature",
@@ -119,19 +152,62 @@ await client.usage.consume({
 ```
 ##### Session based / IP based
 ```ts
-const customer: Customer = {
-    referenceId: session.session.ipAddress ?? session.session.id,
-    referenceType: "session",
-}
-
-await client.usage.registerCustomer(customer)
+const referenceId = session.session.ipAddress ?? session.session.id;
 
+await client.usage.upsertCustomer({
+    referenceId,
+    referenceType: "session",
+})
 
 await client.usage.consume({
     featureKey: "token-feature",
-    referenceId: session.session.ipAddress ?? session.session.id,
-    amount: 1
+    referenceId,
+    amount: 1,
 })
 ```
 
-In this current version, we apply to all customers the root limits, then overrides, and finally with customer specific overrides. 
+### API Endpoints
+
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/usage/features` | GET | none | List all registered features |
+| `/usage/features/{featureKey}` | GET | none | Get a single feature config (with optional override) |
+| `/usage/consume` | POST | session | Consume/increment usage for a feature |
+| `/usage/check` | POST | session | Check current usage vs limits (with optional preview amount) |
+| `/usage/check-customer` | POST | session | Get customer details by referenceId |
+| `/usage/upsert-customer` | POST | session | Create or update a customer |
+| `/usage/sync` | POST | none | Manually trigger reset if due |
+
+### Override Structure
+
+Overrides require a nested `features` key:
+
+```ts
+overrides: {
+    "plan-name": {
+        features: {                    // <-- required
+            "feature-key": {
+                maxLimit: 10_000,      // overrides the base feature's maxLimit
+                // any Feature field except `key` can be overridden
+            },
+        },
+    },
+}
+```
+
+The `overrideKey` is passed per-request to `consume`, `check`, or `sync` endpoints to apply the override for that specific call.
+
+### Reset Strategies
+
+Features can specify a `reset` interval to automatically zero out usage:
+
+| Reset | Boundary |
+|-------|----------|
+| `"hourly"` | Start of next hour |
+| `"6-hourly"` | Next 6-hour block (00:00, 06:00, 12:00, 18:00) |
+| `"daily"` | Tomorrow at 00:00 |
+| `"weekly"` | Next Monday at 00:00 |
+| `"monthly"` | 1st of next month at 00:00 |
+| `"quarterly"` | 1st of next quarter at 00:00 |
+| `"yearly"` | January 1st of next year at 00:00 |
+| `"never"` | Never resets |

TESTING.md

@@ -0,0 +1,60 @@
+# Testing Guide
+
+This document provides information about the test suite for the better-auth-usage plugin.
+
+## Overview
+
+The test suite uses **Bun's built-in test runner** and covers all major components including:
+
+- Utility functions (date handling, limit checking, error handling)
+- Cache adapter (Redis-based caching)
+- Database query adapters (get, insert, reset operations)
+- Real-time usage tracking (pub/sub)
+- WebSocket server functionality
+
+## Running Tests
+
+### Run All Tests
+```bash
+bun test
+```
+
+### Run Tests in Watch Mode
+```bash
+bun test --watch
+```
+
+### Run Tests with Coverage
+```bash
+bun test --coverage
+```
+
+### Run Specific Test File
+```bash
+bun test package/__tests__/utils.test.ts
+```
+
+## Test Coverage Summary
+
+- **8 test files** created covering all changed components
+- **200+ individual test cases** across the codebase
+- Tests for happy paths, edge cases, and error conditions
+
+## Available Test Commands
+
+- `bun test` - Run all tests once
+- `bun test --watch` - Run tests in watch mode (re-run on file changes)
+- `bun test --coverage` - Run tests with coverage report
+
+## Test Files Created
+
+1. **utils.test.ts** - Tests for utility functions (checkLimit, shouldReset, tryCatch)
+2. **adapters/cache.test.ts** - Tests for Redis cache adapter
+3. **adapters/index.test.ts** - Integration tests for main adapter
+4. **adapters/queries/get-usage.test.ts** - Tests for get usage query
+5. **adapters/queries/insert-usage.test.ts** - Tests for insert usage query
+6. **adapters/queries/reset-usage.test.ts** - Tests for reset usage query
+7. **realtime/usage-tracker.test.ts** - Tests for real-time usage tracker
+8. **realtime/websocket-server.test.ts** - Tests for WebSocket server
+
+All tests follow Bun's testing conventions and best practices.