@vectorcloud/bug-capture

Browser SDK for submitting Bug Desk reports from organization-owned internal web apps.

For mobile apps, use the separate mobile capture contract under sdk/bug-capture-mobile / @vectorcloud/bug-capture-mobile. Mobile clients reuse the same Bug Desk backend but use bug-desk-mobile-capture.v1, mobile app identity, and bundle/package ID validation instead of browser Origin validation.

Vector Setup

Before installing the SDK in a host app, create the Bug Desk app registration in Vector:

1. In Vector, open the target organization.
2. Go to Bug Desk -> Applications.
3. Create or open the application that will send reports.
4. Set the application key. This must match appKey in VectorBugCapture.init.
5. Add an environment such as production or staging. This must match environment in VectorBugCapture.init.
6. In the app detail page, find SDK Keys.
7. Enter allowed origins, one per line, for example https://billing.example.com.
8. Click Create SDK key.
9. Copy the plaintext vbd_... key immediately. Vector shows it only once.

Use exact browser origins only: scheme + host + optional port. Do not include paths, query strings, or wildcards.

The Vector values map to SDK init like this:

• Vector organization ID -> orgId
• Vector organization slug/key -> orgKey
• Bug Desk application key -> appKey
• Bug Desk environment key -> environment
• SDK key shown once after creation -> sdkKey
• Vector API origin -> apiBaseUrl

Install

npm install @vectorcloud/bug-capture

Initialize

import { VectorBugCapture } from '@vectorcloud/bug-capture';

VectorBugCapture.init({
  orgId: '00000000-0000-4000-8000-000000000001',
  orgKey: 'acme',
  appKey: 'billing-portal',
  environment: 'production',
  sdkKey: 'vbd_...',
  apiBaseUrl: 'https://api.vectorcloud.in',
  clientVersion: '1.4.2',
  buildIdentity: {
    appVersion: '1.4.2',
    buildSha: 'abc123',
    bundleVersion: 'web-2026.05.02',
    releaseChannel: 'stable',
    deploymentId: 'deploy-123',
    environment: 'production',
  },
});

await VectorBugCapture.loadCapturePolicy();

The server verifies the SDK key, registered application, environment, and request origin before returning a capture policy. Host apps must refresh policy before capture and must not start screenshot/video capture if the requested mode is not in allowedModes.

Local development (localhost)

• Application “Allowed origins” (saved on the Bug Desk application) is not the same list the server uses for SDK capture-policy. The API resolves your key, then checks the browser Origin against allowedOrigins stored on that SDK key when the key was created. If you only added http://localhost:5173 to the application policy but the key was created earlier without it, create a new SDK key (or ensure the create-key step included every dev origin you need).

• http://localhost:PORT and http://127.0.0.1:PORT are different origins — add the one your dev server actually opens in the browser.

• Pass developmentMode: true in VectorBugCapture.init({ ... }) (local / staging only) to print a console reminder with the current window.location.origin. Omit in production. It does not relax server rules; failed policy loads still throw with an explicit message (and 403 responses include origin guidance when the body is JSON).

• CORS: the browser must be allowed to POST to apiBaseUrl from your dev origin; that is configured on the API, not inside this SDK.

Drop-In Widget

The modal matches Vector’s out-of-the-box flow: a compact Capture evidence launcher first — title row + icon-only screenshot / record + seconds in one horizontal row (no in-launcher body copy or Close control; dismiss with outside click or Escape). With mountWidget, that launcher is anchored under the SDK button (same geometry as Vector’s header quick-capture). The browser’s screen-share picker uses the same constraints as Vector (preferCurrentTab, browser surface) so Chrome opens on Chrome tab and emphasizes the invoking tab. While the picker is open, the SDK hides its overlay so the native UI is not covered. Only after capture succeeds does the Bug Desk capture detail sheet open (centered: evidence summary, preview, fields, submit).

Hosts that call openWidget() without mountWidget can pass launcherAnchor: yourButton to get the same anchored launcher, or omit it for a centered launcher.

For the lowest-code integration, mount the SDK-provided button and modal:

VectorBugCapture.mountWidget({
  target: '#bug-report-slot',
  buttonLabel: 'Report bug',
  position: 'inline',
  defaultMode: 'image_only',
  theme: {
    primaryColor: 'rgb(37 99 235)',
    borderRadius: '12px',
    fontFamily: 'Inter, sans-serif',
  },
});

Header / app-chrome (icon only, same affordance as Vector web): pass launcherPresentation: 'icon'. The launcher is a bug-outline control; buttonLabel becomes aria-label and title only.

VectorBugCapture.mountWidget({
  target: '#header-bug-slot',
  position: 'inline',
  launcherPresentation: 'icon',
  buttonLabel: 'Report a bug',
  theme: {
    textColor: 'rgb(30 41 59)',
    primaryColor: 'rgb(79 70 229)',
  },
});

Errors and UI

• Launcher click, before the modal opens (for example loadCapturePolicy fails): the SDK shows a red role="alert" paragraph under the launcher inside the widget shadow (so you still see the failure without opening the modal).
• Inside the modal: validation / unsupported-browser messages use the .vbc-error style in the modal markup.

The widget handles:

• server policy loading and allowed capture modes
• launcher-first capture (screenshot or record) then the full report form
• user-triggered browser screen/window/tab permission
• screenshot capture
• video capture capped by maxCaptureVideoSeconds (optional seconds on the launcher before record)
• title, behavior, expected behavior, and repro-step form fields
• screenshot/video preview state
• recapture, delete screenshot, delete video, and downgrade to image-only
• Bug Desk submit and media upload

The browser permission dialog is still native to the browser. The SDK never starts screen capture silently.

CDN / Script Tag

For older apps without a modern bundler, publish and load dist/index.global.js from your approved CDN:

<script src="https://cdn.vectorcloud.in/bug-capture/v0.1.7/index.global.js"></script>
<script>
  window.VectorBugCapture.init({
    orgId: '00000000-0000-4000-8000-000000000001',
    orgKey: 'acme',
    appKey: 'billing-portal',
    environment: 'production',
    sdkKey: 'vbd_...',
    apiBaseUrl: 'https://api.vectorcloud.in',
    buildIdentity: {
      appVersion: '1.4.2',
      buildSha: 'abc123',
      bundleVersion: 'web-2026.05.02',
      releaseChannel: 'stable',
      deploymentId: 'deploy-123',
      environment: 'production'
    }
  });
  window.VectorBugCapture.mountWidget({ position: 'bottom-right' });
</script>

Enterprise Helpers

• VectorBugCapture.diagnose() verifies initialization, backend reachability, capture policy, origin/app/key acceptance, and browser capture support.
• VectorBugCapture.getBrowserSupport() returns HTTPS, getDisplayMedia, ImageCapture, and MediaRecorder availability.
• VectorBugCapture.getRedactionPreview() returns included and excluded diagnostic categories for trust messaging.
• VectorBugCapture.attachAxios(axios) adds safe Axios request/response timing capture.
• The SDK automatically instruments fetch, XMLHttpRequest, console, and browser history fallback navigation.
• VectorBugCapture.destroy() unmounts the widget and restores patched browser APIs.
• Failed report submissions are saved as no-secret local drafts. Use listDrafts(), retryDraft(id), and deleteDraft(id).

Host-App Integration Points

• Action trail: call VectorBugCapture.recordAction(surfaceName, eventName, selector) with safe surface names. The SDK stores selector hashes, not raw selectors.
• Router context: call VectorBugCapture.recordNavigation(from, to) from your router. The SDK also installs a browser-history fallback and redacts query secrets.
• Feature flags: register VectorBugCapture.registerFeatureFlagProvider(() => flags) using flag keys and primitive values only.
• Build identity: pass buildIdentity during init.
• Client/project context: register providers with registerClientContextProvider and registerProjectContextProvider.
• Component boundary: call recordComponentBoundary(name) from error boundaries or route-level boundaries.
• Retry history: call recordRetry({ endpointKey, attempt, reason, statusCode }) from your API client retry wrapper.
• Form summaries: first call registerFormSchema(formKey, safeFieldNames), then call recordFormSummary(formKey, { dirtyFieldCount, invalidFieldCount }). Do not pass raw values.
• Cache/state summaries: first call registerCacheNamespace(namespace), then call recordCacheSummary(namespace, { version, keyCount, hashedKeys }). Hash cache keys in the host app; do not pass raw store state or raw cache contents.

Launcher Pattern

Add a host-owned button in a header, help menu, command palette, or floating support widget. The button should call:

const preview = await VectorBugCapture.startCapture('image_only');
// or:
const preview = await VectorBugCapture.startCapture('image_and_video');
// optional second argument: requested record length in seconds (clamped to server max)
const previewWithClip = await VectorBugCapture.startCapture('image_and_video', 8);

Show the returned preview to the reporter before submit. The preview exposes:

• screenshot
• video
• deleteScreenshot()
• deleteVideo()
• downgradeToImageOnly()

Video duration is capped by the server-issued maxCaptureVideoSeconds. If the server omits that field, the SDK uses a 10-second cap.

Submit

await VectorBugCapture.submitReport({
  idempotencyKey: crypto.randomUUID(),
  title: 'Checkout fails after applying discount',
  actualBehavior: 'Checkout returns a 500 after the coupon is applied.',
  expectedBehavior: 'Checkout should complete successfully.',
  reproSteps: ['Open checkout', 'Apply coupon', 'Click Pay'],
  severity: 'sev_2_high',
  priority: 'p1_high',
  routeUrl: window.location.href,
}, preview);

The SDK sends schemaVersion, clientVersion, source, platform, capturePolicyVersion, sanitizerVersion, and captureSource in every report payload. The server rejects unsupported schema versions with UNSUPPORTED_CAPTURE_SCHEMA_VERSION.

Forbidden Data

The SDK refuses payloads containing forbidden field names before submission. Do not send auth headers, cookies, raw DOM, local/session storage, raw request or response bodies, raw form values, raw store state, or raw cache contents.