@genvoris/node 1.0.1 → 1.1.0

package/README.md

@@ -17,6 +17,7 @@ npm install @genvoris/node
 ```ts
 import Genvoris from '@genvoris/node';
 
+// Server-side only. Never expose GENVORIS_API_KEY in browser code.
 const gv = new Genvoris({ apiKey: process.env.GENVORIS_API_KEY! });
 
 // Create a customer
@@ -61,6 +62,47 @@ await gv.plans.archive(id)
 await gv.sessions.mint({ customerId, ttlSeconds? })
 ```
 
+### Events
+
+```ts
+await gv.events.track({
+  sessionId: 'session_12345678',
+  eventType: 'WIDGET_OPENED',
+  productId: 'sku_123',
+  productTitle: 'Linen Shirt',
+  pageUrl: 'https://store.example/products/linen-shirt',
+})
+
+await gv.events.trackBatch([
+  { sessionId, eventType: 'PHOTO_UPLOADED' },
+  { sessionId, eventType: 'TRYON_GENERATED', productId },
+])
+```
+
+### Conversions and returns
+
+```ts
+await gv.conversions.create({
+  orderId: 'order_1001',
+  platform: 'custom',
+  amountCents: 12900,
+  currency: 'USD',
+  quantity: 1,
+  productId: 'sku_123',
+  productTitle: 'Linen Shirt',
+  sessionId: 'session_12345678',
+  customerEmail: 'shopper@example.com',
+})
+
+await gv.returns.create({
+  orderId: 'order_1001',
+  platform: 'custom',
+  refundedAmountCents: 12900,
+  currency: 'USD',
+  reason: 'size_exchange',
+})
+```
+
 ### Webhooks
 
 ```ts
@@ -70,6 +112,16 @@ await gv.webhooks.test(id)
 await gv.webhooks.delete(id)
 ```
 
+## Hosted widget integration
+
+Use this SDK from your backend to mint short-lived customer session tokens, record conversions/returns, and verify webhooks. For browser-hosted widgets, route try-on and analytics calls through your own same-origin endpoint or another approved public-widget flow; do not place `gvk_live_...` keys in HTML or client JavaScript.
+
+A typical flow is:
+
+1. Backend uses `gv.customers.create(...)` and `gv.sessions.mint(...)`.
+2. Frontend loads `https://api.genvoris.org/widget.js?no_fab=1` with a same-origin `data-api-url`/`data-events-url` and the minted customer token.
+3. Backend records orders with `gv.conversions.create(...)` and refunds with `gv.returns.create(...)`.
+
 ## Webhook verification
 
 ```ts
@@ -118,7 +170,7 @@ The client automatically retries `429`, `502`, `503`, and `504` responses using
 
 ```ts
 const gv = new Genvoris({
-  apiKey: 'gvk_live_...',
+  apiKey: process.env.GENVORIS_API_KEY!,
   baseUrl: 'https://genvoris.org/api/v1', // default
   timeoutMs: 30_000,                       // default 30 s
   maxRetries: 3,                           // default 3

package/dist/index.d.mts

@@ -283,6 +283,82 @@ declare class WebhooksResource {
     static verify<T extends Record<string, unknown> = Record<string, unknown>>({ payload, header, secret, toleranceSeconds, }: WebhookVerifyOptions): GenvorisEvent<T>;
 }
 
+type WidgetEventType = 'WIDGET_OPENED' | 'PHOTO_UPLOADED' | 'TRYON_GENERATED' | 'TRYON_VIEWED' | 'RESULT_SHARED' | 'ADDED_TO_CART' | 'CHECKOUT_STARTED' | 'CLOSED';
+interface WidgetEventInput {
+    sessionId: string;
+    eventType: WidgetEventType;
+    productId?: string;
+    productTitle?: string;
+    pageUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+interface EventBatchInput {
+    events: WidgetEventInput[];
+}
+interface EventsAccepted {
+    accepted: number;
+}
+declare class EventsResource {
+    private readonly config;
+    constructor(config: GenvorisConfig);
+    /** Track one hosted-widget funnel event. */
+    track(event: WidgetEventInput): Promise<EventsAccepted>;
+    /** Track a batch of 1–50 hosted-widget funnel events. */
+    trackBatch(events: WidgetEventInput[]): Promise<EventsAccepted>;
+}
+
+type ConversionPlatform = 'shopify' | 'woocommerce' | 'custom';
+interface ConversionCreateParams {
+    /** Platform order ID. Duplicate order IDs are idempotently deduped per merchant/platform. */
+    orderId: string;
+    platform: ConversionPlatform;
+    /** Order value in integer cents. */
+    amountCents: number;
+    /** ISO 4217 currency code. Defaults to USD server-side. */
+    currency?: string;
+    quantity?: number;
+    productId?: string;
+    productTitle?: string;
+    /** Widget session ID for hard attribution. */
+    sessionId?: string;
+    /** Hashed by the portal before storage. */
+    customerEmail?: string;
+    /** Soft-attribution lookback window. Default: 1440 minutes. */
+    attributionWindowMinutes?: number;
+}
+interface ConversionEvent {
+    id: string;
+    attributedFromTryOn: boolean;
+    deduped?: boolean;
+}
+declare class ConversionsResource {
+    private readonly config;
+    constructor(config: GenvorisConfig);
+    /** Store an order conversion for attribution/lift analytics. */
+    create(params: ConversionCreateParams): Promise<ConversionEvent>;
+}
+
+interface ReturnCreateParams {
+    /** Platform order ID matching a conversion when possible. */
+    orderId: string;
+    platform: ConversionPlatform;
+    /** Refunded amount in integer cents. */
+    refundedAmountCents: number;
+    /** ISO 4217 currency code. Defaults to USD server-side. */
+    currency?: string;
+    reason?: string;
+}
+interface ReturnEvent {
+    id: string;
+    conversionEventId: string | null;
+}
+declare class ReturnsResource {
+    private readonly config;
+    constructor(config: GenvorisConfig);
+    /** Store a return/refund event for conversion and returns-saved analytics. */
+    create(params: ReturnCreateParams): Promise<ReturnEvent>;
+}
+
 declare class GenvorisAPIError extends Error {
     readonly status: number;
     readonly code: string;
@@ -340,7 +416,10 @@ declare class Genvoris {
     readonly plans: PlansResource;
     readonly sessions: SessionsResource;
     readonly webhooks: WebhooksResource;
+    readonly events: EventsResource;
+    readonly conversions: ConversionsResource;
+    readonly returns: ReturnsResource;
     constructor(config: GenvorisConfig);
 }
 
-export { type Customer, type CustomerCreateParams, type CustomerList, type CustomerListParams, type CustomerSession, type CustomerSessionList, type CustomerUpdateParams, type CustomerUsage, GenvorisAPIError, GenvorisAuthError, type GenvorisConfig, type GenvorisEvent, GenvorisRateLimitError, GenvorisValidationError, type MintedSession, type Plan, type PlanCreateParams, type PlanList, type PlanListParams, type PlanUpdateParams, type SessionMintParams, type WebhookCreateParams, type WebhookEndpoint, type WebhookEndpointList, type WebhookVerifyOptions, WebhooksResource, Genvoris as default };
+export { type ConversionCreateParams, type ConversionEvent, type ConversionPlatform, type Customer, type CustomerCreateParams, type CustomerList, type CustomerListParams, type CustomerSession, type CustomerSessionList, type CustomerUpdateParams, type CustomerUsage, type EventBatchInput, type EventsAccepted, GenvorisAPIError, GenvorisAuthError, type GenvorisConfig, type GenvorisEvent, GenvorisRateLimitError, GenvorisValidationError, type MintedSession, type Plan, type PlanCreateParams, type PlanList, type PlanListParams, type PlanUpdateParams, type ReturnCreateParams, type ReturnEvent, type SessionMintParams, type WebhookCreateParams, type WebhookEndpoint, type WebhookEndpointList, type WebhookVerifyOptions, WebhooksResource, type WidgetEventInput, type WidgetEventType, Genvoris as default };

package/dist/index.d.ts

@@ -283,6 +283,82 @@ declare class WebhooksResource {
     static verify<T extends Record<string, unknown> = Record<string, unknown>>({ payload, header, secret, toleranceSeconds, }: WebhookVerifyOptions): GenvorisEvent<T>;
 }
 
+type WidgetEventType = 'WIDGET_OPENED' | 'PHOTO_UPLOADED' | 'TRYON_GENERATED' | 'TRYON_VIEWED' | 'RESULT_SHARED' | 'ADDED_TO_CART' | 'CHECKOUT_STARTED' | 'CLOSED';
+interface WidgetEventInput {
+    sessionId: string;
+    eventType: WidgetEventType;
+    productId?: string;
+    productTitle?: string;
+    pageUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+interface EventBatchInput {
+    events: WidgetEventInput[];
+}
+interface EventsAccepted {
+    accepted: number;
+}
+declare class EventsResource {
+    private readonly config;
+    constructor(config: GenvorisConfig);
+    /** Track one hosted-widget funnel event. */
+    track(event: WidgetEventInput): Promise<EventsAccepted>;
+    /** Track a batch of 1–50 hosted-widget funnel events. */
+    trackBatch(events: WidgetEventInput[]): Promise<EventsAccepted>;
+}
+
+type ConversionPlatform = 'shopify' | 'woocommerce' | 'custom';
+interface ConversionCreateParams {
+    /** Platform order ID. Duplicate order IDs are idempotently deduped per merchant/platform. */
+    orderId: string;
+    platform: ConversionPlatform;
+    /** Order value in integer cents. */
+    amountCents: number;
+    /** ISO 4217 currency code. Defaults to USD server-side. */
+    currency?: string;
+    quantity?: number;
+    productId?: string;
+    productTitle?: string;
+    /** Widget session ID for hard attribution. */
+    sessionId?: string;
+    /** Hashed by the portal before storage. */
+    customerEmail?: string;
+    /** Soft-attribution lookback window. Default: 1440 minutes. */
+    attributionWindowMinutes?: number;
+}
+interface ConversionEvent {
+    id: string;
+    attributedFromTryOn: boolean;
+    deduped?: boolean;
+}
+declare class ConversionsResource {
+    private readonly config;
+    constructor(config: GenvorisConfig);
+    /** Store an order conversion for attribution/lift analytics. */
+    create(params: ConversionCreateParams): Promise<ConversionEvent>;
+}
+
+interface ReturnCreateParams {
+    /** Platform order ID matching a conversion when possible. */
+    orderId: string;
+    platform: ConversionPlatform;
+    /** Refunded amount in integer cents. */
+    refundedAmountCents: number;
+    /** ISO 4217 currency code. Defaults to USD server-side. */
+    currency?: string;
+    reason?: string;
+}
+interface ReturnEvent {
+    id: string;
+    conversionEventId: string | null;
+}
+declare class ReturnsResource {
+    private readonly config;
+    constructor(config: GenvorisConfig);
+    /** Store a return/refund event for conversion and returns-saved analytics. */
+    create(params: ReturnCreateParams): Promise<ReturnEvent>;
+}
+
 declare class GenvorisAPIError extends Error {
     readonly status: number;
     readonly code: string;
@@ -340,7 +416,10 @@ declare class Genvoris {
     readonly plans: PlansResource;
     readonly sessions: SessionsResource;
     readonly webhooks: WebhooksResource;
+    readonly events: EventsResource;
+    readonly conversions: ConversionsResource;
+    readonly returns: ReturnsResource;
     constructor(config: GenvorisConfig);
 }
 
-export { type Customer, type CustomerCreateParams, type CustomerList, type CustomerListParams, type CustomerSession, type CustomerSessionList, type CustomerUpdateParams, type CustomerUsage, GenvorisAPIError, GenvorisAuthError, type GenvorisConfig, type GenvorisEvent, GenvorisRateLimitError, GenvorisValidationError, type MintedSession, type Plan, type PlanCreateParams, type PlanList, type PlanListParams, type PlanUpdateParams, type SessionMintParams, type WebhookCreateParams, type WebhookEndpoint, type WebhookEndpointList, type WebhookVerifyOptions, WebhooksResource, Genvoris as default };
+export { type ConversionCreateParams, type ConversionEvent, type ConversionPlatform, type Customer, type CustomerCreateParams, type CustomerList, type CustomerListParams, type CustomerSession, type CustomerSessionList, type CustomerUpdateParams, type CustomerUsage, type EventBatchInput, type EventsAccepted, GenvorisAPIError, GenvorisAuthError, type GenvorisConfig, type GenvorisEvent, GenvorisRateLimitError, GenvorisValidationError, type MintedSession, type Plan, type PlanCreateParams, type PlanList, type PlanListParams, type PlanUpdateParams, type ReturnCreateParams, type ReturnEvent, type SessionMintParams, type WebhookCreateParams, type WebhookEndpoint, type WebhookEndpointList, type WebhookVerifyOptions, WebhooksResource, type WidgetEventInput, type WidgetEventType, Genvoris as default };

package/dist/index.js

@@ -64,7 +64,7 @@ var GenvorisValidationError = class extends GenvorisAPIError {
 var RETRY_STATUSES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
 var MAX_DELAY_MS = 8e3;
 var DEFAULT_BASE_URL = "https://genvoris.org/api/v1";
-var SDK_VERSION = "1.0.0";
+var SDK_VERSION = "1.1.0";
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -393,6 +393,55 @@ var WebhooksResource = class {
   }
 };
 
+// src/resources/events.ts
+var EventsResource = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /** Track one hosted-widget funnel event. */
+  track(event) {
+    return request(this.config, "/events", {
+      method: "POST",
+      body: event
+    });
+  }
+  /** Track a batch of 1–50 hosted-widget funnel events. */
+  trackBatch(events) {
+    return request(this.config, "/events", {
+      method: "POST",
+      body: { events }
+    });
+  }
+};
+
+// src/resources/conversions.ts
+var ConversionsResource = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /** Store an order conversion for attribution/lift analytics. */
+  create(params) {
+    return request(this.config, "/conversions", {
+      method: "POST",
+      body: params
+    });
+  }
+};
+
+// src/resources/returns.ts
+var ReturnsResource = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /** Store a return/refund event for conversion and returns-saved analytics. */
+  create(params) {
+    return request(this.config, "/returns", {
+      method: "POST",
+      body: params
+    });
+  }
+};
+
 // src/index.ts
 var Genvoris = class {
   constructor(config) {
@@ -403,6 +452,9 @@ var Genvoris = class {
     this.plans = new PlansResource(config);
     this.sessions = new SessionsResource(config);
     this.webhooks = new WebhooksResource(config);
+    this.events = new EventsResource(config);
+    this.conversions = new ConversionsResource(config);
+    this.returns = new ReturnsResource(config);
   }
 };
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.mjs

@@ -33,7 +33,7 @@ var GenvorisValidationError = class extends GenvorisAPIError {
 var RETRY_STATUSES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
 var MAX_DELAY_MS = 8e3;
 var DEFAULT_BASE_URL = "https://genvoris.org/api/v1";
-var SDK_VERSION = "1.0.0";
+var SDK_VERSION = "1.1.0";
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -362,6 +362,55 @@ var WebhooksResource = class {
   }
 };
 
+// src/resources/events.ts
+var EventsResource = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /** Track one hosted-widget funnel event. */
+  track(event) {
+    return request(this.config, "/events", {
+      method: "POST",
+      body: event
+    });
+  }
+  /** Track a batch of 1–50 hosted-widget funnel events. */
+  trackBatch(events) {
+    return request(this.config, "/events", {
+      method: "POST",
+      body: { events }
+    });
+  }
+};
+
+// src/resources/conversions.ts
+var ConversionsResource = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /** Store an order conversion for attribution/lift analytics. */
+  create(params) {
+    return request(this.config, "/conversions", {
+      method: "POST",
+      body: params
+    });
+  }
+};
+
+// src/resources/returns.ts
+var ReturnsResource = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /** Store a return/refund event for conversion and returns-saved analytics. */
+  create(params) {
+    return request(this.config, "/returns", {
+      method: "POST",
+      body: params
+    });
+  }
+};
+
 // src/index.ts
 var Genvoris = class {
   constructor(config) {
@@ -372,6 +421,9 @@ var Genvoris = class {
     this.plans = new PlansResource(config);
     this.sessions = new SessionsResource(config);
     this.webhooks = new WebhooksResource(config);
+    this.events = new EventsResource(config);
+    this.conversions = new ConversionsResource(config);
+    this.returns = new ReturnsResource(config);
   }
 };
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genvoris/node",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Official Node.js SDK for the Genvoris Virtual Try-On API",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",