feat: Configurable filter and transform functions for TrackPayload

[christiankalinowski]

Added option to RybbitConfig to allow defining optional filter and transform functions. Those can be used to fine tune the payload before sending.

Example use-cases for filter:

• Filtering autotracked button events of external library components

Example use-cases for transform:

• Removing specific query parameters (e.g. remove all except utm_*)
• Removing sensitive information from page_title

References: #1

Summary by CodeRabbit

• New Features

  • Event filtering: New configuration option to conditionally prevent events from being tracked based on custom predicates.
  • Payload transformation: New configuration option to modify tracked event data before transmission to your analytics backend.

• Tests

  • Comprehensive test coverage added for event filtering and payload transformation capabilities.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds event filtering and payload transformation hooks to the Rybbit tracking configuration. The RybbitConfig interface gains filter and transform callbacks. The track() function now evaluates the filter predicate and drops events early when rejected, applies the optional transform to modify the payload before transmission, and sends the transformed result.

Changes

Event Filter and Transform Configuration

Layer / File(s)	Summary
Type contract for filter and transform callbacks src/types.ts	RybbitConfig adds optional filter (payload → boolean) and transform (payload → payload) callbacks.
Configuration defaults and initialization src/config.ts, src/config.test.ts	Default filter always returns true; default transform is identity. Configuration stores and exposes these callbacks after initialization, and tests verify the injected callbacks are properly stored.
Core tracking flow with filtering and transformation src/core.ts, src/core.test.ts	The track() function applies the filter predicate and exits early if rejected, applies transform to the payload, and sends the transformed result. Tests verify skipPatterns blocking, filter-based rejection, and transform modification of fields.

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant track
  participant filter
  participant transform
  participant Network
  Caller->>track: track(event)
  track->>track: buildPayload()
  track->>filter: currentConfig.filter(payload)
  alt filter returns false
    filter-->>track: false
    track-->>Caller: return (filtered)
  else filter returns true
    filter-->>track: true
    track->>transform: currentConfig.transform(payload)
    transform-->>track: transformedPayload
    track->>Network: JSON.stringify(transformedPayload)
    Network-->>Caller: sent
  end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Filter and transform, now in place,
Events dance through custom space.
Drop the noise, reshape the call,
Rybbit tracks them, one and all! 🎯

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main change: configurable filter and transform hooks for TrackPayload.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/config.ts`:
- Around line 163-164: When building the config (where filter: options.filter ??
localDefaults.filter and transform: options.transform ?? localDefaults.transform
are set) validate that both filter and transform are functions before saving
them: if typeof options.filter === 'function' use it, else fall back to
localDefaults.filter only if it's a function (same for transform), otherwise set
the config value to undefined (or throw a clear error). Update the config
assembly logic that references filter and transform so the persisted config only
contains actual functions (use typeof ... === 'function' checks) to avoid
runtime TypeErrors when track() invokes filter() or transform().

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d47c9d07-2091-42e0-a31b-792325977bbb

📥 Commits

Reviewing files that changed from the base of the PR and between d0fad56 and 66fd6c6.

📒 Files selected for processing (5)

• src/config.test.ts
• src/config.ts
• src/core.test.ts
• src/core.ts
• src/types.ts

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Validate filter/transform are functions before persisting config.

Truthy non-function values can be accepted here and then throw at runtime when invoked in track() (src/core.ts Line 109 and Line 114), dropping events.

Suggested fix

+  const validatedFilter =
+    typeof options.filter === "function" ? options.filter : localDefaults.filter;
+  const validatedTransform =
+    typeof options.transform === "function" ? options.transform : localDefaults.transform;
+
+  if (options.filter !== undefined && typeof options.filter !== "function") {
+    logError("`filter` must be a function. Falling back to default.");
+  }
+  if (options.transform !== undefined && typeof options.transform !== "function") {
+    logError("`transform` must be a function. Falling back to default.");
+  }
+
   internalConfig = {
@@
-    filter: options.filter ?? localDefaults.filter,
-    transform: options.transform ?? localDefaults.transform,
+    filter: validatedFilter,
+    transform: validatedTransform,

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/config.ts` around lines 163 - 164, When building the config (where
filter: options.filter ?? localDefaults.filter and transform: options.transform
?? localDefaults.transform are set) validate that both filter and transform are
functions before saving them: if typeof options.filter === 'function' use it,
else fall back to localDefaults.filter only if it's a function (same for
transform), otherwise set the config value to undefined (or throw a clear
error). Update the config assembly logic that references filter and transform so
the persisted config only contains actual functions (use typeof ... ===
'function' checks) to avoid runtime TypeErrors when track() invokes filter() or
transform().