Client

toolaby.js is the client the wiring writes beside your code, typed by toolaby.d.ts. It has fifteen methods and two events. Everything it answers comes from a token Toolaby signed for this device and the client verified with the workspace's public key; a method marked no request answers from the device alone.

import { toolaby } from './toolaby.js';

The same import works in the background service worker, the popup, a side panel and a content script. In the background the methods run; elsewhere they are forwarded to the background over chrome.runtime.sendMessage and answer the same.

toolaby.config.js

The whole configuration, written by the wiring beside toolaby.js.

Swapping the key for the live one is the whole of shipping to the store; nothing else in the file changes. See Test and Live.

startBackground()

startBackground(options?: BackgroundOptions): void

Starts the client in the service worker: the message listeners the other contexts use, the handoffs from the sign-in and checkout pages, and the version check. Call it once, synchronously, at the top level of background.js. Throws outside the background.

The sign-in and purchase handoffs are taken only from a page of Toolaby's own address, never from another extension.

toolaby.startBackground({
  handlers: {
    exportSheet: async ({ tab }) => {
      const permit = await toolaby.gate();
      if (!permit.allowed) return permit;
      return exportTableFrom(tab);
    },
  },
});

A handler runs inside the message that called it. An API that needs the click that sent the message, such as chrome.sidePanel.open(), works when the handler calls it before its first await.

ensureBackground()

ensureBackground(): void

startBackground() unless something already called it. The Toolaby background the wiring puts in front of yours (toolaby.background.js), and the WXT module it writes (modules/toolaby.wxt.ts), call this after your own code has run, and so does ExtPay's startBackground() once switched. A background that calls startBackground({ handlers }) itself keeps its handlers, and one that never mentions Toolaby still starts it. When ensureBackground() ran first, as when ExtPay starts in a module your background imports, your own startBackground() takes over with its options. Not something you call.

getUser()

getUser(): Promise<User>

What the device knows now. No request. user.token says when the answer was issued. See User.

getPlans()

getPlans(): Promise<ToolPlan[]>

The plans the tool sells, in the order Pricing shows them: each a Plan with its tier and its trialDays. Asks Toolaby at most once a minute, also when the service worker stops and starts again in between; a page of the extension asks its background. Rejects when Toolaby cannot be reached, in every context.

refresh()

refresh(): Promise<User>

Asks Toolaby, then answers as getUser() does. Call it when the popup opens, not on every action. Offline, answers what the device has.

A purchase, a sign-in and a licence key are asked about when they happen, not at the next refresh(). Signing in as someone else, signing out or putting a licence key in forgets Toolaby's last answer, so the five minutes never hold one account to what Toolaby said about another.

gate()

gate(arg?: number | { count?: number; feature?: string }): Promise<Permit>

May this device do the thing, now? Call it before the action, not when the popup opens.

Offline, the device counts and answers with offline: true. See Permit.

has()

has(feature: string): Promise<boolean>

Whether the device holds the feature: always for a Free plan feature, otherwise when the last token lists it. A tool with no features holds everything. No request, no use spent.

For display — the button drawn, greyed or badged. It stops nothing by itself: enforce a feature with gate({ feature }) at the action.

signOut()

signOut(): Promise<void>

Signs this device out and fires onChange. Its link is revoked on the account, so the account page no longer lists the device, and the entitlement and any site tokens go from the device. The account is untouched. Offline, the device signs out and the link lapses on its own.

siteToken()

siteToken(options: { audience: string; fresh?: boolean }): Promise<string | null>

A site token for one of your own pages: the buyer signed in on this device, for that page's server. Use it when your extension does its work through your web app's server: the server checks who is asking and counts the buyer's uses with the token, as it does for the page. See Your server.

The token carries a page token's claims and two more: azp, this extension's origin (chrome-extension://<id>), and ins, this device's install id. Toolaby reads what the account holds at each token; a device past the account's device limit gets ent: false. Signing out or signing in as someone else drops every token kept. Not from a content script.

noteUses()

noteUses(usage: UsesAnswer): Promise<boolean>

Takes Toolaby's answer from /api/v1/tools/{tool}/uses, as your server passed it on, into this device's meter: getUser().usage and the account line then say what is left. Call it after each answer your server sends back from a count, or from a GET of the same route when the popup opens.

Returns true when the meter took it. The meter only ever counts more uses, never fewer, and takes an answer only for a tool that requires an account, with one signed in, in the period Toolaby last signed. It gives no use: what is allowed stays your server's answer. Not from a content script.

versionState()

versionState(options?: { fresh?: boolean }): Promise<VersionState>

The version check's last answer, kept across the service worker's restarts. { fresh: true } asks Toolaby again: on Test at every call, on Live when the answer is five minutes old or more. See VersionState.

openPaymentPage()

openPaymentPage(planId?: string): Promise<void>

Opens the checkout page in a tab, with the plan preselected when named. A purchase is on the buyer's account, and the device holds it through the account the extension is signed in to. After payment, Toolaby's after-purchase page signs the extension in to that account at once, if the buyer paid signed in. Bought signed out, the page's one button is the sign-in that does it, with the address the purchase was made with. onPaid fires when the device unlocks.

openLoginPage()

openLoginPage(provider?: 'google'): Promise<void>

Opens the sign-in page. Signed in, the page hands the session to the extension. With 'google' — the popup's Continue with Google — the page goes straight to Google instead of asking again. Google sign-in is on for every workspace, through Toolaby's Google client or your own from Configure → Sign-in.

openAccountPage()

openAccountPage(): Promise<void>

Opens the buyer's account page.

showPaywall()

showPaywall(permit: Permit | { feature: string; needs?: string[] }): Promise<void>

Answers a refused permit with the paywall, from your popup or your side panel. The page gives way to the paywall for that reason, at that surface's width, in your brand and the buyer's language. A Back button returns to the page. Once the device may continue (bought, signed in, the feature held), it returns there by itself. Showing it spends nothing.

const permit = await toolaby.gate({ feature: 'export' });
if (!permit.allowed) return toolaby.showPaywall(permit);

{ feature: 'export' } on its own asks for a feature's plans without calling gate() first — for a button drawn locked because has() said no.

The paywall opens in the Toolaby popup's own page, toolaby-popup.html or toolaby-sidepanel.html, which wire and create put beside every popup and side panel. An extension without it — a build that left it out — gets the checkout page in a new tab instead, never a missing page. A side panel of your own says it is one with <html data-toolaby-surface="sidepanel">, or the paywall opens at popup width.

From a page of the extension open in a tab, such as an editor or a report, navigating away would lose its work. There it opens the checkout page in a new tab instead: the sign-in page for sign_in, nothing for blocked. A content script, whose page is not the extension's, does the same. The purchase reaches the extension as any other does: onPaid fires, and has() answers yes at the page's next call. In the background it throws, since there is no page to show it in: return the permit to the page and call it there. See Gate your extension.

onPaid, onChange

onPaid: { addListener(cb: (user: User) => void): void; removeListener(cb): void }
onChange: { addListener(cb: (user: User) => void): void; removeListener(cb): void }

Background only. onPaid fires when the device goes from unpaid to paid. onChange fires on every change of user.paid. Neither fires for the first observation after the worker wakes. A popup reads getUser() when it opens instead.

ExtensionPay's calls

toolaby.js also exports ExtPay, which answers ExtensionPay's calls (getUser(), openPaymentPage(), onPaid and the rest) in ExtensionPay's shapes, for an extension moving from it. See Move from ExtensionPay.

Errors

No method throws on a network failure; each answers from the device and marks the answer offline where it matters. startBackground() throws outside the background; Toolaby({ key }) throws at startup when key is not a tool key. A method called from a page rejects with Toolaby is not running in this extension's background when nothing started it there. See Troubleshoot an extension.