@outcode/bug-reporter-native 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,93 @@
+# @outcode/bug-reporter-native
+
+[![npm version](https://img.shields.io/npm/v/@outcode/bug-reporter-native.svg)](https://www.npmjs.com/package/@outcode/bug-reporter-native)
+[![npm downloads](https://img.shields.io/npm/dm/@outcode/bug-reporter-native.svg)](https://www.npmjs.com/package/@outcode/bug-reporter-native)
+[![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/)
+
+**In-app bug reporter for React Native & Expo.** A draggable floating button captures the current screen,
+lets users annotate it (draw, arrow, box, blur, text), set a severity and type, and file a report to
+**ClickUp** or any custom backend.
+
+> Part of the [OutCode Bug Reporter](https://github.com/OutCode-Software/bug-reporter) monorepo.
+> For React web, see [`@outcode/bug-reporter-web`](https://www.npmjs.com/package/@outcode/bug-reporter-web).
+
+## Features
+
+- 🐛 **Draggable floating button** that snaps to the screen edge
+- ✏️ **Annotate** — pen, arrow, box, **blur/redact**, and text on the captured screenshot
+- 🧭 **Auto-captured context** — platform, OS, screen, density, orientation, language, color scheme… consent-free
+- 🎨 **Themeable** — Indigo / Noir / Mint presets or your own tokens
+- 📡 **Offline retry queue**, **breadcrumb capture**, screenshot compression
+- 🧩 **Pluggable backends** — ClickUp out of the box, or any `repository` / HTTP endpoint
+- 📦 ESM + CJS, fully typed; native peers are externalized (never bundled)
+
+## Install
+
+```bash
+npm install @outcode/bug-reporter-native @outcode/bug-reporter-core
+# peers (use `npx expo install …` on Expo):
+npm install react-native-svg react-native-view-shot react-native-safe-area-context
+```
+
+> **Requires a dev build / bare workflow** — `react-native-view-shot` ships native code that is **not** in
+> the Expo Go sandbox. Screen capture silently returns nothing in Expo Go; run a dev build
+> (`expo run:ios` / `expo run:android` / EAS Build).
+
+## Quick start
+
+Wrap your app so the reporter can screenshot the current screen, then mount the button:
+
+```tsx
+import {
+  BugReporterButton,
+  BugReporterCaptureRefProvider,
+  BugReporterScreenCaptureView,
+} from '@outcode/bug-reporter-native';
+import { ClickUpBugReporterRepository } from '@outcode/bug-reporter-core';
+
+export default function App() {
+  return (
+    <BugReporterCaptureRefProvider>
+      <BugReporterScreenCaptureView style={{ flex: 1 }}>
+        {/* …your navigator / screens… */}
+      </BugReporterScreenCaptureView>
+
+      <BugReporterButton
+        config={{
+          appName: 'My Mobile App',
+          appVersion: '1.0.0',
+          theme: 'indigo',
+          repository: new ClickUpBugReporterRepository({ apiKey, problemListId, suggestionListId }),
+        }}
+      />
+    </BugReporterCaptureRefProvider>
+  );
+}
+```
+
+### WiFi / cellular context (optional)
+
+The reporter auto-captures consent-free context. To add network type on native, inject it via
+`collectContext` (e.g. with [`expo-network`](https://docs.expo.dev/versions/latest/sdk/network/)):
+
+```ts
+import * as Network from 'expo-network';
+
+config={{
+  // …
+  collectContext: async () => {
+    const n = await Network.getNetworkStateAsync();
+    return { Network: n.type, Online: String(n.isConnected) };
+  },
+}}
+```
+
+## Configuration
+
+Full `BugReporterConfig` reference lives in the
+[root README](https://github.com/OutCode-Software/bug-reporter#readme).
+
+## License
+
+MIT © OutCode Software

package/dist/index.d.mts

@@ -0,0 +1,139 @@
+import React, { RefObject } from 'react';
+import { ScreenshotOptions, BugReporterConfig, BugReporterTheme, AnnotationTool, ReportSeverity, ReportType } from '@outcode/bug-reporter-core';
+import { View } from 'react-native';
+
+/**
+ * Capture a React Native view as base64 (for API) or data URI (for display).
+ * Uses react-native-view-shot.
+ * Prefers captureScreen() (full screen, no ref) when available; falls back to captureRef(view).
+ */
+
+type CaptureViewRef = RefObject<View | null>;
+/**
+ * Capture the given view as base64 string.
+ * Pass the ref of the View that wraps the screen content (e.g. the navigator container).
+ */
+declare function captureViewBase64(viewRef: CaptureViewRef, options?: ScreenshotOptions): Promise<string | undefined>;
+/**
+ * Capture the full screen. Returns data URI or file URI (both valid for Image source).
+ * Tries data-uri first (displays reliably in Image); falls back to tmpfile.
+ */
+declare function captureScreenDataUri(options?: ScreenshotOptions): Promise<string | undefined>;
+/**
+ * Capture the current screen as data URI (for Image source).
+ * Tries full-screen capture first (no ref needed), then ref-based if a ref is provided.
+ */
+declare function captureViewDataUri(viewRef?: CaptureViewRef | null, options?: ScreenshotOptions): Promise<string | undefined>;
+/** Strip data URL prefix to get raw base64 for API. */
+declare function dataUrlToBase64(dataUrl: string): string;
+
+/**
+ * Bug reporter (native) — floating button + capture→annotate→form→done flow,
+ * mirroring the OC-BugReporter design. Orchestrates the step state machine and
+ * hosts the themed overlays (annotate editor, bottom-sheet form, success card).
+ */
+
+interface BugReporterButtonProps {
+    config: BugReporterConfig;
+    captureRef?: CaptureViewRef;
+    label?: string;
+}
+declare function BugReporterButton({ config, captureRef, label }: BugReporterButtonProps): React.JSX.Element;
+
+/**
+ * Full-screen annotation editor (native) — mirrors the OC-BugReporter design.
+ * Tools: pen, arrow, box, blur (opaque redaction), text. Static header keeps
+ * Back / Delete / Continue always reachable; text is edited in a keyboard-safe
+ * top bar (and tapping an existing label re-opens it). Flattened via captureRef.
+ */
+
+interface AnnotateOverlayProps {
+    t: BugReporterTheme;
+    visible: boolean;
+    src: string;
+    onCancel: () => void;
+    onContinue: (flattenedDataUrl: string, annotationCount: number) => void;
+}
+declare function AnnotateOverlay({ t, visible, src, onCancel, onContinue }: AnnotateOverlayProps): React.JSX.Element;
+
+/**
+ * Annotation toolbar (native) — tools, colors, undo/clear, Continue.
+ * Mirrors the OC-BugReporter AnnotateToolbar design. Themed via the token object.
+ */
+
+interface AnnotateToolbarProps {
+    t: BugReporterTheme;
+    tool: AnnotationTool;
+    color: string;
+    onTool: (tool: AnnotationTool) => void;
+    onColor: (c: string) => void;
+    onUndo: () => void;
+}
+declare function AnnotateToolbar({ t, tool, color, onTool, onColor, onUndo }: AnnotateToolbarProps): React.JSX.Element;
+
+/**
+ * Bug report form (native) — mirrors the OC-BugReporter BugReportForm design.
+ * Rendered inside a bottom sheet by the orchestrator.
+ */
+
+interface MetaRow {
+    label: string;
+    value: string;
+    flag?: 'err' | 'warn';
+}
+interface BugReportFormProps {
+    t: BugReporterTheme;
+    screenshotUrl?: string;
+    annotationCount: number;
+    title: string;
+    description: string;
+    severity: ReportSeverity;
+    type: ReportType;
+    meta: MetaRow[];
+    backendName: string;
+    submitting: boolean;
+    error?: string;
+    onTitle: (v: string) => void;
+    onDescription: (v: string) => void;
+    onSeverity: (s: ReportSeverity) => void;
+    onType: (t: ReportType) => void;
+    onBack: () => void;
+    onClose: () => void;
+    onEditAnnotations: () => void;
+    onSubmit: () => void;
+}
+declare function BugReportForm(props: BugReportFormProps): React.JSX.Element;
+
+/**
+ * Success card (native) — mirrors the OC-BugReporter "Report filed" state.
+ */
+
+interface SuccessCardProps {
+    t: BugReporterTheme;
+    ticket?: string;
+    ticketTitle: string;
+    backendName: string;
+    onDone: () => void;
+}
+declare function SuccessCard({ t, ticket, ticketTitle, backendName, onDone }: SuccessCardProps): React.JSX.Element;
+
+/**
+ * Optional context so the current screen can register its root View for screenshot capture.
+ * Use when capturing the app-level wrapper (e.g. around NavigationContainer) returns empty
+ * or wrong content (e.g. on Android with native stack). Wrap screen content in
+ * BugReporterScreenCaptureView or call useSetBugReporterCaptureRef(ref).
+ */
+
+declare function BugReporterCaptureRefProvider({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** Call from the current screen to register its root View for capture. Unregisters on unmount. */
+declare function useSetBugReporterCaptureRef(ref: CaptureViewRef | null): void;
+declare function useBugReporterCaptureRef(): CaptureViewRef | null;
+/** Wraps screen content so this view is used for bug report screenshots. Use inside screens when app-level capture is empty. */
+declare function BugReporterScreenCaptureView({ children, style, }: {
+    children: React.ReactNode;
+    style?: React.ComponentProps<typeof View>['style'];
+}): React.JSX.Element;
+
+export { AnnotateOverlay, type AnnotateOverlayProps, AnnotateToolbar, BugReportForm, type BugReportFormProps, BugReporterButton, type BugReporterButtonProps, BugReporterCaptureRefProvider, BugReporterScreenCaptureView, type CaptureViewRef, type MetaRow, SuccessCard, captureScreenDataUri, captureViewBase64, captureViewDataUri, dataUrlToBase64, useBugReporterCaptureRef, useSetBugReporterCaptureRef };

package/dist/index.d.ts

@@ -0,0 +1,139 @@
+import React, { RefObject } from 'react';
+import { ScreenshotOptions, BugReporterConfig, BugReporterTheme, AnnotationTool, ReportSeverity, ReportType } from '@outcode/bug-reporter-core';
+import { View } from 'react-native';
+
+/**
+ * Capture a React Native view as base64 (for API) or data URI (for display).
+ * Uses react-native-view-shot.
+ * Prefers captureScreen() (full screen, no ref) when available; falls back to captureRef(view).
+ */
+
+type CaptureViewRef = RefObject<View | null>;
+/**
+ * Capture the given view as base64 string.
+ * Pass the ref of the View that wraps the screen content (e.g. the navigator container).
+ */
+declare function captureViewBase64(viewRef: CaptureViewRef, options?: ScreenshotOptions): Promise<string | undefined>;
+/**
+ * Capture the full screen. Returns data URI or file URI (both valid for Image source).
+ * Tries data-uri first (displays reliably in Image); falls back to tmpfile.
+ */
+declare function captureScreenDataUri(options?: ScreenshotOptions): Promise<string | undefined>;
+/**
+ * Capture the current screen as data URI (for Image source).
+ * Tries full-screen capture first (no ref needed), then ref-based if a ref is provided.
+ */
+declare function captureViewDataUri(viewRef?: CaptureViewRef | null, options?: ScreenshotOptions): Promise<string | undefined>;
+/** Strip data URL prefix to get raw base64 for API. */
+declare function dataUrlToBase64(dataUrl: string): string;
+
+/**
+ * Bug reporter (native) — floating button + capture→annotate→form→done flow,
+ * mirroring the OC-BugReporter design. Orchestrates the step state machine and
+ * hosts the themed overlays (annotate editor, bottom-sheet form, success card).
+ */
+
+interface BugReporterButtonProps {
+    config: BugReporterConfig;
+    captureRef?: CaptureViewRef;
+    label?: string;
+}
+declare function BugReporterButton({ config, captureRef, label }: BugReporterButtonProps): React.JSX.Element;
+
+/**
+ * Full-screen annotation editor (native) — mirrors the OC-BugReporter design.
+ * Tools: pen, arrow, box, blur (opaque redaction), text. Static header keeps
+ * Back / Delete / Continue always reachable; text is edited in a keyboard-safe
+ * top bar (and tapping an existing label re-opens it). Flattened via captureRef.
+ */
+
+interface AnnotateOverlayProps {
+    t: BugReporterTheme;
+    visible: boolean;
+    src: string;
+    onCancel: () => void;
+    onContinue: (flattenedDataUrl: string, annotationCount: number) => void;
+}
+declare function AnnotateOverlay({ t, visible, src, onCancel, onContinue }: AnnotateOverlayProps): React.JSX.Element;
+
+/**
+ * Annotation toolbar (native) — tools, colors, undo/clear, Continue.
+ * Mirrors the OC-BugReporter AnnotateToolbar design. Themed via the token object.
+ */
+
+interface AnnotateToolbarProps {
+    t: BugReporterTheme;
+    tool: AnnotationTool;
+    color: string;
+    onTool: (tool: AnnotationTool) => void;
+    onColor: (c: string) => void;
+    onUndo: () => void;
+}
+declare function AnnotateToolbar({ t, tool, color, onTool, onColor, onUndo }: AnnotateToolbarProps): React.JSX.Element;
+
+/**
+ * Bug report form (native) — mirrors the OC-BugReporter BugReportForm design.
+ * Rendered inside a bottom sheet by the orchestrator.
+ */
+
+interface MetaRow {
+    label: string;
+    value: string;
+    flag?: 'err' | 'warn';
+}
+interface BugReportFormProps {
+    t: BugReporterTheme;
+    screenshotUrl?: string;
+    annotationCount: number;
+    title: string;
+    description: string;
+    severity: ReportSeverity;
+    type: ReportType;
+    meta: MetaRow[];
+    backendName: string;
+    submitting: boolean;
+    error?: string;
+    onTitle: (v: string) => void;
+    onDescription: (v: string) => void;
+    onSeverity: (s: ReportSeverity) => void;
+    onType: (t: ReportType) => void;
+    onBack: () => void;
+    onClose: () => void;
+    onEditAnnotations: () => void;
+    onSubmit: () => void;
+}
+declare function BugReportForm(props: BugReportFormProps): React.JSX.Element;
+
+/**
+ * Success card (native) — mirrors the OC-BugReporter "Report filed" state.
+ */
+
+interface SuccessCardProps {
+    t: BugReporterTheme;
+    ticket?: string;
+    ticketTitle: string;
+    backendName: string;
+    onDone: () => void;
+}
+declare function SuccessCard({ t, ticket, ticketTitle, backendName, onDone }: SuccessCardProps): React.JSX.Element;
+
+/**
+ * Optional context so the current screen can register its root View for screenshot capture.
+ * Use when capturing the app-level wrapper (e.g. around NavigationContainer) returns empty
+ * or wrong content (e.g. on Android with native stack). Wrap screen content in
+ * BugReporterScreenCaptureView or call useSetBugReporterCaptureRef(ref).
+ */
+
+declare function BugReporterCaptureRefProvider({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** Call from the current screen to register its root View for capture. Unregisters on unmount. */
+declare function useSetBugReporterCaptureRef(ref: CaptureViewRef | null): void;
+declare function useBugReporterCaptureRef(): CaptureViewRef | null;
+/** Wraps screen content so this view is used for bug report screenshots. Use inside screens when app-level capture is empty. */
+declare function BugReporterScreenCaptureView({ children, style, }: {
+    children: React.ReactNode;
+    style?: React.ComponentProps<typeof View>['style'];
+}): React.JSX.Element;
+
+export { AnnotateOverlay, type AnnotateOverlayProps, AnnotateToolbar, BugReportForm, type BugReportFormProps, BugReporterButton, type BugReporterButtonProps, BugReporterCaptureRefProvider, BugReporterScreenCaptureView, type CaptureViewRef, type MetaRow, SuccessCard, captureScreenDataUri, captureViewBase64, captureViewDataUri, dataUrlToBase64, useBugReporterCaptureRef, useSetBugReporterCaptureRef };