@pingaura/telemetry 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 PingAura AI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,124 @@
+# @pingaura/telemetry
+
+First-party, privacy-respecting analytics SDK for server and edge runtimes. It
+sends page views and custom events to the PingAura collector from your own
+infrastructure — no client-side script, no third-party cookies.
+
+- **Zero runtime dependencies.**
+- **Fire-and-forget** — tracking never blocks, alters, or fails a request.
+- **First-class entry points** for Next.js, Node/Express, and Cloudflare
+  Workers, plus a generic client for any other JavaScript or TypeScript server.
+- **ESM and CommonJS**, with bundled TypeScript types.
+
+## Install
+
+```bash
+npm install @pingaura/telemetry
+# or: pnpm add @pingaura/telemetry / yarn add @pingaura/telemetry
+```
+
+Requires Node.js 24+ (or any runtime with a global `fetch`).
+
+## Configuration
+
+Every entry point takes the same two required fields:
+
+| Field      | Description                                                   |
+| ---------- | ------------------------------------------------------------- |
+| `writeKey` | Your ingest key, e.g. from `process.env.PINGAURA_INGEST_KEY`. |
+| `domain`   | The site domain registered in PingAura, e.g. `"example.com"`. |
+
+If either is missing or empty, the SDK becomes a no-op and warns once — it never
+throws. Optional fields: `endpoint`, `timeoutMs`, `debug`, `keepalive`,
+`fetchImpl`, `onWarn`.
+
+## Usage
+
+### Next.js middleware
+
+```ts
+// middleware.ts
+import { createAnalyticsMiddleware } from '@pingaura/telemetry/next';
+import { NextResponse } from 'next/server';
+
+const track = createAnalyticsMiddleware({
+  writeKey: process.env.PINGAURA_INGEST_KEY,
+  domain: 'example.com',
+});
+
+export function middleware(req, event) {
+  track(req, event);
+  return NextResponse.next();
+}
+```
+
+### Node / Express
+
+```ts
+import { analyticsMiddleware } from '@pingaura/telemetry/node';
+
+app.use(
+  analyticsMiddleware({
+    writeKey: process.env.PINGAURA_INGEST_KEY,
+    domain: 'example.com',
+  }),
+);
+```
+
+### Cloudflare Worker
+
+```ts
+import { trackEdge } from '@pingaura/telemetry/cloudflare';
+
+export default {
+  async fetch(request, env, ctx) {
+    const response = await fetch(request);
+    trackEdge(request, response, ctx, {
+      writeKey: env.PINGAURA_INGEST_KEY,
+      domain: env.PINGAURA_DOMAIN,
+    });
+    return response;
+  },
+};
+```
+
+See [`examples/cloudflare-worker`](./examples/cloudflare-worker) for a complete,
+deployable worker.
+
+### Generic client
+
+```ts
+import { createClient } from '@pingaura/telemetry';
+
+const client = createClient({
+  writeKey: process.env.PINGAURA_INGEST_KEY,
+  domain: 'example.com',
+});
+
+await client.pageView({ url: 'https://example.com/pricing', path: '/pricing' });
+await client.track(
+  'signup_completed',
+  { plan: 'pro' },
+  { url: 'https://example.com/welcome' },
+);
+```
+
+## Event properties and PII
+
+Custom `properties` are archived verbatim. **Never put PII in them** — no emails,
+names, user IDs, or raw query strings. The collector rejects events whose values
+look like PII. Use opaque or aggregate values only.
+
+## Development
+
+```bash
+pnpm install
+pnpm test        # vitest
+pnpm typecheck   # tsc --noEmit
+pnpm lint        # eslint
+pnpm build       # tsup → dist/
+```
+
+## License
+
+[Apache-2.0](./LICENSE) © PingAura AI

package/dist/cloudflare.cjs

@@ -0,0 +1,60 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_core = require("./core-KgLaVgR4.cjs");
+const require_matchers = require("./matchers-CMwG37qc.cjs");
+//#region src/cloudflare.ts
+/** Map a Cloudflare `cf-cache-status` header to our coarse vocab. */
+function mapCacheStatus(header) {
+	if (!header) return void 0;
+	switch (header.toUpperCase()) {
+		case "HIT":
+		case "REVALIDATED": return "hit";
+		case "MISS":
+		case "EXPIRED":
+		case "STALE":
+		case "UPDATING": return "miss";
+		case "BYPASS":
+		case "DYNAMIC": return "bypass";
+		default: return;
+	}
+}
+/** True when the response is an HTML document (worth a page_view). */
+function isHtmlResponse(response) {
+	return (response.headers.get("content-type") ?? "").toLowerCase().includes("text/html");
+}
+/**
+* Fire-and-forget edge page_view. Reads only headers; never consumes the body;
+* never throws. Call from a Cloudflare Worker:
+*   const res = await fetch(request);
+*   trackEdge(request, res, ctx, { writeKey: env.PINGAURA_INGEST_KEY, domain: env.PINGAURA_DOMAIN });
+*   return res;
+*/
+function trackEdge(request, response, ctx, config) {
+	try {
+		let pathname;
+		try {
+			pathname = new URL(request.url).pathname;
+		} catch {
+			return;
+		}
+		if (!(config.shouldTrack ?? require_matchers.shouldTrackPath)(pathname) || !isHtmlResponse(response)) return;
+		const client = require_core.createClient({
+			...config,
+			keepalive: false
+		});
+		const cacheStatus = mapCacheStatus(response.headers.get("cf-cache-status"));
+		ctx.waitUntil(client.pageView({
+			url: request.url,
+			path: pathname,
+			referrer: request.headers.get("referer") ?? void 0,
+			userAgent: request.headers.get("user-agent") ?? void 0,
+			ip: request.headers.get("cf-connecting-ip") ?? void 0,
+			properties: cacheStatus ? { cache_status: cacheStatus } : void 0
+		}));
+	} catch {}
+}
+//#endregion
+exports.isHtmlResponse = isHtmlResponse;
+exports.mapCacheStatus = mapCacheStatus;
+exports.trackEdge = trackEdge;
+
+//# sourceMappingURL=cloudflare.cjs.map

package/dist/cloudflare.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.cjs","names":["shouldTrackPath","createClient"],"sources":["../src/cloudflare.ts"],"sourcesContent":["import { type ClientConfig, createClient } from './core';\nimport { shouldTrackPath } from './matchers';\n\n// Structural Cloudflare types — no @cloudflare/workers-types runtime dependency.\ninterface CfRequestLike {\n  url: string;\n  headers: { get(name: string): string | null };\n}\ninterface CfResponseLike {\n  headers: { get(name: string): string | null };\n}\ninterface CfCtxLike {\n  waitUntil(promise: Promise<unknown>): void;\n}\n\nexport type CacheStatus = 'hit' | 'miss' | 'bypass';\n\n/** Map a Cloudflare `cf-cache-status` header to our coarse vocab. */\nexport function mapCacheStatus(header: string | null): CacheStatus | undefined {\n  if (!header) return undefined;\n  switch (header.toUpperCase()) {\n    case 'HIT':\n    case 'REVALIDATED':\n      return 'hit';\n    case 'MISS':\n    case 'EXPIRED':\n    case 'STALE':\n    case 'UPDATING':\n      return 'miss';\n    case 'BYPASS':\n    case 'DYNAMIC':\n      return 'bypass';\n    default:\n      return undefined;\n  }\n}\n\n/** True when the response is an HTML document (worth a page_view). */\nexport function isHtmlResponse(response: CfResponseLike): boolean {\n  return (response.headers.get('content-type') ?? '')\n    .toLowerCase()\n    .includes('text/html');\n}\n\nexport interface EdgeConfig extends ClientConfig {\n  /** Override the default path matcher. */\n  shouldTrack?: (pathname: string) => boolean;\n}\n\n/**\n * Fire-and-forget edge page_view. Reads only headers; never consumes the body;\n * never throws. Call from a Cloudflare Worker:\n *   const res = await fetch(request);\n *   trackEdge(request, res, ctx, { writeKey: env.PINGAURA_INGEST_KEY, domain: env.PINGAURA_DOMAIN });\n *   return res;\n */\nexport function trackEdge(\n  request: CfRequestLike,\n  response: CfResponseLike,\n  ctx: CfCtxLike,\n  config: EdgeConfig,\n): void {\n  try {\n    let pathname: string;\n    try {\n      pathname = new URL(request.url).pathname;\n    } catch {\n      return; // malformed url — skip\n    }\n\n    const matcher = config.shouldTrack ?? shouldTrackPath;\n    if (!matcher(pathname) || !isHtmlResponse(response)) return;\n\n    // Workers use ctx.waitUntil for fire-and-forget — keepalive off.\n    const client = createClient({ ...config, keepalive: false });\n    const cacheStatus = mapCacheStatus(response.headers.get('cf-cache-status'));\n\n    ctx.waitUntil(\n      client.pageView({\n        url: request.url,\n        path: pathname,\n        referrer: request.headers.get('referer') ?? undefined,\n        userAgent: request.headers.get('user-agent') ?? undefined,\n        ip: request.headers.get('cf-connecting-ip') ?? undefined,\n        properties: cacheStatus ? { cache_status: cacheStatus } : undefined,\n      }),\n    );\n  } catch {\n    // never throw into the request path\n  }\n}\n"],"mappings":";;;;;AAkBA,SAAgB,eAAe,QAAgD;CAC7E,IAAI,CAAC,QAAQ,OAAO,KAAA;CACpB,QAAQ,OAAO,YAAY,GAA3B;EACE,KAAK;EACL,KAAK,eACH,OAAO;EACT,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK,YACH,OAAO;EACT,KAAK;EACL,KAAK,WACH,OAAO;EACT,SACE;CACJ;AACF;;AAGA,SAAgB,eAAe,UAAmC;CAChE,QAAQ,SAAS,QAAQ,IAAI,cAAc,KAAK,GAAA,CAC7C,YAAY,CAAC,CACb,SAAS,WAAW;AACzB;;;;;;;;AAcA,SAAgB,UACd,SACA,UACA,KACA,QACM;CACN,IAAI;EACF,IAAI;EACJ,IAAI;GACF,WAAW,IAAI,IAAI,QAAQ,GAAG,CAAC,CAAC;EAClC,QAAQ;GACN;EACF;EAGA,IAAI,EADY,OAAO,eAAeA,iBAAAA,gBAAAA,CACzB,QAAQ,KAAK,CAAC,eAAe,QAAQ,GAAG;EAGrD,MAAM,SAASC,aAAAA,aAAa;GAAE,GAAG;GAAQ,WAAW;EAAM,CAAC;EAC3D,MAAM,cAAc,eAAe,SAAS,QAAQ,IAAI,iBAAiB,CAAC;EAE1E,IAAI,UACF,OAAO,SAAS;GACd,KAAK,QAAQ;GACb,MAAM;GACN,UAAU,QAAQ,QAAQ,IAAI,SAAS,KAAK,KAAA;GAC5C,WAAW,QAAQ,QAAQ,IAAI,YAAY,KAAK,KAAA;GAChD,IAAI,QAAQ,QAAQ,IAAI,kBAAkB,KAAK,KAAA;GAC/C,YAAY,cAAc,EAAE,cAAc,YAAY,IAAI,KAAA;EAC5D,CAAC,CACH;CACF,QAAQ,CAER;AACF"}

package/dist/cloudflare.d.cts

@@ -0,0 +1,37 @@
+import { n as ClientConfig } from "./core-DVilpn_i.cjs";
+
+//#region src/cloudflare.d.ts
+interface CfRequestLike {
+  url: string;
+  headers: {
+    get(name: string): string | null;
+  };
+}
+interface CfResponseLike {
+  headers: {
+    get(name: string): string | null;
+  };
+}
+interface CfCtxLike {
+  waitUntil(promise: Promise<unknown>): void;
+}
+type CacheStatus = 'hit' | 'miss' | 'bypass';
+/** Map a Cloudflare `cf-cache-status` header to our coarse vocab. */
+declare function mapCacheStatus(header: string | null): CacheStatus | undefined;
+/** True when the response is an HTML document (worth a page_view). */
+declare function isHtmlResponse(response: CfResponseLike): boolean;
+interface EdgeConfig extends ClientConfig {
+  /** Override the default path matcher. */
+  shouldTrack?: (pathname: string) => boolean;
+}
+/**
+ * Fire-and-forget edge page_view. Reads only headers; never consumes the body;
+ * never throws. Call from a Cloudflare Worker:
+ *   const res = await fetch(request);
+ *   trackEdge(request, res, ctx, { writeKey: env.PINGAURA_INGEST_KEY, domain: env.PINGAURA_DOMAIN });
+ *   return res;
+ */
+declare function trackEdge(request: CfRequestLike, response: CfResponseLike, ctx: CfCtxLike, config: EdgeConfig): void;
+//#endregion
+export { CacheStatus, EdgeConfig, isHtmlResponse, mapCacheStatus, trackEdge };
+//# sourceMappingURL=cloudflare.d.cts.map

package/dist/cloudflare.d.mts

@@ -0,0 +1,37 @@
+import { n as ClientConfig } from "./core-DVilpn_i.mjs";
+
+//#region src/cloudflare.d.ts
+interface CfRequestLike {
+  url: string;
+  headers: {
+    get(name: string): string | null;
+  };
+}
+interface CfResponseLike {
+  headers: {
+    get(name: string): string | null;
+  };
+}
+interface CfCtxLike {
+  waitUntil(promise: Promise<unknown>): void;
+}
+type CacheStatus = 'hit' | 'miss' | 'bypass';
+/** Map a Cloudflare `cf-cache-status` header to our coarse vocab. */
+declare function mapCacheStatus(header: string | null): CacheStatus | undefined;
+/** True when the response is an HTML document (worth a page_view). */
+declare function isHtmlResponse(response: CfResponseLike): boolean;
+interface EdgeConfig extends ClientConfig {
+  /** Override the default path matcher. */
+  shouldTrack?: (pathname: string) => boolean;
+}
+/**
+ * Fire-and-forget edge page_view. Reads only headers; never consumes the body;
+ * never throws. Call from a Cloudflare Worker:
+ *   const res = await fetch(request);
+ *   trackEdge(request, res, ctx, { writeKey: env.PINGAURA_INGEST_KEY, domain: env.PINGAURA_DOMAIN });
+ *   return res;
+ */
+declare function trackEdge(request: CfRequestLike, response: CfResponseLike, ctx: CfCtxLike, config: EdgeConfig): void;
+//#endregion
+export { CacheStatus, EdgeConfig, isHtmlResponse, mapCacheStatus, trackEdge };
+//# sourceMappingURL=cloudflare.d.mts.map

package/dist/cloudflare.mjs

@@ -0,0 +1,57 @@
+import { t as createClient } from "./core-Cvg8zn6Q.mjs";
+import { t as shouldTrackPath } from "./matchers-CUD5NL5K.mjs";
+//#region src/cloudflare.ts
+/** Map a Cloudflare `cf-cache-status` header to our coarse vocab. */
+function mapCacheStatus(header) {
+	if (!header) return void 0;
+	switch (header.toUpperCase()) {
+		case "HIT":
+		case "REVALIDATED": return "hit";
+		case "MISS":
+		case "EXPIRED":
+		case "STALE":
+		case "UPDATING": return "miss";
+		case "BYPASS":
+		case "DYNAMIC": return "bypass";
+		default: return;
+	}
+}
+/** True when the response is an HTML document (worth a page_view). */
+function isHtmlResponse(response) {
+	return (response.headers.get("content-type") ?? "").toLowerCase().includes("text/html");
+}
+/**
+* Fire-and-forget edge page_view. Reads only headers; never consumes the body;
+* never throws. Call from a Cloudflare Worker:
+*   const res = await fetch(request);
+*   trackEdge(request, res, ctx, { writeKey: env.PINGAURA_INGEST_KEY, domain: env.PINGAURA_DOMAIN });
+*   return res;
+*/
+function trackEdge(request, response, ctx, config) {
+	try {
+		let pathname;
+		try {
+			pathname = new URL(request.url).pathname;
+		} catch {
+			return;
+		}
+		if (!(config.shouldTrack ?? shouldTrackPath)(pathname) || !isHtmlResponse(response)) return;
+		const client = createClient({
+			...config,
+			keepalive: false
+		});
+		const cacheStatus = mapCacheStatus(response.headers.get("cf-cache-status"));
+		ctx.waitUntil(client.pageView({
+			url: request.url,
+			path: pathname,
+			referrer: request.headers.get("referer") ?? void 0,
+			userAgent: request.headers.get("user-agent") ?? void 0,
+			ip: request.headers.get("cf-connecting-ip") ?? void 0,
+			properties: cacheStatus ? { cache_status: cacheStatus } : void 0
+		}));
+	} catch {}
+}
+//#endregion
+export { isHtmlResponse, mapCacheStatus, trackEdge };
+
+//# sourceMappingURL=cloudflare.mjs.map

package/dist/cloudflare.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.mjs","names":[],"sources":["../src/cloudflare.ts"],"sourcesContent":["import { type ClientConfig, createClient } from './core';\nimport { shouldTrackPath } from './matchers';\n\n// Structural Cloudflare types — no @cloudflare/workers-types runtime dependency.\ninterface CfRequestLike {\n  url: string;\n  headers: { get(name: string): string | null };\n}\ninterface CfResponseLike {\n  headers: { get(name: string): string | null };\n}\ninterface CfCtxLike {\n  waitUntil(promise: Promise<unknown>): void;\n}\n\nexport type CacheStatus = 'hit' | 'miss' | 'bypass';\n\n/** Map a Cloudflare `cf-cache-status` header to our coarse vocab. */\nexport function mapCacheStatus(header: string | null): CacheStatus | undefined {\n  if (!header) return undefined;\n  switch (header.toUpperCase()) {\n    case 'HIT':\n    case 'REVALIDATED':\n      return 'hit';\n    case 'MISS':\n    case 'EXPIRED':\n    case 'STALE':\n    case 'UPDATING':\n      return 'miss';\n    case 'BYPASS':\n    case 'DYNAMIC':\n      return 'bypass';\n    default:\n      return undefined;\n  }\n}\n\n/** True when the response is an HTML document (worth a page_view). */\nexport function isHtmlResponse(response: CfResponseLike): boolean {\n  return (response.headers.get('content-type') ?? '')\n    .toLowerCase()\n    .includes('text/html');\n}\n\nexport interface EdgeConfig extends ClientConfig {\n  /** Override the default path matcher. */\n  shouldTrack?: (pathname: string) => boolean;\n}\n\n/**\n * Fire-and-forget edge page_view. Reads only headers; never consumes the body;\n * never throws. Call from a Cloudflare Worker:\n *   const res = await fetch(request);\n *   trackEdge(request, res, ctx, { writeKey: env.PINGAURA_INGEST_KEY, domain: env.PINGAURA_DOMAIN });\n *   return res;\n */\nexport function trackEdge(\n  request: CfRequestLike,\n  response: CfResponseLike,\n  ctx: CfCtxLike,\n  config: EdgeConfig,\n): void {\n  try {\n    let pathname: string;\n    try {\n      pathname = new URL(request.url).pathname;\n    } catch {\n      return; // malformed url — skip\n    }\n\n    const matcher = config.shouldTrack ?? shouldTrackPath;\n    if (!matcher(pathname) || !isHtmlResponse(response)) return;\n\n    // Workers use ctx.waitUntil for fire-and-forget — keepalive off.\n    const client = createClient({ ...config, keepalive: false });\n    const cacheStatus = mapCacheStatus(response.headers.get('cf-cache-status'));\n\n    ctx.waitUntil(\n      client.pageView({\n        url: request.url,\n        path: pathname,\n        referrer: request.headers.get('referer') ?? undefined,\n        userAgent: request.headers.get('user-agent') ?? undefined,\n        ip: request.headers.get('cf-connecting-ip') ?? undefined,\n        properties: cacheStatus ? { cache_status: cacheStatus } : undefined,\n      }),\n    );\n  } catch {\n    // never throw into the request path\n  }\n}\n"],"mappings":";;;;AAkBA,SAAgB,eAAe,QAAgD;CAC7E,IAAI,CAAC,QAAQ,OAAO,KAAA;CACpB,QAAQ,OAAO,YAAY,GAA3B;EACE,KAAK;EACL,KAAK,eACH,OAAO;EACT,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK,YACH,OAAO;EACT,KAAK;EACL,KAAK,WACH,OAAO;EACT,SACE;CACJ;AACF;;AAGA,SAAgB,eAAe,UAAmC;CAChE,QAAQ,SAAS,QAAQ,IAAI,cAAc,KAAK,GAAA,CAC7C,YAAY,CAAC,CACb,SAAS,WAAW;AACzB;;;;;;;;AAcA,SAAgB,UACd,SACA,UACA,KACA,QACM;CACN,IAAI;EACF,IAAI;EACJ,IAAI;GACF,WAAW,IAAI,IAAI,QAAQ,GAAG,CAAC,CAAC;EAClC,QAAQ;GACN;EACF;EAGA,IAAI,EADY,OAAO,eAAe,gBAAA,CACzB,QAAQ,KAAK,CAAC,eAAe,QAAQ,GAAG;EAGrD,MAAM,SAAS,aAAa;GAAE,GAAG;GAAQ,WAAW;EAAM,CAAC;EAC3D,MAAM,cAAc,eAAe,SAAS,QAAQ,IAAI,iBAAiB,CAAC;EAE1E,IAAI,UACF,OAAO,SAAS;GACd,KAAK,QAAQ;GACb,MAAM;GACN,UAAU,QAAQ,QAAQ,IAAI,SAAS,KAAK,KAAA;GAC5C,WAAW,QAAQ,QAAQ,IAAI,YAAY,KAAK,KAAA;GAChD,IAAI,QAAQ,QAAQ,IAAI,kBAAkB,KAAK,KAAA;GAC/C,YAAY,cAAc,EAAE,cAAc,YAAY,IAAI,KAAA;EAC5D,CAAC,CACH;CACF,QAAQ,CAER;AACF"}

package/dist/core-Cvg8zn6Q.mjs

@@ -0,0 +1,139 @@
+//#region src/contract.ts
+const ANALYTICS_SCHEMA_VERSION = 1;
+const EVENT_TYPES = [
+	"page_view",
+	"page_leave",
+	"web_vitals",
+	"track"
+];
+/** Build a contract-valid event envelope. `now` is injectable for tests. */
+function buildEvent(input, now = () => (/* @__PURE__ */ new Date()).toISOString()) {
+	const ts = input.timestamp ?? now();
+	return {
+		event_id: globalThis.crypto.randomUUID(),
+		schema_version: 1,
+		type: input.type,
+		view_id: input.view_id,
+		timestamp: ts,
+		sent_at: now(),
+		context: input.context,
+		properties: input.properties ?? {},
+		library: input.library
+	};
+}
+//#endregion
+//#region src/core.ts
+const DEFAULT_TIMEOUT_MS = 2e3;
+const DEFAULT_ENDPOINT = "https://telemetry.pingaura.ai/v1/events";
+async function drainAndCountRejected(res) {
+	try {
+		if (typeof res.json === "function") {
+			const rejected = (await res.json())?.rejected;
+			if (Array.isArray(rejected)) return rejected.length;
+			if (typeof rejected === "number") return rejected;
+			return 0;
+		}
+	} catch {}
+	await res.body?.cancel?.().catch(() => {});
+	return 0;
+}
+function createClient(config) {
+	const fetchImpl = config.fetchImpl ?? globalThis.fetch;
+	const warn = config.onWarn ?? ((m) => console.warn(m));
+	const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const endpoint = config.endpoint ?? DEFAULT_ENDPOINT;
+	const warnedStatuses = /* @__PURE__ */ new Set();
+	if (!config.writeKey) warn("[pingaura] writeKey missing — analytics disabled");
+	if (!config.domain) warn("[pingaura] domain missing — analytics disabled");
+	async function send(event, options = {}) {
+		if (!config.writeKey || !config.domain) return;
+		const headers = {
+			"content-type": "application/json",
+			authorization: `Bearer ${config.writeKey}`
+		};
+		if (options.ip) headers["x-pa-client-ip"] = options.ip;
+		let body;
+		try {
+			body = JSON.stringify({
+				domain: config.domain,
+				events: [event]
+			});
+		} catch (err) {
+			if (config.debug) warn(`[pingaura] failed to serialize event: ${String(err)}`);
+			return;
+		}
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		try {
+			const res = await fetchImpl(endpoint, {
+				method: "POST",
+				headers,
+				body,
+				signal: controller.signal,
+				keepalive: config.keepalive ?? true
+			});
+			if (res.status < 200 || res.status >= 300) {
+				let detail = "";
+				try {
+					detail = (await res.text?.() ?? "").slice(0, 200);
+				} catch {}
+				const message = `[pingaura] ingest rejected (${res.status})${detail ? `: ${detail}` : ""}`;
+				if (res.status === 429 || res.status >= 500) {
+					if (config.debug) warn(message);
+				} else if (!warnedStatuses.has(res.status)) {
+					warnedStatuses.add(res.status);
+					warn(message);
+				}
+				return;
+			}
+			const rejected = await drainAndCountRejected(res);
+			if (rejected > 0) warn(`[pingaura] ${rejected} event(s) rejected by collector`);
+		} catch (err) {
+			if (config.debug) warn(`[pingaura] send failed: ${String(err)}`);
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+	function safeSend(input, options) {
+		let event;
+		try {
+			event = buildEvent(input);
+		} catch (err) {
+			if (config.debug) warn(`[pingaura] failed to build event: ${String(err)}`);
+			return Promise.resolve();
+		}
+		return send(event, options);
+	}
+	return {
+		send,
+		sendRaw: (input, options) => safeSend(input, options),
+		pageView: (input) => safeSend({
+			type: "page_view",
+			context: {
+				url: input.url,
+				path: input.path,
+				referrer: input.referrer,
+				title: input.title,
+				locale: input.locale,
+				user_agent: input.userAgent
+			},
+			properties: input.properties
+		}, { ip: input.ip }),
+		track: (name, properties = {}, context) => safeSend({
+			type: "track",
+			context: {
+				url: context.url,
+				path: context.path,
+				referrer: context.referrer
+			},
+			properties: {
+				...properties,
+				name
+			}
+		})
+	};
+}
+//#endregion
+export { buildEvent as i, ANALYTICS_SCHEMA_VERSION as n, EVENT_TYPES as r, createClient as t };
+
+//# sourceMappingURL=core-Cvg8zn6Q.mjs.map