@pinpoint-feedback/nextjs 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pinpoint Feedback 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

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @pinpoint-feedback/nextjs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Next.js App Router integration: FeedbackProvider and createFeedbackHandler.
+
+Part of [Pinpoint Feedback](https://github.com/dwrth/pinpoint-feedback): visual website feedback that lands in Notion. Most apps install the umbrella package instead:
+
+```bash
+npm install pinpoint-feedback
+```
+
+Docs: https://github.com/dwrth/pinpoint-feedback#docs

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import type { CategoryList } from "@pinpoint-feedback/core";
+import { type ReactElement } from "react";
+import { type DefaultCategoryList, type FeedbackProviderProps, type FeedbackWidgetProps } from "@pinpoint-feedback/react";
+export { useFeedback } from "@pinpoint-feedback/react";
+export type { CategoryColor, CategoryDefinition, CategoryId, CategoryInput, CategoryList, DefaultCategoryList, FeedbackController, FeedbackProviderProps, FeedbackWidgetError, FeedbackWidgetPosition, FeedbackWidgetProps, FeedbackWidgetTheme, LocaleBundle, LocaleOverrides, TextDirection, } from "@pinpoint-feedback/react";
+export declare const DEFAULT_FEEDBACK_ENDPOINT = "/api/feedback";
+/**
+ * Feedback widget for the Next.js App Router. Can be rendered directly from a Server
+ * Component layout; `children` are optional.
+ *
+ * Pass `categories` as a plain array (e.g. from a shared `feedback.config.ts` built with
+ * `defineCategories` from `"pinpoint-feedback"`) so the same list reaches the route handler.
+ *
+ * Locale bundles are plain data, so they can be imported in the Server Component and passed down:
+ *
+ * ```tsx
+ * import de from "pinpoint-feedback/locales/de";
+ *
+ * <FeedbackProvider position="bottom-right" theme="light" categories={categories} defaultCategory="bug" locale={de} />
+ * ```
+ */
+export declare function FeedbackProvider<const C extends CategoryList = DefaultCategoryList>(props: FeedbackProviderProps<C>): ReactElement;
+export declare function FeedbackWidget<const C extends CategoryList = DefaultCategoryList>(props: FeedbackWidgetProps<C>): ReactElement;

package/dist/index.js

@@ -0,0 +1,51 @@
+"use client";
+import { createElement } from "react";
+import { FeedbackProvider as FeedbackProvider$1, FeedbackWidget as FeedbackWidget$1, useFeedback } from "@pinpoint-feedback/react";
+// src/index.ts
+var DEFAULT_FEEDBACK_ENDPOINT = "/api/feedback";
+/**
+* `process.env.NEXT_PUBLIC_*` must be accessed literally so that Next.js can inline the
+* values into the client bundle at build time.
+*/
+function readPublicEnv() {
+	try {
+		return {
+			endpoint: process.env.NEXT_PUBLIC_PINPOINT_ENDPOINT || void 0,
+			projectId: process.env.NEXT_PUBLIC_PINPOINT_PROJECT_ID || void 0
+		};
+	} catch {
+		return {};
+	}
+}
+function withDefaults(props) {
+	const env = readPublicEnv();
+	return {
+		...props,
+		endpoint: props.endpoint ?? env.endpoint ?? "/api/feedback",
+		projectId: props.projectId ?? env.projectId
+	};
+}
+/**
+* Feedback widget for the Next.js App Router. Can be rendered directly from a Server
+* Component layout; `children` are optional.
+*
+* Pass `categories` as a plain array (e.g. from a shared `feedback.config.ts` built with
+* `defineCategories` from `"pinpoint-feedback"`) so the same list reaches the route handler.
+*
+* Locale bundles are plain data, so they can be imported in the Server Component and passed down:
+*
+* ```tsx
+* import de from "pinpoint-feedback/locales/de";
+*
+* <FeedbackProvider position="bottom-right" theme="light" categories={categories} defaultCategory="bug" locale={de} />
+* ```
+*/
+function FeedbackProvider(props) {
+	return createElement(FeedbackProvider$1, withDefaults(props));
+}
+function FeedbackWidget(props) {
+	return createElement(FeedbackWidget$1, withDefaults(props));
+}
+export { DEFAULT_FEEDBACK_ENDPOINT, FeedbackProvider, FeedbackWidget, useFeedback };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["BaseFeedbackProvider","BaseFeedbackWidget"],"sources":["../src/index.ts"],"sourcesContent":["// Client boundary: vite.config.ts prepends the \"use client\" directive to the built entry.\nimport type { CategoryList } from \"@pinpoint-feedback/core\";\nimport { createElement, type ReactElement } from \"react\";\nimport {\n  FeedbackProvider as BaseFeedbackProvider,\n  FeedbackWidget as BaseFeedbackWidget,\n  type DefaultCategoryList,\n  type FeedbackProviderProps,\n  type FeedbackWidgetProps,\n} from \"@pinpoint-feedback/react\";\n\nexport { useFeedback } from \"@pinpoint-feedback/react\";\nexport type {\n  CategoryColor,\n  CategoryDefinition,\n  CategoryId,\n  CategoryInput,\n  CategoryList,\n  DefaultCategoryList,\n  FeedbackController,\n  FeedbackProviderProps,\n  FeedbackWidgetError,\n  FeedbackWidgetPosition,\n  FeedbackWidgetProps,\n  FeedbackWidgetTheme,\n  LocaleBundle,\n  LocaleOverrides,\n  TextDirection,\n} from \"@pinpoint-feedback/react\";\n\nexport const DEFAULT_FEEDBACK_ENDPOINT = \"/api/feedback\";\n\n/**\n * `process.env.NEXT_PUBLIC_*` must be accessed literally so that Next.js can inline the\n * values into the client bundle at build time.\n */\nfunction readPublicEnv(): { endpoint?: string; projectId?: string } {\n  try {\n    return {\n      endpoint: process.env.NEXT_PUBLIC_PINPOINT_ENDPOINT || undefined,\n      projectId: process.env.NEXT_PUBLIC_PINPOINT_PROJECT_ID || undefined,\n    };\n  } catch {\n    return {};\n  }\n}\n\nfunction withDefaults<P extends FeedbackWidgetProps<CategoryList>>(props: P): P {\n  const env = readPublicEnv();\n  return {\n    ...props,\n    endpoint: props.endpoint ?? env.endpoint ?? DEFAULT_FEEDBACK_ENDPOINT,\n    projectId: props.projectId ?? env.projectId,\n  };\n}\n\n/**\n * Feedback widget for the Next.js App Router. Can be rendered directly from a Server\n * Component layout; `children` are optional.\n *\n * Pass `categories` as a plain array (e.g. from a shared `feedback.config.ts` built with\n * `defineCategories` from `\"pinpoint-feedback\"`) so the same list reaches the route handler.\n *\n * Locale bundles are plain data, so they can be imported in the Server Component and passed down:\n *\n * ```tsx\n * import de from \"pinpoint-feedback/locales/de\";\n *\n * <FeedbackProvider position=\"bottom-right\" theme=\"light\" categories={categories} defaultCategory=\"bug\" locale={de} />\n * ```\n */\nexport function FeedbackProvider<const C extends CategoryList = DefaultCategoryList>(\n  props: FeedbackProviderProps<C>,\n): ReactElement {\n  return createElement(BaseFeedbackProvider<C>, withDefaults(props));\n}\n\nexport function FeedbackWidget<const C extends CategoryList = DefaultCategoryList>(\n  props: FeedbackWidgetProps<C>,\n): ReactElement {\n  return createElement(BaseFeedbackWidget<C>, withDefaults(props));\n}\n"],"mappings":";;;;AA8BA,IAAa,4BAA4B;;;;;AAMzC,SAAS,gBAA2D;CAClE,IAAI;EACF,OAAO;GACL,UAAU,QAAQ,IAAI,iCAAiC,KAAA;GACvD,WAAW,QAAQ,IAAI,mCAAmC,KAAA;EAC5D;CACF,QAAQ;EACN,OAAO,CAAC;CACV;AACF;AAEA,SAAS,aAA0D,OAAa;CAC9E,MAAM,MAAM,cAAc;CAC1B,OAAO;EACL,GAAG;EACH,UAAU,MAAM,YAAY,IAAI,YAAA;EAChC,WAAW,MAAM,aAAa,IAAI;CACpC;AACF;;;;;;;;;;;;;;;;AAiBA,SAAgB,iBACd,OACc;CACd,OAAO,cAAcA,oBAAyB,aAAa,KAAK,CAAC;AACnE;AAEA,SAAgB,eACd,OACc;CACd,OAAO,cAAcC,kBAAuB,aAAa,KAAK,CAAC;AACjE"}

package/dist/server.d.ts

@@ -0,0 +1,33 @@
+import "server-only";
+import { type FeedbackHandlerOptions } from "@pinpoint-feedback/server";
+export type { FeedbackHandlerOptions } from "@pinpoint-feedback/server";
+export type FeedbackRouteHandler = (request: Request) => Promise<Response>;
+export interface NextFeedbackHandlerOptions extends Partial<FeedbackHandlerOptions> {
+    /** Environment to read Notion settings from. Defaults to `process.env`, read on the first request. */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Creates a Next.js route handler for feedback submissions.
+ *
+ * Notion credentials are read from `NOTION_API_KEY` / `NOTION_FEEDBACK_DATABASE_ID`
+ * (plus optional `NOTION_API_BASE_URL` and `PINPOINT_PROJECT_ID`) when the first request
+ * arrives, so `next build` works without them. Explicit options take precedence.
+ *
+ * ```ts
+ * // app/api/feedback/route.ts
+ * export const POST = createFeedbackHandler();
+ * ```
+ */
+export declare function createFeedbackHandler(options?: NextFeedbackHandlerOptions): FeedbackRouteHandler;
+/**
+ * Same as {@link createFeedbackHandler}, returned as `{ POST, OPTIONS }` sharing one handler,
+ * for endpoints that receive cross-origin submissions (see `allowedOrigins`).
+ *
+ * ```ts
+ * export const { POST, OPTIONS } = createFeedbackRouteHandlers({ allowedOrigins: ["https://example.com"] });
+ * ```
+ */
+export declare function createFeedbackRouteHandlers(options?: NextFeedbackHandlerOptions): {
+    POST: FeedbackRouteHandler;
+    OPTIONS: FeedbackRouteHandler;
+};

package/dist/server.js

@@ -0,0 +1,98 @@
+import "server-only";
+import { createFeedbackRequestHandler, resolveNotionConfigFromEnv } from "@pinpoint-feedback/server";
+// src/server.ts
+function readProcessEnv() {
+	return typeof process !== "undefined" && process.env ? process.env : {};
+}
+function resolveOptions({ env, ...options }) {
+	if (options.backend) return {
+		ok: true,
+		options
+	};
+	const source = env ?? readProcessEnv();
+	const hasExplicitNotion = Boolean(options.notion?.apiKey && options.notion?.databaseId);
+	let fromEnv;
+	try {
+		fromEnv = resolveNotionConfigFromEnv(source);
+	} catch (error) {
+		if (!hasExplicitNotion) return {
+			ok: false,
+			message: error instanceof Error ? error.message : String(error)
+		};
+	}
+	const { projectId: envProjectId, ...envNotion } = fromEnv ?? {};
+	const notion = {
+		...envNotion,
+		...options.notion
+	};
+	return {
+		ok: true,
+		options: {
+			...options,
+			notion,
+			projectId: options.projectId ?? envProjectId
+		}
+	};
+}
+function misconfigured() {
+	return Response.json({
+		ok: false,
+		error: {
+			code: "misconfigured",
+			message: "The feedback service is not configured. Please contact the site owner.",
+			retryable: false
+		}
+	}, {
+		status: 500,
+		headers: { "cache-control": "no-store" }
+	});
+}
+/**
+* Creates a Next.js route handler for feedback submissions.
+*
+* Notion credentials are read from `NOTION_API_KEY` / `NOTION_FEEDBACK_DATABASE_ID`
+* (plus optional `NOTION_API_BASE_URL` and `PINPOINT_PROJECT_ID`) when the first request
+* arrives, so `next build` works without them. Explicit options take precedence.
+*
+* ```ts
+* // app/api/feedback/route.ts
+* export const POST = createFeedbackHandler();
+* ```
+*/
+function createFeedbackHandler(options = {}) {
+	let handler;
+	return async function feedbackRouteHandler(request) {
+		if (!handler) {
+			const resolved = resolveOptions(options);
+			if (!resolved.ok) {
+				(options.logger ?? console).error(`[pinpoint-feedback] ${resolved.message}`);
+				return misconfigured();
+			}
+			try {
+				handler = createFeedbackRequestHandler(resolved.options);
+			} catch (error) {
+				(options.logger ?? console).error("[pinpoint-feedback] Failed to create feedback handler", error);
+				return misconfigured();
+			}
+		}
+		return handler(request);
+	};
+}
+/**
+* Same as {@link createFeedbackHandler}, returned as `{ POST, OPTIONS }` sharing one handler,
+* for endpoints that receive cross-origin submissions (see `allowedOrigins`).
+*
+* ```ts
+* export const { POST, OPTIONS } = createFeedbackRouteHandlers({ allowedOrigins: ["https://example.com"] });
+* ```
+*/
+function createFeedbackRouteHandlers(options = {}) {
+	const handler = createFeedbackHandler(options);
+	return {
+		POST: handler,
+		OPTIONS: handler
+	};
+}
+export { createFeedbackHandler, createFeedbackRouteHandlers };
+
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","names":[],"sources":["../src/server.ts"],"sourcesContent":["import \"server-only\";\n\nimport {\n  createFeedbackRequestHandler,\n  resolveNotionConfigFromEnv,\n  type FeedbackHandlerOptions,\n} from \"@pinpoint-feedback/server\";\nimport type { SubmissionFailure } from \"@pinpoint-feedback/core\";\n\nexport type { FeedbackHandlerOptions } from \"@pinpoint-feedback/server\";\n\nexport type FeedbackRouteHandler = (request: Request) => Promise<Response>;\n\nexport interface NextFeedbackHandlerOptions extends Partial<FeedbackHandlerOptions> {\n  /** Environment to read Notion settings from. Defaults to `process.env`, read on the first request. */\n  env?: Record<string, string | undefined>;\n}\n\ntype Resolved = { ok: true; options: FeedbackHandlerOptions } | { ok: false; message: string };\n\nfunction readProcessEnv(): Record<string, string | undefined> {\n  return typeof process !== \"undefined\" && process.env ? process.env : {};\n}\n\nfunction resolveOptions({ env, ...options }: NextFeedbackHandlerOptions): Resolved {\n  if (options.backend) return { ok: true, options: options as FeedbackHandlerOptions };\n\n  const source = env ?? readProcessEnv();\n  const hasExplicitNotion = Boolean(options.notion?.apiKey && options.notion?.databaseId);\n  let fromEnv: ReturnType<typeof resolveNotionConfigFromEnv> | undefined;\n  try {\n    fromEnv = resolveNotionConfigFromEnv(source);\n  } catch (error) {\n    if (!hasExplicitNotion) return { ok: false, message: error instanceof Error ? error.message : String(error) };\n  }\n\n  const { projectId: envProjectId, ...envNotion } = fromEnv ?? {};\n  const notion = { ...envNotion, ...options.notion } as NonNullable<FeedbackHandlerOptions[\"notion\"]>;\n  return {\n    ok: true,\n    options: { ...options, notion, projectId: options.projectId ?? envProjectId } as FeedbackHandlerOptions,\n  };\n}\n\nfunction misconfigured(): Response {\n  const body: SubmissionFailure = {\n    ok: false,\n    error: {\n      code: \"misconfigured\",\n      message: \"The feedback service is not configured. Please contact the site owner.\",\n      retryable: false,\n    },\n  };\n  return Response.json(body, { status: 500, headers: { \"cache-control\": \"no-store\" } });\n}\n\n/**\n * Creates a Next.js route handler for feedback submissions.\n *\n * Notion credentials are read from `NOTION_API_KEY` / `NOTION_FEEDBACK_DATABASE_ID`\n * (plus optional `NOTION_API_BASE_URL` and `PINPOINT_PROJECT_ID`) when the first request\n * arrives, so `next build` works without them. Explicit options take precedence.\n *\n * ```ts\n * // app/api/feedback/route.ts\n * export const POST = createFeedbackHandler();\n * ```\n */\nexport function createFeedbackHandler(options: NextFeedbackHandlerOptions = {}): FeedbackRouteHandler {\n  let handler: FeedbackRouteHandler | undefined;\n\n  return async function feedbackRouteHandler(request: Request): Promise<Response> {\n    if (!handler) {\n      const resolved = resolveOptions(options);\n      if (!resolved.ok) {\n        (options.logger ?? console).error(`[pinpoint-feedback] ${resolved.message}`);\n        return misconfigured();\n      }\n      try {\n        handler = createFeedbackRequestHandler(resolved.options);\n      } catch (error) {\n        (options.logger ?? console).error(\"[pinpoint-feedback] Failed to create feedback handler\", error);\n        return misconfigured();\n      }\n    }\n    return handler(request);\n  };\n}\n\n/**\n * Same as {@link createFeedbackHandler}, returned as `{ POST, OPTIONS }` sharing one handler,\n * for endpoints that receive cross-origin submissions (see `allowedOrigins`).\n *\n * ```ts\n * export const { POST, OPTIONS } = createFeedbackRouteHandlers({ allowedOrigins: [\"https://example.com\"] });\n * ```\n */\nexport function createFeedbackRouteHandlers(options: NextFeedbackHandlerOptions = {}): {\n  POST: FeedbackRouteHandler;\n  OPTIONS: FeedbackRouteHandler;\n} {\n  const handler = createFeedbackHandler(options);\n  return { POST: handler, OPTIONS: handler };\n}\n"],"mappings":";;;AAoBA,SAAS,iBAAqD;CAC5D,OAAO,OAAO,YAAY,eAAe,QAAQ,MAAM,QAAQ,MAAM,CAAC;AACxE;AAEA,SAAS,eAAe,EAAE,KAAK,GAAG,WAAiD;CACjF,IAAI,QAAQ,SAAS,OAAO;EAAE,IAAI;EAAe;CAAkC;CAEnF,MAAM,SAAS,OAAO,eAAe;CACrC,MAAM,oBAAoB,QAAQ,QAAQ,QAAQ,UAAU,QAAQ,QAAQ,UAAU;CACtF,IAAI;CACJ,IAAI;EACF,UAAU,2BAA2B,MAAM;CAC7C,SAAS,OAAO;EACd,IAAI,CAAC,mBAAmB,OAAO;GAAE,IAAI;GAAO,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;EAAE;CAC9G;CAEA,MAAM,EAAE,WAAW,cAAc,GAAG,cAAc,WAAW,CAAC;CAC9D,MAAM,SAAS;EAAE,GAAG;EAAW,GAAG,QAAQ;CAAO;CACjD,OAAO;EACL,IAAI;EACJ,SAAS;GAAE,GAAG;GAAS;GAAQ,WAAW,QAAQ,aAAa;EAAa;CAC9E;AACF;AAEA,SAAS,gBAA0B;CASjC,OAAO,SAAS,KAAK;EAPnB,IAAI;EACJ,OAAO;GACL,MAAM;GACN,SAAS;GACT,WAAW;EACb;CAEmB,GAAM;EAAE,QAAQ;EAAK,SAAS,EAAE,iBAAiB,WAAW;CAAE,CAAC;AACtF;;;;;;;;;;;;;AAcA,SAAgB,sBAAsB,UAAsC,CAAC,GAAyB;CACpG,IAAI;CAEJ,OAAO,eAAe,qBAAqB,SAAqC;EAC9E,IAAI,CAAC,SAAS;GACZ,MAAM,WAAW,eAAe,OAAO;GACvC,IAAI,CAAC,SAAS,IAAI;IAChB,CAAC,QAAQ,UAAU,QAAA,CAAS,MAAM,uBAAuB,SAAS,SAAS;IAC3E,OAAO,cAAc;GACvB;GACA,IAAI;IACF,UAAU,6BAA6B,SAAS,OAAO;GACzD,SAAS,OAAO;IACd,CAAC,QAAQ,UAAU,QAAA,CAAS,MAAM,yDAAyD,KAAK;IAChG,OAAO,cAAc;GACvB;EACF;EACA,OAAO,QAAQ,OAAO;CACxB;AACF;;;;;;;;;AAUA,SAAgB,4BAA4B,UAAsC,CAAC,GAGjF;CACA,MAAM,UAAU,sBAAsB,OAAO;CAC7C,OAAO;EAAE,MAAM;EAAS,SAAS;CAAQ;AAC3C"}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@pinpoint-feedback/nextjs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Next.js App Router integration for Pinpoint Feedback.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dwrth/pinpoint-feedback.git",
+    "directory": "packages/nextjs"
+  },
+  "homepage": "https://github.com/dwrth/pinpoint-feedback#readme",
+  "bugs": {
+    "url": "https://github.com/dwrth/pinpoint-feedback/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@pinpoint-feedback/core": "0.1.0",
+    "@pinpoint-feedback/react": "0.1.0",
+    "@pinpoint-feedback/server": "0.1.0",
+    "server-only": "^0.0.1"
+  },
+  "peerDependencies": {
+    "next": ">=14.2.0",
+    "react": ">=18.2.0",
+    "react-dom": ">=18.2.0"
+  }
+}