@genvoris/node 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Genvoris
+
+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

@@ -0,0 +1,132 @@
+# @genvoris/node
+
+Official Node.js SDK for the [Genvoris Virtual Try-On API](https://docs.genvoris.org).
+
+## Requirements
+
+Node.js **18** or higher (uses native `fetch`).
+
+## Installation
+
+```bash
+npm install @genvoris/node
+```
+
+## Quick start
+
+```ts
+import Genvoris from '@genvoris/node';
+
+const gv = new Genvoris({ apiKey: process.env.GENVORIS_API_KEY! });
+
+// Create a customer
+const customer = await gv.customers.create({
+  externalId: 'user_42',
+  email: 'shopper@example.com',
+  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
+
+```ts
+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
+
+```ts
+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
+
+```ts
+await gv.sessions.mint({ customerId, ttlSeconds? })
+```
+
+### Webhooks
+
+```ts
+await gv.webhooks.list()
+await gv.webhooks.create({ url, secret, events })
+await gv.webhooks.test(id)
+await gv.webhooks.delete(id)
+```
+
+## Webhook verification
+
+```ts
+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
+
+```ts
+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
+
+```ts
+const gv = new Genvoris({
+  apiKey: 'gvk_live_...',
+  baseUrl: 'https://genvoris.org/api/v1', // default
+  timeoutMs: 30_000,                       // default 30 s
+  maxRetries: 3,                           // default 3
+  defaultHeaders: { 'X-My-Header': 'val' },
+  fetch: customFetch,                      // bring-your-own fetch
+});
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/index.d.mts

@@ -0,0 +1,328 @@
+interface GenvorisConfig {
+    /** Your store API key — starts with `gvk_live_` */
+    apiKey: string;
+    /** Override the base URL. Default: `https://genvoris.org/api/v1` */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Default: 30 000 */
+    timeoutMs?: number;
+    /** Maximum number of retries on 429/502/503/504. Default: 3 */
+    maxRetries?: number;
+    /** Additional headers to send on every request */
+    defaultHeaders?: Record<string, string>;
+    /** Custom fetch implementation. Default: `globalThis.fetch` */
+    fetch?: typeof globalThis.fetch;
+}
+
+interface CustomerCreateParams {
+    /** Your stable external identifier. Re-POSTing with the same value upserts. */
+    externalId: string;
+    email?: string;
+    /** Plan to assign. No plan = every try-on returns 402. */
+    planId?: string;
+    /** Free-form metadata stored with the customer. */
+    metadata?: Record<string, unknown>;
+}
+interface CustomerUpdateParams {
+    email?: string | null;
+    /** Pass `null` to detach the plan. */
+    planId?: string | null;
+    status?: 'ACTIVE' | 'PAUSED' | 'CANCELLED';
+    metadata?: Record<string, unknown> | null;
+    /** When `true`, resets the period start to now and end to now + 30 days. */
+    resetPeriod?: boolean;
+}
+interface CustomerListParams {
+    status?: 'ACTIVE' | 'PAUSED' | 'CANCELLED';
+    /** 1–200. Default: 50. */
+    limit?: number;
+    /** Pagination cursor from the previous page's `next_cursor`. */
+    cursor?: string;
+}
+interface Customer {
+    id: string;
+    externalId: string;
+    email?: string | null;
+    planId?: string | null;
+    status: 'ACTIVE' | 'PAUSED' | 'CANCELLED';
+    createdAt: string;
+    updatedAt: string;
+    metadata?: Record<string, unknown> | null;
+}
+interface CustomerList {
+    data: Customer[];
+    next_cursor?: string | null;
+}
+interface CustomerUsage {
+    data: {
+        customer_id: string;
+        external_id: string;
+        plan: {
+            id: string;
+            name: string;
+            monthlyTryOns: number;
+        } | null;
+        status: string;
+        period_start: string;
+        period_end: string;
+        current: {
+            used: number;
+            limit: number;
+            remaining: number;
+            ok: boolean;
+        };
+        history: Array<{
+            period_start: string;
+            period_end: string;
+            used: number;
+            limit: number;
+        }>;
+    };
+}
+interface CustomerSession {
+    token: string;
+    expires_at: string;
+}
+interface CustomerSessionList {
+    data: CustomerSession[];
+}
+declare class CustomersResource {
+    private readonly config;
+    constructor(config: GenvorisConfig);
+    /** Create or upsert an end-customer. */
+    create(params: CustomerCreateParams): Promise<Customer>;
+    /** Retrieve a single customer by their Genvoris `id`. */
+    retrieve(id: string): Promise<Customer>;
+    /** Update a customer's email, plan, status, or metadata. */
+    update(id: string, params: CustomerUpdateParams): Promise<Customer>;
+    /** List customers with optional status filter and cursor pagination. */
+    list(params?: CustomerListParams): Promise<CustomerList>;
+    /** Soft-cancel a customer. Future try-ons return 402 `cancelled`. */
+    cancel(id: string): Promise<void>;
+    /** Return the customer's current-period quota state and usage history. */
+    usage(id: string): Promise<CustomerUsage>;
+    /** List active widget sessions for this customer. */
+    sessions(id: string): Promise<CustomerSessionList>;
+}
+
+interface PlanCreateParams {
+    /** Display name. 1–80 characters. */
+    name: string;
+    /** Monthly try-on quota. 1–1 000 000. */
+    monthlyTryOns: number;
+    /** Map back to your billing price ID (e.g. Stripe price_xxx). */
+    externalPriceId?: string;
+    /** Defaults to `true`. */
+    active?: boolean;
+}
+interface PlanUpdateParams {
+    name?: string;
+    monthlyTryOns?: number;
+    externalPriceId?: string;
+    active?: boolean;
+}
+interface PlanListParams {
+    /** Include soft-disabled plans. Default: `false`. */
+    include_inactive?: boolean;
+}
+interface Plan {
+    id: string;
+    name: string;
+    monthlyTryOns: number;
+    externalPriceId?: string | null;
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface PlanList {
+    data: Plan[];
+}
+declare class PlansResource {
+    private readonly config;
+    constructor(config: GenvorisConfig);
+    /** List all plans. Pass `{ include_inactive: true }` to include disabled ones. */
+    list(params?: PlanListParams): Promise<PlanList>;
+    /** Create a new plan. Returns `201 Created`. */
+    create(params: PlanCreateParams): Promise<Plan>;
+    /** Retrieve a single plan. */
+    retrieve(id: string): Promise<Plan>;
+    /** Update any plan fields. */
+    update(id: string, params: PlanUpdateParams): Promise<Plan>;
+    /**
+     * Soft-disable a plan. Existing customers keep quota until cancelled or
+     * reassigned. The plan stops appearing in `list()` unless `include_inactive`
+     * is `true`.
+     */
+    archive(id: string): Promise<void>;
+}
+
+interface SessionMintParams {
+    /** Genvoris customer ID or your `externalId`. */
+    customerId: string;
+    /** JWT lifetime in seconds. Default: 900 (15 min). */
+    ttlSeconds?: number;
+}
+interface MintedSession {
+    token: string;
+    token_type: 'Bearer';
+    /** Remaining lifetime in seconds at issuance. */
+    expires_in: number;
+    /** ISO-8601 expiry timestamp. */
+    expires_at: string;
+    customer: {
+        id: string;
+        external_id: string;
+        plan_name: string | null;
+        monthly_try_ons: number | null;
+        period_end: string | null;
+    };
+}
+declare class SessionsResource {
+    private readonly config;
+    constructor(config: GenvorisConfig);
+    /**
+     * Mint a short-lived widget session token for a customer.
+     *
+     * The token should be sent to your frontend and passed to the
+     * Genvoris widget — never exposed in client-side code directly.
+     */
+    mint({ customerId, ttlSeconds }: SessionMintParams): Promise<MintedSession>;
+}
+
+interface WebhookCreateParams {
+    /** HTTPS endpoint URL Genvoris will POST events to. */
+    url: string;
+    /** Signing secret — store this securely; shown only once in the dashboard. */
+    secret: string;
+    /** Event types to subscribe to, e.g. `['end_customer.created']`. */
+    events: string[];
+    description?: string;
+}
+interface WebhookVerifyOptions {
+    /**
+     * The raw request body **as received over the wire** — do NOT parse and
+     * re-serialise, or the HMAC will mismatch.
+     *
+     * Pass a `string` or any `ArrayBufferView` (e.g. `Uint8Array`).
+     */
+    payload: Uint8Array | string;
+    /** Value of the `X-Genvoris-Signature` header. */
+    header: string;
+    /** The endpoint signing secret from your dashboard. */
+    secret: string;
+    /**
+     * Maximum age of the timestamp in seconds before the signature is rejected.
+     * Default: 300 (5 minutes).
+     */
+    toleranceSeconds?: number;
+}
+interface WebhookEndpoint {
+    id: string;
+    url: string;
+    events: string[];
+    description?: string | null;
+    active: boolean;
+    createdAt: string;
+}
+interface WebhookEndpointList {
+    data: WebhookEndpoint[];
+}
+/** Parsed, verified webhook event envelope. */
+interface GenvorisEvent<T extends Record<string, unknown> = Record<string, unknown>> {
+    id: string;
+    type: string;
+    created: number;
+    data: T;
+}
+declare class WebhooksResource {
+    private readonly config;
+    constructor(config: GenvorisConfig);
+    /** List all webhook endpoints for your store. */
+    list(): Promise<WebhookEndpointList>;
+    /** Register a new webhook endpoint. */
+    create(params: WebhookCreateParams): Promise<WebhookEndpoint>;
+    /** Send a synthetic `webhook.test` ping to the endpoint. */
+    test(id: string): Promise<void>;
+    /** Delete a webhook endpoint. */
+    delete(id: string): Promise<void>;
+    /**
+     * Verify the `X-Genvoris-Signature` header and return the parsed event.
+     *
+     * Throws if the signature is invalid, the timestamp is too old, or the
+     * header is malformed. Uses `crypto.timingSafeEqual` to prevent
+     * timing attacks.
+     *
+     * @example
+     * ```ts
+     * import { WebhooksResource } from '@genvoris/node';
+     *
+     * const event = WebhooksResource.verify({
+     *   payload: req.body,  // raw Buffer — do NOT parse JSON first
+     *   header: req.header('x-genvoris-signature') ?? '',
+     *   secret: process.env.GENVORIS_WEBHOOK_SECRET!,
+     * });
+     * ```
+     */
+    static verify<T extends Record<string, unknown> = Record<string, unknown>>({ payload, header, secret, toleranceSeconds, }: WebhookVerifyOptions): GenvorisEvent<T>;
+}
+
+declare class GenvorisAPIError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string | undefined;
+    constructor(args: {
+        status: number;
+        code: string;
+        message?: string;
+        requestId?: string;
+    });
+}
+declare class GenvorisAuthError extends GenvorisAPIError {
+    constructor(args: {
+        status: number;
+        code: string;
+        message?: string;
+        requestId?: string;
+    });
+}
+declare class GenvorisRateLimitError extends GenvorisAPIError {
+    readonly retryAfterSeconds: number;
+    constructor(args: {
+        status: number;
+        code: string;
+        message?: string;
+        requestId?: string;
+        retryAfterSeconds?: number;
+    });
+}
+declare class GenvorisValidationError extends GenvorisAPIError {
+    readonly fieldErrors: Record<string, string[]>;
+    constructor(args: {
+        status: number;
+        code: string;
+        message?: string;
+        requestId?: string;
+        fieldErrors?: Record<string, string[]>;
+    });
+}
+
+/**
+ * Official Genvoris Node.js SDK client.
+ *
+ * @example
+ * ```ts
+ * import Genvoris from '@genvoris/node';
+ *
+ * const gv = new Genvoris({ apiKey: process.env.GENVORIS_API_KEY! });
+ *
+ * const session = await gv.sessions.mint({ customerId: 'ec_abc' });
+ * ```
+ */
+declare class Genvoris {
+    readonly customers: CustomersResource;
+    readonly plans: PlansResource;
+    readonly sessions: SessionsResource;
+    readonly webhooks: WebhooksResource;
+    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 };