Skip to main content

Express SDK

The Syntropy Express SDK adds request context and error capture middleware for Express applications.

npm install @eclosion-tech/syntropy-express

Basic Setup​

import express from 'express';
import {
  Syntropy,
  syntropyMiddleware,
  syntropyErrorHandler,
} from '@eclosion-tech/syntropy-express';

Syntropy.init({
  projectId: 'your-project-id',
  release: process.env.npm_package_version,
  environment: process.env.NODE_ENV,
});

const app = express();

// Add early so request context exists for downstream handlers
app.use(syntropyMiddleware());

app.get('/', (_req, res) => {
  res.send('ok');
});

app.get('/error', () => {
  throw new Error('Test error');
});

// Add last in the error middleware chain
app.use(syntropyErrorHandler());

Middleware Configuration​

app.use(
  syntropyMiddleware({
    excludeRoutes: ['/health', '/metrics'],
    captureBody: false,
    getSessionId: (req) => req.headers['x-session-id'] as string | undefined,
    getUser: (req) =>
      req.user
        ? {
            id: req.user.id,
            email: req.user.email,
          }
        : undefined,
  })
);

Error Handler Behavior​

app.use(
  syntropyErrorHandler({
    rethrow: false, // pass to next error handler
  })
);

Manual Capture​

app.post('/checkout', async (req, res, next) => {
  try {
    await processPayment(req.body);
    res.json({ ok: true });
  } catch (error) {
    if (error instanceof Error) {
      Syntropy.captureError(error, {
        tags: { route: 'checkout' },
        extra: { orderId: req.body.orderId },
      });
    }
    next(error);
  }
});

Typed Project APIs​

import { createSyntropyApiClient } from '@eclosion-tech/syntropy-express';

const api = createSyntropyApiClient({
  baseUrl: 'https://syntropy.chat/api',
  apiKey: process.env.SYNTROPY_API_KEY,
});

await api.customers.trackEvent(
  { organizationId: 'org_uuid', projectId: 'project_uuid' },
  {
    name: 'checkout_completed',
    externalId: 'user_123',
    payload: { amount: 99.99 },
  }
);

See SDK API Client for all available methods.