@emseepea/feedback 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Em See Pea contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# `@emseepea/feedback`
+
+Add detailed feedback or a durable support conversation to any Em See Pea
+server. The package is optional. Generated applications do not configure it.
+Their semantic tests install it only as a development dependency so successful
+example journeys can prove that the AI did not record negative feedback.
+
+Use a submission when the team only needs one useful observation. Use a
+conversation when the team must reply and the AI must bring that reply back to
+the user.
+
+## Record One Detailed Observation
+
+```ts
+import { defineFeedbackSubmission } from "@emseepea/feedback";
+import { createPostgresFeedbackSubmissionBackend } from "@emseepea/feedback/postgres";
+import { createEmseepea } from "@emseepea/server";
+import { z } from "zod";
+
+const feedback = defineFeedbackSubmission({
+  access: "public",
+  scope: "pea-guide",
+  contextSchema: z.strictObject({
+    feature: z.string().max(80).describe("Feature involved in the observation."),
+  }),
+  backend: createPostgresFeedbackSubmissionBackend({ pool }),
+});
+
+const app = createEmseepea({
+  name: "pea-guide",
+  version: "1.0.0",
+  tools: applicationTools,
+  additionalTools: [feedback],
+});
+```
+
+The tool records one category and bounded explanatory prose. It can also accept
+application-declared structured context. It never captures the surrounding
+conversation, raw tool requests or results, credentials, or application data
+automatically.
+
+Its model-facing description covers errors, friction, annoyance, unnecessary
+difficulty, confusion, repetition, surprising good or bad outcomes, capability
+mismatches, suggestions, and notable success. It tells the AI to:
+
+- record one notable observation without asking a separate permission question
+- openly tell the user in the same response what it recorded
+- avoid normal uneventful operation, expected empty results, and duplicates
+- stop recording if the user objects
+
+The successful structured result includes `nextAction`. It reminds the AI to
+finish every part of the user's original request before briefly stating the
+specific feedback recorded. A routine successful tool call, structured result,
+or expected number of steps is not feedback-worthy.
+
+These are instructions for the AI, not server-enforced guarantees. Qualify the
+behaviour with a native semantic test for every AI client you support.
+
+## Add a Protected Support Conversation
+
+```ts
+import { defineFeedbackConversation } from "@emseepea/feedback";
+import { createGitHubFeedbackBackend } from "@emseepea/feedback/github";
+import { createEmseepea } from "@emseepea/server";
+
+const feedbackTools = defineFeedbackConversation({
+  requiredScopes: ["feedback"],
+  backend: createGitHubFeedbackBackend({
+    owner: "your-organisation",
+    repository: "support",
+    token: () => getGitHubToken(),
+  }),
+  hooks: [sendFeedbackEvent],
+});
+
+const app = createEmseepea({
+  name: "pea-guide",
+  version: "1.0.0",
+  tools: applicationTools,
+  additionalTools: feedbackTools,
+  authentication,
+});
+```
+
+The four tools create a thread, append a user reply, list scoped threads, and
+read one exact thread. Conversations are protected and default to the
+framework-normalized OAuth client ID as their scope. Supply `scope(principal)`
+when your application has a safer account-level projection. Do not pass tokens,
+raw provider claims, or credentials as a scope.
+
+Messages are append-only and ordered by stable sequence numbers. Reading a
+thread may record `offeredToClientAt` on a team reply. That timestamp means the
+reply was included in a validated MCP tool result available to the AI. It does
+not prove the user read or understood it. No acknowledgement button or reply is
+required.
+
+## Choose a Backend
+
+### PostgreSQL
+
+Run `migratePostgresFeedback(pool)` once during controlled setup, then use
+`createPostgresFeedbackBackend({ pool })`. The adapter uses transactions, row
+locks, scope-qualified keys, append-only messages, and a unique first-offer
+update. `appendPostgresTeamReply` is the checked team-side write helper.
+
+Set `outbox: true` to write typed events to
+`emseepea_feedback_outbox` in the same transaction as the feedback change. An
+application worker can claim those rows, send email or queue work, and set
+`dispatched_at`. Em See Pea does not prescribe a queue, retry schedule, or mail
+provider.
+
+### Firestore
+
+Pass an initialized `@google-cloud/firestore` database to
+`createFirestoreFeedbackBackend({ database })`. The package uses the small
+common Firestore transaction and collection surface without taking a runtime
+dependency on Google's SDK. Scope hashes select separate document trees.
+
+`appendFirestoreTeamReply` provides a checked team-side write. Set
+`outbox: true` to write event documents with the feedback transaction. Your
+application owns delivery and retry.
+
+### GitHub Issues
+
+`createGitHubFeedbackBackend` keeps GitHub authoritative:
+
+- a thread is an issue
+- later user messages and team replies are comments
+- support staff use native labels, assignees, milestones, close, and reopen
+- an eyes reaction on the exact support comment records the first client offer
+- normal GitHub notifications and email remain available
+
+Use a private support repository when feedback is sensitive. The adapter uses
+hashed scope labels and exact issue and comment IDs. It never locates an issue
+by title.
+
+### Zendesk
+
+`createZendeskFeedbackBackend` keeps Zendesk authoritative:
+
+- a thread is a ticket
+- user and team messages are public comments
+- agents use native assignment, tags, status, views, triggers, and email
+- a private note on the exact public team comment records the first client offer
+- private agent notes never enter the MCP conversation
+
+Use an OAuth bearer token through the `token` option. The adapter scopes tickets
+with a hashed tag and always reopens the exact ticket ID returned by Zendesk.
+
+GitHub and Zendesk are polled through their authenticated APIs when a client
+lists or reads feedback. Provider response shapes cross runtime validation
+before they become feedback data. Native provider notifications are preferred
+for reliable email.
+
+Use `ingestGitHubFeedbackWebhook` or `ingestZendeskFeedbackWebhook` from
+`@emseepea/feedback/webhooks` to turn provider changes into typed events. The
+caller supplies:
+
+- raw body bytes and lower-case provider headers
+- a randomly generated, high-entropy secret of at least 32 UTF-8 bytes, stored
+  outside source control, and the configured destination
+- a store that resolves scope hashes and atomically claims stable delivery or
+  audit IDs
+
+The boundary verifies the signature, 64 KiB size limit, destination, payload
+schema, scope, deadline, and duplicate status before returning an event.
+Configure Zendesk's webhook body to match the documented `eventId`, `subdomain`,
+`ticketId`, `scopeTag`, `occurredAt`, and `change` shape exported by the
+TypeScript API.
+
+The included GitHub and Zendesk checks are deterministic HTTP contract tests,
+not evidence from a live customer account. Provider-native assignment,
+categorisation, milestone, status, notification, and email behavior remains the
+provider's responsibility and must be qualified in the account where you deploy
+the adapter.
+
+## Handle Feedback Events
+
+Hooks receive references, not feedback content:
+
+```ts
+async function sendFeedbackEvent(event, { signal, deadlineMs }) {
+  await queue.send({
+    id: event.id,
+    type: event.type,
+    threadId: event.threadId,
+    messageId: event.messageId,
+  }, { signal, deadlineMs });
+}
+```
+
+The event vocabulary is limited to thread creation, message addition, status
+change, and message offer. Events contain an opaque scope and stable IDs. They
+contain no feedback body, summary, email address, recipient, vendor payload,
+credentials, request, response, or provider error.
+
+Hooks run after durable state succeeds and receive the request's cancellation
+signal and absolute deadline. They are best-effort, have no framework retry,
+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.
+
+## Effect and Retry Limits
+
+Creating a thread, submitting feedback, and appending a message are
+non-idempotent. Em See Pea does not retry them. A client retry can create a
+duplicate unless your backend atomically deduplicates a stable operation ID that
+the model cannot supply or alter.
+
+Reading a conversation can write the first-offer receipt. PostgreSQL and
+Firestore claim that receipt atomically, and GitHub uses the provider's
+idempotent reaction endpoint.
+
+Zendesk private receipt notes are best-effort and can duplicate when clients
+read concurrently; their stable message marker lets application automation
+deduplicate them. Receipt failure never hides a support reply from the AI.
+
+The package makes no claim that an AI will always record feedback, avoid
+duplicates, present a reply, or honor an objection. Native semantic tests
+provide evidence only for the tested client, model, prompts, and revision.

package/dist/deadline.d.ts

@@ -0,0 +1,4 @@
+import type { FeedbackAdapterContext } from "./index.js";
+export declare function deadlineSignal(context: Pick<FeedbackAdapterContext, "signal" | "deadlineMs">): AbortSignal;
+export declare function beforeDeadline<T>(promise: Promise<T>, context: Pick<FeedbackAdapterContext, "signal" | "deadlineMs">): Promise<T>;
+//# sourceMappingURL=deadline.d.ts.map

package/dist/deadline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deadline.d.ts","sourceRoot":"","sources":["../src/deadline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,IAAI,CAAC,sBAAsB,EAAE,QAAQ,GAAG,YAAY,CAAC,GAC7D,WAAW,CAKb;AAED,wBAAsB,cAAc,CAAC,CAAC,EACpC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,OAAO,EAAE,IAAI,CAAC,sBAAsB,EAAE,QAAQ,GAAG,YAAY,CAAC,GAC7D,OAAO,CAAC,CAAC,CAAC,CA+BZ"}

package/dist/deadline.js

@@ -0,0 +1,41 @@
+export function deadlineSignal(context) {
+    context.signal.throwIfAborted();
+    const remaining = context.deadlineMs - Date.now();
+    if (remaining <= 0)
+        throw new DOMException("The feedback deadline expired", "TimeoutError");
+    return AbortSignal.any([context.signal, AbortSignal.timeout(remaining)]);
+}
+export async function beforeDeadline(promise, context) {
+    context.signal.throwIfAborted();
+    const remaining = context.deadlineMs - Date.now();
+    if (remaining <= 0)
+        throw new DOMException("The feedback deadline expired", "TimeoutError");
+    return new Promise((resolve, reject) => {
+        let timer;
+        let settled = false;
+        const cleanup = () => {
+            if (timer)
+                clearTimeout(timer);
+            context.signal.removeEventListener("abort", abort);
+        };
+        const succeed = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(value);
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        };
+        const abort = () => fail(context.signal.reason);
+        context.signal.addEventListener("abort", abort, { once: true });
+        timer = setTimeout(() => fail(new DOMException("The feedback deadline expired", "TimeoutError")), remaining);
+        promise.then(succeed, fail);
+    });
+}
+//# sourceMappingURL=deadline.js.map

package/dist/deadline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deadline.js","sourceRoot":"","sources":["../src/deadline.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,cAAc,CAC5B,OAA8D;IAE9D,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;IAChC,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAClD,IAAI,SAAS,IAAI,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,+BAA+B,EAAE,cAAc,CAAC,CAAC;IAC5F,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAmB,EACnB,OAA8D;IAE9D,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;IAChC,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAClD,IAAI,SAAS,IAAI,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,+BAA+B,EAAE,cAAc,CAAC,CAAC;IAC5F,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxC,IAAI,KAAgD,CAAC;QACrD,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,IAAI,KAAK;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YAC/B,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACrD,CAAC,CAAC;QACF,MAAM,OAAO,GAAG,CAAC,KAAQ,EAAE,EAAE;YAC3B,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,OAAO,EAAE,CAAC;YACV,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC,CAAC;QACF,MAAM,IAAI,GAAG,CAAC,KAAc,EAAE,EAAE;YAC9B,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,OAAO,EAAE,CAAC;YACV,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAChD,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAChE,KAAK,GAAG,UAAU,CAChB,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,+BAA+B,EAAE,cAAc,CAAC,CAAC,EAC7E,SAAS,CACV,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/firestore.d.ts

@@ -0,0 +1,48 @@
+import type { FeedbackConversationBackend, FeedbackSubmissionBackend } from "./index.js";
+interface FirestoreDocumentSnapshot {
+    readonly id: string;
+    readonly exists: boolean;
+    data(): unknown;
+}
+interface FirestoreQuerySnapshot {
+    readonly docs: readonly FirestoreDocumentSnapshot[];
+}
+interface FirestoreQuery {
+    orderBy(field: string, direction?: "asc" | "desc"): FirestoreQuery;
+    startAfter(value: unknown): FirestoreQuery;
+    limit(value: number): FirestoreQuery;
+}
+interface FirestoreDocumentReference {
+    readonly id: string;
+    collection(path: string): FirestoreCollectionReference;
+}
+interface FirestoreCollectionReference extends FirestoreQuery {
+    doc(id?: string): FirestoreDocumentReference;
+}
+interface FirestoreTransaction {
+    get(reference: FirestoreDocumentReference | FirestoreQuery): Promise<FirestoreDocumentSnapshot | FirestoreQuerySnapshot>;
+    set(reference: FirestoreDocumentReference, data: Readonly<Record<string, unknown>>): void;
+    update(reference: FirestoreDocumentReference, data: Readonly<Record<string, unknown>>): void;
+}
+export interface FirestoreFeedbackDatabase {
+    collection(path: string): FirestoreCollectionReference;
+    runTransaction<T>(work: (transaction: FirestoreTransaction) => Promise<T>): Promise<T>;
+}
+export interface FirestoreFeedbackOptions {
+    readonly database: FirestoreFeedbackDatabase;
+    readonly rootCollection?: string;
+    readonly outbox?: boolean;
+}
+export declare function createFirestoreFeedbackSubmissionBackend<Context = undefined>(options: FirestoreFeedbackOptions): FeedbackSubmissionBackend<Context>;
+export declare function createFirestoreFeedbackBackend(options: FirestoreFeedbackOptions): FeedbackConversationBackend;
+export declare function appendFirestoreTeamReply(options: FirestoreFeedbackOptions, command: Readonly<{
+    scope: string;
+    threadId: string;
+    message: string;
+    status?: string;
+}>, context: Readonly<{
+    signal: AbortSignal;
+    deadlineMs: number;
+}>): Promise<void>;
+export {};
+//# sourceMappingURL=firestore.d.ts.map

package/dist/firestore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firestore.d.ts","sourceRoot":"","sources":["../src/firestore.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAGV,2BAA2B,EAC3B,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAGpB,UAAU,yBAAyB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,IAAI,IAAI,OAAO,CAAC;CACjB;AAED,UAAU,sBAAsB;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,yBAAyB,EAAE,CAAC;CACrD;AAED,UAAU,cAAc;IACtB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,cAAc,CAAC;IACnE,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAAC;IAC3C,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC;CACtC;AAED,UAAU,0BAA0B;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,4BAA4B,CAAC;CACxD;AAED,UAAU,4BAA6B,SAAQ,cAAc;IAC3D,GAAG,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,0BAA0B,CAAC;CAC9C;AAED,UAAU,oBAAoB;IAC5B,GAAG,CAAC,SAAS,EAAE,0BAA0B,GAAG,cAAc,GAAG,OAAO,CAAC,yBAAyB,GAAG,sBAAsB,CAAC,CAAC;IACzH,GAAG,CAAC,SAAS,EAAE,0BAA0B,EAAE,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAC1F,MAAM,CAAC,SAAS,EAAE,0BAA0B,EAAE,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CAC9F;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,4BAA4B,CAAC;IACvD,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,oBAAoB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACxF;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,CAAC;IAC7C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,wBAAgB,wCAAwC,CAAC,OAAO,GAAG,SAAS,EAC1E,OAAO,EAAE,wBAAwB,GAChC,yBAAyB,CAAC,OAAO,CAAC,CAoBpC;AAED,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,wBAAwB,GAChC,2BAA2B,CA6J7B;AAED,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,EACF,OAAO,EAAE,QAAQ,CAAC;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7D,OAAO,CAAC,IAAI,CAAC,CAsCf"}

package/dist/firestore.js

@@ -0,0 +1,296 @@
+import { createHash, randomUUID } from "node:crypto";
+import { z } from "zod";
+import { feedbackConversationSchema } from "./index.js";
+import { beforeDeadline, deadlineSignal } from "./deadline.js";
+export function createFirestoreFeedbackSubmissionBackend(options) {
+    return {
+        async submit(command, context) {
+            context.signal.throwIfAborted();
+            const id = randomUUID();
+            const recordedAt = new Date().toISOString();
+            const events = [event("feedback.message.added", id, id, "user", recordedAt)];
+            await runTransaction(options, context, async (transaction) => {
+                context.signal.throwIfAborted();
+                transaction.set(scopeRoot(options, context.scope).collection("submissions").doc(id), {
+                    observation: command.observation,
+                    detail: command.detail,
+                    context: JSON.parse(JSON.stringify(command.context ?? null)),
+                    recordedAt,
+                });
+                if (options.outbox)
+                    writeOutbox(transaction, options, context.scope, events);
+            });
+            return { id, recordedAt, events };
+        },
+    };
+}
+export function createFirestoreFeedbackBackend(options) {
+    return {
+        async createThread(command, context) {
+            const threadId = randomUUID();
+            const messageId = randomUUID();
+            const now = new Date().toISOString();
+            const thread = {
+                id: threadId,
+                subject: command.subject,
+                status: "open",
+                createdAt: now,
+                updatedAt: now,
+                pageKey: pageKey(now, threadId),
+                latestSequence: 1,
+            };
+            const message = {
+                id: messageId,
+                threadId,
+                sequence: 1,
+                author: "user",
+                kind: "comment",
+                body: command.message,
+                createdAt: now,
+            };
+            const events = [
+                event("feedback.thread.created", threadId, undefined, "user", now),
+                event("feedback.message.added", threadId, messageId, "user", now),
+            ];
+            await runTransaction(options, context, async (transaction) => {
+                context.signal.throwIfAborted();
+                const reference = threads(options, context.scope).doc(threadId);
+                transaction.set(reference, thread);
+                transaction.set(reference.collection("messages").doc(messageId), message);
+                if (options.outbox)
+                    writeOutbox(transaction, options, context.scope, events);
+            });
+            return { conversation: { ...publicThread(thread), messages: [message] }, events };
+        },
+        async appendMessage(command, context) {
+            return runTransaction(options, context, async (transaction) => {
+                context.signal.throwIfAborted();
+                const reference = threads(options, context.scope).doc(command.threadId);
+                const snapshot = document(await transaction.get(reference));
+                if (!snapshot.exists)
+                    throw new Error("Feedback thread not found");
+                const thread = threadDocument.parse(snapshot.data());
+                const now = new Date().toISOString();
+                const message = {
+                    id: randomUUID(),
+                    threadId: command.threadId,
+                    sequence: thread.latestSequence + 1,
+                    author: "user",
+                    kind: "comment",
+                    body: command.message,
+                    createdAt: now,
+                };
+                transaction.set(reference.collection("messages").doc(message.id), message);
+                transaction.update(reference, {
+                    updatedAt: now,
+                    pageKey: pageKey(now, command.threadId),
+                    latestSequence: message.sequence,
+                });
+                const events = [event("feedback.message.added", command.threadId, message.id, "user", now)];
+                if (options.outbox)
+                    writeOutbox(transaction, options, context.scope, events);
+                return { message, events };
+            });
+        },
+        async listThreads({ cursor, limit }, context) {
+            context.signal.throwIfAborted();
+            let query = threads(options, context.scope).orderBy("pageKey", "desc");
+            if (cursor)
+                query = query.startAfter(decodeCursor(cursor));
+            query = query.limit(limit + 1);
+            const snapshot = querySnapshot(await runTransaction(options, context, (transaction) => transaction.get(query)));
+            const rows = snapshot.docs.slice(0, limit + 1).map((item) => threadDocument.parse(item.data()));
+            const visible = rows.slice(0, limit);
+            const last = visible.at(-1);
+            return {
+                page: {
+                    threads: visible.map(publicThread),
+                    nextCursor: rows.length > limit && last ? encodeCursor(last.pageKey) : undefined,
+                },
+            };
+        },
+        async getThread(query, context) {
+            const conversation = await runTransaction(options, context, async (transaction) => {
+                context.signal.throwIfAborted();
+                const reference = threads(options, context.scope).doc(query.threadId);
+                const threadSnapshot = document(await transaction.get(reference));
+                if (!threadSnapshot.exists)
+                    throw new Error("Feedback thread not found");
+                const thread = threadDocument.parse(threadSnapshot.data());
+                const messagesSnapshot = querySnapshot(await transaction.get(reference.collection("messages").orderBy("sequence", "asc").limit(200)));
+                const messages = messagesSnapshot.docs.map((item) => messageDocument.parse(item.data()));
+                return { ...publicThread(thread), messages };
+            });
+            feedbackConversationSchema.parse(conversation);
+            const pending = conversation.messages.filter((message) => message.author === "team" && !message.offeredToClientAt);
+            if (pending.length === 0)
+                return { conversation, events: [] };
+            try {
+                const receipt = await runTransaction(options, context, async (transaction) => {
+                    const reference = threads(options, context.scope).doc(query.threadId);
+                    const timestamps = new Map();
+                    const unclaimed = [];
+                    for (const message of pending) {
+                        const messageReference = reference.collection("messages").doc(message.id);
+                        const snapshot = document(await transaction.get(messageReference));
+                        if (!snapshot.exists)
+                            throw new Error("Feedback message not found");
+                        const current = messageDocument.parse(snapshot.data());
+                        if (current.offeredToClientAt) {
+                            timestamps.set(message.id, current.offeredToClientAt);
+                            continue;
+                        }
+                        unclaimed.push(message);
+                    }
+                    const offeredAt = new Date().toISOString();
+                    const events = [];
+                    for (const message of unclaimed) {
+                        const messageReference = reference.collection("messages").doc(message.id);
+                        transaction.update(messageReference, { offeredToClientAt: offeredAt });
+                        timestamps.set(message.id, offeredAt);
+                        events.push(event("feedback.message.offered-to-client", query.threadId, message.id, "team", offeredAt));
+                    }
+                    if (options.outbox)
+                        writeOutbox(transaction, options, context.scope, events);
+                    return { timestamps, events };
+                });
+                return {
+                    conversation: {
+                        ...conversation,
+                        messages: conversation.messages.map((message) => receipt.timestamps.has(message.id)
+                            ? { ...message, offeredToClientAt: receipt.timestamps.get(message.id) }
+                            : message),
+                    },
+                    events: receipt.events,
+                };
+            }
+            catch {
+                return { conversation, events: [] };
+            }
+        },
+    };
+}
+export async function appendFirestoreTeamReply(options, command, context) {
+    const scope = z.string().min(1).max(240).parse(command.scope);
+    const body = z.string().min(1).max(4_000).parse(command.message);
+    await runTransaction(options, { ...context, scope }, async (transaction) => {
+        context.signal.throwIfAborted();
+        const reference = threads(options, scope).doc(command.threadId);
+        const snapshot = document(await transaction.get(reference));
+        if (!snapshot.exists)
+            throw new Error("Feedback thread not found");
+        const thread = threadDocument.parse(snapshot.data());
+        const now = new Date().toISOString();
+        const message = {
+            id: randomUUID(),
+            threadId: command.threadId,
+            sequence: thread.latestSequence + 1,
+            author: "team",
+            kind: "comment",
+            body,
+            createdAt: now,
+        };
+        transaction.set(reference.collection("messages").doc(message.id), message);
+        transaction.update(reference, {
+            status: command.status ?? thread.status,
+            updatedAt: now,
+            pageKey: pageKey(now, command.threadId),
+            latestSequence: message.sequence,
+        });
+        const events = [event("feedback.message.added", command.threadId, message.id, "team", now)];
+        if (command.status && command.status !== thread.status) {
+            events.push(event("feedback.status.changed", command.threadId, undefined, "team", now));
+        }
+        if (options.outbox)
+            writeOutbox(transaction, options, scope, events);
+    });
+}
+async function runTransaction(options, context, work) {
+    return beforeDeadline(options.database.runTransaction(async (transaction) => {
+        deadlineSignal(context);
+        const result = await work(transaction);
+        deadlineSignal(context);
+        return result;
+    }), context);
+}
+const threadDocument = z.object({
+    id: z.string(),
+    subject: z.string(),
+    status: z.string(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    pageKey: z.string(),
+    latestSequence: z.number().int().positive(),
+});
+const messageDocument = z.object({
+    id: z.string(),
+    threadId: z.string(),
+    sequence: z.number().int().positive(),
+    author: z.enum(["user", "team", "system"]),
+    kind: z.enum(["comment", "question", "status"]),
+    body: z.string(),
+    createdAt: z.string(),
+    offeredToClientAt: z.string().optional(),
+});
+function scopeRoot(options, scope) {
+    return options.database.collection(options.rootCollection ?? "emseepeaFeedbackScopes").doc(scopeHash(scope));
+}
+function threads(options, scope) {
+    return scopeRoot(options, scope).collection("threads");
+}
+function publicThread(thread) {
+    return {
+        id: thread.id,
+        subject: thread.subject,
+        status: thread.status,
+        createdAt: thread.createdAt,
+        updatedAt: thread.updatedAt,
+    };
+}
+function writeOutbox(transaction, options, scope, events) {
+    const outbox = scopeRoot(options, scope).collection("outbox");
+    for (const item of events) {
+        transaction.set(outbox.doc(scopeHash(item.id)), Object.fromEntries(Object.entries({ ...item, scope }).filter(([, value]) => value !== undefined)));
+    }
+}
+function document(value) {
+    if ("docs" in value)
+        throw new Error("Firestore returned a query snapshot for a document");
+    return value;
+}
+function querySnapshot(value) {
+    if (!("docs" in value))
+        throw new Error("Firestore returned a document snapshot for a query");
+    return value;
+}
+function scopeHash(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function pageKey(updatedAt, id) {
+    return `${updatedAt}|${id}`;
+}
+function encodeCursor(value) {
+    return Buffer.from(value).toString("base64url");
+}
+function decodeCursor(value) {
+    try {
+        const decoded = Buffer.from(value, "base64url").toString("utf8");
+        if (!/^\d{4}-\d{2}-\d{2}T.+\|.+$/.test(decoded))
+            throw new Error();
+        return decoded;
+    }
+    catch {
+        throw new Error("Invalid Firestore feedback cursor");
+    }
+}
+function event(type, threadId, messageId, author, occurredAt) {
+    return {
+        id: messageId ? `${type}:${messageId}` : `${type}:${threadId}:${occurredAt}`,
+        type,
+        occurredAt,
+        threadId,
+        messageId,
+        author,
+    };
+}
+//# sourceMappingURL=firestore.js.map