@better-webhook/cli 3.8.0 → 3.10.0

package/dist/core/signature.js

@@ -0,0 +1,224 @@
+import { Buffer } from "node:buffer";
+import { createHmac } from "crypto";
+export function generateStripeSignature(payload, secret, timestamp) {
+    const ts = timestamp || Math.floor(Date.now() / 1000);
+    const signedPayload = `${ts}.${payload}`;
+    const signature = createHmac("sha256", secret)
+        .update(signedPayload)
+        .digest("hex");
+    return {
+        header: "Stripe-Signature",
+        value: `t=${ts},v1=${signature}`,
+    };
+}
+export function generateGitHubSignature(payload, secret) {
+    const signature = createHmac("sha256", secret).update(payload).digest("hex");
+    return {
+        header: "X-Hub-Signature-256",
+        value: `sha256=${signature}`,
+    };
+}
+export function generateShopifySignature(payload, secret) {
+    const signature = createHmac("sha256", secret)
+        .update(payload)
+        .digest("base64");
+    return {
+        header: "X-Shopify-Hmac-SHA256",
+        value: signature,
+    };
+}
+export function generateTwilioSignature(payload, secret, url) {
+    const signatureInput = url + payload;
+    const signature = createHmac("sha1", secret)
+        .update(signatureInput)
+        .digest("base64");
+    return {
+        header: "X-Twilio-Signature",
+        value: signature,
+    };
+}
+export function generateSlackSignature(payload, secret, timestamp) {
+    const ts = timestamp || Math.floor(Date.now() / 1000);
+    const signatureBaseString = `v0:${ts}:${payload}`;
+    const signature = createHmac("sha256", secret)
+        .update(signatureBaseString)
+        .digest("hex");
+    return {
+        header: "X-Slack-Signature",
+        value: `v0=${signature}`,
+    };
+}
+export function generateLinearSignature(payload, secret) {
+    const signature = createHmac("sha256", secret).update(payload).digest("hex");
+    return {
+        header: "Linear-Signature",
+        value: signature,
+    };
+}
+export function generateClerkSignature(payload, secret, timestamp, webhookId) {
+    const ts = timestamp || Math.floor(Date.now() / 1000);
+    const msgId = webhookId || `msg_${Date.now()}`;
+    const signedPayload = `${msgId}.${ts}.${payload}`;
+    const signature = createHmac("sha256", secret)
+        .update(signedPayload)
+        .digest("base64");
+    return {
+        header: "Svix-Signature",
+        value: `v1,${signature}`,
+    };
+}
+export function generateSendGridSignature(payload, secret, timestamp) {
+    const ts = timestamp || Math.floor(Date.now() / 1000);
+    const signedPayload = `${ts}${payload}`;
+    const signature = createHmac("sha256", secret)
+        .update(signedPayload)
+        .digest("base64");
+    return {
+        header: "X-Twilio-Email-Event-Webhook-Signature",
+        value: signature,
+    };
+}
+export function generateRagieSignature(payload, secret) {
+    const signature = createHmac("sha256", secret).update(payload).digest("hex");
+    return {
+        header: "X-Signature",
+        value: signature,
+    };
+}
+export function generateRecallSignature(payload, secret, timestamp, webhookId) {
+    if (!secret.startsWith("whsec_")) {
+        throw new Error("Recall signature generation requires a secret with the whsec_ prefix");
+    }
+    const ts = timestamp ?? Math.floor(Date.now() / 1000);
+    const msgId = webhookId ?? `msg_${Date.now()}`;
+    const key = Buffer.from(secret.slice("whsec_".length), "base64");
+    if (key.length === 0) {
+        throw new Error("Recall signing secret is invalid");
+    }
+    const signedPayload = `${msgId}.${ts}.${payload}`;
+    const signature = createHmac("sha256", key)
+        .update(signedPayload)
+        .digest("base64");
+    return {
+        header: "Webhook-Signature",
+        value: `v1,${signature}`,
+    };
+}
+export function generateSignature(provider, payload, secret, options) {
+    const timestamp = options?.timestamp;
+    switch (provider) {
+        case "stripe":
+            return generateStripeSignature(payload, secret, timestamp);
+        case "github":
+            return generateGitHubSignature(payload, secret);
+        case "shopify":
+            return generateShopifySignature(payload, secret);
+        case "twilio":
+            if (!options?.url) {
+                throw new Error("Twilio signature requires URL");
+            }
+            return generateTwilioSignature(payload, secret, options.url);
+        case "slack":
+            return generateSlackSignature(payload, secret, timestamp);
+        case "linear":
+            return generateLinearSignature(payload, secret);
+        case "clerk":
+            return generateClerkSignature(payload, secret, timestamp, options?.webhookId);
+        case "sendgrid":
+            return generateSendGridSignature(payload, secret, timestamp);
+        case "ragie":
+            return generateRagieSignature(payload, secret);
+        case "recall":
+            return generateRecallSignature(payload, secret, timestamp, options?.webhookId);
+        case "discord":
+        case "custom":
+        default:
+            return null;
+    }
+}
+export function getProviderHeaders(provider, options) {
+    const headers = [];
+    const timestamp = options?.timestamp || Math.floor(Date.now() / 1000);
+    switch (provider) {
+        case "stripe":
+            headers.push({ key: "Content-Type", value: "application/json" }, {
+                key: "User-Agent",
+                value: "Stripe/1.0 (+https://stripe.com/docs/webhooks)",
+            });
+            break;
+        case "github":
+            headers.push({ key: "Content-Type", value: "application/json" }, { key: "User-Agent", value: "GitHub-Hookshot/better-webhook" }, { key: "X-GitHub-Event", value: options?.event || "push" }, {
+                key: "X-GitHub-Delivery",
+                value: options?.webhookId || generateDeliveryId(),
+            });
+            break;
+        case "shopify":
+            headers.push({ key: "Content-Type", value: "application/json" }, { key: "X-Shopify-Topic", value: options?.event || "orders/create" }, { key: "X-Shopify-Shop-Domain", value: "example.myshopify.com" }, { key: "X-Shopify-API-Version", value: "2024-01" });
+            break;
+        case "slack":
+            headers.push({ key: "Content-Type", value: "application/json" }, { key: "X-Slack-Request-Timestamp", value: String(timestamp) });
+            break;
+        case "clerk":
+            headers.push({ key: "Content-Type", value: "application/json" }, { key: "Svix-Id", value: options?.webhookId || `msg_${Date.now()}` }, { key: "Svix-Timestamp", value: String(timestamp) });
+            break;
+        case "sendgrid":
+            headers.push({ key: "Content-Type", value: "application/json" }, {
+                key: "X-Twilio-Email-Event-Webhook-Timestamp",
+                value: String(timestamp),
+            });
+            break;
+        case "twilio":
+            headers.push({
+                key: "Content-Type",
+                value: "application/x-www-form-urlencoded",
+            });
+            break;
+        case "linear":
+            headers.push({ key: "Content-Type", value: "application/json" }, {
+                key: "Linear-Delivery",
+                value: options?.webhookId || generateDeliveryId(),
+            });
+            break;
+        case "discord":
+            headers.push({ key: "Content-Type", value: "application/json" }, { key: "User-Agent", value: "Discord-Webhook/1.0" });
+            break;
+        case "ragie":
+            headers.push({ key: "Content-Type", value: "application/json" });
+            break;
+        case "recall":
+            headers.push({ key: "Content-Type", value: "application/json" }, { key: "Webhook-Id", value: options?.webhookId || `msg_${Date.now()}` }, { key: "Webhook-Timestamp", value: String(timestamp) });
+            break;
+        default:
+            headers.push({ key: "Content-Type", value: "application/json" });
+    }
+    return headers;
+}
+function generateDeliveryId() {
+    const chars = "0123456789abcdef";
+    let id = "";
+    for (let i = 0; i < 36; i++) {
+        if (i === 8 || i === 13 || i === 18 || i === 23) {
+            id += "-";
+        }
+        else {
+            id += chars[Math.floor(Math.random() * chars.length)];
+        }
+    }
+    return id;
+}
+export function verifySignature(provider, payload, signature, secret, options) {
+    const generated = generateSignature(provider, payload, secret, options);
+    if (!generated) {
+        return false;
+    }
+    const a = generated.value;
+    const b = signature;
+    if (a.length !== b.length) {
+        return false;
+    }
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+}

package/dist/core/signature.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/signature.test.js

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { generateRecallSignature, generateSignature, getProviderHeaders, } from "./signature.js";
+describe("signature helpers", () => {
+    describe("generateRecallSignature", () => {
+        it("generates a v1 signature for Recall payloads", () => {
+            const payload = '{"event":"transcript.data"}';
+            const timestamp = 1731705121;
+            const webhookId = "msg_test_123";
+            const secret = "whsec_dGVzdC1yZWNhbGwtc2VjcmV0";
+            const signature = generateRecallSignature(payload, secret, timestamp, webhookId);
+            expect(signature.header).toBe("Webhook-Signature");
+            expect(signature.value).toBe("v1,/Tpb01gdtwsQOKZ92HQ+9qzHEHG5ZxDXmPhaxPG4yFs=");
+        });
+        it("throws when secret does not use whsec_ prefix", () => {
+            expect(() => generateRecallSignature('{"event":"participant_events.join"}', "invalid-secret")).toThrow("Recall signature generation requires a secret with the whsec_ prefix");
+        });
+    });
+    describe("generateSignature", () => {
+        it("generates Recall signature with provider dispatch", () => {
+            const generated = generateSignature("recall", '{"event":"bot.done"}', "whsec_dGVzdC1yZWNhbGwtc2VjcmV0", { timestamp: 1731705121, webhookId: "msg_test_456" });
+            expect(generated?.header).toBe("Webhook-Signature");
+            expect(generated?.value).toBe("v1,1S4uDLnwC3qN9n7rIcbvZeQpikXxcznCf/DzNCSEzXA=");
+        });
+    });
+    describe("getProviderHeaders", () => {
+        it("returns Recall webhook id and timestamp headers", () => {
+            const headers = getProviderHeaders("recall", {
+                timestamp: 1731705121,
+                webhookId: "msg_test_789",
+            });
+            expect(headers).toEqual(expect.arrayContaining([
+                { key: "Content-Type", value: "application/json" },
+                { key: "Webhook-Id", value: "msg_test_789" },
+                { key: "Webhook-Timestamp", value: "1731705121" },
+            ]));
+        });
+    });
+});

package/dist/core/template-manager.d.ts

@@ -0,0 +1,33 @@
+import { type TemplatesIndex, type WebhookTemplate, type LocalTemplate, type RemoteTemplate, type SaveAsTemplateResult } from "../types/index.js";
+export declare class TemplateManager {
+    private baseDir;
+    private templatesDir;
+    private cacheFile;
+    private indexCache;
+    constructor(baseDir?: string);
+    getTemplatesDir(): string;
+    fetchRemoteIndex(forceRefresh?: boolean): Promise<TemplatesIndex>;
+    listRemoteTemplates(options?: {
+        forceRefresh?: boolean;
+    }): Promise<RemoteTemplate[]>;
+    downloadTemplate(templateId: string): Promise<LocalTemplate>;
+    listLocalTemplates(): LocalTemplate[];
+    getLocalTemplate(templateId: string): LocalTemplate | null;
+    deleteLocalTemplate(templateId: string): boolean;
+    searchTemplates(query: string): Promise<{
+        remote: RemoteTemplate[];
+        local: LocalTemplate[];
+    }>;
+    clearCache(): void;
+    deleteAllLocalTemplates(): number;
+    templateExists(templateId: string): boolean;
+    private generateTemplateId;
+    saveUserTemplate(template: WebhookTemplate, options?: {
+        id?: string;
+        name?: string;
+        event?: string;
+        description?: string;
+        overwrite?: boolean;
+    }): SaveAsTemplateResult;
+}
+export declare function getTemplateManager(baseDir?: string): TemplateManager;

package/dist/core/template-manager.js

@@ -0,0 +1,313 @@
+import { request } from "undici";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmdirSync, unlinkSync, writeFileSync, } from "fs";
+import { join, basename } from "path";
+import { homedir } from "os";
+import { TemplatesIndexSchema, WebhookTemplateSchema, } from "../types/index.js";
+const GITHUB_RAW_BASE = "https://raw.githubusercontent.com/endalk200/better-webhook/main";
+const TEMPLATES_INDEX_URL = `${GITHUB_RAW_BASE}/templates/templates.json`;
+const TEMPLATE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/i;
+function isValidTemplateId(id) {
+    if (!id || id.length > 128)
+        return false;
+    if (id.includes("/") || id.includes("\\") || id.includes(".."))
+        return false;
+    return TEMPLATE_ID_PATTERN.test(id);
+}
+export class TemplateManager {
+    baseDir;
+    templatesDir;
+    cacheFile;
+    indexCache = null;
+    constructor(baseDir) {
+        this.baseDir = baseDir || join(homedir(), ".better-webhook");
+        this.templatesDir = join(this.baseDir, "templates");
+        this.cacheFile = join(this.baseDir, "templates-cache.json");
+        if (!existsSync(this.baseDir)) {
+            mkdirSync(this.baseDir, { recursive: true });
+        }
+        if (!existsSync(this.templatesDir)) {
+            mkdirSync(this.templatesDir, { recursive: true });
+        }
+    }
+    getTemplatesDir() {
+        return this.templatesDir;
+    }
+    async fetchRemoteIndex(forceRefresh = false) {
+        if (!forceRefresh && this.indexCache) {
+            return this.indexCache;
+        }
+        if (!forceRefresh && existsSync(this.cacheFile)) {
+            try {
+                const cached = JSON.parse(readFileSync(this.cacheFile, "utf-8"));
+                const cacheAge = Date.now() - (cached.cachedAt || 0);
+                if (cacheAge < 3600000) {
+                    this.indexCache = cached.index;
+                    return cached.index;
+                }
+            }
+            catch {
+            }
+        }
+        try {
+            const { statusCode, body } = await request(TEMPLATES_INDEX_URL);
+            if (statusCode !== 200) {
+                throw new Error(`HTTP ${statusCode}`);
+            }
+            const text = await body.text();
+            const json = JSON.parse(text);
+            const index = TemplatesIndexSchema.parse(json);
+            this.indexCache = index;
+            writeFileSync(this.cacheFile, JSON.stringify({ index, cachedAt: Date.now() }, null, 2));
+            return index;
+        }
+        catch (error) {
+            if (existsSync(this.cacheFile)) {
+                try {
+                    const cached = JSON.parse(readFileSync(this.cacheFile, "utf-8"));
+                    if (cached.index) {
+                        this.indexCache = cached.index;
+                        return cached.index;
+                    }
+                }
+                catch {
+                }
+            }
+            throw new Error(`Failed to fetch templates index: ${error.message}`);
+        }
+    }
+    async listRemoteTemplates(options) {
+        const index = await this.fetchRemoteIndex(!!options?.forceRefresh);
+        const localIds = new Set(this.listLocalTemplates().map((t) => t.id));
+        return index.templates.map((metadata) => ({
+            metadata,
+            isDownloaded: localIds.has(metadata.id),
+        }));
+    }
+    async downloadTemplate(templateId) {
+        const index = await this.fetchRemoteIndex();
+        const templateMeta = index.templates.find((t) => t.id === templateId);
+        if (!templateMeta) {
+            throw new Error(`Template not found: ${templateId}`);
+        }
+        const templateUrl = `${GITHUB_RAW_BASE}/templates/${templateMeta.file}`;
+        try {
+            const { statusCode, body } = await request(templateUrl);
+            if (statusCode !== 200) {
+                throw new Error(`HTTP ${statusCode}`);
+            }
+            const text = await body.text();
+            const json = JSON.parse(text);
+            const template = WebhookTemplateSchema.parse(json);
+            const providerDir = join(this.templatesDir, templateMeta.provider);
+            if (!existsSync(providerDir)) {
+                mkdirSync(providerDir, { recursive: true });
+            }
+            const fileName = `${templateId}.json`;
+            const filePath = join(providerDir, fileName);
+            const localTemplate = {
+                id: templateId,
+                metadata: templateMeta,
+                template,
+                downloadedAt: new Date().toISOString(),
+                filePath,
+            };
+            const saveData = {
+                ...template,
+                _metadata: {
+                    ...templateMeta,
+                    downloadedAt: localTemplate.downloadedAt,
+                },
+            };
+            writeFileSync(filePath, JSON.stringify(saveData, null, 2));
+            return localTemplate;
+        }
+        catch (error) {
+            throw new Error(`Failed to download template ${templateId}: ${error.message}`);
+        }
+    }
+    listLocalTemplates() {
+        const templates = [];
+        if (!existsSync(this.templatesDir)) {
+            return templates;
+        }
+        const scanDir = (dir) => {
+            const entries = readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    scanDir(fullPath);
+                }
+                else if (entry.isFile() && entry.name.endsWith(".json")) {
+                    try {
+                        const content = JSON.parse(readFileSync(fullPath, "utf-8"));
+                        const metadata = content._metadata;
+                        if (metadata) {
+                            const { _metadata, ...templateData } = content;
+                            templates.push({
+                                id: metadata.id,
+                                metadata,
+                                template: templateData,
+                                downloadedAt: metadata.downloadedAt || new Date().toISOString(),
+                                filePath: fullPath,
+                            });
+                        }
+                        else {
+                            const id = basename(entry.name, ".json");
+                            templates.push({
+                                id,
+                                metadata: {
+                                    id,
+                                    name: id,
+                                    provider: "custom",
+                                    event: "unknown",
+                                    file: entry.name,
+                                },
+                                template: content,
+                                downloadedAt: new Date().toISOString(),
+                                filePath: fullPath,
+                            });
+                        }
+                    }
+                    catch {
+                    }
+                }
+            }
+        };
+        scanDir(this.templatesDir);
+        return templates;
+    }
+    getLocalTemplate(templateId) {
+        const templates = this.listLocalTemplates();
+        return templates.find((t) => t.id === templateId) || null;
+    }
+    deleteLocalTemplate(templateId) {
+        const template = this.getLocalTemplate(templateId);
+        if (!template) {
+            return false;
+        }
+        try {
+            unlinkSync(template.filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async searchTemplates(query) {
+        const queryLower = query.toLowerCase();
+        const remote = await this.listRemoteTemplates();
+        const local = this.listLocalTemplates();
+        const matchesMeta = (meta) => {
+            return (meta.id.toLowerCase().includes(queryLower) ||
+                meta.name.toLowerCase().includes(queryLower) ||
+                meta.provider.toLowerCase().includes(queryLower) ||
+                meta.event.toLowerCase().includes(queryLower) ||
+                (meta.description?.toLowerCase().includes(queryLower) ?? false));
+        };
+        return {
+            remote: remote.filter((t) => matchesMeta(t.metadata)),
+            local: local.filter((t) => matchesMeta(t.metadata)),
+        };
+    }
+    clearCache() {
+        this.indexCache = null;
+        if (existsSync(this.cacheFile)) {
+            unlinkSync(this.cacheFile);
+        }
+    }
+    deleteAllLocalTemplates() {
+        const templates = this.listLocalTemplates();
+        let deleted = 0;
+        for (const template of templates) {
+            try {
+                unlinkSync(template.filePath);
+                deleted++;
+            }
+            catch {
+            }
+        }
+        if (existsSync(this.templatesDir)) {
+            const entries = readdirSync(this.templatesDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    const dirPath = join(this.templatesDir, entry.name);
+                    try {
+                        const contents = readdirSync(dirPath);
+                        if (contents.length === 0) {
+                            rmdirSync(dirPath);
+                        }
+                    }
+                    catch {
+                    }
+                }
+            }
+        }
+        return deleted;
+    }
+    templateExists(templateId) {
+        return this.getLocalTemplate(templateId) !== null;
+    }
+    generateTemplateId(provider, event) {
+        const providerPart = provider || "custom";
+        const eventPart = event || "webhook";
+        const baseId = `${providerPart}-${eventPart}`
+            .toLowerCase()
+            .replace(/\s+/g, "-");
+        if (!this.templateExists(baseId)) {
+            return baseId;
+        }
+        let counter = 1;
+        while (this.templateExists(`${baseId}-${counter}`)) {
+            counter++;
+        }
+        return `${baseId}-${counter}`;
+    }
+    saveUserTemplate(template, options = {}) {
+        const provider = template.provider || "custom";
+        const event = options.event || template.event || "webhook";
+        const templateId = options.id || this.generateTemplateId(provider, event);
+        const name = options.name || templateId;
+        const description = options.description || template.description;
+        if (!isValidTemplateId(templateId)) {
+            throw new Error(`Invalid template ID "${templateId}". IDs must start with alphanumeric, contain only letters, numbers, dots, underscores, and hyphens.`);
+        }
+        if (!options.overwrite && this.templateExists(templateId)) {
+            throw new Error(`Template with ID "${templateId}" already exists. Use --overwrite to replace it.`);
+        }
+        const providerDir = join(this.templatesDir, provider);
+        if (!existsSync(providerDir)) {
+            mkdirSync(providerDir, { recursive: true });
+        }
+        const metadata = {
+            id: templateId,
+            name,
+            provider,
+            event,
+            file: `${provider}/${templateId}.json`,
+            description,
+            source: "capture",
+            createdAt: new Date().toISOString(),
+        };
+        const saveData = {
+            ...template,
+            provider,
+            event,
+            description,
+            _metadata: metadata,
+        };
+        const filePath = join(providerDir, `${templateId}.json`);
+        writeFileSync(filePath, JSON.stringify(saveData, null, 2));
+        return {
+            id: templateId,
+            filePath,
+            template: saveData,
+        };
+    }
+}
+let instance = null;
+export function getTemplateManager(baseDir) {
+    if (!instance) {
+        instance = new TemplateManager(baseDir);
+    }
+    return instance;
+}

package/dist/core/template-manager.test.d.ts

@@ -0,0 +1 @@
+export {};