@luminpdf/node-pinpoint

A Node.js AWS Pinpoint SDK for event tracking. This package provides a simple, type-safe interface for tracking events to AWS Pinpoint from your server-side applications.

Features

• 🎯 Singleton Pattern: Ensures a single instance across your application
• 🔒 Type-Safe: Full TypeScript support with proper type definitions
• 📊 Event Tracking: Track single or batch events to AWS Pinpoint
• 🚀 Easy to Use: Simple API for common Pinpoint operations
• 🔧 Flexible Configuration: Support for custom credentials, regions, and endpoints

Installation

npm install @luminpdf/node-pinpoint

or

pnpm add @luminpdf/node-pinpoint

or

yarn add @luminpdf/node-pinpoint

Prerequisites

• AWS Pinpoint Application ID
• AWS credentials (via environment variables, IAM roles, or explicit configuration)
• Node.js 18+ and TypeScript 4.5+

Usage

Initialize the Client

import { PinpointClient } from "@luminpdf/node-pinpoint";

const pinpointClient = PinpointClient.create({
  applicationId: "your-pinpoint-app-id",
  region: "us-east-1",
  disableInDevelopment: false,
});

With Custom Credentials

const pinpointClient = PinpointClient.create({
  applicationId: "your-pinpoint-app-id",
  region: "us-east-1",
  credentials: {
    accessKeyId: "your-access-key-id",
    secretAccessKey: "your-secret-access-key",
  },
});

Track a Single Event

await pinpointClient.trackEvent({
  eventType: "user_signup",
  userId: "user-123",
  attributes: {
    plan: "premium",
    source: "web",
  },
  metrics: {
    signup_duration: 1500,
  },
});

Track Events with Custom Endpoint ID

await pinpointClient.trackEvent({
  eventType: "purchase",
  userId: "user-123",
  endpointId: "device-456",
  attributes: {
    product_id: "prod-789",
    category: "electronics",
  },
  metrics: {
    price: 99.99,
    quantity: 2,
  },
});

Track Multiple Events (Batch)

await pinpointClient.trackEvents(
  [
    {
      eventType: "page_view",
      attributes: {
        page: "/home",
        referrer: "google.com",
      },
    },
    {
      eventType: "button_click",
      attributes: {
        button_id: "cta-signup",
      },
    },
  ],
  "user-123",
  "device-456"
);

Get Instance After Initialization

import { PinpointClient } from "@luminpdf/node-pinpoint";

const pinpointClient = PinpointClient.getInstance();

Check Configuration

const config = pinpointClient.getConfig();
console.log(config.applicationId);
console.log(config.region);

const isConfigured = pinpointClient.isClientConfigured();

API Reference

PinpointClient.create(config: PinpointClientConfig): PinpointClient

Creates and returns a singleton instance of the PinpointClient.

Parameters:

• config.applicationId (required): Your AWS Pinpoint Application ID
• config.region (optional): AWS region (default: "us-east-1")
• config.endpointId (optional): Default endpoint ID for events
• config.credentials (optional): AWS credentials object
• config.disableInDevelopment (optional): Disable tracking in development (default: false)

PinpointClient.getInstance(): PinpointClient

Returns the existing singleton instance. Throws an error if create() hasn't been called.

trackEvent(options: TrackEventOptions): Promise<void>

Tracks a single event to AWS Pinpoint.

Parameters:

• options.eventType (required): The type of event
• options.userId (optional): User ID associated with the event
• options.endpointId (optional): Endpoint ID (defaults to config or generates UUID)
• options.attributes (optional): Event attributes (string, number, or boolean values)
• options.metrics (optional): Event metrics (numeric values)

trackEvents(events: TrackEventOptions[], userId?: string, endpointId?: string): Promise<void>

Tracks multiple events in a single batch request.

Parameters:

• events: Array of event options
• userId (optional): User ID for all events in the batch
• endpointId (optional): Endpoint ID for all events in the batch

AWS Credentials

The SDK supports multiple ways to provide AWS credentials:

1. Environment Variables (default):

   • AWS_ACCESS_KEY_ID
   • AWS_SECRET_ACCESS_KEY

2. IAM Roles (when running on EC2, Lambda, etc.)

3. Explicit Configuration:

   PinpointClient.create({
     applicationId: "your-app-id",
     credentials: {
       accessKeyId: "your-key",
       secretAccessKey: "your-secret",
     },
   });

Error Handling

The SDK throws errors if:

• applicationId is not provided
• Client is used before initialization
• AWS API calls fail

Always wrap tracking calls in try-catch blocks:

try {
  await pinpointClient.trackEvent({
    eventType: "user_action",
    attributes: { action: "click" },
  });
} catch (error) {
  console.error("Failed to track event:", error);
}

Development Mode

When disableInDevelopment is set to true, tracking methods will return early without making API calls when NODE_ENV is set to development or dev.

TypeScript Support

Full TypeScript support is included. Import types as needed:

import type {
  PinpointClientConfig,
  TrackEventOptions,
  EventAttributes,
  EventMetrics,
} from "@luminpdf/node-pinpoint";

License

ISC