@outcode/bug-reporter-core 0.1.0

package/LICENSE

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

@@ -0,0 +1,51 @@
+# @outcode/bug-reporter-core
+
+[![npm version](https://img.shields.io/npm/v/@outcode/bug-reporter-core.svg)](https://www.npmjs.com/package/@outcode/bug-reporter-core)
+[![npm downloads](https://img.shields.io/npm/dm/@outcode/bug-reporter-core.svg)](https://www.npmjs.com/package/@outcode/bug-reporter-core)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![types: TypeScript](https://img.shields.io/badge/types-TypeScript-3178c6.svg)](https://www.typescriptlang.org/)
+
+**Framework-agnostic core for the [OutCode Bug Reporter](https://github.com/OutCode-Software/bug-reporter).**
+No React or React Native — just types, the submit API, theming tokens, the offline retry queue, log/breadcrumb
+capture, and pluggable backend repositories (ClickUp included). Used by the
+[`web`](https://www.npmjs.com/package/@outcode/bug-reporter-web) and
+[`native`](https://www.npmjs.com/package/@outcode/bug-reporter-native) UI packages, and usable standalone
+in any JS/TS runtime with `fetch`.
+
+## Install
+
+```bash
+npm install @outcode/bug-reporter-core
+```
+
+## What's inside
+
+- **Types** — `BugReporterConfig`, `CreateReportParams`, `IBugReporterRepository`, severity/type/theme types
+- **`submitReport(config, options)`** — routes to a `repository` or POSTs to `apiUrl`
+- **`ClickUpBugReporterRepository`** — creates a task (priority from severity, type → tag, screenshot
+  attachment, markdown body with merged context + breadcrumbs)
+- **`installLogCapture()`** — rolling buffer of recent `console` warnings/errors + last failed `fetch`
+- **`ReportQueue` / `getReportQueue()`** — offline retry queue over any storage adapter
+- **Theme tokens** — `THEMES`, `resolveTheme()` (Indigo / Noir / Mint)
+- **Taxonomy + annotation model** — `SEVERITIES`, `REPORT_TYPES`, `ANNOTATION_TOOLS`, `Annotation`
+
+## Example: a custom backend
+
+```ts
+import type { IBugReporterRepository, CreateReportParams, BugReportResponse } from '@outcode/bug-reporter-core';
+
+class MyRepository implements IBugReporterRepository {
+  async createReport(params: CreateReportParams): Promise<BugReportResponse> {
+    const res = await fetch('https://api.example.com/bugs', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(params),
+    });
+    return { success: res.ok, id: (await res.json()).id };
+  }
+}
+```
+
+## License
+
+MIT © OutCode Software

package/dist/index.d.mts

@@ -0,0 +1,406 @@
+/**
+ * Theme tokens for the OC Bug Reporter UI, ported from the OC-BugReporter design.
+ * Platform-agnostic colour tokens; web applies them as CSS variables, native
+ * reads them directly. Three presets (indigo default, noir, mint); callers may
+ * also pass a partial override object.
+ */
+interface BugReporterTheme {
+    canvas: string;
+    surface: string;
+    panel: string;
+    border: string;
+    borderStrong: string;
+    text: string;
+    muted: string;
+    faint: string;
+    accent: string;
+    accentPress: string;
+    onAccent: string;
+    /** Translucent accent tint (selection / focus ring backgrounds). */
+    ring: string;
+    ok: string;
+    okBg: string;
+    /** CSS box-shadow string (web). Native composes its own elevation. */
+    shadow: string;
+    /** Whether this is a dark theme (affects native device frame / status bar). */
+    dark: boolean;
+}
+type BugReporterThemeName = 'indigo' | 'noir' | 'mint';
+declare const THEMES: Record<BugReporterThemeName, BugReporterTheme>;
+type ThemeInput = BugReporterThemeName | Partial<BugReporterTheme>;
+/** Resolve a theme name or partial override into a full token set (indigo base). */
+declare function resolveTheme(theme?: ThemeInput): BugReporterTheme;
+
+/**
+ * Shared types for OC Bug Reporter (React & React Native).
+ * Align with Flutter OC Bug Reporter spec when available.
+ */
+/** Report priority. Maps to backend priority (e.g. ClickUp 1=urgent … 4=low). */
+type ReportPriority = 'urgent' | 'high' | 'normal' | 'low';
+/** Severity selected in the report form (design taxonomy). Maps to priority. */
+type ReportSeverity = 'low' | 'medium' | 'high' | 'critical';
+/** Report type/category (design taxonomy). Mapped to a backend tag. */
+type ReportType = 'bug' | 'crash' | 'ui' | 'perf' | 'other';
+/** A single auto-captured context row (label → value) shown in the form and report. */
+interface ReportContextRow {
+    label: string;
+    value: string;
+    /** Optional severity hint for the row's value colour. */
+    flag?: 'err' | 'warn';
+}
+/** Screenshot capture options (size guard / encoding). */
+interface ScreenshotOptions {
+    /** Max width in pixels; larger captures are downscaled (aspect preserved). Default 1280. */
+    maxWidth?: number;
+    /** Output image format. Default 'png'. */
+    format?: 'png' | 'jpeg';
+    /** JPEG quality 0..1 (ignored for png). Default 0.92. */
+    quality?: number;
+}
+/**
+ * Minimal storage interface for the offline retry queue. Methods may be sync
+ * or async, so it works with both web `localStorage` and React Native
+ * `AsyncStorage` (pass `AsyncStorage` directly — its shape is compatible).
+ */
+interface ReportQueueStorage {
+    getItem(key: string): Promise<string | null> | string | null;
+    setItem(key: string, value: string): Promise<void> | void;
+    removeItem(key: string): Promise<void> | void;
+}
+interface BugReporterConfig {
+    /** API endpoint to submit bug reports (used when repository is not set) */
+    apiUrl?: string;
+    /** Application name (e.g. "CheckRidePro Web") */
+    appName: string;
+    /** Optional app version */
+    appVersion?: string;
+    /** Optional extra headers (e.g. Authorization) for default HTTP */
+    headers?: Record<string, string>;
+    /**
+     * Optional repository (ClickUp, Jira, or custom).
+     * When set, Submit uses repository.createReport() instead of POST to apiUrl.
+     */
+    repository?: IBugReporterRepository;
+    /**
+     * Optional static device info merged into every report (e.g. model, osVersion).
+     * Platform apps populate this (mobile: expo-device / expo-constants).
+     */
+    deviceInfo?: Record<string, unknown>;
+    /**
+     * Optional static package/app info merged into every report
+     * (e.g. packageName, buildNumber). Platform apps populate this.
+     */
+    packageInfo?: Record<string, unknown>;
+    /**
+     * Optional callback invoked at submit time to collect dynamic diagnostics
+     * (e.g. the last failed API call). Called fresh on every submit so the data
+     * reflects the moment the user reports the bug.
+     */
+    collectDiagnostics?: () => Record<string, unknown> | undefined;
+    /**
+     * Optional hook to add extra auto-captured context rows shown in the form and
+     * included in the report (e.g. network type via expo-network / NetInfo, build
+     * channel, feature flags, user tier). Called when the form opens; may be async.
+     * Use for anything consent-free that needs a native module the library can't
+     * safely depend on. Return rows or a plain `{ label: value }` object.
+     */
+    collectContext?: () => ReportContextRow[] | Record<string, string> | Promise<ReportContextRow[] | Record<string, string>>;
+    /** Default priority used when the user doesn't pick one in the modal. Defaults to 'normal'. */
+    defaultPriority?: ReportPriority;
+    /**
+     * UI theme: a preset name ('indigo' | 'noir' | 'mint') or a partial token
+     * override. Imported from the OC-BugReporter design. Defaults to 'indigo'.
+     */
+    theme?: ThemeInput;
+    /** Name shown in the form footer ("Filing to …"). Defaults to 'ClickUp'. */
+    backendName?: string;
+    /** Screenshot capture options (size guard / encoding) read by the platform capture. */
+    screenshot?: ScreenshotOptions;
+    /**
+     * Optional storage backing the offline retry queue. When set, reports that
+     * fail to submit are persisted and retried on next launch / next open.
+     * Web auto-defaults to `localStorage` when available; React Native should
+     * pass an `AsyncStorage`-compatible adapter here.
+     */
+    storage?: ReportQueueStorage;
+}
+interface BugReportRequest {
+    /** Short title/summary */
+    title: string;
+    /** User description of the bug */
+    description: string;
+    /** Optional base64 screenshot (web or native) */
+    screenshotBase64?: string;
+    /** Optional steps to reproduce */
+    stepsToReproduce?: string;
+    /** Optional device/app metadata (filled by core or platform) */
+    metadata?: BugReportMetadata;
+}
+interface BugReportMetadata {
+    appName?: string;
+    appVersion?: string;
+    platform?: string;
+    osVersion?: string;
+    userAgent?: string;
+    /** Any extra key-value data */
+    [key: string]: string | undefined;
+}
+interface BugReportResponse {
+    success: boolean;
+    id?: string;
+    message?: string;
+    /** True when the report could not be sent and was saved to the offline queue for retry. */
+    queued?: boolean;
+}
+/**
+ * Parameters for createReport (aligned with Flutter BugReporterRepository).
+ * Used by ClickUp, Jira, or custom repositories.
+ */
+interface CreateReportParams {
+    title: string;
+    description: string;
+    /** Base64 screenshot (optional). */
+    screenshotBase64?: string;
+    /** true = problem/bug list, false = suggestion list (e.g. ClickUp). */
+    isReportingProblem?: boolean;
+    /** Optional priority (maps to backend priority, e.g. ClickUp). */
+    priority?: ReportPriority;
+    /** Severity selected in the form (informational; also mapped into priority). */
+    severity?: ReportSeverity;
+    /** Report type/category. Backends may map this to a tag. */
+    type?: ReportType;
+    /** Tags to attach to the created item (e.g. ClickUp tags). */
+    tags?: string[];
+    /**
+     * Auto-captured context rows shown in the form (route, platform, viewport,
+     * release, console/network summary…). Rendered into the report body, merged
+     * with app/device info.
+     */
+    context?: {
+        label: string;
+        value: string;
+    }[];
+    deviceInfo: Record<string, unknown>;
+    packageInfo: Record<string, unknown>;
+    userInfo?: Record<string, unknown>;
+    /** Dynamic diagnostics collected at submit time (e.g. lastFailedApiCall). */
+    diagnostics?: Record<string, unknown>;
+}
+/**
+ * Repository interface for bug/suggestion reports.
+ * Implementations: ClickUpBugReporterRepository, JiraBugReporterRepository, or custom.
+ * When provided in config, Submit uses this instead of the default HTTP POST.
+ */
+interface IBugReporterRepository {
+    createReport(params: CreateReportParams): Promise<BugReportResponse>;
+}
+
+/**
+ * Report taxonomy + annotation model shared by web and native, ported from the
+ * OC-BugReporter design. Severity maps to backend priority; type becomes a tag.
+ */
+
+/** Normalize a collectContext() result (array or `{label: value}` object) into rows. */
+declare function normalizeContext(input?: ReportContextRow[] | Record<string, string> | null): ReportContextRow[];
+declare const SEVERITIES: {
+    id: ReportSeverity;
+    label: string;
+    color: string;
+}[];
+declare const REPORT_TYPES: {
+    id: ReportType;
+    label: string;
+}[];
+/** Annotation palette (matches the design's 8-swatch toolbar). */
+declare const ANNOTATION_COLORS: string[];
+type AnnotationTool = 'pen' | 'arrow' | 'rect' | 'blur' | 'text';
+/** Toolbar tools with their SVG icon paths (rendered identically on web + native). */
+declare const ANNOTATION_TOOLS: {
+    id: AnnotationTool;
+    label: string;
+    iconPath: string;
+}[];
+/** Map design severity to backend (ClickUp) priority. */
+declare function severityToPriority(severity?: ReportSeverity): ReportPriority | undefined;
+interface Point {
+    x: number;
+    y: number;
+}
+interface PenAnnotation {
+    id: string;
+    type: 'pen';
+    color: string;
+    points: Point[];
+}
+interface BoxAnnotation {
+    id: string;
+    type: 'arrow' | 'rect' | 'blur';
+    color: string;
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+interface TextAnnotation {
+    id: string;
+    type: 'text';
+    color: string;
+    x: number;
+    y: number;
+    text: string;
+}
+type Annotation = PenAnnotation | BoxAnnotation | TextAnnotation;
+
+/**
+ * API client for submitting bug reports.
+ * Platform-agnostic (no React/React Native).
+ */
+
+declare function submitBugReport(request: BugReportRequest, config: BugReporterConfig): Promise<BugReportResponse>;
+/** Options accepted by {@link submitReport}; also the unit persisted by the offline queue. */
+interface SubmitReportOptions {
+    title: string;
+    description: string;
+    screenshotBase64?: string;
+    isReportingProblem?: boolean;
+    priority?: ReportPriority;
+    severity?: ReportSeverity;
+    type?: ReportType;
+    tags?: string[];
+    /** Auto-captured context rows to include in the report body. */
+    context?: {
+        label: string;
+        value: string;
+    }[];
+    metadata?: Record<string, string | undefined>;
+}
+/**
+ * Build the repository's CreateReportParams from config + submit options.
+ * Diagnostics are collected fresh here (via config.collectDiagnostics) so a
+ * replayed/queued report reflects the moment it is actually sent.
+ */
+declare function buildCreateReportParams(config: BugReporterConfig, options: SubmitReportOptions): CreateReportParams;
+/**
+ * Submit a report using config.repository if set, otherwise default HTTP (apiUrl).
+ * Builds CreateReportParams from title, description, screenshot, and config/metadata.
+ */
+declare function submitReport(config: BugReporterConfig, options: SubmitReportOptions): Promise<BugReportResponse>;
+
+/**
+ * Offline retry queue for bug reports.
+ * When a submit fails (offline, server error), the report is persisted and
+ * replayed later via the current config. Platform-agnostic: works with any
+ * ReportQueueStorage (web localStorage, RN AsyncStorage).
+ */
+
+declare class ReportQueue {
+    private readonly storage;
+    private readonly key;
+    constructor(storage: ReportQueueStorage, key?: string);
+    private read;
+    private write;
+    /** Number of reports currently waiting to be retried. */
+    size(): Promise<number>;
+    /** Persist a report that failed to send. Oldest entries are dropped past the cap. */
+    enqueue(options: SubmitReportOptions): Promise<void>;
+    /**
+     * Replay all queued reports using the current config. Reports that submit
+     * successfully are removed; failures stay queued for the next attempt.
+     */
+    flush(config: BugReporterConfig): Promise<{
+        flushed: number;
+        remaining: number;
+    }>;
+}
+/** Build a ReportQueue from config.storage, or undefined when no storage is configured. */
+declare function getReportQueue(config: BugReporterConfig): ReportQueue | undefined;
+
+/**
+ * Optional automatic diagnostics capture.
+ *
+ * `installLogCapture()` patches `console` (and optionally `fetch`) to keep a
+ * rolling ring buffer of recent log lines plus the last failed network call.
+ * Wire its `collect()` into `BugReporterConfig.collectDiagnostics` so every
+ * report carries recent context automatically — turning "it's broken" tickets
+ * into actionable ones.
+ *
+ * Platform-agnostic: `console` and `fetch` exist on web and React Native.
+ */
+type LogLevel = 'log' | 'info' | 'warn' | 'error';
+interface Breadcrumb {
+    level: LogLevel;
+    message: string;
+    /** ISO timestamp. */
+    timestamp: string;
+}
+interface LastFailedApiCall {
+    method?: string;
+    url?: string;
+    status?: number;
+    code?: string;
+    message?: string;
+    timestamp?: string;
+}
+interface LogCaptureOptions {
+    /** Console levels to record. Default ['warn', 'error']. */
+    levels?: LogLevel[];
+    /** Max breadcrumbs retained (ring buffer). Default 25. */
+    max?: number;
+    /** Also wrap global fetch to record failed requests. Default true. */
+    captureFetch?: boolean;
+}
+interface LogCaptureHandle {
+    getBreadcrumbs(): Breadcrumb[];
+    getLastFailedApiCall(): LastFailedApiCall | undefined;
+    /** Snapshot suitable to spread into diagnostics (`{ breadcrumbs, lastFailedApiCall }`). */
+    collect(): Record<string, unknown>;
+    clear(): void;
+    /** Restore the original console/fetch. */
+    uninstall(): void;
+}
+/**
+ * Install console/fetch capture. Call once near app startup. The returned
+ * handle exposes the collected data and an `uninstall()` to undo the patches.
+ */
+declare function installLogCapture(options?: LogCaptureOptions): LogCaptureHandle;
+
+/**
+ * ClickUp implementation of the bug reporter repository.
+ * Creates bug/suggestion reports as tasks in ClickUp and uploads screenshot as attachment.
+ * Aligned with Flutter ClickUpBugReporterRepository.
+ */
+
+interface ClickUpBugReporterRepositoryOptions {
+    /** ClickUp API key (used in Authorization header) */
+    apiKey: string;
+    /** ClickUp list ID for problem/bug reports */
+    problemListId: string;
+    /** ClickUp list ID for suggestion reports */
+    suggestionListId: string;
+    /**
+     * Optional initial status to set on created tasks (e.g. 'triage'). Must be a
+     * valid status on the target list, or ClickUp rejects the task. Omit to use
+     * the list's default status.
+     */
+    status?: string;
+}
+/**
+ * ClickUp bug reporter repository.
+ * Use when your project uses ClickUp for bug/suggestion tracking.
+ */
+declare class ClickUpBugReporterRepository implements IBugReporterRepository {
+    private readonly options;
+    constructor(options: ClickUpBugReporterRepositoryOptions);
+    createReport(params: CreateReportParams): Promise<BugReportResponse>;
+    private buildDescription;
+    /**
+     * Attach tags to an already-created task. ClickUp rejects unknown tag names on
+     * the create-task call (failing the whole report), so we attach afterwards and
+     * swallow failures — a missing/uncreatable tag never costs the user their report.
+     * Tags must already exist in the Space to actually attach.
+     */
+    private attachTags;
+    private uploadAttachment;
+}
+
+export { ANNOTATION_COLORS, ANNOTATION_TOOLS, type Annotation, type AnnotationTool, type BoxAnnotation, type Breadcrumb, type BugReportMetadata, type BugReportRequest, type BugReportResponse, type BugReporterConfig, type BugReporterTheme, type BugReporterThemeName, ClickUpBugReporterRepository, type ClickUpBugReporterRepositoryOptions, type CreateReportParams, type IBugReporterRepository, type LastFailedApiCall, type LogCaptureHandle, type LogCaptureOptions, type LogLevel, type PenAnnotation, type Point, REPORT_TYPES, type ReportContextRow, type ReportPriority, ReportQueue, type ReportQueueStorage, type ReportSeverity, type ReportType, SEVERITIES, type ScreenshotOptions, type SubmitReportOptions, THEMES, type TextAnnotation, type ThemeInput, buildCreateReportParams, getReportQueue, installLogCapture, normalizeContext, resolveTheme, severityToPriority, submitBugReport, submitReport };