@behindthescenes/analytics 0.0.9 → 0.0.11

package/README.md

@@ -1,63 +1,21 @@
 # `@behindthescenes/analytics`
 
-Browser SDK for BTS external-site analytics.
+Browser SDK for BTS external-site analytics. Track visitor behavior, capture conversion events, and maintain attribution across the customer journey.
 
-## What it does
+## Overview
 
-- Records standard web events such as `page_view`, `view_content`, `lead`, `sign_up`, `begin_checkout`, and `purchase`
-- Auto-tracks pageviews, SPA history changes, outbound clicks, button clicks, form submissions, safe GET search forms, and opt-in content views by default
-- Supports custom client-side events with `track(...)`
-- Preserves journey tokens, UTM params, and click IDs for downstream attribution and CAPI delivery
+The BTS Analytics SDK provides:
 
-## Auto-tracked events
+- **Automatic event tracking** - Page views, clicks, form submissions, and content views captured without code changes
+- **Conversion tracking** - Standard e-commerce and lead events (purchase, checkout, sign_up, lead)
+- **Cross-site attribution** - Journey tokens preserve visitor context across domains
+- **Attribution preservation** - UTM parameters and click IDs captured and persisted
+- **GoHighLevel integration** - Contact form submissions directly to GHL
+- **Google Analytics compatibility** - Detects existing GA installations or loads tags in proxy mode
 
-The SDK automatically captures events that can be detected safely from browser behavior:
+## Installation
 
-- `page_view`: initial page load and SPA navigation
-- `outbound_click`: links to external origins
-- `button_click`: clicks on `button`, `[role="button"]`, or `[data-bts-track-click]`
-- `form_submit`: form submissions
-- `search`: GET search forms with common query keys (`q`, `query`, `search`)
-- `view_content`: elements that opt in with `data-bts-view-content`
-
-Opt into automatic content-view tracking by marking elements that represent content cards, offers, posts, videos, or products:
-
-```html
-<article
-  data-bts-view-content="offer_123"
-  data-bts-content-type="offer"
-  data-bts-content-title="Creator Accelerator"
->
-  Creator Accelerator
-</article>
-```
-
-Identity, purchases, signups, payment steps, and arbitrary custom events are not auto-detected because they need product context. Call those explicitly after your app knows what happened.
-
-```ts
-// analytics.identify("user_123", { email: "fan@example.com" });
-// analytics.track("watch_preview_clicked", { placement: "hero" });
-// analytics.trackStandard("lead", { formId: "newsletter" });
-// analytics.trackStandard("sign_up", { method: "email" });
-// analytics.trackStandard("begin_checkout", { checkoutId: "offer_123" });
-// analytics.trackStandard("add_payment_info", { checkoutId: "offer_123" });
-// analytics.trackStandard("purchase", { orderId: "order_123", monetaryValue: 149 });
-// const { journeyToken } = await analytics.startFunnel("/landing");
-// const checkoutUrl = analytics.decorateUrl("https://behindthescenes.com/checkout", journeyToken);
-// await analytics.flushNow();
-```
-
-## Auto pageviews and SPA navigation
-
-- `**autoPageviews: false**` turns off the initial `page_view` **and** disables SPA history hooks (`pushState` / `replaceState` / `popstate`), so route changes do not emit automatic `page_view` events.
-- To track SPA navigations without the first-load pageview, pass an `autoTrack` object, for example `{ pageviews: false, history: true, outboundLinks: true, buttonClicks: true, formSubmissions: true, search: true, viewContent: true }`.
-
-## Flush reliability
-
-- If a batch flush fails (network error or non-2xx response), events are **put back on the queue** and a later flush is scheduled (including the keepalive path used when `requestHeaders` is set).
-- The default `sendBeacon` unload path cannot attach custom headers or observe success; use `requestHeaders` if you need the same retry semantics on `pagehide`.
-
-## Install from npm
+### npm/yarn/pnpm/bun
 
 ```bash
 npm install @behindthescenes/analytics
@@ -75,174 +33,458 @@ yarn add @behindthescenes/analytics
 bun add @behindthescenes/analytics
 ```
 
-```ts
-import { createBTSAnalytics } from "@behindthescenes/analytics";
+### Browser Bundle (Hosted)
 
-const analytics = createBTSAnalytics({
-  siteKey: "your-public-site-key",
-});
+```html
+<script type="module">
+  import { createBTSAnalytics } from "https://behindthescenes.com/sdk/analytics/latest/browser/browser.js";
 
-// Optional explicit-only examples:
-// analytics.identify("user_123", { email: "fan@example.com" });
-// analytics.track("video_played", { videoId: "intro-01" });
-// analytics.trackStandard("lead", { formId: "newsletter" });
-// analytics.trackStandard("begin_checkout", { checkoutId: "offer_123" });
-// const { journeyToken } = await analytics.startFunnel("/landing");
-// const checkoutUrl = analytics.decorateUrl("https://behindthescenes.com/checkout", journeyToken);
-// await analytics.flushNow();
+  window.btsAnalytics = createBTSAnalytics({
+    siteKey: "your-public-site-key"
+  });
+</script>
 ```
 
-## Endpoint Override
+## Quick Start
 
-The SDK defaults to the production BTS analytics endpoint. Override `endpoint` only for staging, local development, or a custom proxy.
+```typescript
+import { createBTSAnalytics } from "@behindthescenes/analytics";
 
-```ts
 const analytics = createBTSAnalytics({
   siteKey: "your-public-site-key",
-  endpoint: "https://staging-api.bts.dev/v2/website/analytics",
 });
 ```
 
-## Contact forms
+## Setup in BTS
 
-Use `submitContactForm(...)` when an external website needs to submit a simple contact enquiry into the space's GoHighLevel contact list.
+Before using the SDK, configure your site in the BTS platform:
 
-```ts
-await analytics.submitContactForm({
-  locationId: "your-ghl-location-id",
-  email: "fan@example.com",
-  subject: "Partnership enquiry",
-  body: "Tell us more about working together.",
-});
-```
+### 1. Get Your Site Key
 
-Required fields:
+- In BTS, navigate to your creator dashboard
+- Go to **Settings > Website Integration**
+- Copy your **Public Site Key**
 
-- `locationId`: the GoHighLevel location configured for the BTS space
-- `email`: the visitor's email address
-- `subject`: short enquiry subject
-- `body`: the message or "tell us more" text
+### 2. Configure GoHighLevel (Optional)
 
-Optional fields:
+For contact form submissions:
 
-- `name`, `firstName`, `lastName`: contact identity fields
-- `source`: defaults to `behind_the_scenes` when omitted
-- `tags`: extra GHL tags to attach to the contact
-- `customFields`: GHL custom fields to pass through directly
-- `metadata`: extra BTS metadata; values are forwarded as `bts_meta_<key>` contact fields
+- Go to **Settings > Integrations > GoHighLevel**
+- Connect your GHL account
+- Note your **Location ID** for use with `submitContactForm()`
 
-`subject` and `body` are also stored as BTS metadata fields on the GHL contact (`bts_meta_subject` and `bts_meta_body`). This helper creates or updates the contact only; it does not create a GHL opportunity.
+### 3. Enable External Site Tracking
 
-The SDK uses the production website analytics endpoint by default:
+Ensure your domain is added to the allowed domains list in your BTS space settings.
 
-```ts
-const analytics = createBTSAnalytics({
+## Framework Setup
+
+### React
+
+```tsx
+// BTSAnalyticsProvider.tsx
+import { createBTSAnalytics, BTSAnalytics } from "@behindthescenes/analytics";
+import { createContext, PropsWithChildren, useContext, useMemo } from "react";
+
+const BTSAnalyticsContext = createContext<BTSAnalytics | null>(null);
+
+export function BTSAnalyticsProvider({ children }: PropsWithChildren) {
+  const analytics = useMemo(() =>
+    createBTSAnalytics({
+      siteKey: "your-public-site-key",
+      autoPageviews: true,
+    }),
+    []
+  );
+
+  return (
+    <BTSAnalyticsContext.Provider value={analytics}>
+      {children}
+    </BTSAnalyticsContext.Provider>
+  );
+}
+
+export function useBTSAnalytics() {
+  const analytics = useContext(BTSAnalyticsContext);
+  if (!analytics) throw new Error("useBTSAnalytics must be used inside BTSAnalyticsProvider");
+  return analytics;
+}
+```
+
+Usage:
+```tsx
+const analytics = useBTSAnalytics();
+analytics.track("cta_clicked", { placement: "hero" });
+```
+
+### Next.js
+
+```tsx
+// app/providers.tsx
+"use client";
+
+import { createBTSAnalytics, BTSAnalytics } from "@behindthescenes/analytics";
+import { createContext, PropsWithChildren, useContext, useMemo } from "react";
+
+const BTSAnalyticsContext = createContext<BTSAnalytics | null>(null);
+
+export function Providers({ children }: PropsWithChildren) {
+  const analytics = useMemo(() =>
+    createBTSAnalytics({
+      siteKey: "your-public-site-key",
+      autoPageviews: true,
+    }),
+    []
+  );
+
+  return (
+    <BTSAnalyticsContext.Provider value={analytics}>
+      {children}
+    </BTSAnalyticsContext.Provider>
+  );
+}
+
+export function useBTSAnalytics() {
+  const analytics = useContext(BTSAnalyticsContext);
+  if (!analytics) throw new Error("useBTSAnalytics must be used inside Providers");
+  return analytics;
+}
+```
+
+### Remix
+
+```tsx
+// app/root.tsx
+import { createBTSAnalytics } from "@behindthescenes/analytics";
+import { useEffect, useMemo } from "react";
+import { Outlet, useLocation } from "react-router";
+
+export const analytics = createBTSAnalytics({
   siteKey: "your-public-site-key",
+  autoPageviews: false,
 });
-```
 
-`submitContactForm(...)` derives the sibling contact endpoint from the configured analytics URL and posts to `/v2/website/ghl/leads`.
+export function Layout() {
+  const location = useLocation();
+  const path = useMemo(() => location.pathname + location.search, [location]);
 
-Example form wiring:
+  useEffect(() => {
+    analytics.page(path);
+  }, [path]);
 
-```ts
-const form = document.querySelector<HTMLFormElement>("#contact-form");
+  return <Outlet />;
+}
+```
 
-form?.addEventListener("submit", async (event) => {
-  event.preventDefault();
+### Vue
 
-  const data = new FormData(form);
-  await analytics.submitContactForm({
-    locationId: "your-ghl-location-id",
-    email: String(data.get("email") ?? ""),
-    subject: String(data.get("subject") ?? ""),
-    body: String(data.get("body") ?? ""),
-    name: String(data.get("name") ?? ""),
-    metadata: {
-      page: window.location.pathname,
-    },
-  });
+```typescript
+// src/plugins/bts-analytics.ts
+import { createBTSAnalytics } from "@behindthescenes/analytics";
+import type { App } from "vue";
+
+export const analytics = createBTSAnalytics({
+  siteKey: "your-public-site-key",
+  autoPageviews: true,
 });
+
+export function installBTSAnalytics(app: App) {
+  app.provide("btsAnalytics", analytics);
+}
 ```
 
-## BTS-hosted browser bundle
+```vue
+<script setup lang="ts">
+import { inject } from "vue";
+import type { BTSAnalytics } from "@behindthescenes/analytics";
 
-```html
-<script type="module">
-  import { createBTSAnalytics } from "https://app.behindthescenes.com/sdk/analytics/latest/browser/browser.js";
+const analytics = inject<BTSAnalytics>("btsAnalytics")!;
 
-  window.btsAnalytics = createBTSAnalytics({
-    siteKey: "your-public-site-key"
-  });
+function trackEvent() {
+  analytics.track("button_clicked", { buttonId: "cta" });
+}
 </script>
 ```
 
-The hosted bundle is generated from `packages/analytics/dist` and synced into `apps/bts-web/public/sdk/analytics`.
+### Plain JavaScript
+
+```html
+<script async src="https://api.bts.it.com/v2/website/analytics/sdk/analytics/latest/browser/browser.js"></script>
+<script>
+  window.btsDataLayer = window.btsDataLayer || [];
+  function bts(){window.btsDataLayer.push(arguments);}
+  bts("js", new Date());
+  bts("config", "your-public-site-key", {
+    autoPageviews: true
+  });
+</script>
+```
 
-Release builds do not emit or publish source maps. The package build fails if any `.map` files are present in `dist`.
+**See the [docs folder](./docs) for complete framework guides:**
+- [Frameworks Guide](./docs/frameworks.md) - React, Next.js, Remix, Vue, Svelte, Angular, SolidJS
+- [Advanced Setup](./docs/advanced-setup.md) - Custom endpoints, request signing, GA integration, SPA config
+- [API Reference](./docs/api-reference.md) - Complete API documentation
 
-## Releases
+## Auto-Tracked Events
 
-Publishing the npm package bumps the version with standard semver release types:
+The SDK automatically captures these events without additional code:
 
-- `patch`: bug fixes and backwards-compatible corrections, for example `1.2.3` to `1.2.4`
-- `minor`: backwards-compatible features, for example `1.2.3` to `1.3.0`
-- `major`: breaking changes, for example `1.2.3` to `2.0.0`
+| Event | Trigger | Description |
+|-------|---------|-------------|
+| `page_view` | Page load, SPA navigation | Initial load and history changes |
+| `outbound_click` | External link clicks | Links to different origins |
+| `button_click` | Button interactions | `button`, `[role="button"]`, or `[data-bts-track-click]` |
+| `form_submit` | Form submissions | Any form submit event |
+| `search` | GET search forms | Forms with query params `q`, `query`, or `search` |
+| `view_content` | Element visibility | Elements with `data-bts-view-content` |
 
-Run the GitHub Actions release workflow manually and choose the release type to publish the next package version. The workflow reads the latest published npm version, increments it, validates the package, publishes it, and commits the updated `package.json` version.
+### Content View Tracking
 
-For local publishing, set the release type before running the publish script:
+Opt-in to automatic content-view tracking by marking elements:
 
-```sh
-RELEASE_TYPE=minor bun run release:publish
+```html
+<article
+  data-bts-view-content="offer_123"
+  data-bts-content-type="offer"
+  data-bts-content-title="Creator Accelerator"
+>
+  Creator Accelerator
+</article>
 ```
 
-## Standard events
+## Standard Events
 
-```ts
-analytics.trackStandard("view_content", {
-  contentId: "offer-42",
-});
+Use `trackStandard()` for built-in conversion and engagement events:
 
+```typescript
+// Engagement
+analytics.trackStandard("page_view");
+analytics.trackStandard("view_content", { contentId: "offer-42" });
+analytics.trackStandard("search", { query: "pricing" });
+
+// Lead & Account
+analytics.trackStandard("lead", { formId: "newsletter" });
+analytics.trackStandard("sign_up", { method: "email" });
+
+// E-commerce
+analytics.trackStandard("begin_checkout", { checkoutId: "offer_123" });
+analytics.trackStandard("add_payment_info", { checkoutId: "offer_123" });
 analytics.trackStandard("purchase", {
-  currency: "USD",
-  monetaryValue: 149,
   orderId: "order_123",
+  monetaryValue: 149,
+  currency: "USD"
 });
+
+// Engagement
+analytics.trackStandard("outbound_click", { url: "https://partner.com" });
+analytics.trackStandard("button_click", { buttonId: "cta-primary" });
+analytics.trackStandard("form_submit", { formId: "contact" });
 ```
 
-Supported standard events:
+### Legacy Event Aliases
 
-- `page_view`
-- `view_content`
-- `search`
-- `lead`
-- `sign_up`
-- `begin_checkout`
-- `add_payment_info`
-- `purchase`
-- `outbound_click`
-- `button_click`
-- `form_submit`
+These aliases are automatically normalized to standard events:
 
-Legacy aliases such as `lead_capture`, `registration_complete`, `checkout_started`, and `purchase_completed` are normalized into the standard conversion catalog.
+| Legacy Name | Standard Event |
+|-------------|----------------|
+| `$pageview` | `page_view` |
+| `checkout_started` | `begin_checkout` |
+| `lead_capture` | `lead` |
+| `purchase_completed` | `purchase` |
+| `registration_complete` | `sign_up` |
 
-## Custom events
+## Custom Events
+
+Track arbitrary events with custom properties:
+
+```typescript
+analytics.track("video_played", {
+  videoId: "intro-01",
+  duration: 120,
+  autoplay: false
+});
 
-```ts
 analytics.track("cta_clicked", {
   ctaId: "hero-primary",
   placement: "hero",
+  variant: "blue"
+});
+```
+
+## User Identification
+
+Associate events with a known user:
+
+```typescript
+analytics.identify("user_123", {
+  email: "fan@example.com",
+  name: "John Doe",
+  plan: "pro"
 });
 ```
 
-## Request signing headers
+## Contact Form Submission
+
+Submit contact enquiries directly to GoHighLevel:
+
+```typescript
+await analytics.submitContactForm({
+  locationId: "your-ghl-location-id",
+  email: "fan@example.com",
+  subject: "Partnership enquiry",
+  body: "Tell us more about working together.",
+  name: "Jane Smith",
+  source: "website_contact",
+  tags: ["partnership", "high-value"],
+  customFields: {
+    company: "Acme Inc"
+  },
+  metadata: {
+    page: window.location.pathname,
+    referrer: document.referrer
+  }
+});
+```
+
+### Required Fields
+
+- `locationId`: Your GoHighLevel location ID
+- At least one of `email` or `phone`
+
+### Optional Fields
+
+- `subject`, `body`: Message content (stored as `bts_meta_subject` and `bts_meta_body`)
+- `name`, `firstName`, `lastName`: Contact identity
+- `source`: Defaults to `behind_the_scenes`
+- `tags`: Array of GHL tags to attach
+- `customFields`: Direct GHL custom field mappings
+- `metadata`: Additional context forwarded as `bts_meta_<key>` fields
 
-Use `requestHeaders` to attach custom anti-spoof headers to every API request. The hook receives the serialized request body, so you can sign the exact payload being sent.
+## Journey Tracking (Cross-Site Attribution)
 
-```ts
+Track visitors across external sites and BTS properties:
+
+```typescript
+// Start a funnel journey
+const { journeyToken, journeyId, expiresAt } = await analytics.startFunnel("/landing");
+
+// Decorate BTS URLs with journey context
+const checkoutUrl = analytics.decorateUrl(
+  "https://behindthescenes.com/checkout",
+  journeyToken
+);
+
+// Get the persisted token for later use
+const token = analytics.getPersistedJourneyToken();
+
+// Notify handoff after visitor reaches BTS
+await analytics.notifyHandoff(journeyToken, {
+  source: "external_landing_page",
+  campaign: "summer_2024"
+});
+```
+
+## Configuration Options
+
+```typescript
 const analytics = createBTSAnalytics({
-  siteKey: "your-public-site-key",
+  siteKey: "required-site-key",
+
+  // Auto-tracking configuration
+  autoTrack: {
+    pageviews: true,        // Initial page_view + SPA navigation
+    history: true,          // pushState/replaceState hooks
+    outboundLinks: true,    // External link clicks
+    buttonClicks: true,     // Button interactions
+    formSubmissions: true,  // Form submit events
+    search: true,           // GET search forms
+    viewContent: true       // IntersectionObserver content views
+  },
+
+  // Or disable all auto-tracking
+  autoTrack: false,
+
+  // Legacy option: disable pageviews (also disables history hooks)
+  autoPageviews: false,
+
+  // Debug mode (logs to console)
+  debug: false,
+
+  // Flush interval in milliseconds (default: 300ms)
+  flushIntervalMs: 300,
+
+  // Google Analytics integration
+  googleAnalytics: {
+    loadTag: true,
+    measurementId: "G-XXXXXXXXXX"
+  },
+
+  // Custom request signing
+  requestHeaders: async ({ bodyText, path, headers }) => {
+    return {
+      ...headers,
+      "X-Signature": await signPayload(bodyText)
+    };
+  }
+});
+```
+
+### Auto-Tracking Behavior
+
+- `autoTrack: false` - Disables all automatic tracking
+- `autoPageviews: false` - Disables initial pageview and SPA navigation
+- Setting `pageviews: false` in `autoTrack` object also disables `history` hooks
+- Disabling pageviews prevents duplicate tracking when implementing custom pageview logic
+
+## Google Analytics Integration
+
+### Detection Mode (Default)
+
+The SDK automatically detects existing GA installations and includes context:
+
+- `ga_client_id`: From `_ga` cookie
+- `ga_tag_installed`: Boolean if gtag detected
+- `ga_measurement_id`: From script tag
+
+### Proxy Mode
+
+Load GA tag for scanner visibility while forwarding events server-side:
+
+```typescript
+const analytics = createBTSAnalytics({
+  siteKey: "your-site-key",
+  googleAnalytics: {
+    loadTag: true,
+    measurementId: "G-XXXXXXXXXX"
+  }
+});
+```
+
+This loads the Google tag with `send_page_view: false` so BTS can forward events while GA scanners detect an installed tag.
+
+## Attribution & UTM Parameters
+
+The SDK automatically captures and persists:
+
+**UTM Parameters:**
+- `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`
+
+**Click IDs:**
+- `fbclid`, `gclid`, `gbraid`, `wbraid`
+- `li_fat_id`, `msclkid`, `ttclid`
+
+**Cookies:**
+- `_fbp`, `_fbc` (Facebook Pixel)
+
+Attribution data is stored in localStorage and attached to every event, preserving the original landing URL and referrer across the session.
+
+## Request Signing
+
+Add custom headers for request validation:
+
+```typescript
+const analytics = createBTSAnalytics({
+  siteKey: "your-site-key",
   requestHeaders: async ({ bodyText, headers, path }) => {
     const timestamp = new Date().toISOString();
     const signature = await signAnalyticsPayload(`${timestamp}:${path}:${bodyText}`);
@@ -256,12 +498,88 @@ const analytics = createBTSAnalytics({
 });
 ```
 
-When `requestHeaders` is configured, page-unload flushes use `fetch(..., { keepalive: true })` instead of `sendBeacon`, because browsers do not allow custom headers on beacon requests.
+When `requestHeaders` is configured, the SDK uses `fetch(..., { keepalive: true })` instead of `sendBeacon` for page-unload events, enabling the same retry semantics for all requests.
+
+## Flush Reliability
+
+The SDK queues events and flushes them in batches:
 
-## Journeys
+- Automatic flush every 300ms (configurable)
+- Immediate flush when queue reaches 50 events
+- Failed batches are requeued and retried
+- Page unload uses `sendBeacon` (or `fetch` with `keepalive` when custom headers are set)
 
-```ts
-const { journeyToken } = await analytics.startFunnel();
-const checkoutUrl = analytics.decorateUrl("https://behindthescenes.com/checkout", journeyToken);
+### Manual Flush
+
+```typescript
+// Force immediate flush
+await analytics.flushNow();
 ```
 
+## Cleanup
+
+Remove event listeners and flush pending events:
+
+```typescript
+analytics.destroy();
+```
+
+This:
+- Removes click, submit, and navigation listeners
+- Disconnects IntersectionObserver and MutationObserver
+- Flushes any pending events
+- Prevents further event tracking
+
+## API Reference
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `track(eventName, properties?)` | Track a custom event |
+| `trackStandard(eventName, properties?)` | Track a standard event |
+| `identify(userId, traits?)` | Identify the current user |
+| `page(path?)` | Manually trigger a page view |
+| `startFunnel(entryPath?)` | Start a cross-site journey |
+| `decorateUrl(url, journeyToken?)` | Append site key and journey to URL |
+| `getPersistedJourneyToken()` | Get stored journey token |
+| `notifyHandoff(journeyToken, context?)` | Notify BTS of journey handoff |
+| `submitContactForm(input)` | Submit to GoHighLevel |
+| `flushNow()` | Immediately flush event queue |
+| `listStandardEvents()` | Get list of standard event names |
+| `destroy()` | Cleanup and remove listeners |
+
+### Types
+
+```typescript
+type BTSAnalyticsStandardEventName =
+  | "page_view"
+  | "view_content"
+  | "search"
+  | "lead"
+  | "sign_up"
+  | "begin_checkout"
+  | "add_payment_info"
+  | "purchase"
+  | "outbound_click"
+  | "button_click"
+  | "form_submit";
+
+type BTSAnalyticsEventType = "page_view" | "custom" | "identify" | "conversion";
+```
+
+## Releases
+
+Publishing the npm package bumps the version with standard semver release types:
+
+- `patch`: Bug fixes and backwards-compatible corrections (e.g., `1.2.3` to `1.2.4`)
+- `minor`: Backwards-compatible features (e.g., `1.2.3` to `1.3.0`)
+- `major`: Breaking changes (e.g., `1.2.3` to `2.0.0`)
+
+Run the GitHub Actions release workflow manually and choose the release type to publish the next package version. The workflow reads the latest published npm version, increments it, validates the package, publishes it, and commits the updated `package.json` version.
+
+For local publishing, set the release type before running the publish script:
+
+```sh
+RELEASE_TYPE=minor bun run release:publish
+```