@genvoris/node 1.0.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -0,0 +1,384 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  GenvorisAPIError: () => GenvorisAPIError,
+  GenvorisAuthError: () => GenvorisAuthError,
+  GenvorisRateLimitError: () => GenvorisRateLimitError,
+  GenvorisValidationError: () => GenvorisValidationError,
+  WebhooksResource: () => WebhooksResource,
+  default: () => Genvoris
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var GenvorisAPIError = class extends Error {
+  constructor(args) {
+    super(args.message ?? args.code);
+    this.name = "GenvorisAPIError";
+    this.status = args.status;
+    this.code = args.code;
+    this.requestId = args.requestId;
+  }
+};
+var GenvorisAuthError = class extends GenvorisAPIError {
+  constructor(args) {
+    super(args);
+    this.name = "GenvorisAuthError";
+  }
+};
+var GenvorisRateLimitError = class extends GenvorisAPIError {
+  constructor(args) {
+    super(args);
+    this.name = "GenvorisRateLimitError";
+    this.retryAfterSeconds = args.retryAfterSeconds ?? 60;
+  }
+};
+var GenvorisValidationError = class extends GenvorisAPIError {
+  constructor(args) {
+    super(args);
+    this.name = "GenvorisValidationError";
+    this.fieldErrors = args.fieldErrors ?? {};
+  }
+};
+
+// 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";
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function request(config, path, opts = {}, attempt = 0) {
+  const { method = "GET", body, query } = opts;
+  const fetchFn = config.fetch ?? globalThis.fetch;
+  const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  let url = `${baseUrl}${path}`;
+  if (query) {
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== void 0 && v !== null) params.set(k, String(v));
+    }
+    const qs = params.toString();
+    if (qs) url += `?${qs}`;
+  }
+  const controller = new AbortController();
+  const timerId = setTimeout(
+    () => controller.abort(),
+    config.timeoutMs ?? 3e4
+  );
+  let res;
+  try {
+    res = await fetchFn(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${config.apiKey}`,
+        "Content-Type": "application/json",
+        "User-Agent": `genvoris-node/${SDK_VERSION}`,
+        ...config.defaultHeaders
+      },
+      body: body !== void 0 ? JSON.stringify(body) : void 0,
+      signal: controller.signal
+    });
+  } finally {
+    clearTimeout(timerId);
+  }
+  if (res.ok) {
+    if (res.status === 204) return void 0;
+    return res.json();
+  }
+  const requestId = res.headers.get("x-request-id") ?? void 0;
+  let errBody = {};
+  try {
+    errBody = await res.json();
+  } catch {
+  }
+  const code = errBody.error ?? "unknown_error";
+  const message = errBody.message ?? code;
+  if (RETRY_STATUSES.has(res.status)) {
+    const maxRetries = config.maxRetries ?? 3;
+    if (attempt < maxRetries) {
+      const base = Math.min(Math.pow(2, attempt) * 250, MAX_DELAY_MS);
+      const delay = Math.random() * base;
+      await sleep(delay);
+      return request(config, path, opts, attempt + 1);
+    }
+  }
+  const errorBase = { status: res.status, code, message, requestId };
+  if (res.status === 401 || res.status === 403) {
+    throw new GenvorisAuthError(errorBase);
+  }
+  if (res.status === 429) {
+    const retryAfter = res.headers.get("retry-after");
+    throw new GenvorisRateLimitError({
+      ...errorBase,
+      retryAfterSeconds: retryAfter ? Number(retryAfter) : 60
+    });
+  }
+  if (res.status === 400 || res.status === 422) {
+    throw new GenvorisValidationError({
+      ...errorBase,
+      fieldErrors: errBody.fieldErrors ?? {}
+    });
+  }
+  throw new GenvorisAPIError(errorBase);
+}
+
+// src/resources/customers.ts
+var CustomersResource = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /** Create or upsert an end-customer. */
+  create(params) {
+    return request(this.config, "/customers", {
+      method: "POST",
+      body: params
+    });
+  }
+  /** Retrieve a single customer by their Genvoris `id`. */
+  retrieve(id) {
+    return request(
+      this.config,
+      `/customers/${encodeURIComponent(id)}`
+    );
+  }
+  /** Update a customer's email, plan, status, or metadata. */
+  update(id, params) {
+    return request(
+      this.config,
+      `/customers/${encodeURIComponent(id)}`,
+      { method: "PATCH", body: params }
+    );
+  }
+  /** List customers with optional status filter and cursor pagination. */
+  list(params = {}) {
+    return request(this.config, "/customers", {
+      query: params
+    });
+  }
+  /** Soft-cancel a customer. Future try-ons return 402 `cancelled`. */
+  cancel(id) {
+    return request(
+      this.config,
+      `/customers/${encodeURIComponent(id)}`,
+      { method: "DELETE" }
+    );
+  }
+  /** Return the customer's current-period quota state and usage history. */
+  usage(id) {
+    return request(
+      this.config,
+      `/customers/${encodeURIComponent(id)}/usage`
+    );
+  }
+  /** List active widget sessions for this customer. */
+  sessions(id) {
+    return request(
+      this.config,
+      `/customers/${encodeURIComponent(id)}/sessions`
+    );
+  }
+};
+
+// src/resources/plans.ts
+var PlansResource = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /** List all plans. Pass `{ include_inactive: true }` to include disabled ones. */
+  list(params = {}) {
+    return request(this.config, "/plans", {
+      query: params
+    });
+  }
+  /** Create a new plan. Returns `201 Created`. */
+  create(params) {
+    return request(this.config, "/plans", {
+      method: "POST",
+      body: params
+    });
+  }
+  /** Retrieve a single plan. */
+  retrieve(id) {
+    return request(this.config, `/plans/${encodeURIComponent(id)}`);
+  }
+  /** Update any plan fields. */
+  update(id, params) {
+    return request(this.config, `/plans/${encodeURIComponent(id)}`, {
+      method: "PATCH",
+      body: params
+    });
+  }
+  /**
+   * 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) {
+    return request(this.config, `/plans/${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
+  }
+};
+
+// src/resources/sessions.ts
+var SessionsResource = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * 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 }) {
+    return request(
+      this.config,
+      `/customers/${encodeURIComponent(customerId)}/sessions`,
+      {
+        method: "POST",
+        body: ttlSeconds !== void 0 ? { expires_in: ttlSeconds } : void 0
+      }
+    );
+  }
+};
+
+// src/resources/webhooks.ts
+var import_node_crypto = require("crypto");
+function hexToBytes(hex) {
+  if (hex.length % 2 !== 0) throw new Error("genvoris: invalid hex string");
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+var WebhooksResource = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /** List all webhook endpoints for your store. */
+  list() {
+    return request(this.config, "/webhooks");
+  }
+  /** Register a new webhook endpoint. */
+  create(params) {
+    return request(this.config, "/webhooks", {
+      method: "POST",
+      body: params
+    });
+  }
+  /** Send a synthetic `webhook.test` ping to the endpoint. */
+  test(id) {
+    return request(
+      this.config,
+      `/webhooks/${encodeURIComponent(id)}/test`,
+      { method: "POST" }
+    );
+  }
+  /** Delete a webhook endpoint. */
+  delete(id) {
+    return request(
+      this.config,
+      `/webhooks/${encodeURIComponent(id)}`,
+      { method: "DELETE" }
+    );
+  }
+  // -------------------------------------------------------------------------
+  // Static helpers
+  // -------------------------------------------------------------------------
+  /**
+   * 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({
+    payload,
+    header,
+    secret,
+    toleranceSeconds = 300
+  }) {
+    const raw = typeof payload === "string" ? payload : new TextDecoder().decode(payload);
+    const parts = {};
+    for (const part of header.split(",")) {
+      const eq = part.indexOf("=");
+      if (eq !== -1) parts[part.slice(0, eq).trim()] = part.slice(eq + 1).trim();
+    }
+    const { t, v1 } = parts;
+    if (!t || !v1) {
+      throw new Error("genvoris: invalid signature header \u2014 expected t=...,v1=...");
+    }
+    const ts = parseInt(t, 10);
+    if (!Number.isFinite(ts)) {
+      throw new Error("genvoris: invalid signature timestamp");
+    }
+    const age = Math.abs(Date.now() / 1e3 - ts);
+    if (age > toleranceSeconds) {
+      throw new Error(
+        `genvoris: signature timestamp too old (${Math.round(age)}s > ${toleranceSeconds}s tolerance)`
+      );
+    }
+    const expectedHex = (0, import_node_crypto.createHmac)("sha256", secret).update(`${ts}.${raw}`).digest("hex");
+    const a = hexToBytes(expectedHex);
+    const b = hexToBytes(v1);
+    if (a.length !== b.length || !(0, import_node_crypto.timingSafeEqual)(a, b)) {
+      throw new Error("genvoris: signature mismatch");
+    }
+    return JSON.parse(raw);
+  }
+};
+
+// src/index.ts
+var Genvoris = class {
+  constructor(config) {
+    if (!config?.apiKey) {
+      throw new Error("Genvoris: apiKey is required");
+    }
+    this.customers = new CustomersResource(config);
+    this.plans = new PlansResource(config);
+    this.sessions = new SessionsResource(config);
+    this.webhooks = new WebhooksResource(config);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GenvorisAPIError,
+  GenvorisAuthError,
+  GenvorisRateLimitError,
+  GenvorisValidationError,
+  WebhooksResource
+});