SDK API Reference

Functions

init(config)

Initializes the SDK, loads or creates an anonymous ID, queues the initial pageview, and starts the event flush timer.

checkAccess(url?)

Calls GET /api/v1/access/check with the URL, userId, and anonymousId.

• if denied and onPaywall is set, the callback runs
• if denied and onPaywall is not set, the built-in paywall is shown
• on error, the SDK returns { granted: true, reason: 'error_fallback' }

identify(userId)

Sets the current userId for future access checks and events.

resetIdentity()

Clears userId and falls back to the browser’s stored anonymous ID.

trackEvent(eventType, properties?)

Queues a custom event for batched delivery.

trackPageview(properties?)

Queues a pageview event and automatically includes url, path, title, and referrer.

showPaywall(result)

Renders the built-in paywall UI for a supplied access result.

hidePaywall()

Removes the built-in paywall from the DOM.

getConfig()

Returns the current SDK config or null before initialization.

Auth Functions

register(email, password, name?)

Register a new customer. Stores tokens in localStorage and fires auth change listeners. Returns an AuthResult.

login(email, password)

Log in an existing customer. Stores tokens in localStorage and fires auth change listeners. Returns an AuthResult.

logout()

Revoke the refresh token on the server and clear all stored tokens. Fires auth change listeners with null.

getSession()

Get the current customer’s profile from the server. Automatically refreshes the access token if expired. Returns CustomerProfile | null.

isAuthenticated()

Check if the customer has stored tokens (synchronous, no network request). Returns boolean.

getStoredCustomer()

Get the stored customer info from localStorage without a network request. Returns AuthCustomer | null.

getValidAccessToken()

Get a valid access token, refreshing if necessary. Used internally by checkAccess(). Returns string | null.

onAuthChange(callback)

Register a callback that fires whenever the auth state changes (login, logout, token refresh). Returns an unsubscribe function.

const unsubscribe = onAuthChange((customer) => {
  if (customer) {
    console.log('Logged in as', customer.email);
  } else {
    console.log('Logged out');
  }
});

Billing Functions

checkout(options)

Create a Stripe Checkout session and redirect the browser. Requires the customer to be logged in. Uses the JWT Bearer token with a pk_ key.

await checkout({
  priceId: 'latch-price-uuid',
  successUrl: 'https://yoursite.com/welcome',
  cancelUrl: 'https://yoursite.com/pricing',
});

Options: priceId (required), successUrl (optional), cancelUrl (optional). Returns CheckoutResult.

openPortal(options?)

Open the Stripe Customer Portal for subscription self-service. Requires the customer to be logged in and have a Stripe customer record.

await openPortal({ returnUrl: 'https://yoursite.com/account' });

Options: returnUrl (optional, defaults to current page). Returns PortalResult.

getSubscription()

Get the current customer’s active subscription. Returns SubscriptionInfo | null.

const sub = await getSubscription();
if (sub) console.log(sub.status, sub.currentPeriodEnd);

Types

LatchConfig

interface LatchConfig {
  apiKey: string;
  apiUrl?: string;
  userId?: string;
  anonymousId?: string;
  onPaywall?: (result: AccessResult) => void;
  onCheckout?: (productIds: string[]) => void;
  paywallSelector?: string;
  debug?: boolean;
}

Field	Description
apiKey	Publishable key
apiUrl	API base URL
userId	Known reader ID
anonymousId	Override the browser-stored anonymous ID
onPaywall	Custom denied-access handler
onCheckout	Built-in Subscribe-button handler
paywallSelector	Target for inline paywalls
debug	Enables console logs

AccessResult

interface AccessResult {
  granted: boolean;
  reason?: string;
  paywallRule?: {
    id: string;
    type: string;
    action: {
      productIds: string[];
      message?: string;
      meterLimit?: number;
      template?: string;
    };
  };
  meterRemaining?: number;
}

Current reason values returned by the implementation are subscribed, free_content, metered_remaining, registered, and error_fallback.

AuthResult

interface AuthResult {
  accessToken: string;
  refreshToken: string;
  expiresAt: number;
  customer: AuthCustomer;
}

AuthCustomer

interface AuthCustomer {
  id: string;
  email: string;
  name: string | null;
}

CustomerProfile

interface CustomerProfile {
  id: string;
  email: string;
  name: string | null;
  customAttributes: Record<string, unknown>;
  createdAt: string;
}

CheckoutOptions

interface CheckoutOptions {
  priceId: string;
  successUrl?: string;
  cancelUrl?: string;
}

CheckoutResult

interface CheckoutResult {
  sessionId: string;
  url: string;
}

PortalResult

interface PortalResult {
  url: string;
}

SubscriptionInfo

interface SubscriptionInfo {
  id: string;
  priceId: string;
  status: string;
  cancelAtPeriodEnd: boolean;
  currentPeriodStart: string | null;
  currentPeriodEnd: string | null;
  cancelledAt: string | null;
  createdAt: string;
}