@appspro-dev/sdk-js 0.1.1

package/README.md

@@ -0,0 +1,205 @@
+# @appspro/sdk-js
+
+> Zero-dependency analytics SDK for the **AppsPro** platform.  
+> Works in browsers **and** Node.js (18+).
+
+---
+
+## Installation
+
+```bash
+npm install @appspro/sdk-js
+# or
+yarn add @appspro/sdk-js
+# or
+pnpm add @appspro/sdk-js
+```
+
+## Quick Start
+
+```typescript
+import { AppsPro } from '@appspro/sdk-js';
+
+const analytics = new AppsPro({
+  apiKey: 'ws_abc123.your-secret-key',
+});
+
+// Track a custom event
+analytics.track('button_clicked', { label: 'Sign Up' });
+
+// Track a page view
+analytics.page('Home');
+
+// Identify a user
+analytics.identify('user_42', {
+  email: 'jane@example.com',
+  plan: 'pro',
+});
+```
+
+## Configuration
+
+| Option          | Type     | Default                        | Description                                   |
+| --------------- | -------- | ------------------------------ | --------------------------------------------- |
+| `apiKey`        | `string` | **(required)**                 | Your AppsPro API key                          |
+| `endpoint`      | `string` | `https://collect.appspro.io`   | Collector endpoint URL                        |
+| `flushInterval` | `number` | `10000`                        | Auto-flush interval in milliseconds           |
+| `flushSize`     | `number` | `20`                           | Number of queued events that triggers a flush |
+| `maxRetries`    | `number` | `3`                            | Max retry attempts on network failure         |
+| `workspaceId`   | `string` | Extracted from `apiKey` prefix | Override the workspace ID                     |
+
+```typescript
+const analytics = new AppsPro({
+  apiKey: 'ws_abc123.your-secret-key',
+  endpoint: 'https://your-collector.example.com',
+  flushInterval: 5000,
+  flushSize: 10,
+  maxRetries: 5,
+});
+```
+
+## API Reference
+
+### `new AppsPro(config)`
+
+Creates a new SDK instance. An anonymous ID is generated automatically.
+
+### `analytics.track(event, properties?)`
+
+Track a custom event.
+
+```typescript
+analytics.track('purchase', {
+  amount: 49.99,
+  currency: 'USD',
+  item_id: 'sku_001',
+});
+```
+
+### `analytics.identify(userId, traits?)`
+
+Identify a user and merge the anonymous session with a known user ID. Sends
+an identify call to `POST /v1/identify` immediately and sets the `user_id`
+for all subsequent events.
+
+```typescript
+analytics.identify('user_42', {
+  email: 'jane@example.com',
+  name: 'Jane Doe',
+  plan: 'pro',
+});
+```
+
+### `analytics.page(name?, properties?)`
+
+Track a page view. Automatically captures `page_url` and `referrer`.
+
+```typescript
+analytics.page('Pricing', { experiment: 'variant_b' });
+```
+
+### `analytics.setAnonymousId(id)`
+
+Override the auto-generated anonymous ID (e.g. restore from a cookie).
+
+```typescript
+analytics.setAnonymousId('anon_from_cookie_abc');
+```
+
+### `analytics.flush()`
+
+Flush all pending events to the collector immediately. Returns a `Promise`.
+
+```typescript
+await analytics.flush();
+```
+
+### `analytics.shutdown()`
+
+Stop the automatic flush timer and send remaining events. Call this when your
+application is shutting down.
+
+```typescript
+await analytics.shutdown();
+```
+
+### `analytics.reset()`
+
+Reset identity state (e.g. on user logout). Generates a new anonymous ID and
+clears the known user ID.
+
+```typescript
+analytics.reset();
+```
+
+## Server-Side Usage (Node.js)
+
+The SDK works in Node.js 18+ (which ships with global `fetch`). Browser-only
+context fields (page URL, referrer, user agent, screen size, UTM params) are
+gracefully skipped in server environments.
+
+```typescript
+import { AppsPro } from '@appspro/sdk-js';
+
+const analytics = new AppsPro({
+  apiKey: 'ws_abc123.your-secret-key',
+  endpoint: 'https://collect.appspro.io',
+});
+
+// Server-side tracking
+analytics.track('api_request', {
+  path: '/api/users',
+  method: 'GET',
+  status: 200,
+  duration_ms: 42,
+});
+
+// Important: flush before process exits
+process.on('SIGTERM', async () => {
+  await analytics.shutdown();
+  process.exit(0);
+});
+```
+
+## Event Payload
+
+Each event sent to the collector follows this shape:
+
+```jsonc
+{
+  "event_id": "550e8400-e29b-41d4-a716-446655440000",
+  "event": "button_clicked",
+  "anonymous_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
+  "user_id": "user_42", // present after identify()
+  "properties": { "label": "Sign Up" },
+  "context": {
+    "page_url": "https://example.com/pricing",
+    "referrer": "https://google.com",
+    "user_agent": "Mozilla/5.0 ...",
+    "locale": "en-US",
+    "timezone": "America/New_York",
+    "screen_width": 1920,
+    "screen_height": 1080,
+    "utm_source": "google",
+    "utm_medium": "cpc",
+  },
+  "timestamp": "2026-02-06T12:00:00.000Z",
+  "workspace_id": "ws_abc123",
+}
+```
+
+## How It Works
+
+1. **Queueing** — Events are queued in memory.
+2. **Auto-flush** — The queue flushes when it reaches `flushSize` events or
+   every `flushInterval` milliseconds, whichever comes first.
+3. **Batching** — Flushed events are sent as a single `POST /v1/events/batch`
+   request with `Authorization: Bearer <apiKey>`.
+4. **Retry** — Failed requests are retried with exponential backoff (up to
+   `maxRetries` times). Events are re-queued on failure.
+5. **Identify** — `identify()` sends to `POST /v1/identify` immediately with
+   its own retry logic.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,111 @@
+import type { AppsProConfig } from './types.js';
+/**
+ * The main AppsPro analytics client.
+ *
+ * @example
+ * ```ts
+ * import { AppsPro } from '@appspro/sdk-js';
+ *
+ * const analytics = new AppsPro({ apiKey: 'ws_abc123.secret' });
+ *
+ * analytics.track('button_clicked', { label: 'Sign Up' });
+ * analytics.page();
+ * analytics.identify('user_42', { email: 'user@example.com' });
+ * ```
+ */
+export declare class AppsPro {
+    private readonly apiKey;
+    private readonly endpoint;
+    private readonly maxRetries;
+    private readonly workspaceId;
+    private anonymousId;
+    private userId;
+    private queue;
+    /**
+     * Create a new AppsPro analytics client.
+     *
+     * @param config - SDK configuration. At minimum `apiKey` is required.
+     */
+    constructor(config: AppsProConfig);
+    /**
+     * Track a custom event.
+     *
+     * @param event      - The event name (e.g. `"button_clicked"`).
+     * @param properties - Optional key-value properties attached to the event.
+     *
+     * @example
+     * ```ts
+     * analytics.track('purchase', { amount: 49.99, currency: 'USD' });
+     * ```
+     */
+    track(event: string, properties?: Record<string, unknown>): void;
+    /**
+     * Identify a user and merge the anonymous session with a known user ID.
+     *
+     * The identify call is sent to `POST /v1/identify` immediately (with
+     * retry). Subsequent `track()` / `page()` calls will include the
+     * `user_id`.
+     *
+     * @param userId - The unique user identifier in your system.
+     * @param traits - Optional traits describing the user (email, name, etc.).
+     *
+     * @example
+     * ```ts
+     * analytics.identify('user_42', { email: 'j@example.com', plan: 'pro' });
+     * ```
+     */
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    /**
+     * Track a page view.
+     *
+     * This is sugar over {@link track} with event name `"page_view"` and
+     * automatic `page_name`, `page_url`, and `referrer` properties.
+     *
+     * @param name       - Optional human-readable page name.
+     * @param properties - Additional properties to attach.
+     *
+     * @example
+     * ```ts
+     * analytics.page('Home');
+     * analytics.page('Pricing', { experiment: 'v2' });
+     * ```
+     */
+    page(name?: string, properties?: Record<string, unknown>): void;
+    /**
+     * Override the anonymous ID.
+     *
+     * By default a random UUID is generated on construction. Use this method
+     * to restore a previously persisted anonymous ID (e.g. from a cookie).
+     *
+     * @param id - The anonymous ID to use.
+     */
+    setAnonymousId(id: string): void;
+    /**
+     * Flush all pending events to the collector immediately.
+     *
+     * @returns A promise that resolves once the flush network call completes
+     *          (or rejects if all retries are exhausted).
+     */
+    flush(): Promise<void>;
+    /**
+     * Gracefully shut down the SDK.
+     *
+     * Stops the automatic flush timer and sends any remaining queued events.
+     * After calling `shutdown()` the client should not be used again.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Reset identity state (e.g. on user logout).
+     *
+     * Generates a new anonymous ID and clears the known user ID. Pending
+     * events already in the queue are **not** affected.
+     */
+    reset(): void;
+    /** Build a {@link TrackEvent} payload. */
+    private buildEvent;
+    /** Capture the current environment context. */
+    private getContext;
+    /** Send an identify payload to POST /v1/identify with retry. */
+    private sendIdentify;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAA6C,MAAM,YAAY,CAAC;AAa3F;;;;;;;;;;;;;GAaG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IAEjD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,KAAK,CAAa;IAE1B;;;;OAIG;gBACS,MAAM,EAAE,aAAa;IAwBjC;;;;;;;;;;OAUG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAKhE;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAgBhE;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAa/D;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIhC;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAK/B;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IASb,0CAA0C;IAC1C,OAAO,CAAC,UAAU;IAqBlB,+CAA+C;IAC/C,OAAO,CAAC,UAAU;IAIlB,gEAAgE;YAClD,YAAY;CA0B3B"}

package/dist/client.js

@@ -0,0 +1,214 @@
+// ---------------------------------------------------------------------------
+// AppsPro SDK — Main Client
+// ---------------------------------------------------------------------------
+import { EventQueue } from './queue.js';
+import { captureContext } from './context.js';
+import { generateUUID, extractWorkspaceId, retryWithBackoff } from './utils.js';
+/** Default configuration values. */
+const DEFAULTS = {
+    endpoint: 'https://collect.appspro.io',
+    flushInterval: 10000,
+    flushSize: 20,
+    maxRetries: 3,
+};
+/**
+ * The main AppsPro analytics client.
+ *
+ * @example
+ * ```ts
+ * import { AppsPro } from '@appspro/sdk-js';
+ *
+ * const analytics = new AppsPro({ apiKey: 'ws_abc123.secret' });
+ *
+ * analytics.track('button_clicked', { label: 'Sign Up' });
+ * analytics.page();
+ * analytics.identify('user_42', { email: 'user@example.com' });
+ * ```
+ */
+export class AppsPro {
+    /**
+     * Create a new AppsPro analytics client.
+     *
+     * @param config - SDK configuration. At minimum `apiKey` is required.
+     */
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error('AppsPro: apiKey is required');
+        }
+        this.apiKey = config.apiKey;
+        this.endpoint = (config.endpoint ?? DEFAULTS.endpoint).replace(/\/+$/, '');
+        this.maxRetries = config.maxRetries ?? DEFAULTS.maxRetries;
+        this.workspaceId = config.workspaceId ?? extractWorkspaceId(config.apiKey);
+        this.anonymousId = generateUUID();
+        this.queue = new EventQueue({
+            endpoint: this.endpoint,
+            apiKey: this.apiKey,
+            flushSize: config.flushSize ?? DEFAULTS.flushSize,
+            flushInterval: config.flushInterval ?? DEFAULTS.flushInterval,
+            maxRetries: this.maxRetries,
+        });
+    }
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+    /**
+     * Track a custom event.
+     *
+     * @param event      - The event name (e.g. `"button_clicked"`).
+     * @param properties - Optional key-value properties attached to the event.
+     *
+     * @example
+     * ```ts
+     * analytics.track('purchase', { amount: 49.99, currency: 'USD' });
+     * ```
+     */
+    track(event, properties) {
+        const payload = this.buildEvent(event, properties);
+        this.queue.enqueue(payload);
+    }
+    /**
+     * Identify a user and merge the anonymous session with a known user ID.
+     *
+     * The identify call is sent to `POST /v1/identify` immediately (with
+     * retry). Subsequent `track()` / `page()` calls will include the
+     * `user_id`.
+     *
+     * @param userId - The unique user identifier in your system.
+     * @param traits - Optional traits describing the user (email, name, etc.).
+     *
+     * @example
+     * ```ts
+     * analytics.identify('user_42', { email: 'j@example.com', plan: 'pro' });
+     * ```
+     */
+    identify(userId, traits) {
+        this.userId = userId;
+        const payload = {
+            anonymous_id: this.anonymousId,
+            user_id: userId,
+            traits,
+            context: this.getContext(),
+            timestamp: new Date().toISOString(),
+            workspace_id: this.workspaceId,
+        };
+        // Fire-and-forget with retry
+        void this.sendIdentify(payload);
+    }
+    /**
+     * Track a page view.
+     *
+     * This is sugar over {@link track} with event name `"page_view"` and
+     * automatic `page_name`, `page_url`, and `referrer` properties.
+     *
+     * @param name       - Optional human-readable page name.
+     * @param properties - Additional properties to attach.
+     *
+     * @example
+     * ```ts
+     * analytics.page('Home');
+     * analytics.page('Pricing', { experiment: 'v2' });
+     * ```
+     */
+    page(name, properties) {
+        const ctx = this.getContext();
+        const pageProps = {
+            ...properties,
+        };
+        if (name)
+            pageProps['page_name'] = name;
+        if (ctx.page_url)
+            pageProps['page_url'] = ctx.page_url;
+        if (ctx.referrer)
+            pageProps['referrer'] = ctx.referrer;
+        this.track('page_view', pageProps);
+    }
+    /**
+     * Override the anonymous ID.
+     *
+     * By default a random UUID is generated on construction. Use this method
+     * to restore a previously persisted anonymous ID (e.g. from a cookie).
+     *
+     * @param id - The anonymous ID to use.
+     */
+    setAnonymousId(id) {
+        this.anonymousId = id;
+    }
+    /**
+     * Flush all pending events to the collector immediately.
+     *
+     * @returns A promise that resolves once the flush network call completes
+     *          (or rejects if all retries are exhausted).
+     */
+    async flush() {
+        await this.queue.flush();
+    }
+    /**
+     * Gracefully shut down the SDK.
+     *
+     * Stops the automatic flush timer and sends any remaining queued events.
+     * After calling `shutdown()` the client should not be used again.
+     */
+    async shutdown() {
+        this.queue.stopTimer();
+        await this.queue.flush();
+    }
+    /**
+     * Reset identity state (e.g. on user logout).
+     *
+     * Generates a new anonymous ID and clears the known user ID. Pending
+     * events already in the queue are **not** affected.
+     */
+    reset() {
+        this.anonymousId = generateUUID();
+        this.userId = undefined;
+    }
+    // -----------------------------------------------------------------------
+    // Internals
+    // -----------------------------------------------------------------------
+    /** Build a {@link TrackEvent} payload. */
+    buildEvent(event, properties) {
+        const payload = {
+            event_id: generateUUID(),
+            event,
+            anonymous_id: this.anonymousId,
+            properties,
+            context: this.getContext(),
+            timestamp: new Date().toISOString(),
+        };
+        if (this.userId) {
+            payload.user_id = this.userId;
+        }
+        if (this.workspaceId) {
+            payload.workspace_id = this.workspaceId;
+        }
+        return payload;
+    }
+    /** Capture the current environment context. */
+    getContext() {
+        return captureContext();
+    }
+    /** Send an identify payload to POST /v1/identify with retry. */
+    async sendIdentify(payload) {
+        const url = `${this.endpoint}/v1/identify`;
+        try {
+            await retryWithBackoff(async () => {
+                const res = await fetch(url, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Authorization: `Bearer ${this.apiKey}`,
+                    },
+                    body: JSON.stringify(payload),
+                });
+                if (!res.ok) {
+                    throw new Error(`AppsPro identify responded with ${res.status}: ${res.statusText}`);
+                }
+            }, { maxRetries: this.maxRetries });
+        }
+        catch {
+            // Silently drop after retries exhausted — analytics should never
+            // break the host application.
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/context.d.ts

@@ -0,0 +1,14 @@
+import type { EventContext } from './types.js';
+/**
+ * Capture contextual information from the current environment.
+ *
+ * **Browser** — includes page URL, referrer, user agent, locale, screen
+ * dimensions, timezone, and UTM parameters.
+ *
+ * **Node.js / SSR** — only fields available from the runtime are populated
+ * (e.g. locale, timezone).
+ *
+ * @returns An {@link EventContext} with all available fields populated.
+ */
+export declare function captureContext(): EventContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAc/C;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,IAAI,YAAY,CAgE7C"}

package/dist/context.js

@@ -0,0 +1,90 @@
+// ---------------------------------------------------------------------------
+// AppsPro SDK — Automatic Context Capture
+// ---------------------------------------------------------------------------
+import { parseUtmParams } from './utils.js';
+/**
+ * Detect whether the current runtime is a browser environment.
+ */
+function isBrowser() {
+    return (typeof window !== 'undefined' &&
+        typeof document !== 'undefined' &&
+        typeof window.location !== 'undefined');
+}
+/**
+ * Capture contextual information from the current environment.
+ *
+ * **Browser** — includes page URL, referrer, user agent, locale, screen
+ * dimensions, timezone, and UTM parameters.
+ *
+ * **Node.js / SSR** — only fields available from the runtime are populated
+ * (e.g. locale, timezone).
+ *
+ * @returns An {@link EventContext} with all available fields populated.
+ */
+export function captureContext() {
+    const ctx = {};
+    // Timezone (available in both browser & Node)
+    try {
+        ctx.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    }
+    catch {
+        // ignore
+    }
+    // Locale
+    if (typeof navigator !== 'undefined' && navigator.language) {
+        ctx.locale = navigator.language;
+    }
+    if (!isBrowser()) {
+        return ctx;
+    }
+    // --- Browser-only fields ---------------------------------------------------
+    try {
+        ctx.page_url = window.location.href;
+    }
+    catch {
+        // ignore
+    }
+    try {
+        if (document.referrer) {
+            ctx.referrer = document.referrer;
+        }
+    }
+    catch {
+        // ignore
+    }
+    try {
+        ctx.user_agent = navigator.userAgent;
+    }
+    catch {
+        // ignore
+    }
+    // Screen dimensions
+    try {
+        if (typeof screen !== 'undefined') {
+            ctx.screen_width = screen.width;
+            ctx.screen_height = screen.height;
+        }
+    }
+    catch {
+        // ignore
+    }
+    // UTM parameters from current URL
+    try {
+        const utms = parseUtmParams(window.location.href);
+        if (utms.utm_source)
+            ctx.utm_source = utms.utm_source;
+        if (utms.utm_medium)
+            ctx.utm_medium = utms.utm_medium;
+        if (utms.utm_campaign)
+            ctx.utm_campaign = utms.utm_campaign;
+        if (utms.utm_content)
+            ctx.utm_content = utms.utm_content;
+        if (utms.utm_term)
+            ctx.utm_term = utms.utm_term;
+    }
+    catch {
+        // ignore
+    }
+    return ctx;
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,0CAA0C;AAC1C,8EAA8E;AAG9E,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C;;GAEG;AACH,SAAS,SAAS;IAChB,OAAO,CACL,OAAO,MAAM,KAAK,WAAW;QAC7B,OAAO,QAAQ,KAAK,WAAW;QAC/B,OAAO,MAAM,CAAC,QAAQ,KAAK,WAAW,CACvC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,GAAG,GAAiB,EAAE,CAAC;IAE7B,8CAA8C;IAC9C,IAAI,CAAC;QACH,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC,eAAe,EAAE,CAAC,QAAQ,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,SAAS;IACX,CAAC;IAED,SAAS;IACT,IAAI,OAAO,SAAS,KAAK,WAAW,IAAI,SAAS,CAAC,QAAQ,EAAE,CAAC;QAC3D,GAAG,CAAC,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC;IAClC,CAAC;IAED,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;QACjB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,8EAA8E;IAE9E,IAAI,CAAC;QACH,GAAG,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,SAAS;IACX,CAAC;IAED,IAAI,CAAC;QACH,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;YACtB,GAAG,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;QACnC,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,SAAS;IACX,CAAC;IAED,IAAI,CAAC;QACH,GAAG,CAAC,UAAU,GAAG,SAAS,CAAC,SAAS,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,SAAS;IACX,CAAC;IAED,oBAAoB;IACpB,IAAI,CAAC;QACH,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,GAAG,CAAC,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC;YAChC,GAAG,CAAC,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC;QACpC,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,SAAS;IACX,CAAC;IAED,kCAAkC;IAClC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAClD,IAAI,IAAI,CAAC,UAAU;YAAE,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QACtD,IAAI,IAAI,CAAC,UAAU;YAAE,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QACtD,IAAI,IAAI,CAAC,YAAY;YAAE,GAAG,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QAC5D,IAAI,IAAI,CAAC,WAAW;YAAE,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACzD,IAAI,IAAI,CAAC,QAAQ;YAAE,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,SAAS;IACX,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { AppsPro } from './client.js';
+export type { AppsProConfig, EventContext, TrackEvent, BatchPayload, IdentifyPayload, } from './types.js';
+export { generateUUID, parseUtmParams } from './utils.js';
+export type { UtmParams } from './utils.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEtC,YAAY,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC1D,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+// ---------------------------------------------------------------------------
+// AppsPro SDK — Public API
+// ---------------------------------------------------------------------------
+//
+// This is the main entry point for `@appspro/sdk-js`.
+// Only symbols that are part of the public API are re-exported here.
+// ---------------------------------------------------------------------------
+export { AppsPro } from './client.js';
+export { generateUUID, parseUtmParams } from './utils.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAC9E,EAAE;AACF,sDAAsD;AACtD,qEAAqE;AACrE,8EAA8E;AAE9E,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAUtC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/queue.d.ts

@@ -0,0 +1,50 @@
+import type { TrackEvent } from './types.js';
+export interface QueueOptions {
+    /** Collector endpoint (no trailing slash). */
+    endpoint: string;
+    /** API key sent as Bearer token. */
+    apiKey: string;
+    /** Max events before an automatic flush. */
+    flushSize: number;
+    /** Interval (ms) between automatic flushes. */
+    flushInterval: number;
+    /** Max retry attempts per network request. */
+    maxRetries: number;
+}
+/**
+ * In-memory event queue that batches events and flushes them to the
+ * AppsPro collector at configurable size/time thresholds.
+ */
+export declare class EventQueue {
+    private queue;
+    private timer;
+    private flushing;
+    private readonly opts;
+    constructor(opts: QueueOptions);
+    /**
+     * Add an event to the queue.  Triggers an automatic flush when
+     * `flushSize` is reached.
+     */
+    enqueue(event: TrackEvent): void;
+    /**
+     * Flush all queued events to the collector immediately.
+     *
+     * Safe to call concurrently — concurrent flushes are serialised
+     * internally so events are never sent twice.
+     */
+    flush(): Promise<void>;
+    /**
+     * Stop the automatic flush timer. Call this during shutdown.
+     */
+    stopTimer(): void;
+    /**
+     * Returns the number of events currently queued.
+     */
+    get length(): number;
+    private startTimer;
+    /**
+     * Send a batch of events to POST /v1/events/batch with retry logic.
+     */
+    private sendBatch;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAgB,MAAM,YAAY,CAAC;AAG3D,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;gBAExB,IAAI,EAAE,YAAY;IAS9B;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAShC;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B;;OAEG;IACH,SAAS,IAAI,IAAI;IAOjB;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAMD,OAAO,CAAC,UAAU;IAalB;;OAEG;YACW,SAAS;CAsBxB"}

package/dist/queue.js

@@ -0,0 +1,105 @@
+// ---------------------------------------------------------------------------
+// AppsPro SDK — Event Queue
+// ---------------------------------------------------------------------------
+import { retryWithBackoff } from './utils.js';
+/**
+ * In-memory event queue that batches events and flushes them to the
+ * AppsPro collector at configurable size/time thresholds.
+ */
+export class EventQueue {
+    constructor(opts) {
+        this.queue = [];
+        this.timer = null;
+        this.flushing = false;
+        this.opts = opts;
+        this.startTimer();
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Add an event to the queue.  Triggers an automatic flush when
+     * `flushSize` is reached.
+     */
+    enqueue(event) {
+        this.queue.push(event);
+        if (this.queue.length >= this.opts.flushSize) {
+            // Fire-and-forget; errors are swallowed internally
+            void this.flush();
+        }
+    }
+    /**
+     * Flush all queued events to the collector immediately.
+     *
+     * Safe to call concurrently — concurrent flushes are serialised
+     * internally so events are never sent twice.
+     */
+    async flush() {
+        if (this.flushing || this.queue.length === 0)
+            return;
+        this.flushing = true;
+        // Snapshot the current queue and clear it so new events can accumulate
+        // while the network request is in flight.
+        const batch = this.queue.splice(0, this.queue.length);
+        try {
+            await this.sendBatch(batch);
+        }
+        catch {
+            // Re-enqueue events that failed to send (prepend to preserve order)
+            this.queue.unshift(...batch);
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    /**
+     * Stop the automatic flush timer. Call this during shutdown.
+     */
+    stopTimer() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * Returns the number of events currently queued.
+     */
+    get length() {
+        return this.queue.length;
+    }
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+    startTimer() {
+        if (this.opts.flushInterval > 0) {
+            this.timer = setInterval(() => {
+                void this.flush();
+            }, this.opts.flushInterval);
+            // Allow the Node.js process to exit even if the timer is active.
+            if (typeof this.timer === 'object' && 'unref' in this.timer) {
+                this.timer.unref();
+            }
+        }
+    }
+    /**
+     * Send a batch of events to POST /v1/events/batch with retry logic.
+     */
+    async sendBatch(batch) {
+        const url = `${this.opts.endpoint}/v1/events/batch`;
+        const payload = { batch };
+        await retryWithBackoff(async () => {
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.opts.apiKey}`,
+                },
+                body: JSON.stringify(payload),
+            });
+            if (!res.ok) {
+                throw new Error(`AppsPro collector responded with ${res.status}: ${res.statusText}`);
+            }
+        }, { maxRetries: this.opts.maxRetries });
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/queue.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Configuration options for the AppsPro SDK client.
+ */
+export interface AppsProConfig {
+    /** Your AppsPro API key (required). */
+    apiKey: string;
+    /**
+     * Collector endpoint URL.
+     * @default "https://collect.appspro.io"
+     */
+    endpoint?: string;
+    /**
+     * How often (in ms) the queue is automatically flushed.
+     * @default 10000
+     */
+    flushInterval?: number;
+    /**
+     * Number of events that triggers an automatic flush.
+     * @default 20
+     */
+    flushSize?: number;
+    /**
+     * Maximum number of retries for a failed network request.
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Optional workspace ID.  When omitted the SDK attempts to extract it from
+     * the apiKey prefix (everything before the first dot).
+     */
+    workspaceId?: string;
+}
+/** Context automatically captured by the SDK. */
+export interface EventContext {
+    page_url?: string;
+    referrer?: string;
+    user_agent?: string;
+    locale?: string;
+    timezone?: string;
+    screen_width?: number;
+    screen_height?: number;
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_content?: string;
+    utm_term?: string;
+    [key: string]: unknown;
+}
+/** Shape of a single event sent to the collector. */
+export interface TrackEvent {
+    event_id: string;
+    event: string;
+    anonymous_id: string;
+    user_id?: string;
+    properties?: Record<string, unknown>;
+    context: EventContext;
+    timestamp: string;
+    workspace_id?: string;
+}
+/** Payload for the /v1/events/batch endpoint. */
+export interface BatchPayload {
+    batch: TrackEvent[];
+}
+/** Payload for the /v1/identify endpoint. */
+export interface IdentifyPayload {
+    anonymous_id: string;
+    user_id: string;
+    traits?: Record<string, unknown>;
+    context: EventContext;
+    timestamp: string;
+    workspace_id?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qDAAqD;AACrD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}

package/dist/types.js

@@ -0,0 +1,5 @@
+// ---------------------------------------------------------------------------
+// AppsPro SDK — Public Types
+// ---------------------------------------------------------------------------
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,6BAA6B;AAC7B,8EAA8E"}

package/dist/utils.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Generate a RFC 4122 v4 UUID.
+ *
+ * Uses `crypto.randomUUID()` when available (modern browsers, Node >= 19).
+ * Falls back to a Math.random-based implementation for older environments.
+ */
+export declare function generateUUID(): string;
+declare const UTM_PARAMS: readonly ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term"];
+export type UtmParams = Partial<Record<(typeof UTM_PARAMS)[number], string>>;
+/**
+ * Extract UTM parameters from a URL string.
+ *
+ * @param url - Full URL or query string to parse.
+ * @returns Object containing found UTM values (keys omitted if absent).
+ */
+export declare function parseUtmParams(url: string): UtmParams;
+export interface RetryOptions {
+    /** Maximum number of retry attempts (not counting the initial try). */
+    maxRetries: number;
+    /** Base delay in ms (doubled each retry). @default 1000 */
+    baseDelay?: number;
+}
+/**
+ * Execute an async function with exponential-backoff retries.
+ *
+ * @param fn       - The async operation to attempt.
+ * @param options  - Retry configuration.
+ * @returns The resolved value of `fn`.
+ * @throws The last error if all retries are exhausted.
+ */
+export declare function retryWithBackoff<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>;
+/**
+ * Returns a promise that resolves after `ms` milliseconds.
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Attempt to extract a workspace ID from an API key.
+ *
+ * Convention: keys are formatted as `ws_<workspaceId>.<secret>`.
+ * If the key does not match this pattern, returns `undefined`.
+ */
+export declare function extractWorkspaceId(apiKey: string): string | undefined;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAYrC;AAMD,QAAA,MAAM,UAAU,kFAAmF,CAAC;AAEpG,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AAE7E;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAsBrD;AAMD,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,CAkBjG;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOrE"}

package/dist/utils.js

@@ -0,0 +1,105 @@
+// ---------------------------------------------------------------------------
+// AppsPro SDK — Utilities
+// ---------------------------------------------------------------------------
+/**
+ * Generate a RFC 4122 v4 UUID.
+ *
+ * Uses `crypto.randomUUID()` when available (modern browsers, Node >= 19).
+ * Falls back to a Math.random-based implementation for older environments.
+ */
+export function generateUUID() {
+    // Modern environments (browsers with secure context, Node >= 19)
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    // Fallback — RFC 4122 v4 compliant
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+// ---------------------------------------------------------------------------
+// UTM parameter extraction
+// ---------------------------------------------------------------------------
+const UTM_PARAMS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term'];
+/**
+ * Extract UTM parameters from a URL string.
+ *
+ * @param url - Full URL or query string to parse.
+ * @returns Object containing found UTM values (keys omitted if absent).
+ */
+export function parseUtmParams(url) {
+    const params = {};
+    try {
+        const searchString = url.includes('?') ? (url.split('?')[1] ?? '') : '';
+        if (!searchString)
+            return params;
+        const pairs = searchString.split('#')[0]?.split('&') ?? [];
+        for (const pair of pairs) {
+            const eqIdx = pair.indexOf('=');
+            if (eqIdx === -1)
+                continue;
+            const key = decodeURIComponent(pair.slice(0, eqIdx));
+            const val = decodeURIComponent(pair.slice(eqIdx + 1));
+            if (UTM_PARAMS.includes(key)) {
+                params[key] = val;
+            }
+        }
+    }
+    catch {
+        // Swallow malformed URLs silently
+    }
+    return params;
+}
+/**
+ * Execute an async function with exponential-backoff retries.
+ *
+ * @param fn       - The async operation to attempt.
+ * @param options  - Retry configuration.
+ * @returns The resolved value of `fn`.
+ * @throws The last error if all retries are exhausted.
+ */
+export async function retryWithBackoff(fn, options) {
+    const { maxRetries, baseDelay = 1000 } = options;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt < maxRetries) {
+                const jitter = Math.random() * 0.3 + 0.85; // 0.85 – 1.15
+                const delay = baseDelay * Math.pow(2, attempt) * jitter;
+                await sleep(delay);
+            }
+        }
+    }
+    throw lastError;
+}
+/**
+ * Returns a promise that resolves after `ms` milliseconds.
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ---------------------------------------------------------------------------
+// Workspace ID extraction
+// ---------------------------------------------------------------------------
+/**
+ * Attempt to extract a workspace ID from an API key.
+ *
+ * Convention: keys are formatted as `ws_<workspaceId>.<secret>`.
+ * If the key does not match this pattern, returns `undefined`.
+ */
+export function extractWorkspaceId(apiKey) {
+    if (!apiKey)
+        return undefined;
+    const dotIndex = apiKey.indexOf('.');
+    if (dotIndex > 0) {
+        return apiKey.slice(0, dotIndex);
+    }
+    return undefined;
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

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

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@appspro-dev/sdk-js",
+  "version": "0.1.1",
+  "description": "AppsPro Analytics SDK for browser and Node.js — zero dependencies",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/appspro-dev/apps-pro.git",
+    "directory": "packages/sdk-js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit --pretty"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "analytics",
+    "tracking",
+    "appspro",
+    "events",
+    "sdk"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}