@caruuto/caruuto-js 0.4.3 → 0.7.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/index.js

@@ -10,7 +10,8 @@ const CaruutoClient = function (caruutoUrl, caruutoApiKey, options = {}) {
     'created_at',
     'created_by',
     'updated_at',
-    'updated_by'
+    'updated_by',
+    'v'
   ]
 
   if (this.options.caruutoUrl === undefined) {

package/lib/constants.js

@@ -0,0 +1,3 @@
+const API_KEY_PREFIX = 'Api-Key-v1'
+
+module.exports = { API_KEY_PREFIX }

package/lib/extensions/ai.js

@@ -0,0 +1,422 @@
+const undici = require('undici')
+const { API_KEY_PREFIX } = require('../constants')
+
+module.exports = function (CaruutoClient, clientInstance) {
+  CaruutoClient.prototype.ai = {
+    /**
+     * Send a message and receive a complete blocking response.
+     *
+     * @param {Object} opts
+     * @param {string}  opts.projectId         - Caruuto project ID (UUID)
+     * @param {string}  opts.message           - User's message
+     * @param {string}  [opts.conversationId]  - Existing conversation ID (omit to start new)
+     * @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
+     * @param {number}  [opts.maxItems]        - Max knowledge items to retrieve (1–10)
+     * @returns {Promise<{ answer, conversation_id, context, entities, _meta, from_cache? }>}
+     */
+    query: async function (opts = {}) {
+      const body = buildRequestBody(opts, false)
+      const response = await doFetch(
+        this,
+        `${this.options.caruutoUrl}/api/ai/external`,
+        body
+      )
+      return response.status === 204 ? undefined : response.json()
+    }.bind(clientInstance),
+
+    /**
+     * Send a message and receive a streaming response.
+     * Returns an async generator. Iterate with `for await`.
+     *
+     * Yields:
+     *   { type: 'text',  text: string }
+     *   { type: 'done',  conversation_id: string, context: [], entities: [], _meta: {}, from_cache?: boolean }
+     *
+     * @param {Object} opts - Same options as query()
+     * @returns {AsyncGenerator}
+     */
+    stream: async function* (opts = {}) {
+      const body = buildRequestBody(opts, true)
+      const response = await doFetch(
+        this,
+        `${this.options.caruutoUrl}/api/ai/external`,
+        body
+      )
+
+      const reader = response.body.getReader()
+      const decoder = new TextDecoder()
+      let buffer = ''
+
+      try {
+        while (true) {
+          const { done, value } = await reader.read()
+          if (done) {
+            break
+          }
+
+          buffer += decoder.decode(value, { stream: true })
+          const lines = buffer.split('\n')
+          buffer = lines.pop()
+
+          for (const line of lines) {
+            if (!line.startsWith('data: ')) {
+              continue
+            }
+
+            const raw = line.slice(6).trim()
+            if (!raw) {
+              continue
+            }
+
+            let parsed
+            try {
+              parsed = JSON.parse(raw)
+            } catch (_) {
+              continue
+            }
+
+            if (parsed.error) {
+              throw new Error(parsed.error)
+            } else if (parsed.done) {
+              yield { type: 'done', ...parsed }
+            } else if (parsed.text !== undefined) {
+              yield { type: 'text', text: parsed.text }
+            }
+          }
+        }
+      } finally {
+        reader.releaseLock()
+      }
+    }.bind(clientInstance),
+
+    /**
+     * Explicitly end a conversation, marking it as 'ended'.
+     * Call this when the user closes the chat widget or navigates away.
+     *
+     * @param {Object} opts
+     * @param {string} opts.conversationId - The conversation to end
+     * @param {string} opts.projectId      - The project the conversation belongs to
+     * @returns {Promise<{ id, status, turn_count, total_input_tokens, total_output_tokens, total_tokens, started_at, ended_at }>}
+     */
+    endConversation: async function ({ conversationId, projectId } = {}) {
+      if (!conversationId) {
+        throw new Error('conversationId is required')
+      }
+
+      if (!projectId) {
+        throw new Error('projectId is required')
+      }
+
+      const url = `${this.options.caruutoUrl}/api/ai/conversations/${conversationId}/end`
+      const response = await doFetch(this, url, { project_id: projectId })
+      return response.json()
+    }.bind(clientInstance),
+
+    /**
+     * Retrieve assembled context for a message without calling the LLM.
+     * Use this when you want to call your own LLM (e.g. with AI SDK + tools)
+     * and need Caruuto to handle retrieval, entity detection, and prompt assembly.
+     *
+     * On a cache hit, returns { from_cache: true, cached_answer, conversation_id, _meta }.
+     * On a miss, returns { from_cache: false, system_prompt, history, context, entities,
+     *   conversation_id, _meta }.
+     *
+     * @param {Object} opts - Same options as query(), minus stream/lead fields
+     * @returns {Promise<Object>}
+     */
+    context: async function (opts = {}) {
+      const {
+        projectId,
+        message,
+        conversationId,
+        clientSessionId,
+        source,
+        referrerUrl,
+        utmSource,
+        utmMedium,
+        utmCampaign,
+        utmTerm,
+        utmContent,
+        type,
+        maxItems
+      } = opts
+
+      const body = { project_id: projectId, message }
+
+      if (conversationId) body.conversation_id = conversationId
+      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
+
+      const response = await doFetch(
+        this,
+        `${this.options.caruutoUrl}/api/ai/context`,
+        body
+      )
+      return response.json()
+    }.bind(clientInstance),
+
+    /**
+     * Persist a completed turn (user message + assistant response) to Caruuto.
+     * Call this after your LLM stream completes with the full response text and
+     * token usage. Caruuto writes to ai_conversation_messages, updates token
+     * totals on the conversation, and caches the answer if it's the first turn.
+     *
+     * @param {Object} opts
+     * @param {string}   opts.conversationId        - From context() response
+     * @param {string}   opts.projectId
+     * @param {string}   opts.userContent           - The user's message text
+     * @param {string}   opts.assistantContent      - The full assistant response
+     * @param {string}   [opts.modelId]             - Model used (e.g. 'gpt-4o-mini')
+     * @param {number}   [opts.inputTokens]
+     * @param {number}   [opts.outputTokens]
+     * @param {Object[]} [opts.contextItems]        - From context() response
+     * @param {string[]} [opts.entitiesReferenced]  - Entity IDs from context()
+     * @param {string}   [opts.leadEmail]
+     * @param {string}   [opts.leadName]
+     * @returns {Promise<{ ok: boolean, turn_count: number }>}
+     */
+    /**
+     * Load a conversation and its messages, formatted as AI SDK UIMessage objects.
+     * Use this to restore a prior conversation into the chat UI.
+     *
+     * @param {Object} opts
+     * @param {string} opts.conversationId - The Caruuto conversation ID
+     * @param {string} opts.projectId
+     * @returns {Promise<{ id, status, turn_count, started_at, ended_at, messages }>}
+     */
+    /**
+     * Set a conversation's visibility to 'public' or 'private'.
+     *
+     * @param {Object} opts
+     * @param {string} opts.conversationId
+     * @param {string} opts.projectId
+     * @param {'public'|'private'} opts.visibility
+     * @returns {Promise<{ id, visibility, share_url }>}
+     */
+    /**
+     * Fork a conversation or question cache entry into a new conversation.
+     *
+     * @param {Object} opts
+     * @param {string} opts.sourceId      - Conversation ID or question cache entry ID
+     * @param {string} opts.projectId
+     * @param {'conversation'|'question_cache'} opts.source
+     * @returns {Promise<{ id: string }>}  New conversation ID
+     */
+    forkConversation: async function ({ sourceId, projectId, source = 'conversation' } = {}) {
+      if (!sourceId) throw new Error('sourceId is required')
+      if (!projectId) throw new Error('projectId is required')
+
+      const url = `${this.options.caruutoUrl}/api/ai/conversations/${sourceId}/fork`
+      const response = await doFetch(this, url, { project_id: projectId, source })
+      return response.json()
+    }.bind(clientInstance),
+
+    shareConversation: async function ({ conversationId, projectId, visibility = 'public' } = {}) {
+      if (!conversationId) throw new Error('conversationId is required')
+      if (!projectId) throw new Error('projectId is required')
+
+      const url = `${this.options.caruutoUrl}/api/ai/conversations/${conversationId}/share`
+      const response = await doFetch(this, url, { project_id: projectId, visibility })
+      return response.json()
+    }.bind(clientInstance),
+
+    /**
+     * Fetch a publicly shared conversation without authentication.
+     * Resolves with null if the conversation is private or not found.
+     *
+     * @param {Object} opts
+     * @param {string} opts.conversationId
+     * @returns {Promise<{ id, turn_count, started_at, ended_at, messages } | null>}
+     */
+    getPublicConversation: async function ({ conversationId } = {}) {
+      if (!conversationId) throw new Error('conversationId is required')
+
+      const fetch = this.options.fetch || undici.fetch
+      const url = `${this.options.caruutoUrl}/api/ai/conversations/${conversationId}/public`
+
+      const response = await fetch(url, { method: 'GET' })
+
+      if (response.status === 403 || response.status === 404) {
+        return null
+      }
+
+      if (!response.ok) {
+        const err = new Error('Failed to fetch public conversation')
+        err.status = response.status
+        throw err
+      }
+
+      return response.json()
+    }.bind(clientInstance),
+
+    loadConversation: async function ({ conversationId, projectId } = {}) {
+      if (!conversationId) {
+        throw new Error('conversationId is required')
+      }
+
+      if (!projectId) {
+        throw new Error('projectId is required')
+      }
+
+      const url = `${this.options.caruutoUrl}/api/ai/conversations/${conversationId}?project_id=${encodeURIComponent(projectId)}`
+      const response = await doGet(this, url)
+      return response.json()
+    }.bind(clientInstance),
+
+    saveTurn: async function ({
+      conversationId,
+      projectId,
+      userContent,
+      assistantContent,
+      modelId,
+      inputTokens,
+      outputTokens,
+      contextItems,
+      entitiesReferenced,
+      leadEmail,
+      leadName
+    } = {}) {
+      if (!conversationId) {
+        throw new Error('conversationId is required')
+      }
+
+      if (!projectId) {
+        throw new Error('projectId is required')
+      }
+
+      const body = {
+        project_id: projectId,
+        user_content: userContent,
+        assistant_content: assistantContent
+      }
+
+      if (modelId) body.model_id = modelId
+      if (inputTokens !== undefined) body.input_tokens = inputTokens
+      if (outputTokens !== undefined) body.output_tokens = outputTokens
+      if (contextItems) body.context_items = contextItems
+      if (entitiesReferenced) body.entities_referenced = entitiesReferenced
+      if (leadEmail) body.lead_email = leadEmail
+      if (leadName) body.lead_name = leadName
+
+      const url = `${this.options.caruutoUrl}/api/ai/conversations/${conversationId}/turn`
+      const response = await doFetch(this, url, body)
+      return response.json()
+    }.bind(clientInstance)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers (module-private)
+// ---------------------------------------------------------------------------
+
+function buildRequestBody(opts, stream) {
+  const {
+    projectId,
+    message,
+    conversationId,
+    clientSessionId,
+    source,
+    referrerUrl,
+    utmSource,
+    utmMedium,
+    utmCampaign,
+    utmTerm,
+    utmContent,
+    leadEmail,
+    leadName,
+    type,
+    maxItems
+  } = opts
+
+  const body = { project_id: projectId, message, stream }
+
+  if (conversationId) body.conversation_id = conversationId
+  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
+  if (maxItems !== undefined) body.max_items = maxItems
+
+  return body
+}
+
+async function doGet(client, url) {
+  const fetch = client.options.fetch || undici.fetch
+
+  const response = await fetch(url, {
+    method: 'GET',
+    headers: {
+      authorization: `${API_KEY_PREFIX} ${client.options.caruutoApiKey}`
+    }
+  })
+
+  if (!response.ok) {
+    const err = new Error('Caruuto AI request failed')
+    err.status = response.status
+
+    try {
+      const data = await response.clone().json()
+      if (data.error) {
+        err.message = data.error
+      }
+    } catch (_) {}
+
+    throw err
+  }
+
+  return response
+}
+
+async function doFetch(client, url, body) {
+  const fetch = client.options.fetch || undici.fetch
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      authorization: `${API_KEY_PREFIX} ${client.options.caruutoApiKey}`
+    },
+    body: JSON.stringify(body)
+  })
+
+  if (!response.ok) {
+    const err = new Error('Caruuto AI request failed')
+    err.status = response.status
+
+    try {
+      const data = await response.clone().json()
+      if (data.error) {
+        err.message = data.error
+      }
+    } catch (_) {}
+
+    throw err
+  }
+
+  return response
+}

package/lib/extensions/email.js

@@ -1,57 +1,12 @@
+const { makeEndpointMethod } = require('./utils')
+
 module.exports = function (CaruutoClient, clientInstance) {
   CaruutoClient.prototype.email = {
-    find: function (query) {
-      this.endpoint = 'email'
-
-      this.query = query
-
-      const requestPayload = {
-        method: 'GET',
-        uri: this._buildURL({ useParams: true })
-      }
-
-      this._setHeader('content-type', 'application/json')
-
-      return this._createRequestObject(requestPayload)
-    }.bind(clientInstance),
-    queue: function (data) {
-      this.endpoint = 'email'
-
-      const requestPayload = {
-        body: data,
-        method: 'POST',
-        uri: this._buildURL()
-      }
-
-      this._setHeader('content-type', 'application/json')
-
-      return this._createRequestObject(requestPayload)
-    }.bind(clientInstance),
-    update: function (data) {
-      this.endpoint = 'email'
-
-      const requestPayload = {
-        body: data,
-        method: 'PUT',
-        uri: this._buildURL()
-      }
-
-      this._setHeader('content-type', 'application/json')
-
-      return this._createRequestObject(requestPayload)
-    }.bind(clientInstance),
-    delete: function (data) {
-      this.endpoint = 'email'
-
-      const requestPayload = {
-        body: data,
-        method: 'DELETE',
-        uri: this._buildURL()
-      }
-
-      this._setHeader('content-type', 'application/json')
-
-      return this._createRequestObject(requestPayload)
-    }.bind(clientInstance)
+    find: makeEndpointMethod('email', 'GET', { query: true }).bind(
+      clientInstance
+    ),
+    queue: makeEndpointMethod('email', 'POST').bind(clientInstance),
+    update: makeEndpointMethod('email', 'PUT').bind(clientInstance),
+    delete: makeEndpointMethod('email', 'DELETE').bind(clientInstance)
   }
 }

package/lib/extensions/tokens.js

@@ -1,33 +1,10 @@
+const { makeEndpointMethod } = require('./utils')
+
 module.exports = function (CaruutoClient, clientInstance) {
   CaruutoClient.prototype.tokens = {
-    create: function (data) {
-      this.endpoint = 'tokens'
-
-      const requestPayload = {
-        body: data,
-        method: 'POST',
-        uri: this._buildURL()
-      }
-
-      this._setHeader('content-type', 'application/json')
-
-      return this._createRequestObject(requestPayload)
-    }.bind(clientInstance),
-    verify: function (token) {
-      this.endpoint = 'tokens'
-
-      const requestPayload = {
-        body: {
-          token,
-          verify: true
-        },
-        method: 'POST',
-        uri: this._buildURL()
-      }
-
-      this._setHeader('content-type', 'application/json')
-
-      return this._createRequestObject(requestPayload)
-    }.bind(clientInstance)
+    create: makeEndpointMethod('tokens', 'POST').bind(clientInstance),
+    verify: makeEndpointMethod('tokens', 'POST', {
+      transform: token => ({ token, verify: true })
+    }).bind(clientInstance)
   }
 }

package/lib/extensions/utils.js

@@ -0,0 +1,32 @@
+/**
+ * Creates an endpoint method bound to a given HTTP method and endpoint name.
+ *
+ * @param {string} endpoint - The API endpoint path segment (e.g. 'email', 'tokens')
+ * @param {string} httpMethod - HTTP verb ('GET', 'POST', 'PUT', 'DELETE')
+ * @param {Object} [opts]
+ * @param {boolean} [opts.query] - If true, the argument is treated as a query filter (GET style)
+ * @param {Function} [opts.transform] - Transform the argument before using it as the request body
+ */
+function makeEndpointMethod(endpoint, httpMethod, opts = {}) {
+  const { transform, query: isQuery = false } = opts
+
+  return function (data) {
+    this.endpoint = endpoint
+
+    const requestPayload = { method: httpMethod }
+
+    if (isQuery) {
+      this.query = data
+      requestPayload.uri = this._buildURL({ useParams: true })
+    } else {
+      requestPayload.body = transform ? transform(data) : data
+      requestPayload.uri = this._buildURL()
+    }
+
+    this._setHeader('content-type', 'application/json')
+
+    return this._createRequestObject(requestPayload)
+  }
+}
+
+module.exports = { makeEndpointMethod }

package/lib/extensions.js

@@ -33,11 +33,15 @@ module.exports = function (CaruutoClient, clientInstance) {
 ```
 */
 
+const aiExtension = require('./extensions/ai')
 const emailExtension = require('./extensions/email')
 const tokensExtension = require('./extensions/tokens')
 
-// Load all extensions from the lib/extensions directory/
 module.exports = function (CaruutoClient, clientInstance) {
+  if (typeof aiExtension === 'function') {
+    aiExtension(CaruutoClient, clientInstance)
+  }
+
   if (typeof emailExtension === 'function') {
     emailExtension(CaruutoClient, clientInstance)
   }
@@ -45,6 +49,4 @@ module.exports = function (CaruutoClient, clientInstance) {
   if (typeof tokensExtension === 'function') {
     tokensExtension(CaruutoClient, clientInstance)
   }
-
-  // Add any other extensions here.
 }

package/lib/filters.js

@@ -25,21 +25,6 @@ module.exports = function (CaruutoClient) {
     return this
   }
 
-  /**
-   * Select a bucket
-   *
-   * @param {String} bucket
-   * @return API
-   * @api public
-   */
-  CaruutoClient.prototype.inMedia = function (bucket) {
-    bucket = bucket || true
-
-    this.mediaBucket = bucket
-
-    return this
-  }
-
   /**
    * Select a document limit
    *

package/lib/helpers.js

@@ -1,5 +1,4 @@
 const querystring = require('query-string')
-const url = require('node:url')
 
 module.exports = function (CaruutoClient) {
   /**
@@ -35,7 +34,6 @@ module.exports = function (CaruutoClient) {
    * @api private
    */
   CaruutoClient.prototype._buildURL = function (options) {
-    // console.log('options :>> ', options)
     options = options || {}
 
     options.version = this.customVersion || `v${this.options.version || 0}`
@@ -43,28 +41,13 @@ module.exports = function (CaruutoClient) {
     let url = ''
 
     url += this.options.caruutoUrl
-    // url += ':' + this.options.port
 
-    if (this.mediaBucket) {
-      url +=
-        '/media' +
-        (typeof this.mediaBucket === 'string' ? '/' + this.mediaBucket : '')
-
-      if (this.terminator === 'uploadFile') {
-        url += '/upload'
-      }
-    } else if (this.collection) {
-      url += '/' + options.version + '/' + this.collection
+    if (this.collection) {
+      url += '/' + options.version + '/' + encodeURIComponent(this.collection)
     } else if (this.searchPhrase) {
       url += '/' + options.version
     } else {
-      url +=
-        '/' +
-        (this.customVersion !== undefined
-          ? this.customVersion
-          : options.version) +
-        '/' +
-        this.endpoint
+      url += '/' + options.version + '/' + encodeURIComponent(this.endpoint)
     }
 
     if (options.signUrl) {
@@ -75,28 +58,16 @@ module.exports = function (CaruutoClient) {
       url += '/sync'
     }
 
-    // if (options.config) {
-    //   url += '/config'
-    // }
-
-    if (options.status) {
-      url += '/status'
-    }
-
     if (options.collections) {
       url = this.options.caruutoUrl + '/api/contentTypes'
     }
 
-    // if (options.stats) {
-    //   url += '/stats'
-    // }
-
     if (this.count) {
       url += '/count'
     }
 
     if (options.id) {
-      url += '/' + options.id
+      url += '/' + encodeURIComponent(options.id)
     }
 
     if (this.searchPhrase) {
@@ -122,14 +93,6 @@ module.exports = function (CaruutoClient) {
         params.page = this.page
       }
 
-      if (this.compose !== undefined) {
-        params.compose = this.compose
-      }
-
-      if (typeof this.history !== 'undefined') {
-        params.includeHistory = this.history
-      }
-
       if (this.sort) {
         params.sort = JSON.stringify(this.sort)
       }
@@ -158,7 +121,7 @@ module.exports = function (CaruutoClient) {
    * @api private
    */
   CaruutoClient.prototype._createRequestObject = function (options) {
-    const parsedUri = url.parse(options.uri)
+    const parsedUri = new URL(options.uri)
     const requestObject = {
       ...options,
       uri: {
@@ -175,7 +138,9 @@ module.exports = function (CaruutoClient) {
     }
 
     if (typeof this.options.callback === 'function') {
-      return this.options.callback(requestObject, this)
+      return Promise.resolve(
+        this.options.callback(requestObject, this)
+      ).finally(() => this._reset())
     }
 
     return requestObject
@@ -186,14 +151,18 @@ module.exports = function (CaruutoClient) {
    * @param  {Object} object The object to encode
    * @return {Object}        The encoded object
    */
-  CaruutoClient.prototype._encodeObjectKeys = function (object) {
+  CaruutoClient.prototype._encodeObjectKeys = function (object, _depth) {
+    if ((_depth || 0) > 10) {
+      return {}
+    }
+
     return Object.keys(object).reduce((result, key) => {
       if (
         object[key] &&
         typeof object[key] === 'object' &&
         !Array.isArray(object[key])
       ) {
-        result[key] = this._encodeObjectKeys(object[key])
+        result[key] = this._encodeObjectKeys(object[key], (_depth || 0) + 1)
       } else {
         result[key] =
           typeof object[key] === 'string'
@@ -205,19 +174,6 @@ module.exports = function (CaruutoClient) {
     }, {})
   }
 
-  /**
-   * Logs a message
-   *
-   * @param {String} message
-   * @return undefined
-   * @api private
-   */
-  CaruutoClient.prototype._log = function (message) {
-    if (console && console.log) {
-      console.log(`[Caruuto JS] ${message}`)
-    }
-  }
-
   /**
    * Clear any saved options and parameters
    *
@@ -225,9 +181,20 @@ module.exports = function (CaruutoClient) {
    * @api private
    */
   CaruutoClient.prototype._reset = function () {
-    this.params = {}
+    this.collection = undefined
+    this.count = undefined
     this.customVersion = undefined
+    this.endpoint = undefined
+    this.fields = undefined
+    this.headers = undefined
+    this.limit = undefined
+    this.page = undefined
+    this.params = {}
     this.property = undefined
+    this.query = undefined
+    this.searchPhrase = undefined
+    this.sort = undefined
+    this.terminator = undefined
   }
 
   /**

package/lib/performFetch.js

@@ -1,93 +1,61 @@
-// const crossFetch = require('cross-fetch')
 const debug = require('debug')('caruuto-js')
 const undici = require('undici')
+const { API_KEY_PREFIX } = require('./constants')
 
-const resolveFetch = customFetch => {
-  let _fetch
+function buildRequestOptions(client, requestObject) {
+  const headers = Object.assign({}, requestObject.headers)
 
-  if (customFetch) {
-    _fetch = customFetch
-    // } else if (typeof fetch === 'undefined') {
-    //   _fetch = crossFetch
-  } else {
-    _fetch = undici.fetch
+  if (client.options.caruutoApiKey) {
+    headers.authorization = `${API_KEY_PREFIX} ${client.options.caruutoApiKey}`
   }
 
-  return (...args) => _fetch(...args)
+  if (
+    headers['content-type'] !== 'application/json' &&
+    client.terminator !== 'uploadFile'
+  ) {
+    headers['content-type'] = 'application/json'
+  }
+
+  const options = { headers, method: requestObject.method }
+
+  if (
+    requestObject.body &&
+    requestObject.method !== 'GET' &&
+    requestObject.method !== 'HEAD'
+  ) {
+    if (client.terminator === 'uploadFile') {
+      options.body = requestObject.body
+    } else if (typeof requestObject.body === 'object') {
+      options.body = JSON.stringify(requestObject.body)
+    } else {
+      options.body = requestObject.body
+    }
+  }
+
+  return options
 }
 
 module.exports = function (CaruutoClient) {
   /**
-   * Makes a request to API and handles possible failures
+   * Makes a request to the API and handles possible failures.
    *
-   * @param {Object} options - request options
-   * @return Results
+   * @param {Object} requestObject
+   * @return Promise
    * @api private
    */
   CaruutoClient.prototype._processRequest = async function (requestObject) {
-    const fetch = resolveFetch(this.options.fetch)
+    const fetch = this.options.fetch || undici.fetch
+    const options = buildRequestOptions(this, requestObject)
+    const uri = requestObject.uri.href
 
-    const options = {
-      headers: Object.assign({}, requestObject.headers),
-      method: requestObject.method,
-      uri: requestObject.uri.href
-    }
+    debug(`Querying URI: ${requestObject.uri.path}`)
 
-    // Add authorization header if an API key has been provided.
-    if (this.options.caruutoApiKey) {
-      options.headers.authorization = `Api-Key-v1 ${this.options.caruutoApiKey}`
-    }
-
-    if (requestObject.body) {
-      // If the body is a FormData object, we need to handle it differently
-      if (this.terminator === 'uploadFile') {
-        options.body = requestObject.body
-      } else if (typeof requestObject.body === 'object') {
-        // If the body is an object, we need to stringify it
-        options.body = JSON.stringify(requestObject.body)
-      } else {
-        options.body = requestObject.body
-      }
-    }
-
-    if (
-      options.headers['content-type'] !== 'application/json' &&
-      this.terminator !== 'uploadFile'
-    ) {
-      options.headers['content-type'] = 'application/json'
-    }
-
-    // if (this.terminator === 'uploadFile') {
-    // If we are uploading a file, we need to set the content type to multipart/form-data
-    // options.headers['content-type'] = 'multipart/form-data'
-    // }
-
-    // If the request is a GET request, we don't need to set the body
-    if (requestObject.method === 'GET' || requestObject.method === 'HEAD') {
-      delete options.body
-    }
-
-    // if (
-    //   requestObject.headers &&
-    //   requestObject.headers['content-type'] &&
-    //   requestObject.headers['content-type'] !== 'application/json'
-    // ) {
-    //   options.json = false
-    // } else {
-    //   options.json = true
-    // }
-
-    debug(`Querying URI: ${decodeURIComponent(options.uri)}`)
-
-    // Make the request using fetch
-    const response = await fetch(options.uri, options).catch(err => {
-      return Promise.reject(err)
-    })
+    const response = await fetch(uri, options).catch(err => Promise.reject(err))
 
     if (response.status >= 400) {
       const err = new Error()
       err.status = response.status
-      err.uri = options.uri
+      err.uri = requestObject.uri.path
 
       try {
         const responseData = await response.json()
@@ -99,12 +67,15 @@ module.exports = function (CaruutoClient) {
         if (responseData.errors) {
           err.errors = responseData.errors
         }
-      } catch (error) {
-        console.log('error :>> ', error)
-      }
+      } catch (_) {}
+
       return Promise.reject(err)
     }
 
-    return await response.json()
+    if (response.status === 204) {
+      return undefined
+    }
+
+    return response.json()
   }
 }

package/lib/terminators.js

@@ -1,10 +1,9 @@
-// const FormData = require('form-data')
 const undici = require('undici')
 const { FormData } = undici
 
 module.exports = function (CaruutoClient) {
   /**
-   * Create one/multiple documents or hooks
+   * Create one/multiple documents
    *
    * @param {Object} data
    * @return Promise
@@ -20,16 +19,10 @@ module.exports = function (CaruutoClient) {
 
     this._setHeader('content-type', 'application/json')
 
-    // if (this._isValidHook()) {
-    //   requestPayload.body = data
-
-    //   this._setHeader('content-type', 'text/plain')
-    // } else {
     requestPayload.body =
       data instanceof Array
         ? data.map(this._stripReservedProperties.bind(this))
         : this._stripReservedProperties(data)
-    // }
 
     return this._createRequestObject(requestPayload)
   }
@@ -48,14 +41,6 @@ module.exports = function (CaruutoClient) {
       uri: this._buildURL()
     }
 
-    // if (!this._isValidHook()) {
-    //   if (this.isClient) {
-    //     if (!this.isClient.id && !this.isClient.self) {
-    //       throw new Error(
-    //         'Unable run delete on all clients. Please use the whereClientIs() filter.'
-    //       )
-    //     }
-    //   } else {
     if (this.query === undefined) {
       throw new Error('Unable to find query for delete')
     }
@@ -63,8 +48,6 @@ module.exports = function (CaruutoClient) {
     requestPayload.body = {
       query: this.query
     }
-    //   }
-    // }
 
     return this._createRequestObject(requestPayload)
   }
@@ -87,8 +70,6 @@ module.exports = function (CaruutoClient) {
       uri: this._buildURL({
         useParams: true
       })
-    }).then(response => {
-      return response
     })
   }
 
@@ -107,36 +88,6 @@ module.exports = function (CaruutoClient) {
     })
   }
 
-  /**
-   * Get the config for a collection if one is specified, or for main API if not
-   *
-   * @return Promise
-   * @api public
-   */
-  CaruutoClient.prototype.getConfig = function () {
-    this.terminator = 'getConfig'
-
-    return this._createRequestObject({
-      method: 'GET',
-      uri: this._buildURL({ config: true })
-    })
-  }
-
-  /**
-   * Get the languages supported by the API
-   *
-   * @return Promise
-   * @api public
-   */
-  // CaruutoClient.prototype.getLanguages = function () {
-  //   this.terminator = 'getLanguages'
-
-  //   return this._createRequestObject({
-  //     method: 'GET',
-  //     uri: this._buildURL({ languages: true })
-  //   })
-  // }
-
   /**
    * Get a signed URL for media upload
    *
@@ -153,21 +104,6 @@ module.exports = function (CaruutoClient) {
     })
   }
 
-  /**
-   * Get the status of the API
-   *
-   * @return Promise
-   * @api public
-   */
-  CaruutoClient.prototype.getStatus = function () {
-    this.terminator = 'getStatus'
-
-    return this._createRequestObject({
-      method: 'POST',
-      uri: this._buildURL({ status: true })
-    })
-  }
-
   /**
    * Upload a file to the media bucket.
    *
@@ -192,13 +128,11 @@ module.exports = function (CaruutoClient) {
 
     const requestPayload = {
       method: 'POST',
-      uri: this._buildURL()
+      uri: this.options.caruutoUrl + '/api/media/upload'
     }
 
     const formData = new FormData()
 
-    console.log(directory, fileName, mimeType, buffer, contentLength)
-
     try {
       formData.append(
         'file',
@@ -233,25 +167,6 @@ module.exports = function (CaruutoClient) {
 
     this._setHeader('content-type', 'application/json')
 
-    // if (this._isValidHook()) {
-    //   requestPayload.body = update
-
-    //   this._setHeader('content-type', 'text/plain')
-    // } else {
-    //   if (this.isClient) {
-    //     if (!this.isClient.id && !this.isClient.self) {
-    //       throw new Error(
-    //         'Unable to run update on all clients. Please use whereClientIs() or whereClientIsSelf() filters.'
-    //       )
-    //     }
-
-    //     // Remove `clientId` from the payload.
-    //     if (update.clientId) {
-    //       delete update.clientId
-    //     }
-
-    //     requestPayload.body = update
-    //   } else {
     if (this.query === undefined) {
       throw new Error('Unable to find query for update')
     }
@@ -260,8 +175,6 @@ module.exports = function (CaruutoClient) {
       query: this.query,
       update: this._stripReservedProperties(update)
     }
-    // }
-    // }
 
     return this._createRequestObject(requestPayload)
   }
@@ -302,44 +215,13 @@ module.exports = function (CaruutoClient) {
     return this._createRequestObject(requestPayload)
   }
 
-  /*
-   * Create a new token.
-   * @param {Object} data
-   * @api public
-   */
+  // Requires createClient() — delegates to the tokens extension.
   CaruutoClient.prototype.createToken = function (data) {
-    this.endpoint = 'tokens'
-
-    const requestPayload = {
-      body: data,
-      method: 'POST',
-      uri: this._buildURL()
-    }
-
-    this._setHeader('content-type', 'application/json')
-
-    return this._createRequestObject(requestPayload)
+    return this.tokens.create(data)
   }
 
-  /*
-   * Verify a token.
-   * @param {Object} data
-   * @api public
-   */
+  // Requires createClient() — delegates to the tokens extension.
   CaruutoClient.prototype.verifyToken = function (token) {
-    this.endpoint = 'tokens'
-
-    const requestPayload = {
-      body: {
-        token,
-        verify: true
-      },
-      method: 'POST',
-      uri: this._buildURL()
-    }
-
-    this._setHeader('content-type', 'application/json')
-
-    return this._createRequestObject(requestPayload)
+    return this.tokens.verify(token)
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caruuto/caruuto-js",
-  "version": "0.4.3",
+  "version": "0.7.0",
   "description": "A high-level library for interacting with Caruuto",
   "exports": "./index.js",
   "scripts": {
@@ -10,24 +10,20 @@
   "author": "Jim Lambie <jim@27.works>",
   "license": "GPL",
   "dependencies": {
-    "cross-fetch": "^4.0.0",
     "debug": "^2.6.1",
     "encoding": "^0.1.13",
-    "got": "^11.0.0",
-    "human-interval": "^2.0.1",
-    "mocha": "^10.2.0",
     "query-string": "5.0.1",
     "undici": "6.21.3"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/Caruuto/caruuto-js.git"
+    "url": "git+https://github.com/Caruuto/caruuto-js.git"
   },
   "bugs": {
     "url": "https://github.com/Caruuto/caruuto-js/issues"
   },
   "engines": {
-    "node": ">=12"
+    "node": ">=18"
   },
   "husky": {
     "hooks": {
@@ -42,30 +38,16 @@
   },
   "homepage": "https://github.com/Caruuto/caruuto-js",
   "devDependencies": {
-    "chai": "^5.2.0",
     "coveralls": "^3.0.2",
     "eslint": "8.5.0",
-    "eslint-config-next": "13.0.5",
     "eslint-config-prettier": "^8.6.0",
     "eslint-plugin-prettier": "^4.2.1",
-    "eslint-plugin-react": "^7.32.2",
-    "form-data": "^4.0.2",
     "husky": "^8.0.0",
     "lint-staged": "^12.5.0",
-    "mockery": "^1.7.0",
-    "nock": "^12.0.0",
+    "mocha": "^10.2.0",
     "nyc": "^15.0.1",
     "prettier": "2.8.4",
-    "prettier-standard": "^15.0.1",
     "should": "^9.0.2",
-    "sinon": "^4.5.0",
-    "standard": "^16.0.3",
-    "supertest": "^4.0.0",
-    "underscore": "^1.8.3"
-  },
-  "standard.options": {
-    "ignore": [],
-    "plugins": [],
-    "envs": []
+    "sinon": "^4.5.0"
   }
-}
+}

package/.editorconfig

@@ -1,9 +0,0 @@
-root = true
-
-[*]
-charset = utf-8
-end_of_line = lf
-indent_size = 2
-indent_style = space
-insert_final_newline = true
-trim_trailing_whitespace = true

package/.eslintignore

@@ -1 +0,0 @@
-node_modules

package/.eslintrc.js

@@ -1,19 +0,0 @@
-module.exports = {
-  env: {
-    es2021: true,
-    mocha: true,
-    node: true
-  },
-  extends: ['eslint:recommended', 'plugin:prettier/recommended'],
-  overrides: [],
-  parserOptions: {
-    ecmaVersion: 12,
-    sourceType: 'module'
-  },
-  plugins: [],
-  rules: {
-    'no-redeclare': 0,
-    'prettier/prettier': 0,
-    quotes: ['error', 'single']
-  }
-}

package/.prettierignore

@@ -1 +0,0 @@
-node_modules

package/scripts/coverage.js

@@ -1,13 +0,0 @@
-#! /usr/bin/env node
-
-const exec = require('child_process').exec
-
-if (process.env.CI) {
-  exec(
-    'cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js',
-    (err, out) => {
-      if (err) console.log(err)
-      console.log(out)
-    }
-  )
-}

package/x.js

@@ -1,53 +0,0 @@
-const { createClient } = require('./index')
-
-// https://caruuto.27.works/api
-// EYeRSSEtmcVF9OFhVHjcf1TcPLHbTpPgBbHVHIce1buYKHOCNB1A2NC4UoThmQhk
-
-;(async () => {
-  const x = createClient(
-    'https://caruuto.27.works/api',
-    'EYeRSSEtmcVF9OFhVHjcf1TcPLHbTpPgBbHVHIce1buYKHOCNB1A2NC4UoThmQhk',
-    { reservedProperties: ['created_at'] }
-  )
-
-  // const signedUrl = await x.inMedia('radical').getSignedUrl('test.jpg')
-
-  // console.log(signedUrl)
-
-  // const y = await x.insertDataPoint({
-  //   memberId: '0bcdd373-fbb6-4998-b0ed-57c842709acc',
-  //   optionId: '10',
-  //   questionId: 'f373b0a2-9c87-41f1-af49-f643da8f836c'
-  // })
-
-  // x.search({ phrase: 'grower' })
-  // const y = await x.find()
-  // console.log('y :>> ', y)
-
-  // const z = await x.tokens.create({
-  //   email: 'jameslambie@gmail.com',
-  //   expiry: 7200000,
-  //   type: 'RESET'
-  // })
-  // const z = await x.verifyToken('q8ug8epjx5hzcg48ku')
-  // console.log('z :>> ', z)
-
-  // console.log('p :>> ', await x.create({ x: 1 }))
-
-  // console.log('x :>> ', x.email)
-  // console.log('x :>> ', x.email.queue)
-  // const xx = await x.email.queue({
-  //   to: 'x@x.com',
-  //   from: 'z@z.com',
-  //   templateId: 'test'
-  // })
-
-  // console.log('xx :>> ', xx)
-
-  x.in('retailers')
-  console.log('x :>> ', x)
-
-  const zz = await x.find({ sent: true })
-
-  console.log('zz :>> ', zz)
-})()