@appmachina/node 0.0.1 → 2.2.0

package/dist/nextjs.d.ts

@@ -0,0 +1,59 @@
+import "./persistence-ChBsyTkr.js";
+import { o as AppMachinaNode } from "./express-D5w2Pl15.js";
+
+//#region src/nextjs.d.ts
+interface RequestContext {
+  distinctId: string;
+  properties: Record<string, unknown>;
+}
+/**
+ * Extract attribution parameters from a URL string.
+ *
+ * Parses the query string and returns any recognized click ID or UTM
+ * parameters, prefixed with `$url_` to avoid collisions with user properties.
+ */
+declare function extractUrlParamsFromUrl(url: string): Record<string, string>;
+/**
+ * Run a callback with a AppMachina request context.
+ * Inside the callback, `getAppMachinaContext()` returns the context.
+ *
+ * Usage in Next.js middleware or API routes:
+ *   withAppMachinaContext({ distinctId: userId }, async () => {
+ *     // ... handler code
+ *     sdk.track(getAppMachinaContext()!.distinctId, 'page_view', { path });
+ *   });
+ */
+declare function withAppMachinaContext<T>(context: RequestContext, fn: () => T): T;
+/**
+ * Create a AppMachina request context from a Next.js request URL, automatically
+ * extracting attribution URL parameters and merging them into the context
+ * properties.
+ *
+ * Usage:
+ *   withAppMachinaRequestContext({ distinctId: userId, url: req.url }, async () => {
+ *     trackServerPageView(sdk, '/dashboard');
+ *   });
+ */
+declare function withAppMachinaRequestContext<T>(options: {
+  distinctId: string;
+  url?: string;
+  properties?: Record<string, unknown>;
+}, fn: () => T): T;
+/**
+ * Get the current AppMachina request context (set by withAppMachinaContext).
+ * Returns undefined if called outside a context.
+ */
+declare function getAppMachinaContext(): RequestContext | undefined;
+/**
+ * Track a server-side page view in Next.js.
+ * Resolves the distinctId from the current AsyncLocalStorage context
+ * or falls back to the provided distinctId.
+ */
+declare function trackServerPageView(sdk: AppMachinaNode, path: string, distinctId?: string): void;
+/**
+ * Track a Next.js Server Action invocation.
+ */
+declare function trackServerAction(sdk: AppMachinaNode, actionName: string, properties?: Record<string, unknown>, distinctId?: string): void;
+//#endregion
+export { RequestContext, extractUrlParamsFromUrl, getAppMachinaContext, trackServerAction, trackServerPageView, withAppMachinaContext, withAppMachinaRequestContext };
+//# sourceMappingURL=nextjs.d.ts.map

package/dist/nextjs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nextjs.d.ts","names":[],"sources":["../src/nextjs.ts"],"sourcesContent":[],"mappings":";;;;UAkBiB,cAAA;;cAEH;AAFd;AAaA;AA+BA;;;;;AAcgB,iBA7CA,uBAAA,CA6C4B,GAAA,EAAA,MAAA,CAAA,EA7CU,MA6CV,CAAA,MAAA,EAAA,MAAA,CAAA;;;;;AAgB5C;AASA;AAcA;;;;iBArDgB,kCAAkC,0BAA0B,IAAI;;;;;;;;;;;iBAchE;;;eAC4C;aAChD,IACT;;;;;iBAaa,oBAAA,CAAA,GAAwB;;;;;;iBASxB,mBAAA,MAAyB;;;;iBAczB,iBAAA,MACT,iDAEQ"}

package/dist/nextjs.js

@@ -0,0 +1,112 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+//#region src/nextjs.ts
+/** Attribution URL parameters captured from Next.js request URLs. */
+const CLICK_ID_PARAMS = [
+	"fbclid",
+	"gclid",
+	"gbraid",
+	"wbraid",
+	"ttclid",
+	"msclkid",
+	"rclid"
+];
+const UTM_PARAMS = [
+	"utm_source",
+	"utm_medium",
+	"utm_campaign",
+	"utm_content",
+	"utm_term"
+];
+const ALL_ATTRIBUTION_PARAMS = [...CLICK_ID_PARAMS, ...UTM_PARAMS];
+const storage = new AsyncLocalStorage();
+/**
+* Extract attribution parameters from a URL string.
+*
+* Parses the query string and returns any recognized click ID or UTM
+* parameters, prefixed with `$url_` to avoid collisions with user properties.
+*/
+function extractUrlParamsFromUrl(url) {
+	const params = {};
+	try {
+		const queryStart = url.indexOf("?");
+		if (queryStart === -1) return params;
+		const searchParams = new URLSearchParams(url.slice(queryStart));
+		for (const param of ALL_ATTRIBUTION_PARAMS) {
+			const value = searchParams.get(param);
+			if (value) params[`$url_${param}`] = value;
+		}
+	} catch {}
+	return params;
+}
+/**
+* Run a callback with a AppMachina request context.
+* Inside the callback, `getAppMachinaContext()` returns the context.
+*
+* Usage in Next.js middleware or API routes:
+*   withAppMachinaContext({ distinctId: userId }, async () => {
+*     // ... handler code
+*     sdk.track(getAppMachinaContext()!.distinctId, 'page_view', { path });
+*   });
+*/
+function withAppMachinaContext(context, fn) {
+	return storage.run(context, fn);
+}
+/**
+* Create a AppMachina request context from a Next.js request URL, automatically
+* extracting attribution URL parameters and merging them into the context
+* properties.
+*
+* Usage:
+*   withAppMachinaRequestContext({ distinctId: userId, url: req.url }, async () => {
+*     trackServerPageView(sdk, '/dashboard');
+*   });
+*/
+function withAppMachinaRequestContext(options, fn) {
+	const urlParams = options.url ? extractUrlParamsFromUrl(options.url) : {};
+	const context = {
+		distinctId: options.distinctId,
+		properties: {
+			...urlParams,
+			...options.properties
+		}
+	};
+	return storage.run(context, fn);
+}
+/**
+* Get the current AppMachina request context (set by withAppMachinaContext).
+* Returns undefined if called outside a context.
+*/
+function getAppMachinaContext() {
+	return storage.getStore();
+}
+/**
+* Track a server-side page view in Next.js.
+* Resolves the distinctId from the current AsyncLocalStorage context
+* or falls back to the provided distinctId.
+*/
+function trackServerPageView(sdk, path, distinctId) {
+	const ctx = getAppMachinaContext();
+	const resolvedId = distinctId ?? ctx?.distinctId ?? "anonymous";
+	sdk.track(resolvedId, "page_view", {
+		path,
+		...ctx?.properties,
+		server_rendered: true
+	});
+}
+/**
+* Track a Next.js Server Action invocation.
+*/
+function trackServerAction(sdk, actionName, properties, distinctId) {
+	const ctx = getAppMachinaContext();
+	const resolvedId = distinctId ?? ctx?.distinctId ?? "anonymous";
+	sdk.track(resolvedId, "server_action", {
+		action_name: actionName,
+		...properties,
+		...ctx?.properties
+	});
+}
+
+//#endregion
+export { extractUrlParamsFromUrl, getAppMachinaContext, trackServerAction, trackServerPageView, withAppMachinaContext, withAppMachinaRequestContext };
+//# sourceMappingURL=nextjs.js.map

package/dist/nextjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nextjs.js","names":["params: Record<string, string>","context: RequestContext"],"sources":["../src/nextjs.ts"],"sourcesContent":["// @appmachina/node/nextjs — Next.js integration with AsyncLocalStorage for request context.\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\nimport type { AppMachinaNode } from './index.js';\n\n/** Attribution URL parameters captured from Next.js request URLs. */\nconst CLICK_ID_PARAMS = [\n  'fbclid',\n  'gclid',\n  'gbraid',\n  'wbraid',\n  'ttclid',\n  'msclkid',\n  'rclid'\n] as const;\nconst UTM_PARAMS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term'] as const;\nconst ALL_ATTRIBUTION_PARAMS = [...CLICK_ID_PARAMS, ...UTM_PARAMS] as const;\n\nexport interface RequestContext {\n  distinctId: string;\n  properties: Record<string, unknown>;\n}\n\nconst storage = new AsyncLocalStorage<RequestContext>();\n\n/**\n * Extract attribution parameters from a URL string.\n *\n * Parses the query string and returns any recognized click ID or UTM\n * parameters, prefixed with `$url_` to avoid collisions with user properties.\n */\nexport function extractUrlParamsFromUrl(url: string): Record<string, string> {\n  const params: Record<string, string> = {};\n\n  try {\n    const queryStart = url.indexOf('?');\n    if (queryStart === -1) return params;\n\n    const searchParams = new URLSearchParams(url.slice(queryStart));\n    for (const param of ALL_ATTRIBUTION_PARAMS) {\n      const value = searchParams.get(param);\n      if (value) {\n        params[`$url_${param}`] = value;\n      }\n    }\n  } catch {\n    // URL parsing failed — return empty\n  }\n\n  return params;\n}\n\n/**\n * Run a callback with a AppMachina request context.\n * Inside the callback, `getAppMachinaContext()` returns the context.\n *\n * Usage in Next.js middleware or API routes:\n *   withAppMachinaContext({ distinctId: userId }, async () => {\n *     // ... handler code\n *     sdk.track(getAppMachinaContext()!.distinctId, 'page_view', { path });\n *   });\n */\nexport function withAppMachinaContext<T>(context: RequestContext, fn: () => T): T {\n  return storage.run(context, fn);\n}\n\n/**\n * Create a AppMachina request context from a Next.js request URL, automatically\n * extracting attribution URL parameters and merging them into the context\n * properties.\n *\n * Usage:\n *   withAppMachinaRequestContext({ distinctId: userId, url: req.url }, async () => {\n *     trackServerPageView(sdk, '/dashboard');\n *   });\n */\nexport function withAppMachinaRequestContext<T>(\n  options: { distinctId: string; url?: string; properties?: Record<string, unknown> },\n  fn: () => T\n): T {\n  const urlParams = options.url ? extractUrlParamsFromUrl(options.url) : {};\n  const context: RequestContext = {\n    distinctId: options.distinctId,\n    properties: { ...urlParams, ...options.properties }\n  };\n  return storage.run(context, fn);\n}\n\n/**\n * Get the current AppMachina request context (set by withAppMachinaContext).\n * Returns undefined if called outside a context.\n */\nexport function getAppMachinaContext(): RequestContext | undefined {\n  return storage.getStore();\n}\n\n/**\n * Track a server-side page view in Next.js.\n * Resolves the distinctId from the current AsyncLocalStorage context\n * or falls back to the provided distinctId.\n */\nexport function trackServerPageView(sdk: AppMachinaNode, path: string, distinctId?: string): void {\n  const ctx = getAppMachinaContext();\n  const resolvedId = distinctId ?? ctx?.distinctId ?? 'anonymous';\n\n  sdk.track(resolvedId, 'page_view', {\n    path,\n    ...ctx?.properties,\n    server_rendered: true\n  });\n}\n\n/**\n * Track a Next.js Server Action invocation.\n */\nexport function trackServerAction(\n  sdk: AppMachinaNode,\n  actionName: string,\n  properties?: Record<string, unknown>,\n  distinctId?: string\n): void {\n  const ctx = getAppMachinaContext();\n  const resolvedId = distinctId ?? ctx?.distinctId ?? 'anonymous';\n\n  sdk.track(resolvedId, 'server_action', {\n    action_name: actionName,\n    ...properties,\n    ...ctx?.properties\n  });\n}\n"],"mappings":";;;;AAMA,MAAM,kBAAkB;CACtB;CACA;CACA;CACA;CACA;CACA;CACA;CACD;AACD,MAAM,aAAa;CAAC;CAAc;CAAc;CAAgB;CAAe;CAAW;AAC1F,MAAM,yBAAyB,CAAC,GAAG,iBAAiB,GAAG,WAAW;AAOlE,MAAM,UAAU,IAAI,mBAAmC;;;;;;;AAQvD,SAAgB,wBAAwB,KAAqC;CAC3E,MAAMA,SAAiC,EAAE;AAEzC,KAAI;EACF,MAAM,aAAa,IAAI,QAAQ,IAAI;AACnC,MAAI,eAAe,GAAI,QAAO;EAE9B,MAAM,eAAe,IAAI,gBAAgB,IAAI,MAAM,WAAW,CAAC;AAC/D,OAAK,MAAM,SAAS,wBAAwB;GAC1C,MAAM,QAAQ,aAAa,IAAI,MAAM;AACrC,OAAI,MACF,QAAO,QAAQ,WAAW;;SAGxB;AAIR,QAAO;;;;;;;;;;;;AAaT,SAAgB,sBAAyB,SAAyB,IAAgB;AAChF,QAAO,QAAQ,IAAI,SAAS,GAAG;;;;;;;;;;;;AAajC,SAAgB,6BACd,SACA,IACG;CACH,MAAM,YAAY,QAAQ,MAAM,wBAAwB,QAAQ,IAAI,GAAG,EAAE;CACzE,MAAMC,UAA0B;EAC9B,YAAY,QAAQ;EACpB,YAAY;GAAE,GAAG;GAAW,GAAG,QAAQ;GAAY;EACpD;AACD,QAAO,QAAQ,IAAI,SAAS,GAAG;;;;;;AAOjC,SAAgB,uBAAmD;AACjE,QAAO,QAAQ,UAAU;;;;;;;AAQ3B,SAAgB,oBAAoB,KAAqB,MAAc,YAA2B;CAChG,MAAM,MAAM,sBAAsB;CAClC,MAAM,aAAa,cAAc,KAAK,cAAc;AAEpD,KAAI,MAAM,YAAY,aAAa;EACjC;EACA,GAAG,KAAK;EACR,iBAAiB;EAClB,CAAC;;;;;AAMJ,SAAgB,kBACd,KACA,YACA,YACA,YACM;CACN,MAAM,MAAM,sBAAsB;CAClC,MAAM,aAAa,cAAc,KAAK,cAAc;AAEpD,KAAI,MAAM,YAAY,iBAAiB;EACrC,aAAa;EACb,GAAG;EACH,GAAG,KAAK;EACT,CAAC"}

package/dist/persistence-ChBsyTkr.d.ts

@@ -0,0 +1,22 @@
+import { PersistenceBackend } from "@appmachina/core-wasm";
+
+//#region src/persistence.d.ts
+
+/**
+ * File-system-backed persistence for Node.js environments.
+ *
+ * Stores each key as a separate file in a directory scoped by appId.
+ * Uses synchronous fs APIs so writes are guaranteed before the call returns
+ * (important for SIGTERM / graceful-shutdown scenarios).
+ */
+declare class FilePersistence implements PersistenceBackend {
+  private readonly dir;
+  constructor(appId: string, baseDir?: string);
+  write(key: string, data: Uint8Array): void;
+  read(key: string): Uint8Array | null;
+  delete(key: string): void;
+  listKeys(prefix: string): string[];
+}
+//#endregion
+export { FilePersistence as t };
+//# sourceMappingURL=persistence-ChBsyTkr.d.ts.map

package/dist/persistence-ChBsyTkr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-ChBsyTkr.d.ts","names":[],"sources":["../src/persistence.ts"],"sourcesContent":[],"mappings":";;;;;;AAoBA;;;;;cAAa,eAAA,YAA2B;;;2BAUb;qBAKN"}

package/dist/persistence-D_zFNklE.js

@@ -0,0 +1,47 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+//#region src/persistence.ts
+/**
+* File-system-backed persistence for Node.js environments.
+*
+* Stores each key as a separate file in a directory scoped by appId.
+* Uses synchronous fs APIs so writes are guaranteed before the call returns
+* (important for SIGTERM / graceful-shutdown scenarios).
+*/
+var FilePersistence = class {
+	dir;
+	constructor(appId, baseDir) {
+		this.dir = join(baseDir ?? tmpdir(), "appmachina-sdk", appId);
+		if (!existsSync(this.dir)) mkdirSync(this.dir, { recursive: true });
+	}
+	write(key, data) {
+		writeFileSync(join(this.dir, encodeURIComponent(key)), Buffer.from(data));
+	}
+	read(key) {
+		const path = join(this.dir, encodeURIComponent(key));
+		try {
+			return new Uint8Array(readFileSync(path));
+		} catch {
+			return null;
+		}
+	}
+	delete(key) {
+		const path = join(this.dir, encodeURIComponent(key));
+		try {
+			unlinkSync(path);
+		} catch {}
+	}
+	listKeys(prefix) {
+		try {
+			return readdirSync(this.dir).map((f) => decodeURIComponent(f)).filter((k) => k.startsWith(prefix));
+		} catch {
+			return [];
+		}
+	}
+};
+
+//#endregion
+export { FilePersistence as t };
+//# sourceMappingURL=persistence-D_zFNklE.js.map

package/dist/persistence-D_zFNklE.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-D_zFNklE.js","names":[],"sources":["../src/persistence.ts"],"sourcesContent":["import {\n  existsSync,\n  mkdirSync,\n  readFileSync,\n  readdirSync,\n  unlinkSync,\n  writeFileSync\n} from 'node:fs';\nimport { tmpdir } from 'node:os';\nimport { join } from 'node:path';\n\nimport type { PersistenceBackend } from '@appmachina/core-wasm';\n\n/**\n * File-system-backed persistence for Node.js environments.\n *\n * Stores each key as a separate file in a directory scoped by appId.\n * Uses synchronous fs APIs so writes are guaranteed before the call returns\n * (important for SIGTERM / graceful-shutdown scenarios).\n */\nexport class FilePersistence implements PersistenceBackend {\n  private readonly dir: string;\n\n  constructor(appId: string, baseDir?: string) {\n    this.dir = join(baseDir ?? tmpdir(), 'appmachina-sdk', appId);\n    if (!existsSync(this.dir)) {\n      mkdirSync(this.dir, { recursive: true });\n    }\n  }\n\n  write(key: string, data: Uint8Array): void {\n    const path = join(this.dir, encodeURIComponent(key));\n    writeFileSync(path, Buffer.from(data));\n  }\n\n  read(key: string): Uint8Array | null {\n    const path = join(this.dir, encodeURIComponent(key));\n    try {\n      return new Uint8Array(readFileSync(path));\n    } catch {\n      return null;\n    }\n  }\n\n  delete(key: string): void {\n    const path = join(this.dir, encodeURIComponent(key));\n    try {\n      unlinkSync(path);\n    } catch {\n      // File may not exist — ignore\n    }\n  }\n\n  listKeys(prefix: string): string[] {\n    try {\n      return readdirSync(this.dir)\n        .map((f) => decodeURIComponent(f))\n        .filter((k) => k.startsWith(prefix));\n    } catch {\n      return [];\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAoBA,IAAa,kBAAb,MAA2D;CACzD,AAAiB;CAEjB,YAAY,OAAe,SAAkB;AAC3C,OAAK,MAAM,KAAK,WAAW,QAAQ,EAAE,kBAAkB,MAAM;AAC7D,MAAI,CAAC,WAAW,KAAK,IAAI,CACvB,WAAU,KAAK,KAAK,EAAE,WAAW,MAAM,CAAC;;CAI5C,MAAM,KAAa,MAAwB;AAEzC,gBADa,KAAK,KAAK,KAAK,mBAAmB,IAAI,CAAC,EAChC,OAAO,KAAK,KAAK,CAAC;;CAGxC,KAAK,KAAgC;EACnC,MAAM,OAAO,KAAK,KAAK,KAAK,mBAAmB,IAAI,CAAC;AACpD,MAAI;AACF,UAAO,IAAI,WAAW,aAAa,KAAK,CAAC;UACnC;AACN,UAAO;;;CAIX,OAAO,KAAmB;EACxB,MAAM,OAAO,KAAK,KAAK,KAAK,mBAAmB,IAAI,CAAC;AACpD,MAAI;AACF,cAAW,KAAK;UACV;;CAKV,SAAS,QAA0B;AACjC,MAAI;AACF,UAAO,YAAY,KAAK,IAAI,CACzB,KAAK,MAAM,mBAAmB,EAAE,CAAC,CACjC,QAAQ,MAAM,EAAE,WAAW,OAAO,CAAC;UAChC;AACN,UAAO,EAAE"}

package/dist/persistence.d.ts

@@ -0,0 +1,2 @@
+import { t as FilePersistence } from "./persistence-ChBsyTkr.js";
+export { FilePersistence };

package/dist/persistence.js

@@ -0,0 +1,3 @@
+import { t as FilePersistence } from "./persistence-D_zFNklE.js";
+
+export { FilePersistence };

package/package.json

@@ -1,7 +1,54 @@
 {
   "name": "@appmachina/node",
-  "version": "0.0.1",
-  "description": "AppMachina SDK - node (placeholder)",
-  "main": "index.js",
-  "access": "public"
-}
+  "version": "2.2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "AppMachina Analytics Node.js SDK — thin wrapper over Rust core via WASM",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/appmachina/sdks.git",
+    "directory": "packages/node"
+  },
+  "author": "AppMachina Team",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./express": {
+      "types": "./dist/express.d.ts",
+      "default": "./dist/express.js"
+    },
+    "./nextjs": {
+      "types": "./dist/nextjs.d.ts",
+      "default": "./dist/nextjs.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@appmachina/core-wasm": "2.2.0"
+  },
+  "keywords": [
+    "appmachina",
+    "analytics",
+    "sdk",
+    "node",
+    "server"
+  ],
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts src/express.ts src/nextjs.ts src/persistence.ts --format esm --dts",
+    "test": "vitest run"
+  }
+}

package/index.js

@@ -1 +0,0 @@
-module.exports = {};