@wool-so/node 0.3.0

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@wool-so/node",
+  "version": "0.3.0",
+  "description": "Server-side analytics SDK for Wool.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "node --check src/index.js",
+    "test": "node --test test/*.test.js"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,195 @@
+export const VERSION: '0.3.0'
+export const DEFAULT_ENDPOINT: 'https://wool-api.gurjas1882.workers.dev/v1/events'
+
+export type WoolPropertyValue = string | number | boolean | null | undefined
+export type WoolProperties = Record<string, WoolPropertyValue>
+
+export interface WoolFetchResponse {
+  ok: boolean
+  status: number
+  text?: () => Promise<string>
+}
+
+export type WoolFetch = (
+  input: string,
+  init: {
+    method: 'POST'
+    headers: Record<string, string>
+    body: string
+  }
+) => Promise<WoolFetchResponse>
+
+export interface WoolBaseOptions {
+  endpoint?: string
+  apiUrl?: string
+  apiHost?: string
+  fetch?: WoolFetch
+  enabled?: boolean
+  referrer?: string
+  referer?: string
+  retentionId?: string
+  retention_id?: string
+  subjectKey?: string
+  subject_key?: string
+  groupKey?: string
+  group_key?: string
+}
+
+export type WoolInitOptions = WoolBaseOptions &
+  (
+    | {
+        projectId: string
+        project_id?: string
+      }
+    | {
+        projectId?: string
+        project_id: string
+      }
+  ) &
+  (
+    | {
+        apiKey: string
+        api_key?: string
+      }
+    | {
+        apiKey?: string
+        api_key: string
+      }
+  ) &
+  (
+    | {
+        siteUrl: string
+        site_url?: string
+        url?: string
+      }
+    | {
+        siteUrl?: string
+        site_url: string
+        url?: string
+      }
+    | {
+        siteUrl?: string
+        site_url?: string
+        url: string
+      }
+  )
+
+export interface WoolIdentifyOptions {
+  groupKey?: string
+  group_key?: string
+}
+
+export interface WoolRequestLike {
+  url?: string
+  originalUrl?: string
+  path?: string
+  protocol?: string
+  hostname?: string
+  headers?: Headers | Record<string, string | string[] | undefined>
+  socket?: {
+    encrypted?: boolean
+  }
+  connection?: {
+    encrypted?: boolean
+  }
+  nextUrl?: {
+    pathname?: string
+  }
+}
+
+export interface WoolRequestContextOptions {
+  url?: string
+  referrer?: string
+  referer?: string
+}
+
+export interface WoolRequestContext {
+  url: string
+  referrer: string
+}
+
+export interface WoolTrackOptions extends WoolRequestContextOptions {
+  request?: Request | WoolRequestLike
+  req?: Request | WoolRequestLike
+  source?: string
+  eventId?: string
+  id?: string
+  visitorKey?: string
+  visitor_key?: string
+  value?: number | string
+  currency?: string
+  duration?: number | string
+  nonInteractive?: boolean
+  non_interactive?: boolean
+  retentionId?: string
+  retention_id?: string
+  subjectKey?: string
+  subject_key?: string
+  anonymousId?: string
+  anonymous_id?: string
+  groupKey?: string
+  group_key?: string
+}
+
+export interface WoolPageviewOptions extends WoolRequestContextOptions {
+  request?: Request | WoolRequestLike
+  req?: Request | WoolRequestLike
+}
+
+export interface WoolResult {
+  ok: boolean
+  status: number
+  skipped?: boolean
+  response?: WoolFetchResponse
+}
+
+export interface WoolClient {
+  identify(retentionId: string, options?: WoolIdentifyOptions): void
+  reset(): void
+  track(name: string, properties?: WoolProperties, options?: WoolTrackOptions): Promise<WoolResult>
+  pageview(options?: WoolPageviewOptions): Promise<WoolResult>
+  requestContext(input?: Request | WoolRequestLike | string, options?: WoolRequestContextOptions): WoolRequestContext
+}
+
+export class WoolError extends Error {
+  status: number
+  response: WoolFetchResponse | null
+  constructor(message: string, status?: number, response?: WoolFetchResponse | null)
+}
+
+export function createClient(options: WoolInitOptions): WoolClient
+export function init(options: WoolInitOptions): WoolClient
+export function identify(retentionId: string, options?: WoolIdentifyOptions): void
+export function reset(): void
+export function track(name: string, properties?: WoolProperties, options?: WoolTrackOptions): Promise<WoolResult>
+export function pageview(options?: WoolPageviewOptions): Promise<WoolResult>
+export function requestContext(
+  input?: Request | WoolRequestLike | string,
+  options?: WoolRequestContextOptions
+): WoolRequestContext
+
+export type ExpressMiddleware = (req: WoolRequestLike & { wool?: WoolClient }, res: unknown, next?: () => void) => void
+export type NestMiddleware = ExpressMiddleware
+export type FastifyPlugin = (
+  fastify: { decorate?: (name: string, value: WoolClient) => void; wool?: WoolClient },
+  options?: unknown,
+  done?: () => void
+) => void
+export type HonoMiddleware = (context: { set?: (name: string, value: WoolClient) => void; wool?: WoolClient }, next?: () => Promise<void> | void) => Promise<void>
+
+export function expressMiddleware(options: WoolInitOptions | WoolClient): ExpressMiddleware
+export function nestMiddleware(options: WoolInitOptions | WoolClient): NestMiddleware
+export function fastifyPlugin(options: WoolInitOptions | WoolClient): FastifyPlugin
+export function honoMiddleware(options: WoolInitOptions | WoolClient): HonoMiddleware
+
+export const wool: WoolClient & {
+  init: typeof init
+  createClient: typeof createClient
+  requestContext: typeof requestContext
+  expressMiddleware: typeof expressMiddleware
+  fastifyPlugin: typeof fastifyPlugin
+  honoMiddleware: typeof honoMiddleware
+  nestMiddleware: typeof nestMiddleware
+}
+
+export default wool

package/src/index.js

@@ -0,0 +1,404 @@
+export const VERSION = '0.3.0'
+export const DEFAULT_ENDPOINT = 'https://wool-api.gurjas1882.workers.dev/v1/events'
+
+const IDENTITY_KEY_PATTERN =
+  /^(anonymousId|anonymous_id|retentionId|retention_id|subjectKey|subject_key|groupKey|group_key)$/i
+const TRACK_OPTION_KEYS = new Set([
+  'source',
+  'eventId',
+  'id',
+  'visitorKey',
+  'visitor_key',
+  'value',
+  'currency',
+  'duration',
+  'nonInteractive',
+  'non_interactive',
+  'retentionId',
+  'retention_id',
+  'subjectKey',
+  'subject_key',
+  'anonymousId',
+  'anonymous_id',
+  'groupKey',
+  'group_key',
+  'url',
+  'referrer',
+  'referer',
+  'request',
+  'req'
+])
+
+export class WoolError extends Error {
+  constructor(message, status = 0, response = null) {
+    super(message)
+    this.name = 'WoolError'
+    this.status = status
+    this.response = response
+  }
+}
+
+function cleanText(value, maxLength = 128) {
+  const text = String(value || '').trim()
+  return text.length > maxLength ? text.slice(0, maxLength) : text
+}
+
+function endpointFromApiUrl(value) {
+  const text = cleanText(value, 2048)
+  if (!text) return ''
+
+  try {
+    return new URL('/v1/events', text).toString()
+  } catch {
+    return ''
+  }
+}
+
+function resolveEndpoint(options) {
+  return cleanText(options.endpoint, 2048) || endpointFromApiUrl(options.apiUrl || options.apiHost) || DEFAULT_ENDPOINT
+}
+
+function isPlainObject(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value))
+}
+
+function cleanProperties(properties) {
+  if (!isPlainObject(properties)) return {}
+
+  const clean = {}
+  Object.keys(properties)
+    .filter((key) => !IDENTITY_KEY_PATTERN.test(key))
+    .slice(0, 12)
+    .forEach((key) => {
+      const value = properties[key]
+      if (value === undefined || value === null) return
+      if (typeof value === 'object') return
+      clean[key] = value
+    })
+
+  return clean
+}
+
+function identityValueFrom(source, keys) {
+  if (!isPlainObject(source)) return ''
+
+  for (const key of keys) {
+    const value = source[key]
+    if (value !== undefined && value !== null && String(value).trim()) return value
+  }
+
+  return ''
+}
+
+function applyIdentity(payload, state, properties, options) {
+  const retentionId =
+    identityValueFrom(options, ['retentionId', 'retention_id', 'subjectKey', 'subject_key', 'anonymousId', 'anonymous_id']) ||
+    identityValueFrom(properties, ['retentionId', 'retention_id', 'subjectKey', 'subject_key', 'anonymousId', 'anonymous_id']) ||
+    state.identity.retentionId
+  const groupKey =
+    identityValueFrom(options, ['groupKey', 'group_key']) ||
+    identityValueFrom(properties, ['groupKey', 'group_key']) ||
+    state.identity.groupKey
+
+  if (retentionId) payload.retentionId = cleanText(retentionId)
+  if (groupKey) payload.groupKey = cleanText(groupKey)
+}
+
+function createEventId() {
+  const crypto = globalThis.crypto
+  if (crypto?.randomUUID) return crypto.randomUUID()
+  return `${Date.now()}-${Math.random().toString(36).slice(2)}`
+}
+
+function headersFrom(value) {
+  if (!value) return null
+
+  if (value instanceof Headers) return value
+  if (value.headers instanceof Headers) return value.headers
+  if (value.raw instanceof Headers) return value.raw
+
+  return {
+    get(name) {
+      const lower = String(name).toLowerCase()
+      const headers = value.headers || value
+      const direct = headers[name] ?? headers[lower]
+      if (Array.isArray(direct)) return direct.join(', ')
+      return direct === undefined || direct === null ? '' : String(direct)
+    }
+  }
+}
+
+function headerValue(headers, names) {
+  if (!headers) return ''
+
+  for (const name of names) {
+    const value = headers.get?.(name)
+    if (value) return String(value)
+  }
+
+  return ''
+}
+
+function hostFromRequest(input, headers) {
+  const host = headerValue(headers, ['x-forwarded-host', 'host'])
+  if (host) return host.split(',')[0].trim()
+
+  const hostname = input?.hostname || input?.headers?.host || ''
+  return Array.isArray(hostname) ? hostname[0] || '' : String(hostname || '')
+}
+
+function protocolFromRequest(input, headers) {
+  const protocol = headerValue(headers, ['x-forwarded-proto'])
+  if (protocol) return protocol.split(',')[0].trim()
+
+  if (input?.protocol) return String(input.protocol).replace(/:$/, '')
+  if (input?.socket?.encrypted || input?.connection?.encrypted) return 'https'
+  return 'https'
+}
+
+function urlFromRequest(input, headers) {
+  if (!input) return ''
+  if (typeof input === 'string') return input
+  if (input.url && /^https?:\/\//i.test(String(input.url))) return String(input.url)
+
+  const path = input.originalUrl || input.url || input.path || input.nextUrl?.pathname || ''
+  if (!path) return ''
+
+  const host = hostFromRequest(input, headers)
+  if (!host) return ''
+
+  return `${protocolFromRequest(input, headers)}://${host}${path.startsWith('/') ? path : `/${path}`}`
+}
+
+export function requestContext(input = {}, options = {}) {
+  const headers = headersFrom(input)
+  const url = cleanText(options.url, 2048) || urlFromRequest(input, headers)
+  const referrer =
+    cleanText(options.referrer || options.referer, 2048) || headerValue(headers, ['referer', 'referrer']) || ''
+
+  return {
+    url,
+    referrer
+  }
+}
+
+function trackOptionsFrom(options) {
+  if (!isPlainObject(options)) return {}
+
+  const clean = {}
+  for (const key of TRACK_OPTION_KEYS) {
+    if (options[key] !== undefined) clean[key] = options[key]
+  }
+
+  return clean
+}
+
+function resolveFetch(options) {
+  const fetcher = options.fetch || globalThis.fetch
+  if (typeof fetcher !== 'function') {
+    throw new WoolError('A fetch implementation is required.')
+  }
+
+  return fetcher
+}
+
+function createState(options) {
+  const projectId = cleanText(options.projectId || options.project_id, 96)
+  const apiKey = cleanText(options.apiKey || options.api_key, 4096)
+  const siteUrl = cleanText(options.siteUrl || options.site_url || options.url, 2048)
+
+  if (!projectId) throw new WoolError('projectId is required.')
+  if (!apiKey) throw new WoolError('apiKey is required.')
+
+  return {
+    projectId,
+    apiKey,
+    endpoint: resolveEndpoint(options),
+    defaultUrl: siteUrl,
+    defaultReferrer: cleanText(options.referrer || options.referer, 2048),
+    enabled: options.enabled !== false,
+    fetch: resolveFetch(options),
+    identity: {
+      retentionId: cleanText(options.retentionId || options.retention_id || options.subjectKey || options.subject_key),
+      groupKey: cleanText(options.groupKey || options.group_key)
+    }
+  }
+}
+
+function bodyFromResponse(response) {
+  return response?.text ? response.text().catch(() => '') : Promise.resolve('')
+}
+
+export function createClient(options = {}) {
+  const state = createState(options)
+
+  async function send(payload) {
+    if (!state.enabled) {
+      return { ok: true, status: 0, skipped: true }
+    }
+
+    const response = await state.fetch(state.endpoint, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${state.apiKey}`,
+        'Content-Type': 'application/json',
+        'X-Wool-SDK': `@wool-so/node/${VERSION}`
+      },
+      body: JSON.stringify(payload)
+    })
+
+    if (!response?.ok && response?.status !== 204) {
+      const body = await bodyFromResponse(response)
+      throw new WoolError(body || 'Unable to send Wool analytics event.', response?.status || 0, response || null)
+    }
+
+    return { ok: true, status: response?.status || 0, response }
+  }
+
+  function basePayload(type, options = {}) {
+    const context = requestContext(options.request || options.req, options)
+    const url = cleanText(context.url || state.defaultUrl, 2048)
+
+    if (!url) throw new WoolError('url or siteUrl is required.')
+
+    const payload = {
+      projectId: state.projectId,
+      type,
+      url,
+      referrer: cleanText(context.referrer || state.defaultReferrer, 2048),
+      v: VERSION
+    }
+
+    if (state.identity.retentionId) payload.retentionId = state.identity.retentionId
+    if (state.identity.groupKey) payload.groupKey = state.identity.groupKey
+
+    return payload
+  }
+
+  async function track(name, properties = {}, options = {}) {
+    const eventName = cleanText(name, 96)
+    if (!eventName) throw new WoolError('Event name is required.')
+
+    const opts = trackOptionsFrom(options)
+    const eventId = cleanText(opts.eventId || opts.id || createEventId(), 96)
+    const payload = {
+      ...basePayload('event', opts),
+      name: eventName,
+      properties: cleanProperties(properties),
+      source: cleanText(opts.source || 'server', 32),
+      eventId,
+      visitorKey: cleanText(opts.visitorKey || opts.visitor_key || eventId, 96)
+    }
+
+    applyIdentity(payload, state, properties, opts)
+
+    if (Number.isFinite(Number(opts.value))) payload.value = Number(opts.value)
+    if (opts.currency) payload.currency = cleanText(opts.currency, 16)
+    if (Number.isFinite(Number(opts.duration))) payload.duration = Number(opts.duration)
+    if (opts.nonInteractive || opts.non_interactive) payload.nonInteractive = true
+
+    return send(payload)
+  }
+
+  async function pageview(options = {}) {
+    return send(basePayload('pageview', options))
+  }
+
+  function identify(retentionId, options = {}) {
+    state.identity = {
+      retentionId: cleanText(retentionId),
+      groupKey: cleanText(options.groupKey || options.group_key)
+    }
+  }
+
+  function reset() {
+    state.identity = {
+      retentionId: '',
+      groupKey: ''
+    }
+  }
+
+  return {
+    identify,
+    pageview,
+    requestContext,
+    reset,
+    track
+  }
+}
+
+function clientFrom(input) {
+  return typeof input?.track === 'function' ? input : createClient(input)
+}
+
+export function expressMiddleware(input) {
+  const client = clientFrom(input)
+  return function woolExpressMiddleware(req, _res, next) {
+    req.wool = client
+    if (typeof next === 'function') next()
+  }
+}
+
+export const nestMiddleware = expressMiddleware
+
+export function fastifyPlugin(input) {
+  const client = clientFrom(input)
+  return function woolFastifyPlugin(fastify, _options, done) {
+    if (typeof fastify?.decorate === 'function') fastify.decorate('wool', client)
+    else if (fastify && typeof fastify === 'object') fastify.wool = client
+    if (typeof done === 'function') done()
+  }
+}
+
+export function honoMiddleware(input) {
+  const client = clientFrom(input)
+  return async function woolHonoMiddleware(c, next) {
+    if (typeof c?.set === 'function') c.set('wool', client)
+    else if (c && typeof c === 'object') c.wool = client
+    if (typeof next === 'function') await next()
+  }
+}
+
+let defaultClient = null
+
+export function init(options = {}) {
+  defaultClient = createClient(options)
+  return defaultClient
+}
+
+function requireDefaultClient() {
+  if (!defaultClient) throw new WoolError('Call init before using the default Wool client.')
+  return defaultClient
+}
+
+export function identify(retentionId, options) {
+  return requireDefaultClient().identify(retentionId, options)
+}
+
+export function reset() {
+  return requireDefaultClient().reset()
+}
+
+export function track(name, properties, options) {
+  return requireDefaultClient().track(name, properties, options)
+}
+
+export function pageview(options) {
+  return requireDefaultClient().pageview(options)
+}
+
+export const wool = {
+  init,
+  identify,
+  reset,
+  track,
+  pageview,
+  createClient,
+  requestContext,
+  expressMiddleware,
+  fastifyPlugin,
+  honoMiddleware,
+  nestMiddleware
+}
+
+export default wool