@multraverse/sdk

@multraverse/sdk

Typed client for the Multraverse platform hub. Every call goes through the tenant's own multraverse-proxy edge function, so the browser never sees the Multraverse API key.

Install

This package is published to GitHub Packages, not the public npm registry, so consumers need a registry line and a token before bun add will resolve it.

Create .npmrc in the tenant app's root:

@multraverse:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Commit that file — it holds no secret, only the variable name. Put the actual token in the environment as GITHUB_TOKEN; it needs the read:packages scope and nothing more. Publishing needs write:packages, which only the release machine should hold.

Then:

bun add @multraverse/sdk

Casing matters. The GitHub org is Multraverse but npm scopes must be lowercase, so the scope is always @multraverse. A capital letter in .npmrc or in package.json will 404 rather than fail clearly.

Without the .npmrc, bun add @multraverse/sdk hits the public registry, finds nothing, and reports the package as non-existent — which looks like a typo rather than an auth problem. Check .npmrc first when that happens.

Use

import { createMailClient } from "@multraverse/sdk";
// or a subpath, which is what the React drop-ins use:
import { createCalendarClient } from "@multraverse/sdk/calendar";

Auth

Clients that call non-public proxy scopes need a bearer token. Pass getAccessToken; the library never reaches into your app's Supabase instance:

import { createSupportClient } from "@multraverse/sdk/support";

const support = createSupportClient({
  getAccessToken: async () =>
    (await supabase.auth.getSession()).data.session?.access_token ?? null,
});

support, payments, ai, mail, sms, voice, and calendar are all gated. The public scopes — config, tenant-config, account, health, build, storage, users — work without a token.

Omitting getAccessToken on a gated scope produces a 401 from the proxy, not a client-side error, so check there first if calls start failing after an upgrade.

Resilience

Hub calls route through createHubClient, which retries on 503 and network errors and raises HubUnavailableError. Tenant apps are expected to degrade gracefully — serve cached config, queue sends — rather than surface a failure.

Shipping format

This package publishes TypeScript source, not a compiled bundle. Every consumer is a Vite + TypeScript app, so a build step would add a release artifact to verify without buying anything. If a non-TS or non-bundler consumer ever appears, add a tsup build and point exports at the output — the public API is already organised by subpath, so that change would not be breaking.

Versioning

Breaking changes get a major bump and a note here. The 0.1.0 line removed an implicit Supabase session lookup: callers that relied on it must now pass getAccessToken explicitly.