@mostly-good-metrics/javascript 0.1.0

package/dist/types/types.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Configuration options for the MostlyGoodMetrics SDK.
+ */
+export interface MGMConfiguration {
+    /**
+     * The API key for authenticating with MostlyGoodMetrics.
+     * Required.
+     */
+    apiKey: string;
+    /**
+     * The base URL for the MostlyGoodMetrics API.
+     * @default "https://mostlygoodmetrics.com"
+     */
+    baseURL?: string;
+    /**
+     * The environment name (e.g., "production", "staging", "development").
+     * @default "production"
+     */
+    environment?: string;
+    /**
+     * Maximum number of events to send in a single batch.
+     * Must be between 1 and 1000.
+     * @default 100
+     */
+    maxBatchSize?: number;
+    /**
+     * Interval in seconds between automatic flush attempts.
+     * Must be at least 1 second.
+     * @default 30
+     */
+    flushInterval?: number;
+    /**
+     * Maximum number of events to store locally before dropping oldest events.
+     * Must be at least 100.
+     * @default 10000
+     */
+    maxStoredEvents?: number;
+    /**
+     * Whether to enable debug logging to the console.
+     * @default false
+     */
+    enableDebugLogging?: boolean;
+    /**
+     * Whether to automatically track app lifecycle events
+     * ($app_opened, $app_backgrounded, $app_installed, $app_updated).
+     * @default true
+     */
+    trackAppLifecycleEvents?: boolean;
+    /**
+     * Custom bundle identifier to use instead of auto-detection.
+     * Useful for multi-tenant applications.
+     */
+    bundleId?: string;
+    /**
+     * The app version string to include with events.
+     * If not provided, will attempt to auto-detect from the environment.
+     */
+    appVersion?: string;
+    /**
+     * The OS version string to include with events.
+     * If not provided, will attempt to auto-detect from the environment.
+     * For React Native, pass Platform.Version.toString().
+     */
+    osVersion?: string;
+    /**
+     * Custom storage adapter. If not provided, uses localStorage in browsers
+     * or in-memory storage in non-browser environments.
+     */
+    storage?: IEventStorage;
+    /**
+     * Custom network client. If not provided, uses fetch-based client.
+     */
+    networkClient?: INetworkClient;
+}
+/**
+ * Internal resolved configuration with all defaults applied.
+ */
+export interface ResolvedConfiguration extends Required<Omit<MGMConfiguration, 'storage' | 'networkClient'>> {
+    storage?: IEventStorage;
+    networkClient?: INetworkClient;
+}
+/**
+ * Properties that can be attached to an event.
+ * Supports nested objects up to 3 levels deep.
+ */
+export type EventProperties = Record<string, EventPropertyValue>;
+/**
+ * Valid types for event property values.
+ */
+export type EventPropertyValue = null | boolean | number | string | EventPropertyValue[] | {
+    [key: string]: EventPropertyValue;
+};
+/**
+ * An analytics event to be tracked.
+ */
+export interface MGMEvent {
+    /**
+     * The name of the event. Must match pattern: ^$?[a-zA-Z][a-zA-Z0-9_]*$
+     * Max 255 characters.
+     */
+    name: string;
+    /**
+     * ISO8601 timestamp when the event occurred.
+     */
+    timestamp: string;
+    /**
+     * The user ID associated with this event.
+     */
+    userId?: string;
+    /**
+     * The session ID associated with this event.
+     */
+    sessionId?: string;
+    /**
+     * The platform this event was generated from.
+     */
+    platform: Platform;
+    /**
+     * The app version string.
+     */
+    appVersion?: string;
+    /**
+     * The OS version string.
+     */
+    osVersion?: string;
+    /**
+     * The environment name.
+     */
+    environment: string;
+    /**
+     * Custom properties attached to this event.
+     */
+    properties?: EventProperties;
+}
+/**
+ * Context sent with each batch of events.
+ * Applied to all events in the batch server-side.
+ */
+export interface MGMEventContext {
+    platform: Platform;
+    appVersion?: string;
+    osVersion?: string;
+    userId?: string;
+    sessionId?: string;
+    environment: string;
+}
+/**
+ * The payload sent to the events API.
+ */
+export interface MGMEventsPayload {
+    events: MGMEvent[];
+    context: MGMEventContext;
+}
+/**
+ * Supported platforms.
+ */
+export type Platform = 'web' | 'ios' | 'android' | 'react-native' | 'expo' | 'node';
+/**
+ * Device types for automatic device detection.
+ */
+export type DeviceType = 'phone' | 'tablet' | 'desktop' | 'tv' | 'watch' | 'unknown';
+/**
+ * Error types that can occur in the SDK.
+ */
+export type MGMErrorType = 'NETWORK_ERROR' | 'ENCODING_ERROR' | 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'INVALID_EVENT_NAME' | 'STORAGE_ERROR' | 'UNKNOWN_ERROR';
+/**
+ * Result of a network send operation.
+ */
+export type SendResult = {
+    success: true;
+} | {
+    success: false;
+    error: MGMError;
+    shouldRetry: boolean;
+};
+/**
+ * Interface for event storage implementations.
+ */
+export interface IEventStorage {
+    /**
+     * Store an event for later sending.
+     */
+    store(event: MGMEvent): Promise<void>;
+    /**
+     * Fetch up to `limit` events from storage (FIFO order).
+     */
+    fetchEvents(limit: number): Promise<MGMEvent[]>;
+    /**
+     * Remove events from storage after successful send.
+     */
+    removeEvents(count: number): Promise<void>;
+    /**
+     * Get the current count of stored events.
+     */
+    eventCount(): Promise<number>;
+    /**
+     * Clear all stored events.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Interface for network client implementations.
+ */
+export interface INetworkClient {
+    /**
+     * Send a batch of events to the server.
+     */
+    sendEvents(payload: MGMEventsPayload, config: ResolvedConfiguration): Promise<SendResult>;
+    /**
+     * Check if the client is currently rate-limited.
+     */
+    isRateLimited(): boolean;
+    /**
+     * Get the retry-after time if rate-limited, or null if not.
+     */
+    getRetryAfterTime(): Date | null;
+}
+/**
+ * Custom error class for SDK errors.
+ */
+export declare class MGMError extends Error {
+    readonly type: MGMErrorType;
+    readonly retryAfter?: number;
+    readonly statusCode?: number;
+    constructor(type: MGMErrorType, message: string, options?: {
+        retryAfter?: number;
+        statusCode?: number;
+    });
+}
+/**
+ * System event names (prefixed with $).
+ */
+export declare const SystemEvents: {
+    readonly APP_INSTALLED: "$app_installed";
+    readonly APP_UPDATED: "$app_updated";
+    readonly APP_OPENED: "$app_opened";
+    readonly APP_BACKGROUNDED: "$app_backgrounded";
+};
+/**
+ * System property keys (prefixed with $).
+ */
+export declare const SystemProperties: {
+    readonly DEVICE_TYPE: "$device_type";
+    readonly DEVICE_MODEL: "$device_model";
+    readonly VERSION: "$version";
+    readonly PREVIOUS_VERSION: "$previous_version";
+};
+/**
+ * Default configuration values.
+ */
+export declare const DefaultConfiguration: {
+    readonly baseURL: "https://mostlygoodmetrics.com";
+    readonly environment: "production";
+    readonly maxBatchSize: 100;
+    readonly flushInterval: 30;
+    readonly maxStoredEvents: 10000;
+    readonly enableDebugLogging: false;
+    readonly trackAppLifecycleEvents: true;
+};
+/**
+ * Validation constraints.
+ */
+export declare const Constraints: {
+    readonly MAX_EVENT_NAME_LENGTH: 255;
+    readonly MAX_BATCH_SIZE: 1000;
+    readonly MIN_BATCH_SIZE: 1;
+    readonly MIN_FLUSH_INTERVAL: 1;
+    readonly MIN_STORED_EVENTS: 100;
+    readonly MAX_STRING_PROPERTY_LENGTH: 1000;
+    readonly MAX_PROPERTY_DEPTH: 3;
+    readonly MAX_PROPERTY_SIZE_BYTES: number;
+    readonly COMPRESSION_THRESHOLD_BYTES: 1024;
+};
+/**
+ * Regular expression for validating event names.
+ * Must start with a letter (or $ for system events) followed by alphanumeric and underscores.
+ */
+export declare const EVENT_NAME_REGEX: RegExp;
+//# sourceMappingURL=types.d.ts.map

package/dist/types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types/utils.d.ts

@@ -0,0 +1,48 @@
+import { DeviceType, EventProperties, MGMConfiguration, Platform, ResolvedConfiguration } from './types';
+/**
+ * Generate a UUID v4 string.
+ */
+export declare function generateUUID(): string;
+/**
+ * Get the current timestamp in ISO8601 format.
+ */
+export declare function getISOTimestamp(): string;
+/**
+ * Validate an event name.
+ * Must match pattern: ^$?[a-zA-Z][a-zA-Z0-9_]*$
+ * Max 255 characters.
+ */
+export declare function isValidEventName(name: string): boolean;
+/**
+ * Validate an event name and throw if invalid.
+ */
+export declare function validateEventName(name: string): void;
+/**
+ * Sanitize event properties by truncating strings and limiting depth.
+ */
+export declare function sanitizeProperties(properties: EventProperties | undefined, maxDepth?: number): EventProperties | undefined;
+/**
+ * Resolve configuration with defaults.
+ */
+export declare function resolveConfiguration(config: MGMConfiguration): ResolvedConfiguration;
+/**
+ * Detect the current platform.
+ */
+export declare function detectPlatform(): Platform;
+/**
+ * Detect the device type from user agent.
+ */
+export declare function detectDeviceType(): DeviceType;
+/**
+ * Get the OS version string.
+ */
+export declare function getOSVersion(): string;
+/**
+ * Get the browser/device model.
+ */
+export declare function getDeviceModel(): string;
+/**
+ * Delay execution for a specified number of milliseconds.
+ */
+export declare function delay(ms: number): Promise<void>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/types/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,UAAU,EAEV,eAAe,EAEf,gBAAgB,EAEhB,QAAQ,EACR,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAYrC;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKtD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAkBpD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,eAAe,GAAG,SAAS,EACvC,QAAQ,GAAE,MAAuC,GAChD,eAAe,GAAG,SAAS,CAW7B;AA0DD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,qBAAqB,CAgCpF;AAeD;;GAEG;AACH,wBAAgB,cAAc,IAAI,QAAQ,CAczC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CA0B7C;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CA0BrC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAyBvC;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@mostly-good-metrics/javascript",
+  "version": "0.1.0",
+  "description": "JavaScript/TypeScript SDK for MostlyGoodMetrics - a lightweight analytics library for web applications",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "npm run build:cjs && npm run build:esm && npm run build:types",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "clean": "rm -rf dist",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "analytics",
+    "metrics",
+    "tracking",
+    "events",
+    "mostlygoodmetrics"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "prettier": "^3.2.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Mostly-Good-Metrics/mostly-good-metrics-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Mostly-Good-Metrics/mostly-good-metrics-js/issues"
+  },
+  "homepage": "https://mostlygoodmetrics.com"
+}