ai-app-feedback 0.1.0 → 0.2.1

package/PRODUCT.md

@@ -6,11 +6,11 @@ product
 
 ## Users
 
-Product teams and application users. Users are already inside a web app when they notice a bug, confusing workflow, broken visual state, or missing behavior. Developers and coding agents receive the report later and need enough context to reproduce and triage the issue quickly.
+Teams using internal applications. Teammates are already inside a web app when they notice a bug, confusing workflow, broken visual state, or missing behavior. Developers and coding agents receive the report later and need enough context to understand the feedback and decide what to do.
 
 ## Product Purpose
 
-`ai-app-feedback` gives Next.js apps an embeddable feedback assistant. It helps users describe what happened, captures recent navigation and browser context, optionally attaches a screenshot, and formats a developer-ready report that can be handed to an issue tracker or coding AI agent.
+`ai-app-feedback` gives Next.js apps a small feedback widget. Teammates choose Problem or Improvement and describe the request. Expected results and work impact are optional. The widget captures recent navigation and browser context, supports screenshots and image uploads, and emails a readable report with attached context for a coding agent. Replies to the notification reach the reporter, keeping follow-up in the team's existing email workflow.
 
 ## Brand Personality
 
@@ -23,10 +23,13 @@ Avoid marketing-style widgets, decorative motion, chat bubbles that pretend to b
 ## Design Principles
 
 - Capture context silently, ask users only for judgment and details.
+- Use the host application's authenticated session instead of asking signed-in users to identify themselves again.
 - Make privacy boundaries explicit, especially around screenshots and interaction history.
 - Prefer developer-ready structured reports over free-form message blobs.
 - Keep the widget small enough to live in production apps without becoming part of the app's visual identity.
 - Make framework integration thin, so core reporting remains portable and testable.
+- Keep one required text field. Do not require teammates to classify engineering categories, write acceptance criteria, or learn a separate tracking system.
+- Supply the original feedback and captured evidence. The receiving agent decides what to do; the report does not prescribe an implementation, workflow, or reply.
 
 ## Accessibility & Inclusion
 

package/README.md

@@ -1,6 +1,18 @@
 # ai-app-feedback
 
-A Next.js-ready feedback widget that helps users send useful reports and gives developers enough context to reproduce issues. It captures recent navigation, selected interaction events, browser context, optional screenshots, and a prompt formatted for coding AI triage.
+A Next.js-ready feedback widget for teams using internal applications. Teammates describe a problem or improvement; the widget captures context and emails a report that can be shared with a coding agent.
+
+## Team workflow
+
+1. Choose **Problem** or **Improvement** and describe it in one text box.
+2. Optionally expand **Add details** to describe the expected result (a concrete example helps with calculations) and the impact on your work. Attach screenshots or images as needed.
+3. Send. The confirmation includes the report's reference ID.
+4. The recipient gets an email whose subject describes the request. Share the attached `*-context.md`, `*-trace.json`, and images with the receiving agent as context.
+5. The receiving agent decides what to do using that context and its own instructions. Reply to the email to follow up with the reporter.
+
+Only the description is required. Email remains the handoff and follow-up channel; this package does not maintain a task inbox or automatically run an agent.
+
+Improvements use `category: "feature"`. Existing categories and severity values remain supported by the core API. The stock widget presents two choices and labels severity as work impact. `defaultCategory` still applies to problem reports; set it to `"feature"` to start with an improvement. Draft text survives closing and reopening the widget while it remains mounted, but is not persisted across reloads.
 
 ## Install
 
@@ -34,19 +46,85 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
-Create an endpoint that stores the report, forwards it to an issue tracker, or hands `developerPrompt` to your coding AI agent.
+The stock widget does not ask for an email. Pass the current Better Auth user to the provider so the client report is useful immediately; the endpoint below still resolves the session again and treats the server-side identity as authoritative.
+
+```tsx
+// components/app-feedback.tsx
+"use client";
+
+import { NextFeedbackProvider } from "ai-app-feedback/next";
+import { authClient } from "@/lib/auth-client";
+
+export function AppFeedback({ children }: { children: React.ReactNode }) {
+  const { data: session } = authClient.useSession();
+
+  return (
+    <NextFeedbackProvider
+      appId="vaster-agent"
+      endpoint="/api/feedback"
+      user={session?.user
+        ? {
+            id: session.user.id,
+            email: session.user.email,
+            name: session.user.name,
+          }
+        : undefined}
+    >
+      {children}
+    </NextFeedbackProvider>
+  );
+}
+```
+
+To show an email field in a public app instead, set `widgetProps={{ showEmailField: true }}`.
+
+## Authenticated SES notifications
+
+Install the AWS SES v2 client in the host app:
+
+```bash
+bun add @aws-sdk/client-sesv2
+```
+
+Create an authenticated endpoint. This example uses Better Auth directly; if your app wraps session lookup, call that wrapper from `getUser` instead.
 
 ```ts
 // app/api/feedback/route.ts
-import type { FeedbackReport } from "ai-app-feedback";
+import { auth } from "@/lib/auth";
+import { createFeedbackRouteHandler } from "ai-app-feedback/server";
+
+export const runtime = "nodejs";
 
-export async function POST(request: Request) {
-  const report = (await request.json()) as FeedbackReport;
+export const POST = createFeedbackRouteHandler({
+  getUser: async (request) => {
+    const session = await auth.api.getSession({ headers: request.headers });
+    return session?.user ?? null;
+  },
+});
+```
 
-  console.log(report.developerPrompt);
+Configure SES with the host's normal AWS credentials:
 
-  return Response.json({ ok: true });
-}
+```dotenv
+AWS_REGION=us-east-1
+FEEDBACK_EMAIL_FROM="Vaster Feedback <feedback@vaster.com>"
+# Optional. Defaults to dzuloaga@vaster.com.
+FEEDBACK_EMAIL_TO=dzuloaga@vaster.com
+```
+
+The route bounds the actual request body even when `Content-Length` is absent or inaccurate, validates nested report fields, rejects signed-out requests, overwrites client-supplied identity with the Better Auth session user, rebuilds the readable context, and sends the report through SES. The email body starts with the request and expected result. A Markdown context report includes the original feedback, browser context, metadata, and recent activity; the JSON attachment retains the structured trace. The captured screenshot and user-uploaded images are attached as viewable image files. Pass the image files alongside the context report: its text does not embed the image contents. Missing SES configuration or a delivery failure returns a non-success response, so the widget never says “Feedback sent” when no notification was delivered.
+
+Email subjects now use the request text rather than the route and severity. Update any mailbox rules that depend on the old subject format. Custom integrations that render their own email must adopt the updated formatter or attachment builder to get this handoff.
+
+Use `onReport` to persist the authenticated report or forward it to another system in addition to email:
+
+```ts
+export const POST = createFeedbackRouteHandler({
+  getUser: async (request) => (await getRequestSession(request))?.user,
+  onReport: async (report) => {
+    await saveFeedback(report);
+  },
+});
 ```
 
 ## Screenshot capture
@@ -66,6 +144,22 @@ import { createHtml2CanvasCapture } from "ai-app-feedback";
 </NextFeedbackProvider>;
 ```
 
+The widget also accepts up to three PNG, JPEG, WebP, or GIF uploads by default, with a 2 MB limit per image and across all uploads. Configure this through `widgetProps`:
+
+```tsx
+<NextFeedbackProvider
+  endpoint="/api/feedback"
+  widgetProps={{
+    allowImageUploads: true,
+    maxImageAttachments: 3,
+    maxImageBytes: 2_000_000,
+    maxTotalImageBytes: 2_000_000,
+  }}
+>
+  {children}
+</NextFeedbackProvider>
+```
+
 ## Core API
 
 Use the core session outside Next.js or with a custom UI.
@@ -94,7 +188,7 @@ await session.submit({
 - Click tracking stores a small element summary, not full DOM snapshots.
 - Screenshot capture is user-visible and permission-gated unless you provide a custom capture function.
 - URLs are captured in full by default; pass `scrubUrl` to strip query strings or tokens before they are recorded.
-- Reports include `developerPrompt`, a concise repro bundle intended for issue triage and coding agents.
+- Reports include `developerPrompt`, readable context with the original feedback and captured evidence. The existing `developerPrompt` field and `formatFeedbackForAgent` function names are retained for compatibility; their output contains no implementation plan, agent workflow, or suggested reply. User-controlled report fields are kept inside the untrusted-content block.
 
 ```tsx
 <NextFeedbackProvider
@@ -112,3 +206,31 @@ bun install
 bun test
 bun run build
 ```
+
+
+## Publishing
+
+The **Publish npm package** GitHub Actions workflow runs from `main`, using the
+`npm` environment restricted to that branch. npm trusts
+`Vastermortgage/ai-app-feedback`, workflow `publish.yml`, environment `npm`.
+It uses OIDC instead of a stored npm token; local npm login is not needed.
+
+Validate a release without publishing (the default):
+
+```bash
+gh workflow run publish.yml --ref main -f version=0.2.1 -F dry_run=true
+```
+
+After committing and pushing a version bump, release that exact version:
+
+```bash
+gh workflow run publish.yml --ref main -f version=0.2.1 -F dry_run=false
+```
+
+The workflow checks the requested version against `package.json`, installs the
+frozen lockfile, runs type checks and tests, builds the package, and validates
+its exports and React client boundaries before publishing. GitHub CLI access
+is required to trigger it, or use **Run workflow** in GitHub Actions.
+A dry run verifies the build and package contents; OIDC publishing authentication
+is exercised only by an actual release. This repository is private, so npm does
+not generate public build provenance for its releases.

package/dist/core/attachments.d.ts

@@ -0,0 +1,7 @@
+import type { FeedbackImageAttachment } from "./types";
+export declare const DEFAULT_IMAGE_MEDIA_TYPES: readonly ["image/jpeg", "image/png", "image/webp", "image/gif"];
+export interface ReadFeedbackImageOptions {
+    maxBytes?: number;
+    acceptedMediaTypes?: readonly string[];
+}
+export declare function readFeedbackImage(file: File, options?: ReadFeedbackImageOptions): Promise<FeedbackImageAttachment>;

package/dist/core/types.d.ts

@@ -3,7 +3,7 @@ export type JsonValue = JsonPrimitive | JsonValue[] | {
     [key: string]: JsonValue;
 };
 export type FeedbackSeverity = "low" | "medium" | "high" | "blocking";
-export type FeedbackCategory = "bug" | "ux" | "content" | "performance" | "accessibility" | "other";
+export type FeedbackCategory = "bug" | "feature" | "ux" | "content" | "performance" | "accessibility" | "other";
 export interface FeedbackUser {
     id?: string;
     email?: string;
@@ -66,6 +66,15 @@ export interface FeedbackScreenshot {
     capturedAt: string;
     source: "display-media" | "html2canvas" | "custom" | string;
 }
+export interface FeedbackImageAttachment {
+    id: string;
+    fileName: string;
+    mediaType: string;
+    size: number;
+    dataUrl: string;
+    attachedAt: string;
+    source: "upload" | string;
+}
 export interface FeedbackDraft {
     message: string;
     expected?: string;
@@ -73,6 +82,7 @@ export interface FeedbackDraft {
     category: FeedbackCategory;
     userEmail?: string;
     includeScreenshot?: boolean;
+    attachments?: FeedbackImageAttachment[];
     tags?: string[];
     metadata?: Record<string, JsonValue>;
 }
@@ -95,7 +105,9 @@ export interface FeedbackReport {
     navigation: NavigationEvent[];
     recentActivity: FeedbackTimelineEvent[];
     screenshot?: FeedbackScreenshot;
+    attachments?: FeedbackImageAttachment[];
     metadata: Record<string, JsonValue>;
+    /** Readable feedback context, without agent task instructions. Legacy field name. */
     developerPrompt: string;
 }
 export interface ScreenshotCaptureContext {

package/dist/core-entry.d.ts

@@ -1,9 +1,13 @@
 import { formatFeedbackForAgent as formatFeedbackForAgentImpl } from "./core/agent-prompt";
+import { readFeedbackImage as readFeedbackImageImpl } from "./core/attachments";
 import { captureVisibleTabWithDisplayMedia as captureVisibleTabWithDisplayMediaImpl, createHtml2CanvasCapture as createHtml2CanvasCaptureImpl } from "./core/screenshot";
 import { createFeedbackSession as createFeedbackSessionImpl } from "./core/session";
 export declare const captureVisibleTabWithDisplayMedia: typeof captureVisibleTabWithDisplayMediaImpl;
 export declare const createFeedbackSession: typeof createFeedbackSessionImpl;
 export declare const createHtml2CanvasCapture: typeof createHtml2CanvasCaptureImpl;
 export declare const formatFeedbackForAgent: typeof formatFeedbackForAgentImpl;
+export declare const DEFAULT_IMAGE_MEDIA_TYPES: readonly ["image/jpeg", "image/png", "image/webp", "image/gif"];
+export declare const readFeedbackImage: typeof readFeedbackImageImpl;
 export type { FeedbackSession } from "./core/session";
-export type { BrowserContext, ElementSummary, FeedbackCategory, FeedbackDraft, FeedbackReport, FeedbackScreenshot, FeedbackSessionOptions, FeedbackSeverity, FeedbackSubmitHandler, FeedbackTimelineEvent, FeedbackUser, JsonValue, NavigationEvent, RuntimeErrorEvent, ScreenshotCapture, ScreenshotCaptureContext, } from "./core/types";
+export type { BrowserContext, ElementSummary, FeedbackCategory, FeedbackDraft, FeedbackImageAttachment, FeedbackReport, FeedbackScreenshot, FeedbackSessionOptions, FeedbackSeverity, FeedbackSubmitHandler, FeedbackTimelineEvent, FeedbackUser, JsonValue, NavigationEvent, RuntimeErrorEvent, ScreenshotCapture, ScreenshotCaptureContext, } from "./core/types";
+export type { ReadFeedbackImageOptions } from "./core/attachments";