@usageflow/core 0.2.5 → 0.3.0

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,13 +1,14 @@
 import { Route, UsageFlowConfig, RoutesMap, Headers, RequestForAllocation, RequestMetadata, UsageFlowRequest, UsageFlowAPIConfig } from "./types";
-import { UsageFlowSocketManger } from "./socket";
 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[];
+    protected blockedEndpoints: string[];
     private configUpdateInterval;
-    socketManager: UsageFlowSocketManger | null;
+    private socketManager;
     private applicationId;
+    private logger;
     constructor(config?: UsageFlowAPIConfig);
     /**
      * Initialize the UsageFlow API with credentials
@@ -16,7 +17,7 @@ export declare abstract class UsageFlowAPI {
      * @param poolSize - Number of WebSocket connections in the pool (default: 5)
      */
     private init;
-    setWebServer(webServer: 'express' | 'fastify' | 'nestjs'): void;
+    setWebServer(webServer: "express" | "fastify" | "nestjs"): void;
     getApiKey(): string | null;
     getUsageflowUrl(): string;
     /**
@@ -24,10 +25,14 @@ export declare abstract class UsageFlowAPI {
      */
     private startConfigUpdater;
     getRoutePattern(request: UsageFlowRequest): string;
-    guessLedgerId(request: UsageFlowRequest, overrideUrl?: string): string;
+    guessLedgerId(request: UsageFlowRequest, overrideUrl?: string): {
+        ledgerId: string;
+        hasLimit: boolean;
+    };
     private fetchApiPolicies;
+    private fetchBlockedEndpoints;
     useAllocationRequest(payload: RequestForAllocation): Promise<void>;
-    allocationRequest(request: UsageFlowRequest, payload: RequestForAllocation, metadata: RequestMetadata): Promise<void>;
+    allocationRequest(request: UsageFlowRequest, payload: RequestForAllocation, metadata: RequestMetadata, hasLimit: boolean): Promise<void>;
     /**
      * Convert routes list to a map for faster lookup
      */