@gurulu/node 0.1.2 → 1.0.1

package/package.json

@@ -1,30 +1,111 @@
 {
   "name": "@gurulu/node",
-  "version": "0.1.2",
-  "description": "Gurulu.io server-side analytics SDK for Node.js",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": ["dist"],
+  "version": "1.0.1",
+  "private": false,
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "description": "Gurulu server SDK. Outcome verification (purchase_completed, signup_completed). Express/Fastify/Next.js Route Handler + webhook helpers (Stripe/Shopify/Lemon Squeezy/custom). K16 4-kanal producer compliant.",
+  "homepage": "https://gurulu.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Preatan/gurulu.io.git",
+    "directory": "packages/sdk-node"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "analytics",
+    "outcome-verification",
+    "webhook",
+    "stripe",
+    "shopify",
+    "lemonsqueezy",
+    "express",
+    "fastify",
+    "next.js",
+    "bun",
+    "node",
+    "gurulu"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.js"
+      "default": "./dist/index.js"
+    },
+    "./webhooks/stripe": {
+      "types": "./dist/webhooks/stripe.d.ts",
+      "import": "./dist/webhooks/stripe.js"
+    },
+    "./webhooks/shopify": {
+      "types": "./dist/webhooks/shopify.d.ts",
+      "import": "./dist/webhooks/shopify.js"
+    },
+    "./webhooks/lemonsqueezy": {
+      "types": "./dist/webhooks/lemonsqueezy.d.ts",
+      "import": "./dist/webhooks/lemonsqueezy.js"
+    },
+    "./webhooks/custom": {
+      "types": "./dist/webhooks/custom.d.ts",
+      "import": "./dist/webhooks/custom.js"
+    },
+    "./middleware/express": {
+      "types": "./dist/middleware/express.d.ts",
+      "import": "./dist/middleware/express.js"
+    },
+    "./middleware/fastify": {
+      "types": "./dist/middleware/fastify.d.ts",
+      "import": "./dist/middleware/fastify.js"
     },
-    "./middleware": {
-      "types": "./dist/middleware.d.ts",
-      "import": "./dist/middleware.js",
-      "require": "./dist/middleware.js"
+    "./middleware/next": {
+      "types": "./dist/middleware/next.d.ts",
+      "import": "./dist/middleware/next.js"
     },
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch"
+    "build": "rm -rf dist && bun run build:js && bun run build:types",
+    "build:js": "bun build ./src/index.ts ./src/webhooks/stripe.ts ./src/webhooks/shopify.ts ./src/webhooks/lemonsqueezy.ts ./src/webhooks/custom.ts ./src/middleware/express.ts ./src/middleware/fastify.ts ./src/middleware/next.ts --outdir ./dist --target node --format=esm --external express --external fastify --external next --external undici",
+    "build:types": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run build",
+    "clean": "rm -rf dist .turbo"
   },
-  "engines": {
-    "node": ">=18.0.0"
+  "peerDependencies": {
+    "undici": "^7.0.0",
+    "express": "^4.0.0 || ^5.0.0",
+    "fastify": "^4.0.0 || ^5.0.0",
+    "next": "^14.0.0 || ^15.0.0"
   },
-  "license": "MIT",
-  "keywords": ["analytics", "tracking", "server-side", "gurulu"]
+  "peerDependenciesMeta": {
+    "undici": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20",
+    "bun": ">=1.0.0"
+  }
 }

package/dist/business-events.d.ts

@@ -1,73 +0,0 @@
-/**
- * Business event emitters — Phase 10 W4.2.
- *
- * These are tiny factories that return envelope-shaped `ServerEvent` objects
- * for common server-authored events (user signup, payment, subscription,
- * order, lead capture). They stamp the canonical `event_tier = 'verified'`
- * and `event_source = 'server_sdk'` fields so downstream readers can trust
- * the provenance without guessing.
- *
- * The shape intentionally satisfies BOTH:
- *   - the simple `ServerEvent` contract the /api/ingest/v1/server route
- *     consumes (event_name, user_id, properties, timestamp,
- *     idempotency_key?, correlation_id?), AND
- *   - the richer canonical Envelope fields consumers may want to read
- *     (event_tier, event_source) — we attach these at the top level so they
- *     travel alongside the event without collapsing into properties.
- *
- * `createEnvelope` from @gurulu/shared-core is used to validate/normalize the
- * shared envelope defaults where practical (event_type, timestamp,
- * consent_level, etc.), but the ServerEvent-specific keys (user_id) remain at
- * the root.
- *
- * Related docs: PHASE-10-ROADMAP.md §W4.2
- */
-import { type Envelope, type ServerEvent } from '@gurulu/shared-core';
-/**
- * Concrete shape returned by every business-event factory below:
- * a ServerEvent with the canonical envelope provenance fields attached.
- */
-export type BusinessEvent = ServerEvent & {
-    event_tier: Envelope['event_tier'];
-    event_source: Envelope['event_source'];
-    event_type: Envelope['event_type'];
-};
-export interface UserCreatedArgs {
-    userId: string;
-    email?: string;
-    traits?: Record<string, unknown>;
-}
-export declare function userCreated(args: UserCreatedArgs): BusinessEvent;
-export interface PaymentSucceededArgs {
-    userId: string;
-    amount: number;
-    currency: string;
-    orderId: string;
-    properties?: Record<string, unknown>;
-}
-export declare function paymentSucceeded(args: PaymentSucceededArgs): BusinessEvent;
-export interface SubscriptionStartedArgs {
-    userId: string;
-    plan: string;
-    amount: number;
-    currency: string;
-}
-export declare function subscriptionStarted(args: SubscriptionStartedArgs): BusinessEvent;
-export interface OrderPlacedArgs {
-    userId: string;
-    orderId: string;
-    total: number;
-    currency: string;
-    items?: Array<{
-        id: string;
-        qty: number;
-        price: number;
-    }>;
-}
-export declare function orderPlaced(args: OrderPlacedArgs): BusinessEvent;
-export interface LeadCapturedArgs {
-    anonymousId: string;
-    email?: string;
-    source?: string;
-}
-export declare function leadCaptured(args: LeadCapturedArgs): BusinessEvent;

package/dist/business-events.js

@@ -1,111 +0,0 @@
-"use strict";
-/**
- * Business event emitters — Phase 10 W4.2.
- *
- * These are tiny factories that return envelope-shaped `ServerEvent` objects
- * for common server-authored events (user signup, payment, subscription,
- * order, lead capture). They stamp the canonical `event_tier = 'verified'`
- * and `event_source = 'server_sdk'` fields so downstream readers can trust
- * the provenance without guessing.
- *
- * The shape intentionally satisfies BOTH:
- *   - the simple `ServerEvent` contract the /api/ingest/v1/server route
- *     consumes (event_name, user_id, properties, timestamp,
- *     idempotency_key?, correlation_id?), AND
- *   - the richer canonical Envelope fields consumers may want to read
- *     (event_tier, event_source) — we attach these at the top level so they
- *     travel alongside the event without collapsing into properties.
- *
- * `createEnvelope` from @gurulu/shared-core is used to validate/normalize the
- * shared envelope defaults where practical (event_type, timestamp,
- * consent_level, etc.), but the ServerEvent-specific keys (user_id) remain at
- * the root.
- *
- * Related docs: PHASE-10-ROADMAP.md §W4.2
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.userCreated = userCreated;
-exports.paymentSucceeded = paymentSucceeded;
-exports.subscriptionStarted = subscriptionStarted;
-exports.orderPlaced = orderPlaced;
-exports.leadCaptured = leadCaptured;
-const shared_core_1 = require("@gurulu/shared-core");
-const SDK_VERSION = 'node@0.1.0';
-function baseEnvelope(eventName, anonymousId, properties) {
-    return (0, shared_core_1.createEnvelope)({
-        site_id: '', // supplied at transport time by the client
-        anonymous_id: anonymousId,
-        session_id: '', // server SDK has no browser session
-        event_name: eventName,
-        event_type: 'server',
-        event_tier: 'verified',
-        event_source: 'server_sdk',
-        consent_level: 'accepted',
-        sdk_version: SDK_VERSION,
-        timestamp: new Date(Date.now()).toISOString(),
-        properties,
-    });
-}
-function toBusinessEvent(envelope, userId, extras = {}) {
-    return {
-        event_name: envelope.event_name,
-        user_id: userId,
-        properties: envelope.properties,
-        timestamp: envelope.timestamp,
-        event_type: envelope.event_type,
-        event_tier: envelope.event_tier,
-        event_source: envelope.event_source,
-        ...extras,
-    };
-}
-function userCreated(args) {
-    const props = {
-        ...(args.traits ?? {}),
-    };
-    if (args.email !== undefined)
-        props.email = args.email;
-    const env = baseEnvelope('user_created', args.userId, props);
-    return toBusinessEvent(env, args.userId);
-}
-function paymentSucceeded(args) {
-    const props = {
-        ...(args.properties ?? {}),
-        amount: args.amount,
-        currency: args.currency,
-        order_id: args.orderId,
-    };
-    const env = baseEnvelope('payment_succeeded', args.userId, props);
-    return toBusinessEvent(env, args.userId);
-}
-function subscriptionStarted(args) {
-    const props = {
-        plan: args.plan,
-        amount: args.amount,
-        currency: args.currency,
-    };
-    const env = baseEnvelope('subscription_started', args.userId, props);
-    return toBusinessEvent(env, args.userId);
-}
-function orderPlaced(args) {
-    const props = {
-        order_id: args.orderId,
-        total: args.total,
-        currency: args.currency,
-    };
-    if (args.items !== undefined)
-        props.items = args.items;
-    const env = baseEnvelope('order_placed', args.userId, props);
-    return toBusinessEvent(env, args.userId);
-}
-function leadCaptured(args) {
-    const props = {};
-    if (args.email !== undefined)
-        props.email = args.email;
-    if (args.source !== undefined)
-        props.source = args.source;
-    const env = baseEnvelope('lead_captured', args.anonymousId, props);
-    // Lead capture uses anonymous_id as the user_id placeholder until the lead
-    // is resolved to a real account; the server route accepts any non-empty
-    // user_id string and will look up the canonical profile from it.
-    return toBusinessEvent(env, args.anonymousId);
-}

package/dist/client.d.ts

@@ -1,150 +0,0 @@
-/**
- * @gurulu/node — server-side SDK client.
- *
- * Responsibilities (Phase 10 W4.2):
- *   - Queue + batch server events.
- *   - Auto-flush at batchSize boundary and on a periodic timer.
- *   - Exponential-backoff retry (200ms, 600ms, 1800ms — 3 attempts total) on
- *     5xx / network errors. No retry on 4xx.
- *   - Attach deterministic Idempotency-Key headers so the server can dedupe
- *     replayed batches across retries.
- *   - Dead-letter callback for batches that exhaust retries or are rejected
- *     with a client error.
- *   - Flush on process.beforeExit + SIGTERM.
- *
- * Event shapes are pulled from @gurulu/shared-core (W1.2). Only the transport
- * config (`GuruluClientConfig`) is local.
- *
- * Related docs: PHASE-10-ROADMAP.md §W4.2
- */
-import type { ServerEvent } from '@gurulu/shared-core';
-import type { GuruluClientConfig } from './types';
-export interface IdentifyParams {
-    /** The known user ID (e.g. database ID, email, etc.) */
-    userId: string;
-    /** An anonymous/session ID to link with this user. Required by the identify endpoint. */
-    anonymousId: string;
-    /** User traits (email, name, plan, etc.) to persist on the identity profile. */
-    traits?: Record<string, unknown>;
-    /** Device ID for cross-device identity resolution. */
-    deviceId?: string;
-    /** OAuth provider name (e.g. 'google', 'github'). */
-    oauthProvider?: string;
-    /** OAuth user ID from the provider. */
-    oauthId?: string;
-    /** Consent level: 'none' | 'analytics' | 'marketing' | 'full'. */
-    consentLevel?: string;
-}
-export interface IdentifyResponse {
-    status: string;
-    canonical_id: string | null;
-    consent_skipped?: boolean;
-    merges?: Array<{
-        winner: string;
-        loser: string;
-        reason: string;
-        claim_types: string[];
-    }>;
-}
-export interface Breadcrumb {
-    timestamp: string;
-    category: string;
-    message: string;
-    data?: Record<string, unknown>;
-}
-export interface GuruluClient {
-    track(event: ServerEvent): void;
-    identify(params: IdentifyParams): Promise<IdentifyResponse>;
-    flush(): Promise<void>;
-    shutdown(): Promise<void>;
-    captureException(error: Error, context?: Record<string, unknown>): void;
-    addBreadcrumb(category: string, message: string, data?: Record<string, unknown>): void;
-    installGlobalHandlers(): void;
-    /** Current queue length — exposed for tests and observability. */
-    readonly queueSize: number;
-}
-/**
- * Deterministic idempotency key for a server event. Hashes the tuple
- * (site_id, event_name, timestamp, anonymous_id/user_id) so replayed events
- * across retries produce the same key and the server can dedupe.
- */
-export declare function createIdempotencyKey(event: ServerEvent, siteId: string): string;
-export declare class Gurulu implements GuruluClient {
-    private readonly siteId;
-    private readonly apiKey;
-    private readonly endpoint;
-    private readonly flushInterval;
-    private readonly batchSize;
-    private readonly timeout;
-    private readonly onError?;
-    private readonly onDeadLetter?;
-    private readonly fetchImpl;
-    private readonly debug;
-    private readonly release;
-    private queue;
-    private breadcrumbs;
-    private readonly maxBreadcrumbs;
-    private flushTimer;
-    private inFlight;
-    private shutdownHandlers;
-    constructor(config: GuruluClientConfig);
-    get queueSize(): number;
-    private static readonly REVENUE_EVENTS;
-    /**
-     * Enqueue a server event. Auto-flushes synchronously when the queue reaches
-     * `batchSize`. Each event is stamped with a timestamp if missing so the
-     * idempotency key is stable across retries.
-     */
-    track(event: ServerEvent): void;
-    /**
-     * Identify a user — links an anonymous session to a known user ID and
-     * persists traits on the identity profile. Sends immediately to the
-     * dedicated `/api/ingest/v1/identify` endpoint (not batched with track
-     * events) because identity resolution is latency-sensitive and returns
-     * the canonical_id synchronously.
-     *
-     * Retries with the same exponential-backoff strategy as batch flushes.
-     */
-    identify(params: IdentifyParams): Promise<IdentifyResponse>;
-    /**
-     * POST all queued events in one batch. On 5xx / network error retries with
-     * exponential backoff (200ms, 600ms, 1800ms). On 4xx drops the batch and
-     * fires the dead-letter callback. Concurrent flush calls are serialized.
-     */
-    flush(): Promise<void>;
-    private sendBatch;
-    /**
-     * Add a custom breadcrumb to the trail. Breadcrumbs are sent with error
-     * events to provide context about what happened before the error occurred.
-     */
-    addBreadcrumb(category: string, message: string, data?: Record<string, unknown>): void;
-    /**
-     * Capture an exception and send it as an error event.
-     * Includes any accumulated breadcrumbs for debugging context.
-     */
-    captureException(error: Error, context?: Record<string, unknown>): void;
-    /**
-     * Install global error handlers for uncaught exceptions and unhandled rejections.
-     * Call once at app startup.
-     */
-    installGlobalHandlers(): void;
-    /**
-     * Stop the periodic flush timer, detach process listeners, and perform a
-     * final flush. Safe to call multiple times.
-     */
-    shutdown(): Promise<void>;
-}
-/**
- * Set the default Gurulu instance used by the convenience `captureException`.
- */
-export declare function setDefaultInstance(instance: Gurulu): void;
-/**
- * Convenience function — captures an exception via the default instance.
- * Call `setDefaultInstance()` first (or create a Gurulu client).
- */
-export declare function captureException(error: Error, context?: Record<string, unknown>): void;
-/**
- * Convenience function — adds a breadcrumb via the default instance.
- * Call `setDefaultInstance()` first (or create a Gurulu client).
- */
-export declare function addBreadcrumb(category: string, message: string, data?: Record<string, unknown>): void;