@asyncify-hq/agent 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @asyncify-hq/agent
+
+Build the brain; Asyncify handles the channels. This SDK receives
+normalized conversation events from Asyncify (any channel — in-app today,
+more coming), lets your code reply, and batches **signals** — conversation
+metadata, workflow triggers, resolution — into the single HTTP response.
+
+Zero dependencies. Works with plain Node `http`, Express, Fastify, or any
+framework that exposes the raw request.
+
+## Quickstart
+
+1. Register an agent (dashboard → Agents, or the API) with the URL your
+   handler will listen on. Copy the signing secret — it is shown once.
+
+2. Write the brain:
+
+```ts
+import http from 'node:http';
+import { defineAgent, createHandler } from '@asyncify-hq/agent';
+
+const support = defineAgent({
+  async onMessage(ctx) {
+    // ctx.history is pre-shaped for LLM SDKs: [{ role, content }, ...]
+    if (ctx.message.text.toLowerCase().includes('order')) {
+      ctx.metadata.set('topic', 'orders');
+      // fire a real notification workflow, mid-conversation
+      ctx.trigger('order-replacement', { payload: { order: '#1042' } });
+      return 'So sorry! A replacement is on the way — confirmation email incoming.';
+    }
+    if (ctx.message.text.toLowerCase().includes('thanks')) {
+      ctx.resolve('customer satisfied');
+      return 'Anytime!';
+    }
+    return `You said: ${ctx.message.text}`;
+  },
+});
+
+http
+  .createServer(createHandler(support, { signingSecret: process.env.ASYNCIFY_AGENT_SECRET! }))
+  .listen(4100);
+```
+
+3. Send a message from the `<AgentChat />` widget (`@asyncify-hq/react`)
+   or the API — your handler answers, Asyncify delivers.
+
+## Adding an LLM
+
+`ctx.history` maps directly onto chat-completion messages:
+
+```ts
+const { text } = await generateText({
+  model: openai('gpt-4o-mini'),
+  system: 'You are a support agent for Acme.',
+  messages: [...ctx.history, { role: 'user', content: ctx.message.text }],
+});
+return text;
+```
+
+## Security
+
+Every request is HMAC-SHA256 signed (`x-asyncify-signature` over
+`timestamp.body`, replay-protected by `x-asyncify-timestamp`). The handler
+rejects anything unsigned or stale; `verifySignature` is exported if you
+need to verify manually.

package/dist/index.cjs

@@ -0,0 +1,134 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createHandler: () => createHandler,
+  defineAgent: () => defineAgent,
+  handleEvent: () => handleEvent,
+  verifySignature: () => verifySignature
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_crypto = require("crypto");
+function defineAgent(definition) {
+  if (typeof definition.onMessage !== "function") {
+    throw new Error("defineAgent requires an onMessage handler");
+  }
+  return definition;
+}
+function verifySignature(secret, timestamp, signature, rawBody, toleranceSec = 300) {
+  if (!timestamp || !signature) return false;
+  const ts = Number.parseInt(timestamp, 10);
+  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1e3 - ts) > toleranceSec) return false;
+  const expected = (0, import_node_crypto.createHmac)("sha256", secret).update(`${timestamp}.${rawBody}`).digest();
+  let provided;
+  try {
+    provided = Buffer.from(signature, "hex");
+  } catch {
+    return false;
+  }
+  return provided.length === expected.length && (0, import_node_crypto.timingSafeEqual)(provided, expected);
+}
+async function handleEvent(agent, event) {
+  const signals = [];
+  let reply;
+  const metadata = { ...event.conversation.metadata };
+  const ctx = {
+    message: event.message,
+    conversation: event.conversation,
+    subscriber: event.subscriber,
+    history: event.history,
+    reply(text) {
+      reply = text;
+    },
+    metadata: {
+      set(key, value) {
+        metadata[key] = value;
+        signals.push({ type: "metadata.set", key, value });
+      },
+      get(key) {
+        return metadata[key];
+      }
+    },
+    trigger(workflowKey, options) {
+      signals.push({
+        type: "trigger",
+        workflowKey,
+        payload: options?.payload,
+        priority: options?.priority
+      });
+    },
+    resolve(summary) {
+      signals.push({ type: "resolve", summary });
+    }
+  };
+  const returned = await agent.onMessage(ctx);
+  if (typeof returned === "string") reply = returned;
+  return { reply, signals };
+}
+function createHandler(agent, options) {
+  if (!options.signingSecret) throw new Error("createHandler requires signingSecret");
+  return (req, res) => {
+    const chunks = [];
+    req.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+    req.on("error", () => respond(res, 400, { error: "read error" }));
+    req.on("end", () => {
+      void (async () => {
+        const rawBody = Buffer.concat(chunks).toString("utf8");
+        const header = (name) => {
+          const v = req.headers[name];
+          return Array.isArray(v) ? v[0] : v;
+        };
+        const ok = verifySignature(
+          options.signingSecret,
+          header("x-asyncify-timestamp"),
+          header("x-asyncify-signature"),
+          rawBody,
+          options.toleranceSec
+        );
+        if (!ok) return respond(res, 401, { error: "invalid signature" });
+        let event;
+        try {
+          event = JSON.parse(rawBody);
+        } catch {
+          return respond(res, 400, { error: "invalid JSON" });
+        }
+        if (event.type !== "message") return respond(res, 200, { signals: [] });
+        try {
+          respond(res, 200, await handleEvent(agent, event));
+        } catch (err) {
+          respond(res, 500, { error: err.message });
+        }
+      })();
+    });
+  };
+}
+function respond(res, status, body) {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json");
+  res.end(JSON.stringify(body));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createHandler,
+  defineAgent,
+  handleEvent,
+  verifySignature
+});

package/dist/index.d.cts

@@ -0,0 +1,127 @@
+/**
+ * @asyncify-hq/agent — build the brain, Asyncify handles the channels.
+ *
+ *   import { defineAgent, createHandler } from '@asyncify-hq/agent';
+ *
+ *   const support = defineAgent({
+ *     async onMessage(ctx) {
+ *       if (ctx.message.text.includes('order')) {
+ *         ctx.metadata.set('topic', 'orders');
+ *         ctx.trigger('order-shipped', { payload: { order: '#1042' } });
+ *         return 'A replacement is on the way — confirmation email incoming.';
+ *       }
+ *       return `You said: ${ctx.message.text}`;
+ *     },
+ *   });
+ *
+ *   http.createServer(createHandler(support, {
+ *     signingSecret: process.env.ASYNCIFY_AGENT_SECRET!,
+ *   })).listen(4100);
+ *
+ * Asyncify POSTs each normalized conversation turn (any channel) to this
+ * handler; the reply and any signals (metadata / trigger / resolve) are
+ * batched into the single HTTP response. Zero dependencies.
+ */
+interface AgentEventMessage {
+    id: string;
+    text: string;
+    createdAt: string;
+}
+interface AgentEventConversation {
+    id: string;
+    channel: string;
+    status: 'active' | 'resolved';
+    metadata: Record<string, unknown>;
+    messageCount: number;
+}
+interface AgentEventSubscriber {
+    subscriberId: string;
+    email: string | null;
+    phone: string | null;
+}
+/** Prior turns, pre-shaped for LLM SDKs (drop straight into messages[]). */
+interface HistoryEntry {
+    role: 'user' | 'assistant';
+    content: string;
+}
+interface AgentEvent {
+    type: 'message';
+    agent: {
+        identifier: string;
+        name: string;
+    };
+    conversation: AgentEventConversation;
+    subscriber: AgentEventSubscriber;
+    message: AgentEventMessage;
+    history: HistoryEntry[];
+}
+type Priority = 'p0' | 'p1' | 'p2';
+type Signal = {
+    type: 'metadata.set';
+    key: string;
+    value: unknown;
+} | {
+    type: 'trigger';
+    workflowKey: string;
+    payload?: Record<string, unknown>;
+    priority?: Priority;
+} | {
+    type: 'resolve';
+    summary?: string;
+};
+interface BridgeResponse {
+    reply?: string;
+    signals: Signal[];
+}
+interface AgentContext {
+    /** The inbound turn being handled. */
+    message: AgentEventMessage;
+    conversation: AgentEventConversation;
+    subscriber: AgentEventSubscriber;
+    /** Prior user/assistant turns, oldest first. */
+    history: HistoryEntry[];
+    /** Send a reply to the user (last call wins; returning a string does the same). */
+    reply(text: string): void;
+    metadata: {
+        /** Persist a key on the conversation (survives across turns, 64KB total). */
+        set(key: string, value: unknown): void;
+        get(key: string): unknown;
+    };
+    /** Fire a normal Asyncify notification workflow, mid-conversation. */
+    trigger(workflowKey: string, options?: {
+        payload?: Record<string, unknown>;
+        priority?: Priority;
+    }): void;
+    /** Mark the conversation resolved (a new message reopens it). */
+    resolve(summary?: string): void;
+}
+type MessageHandler = (ctx: AgentContext) => string | void | undefined | Promise<string | void | undefined>;
+interface AgentDefinition {
+    onMessage: MessageHandler;
+    /** Reserved for platform-dispatched resolve events (not sent yet). */
+    onResolve?: (ctx: AgentContext) => void | Promise<void>;
+}
+declare function defineAgent(definition: AgentDefinition): AgentDefinition;
+declare function verifySignature(secret: string, timestamp: string | undefined, signature: string | undefined, rawBody: string, toleranceSec?: number): boolean;
+declare function handleEvent(agent: AgentDefinition, event: AgentEvent): Promise<BridgeResponse>;
+/** Structural subset of http.IncomingMessage / ServerResponse. */
+interface RequestLike {
+    headers: Record<string, string | string[] | undefined>;
+    on(event: 'data', cb: (chunk: unknown) => void): unknown;
+    on(event: 'end', cb: () => void): unknown;
+    on(event: 'error', cb: (err: Error) => void): unknown;
+}
+interface ResponseLike {
+    statusCode: number;
+    setHeader(name: string, value: string): unknown;
+    end(body?: string): unknown;
+}
+interface HandlerOptions {
+    /** The signing secret shown once when the agent was created (ags_...). */
+    signingSecret: string;
+    /** Clock-skew tolerance for the signed timestamp, seconds. */
+    toleranceSec?: number;
+}
+declare function createHandler(agent: AgentDefinition, options: HandlerOptions): (req: RequestLike, res: ResponseLike) => void;
+
+export { type AgentContext, type AgentDefinition, type AgentEvent, type AgentEventConversation, type AgentEventMessage, type AgentEventSubscriber, type BridgeResponse, type HandlerOptions, type HistoryEntry, type MessageHandler, type Priority, type RequestLike, type ResponseLike, type Signal, createHandler, defineAgent, handleEvent, verifySignature };

package/dist/index.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @asyncify-hq/agent — build the brain, Asyncify handles the channels.
+ *
+ *   import { defineAgent, createHandler } from '@asyncify-hq/agent';
+ *
+ *   const support = defineAgent({
+ *     async onMessage(ctx) {
+ *       if (ctx.message.text.includes('order')) {
+ *         ctx.metadata.set('topic', 'orders');
+ *         ctx.trigger('order-shipped', { payload: { order: '#1042' } });
+ *         return 'A replacement is on the way — confirmation email incoming.';
+ *       }
+ *       return `You said: ${ctx.message.text}`;
+ *     },
+ *   });
+ *
+ *   http.createServer(createHandler(support, {
+ *     signingSecret: process.env.ASYNCIFY_AGENT_SECRET!,
+ *   })).listen(4100);
+ *
+ * Asyncify POSTs each normalized conversation turn (any channel) to this
+ * handler; the reply and any signals (metadata / trigger / resolve) are
+ * batched into the single HTTP response. Zero dependencies.
+ */
+interface AgentEventMessage {
+    id: string;
+    text: string;
+    createdAt: string;
+}
+interface AgentEventConversation {
+    id: string;
+    channel: string;
+    status: 'active' | 'resolved';
+    metadata: Record<string, unknown>;
+    messageCount: number;
+}
+interface AgentEventSubscriber {
+    subscriberId: string;
+    email: string | null;
+    phone: string | null;
+}
+/** Prior turns, pre-shaped for LLM SDKs (drop straight into messages[]). */
+interface HistoryEntry {
+    role: 'user' | 'assistant';
+    content: string;
+}
+interface AgentEvent {
+    type: 'message';
+    agent: {
+        identifier: string;
+        name: string;
+    };
+    conversation: AgentEventConversation;
+    subscriber: AgentEventSubscriber;
+    message: AgentEventMessage;
+    history: HistoryEntry[];
+}
+type Priority = 'p0' | 'p1' | 'p2';
+type Signal = {
+    type: 'metadata.set';
+    key: string;
+    value: unknown;
+} | {
+    type: 'trigger';
+    workflowKey: string;
+    payload?: Record<string, unknown>;
+    priority?: Priority;
+} | {
+    type: 'resolve';
+    summary?: string;
+};
+interface BridgeResponse {
+    reply?: string;
+    signals: Signal[];
+}
+interface AgentContext {
+    /** The inbound turn being handled. */
+    message: AgentEventMessage;
+    conversation: AgentEventConversation;
+    subscriber: AgentEventSubscriber;
+    /** Prior user/assistant turns, oldest first. */
+    history: HistoryEntry[];
+    /** Send a reply to the user (last call wins; returning a string does the same). */
+    reply(text: string): void;
+    metadata: {
+        /** Persist a key on the conversation (survives across turns, 64KB total). */
+        set(key: string, value: unknown): void;
+        get(key: string): unknown;
+    };
+    /** Fire a normal Asyncify notification workflow, mid-conversation. */
+    trigger(workflowKey: string, options?: {
+        payload?: Record<string, unknown>;
+        priority?: Priority;
+    }): void;
+    /** Mark the conversation resolved (a new message reopens it). */
+    resolve(summary?: string): void;
+}
+type MessageHandler = (ctx: AgentContext) => string | void | undefined | Promise<string | void | undefined>;
+interface AgentDefinition {
+    onMessage: MessageHandler;
+    /** Reserved for platform-dispatched resolve events (not sent yet). */
+    onResolve?: (ctx: AgentContext) => void | Promise<void>;
+}
+declare function defineAgent(definition: AgentDefinition): AgentDefinition;
+declare function verifySignature(secret: string, timestamp: string | undefined, signature: string | undefined, rawBody: string, toleranceSec?: number): boolean;
+declare function handleEvent(agent: AgentDefinition, event: AgentEvent): Promise<BridgeResponse>;
+/** Structural subset of http.IncomingMessage / ServerResponse. */
+interface RequestLike {
+    headers: Record<string, string | string[] | undefined>;
+    on(event: 'data', cb: (chunk: unknown) => void): unknown;
+    on(event: 'end', cb: () => void): unknown;
+    on(event: 'error', cb: (err: Error) => void): unknown;
+}
+interface ResponseLike {
+    statusCode: number;
+    setHeader(name: string, value: string): unknown;
+    end(body?: string): unknown;
+}
+interface HandlerOptions {
+    /** The signing secret shown once when the agent was created (ags_...). */
+    signingSecret: string;
+    /** Clock-skew tolerance for the signed timestamp, seconds. */
+    toleranceSec?: number;
+}
+declare function createHandler(agent: AgentDefinition, options: HandlerOptions): (req: RequestLike, res: ResponseLike) => void;
+
+export { type AgentContext, type AgentDefinition, type AgentEvent, type AgentEventConversation, type AgentEventMessage, type AgentEventSubscriber, type BridgeResponse, type HandlerOptions, type HistoryEntry, type MessageHandler, type Priority, type RequestLike, type ResponseLike, type Signal, createHandler, defineAgent, handleEvent, verifySignature };

package/dist/index.js

@@ -0,0 +1,106 @@
+// src/index.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function defineAgent(definition) {
+  if (typeof definition.onMessage !== "function") {
+    throw new Error("defineAgent requires an onMessage handler");
+  }
+  return definition;
+}
+function verifySignature(secret, timestamp, signature, rawBody, toleranceSec = 300) {
+  if (!timestamp || !signature) return false;
+  const ts = Number.parseInt(timestamp, 10);
+  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1e3 - ts) > toleranceSec) return false;
+  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest();
+  let provided;
+  try {
+    provided = Buffer.from(signature, "hex");
+  } catch {
+    return false;
+  }
+  return provided.length === expected.length && timingSafeEqual(provided, expected);
+}
+async function handleEvent(agent, event) {
+  const signals = [];
+  let reply;
+  const metadata = { ...event.conversation.metadata };
+  const ctx = {
+    message: event.message,
+    conversation: event.conversation,
+    subscriber: event.subscriber,
+    history: event.history,
+    reply(text) {
+      reply = text;
+    },
+    metadata: {
+      set(key, value) {
+        metadata[key] = value;
+        signals.push({ type: "metadata.set", key, value });
+      },
+      get(key) {
+        return metadata[key];
+      }
+    },
+    trigger(workflowKey, options) {
+      signals.push({
+        type: "trigger",
+        workflowKey,
+        payload: options?.payload,
+        priority: options?.priority
+      });
+    },
+    resolve(summary) {
+      signals.push({ type: "resolve", summary });
+    }
+  };
+  const returned = await agent.onMessage(ctx);
+  if (typeof returned === "string") reply = returned;
+  return { reply, signals };
+}
+function createHandler(agent, options) {
+  if (!options.signingSecret) throw new Error("createHandler requires signingSecret");
+  return (req, res) => {
+    const chunks = [];
+    req.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+    req.on("error", () => respond(res, 400, { error: "read error" }));
+    req.on("end", () => {
+      void (async () => {
+        const rawBody = Buffer.concat(chunks).toString("utf8");
+        const header = (name) => {
+          const v = req.headers[name];
+          return Array.isArray(v) ? v[0] : v;
+        };
+        const ok = verifySignature(
+          options.signingSecret,
+          header("x-asyncify-timestamp"),
+          header("x-asyncify-signature"),
+          rawBody,
+          options.toleranceSec
+        );
+        if (!ok) return respond(res, 401, { error: "invalid signature" });
+        let event;
+        try {
+          event = JSON.parse(rawBody);
+        } catch {
+          return respond(res, 400, { error: "invalid JSON" });
+        }
+        if (event.type !== "message") return respond(res, 200, { signals: [] });
+        try {
+          respond(res, 200, await handleEvent(agent, event));
+        } catch (err) {
+          respond(res, 500, { error: err.message });
+        }
+      })();
+    });
+  };
+}
+function respond(res, status, body) {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json");
+  res.end(JSON.stringify(body));
+}
+export {
+  createHandler,
+  defineAgent,
+  handleEvent,
+  verifySignature
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@asyncify-hq/agent",
+  "version": "0.1.0",
+  "description": "Agent SDK for Asyncify — receive normalized conversation events from any channel, reply, and fire notification workflows mid-conversation",
+  "keywords": ["agents", "ai-agents", "conversations", "chat", "notifications", "asyncify"],
+  "homepage": "https://asyncify.org",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shubam14dec/Scalable-Notification-System.git",
+    "directory": "packages/agent"
+  },
+  "license": "MIT",
+  "author": "Shubam Patil",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}