JavaScript Documentation

npm install usethatapp

UTA_CLIENT_ID=...            # required
UTA_CLIENT_SECRET=...        # required (server-side only)
UTA_REDIRECT_URI=https://yourapp.com/callback
# optional — default to production:
UTA_ISSUER=https://www.usethatapp.com/o
UTA_API_URL=https://www.usethatapp.com
UTA_SCOPES="openid entitlements"

import {
  beginLogin,      // () => { authorizationUrl, flowState }
  completeLogin,   // ({ code, state, flowState }) => UtaSession
  getEntitlement,  // (accessToken) => Entitlement
  refresh,         // (refreshToken) => UtaSession
  userinfo,        // (accessToken) => { sub }
  logoutUrl,       // ({ idToken, postLogoutRedirectUri }) => string

  // Selling — hosted checkout & live pricing
  purchaseUrl,     // (priceId, { next, ref, email }?) => string — pure URL builder
  manageUrl,       // ({ next }?) => string — subscription management, pure
  getPrices,       // () => Promise<AppPrices> — live prices, no auth
  getAppInfo,      // () => Promise<AppInfo> — public app profile, no auth

  configure,       // override env config
  resetConfig,

  // Errors (all extend UtaError)
  UtaError,
  UtaConfigError,
  UtaDiscoveryError,
  UtaAuthError,
  UtaTokenError,       // 401
  UtaPermissionError,  // 403
  UtaServerError,

  // Types (TypeScript)
  type UtaSession,
  type Entitlement,
  type UtaFlowState,
  type AppInfo,
  type AppPrices,
  type UtaPrice,
} from "usethatapp";

interface UtaSession {
  readonly sub: string;                  // pairwise, stable per-app — your local user key
  readonly access_token: string;         // pass to getEntitlement
  readonly expires_at: number;           // unix seconds
  readonly refresh_token: string | null; // null when no refresh token was granted
  readonly id_token: string | null;      // pass to logoutUrl
  readonly scope: string;
  readonly token_type: string;
  readonly claims: Record<string, unknown>; // validated ID-token claims
}

interface Entitlement {
  readonly entitled: boolean;            // may the user use the app
  readonly version: string | null;       // plan display name, e.g. "Pro" — mutable
  readonly product_id: string | null;    // stable prod_... id — gate features on this
  readonly product_public_id: string | null; // same prod_... value — equal-valued alias
  readonly status: string;               // active / trialing / free / preview / none / ...
  readonly is_free: boolean;
  readonly period_end: string | null;
  readonly raw: Record<string, unknown>; // the full decoded response
}

interface AppPrices {
  readonly client_id: string;
  readonly app_name: string;
  readonly has_free_tier: boolean;
  readonly prices: readonly UtaPrice[]; // readonly — copy with [...prices] before sorting
  readonly raw: Record<string, unknown>;
}

interface UtaPrice {
  readonly public_id: string;      // prc_... — pass to purchaseUrl()
  readonly product_id: string;     // matches the entitlement's product_public_id
  readonly product_name: string;
  readonly amount: string;         // decimal string, e.g. "10.00"
  readonly currency: string;       // lowercase ISO code, e.g. "usd"
  readonly is_recurring: boolean;
  readonly frequency: string | null; // "day" | "week" | "month" | "year"; null = one-time
  readonly buy_url: string;        // ready-made hosted-checkout buy link
}

interface AppInfo {
  readonly client_id: string;
  readonly name: string;
  readonly tagline: string;
  readonly listing_mode: string;   // "marketplace" or "external"
  readonly url: string;
  readonly marketplace_url: string;
  readonly raw: Record<string, unknown>;
}

import { beginLogin, completeLogin, getEntitlement } from "usethatapp";

// 1) Start login — however your framework spells "redirect":
const { authorizationUrl, flowState } = await beginLogin();
saveToSession("utaFlow", flowState);        // JSON-serializable
res.redirect(authorizationUrl);

// 2) In your callback (reads ?code=...&state=... off the request).
//    On cancel/deny the provider sends ?error=... and no code — handle it first:
if (req.query.error) return res.redirect("/");   // login was canceled
const session = await completeLogin({
  code: req.query.code,
  state: req.query.state,
  flowState: loadFromSession("utaFlow"),
});
saveToSession("utaSub", session.sub);
saveToSession("utaAccessToken", session.access_token);

// 3) Anywhere you gate features:
const ent = await getEntitlement(loadFromSession("utaAccessToken"));
if (ent.entitled && ent.product_public_id === "prod_<your-pro-id>") { /* ... */ }