surge-feedback

Reusable feedback widget and Next.js route handlers for sending customer feedback into a Surge-managed ticket API.

This package is designed for client applications that want:

• A drop-in React feedback widget
• Next.js App Router route handlers that proxy requests server-side
• Vendor API credentials and hostnames kept out of the browser

The client widget is plain React and does not require MUI or Emotion.

Who Should Use This

Use this package when your application:

• Runs React 18+
• Uses Next.js App Router route handlers
• Can store server-side environment variables securely
• Wants the browser to post to its own /api/... routes instead of calling the upstream ticket API directly

Where It Works

This package works out of the box for:

• Next.js applications using app/api/.../route.js
• React client components that can render FeedbackDock
• Server environments where SURGE_TICKET_API_URL, SURGE_TICKET_API_APP_KEY, and SURGE_TICKET_API_SECRET are available at runtime

Where It Does Not Work

This package does not work as-is for:

• Browser-only apps with no server layer
• Static exports with no runtime route handlers
• Non-React frontends
• Next.js Pages Router API routes unless you build your own adapter using the lower-level surge-feedback/server exports
• Any setup that exposes SURGE_TICKET_API_URL, app keys, or secrets to the browser

Security Model

The upstream ticket API base URL is intentionally read from a server-side environment variable:

• SURGE_TICKET_API_URL

Do not expose this value with a NEXT_PUBLIC_ prefix. The browser should only talk to your application's own Next.js API routes.

Install

npm install surge-feedback

Required Environment Variables

Server-only:

SURGE_TICKET_API_URL=https://your-private-ticket-api.example.com
SURGE_TICKET_API_APP_KEY=replace-with-generated-app-key
SURGE_TICKET_API_SECRET=replace-with-generated-secret

Optional server-only:

SURGE_TICKET_API_TIMEOUT_MS=30000

Client:

NEXT_PUBLIC_ENABLE_FEEDBACK=true
NEXT_PUBLIC_APP_ENV=production

Optional client flags:

NEXT_PUBLIC_FEEDBACK_ENABLE_SCREENSHOT=true
NEXT_PUBLIC_FEEDBACK_ENABLE_VIDEO=true
NEXT_PUBLIC_FEEDBACK_ENABLE_MIC=true
NEXT_PUBLIC_FEEDBACK_MAX_ATTACHMENTS=5
NEXT_PUBLIC_FEEDBACK_MAX_FILE_SIZE_MB=100

Next.js App Router Setup

Create these route handlers in the consuming app.

// app/api/client-tickets/route.js
import { createCreateTicketHandler } from "surge-feedback/next";

export const POST = createCreateTicketHandler({ sourceApp: "your-app" });

// app/api/client-tickets/[ticketId]/attachments/init/route.js
import { createInitAttachmentHandler } from "surge-feedback/next";

export const POST = createInitAttachmentHandler();

// app/api/client-tickets/[ticketId]/attachments/complete/route.js
import { createCompleteAttachmentHandler } from "surge-feedback/next";

export const POST = createCompleteAttachmentHandler();

Client Setup

import { FeedbackDock } from "surge-feedback";

<FeedbackDock
  user={user}
  route={{
    pathname,
    search,
    hash,
    href,
  }}
  sourceApp="your-app"
/>

Runtime Notes

• The package default ticket priority is medium.
• The widget is enabled only when NEXT_PUBLIC_ENABLE_FEEDBACK=true.
• Attachment upload and ticket creation still depend on your upstream ticket API exposing the expected endpoints behind SURGE_TICKET_API_URL.

Publishing Changes

After editing this package locally:

cd /path/to/surge-feedback
npm version patch --no-git-tag-version
npm pack
npm publish

You must publish a new version. npm will not allow replacing an existing published version.