SDK reference

Client SDK

Import from wattfare/client. Framework-agnostic, runs in the browser, never touches the secret key — it works entirely with session tokens minted by your backend.

createWattfare(config)

Creates a browser client. It throws immediately if the publishable key is missing or malformed.

createWattfare

import { createWattfare } from "wattfare/client";

const wf = createWattfare({
  publishableKey: "pk_live_…",        // required, starts with "pk_"
  session: "/api/wattfare-token",     // backend route OR a token function
  baseURL: "https://wattfare.com",    // optional
  consentURL: "https://wattfare.com", // optional popup origin
});

Option	Type	Default	Notes
publishableKey	string	—	Required. Must start with `pk_`.
session	string \| () => string \| Promise<string>	—	Required. Your backend route path, or a function returning a token.
baseURL	string	https://wattfare.com	Override the Wattfare service URL.
consentURL	string	https://wattfare.com	Override the consent popup origin.

The session source

session is how the client gets a token without ever seeing your secret key. Pass a string for the easy path, or a function when you need custom headers or token plumbing:

two ways to provide a session

// Shorthand: a backend route path. The SDK POSTs to it and reads
// { token } (or a raw token string) from the response.
const wf = createWattfare({ publishableKey, session: "/api/wattfare-token" });

// Full control: a function that returns (or resolves) a token string.
const wf = createWattfare({
  publishableKey,
  session: async () => {
    const res = await fetch("/api/wattfare-token", { method: "POST" });
    const { token } = await res.json();
    return token;
  },
});

connect()

Opens the consent popup and resolves once the user approves or denies. On approval it returns the fresh ConnectionStatus; on denial (or if they close the popup) it returns the not-connected status.

connect()

// Must be called from a user gesture (click/tap).
connectBtn.onclick = async () => {
  const status = await wf.connect();
  if (status.connected) renderBudget(status.remainingUsd);
};

status()

Fetches the current connection and budget snapshot for the session's user. Returns { connected: false, … } when they haven't connected — it never throws for that case, so you can call it on every page load safely.

status()

const status = await wf.status();
// { connected: true, limits: { monthlyUsd: 10 },
//   usage: { monthlyUsd: 3.2 }, remainingUsd: 6.8 }

if (!status.connected) showConnectButton();

disconnect()

Revokes the connection for the session's user. Their budget is immediately cut off from your app.

disconnect()

await wf.disconnect();
// Connection revoked. In-flight requests may finish; new ones won't be authorised.

requestGrant(options)

Opens the consent popup for a one-time access grant — no persistent connection needed. See One-time grants for the full API, options, and examples.

WattfareClient

Method	Returns	Description
connect()	Promise<ConnectionStatus>	Open the consent popup; resolve on approve/deny.
status()	Promise<ConnectionStatus>	Current connection + budget snapshot.
disconnect()	Promise<void>	Revoke the connection.
requestGrant(options)	Promise<GrantResult \| null>	Request a one-time access grant; resolve on approve/deny.