@bliplogs/sdk

v0.2.2

Published

3 days ago

Zero-dependency event logging SDK for BlipLogs. Track events from browser and server with minimal overhead.

Downloads

507

0High
0Medium
0Low

nicknosweat

logging events analytics bliplogs event-tracking telemetry observability monitoring sendbeacon fire-and-forget zero-dependencies debugging

BlipLogs SDK

Lightweight event tracking for browser and server. Zero dependencies, under 2KB gzipped.

Why BlipLogs?

Tiny – Under 2KB gzipped, no dependencies
Universal – Works in browsers, Node 18+, Cloudflare Workers, edge runtimes
Fast – Uses fetch with keepalive: true for non-blocking delivery (supports secure headers); falls back to sendBeacon when fetch is unavailable
Simple – Configure once, track anywhere

Installation

npm install @bliplogs/sdk

Quick Start

Browser (No API Key Required)

Configure allowed domains in your BlipLogs dashboard settings, then:

import BlipLogs from '@bliplogs/sdk';

BlipLogs.configure({
  projectId: 'your-project-id'  // That's it - no API key needed!
});

BlipLogs.track('signup_clicked', { plan: 'pro' });

The browser's origin is automatically validated against your allowed domains.

Server (Secret Key Required)

import BlipLogs from '@bliplogs/sdk';

BlipLogs.configure({
  projectId: 'your-project-id',
  secretKey: 'your-secret-api-key',  // Required for server; never sent in browser
  // publicKey defaults to projectId; override if you use a separate public id
});

BlipLogs.track('order_created', { orderId: '123' });

You can still use apiKey (deprecated) as an alias for secretKey.

That's it. Three lines to start tracking.

Log Levels

BlipLogs.info('page_viewed', { page: '/dashboard' });
BlipLogs.warn('slow_request', { duration: 5000 });
BlipLogs.error('api_error', { status: 500 });

Framework Examples

For detailed setup (client-only, server-only, or both) in Next.js and Astro, see FRAMEWORKS.md.

React / Next.js

1. Create lib/bliplogs.ts:

import BlipLogs from '@bliplogs/sdk';

BlipLogs.configure({
  apiKey: process.env.NEXT_PUBLIC_BLIPLOGS_API_KEY || '',
  projectId: process.env.NEXT_PUBLIC_BLIPLOGS_PROJECT_ID || ''
});

2. Import in your app entry (app/layout.tsx or pages/_app.tsx):

import '../lib/bliplogs';

3. Use anywhere:

import BlipLogs from '@bliplogs/sdk';

function SignupButton() {
  return (
    <button onClick={() => BlipLogs.track('signup_clicked')}>
      Sign Up
    
  );
}

Astro

1. Configure in your layout (src/layouts/Layout.astro):

---
// Configuration runs at build time, but the SDK handles this gracefully
import BlipLogs from '@bliplogs/sdk';

BlipLogs.configure({
  apiKey: import.meta.env.PUBLIC_BLIPLOGS_API_KEY,
  projectId: import.meta.env.PUBLIC_BLIPLOGS_PROJECT_ID
});
---

<html>
  <body>
    <slot />
  </body>
</html>

2. Track events with a script tag:

<button id="signup">Sign Up</button>

<script>
  import BlipLogs from '@bliplogs/sdk';

  document.getElementById('signup')?.addEventListener('click', () => {
    BlipLogs.track('signup_clicked');
  });
</script>

Or use a React/Svelte/Vue component with client:load:

---
import SignupButton from '../components/SignupButton.tsx';
---

<SignupButton client:load />

Vanilla JavaScript


  import BlipLogs from './node_modules/@bliplogs/sdk/dist/index.mjs';

  BlipLogs.configure({
    apiKey: 'your-api-key',
    projectId: 'your-project-id'
  });

  document.getElementById('myButton').addEventListener('click', () => {
    BlipLogs.track('button_clicked');
  });

Server-Side Usage

The SDK works anywhere with global fetch: Node 18+, Cloudflare Workers, Astro actions, and most serverless runtimes.

Node.js

import BlipLogs from '@bliplogs/sdk';

BlipLogs.configure({
  apiKey: process.env.BLIPLOGS_API_KEY!,
  projectId: process.env.BLIPLOGS_PROJECT_ID!
});

// In your request handler
BlipLogs.info('order_created', { orderId: '123', amount: 4999 });

Cloudflare Workers

import BlipLogs from '@bliplogs/sdk';

export default {
  async fetch(req: Request, env: Env) {
    BlipLogs.configure({
      apiKey: env.BLIPLOGS_API_KEY,
      projectId: env.BLIPLOGS_PROJECT_ID
    });

    BlipLogs.track('worker_request', {
      path: new URL(req.url).pathname,
      method: req.method
    });

    return new Response('OK');
  }
};

Server-Side Limitations

| Feature | Browser | Server | |---------|---------|--------| | Session ID | ✓ Auto-generated | ✗ Not available | | URL/Referrer/User Agent | ✓ Auto-captured | ✗ Not captured | | Transport | sendBeacon → fetch | fetch only |

Pass any server-specific context via metadata:

BlipLogs.track('api_request', {
  path: req.url,
  userAgent: req.headers['user-agent'],
  duration: 120
});

Configuration Options

BlipLogs.configure({
  projectId: 'your-project-id', // Required
  apiKey: 'your-api-key',       // Required for server, optional in browser*
  debug: true,                  // Log errors to console
  onError: (error) => {         // Custom error handling
    console.error(error.type, error.message);
  },
  privacy: {                    // GDPR/privacy controls
    anonymizeIp: true,          // Don't store IP or geo data
    collectUrl: false,          // Don't collect page URL
    collectReferrer: false,     // Don't collect referrer
    collectUserAgent: false,    // Don't collect user agent
    collectSessionId: false     // Don't track sessions
  }
});

*Browser SDK without API key requires domain whitelisting in dashboard settings.

API Reference

`BlipLogs.configure(config)`

Configure the SDK. Call once at app startup.

`BlipLogs.track(event, metadata?, level?)`

Track an event. Returns boolean indicating if the event was queued.

BlipLogs.track('checkout_started', { cartValue: 99.99 }, 'info');

`BlipLogs.info(event, metadata?)`

`BlipLogs.warn(event, metadata?)`

`BlipLogs.error(event, metadata?)`

Convenience methods for specific log levels.

Instance-Based Usage

Need multiple configurations? Create instances:

const analytics = new BlipLogs({
  apiKey: 'analytics-key',
  projectId: 'analytics-project'
});

const errors = new BlipLogs({
  apiKey: 'errors-key',
  projectId: 'errors-project'
});

analytics.track('page_view');
errors.error('unhandled_exception', { stack: '...' });

Error Handling

The SDK is fire-and-forget by default – errors won't crash your app. Enable visibility when needed:

BlipLogs.configure({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  debug: true,
  onError: (error) => {
    if (error.type === 'rate_limit') {
      console.warn('Rate limit hit');
    }
  }
});

Error types: network, rate_limit, auth, validation, unknown

TypeScript

Full type definitions included:

import BlipLogs, {
  BlipMetadata,
  BlipLevel,
  BlipLogsConfig,
  BlipLogsError,
  BlipContext,
  BlipPayload,
  BlipPrivacyConfig
} from '@bliplogs/sdk';

How It Works

Transport: Uses fetch() with keepalive: true by default (allows X-Blip-Public-Key and X-Blip-Secret-Key headers for the seamless secure model). Falls back to sendBeacon only when fetch is unavailable (e.g. very old envs); in that case a console warning notes that keys are passed via query and domain whitelisting should be used in browser.
Browser: Sends only X-Blip-Public-Key (project id); secret key is never sent in browser. The API validates the request using the Origin/Referer header against your project’s allowed domains.
Server: Sends X-Blip-Public-Key and X-Blip-Secret-Key; the API verifies the secret key in D1 and allows the request (server trust).
Context: Auto-captures URL, referrer, and user agent in browsers.

Privacy

The SDK collects minimal data by default and provides controls for GDPR compliance.

Data Collected

| Data | Default | Privacy Option | |------|---------|----------------| | Page URL | Collected | collectUrl: false | | Referrer | Collected | collectReferrer: false | | User Agent | Collected | collectUserAgent: false | | Session ID | Generated | collectSessionId: false | | IP Address | Stored server-side | anonymizeIp: true |

Privacy-First Configuration

For maximum privacy (e.g., before cookie consent):

BlipLogs.configure({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  privacy: {
    anonymizeIp: true,
    collectUrl: false,
    collectReferrer: false,
    collectUserAgent: false,
    collectSessionId: false
  }
});

Automatic Protections

The SDK automatically redacts sensitive URL parameters:

Auth tokens (token, access_token, api_key)
OAuth params (code, state, nonce)
PII (email, phone, ssn)
Payment data (credit_card, cvv)

Your Responsibilities

Privacy policy – Disclose BlipLogs in your privacy policy
Consent – Obtain consent if required (cookie banner)
Data deletion – Contact support for deletion requests

License

MIT