totalum-sdk 0.1.0-dev.10

package/dist/webhooks/index.d.ts

@@ -0,0 +1,48 @@
+import { a as WebhookEvent } from '../_types/billing.d-BbSZh1wY.js';
+export { W as WebhookConfig, b as WebhookSecretOutput } from '../_types/billing.d-BbSZh1wY.js';
+import { T as TotalumClientOptions, a as TotalumError } from '../_types/errors.d-Cu3q_E_r.js';
+export { i as isTotalumError } from '../_types/errors.d-Cu3q_E_r.js';
+
+/** A webhook refusal (plan 05 §7.2): the codes never travel, the app answers 400. */
+declare class TotalumWebhookError extends TotalumError {
+    name: string;
+    readonly errorCode: 'WEBHOOK_SECRET_MISSING' | 'WEBHOOK_SIGNATURE_INVALID' | 'WEBHOOK_TIMESTAMP_EXPIRED';
+    constructor(errorCode: TotalumWebhookError['errorCode'], message: string);
+}
+/**
+ * `totalum.webhooks.verify` (plan 04 §5.13): checks `Totalum-Signature: t=…,v1=…` — HMAC-SHA256 keyed with the
+ * endpoint's secret string over `${t}.${rawBody}` — within ±300 s, and returns the parsed event. Pass the body exactly
+ * as received (`await request.text()`). `secret` defaults to `TOTALUM_WEBHOOK_SECRET`.
+ *
+ * @example
+ * const event = await verifyWebhook(await request.text(), request.headers);
+ */
+declare function verifyWebhook(rawBody: string, headers: Headers | Record<string, string | undefined>, secret?: string | undefined, now?: number): Promise<WebhookEvent>;
+/**
+ * `totalum.webhooks` (plan 04 §5.13) over SDK-API `/v1/webhooks` (a key with scope `*`): where the project receives its
+ * signed events (payments, e-mail, browser programs, `project.credits.exhausted`) and the secret they are signed with.
+ */
+declare function totalumWebhooks(options?: TotalumClientOptions): {
+    /** Same as `verifyWebhook`: checks `Totalum-Signature` and returns the parsed event. */
+    verify: typeof verifyWebhook;
+    /** The endpoint and the first characters of its secret (the secret itself is shown only by `rotateSecret`). */
+    get: () => Promise<{
+        url: string | null;
+        enabled: boolean;
+        secretPrefix: string | null;
+    }>;
+    /** Sets the `https://` URL the project's events are delivered to. */
+    setUrl: (url: string) => Promise<{
+        url: string | null;
+        enabled: boolean;
+        secretPrefix: string | null;
+    }>;
+    /** A new signing secret, shown once; the old one keeps co-signing for 24 h. Store it as `TOTALUM_WEBHOOK_SECRET`. */
+    rotateSecret: () => Promise<{
+        secret: string;
+    }>;
+};
+type TotalumWebhooks = ReturnType<typeof totalumWebhooks>;
+
+export { TotalumClientOptions, TotalumError, TotalumWebhookError, WebhookEvent, totalumWebhooks, verifyWebhook };
+export type { TotalumWebhooks };

package/dist/webhooks/index.js

@@ -0,0 +1,61 @@
+import { TotalumError } from '../errors.js';
+import { jsonClient, readEnv } from '../http.js';
+export { TotalumError, isTotalumError } from '../errors.js';
+/** Literals type-locked to contracts, so the published package imports nothing at runtime (plan 05 §1). */
+const SIGNATURE_HEADER = 'Totalum-Signature';
+const TOLERANCE_SECONDS = 300;
+/** A webhook refusal (plan 05 §7.2): the codes never travel, the app answers 400. */
+export class TotalumWebhookError extends TotalumError {
+    name = 'TotalumWebhookError';
+    constructor(errorCode, message) {
+        super(errorCode, message, errorCode === 'WEBHOOK_SECRET_MISSING' ? 500 : 401);
+    }
+}
+const enc = new TextEncoder();
+/**
+ * `totalum.webhooks.verify` (plan 04 §5.13): checks `Totalum-Signature: t=…,v1=…` — HMAC-SHA256 keyed with the
+ * endpoint's secret string over `${t}.${rawBody}` — within ±300 s, and returns the parsed event. Pass the body exactly
+ * as received (`await request.text()`). `secret` defaults to `TOTALUM_WEBHOOK_SECRET`.
+ *
+ * @example
+ * const event = await verifyWebhook(await request.text(), request.headers);
+ */
+export async function verifyWebhook(rawBody, headers, secret = readEnv('TOTALUM_WEBHOOK_SECRET'), now = Date.now()) {
+    if (!secret)
+        throw new TotalumWebhookError('WEBHOOK_SECRET_MISSING', 'Set TOTALUM_WEBHOOK_SECRET or pass the secret.');
+    const name = SIGNATURE_HEADER;
+    const header = headers instanceof Headers ? headers.get(name) : (headers[name] ?? headers[name.toLowerCase()] ?? null);
+    const parts = (header ?? '').split(',').map((p) => p.split('=', 2));
+    const t = Number(parts.find(([k]) => k === 't')?.[1]);
+    if (!Number.isInteger(t))
+        throw new TotalumWebhookError('WEBHOOK_SIGNATURE_INVALID', 'Missing Totalum-Signature');
+    if (Math.abs(now / 1000 - t) > TOLERANCE_SECONDS)
+        throw new TotalumWebhookError('WEBHOOK_TIMESTAMP_EXPIRED', 'Signature timestamp outside ±300 s');
+    const key = await crypto.subtle.importKey('raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+    const payload = enc.encode(`${String(t)}.${rawBody}`);
+    for (const [k, v] of parts) {
+        if (k !== 'v1' || !v || !/^[0-9a-f]{64}$/.test(v))
+            continue;
+        const sig = new Uint8Array(v.match(/../g)?.map((h) => parseInt(h, 16)) ?? []);
+        if (await crypto.subtle.verify('HMAC', key, sig, payload))
+            return JSON.parse(rawBody);
+    }
+    throw new TotalumWebhookError('WEBHOOK_SIGNATURE_INVALID', 'Totalum-Signature does not match');
+}
+/**
+ * `totalum.webhooks` (plan 04 §5.13) over SDK-API `/v1/webhooks` (a key with scope `*`): where the project receives its
+ * signed events (payments, e-mail, browser programs, `project.credits.exhausted`) and the secret they are signed with.
+ */
+export function totalumWebhooks(options = {}) {
+    const call = jsonClient(options);
+    return {
+        /** Same as `verifyWebhook`: checks `Totalum-Signature` and returns the parsed event. */
+        verify: verifyWebhook,
+        /** The endpoint and the first characters of its secret (the secret itself is shown only by `rotateSecret`). */
+        get: () => call('GET', '/v1/webhooks'),
+        /** Sets the `https://` URL the project's events are delivered to. */
+        setUrl: (url) => call('PUT', '/v1/webhooks', { url }),
+        /** A new signing secret, shown once; the old one keeps co-signing for 24 h. Store it as `TOTALUM_WEBHOOK_SECRET`. */
+        rotateSecret: () => call('POST', '/v1/webhooks/rotate-secret'),
+    };
+}

package/package.json

@@ -0,0 +1,146 @@
+{
+  "name": "totalum-sdk",
+  "version": "0.1.0-dev.10",
+  "description": "The SDK generated Totalum apps import: every integration namespace over SDK-API (totalum-sdk, or one subpath each: /files, /ai, /web, …) and totalum-sdk/d1, the D1 driver",
+  "license": "UNLICENSED",
+  "type": "module",
+  "packageManager": "pnpm@10.34.5",
+  "engines": {
+    "node": ">=22 <23"
+  },
+  "files": [
+    "dist",
+    "totalum-sdk.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./d1": {
+      "types": "./dist/d1/index.d.ts",
+      "default": "./dist/d1/index.js"
+    },
+    "./files": {
+      "types": "./dist/files/index.d.ts",
+      "default": "./dist/files/index.js"
+    },
+    "./payments": {
+      "types": "./dist/payments/index.d.ts",
+      "default": "./dist/payments/index.js"
+    },
+    "./webhooks": {
+      "types": "./dist/webhooks/index.d.ts",
+      "default": "./dist/webhooks/index.js"
+    },
+    "./web": {
+      "types": "./dist/web/index.d.ts",
+      "default": "./dist/web/index.js"
+    },
+    "./pdf": {
+      "types": "./dist/pdf/index.d.ts",
+      "default": "./dist/pdf/index.js"
+    },
+    "./scan": {
+      "types": "./dist/scan/index.d.ts",
+      "default": "./dist/scan/index.js"
+    },
+    "./speech": {
+      "types": "./dist/speech/index.d.ts",
+      "default": "./dist/speech/index.js"
+    },
+    "./ai": {
+      "types": "./dist/ai/index.d.ts",
+      "default": "./dist/ai/index.js"
+    },
+    "./email": {
+      "types": "./dist/email/index.d.ts",
+      "default": "./dist/email/index.js"
+    },
+    "./cron": {
+      "types": "./dist/cron/index.d.ts",
+      "default": "./dist/cron/index.js"
+    },
+    "./seo": {
+      "types": "./dist/seo/index.d.ts",
+      "default": "./dist/seo/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "default": "./dist/browser/index.js"
+    },
+    "./realtime": {
+      "types": "./dist/realtime/index.d.ts",
+      "default": "./dist/realtime/index.js"
+    },
+    "./logs": {
+      "types": "./dist/logs/index.d.ts",
+      "default": "./dist/logs/index.js"
+    },
+    "./analytics": {
+      "types": "./dist/analytics/index.d.ts",
+      "default": "./dist/analytics/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "rm -rf dist build && tsc -p tsconfig.build.json && rollup -c scripts/dts.config.mjs --silent",
+    "size": "node scripts/size.mjs",
+    "docs": "node scripts/gen-docs.mjs",
+    "docs:check": "node scripts/gen-docs.mjs --check",
+    "release:dev": "rm -rf dist && pnpm build && npm publish --tag dev",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:node": "vitest run --project node",
+    "test:workerd": "vitest run --project workerd",
+    "test:dev": "vitest run --config test/dev/vitest.config.ts",
+    "prepare": "lefthook install || echo \"lefthook: hooks not installed (git >= 2.31 required)\"",
+    "types:check": "node scripts/check-types.mjs"
+  },
+  "peerDependencies": {
+    "@libsql/client": "0.18.0",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "@libsql/client": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "0.22.0",
+    "@cloudflare/workers-types": "5.20260922.1",
+    "@commitlint/cli": "21.2.3",
+    "@commitlint/config-conventional": "21.2.3",
+    "@eslint/js": "9.39.5",
+    "@libsql/client": "0.18.0",
+    "@speed-paradigm/totalum-contracts": "link:../totalum-contracts",
+    "@types/node": "22.20.4",
+    "@types/react": "19.3.0",
+    "drizzle-orm": "0.45.3",
+    "esbuild": "0.28.1",
+    "eslint": "9.39.5",
+    "eslint-plugin-import-x": "4.17.1",
+    "eslint-plugin-no-only-tests": "3.4.0",
+    "lefthook": "2.1.14",
+    "miniflare": "5.20260921.0-alpha",
+    "prettier": "3.9.8",
+    "react": "19.3.0",
+    "rollup": "4.63.4",
+    "rollup-plugin-dts": "6.5.1",
+    "totalum-sdk-api": "link:../totalum-sdk-api",
+    "typescript": "5.8.3",
+    "typescript-eslint": "8.70.1",
+    "vitest": "4.1.11",
+    "wrangler": "4.136.2"
+  },
+  "prettier": "@speed-paradigm/totalum-contracts/configs/prettier.json"
+}