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

``bash
npm install @bliplogs/sdk
`

Quick Start

$3

Configure allowed domains in your BlipLogs dashboard settings, then:

`typescript
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.

$3

`typescript
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

`typescript
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.

$3

1. Create lib/bliplogs.ts:

`typescript
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):

`typescript
import '../lib/bliplogs';
`

3. Use anywhere:

`tsx
import BlipLogs from '@bliplogs/sdk';

function SignupButton() {
return (
BlipLogs.track('signup_clicked')}>
Sign Up

);
}
`

$3

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

`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
});
---






`

2. Track events with a script tag:

`astro


Sign Up


`

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

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


`

$3

`html

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.

$3

`typescript
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 });
`

$3

`typescript
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');
}
};
`

$3

| 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:

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

Configuration Options

`typescript
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

$3

Configure the SDK. Call once at app startup.

$3

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

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

$3

`typescript
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:

`typescript
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:

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

How It Works

1. 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.
2. 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.
3. 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).
4. Context: Auto-captures URL, referrer, and user agent in browsers.

Privacy

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

$3

| 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 |

$3

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

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

$3

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`)

$3

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

Links

- Dashboard – Sign up and manage projects
- Documentation – Full docs
- GitHub Issues – Bugs and feature requests

License

MIT