@masterpack/sdk

Auth + usage tracking for apps in the MasterPack catalog. One subscription unlocks every app; makers get paid monthly based on real usage — this SDK is how both halves happen.

Full integration guide: https://masterpack.app/docs/integrate.md (agents: https://masterpack.app/llms.txt)

Install

npm install @masterpack/sdk

Sign in with MasterPack (browser)

import { MasterPackAuth } from "@masterpack/sdk";

const auth = new MasterPackAuth({
  gateUrl: "https://auth.masterpack.app",
  clientId: process.env.NEXT_PUBLIC_MASTERPACK_CLIENT_ID!, // mpc_test_* in dev, mpc_live_* in prod
  redirectUri: `${location.origin}/callback`,
});

// sign-in button
auth.beginLogin().then((url) => location.assign(url));

// on /callback
await auth.completeLogin(location.href);

// everywhere else
const session = await auth.ensureFreshSession();
// null → show the button; else session.user = { sub, displayName, tier, } and
// the token's mode claim tells you test vs live

Usage heartbeats (required for payouts)

import { HeartbeatEngine, browserEnv } from "@masterpack/sdk";

new HeartbeatEngine(browserEnv("https://auth.masterpack.app/api/beats"), {
  appId: CLIENT_ID,
  sid: session.sid,
  getAccessToken: () => auth.getSession()?.accessToken ?? null,
}).start();

Heartbeats only fire while the page is visible and the user actually interacted — parked tabs earn nothing, by design.

Verify tokens on your backend (optional)

import { createTokenVerifier } from "@masterpack/sdk/server";

const verify = createTokenVerifier({
  gateUrl: "https://auth.masterpack.app",
  clientId: CLIENT_ID,
});
const user = await verify(bearerToken); // throws if invalid/expired

Test vs live

Every app has two client ids: mpc_test_* (sandbox — no subscription required, localhost redirects allowed, usage never earns, gate shows a Dev Mode banner) and mpc_live_* (production). Tokens carry mode: "test" | "live". Grab both ids in the maker dashboard.

License

MIT