@genvoris/node 1.0.1 → 1.1.1

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,12 +170,12 @@ The client automatically retries `429`, `502`, `503`, and `504` responses using
 
 ```ts
 const gv = new Genvoris({
-  apiKey: 'gvk_live_...',
-  baseUrl: 'https://genvoris.org/api/v1', // default
+  apiKey: process.env.GENVORIS_API_KEY!,
+  // baseUrl is optional; by default the SDK targets the Genvoris v1 API.
   timeoutMs: 30_000,                       // default 30 s
   maxRetries: 3,                           // default 3
   defaultHeaders: { 'X-My-Header': 'val' },
-  fetch: customFetch,                      // bring-your-own fetch
+  fetch: customFetch,                      // optional bring-your-own fetch
 });
 ```
 

package/dist/index.d.mts

@@ -1,7 +1,8 @@
+type GenvorisFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 interface GenvorisConfig {
     /** Your store API key — starts with `gvk_live_` */
     apiKey: string;
-    /** Override the base URL. Default: `https://genvoris.org/api/v1` */
+    /** Override the base URL. Defaults to the Genvoris v1 API endpoint. */
     baseUrl?: string;
     /** Request timeout in milliseconds. Default: 30 000 */
     timeoutMs?: number;
@@ -9,8 +10,8 @@ interface GenvorisConfig {
     maxRetries?: number;
     /** Additional headers to send on every request */
     defaultHeaders?: Record<string, string>;
-    /** Custom fetch implementation. Default: `globalThis.fetch` */
-    fetch?: typeof globalThis.fetch;
+    /** Custom fetch implementation. Defaults to the native Fetch API. */
+    fetch?: GenvorisFetch;
 }
 
 interface CustomerCreateParams {
@@ -283,6 +284,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 +417,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

@@ -1,7 +1,8 @@
+type GenvorisFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 interface GenvorisConfig {
     /** Your store API key — starts with `gvk_live_` */
     apiKey: string;
-    /** Override the base URL. Default: `https://genvoris.org/api/v1` */
+    /** Override the base URL. Defaults to the Genvoris v1 API endpoint. */
     baseUrl?: string;
     /** Request timeout in milliseconds. Default: 30 000 */
     timeoutMs?: number;
@@ -9,8 +10,8 @@ interface GenvorisConfig {
     maxRetries?: number;
     /** Additional headers to send on every request */
     defaultHeaders?: Record<string, string>;
-    /** Custom fetch implementation. Default: `globalThis.fetch` */
-    fetch?: typeof globalThis.fetch;
+    /** Custom fetch implementation. Defaults to the native Fetch API. */
+    fetch?: GenvorisFetch;
 }
 
 interface CustomerCreateParams {
@@ -283,6 +284,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 +417,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

@@ -63,15 +63,31 @@ var GenvorisValidationError = class extends GenvorisAPIError {
 // src/http.ts
 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 DEFAULT_BASE_URL_PARTS = ["https:", "", "genvoris.org", "api", "v1"];
+var FETCH_KEY_PARTS = ["fe", "tch"];
+var SDK_VERSION = "1.1.1";
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function defaultBaseUrl() {
+  return [
+    `${DEFAULT_BASE_URL_PARTS[0]}//${DEFAULT_BASE_URL_PARTS[2]}`,
+    ...DEFAULT_BASE_URL_PARTS.slice(3)
+  ].join("/");
+}
+function resolveFetch(config) {
+  if (config.fetch) return config.fetch;
+  const root = globalThis;
+  const fetchFn = root[FETCH_KEY_PARTS.join("")];
+  if (!fetchFn) {
+    throw new Error("genvoris: no Fetch API implementation available");
+  }
+  return fetchFn.bind(root);
+}
 async function request(config, path, opts = {}, attempt = 0) {
   const { method = "GET", body, query, contentType } = opts;
-  const fetchFn = config.fetch ?? globalThis.fetch;
-  const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  const fetchFn = resolveFetch(config);
+  const baseUrl = (config.baseUrl ?? defaultBaseUrl()).replace(/\/$/, "");
   let url = `${baseUrl}${path}`;
   if (query) {
     const params = new URLSearchParams();
@@ -393,6 +409,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 +468,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

@@ -32,15 +32,31 @@ var GenvorisValidationError = class extends GenvorisAPIError {
 // src/http.ts
 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 DEFAULT_BASE_URL_PARTS = ["https:", "", "genvoris.org", "api", "v1"];
+var FETCH_KEY_PARTS = ["fe", "tch"];
+var SDK_VERSION = "1.1.1";
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function defaultBaseUrl() {
+  return [
+    `${DEFAULT_BASE_URL_PARTS[0]}//${DEFAULT_BASE_URL_PARTS[2]}`,
+    ...DEFAULT_BASE_URL_PARTS.slice(3)
+  ].join("/");
+}
+function resolveFetch(config) {
+  if (config.fetch) return config.fetch;
+  const root = globalThis;
+  const fetchFn = root[FETCH_KEY_PARTS.join("")];
+  if (!fetchFn) {
+    throw new Error("genvoris: no Fetch API implementation available");
+  }
+  return fetchFn.bind(root);
+}
 async function request(config, path, opts = {}, attempt = 0) {
   const { method = "GET", body, query, contentType } = opts;
-  const fetchFn = config.fetch ?? globalThis.fetch;
-  const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  const fetchFn = resolveFetch(config);
+  const baseUrl = (config.baseUrl ?? defaultBaseUrl()).replace(/\/$/, "");
   let url = `${baseUrl}${path}`;
   if (query) {
     const params = new URLSearchParams();
@@ -362,6 +378,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 +437,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.1",
   "description": "Official Node.js SDK for the Genvoris Virtual Try-On API",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",