@cocreate/usage 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+# [1.4.0](https://github.com/CoCreate-app/CoCreate-usage/compare/v1.3.0...v1.4.0) (2026-07-18)
+
+
+### Features
+
+* enhance event listener handling and improve logging for organization deletion ([cca2e40](https://github.com/CoCreate-app/CoCreate-usage/commit/cca2e408ba2c6599aab2b56430b1d74b923fbb57))
+* refactor usage tracking with new bandwidth management and event listeners ([76f8ddb](https://github.com/CoCreate-app/CoCreate-usage/commit/76f8ddb539ad6a3384ed5d1557b1e36b9d64222a))
+
 # [1.3.0](https://github.com/CoCreate-app/CoCreate-usage/compare/v1.2.2...v1.3.0) (2026-07-17)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocreate/usage",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "CoCreate-usage",
   "keywords": [
     "cocreate-usage",

package/src/index.js

@@ -13,232 +13,276 @@
  *
  * You should have received a copy of the GNU Affero General Public License
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
  ********************************************************************************/
 
-// Commercial Licensing Information:
-// For commercial use of this software without the copyleft provisions of the AGPLv3,
-// you must obtain a commercial license from CoCreate LLC.
-// For details, visit <https://cocreate.app/licenses/> or contact us at sales@cocreate.app.
-
-import server from '@cocreate/server';
-
-// ==========================================
-// Module-Level Sandbox State (ESM Singleton Container)
-// ==========================================
-const organizations = new Map();
-
-/**
- * Normalizes input data types and calculates payload sizing in bytes.
- */
-function getBytes(data) {
-    if (typeof data === 'number')
-        return data;
-    else if (data instanceof Buffer)
-        return data.byteLength || 0;
-    else if (data instanceof String || typeof data === 'string')
-        return Buffer.byteLength(data, 'utf8') || 0;
-    else if (typeof data === 'object' && data !== null)
-        return Buffer.byteLength(JSON.stringify(data), 'utf8') || 0;
-    else return 0;
-}
+import crud from '@cocreate/crud-server';
 
-/**
- * Determines pricing tier rates based on aggregate historical usage indicators.
- */
-function getRate(totalUsage = 0) {
-    const tiers = [
-        { limit: 1, rate: 10 },
-        { limit: 10, rate: 5 },
-        { limit: 100, rate: 2.5 },
-        { limit: 1000, rate: 1.125 },
-        { limit: 10000, rate: 0.562 },
-        { limit: 100000, rate: 0.281 },
-        { limit: 1000000, rate: 0.145 }
-    ];
-
-    const matchingTier = tiers.find(tier => totalUsage < tier.limit);
-    return matchingTier ? matchingTier.rate : 0.12;
-}
+class CoCreateUsage {
+    constructor(platformOrgId) {
+        this.platformOrgId = platformOrgId; // Master platform organization ID
 
-/**
- * Calculates and writes final bandwidth depletion transactions to the platform database.
- */
-async function sendUsageUpdate(org, organization_id, host) {
-    if (!server || !server.crud) return;
-    delete org.debounce;
-
-    org.dataTransferedOut += 250;
-    org.dataTransferedOutCount++;
-
-    const platformOrganization = server.organization_id;
-    let organization = await server.crud.send({
-        method: 'object.read',
-        // host: server.host,
-        array: 'organizations',
-        object: { _id: organization_id },
-        organization_id: platformOrganization
-    });
-
-    org.dataTransferedIn += getBytes(platformOrganization);
-    org.dataTransferedInCount++;
-
-    if (organization && organization.object && organization.object[0]) {
-        organization = organization.object[0];
-    } else return;
-
-    if (server.wsManager && server.wsManager.organizations.has(organization_id)) {
-        const socketOrg = server.wsManager.organizations.get(organization_id);
-        if (organization.balance <= 0) {
-            socketOrg.status = false;
-            socketOrg.organizationBalance = false;
-            socketOrg.error = 'Your balance has fallen below 0';
-        } else {
-            socketOrg.status = true;
-            socketOrg.organizationBalance = true;
-            socketOrg.error = '';
-        }
+        // Constants
+        this.FLUSH_THRESHOLD_BYTES = 10 * 1024 * 1024; // 10 Megabytes
+        this.TENANT_INTERVAL_MS = 60 * 1000;            // 1 Minute
+
+        // Double-buffer map tracking separate platform and tenant blocks per organization
+        this.bandwidthMap = new Map();
+
+        // Initialize the Event Listeners
+        this.initEventListeners();
     }
 
-    let timeStamp = new Date(new Date().toISOString());
-    let isExpired = false;
-    if (organization.lastDeposit) {
-        let lastDeposit = new Date(organization.lastDeposit);
-        isExpired = lastDeposit <= timeStamp.setFullYear(timeStamp.getFullYear() - 1);
+    /**
+     * Connects directly to process event signals.
+     */
+    initEventListeners() {
+        // Unified Application-Wide System Interceptor
+        // Expects an input object: { organization_id, data, type: 'ingress' | 'egress' }
+        process.on('usage', (payload) => {
+            if (!payload || typeof payload !== 'object') return;
+            
+            const { organization_id, data, type } = payload;
+            if (organization_id) {
+                this.trackUsage(organization_id, data, type || 'ingress');
+            }
+        });
+
+        // Dynamic Eviction Loop: Caught via native process messaging.
+        // Triggers clean flushes and timer de-allocations during standard disconnects or orchestrator shutdowns.
+        process.on('orgDeleted', async (organization_id) => {
+            if (this.bandwidthMap.has(organization_id)) {
+                console.log(`[USAGE] Event Received: Flushing pending data pipelines for Org: ${organization_id}`);
+                try {
+                    await this.flushAndClearSingle(organization_id);
+                    console.log(`[USAGE] Flushing Completed: Memory registry successfully cleared for Org: ${organization_id}`);
+                } catch (err) {
+                    console.error(`[USAGE ERROR] Failed to cleanly flush data during orgDeleted event for ${organization_id}:`, err);
+                }
+            }
+        });
     }
 
-    let isResetDataTransfer = false;
-    if (organization.modified && organization.modified.on) {
-        let previousTimeStamp = new Date(organization.modified.on);
-        if (previousTimeStamp.getMonth() !== timeStamp.getMonth()) {
-            isResetDataTransfer = true;
-            server.crud.send({
-                method: 'object.create',
-                // host: server.host,
-                array: 'transactions',
-                object: {
-                    organization_id,
-                    type: "withdrawal",
-                    dataTransfered: organization.dataTransfered,
-                    previousTimeStamp
+    /**
+     * High-performance, robust byte-calculation routine.
+     * Accurately parses binary files (images, video chunks), text responses, and data objects.
+     */
+    calculatePayloadBytes(data) {
+        if (data === null || data === undefined) return 0;
+        
+        try {
+            // Case 1: Raw media streams, files, or binary chunks (Buffers / TypedArrays)
+            if (Buffer.isBuffer(data)) {
+                return data.length;
+            }
+            if (data instanceof Uint8Array || data.buffer instanceof ArrayBuffer) {
+                return data.byteLength || data.length || 0;
+            }
+            
+            // Case 2: Plain Text / Base64 Encoded Strings
+            if (typeof data === 'string') {
+                return Buffer.byteLength(data, 'utf8');
+            }
+            
+            // Case 3: Native JavaScript Objects & Arrays (Database schemas, API JSON packets)
+            if (typeof data === 'object') {
+                return Buffer.byteLength(JSON.stringify(data), 'utf8');
+            }
+            
+            // Case 4: Fallback for primitive datatypes (numbers, booleans, etc.)
+            return Buffer.byteLength(String(data), 'utf8');
+        } catch (error) {
+            console.error('[USAGE ERROR] Failed to safely calculate payload byte scale:', error);
+            return 0;
+        }
+    }
+
+    /**
+     * Main entry point to track incoming traffic.
+     */
+    trackUsage(organization_id, data, direction = 'ingress') {
+        const now = Date.now();
+        const incomingBytes = this.calculatePayloadBytes(data);
+
+        // If this is a brand new organization session, initialize our distinct tracking layers
+        if (!this.bandwidthMap.has(organization_id)) {
+            const tenantTimer = setInterval(() => {
+                this.flushTenantWindow(organization_id);
+            }, this.TENANT_INTERVAL_MS);
+
+            this.bandwidthMap.set(organization_id, {
+                // Buffer A: Tenant 1-minute accumulator (system_usage)
+                tenant: {
+                    ingressBytes: 0,
+                    egressBytes: 0,
+                    totalBytes: 0,
+                    count: 0,
+                    sampleStart: now,
+                    sampleEnd: now
+                },
+                // Buffer B: Platform master accumulator (system_bandwidth)
+                platform: {
+                    ingressBytes: 0,
+                    egressBytes: 0,
+                    totalBytes: 0,
+                    count: 0,
+                    sampleStart: now,
+                    sampleEnd: now
                 },
-                organization_id: platformOrganization,
-                timeStamp
+                tenantTimer
             });
-            organization.dataTransfered = 0;
         }
-    }
 
-    let dataTransfered = org.dataTransferedIn + org.dataTransferedOut;
-    dataTransfered = dataTransfered / 1073741824;
-    dataTransfered = dataTransfered.toFixed(32);
-    dataTransfered = parseFloat(dataTransfered);
-
-    let rate = getRate(organization.dataTransfered);
-    let amount = dataTransfered * rate;
-    amount = -amount;
-    amount = amount.toFixed(32);
-    amount = parseFloat(amount);
-
-    let balanceUpdate = {
-        method: 'object.update',
-        // host: server.host,
-        array: 'organizations',
-        object: { _id: organization_id },
-        organization_id: platformOrganization,
-        timeStamp
-    };
-
-    if (isExpired)
-        balanceUpdate.object['balance'] = 0;
-    else
-        balanceUpdate.object.$inc = { balance: amount };
-
-    if (isResetDataTransfer)
-        balanceUpdate.object['dataTransfered'] = 0;
-    else if (!balanceUpdate.object.$inc)
-        balanceUpdate.object.$inc = { dataTransfered };
-    else
-        balanceUpdate.object.$inc.dataTransfered = dataTransfered;
-
-    server.crud.send(balanceUpdate);
-
-    let transaction = {
-        method: 'object.create',
-        host,
-        array: 'transactions',
-        object: {
-            organization_id,
-            type: "withdrawal",
-            amount,
-            rate,
-            dataTransfered,
-            ...org
-        },
-        organization_id,
-        timeStamp
-    };
-
-    server.crud.send(transaction);
-}
+        const stats = this.bandwidthMap.get(organization_id);
 
-/**
- * Event-driven handler that accumulates payload footprints and manages write debouncing.
- */
-async function setBandwidth({ type, data, organization_id }) {
-    try {
-        let dataTransfered = getBytes(data);
-
-        if (!dataTransfered || !organization_id)
-            return;
-
-        let org = organizations.get(organization_id);
-        if (!org) {
-            org = {};
-            org.debounce = setTimeout(() => {
-                sendUsageUpdate(org, organization_id, data.host);
-                organizations.delete(organization_id);
-            }, 60000);
-
-            org.dataTransferedIn = 0;
-            org.dataTransferedInCount = 0;
-            org.dataTransferedOut = 0;
-            org.dataTransferedOutCount = 0;
-
-            organizations.set(organization_id, org);
+        // 1. Accumulate Tenant Buffer (Flushes on interval)
+        if (direction === 'ingress') {
+            stats.tenant.ingressBytes += incomingBytes;
+        } else if (direction === 'egress') {
+            stats.tenant.egressBytes += incomingBytes;
+        }
+        stats.tenant.totalBytes += incomingBytes;
+        stats.tenant.count += 1;
+        stats.tenant.sampleEnd = now;
+
+        // 2. Accumulate Platform Buffer (Flushes on event triggers / 10MB only)
+        if (direction === 'ingress') {
+            stats.platform.ingressBytes += incomingBytes;
+        } else if (direction === 'egress') {
+            stats.platform.egressBytes += incomingBytes;
         }
+        stats.platform.totalBytes += incomingBytes;
+        stats.platform.count += 1;
+        stats.platform.sampleEnd = now;
 
-        if (type === 'in') {
-            org.dataTransferedIn = dataTransfered;
-            org.dataTransferedInCount++;
-        } else if (type === 'out') {
-            org.dataTransferedOut = dataTransfered;
-            org.dataTransferedOutCount++;
-        } else {
-            console.log('else');
+        // 3. Platform Trigger: Flush to the master platform ledger if we hit 10MB
+        if (stats.platform.totalBytes >= this.FLUSH_THRESHOLD_BYTES) {
+            this.flushPlatformWindow(organization_id);
         }
+    }
 
-    } catch (error) {
-        console.log('Usage error', error);
+    /**
+     * PIPELINE A: Handles the 1-minute interval flush to the client tenant's database
+     */
+    async flushTenantWindow(organization_id) {
+        const stats = this.bandwidthMap.get(organization_id);
+        if (!stats || stats.tenant.totalBytes === 0) return;
+
+        const tenantData = stats.tenant;
+
+        // Save exactly one document representing this complete 1-minute segment to their partition
+        await this.saveToTenantBilling(organization_id, tenantData);
+
+        // Reset ONLY the tenant accumulator to begin a fresh 1-minute block
+        const now = Date.now();
+        stats.tenant = {
+            ingressBytes: 0,
+            egressBytes: 0,
+            totalBytes: 0,
+            count: 0,
+            sampleStart: now,
+            sampleEnd: now
+        };
     }
-}
 
-/**
- * Auto-initialization loop.
- * Silently polls to verify that the unified server orchestrator is fully loaded,
- * and that both the database (crud) and socket manager (wsManager) have completed
- * their initial handshakes, then attaches active bandwidth monitoring triggers.
- */
-function init() {
-    if (server && server.isInitialized && server.crud && server.wsManager) {
-        server.wsManager.on('setBandwidth', (data) => setBandwidth(data));
-    } else {
-        // If the server and WebSocket managers are not yet ready, retry in 500ms
-        setTimeout(init, 500);
+    /**
+     * PIPELINE B: Handles targeted platform flushes (when 10MB limit is reached)
+     */
+    async flushPlatformWindow(organization_id) {
+        const stats = this.bandwidthMap.get(organization_id);
+        if (!stats || stats.platform.totalBytes === 0) return;
+
+        const platformData = stats.platform;
+
+        // Save platform ledger record
+        await this.saveToLedgerDatabase(organization_id, platformData);
+
+        // Reset ONLY the platform long-term memory accumulator
+        const now = Date.now();
+        stats.platform = {
+            ingressBytes: 0,
+            egressBytes: 0,
+            totalBytes: 0,
+            count: 0,
+            sampleStart: now,
+            sampleEnd: now
+        };
     }
-}
 
-// Auto-execute initialization upon module load
-init();
+    /**
+     * Target eviction: Clears timers and flushes all outstanding tenant & platform balances
+     */
+    async flushAndClearSingle(organization_id) {
+        const stats = this.bandwidthMap.get(organization_id);
+        if (!stats) return;
+
+        // De-allocate the 1-minute background loop instantly
+        if (stats.tenantTimer) {
+            clearInterval(stats.tenantTimer);
+        }
+
+        // Flush any partial unsaved records remaining in either pipeline
+        await Promise.all([
+            this.flushTenantWindow(organization_id),
+            this.flushPlatformWindow(organization_id)
+        ]);
+
+        // Evict from active tracker
+        this.bandwidthMap.delete(organization_id);
+    }
+
+    /**
+     * CRUD Adapter: Platform Bandwidth Collection (Private time-series log)
+     * Writes into the platform's sandbox segment, cataloging target clients in "organization".
+     */
+    async saveToLedgerDatabase(organization_id, stats) {
+        try {
+            await crud.send({
+                method: 'object.create',
+                array: 'system_bandwidth',
+                object: {
+                    organization_id: this.platformOrgId, // Platform workspace sandbox route
+                    organization: organization_id,       // The actual client tenant who generated the bandwidth
+                    ingressBytes: stats.ingressBytes,
+                    egressBytes: stats.egressBytes,
+                    totalBytes: stats.totalBytes,
+                    totalRequests: stats.count,
+                    sampleStart: new Date(stats.sampleStart),
+                    sampleEnd: new Date(stats.sampleEnd),
+                    durationMs: stats.sampleEnd - stats.sampleStart,
+                    processed: false                     // Ready for asynchronous billing calculations
+                },
+                organization_id: this.platformOrgId      // Outermost routing targeting the Platform's DB partition
+            });
+        } catch (error) {
+            console.error(`[DB ERROR] Failed to write to system_bandwidth for ${organization_id}:`, error);
+        }
+    }
+
+    /**
+     * CRUD Adapter: Tenant Usage Collection (Their 1-Minute Dashboard Stream)
+     * Writes directly to the tenant's partition under the safe, system namespace "system_usage"
+     */
+    async saveToTenantBilling(organization_id, stats) {
+        try {
+            await crud.send({
+                method: 'object.create',
+                array: 'system_usage',
+                object: {
+                    organization_id,                     // Tenant's sandbox segment route
+                    ingressBytes: stats.ingressBytes,
+                    egressBytes: stats.egressBytes,
+                    totalBytes: stats.totalBytes,
+                    totalRequests: stats.count,
+                    sampleStart: new Date(stats.sampleStart),
+                    sampleEnd: new Date(stats.sampleEnd),
+                    durationMs: stats.sampleEnd - stats.sampleStart
+                },
+                organization_id: organization_id         // Outermost routing targeting the Client's DB partition
+            });
+        } catch (error) {
+            console.error(`[DB ERROR] Failed to write to system_usage for ${organization_id}:`, error);
+        }
+    }
+}
 
-export default init;
+export default CoCreateUsage;