@usageflow/core 0.2.4 → 0.2.6

package/README.md

@@ -2,7 +2,8 @@
 
 Core functionality for UsageFlow API tracking. This package provides the base implementation for tracking API usage across different Node.js frameworks.
 
-⚠️ **Beta Version Notice**: This package is currently in beta. Early adopters may encounter issues. We appreciate your feedback and contributions!
+[![npm version](https://img.shields.io/npm/v/@usageflow/core.svg)](https://www.npmjs.com/package/@usageflow/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Installation
 
@@ -10,46 +11,226 @@ Core functionality for UsageFlow API tracking. This package provides the base im
 npm install @usageflow/core
 ```
 
+## Overview
+
+`@usageflow/core` is the foundational package that provides core functionality for UsageFlow integrations. It includes:
+
+- Base `UsageFlowAPI` class for framework-agnostic usage tracking
+- WebSocket connection management with connection pooling
+- Route pattern matching and ledger ID generation
+- Request metadata collection and sanitization
+- Configuration management and policy fetching
+
 ## Usage
 
-This is the core package that provides base functionality for UsageFlow integrations. You typically won't use this package directly, but rather through framework-specific implementations:
+This package is typically used indirectly through framework-specific implementations:
 
-- [@usageflow/express](https://www.npmjs.com/package/@usageflow/express) for Express.js
-- [@usageflow/fastify](https://www.npmjs.com/package/@usageflow/fastify) for Fastify
-- [@usageflow/nestjs](https://www.npmjs.com/package/@usageflow/nestjs) for NestJS
+- [@usageflow/express](../express) for Express.js
+- [@usageflow/fastify](../fastify) for Fastify
+- [@usageflow/nestjs](../nestjs) for NestJS
+
+If you need to extend UsageFlow for a different framework, you can extend the `UsageFlowAPI` class:
+
+```typescript
+import { UsageFlowAPI, UsageFlowAPIConfig } from '@usageflow/core';
 
-If you need to extend UsageFlow for a different framework, you can use this core package as your starting point.
+class CustomFrameworkUsageFlowAPI extends UsageFlowAPI {
+  constructor(config: UsageFlowAPIConfig) {
+    super(config);
+    this.setWebServer('custom');
+  }
+
+  // Implement framework-specific methods
+}
+```
 
 ## API Reference
 
+### UsageFlowAPIConfig
+
+```typescript
+interface UsageFlowAPIConfig {
+  apiKey: string; // Your UsageFlow API key
+  poolSize?: number; // Number of WebSocket connections (default: 5)
+}
+```
+
+### UsageFlowAPI
+
+Base class for all UsageFlow implementations.
+
+#### Constructor
+
+```typescript
+constructor(config: UsageFlowAPIConfig)
+```
+
+#### Methods
+
+##### `setWebServer(webServer: 'express' | 'fastify' | 'nestjs'): void`
+
+Sets the web server type for route pattern extraction.
+
+##### `getApiKey(): string | null`
+
+Returns the configured API key.
+
+##### `getUsageflowUrl(): string`
+
+Returns the UsageFlow API URL.
+
+##### `getRoutePattern(request: UsageFlowRequest): string`
+
+Extracts the route pattern from a request object. Supports Express, Fastify, and NestJS.
+
+##### `guessLedgerId(request: UsageFlowRequest, overrideUrl?: string): string`
+
+Generates a ledger ID for tracking based on the request and configured policies.
+
+##### `createRoutesMap(routes: Route[]): RoutesMap`
+
+Converts an array of routes into a map for efficient lookup.
+
+##### `shouldSkipRoute(method: string, url: string, whitelistMap: RoutesMap): boolean`
+
+Checks if a route should be skipped based on the whitelist.
+
+##### `shouldMonitorRoute(method: string, url: string, routesMap: RoutesMap): boolean`
+
+Checks if a route should be monitored based on the routes map.
+
+##### `sanitizeHeaders(headers: Headers): Headers`
+
+Sanitizes sensitive information from headers (authorization tokens, API keys, etc.).
+
+##### `extractBearerToken(authHeader?: string): string | null`
+
+Extracts the bearer token from an Authorization header.
+
+##### `decodeJwtUnverified(token: string): Record<string, any> | null`
+
+Decodes a JWT token without verifying the signature.
+
+##### `allocationRequest(request: UsageFlowRequest, payload: RequestForAllocation, metadata: RequestMetadata): Promise<void>`
+
+Sends an allocation request via WebSocket.
+
+##### `useAllocationRequest(payload: RequestForAllocation): Promise<void>`
+
+Finalizes an allocation request.
+
+##### `destroy(): void`
+
+Cleans up resources including intervals and WebSocket connections.
+
+### UsageFlowSocketManager
+
+Manages WebSocket connections with connection pooling.
+
+#### Constructor
+
+```typescript
+constructor(apiKey: string, poolSize?: number)
+```
+
+#### Methods
+
+##### `connect(): Promise<void>`
+
+Establishes WebSocket connections in the pool.
+
+##### `sendAsync<T>(payload: UsageFlowSocketMessage): Promise<UsageFlowSocketResponse<T>>`
+
+Sends a message and waits for a response.
+
+##### `send(payload: UsageFlowSocketMessage): void`
+
+Sends a message without waiting for a response.
+
+##### `isConnected(): boolean`
+
+Checks if at least one WebSocket connection is active.
+
+##### `close(): void`
+
+Closes all WebSocket connections.
+
+##### `destroy(): void`
+
+Cleans up all resources.
+
+## Types
+
+### Route
+
+```typescript
+interface Route {
+  method: string; // HTTP method or '*' for all methods
+  url: string; // URL pattern or '*' for all URLs
+}
+```
+
+### RequestMetadata
+
+```typescript
+interface RequestMetadata {
+  method: string;
+  url: string;
+  rawUrl: string;
+  clientIP: string;
+  userAgent?: string;
+  timestamp: string;
+  headers: Record<string, string>;
+  queryParams: Record<string, any> | null;
+  pathParams: Record<string, any> | null;
+  body?: any;
+  requestDuration?: number;
+}
+```
+
+### UsageFlowConfig
+
 ```typescript
-class UsageFlowAPI {
-  init(apiKey: string, usageflowUrl?: string): void;
-  createRoutesMap(routes: Route[]): Map<string, Set<string>>;
-  shouldMonitorRoute(
-    method: string,
-    url: string,
-    routesMap: Map<string, Set<string>>,
-  ): boolean;
-  shouldSkipRoute(
-    method: string,
-    url: string,
-    whitelistMap: Map<string, Set<string>>,
-  ): boolean;
-  sanitizeHeaders(headers: Record<string, string>): Record<string, string>;
+interface UsageFlowConfig {
+  url: string;
+  method: string;
+  identityFieldName?: string;
+  identityFieldLocation?:
+    | 'path_params'
+    | 'query_params'
+    | 'body'
+    | 'bearer_token'
+    | 'headers';
 }
 ```
 
-## Beta Status
+## Requirements
 
-This is a beta release meant for early adopters. You may encounter:
+- Node.js >= 18.0.0
+- TypeScript >= 5.0.0 (for TypeScript projects)
 
-- API changes in future versions
-- Incomplete features
-- Potential bugs
+## Dependencies
 
-We're actively working on improvements and appreciate your feedback!
+- `axios`: HTTP client for API requests
+- `ws`: WebSocket client library
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Run tests
+npm test
+```
 
 ## License
 
 MIT
+
+## Support
+
+For issues, questions, or contributions, please visit our [GitHub repository](https://github.com/usageflow/js-mongorepo).

package/dist/base.d.ts

@@ -1,29 +1,30 @@
-import { Route, UsageFlowConfig, RoutesMap, Headers, RequestForAllocation, RequestMetadata, UsageFlowRequest } from "./types";
-import { UsageFlowSocketManger } from "./socket";
+import { Route, UsageFlowConfig, RoutesMap, Headers, RequestForAllocation, RequestMetadata, UsageFlowRequest, UsageFlowAPIConfig } from "./types";
 export declare abstract class UsageFlowAPI {
     protected apiKey: string | null;
     protected usageflowUrl: string;
-    protected webServer: 'express' | 'fastify' | 'nestjs';
+    protected webServer: "express" | "fastify" | "nestjs";
     protected apiConfigs: UsageFlowConfig[];
     private configUpdateInterval;
-    socketManager: UsageFlowSocketManger | null;
+    private socketManager;
     private applicationId;
+    private logger;
+    constructor(config?: UsageFlowAPIConfig);
     /**
      * Initialize the UsageFlow API with credentials
      * @param apiKey - Your UsageFlow API key
      * @param usageflowUrl - The UsageFlow API URL (default: https://api.usageflow.io)
      * @param poolSize - Number of WebSocket connections in the pool (default: 5)
      */
-    init(apiKey: string, usageflowUrl?: string, poolSize?: number): UsageFlowAPI;
-    setWebServer(webServer: 'express' | 'fastify' | 'nestjs'): void;
+    private init;
+    setWebServer(webServer: "express" | "fastify" | "nestjs"): void;
     getApiKey(): string | null;
     getUsageflowUrl(): string;
     /**
      * Start background config update process
      */
     private startConfigUpdater;
-    protected getRoutePattern(request: UsageFlowRequest): string;
-    guessLedgerId(request: UsageFlowRequest): string;
+    getRoutePattern(request: UsageFlowRequest): string;
+    guessLedgerId(request: UsageFlowRequest, overrideUrl?: string): string;
     private fetchApiPolicies;
     useAllocationRequest(payload: RequestForAllocation): Promise<void>;
     allocationRequest(request: UsageFlowRequest, payload: RequestForAllocation, metadata: RequestMetadata): Promise<void>;

package/dist/base.js

@@ -2,15 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UsageFlowAPI = void 0;
 const socket_1 = require("./socket");
+const logger_1 = require("@usageflow/logger");
 class UsageFlowAPI {
-    constructor() {
+    constructor(config = { apiKey: "", poolSize: 5 }) {
         this.apiKey = null;
         this.usageflowUrl = "https://api.usageflow.io";
-        this.webServer = 'express';
+        this.webServer = "express";
         this.apiConfigs = [];
         this.configUpdateInterval = null;
         this.socketManager = null;
         this.applicationId = false;
+        // Initialize logger with service name
+        this.logger = (0, logger_1.usLogger)({ service: 'USAGEFLOW_BASE', pretty: true, silent: process.env.UF_LOGS_ENABLED !== 'true' });
+        // Set default context for all logs
+        this.logger.setContext({
+            component: 'UsageFlowAPI',
+            webServer: this.webServer,
+        });
+        this.init(config.apiKey, this.usageflowUrl, config.poolSize);
     }
     /**
      * Initialize the UsageFlow API with credentials
@@ -24,15 +33,27 @@ class UsageFlowAPI {
         // this.startConfigUpdater();
         this.socketManager = new socket_1.UsageFlowSocketManger(apiKey, poolSize);
         // Connect the socket manager
-        this.socketManager.connect().catch((error) => {
-            console.error("[UsageFlow] Failed to establish WebSocket connection:", error);
-        }).then(() => {
-            this.startConfigUpdater();
+        this.socketManager
+            .connect()
+            .catch((error) => {
+            this.logger.error("[UsageFlow] Failed to establish WebSocket connection:", error);
+        })
+            .then(() => {
+            var _a;
+            this.logger.info("WebSocket connection established");
+            if ((_a = this.socketManager) === null || _a === void 0 ? void 0 : _a.isConnected()) {
+                this.startConfigUpdater();
+            }
+            else {
+                this.logger.error("WebSocket connection failed");
+            }
         });
         return this;
     }
     setWebServer(webServer) {
         this.webServer = webServer;
+        // Update logger context with new web server
+        this.logger.setContext({ webServer });
     }
     getApiKey() {
         return this.apiKey;
@@ -44,39 +65,74 @@ class UsageFlowAPI {
      * Start background config update process
      */
     startConfigUpdater() {
+        this.logger.info("Starting background config update process");
         if (this.configUpdateInterval) {
             clearInterval(this.configUpdateInterval);
         }
-        this.fetchApiPolicies().catch(console.error);
+        this.fetchApiPolicies().catch(this.logger.error);
         this.configUpdateInterval = setInterval(async () => {
             await this.fetchApiPolicies();
         }, 60000);
         // this.fetchApiConfig().catch(console.error);
     }
     getRoutePattern(request) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
-        if (this.webServer === 'fastify') {
-            return ((_a = request === null || request === void 0 ? void 0 : request.routeOptions) === null || _a === void 0 ? void 0 : _a.url) || request.url || '';
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+        if (this.webServer === "fastify") {
+            return ((_a = request === null || request === void 0 ? void 0 : request.routeOptions) === null || _a === void 0 ? void 0 : _a.url) || request.url || "";
         }
-        const routePattern = ((_b = request.route) === null || _b === void 0 ? void 0 : _b.path) || ((_d = (_c = request.app._router.stack.find((route) => {
-            // a => a.path == request.url
-            if (!route.route)
-                return false;
-            if (route.path) {
-                return route.path == request.url;
+        // For NestJS, prioritize route.path with baseUrl
+        if (this.webServer === "nestjs") {
+            // Method 1: Use request.route.path (available after route matching in NestJS)
+            if ((_b = request.route) === null || _b === void 0 ? void 0 : _b.path) {
+                const baseUrl = request.baseUrl || "";
+                const routePath = request.route.path;
+                // Combine baseUrl and routePath to get full pattern
+                const fullPath = baseUrl + routePath;
+                return fullPath || "/";
             }
-            if (route.regexp) {
-                const patterned = route.regexp.test(request.url);
-                if (patterned) {
-                    return patterned;
+            // Method 2: Reconstruct pattern from params (NestJS-specific)
+            // This is more reliable for NestJS when route.path is not available
+            if (request.params && Object.keys(request.params).length > 0) {
+                let path = request.path || ((_c = request.url) === null || _c === void 0 ? void 0 : _c.split("?")[0]) || "/";
+                // Split path into segments and replace matching segments with param names
+                const pathSegments = path
+                    .split("/")
+                    .filter((segment) => segment !== "");
+                const paramEntries = Object.entries(request.params);
+                // Replace segments that match param values with :paramName
+                for (let i = 0; i < pathSegments.length; i++) {
+                    for (const [paramName, paramValue] of paramEntries) {
+                        if (pathSegments[i] === String(paramValue)) {
+                            pathSegments[i] = `:${paramName}`;
+                            break; // Only replace once per segment
+                        }
+                    }
                 }
+                // Reconstruct the full path pattern
+                const pattern = "/" + pathSegments.join("/");
+                return pattern;
             }
-        })) === null || _c === void 0 ? void 0 : _c.route) === null || _d === void 0 ? void 0 : _d.path);
+        }
+        const routePattern = ((_d = request.route) === null || _d === void 0 ? void 0 : _d.path) ||
+            ((_f = (_e = request.app._router.stack.find((route) => {
+                // a => a.path == request.url
+                if (!route.route)
+                    return false;
+                if (route.path) {
+                    return route.path == request.url;
+                }
+                if (route.regexp) {
+                    const patterned = route.regexp.test(request.url);
+                    if (patterned) {
+                        return patterned;
+                    }
+                }
+            })) === null || _e === void 0 ? void 0 : _e.route) === null || _f === void 0 ? void 0 : _f.path);
         if (routePattern) {
             return routePattern;
         }
         // Method 1: Use request.route.path (available after route matching)
-        if ((_e = request.route) === null || _e === void 0 ? void 0 : _e.path) {
+        if ((_g = request.route) === null || _g === void 0 ? void 0 : _g.path) {
             const baseUrl = request.baseUrl || "";
             const routePath = request.route.path;
             // Combine baseUrl and routePath to get full pattern
@@ -89,13 +145,13 @@ class UsageFlowAPI {
             const router = app._router;
             if (router && router.stack) {
                 const method = request.method.toLowerCase();
-                const path = request.path || ((_f = request.url) === null || _f === void 0 ? void 0 : _f.split("?")[0]) || "";
+                const path = request.path || ((_h = request.url) === null || _h === void 0 ? void 0 : _h.split("?")[0]) || "";
                 // Search through router stack for matching route
                 for (const layer of router.stack) {
                     if (layer.route) {
                         const route = layer.route;
                         const routePath = route.path;
-                        const routeMethods = Object.keys(route.methods).map(m => m.toLowerCase());
+                        const routeMethods = Object.keys(route.methods).map((m) => m.toLowerCase());
                         // Check if method matches and path pattern matches
                         if (routeMethods.includes(method) || routeMethods.includes("*")) {
                             // Try to match the pattern by checking if params match
@@ -104,7 +160,7 @@ class UsageFlowAPI {
                             if (request.params && Object.keys(request.params).length > 0) {
                                 // Check if route path contains the param names
                                 const paramNames = Object.keys(request.params);
-                                const routeHasParams = paramNames.some(param => routePath.includes(`:${param}`));
+                                const routeHasParams = paramNames.some((param) => routePath.includes(`:${param}`));
                                 if (routeHasParams) {
                                     return pattern;
                                 }
@@ -117,7 +173,9 @@ class UsageFlowAPI {
                             }
                         }
                     }
-                    else if (layer.name === "router" && layer.handle && layer.handle.stack) {
+                    else if (layer.name === "router" &&
+                        layer.handle &&
+                        layer.handle.stack) {
                         // Handle router middleware (nested routers)
                         const mountPath = layer.regexp.source
                             .replace("\\/?", "")
@@ -130,19 +188,21 @@ class UsageFlowAPI {
                             if (subLayer.route) {
                                 const route = subLayer.route;
                                 const routePath = route.path;
-                                const routeMethods = Object.keys(route.methods).map(m => m.toLowerCase());
-                                if (routeMethods.includes(method) || routeMethods.includes("*")) {
+                                const routeMethods = Object.keys(route.methods).map((m) => m.toLowerCase());
+                                if (routeMethods.includes(method) ||
+                                    routeMethods.includes("*")) {
                                     const fullPath = mountPath + routePath;
                                     // Check if this route matches by examining params
-                                    if (request.params && Object.keys(request.params).length > 0) {
+                                    if (request.params &&
+                                        Object.keys(request.params).length > 0) {
                                         const paramNames = Object.keys(request.params);
-                                        const routeHasParams = paramNames.some(param => routePath.includes(`:${param}`));
+                                        const routeHasParams = paramNames.some((param) => routePath.includes(`:${param}`));
                                         if (routeHasParams) {
                                             return fullPath;
                                         }
                                     }
                                     else if (!routePath.includes(":")) {
-                                        const currentPath = request.path || ((_g = request.url) === null || _g === void 0 ? void 0 : _g.split("?")[0]) || "";
+                                        const currentPath = request.path || ((_j = request.url) === null || _j === void 0 ? void 0 : _j.split("?")[0]) || "";
                                         if (currentPath === fullPath || currentPath === routePath) {
                                             return fullPath;
                                         }
@@ -160,7 +220,7 @@ class UsageFlowAPI {
         }
         // Method 3: Reconstruct pattern from params and path
         if (request.params && Object.keys(request.params).length > 0) {
-            let path = request.path || ((_h = request.url) === null || _h === void 0 ? void 0 : _h.split("?")[0]) || "/";
+            let path = request.path || ((_k = request.url) === null || _k === void 0 ? void 0 : _k.split("?")[0]) || "/";
             const baseUrl = request.baseUrl || "";
             // Split path into segments and replace matching segments with param names
             const pathSegments = path.split("/");
@@ -179,13 +239,13 @@ class UsageFlowAPI {
         }
         // Fallback: return baseUrl + path or just path
         const baseUrl = request.baseUrl || "";
-        const path = request.path || ((_j = request.url) === null || _j === void 0 ? void 0 : _j.split("?")[0]) || "/";
+        const path = request.path || ((_l = request.url) === null || _l === void 0 ? void 0 : _l.split("?")[0]) || "/";
         return baseUrl + path || "/";
     }
-    guessLedgerId(request) {
+    guessLedgerId(request, overrideUrl) {
         var _a, _b, _c;
         const method = request.method;
-        const url = this.getRoutePattern(request);
+        const url = overrideUrl || this.getRoutePattern(request);
         const configs = this.apiConfigs;
         if (!configs.length) {
             return `${method} ${url}`;
@@ -210,7 +270,7 @@ class UsageFlowAPI {
                     }
                     break;
                 case "bearer_token":
-                    const authHeader = this.getHeaderValue(request.headers, 'authorization');
+                    const authHeader = this.getHeaderValue(request.headers, "authorization");
                     const token = this.extractBearerToken(authHeader || undefined);
                     if (token) {
                         const claims = this.decodeJwtUnverified(token);
@@ -237,17 +297,19 @@ class UsageFlowAPI {
                 type: "get_application_policies",
                 payload: null,
             });
-            if (response.type === 'success') {
+            if (response.type === "success") {
                 this.apiConfigs = ((_a = response.payload) === null || _a === void 0 ? void 0 : _a.policies) || [];
             }
         }
     }
     async useAllocationRequest(payload) {
         if (this.socketManager && this.socketManager.isConnected()) {
-            this.socketManager.sendAsync({
+            this.socketManager
+                .sendAsync({
                 type: "use_allocation",
-                payload
-            }).catch((error) => {
+                payload,
+            })
+                .catch((error) => {
                 console.error("[UsageFlow] Error sending finalization via WebSocket:", error);
                 throw error;
             });
@@ -258,12 +320,12 @@ class UsageFlowAPI {
             try {
                 const allocationResponse = await this.socketManager.sendAsync({
                     type: "request_for_allocation",
-                    payload
+                    payload,
                 });
-                if (allocationResponse.type === 'error') {
+                if (allocationResponse.type === "error") {
                     throw new Error(allocationResponse.message || allocationResponse.error);
                 }
-                if (allocationResponse.type === 'success') {
+                if (allocationResponse.type === "success") {
                     request.usageflow.eventId = allocationResponse.payload.allocationId;
                     request.usageflow.metadata = metadata;
                     return;
@@ -358,8 +420,8 @@ class UsageFlowAPI {
             return null;
         }
         // Check if it's a bearer token
-        const parts = authHeader.split(' ');
-        if (parts.length !== 2 || parts[0].toLowerCase() !== 'bearer') {
+        const parts = authHeader.split(" ");
+        if (parts.length !== 2 || parts[0].toLowerCase() !== "bearer") {
             return null;
         }
         return parts[1];
@@ -369,12 +431,12 @@ class UsageFlowAPI {
      */
     getHeaderValue(headers, key) {
         // Check if it's a Headers object (from Fetch API) by checking for the 'get' method
-        if (headers && typeof headers.get === 'function') {
+        if (headers && typeof headers.get === "function") {
             return headers.get(key) || null;
         }
         // Otherwise, treat it as a Record
         const value = headers[key];
-        if (typeof value === 'string') {
+        if (typeof value === "string") {
             return value;
         }
         if (Array.isArray(value) && value.length > 0) {
@@ -390,13 +452,13 @@ class UsageFlowAPI {
     decodeJwtUnverified(token) {
         try {
             // Split the token into parts
-            const parts = token.split('.');
+            const parts = token.split(".");
             if (parts.length !== 3) {
                 return null;
             }
             // Decode the payload (claims)
             const payload = parts[1];
-            const decoded = Buffer.from(payload, 'base64').toString('utf-8');
+            const decoded = Buffer.from(payload, "base64").toString("utf-8");
             return JSON.parse(decoded);
         }
         catch (error) {