Logwise SDK

The official SDK for Logwise, the support deflection layer for user-facing SaaS errors.

Installation

Requires Node.js 18.0.0 or higher.

npm install logwise-sdk

Quick Start

The easiest way to use Logwise is with environment variables.

1. Set LOGWISE_API_KEY in your environment variables or in a .env file:

   LOGWISE_API_KEY=sk_live_...

   (Note: Your application must be configured to load .env files, for example using dotenv or Next.js)

2. Capture and explain errors:

   import { explain } from 'logwise-sdk';
   
   try {
     doSomethingRisky();
   } catch (error) {
     // Passing the error object directly extracts message, code, and stack trace.
     // Fix suggestions are included by default.
     const data = await explain(error, {
       includeFix: true,
       projectId: 'checkout',
       environment: 'production',
       release: '2026.05.14'
     });
        
     console.log(data.explanation); 
     if (data.fix) {
        console.log("Suggestions:", data.fix);
     }
     console.log("Stored event:", data.errorId);
   }

React Error Boundary Widget

If you are using React, Next.js, or Remix, Logwise provides a pre-built drop-in component that catches UI crashes, explains the problem to the user, tracks whether they recovered, and escalates unresolved errors to your configured support integrations.

1. Install the SDK and add your API key (see Quick Start above).
2. Wrap your application (or risky components):

   import { LogwiseErrorBoundary } from 'logwise-sdk/react';
   
   export default function App() {
     return (
      <LogwiseErrorBoundary
        theme="dark"
        options={{ apiKey: 'sk_live_...' }}
        projectId="checkout"
        environment="production"
        captureGlobalErrors
        captureFetch
      >
         <MyRiskyDashboard />
      </LogwiseErrorBoundary>
     );
   }

Configuration

If you prefer not to use environment variables, you can initialize the SDK manually at the start of your application.

import { init } from 'logwise-sdk';

init({ apiKey: 'sk_live_...' });

Advanced Usage (Class-based)

Reference the class directly if you need multiple instances or custom configurations.

import Logwise from 'logwise-sdk';

const logwise = new Logwise({ 
    apiKey: 'sk_live_...',
    baseUrl: 'https://api.getlogwise.com' // Optional override
});

const response = await logwise.explain({
    code: 'ECONNREFUSED',
    message: 'Connection refused at 0.0.0.0:3000',
    targetAudience: 'user', // 'user' (simple) or 'developer' (technical)
    projectId: 'billing',
    environment: 'production'
}, { includeFix: true });

Response Format

{
  explanation: string; // The human-readable explanation
  fix?: string[]; // Array of actionable suggestions
  errorId: string; // Stored Logwise event ID
  fingerprint: string; // Grouping key for repeated errors
  groupId: string; // Dashboard error group ID
}

Manual Feedback Tracking

If you are using the core explain logic without the React widget, and you show the explanation to a user, track whether they recovered or still needed support. This powers the deflection and support-handoff metrics on your dashboard.

import { submitFeedback } from 'logwise-sdk';

// errorId comes from the response of explain()
await submitFeedback("uuid-error-id-here", true, { resolved: true });

// Escalate unresolved errors to Slack/Zendesk/Freshdesk/Gleap integrations.
await submitFeedback("uuid-error-id-here", false, {
  resolved: false,
  requestSupport: true,
  contactEmail: "[email protected]",
  comment: "I was trying to export my invoice."
});

License

MIT