@userdispatch/sdk

Zero-dependency TypeScript SDK for submitting user feedback, bug reports, contact forms, and automated logs to UserDispatch.

Installation

npm install @userdispatch/sdk

Quick Start

import { UserDispatchClient } from "@userdispatch/sdk";

const client = new UserDispatchClient({
  apiKey: "your-app-api-key",
  baseUrl: "https://userdispatch.com", // optional, this is the default
});

// Submit feedback with a rating
await client.submit({
  type: "feedback",
  email: "[email protected]",
  rating: 4,
  message: "Great product, but search could be faster.",
  metadata: { page: "/dashboard", browser: "Chrome 120" },
});

// Submit a bug report with file attachments
await client.submit({
  type: "bug_report",
  name: "Dev User",
  email: "[email protected]",
  subject: "Crash on save",
  message: "App crashes when saving a large document.",
  files: [
    {
      name: "screenshot.png",
      content: screenshotBlob,
      type: "image/png",
    },
    {
      name: "logs.txt",
      content: new Blob(["error log contents..."]),
      type: "text/plain",
    },
  ],
});

// Shorthand for automated logs
await client.submitLog("Cron job completed", {
  job: "daily-report",
  duration_ms: 4520,
  records_processed: 1843,
});

// Automated log with extra options
await client.submitLog(
  "Deployment failed",
  { commit: "abc123", env: "staging" },
  { subject: "Deploy failure: staging", email: "[email protected]" },
);

API

new UserDispatchClient(options)

| Option | Type | Required | Default | |--------|------|----------|---------| | apiKey | string | Yes | - | | baseUrl | string | No | https://userdispatch.com |

client.submit(data)

Submit a full submission. Returns Promise<{ id, status, created_at }>.

| Field | Type | Required | |-------|------|----------| | type | "feedback" \| "question" \| "bug_report" \| "automated_log" | Yes | | name | string | No | | email | string | No | | subject | string | No | | message | string | No | | rating | number | No | | metadata | Record<string, unknown> | No | | files | Array<{ name, content, type? }> | No |

When files are included, the request is sent as multipart/form-data. Otherwise, it is sent as JSON.

client.submitLog(message, metadata?, options?)

Shorthand for submit({ type: "automated_log", ... }).

| Param | Type | Required | |-------|------|----------| | message | string | Yes | | metadata | Record<string, unknown> | No | | options.subject | string | No | | options.email | string | No | | options.name | string | No |

Error Handling

import { UserDispatchClient, UserDispatchError } from "@userdispatch/sdk";

try {
  await client.submit({ type: "feedback", message: "Hello" });
} catch (err) {
  if (err instanceof UserDispatchError) {
    console.error(err.code);    // e.g. "RATE_LIMITED"
    console.error(err.message); // e.g. "Too many requests"
    console.error(err.status);  // e.g. 429
  }
}