@gurulu/node 0.1.1 → 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 MONAFY LTD (UK Company No. 17031485)
+4 Raven Road, Unit 1C3-1051, London, United Kingdom, E18 1HB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,49 +1,82 @@
 # @gurulu/node
 
-Server-side analytics SDK for Gurulu.io. Tracks events, identifies users, and batches requests with automatic retries.
+Server SDK for [Gurulu](https://gurulu.io) — Truth Layer for product analytics.
 
-## Installation
+Outcome verification, webhook ingestion, and framework middleware for Node.js / Bun.
+
+## Install
 
 ```bash
 npm install @gurulu/node
+# or
+bun add @gurulu/node
 ```
 
-## Usage
+## Quick start
 
-```typescript
-import { Gurulu } from '@gurulu/node';
+```ts
+import { createGurulu } from '@gurulu/node';
 
-const gurulu = new Gurulu({
-  siteId: 'your-site-id',
-  apiKey: 'your-api-key',
+const gurulu = createGurulu({
+  workspace: 'pk_xxxxxxxxxxxx',
+  apiKey: process.env.GURULU_API_KEY,
 });
 
-// Track an event
-gurulu.track('purchase_completed', { amount: 49.99, currency: 'USD' }, {
-  userId: 'user-123',
+// Server-truth event (verified outcome, not client-claimed)
+await gurulu.track('purchase.completed', {
+  user_id: 'u_42',
+  order_id: 'o_123',
+  total: 49.99,
+  currency: 'USD',
 });
+```
 
-// Identify a user
-gurulu.identify('user-123', {
-  email: 'user@example.com',
-  plan: 'pro',
-});
+## Framework middleware
+
+```ts
+// Express
+import { guruluMiddleware } from '@gurulu/node/middleware/express';
+app.use(guruluMiddleware({ workspace: 'pk_xxx' }));
+
+// Fastify
+import { guruluPlugin } from '@gurulu/node/middleware/fastify';
+fastify.register(guruluPlugin, { workspace: 'pk_xxx' });
+
+// Next.js (Route Handler)
+import { guruluHandler } from '@gurulu/node/middleware/next';
+export const POST = guruluHandler({ workspace: 'pk_xxx' });
+```
+
+## Webhook helpers
 
-// Manually flush the event queue
-await gurulu.flush();
+Signature-verified, automatically mapped to canonical events:
 
-// Graceful shutdown (flushes remaining events and stops the timer)
-await gurulu.shutdown();
+```ts
+import { handleStripeWebhook } from '@gurulu/node/webhooks/stripe';
+// Also: /webhooks/shopify, /webhooks/lemonsqueezy, /webhooks/custom
+
+app.post('/webhooks/stripe', async (req, res) => {
+  const event = await handleStripeWebhook(req, {
+    secret: process.env.STRIPE_WEBHOOK_SECRET,
+    workspace: 'pk_xxx',
+  });
+  res.json({ ok: true });
+});
 ```
 
-## Configuration
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `siteId` | `string` | **required** | Your Gurulu site ID |
-| `apiKey` | `string` | **required** | Your Gurulu API key |
-| `endpoint` | `string` | `https://app.gurulu.io/api/ingest/v1/server` | Custom ingest endpoint |
-| `flushInterval` | `number` | `10000` | Auto-flush interval in ms |
-| `maxBatchSize` | `number` | `50` | Max events per batch |
-| `maxRetries` | `number` | `3` | Retry count for failed requests |
-| `debug` | `boolean` | `false` | Enable debug logging |
+## Features
+
+- **Outcome verification** — browser claims `purchase_initiated`; server confirms `purchase.completed` as truth.
+- **Webhook helpers** — Stripe, Shopify, Lemon Squeezy with signature verify + canonical event mapping.
+- **Framework middleware** — Express 4/5, Fastify 4/5, Next.js 14/15 Route Handlers.
+- **Type-safe** — registry-bound event types via codegen.
+
+## Documentation
+
+[gurulu.io/docs](https://gurulu.io/docs)
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+Copyright © 2026 MONAFY LTD (UK Company No. 17031485).

package/dist/context.d.ts

@@ -0,0 +1,12 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { ServerContext } from './types.ts';
+export declare const contextStorage: AsyncLocalStorage<ServerContext>;
+/** Middleware tarafından kullanılır — callback içinde tüm async call'lar context'i görür. */
+export declare function runWithContext<T>(ctx: ServerContext, fn: () => T): T;
+/** Mevcut store'u getir (yoksa undefined). */
+export declare function getContext(): ServerContext | undefined;
+/** Merge: explicit context (track/identify call) > stored context > empty. */
+export declare function mergeContext(explicit?: ServerContext): ServerContext;
+/** Random UUID-ish request_id (Node 20+ crypto.randomUUID native). */
+export declare function generateRequestId(): string;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,eAAO,MAAM,cAAc,kCAAyC,CAAC;AAErE,6FAA6F;AAC7F,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEpE;AAED,8CAA8C;AAC9C,wBAAgB,UAAU,IAAI,aAAa,GAAG,SAAS,CAEtD;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,QAAQ,CAAC,EAAE,aAAa,GAAG,aAAa,CAWpE;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,IAAI,MAAM,CAG1C"}

package/dist/core.d.ts

@@ -0,0 +1,60 @@
+import { type ExpressMiddlewareOptions } from './middleware/express.ts';
+import { type FastifyPluginOptions } from './middleware/fastify.ts';
+import { createNextHandler, type NextHandlerOptions } from './middleware/next.ts';
+import type { EventClass, FlushResult, IdentifyResult, IdentifyTraits, OutgoingEvent, ServerContext, ServerSDKConfig, TrackResult } from './types.ts';
+import { type CreateCustomWebhookOptions, type CustomWebhookHandler } from './webhooks/custom.ts';
+export declare class Gurulu {
+    private config;
+    private queue;
+    private sigtermBound;
+    private sigtermHandler;
+    constructor(initial?: ServerSDKConfig);
+    /** Initialize SDK. May be called once (idempotent guard). */
+    init(input: ServerSDKConfig): void;
+    private requireConfig;
+    /** Server-side identify (backend doğrulanmış user). */
+    identify(externalUserId: string, traits?: IdentifyTraits, explicitContext?: ServerContext): Promise<IdentifyResult>;
+    /** Outcome event track (queue + auto-flush). */
+    track(eventKey: string, properties?: Record<string, unknown>, explicitContext?: ServerContext, eventType?: EventClass): TrackResult;
+    /** Manual flush (force send current queue). */
+    flush(): Promise<FlushResult>;
+    /** Graceful shutdown — flush + cancel timer + max 10s timeout. */
+    shutdown(timeoutMs?: number): Promise<FlushResult>;
+    private bindSignals;
+    private unbindSignals;
+    /** Webhook helpers (lazy-bound to enqueue). */
+    get webhooks(): {
+        stripe: {
+            verify: (rawBody: string, sig: string | undefined, secret: string) => void;
+            map: (payload: import("./webhooks/stripe.ts").StripeEventPayload, options?: import("./index.ts").StripeHandleOptions) => OutgoingEvent;
+            handle: (req: import("./webhooks/stripe.ts").StripeHandleReq, secret: string, options?: import("./index.ts").StripeHandleOptions) => Promise<import("./types.ts").HandleResult>;
+        };
+        shopify: {
+            verify: typeof import("./index.ts").verifyShopify;
+            map: typeof import("./index.ts").mapShopifyEvent;
+            handle: (req: import("./webhooks/shopify.ts").ShopifyHandleReq, secret: string, options?: import("./index.ts").ShopifyHandleOptions) => Promise<import("./types.ts").HandleResult>;
+        };
+        lemonsqueezy: {
+            verify: typeof import("./index.ts").verifyLemonSqueezy;
+            map: typeof import("./index.ts").mapLemonSqueezyEvent;
+            handle: (req: import("./webhooks/lemonsqueezy.ts").LemonSqueezyHandleReq, secret: string, options?: import("./index.ts").LemonSqueezyHandleOptions) => Promise<import("./types.ts").HandleResult>;
+        };
+        custom: (options: CreateCustomWebhookOptions) => CustomWebhookHandler;
+    };
+    /** Framework integrations (middleware factories). */
+    get express(): {
+        middleware: (opts?: ExpressMiddlewareOptions) => (req: import("./middleware/express.ts").ExpressReqLike, res: import("./middleware/express.ts").ExpressResLike, next: import("./middleware/express.ts").NextFn) => void;
+    };
+    get fastify(): {
+        plugin: (opts?: FastifyPluginOptions) => (fastify: import("./middleware/fastify.ts").FastifyInstanceLike) => Promise<void>;
+    };
+    get next(): {
+        handler: typeof createNextHandler;
+    };
+}
+/** Convenience factory — `const gurulu = createGurulu({ workspaceKey: 'sk_...' });`. */
+export declare function createGurulu(config: ServerSDKConfig): Gurulu;
+export declare function getDefault(): Gurulu;
+export declare function initDefault(config: ServerSDKConfig): Gurulu;
+export type { ExpressMiddlewareOptions, FastifyPluginOptions, NextHandlerOptions };
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAKA,OAAO,EAA2B,KAAK,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACjG,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAIlF,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,cAAc,EACd,cAAc,EACd,aAAa,EAGb,aAAa,EACb,eAAe,EACf,WAAW,EACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,0BAA0B,EAC/B,KAAK,oBAAoB,EAE1B,MAAM,sBAAsB,CAAC;AA2C9B,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,cAAc,CAA6B;gBAEvC,OAAO,CAAC,EAAE,eAAe;IAIrC,6DAA6D;IAC7D,IAAI,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAOlC,OAAO,CAAC,aAAa;IAKrB,uDAAuD;IACjD,QAAQ,CACZ,cAAc,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,cAAc,EACvB,eAAe,CAAC,EAAE,aAAa,GAC9B,OAAO,CAAC,cAAc,CAAC;IAO1B,gDAAgD;IAChD,KAAK,CACH,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,eAAe,CAAC,EAAE,aAAa,EAC/B,SAAS,GAAE,UAAsB,GAChC,WAAW;IAad,+CAA+C;IACzC,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;IAKnC,kEAAkE;IAC5D,QAAQ,CAAC,SAAS,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;IASxD,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,aAAa;IAUrB,+CAA+C;IAC/C,IAAI,QAAQ;;;qFA5BS,CAAC;iGAOnB,CAAC;;;;;mGAjCgB,CAAC;;;;;6GAIQ,CAAC;;0BA2DR,0BAA0B,KAAG,oBAAoB;MAGtE;IAED,qDAAqD;IACrD,IAAI,OAAO;4BACoB,wBAAwB;MACtD;IAED,IAAI,OAAO;wBACgB,oBAAoB;MAC9C;IAED,IAAI,IAAI;;MAEP;CACF;AAED,wFAAwF;AACxF,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAE5D;AAKD,wBAAgB,UAAU,IAAI,MAAM,CAGnC;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAI3D;AAED,YAAY,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,32 @@
+export declare class GuruluSDKError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Init çağrılmadan track/identify. */
+export declare class NotInitializedError extends GuruluSDKError {
+    constructor();
+}
+/** workspaceKey formatı yanlış (sk_ prefix yok). */
+export declare class InvalidWorkspaceKeyError extends GuruluSDKError {
+    constructor(message: string);
+}
+/** Webhook signature verification fail. */
+export declare class WebhookSignatureError extends GuruluSDKError {
+    constructor(message: string);
+}
+/** Vendor event'i Gurulu mapping'inde yok. */
+export declare class WebhookMappingNotFoundError extends GuruluSDKError {
+    constructor(message: string);
+}
+/** Network/HTTP fail after retry exhaust. */
+export declare class TransportError extends GuruluSDKError {
+    readonly status?: number;
+    readonly attempts: number;
+    constructor(message: string, attempts: number, status?: number);
+}
+/** Queue overflow — drop oldest sırasında warn için. */
+export declare class QueueOverflowError extends GuruluSDKError {
+    readonly dropped: number;
+    constructor(dropped: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED,uCAAuC;AACvC,qBAAa,mBAAoB,SAAQ,cAAc;;CAItD;AAED,oDAAoD;AACpD,qBAAa,wBAAyB,SAAQ,cAAc;gBAC9C,OAAO,EAAE,MAAM;CAG5B;AAED,2CAA2C;AAC3C,qBAAa,qBAAsB,SAAQ,cAAc;gBAC3C,OAAO,EAAE,MAAM;CAG5B;AAED,8CAA8C;AAC9C,qBAAa,2BAA4B,SAAQ,cAAc;gBACjD,OAAO,EAAE,MAAM;CAG5B;AAED,6CAA6C;AAC7C,qBAAa,cAAe,SAAQ,cAAc;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBACd,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAK/D;AAED,wDAAwD;AACxD,qBAAa,kBAAmB,SAAQ,cAAc;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBACb,OAAO,EAAE,MAAM;CAI5B"}

package/dist/identify.d.ts

@@ -0,0 +1,9 @@
+import type { IdentifyTraits, OutgoingIdentify, ResolvedConfig, ServerContext } from './types.ts';
+export interface BuildIdentifyInput {
+    config: ResolvedConfig;
+    externalUserId: string;
+    traits?: IdentifyTraits;
+    explicitContext?: ServerContext;
+}
+export declare function buildIdentify(input: BuildIdentifyInput): OutgoingIdentify;
+//# sourceMappingURL=identify.d.ts.map

package/dist/identify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identify.d.ts","sourceRoot":"","sources":["../src/identify.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAElG,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,cAAc,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,eAAe,CAAC,EAAE,aAAa,CAAC;CACjC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,gBAAgB,CAqBzE"}

package/dist/index.d.ts

@@ -1,12 +1,13 @@
-/**
- * @gurulu/node — public entry point.
- *
- * Phase 10 W4.2: server SDK hardening adds batch+retry, deterministic
- * idempotency keys, dead-letter callbacks, and business event emitters.
- */
-export { Gurulu, createIdempotencyKey, captureException, setDefaultInstance } from './client';
-export type { GuruluClient } from './client';
-export type { GuruluClientConfig, DeadLetterCallback, ErrorCallback, } from './types';
-export type { Envelope, ServerEvent, EventTier, EventSource, ConsentLevel, } from '@gurulu/shared-core';
-export { userCreated, paymentSucceeded, subscriptionStarted, orderPlaced, leadCaptured, } from './business-events';
-export type { BusinessEvent, UserCreatedArgs, PaymentSucceededArgs, SubscriptionStartedArgs, OrderPlacedArgs, LeadCapturedArgs, } from './business-events';
+export declare const VERSION = "0.1.0";
+export { contextStorage, getContext, mergeContext, runWithContext } from './context.ts';
+export { createGurulu, Gurulu, getDefault, initDefault } from './core.ts';
+export { GuruluSDKError, InvalidWorkspaceKeyError, NotInitializedError, QueueOverflowError, TransportError, WebhookMappingNotFoundError, WebhookSignatureError, } from './errors.ts';
+export { createExpressMiddleware, type ExpressMiddlewareOptions, } from './middleware/express.ts';
+export { createFastifyPlugin, type FastifyPluginOptions } from './middleware/fastify.ts';
+export { createNextHandler, type NextHandlerOptions } from './middleware/next.ts';
+export type { EventClass, FlushResult, HandleResult, IdentifyResult, IdentifyTraits, OutgoingEvent, OutgoingIdentify, ServerConsentSnapshot, ServerContext, ServerProducer, ServerSDKConfig, TrackResult, } from './types.ts';
+export type { CreateCustomWebhookOptions, CustomMapResult } from './webhooks/custom.ts';
+export { LEMONSQUEEZY_DEFAULT_MAPPING, type LemonSqueezyHandleOptions, mapLemonSqueezyEvent, verifyLemonSqueezy, } from './webhooks/lemonsqueezy.ts';
+export { mapShopifyEvent, SHOPIFY_DEFAULT_MAPPING, type ShopifyHandleOptions, verifyShopify, } from './webhooks/shopify.ts';
+export { mapStripeEvent, STRIPE_DEFAULT_MAPPING, STRIPE_REPLAY_TOLERANCE_SECONDS, type StripeHandleOptions, verifyStripe, } from './webhooks/stripe.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkBA,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAExF,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG1E,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,uBAAuB,EACvB,KAAK,wBAAwB,GAC9B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,mBAAmB,EAAE,KAAK,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAElF,YAAY,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,0BAA0B,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAExF,OAAO,EACL,4BAA4B,EAC5B,KAAK,yBAAyB,EAC9B,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,KAAK,oBAAoB,EACzB,aAAa,GACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,+BAA+B,EAC/B,KAAK,mBAAmB,EACxB,YAAY,GACb,MAAM,sBAAsB,CAAC"}