Skip to main content

​
Basic Usage

Install the package and start logging messages in minutes: 
npm install greenflash
# or
yarn add greenflash
# or
pnpm add greenflash

import Greenflash from 'greenflash';

const client = new Greenflash({
  apiKey: process.env['GREENFLASH_API_KEY'],
});

// Log your first conversation
client.messages.create({
  productId: 'YOUR_PRODUCT_ID',
  externalUserId: 'USER_ID',
  externalConversationId: 'CONVO_ID',
  messages: [
    { role: 'user', content: 'Hello, how can you help me today?' },
    { role: 'assistant', content: 'I can answer any questions you have!' },
  ],
});

​
Type Safety

The SDK provides full TypeScript support with built-in types for all requests and responses: 
import Greenflash from 'greenflash';

const client = new Greenflash({ apiKey: process.env['GREENFLASH_API_KEY'] });

// Type-safe message creation
const params: Greenflash.MessageCreateParams = {
  productId: 'YOUR_PRODUCT_ID',
  externalUserId: 'USER_ID',
  externalConversationId: 'CONVO_ID',
  messages: [{ role: 'user', content: '...' }],
};

const response: Greenflash.CreateResponse = await client.messages.create(params);

​
Handling Errors Gracefully

The SDK throws specific error classes for different failure scenarios, making error handling straightforward: 
try {
  await client.messages.create({ /* ... */ });
} catch (err) {
  if (err instanceof Greenflash.APIError) {
    // Handle API-specific errors
    console.log(`API Error ${err.status}: ${err.name}`);
    console.log('Response headers:', err.headers);
  } else {
    // Re-throw unexpected errors
    throw err;
  }
}
Available Error Classes:
  • AuthenticationError - Invalid or missing API key
  • PermissionDeniedError - Insufficient permissions
  • NotFoundError - Resource not found
  • RateLimitError - Too many requests
  • ValidationError - Invalid request data

​
Configure Retry Behavior

Automatically retry failed requests with intelligent backoff: 
// Disable retries globally
const client = new Greenflash({ maxRetries: 0 });

// Override retries per request
client.messages.create({ /* ... */ }, { maxRetries: 5 });
Default Retry Strategy:
  • Retries on connection errors, 408, 409, 429, and 5xx responses
  • Maximum of 2 retries with exponential backoff
  • Configurable per client or per request

​
Set Request Timeouts

Control how long to wait for responses: 
// Set global timeout to 20 seconds
const client = new Greenflash({ timeout: 20_000 });

// Override timeout for specific request
client.messages.create({ /* ... */ }, { timeout: 5_000 });
Timeout Behavior:
  • Default timeout: 60 seconds
  • Throws APIConnectionTimeoutError on timeout
  • Configurable globally or per request

​
Advanced Features

​
Access Raw HTTP Response

Get full control over the HTTP response for custom handling: 
// Get raw response object
const raw = await client.messages.create({ /* ... */ }).asResponse();
console.log('Custom header:', raw.headers.get('X-My-Header'));

// Get both data and response
const { data, response } = await client.messages.create({ /* ... */ }).withResponse();
console.log('Response status:', response.status);
console.log('Response data:', data);

​
Configure Logging

Control SDK logging verbosity and use custom loggers: 
// Set log level via environment variable
// GREENFLASH_LOG=debug

// Or configure programmatically
const client = new Greenflash({
  logLevel: 'debug',
  logger: pino() // Use custom logger like pino
});
Log Levels:
  • error - Only errors (default)
  • warn - Warnings and errors
  • info - General information
  • debug - Detailed debugging info