@ruizrica/mako-shared

Shared types and utilities for the Mako monitoring platform. Pure ESM, zero runtime dependencies, works in browsers, Node.js (>=18), and Cloudflare Workers.

This package is consumed internally by @ruizrica/mako-sdk, the Mako API worker, the event processor, and the dashboard. It is published so that external consumers (test apps, custom integrations, third-party tooling) can import the same envelope/event types and validators that Mako itself uses.

Install

npm install @ruizrica/mako-shared

What's inside

• Types — Envelope, EnvelopeItem, ErrorEvent, LogEvent, TraceSpan, StackFrame, Breadcrumb, User, and supporting unions for the Mako transport format.
• Validation — validateEnvelope, validateErrorEvent, validateLogEvent, validateTraceSpan. Each returns { valid, errors }. Enforces required fields, allowed level/status values, and the 1 MB envelope size cap.
• Fingerprinting — generateFingerprint(errorType, message, stackFrames) returns a deterministic SHA-256 hex string built from the error type, normalized message, and top 3 stack frames. Used by the processor to group events into issues.
• Severity — helpers and constants for log/event level handling.

Quick start

import {
  validateEnvelope,
  generateFingerprint,
  type Envelope,
  type ErrorEvent,
} from '@ruizrica/mako-shared';

const result = validateEnvelope(payload);
if (!result.valid) {
  console.error('invalid envelope', result.errors);
}

const fingerprint = await generateFingerprint(
  'TypeError',
  "Cannot read properties of undefined (reading 'id')",
  [{ filename: 'src/users.ts', lineno: 42, colno: 7, function: 'getUser', in_app: true }],
);

Envelope shape

Mako uses a Sentry-style envelope: a single header followed by one or more typed items.

type Envelope = {
  header: {
    dsn: string;
    sdk: { name: string; version: string };
    sent_at: string; // ISO 8601
  };
  items: Array<{
    type: 'error' | 'log' | 'span';
    payload: ErrorEvent | LogEvent | TraceSpan;
  }>;
};

The envelope is posted to /api/v1/envelope on your Mako host with an Authorization: DSN <dsn> header.

Compatibility

• Node.js >=18 (uses crypto.subtle, TextEncoder)
• Modern browsers
• Cloudflare Workers
• ESM only — no CommonJS build is shipped

License

MIT — see LICENSE.