@columenlabs/lumen-ops 0.1.36 → 0.1.38

package/README.md

@@ -1,6 +1,6 @@
 # @columenlabs/lumen-ops
 
-Lumen's ops meters for Cloudflare Workers: every data query your app runs becomes one Analytics Engine point, so you can find slow and heavy queries and fix them. The meter wraps your bindings once, so new code is metered without opting in. It writes only each query's shape, never a value.
+Lumen's ops parts for Cloudflare Workers: every data query your app runs becomes one Analytics Engine point, so you can find slow and heavy queries and fix them. The meter wraps your bindings once, so new code is metered without opting in. It writes only each query's shape, never a value. It also meters tool calls (`/tools`) and sends signed webhooks (`/webhooks`).
 
 - Docs: https://lumen.columenlabs.com/docs/
 - For agents: https://lumen.columenlabs.com/llms.txt
@@ -124,6 +124,32 @@ Arguments and results are never written; only their sizes.
 | `meteredCall(point, fn, errorKind?)` | Runs `fn`, timing it and writing its outcome |
 | `codeHash(code)` | A short hash of a script, whitespace folded |
 
+## Webhooks out
+
+`@columenlabs/lumen-ops/webhooks` sends one delivery, signed per the [Standard Webhooks](https://www.standardwebhooks.com) spec when a secret is given, so the receiver can verify it with any Standard Webhooks library. It never throws: the result says how it went, for the app's own delivery log and retries.
+
+```ts
+import { newWebhookSecret, sendWebhook } from '@columenlabs/lumen-ops/webhooks';
+
+const secret = newWebhookSecret(); // whsec_…, shown to its owner once, kept sealed
+const r = await sendWebhook({
+  url: endpoint.url,
+  secret,
+  id: event.id, // the same id on a retry
+  body: JSON.stringify(event.payload),
+  headers: { authorization: `Bearer ${endpoint.token}` },
+  userAgent: 'MyApp-Webhooks/1',
+});
+if (!r.ok) scheduleRetry(event, r.status, r.error);
+```
+
+| Export | What it does |
+|---|---|
+| `sendWebhook(send)` | One POST: `{ ok, status, ms, id, error? }`; status 0 when the endpoint never answered |
+| `newWebhookSecret()` | A new `whsec_` secret, 32 random bytes |
+
+The endpoint's own headers go first, so they can never replace the signature headers. Redirects count as failures unless `redirect` says otherwise; the timeout is 10 s by default.
+
 ## Versions
 
 0.x: any minor may break things until 1.0. Every merge to Lumen's `main` publishes the next patch of every Lumen package; see the [releases](https://github.com/columenlabs/lumen/releases).

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './points.js';
 export * from './queries.js';
 export * from './tools.js';
+export * from './webhooks.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from './points.js';
 export * from './queries.js';
 export * from './tools.js';
+export * from './webhooks.js';

package/dist/webhooks.d.ts

@@ -0,0 +1,34 @@
+export interface WebhookSend {
+    url: string;
+    /** The body as sent and signed, usually JSON. */
+    body: string;
+    /** Signs the delivery: `whsec_…` (see `newWebhookSecret`). Left out, nothing is signed. */
+    secret?: string;
+    /** The message id the signature covers; the same id on a retry. Made up when left out. */
+    id?: string;
+    /** The endpoint's own headers (its auth). They can never replace the signature headers. */
+    headers?: Record<string, string>;
+    /** Default `application/json`. */
+    contentType?: string;
+    userAgent?: string;
+    /** Default 10 s. */
+    timeoutMs?: number;
+    /** Default `manual`: a redirect counts as a failed delivery, never followed. */
+    redirect?: RequestRedirect;
+    /** For tests or a service binding; default the global fetch. */
+    fetch?: typeof fetch;
+}
+export interface WebhookResult {
+    ok: boolean;
+    /** The endpoint's HTTP status; 0 when it never answered (timeout, DNS, refused). */
+    status: number;
+    ms: number;
+    /** The message id sent. */
+    id: string;
+    /** On a failure: the first 200 characters of the answer, or why there was none. */
+    error?: string;
+}
+/** A new signing secret, `whsec_` and 32 random bytes in base64. Show it to its owner once. */
+export declare function newWebhookSecret(): string;
+/** Sends one delivery. */
+export declare function sendWebhook(send: WebhookSend): Promise<WebhookResult>;

package/dist/webhooks.js

@@ -0,0 +1,49 @@
+/**
+ * Webhooks out: one POST to an endpoint, signed per the Standard Webhooks spec
+ * (https://www.standardwebhooks.com) when a secret is given, so any of its libraries verifies it.
+ * The send never throws: it returns how it went, for the app's own delivery log and retries.
+ */
+import { Webhook } from 'standardwebhooks';
+/** A new signing secret, `whsec_` and 32 random bytes in base64. Show it to its owner once. */
+export function newWebhookSecret() {
+    const bytes = crypto.getRandomValues(new Uint8Array(32));
+    return `whsec_${btoa(String.fromCharCode(...bytes))}`;
+}
+/** Sends one delivery. */
+export async function sendWebhook(send) {
+    const id = send.id ?? `msg_${crypto.randomUUID().replaceAll('-', '')}`;
+    const at = new Date();
+    const signed = send.secret
+        ? {
+            'webhook-id': id,
+            'webhook-timestamp': String(Math.floor(at.getTime() / 1000)),
+            'webhook-signature': new Webhook(send.secret).sign(id, at, send.body),
+        }
+        : {};
+    const started = Date.now();
+    try {
+        const res = await (send.fetch ?? fetch)(send.url, {
+            method: 'POST',
+            redirect: send.redirect ?? 'manual',
+            signal: AbortSignal.timeout(send.timeoutMs ?? 10_000),
+            headers: {
+                ...send.headers,
+                'content-type': send.contentType ?? 'application/json',
+                ...(send.userAgent ? { 'user-agent': send.userAgent } : {}),
+                ...signed,
+            },
+            body: send.body,
+        });
+        const ok = res.status >= 200 && res.status < 300;
+        let error;
+        if (ok)
+            await res.body?.cancel();
+        else
+            error = (await res.text().catch(() => '')).slice(0, 200) || `HTTP ${res.status}`;
+        return { ok, status: res.status, ms: Date.now() - started, id, ...(error ? { error } : {}) };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        return { ok: false, status: 0, ms: Date.now() - started, id, error: error.slice(0, 200) };
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@columenlabs/lumen-ops",
-  "version": "0.1.36",
-  "description": "Lumen's ops meters: every data query and every tool call an app runs as one Analytics Engine point, by shape and hash only.",
+  "version": "0.1.38",
+  "description": "Lumen's ops parts: every data query and tool call an app runs as one Analytics Engine point (shapes and hashes only), and signed webhooks out.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,6 +22,10 @@
     "./tools": {
       "types": "./dist/tools.d.ts",
       "default": "./dist/tools.js"
+    },
+    "./webhooks": {
+      "types": "./dist/webhooks.d.ts",
+      "default": "./dist/webhooks.js"
     }
   },
   "files": [
@@ -43,5 +47,7 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "dependencies": {}
+  "dependencies": {
+    "standardwebhooks": "1.1.1"
+  }
 }