Skip to main content

README

Upgather SDK

Upgather SDK API Documentation

The official TypeScript SDK for the Upgather Event Management System (EMS).

Welcome to the Upgather SDK API documentation. This documentation provides detailed information about the classes, interfaces, and types available in the Upgather SDK.

Installation​

# Using npm
npm install @upgather/upgather-sdk

# Using yarn
yarn add @upgather/upgather-sdk

API Reference​

For a complete list of all exported classes, interfaces, and types, see the API Reference.

Getting Started​

import { UpgatherService, TokenAuth } from '@upgather/upgather-sdk';

const auth = new TokenAuth('your-api-token');
const upgather = new UpgatherService({
  baseUrl: 'https://api.upgather.com',
  auth
});

async function getEvents() {
  try {
    const events = await upgather.getEvents();
    console.log(events);
  } catch (error) {
    console.error('Error fetching events:', error);
  }
}

getEvents();

Key Features​

  • Complete TypeScript support with detailed type definitions
  • Built-in authentication handling
  • Automatic retry and error handling
  • Vector store integration for AI-powered features
  • Strapi CMS integration
  • Flexible logging system with custom logger support

Logging​

The Upgather SDK includes a flexible logging system that allows you to control how the SDK logs information, warnings, and errors. You can use the built-in logger, integrate with popular logging libraries like Winston or Pino, or completely suppress logging.

Basic Usage​

Using the Default Logger​

The SDK uses a built-in logger with configurable log levels:

import { ClientFactory, StrapiAdapter, DefaultLogger } from '@upgather/upgather-sdk';

// Create a logger with custom configuration
const logger = new DefaultLogger({
  level: 'info',          // 'debug' | 'info' | 'warn' | 'error'
  prefix: 'my-app',       // Custom prefix for log messages
  enableColors: true      // Enable colored output (default: true)
});

// Configure the SDK with the logger
const client = new ClientFactory(new StrapiAdapter('https://api.example.com'))
  .setLogger(logger)
  .build();

Quick Configuration​

For simple use cases, use setLoggerConfig():

const client = new ClientFactory(adapter)
  .setLoggerConfig({ level: 'debug' })
  .build();

Custom Logger Integration​

The SDK supports any logging library that implements the LoggerInterface:

interface LoggerInterface {
  debug(message: string, ...meta: any[]): void;
  info(message: string, ...meta: any[]): void;
  warn(message: string, ...meta: any[]): void;
  error(message: string, ...meta: any[]): void;
}

Winston Integration​

import { ClientFactory, LoggerInterface } from '@upgather/upgather-sdk';
import winston from 'winston';

// Create Winston logger
const winstonLogger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.Console({ format: winston.format.simple() })
  ]
});

// Adapt Winston to LoggerInterface
const logger: LoggerInterface = {
  debug: (msg, ...meta) => winstonLogger.debug(msg, ...meta),
  info: (msg, ...meta) => winstonLogger.info(msg, ...meta),
  warn: (msg, ...meta) => winstonLogger.warn(msg, ...meta),
  error: (msg, ...meta) => winstonLogger.error(msg, ...meta)
};

// Use with SDK
const client = new ClientFactory(adapter)
  .setLogger(logger)
  .build();

Pino Integration​

import { LoggerInterface } from '@upgather/upgather-sdk';
import pino from 'pino';

const pinoLogger = pino();

const logger: LoggerInterface = {
  debug: (msg, ...meta) => pinoLogger.debug(meta, msg),
  info: (msg, ...meta) => pinoLogger.info(meta, msg),
  warn: (msg, ...meta) => pinoLogger.warn(meta, msg),
  error: (msg, ...meta) => pinoLogger.error(meta, msg)
};

const client = new ClientFactory(adapter)
  .setLogger(logger)
  .build();

Silent Mode​

Suppress all SDK logging (useful for production or testing):

import { SilentLogger } from '@upgather/upgather-sdk';

const client = new ClientFactory(adapter)
  .setLogger(new SilentLogger())
  .build();

Log Levels​

The SDK uses four log levels:

  • debug: Detailed information for debugging (HTTP requests, cache hits/misses, etc.)
  • info: General informational messages (successful operations, state changes)
  • warn: Warning messages (retry attempts, rate limiting, circuit breaker events)
  • error: Error messages (failed requests, errors that need attention)

What Gets Logged​

The SDK logs various events across its components:

HTTP Requests (LoggingInterceptor)

  • Request details (method, URL, headers, body)
  • Response information

Error Handling

  • Retry attempts with backoff delays
  • Circuit breaker state changes (open, half-open, closed)
  • Error details and stack traces

Rate Limiting

  • Rate limit warnings when limits are hit
  • Wait times and throttling events

Caching (when debug enabled)

  • Cache hits and misses
  • Cache invalidation events

Testing with Mock Logger​

For unit tests, create a mock logger to verify logging behavior:

import { LoggerInterface } from '@upgather/upgather-sdk';

const mockLogger: LoggerInterface = {
  debug: jest.fn(),
  info: jest.fn(),
  warn: jest.fn(),
  error: jest.fn()
};

const client = new ClientFactory(adapter)
  .setLogger(mockLogger)
  .build();

// Verify logging
expect(mockLogger.error).toHaveBeenCalledWith(
  expect.stringContaining('API Error')
);

Advanced Configuration​

Per-Component Configuration​

The logger is automatically propagated to all SDK components:

const logger = new DefaultLogger({ level: 'debug' });

const client = new ClientFactory(adapter)
  .setLogger(logger)                    // Shared by all components
  .setRetryStrategy(3)                  // Retry handler uses this logger
  .enableCircuitBreaker({ threshold: 5 }) // Circuit breaker uses this logger
  .enableRateLimit({ requestsPerSecond: 10 }) // Rate limiter uses this logger
  .build();

Service-Level Logging​

Services also support logger injection:

const logger = new DefaultLogger({ level: 'info', prefix: 'upgather' });

const upgatherService = new UpgatherService({
  baseUrl: 'https://api.upgather.com',
  auth: new TokenAuth('your-token'),
  logger: logger  // Optional logger for service operations
});

Services​

The SDK provides several services:

UpgatherService​

The main service for interacting with the Upgather platform.

StrapiService​

Integration with Strapi CMS for content management.

VectorStoreService​

For AI-powered vector search and retrieval.

Support​

For issues and feature requests, please open an issue on our GitHub repository.

License​

This SDK is distributed under the MIT license. See the LICENSE file for more details.