Zero-dependency event logging SDK for BlipLogs. Track events from browser and server with minimal overhead.
npm install @bliplogs/sdk


Lightweight event tracking for browser and server. Zero dependencies, under 2KB gzipped.
- 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
``bash`
npm install @bliplogs/sdk
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.
`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.
`typescript`
BlipLogs.info('page_viewed', { page: '/dashboard' });
BlipLogs.warn('slow_request', { duration: 5000 });
BlipLogs.error('api_error', { status: 500 });
For detailed setup (client-only, server-only, or both) in Next.js and Astro, see FRAMEWORKS.md.
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 (
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
`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
$3
$3
Convenience methods for specific log levels.
$3
Need multiple configurations? Create instances:
`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, unknownTypeScript
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`)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
- Dashboard – Sign up and manage projects
- Documentation – Full docs
- GitHub Issues – Bugs and feature requests
MIT