Geng SDK

A universal SDK for JavaScript/TypeScript projects that enables businesses to send events to internal API endpoints. This SDK is designed for internal use across multiple business clients and provides seamless event tracking across different platforms including Node.js, browser environments, and Shopify stores.

Features

• 🌍 Universal Support - Works in Node.js, browsers, and Shopify environments
• 📊 Event Tracking - Simple API for sending events to internal endpoints
• 🔍 Environment Detection - Automatic environment and platform detection
• 📱 Multi-Platform - Supports ESM and CommonJS module formats
• 🛡️ TypeScript Support - Full TypeScript definitions included
• 🔧 Configurable - Flexible configuration options
• 📝 Debug Mode - Built-in logging and debugging capabilities

Installation

npm install geng-sdk

Quick Start

Basic Usage

import { GengSDK } from 'geng-sdk';

// Initialize the SDK
const sdk = new GengSDK({
  apiSecret: 'your-api-secret',
  businessId: 'your-business-id',
  debug: true // Enable debug mode
});

// Send an event
await sdk.track('user_signup', {
  userId: 'user123',
  email: '[email protected]',
  plan: 'premium'
});

Node.js Environment

const { GengSDK } = require('geng-sdk');

const sdk = new GengSDK({
  apiSecret: process.env.GENG_API_SECRET,
  businessId: process.env.GENG_BUSINESS_ID,
  apiUrl: process.env.GENG_API_URL
});

Browser Environment

<script type="module">
import { GengSDK } from 'geng-sdk';

const sdk = new GengSDK({
  apiSecret: 'your-api-secret',
  businessId: 'your-business-id'
});

// Track page view
sdk.track('page_view', {
  page: window.location.pathname,
  referrer: document.referrer
});
</script>

Shopify Environment

// In your Shopify theme or app
import { GengSDK } from 'geng-sdk';

const sdk = new GengSDK({
  apiSecret: 'your-api-secret',
  businessId: 'your-shopify-store-id'
});

// Track purchase events
sdk.track('purchase', {
  orderId: checkout.order_id,
  total: checkout.total_price,
  currency: checkout.currency,
  items: checkout.line_items
});

Configuration

The SDK accepts the following configuration options:

const sdk = new GengSDK({
  // Required
  apiSecret: 'your-api-secret',     // Your API secret for authentication
  businessId: 'your-business-id',   // Unique business identifier

  // Optional
  apiUrl: 'https://api.geng.com',   // API endpoint URL
  environment: 'production',        // 'development', 'production', or 'test'
  debug: false,                     // Enable debug logging
  timeout: 5000,                    // Request timeout in milliseconds
  retryAttempts: 3,                 // Number of retry attempts for failed requests
  batchSize: 50,                    // Number of events to batch together
  flushInterval: 5000               // Interval to flush batched events (ms)
});

API Reference

track(eventType, properties, options?)

Send a tracking event to the API.

await sdk.track('button_click', {
  buttonId: 'signup-button',
  page: '/landing',
  userId: 'user123'
}, {
  timestamp: '2023-12-01T10:00:00Z', // Optional custom timestamp
  eventId: 'custom-event-id'         // Optional custom event ID
});

getConfig()

Get the current SDK configuration.

const config = sdk.getConfig();
console.log(config);

getEnvironmentInfo()

Get detailed information about the current environment.

const envInfo = sdk.getEnvironmentInfo();
console.log(envInfo);
// {
//   environment: 'development',
//   platform: 'browser',
//   isShopifyContext: false,
//   hostname: 'localhost',
//   timestamp: '2023-12-01T10:00:00Z'
// }

getCurrentEnvironment()

Get the current environment setting.

const env = sdk.getCurrentEnvironment(); // 'development' | 'production' | 'test'

isDebugMode()

Check if debug mode is enabled.

if (sdk.isDebugMode()) {
  console.log('Debug mode is enabled');
}

updateConfig(config)

Update the SDK configuration at runtime.

sdk.updateConfig({
  debug: true,
  timeout: 10000
});

Environment Variables

For Node.js environments, you can use environment variables:

# .env file
NODE_ENV=development
DEBUG=true
GENG_API_SECRET=your-api-secret
GENG_BUSINESS_ID=your-business-id
GENG_API_URL=https://api.geng.com

Error Handling

The SDK provides comprehensive error handling:

try {
  await sdk.track('user_action', { userId: '123' });
} catch (error) {
  if (error.code === 'NETWORK_ERROR') {
    console.log('Network error occurred:', error.message);
  } else if (error.code === 'VALIDATION_ERROR') {
    console.log('Invalid event data:', error.details);
  }
}

Platform Detection

The SDK automatically detects the current platform and adjusts behavior accordingly:

• Node.js: Uses Node.js APIs and environment variables
• Browser: Uses browser APIs and localStorage for configuration
• Shopify: Detects Shopify context and provides Shopify-specific utilities

Development

Building

npm run build

Development Mode

npm run dev

Type Checking

npm run typecheck

TypeScript Support

The SDK is written in TypeScript and includes comprehensive type definitions:

import { GengSDK, TrackingEvent, SDKResponse } from 'geng-sdk';

interface CustomEventData {
  userId: string;
  action: string;
  metadata?: Record<string, any>;
}

const sdk = new GengSDK({
  apiSecret: 'your-secret',
  businessId: 'your-business-id'
});

// TypeScript will validate the event data structure
const response: SDKResponse = await sdk.track('custom_event', {
  userId: '123',
  action: 'button_click'
} as CustomEventData);

Browser Support

• Modern browsers with ES6+ support
• IE11+ (with polyfills)
• All major mobile browsers

Node.js Support

• Node.js 16.0.0 or higher

License

MIT

Support

For internal support and questions, please contact the development team or create an issue in the internal repository.