@bliplogs/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to the BlipLogs SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-02-03
+
+### Added
+
+- Initial release of the BlipLogs SDK
+- Zero-dependency event tracking for browser and server environments
+- `BlipLogs.configure()` for global configuration
+- `BlipLogs.track()` for general event tracking
+- `BlipLogs.info()`, `BlipLogs.warn()`, `BlipLogs.error()` convenience methods
+- Instance-based API for multiple configurations
+- Automatic browser context capture (URL, referrer, user agent)
+- Sensitive URL parameter redaction for privacy
+- Session tracking with 30-minute timeout
+- `sendBeacon` primary transport with `fetch` fallback
+- Server-side support for Node 18+, Cloudflare Workers, and edge runtimes
+- Debug mode and error callbacks for troubleshooting
+- Full TypeScript support with exported types

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BlipLogs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,356 @@
+# BlipLogs SDK
+
+[![npm version](https://img.shields.io/npm/v/@bliplogs/sdk.svg)](https://www.npmjs.com/package/@bliplogs/sdk)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@bliplogs/sdk)](https://bundlephobia.com/package/@bliplogs/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+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 `sendBeacon` for non-blocking delivery, falls back to `fetch`
+- **Simple** – Configure once, track anywhere
+
+## Installation
+
+```bash
+npm install @bliplogs/sdk
+```
+
+## Quick Start
+
+```typescript
+import BlipLogs from '@bliplogs/sdk';
+
+BlipLogs.configure({
+  apiKey: 'your-api-key',
+  projectId: 'your-project-id'
+});
+
+BlipLogs.track('signup_clicked', { plan: 'pro' });
+```
+
+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
+
+### React / Next.js
+
+**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 (
+    <button onClick={() => BlipLogs.track('signup_clicked')}>
+      Sign Up
+    
+  );
+}
+```
+
+### Astro
+
+**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
+});
+---
+
+<html>
+  <body>
+    <slot />
+  </body>
+</html>
+```
+
+**2. Track events with a script tag:**
+
+```astro
+<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`:**
+
+```astro
+---
+import SignupButton from '../components/SignupButton.tsx';
+---
+
+<SignupButton client:load />
+```
+
+### Vanilla JavaScript
+
+```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.
+
+### Node.js
+
+```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 });
+```
+
+### Cloudflare Workers
+
+```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');
+  }
+};
+```
+
+### 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:
+
+```typescript
+BlipLogs.track('api_request', {
+  path: req.url,
+  userAgent: req.headers['user-agent'],
+  duration: 120
+});
+```
+
+## Configuration Options
+
+```typescript
+BlipLogs.configure({
+  apiKey: 'your-api-key',       // Required
+  projectId: 'your-project-id', // Required
+  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
+  }
+});
+```
+
+## 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.
+
+```typescript
+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:
+
+```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. **Browser:** Uses `navigator.sendBeacon()` for fast, non-blocking delivery
+2. **Fallback:** Automatically uses `fetch()` with `keepalive: true` if sendBeacon is unavailable
+3. **Server:** Uses `fetch()` directly
+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.
+
+### 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):
+
+```typescript
+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
+
+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](https://bliplogs.co.uk) – Sign up and manage projects
+- [Documentation](https://bliplogs.co.uk/docs) – Full docs
+- [GitHub Issues](https://github.com/NoSweatWebsites/bliplogs-sdk/issues) – Bugs and feature requests
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,185 @@
+type BlipLevel = 'info' | 'warn' | 'error';
+interface BlipMetadata {
+    [key: string]: unknown;
+}
+interface BlipContext {
+    projectId?: string;
+    url?: string;
+    referrer?: string;
+    userAgent?: string;
+}
+interface BlipPayload {
+    event: string;
+    level: BlipLevel;
+    metadata?: BlipMetadata;
+    context: BlipContext;
+    timestamp: string;
+    session_id?: string;
+    timestamp_ms?: number;
+    api_key?: string;
+    anonymize_ip?: boolean;
+}
+interface BlipLogsError {
+    type: 'network' | 'rate_limit' | 'auth' | 'validation' | 'unknown';
+    message: string;
+    statusCode?: number;
+    originalError?: Error;
+}
+/**
+ * Privacy configuration options for GDPR compliance
+ */
+interface BlipPrivacyConfig {
+    /** Anonymize IP address on server (default: false) */
+    anonymizeIp?: boolean;
+    /** Collect page URL (default: true) */
+    collectUrl?: boolean;
+    /** Collect referrer URL (default: true) */
+    collectReferrer?: boolean;
+    /** Collect user agent string (default: true) */
+    collectUserAgent?: boolean;
+    /** Enable session tracking (default: true) */
+    collectSessionId?: boolean;
+}
+interface BlipLogsConfig {
+    apiKey: string;
+    projectId: string;
+    /** Enable debug mode to log errors to console (default: false) */
+    debug?: boolean;
+    /** Callback fired when an error occurs during event tracking */
+    onError?: (error: BlipLogsError) => void;
+    /** Privacy settings for GDPR compliance */
+    privacy?: BlipPrivacyConfig;
+}
+/**
+ * BlipLogs SDK - Zero-dependency event logging client
+ *
+ * @example
+ * ```ts
+ * // Global configuration (recommended for Astro/React apps)
+ * BlipLogs.configure({ apiKey: 'your-api-key', projectId: 'your-project-id' });
+ * BlipLogs.track('button_clicked', { buttonId: 'signup' });
+ *
+ * // Or use instance-based API
+ * const blip = new BlipLogs({ apiKey: 'your-api-key', projectId: 'your-project-id' });
+ * blip.track('error_occurred', { message: 'Failed to load' }, 'error');
+ * ```
+ */
+declare class BlipLogs {
+    private static globalInstance;
+    private static readonly API_ENDPOINT;
+    private apiKey;
+    private projectId;
+    private debug;
+    private onError?;
+    private privacy;
+    constructor(config: BlipLogsConfig);
+    /**
+     * Configure the global BlipLogs instance
+     * Call this once at the start of your application (e.g., in your Astro layout)
+     *
+     * @example
+     * ```ts
+     * // In Astro layout or initialization script
+     * BlipLogs.configure({
+     *   apiKey: import.meta.env.PUBLIC_BLIPLOGS_API_KEY,
+     *   projectId: import.meta.env.PUBLIC_BLIPLOGS_PROJECT_ID
+     * });
+     * ```
+     */
+    static configure(config: BlipLogsConfig): void;
+    /**
+     * Get the global BlipLogs instance
+     * Throws an error if not configured
+     */
+    private static getInstance;
+    /**
+     * Track an event using the global instance
+     *
+     * @example
+     * ```ts
+     * BlipLogs.track('button_clicked', { buttonId: 'signup' });
+     * ```
+     */
+    static track(event: string, metadata?: BlipMetadata, level?: BlipLevel): boolean;
+    /**
+     * Track an info-level event using the global instance
+     *
+     * @example
+     * ```ts
+     * BlipLogs.info('page_viewed', { page: '/dashboard' });
+     * ```
+     */
+    static info(event: string, metadata?: BlipMetadata): boolean;
+    /**
+     * Track a warn-level event using the global instance
+     *
+     * @example
+     * ```ts
+     * BlipLogs.warn('slow_request', { duration: 5000 });
+     * ```
+     */
+    static warn(event: string, metadata?: BlipMetadata): boolean;
+    /**
+     * Track an error-level event using the global instance
+     *
+     * @example
+     * ```ts
+     * BlipLogs.error('api_error', { message: 'Failed to fetch' });
+     * ```
+     */
+    static error(event: string, metadata?: BlipMetadata): boolean;
+    /**
+     * Gets or creates a session ID from sessionStorage
+     * Sessions expire after 30 minutes of inactivity
+     */
+    private getSessionId;
+    /**
+     * Sensitive URL parameters that should be redacted
+     */
+    private static readonly SENSITIVE_PARAMS;
+    /**
+     * Sanitize a URL by removing sensitive query parameters
+     */
+    private sanitizeUrl;
+    /**
+     * Auto-captures browser context information with sensitive data sanitization
+     * Respects privacy configuration settings
+     */
+    private getContext;
+    /**
+     * Track an event with optional metadata and level
+     *
+     * @param event - The event name (e.g., 'signup_modal_opened')
+     * @param metadata - Optional custom data to attach to the event
+     * @param level - Event level: 'info' (default), 'warn', or 'error'
+     * @returns boolean - Whether the event was queued for delivery
+     */
+    track(event: string, metadata?: BlipMetadata, level?: BlipLevel): boolean;
+    /**
+     * Convenience method for info-level events
+     */
+    info(event: string, metadata?: BlipMetadata): boolean;
+    /**
+     * Convenience method for warn-level events
+     */
+    warn(event: string, metadata?: BlipMetadata): boolean;
+    /**
+     * Convenience method for error-level events
+     */
+    error(event: string, metadata?: BlipMetadata): boolean;
+    /**
+     * Sends the payload using sendBeacon for speed and reliability
+     * Falls back to fetch if sendBeacon is unavailable or blocked
+     */
+    private send;
+    /**
+     * Handle and report errors
+     */
+    private handleError;
+    /**
+     * Fallback method using fetch API
+     */
+    private sendWithFetch;
+}
+
+export { type BlipContext, type BlipLevel, BlipLogs, type BlipLogsConfig, type BlipLogsError, type BlipMetadata, type BlipPayload, type BlipPrivacyConfig, BlipLogs as default };