@hellsoft/vaka-node 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  FeedbackError: () => FeedbackError,
   SDK: () => SDK,
   VakaScopeSpanProcessor: () => VakaScopeSpanProcessor,
   _globalScope: () => globalScope,
@@ -37,6 +38,7 @@ __export(index_exports, {
   addBreadcrumb: () => addBreadcrumb,
   captureError: () => captureError,
   captureException: () => captureException,
+  captureFeedback: () => captureFeedback,
   captureMessage: () => captureMessage,
   close: () => close,
   currentScope: () => currentScope,
@@ -556,7 +558,7 @@ function makeFastifyPlugin(capture, shouldCapture2) {
 }
 
 // src/index.ts
-var SDK = { name: "vaka-node", version: "0.2.0" };
+var SDK = { name: "vaka-node", version: "0.3.0" };
 var opts;
 var transport;
 var otelSdk;
@@ -751,6 +753,83 @@ function captureMessage(message, level = "info", ctx = {}) {
   const item = { type: "error", ...baseItem(currentScope(), ctx), level, message, fingerprint: ctx.fingerprint };
   return enqueue(item, level === "error" || level === "fatal") ? item.event_id : void 0;
 }
+var FeedbackError = class extends Error {
+  /** HTTP status, or 0 when nothing was sent. 429 means a rate limit was hit. */
+  status;
+  constructor(message, status = 0) {
+    super(message);
+    this.name = "FeedbackError";
+    this.status = status;
+  }
+};
+function contentTypeOf(filename) {
+  const ext = filename.toLowerCase().split(".").pop();
+  return ext === "png" ? "image/png" : ext === "webp" ? "image/webp" : "image/jpeg";
+}
+async function captureFeedback(f) {
+  if (!opts || !transport) throw new FeedbackError("vaka is not initialized");
+  const message = String(f?.message ?? "").trim();
+  if (!message) throw new FeedbackError("feedback needs a message");
+  const files = (f.attachments || []).filter(Boolean);
+  if (files.length > 3) throw new FeedbackError("at most 3 attachments per feedback");
+  const scope = currentScope();
+  const userId = f.userId || scope.user?.id;
+  const item = {
+    id: (0, import_node_crypto.randomUUID)(),
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    platform: "node",
+    source: "api",
+    message: message.slice(0, 5e3),
+    email: f.email?.trim() || void 0,
+    name: f.name?.trim() || void 0,
+    event_id: f.eventId,
+    issue: f.issue,
+    user_id: userId,
+    anon_id: userId ? void 0 : processId,
+    session_id: f.sessionId,
+    url: f.url || scope.request?.url,
+    release: opts.release,
+    environment: opts.environment,
+    tags: { ...scope.tags, ...f.tags || {} },
+    flags: Object.keys(scope.flags).length ? { ...scope.flags } : void 0
+  };
+  for (const k of Object.keys(item)) if (item[k] === void 0) delete item[k];
+  const headers2 = { "X-Vaka-Key": opts.key, "X-Vaka-Sdk": `${SDK.name}/${SDK.version}` };
+  if (f.ip) headers2["X-Forwarded-For"] = f.ip;
+  let body;
+  if (files.length) {
+    const form = new FormData();
+    form.append("feedback", JSON.stringify(item));
+    for (const a of files) {
+      const data = a.data instanceof ArrayBuffer ? new Uint8Array(a.data) : a.data;
+      form.append("attachment", new Blob([data], { type: a.contentType || contentTypeOf(a.filename) }), a.filename);
+    }
+    body = form;
+  } else {
+    headers2["Content-Type"] = "application/json";
+    body = JSON.stringify(item);
+  }
+  const { context: context2 } = await import("@opentelemetry/api");
+  const { suppressTracing: suppressTracing2 } = await import("@opentelemetry/core");
+  let r;
+  try {
+    r = await context2.with(
+      suppressTracing2(context2.active()),
+      () => fetch(`${opts.endpoint}/ingest/v1/feedback`, { method: "POST", headers: headers2, body, signal: AbortSignal.timeout(3e4) })
+    );
+  } catch (e) {
+    throw new FeedbackError(`vaka feedback: ${String(e?.message || e)}`);
+  }
+  const text = await r.text().catch(() => "");
+  let json = {};
+  try {
+    json = text ? JSON.parse(text) : {};
+  } catch {
+  }
+  if (r.status < 200 || r.status >= 300) throw new FeedbackError(`vaka feedback: HTTP ${r.status}${json.error ? `: ${json.error}` : ""}`, r.status);
+  scope.addBreadcrumb({ category: "feedback", message: "user feedback sent" }, opts.maxBreadcrumbs);
+  return { id: json.id || String(item.id), shortId: json.short_id || "" };
+}
 function track(name, props, o = {}) {
   if (!opts || !name) return;
   const scope = currentScope();
@@ -905,6 +984,7 @@ async function _reset() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  FeedbackError,
   SDK,
   VakaScopeSpanProcessor,
   _globalScope,
@@ -912,6 +992,7 @@ async function _reset() {
   addBreadcrumb,
   captureError,
   captureException,
+  captureFeedback,
   captureMessage,
   close,
   currentScope,

package/dist/index.d.ts

@@ -110,6 +110,55 @@ export declare function captureException(error: unknown, ctx?: CaptureContext, f
 export declare const captureError: typeof captureException;
 /** Report a message as an error-like event. */
 export declare function captureMessage(message: string, level?: Level, ctx?: CaptureContext): string | undefined;
+/** A file attached to feedback: PNG, JPEG or WebP, at most 5 MB. */
+export interface FeedbackAttachment {
+    filename: string;
+    data: Uint8Array | ArrayBuffer;
+    /** Default: guessed from the file name. */
+    contentType?: string;
+}
+export interface Feedback {
+    /** What the user wrote (required). Longer than 5000 characters is cut. */
+    message: string;
+    /** Contact email, only when the user gave it. */
+    email?: string;
+    name?: string;
+    /** The error event this feedback is about (the id captureException returned). */
+    eventId?: string;
+    /** The issue this feedback is about: id or short id like `API-12`. */
+    issue?: string;
+    /** Default: the current scope's user. */
+    userId?: string;
+    /** The end user's session id, when your app has one. */
+    sessionId?: string;
+    /** Page or screen the feedback is about. Default: the current request's URL. */
+    url?: string;
+    /**
+     * The end user's IP address (e.g. `req.ip`). Feedback is rate limited per address, so without it
+     * all feedback from this server shares one limit.
+     */
+    ip?: string;
+    tags?: Record<string, string>;
+    /** Up to 3 images. */
+    attachments?: FeedbackAttachment[];
+}
+export interface FeedbackResult {
+    id: string;
+    /** e.g. `API-F12` */
+    shortId: string;
+}
+/** Thrown by captureFeedback when the server rejects the feedback or cannot be reached. */
+export declare class FeedbackError extends Error {
+    /** HTTP status, or 0 when nothing was sent. 429 means a rate limit was hit. */
+    status: number;
+    constructor(message: string, status?: number);
+}
+/**
+ * Forward feedback your users wrote (a support form, in-app chat) to Vaka, with the current
+ * scope's user, release, environment, tags and flags. Sent right away, not batched.
+ * Rejects with a FeedbackError when the server refuses it (e.g. 429 for a rate limit).
+ */
+export declare function captureFeedback(f: Feedback): Promise<FeedbackResult>;
 /** Record a custom server-side event (e.g. `track('order_paid', { amount: 49 })`). */
 export declare function track(name: string, props?: Props, o?: {
     userId?: string;

package/dist/index.mjs

@@ -492,7 +492,7 @@ function makeFastifyPlugin(capture, shouldCapture2) {
 }
 
 // src/index.ts
-var SDK = { name: "vaka-node", version: "0.2.0" };
+var SDK = { name: "vaka-node", version: "0.3.0" };
 var opts;
 var transport;
 var otelSdk;
@@ -687,6 +687,83 @@ function captureMessage(message, level = "info", ctx = {}) {
   const item = { type: "error", ...baseItem(currentScope(), ctx), level, message, fingerprint: ctx.fingerprint };
   return enqueue(item, level === "error" || level === "fatal") ? item.event_id : void 0;
 }
+var FeedbackError = class extends Error {
+  /** HTTP status, or 0 when nothing was sent. 429 means a rate limit was hit. */
+  status;
+  constructor(message, status = 0) {
+    super(message);
+    this.name = "FeedbackError";
+    this.status = status;
+  }
+};
+function contentTypeOf(filename) {
+  const ext = filename.toLowerCase().split(".").pop();
+  return ext === "png" ? "image/png" : ext === "webp" ? "image/webp" : "image/jpeg";
+}
+async function captureFeedback(f) {
+  if (!opts || !transport) throw new FeedbackError("vaka is not initialized");
+  const message = String(f?.message ?? "").trim();
+  if (!message) throw new FeedbackError("feedback needs a message");
+  const files = (f.attachments || []).filter(Boolean);
+  if (files.length > 3) throw new FeedbackError("at most 3 attachments per feedback");
+  const scope = currentScope();
+  const userId = f.userId || scope.user?.id;
+  const item = {
+    id: randomUUID(),
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    platform: "node",
+    source: "api",
+    message: message.slice(0, 5e3),
+    email: f.email?.trim() || void 0,
+    name: f.name?.trim() || void 0,
+    event_id: f.eventId,
+    issue: f.issue,
+    user_id: userId,
+    anon_id: userId ? void 0 : processId,
+    session_id: f.sessionId,
+    url: f.url || scope.request?.url,
+    release: opts.release,
+    environment: opts.environment,
+    tags: { ...scope.tags, ...f.tags || {} },
+    flags: Object.keys(scope.flags).length ? { ...scope.flags } : void 0
+  };
+  for (const k of Object.keys(item)) if (item[k] === void 0) delete item[k];
+  const headers2 = { "X-Vaka-Key": opts.key, "X-Vaka-Sdk": `${SDK.name}/${SDK.version}` };
+  if (f.ip) headers2["X-Forwarded-For"] = f.ip;
+  let body;
+  if (files.length) {
+    const form = new FormData();
+    form.append("feedback", JSON.stringify(item));
+    for (const a of files) {
+      const data = a.data instanceof ArrayBuffer ? new Uint8Array(a.data) : a.data;
+      form.append("attachment", new Blob([data], { type: a.contentType || contentTypeOf(a.filename) }), a.filename);
+    }
+    body = form;
+  } else {
+    headers2["Content-Type"] = "application/json";
+    body = JSON.stringify(item);
+  }
+  const { context: context2 } = await import("@opentelemetry/api");
+  const { suppressTracing: suppressTracing2 } = await import("@opentelemetry/core");
+  let r;
+  try {
+    r = await context2.with(
+      suppressTracing2(context2.active()),
+      () => fetch(`${opts.endpoint}/ingest/v1/feedback`, { method: "POST", headers: headers2, body, signal: AbortSignal.timeout(3e4) })
+    );
+  } catch (e) {
+    throw new FeedbackError(`vaka feedback: ${String(e?.message || e)}`);
+  }
+  const text = await r.text().catch(() => "");
+  let json = {};
+  try {
+    json = text ? JSON.parse(text) : {};
+  } catch {
+  }
+  if (r.status < 200 || r.status >= 300) throw new FeedbackError(`vaka feedback: HTTP ${r.status}${json.error ? `: ${json.error}` : ""}`, r.status);
+  scope.addBreadcrumb({ category: "feedback", message: "user feedback sent" }, opts.maxBreadcrumbs);
+  return { id: json.id || String(item.id), shortId: json.short_id || "" };
+}
 function track(name, props, o = {}) {
   if (!opts || !name) return;
   const scope = currentScope();
@@ -840,6 +917,7 @@ async function _reset() {
   _resetScopes();
 }
 export {
+  FeedbackError,
   SDK,
   VakaScopeSpanProcessor,
   globalScope as _globalScope,
@@ -847,6 +925,7 @@ export {
   addBreadcrumb,
   captureError,
   captureException,
+  captureFeedback,
   captureMessage,
   close,
   currentScope,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hellsoft/vaka-node",
   "publishConfig": {"access": "public"},
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Vaka Node.js SDK: crash reporting, OpenTelemetry tracing and logs, feature flags",
   "license": "MIT OR Apache-2.0",
   "repository": {