Mobile Audit SDK

React Native / Expo compatible SDK for collecting structured notes on selected mobile UI elements.

The SDK is element based: users select a registered UI element, choose a nested child or parent when targets overlap, write a required note, save notes into a local queue, and submit the collected notes to your project API as plain JSON. Saved notes belong to an implicit draft audit session until the user submits or clears the queue.

Install

npm install @xtatistix/bugline-sdk

Peer dependencies:

npm install react react-native

Basic Usage

Wrap the app with AuditProvider and AuditSelectionRoot, then mark important UI elements with stable AuditSelectable ids.

import {
  AuditProvider,
  AuditSelectable,
  AuditSelectionRoot,
  AuditWidget,
  createAuditClient,
} from '@xtatistix/bugline-sdk';

const audit = createAuditClient({
  apiKey: 'project-api-key',
  endpoint: 'https://your-domain.com/api/audit/issues',
  environment: 'staging',
  projectId: 'mobile-app',
  sdkVersion: '0.1.0',
  reporter: {
    id: 'user-123',
    role: 'tester',
  },
  privacy: {
    enabled: true,
  },
});

export function App() {
  return (
    <AuditProvider client={audit}>
      <AuditSelectionRoot>
        <AuditSelectable id="top-bar" kind="navigation">
          <TopBar />
        </AuditSelectable>

        <AuditSelectable id="save-button" kind="button">
          <Button title="Save" />
        </AuditSelectable>

        <AuditWidget screenName="Profile" />
      </AuditSelectionRoot>
    </AuditProvider>
  );
}

Selection Behavior

• Registered elements are measured by AuditSelectionRoot.
• AuditSelectionOverlay outlines selectable elements while selection mode is active.
• Tapping a point selects the smallest matching child by default.
• The parent/child switcher lets the user move between nested targets.
• Confirming a target opens a required note flow.
• Saving a note keeps it in the local draft audit session.
• Category and severity are optional note metadata.
• Audit-only breadcrumbs track selection, save, delete, and submit events.
• Submitting the saved session creates Firebase-friendly plain JSON payloads.

Example nested target order:

SaveText -> SaveButton -> TopBar

Transport Boundary

The mobile SDK does not connect to Firebase directly. It sends JSON to your HTTP endpoint. The recommended backend boundary is:

Mobile SDK -> Next.js API route handler -> Firebase

The built-in HttpAuditTransport sends:

• content-type: application/json
• x-audit-api-key when apiKey is configured
• JSON body from buildElementNotePayload
• batch JSON body with { "session": {...}, "notes": [...] } when multiple saved notes are submitted together

Privacy

Privacy masking is enabled by default in the payload builder. The SDK redacts common sensitive keys and string patterns before JSON leaves the app:

• keys containing token, authorization, cookie, secret, password, email, or phone
• email addresses
• phone-like numeric strings
• bearer/JWT/API-token-like values

Override the defaults through createAuditClient({ privacy: ... }).

Payload Shape

buildElementNotePayload(...) returns a plain JSON-compatible object with:

• projectId
• environment
• sdkVersion
• screenName
• selectedElement
• ancestors
• children
• note
• category
• severity
• sessionId
• breadcrumbs
• createdAt

Element metadata can include stable ids, kind, text, testID, accessibilityLabel, role, path, bounds, and custom metadata.

Product Mobile App

The repository includes the product mobile app under apps/mobile. It is not a throwaway demo; this is the app surface we will keep evolving after the audit selection flow is stable.

Install mobile app dependencies:

cd apps/mobile
npm install

Start the mock endpoint from the repository root:

npm run mobile:mock-api

The mock server prints local network URLs. For a physical device, use the LAN URL it prints:

$env:EXPO_PUBLIC_AUDIT_ENDPOINT="http://YOUR_LAN_IP:4318/api/audit/issues"
cd apps/mobile
npm start

For iOS simulator or Android emulator, the mobile app has local defaults:

• iOS simulator: http://127.0.0.1:4318/api/audit/issues
• Android emulator: http://10.0.2.2:4318/api/audit/issues

Open selection mode from the floating Audit button, tap a nested element, switch parent/child if needed, and save a required note into the local queue. Double tap Audit to review saved notes, delete notes, or submit all saved notes together. Each queue is submitted as a draft audit session. The mock endpoint logs the received payloads and returns mock issueId values.

Submitted notes are stored in the mock server memory for the current process. After submitting the queue, download them as Markdown from:

http://YOUR_LAN_IP:4318/api/audit/issues.md

The current app includes a product-style audit workspace with queue, component-map, and settings surfaces so selection can be tested against nested navigation, segmented controls, panels, rows, buttons, and text nodes.

Package Commands

npm run typecheck
npm run build
npm pack --dry-run