feat: add opt-in system attributes to publish payload

README.md

@@ -53,6 +53,16 @@ const sdk = new absmartly.SDK({
 });
 ```
 
+The `application` option can also be an object with `name` and `version` to track which version of your application is generating events. The version can be a number or a semver string:
+```javascript
+const sdk = new absmartly.SDK({
+    endpoint: 'https://sandbox.absmartly.io/v1',
+    apiKey: process.env.ABSMARTLY_API_KEY,
+    environment: process.env.NODE_ENV,
+    application: { name: 'website', version: '1.2.3' },
+});
+```
+
 #### Creating a new Context with raw promises
 ```javascript
 // define a new context request
@@ -137,6 +147,28 @@ context.attributes({
 });
 ```
 
+#### Including system attributes
+You can opt in to automatically include system attributes (SDK name, SDK version, application, environment, and application version) in every publish payload. These are sent as context attributes and can be useful for debugging and filtering in the Web Console.
+
+To enable this, set the `includeSystemAttributes` option to `true` when creating the context:
+```javascript
+const context = sdk.createContext(request, {
+    includeSystemAttributes: true,
+});
+```
+
+When enabled, the following attributes are automatically prepended to the publish request payload:
+
+| Attribute | Description |
+|:--- |---|
+| `sdk_name` | The SDK agent name (e.g. `"absmartly-javascript-sdk"`) |
+| `sdk_version` | The SDK version (e.g. `"1.13.4"`) |
+| `application` | The application name from the SDK configuration |
+| `environment` | The environment from the SDK configuration |
+| `app_version` | The application version, only included if greater than `0` |
+
+These system attributes are prepended before any user-defined attributes.
+
 #### Selecting a treatment
 ```javascript
 if (context.treament("exp_test_experiment") == 0) {

package.json

@@ -28,12 +28,13 @@
 		"build-browser": "TARGET=browser webpack --progress --config webpack.config.js && TARGET=browser NODE_ENV=production webpack --progress --config webpack.config.js",
 		"build-cjs": "TARGET=cjs babel js --delete-dir-on-start --ignore 'browser.js' -d lib",
 		"build-es": "TARGET=es babel js --delete-dir-on-start --ignore 'browser.js' -d es",
-		"build": "npm run -s format && npm run -s lint && npm run -s compile && npm run -s test && npm run -s build-es && npm run -s build-cjs && npm run -s build-browser",
+		"build": "npm run -s format && npm run -s lint && npm run -s generate-version && npm run -s compile && npm run -s test && npm run -s build-es && npm run -s build-cjs && npm run -s build-browser",
 		"lint": "eslint -f stylish 'src/**/*.{js,mjs,jsx,ts,mts,tsx}'",
 		"format": "prettier --write '**/*.{js,mjs,jsx,json,ts,mts,tsx}'",
 		"test": "jest --coverage",
 		"prepack": "npm run -s build",
-		"compile": "tsc"
+		"compile": "tsc",
+		"generate-version": "node scripts/generate-version.js"
 	},
 	"dependencies": {
 		"node-fetch": "^2.6.7",

scripts/generate-version.js

@@ -0,0 +1,7 @@
+const fs = require("fs");
+const path = require("path");
+
+const pkg = require(path.resolve(__dirname, "../package.json"));
+const versionFile = path.resolve(__dirname, "../src/version.ts");
+
+fs.writeFileSync(versionFile, `export const SDK_VERSION = "${pkg.version}";\n`);

src/__tests__/client.test.js

@@ -4,6 +4,7 @@ import fetch from "../fetch";
 // eslint-disable-next-line no-shadow
 import { AbortController } from "../abort";
 import { AbortError, RetryError, TimeoutError } from "../errors"; //eslint-disable-line no-shadow
+import { SDK_VERSION } from "../version";
 
 jest.mock("../fetch");
 
@@ -830,6 +831,7 @@ describe("Client", () => {
 			.publish({
 				units,
 				publishedAt,
+				sdkVersion: SDK_VERSION,
 				goals,
 				exposures,
 				attributes,
@@ -850,6 +852,7 @@ describe("Client", () => {
 					body: JSON.stringify({
 						units,
 						publishedAt,
+						sdkVersion: SDK_VERSION,
 						goals,
 						exposures,
 						attributes,
@@ -872,6 +875,7 @@ describe("Client", () => {
 			.publish({
 				units,
 				publishedAt,
+				sdkVersion: SDK_VERSION,
 				goals: [],
 				exposures: [],
 			})
@@ -891,6 +895,7 @@ describe("Client", () => {
 					body: JSON.stringify({
 						units,
 						publishedAt,
+						sdkVersion: SDK_VERSION,
 					}),
 					signal: expect.any(Object),
 				});
@@ -910,6 +915,7 @@ describe("Client", () => {
 		client
 			.publish({
 				units,
+				sdkVersion: SDK_VERSION,
 				goals: [],
 				exposures: [],
 			})
@@ -929,6 +935,7 @@ describe("Client", () => {
 					body: JSON.stringify({
 						units,
 						publishedAt: publishedAt + 100,
+						sdkVersion: SDK_VERSION,
 					}),
 					signal: expect.any(Object),
 				});
@@ -972,6 +979,58 @@ describe("Client", () => {
 			});
 	});
 
+	it("publish() should include sdkVersion in body", (done) => {
+		fetch.mockResolvedValueOnce(responseMock(200, "OK", defaultMockResponse));
+
+		const client = new Client(clientOptions);
+
+		client
+			.publish({
+				units,
+				publishedAt,
+				sdkVersion: "1.2.3",
+				goals: [],
+				exposures: [],
+			})
+			.then(() => {
+				const body = JSON.parse(fetch.mock.calls[0][1].body);
+				expect(body.sdkVersion).toEqual("1.2.3");
+
+				done();
+			});
+	});
+
+	it("getAgent() should return default agent when not specified", () => {
+		const { agent: _, ...optionsWithoutAgent } = clientOptions;
+		const client = new Client(optionsWithoutAgent);
+		expect(client.getAgent()).toEqual("javascript-client");
+	});
+
+	it("getAgent() should return custom agent when specified", () => {
+		const client = new Client({ ...clientOptions, agent: "custom-sdk" });
+		expect(client.getAgent()).toEqual("custom-sdk");
+	});
+
+	it("getApplication() should return normalized application object", () => {
+		const client = new Client(clientOptions);
+		expect(client.getApplication()).toEqual({ name: "test_app", version: 1000000 });
+	});
+
+	it("getApplication() should normalize string application to object", () => {
+		const client = new Client({ ...clientOptions, application: "website" });
+		expect(client.getApplication()).toEqual({ name: "website", version: 0 });
+	});
+
+	it("getApplication() should accept semver string version", () => {
+		const client = new Client({ ...clientOptions, application: { name: "website", version: "1.2.3" } });
+		expect(client.getApplication()).toEqual({ name: "website", version: "1.2.3" });
+	});
+
+	it("getEnvironment() should return the environment", () => {
+		const client = new Client(clientOptions);
+		expect(client.getEnvironment()).toEqual(environment);
+	});
+
 	it("publish() should not have the keepalive flag if specified", (done) => {
 		fetch.mockResolvedValueOnce(responseMock(200, "OK", defaultMockResponse));