@genvoris/node

Official Node.js SDK for the Genvoris Virtual Try-On API.

Requirements

Node.js 18 or higher (uses native fetch).

Installation

npm install @genvoris/node

Quick start

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
const customer = await gv.customers.create({
  externalId: 'user_42',
  email: '[email protected]',
  planId: 'pln_xxxxxxxx',
});

// Mint a session token for the widget
const session = await gv.sessions.mint({ customerId: customer.id });
// → pass session.token to your frontend

Resources

Customers

await gv.customers.create({ externalId, email?, planId?, metadata? })
await gv.customers.retrieve(id)
await gv.customers.update(id, { email?, planId?, status?, resetPeriod? })
await gv.customers.list({ status?, limit?, cursor? })
await gv.customers.cancel(id)
await gv.customers.usage(id)
await gv.customers.sessions(id)

Plans

await gv.plans.list({ include_inactive? })
await gv.plans.create({ name, monthlyTryOns, externalPriceId?, active? })
await gv.plans.retrieve(id)
await gv.plans.update(id, { name?, monthlyTryOns?, active? })
await gv.plans.archive(id)

Sessions

await gv.sessions.mint({ customerId, ttlSeconds? })

Events

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

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: '[email protected]',
})

await gv.returns.create({
  orderId: 'order_1001',
  platform: 'custom',
  refundedAmountCents: 12900,
  currency: 'USD',
  reason: 'size_exchange',
})

Webhooks

await gv.webhooks.list()
await gv.webhooks.create({ url, secret, events })
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

import { WebhooksResource } from '@genvoris/node';

// In your Express / Next.js handler — pass the raw body, not parsed JSON
const event = WebhooksResource.verify({
  payload: req.body,
  header: req.header('x-genvoris-signature') ?? '',
  secret: process.env.GENVORIS_WEBHOOK_SECRET!,
});

console.log(event.type, event.data);

The signature format is t=<unix>,v1=<hex>. The signed string is ${timestamp}.${rawBody} using HMAC-SHA256. Verification uses crypto.timingSafeEqual.

Error handling

import {
  GenvorisAPIError,
  GenvorisAuthError,
  GenvorisRateLimitError,
  GenvorisValidationError,
} from '@genvoris/node';

try {
  await gv.customers.retrieve('cus_missing');
} catch (err) {
  if (err instanceof GenvorisAuthError) {
    // 401 / 403 — bad or revoked key
  } else if (err instanceof GenvorisRateLimitError) {
    console.log(`retry after ${err.retryAfterSeconds}s`);
  } else if (err instanceof GenvorisValidationError) {
    console.error(err.fieldErrors);
  } else if (err instanceof GenvorisAPIError) {
    console.error(err.status, err.code, err.requestId);
  }
}

The client automatically retries 429, 502, 503, and 504 responses using exponential backoff with jitter (min(2^n × 250 ms, 8 000 ms)), up to maxRetries (default: 3).

Configuration

const gv = new Genvoris({
  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,                      // optional bring-your-own fetch
});

License

MIT — see LICENSE.