@caruuto/caruuto-js 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## 0.7.0 - 2026-06-08
+
+### Added
+
+- `ai.query()`, `ai.stream()`, and `ai.context()` now accept `utmSource`,
+  `utmMedium`, `utmCampaign`, `utmTerm`, and `utmContent` options, sent through
+  as `utm_source` / `utm_medium` / `utm_campaign` / `utm_term` / `utm_content`
+  alongside the existing `referrerUrl`. Lets callers forward acquisition data
+  from the page URL so Caruuto can attribute AI sessions to a referral channel.
+
 ## 0.3.6 - 2024-09-06
 
 ### Added

package/lib/extensions/ai.js

@@ -13,6 +13,11 @@ module.exports = function (CaruutoClient, clientInstance) {
      * @param {string}  [opts.clientSessionId] - Client's anonymous user token
      * @param {string}  [opts.source]          - 'widget' | 'api' | 'embed'
      * @param {string}  [opts.referrerUrl]     - URL where the chat is embedded
+     * @param {string}  [opts.utmSource]       - UTM source param from the page URL
+     * @param {string}  [opts.utmMedium]       - UTM medium param from the page URL
+     * @param {string}  [opts.utmCampaign]     - UTM campaign param from the page URL
+     * @param {string}  [opts.utmTerm]         - UTM term param from the page URL
+     * @param {string}  [opts.utmContent]      - UTM content param from the page URL
      * @param {string}  [opts.leadEmail]       - Capture a lead email on this turn
      * @param {string}  [opts.leadName]        - Lead name (paired with leadEmail)
      * @param {string}  [opts.type]            - Restrict retrieval to a single knowledge type
@@ -137,6 +142,11 @@ module.exports = function (CaruutoClient, clientInstance) {
         clientSessionId,
         source,
         referrerUrl,
+        utmSource,
+        utmMedium,
+        utmCampaign,
+        utmTerm,
+        utmContent,
         type,
         maxItems
       } = opts
@@ -147,6 +157,11 @@ module.exports = function (CaruutoClient, clientInstance) {
       if (clientSessionId) body.client_session_id = clientSessionId
       if (source) body.source = source
       if (referrerUrl) body.referrer_url = referrerUrl
+      if (utmSource) body.utm_source = utmSource
+      if (utmMedium) body.utm_medium = utmMedium
+      if (utmCampaign) body.utm_campaign = utmCampaign
+      if (utmTerm) body.utm_term = utmTerm
+      if (utmContent) body.utm_content = utmContent
       if (type) body.type = type
       if (maxItems !== undefined) body.max_items = maxItems
 
@@ -304,6 +319,49 @@ module.exports = function (CaruutoClient, clientInstance) {
       const url = `${this.options.caruutoUrl}/api/ai/conversations/${conversationId}/turn`
       const response = await doFetch(this, url, body)
       return response.json()
+    }.bind(clientInstance),
+
+    /**
+     * Record a click on a link surfaced in an assistant response — powers the
+     * CTA-click and conversion panels on the analytics dashboard. Caruuto
+     * classifies the link as 'internal' or 'external' relative to the
+     * project's site_domain and persists it to ai_link_click_events.
+     *
+     * @param {Object} opts
+     * @param {string} opts.conversationId   - The conversation the link appeared in
+     * @param {string} opts.projectId
+     * @param {string} opts.url              - The full clicked URL, exactly as rendered
+     * @param {string} [opts.linkLabel]      - The link's visible text
+     * @param {number} [opts.messageIndex]   - Position of the assistant message clicked from
+     * @returns {Promise<{ ok: boolean }>}
+     */
+    trackLinkClick: async function ({
+      conversationId,
+      projectId,
+      url,
+      linkLabel,
+      messageIndex
+    } = {}) {
+      if (!conversationId) {
+        throw new Error('conversationId is required')
+      }
+
+      if (!projectId) {
+        throw new Error('projectId is required')
+      }
+
+      if (!url) {
+        throw new Error('url is required')
+      }
+
+      const body = { project_id: projectId, url }
+
+      if (linkLabel) body.link_label = linkLabel
+      if (messageIndex !== undefined) body.message_index = messageIndex
+
+      const trackUrl = `${this.options.caruutoUrl}/api/ai/conversations/${conversationId}/link-click`
+      const response = await doFetch(this, trackUrl, body)
+      return response.json()
     }.bind(clientInstance)
   }
 }
@@ -320,6 +378,11 @@ function buildRequestBody(opts, stream) {
     clientSessionId,
     source,
     referrerUrl,
+    utmSource,
+    utmMedium,
+    utmCampaign,
+    utmTerm,
+    utmContent,
     leadEmail,
     leadName,
     type,
@@ -332,6 +395,11 @@ function buildRequestBody(opts, stream) {
   if (clientSessionId) body.client_session_id = clientSessionId
   if (source) body.source = source
   if (referrerUrl) body.referrer_url = referrerUrl
+  if (utmSource) body.utm_source = utmSource
+  if (utmMedium) body.utm_medium = utmMedium
+  if (utmCampaign) body.utm_campaign = utmCampaign
+  if (utmTerm) body.utm_term = utmTerm
+  if (utmContent) body.utm_content = utmContent
   if (leadEmail) body.lead_email = leadEmail
   if (leadName) body.lead_name = leadName
   if (type) body.type = type

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caruuto/caruuto-js",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "A high-level library for interacting with Caruuto",
   "exports": "./index.js",
   "scripts": {