@metr-sdk/express 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @metr/express - One line of middleware to monetize any Express.js API
+ *
+ * @example
+ * ```typescript
+ * import { metr } from '@metr/express';
+ *
+ * app.post('/api/summarize', metr({ price: 0.001 }), (req, res) => {
+ *   res.json({ summary: 'Your text summary...' });
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { Request, Response, NextFunction } from 'express';
+export interface MetrConfig {
+    /** Price per unit in USD (e.g., 0.001 = $0.001 per request) */
+    price: number;
+    /** Unit type for metering. Default: "request" */
+    unitType?: 'request' | 'token' | 'byte' | 'second';
+    /** Your metr API key. Falls back to METR_API_KEY env var */
+    apiKey?: string;
+    /** Your registered endpoint ID. Falls back to METR_ENDPOINT_ID env var */
+    endpointId?: string;
+    /** metr gateway URL. Falls back to METR_GATEWAY_URL env var */
+    gatewayUrl?: string;
+}
+export interface MetrPaymentInfo {
+    sessionToken: string;
+    buyerId: string;
+    balanceUsd: number;
+}
+declare global {
+    namespace Express {
+        interface Request {
+            metr?: MetrPaymentInfo;
+        }
+    }
+}
+/**
+ * metr middleware - add to any Express route to require payment.
+ *
+ * Checks for a valid billing session token in the `Authorization` header.
+ * If missing or invalid, returns 402 Payment Required with a checkout URL.
+ * If valid, meters the usage and passes control to your handler.
+ */
+export declare function metr(config: MetrConfig): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+export default metr;

package/dist/index.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * @metr/express - One line of middleware to monetize any Express.js API
+ *
+ * @example
+ * ```typescript
+ * import { metr } from '@metr/express';
+ *
+ * app.post('/api/summarize', metr({ price: 0.001 }), (req, res) => {
+ *   res.json({ summary: 'Your text summary...' });
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.metr = metr;
+const DEFAULT_GATEWAY_URL = 'https://api.metr.dev';
+/**
+ * metr middleware - add to any Express route to require payment.
+ *
+ * Checks for a valid billing session token in the `Authorization` header.
+ * If missing or invalid, returns 402 Payment Required with a checkout URL.
+ * If valid, meters the usage and passes control to your handler.
+ */
+function metr(config) {
+    const apiKey = config.apiKey || process.env.METR_API_KEY;
+    const endpointId = config.endpointId || process.env.METR_ENDPOINT_ID;
+    const gatewayUrl = config.gatewayUrl || process.env.METR_GATEWAY_URL || DEFAULT_GATEWAY_URL;
+    if (!apiKey) {
+        throw new Error('metr: API key required. Set config.apiKey or METR_API_KEY env var.');
+    }
+    return async (req, res, next) => {
+        // Extract session token from Authorization header
+        const authHeader = req.headers.authorization;
+        const sessionToken = authHeader?.startsWith('Bearer metr_sess_')
+            ? authHeader.slice(7)
+            : null;
+        if (!sessionToken) {
+            // No valid session — return 402 with checkout URL
+            try {
+                const checkoutRes = await fetch(`${gatewayUrl}/api/v1/checkout/create`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-Metr-Api-Key': apiKey,
+                    },
+                    body: JSON.stringify({
+                        endpoint_id: endpointId,
+                        amount_usd: config.price,
+                    }),
+                });
+                const checkout = await checkoutRes.json();
+                res.status(402).json({
+                    error: 'payment_required',
+                    message: 'This API requires payment. Complete checkout to get access.',
+                    checkout_url: checkout.checkout_url,
+                    price: config.price,
+                    unit_type: config.unitType || 'request',
+                });
+            }
+            catch (err) {
+                res.status(500).json({ error: 'Failed to create checkout session' });
+            }
+            return;
+        }
+        // Verify session is valid
+        try {
+            const verifyRes = await fetch(`${gatewayUrl}/api/v1/verify`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-Metr-Api-Key': apiKey,
+                },
+                body: JSON.stringify({ session_token: sessionToken }),
+            });
+            const session = await verifyRes.json();
+            if (!session.valid) {
+                res.status(402).json({
+                    error: 'session_expired',
+                    message: 'Your billing session has expired. Please create a new checkout.',
+                });
+                return;
+            }
+            // Attach payment info to request
+            req.metr = {
+                sessionToken,
+                buyerId: session.buyer_id || '',
+                balanceUsd: session.remaining_balance_usd || 0,
+            };
+            // Let the handler execute
+            next();
+            // After handler completes, record usage (fire and forget)
+            fetch(`${gatewayUrl}/api/v1/meter`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-Metr-Api-Key': apiKey,
+                },
+                body: JSON.stringify({
+                    endpoint_id: endpointId,
+                    session_token: sessionToken,
+                    units: 1,
+                    unit_type: config.unitType || 'request',
+                }),
+            }).catch((err) => {
+                console.error('[metr] Failed to record usage:', err);
+            });
+        }
+        catch (err) {
+            res.status(500).json({ error: 'Failed to verify session' });
+        }
+    };
+}
+exports.default = metr;

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@metr-sdk/express",
+  "version": "0.1.0",
+  "description": "One line of middleware to monetize any Express.js API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["metr", "api", "monetization", "metering", "billing", "stripe", "middleware", "express"],
+  "license": "MIT",
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "express": "^4.18.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.3.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,161 @@
+/**
+ * @metr/express - One line of middleware to monetize any Express.js API
+ *
+ * @example
+ * ```typescript
+ * import { metr } from '@metr/express';
+ *
+ * app.post('/api/summarize', metr({ price: 0.001 }), (req, res) => {
+ *   res.json({ summary: 'Your text summary...' });
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import { Request, Response, NextFunction } from 'express';
+
+export interface MetrConfig {
+  /** Price per unit in USD (e.g., 0.001 = $0.001 per request) */
+  price: number;
+
+  /** Unit type for metering. Default: "request" */
+  unitType?: 'request' | 'token' | 'byte' | 'second';
+
+  /** Your metr API key. Falls back to METR_API_KEY env var */
+  apiKey?: string;
+
+  /** Your registered endpoint ID. Falls back to METR_ENDPOINT_ID env var */
+  endpointId?: string;
+
+  /** metr gateway URL. Falls back to METR_GATEWAY_URL env var */
+  gatewayUrl?: string;
+}
+
+export interface MetrPaymentInfo {
+  sessionToken: string;
+  buyerId: string;
+  balanceUsd: number;
+}
+
+declare global {
+  namespace Express {
+    interface Request {
+      metr?: MetrPaymentInfo;
+    }
+  }
+}
+
+const DEFAULT_GATEWAY_URL = 'https://api.metr.dev';
+
+/**
+ * metr middleware - add to any Express route to require payment.
+ *
+ * Checks for a valid billing session token in the `Authorization` header.
+ * If missing or invalid, returns 402 Payment Required with a checkout URL.
+ * If valid, meters the usage and passes control to your handler.
+ */
+export function metr(config: MetrConfig) {
+  const apiKey = config.apiKey || process.env.METR_API_KEY;
+  const endpointId = config.endpointId || process.env.METR_ENDPOINT_ID;
+  const gatewayUrl = config.gatewayUrl || process.env.METR_GATEWAY_URL || DEFAULT_GATEWAY_URL;
+
+  if (!apiKey) {
+    throw new Error('metr: API key required. Set config.apiKey or METR_API_KEY env var.');
+  }
+
+  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    // Extract session token from Authorization header
+    const authHeader = req.headers.authorization;
+    const sessionToken = authHeader?.startsWith('Bearer metr_sess_')
+      ? authHeader.slice(7)
+      : null;
+
+    if (!sessionToken) {
+      // No valid session — return 402 with checkout URL
+      try {
+        const checkoutRes = await fetch(`${gatewayUrl}/api/v1/checkout/create`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'X-Metr-Api-Key': apiKey,
+          },
+          body: JSON.stringify({
+            endpoint_id: endpointId,
+            amount_usd: config.price,
+          }),
+        });
+
+        const checkout = await checkoutRes.json() as { checkout_url: string; session_token: string };
+
+        res.status(402).json({
+          error: 'payment_required',
+          message: 'This API requires payment. Complete checkout to get access.',
+          checkout_url: checkout.checkout_url,
+          price: config.price,
+          unit_type: config.unitType || 'request',
+        });
+      } catch (err) {
+        res.status(500).json({ error: 'Failed to create checkout session' });
+      }
+      return;
+    }
+
+    // Verify session is valid
+    try {
+      const verifyRes = await fetch(`${gatewayUrl}/api/v1/verify`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Metr-Api-Key': apiKey,
+        },
+        body: JSON.stringify({ session_token: sessionToken }),
+      });
+
+      const session = await verifyRes.json() as {
+        valid: boolean;
+        buyer_id?: string;
+        remaining_balance_usd?: number;
+      };
+
+      if (!session.valid) {
+        res.status(402).json({
+          error: 'session_expired',
+          message: 'Your billing session has expired. Please create a new checkout.',
+        });
+        return;
+      }
+
+      // Attach payment info to request
+      req.metr = {
+        sessionToken,
+        buyerId: session.buyer_id || '',
+        balanceUsd: session.remaining_balance_usd || 0,
+      };
+
+      // Let the handler execute
+      next();
+
+      // After handler completes, record usage (fire and forget)
+      fetch(`${gatewayUrl}/api/v1/meter`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Metr-Api-Key': apiKey,
+        },
+        body: JSON.stringify({
+          endpoint_id: endpointId,
+          session_token: sessionToken,
+          units: 1,
+          unit_type: config.unitType || 'request',
+        }),
+      }).catch((err) => {
+        console.error('[metr] Failed to record usage:', err);
+      });
+    } catch (err) {
+      res.status(500).json({ error: 'Failed to verify session' });
+    }
+  };
+}
+
+export default metr;

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "strict": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}