@a11ops/sdk

Official Node.js SDK for a11ops - Enterprise-grade push notification infrastructure for critical alerts.

Installation

npm install @a11ops/sdk

Quick Start - 2 Lines of Code!

import { a11ops } from "@a11ops/sdk";

// That's it. Send critical alerts instantly.
await a11ops.alert({
  title: "Database CPU at 95%",
  priority: "critical",
  workspace: "production",
});

Zero Configuration Setup

The SDK automatically handles authentication for you:

1. First time? Run your code and follow the interactive setup
2. CI/Production? Set the A11OPS_API_KEY environment variable
3. Already configured? Just start sending alerts!

Usage Examples

Simple Alerts

import { a11ops } from "@a11ops/sdk";

// Send alerts with different priorities
await a11ops.critical("Payment gateway down!");
await a11ops.error("Failed to process order", "Order ID: 12345");
await a11ops.warning("High memory usage", "Server using 85% RAM");
await a11ops.info("Deployment completed", "Version 2.0.1 live");

Detailed Alerts

await a11ops.alert({
  title: "Database Connection Lost",
  message: "Primary database unreachable",
  priority: "critical",
  workspace: "production",
  metadata: {
    server: "db-primary-01",
    region: "us-east-1",
    connectionPool: 0,
  },
});

Error Monitoring

process.on("uncaughtException", async (error) => {
  await a11ops.critical({
    title: `Uncaught Exception: ${error.message}`,
    message: error.stack,
    workspace: "production",
  });
});

Express.js Integration

app.use(async (err, req, res, next) => {
  await a11ops.error({
    title: "API Error",
    message: `${req.method} ${req.path}: ${err.message}`,
    metadata: {
      statusCode: err.status || 500,
      userId: req.user?.id,
      requestId: req.id,
    },
  });

  res.status(500).json({ error: "Internal Server Error" });
});

Configuration

Environment Variables

# Set your API key (required in production)
A11OPS_API_KEY=your-api-key

# Optional: Set default workspace
A11OPS_DEFAULT_WORKSPACE=production

# Optional: Custom API endpoint
A11OPS_API_URL=https://api.a11ops.com

Programmatic Configuration

import { a11ops } from "@a11ops/sdk";

// Configure once in your app initialization
a11ops.configure({
  apiKey: "your-api-key", // Optional if set via env
});

Traditional API (Class-based)

For more control, you can use the class-based API:

import A11ops from "@a11ops/sdk";

const client = new A11ops("your-api-key", {
  baseUrl: "https://api.a11ops.com",
  region: "us-west-2",
  timeout: 30000,
  retries: 3,
  retryDelay: 1000,
});

await client.alert({
  title: "Alert Title",
  severity: "critical",
});

// Batch alerts
await client.batchAlert([
  { title: "Alert 1" },
  { title: "Alert 2" },
  { title: "Alert 3" },
]);

// Get metrics
const metrics = await client.getMetrics({
  workspaceId: "workspace-123",
  period: "7d",
});

TypeScript

Full TypeScript support with type definitions included:

import { a11ops } from "@a11ops/sdk";

interface CustomAlert {
  userId: string;
  action: string;
  timestamp: Date;
}

await a11ops.alert<CustomAlert>({
  title: "User Action",
  priority: "info",
  metadata: {
    userId: "user-123",
    action: "login",
    timestamp: new Date(),
  },
});

Priority Levels

• critical - Immediate attention required
• high - High priority issues
• medium - Warning conditions
• low - Low priority notifications
• info - Informational messages

Error Handling

try {
  await a11ops.alert({ title: "Test Alert" });
} catch (error) {
  if (error.status === 429) {
    console.log("Rate limit exceeded");
  } else {
    console.error("Failed to send alert:", error.message);
  }
}

Log Monitoring

a11ops includes comprehensive log monitoring capabilities. Automatically capture and track errors with rich context, breadcrumbs, and user information.

Quick Start

import A11ops from "@a11ops/sdk";

const client = new A11ops("your-api-key", {
  logMonitoring: true, // Enable log monitoring
  environment: "production",
  release: "1.0.0",
});

// Errors are now automatically captured!
// Manual capture also available:
client.captureError(new Error("Something went wrong"), {
  level: "error",
  tags: { module: "payment" },
  user: { id: "123", email: "[email protected]" },
});

Automatic Error Capture

// Browser: Automatically captures unhandled errors and promise rejections
window.addEventListener("error", (e) => {
  /* Handled automatically */
});

// Node.js: Automatically captures uncaught exceptions
process.on("uncaughtException", (e) => {
  /* Handled automatically */
});

Breadcrumbs & Context

// Add breadcrumbs for debugging
client.addBreadcrumb({
  message: "User clicked checkout",
  category: "user-action",
  level: "info",
});

// Set user context
client.setUser({
  id: "user-123",
  email: "[email protected]",
  username: "johndoe",
});

// Set additional context
client.setContext("subscription", {
  plan: "enterprise",
  seats: 50,
});

// Set tags for filtering
client.setTag("release", "2.0.1");
client.setTag("environment", "production");

Express.js Error Tracking

app.use((err, req, res, next) => {
  // Capture error with request context
  client.captureError(err, {
    level: "error",
    user: req.user,
    extra: {
      method: req.method,
      url: req.url,
      ip: req.ip,
    },
    tags: {
      endpoint: `${req.method} ${req.path}`,
    },
  });

  res.status(500).json({ error: "Internal Server Error" });
});

Capture Messages

// Capture informational messages
client.captureMessage("Payment processed successfully", "info", {
  extra: { amount: 99.99, currency: "USD" },
});

Local Development

The SDK stores configuration in ~/.a11ops/config.json in your home directory (not your project directory) after initial setup.

Security Notes

• Configuration location: ~/.a11ops/config.json is stored in your home directory, not your project
• API keys: Never commit API keys to version control
• Environment variables: Use A11OPS_API_KEY in production instead of config files
• CI/CD: Always use environment variables, never config files

Reset Configuration

To reset your local configuration:

rm -rf ~/.a11ops

Best Practices

1. Development: Use the interactive setup for local development
2. Production: Always use environment variables:

   export A11OPS_API_KEY=your-api-key

3. Version Control: Add to .gitignore if you ever store keys in your project:

   # A11ops configuration
   .a11ops/
   *.a11ops.json

Support

• 📚 Documentation: https://a11ops.com/docs
• 🐛 Issues: https://github.com/a11ops/sdk/issues
• 💬 Discord: https://discord.gg/ywZvTAHT8N
• 📧 Email: [email protected]

License

MIT