@emseepea/feedback 0.5.3 → 0.6.0

package/README.md

@@ -241,6 +241,37 @@ and cannot change the MCP result. Hook code must honor that signal and deadline.
 For reliable delivery, use the PostgreSQL or Firestore outbox, or GitHub and
 Zendesk native automation.
 
+### Notify an AI client about a team reply
+
+A protected conversation can optionally use MCP Events to tell a subscribed AI
+client that a team reply is ready. The event carries only the account or client
+scope and stable thread, message, and source-event IDs. It does not carry the
+reply text. The client should call `get-feedback-thread` and present the reply
+to the person.
+
+1. Configure `createFeedbackReplyEventsOptions` from
+   `@emseepea/feedback/mcp-events` as the server's `events` option. Use the same
+   stable account or client scope for its `ownerKey` as for
+   `defineFeedbackConversation({ scope })`.
+2. Supply `canReadThread(ownerKey, threadId)` to check access to the exact
+   thread. The check runs when subscribing and again before delivery. Supply
+   your durable MCP Events store and health check as described in the
+   [MCP Events guide](https://emseepea.github.io/emseepea/mcp-events/).
+3. After saving a team reply, pass its typed feedback event to
+   `publishFeedbackTeamReplyEvent(app, event)`. For PostgreSQL or Firestore,
+   publish from the transactional outbox: a saved queue that can be retried
+   after failures. For GitHub or Zendesk, use the checked provider webhook.
+   The helper ignores non-team events and publishes only a reference to a team
+   message.
+
+An outbox retry can publish the same reply more than once. Use the stable
+`sourceEventId` in the event payload to recognise duplicates.
+
+The Markdown destination is one-way and has no team reply to announce. An
+event delivery, or a reply being offered to an AI client, does not prove a
+person saw it. Test the complete reply journey in your own client and
+deployment before relying on it.
+
 ## Effect and Retry Limits
 
 Creating a thread, submitting feedback, and appending a message are

package/dist/mcp-events.d.ts

@@ -0,0 +1,15 @@
+import { publishMcpEvent, type McpEventsOptions } from "@emseepea/server";
+export declare const feedbackReplyEventName = "feedback.reply.ready";
+export interface FeedbackReplyEventsOptions {
+    /** Use the same stable scope projection as defineFeedbackConversation. */
+    readonly ownerKey: McpEventsOptions["ownerKey"];
+    /** Check access to this exact thread, including when a delivery is due. */
+    readonly canReadThread: (ownerKey: string, threadId: string) => boolean | Promise<boolean>;
+    readonly health: McpEventsOptions["health"];
+    readonly store: McpEventsOptions["store"];
+    readonly callbackTimeoutMs?: number;
+}
+export declare function createFeedbackReplyEventsOptions(options: FeedbackReplyEventsOptions): McpEventsOptions;
+/** Publish a durable team reply reference after the feedback backend commits it. */
+export declare function publishFeedbackTeamReplyEvent(app: Parameters<typeof publishMcpEvent>[0], event: unknown): Promise<boolean>;
+//# sourceMappingURL=mcp-events.d.ts.map

package/dist/mcp-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-events.d.ts","sourceRoot":"","sources":["../src/mcp-events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAI1E,eAAO,MAAM,sBAAsB,yBAAyB,CAAC;AAa7D,MAAM,WAAW,0BAA0B;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAChD,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3F,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,0BAA0B,GAAG,gBAAgB,CAuBtG;AAED,oFAAoF;AACpF,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC,EAC1C,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,OAAO,CAAC,CAYlB"}

package/dist/mcp-events.js

@@ -0,0 +1,57 @@
+import { publishMcpEvent } from "@emseepea/server";
+import { z } from "zod";
+import { feedbackEventSchema } from "./index.js";
+export const feedbackReplyEventName = "feedback.reply.ready";
+const identifier = z.string().min(1).max(240);
+const threadArguments = z.strictObject({
+    threadId: identifier.describe("Exact feedback thread to watch for a team reply."),
+});
+const replyReference = z.strictObject({
+    scope: identifier,
+    threadId: identifier,
+    messageId: identifier,
+    sourceEventId: identifier,
+});
+export function createFeedbackReplyEventsOptions(options) {
+    if (typeof options?.canReadThread !== "function")
+        throw new TypeError("feedback reply events require canReadThread");
+    return {
+        definitions: [{
+                name: feedbackReplyEventName,
+                description: "A team reply is ready. Read the exact thread with get-feedback-thread and present the reply to the user.",
+                inputSchema: threadArguments,
+                payloadSchema: replyReference,
+                matches: (arguments_, data, ownerKey) => arguments_.threadId === data.threadId && ownerKey === data.scope,
+            }],
+        ownerKey: options.ownerKey,
+        async authorize({ ownerKey, name, arguments: arguments_, phase }) {
+            if (name !== feedbackReplyEventName)
+                return false;
+            if (phase === "list")
+                return true;
+            const parsed = threadArguments.safeParse(arguments_);
+            return parsed.success && await options.canReadThread(ownerKey, parsed.data.threadId);
+        },
+        health: options.health,
+        store: options.store,
+        ...(options.callbackTimeoutMs === undefined ? {} : { callbackTimeoutMs: options.callbackTimeoutMs }),
+    };
+}
+/** Publish a durable team reply reference after the feedback backend commits it. */
+export async function publishFeedbackTeamReplyEvent(app, event) {
+    const checked = feedbackEventSchema.safeParse(event);
+    if (!checked.success)
+        throw new TypeError("Invalid feedback event");
+    if (checked.data.type !== "feedback.message.added" || checked.data.author !== "team")
+        return false;
+    if (!checked.data.messageId)
+        throw new TypeError("Team reply event requires messageId");
+    await publishMcpEvent(app, feedbackReplyEventName, replyReference.parse({
+        scope: checked.data.scope,
+        threadId: checked.data.threadId,
+        messageId: checked.data.messageId,
+        sourceEventId: checked.data.id,
+    }));
+    return true;
+}
+//# sourceMappingURL=mcp-events.js.map

package/dist/mcp-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-events.js","sourceRoot":"","sources":["../src/mcp-events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAyB,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,CAAC,MAAM,sBAAsB,GAAG,sBAAsB,CAAC;AAE7D,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC9C,MAAM,eAAe,GAAG,CAAC,CAAC,YAAY,CAAC;IACrC,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,kDAAkD,CAAC;CAClF,CAAC,CAAC;AACH,MAAM,cAAc,GAAG,CAAC,CAAC,YAAY,CAAC;IACpC,KAAK,EAAE,UAAU;IACjB,QAAQ,EAAE,UAAU;IACpB,SAAS,EAAE,UAAU;IACrB,aAAa,EAAE,UAAU;CAC1B,CAAC,CAAC;AAYH,MAAM,UAAU,gCAAgC,CAAC,OAAmC;IAClF,IAAI,OAAO,OAAO,EAAE,aAAa,KAAK,UAAU;QAC9C,MAAM,IAAI,SAAS,CAAC,6CAA6C,CAAC,CAAC;IACrE,OAAO;QACL,WAAW,EAAE,CAAC;gBACZ,IAAI,EAAE,sBAAsB;gBAC5B,WAAW,EAAE,0GAA0G;gBACvH,WAAW,EAAE,eAAe;gBAC5B,aAAa,EAAE,cAAc;gBAC7B,OAAO,EAAE,CAAC,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CACtC,UAAU,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ,IAAI,QAAQ,KAAK,IAAI,CAAC,KAAK;aACnE,CAAC;QACF,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,KAAK,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE;YAC9D,IAAI,IAAI,KAAK,sBAAsB;gBAAE,OAAO,KAAK,CAAC;YAClD,IAAI,KAAK,KAAK,MAAM;gBAAE,OAAO,IAAI,CAAC;YAClC,MAAM,MAAM,GAAG,eAAe,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;YACrD,OAAO,MAAM,CAAC,OAAO,IAAI,MAAM,OAAO,CAAC,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvF,CAAC;QACD,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,GAAG,CAAC,OAAO,CAAC,iBAAiB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,EAAE,CAAC;KACrG,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,GAA0C,EAC1C,KAAc;IAEd,MAAM,OAAO,GAAG,mBAAmB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACrD,IAAI,CAAC,OAAO,CAAC,OAAO;QAAE,MAAM,IAAI,SAAS,CAAC,wBAAwB,CAAC,CAAC;IACpE,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,KAAK,wBAAwB,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IACnG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,SAAS,CAAC,qCAAqC,CAAC,CAAC;IACxF,MAAM,eAAe,CAAC,GAAG,EAAE,sBAAsB,EAAE,cAAc,CAAC,KAAK,CAAC;QACtE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK;QACzB,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,QAAQ;QAC/B,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,SAAS;QACjC,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE;KAC/B,CAAC,CAAC,CAAC;IACJ,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emseepea/feedback",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Optional detailed feedback and support conversations for Em See Pea servers",
   "license": "MIT",
   "repository": {
@@ -44,6 +44,10 @@
       "types": "./dist/webhooks.d.ts",
       "import": "./dist/webhooks.js"
     },
+    "./mcp-events": {
+      "types": "./dist/mcp-events.d.ts",
+      "import": "./dist/mcp-events.js"
+    },
     "./testing-server": "./dist/testing-server.js"
   },
   "files": [
@@ -55,18 +59,18 @@
     "build": "tsc -p tsconfig.json && tsc -p tsconfig.type-tests.json",
     "prepack": "npm run build",
     "test": "npm run build && npm run test:built",
-    "test:built": "node --test test/*.test.mjs",
+    "test:built": "node --test test/*.test.mjs src/*.test.js",
     "test:postgres": "cd ../../examples/multi-instance-postgres-server && node test/with-postgres.mjs node --test ../../packages/feedback/test/postgres.integration.mjs",
     "test:llm": "npm run build && npm run test:llm:built",
     "test:llm:built": "emseepea-test eval",
     "lint": "oxlint src test eval"
   },
   "dependencies": {
-    "@emseepea/server": "0.21.0",
+    "@emseepea/server": "0.21.1",
     "zod": "4.4.3"
   },
   "devDependencies": {
-    "@emseepea/testing": "0.20.2",
+    "@emseepea/testing": "0.20.3",
     "pg": "8.23.0"
   },
   "engines": {