@bitvea/feedback-toolbar 0.0.1

package/dist/cli/strategies.js

@@ -0,0 +1,198 @@
+// How the provider gets into a host app, one strategy per install path.
+//
+// The spec asks for this explicitly: another framework, or another way of
+// mounting into Next.js, should be a new strategy rather than a rewrite of the
+// injector. So the orchestration in `init.ts` knows only this interface, and
+// the one strategy that exists here knows only App Router layouts.
+import { joinPath } from "./fs.js";
+export const PACKAGE_NAME = "@bitvea/feedback-toolbar";
+export const COMPONENT_NAME = "FeedbackToolbar";
+/** The file the script-tag route is served as, relative to the backend URL. */
+export const SCRIPT_BUNDLE_PATH = "/toolbar.js";
+/**
+ * The environment a script-tag install declares, when the developer has not
+ * said otherwise.
+ *
+ * The gate treats "absent" as off, and a static HTML file cannot know which
+ * deployment served it - so a tag with no `data-environment` mounts nothing,
+ * ever. That is the correct default for a value we could only guess, and the
+ * wrong default for an installer whose whole job is to leave a working
+ * install behind: #17 asks for a toolbar that mounts on a plain page with no
+ * build step, and a tag the developer has to hand-edit is not that.
+ *
+ * So `init` writes an environment, and the value is a review environment
+ * because installing a review tool on a page is what the command means. The
+ * result is printed as a change and called out as a note, and `--environment`
+ * overrides it - including with `production`, which is how somebody turns the
+ * tag off without removing it.
+ */
+export const DEFAULT_SCRIPT_ENVIRONMENT = "preview";
+/** Where an App Router root layout lives, most conventional first. */
+const APP_ROUTER_LAYOUTS = [
+    "app/layout.tsx",
+    "src/app/layout.tsx",
+    "app/layout.jsx",
+    "src/app/layout.jsx",
+];
+export const nextAppRouterStrategy = {
+    id: "next-app-router",
+    label: "Next.js App Router",
+    delivery: "npm-package",
+    detect(fs, root) {
+        for (const candidate of APP_ROUTER_LAYOUTS) {
+            const path = joinPath(root, candidate);
+            if (fs.exists(path)) {
+                return { path, description: `root layout at ${candidate}` };
+            }
+        }
+        return null;
+    },
+    isInstalled(source) {
+        // Both halves, because a half-installed file is what a failed earlier run
+        // would leave and re-running should finish it rather than skip it.
+        return (source.includes(PACKAGE_NAME) && source.includes(`<${COMPONENT_NAME}`));
+    },
+    inject(source, context) {
+        let out = source;
+        if (!out.includes(PACKAGE_NAME)) {
+            out = addImport(out);
+        }
+        if (!out.includes(`<${COMPONENT_NAME}`)) {
+            // The API URL goes in the MARKUP, not only into an env file, and that is
+            // the difference between an install that works after a deploy and one
+            // that silently does nothing.
+            //
+            // `init` writes `NEXT_PUBLIC_FEEDBACK_TOOLBAR_API_URL` into `.env.local`,
+            // which create-next-app gitignores - so on the host's next deploy the
+            // variable does not exist, `resolveConfig` leaves `enabled` false, and
+            // the deployed toolbar renders nothing. The developer sees no toolbar and
+            // no error, and nothing in the install told them to add the variable to
+            // their hosting provider by hand.
+            //
+            // The value is not a secret - it is a `NEXT_PUBLIC_` URL, and the
+            // script-tag route already writes the same value into a page - so
+            // committing it is exactly right. `resolveConfig` lets a prop beat the
+            // environment, which is what makes this deterministic; a developer who
+            // wants a different backend per environment deletes the prop and sets
+            // the variable in their hosting provider instead.
+            out = insertBeforeClosingBody(out, `<${COMPONENT_NAME} apiUrl="${context.apiUrl}" />`);
+        }
+        return out;
+    },
+};
+/** Where a plain HTML entry point lives, most conventional first. */
+const HTML_ENTRY_FILES = ["index.html", "public/index.html", "src/index.html"];
+/**
+ * The `<script src>` install, for an app with no build step to add a
+ * dependency to. Second in the list on purpose: an App Router app usually
+ * also has an index.html somewhere, and the npm install is the better one.
+ *
+ * Note what the injected tag does NOT carry: a deploy key. There is no
+ * supported way to put one in a page, and the bundle refuses to mount when it
+ * finds anything that looks like one - a key in a page is a key in every
+ * visitor's hands, and its whole power is creating projects.
+ *
+ * It does carry an environment, and it has to. A static file cannot know which
+ * deployment served it and the gate treats absent as off, so a tag without one
+ * mounts nothing at all - which is what #17's "mounts a working toolbar on a
+ * plain HTML page" cannot mean. The value is written, printed as a change, and
+ * called out as a note; `--environment production` is how a developer turns
+ * the tag off without deleting it. See DEFAULT_SCRIPT_ENVIRONMENT.
+ */
+export const htmlScriptTagStrategy = {
+    id: "html-script-tag",
+    label: "plain HTML page",
+    delivery: "script-tag",
+    detect(fs, root) {
+        for (const candidate of HTML_ENTRY_FILES) {
+            const path = joinPath(root, candidate);
+            if (fs.exists(path)) {
+                return { path, description: `HTML page at ${candidate}` };
+            }
+        }
+        return null;
+    },
+    isInstalled(source) {
+        return source.includes(SCRIPT_BUNDLE_PATH);
+    },
+    inject(source, context) {
+        if (!context.projectUrl) {
+            // Unlike the npm route, this one cannot fall back to reading the URL
+            // from the environment at runtime: a static page has no environment.
+            // Without it the toolbar would ask the backend about a project keyed on
+            // the empty string, so refuse rather than install something inert.
+            throw new InjectionError("a script-tag install needs the project's URL, and nothing here reports one.\n" +
+                "Re-run with --project-url https://myapp.com.");
+        }
+        const environment = context.environment ?? DEFAULT_SCRIPT_ENVIRONMENT;
+        return insertBeforeClosingBody(source, `<script src="${context.apiUrl}${SCRIPT_BUNDLE_PATH}" ` +
+            `data-api-url="${context.apiUrl}" ` +
+            `data-project-url="${context.projectUrl}" ` +
+            `data-environment="${environment}" defer></script>`);
+    },
+};
+function addImport(source) {
+    const importLine = `import { ${COMPONENT_NAME} } from "${PACKAGE_NAME}";\n`;
+    // After the last top-level import, so the file keeps its import block
+    // together rather than growing a stray line above a directive.
+    const importRe = /^import[\s\S]*?;[ \t]*$/gm;
+    let lastEnd = -1;
+    for (const match of source.matchAll(importRe)) {
+        lastEnd = match.index + match[0].length;
+    }
+    if (lastEnd >= 0) {
+        return `${source.slice(0, lastEnd)}\n${importLine.trimEnd()}${source.slice(lastEnd)}`;
+    }
+    // No imports at all: go after a leading "use client" directive if present,
+    // since nothing may precede one.
+    const directive = /^\s*("use client"|'use client');?\s*\n/.exec(source);
+    if (directive) {
+        const end = directive.index + directive[0].length;
+        return `${source.slice(0, end)}\n${importLine}${source.slice(end)}`;
+    }
+    return `${importLine}\n${source}`;
+}
+/**
+ * Put `markup` immediately inside the closing `</body>`.
+ *
+ * Shared by both strategies because the placement problem is the same one in
+ * JSX and in HTML, and the interesting case is the same too: the one-line
+ * `<body>…</body>` that Next's template and hand-written HTML pages both use.
+ */
+function insertBeforeClosingBody(source, markup) {
+    const closingBody = source.lastIndexOf("</body>");
+    if (closingBody === -1) {
+        // Refusing beats guessing. A layout with no <body> is not an App Router
+        // root layout, and injecting somewhere plausible would produce a build
+        // failure the developer has to reverse-engineer.
+        throw new InjectionError("found a layout file but no <body> tag to place the toolbar in");
+    }
+    // Immediately before `</body>`, never at the start of its line: Next's own
+    // template ships `<body>{children}</body>` on one line, and inserting at the
+    // line start would put the toolbar between <html> and <body>, which is a
+    // broken layout rather than an install.
+    const lineStart = source.lastIndexOf("\n", closingBody) + 1;
+    const beforeOnLine = source.slice(lineStart, closingBody);
+    const openingBodyOnSameLine = beforeOnLine.includes("<body");
+    if (openingBodyOnSameLine) {
+        // Everything is on one line, so splice in place rather than reformat.
+        return `${source.slice(0, closingBody)}${markup}${source.slice(closingBody)}`;
+    }
+    // `</body>` is on its own line: take its indentation plus one step, so the
+    // diff reads as if a person wrote it.
+    const indent = beforeOnLine.match(/^\s*/)?.[0] ?? "";
+    const line = `${indent}  ${markup}\n`;
+    return `${source.slice(0, lineStart)}${line}${source.slice(lineStart)}`;
+}
+/** A failure the developer can act on, as opposed to an internal error. */
+export class InjectionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InjectionError";
+    }
+}
+export const STRATEGIES = [
+    nextAppRouterStrategy,
+    htmlScriptTagStrategy,
+];
+//# sourceMappingURL=strategies.js.map

package/dist/cli/strategies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategies.js","sourceRoot":"","sources":["../../src/cli/strategies.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,59 @@
+import type { FeedbackCreateInput, FeedbackItemDTO, FeedbackStatus, ToolbarSessionState } from "./vendor/types/index.js";
+export interface ToolbarSession {
+    state: ToolbarSessionState;
+    user?: {
+        id: string;
+        email: string;
+        name: string;
+    };
+    project?: {
+        id: string;
+        name: string;
+    };
+    role?: string;
+}
+/** A failed call, carrying the API's machine-readable code where there is one. */
+export declare class ToolbarApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, status: number, message?: string);
+}
+export declare function createToolbarClient(apiUrl: string): {
+    /** Who the caller is, and whether they can act on this project. */
+    session(projectUrl: string): Promise<ToolbarSession>;
+    /** Ask for a sign-in link. Always resolves, whoever the address belongs to. */
+    requestMagicLink(email: string, callbackUrl?: string): Promise<{
+        sent: true;
+    }>;
+    signOut(): Promise<{
+        ok: true;
+    }>;
+    submit(input: FeedbackCreateInput): Promise<FeedbackItemDTO>;
+    /** Feedback on one page, which is how the toolbar finds this page's pins. */
+    listForPage(organizationId: string, pageUrl: string, status?: FeedbackStatus): Promise<FeedbackItemDTO[]>;
+    /**
+     * Every item in the project, whatever page it was filed on, newest first.
+     * The inbox sheet widens to this: a reviewer working through a round of
+     * feedback needs to see the items waiting on the pages they have not
+     * opened yet, and the same route answers both because `pageUrl` is an
+     * optional filter rather than a separate endpoint.
+     *
+     * `limit` is passed explicitly rather than left to the server's default
+     * because this is the one unfiltered read the toolbar makes, against the
+     * one table that grows for the life of a project. Stating the bound here
+     * is what lets the sheet say "the newest N" instead of quietly showing a
+     * truncated list as if it were the whole thing.
+     */
+    listForProject(organizationId: string, limit: number, status?: FeedbackStatus): Promise<FeedbackItemDTO[]>;
+    /**
+     * Move an item between lanes. The mover is never on the wire: the API
+     * takes it from the session cookie and records it alongside the new
+     * status, so a reviewer cannot attribute their own triage to someone
+     * else. The re-read item comes back carrying that attribution, which is
+     * why the thread can render "resolved by X" straight from the response.
+     */
+    setStatus(organizationId: string, itemId: string, status: FeedbackStatus): Promise<FeedbackItemDTO>;
+    reply(organizationId: string, itemId: string, body: string, screenshot?: string): Promise<FeedbackItemDTO>;
+};
+export type ToolbarClient = ReturnType<typeof createToolbarClient>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,mBAAmB,EACpB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,mBAAmB,CAAC;IAC3B,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,OAAO,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,kFAAkF;AAClF,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAM3D;AA8BD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM;IAE9C,mEAAmE;wBAC/C,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAOpD,+EAA+E;4BAEtE,MAAM,gBACC,MAAM,GACnB,OAAO,CAAC;QAAE,IAAI,EAAE,IAAI,CAAA;KAAE,CAAC;eAOf,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,CAAC;kBAMlB,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IAO5D,6EAA6E;gCAE3D,MAAM,WACb,MAAM,WACN,cAAc,GACtB,OAAO,CAAC,eAAe,EAAE,CAAC;IAM7B;;;;;;;;;;;;OAYG;mCAEe,MAAM,SACf,MAAM,WACJ,cAAc,GACtB,OAAO,CAAC,eAAe,EAAE,CAAC;IAS7B;;;;;;OAMG;8BAEe,MAAM,UACd,MAAM,UACN,cAAc,GACrB,OAAO,CAAC,eAAe,CAAC;0BAST,MAAM,UACd,MAAM,QACR,MAAM,eAOC,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC;EAW9B;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/client.js

@@ -0,0 +1,113 @@
+/** A failed call, carrying the API's machine-readable code where there is one. */
+export class ToolbarApiError extends Error {
+    code;
+    status;
+    constructor(code, status, message) {
+        super(message ?? code);
+        this.name = "ToolbarApiError";
+        this.code = code;
+        this.status = status;
+    }
+}
+async function request(apiUrl, path, init = {}) {
+    let res;
+    try {
+        res = await fetch(`${apiUrl}${path}`, {
+            ...init,
+            credentials: "include",
+            headers: {
+                ...(init.body ? { "content-type": "application/json" } : {}),
+                ...init.headers,
+            },
+        });
+    }
+    catch (cause) {
+        // A network failure and a rejected CORS preflight look the same from here.
+        // Both mean the same thing to a reviewer: it did not send, try again.
+        throw new ToolbarApiError("network_error", 0, String(cause));
+    }
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        throw new ToolbarApiError(body.error ?? "request_failed", res.status);
+    }
+    return (await res.json());
+}
+export function createToolbarClient(apiUrl) {
+    return {
+        /** Who the caller is, and whether they can act on this project. */
+        session(projectUrl) {
+            return request(apiUrl, `/api/v1/toolbar-auth/session?projectUrl=${encodeURIComponent(projectUrl)}`);
+        },
+        /** Ask for a sign-in link. Always resolves, whoever the address belongs to. */
+        requestMagicLink(email, callbackUrl) {
+            return request(apiUrl, "/api/v1/toolbar-auth/magic-link", {
+                method: "POST",
+                body: JSON.stringify({ email, callbackUrl }),
+            });
+        },
+        signOut() {
+            return request(apiUrl, "/api/v1/toolbar-auth/sign-out", {
+                method: "POST",
+            });
+        },
+        submit(input) {
+            return request(apiUrl, "/api/v1/feedback", {
+                method: "POST",
+                body: JSON.stringify(input),
+            });
+        },
+        /** Feedback on one page, which is how the toolbar finds this page's pins. */
+        listForPage(organizationId, pageUrl, status) {
+            const params = new URLSearchParams({ organizationId, pageUrl });
+            if (status)
+                params.set("status", status);
+            return request(apiUrl, `/api/v1/feedback?${params.toString()}`);
+        },
+        /**
+         * Every item in the project, whatever page it was filed on, newest first.
+         * The inbox sheet widens to this: a reviewer working through a round of
+         * feedback needs to see the items waiting on the pages they have not
+         * opened yet, and the same route answers both because `pageUrl` is an
+         * optional filter rather than a separate endpoint.
+         *
+         * `limit` is passed explicitly rather than left to the server's default
+         * because this is the one unfiltered read the toolbar makes, against the
+         * one table that grows for the life of a project. Stating the bound here
+         * is what lets the sheet say "the newest N" instead of quietly showing a
+         * truncated list as if it were the whole thing.
+         */
+        listForProject(organizationId, limit, status) {
+            const params = new URLSearchParams({
+                organizationId,
+                limit: String(limit),
+            });
+            if (status)
+                params.set("status", status);
+            return request(apiUrl, `/api/v1/feedback?${params.toString()}`);
+        },
+        /**
+         * Move an item between lanes. The mover is never on the wire: the API
+         * takes it from the session cookie and records it alongside the new
+         * status, so a reviewer cannot attribute their own triage to someone
+         * else. The re-read item comes back carrying that attribution, which is
+         * why the thread can render "resolved by X" straight from the response.
+         */
+        setStatus(organizationId, itemId, status) {
+            return request(apiUrl, `/api/v1/feedback/${itemId}/status?organizationId=${encodeURIComponent(organizationId)}`, { method: "PATCH", body: JSON.stringify({ status }) });
+        },
+        reply(organizationId, itemId, body, 
+        /**
+         * A data URL of one element the reviewer pointed at, or undefined.
+         * Omitted from the payload entirely when absent rather than sent as
+         * null: the schema makes it optional, and an explicit null would be a
+         * different shape for the same fact.
+         */
+        screenshot) {
+            return request(apiUrl, `/api/v1/feedback/${itemId}/replies?organizationId=${encodeURIComponent(organizationId)}`, {
+                method: "POST",
+                body: JSON.stringify(screenshot ? { body, screenshot } : { body }),
+            });
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,92 @@
+import { type PinShortcutSetting } from "./shortcut.js";
+export interface ToolbarConfig {
+    /** Base URL of the BitVea Feedback backend, no trailing slash. */
+    apiUrl: string;
+    /**
+     * Where the toolbar's own static assets - the two font files - are served
+     * from, no trailing slash. Defaults to `apiUrl`, which is right for every
+     * real install: the backend that serves the API serves `/fonts` too.
+     *
+     * It is a separate field because the two are not the same question. A
+     * harness can legitimately point the API at a host that does not exist and
+     * answer every call locally, which is exactly what the preview route does -
+     * and welding the font URL to `apiUrl` made the fonts 404 there, so the one
+     * page built to review the toolbar was the one page that rendered it in the
+     * wrong typeface.
+     */
+    assetOrigin: string;
+    /** The project this deployment reports against, its normalised origin. */
+    projectUrl: string;
+    /** "preview", "development" or "production". */
+    environment: string;
+    /** Git branch, when the build knows it. */
+    gitBranch?: string | undefined;
+    /** Git commit SHA, when the build knows it. */
+    gitCommit?: string | undefined;
+    /** Whether the toolbar renders and talks to the network at all. */
+    enabled: boolean;
+    /**
+     * The chord that arms pinning, or `null` to claim no key at all.
+     *
+     * THIS IS THE HOST'S REMEDY, not a preference. The toolbar listens for the
+     * chord in the capture phase and swallows it when it acts, so a host
+     * application that binds the same keys loses its own binding silently - and
+     * the default chord is known to collide (`Cmd+Space` is Spotlight on macOS;
+     * `Ctrl+Space` is commonly an input method's). Claiming a key inside
+     * somebody else's application is only defensible while there is a way out
+     * of it, so this field is that way out, and `null` is honoured by
+     * registering no listener rather than by declining inside one.
+     */
+    pinShortcut: PinShortcutSetting;
+}
+/** Props a host app may pass to override what the environment reports. */
+export interface ToolbarConfigOverrides {
+    apiUrl?: string;
+    assetOrigin?: string;
+    projectUrl?: string;
+    environment?: string;
+    gitBranch?: string;
+    gitCommit?: string;
+    /** Force the gate one way for a test harness. Not for production use. */
+    enabled?: boolean;
+    /**
+     * Replace the pinning chord, or pass `null` to switch it off.
+     *
+     * Omitted means the default. `null` is a deliberate value rather than a
+     * missing one, which is why this is not `ShortcutChord | undefined`: a host
+     * has to be able to say "no key" and be heard.
+     */
+    pinShortcut?: PinShortcutSetting;
+}
+export declare const API_URL_ENV_VAR = "NEXT_PUBLIC_FEEDBACK_TOOLBAR_API_URL";
+/**
+ * `NEXT_PUBLIC_` env names Vercel populates in the client bundle. They are
+ * read through a bag rather than off `process.env` directly so this stays a
+ * pure function, and because a bundler needs literal member access to inline
+ * them, which the caller does.
+ */
+export declare const VERCEL_ENV_VARS: {
+    readonly env: "NEXT_PUBLIC_VERCEL_ENV";
+    readonly branch: "NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF";
+    readonly commit: "NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA";
+    /**
+     * The project's stable production hostname, and the identity a Project row
+     * is keyed by. Preferred over the per-deployment URL below because a
+     * preview URL changes on every commit, and keying on it would create a new
+     * project per deploy instead of collecting a project's feedback in one
+     * place. The installer registers the same value, so the two agree.
+     */
+    readonly productionUrl: "NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL";
+    /** This deployment's own URL. The fallback, and what a local build has. */
+    readonly url: "NEXT_PUBLIC_VERCEL_URL";
+};
+/**
+ * Resolve the running configuration. Overrides win over the environment, and
+ * the environment wins over nothing.
+ *
+ * `enabled` folds in one extra condition beyond the environment gate: without
+ * an API URL the toolbar has nowhere to send anything, so it stays dark rather
+ * than rendering a button that fails on click.
+ */
+export declare function resolveConfig(env: Record<string, string | undefined>, overrides?: ToolbarConfigOverrides): ToolbarConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAOA,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE3E,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;OAWG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,mEAAmE;IACnE,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;;;;;;OAWG;IACH,WAAW,EAAE,kBAAkB,CAAC;CACjC;AAED,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAED,eAAO,MAAM,eAAe,yCAAyC,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;;;IAI1B;;;;;;OAMG;;IAEH,2EAA2E;;CAEnE,CAAC;AAMX;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,SAAS,GAAE,sBAA2B,GACrC,aAAa,CA8Bf"}

package/dist/config.js

@@ -0,0 +1,65 @@
+// The toolbar's configuration, and where each field comes from.
+//
+// Defaults are read from the environment Vercel already populates, so a
+// correct install needs no config object at all; every field can still be
+// overridden by a prop for the cases the environment cannot describe (a local
+// harness, a preview pointed at a different backend).
+import { isToolbarEnabledFromEnv } from "./gating.js";
+import { DEFAULT_PIN_SHORTCUT } from "./shortcut.js";
+export const API_URL_ENV_VAR = "NEXT_PUBLIC_FEEDBACK_TOOLBAR_API_URL";
+/**
+ * `NEXT_PUBLIC_` env names Vercel populates in the client bundle. They are
+ * read through a bag rather than off `process.env` directly so this stays a
+ * pure function, and because a bundler needs literal member access to inline
+ * them, which the caller does.
+ */
+export const VERCEL_ENV_VARS = {
+    env: "NEXT_PUBLIC_VERCEL_ENV",
+    branch: "NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF",
+    commit: "NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA",
+    /**
+     * The project's stable production hostname, and the identity a Project row
+     * is keyed by. Preferred over the per-deployment URL below because a
+     * preview URL changes on every commit, and keying on it would create a new
+     * project per deploy instead of collecting a project's feedback in one
+     * place. The installer registers the same value, so the two agree.
+     */
+    productionUrl: "NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL",
+    /** This deployment's own URL. The fallback, and what a local build has. */
+    url: "NEXT_PUBLIC_VERCEL_URL",
+};
+function trimSlashes(value) {
+    return value.replace(/\/+$/, "");
+}
+/**
+ * Resolve the running configuration. Overrides win over the environment, and
+ * the environment wins over nothing.
+ *
+ * `enabled` folds in one extra condition beyond the environment gate: without
+ * an API URL the toolbar has nowhere to send anything, so it stays dark rather
+ * than rendering a button that fails on click.
+ */
+export function resolveConfig(env, overrides = {}) {
+    const apiUrl = trimSlashes(overrides.apiUrl ?? env[API_URL_ENV_VAR] ?? "");
+    const assetOrigin = trimSlashes(overrides.assetOrigin ?? apiUrl);
+    const vercelHost = env[VERCEL_ENV_VARS.productionUrl] ?? env[VERCEL_ENV_VARS.url];
+    const projectUrl = trimSlashes(overrides.projectUrl ?? (vercelHost ? `https://${vercelHost}` : ""));
+    const environment = overrides.environment ?? env[VERCEL_ENV_VARS.env] ?? "unknown";
+    const gatePasses = isToolbarEnabledFromEnv(env);
+    const enabled = (overrides.enabled ?? gatePasses) && apiUrl.length > 0;
+    return {
+        apiUrl,
+        assetOrigin,
+        projectUrl,
+        environment,
+        gitBranch: overrides.gitBranch ?? env[VERCEL_ENV_VARS.branch],
+        gitCommit: overrides.gitCommit ?? env[VERCEL_ENV_VARS.commit],
+        enabled,
+        // `??` and not `||`, because `null` is the host saying "no key" and must
+        // survive; only an omitted override falls back to the default.
+        pinShortcut: overrides.pinShortcut === undefined
+            ? DEFAULT_PIN_SHORTCUT
+            : overrides.pinShortcut,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,wEAAwE;AACxE,0EAA0E;AAC1E,8EAA8E;AAC9E,sDAAsD;AACtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAA2B,MAAM,YAAY,CAAC;AA+D3E,MAAM,CAAC,MAAM,eAAe,GAAG,sCAAsC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,GAAG,EAAE,wBAAwB;IAC7B,MAAM,EAAE,mCAAmC;IAC3C,MAAM,EAAE,mCAAmC;IAC3C;;;;;;OAMG;IACH,aAAa,EAAE,2CAA2C;IAC1D,2EAA2E;IAC3E,GAAG,EAAE,wBAAwB;CACrB,CAAC;AAEX,SAAS,WAAW,CAAC,KAAa;IAChC,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAuC,EACvC,YAAoC,EAAE;IAEtC,MAAM,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC,MAAM,IAAI,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3E,MAAM,WAAW,GAAG,WAAW,CAAC,SAAS,CAAC,WAAW,IAAI,MAAM,CAAC,CAAC;IACjE,MAAM,UAAU,GACd,GAAG,CAAC,eAAe,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;IACjE,MAAM,UAAU,GAAG,WAAW,CAC5B,SAAS,CAAC,UAAU,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CACpE,CAAC;IACF,MAAM,WAAW,GACf,SAAS,CAAC,WAAW,IAAI,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC;IAEjE,MAAM,UAAU,GAAG,uBAAuB,CAAC,GAAG,CAAC,CAAC;IAChD,MAAM,OAAO,GACX,CAAC,SAAS,CAAC,OAAO,IAAI,UAAU,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IAEzD,OAAO;QACL,MAAM;QACN,WAAW;QACX,UAAU;QACV,WAAW;QACX,SAAS,EAAE,SAAS,CAAC,SAAS,IAAI,GAAG,CAAC,eAAe,CAAC,MAAM,CAAC;QAC7D,SAAS,EAAE,SAAS,CAAC,SAAS,IAAI,GAAG,CAAC,eAAe,CAAC,MAAM,CAAC;QAC7D,OAAO;QACP,yEAAyE;QACzE,+DAA+D;QAC/D,WAAW,EACT,SAAS,CAAC,WAAW,KAAK,SAAS;YACjC,CAAC,CAAC,oBAAoB;YACtB,CAAC,CAAC,SAAS,CAAC,WAAW;KAC5B,CAAC;AACJ,CAAC"}

package/dist/deepLink.d.ts

@@ -0,0 +1,86 @@
+/** The whole namespace. Nothing else in a hash is ours. */
+export declare const DEEP_LINK_PREFIX = "#bitvea-feedback=";
+/**
+ * The feedback id a hash names, or null for every other hash there is -
+ * including `#pricing`, `#/route/23` and a bare `#`.
+ */
+export declare function parseDeepLink(hash: string): string | null;
+/**
+ * The URL that opens one item's thread on the page it was filed on. Used by
+ * the inbox sheet for an item on another page of the same site.
+ *
+ * Any existing fragment is dropped, because a URL has one fragment and this
+ * one is ours. That is safe precisely because page identity drops the fragment
+ * too - see the note at the top of this file - so the URL this returns and the
+ * `pageUrl` the item was stored under reduce to the same identity.
+ */
+export declare function buildDeepLink(pageUrl: string, feedbackItemId: string): string;
+/**
+ * Read the deep link, once. A pure read: nothing about the document changes.
+ *
+ * It used to strip the fragment here as well, which was a `replaceState` from
+ * inside a render pass - a side effect on the HOST's document, in a phase
+ * React may run twice and may throw away. The clear is now the shell's job
+ * (`clearDeepLinkHash` from an effect), and this function only answers.
+ *
+ * Nothing downstream may assume the clear stuck in any case: a render-phase
+ * clear was overwritten by Next's App Router a moment later, which is why the
+ * pin layer's idea of "this page" comes from `currentPageUrl` rather than from
+ * whatever the address bar ended up saying.
+ */
+export declare function captureDeepLink(): string | null;
+/**
+ * The identity of the page the reviewer is on: its URL with no fragment.
+ *
+ * This is what "which page is this" means everywhere the toolbar asks - the
+ * pin layer's page-scoped query, the inbox sheet's scope, and the metadata
+ * attached to a new report - and it is deliberately not `location.href`.
+ *
+ * Two reasons, and both are about the address bar not being ours to trust. A
+ * host framework can put our own fragment back after we have removed it
+ * (Next's App Router does, see `clearDeepLinkHash`), and a `pageUrl` carrying
+ * `#bitvea-feedback=...` matches no stored row. And a deep link has to replace
+ * the host's fragment to carry the id at all, so a landing URL and the URL a
+ * report was filed from differ by the fragment as a matter of course - see the
+ * note at the top of this file for why identity gives the fragment up rather
+ * than the other way round.
+ *
+ * Deriving it instead of trusting the URL makes that class of bug impossible
+ * rather than merely unlikely: it is right on the first render, whatever the
+ * host does to the address bar afterwards.
+ */
+export declare function currentPageUrl(): string;
+/**
+ * `href` reduced to a page identity: origin, path and query, no fragment.
+ *
+ * Every fragment, not only ours. See the note at the top of this file: a URL
+ * has one fragment and a deep link needs it, so an identity that keeps the
+ * host's cannot be produced by a link we build. Query strings are kept,
+ * because they do distinguish pages on a server-rendered host.
+ */
+export declare function pageIdentity(href: string): string;
+/**
+ * Strip our fragment, leaving the rest of the URL byte-identical. Re-checks
+ * the prefix so this can never be the thing that eats a host's own hash, and
+ * uses `replaceState` so it adds no history entry the back button has to walk
+ * back through.
+ *
+ * Idempotent, and called more than once on purpose. A render-phase clear is
+ * not the last word on the address bar: Next's App Router restores the URL it
+ * considered canonical at load - fragment included - from a commit-phase
+ * effect, and because a parent's effects run after its children's there is no
+ * effect the toolbar can register that is guaranteed to run later. So the
+ * shell schedules one more clear onto the next macrotask, which is after the
+ * whole commit; see `EnabledToolbar`. Re-checking the prefix is what makes
+ * that safe: by then the host may have navigated, and a second clear must
+ * never eat a fragment that is not ours.
+ */
+export declare function clearDeepLinkHash(): void;
+/**
+ * Forget the capture. Only tests need this - a module-scope one-shot is
+ * exactly right in a browser, where there is one page load per module, and
+ * exactly wrong in a runner where there are many renders per module. It is
+ * deliberately not re-exported from the package barrel.
+ */
+export declare function resetDeepLinkCapture(): void;
+//# sourceMappingURL=deepLink.d.ts.map

package/dist/deepLink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepLink.d.ts","sourceRoot":"","sources":["../src/deepLink.ts"],"names":[],"mappings":"AA0BA,2DAA2D;AAC3D,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAWpD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAazD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAI7E;AAiBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAQ/C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAGvC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAYxC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}