@raindrop-ai/browser-sdk

Minimal browser-safe SDK for sending Raindrop events from frontend applications.

Build-injected application identity

Browsers cannot discover a server checkout or process environment. Inject application build metadata through public options: new Raindrop({ apiKey, appGit: { commitSha: APP_BUILD_SHA, branch: APP_BRANCH } }). Only full40/64-character SHA values are inferred from this typed option. branch and boolean commitDirty are optional; do not invent a clean/dirty state when the build does not know it. No Node imports, filesystem/process discovery, or metadata waits are added.

The SDK fills absent raindrop.app.commit_sha, raindrop.app.commit_dirty, and raindrop.app.branch properties. Caller properties—including null, empty, and opaque strings—win unchanged; partial finishes retain their initial identity unless explicitly overridden. Existing release/SDK fields are untouched. appGit: false disables defaults. detectBranch, sourceDirectory, and autoDetect do not enable Node discovery in a browser.

Valid configured SHA and branch strings retain their exact case and whitespace. Invalid or empty configured SHAs are omitted; existing raw per-event properties are still preserved exactly.

Install

pnpm add @raindrop-ai/browser-sdk

Usage

import { Raindrop } from "@raindrop-ai/browser-sdk";

const raindrop = new Raindrop({
  apiKey: process.env.RAINDROP_WRITE_KEY!,
});

Projects

If your org has multiple projects, route events to a specific one by passing its slug as projectId:

const raindrop = new Raindrop({
  apiKey: process.env.RAINDROP_WRITE_KEY!,
  projectId: "support-prod",
});

This sets the X-Raindrop-Project-Id header on every event. Omit it (or pass "default") to use your org's default Production project — the existing behavior. Single-project orgs need nothing new.

Payload size limits

input / output are capped at 1,000,000 characters per field by default and truncated with a ...[truncated by raindrop] marker before the request body is serialized, so a multi-MB transcript costs the cap — not the payload — on the main thread, and lands truncated instead of tripping the 1 MB ingest limit. Tune via maxTextFieldChars. Every request also carries a finite timeout (default 30s, tune via timeoutMs).

Notes

• This package is intentionally small and browser-safe.
• It has zero runtime dependencies.