Lightweight browser SDK for intent events (client-only).
npm install @solomei-ai/intent
The Intent tracker collects consented client context and sends events to Callimacus.
It can be easily integrated into modern applications (React, Vite, Next.js, etc.) via npm or directly via a script tag.
---
Install the package from npm:
``bash`
npm install @solomei-ai/intent
---
Initialize Intent in your app entry point:
`ts
// app entry
import { initIntent } from '@solomei-ai/intent';
initIntent({
clientId: 'cal-pk-...', // your Callimacus Client ID
consent: true, // can be toggled later
geo: true, // can be toggled later
});
`
The initIntent function accepts the following options:
`ts`
initIntent({
clientId: 'cal-pk-...', // Required: Your Callimacus Client ID
consent: true, // Optional: Enable/disable tracking (default: false)
geo: false, // Optional: Enable/disable geolocation (default: false)
baseUrl: 'https://...', // Optional: Custom API endpoint (default: 'https://intent.callimacus.ai')
ip: '192.0.2.1', // Optional: Client IP address
sidMaxAgeSeconds: 2592000, // Optional: Session cookie max-age in seconds (default: 30 days = 2592000 seconds)
debug: false, // Optional: Enable debug logging for timing information (default: false)
debugPanel: false, // Optional: Enable visual debug panel (default: false)
});
---
If you prefer not to use npm, include the package via a
`
`html`
Once loaded, access the module from the global window.Intent namespace:
`html`
---
* npm: @solomei-ai/intent
* jsDelivr: https://www.jsdelivr.com/package/npm/@solomei-ai/intent
* unpkg: https://unpkg.com/@solomei-ai/intent
---
Use the dedicated helper functions for better type safety and IDE support:
`ts
import {setConsent, setGeo, setDebug} from '@solomei-ai/intent';
// Grant or revoke consent
setConsent(true); // granted
setConsent(false); // disabled
// Enable or disable device geolocation capture
setGeo(true); // enabled
setGeo(false); // disabled
// Enable or disable debug logging
setDebug(true); // enabled
setDebug(false); // disabled
`
Benefits of type-safe functions:
- Clear, self-documenting API
- Better IDE autocomplete and type checking
- Prevents typos in flag names
- Explicit boolean-only parameters
The setFlag function remains available for backwards compatibility:
`ts
import {setFlag} from '@solomei-ai/intent';
// Grant or revoke consent
setFlag('intent:consent', true); // granted
setFlag('intent:consent', false); // disabled
// Enable or disable device geolocation capture
setFlag('intent:geo', true); // enabled
setFlag('intent:geo', false); // disabled
// Enable or disable debug logging
setFlag('intent:debug', true); // enabled
setFlag('intent:debug', false); // disabled
`
> ā ļø URGENT DEPRECATION WARNING: The entire setFlag function will be removed in v2.0.0 (February 2026 - approximately 1-2 months). All users must migrate to the type-safe functions (setConsent, setGeo, setDebug) before upgrading to v2.0.0. See the Migration Guide below for details.
---
Behavior:
- When consent is granted, the tracker maintains a first-party cookie intent_sid.intent_sid
- If consent is revoked, the tracker clears and stops sending events.
Upgrading from v1.9.x and earlier:
The new type-safe functions are recommended but optional. Your existing code using setFlag will continue to work without any changes:
`ts
// ā
This still works (backwards compatible)
setFlag('intent:consent', true);
// ā
Recommended: Migrate to type-safe functions for better DX
setConsent(true);
`
No breaking changes - all existing code remains functional.
ā ļø URGENT: Deprecation Timeline
- v1.10.0 (Current - December 2025): setFlag function is deprecated but still supportedsetFlag
- v2.0.0 (February 2026 - ~1-2 months): function will be completely removed
ā ļø You have approximately 1-2 months to complete migration before v2.0.0
Migration Required Before v2.0.0:
All code using setFlag must be migrated to the type-safe alternatives:
`ts
// ā Will NOT work in v2.0.0 - setFlag will be removed
setFlag('intent:consent', true);
setFlag('intent:consent', 'granted');
setFlag('intent:geo', false);
setFlag('intent:debug', true);
// ā
REQUIRED migration for v2.0.0
setConsent(true); // replaces setFlag('intent:consent', true)
setGeo(false); // replaces setFlag('intent:geo', false)
setDebug(true); // replaces setFlag('intent:debug', true)
`
Migration Steps:
1. Find all uses of setFlag in your codebasesetFlag('intent:consent', ...)
2. Replace each call with the appropriate type-safe function:
- ā setConsent(...)setFlag('intent:geo', ...)
- ā setGeo(...)setFlag('intent:debug', ...)
- ā setDebug(...)
3. If you were using custom flag names, you'll need to find an alternative solution or open an issue to discuss your use case
Search & Replace Examples:
`bashFind all uses of setFlag
grep -r "setFlag" your-codebase/
---
Debug Logging & Debug Panel
$3
By default, the SDK does not output any console logs to avoid spamming the browser console. However, you can enable debug logging to see timing information for performance analysis:
`ts
import {initIntent} from '@solomei-ai/intent';// Enable debug logging during initialization
initIntent({
clientId: 'cal-pk-...',
debug: true, // Enable debug logs
});
`Or toggle debug logging at runtime:
`ts
import {setDebug} from '@solomei-ai/intent';// Enable debug logging (recommended - type-safe)
setDebug(true);
// Disable debug logging
setDebug(false);
// Backwards compatible: using setFlag still works
import {setFlag} from '@solomei-ai/intent';
setFlag('intent:debug', true);
setFlag('intent:debug', false);
`When debug logging is enabled, the SDK will output timing information to the console, including:
- HTML serialization time: Time taken to serialize the DOM into HTML
- Screenshot capture time: Time taken by html2canvas-pro to render the page
- JPEG encoding time: Time taken to encode the canvas to JPEG format
- Total capture time: Total time for the entire capture process
This is useful for:
- Performance tuning: Identify bottlenecks in the capture process
- Development debugging: Understand SDK behavior during development
- Production troubleshooting: Temporarily enable logs to diagnose issues
Note: Debug logging is disabled by default to prevent console spam in production. Only enable it when needed for debugging or performance analysis.
$3
> ā ļø WARNING: The debug panel is intended for development and debugging only.
> DO NOT enable in production environments. It exposes internal SDK behavior including screenshots, event payloads, and HTML content that may reveal sensitive application structure.
The SDK provides separate build variants to ensure the debug panel code is not shipped to production:
#### Build Variants
Production Build (Default) - Debug panel excluded
`bash
npm install @solomei-ai/intent
`
`ts
import {initIntent} from '@solomei-ai/intent'; // Production build
`
`html
`Debug Build - Debug panel included (for development/testing only)
`ts
// ESM - use the /debug export
import {initIntent, setDebugPanel} from '@solomei-ai/intent/debug';
`
`html
`#### Best Practice: Environment-Based Loading
Use your build system to load the appropriate variant:
`ts
// Vite / Webpack example
const Intent = import.meta.env.PROD
? await import('@solomei-ai/intent')
: await import('@solomei-ai/intent/debug');Intent.initIntent({
clientId: 'cal-pk-...',
consent: true,
debugPanel: !import.meta.env.PROD // Only in development
});
`Recommended Use Cases:
- Local Development: Debug event capture during integration
- Testing Environments: Verify SDK behavior in test/staging
- Internal Demos: Showcase SDK functionality to internal stakeholders
- Troubleshooting: Diagnose issues in non-production environments
NOT Recommended:
- ā Production websites or applications
- ā Public demos accessible to end users
- ā Any environment where exposing SDK internals is a concern
#### Usage
Enable debug panel during initialization:
`ts
import {initIntent} from '@solomei-ai/intent/debug'; // Use debug buildinitIntent({
clientId: 'cal-pk-...',
consent: true,
debugPanel: true, // Enable visual debug panel
});
`Toggle debug panel at runtime:
`ts
import {setDebugPanel} from '@solomei-ai/intent/debug';// Show debug panel (development only)
setDebugPanel(true);
// Hide debug panel
setDebugPanel(false);
`Debug Panel Features:
- šø Screenshots: View the actual JPEG screenshots captured by the SDK
- š Event Details: Expand each event to see properties, HTML, and bounding box data
- šÆ Event Types: See what type of event was captured (click, pageview, scroll, etc.)
- š Timestamps: Track when each event occurred
- šļø Clear Events: Clear the event log with a single button click
- šØ Draggable: Move the panel anywhere on the screen
- ā Minimize: Collapse the panel when not needed
The debug panel appears as a floating window in the top-right corner and can be dragged anywhere on the page. It displays up to 50 recent events (automatically removes oldest when limit is reached).
---
š® Test & Demo Page
A comprehensive test and demo page is included in the
demo/test-demo.html file. This page showcases:- ā
All form input types (text, email, password, date, color, range, etc.)
- ā
Interactive elements (buttons, links, clickable divs)
- ā
Auto-redacted fields (email, password, phone, credit card, etc.)
- ā
Custom redaction examples with
data-intent-redact
- ā
SDK initialization and consent controls
- ā
Debug panel demonstration
- ā
Complete documentation and usage instructionsTo use the test page:
1. Build the SDK:
`bash
npm run build
`2. Start a local web server from the repository root:
`bash
# Using Python 3
python3 -m http.server 8080
# Or using Node.js http-server
npx http-server -p 8080
`3. Open your browser and navigate to:
`
http://localhost:8080/demo/test-demo.html
`4. Follow the on-page instructions to:
- Initialize the SDK
- Enable the debug panel
- Grant consent
- Interact with elements to see captured events
The test page is perfect for demonstrating the SDK to stakeholders, testing new features, and understanding how the SDK captures and handles different types of data.
---
Using
intent_sidUse these utilities to read or manage the session cookie from your app:
`ts
import {
getIntentSessionId,
clearIntentSessionId,
ensureIntentSessionId,
setIntentSessionMaxAge,
} from '@solomei-ai/intent';const sid = getIntentSessionId(); // string | undefined, can be sent to backend
clearIntentSessionId(); // deletes cookie
ensureIntentSessionId(); // creates cookie if missing
setIntentSessionMaxAge(86400); // updates cookie max-age (in seconds)
`---
š Data Collection & Privacy
$3
When consent is granted, the Intent SDK automatically collects the following data to help understand user behavior and improve experiences:
1. Screenshots: Visual captures of the page viewport, downscaled to JPEG format for efficient transmission
2. HTML Content: Serialized HTML of interacted elements (buttons, links, inputs, etc.)
3. Interaction Events: User actions including:
- Clicks on buttons, links, and interactive elements
- Form submissions (Enter key on input fields)
- Page scroll events
- Page focus/blur events
- Pageview events
4. Session Information:
- Session ID stored in first-party cookie
intent_sid (created when consent is granted)
- Session cookie max-age (default: 30 days, configurable via sidMaxAgeSeconds)
5. Context Information: Browser and device metadata:
- User agent: Browser name, version, and platform
- Languages: Preferred language(s) and accept-language settings
- Timezone: Local timezone and UTC offset
- Local time: Current date and time in user's timezone
- Screen: Resolution, pixel ratio, available space, and color depth
- Viewport: Window size and screen orientation
- Device capabilities: CPU cores, touch support, pointer type (coarse/fine)
- Battery status: Level and charging state (when available)
- Network connection: Connection type, speed, RTT, and data saver mode (when available or inferred from performance timing)
- Performance timing: Used to infer network characteristics
- Online/offline status: Browser connectivity state
- Cookies enabled: Whether the browser allows cookies
- Do Not Track (DNT): Browser DNT setting value
- Referrer: HTTP referrer if present
- PWA status: Service worker presence and display mode
- Device orientation/tilt: Device physical orientation (when available)
- Geolocation: Latitude and longitude (only when explicitly enabled via geo: true)
6. Client Configuration (stored in localStorage):
- Client ID (clientId)
- API endpoint (baseUrl)
- Optional IP address (ip)
- Consent status (intent:consent)
- Geolocation preference (intent:geo)
- Debug logging preference (intent:debug)
- Session max-age setting$3
The SDK automatically redacts the following sensitive information:
- Password fields (
)
- Form fields with sensitive autocomplete attributes (both and