@logitnow/sdk

TypeScript SDK for Logit event logging. Send events to your Logit instance with full type safety.

Installation

npm install @logitnow/sdk
# or
pnpm add @logitnow/sdk
# or
yarn add @logitnow/sdk

Quick Start

import { init } from "@logitnow/sdk";

const logit = init({
  token: "your-api-key",
  projectId: "project-id",
});

await logit.now("channel-name", {
  event: "User signed up",
  description: "New user registration",
  notify: true
});

Configuration

Required Parameters

• token (string): Your Logit API key/token. This is used to authenticate requests.

• projectId (string): Project ID for reference.

Usage

Basic Event Logging

import { init } from "@logitnow/sdk";

const logit = init({ token: "your-api-key" });

// Simple event
await logit.now("free-trial", {
  event: "User signed up"
});

Event with All Fields

await logit.now("free-trial", {
  event: "User signed up",
  description: "New user signed up for a free trial - Email: [email protected] | Name: John Doe",
  icon: "🇺🇸",
  notify: true,
  tags: {
    environment: "production",
    priority: "high"
  },
  metadata: {
    userId: "123",
    email: "[email protected]"
  }
});

Error Handling

import { createLogit, LogitError } from "@logitnow/sdk";

const logit = createLogit({ token: "your-api-key" });

try {
  const response = await logit.now("channel", {
    event: "Test event"
  });
  console.log("Event logged:", response.id);
} catch (error) {
  if (error instanceof LogitError) {
    console.error("Logit error:", error.message);
    console.error("Status code:", error.statusCode);
    console.error("Details:", error.details);
  } else {
    console.error("Unexpected error:", error);
  }
}

Use Cases

User Signed Up

Track new user registrations with detailed information:

import { init } from "@logitnow/sdk";

const logit = init({ token: "your-api-key" });

// After successful user registration
await logit.now("user-signups", {
  event: "User signed up",
  description: `New user signed up - Email: ${user.email} | Name: ${user.name} | Plan: ${user.plan} | Country: ${user.country} | IP: ${user.ip}`,
  icon: "👤",
  notify: true,
  tags: {
    environment: process.env.NODE_ENV,
    plan: user.plan,
    source: user.signupSource
  },
  metadata: {
    userId: user.id,
    email: user.email,
    name: user.name,
    plan: user.plan,
    country: user.country,
    ip: user.ip,
    timestamp: new Date().toISOString()
  }
});

Successful Payment

Log successful payment transactions:

// After payment processing succeeds
await logit.now("payments", {
  event: "Payment successful",
  description: `Payment received - Amount: $${payment.amount} | Plan: ${payment.plan} | Customer: ${customer.email} | Transaction ID: ${payment.transactionId}`,
  icon: "💳",
  notify: true,
  tags: {
    environment: process.env.NODE_ENV,
    plan: payment.plan,
    paymentMethod: payment.method,
    amount: payment.amount
  },
  metadata: {
    userId: customer.id,
    email: customer.email,
    amount: payment.amount,
    currency: payment.currency,
    plan: payment.plan,
    transactionId: payment.transactionId,
    paymentMethod: payment.method,
    timestamp: new Date().toISOString()
  }
});

Trial Activated

Track when users activate their free trial:

// When a user starts their free trial
await logit.now("trials", {
  event: "Trial activated",
  description: `Free trial started - Email: ${user.email} | Plan: ${user.plan} | Trial ends: ${trialEndDate} | Country: ${user.country}`,
  icon: "🎁",
  notify: true,
  tags: {
    environment: process.env.NODE_ENV,
    plan: user.plan,
    trialDuration: "14 days"
  },
  metadata: {
    userId: user.id,
    email: user.email,
    plan: user.plan,
    trialStartDate: new Date().toISOString(),
    trialEndDate: trialEndDate,
    country: user.country
  }
});

Anonymous to Authenticated User Transition

Link anonymous user events to authenticated user events seamlessly:

import { init } from "@logitnow/sdk";

const logit = init({ token: "your-api-key" });

// Anonymous user browsing
await logit.now("page_views", {
  event: "Page Viewed",
  trackingId: "anon_123", // Anonymous session ID
  metadata: { page: "/products" }
});

// User signs up - automatically link to anonymous events
await logit.now("user_signups", {
  event: "User Registered",
  trackingId: "user_456",        // Authenticated user ID
  aliasTrackingId: "anon_123",   // Links to anonymous events
  metadata: {
    userId: "user_456",
    email: "[email protected]"
  }
});

// Continue with authenticated events
await logit.now("purchases", {
  event: "Purchase Completed",
  trackingId: "user_456",
  metadata: { amount: 99.99 }
});

// Now querying with either "anon_123" or "user_456" returns:
// - Page Viewed (anonymous)
// - User Registered (signup)
// - Purchase Completed (authenticated)

Better-Auth Integration

Track user sign-ups automatically using better-auth hooks:

import { betterAuth } from "better-auth";
import { init } from "@logitnow/sdk";

// Initialize Logit SDK
const logit = init({
  projectId: process.env.LOGIT_PROJECT_ID
  token: process.env.LOGIT_API_KEY!,
});

export const auth = betterAuth({
  // ... your other better-auth config
  databaseHooks: {
    user: {
      create: {
        after: async (user) => {
          // Log user sign-up event to Logit
          try {
            await logit.now("user-signups", {
              event: "User signed up",
              description: `New user registered - Email: ${user.email} | Name: ${user.name || "N/A"} | ID: ${user.id}`,
              icon: "👤",
              notify: true,
              tags: {
                environment: process.env.NODE_ENV || "development",
                source: "better-auth"
              },
              metadata: {
                userId: user.id,
                email: user.email,
                name: user.name,
                createdAt: user.createdAt?.toISOString(),
                emailVerified: user.emailVerified || false
              }
            });
          } catch (error) {
            // Log error but don't block user creation
            console.error("Failed to log user sign-up to Logit:", error);
          }
        }
      }
    }
  }
});

Bug Reporting

Capture and log bug reports from your application:

// When a user reports a bug
await logit.now("bugs", {
  event: "Bug reported",
  description: `Bug report - Title: ${bug.title} | Severity: ${bug.severity} | Reporter: ${user.email} | URL: ${bug.url}`,
  icon: "🐛",
  notify: true,
  tags: {
    environment: process.env.NODE_ENV,
    severity: bug.severity,
    status: "open",
    component: bug.component
  },
  metadata: {
    bugId: bug.id,
    title: bug.title,
    description: bug.description,
    severity: bug.severity,
    reporterId: user.id,
    reporterEmail: user.email,
    url: bug.url,
    userAgent: bug.userAgent,
    stackTrace: bug.stackTrace,
    screenshot: bug.screenshot,
    timestamp: new Date().toISOString()
  }
});

// Or for automatic error tracking
try {
  // Your application code
} catch (error) {
  await logit.now("errors", {
    event: "Application error",
    description: `Error occurred - Message: ${error.message} | Stack: ${error.stack?.substring(0, 200)}`,
    icon: "❌",
    notify: true,
    tags: {
      environment: process.env.NODE_ENV,
      errorType: error.constructor.name,
      severity: "high"
    },
    metadata: {
      errorMessage: error.message,
      errorStack: error.stack,
      url: window?.location?.href,
      userAgent: navigator?.userAgent,
      timestamp: new Date().toISOString()
    }
  });
}

API Reference

init(config: LogitConfig)

Initializes a new Logit SDK client instance.

Parameters:

• config.token (string, required): API key/token
• config.projectId (string, required): Project ID for reference

Returns: LogitClient instance

logit.now(channel: string, data: LogEventData)

Logs an event to a channel.

Parameters:

• channel (string, required): Channel name
• data (LogEventData, required): Event data object
  • data.event (string, required): Event name/identifier
  • data.description (string, optional): Event description
  • data.icon (string, optional): Emoji/icon for the event
  • data.notify (boolean, optional): Whether to send a notification
  • data.tags (Record<string, any>, optional): Tags object
  • data.metadata (Record<string, any>, optional): Metadata object (loosely typed)
  • data.trackingId (string, optional): Tracking ID for grouping related events
  • data.aliasTrackingId (string, optional): Alias tracking ID to link this event to existing events

Returns: Promise<LogitResponse> with { success: boolean; id: string }

Throws: LogitError if the request fails

Types

All types are exported for use in your TypeScript projects:

import type {
  LogEventData,
  LogitConfig,
  LogitResponse,
  LogitErrorResponse
} from "@logitnow/sdk";

LogEventData

interface LogEventData {
  event: string; // required
  description?: string;
  icon?: string;
  notify?: boolean;
  tags?: Record<string, any>;
  metadata?: Record<string, any>; // loosely typed
  trackingId?: string;
  aliasTrackingId?: string;
}

LogitConfig

interface LogitConfig {
  token: string; // required
  projectId?: string;
  baseUrl?: string;
}

LogitResponse

interface LogitResponse {
  success: boolean;
  id: string;
}

Environment Variables

You can set the base URL via environment variable:

LOGIT_API_URL=https://your-instance.com

The SDK will automatically use this if no baseUrl is provided in the config.

Self-Hosted Instances

For self-hosted Logit instances, provide your custom base URL:

const logit = init({
  token: "your-api-key",
  baseUrl: "https://your-selfhosted-instance.com"
});

License

Closed Source