npm - @thisbefine/analytics - Versions diffs - 0.1.0 - Mend

@thisbefine/analytics 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (79) hide show

package/LICENSE +21 -0
package/README.md +403 -0
package/dist/core/analytics.d.ts +123 -0
package/dist/core/analytics.d.ts.map +1 -0
package/dist/core/analytics.js +334 -0
package/dist/core/analytics.js.map +1 -0
package/dist/core/errors.d.ts +94 -0
package/dist/core/errors.d.ts.map +1 -0
package/dist/core/errors.js +420 -0
package/dist/core/errors.js.map +1 -0
package/dist/core/logger.d.ts +28 -0
package/dist/core/logger.d.ts.map +1 -0
package/dist/core/logger.js +36 -0
package/dist/core/logger.js.map +1 -0
package/dist/core/logging.d.ts +12 -0
package/dist/core/logging.d.ts.map +1 -0
package/dist/core/logging.js +33 -0
package/dist/core/logging.js.map +1 -0
package/dist/core/privacy.d.ts +53 -0
package/dist/core/privacy.d.ts.map +1 -0
package/dist/core/privacy.js +94 -0
package/dist/core/privacy.js.map +1 -0
package/dist/core/queue.d.ts +59 -0
package/dist/core/queue.d.ts.map +1 -0
package/dist/core/queue.js +263 -0
package/dist/core/queue.js.map +1 -0
package/dist/core/session.d.ts +90 -0
package/dist/core/session.d.ts.map +1 -0
package/dist/core/session.js +246 -0
package/dist/core/session.js.map +1 -0
package/dist/core/storage.d.ts +64 -0
package/dist/core/storage.d.ts.map +1 -0
package/dist/core/storage.js +242 -0
package/dist/core/storage.js.map +1 -0
package/dist/core/types.d.ts +298 -0
package/dist/core/types.d.ts.map +1 -0
package/dist/core/types.js +34 -0
package/dist/core/types.js.map +1 -0
package/dist/core/validation.d.ts +11 -0
package/dist/core/validation.d.ts.map +1 -0
package/dist/core/validation.js +82 -0
package/dist/core/validation.js.map +1 -0
package/dist/core/version.d.ts +2 -0
package/dist/core/version.d.ts.map +1 -0
package/dist/core/version.js +4 -0
package/dist/core/version.js.map +1 -0
package/dist/index.d.ts +45 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +41 -0
package/dist/index.js.map +1 -0
package/dist/next/analytics.d.ts +59 -0
package/dist/next/analytics.d.ts.map +1 -0
package/dist/next/analytics.js +87 -0
package/dist/next/analytics.js.map +1 -0
package/dist/next.d.ts +46 -0
package/dist/next.d.ts.map +1 -0
package/dist/next.js +44 -0
package/dist/next.js.map +1 -0
package/dist/react/analytics.d.ts +51 -0
package/dist/react/analytics.d.ts.map +1 -0
package/dist/react/analytics.js +63 -0
package/dist/react/analytics.js.map +1 -0
package/dist/react/bug-report-widget.d.ts +21 -0
package/dist/react/bug-report-widget.d.ts.map +1 -0
package/dist/react/bug-report-widget.js +34 -0
package/dist/react/bug-report-widget.js.map +1 -0
package/dist/react/hooks.d.ts +141 -0
package/dist/react/hooks.d.ts.map +1 -0
package/dist/react/hooks.js +186 -0
package/dist/react/hooks.js.map +1 -0
package/dist/react.d.ts +42 -0
package/dist/react.d.ts.map +1 -0
package/dist/react.js +39 -0
package/dist/react.js.map +1 -0
package/dist/widget/bug-report.d.ts +16 -0
package/dist/widget/bug-report.d.ts.map +1 -0
package/dist/widget/bug-report.js +416 -0
package/dist/widget/bug-report.js.map +1 -0
package/package.json +107 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025 Thisbefine
+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 ADDED Viewed

@@ -0,0 +1,403 @@
+# @thisbefine/analytics
+> Know what's happening in your app. Fix it before your users complain.
+[![npm version](https://img.shields.io/npm/v/@thisbefine/analytics.svg)](https://www.npmjs.com/package/@thisbefine/analytics)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@thisbefine/analytics)](https://bundlephobia.com/package/@thisbefine/analytics)
+[![license](https://img.shields.io/npm/l/@thisbefine/analytics.svg)](https://github.com/thisbefine/analytics/blob/main/LICENSE)
+Lightweight analytics, error tracking, and logging for indie SaaS. Everything is fine. Your app is on fire? That's fine. Now you'll at least know about it.
+**~5KB gzipped** | **TypeScript-first** | **Privacy-respecting** | **Zero dependencies**
+## Why Thisbefine?
+- **Built for indie hackers** - No enterprise complexity, just what you need
+- **All-in-one** - Analytics + errors + logs in one tiny package
+- **Privacy-first** - Respects DNT and GPC by default (we're not the bad guys)
+- **Framework support** - First-class React and Next.js integration
+## Installation
+```bash
+npm install @thisbefine/analytics
+# or
+pnpm add @thisbefine/analytics
+# or
+yarn add @thisbefine/analytics
+```
+## Quick Start
+### Next.js (App Router)
+```tsx
+// app/layout.tsx
+import { Analytics } from '@thisbefine/analytics/next';
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  );
+}
+```
+Zero config. Reads `NEXT_PUBLIC_TBF_API_KEY` from your environment. Automatic page view tracking on route changes.
+```tsx
+// components/signup-button.tsx
+'use client';
+import { useTrack } from '@thisbefine/analytics/next';
+export function SignupButton() {
+  const track = useTrack('signup_clicked');
+  return (
+    <button onClick={() => track({ location: 'header' })}>
+      Sign Up
+    </button>
+  );
+}
+```
+### React
+```tsx
+// main.tsx
+import { Analytics } from '@thisbefine/analytics/react';
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <>
+    <App />
+    <Analytics apiKey={import.meta.env.VITE_TBF_API_KEY} />
+  </>
+);
+```
+### Vanilla JavaScript
+```typescript
+import { createAnalytics } from '@thisbefine/analytics';
+const analytics = createAnalytics({
+  apiKey: 'tbf_xxx',
+});
+// Track events
+analytics.track('button_clicked', { buttonId: 'signup' });
+// Identify users
+analytics.identify('user_123', { email: 'user@example.com', plan: 'pro' });
+// Track page views
+analytics.page('/dashboard');
+```
+## Features
+### Analytics
+Track what matters. Skip the vanity metrics.
+```typescript
+// Track custom events
+analytics.track('subscription_upgraded', {
+  plan: 'pro',
+  mrr: 29,
+  previous_plan: 'free',
+});
+// Identify users after login
+analytics.identify('user_123', {
+  email: 'user@example.com',
+  name: 'Jane Doe',
+  plan: 'pro',
+});
+// Associate users with companies/accounts
+analytics.group('company_456', {
+  name: 'Acme Inc',
+  plan: 'enterprise',
+  mrr: 499,
+});
+```
+### Error Tracking
+Catch errors before users catch you slipping.
+```typescript
+// Automatic error capture (enabled by default)
+// Or capture manually:
+analytics.captureException(error, {
+  component: 'PaymentForm',
+  userId: 'user_123',
+});
+// Add breadcrumbs for context
+analytics.addBreadcrumb({
+  category: 'ui',
+  message: 'User clicked checkout button',
+});
+// Log error messages
+analytics.captureMessage('Payment failed', 'error', {
+  orderId: 'order_789',
+});
+```
+### Structured Logging
+Logs that actually help you debug.
+```typescript
+analytics.log('User completed onboarding', 'info', {
+  step: 3,
+  duration: 45000,
+});
+// Log levels: debug, info, warn, error, fatal
+analytics.log('Cache miss for user preferences', 'debug', {
+  userId: 'user_123',
+});
+```
+### Privacy Controls
+Because being creepy is bad for business.
+```typescript
+// SDK respects DNT and GPC by default
+// Users can also opt out programmatically:
+analytics.optOut();
+// Check status
+if (analytics.isOptedOut()) {
+  console.log('User has opted out');
+}
+// Opt back in
+analytics.optIn();
+```
+## React Hooks
+All hooks are available from both `@thisbefine/analytics/react` and `@thisbefine/analytics/next`.
+### useTrack
+Memoized track function for a specific event.
+```tsx
+const trackClick = useTrack('button_clicked');
+<button onClick={() => trackClick({ buttonId: 'cta' })}>
+  Click me
+</button>
+```
+### useIdentify
+Identify users after authentication.
+```tsx
+const identify = useIdentify();
+// After login
+identify(user.id, {
+  email: user.email,
+  plan: user.plan,
+});
+```
+### useGroup
+Associate users with accounts/companies.
+```tsx
+const group = useGroup();
+// After selecting workspace
+group(workspace.id, {
+  name: workspace.name,
+  plan: workspace.plan,
+});
+```
+### useAnalytics
+Full analytics instance for advanced usage.
+```tsx
+const analytics = useAnalytics();
+analytics.track('custom_event', { foo: 'bar' });
+analytics.captureException(error);
+analytics.log('Something happened', 'info');
+```
+### useReset
+Reset session on logout.
+```tsx
+const reset = useReset();
+const handleLogout = () => {
+  reset();
+  router.push('/login');
+};
+```
+### useCaptureException
+Capture errors in components.
+```tsx
+const captureException = useCaptureException();
+try {
+  await riskyOperation();
+} catch (error) {
+  captureException(error as Error, { component: 'RiskyComponent' });
+}
+```
+### useLog
+Structured logging from components.
+```tsx
+const log = useLog();
+log('User viewed pricing page', 'info', { referrer: document.referrer });
+```
+## Configuration
+```typescript
+import { createAnalytics } from '@thisbefine/analytics';
+const analytics = createAnalytics({
+  // Required
+  apiKey: 'tbf_xxx',
+  // Optional
+  host: 'https://thisbefine.com',     // API endpoint
+  debug: false,                        // Console logging
+  flushAt: 20,                         // Batch size before sending
+  flushInterval: 10000,                // Ms between flushes
+  sessionTimeout: 1800000,             // 30 min session timeout
+  cookieDomain: '.yourdomain.com',     // Cross-subdomain tracking
+  respectDNT: true,                    // Honor Do Not Track
+  maxRetries: 3,                       // Retry failed requests
+  // Error tracking config
+  errors: {
+    enabled: true,
+    captureUnhandled: true,
+    captureConsoleErrors: true,
+  },
+});
+```
+### Analytics Component Props
+```tsx
+<Analytics
+  apiKey="tbf_xxx"              // Optional if NEXT_PUBLIC_TBF_API_KEY is set
+  host="http://localhost:3000"  // For local development
+  debug={true}                  // Enable console logging
+  trackPageviews={true}         // Auto track page views (default: true)
+  config={{                     // Additional config options
+    flushAt: 10,
+    sessionTimeout: 60 * 60 * 1000,
+  }}
+/>
+```
+## API Reference
+### Core Methods
+| Method | Description |
+|--------|-------------|
+| `track(event, properties?)` | Track a custom event |
+| `identify(userId, traits?)` | Identify a user |
+| `page(name?, properties?)` | Track a page view |
+| `group(accountId, traits?)` | Associate user with account |
+| `reset()` | Clear user data (call on logout) |
+| `flush()` | Force send queued events |
+| `optOut()` | Disable tracking |
+| `optIn()` | Re-enable tracking |
+| `isOptedOut()` | Check opt-out status |
+| `getUser()` | Get current user state |
+### Error Tracking Methods
+| Method | Description |
+|--------|-------------|
+| `captureException(error, context?)` | Capture an error |
+| `captureMessage(message, level?, context?)` | Capture a message |
+| `addBreadcrumb(breadcrumb)` | Add context for errors |
+### Logging Method
+| Method | Description |
+|--------|-------------|
+| `log(message, level, metadata?)` | Send structured log |
+Log levels: `debug` | `info` | `warn` | `error` | `fatal`
+## Storage
+The SDK stores data locally with the `tif_` prefix:
+| Key | Purpose | Persistence |
+|-----|---------|-------------|
+| `tif_anonymous_id` | Anonymous user ID | Permanent |
+| `tif_user_id` | Identified user ID | Until reset |
+| `tif_session_id` | Current session | 30 min timeout |
+| `tif_user_traits` | User properties | Until reset |
+| `tif_opt_out` | Opt-out flag | Permanent |
+Storage fallback: localStorage > sessionStorage > cookies > memory
+## TypeScript
+Full type definitions included:
+```typescript
+import type {
+  Analytics,
+  AnalyticsConfig,
+  UserState,
+  UserTraits,
+  AccountTraits,
+} from '@thisbefine/analytics';
+```
+## Bundle Size
+| Import | Size (gzipped) |
+|--------|----------------|
+| `@thisbefine/analytics` | ~5KB |
+| `@thisbefine/analytics/react` | +2KB |
+| `@thisbefine/analytics/next` | +1KB |
+## Browser Support
+Chrome 80+ | Firefox 75+ | Safari 13+ | Edge 80+
+## Contributing
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.
+## License
+MIT

package/dist/core/analytics.d.ts ADDED Viewed

@@ -0,0 +1,123 @@
+import type { LogLevel } from "./logging";
+import type { AccountTraits, Analytics, AnalyticsConfig, UserState, UserTraits } from "./types";
+/**
+ * Main Analytics class - the primary entry point for the SDK
+ *
+ * Usage:
+ * ```typescript
+ * const analytics = createAnalytics({ apiKey: 'tbf_xxx' });
+ *
+ * analytics.track('button_clicked', { buttonId: 'signup' });
+ * analytics.identify('user_123', { email: 'user@example.com' });
+ * analytics.page('/dashboard');
+ * ```
+ */
+export declare class AnalyticsImpl implements Analytics {
+    private config;
+    private storage;
+    private session;
+    private queue;
+    private privacy;
+    private errorCapture;
+    private initialized;
+    private logger;
+    constructor(config: AnalyticsConfig);
+    /**
+     * Resolve configuration with defaults
+     */
+    private resolveConfig;
+    /**
+     * Track a custom event
+     */
+    track(event: string, properties?: Record<string, unknown>): void;
+    /**
+     * Identify a user with traits
+     */
+    identify(userId: string, traits?: UserTraits): void;
+    /**
+     * Track a page view
+     */
+    page(name?: string, properties?: Record<string, unknown>): void;
+    /**
+     * Associate the current user with an account/company
+     */
+    group(accountId: string, traits?: AccountTraits): void;
+    /**
+     * Capture an exception and send to error tracking
+     */
+    captureException(error: Error, context?: Record<string, unknown>): void;
+    /**
+     * Capture a message as an error event
+     */
+    captureMessage(message: string, level?: "error" | "fatal" | "warning", context?: Record<string, unknown>): void;
+    /**
+     * Add a breadcrumb for error context
+     */
+    addBreadcrumb(breadcrumb: {
+        type: "click" | "navigation" | "network" | "console" | "custom";
+        message: string;
+        data?: Record<string, unknown>;
+    }): void;
+    /**
+     * Send a structured log event
+     */
+    log(message: string, level: LogLevel, metadata?: Record<string, unknown>): void;
+    /**
+     * Reset the current user session (call on logout)
+     */
+    reset(): void;
+    /**
+     * Manually flush the event queue
+     */
+    flush(): Promise<void>;
+    /**
+     * Opt out of tracking
+     */
+    optOut(): void;
+    /**
+     * Opt back in to tracking
+     */
+    optIn(): void;
+    /**
+     * Check if user has opted out
+     */
+    isOptedOut(): boolean;
+    /**
+     * Get current user state
+     */
+    getUser(): UserState;
+    /**
+     * Check if tracking should be allowed
+     */
+    private shouldTrack;
+    /**
+     * Build event context
+     */
+    private getContext;
+}
+/**
+ * Create a new Analytics instance
+ *
+ * @param config - Analytics configuration
+ * @returns Analytics instance
+ *
+ * @example
+ * ```typescript
+ * const analytics = createAnalytics({
+ *   apiKey: 'tbf_xxx',
+ *   debug: process.env.NODE_ENV === 'development',
+ * });
+ *
+ * analytics.track('signup_completed', { plan: 'pro' });
+ * ```
+ */
+export declare const createAnalytics: (config: AnalyticsConfig) => Analytics;
+/**
+ * Get or create a global analytics instance (for script tag usage)
+ */
+export declare const getAnalytics: () => Analytics | null;
+/**
+ * Initialize the global analytics instance
+ */
+export declare const initAnalytics: (config: AnalyticsConfig) => Analytics;
+//# sourceMappingURL=analytics.d.ts.map

package/dist/core/analytics.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../src/core/analytics.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAM1C,OAAO,KAAK,EACX,aAAa,EACb,SAAS,EACT,eAAe,EAOf,SAAS,EACT,UAAU,EACV,MAAM,SAAS,CAAC;AASjB;;;;;;;;;;;GAWG;AACH,qBAAa,aAAc,YAAW,SAAS;IAC9C,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,eAAe;IAkCnC;;OAEG;IACH,OAAO,CAAC,aAAa;IAerB;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IA+BhE;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI;IAmCnD;;OAEG;IACH,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IA+B/D;;OAEG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI;IAmCtD;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAKvE;;OAEG;IACH,cAAc,CACb,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,EACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI;IAKP;;OAEG;IACH,aAAa,CAAC,UAAU,EAAE;QACzB,IAAI,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;QAChE,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC/B,GAAG,IAAI;IAIR;;OAEG;IACH,GAAG,CACF,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,QAAQ,EACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI;IAKP;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACH,MAAM,IAAI,IAAI;IAId;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,OAAO,IAAI,SAAS;IAIpB;;OAEG;IACH,OAAO,CAAC,WAAW;IAanB;;OAEG;IACH,OAAO,CAAC,UAAU;CA8BlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,eAAe,KAAG,SAEzD,CAAC;AAIF;;GAEG;AACH,eAAO,MAAM,YAAY,QAAO,SAAS,GAAG,IAE3C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,eAAe,KAAG,SAQvD,CAAC"}