@soft-where/meter 1.0.0

package/README.md

@@ -0,0 +1,151 @@
+# @soft-where/meter
+
+Production-safe, edge-compatible usage metering for Node and Next.js. Tracks API requests, bandwidth, blob storage, custom metrics, and DB snapshots by posting to the SOFT-WHERE ERP. Stateless, non-blocking, and only active when `NODE_ENV === "production"`.
+
+## Install
+
+```bash
+npm install @soft-where/meter
+```
+
+## Required variables
+
+The meter needs three values. **Pass them in when calling `createMeter()`**; in apps you typically read from environment variables so secrets stay out of code.
+
+| Variable | Purpose | Example |
+|----------|---------|--------|
+| **projectId** | Your SOFT-WHERE project identifier | `"proj_abc123"` |
+| **apiKey** | Secret key for the ERP (do not expose to the client) | From SOFT-WHERE dashboard |
+| **erpUrl** | Full URL of the SOFT-WHERE ERP ingest endpoint | `"https://erp.soft-where.com/ingest"` |
+| **environment** | Optional label (e.g. staging vs production) | `"production"` |
+
+**Important:** Do not use `NEXT_PUBLIC_*` for `apiKey` or other secrets. Use server/edge-only env vars (e.g. `SOFT_WHERE_API_KEY`) so they are not bundled for the browser.
+
+## Usage
+
+### 1. Create a meter
+
+Call `createMeter()` once (e.g. at module load or in a shared helper) and reuse the returned object. Use env vars for config so you can change them per environment without code changes.
+
+```ts
+import { createMeter } from "@soft-where/meter";
+
+const meter = createMeter({
+  projectId: process.env.SOFT_WHERE_PROJECT_ID!,
+  apiKey: process.env.SOFT_WHERE_API_KEY!,
+  erpUrl: process.env.SOFT_WHERE_ERP_URL!,
+  environment: process.env.VERCEL_ENV ?? process.env.NODE_ENV,
+});
+```
+
+### 2. Use the meter
+
+- **trackRequest(req, res, durationMs)** — Call with the same `Request` and `Response` (or Next.js `NextRequest` / `NextResponse`) and the request duration in milliseconds. The library sends one request event (and reads `bandwidthBytes` from `Response#headers` `Content-Length` when present).
+- **trackBlobUpload(bytes)** / **trackBlobDelete(bytes)** — Call from upload/delete handlers with the byte deltas.
+- **trackCustomMetric(name, value)** — Send arbitrary numeric metrics.
+- **attemptDbSnapshot(getDbSize)** — Call with an async function that returns DB size in bytes (e.g. Neon HTTP). The library will call it, then post the snapshot to the ERP without blocking on the network.
+
+All methods are no-ops when `NODE_ENV !== "production"`. They never throw and never block request completion (ERP calls are fire-and-forget with `keepalive: true`).
+
+---
+
+## Next.js: use in `middleware.ts`
+
+Middleware runs on the Edge runtime. You can use `@soft-where/meter` there to send request counts and duration (and bandwidth when `Content-Length` is present on the response) to the SOFT-WHERE ERP.
+
+### Cursor agent instructions (Next.js middleware integration)
+
+Use the following as both documentation and a prompt for a Cursor agent that should wire this package into a Next.js app’s middleware.
+
+**Goal:** Integrate `@soft-where/meter` into the existing Next.js middleware so that every request is metered and reported to the SOFT-WHERE ERP. Do not break existing middleware logic (auth, redirects, etc.); add metering alongside it.
+
+**Steps:**
+
+1. **Install the package**  
+   - Add dependency: `@soft-where/meter`.
+
+2. **Environment variables**  
+   - Ensure the Next.js project has these **server/edge-only** env vars (e.g. in `.env.local` or in the hosting provider’s dashboard). Do **not** prefix them with `NEXT_PUBLIC_`:
+     - `SOFT_WHERE_PROJECT_ID` — SOFT-WHERE project ID.
+     - `SOFT_WHERE_API_KEY` — Secret API key for the ERP.
+     - `SOFT_WHERE_ERP_URL` — Full ERP ingest URL (e.g. `https://erp.soft-where.com/ingest`).
+   - Document these in the project’s env example (e.g. `.env.example`) with short comments.
+
+3. **Create a shared meter instance**  
+   - In the same file as the middleware (or in a small module it imports), create the meter once using the env vars above:
+     - `createMeter({ projectId, apiKey, erpUrl, environment? })`.
+     - Read `projectId`, `apiKey`, and `erpUrl` from `process.env.SOFT_WHERE_PROJECT_ID`, `process.env.SOFT_WHERE_API_KEY`, and `process.env.SOFT_WHERE_ERP_URL`.
+     - Only create/call the meter when these env vars are defined so the app does not crash in dev or when the integration is disabled.
+
+4. **Wire metering into `middleware.ts`**  
+   - In the middleware function:
+     - Record the start time at the very beginning (e.g. `const start = Date.now()`).
+     - Run the existing middleware logic and obtain the `NextResponse` (or other response) you intend to return.
+     - Before returning, call `meter.trackRequest(request, response, durationMs)` where:
+       - `request` is the middleware’s `NextRequest` (it is a standard `Request`).
+       - `response` is the `NextResponse` (or response) you are about to return (it is a standard `Response`).
+       - `durationMs` is `Date.now() - start`.
+     - Return the same response as before so behavior is unchanged.
+   - Do not `await` the meter; `trackRequest` is fire-and-forget and must not block the response.
+
+5. **Edge compatibility**  
+   - Middleware runs on the Edge runtime. `@soft-where/meter` is edge-compatible and uses the global `fetch` with `keepalive: true`. No extra config is required.
+
+6. **Production-only behavior**  
+   - The library only sends data when `NODE_ENV === "production"`. In development, all meter calls are no-ops; no need to guard calls in code.
+
+**Summary for the agent:** Install `@soft-where/meter`, add env vars `SOFT_WHERE_PROJECT_ID`, `SOFT_WHERE_API_KEY`, and `SOFT_WHERE_ERP_URL` (no `NEXT_PUBLIC_`), create one meter with `createMeter()` from those env vars, then in `middleware.ts` measure duration and call `meter.trackRequest(request, response, durationMs)` before returning the response. Leave all other middleware logic intact.
+
+---
+
+### Minimal middleware example
+
+```ts
+// middleware.ts (Next.js)
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+import { createMeter } from "@soft-where/meter";
+
+const projectId = process.env.SOFT_WHERE_PROJECT_ID;
+const apiKey = process.env.SOFT_WHERE_API_KEY;
+const erpUrl = process.env.SOFT_WHERE_ERP_URL;
+
+const meter =
+  projectId && apiKey && erpUrl
+    ? createMeter({ projectId, apiKey, erpUrl })
+    : null;
+
+export function middleware(request: NextRequest) {
+  const start = Date.now();
+  const response = NextResponse.next();
+  const durationMs = Date.now() - start;
+
+  if (meter) {
+    meter.trackRequest(request, response, durationMs);
+  }
+
+  return response;
+}
+```
+
+## API reference
+
+- **createMeter(options)**  
+  `options.projectId` (string), `options.apiKey` (string), `options.erpUrl` (string), `options.environment?` (string).  
+  Returns a **Meter** object.
+
+- **meter.trackRequest(req, res, durationMs)**  
+  `req` and `res` are the Web API `Request` and `Response` (or Next.js equivalents). `durationMs` is the request duration in milliseconds. Sends one request event; bandwidth is taken from `res.headers` `Content-Length` when present.
+
+- **meter.trackBlobUpload(bytes)** / **meter.trackBlobDelete(bytes)**  
+  `bytes` is the size delta.
+
+- **meter.trackCustomMetric(name, value)**  
+  `name` (string), `value` (number).
+
+- **meter.attemptDbSnapshot(getDbSize)**  
+  `getDbSize` is a `() => Promise<number>` (e.g. Neon HTTP size). The library calls it and posts the result to the ERP without awaiting the network. Returns a Promise that resolves when the size has been obtained and the send has been triggered (or on error); never throws.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,23 @@
+/**
+ * SOFT-WHERE usage metering library.
+ * Production-safe, edge-compatible, stateless. Only sends when NODE_ENV === "production".
+ * @packageDocumentation
+ */
+declare const VERSION = "1.0.0";
+
+type CreateMeterOptions = {
+    projectId: string;
+    apiKey: string;
+    erpUrl: string;
+    environment?: string;
+};
+type Meter = {
+    trackRequest: (req: Request, res: Response, durationMs: number) => void;
+    trackBlobUpload: (bytes: number) => void;
+    trackBlobDelete: (bytes: number) => void;
+    trackCustomMetric: (name: string, value: number) => void;
+    attemptDbSnapshot: (getDbSize: () => Promise<number>) => Promise<void>;
+};
+declare function createMeter(options: CreateMeterOptions): Meter;
+
+export { type CreateMeterOptions, type Meter, createMeter, VERSION as version };

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * SOFT-WHERE usage metering library.
+ * Production-safe, edge-compatible, stateless. Only sends when NODE_ENV === "production".
+ * @packageDocumentation
+ */
+declare const VERSION = "1.0.0";
+
+type CreateMeterOptions = {
+    projectId: string;
+    apiKey: string;
+    erpUrl: string;
+    environment?: string;
+};
+type Meter = {
+    trackRequest: (req: Request, res: Response, durationMs: number) => void;
+    trackBlobUpload: (bytes: number) => void;
+    trackBlobDelete: (bytes: number) => void;
+    trackCustomMetric: (name: string, value: number) => void;
+    attemptDbSnapshot: (getDbSize: () => Promise<number>) => Promise<void>;
+};
+declare function createMeter(options: CreateMeterOptions): Meter;
+
+export { type CreateMeterOptions, type Meter, createMeter, VERSION as version };

package/dist/index.js

@@ -0,0 +1,97 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  createMeter: () => createMeter,
+  version: () => VERSION
+});
+module.exports = __toCommonJS(index_exports);
+var VERSION = "1.0.0";
+function getBandwidthBytes(res) {
+  const cl = res.headers.get("content-length");
+  if (cl == null) return 0;
+  const n = Number(cl);
+  return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+function createMeter(options) {
+  const { projectId, apiKey, erpUrl } = options;
+  const isProduction = typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+  function postToErp(payload) {
+    if (!isProduction) return;
+    try {
+      fetch(erpUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-softwhere-key": apiKey
+        },
+        body: JSON.stringify(payload),
+        keepalive: true
+      }).catch(() => {
+      });
+    } catch {
+    }
+  }
+  return {
+    trackRequest(req, res, durationMs) {
+      if (!isProduction) return;
+      const bandwidthBytes = getBandwidthBytes(res);
+      postToErp({
+        type: "request",
+        projectId,
+        apiRequests: 1,
+        bandwidthBytes,
+        durationMs,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    },
+    trackBlobUpload(bytes) {
+      if (!isProduction) return;
+      postToErp({ type: "blob_upload", projectId, bytes });
+    },
+    trackBlobDelete(bytes) {
+      if (!isProduction) return;
+      postToErp({ type: "blob_delete", projectId, bytes });
+    },
+    trackCustomMetric(name, value) {
+      if (!isProduction) return;
+      postToErp({ type: "custom", projectId, metric: name, value });
+    },
+    async attemptDbSnapshot(getDbSize) {
+      if (!isProduction) return;
+      try {
+        const dbBytes = await getDbSize();
+        postToErp({
+          type: "db_snapshot",
+          projectId,
+          dbBytes,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      } catch {
+      }
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createMeter,
+  version
+});

package/dist/index.mjs

@@ -0,0 +1,71 @@
+// index.ts
+var VERSION = "1.0.0";
+function getBandwidthBytes(res) {
+  const cl = res.headers.get("content-length");
+  if (cl == null) return 0;
+  const n = Number(cl);
+  return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+function createMeter(options) {
+  const { projectId, apiKey, erpUrl } = options;
+  const isProduction = typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+  function postToErp(payload) {
+    if (!isProduction) return;
+    try {
+      fetch(erpUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-softwhere-key": apiKey
+        },
+        body: JSON.stringify(payload),
+        keepalive: true
+      }).catch(() => {
+      });
+    } catch {
+    }
+  }
+  return {
+    trackRequest(req, res, durationMs) {
+      if (!isProduction) return;
+      const bandwidthBytes = getBandwidthBytes(res);
+      postToErp({
+        type: "request",
+        projectId,
+        apiRequests: 1,
+        bandwidthBytes,
+        durationMs,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    },
+    trackBlobUpload(bytes) {
+      if (!isProduction) return;
+      postToErp({ type: "blob_upload", projectId, bytes });
+    },
+    trackBlobDelete(bytes) {
+      if (!isProduction) return;
+      postToErp({ type: "blob_delete", projectId, bytes });
+    },
+    trackCustomMetric(name, value) {
+      if (!isProduction) return;
+      postToErp({ type: "custom", projectId, metric: name, value });
+    },
+    async attemptDbSnapshot(getDbSize) {
+      if (!isProduction) return;
+      try {
+        const dbBytes = await getDbSize();
+        postToErp({
+          type: "db_snapshot",
+          projectId,
+          dbBytes,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      } catch {
+      }
+    }
+  };
+}
+export {
+  createMeter,
+  VERSION as version
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@soft-where/meter",
+  "version": "1.0.0",
+  "description": "SOFT-WHERE usage metering library — production-safe, edge-compatible, stateless",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "npx tsup index.ts --format esm,cjs --dts",
+    "dev": "npx tsup index.ts --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["metering", "usage", "analytics", "edge", "soft-where"],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}