@prismer/sdk 1.8.2 → 1.9.0

package/dist/webhook.d.mts

@@ -0,0 +1,114 @@
+/**
+ * Prismer IM Webhook Handler
+ *
+ * Receives, verifies, and parses webhook payloads from Prismer IM server.
+ * Provides framework adapters for Express and Hono.
+ *
+ * @example
+ * ```typescript
+ * import { PrismerWebhook } from '@prismer/sdk/webhook';
+ *
+ * const webhook = new PrismerWebhook({
+ *   secret: process.env.WEBHOOK_SECRET!,
+ *   onMessage: async (payload) => {
+ *     console.log(`[${payload.sender.displayName}]: ${payload.message.content}`);
+ *     return { content: 'Got it!' };
+ *   },
+ * });
+ *
+ * // Express
+ * app.post('/webhook', webhook.express());
+ *
+ * // Hono
+ * app.post('/webhook', webhook.hono());
+ *
+ * // Raw fetch/Request API
+ * const response = await webhook.handle(request);
+ * ```
+ */
+/** Prismer IM webhook payload (POST to agent endpoint) */
+interface WebhookPayload {
+    source: 'prismer_im';
+    event: 'message.new';
+    timestamp: number;
+    message: WebhookMessage;
+    sender: WebhookSender;
+    conversation: WebhookConversation;
+}
+interface WebhookMessage {
+    id: string;
+    type: string;
+    content: string;
+    senderId: string;
+    conversationId: string;
+    parentId: string | null;
+    metadata: Record<string, any>;
+    createdAt: string;
+}
+interface WebhookSender {
+    id: string;
+    username: string;
+    displayName: string;
+    role: 'human' | 'agent';
+}
+interface WebhookConversation {
+    id: string;
+    type: 'direct' | 'group';
+    title: string | null;
+}
+interface WebhookReply {
+    content: string;
+    type?: 'text' | 'markdown' | 'code';
+}
+interface WebhookHandlerOptions {
+    /** HMAC-SHA256 secret for verifying webhook signatures */
+    secret: string;
+    /** Called when a verified webhook payload is received */
+    onMessage: (payload: WebhookPayload) => Promise<WebhookReply | void>;
+}
+/**
+ * Verify a Prismer IM webhook signature using HMAC-SHA256.
+ * Uses timing-safe comparison to prevent timing attacks.
+ */
+declare function verifyWebhookSignature(body: string, signature: string, secret: string): boolean;
+/**
+ * Parse a raw webhook body into a typed WebhookPayload.
+ * Throws if the body is not valid JSON or missing required fields.
+ */
+declare function parseWebhookPayload(body: string): WebhookPayload;
+declare class PrismerWebhook {
+    private readonly secret;
+    private readonly onMessage;
+    constructor(options: WebhookHandlerOptions);
+    /** Verify an HMAC-SHA256 signature */
+    verify(body: string, signature: string): boolean;
+    /** Parse raw body into a typed WebhookPayload */
+    parse(body: string): WebhookPayload;
+    /**
+     * Process a webhook request (verify + parse + call handler).
+     * Works with the standard Web Request/Response API.
+     */
+    handle(request: Request): Promise<Response>;
+    /**
+     * Express middleware adapter.
+     * Expects `express.raw({ type: 'application/json' })` or a raw body parser
+     * so that `req.body` is a Buffer.
+     *
+     * @example
+     * ```typescript
+     * app.post('/webhook', express.raw({ type: 'application/json' }), webhook.express());
+     * ```
+     */
+    express(): (req: any, res: any, next?: any) => void;
+    /**
+     * Hono middleware adapter.
+     *
+     * @example
+     * ```typescript
+     * app.post('/webhook', webhook.hono());
+     * ```
+     */
+    hono(): (c: any) => Promise<any>;
+}
+
+export { PrismerWebhook, type WebhookConversation, type WebhookHandlerOptions, type WebhookMessage, type WebhookPayload, type WebhookReply, type WebhookSender, parseWebhookPayload, verifyWebhookSignature };

package/dist/webhook.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Prismer IM Webhook Handler
+ *
+ * Receives, verifies, and parses webhook payloads from Prismer IM server.
+ * Provides framework adapters for Express and Hono.
+ *
+ * @example
+ * ```typescript
+ * import { PrismerWebhook } from '@prismer/sdk/webhook';
+ *
+ * const webhook = new PrismerWebhook({
+ *   secret: process.env.WEBHOOK_SECRET!,
+ *   onMessage: async (payload) => {
+ *     console.log(`[${payload.sender.displayName}]: ${payload.message.content}`);
+ *     return { content: 'Got it!' };
+ *   },
+ * });
+ *
+ * // Express
+ * app.post('/webhook', webhook.express());
+ *
+ * // Hono
+ * app.post('/webhook', webhook.hono());
+ *
+ * // Raw fetch/Request API
+ * const response = await webhook.handle(request);
+ * ```
+ */
+/** Prismer IM webhook payload (POST to agent endpoint) */
+interface WebhookPayload {
+    source: 'prismer_im';
+    event: 'message.new';
+    timestamp: number;
+    message: WebhookMessage;
+    sender: WebhookSender;
+    conversation: WebhookConversation;
+}
+interface WebhookMessage {
+    id: string;
+    type: string;
+    content: string;
+    senderId: string;
+    conversationId: string;
+    parentId: string | null;
+    metadata: Record<string, any>;
+    createdAt: string;
+}
+interface WebhookSender {
+    id: string;
+    username: string;
+    displayName: string;
+    role: 'human' | 'agent';
+}
+interface WebhookConversation {
+    id: string;
+    type: 'direct' | 'group';
+    title: string | null;
+}
+interface WebhookReply {
+    content: string;
+    type?: 'text' | 'markdown' | 'code';
+}
+interface WebhookHandlerOptions {
+    /** HMAC-SHA256 secret for verifying webhook signatures */
+    secret: string;
+    /** Called when a verified webhook payload is received */
+    onMessage: (payload: WebhookPayload) => Promise<WebhookReply | void>;
+}
+/**
+ * Verify a Prismer IM webhook signature using HMAC-SHA256.
+ * Uses timing-safe comparison to prevent timing attacks.
+ */
+declare function verifyWebhookSignature(body: string, signature: string, secret: string): boolean;
+/**
+ * Parse a raw webhook body into a typed WebhookPayload.
+ * Throws if the body is not valid JSON or missing required fields.
+ */
+declare function parseWebhookPayload(body: string): WebhookPayload;
+declare class PrismerWebhook {
+    private readonly secret;
+    private readonly onMessage;
+    constructor(options: WebhookHandlerOptions);
+    /** Verify an HMAC-SHA256 signature */
+    verify(body: string, signature: string): boolean;
+    /** Parse raw body into a typed WebhookPayload */
+    parse(body: string): WebhookPayload;
+    /**
+     * Process a webhook request (verify + parse + call handler).
+     * Works with the standard Web Request/Response API.
+     */
+    handle(request: Request): Promise<Response>;
+    /**
+     * Express middleware adapter.
+     * Expects `express.raw({ type: 'application/json' })` or a raw body parser
+     * so that `req.body` is a Buffer.
+     *
+     * @example
+     * ```typescript
+     * app.post('/webhook', express.raw({ type: 'application/json' }), webhook.express());
+     * ```
+     */
+    express(): (req: any, res: any, next?: any) => void;
+    /**
+     * Hono middleware adapter.
+     *
+     * @example
+     * ```typescript
+     * app.post('/webhook', webhook.hono());
+     * ```
+     */
+    hono(): (c: any) => Promise<any>;
+}
+
+export { PrismerWebhook, type WebhookConversation, type WebhookHandlerOptions, type WebhookMessage, type WebhookPayload, type WebhookReply, type WebhookSender, parseWebhookPayload, verifyWebhookSignature };

package/dist/webhook.js

@@ -0,0 +1,200 @@
+"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);
+
+// src/webhook.ts
+var webhook_exports = {};
+__export(webhook_exports, {
+  PrismerWebhook: () => PrismerWebhook,
+  parseWebhookPayload: () => parseWebhookPayload,
+  verifyWebhookSignature: () => verifyWebhookSignature
+});
+module.exports = __toCommonJS(webhook_exports);
+var import_node_crypto = require("crypto");
+function verifyWebhookSignature(body, signature, secret) {
+  if (!body || !signature || !secret) return false;
+  const sig = signature.startsWith("sha256=") ? signature.slice(7) : signature;
+  if (!sig) return false;
+  const expected = (0, import_node_crypto.createHmac)("sha256", secret).update(body).digest("hex");
+  if (sig.length !== expected.length) return false;
+  try {
+    return (0, import_node_crypto.timingSafeEqual)(Buffer.from(sig, "hex"), Buffer.from(expected, "hex"));
+  } catch {
+    return false;
+  }
+}
+function parseWebhookPayload(body) {
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    throw new Error("Invalid JSON in webhook body");
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("Webhook body must be a JSON object");
+  }
+  if (parsed.source !== "prismer_im") {
+    throw new Error(`Unknown webhook source: ${parsed.source}`);
+  }
+  if (!parsed.event) {
+    throw new Error("Missing event field in webhook payload");
+  }
+  if (!parsed.message || !parsed.sender || !parsed.conversation) {
+    throw new Error("Missing required fields in webhook payload (message, sender, conversation)");
+  }
+  return parsed;
+}
+var PrismerWebhook = class {
+  constructor(options) {
+    if (!options.secret) {
+      throw new Error("Webhook secret is required");
+    }
+    this.secret = options.secret;
+    this.onMessage = options.onMessage;
+  }
+  /** Verify an HMAC-SHA256 signature */
+  verify(body, signature) {
+    return verifyWebhookSignature(body, signature, this.secret);
+  }
+  /** Parse raw body into a typed WebhookPayload */
+  parse(body) {
+    return parseWebhookPayload(body);
+  }
+  /**
+   * Process a webhook request (verify + parse + call handler).
+   * Works with the standard Web Request/Response API.
+   */
+  async handle(request) {
+    if (request.method !== "POST") {
+      return new Response(JSON.stringify({ error: "Method not allowed" }), {
+        status: 405,
+        headers: { "Content-Type": "application/json" }
+      });
+    }
+    const body = await request.text();
+    const signature = request.headers.get("x-prismer-signature") || "";
+    if (!this.verify(body, signature)) {
+      return new Response(JSON.stringify({ error: "Invalid signature" }), {
+        status: 401,
+        headers: { "Content-Type": "application/json" }
+      });
+    }
+    let payload;
+    try {
+      payload = this.parse(body);
+    } catch (err) {
+      return new Response(
+        JSON.stringify({ error: err instanceof Error ? err.message : "Invalid payload" }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+    try {
+      const reply = await this.onMessage(payload);
+      if (reply) {
+        return new Response(JSON.stringify(reply), {
+          status: 200,
+          headers: { "Content-Type": "application/json" }
+        });
+      }
+      return new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" }
+      });
+    } catch (err) {
+      return new Response(
+        JSON.stringify({ error: err instanceof Error ? err.message : "Handler error" }),
+        { status: 500, headers: { "Content-Type": "application/json" } }
+      );
+    }
+  }
+  /**
+   * Express middleware adapter.
+   * Expects `express.raw({ type: 'application/json' })` or a raw body parser
+   * so that `req.body` is a Buffer.
+   *
+   * @example
+   * ```typescript
+   * app.post('/webhook', express.raw({ type: 'application/json' }), webhook.express());
+   * ```
+   */
+  express() {
+    return async (req, res) => {
+      try {
+        const body = typeof req.body === "string" ? req.body : Buffer.isBuffer(req.body) ? req.body.toString("utf-8") : JSON.stringify(req.body);
+        const signature = req.headers["x-prismer-signature"] || "";
+        if (!this.verify(body, signature)) {
+          res.status(401).json({ error: "Invalid signature" });
+          return;
+        }
+        let payload;
+        try {
+          payload = this.parse(body);
+        } catch (err) {
+          res.status(400).json({ error: err instanceof Error ? err.message : "Invalid payload" });
+          return;
+        }
+        const reply = await this.onMessage(payload);
+        if (reply) {
+          res.status(200).json(reply);
+        } else {
+          res.status(200).json({ ok: true });
+        }
+      } catch (err) {
+        res.status(500).json({ error: err instanceof Error ? err.message : "Handler error" });
+      }
+    };
+  }
+  /**
+   * Hono middleware adapter.
+   *
+   * @example
+   * ```typescript
+   * app.post('/webhook', webhook.hono());
+   * ```
+   */
+  hono() {
+    return async (c) => {
+      const body = await c.req.text();
+      const signature = c.req.header("x-prismer-signature") || "";
+      if (!this.verify(body, signature)) {
+        return c.json({ error: "Invalid signature" }, 401);
+      }
+      let payload;
+      try {
+        payload = this.parse(body);
+      } catch (err) {
+        return c.json({ error: err instanceof Error ? err.message : "Invalid payload" }, 400);
+      }
+      try {
+        const reply = await this.onMessage(payload);
+        if (reply) {
+          return c.json(reply, 200);
+        }
+        return c.json({ ok: true }, 200);
+      } catch (err) {
+        return c.json({ error: err instanceof Error ? err.message : "Handler error" }, 500);
+      }
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PrismerWebhook,
+  parseWebhookPayload,
+  verifyWebhookSignature
+});

package/dist/webhook.mjs

@@ -0,0 +1,175 @@
+import "./chunk-6DZX6EAA.mjs";
+
+// src/webhook.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function verifyWebhookSignature(body, signature, secret) {
+  if (!body || !signature || !secret) return false;
+  const sig = signature.startsWith("sha256=") ? signature.slice(7) : signature;
+  if (!sig) return false;
+  const expected = createHmac("sha256", secret).update(body).digest("hex");
+  if (sig.length !== expected.length) return false;
+  try {
+    return timingSafeEqual(Buffer.from(sig, "hex"), Buffer.from(expected, "hex"));
+  } catch {
+    return false;
+  }
+}
+function parseWebhookPayload(body) {
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    throw new Error("Invalid JSON in webhook body");
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("Webhook body must be a JSON object");
+  }
+  if (parsed.source !== "prismer_im") {
+    throw new Error(`Unknown webhook source: ${parsed.source}`);
+  }
+  if (!parsed.event) {
+    throw new Error("Missing event field in webhook payload");
+  }
+  if (!parsed.message || !parsed.sender || !parsed.conversation) {
+    throw new Error("Missing required fields in webhook payload (message, sender, conversation)");
+  }
+  return parsed;
+}
+var PrismerWebhook = class {
+  constructor(options) {
+    if (!options.secret) {
+      throw new Error("Webhook secret is required");
+    }
+    this.secret = options.secret;
+    this.onMessage = options.onMessage;
+  }
+  /** Verify an HMAC-SHA256 signature */
+  verify(body, signature) {
+    return verifyWebhookSignature(body, signature, this.secret);
+  }
+  /** Parse raw body into a typed WebhookPayload */
+  parse(body) {
+    return parseWebhookPayload(body);
+  }
+  /**
+   * Process a webhook request (verify + parse + call handler).
+   * Works with the standard Web Request/Response API.
+   */
+  async handle(request) {
+    if (request.method !== "POST") {
+      return new Response(JSON.stringify({ error: "Method not allowed" }), {
+        status: 405,
+        headers: { "Content-Type": "application/json" }
+      });
+    }
+    const body = await request.text();
+    const signature = request.headers.get("x-prismer-signature") || "";
+    if (!this.verify(body, signature)) {
+      return new Response(JSON.stringify({ error: "Invalid signature" }), {
+        status: 401,
+        headers: { "Content-Type": "application/json" }
+      });
+    }
+    let payload;
+    try {
+      payload = this.parse(body);
+    } catch (err) {
+      return new Response(
+        JSON.stringify({ error: err instanceof Error ? err.message : "Invalid payload" }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+    try {
+      const reply = await this.onMessage(payload);
+      if (reply) {
+        return new Response(JSON.stringify(reply), {
+          status: 200,
+          headers: { "Content-Type": "application/json" }
+        });
+      }
+      return new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" }
+      });
+    } catch (err) {
+      return new Response(
+        JSON.stringify({ error: err instanceof Error ? err.message : "Handler error" }),
+        { status: 500, headers: { "Content-Type": "application/json" } }
+      );
+    }
+  }
+  /**
+   * Express middleware adapter.
+   * Expects `express.raw({ type: 'application/json' })` or a raw body parser
+   * so that `req.body` is a Buffer.
+   *
+   * @example
+   * ```typescript
+   * app.post('/webhook', express.raw({ type: 'application/json' }), webhook.express());
+   * ```
+   */
+  express() {
+    return async (req, res) => {
+      try {
+        const body = typeof req.body === "string" ? req.body : Buffer.isBuffer(req.body) ? req.body.toString("utf-8") : JSON.stringify(req.body);
+        const signature = req.headers["x-prismer-signature"] || "";
+        if (!this.verify(body, signature)) {
+          res.status(401).json({ error: "Invalid signature" });
+          return;
+        }
+        let payload;
+        try {
+          payload = this.parse(body);
+        } catch (err) {
+          res.status(400).json({ error: err instanceof Error ? err.message : "Invalid payload" });
+          return;
+        }
+        const reply = await this.onMessage(payload);
+        if (reply) {
+          res.status(200).json(reply);
+        } else {
+          res.status(200).json({ ok: true });
+        }
+      } catch (err) {
+        res.status(500).json({ error: err instanceof Error ? err.message : "Handler error" });
+      }
+    };
+  }
+  /**
+   * Hono middleware adapter.
+   *
+   * @example
+   * ```typescript
+   * app.post('/webhook', webhook.hono());
+   * ```
+   */
+  hono() {
+    return async (c) => {
+      const body = await c.req.text();
+      const signature = c.req.header("x-prismer-signature") || "";
+      if (!this.verify(body, signature)) {
+        return c.json({ error: "Invalid signature" }, 401);
+      }
+      let payload;
+      try {
+        payload = this.parse(body);
+      } catch (err) {
+        return c.json({ error: err instanceof Error ? err.message : "Invalid payload" }, 400);
+      }
+      try {
+        const reply = await this.onMessage(payload);
+        if (reply) {
+          return c.json(reply, 200);
+        }
+        return c.json({ ok: true }, 200);
+      } catch (err) {
+        return c.json({ error: err instanceof Error ? err.message : "Handler error" }, 500);
+      }
+    };
+  }
+};
+export {
+  PrismerWebhook,
+  parseWebhookPayload,
+  verifyWebhookSignature
+};

package/package.json

@@ -1,13 +1,10 @@
 {
   "name": "@prismer/sdk",
-  "version": "1.8.2",
+  "version": "1.9.0",
   "description": "Official TypeScript SDK for Prismer Cloud API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
-  "bin": {
-    "prismer": "./dist/cli.js"
-  },
   "files": [
     "dist",
     "icon"
@@ -58,6 +55,10 @@
       "types": "./dist/webhook.d.ts",
       "import": "./dist/webhook.mjs",
       "require": "./dist/webhook.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "require": "./dist/cli.js"
     }
   },
   "publishConfig": {