@kolibri-day/feedback 0.0.0-stage → 0.1.0

package/dist/cjs/adapters/kolibri/target.d.ts

@@ -0,0 +1,100 @@
+import type { FeedbackTarget, FeedbackReport, FeedbackResume, FeedbackSubmission, FeedbackTargetDescriptor, FetchLike } from '../../kernel/feedback/types.js';
+import { type FormatOptions } from '../../kernel/feedback/format.js';
+import { type FeedbackMessages } from '../../kernel/feedback/messages.js';
+/**
+ * What a Kolibri target is, before it has credentials — so a web tier that holds no
+ * token can still tell the reporter where the screenshot goes.
+ *
+ * Self-hosted by the team that runs the app: same controller, no processor, no
+ * third-country transfer. It settles the EXTERNAL question only. The internal one —
+ * who inside the company can open a screenshot — is answered by the feedback
+ * project's membership, and only on a Kolibri that scopes attachments by the project
+ * of the task they hang off. On an older instance attachments were visible to the
+ * whole workspace, which is why a MINIMUM KOLIBRI VERSION is part of the setup, not
+ * just a private project (see the README).
+ */
+export declare const KOLIBRI_TARGET: FeedbackTargetDescriptor;
+export interface KolibriConfig {
+    /**
+     * Kolibri's origin — e.g. https://kolibri.example.com. NOT an /api path. Kolibri
+     * serves its API and its web app from the same origin, so the task backlink is built
+     * from this too.
+     */
+    apiUrl: string;
+    /** API token ("kol_…"), sent as `Authorization: Bearer …`. Needs the `write` scope. */
+    token: string;
+    /** Workspace UUID. A slug is refused with 403 (§A2). */
+    workspaceId: string;
+    /** UUID of the (private) feedback project. A project key is refused with 400 (§A3). */
+    projectId: string;
+    /** Per-request timeout. fetch() has none by default. */
+    timeoutMs?: number;
+    /** Language of the ticket body and of the error messages. Default: German. */
+    messages?: FeedbackMessages;
+    /** Display labels for the app's kinds in the title. */
+    kindLabels?: FormatOptions['kindLabels'];
+}
+/**
+ * Kolibri addresses workspaces and projects by UUID and refuses anything else — a
+ * slug with 403, a project key with 400 (§A2/§A3). Checking the shape up front turns
+ * a per-report round-trip that reads as "Kolibri rejected us" into "this setting is
+ * wrong".
+ */
+export declare const UUID_PATTERN: RegExp;
+/**
+ * Is this status worth retrying?
+ *
+ * 4xx means we sent something Kolibri will reject identically next time — a bad token,
+ * a project that doesn't exist, a body it won't process. Retrying burns the attempt
+ * budget and delays the failed report an operator needs to see. 429 and 408 are the
+ * exceptions inside 4xx: both explicitly mean "later".
+ *
+ * 5xx is transient. Kolibri used to answer a NOT NULL violation with 500, so a
+ * permanently-malformed write could masquerade as an outage; current instances answer
+ * those with 400, so a 5xx is what it claims to be.
+ */
+export declare function isPermanentStatus(status: number): boolean;
+export declare class KolibriFeedbackTarget implements FeedbackTarget {
+    readonly name: string;
+    readonly label: string;
+    readonly trustBoundary: import("../../kernel/feedback/types.js").TrustBoundary;
+    private readonly config;
+    private readonly fetchFn;
+    private readonly timeoutMs;
+    private readonly messages;
+    constructor(config: KolibriConfig, fetchFn?: FetchLike);
+    /** Base with any trailing slash removed, so path joins never double up. */
+    private get base();
+    /** The human backlink. `/t/{id}` accepts the row id or the identifier; the id is stable across a project-key rename (§F24). */
+    taskUrl(taskId: string): string;
+    private request;
+    /**
+     * POST /api/workspaces/{ws}/tasks — idempotent on the report's own id.
+     *
+     * `state_id` is deliberately absent: Kolibri fills in the project's default state
+     * (§A1), and naming one here would mean the app owning a workflow decision that
+     * belongs to whoever configures the board.
+     */
+    private createTask;
+    /**
+     * POST /api/workspaces/{ws}/files?task_id={id} — the body IS the file.
+     *
+     * Not multipart and not base64 (§C11): Kolibri takes the raw bytes with the name in
+     * `x-filename` and the type in `content-type`, and creates the attachment row itself
+     * because `?task_id=` is present. That is why there is no third call.
+     *
+     * Repeating this call is safe — Kolibri matches identical bytes against what already
+     * hangs on the task and hands back the existing row.
+     */
+    private uploadAttachments;
+    /**
+     * Create the task, then upload attachments.
+     *
+     * `resume` is accepted for the interface's sake but carries no information this
+     * target needs: the task id is the report id, so it is known before the first call
+     * and identical on every attempt. Re-running the create on a resume is deliberate —
+     * it is an upsert, it costs one request, and it repairs a task whose description
+     * failed to write the first time.
+     */
+    submit(report: FeedbackReport, _resume?: FeedbackResume): Promise<FeedbackSubmission>;
+}

package/dist/cjs/adapters/kolibri/target.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KolibriFeedbackTarget = exports.UUID_PATTERN = exports.KOLIBRI_TARGET = void 0;
+exports.isPermanentStatus = isPermanentStatus;
+const types_ts_1 = require("../../kernel/feedback/types.js");
+const format_ts_1 = require("../../kernel/feedback/format.js");
+const messages_ts_1 = require("../../kernel/feedback/messages.js");
+/**
+ * What a Kolibri target is, before it has credentials — so a web tier that holds no
+ * token can still tell the reporter where the screenshot goes.
+ *
+ * Self-hosted by the team that runs the app: same controller, no processor, no
+ * third-country transfer. It settles the EXTERNAL question only. The internal one —
+ * who inside the company can open a screenshot — is answered by the feedback
+ * project's membership, and only on a Kolibri that scopes attachments by the project
+ * of the task they hang off. On an older instance attachments were visible to the
+ * whole workspace, which is why a MINIMUM KOLIBRI VERSION is part of the setup, not
+ * just a private project (see the README).
+ */
+exports.KOLIBRI_TARGET = Object.freeze({
+    name: 'kolibri',
+    label: 'Kolibri',
+    trustBoundary: 'self_hosted',
+});
+const DEFAULT_TIMEOUT_MS = 15_000;
+/**
+ * Kolibri addresses workspaces and projects by UUID and refuses anything else — a
+ * slug with 403, a project key with 400 (§A2/§A3). Checking the shape up front turns
+ * a per-report round-trip that reads as "Kolibri rejected us" into "this setting is
+ * wrong".
+ */
+exports.UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Is this status worth retrying?
+ *
+ * 4xx means we sent something Kolibri will reject identically next time — a bad token,
+ * a project that doesn't exist, a body it won't process. Retrying burns the attempt
+ * budget and delays the failed report an operator needs to see. 429 and 408 are the
+ * exceptions inside 4xx: both explicitly mean "later".
+ *
+ * 5xx is transient. Kolibri used to answer a NOT NULL violation with 500, so a
+ * permanently-malformed write could masquerade as an outage; current instances answer
+ * those with 400, so a 5xx is what it claims to be.
+ */
+function isPermanentStatus(status) {
+    if (status === 429 || status === 408)
+        return false;
+    return status >= 400 && status < 500;
+}
+/** Truncated response body for the error message. Never contains the token — that only ever travels in a header. */
+async function errorBody(res) {
+    const text = await res.text().catch(() => '');
+    return text.slice(0, 500);
+}
+class KolibriFeedbackTarget {
+    name = exports.KOLIBRI_TARGET.name;
+    label = exports.KOLIBRI_TARGET.label;
+    trustBoundary = exports.KOLIBRI_TARGET.trustBoundary;
+    config;
+    fetchFn;
+    timeoutMs;
+    messages;
+    constructor(config, fetchFn = (input, init) => fetch(input, init)) {
+        this.config = config;
+        this.fetchFn = fetchFn;
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.messages = config.messages ?? messages_ts_1.en;
+    }
+    /** Base with any trailing slash removed, so path joins never double up. */
+    get base() {
+        return this.config.apiUrl.replace(/\/+$/, '');
+    }
+    /** The human backlink. `/t/{id}` accepts the row id or the identifier; the id is stable across a project-key rename (§F24). */
+    taskUrl(taskId) {
+        return `${this.base}/t/${taskId}`;
+    }
+    async request(path, init) {
+        const url = `${this.base}${path}`;
+        try {
+            return await this.fetchFn(url, {
+                ...init,
+                headers: { Authorization: `Bearer ${this.config.token}`, ...(init.headers ?? {}) },
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (e) {
+            // Network-level: DNS, TLS, connection refused, or our own timeout. No response
+            // to classify, and all of them are worth another attempt later.
+            throw new types_ts_1.FeedbackTargetError(this.messages.kolibri.unreachable(path, e instanceof Error ? e.message : String(e)), false);
+        }
+    }
+    /**
+     * POST /api/workspaces/{ws}/tasks — idempotent on the report's own id.
+     *
+     * `state_id` is deliberately absent: Kolibri fills in the project's default state
+     * (§A1), and naming one here would mean the app owning a workflow decision that
+     * belongs to whoever configures the board.
+     */
+    async createTask(report) {
+        const format = { messages: this.messages, kindLabels: this.config.kindLabels };
+        const res = await this.request(`/api/workspaces/${this.config.workspaceId}/tasks`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                id: report.id,
+                project_id: this.config.projectId,
+                title: (0, format_ts_1.buildTitle)(report, format),
+                description: (0, format_ts_1.buildDescriptionMarkdown)(report, format),
+            }),
+        });
+        if (!res.ok) {
+            const body = await errorBody(res);
+            throw new types_ts_1.FeedbackTargetError(this.messages.kolibri.createRejected(res.status, body), isPermanentStatus(res.status), res.status);
+        }
+    }
+    /**
+     * POST /api/workspaces/{ws}/files?task_id={id} — the body IS the file.
+     *
+     * Not multipart and not base64 (§C11): Kolibri takes the raw bytes with the name in
+     * `x-filename` and the type in `content-type`, and creates the attachment row itself
+     * because `?task_id=` is present. That is why there is no third call.
+     *
+     * Repeating this call is safe — Kolibri matches identical bytes against what already
+     * hangs on the task and hands back the existing row.
+     */
+    async uploadAttachments(taskId, report) {
+        if (report.attachments.length === 0)
+            return 0;
+        let uploaded = 0;
+        for (const att of report.attachments) {
+            // Copy into a fresh ArrayBuffer before sending. Two reasons, and the second is
+            // the one that bites: a Uint8Array read out of a database driver may be a view
+            // onto a larger pooled Node Buffer, so sending the view risks sending its
+            // neighbours; and `Uint8Array<ArrayBufferLike>` is not a `BodyInit`, because the
+            // buffer behind it could be shared. The copy settles both.
+            const body = new ArrayBuffer(att.bytes.byteLength);
+            new Uint8Array(body).set(att.bytes);
+            const res = await this.request(`/api/workspaces/${this.config.workspaceId}/files?task_id=${encodeURIComponent(taskId)}`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': att.contentType,
+                    // Kolibri decodes this and strips path separators itself; encoding is what
+                    // keeps a non-ASCII or spaced filename from breaking the header.
+                    'x-filename': encodeURIComponent(att.filename),
+                },
+                body,
+            });
+            if (!res.ok) {
+                const detail = await errorBody(res);
+                throw new types_ts_1.FeedbackTargetError(this.messages.kolibri.uploadRejected(res.status, detail), isPermanentStatus(res.status), res.status, 
+                // The task EXISTS. Carrying the id lets a durable caller persist it, which is
+                // belt-and-braces here rather than load-bearing: the id is the report's own,
+                // so a retry would find the task even without this.
+                taskId, this.taskUrl(taskId));
+            }
+            uploaded += 1;
+        }
+        return uploaded;
+    }
+    /**
+     * Create the task, then upload attachments.
+     *
+     * `resume` is accepted for the interface's sake but carries no information this
+     * target needs: the task id is the report id, so it is known before the first call
+     * and identical on every attempt. Re-running the create on a resume is deliberate —
+     * it is an upsert, it costs one request, and it repairs a task whose description
+     * failed to write the first time.
+     */
+    async submit(report, _resume) {
+        await this.createTask(report);
+        const attachmentsUploaded = await this.uploadAttachments(report.id, report);
+        return { externalId: report.id, externalUrl: this.taskUrl(report.id), attachmentsUploaded };
+    }
+}
+exports.KolibriFeedbackTarget = KolibriFeedbackTarget;

package/dist/cjs/adapters/react/reporter.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from 'react';
+import { type FeedbackReporterOptions, type FeedbackReporterSnapshot } from '../capture/reporter.js';
+import type { CaptureResult } from '../capture/capture.js';
+export interface FeedbackActions {
+    /** Start the capture and open the dialog. A no-op while it is already open. */
+    openFeedback: () => void;
+}
+export interface FeedbackReporterState extends FeedbackReporterSnapshot {
+    openFeedback: () => void;
+    close: () => void;
+    /** The settled capture — for a submit that outruns the renderer. */
+    waitForCapture: () => Promise<CaptureResult | null>;
+}
+export interface FeedbackReporterProviderProps extends FeedbackReporterOptions {
+    children?: ReactNode;
+}
+export declare function FeedbackReporterProvider({ children, capture, captureOptions }: FeedbackReporterProviderProps): import("react").JSX.Element;
+/**
+ * For triggers. Safe to call from anywhere; a no-op outside the provider, so a
+ * component also rendered on a page without a reporter (a public page with nobody to
+ * attribute a report to) does not crash.
+ */
+export declare function useFeedback(): FeedbackActions;
+/** For the dialog: the full state plus the actions. Must be inside FeedbackReporterProvider. */
+export declare function useFeedbackReporter(): FeedbackReporterState;

package/dist/cjs/adapters/react/reporter.js

@@ -0,0 +1,54 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeedbackReporterProvider = FeedbackReporterProvider;
+exports.useFeedback = useFeedback;
+exports.useFeedbackReporter = useFeedbackReporter;
+const jsx_runtime_1 = require("react/jsx-runtime");
+// React bindings for the reporter: one dialog, any number of triggers.
+//
+// The indirection through context is the design. Every entry point — a floating
+// button, a menu item, a keyboard shortcut, a future shake-to-report — calls
+// `openFeedback()` and knows nothing else; the dialog reads the state. A second copy of
+// the surface would be a second copy of the rules.
+//
+// Two contexts, on purpose: triggers subscribe only to the stable `openFeedback`, so
+// a capture finishing re-renders the dialog and not every button in the app.
+//
+// The markup is the app's. This package ships no dialog, because the one thing every
+// app already has is its own dialog component — and a second one, styled differently,
+// would be the odd one out. Remember the two attributes that keep it out of its own
+// screenshot: REDACT_ATTRIBUTE on the dialog panel AND on its backdrop.
+const react_1 = require("react");
+const reporter_ts_1 = require("../capture/reporter.js");
+const ActionsContext = (0, react_1.createContext)(null);
+const ControllerContext = (0, react_1.createContext)(null);
+function FeedbackReporterProvider({ children, capture, captureOptions }) {
+    // Created once per provider. The options are read at creation; changing them later
+    // would mean a different reporter, which no app has needed.
+    const [controller] = (0, react_1.useState)(() => new reporter_ts_1.FeedbackReporterController({ capture, captureOptions }));
+    const actions = (0, react_1.useMemo)(() => ({ openFeedback: controller.open }), [controller]);
+    return ((0, jsx_runtime_1.jsx)(ControllerContext.Provider, { value: controller, children: (0, jsx_runtime_1.jsx)(ActionsContext.Provider, { value: actions, children: children }) }));
+}
+const noop = { openFeedback: () => { } };
+/**
+ * For triggers. Safe to call from anywhere; a no-op outside the provider, so a
+ * component also rendered on a page without a reporter (a public page with nobody to
+ * attribute a report to) does not crash.
+ */
+function useFeedback() {
+    return (0, react_1.useContext)(ActionsContext) ?? noop;
+}
+/** For the dialog: the full state plus the actions. Must be inside FeedbackReporterProvider. */
+function useFeedbackReporter() {
+    const controller = (0, react_1.useContext)(ControllerContext);
+    if (!controller)
+        throw new Error('useFeedbackReporter must be used inside <FeedbackReporterProvider>');
+    const snapshot = (0, react_1.useSyncExternalStore)(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+    return (0, react_1.useMemo)(() => ({
+        ...snapshot,
+        openFeedback: controller.open,
+        close: controller.close,
+        waitForCapture: controller.waitForCapture,
+    }), [snapshot, controller]);
+}

package/dist/cjs/browser.d.ts

@@ -0,0 +1,4 @@
+export { captureViewport, encodeWithinBudget, fitWithin, isRequestedType, REDACT_ATTRIBUTE, MAX_EDGE_PX, TARGET_MAX_BYTES, HARD_MAX_BYTES, type CaptureOptions, type CaptureResult, } from './adapters/capture/capture.js';
+export { collectClientContext } from './adapters/capture/client-context.js';
+export { FeedbackReporterController, type CaptureState, type FeedbackReporterSnapshot, type FeedbackReporterOptions, } from './adapters/capture/reporter.js';
+export { buildFeedbackForm, submitFeedback, type FeedbackSubmitInput, type FeedbackSubmitResult, } from './adapters/capture/submit.js';

package/dist/cjs/browser.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.submitFeedback = exports.buildFeedbackForm = exports.FeedbackReporterController = exports.collectClientContext = exports.HARD_MAX_BYTES = exports.TARGET_MAX_BYTES = exports.MAX_EDGE_PX = exports.REDACT_ATTRIBUTE = exports.isRequestedType = exports.fitWithin = exports.encodeWithinBudget = exports.captureViewport = void 0;
+// @kolibri-day/feedback/browser — viewport capture, browser facts, the reporter's
+// state machine, and the client half of the wire protocol. Browser-only at call time;
+// importing it on a server is harmless (nothing runs at module load).
+var capture_ts_1 = require("./adapters/capture/capture.js");
+Object.defineProperty(exports, "captureViewport", { enumerable: true, get: function () { return capture_ts_1.captureViewport; } });
+Object.defineProperty(exports, "encodeWithinBudget", { enumerable: true, get: function () { return capture_ts_1.encodeWithinBudget; } });
+Object.defineProperty(exports, "fitWithin", { enumerable: true, get: function () { return capture_ts_1.fitWithin; } });
+Object.defineProperty(exports, "isRequestedType", { enumerable: true, get: function () { return capture_ts_1.isRequestedType; } });
+Object.defineProperty(exports, "REDACT_ATTRIBUTE", { enumerable: true, get: function () { return capture_ts_1.REDACT_ATTRIBUTE; } });
+Object.defineProperty(exports, "MAX_EDGE_PX", { enumerable: true, get: function () { return capture_ts_1.MAX_EDGE_PX; } });
+Object.defineProperty(exports, "TARGET_MAX_BYTES", { enumerable: true, get: function () { return capture_ts_1.TARGET_MAX_BYTES; } });
+Object.defineProperty(exports, "HARD_MAX_BYTES", { enumerable: true, get: function () { return capture_ts_1.HARD_MAX_BYTES; } });
+var client_context_ts_1 = require("./adapters/capture/client-context.js");
+Object.defineProperty(exports, "collectClientContext", { enumerable: true, get: function () { return client_context_ts_1.collectClientContext; } });
+var reporter_ts_1 = require("./adapters/capture/reporter.js");
+Object.defineProperty(exports, "FeedbackReporterController", { enumerable: true, get: function () { return reporter_ts_1.FeedbackReporterController; } });
+var submit_ts_1 = require("./adapters/capture/submit.js");
+Object.defineProperty(exports, "buildFeedbackForm", { enumerable: true, get: function () { return submit_ts_1.buildFeedbackForm; } });
+Object.defineProperty(exports, "submitFeedback", { enumerable: true, get: function () { return submit_ts_1.submitFeedback; } });

package/dist/cjs/index.d.ts

@@ -0,0 +1,6 @@
+export * from './kernel/feedback/types.js';
+export * from './kernel/feedback/messages.js';
+export * from './kernel/feedback/format.js';
+export * from './kernel/feedback/notice.js';
+export * from './kernel/feedback/fake-target.js';
+export * from './kernel/feedback/files.js';

package/dist/cjs/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// @kolibri-day/feedback — the isomorphic core: the report shape, the target contract,
+// the Markdown formatter, the privacy notice, messages, and the in-memory targets.
+// No Node or DOM APIs; safe to import from server and browser code alike.
+__exportStar(require("./kernel/feedback/types.js"), exports);
+__exportStar(require("./kernel/feedback/messages.js"), exports);
+__exportStar(require("./kernel/feedback/format.js"), exports);
+__exportStar(require("./kernel/feedback/notice.js"), exports);
+__exportStar(require("./kernel/feedback/fake-target.js"), exports);
+__exportStar(require("./kernel/feedback/files.js"), exports);

package/dist/cjs/kernel/feedback/dispatch.d.ts

@@ -0,0 +1,64 @@
+import { type FeedbackReport, type FeedbackSubmission, type FeedbackTarget } from './types.js';
+export type StoredFeedbackStatus = 'pending' | 'submitted' | 'failed';
+export interface StoredFeedback {
+    report: FeedbackReport;
+    status: StoredFeedbackStatus;
+    /** Set when an earlier attempt created the item at the target but did not finish. */
+    externalId: string | null;
+}
+export interface FeedbackSubmittedUpdate {
+    targetName: string;
+    externalId: string;
+    externalUrl: string | null;
+    submittedAt: Date;
+}
+export interface FeedbackFailureUpdate {
+    targetName: string;
+    /** The error message, truncated — safe to show an operator (targets never put credentials in it). */
+    message: string;
+    /** Mark the report failed for good; no attempt will ever succeed. */
+    permanent: boolean;
+    /** The item exists at the target — persist it so the next attempt resumes instead of re-creating. */
+    externalId?: string;
+    externalUrl?: string | null;
+}
+/** Where the app keeps its reports. Implement it over your own database. */
+export interface FeedbackStore {
+    load(id: string): Promise<StoredFeedback | null>;
+    /** Record delivery — AND drop the stored screenshot bytes (rule 3). Clears any recorded error. */
+    markSubmitted(id: string, update: FeedbackSubmittedUpdate): Promise<void>;
+    /** Record a failed attempt (rule 1 and 2). */
+    recordFailure(id: string, update: FeedbackFailureUpdate): Promise<void>;
+}
+export type DispatchResult = {
+    outcome: 'submitted';
+    submission: FeedbackSubmission;
+} | {
+    outcome: 'missing';
+} | {
+    outcome: 'already_submitted';
+} | {
+    outcome: 'failed_permanently';
+    message: string;
+};
+export interface DispatchLogger {
+    log(message: string): void;
+    error(message: string): void;
+}
+export interface DispatchOptions {
+    store: FeedbackStore;
+    target: FeedbackTarget;
+    logger?: DispatchLogger;
+}
+/** Longest error message recorded on a report. */
+export declare const MAX_ERROR_LENGTH = 1000;
+/**
+ * Deliver one stored report.
+ *
+ * Resolves on success, on nothing-to-do, and on a PERMANENT failure (recorded — the
+ * failed report IS the alarm, and rethrowing would only burn the retry budget).
+ * Throws on a TRANSIENT failure, after recording it, so the caller's queue backs off
+ * and tries again. Any error that is not a FeedbackTargetError (a bug, a database
+ * hiccup) counts as transient: it is not known to be hopeless.
+ */
+export declare function dispatchFeedback(id: string, options: DispatchOptions): Promise<DispatchResult>;

package/dist/cjs/kernel/feedback/dispatch.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_ERROR_LENGTH = void 0;
+exports.dispatchFeedback = dispatchFeedback;
+// Delivering a STORED report to the configured target — the half of the design that
+// makes feedback honest about failure.
+//
+// The recommended shape is durable: the app confirms a report as soon as it is
+// stored, and delivery runs later from a job queue that provides backoff, an attempt
+// budget and an operator-visible failed state. A synchronous submit in the request
+// path would lose the report outright whenever the tracker is down — which is
+// precisely when people are filing bug reports.
+//
+// The package owns the RULES; the app owns storage and the queue, behind the small
+// FeedbackStore interface below. Three rules worth reading before changing anything:
+//
+// 1. THE EXTERNAL ID IS PERSISTED BEFORE THE ATTACHMENT UPLOAD IS RETRIED. Creating
+//    the item and uploading the screenshot are separate calls at most trackers; a
+//    failure between them must resume the upload, never create a second ticket. The
+//    target reports a post-create failure by carrying the id on the error, and it is
+//    recorded immediately.
+//
+// 2. PERMANENT FAILURES DO NOT RETRY. A bad token or a missing project fails
+//    identically on every attempt, and the delay only postpones the failed report
+//    someone needs to see. Transient failures are rethrown into the queue's backoff.
+//
+// 3. THE SCREENSHOT IS DELETED ON SUCCESS. Once the target holds the bytes, a second
+//    copy in the app's database is pure added exposure — markSubmitted must drop it
+//    (keeping only metadata such as type and size, if the app wants to show that one
+//    was attached).
+const types_ts_1 = require("./types.js");
+const defaultLogger = {
+    log: (m) => console.log(`[feedback] ${m}`),
+    error: (m) => console.error(`[feedback] ${m}`),
+};
+/** Longest error message recorded on a report. */
+exports.MAX_ERROR_LENGTH = 1_000;
+/**
+ * Deliver one stored report.
+ *
+ * Resolves on success, on nothing-to-do, and on a PERMANENT failure (recorded — the
+ * failed report IS the alarm, and rethrowing would only burn the retry budget).
+ * Throws on a TRANSIENT failure, after recording it, so the caller's queue backs off
+ * and tries again. Any error that is not a FeedbackTargetError (a bug, a database
+ * hiccup) counts as transient: it is not known to be hopeless.
+ */
+async function dispatchFeedback(id, options) {
+    const { store, target } = options;
+    const logger = options.logger ?? defaultLogger;
+    const stored = await store.load(id);
+    // Gone, or already delivered: complete rather than throw. A job that can never
+    // succeed must not retry to exhaustion and then sit failed with nothing for an
+    // operator to act on.
+    if (!stored) {
+        logger.log(`report ${id} no longer exists — skipping`);
+        return { outcome: 'missing' };
+    }
+    if (stored.status === 'submitted') {
+        logger.log(`report ${id} already submitted (${stored.externalId ?? '?'}) — skipping`);
+        return { outcome: 'already_submitted' };
+    }
+    try {
+        // Resume when the item already exists (create succeeded, upload didn't).
+        const resume = stored.externalId ? { externalId: stored.externalId } : undefined;
+        const submission = await target.submit(stored.report, resume);
+        await store.markSubmitted(id, {
+            targetName: target.name,
+            externalId: submission.externalId,
+            externalUrl: submission.externalUrl,
+            submittedAt: new Date(),
+        });
+        logger.log(`report ${id} -> ${target.name} ${submission.externalId}`);
+        return { outcome: 'submitted', submission };
+    }
+    catch (e) {
+        const err = e instanceof types_ts_1.FeedbackTargetError ? e : null;
+        const message = (e instanceof Error ? e.message : String(e)).slice(0, exports.MAX_ERROR_LENGTH);
+        const permanent = err?.permanent ?? false;
+        await store.recordFailure(id, {
+            targetName: target.name,
+            message,
+            permanent,
+            // Written the moment it is known — rule 1. Without it, the next attempt creates
+            // a duplicate ticket at any target whose create is not idempotent.
+            ...(err?.externalId ? { externalId: err.externalId, externalUrl: err.externalUrl ?? null } : {}),
+        });
+        if (permanent) {
+            logger.error(`report ${id} permanently failed: ${message}`);
+            return { outcome: 'failed_permanently', message };
+        }
+        throw e;
+    }
+}

package/dist/cjs/kernel/feedback/fake-target.d.ts

@@ -0,0 +1,58 @@
+import type { FeedbackTarget, FeedbackReport, FeedbackResume, FeedbackSubmission, TrustBoundary } from './types.js';
+import { FeedbackTargetError } from './types.js';
+export interface FakeSubmission {
+    report: FeedbackReport;
+    resume: FeedbackResume | undefined;
+    externalId: string;
+}
+export interface FakeFeedbackTargetOptions {
+    /** Origin used for the fake backlinks. */
+    webUrl?: string;
+    label?: string;
+}
+export declare class FakeFeedbackTarget implements FeedbackTarget {
+    readonly name = "fake";
+    readonly label: string;
+    /** Nothing leaves the process, so it is trivially inside the trust boundary. */
+    readonly trustBoundary: TrustBoundary;
+    /** Every submit() call, in order — including the ones that then threw. */
+    readonly submissions: FakeSubmission[];
+    /** Calls that actually created a new item (i.e. were not resumes). Duplicate-ticket detector. */
+    readonly creates: string[];
+    private seq;
+    private failures;
+    private readonly webUrl;
+    constructor(options?: FakeFeedbackTargetOptions);
+    /** Queue a failure for the NEXT submit() call (repeat to script a sequence). */
+    failNext(error: FeedbackTargetError): this;
+    /** Convenience: the two classifications, scripted. */
+    failNextTransient(message?: string): this;
+    failNextPermanent(message?: string): this;
+    /**
+     * Script the partial failure that resumability exists for: the item was created,
+     * the attachment upload then failed. The error carries the id, exactly as a real
+     * target does, so a durable caller can persist it and resume.
+     */
+    failNextAfterCreate(message?: string): this;
+    submit(report: FeedbackReport, resume?: FeedbackResume): Promise<FeedbackSubmission>;
+}
+/**
+ * A target that always fails permanently with a configuration message.
+ *
+ * This is what an unconfigured production deployment gets, and the choice is
+ * deliberate: reports are still PERSISTED and the failure is LOUD (a failed report
+ * naming the missing variables). The alternative — silently discarding reports, or
+ * refusing the button — would mean people file feedback into nothing and conclude the
+ * team ignored them.
+ *
+ * It is also why a missing variable does not throw at process BOOT: that would take
+ * every other job in the same worker down over a feedback misconfiguration.
+ */
+export declare class UnconfiguredFeedbackTarget implements FeedbackTarget {
+    readonly name = "unconfigured";
+    readonly trustBoundary: TrustBoundary;
+    readonly label: string;
+    private readonly reason;
+    constructor(reason: string, label?: string);
+    submit(_report?: FeedbackReport, _resume?: FeedbackResume): Promise<FeedbackSubmission>;
+}