pgp-sdk 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# pgp-sdk (TypeScript)
+
+Isomorphic (Node.js + browser) event ingestion SDK for the PGP platform.
+
+## Install
+
+Copy/`npm pack` from this directory (internal package, not on npm).
+
+## Node.js
+
+```ts
+import { PgpClient } from "pgp-sdk";
+
+const pgp = new PgpClient({ apiKey: "pgp_...", baseUrl: "https://pgp.int.wepromotion.cn" });
+
+pgp.capture("signup", { plan: "free" });
+pgp.setUserId("user-123");
+pgp.capture("purchase", { amount: 99 });
+
+await pgp.close(); // flush on shutdown
+```
+
+## Browser
+
+```html
+<script type="module">
+  import { PgpClient } from "./node_modules/pgp-sdk/dist/index.js";
+  const pgp = new PgpClient({ apiKey: "pgp_..." });
+  pgp.capture("page_view");
+</script>
+```
+
+With no `userId`, an anonymous id is generated and persisted in `localStorage`.
+Queued events are flushed with `keepalive` on `pagehide`, so nothing is lost on navigation.
+
+## Behavior
+
+- Events queue in memory, flush at `flushAt` (default 20) events, every `flushInterval` ms (default 5000), or on `flush()`/`close()`.
+- Failed requests re-queue (events are never dropped on network errors) and retry on the next flush.
+- Concurrent `flush()` calls coalesce into one request.
+
+## Options
+
+| Option | Default | Description |
+|---|---|---|
+| `apiKey` | — | required, from `POST /api/projects` |
+| `baseUrl` | `https://pgp.int.wepromotion.cn` | server base URL |
+| `userId` | anonymous id | `user_id` sent with each event |
+| `flushAt` | `20` | queue size that triggers a flush |
+| `flushInterval` | `5000` | ms between flushes |
+| `fetchFn` | global `fetch` | injectable for tests |
+
+## Dev
+
+```bash
+npm test        # node:test, no server needed
+npm run build   # dist/ ESM + CJS + types
+```

package/dist/index.cjs

@@ -0,0 +1,134 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PgpClient: () => PgpClient,
+  createClient: () => createClient,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var ANON_KEY = "pgp_anon_id";
+function uuid() {
+  return typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID() : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+function anonId() {
+  try {
+    let id = localStorage.getItem(ANON_KEY);
+    if (!id) {
+      id = uuid();
+      localStorage.setItem(ANON_KEY, id);
+    }
+    return id;
+  } catch {
+    return uuid();
+  }
+}
+var PgpClient = class {
+  #opts;
+  #fetch;
+  #queue = [];
+  #flushing = Promise.resolve();
+  #userId;
+  #timer;
+  #onHide;
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("pgp: apiKey is required");
+    this.#opts = {
+      apiKey: opts.apiKey,
+      baseUrl: (opts.baseUrl ?? "https://pgp.int.wepromotion.cn").replace(/\/$/, ""),
+      flushAt: opts.flushAt ?? 20,
+      flushInterval: opts.flushInterval ?? 5e3
+    };
+    this.#fetch = opts.fetchFn ?? fetch.bind(globalThis);
+    this.#userId = opts.userId ?? anonId();
+    if (typeof document !== "undefined") {
+      this.#onHide = () => {
+        if (this.#queue.length) void this.#flush(true);
+      };
+      document.addEventListener("visibilitychange", this.#onHide);
+      window.addEventListener("pagehide", this.#onHide);
+    }
+  }
+  /** Track the logged-in user (switches future events to this id). */
+  setUserId(userId) {
+    this.#userId = userId;
+  }
+  /** Queue an event. Flushing happens automatically. */
+  capture(name, properties) {
+    if (!this.#userId) {
+      console.error(`pgp: dropping event "${name}" \u2014 no user id`);
+      return;
+    }
+    this.#queue.push({ user_id: this.#userId, name, properties });
+    if (!this.#timer) {
+      this.#timer = setInterval(() => void this.flush(), this.#opts.flushInterval);
+      this.#timer.unref?.();
+    }
+    if (this.#queue.length >= this.#opts.flushAt) void this.flush();
+  }
+  /** Flush now. Concurrent calls share one request. Never throws. */
+  flush() {
+    return this.#flushing = this.#flushing.then(() => this.#flush(false));
+  }
+  /** Flush and stop timers/listeners. Call on shutdown. */
+  async close() {
+    if (this.#timer) clearInterval(this.#timer);
+    if (this.#onHide) {
+      document.removeEventListener("visibilitychange", this.#onHide);
+      window.removeEventListener("pagehide", this.#onHide);
+    }
+    await this.flush();
+  }
+  async #flush(keepalive) {
+    if (!this.#queue.length) return;
+    const events = this.#queue;
+    this.#queue = [];
+    try {
+      const res = await this.#fetch(`${this.#opts.baseUrl}/api/events/batch`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.#opts.apiKey}`
+        },
+        body: JSON.stringify({ events }),
+        keepalive
+        // lets the request survive page unload
+      });
+      if (!res.ok) throw new Error(`pgp: flush failed with HTTP ${res.status}`);
+      if (!this.#queue.length && this.#timer) {
+        clearInterval(this.#timer);
+        this.#timer = void 0;
+      }
+    } catch (err) {
+      this.#queue = events.concat(this.#queue);
+      console.error(err instanceof Error ? err.message : err);
+    }
+  }
+};
+function createClient(opts) {
+  return new PgpClient(opts);
+}
+var index_default = { createClient, PgpClient };
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PgpClient,
+  createClient
+});

package/dist/index.d.cts

@@ -0,0 +1,39 @@
+/**
+ * pgp-sdk — isomorphic (Node.js + browser) event ingestion SDK for the PGP platform.
+ *
+ * Batches events, flushes on `flushAt` events / `flushInterval` ms / manual `flush()`.
+ * Failed flushes are re-queued. Browsers flush with `keepalive` on pagehide.
+ */
+interface PgpOptions {
+    /** API key from POST /api/projects */
+    apiKey: string;
+    /** Server base URL, e.g. https://pgp.int.wepromotion.cn */
+    baseUrl?: string;
+    /** Known user id; falls back to a persisted anonymous id */
+    userId?: string;
+    /** Flush when this many events are queued (default 20) */
+    flushAt?: number;
+    /** Flush at least every N ms (default 5000) */
+    flushInterval?: number;
+    /** Injectable fetch, mainly for tests */
+    fetchFn?: typeof fetch;
+}
+declare class PgpClient {
+    #private;
+    constructor(opts: PgpOptions);
+    /** Track the logged-in user (switches future events to this id). */
+    setUserId(userId: string): void;
+    /** Queue an event. Flushing happens automatically. */
+    capture(name: string, properties?: Record<string, unknown>): void;
+    /** Flush now. Concurrent calls share one request. Never throws. */
+    flush(): Promise<void>;
+    /** Flush and stop timers/listeners. Call on shutdown. */
+    close(): Promise<void>;
+}
+declare function createClient(opts: PgpOptions): PgpClient;
+declare const _default: {
+    createClient: typeof createClient;
+    PgpClient: typeof PgpClient;
+};
+
+export { PgpClient, type PgpOptions, createClient, _default as default };

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * pgp-sdk — isomorphic (Node.js + browser) event ingestion SDK for the PGP platform.
+ *
+ * Batches events, flushes on `flushAt` events / `flushInterval` ms / manual `flush()`.
+ * Failed flushes are re-queued. Browsers flush with `keepalive` on pagehide.
+ */
+interface PgpOptions {
+    /** API key from POST /api/projects */
+    apiKey: string;
+    /** Server base URL, e.g. https://pgp.int.wepromotion.cn */
+    baseUrl?: string;
+    /** Known user id; falls back to a persisted anonymous id */
+    userId?: string;
+    /** Flush when this many events are queued (default 20) */
+    flushAt?: number;
+    /** Flush at least every N ms (default 5000) */
+    flushInterval?: number;
+    /** Injectable fetch, mainly for tests */
+    fetchFn?: typeof fetch;
+}
+declare class PgpClient {
+    #private;
+    constructor(opts: PgpOptions);
+    /** Track the logged-in user (switches future events to this id). */
+    setUserId(userId: string): void;
+    /** Queue an event. Flushing happens automatically. */
+    capture(name: string, properties?: Record<string, unknown>): void;
+    /** Flush now. Concurrent calls share one request. Never throws. */
+    flush(): Promise<void>;
+    /** Flush and stop timers/listeners. Call on shutdown. */
+    close(): Promise<void>;
+}
+declare function createClient(opts: PgpOptions): PgpClient;
+declare const _default: {
+    createClient: typeof createClient;
+    PgpClient: typeof PgpClient;
+};
+
+export { PgpClient, type PgpOptions, createClient, _default as default };

package/dist/index.js

@@ -0,0 +1,108 @@
+// src/index.ts
+var ANON_KEY = "pgp_anon_id";
+function uuid() {
+  return typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID() : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+function anonId() {
+  try {
+    let id = localStorage.getItem(ANON_KEY);
+    if (!id) {
+      id = uuid();
+      localStorage.setItem(ANON_KEY, id);
+    }
+    return id;
+  } catch {
+    return uuid();
+  }
+}
+var PgpClient = class {
+  #opts;
+  #fetch;
+  #queue = [];
+  #flushing = Promise.resolve();
+  #userId;
+  #timer;
+  #onHide;
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("pgp: apiKey is required");
+    this.#opts = {
+      apiKey: opts.apiKey,
+      baseUrl: (opts.baseUrl ?? "https://pgp.int.wepromotion.cn").replace(/\/$/, ""),
+      flushAt: opts.flushAt ?? 20,
+      flushInterval: opts.flushInterval ?? 5e3
+    };
+    this.#fetch = opts.fetchFn ?? fetch.bind(globalThis);
+    this.#userId = opts.userId ?? anonId();
+    if (typeof document !== "undefined") {
+      this.#onHide = () => {
+        if (this.#queue.length) void this.#flush(true);
+      };
+      document.addEventListener("visibilitychange", this.#onHide);
+      window.addEventListener("pagehide", this.#onHide);
+    }
+  }
+  /** Track the logged-in user (switches future events to this id). */
+  setUserId(userId) {
+    this.#userId = userId;
+  }
+  /** Queue an event. Flushing happens automatically. */
+  capture(name, properties) {
+    if (!this.#userId) {
+      console.error(`pgp: dropping event "${name}" \u2014 no user id`);
+      return;
+    }
+    this.#queue.push({ user_id: this.#userId, name, properties });
+    if (!this.#timer) {
+      this.#timer = setInterval(() => void this.flush(), this.#opts.flushInterval);
+      this.#timer.unref?.();
+    }
+    if (this.#queue.length >= this.#opts.flushAt) void this.flush();
+  }
+  /** Flush now. Concurrent calls share one request. Never throws. */
+  flush() {
+    return this.#flushing = this.#flushing.then(() => this.#flush(false));
+  }
+  /** Flush and stop timers/listeners. Call on shutdown. */
+  async close() {
+    if (this.#timer) clearInterval(this.#timer);
+    if (this.#onHide) {
+      document.removeEventListener("visibilitychange", this.#onHide);
+      window.removeEventListener("pagehide", this.#onHide);
+    }
+    await this.flush();
+  }
+  async #flush(keepalive) {
+    if (!this.#queue.length) return;
+    const events = this.#queue;
+    this.#queue = [];
+    try {
+      const res = await this.#fetch(`${this.#opts.baseUrl}/api/events/batch`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.#opts.apiKey}`
+        },
+        body: JSON.stringify({ events }),
+        keepalive
+        // lets the request survive page unload
+      });
+      if (!res.ok) throw new Error(`pgp: flush failed with HTTP ${res.status}`);
+      if (!this.#queue.length && this.#timer) {
+        clearInterval(this.#timer);
+        this.#timer = void 0;
+      }
+    } catch (err) {
+      this.#queue = events.concat(this.#queue);
+      console.error(err instanceof Error ? err.message : err);
+    }
+  }
+};
+function createClient(opts) {
+  return new PgpClient(opts);
+}
+var index_default = { createClient, PgpClient };
+export {
+  PgpClient,
+  createClient,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "pgp-sdk",
+  "version": "0.1.0",
+  "description": "Isomorphic (Node.js + browser) event ingestion SDK for the PGP platform",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "node --test 'test/*.test.ts'",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "keywords": ["analytics", "events", "pgp"],
+  "license": "MIT",
+  "repository": { "type": "git", "url": "github:dev-artist-cn/pgp" },
+  "author": "Wei",
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}