Skip to content

feat: add opt-in system attributes to publish payload#54

Merged
joalves merged 7 commits intomainfrom
feat/sdk-version-in-payload
Mar 27, 2026
Merged

feat: add opt-in system attributes to publish payload#54
joalves merged 7 commits intomainfrom
feat/sdk-version-in-payload

Conversation

@joalves
Copy link
Copy Markdown
Contributor

@joalves joalves commented Mar 24, 2026

Summary

  • Add includeSystemAttributes context option (opt-in, defaults to false)
  • When enabled, automatically prepends sdk_name, sdk_version, application, environment, and app_version (if > 0) as attributes in every publish payload
  • Add getAgent(), getApplication(), getEnvironment() getters to Client
  • Add src/version.ts exporting SDK_VERSION

Test plan

  • All 269 existing tests pass
  • 6 new tests covering:
    • System attributes not included by default
    • System attributes included when includeSystemAttributes: true
    • System attributes prepended before user attributes
    • app_version included when application version > 0
    • app_version excluded when application version is 0
    • Only user attributes when not opted in

Summary by CodeRabbit

  • New Features

    • Option to include system context attributes (SDK name, SDK version, application, environment, conditional app version) prepended to publish payloads.
    • SDK now surfaces its version in publish requests and provides accessors to retrieve agent, application and environment metadata.
  • Documentation

    • README updated: application can be provided as an object ({ name, version }) and guidance added for includeSystemAttributes usage.

Add includeSystemAttributes context option that, when enabled, automatically
includes sdk_name, sdk_version, application, environment, and app_version
(if > 0) as attributes in every publish payload.
@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Mar 24, 2026

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

Walkthrough

This PR adds an exported SDK_VERSION constant and includes sdkVersion in publish payloads. ContextOptions gains an optional includeSystemAttributes flag; Context now builds request.attributes (via a new attribute construction flow) that can prepend system attributes (sdk_name, sdk_version, application, environment, and app_version when > 0) before user attributes, and _flush wraps publish logic with error handling. Client exposes getters getAgent(), getApplication(), and getEnvironment(). Tests and the README are updated to reflect and verify the new behaviour.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐇 I nibble bytes and hop with glee,
I tuck the SDK version in where you see,
I line system tags before user lore,
A careful hop, then publish—off they soar,
Little rabbit, tidy and free.

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarises the main change: introducing an opt-in mechanism to include system attributes in publish payloads.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/sdk-version-in-payload

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (2)
src/version.ts (1)

1-1: Consider automating version synchronisation with package.json.

Manually maintaining the SDK version in this file creates a risk of drift from package.json. Consider importing the version from package.json at build time or using a build script to inject it, ensuring consistency.

That said, the current approach is functional and acceptable for now.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@src/version.ts` at line 1, The SDK_VERSION constant is manually maintained
and can drift from package.json; change the implementation so SDK_VERSION is
sourced from package.json at build/runtime (or injected by a build script)
instead of a hardcoded string: replace the current SDK_VERSION export with logic
that reads the "version" field from package.json (or uses an injected env var
during build) and export that value so SDK_VERSION always matches package.json’s
version.
src/__tests__/context.test.js (1)

480-484: Remove unused systemAttributes constant.

This constant is defined but never used in the test file. The tests directly check individual attributes inline instead. Consider removing this dead code to avoid confusion.

🧹 Suggested fix
 client.getAgent.mockReturnValue("absmartly-javascript-sdk");
 client.getApplication.mockReturnValue({ name: "website", version: 0 });
 client.getEnvironment.mockReturnValue("production");
-
-const systemAttributes = [
-	{ name: "sdk_version", value: expect.any(String), setAt: expect.any(Number) },
-	{ name: "application", value: "website", setAt: expect.any(Number) },
-	{ name: "environment", value: "production", setAt: expect.any(Number) },
-];
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@src/__tests__/context.test.js` around lines 480 - 484, Remove the dead
variable declaration systemAttributes from the test file (the const named
systemAttributes in src/__tests__/context.test.js) since it is never referenced;
simply delete the entire const systemAttributes = [...] block to clean up unused
code and keep the tests focused on the inline expectations that already assert
those attributes.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@README.md`:
- Around line 140-141: Update the phrasing in the "Including system attributes"
paragraph: replace "You can opt-in to automatically include system
attributes..." with a grammatically correct alternative such as "You can opt in
to automatically include system attributes..." or "You can choose to
automatically include system attributes (SDK name, SDK version, application,
environment, and application version) in every publish payload." Ensure the new
sentence preserves the same meaning and mentions that these attributes are sent
as context attributes useful for debugging and filtering in the Web Console.

In `@src/__tests__/context.test.js`:
- Around line 4030-4055: The test mutates the shared mock client.getApplication
and only resets it inside the async callback, risking mock leakage; change the
test to use client.getApplication.mockReturnValueOnce({ name: "website",
version: 3 }) when constructing the Context (or move the reset into a
centralized beforeEach/afterEach), so the override is scoped to this single run
and won't affect other tests — update the call site in the "should include
app_version when application version is set" test that currently calls
client.getApplication.mockReturnValue and remove the inline reset at the end.

---

Nitpick comments:
In `@src/__tests__/context.test.js`:
- Around line 480-484: Remove the dead variable declaration systemAttributes
from the test file (the const named systemAttributes in
src/__tests__/context.test.js) since it is never referenced; simply delete the
entire const systemAttributes = [...] block to clean up unused code and keep the
tests focused on the inline expectations that already assert those attributes.

In `@src/version.ts`:
- Line 1: The SDK_VERSION constant is manually maintained and can drift from
package.json; change the implementation so SDK_VERSION is sourced from
package.json at build/runtime (or injected by a build script) instead of a
hardcoded string: replace the current SDK_VERSION export with logic that reads
the "version" field from package.json (or uses an injected env var during build)
and export that value so SDK_VERSION always matches package.json’s version.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 516af9c1-916e-4f24-aecd-35f80b2a4462

📥 Commits

Reviewing files that changed from the base of the PR and between 47390ae and 170c1ff.

📒 Files selected for processing (5)
  • README.md
  • src/__tests__/context.test.js
  • src/client.ts
  • src/context.ts
  • src/version.ts

joalves added 2 commits March 24, 2026 13:48
Add sdkVersion as a top-level field in the publish payload body,
sent with every publish request regardless of includeSystemAttributes.
Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
README.md (1)

160-160: Consider tightening wording in Line 160 for readability.

“prepended to the publish payload” reads a bit awkwardly; “prepended to the published payload” (or “publish request payload”) is clearer.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 160, The sentence "When enabled, the following attributes
are automatically prepended to the publish payload:" is awkward; update that
line (the string "When enabled, the following attributes are automatically
prepended to the publish payload:") to clearer wording such as "When enabled,
the following attributes are automatically prepended to the published payload:"
or "When enabled, the following attributes are automatically prepended to the
publish request payload:" to improve readability.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@README.md`:
- Line 160: The sentence "When enabled, the following attributes are
automatically prepended to the publish payload:" is awkward; update that line
(the string "When enabled, the following attributes are automatically prepended
to the publish payload:") to clearer wording such as "When enabled, the
following attributes are automatically prepended to the published payload:" or
"When enabled, the following attributes are automatically prepended to the
publish request payload:" to improve readability.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6a5f618b-5cb7-4ad4-87ed-c459d704bd7e

📥 Commits

Reviewing files that changed from the base of the PR and between 0c1622e and 74cfcf4.

📒 Files selected for processing (1)
  • README.md

joalves added 2 commits March 24, 2026 15:46
- Fix "opt-in" grammar to "opt in" (verb form)
- Clarify "publish request payload" wording
- Remove unused systemAttributes test constant
- Use mockReturnValueOnce to prevent mock leakage
- Source SDK_VERSION from package.json instead of hardcoding
- Make sdkVersion required in PublishParams (matches actual usage)
- Add explicit return types to Client getters with post-construction types
- Extract _buildAttributes() private method from _flush()
- Wrap request construction in try-catch to prevent silent data loss
- Fix sdkVersion indentation alignment in test assertions
- Add client tests: sdkVersion in publish body, getter methods
- Strictly assert sdk_version attribute value equals SDK_VERSION
- Remove unused getApplicationName/getApplicationVersion imports
- Replace package.json import in version.ts with build-time generation
  via scripts/generate-version.js to avoid bundling package.json
- Support string | number for application version (semver support)
- Update ClientOptions, utils, Client getters, and context system
  attributes to handle string versions
- Add tests for semver string version in both client and context
- Update README and docs with semver version examples
- Introduce NormalizedClientOptions where application is always an
  object after constructor validation/normalization
- Remove 'as' casts from Client getters since internal type is correct
- Remove getApplicationName/getApplicationVersion usage from client
  (application is guaranteed to be an object)
- Replace 1==1 getAgent test with meaningful custom agent test
@joalves joalves merged commit 38ddc48 into main Mar 27, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants