@morfoos/sdk

Framework-agnostic client SDK for Morfoos analytics. Decouples tracking from Next.js / React so any site can integrate with a single init + three track methods.

Install

npm install @morfoos/sdk

In this monorepo the package lives at packages/morfoos-sdk. Host apps must expose the track API routes (POST /api/track/page-view, /api/track/event, /api/track/conversion).

Quick start

import { morfoos } from "@morfoos/sdk";

morfoos.init({
  siteId: "site_your_site",
  apiUrl: "https://yoursite.com",
});

// Automatic path from window.location if omitted
morfoos.trackPageView();

morfoos.trackEvent("cta_click", {
  path: "/pricing",
  data: { label: "Start trial" },
});

morfoos.trackConversion("contact_form_submit", {
  path: "/contact",
  entityId: "contact_main",
});

apiUrl is normalized to absolute track endpoints:

• {apiUrl}/api/track/page-view
• {apiUrl}/api/track/event
• {apiUrl}/api/track/conversion

Override paths when needed:

morfoos.init({
  siteId: "site_your_site",
  apiUrl: "https://yoursite.com",
  endpoints: {
    pageView: "/api/track/page-view",
    event: "/api/track/event",
    conversion: "/api/track/conversion",
  },
});

Next.js (Morfoos OS)

Use @morfoos/morfoos-os for React providers and legacy helpers, or import the SDK directly:

"use client";
import { morfoos } from "@morfoos/sdk";
import { MorfoosAnalyticsProvider } from "@morfoos/morfoos-os/ui";

morfoos.init({
  siteId: process.env.NEXT_PUBLIC_SITE_ID!,
  apiUrl: process.env.NEXT_PUBLIC_SITE_URL!,
});

export function AnalyticsRoot({ children }) {
  return (
    <MorfoosAnalyticsProvider autoTrackClicks>
      {children}
    </MorfoosAnalyticsProvider>
  );
}

Legacy imports from @morfoos/morfoos-os/analytics/client delegate to the SDK and auto-init from NEXT_PUBLIC_SITE_ID / NEXT_PUBLIC_SITE_URL when morfoos.init() was not called yet.

Session identity

The SDK stores session_id in sessionStorage with a 30-minute inactivity window. Server responses may refresh the session id via sessionId in the JSON body.

Low-level send

morfoos.send(pipeline, payload, endpointOverride?) is available for framework adapters that need non-standard payloads (e.g. blog scroll metrics with kind: "blog_metric").

API

| Method | Description | |--------|-------------| | morfoos.init({ siteId, apiUrl, endpoints? }) | Required once before tracking | | morfoos.trackPageView(path?, endpoint?) | Page view pipeline | | morfoos.trackEvent(name, options?, endpoint?) | UI / chatbot events | | morfoos.trackConversion(typeOrEvent, options?, endpoint?) | Conversion pipeline | | morfoos.isInitialized() | Whether init ran | | morfoos.getConfig() | Current site id + resolved endpoints |