@blezgo/api-sdk

Typed HTTP client for the Blezgo platform API. Organized into per-domain modules — import only what your app needs. Every request and response is fully typed from the live OpenAPI spec via openapi-fetch.

Installation

npm install @blezgo/api-sdk

Quick Start

import { createPaymentsClient } from '@blezgo/api-sdk';

const payments = createPaymentsClient({
  baseUrl: 'https://api.yourtenant.com',
  getToken: () => authStore.getAccessToken(),
});

const { data, error } = await payments.GET('/v1/payments/orders', {
  params: { query: { page: 1, limit: 20 } },
});

if (error) {
  console.error(error.message, error.code);
} else {
  console.log(data.data); // typed order list
}

Features

• Identity & Auth — login, sessions, MFA, OAuth, social sign-in, API keys, impersonation
• User Management — provisioning, invitations, roles, permissions (RBAC), quotas
• Products & Catalog — courses, events, packages, tests, pricing, variants, localization
• Commerce & Billing — cart, orders, payments, subscriptions, invoices, wallets, coupons
• Payouts — recipients, settlement rules, disbursements, payout portal
• Services & Bookings — expert matching, availability, credits, cancellations
• Enrollment & Entitlements — user library, access checks across all product types
• Content Library — folders, items, assets, collections, versioning, collaboration
• Messaging — unified inbox, notifications, WebSocket delivery, channel management
• Engagement & Growth — campaigns, funnels, gamification, cart recovery, upsell
• Support — ticketing, SLA, automation, team management, analytics
• Publishing — per-tenant blog and changelog with subscriber management
• Spaces & Discovery — URL experiences, public storefront, search, templates
• Platform Operations — cache, events, storage, SaaS sub-tenant management (operator)
• Full TypeScript support — types generated directly from the live OpenAPI spec

API Reference

The SDK is organized into per-domain modules. Import only the clients your app needs.

| Module | Covers | |---|---| | tenant | Tenant resolution, configuration, profile, audit logs | | authentication | Login, sessions, MFA, social sign-in | | registration | User onboarding and email/mobile verification | | users | User lifecycle, bulk provisioning, invitations | | rbac | Roles, permissions, quotas, access layers | | profile | User profile, password, notification preferences | | products | Product catalog, variants, pricing, localization | | courses | Course-based learning products | | events | Sessions, webinars, and meetings | | packages | Session packages and product bundles | | enrollments | Entitlement checks and user library | | payments | Cart, orders, subscriptions, invoices, wallets, coupons | | payouts | Recipients, runs, disbursements, settlement rules | | services | Service catalog, bookings, expert matching, credits | | notifications | User notification inbox and WebSocket delivery | | inbox | Unified messaging, conversations, attachments | | content | Enterprise content library — folders, items, assets | | search | Search, suggestions, spell correction, history | | spaces | URL experiences, templates, public resolution | | support | Ticketing, SLA, agents, teams, automation | | blog | Per-tenant blog — posts, authors, categories | | changelog | Per-tenant changelog — entries, labels, subscribers | | campaigns | Marketing campaigns — targeting, apply, measure | | gamification | Progress, badges, leaderboards | | apikeys | API key lifecycle, rotation, audit logs | | affiliate | Referrals, commissions, attribution | | platform-cache | Redis cache control (operator) | | saas-provider | L1 provider and sub-tenant lifecycle (operator) |

All 53 modules: tenant dashboard system errors usage i18n tokens registration authentication auth-admin impersonation apikeys rbac users profile onboarding inbox notifications notification-mgmt company metas reasons channels uploads search elasticsearch storefront spaces content products addons reviews courses events packages tests plans services scheduling calendar conference enrollments gamification announcements campaigns funnels cart-recovery upsell pricing cookies payments payouts affiliate support custom-modules changelog blog platform-cache platform-events platform-notifications platform-search platform-storage saas-provider internal-core internal-auth

Configuration

Every client factory accepts the same options object:

| Option | Type | Required | Description | |---|---|---|---| | baseUrl | string | ✅ | Your tenant API base URL, e.g. https://api.yourtenant.com | | getToken | () => string \| null \| undefined | — | Called on every request. Returns the current Bearer token, or null/undefined when unauthenticated. | | getGuestSessionId | () => string \| null \| undefined | — | Returns the guest session ID for unauthenticated cart/checkout flows. |

Token callback

getToken is called per request — a refreshed token is always picked up without recreating the client:

// Works with any auth layer: Zustand, Redux, React Context, a module variable, etc.
const client = createProfileClient({
  baseUrl: 'https://api.yourtenant.com',
  getToken: () => authStore.getAccessToken(), // return null when logged out
});

For Next.js App Router or Remix loaders, pass the resolved token directly from your server context:

const client = createProfileClient({
  baseUrl: process.env.API_BASE_URL!,
  getToken: () => serverSideToken,
});

Guest sessions

Cart and checkout flows work without a logged-in user. Pass getGuestSessionId to send the X-Guest-Session-ID header:

const payments = createPaymentsClient({
  baseUrl: 'https://api.yourtenant.com',
  getToken: () => authStore.getAccessToken(),
  getGuestSessionId: () => sessionStore.getGuestSessionId(),
});

Sharing options across clients

Create the options object once and pass it to every factory:

// lib/api.ts
import { createTenantClient, createPaymentsClient, createEnrollmentsClient } from '@blezgo/api-sdk';

const opts = {
  baseUrl: process.env.NEXT_PUBLIC_API_BASE_URL!,
  getToken: () => authStore.getAccessToken(),
};

export const tenantClient    = createTenantClient(opts);
export const paymentsClient  = createPaymentsClient(opts);
export const enrollments     = createEnrollmentsClient(opts);

Error Handling

Every call returns { data, error } — the client never throws. Always check error before using data:

const { data, error } = await payments.GET('/v1/payments/orders', {
  params: { query: { page: 1 } },
});

if (error) {
  console.error(error.message, error.code); // typed to the OpenAPI error schema
  return;
}

console.log(data.data); // fully typed — no cast needed

Response envelope

All Blezgo API responses follow a standard envelope:

{
  success: true,
  data: { /* resource or list */ },
  message: "...",
  meta: { pagination: { page, limit, total, total_pages } } // list endpoints only
}

TypeScript

Types are bundled — no @types/ package needed.

Every module exposes its full type surface via a subpath import:

import type { paths, components, operations } from '@blezgo/api-sdk/payments';

// Specific response schema
type Order = components['schemas']['OrderResponse'];

// Full path type
type ListOrders = paths['/v1/payments/orders']['get']['responses']['200']['content']['application/json'];

The root import gives you all client factories:

import { createPaymentsClient, createEnrollmentsClient } from '@blezgo/api-sdk';

Contributing

See CONTRIBUTING.md for type regeneration, build, and publish workflow.

License

MIT © Blezgo