@webority/insights-react 0.0.0-stage → 0.65.0

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) Webority Technologies. All rights reserved.
+
+This software and its source code are proprietary and confidential to
+Webority Technologies. Use is restricted to Webority products and teams under
+internal license. Redistribution outside Webority Technologies is prohibited.

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# @webority/insights-react
 
-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.
+Product feedback for a React portal: the one NPS question and a feedback button. Both post to the
+product's feedback API, which the product's backend hosts through Webority.Insights. It is built on
+`@webority/ui-react`, so it looks like the rest of the portal with no extra CSS.
+
+## Install
+
+```bash
+npm install @webority/insights-react @webority/ui-react react-bootstrap bootstrap@5.3.3
+```
+
+`@webority/ui-react`, `react`, `react-dom`, `react-bootstrap` and `bootstrap` are peer
+dependencies: the portal already has them. Pin `@webority/insights-react` to the same exact
+version as `@webority/ui-react`.
+
+## Set up the provider
+
+Give the provider a client built on the portal's own signed-in HTTP instance. That instance already
+carries the bearer token and refreshes it, so the feedback calls sign in the same way as every
+other call.
+
+```jsx
+import { createInsightsFeedbackClient, InsightsFeedbackProvider } from "@webority/insights-react";
+import { userClient } from "./services/api/clients";
+
+const feedbackClient = createInsightsFeedbackClient(userClient);
+
+export function App() {
+    return (
+        <InsightsFeedbackProvider client={feedbackClient}>
+            <Routes />
+        </InsightsFeedbackProvider>
+    );
+}
+```
+
+`createInsightsFeedbackClient(http, options)` accepts any axios-like instance. `options.prefix`
+replaces the API prefix, which defaults to `/api/insights/feedback`. The client returns
+`{ getNps(), answerNps(body), leaveComment(body) }`. Every method rejects with an
+`InsightsFeedbackApiError` carrying `code`, `status` and a `message` written for the person, which
+the components show as-is.
+
+## Components
+
+### `<NpsPrompt />`
+
+The "how likely are you to recommend us" question. It asks the server once per mount whether the
+question is due, and renders nothing while it loads, when it is not due, or when that read fails.
+When it is due it shows a 0 to 10 scale, a comment box once a score is chosen, Send and Not now.
+Send thanks the person. Not now is a permanent answer: the server records it and the question does
+not come back.
+
+```jsx
+<NpsPrompt question="How likely are you to recommend us to a colleague?" />
+```
+
+| Prop | Default |
+|---|---|
+| `question` | "How likely are you to recommend us to a colleague?" |
+| `lowLabel` | "Not likely" |
+| `highLabel` | "Very likely" |
+| `commentLabel` | "What is the main reason for your score? (optional)" |
+| `sendLabel` | "Send" |
+| `notNowLabel` | "Not now" |
+| `thanks` | "Thanks for your feedback." |
+
+### `<FeedbackButton />`
+
+A button that opens a drawer with one comment box. Send posts the comment with the page it was
+written on, then thanks the person. The page path is read when the person sends, unless `pagePath`
+is given.
+
+```jsx
+<FeedbackButton label="Feedback" />
+```
+
+| Prop | Default |
+|---|---|
+| `label` | "Feedback" |
+| `title` | "Send us feedback" |
+| `placeholder` | "Tell us what works and what does not" |
+| `sendLabel` | "Send" |
+| `thanks` | "Thanks, we read every message." |
+| `pagePath` | the current `window.location.pathname` at send time |
+
+## The wire contract
+
+The prefix defaults to `/api/insights/feedback`. Errors are a JSON body `{ code, message }`.
+
+| Method and route | Request body | Response |
+|---|---|---|
+| `GET {prefix}/nps` | none | `{ due, trigger }` |
+| `POST {prefix}/nps` | `{ trigger, score: number or null, comment?: string or null }` | 204. A `score` of `null` is a permanent "not now". |
+| `POST {prefix}/comments` | `{ comment, pagePath?: string or null }` | 204 |
+
+## The X-Webority-Surface header
+
+Every POST sends the header `X-Webority-Surface: Web`, so the server can tell the portal's answers
+from the other surfaces'. The GET does not send it.
+
+## Server side
+
+The server side is Webority.Insights.AspNetCore's `MapWeborityInsightsFeedbackEndpoints`, which maps
+the three routes above under the product's prefix.

package/dist/insights-react.js

@@ -0,0 +1 @@
+import{AppAlert as e,AppButton as t,AppCard as n,AppDrawer as r,AppScoreScale as i,AppTextarea as a}from"@webority/ui-react";import{createContext as o,useContext as s,useEffect as c,useMemo as l,useRef as u,useState as d}from"react";import{Fragment as f,jsx as p,jsxs as m}from"react/jsx-runtime";var h=`/api/insights/feedback`,g=`Something went wrong. Please try again.`,_={headers:{"X-Webority-Surface":`Web`}},v=class extends Error{constructor(e,t,n){super(t),this.name=`InsightsFeedbackApiError`,this.code=e,this.status=n}};async function y(e){if(e&&typeof Blob<`u`&&e instanceof Blob)try{return JSON.parse(await e.text())}catch{return null}if(typeof e==`string`)try{return JSON.parse(e)}catch{return null}return e??null}async function b(e){if(e instanceof v)return e;let t=e?.response;if(!t)return new v(`network`,g);let n=await y(t.data);return new v(typeof n?.code==`string`&&n.code?n.code:`unknown`,typeof n?.message==`string`&&n.message?n.message:g,t.status)}async function x(e){try{return(await e()).data}catch(e){throw await b(e)}}function S(e,t={}){let n=(t.prefix??h).replace(/\/+$/,``);return{getNps:()=>x(()=>e.get(`${n}/nps`)),answerNps:t=>x(()=>e.post(`${n}/nps`,t,_)),leaveComment:t=>x(()=>e.post(`${n}/comments`,t,_))}}var C=o(null);function w(){let e=s(C);if(!e)throw Error(`InsightsFeedbackProvider is missing.`);return e.client}var T=1e3;function E({label:n=`Feedback`,title:i=`Send us feedback`,placeholder:o=`Tell us what works and what does not`,sendLabel:s=`Send`,thanks:c=`Thanks, we read every message.`,pagePath:l}){let u=w(),[h,g]=d(!1),[_,v]=d(``),[y,b]=d(!1),[x,S]=d(!1),[C,E]=d(null);function D(){S(!1),E(null),g(!0)}async function O(){b(!0),E(null);try{await u.leaveComment({comment:_.trim(),pagePath:l??window.location.pathname}),v(``),S(!0)}catch(e){E(e)}finally{b(!1)}}let k=x?null:p(`div`,{className:`d-flex justify-content-end w-100`,children:p(t,{variant:`primary`,onClick:O,disabled:_.trim()===``||y,loading:y,children:s})});return m(f,{children:[p(t,{variant:`outline`,onClick:D,children:n}),p(r,{open:h,onClose:()=>g(!1),title:i,footer:k,children:x?p(`p`,{role:`status`,className:`mb-0`,children:c}):m(f,{children:[p(a,{"aria-label":i,placeholder:o,rows:5,maxLength:T,value:_,disabled:y,onChange:e=>v(e.target.value)}),C&&p(e,{variant:`danger`,children:C.message})]})})]})}function D({client:e,children:t}){let n=l(()=>({client:e}),[e]);return p(C.Provider,{value:n,children:t})}var O=1e3;function k({question:r=`How likely are you to recommend us to a colleague?`,lowLabel:o=`Not likely`,highLabel:s=`Very likely`,commentLabel:l=`What is the main reason for your score? (optional)`,sendLabel:f=`Send`,notNowLabel:h=`Not now`,thanks:g=`Thanks for your feedback.`}){let _=w(),[v,y]=d(`loading`),[b,x]=d(null),[S,C]=d(null),[T,E]=d(``),[D,k]=d(!1),[A,j]=d(null),M=u(!1);c(()=>{M.current||(M.current=!0,_.getNps().then(e=>{e?.due?(x(e.trigger),y(`asking`)):y(`closed`)},()=>y(`closed`)))},[_]);async function N(e){k(!0),j(null);try{return await _.answerNps({trigger:b,...e}),!0}catch(e){return j(e),!1}finally{k(!1)}}async function P(){let e=T.trim();await N({score:S,comment:e||null})&&y(`thanked`)}async function F(){await N({score:null})&&y(`closed`)}return v===`loading`||v===`closed`?null:v===`thanked`?p(n,{children:p(`p`,{role:`status`,className:`mb-0`,children:g})}):m(n,{children:[p(i,{name:`nps-score`,value:S,onChange:C,min:0,max:10,label:r,lowLabel:o,highLabel:s,disabled:D}),S!==null&&p(a,{label:l,rows:2,maxLength:O,value:T,disabled:D,onChange:e=>E(e.target.value)}),A&&p(e,{variant:`danger`,children:A.message}),m(`div`,{className:`d-flex gap-2 mt-3`,children:[p(t,{variant:`primary`,onClick:P,disabled:S===null||D,loading:D,children:f}),p(t,{variant:`secondary`,onClick:F,disabled:D,children:h})]})]})}export{E as FeedbackButton,v as InsightsFeedbackApiError,D as InsightsFeedbackProvider,k as NpsPrompt,S as createInsightsFeedbackClient};

package/dist/types/FeedbackButton.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A button that opens a drawer with one box for a comment. The comment is sent with the current
+ * page path, unless `pagePath` is given.
+ *
+ * @param {object} props
+ * @param {string} [props.label="Feedback"] The button text.
+ * @param {string} [props.title="Send us feedback"] The drawer's heading.
+ * @param {string} [props.placeholder="Tell us what works and what does not"]
+ * @param {string} [props.sendLabel="Send"]
+ * @param {string} [props.thanks="Thanks, we read every message."]
+ * @param {string|null} [props.pagePath] The page the comment is about. Defaults to the current path, read when sent.
+ */
+export default function FeedbackButton({ label, title, placeholder, sendLabel, thanks, pagePath, }: {
+    label?: string;
+    title?: string;
+    placeholder?: string;
+    sendLabel?: string;
+    thanks?: string;
+    pagePath?: string | null;
+}): import("react").JSX.Element;

package/dist/types/InsightsFeedbackProvider.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Makes a feedback client available to the NPS question and the feedback button below it.
+ *
+ * @param {object} props
+ * @param {import('./client.js').InsightsFeedbackClient} props.client From `createInsightsFeedbackClient(http)`.
+ * @param {import('react').ReactNode} props.children
+ */
+export default function InsightsFeedbackProvider({ client, children }: {
+    client: import('./client.js').InsightsFeedbackClient;
+    children: import('react').ReactNode;
+}): import("react").JSX.Element;

package/dist/types/NpsPrompt.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The one "how likely are you to recommend us" question. It asks once per mount, and only when
+ * the server says it is due. Send posts the score and an optional comment; Not now is a permanent
+ * answer the server records, so the question does not come back.
+ *
+ * @param {object} props
+ * @param {string} [props.question="How likely are you to recommend us to a colleague?"]
+ * @param {string} [props.lowLabel="Not likely"]
+ * @param {string} [props.highLabel="Very likely"]
+ * @param {string} [props.commentLabel="What is the main reason for your score? (optional)"]
+ * @param {string} [props.sendLabel="Send"]
+ * @param {string} [props.notNowLabel="Not now"]
+ * @param {string} [props.thanks="Thanks for your feedback."]
+ */
+export default function NpsPrompt({ question, lowLabel, highLabel, commentLabel, sendLabel, notNowLabel, thanks, }: {
+    question?: string;
+    lowLabel?: string;
+    highLabel?: string;
+    commentLabel?: string;
+    sendLabel?: string;
+    notNowLabel?: string;
+    thanks?: string;
+}): import("react").JSX.Element;

package/dist/types/client.d.ts

@@ -0,0 +1,91 @@
+/**
+ * A failed feedback request. `message` is written for the person and is safe to show as-is.
+ */
+export declare class InsightsFeedbackApiError extends Error {
+    code: string;
+    status: number;
+    /**
+     * @param {string} code Machine-readable reason from the API, or "network" when no response arrived.
+     * @param {string} message The sentence to show the person.
+     * @param {number} [status] HTTP status, when a response arrived.
+     */
+    constructor(code: string, message: string, status?: number);
+}
+export type InsightsHttp = {
+    get: (url: string, config?: object) => Promise<{
+        data: any;
+    }>;
+    post: (url: string, data?: any, config?: object) => Promise<{
+        data: any;
+    }>;
+};
+export type NpsState = {
+    /**
+     * Whether the question should be asked now.
+     */
+    due: boolean;
+    /**
+     * The server's reason for asking; sent back with the answer.
+     */
+    trigger: string;
+};
+export type NpsAnswer = {
+    /**
+     * The `trigger` the question was asked with.
+     */
+    trigger: string;
+    /**
+     * 0 to 10, or null for a permanent "not now".
+     */
+    score: number | null;
+    comment?: string | null;
+};
+export type CommentInput = {
+    comment: string;
+    /**
+     * The page the comment is about; the component sends the current path.
+     */
+    pagePath?: string | null;
+};
+export type InsightsFeedbackClient = {
+    getNps: () => Promise<NpsState>;
+    answerNps: (body: NpsAnswer) => Promise<void>;
+    leaveComment: (body: CommentInput) => Promise<void>;
+};
+/**
+ * @typedef {object} InsightsHttp An axios-like HTTP client that already carries the bearer token.
+ * @property {(url: string, config?: object) => Promise<{ data: any }>} get
+ * @property {(url: string, data?: any, config?: object) => Promise<{ data: any }>} post
+ */
+/**
+ * @typedef {object} NpsState What the server says about the question for this person.
+ * @property {boolean} due Whether the question should be asked now.
+ * @property {string} trigger The server's reason for asking; sent back with the answer.
+ */
+/**
+ * @typedef {object} NpsAnswer
+ * @property {string} trigger The `trigger` the question was asked with.
+ * @property {number|null} score 0 to 10, or null for a permanent "not now".
+ * @property {string|null} [comment]
+ */
+/**
+ * @typedef {object} CommentInput
+ * @property {string} comment
+ * @property {string|null} [pagePath] The page the comment is about; the component sends the current path.
+ */
+/**
+ * @typedef {object} InsightsFeedbackClient
+ * @property {() => Promise<NpsState>} getNps
+ * @property {(body: NpsAnswer) => Promise<void>} answerNps
+ * @property {(body: CommentInput) => Promise<void>} leaveComment
+ */
+/**
+ * Binds the feedback HTTP contract to the product's own authenticated client.
+ *
+ * @param {import('axios').AxiosInstance} http The product's signed-in axios client (web-core userClient).
+ * @param {{ prefix?: string }} [options] `prefix` overrides the API prefix, which defaults to /api/insights/feedback.
+ * @returns {InsightsFeedbackClient}
+ */
+export declare function createInsightsFeedbackClient(http: import('axios').AxiosInstance, options?: {
+    prefix?: string;
+}): InsightsFeedbackClient;

package/dist/types/context.d.ts

@@ -0,0 +1,10 @@
+/** @type {import('react').Context<{ client: import('./client.js').InsightsFeedbackClient } | null>} */
+export declare const InsightsFeedbackContext: import('react').Context<{
+    client: import('./client.js').InsightsFeedbackClient;
+} | null>;
+/**
+ * The feedback client the nearest InsightsFeedbackProvider holds. Internal to the package.
+ *
+ * @returns {import('./client.js').InsightsFeedbackClient}
+ */
+export declare function useInsightsFeedbackClient(): import('./client.js').InsightsFeedbackClient;

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export { createInsightsFeedbackClient, InsightsFeedbackApiError } from "./client.js";
+export { default as FeedbackButton } from "./FeedbackButton.jsx";
+export { default as InsightsFeedbackProvider } from "./InsightsFeedbackProvider.jsx";
+export { default as NpsPrompt } from "./NpsPrompt.jsx";

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@webority/insights-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.65.0",
+  "description": "Webority product feedback for React portals: the NPS question and a feedback button that post to the product's Webority.Insights feedback API, built on @webority/ui-react.",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist",
+    "!dist/**/__tests__",
+    "!dist/**/*.test.*",
+    "!dist/**/*.map"
+  ],
+  "main": "./dist/insights-react.js",
+  "module": "./dist/insights-react.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/insights-react.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "bootstrap": "5.3.3",
+    "react": "^19.0.0",
+    "react-bootstrap": "^2.10.0",
+    "react-dom": "^19.0.0",
+    "@webority/ui-react": "0.65.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "10.4.2",
+    "@testing-library/jest-dom": "7.0.1",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.2.17",
+    "@vitejs/plugin-react": "^6.0.1",
+    "@vitest/coverage-v8": "5.0.1",
+    "bootstrap": "5.3.3",
+    "jsdom": "30.1.1",
+    "react": "^19.2.6",
+    "react-bootstrap": "^2.10.6",
+    "react-dom": "^19.2.6",
+    "typescript": "^7.0.2",
+    "vite": "^8.0.12",
+    "vitest": "5.0.1",
+    "@webority/ui-react": "0.65.0"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
 }