ppussh 0.1.0

package/README.md

@@ -0,0 +1,192 @@
+# ppussh
+
+Official TypeScript/JavaScript SDK for the [PPUSSH](https://ppussh.com) platform —
+Accounts (OIDC / OAuth 2.0) and Payments in a single client.
+
+## Requirements
+
+- Node.js 18+
+- An Accounts **clientId** and **clientSecret** (obtain from the Accounts admin console)
+- A running instance of the Accounts and Payments services
+
+## Installation
+
+```bash
+npm install ppussh
+```
+
+## Configuration
+
+The SDK requires the base URLs for both services. Set them via environment
+variables (recommended for production) or pass them directly to the constructor.
+
+| Environment variable    | Purpose                        |
+| ----------------------- | ------------------------------ |
+| `PPUSSH_ACCOUNTS_URL`   | Base URL of the Accounts API   |
+| `PPUSSH_PAYMENTS_URL`   | Base URL of the Payments API   |
+
+```bash
+export PPUSSH_ACCOUNTS_URL="https://accounts.example.com"
+export PPUSSH_PAYMENTS_URL="https://payments.example.com"
+```
+
+## Quick start
+
+```ts
+import { PpusshClient } from "ppussh";
+
+// URLs are read from PPUSSH_ACCOUNTS_URL / PPUSSH_PAYMENTS_URL env vars,
+// or pass them explicitly:
+const client = new PpusshClient({
+  clientId: "your-product-client-id",
+  clientSecret: "your-product-client-secret",
+  paymentsAdminKey: "your-payments-admin-key", // optional; needed for admin calls
+  // accountsUrl: "https://accounts.example.com", // or set PPUSSH_ACCOUNTS_URL
+  // paymentsUrl: "https://payments.example.com", // or set PPUSSH_PAYMENTS_URL
+});
+```
+
+### OIDC callback (Express example)
+
+```ts
+import express from "express";
+import { PpusshClient } from "ppussh";
+
+const app = express();
+const client = new PpusshClient({ clientId: "...", clientSecret: "..." });
+
+const REDIRECT_URI = "https://yourapp.example.com/auth/callback";
+
+app.get("/auth/callback", async (req, res) => {
+  const { code } = req.query as { code: string };
+  const token = await client.accounts.exchangeCode(code, REDIRECT_URI);
+  // token.user contains the authenticated user's profile
+  res.json({ userId: token.user.id, email: token.user.email });
+});
+```
+
+### Token verification middleware
+
+```ts
+import { PpusshClient, PpusshAuthError } from "ppussh";
+
+const client = new PpusshClient({ clientId: "...", clientSecret: "..." });
+
+async function requireAuth(req: Request): Promise<string> {
+  const auth = req.headers.get("authorization") ?? "";
+  if (!auth.startsWith("Bearer ")) throw new Response(null, { status: 401 });
+  const bearer = auth.slice(7);
+  try {
+    const result = await client.accounts.verifyToken(bearer);
+    return result.userId;
+  } catch (err) {
+    if (err instanceof PpusshAuthError) throw new Response(null, { status: 401 });
+    throw err;
+  }
+}
+```
+
+### Token refresh
+
+```ts
+// Uses the refresh token stored internally after exchangeCode()
+const newToken = await client.accounts.refresh();
+
+// Or pass an explicit refresh token:
+const newToken = await client.accounts.refresh("rt_...");
+```
+
+### Logout
+
+```ts
+await client.accounts.logout(); // uses stored refresh token
+```
+
+### Billing — create a customer and subscription
+
+```ts
+import { randomUUID } from "crypto";
+
+// Create or retrieve a customer record
+const customer = await client.payments.createCustomer(token.user.id, {
+  workspaceId: "ws-123", // optional
+});
+
+// List available plans for a product
+const plans = await client.payments.listPlans("prod-abc");
+
+// Subscribe the customer
+const subscription = await client.payments.createSubscription({
+  customerId: customer.id,
+  paymentProductId: "prod-abc",
+  planKey: "pro",
+  idempotencyKey: randomUUID(),
+});
+```
+
+## Error handling
+
+All exceptions are subclasses of `PpusshError`:
+
+```ts
+import {
+  PpusshError,           // base class
+  PpusshAuthError,       // 401 — invalid or expired token / credentials
+  PpusshConsentRequired, // 403 — user hasn't consented to this product's scopes
+  PpusshPaymentError,    // non-2xx from the Payments service
+  PpusshNetworkError,    // all retries exhausted / connection failure
+} from "ppussh";
+
+try {
+  const token = await client.accounts.exchangeCode(code, REDIRECT_URI);
+} catch (err) {
+  if (err instanceof PpusshConsentRequired) {
+    // Redirect the user to the consent flow
+    redirectToConsent(err.clientId, err.productName);
+  } else if (err instanceof PpusshAuthError) {
+    // Invalid code or expired credentials
+  } else if (err instanceof PpusshNetworkError) {
+    // Retry later
+  }
+}
+```
+
+### Retry policy
+
+| Condition               | Behaviour                                                |
+| ----------------------- | -------------------------------------------------------- |
+| 5xx / network error     | Up to 3 attempts, exponential backoff (0.5 s, 1 s, 2 s) |
+| 429 Too Many Requests   | Respects `Retry-After` header, max 2 retries             |
+| 4xx (not 429)           | Never retried — raises immediately                       |
+
+## API reference
+
+### `client.accounts`
+
+| Method | Description |
+| ------ | ----------- |
+| `exchangeCode(code, redirectUri)` | Exchange an auth code for tokens (OIDC callback) |
+| `refresh(refreshToken?)` | Refresh the access token |
+| `verifyToken(accessToken)` | Validate an incoming bearer token (use in middleware) |
+| `logout(refreshToken?)` | Revoke the session |
+| `getUser(accessToken?)` | Fetch the authenticated user's profile |
+| `getEntitlements(accessToken?)` | List the user's product entitlements |
+| `getSessions(accessToken?)` | List the user's active sessions |
+
+### `client.payments`
+
+| Method | Description |
+| ------ | ----------- |
+| `createCustomer(ownerUserId, opts?)` | Create or retrieve a customer record |
+| `getCustomer(customerId)` | Fetch a customer by ID |
+| `createSubscription(opts)` | Create a subscription |
+| `listSubscriptions(customerId, opts?)` | List subscriptions for a customer |
+| `getSubscription(subscriptionId)` | Fetch a subscription by ID |
+| `cancelSubscription(subscriptionId, opts?)` | Cancel a subscription |
+| `listPlans(paymentProductId)` | List billing plans *(requires `paymentsAdminKey`)* |
+| `getProductByAccountsId(accountsProductId)` | Resolve a payments product by its Accounts ID *(requires `paymentsAdminKey`)* |
+| `getMrr(opts?)` | Fetch MRR analytics *(requires `paymentsAdminKey`)* |
+
+## License
+
+MIT

package/dist/accounts/index.d.ts

@@ -0,0 +1,4 @@
+export type { EntitlementResponse, LogoutResult, SessionResponse, TokenResponse, UserInToken, UserProfile, VerifyTokenResult, } from "./types";
+export { effectiveAccessToken } from "./types";
+export { AccountsNamespace } from "./namespace";
+//# sourceMappingURL=index.d.ts.map

package/dist/accounts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/accounts/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,WAAW,EACX,WAAW,EACX,iBAAiB,GAClB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/accounts/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccountsNamespace = exports.effectiveAccessToken = void 0;
+var types_1 = require("./types");
+Object.defineProperty(exports, "effectiveAccessToken", { enumerable: true, get: function () { return types_1.effectiveAccessToken; } });
+var namespace_1 = require("./namespace");
+Object.defineProperty(exports, "AccountsNamespace", { enumerable: true, get: function () { return namespace_1.AccountsNamespace; } });
+//# sourceMappingURL=index.js.map

package/dist/accounts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/accounts/index.ts"],"names":[],"mappings":";;;AAUA,iCAA+C;AAAtC,6GAAA,oBAAoB,OAAA;AAC7B,yCAAgD;AAAvC,8GAAA,iBAAiB,OAAA"}

package/dist/accounts/namespace.d.ts

@@ -0,0 +1,164 @@
+/**
+ * AccountsNamespace — server-side OIDC + user operations.
+ *
+ * Handles the product-backend half of the OIDC flow:
+ *   buildLoginUrl()   → build the redirect URL to send the user to Accounts (synchronous)
+ *   exchangeCode()    → trade the auth code (from callback URL) for tokens
+ *   refresh()         → rotate tokens using a refresh token
+ *   verifyToken()     → validate an incoming access token (e.g. from a request header)
+ *   logout()          → revoke a session via refresh token (POST /oauth/logout)
+ *   logoutAll()       → revoke ALL sessions via access token (POST /auth/logout)
+ *   revokeSession()   → revoke a single session by ID (DELETE /auth/sessions/{id})
+ *   getUser()         → fetch the full user profile for the stored access token
+ *   getEntitlements() → list entitlements for the authenticated user
+ *   getSessions()     → list active sessions for the authenticated user
+ *
+ * Session state:
+ * After a successful exchangeCode() or refresh() call, the client stores:
+ *   _accessToken    — attached automatically to getUser() / getEntitlements() / getSessions()
+ *   _refreshToken   — used automatically by refresh() and logout() if not passed explicitly
+ *   _tokenExpiresAt — informational; not used for auto-refresh (caller's responsibility)
+ */
+import { HttpTransport } from "../http";
+import { EntitlementResponse, LogoutResult, SessionResponse, TokenResponse, UserProfile, VerifyTokenResult } from "./types";
+export declare class AccountsNamespace {
+    private readonly _http;
+    private readonly _clientId;
+    private readonly _clientSecret;
+    private readonly _accountsUrl;
+    private _accessToken;
+    private _refreshToken;
+    private _tokenExpiresAt;
+    constructor(transport: HttpTransport, options: {
+        clientId: string;
+        clientSecret: string;
+        accountsUrl: string;
+    });
+    /**
+     * Build the URL to redirect the user's browser to the Accounts login page.
+     *
+     * This is step 2 of the OIDC flow — call this in your route handler and
+     * issue a 302 redirect to the returned URL.  The Accounts frontend handles
+     * email/password login as well as Google and GitHub social login; the
+     * product backend never needs to call social-auth endpoints directly.
+     *
+     * @param redirectUri Must exactly match the redirect_uri registered for your product.
+     * @param state       A cryptographically random string stored in the user's session
+     *                    to prevent CSRF attacks.
+     * @param opts.nextUrl Optional URL the Accounts frontend redirects to after login
+     *                     within its own domain (rarely needed).
+     * @returns The full login URL, e.g. `https://accounts.example.com/login?client_id=...`
+     */
+    buildLoginUrl(redirectUri: string, state: string, opts?: {
+        nextUrl?: string;
+    }): string;
+    /**
+     * Exchange the authorization code received on your callback URL for tokens.
+     *
+     * This is step 6 of the OIDC flow — called by your server after the
+     * Accounts frontend redirects the user back to your redirectUri with
+     * `?code=...&state=...` in the query string.
+     *
+     * @param code        The raw 64-char hex auth code from the callback URL.
+     * @param redirectUri Must exactly match the redirect_uri registered for your product.
+     * @returns TokenResponse — contains tokens and an embedded UserInToken.
+     *          Tokens are also stored internally for subsequent calls.
+     * @throws PpusshAuthError        If the code is invalid, expired, or already used.
+     * @throws PpusshConsentRequired  If the user has not consented to your product.
+     * @throws PpusshNetworkError     If the request fails after all retries.
+     */
+    exchangeCode(code: string, redirectUri: string): Promise<TokenResponse>;
+    /**
+     * Rotate tokens using a refresh token.
+     *
+     * If refreshToken is omitted, the internally stored refresh token
+     * from the last exchangeCode() / refresh() call is used.
+     *
+     * @throws PpusshAuthError  If the refresh token is invalid, expired, or replayed.
+     *                          Note: a replayed token causes ALL sessions to be revoked
+     *                          server-side — this is a security feature, not a bug.
+     */
+    refresh(refreshToken?: string): Promise<TokenResponse>;
+    /**
+     * Validate an access token your server received from an end-user request.
+     *
+     * Use this in your middleware / request handler to verify that the Bearer
+     * token a user sent to your product's API is valid and not expired.
+     *
+     * @param accessToken The raw JWT string from the `Authorization: Bearer ...` header.
+     * @returns VerifyTokenResult with valid, type, user_id, and email.
+     * @throws PpusshAuthError  If the token is invalid, expired, or the account is deleted.
+     */
+    verifyToken(accessToken: string): Promise<VerifyTokenResult>;
+    /**
+     * Revoke a session and trigger front-channel logout to all connected products.
+     *
+     * Uses POST /oauth/logout with the refresh token — this is the standard
+     * per-session logout that also notifies downstream products via webhooks.
+     *
+     * If refreshToken is omitted, the internally stored refresh token is used.
+     * On success, stored tokens are cleared from the client instance.
+     *
+     * Logout is always safe to call — if the token is already invalid or the session
+     * doesn't exist, the Accounts server returns ok=true silently.
+     *
+     * @throws PpusshAuthError  If client_id or client_secret are invalid.
+     */
+    logout(refreshToken?: string): Promise<LogoutResult>;
+    /**
+     * Revoke **all** sessions for the current user immediately.
+     *
+     * Uses POST /auth/logout with the access token (Bearer header).
+     * Unlike logout(), this does not require a refresh token and revokes every
+     * active session across all devices — useful for "sign out everywhere" UX.
+     *
+     * On success, stored tokens are cleared from the client instance.
+     *
+     * @param accessToken JWT access token. Optional if stored internally.
+     * @throws PpusshAuthError  If the token is invalid or expired.
+     */
+    logoutAll(accessToken?: string): Promise<void>;
+    /**
+     * Revoke a specific session by its ID.
+     *
+     * Uses DELETE /auth/sessions/{sessionId} — the user can only revoke their
+     * own sessions.  Useful for "sign out of this device" UX in a session
+     * management screen.
+     *
+     * @param sessionId   The UUID of the session to revoke (from getSessions()).
+     * @param accessToken JWT access token. Optional if stored internally.
+     * @throws PpusshAuthError  If the token is invalid or the session does not
+     *                          belong to the authenticated user.
+     */
+    revokeSession(sessionId: string, accessToken?: string): Promise<void>;
+    /**
+     * Fetch the full user profile for an access token.
+     *
+     * If accessToken is omitted, the internally stored token from the last
+     * exchangeCode() or refresh() is used.
+     *
+     * @throws PpusshAuthError  If the token is invalid or expired.
+     */
+    getUser(accessToken?: string): Promise<UserProfile>;
+    /**
+     * List products the user has granted consent to (their entitlements).
+     *
+     * @param accessToken JWT access token. Optional if stored internally.
+     */
+    getEntitlements(accessToken?: string): Promise<EntitlementResponse[]>;
+    /**
+     * List all active sessions for the authenticated user.
+     *
+     * @param accessToken JWT access token. Optional if stored internally.
+     */
+    getSessions(accessToken?: string): Promise<SessionResponse[]>;
+    private _storeTokens;
+    private _clearTokens;
+    /** The currently stored access token, if any. */
+    get accessToken(): string | null;
+    /** The currently stored refresh token, if any. */
+    get refreshToken(): string | null;
+    /** UTC Date at which the stored access token expires, if known. */
+    get tokenExpiresAt(): Date | null;
+}
+//# sourceMappingURL=namespace.d.ts.map

package/dist/accounts/namespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace.d.ts","sourceRoot":"","sources":["../../src/accounts/namespace.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAEL,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,WAAW,EACX,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,eAAe,CAAqB;gBAG1C,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE;IAU1E;;;;;;;;;;;;;;OAcG;IACH,aAAa,CACX,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1B,MAAM;IAcT;;;;;;;;;;;;;;OAcG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAe7E;;;;;;;;;OASG;IACG,OAAO,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAuB5D;;;;;;;;;OASG;IACG,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IASlE;;;;;;;;;;;;;OAaG;IACG,MAAM,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAoB1D;;;;;;;;;;;OAWG;IACG,SAAS,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBpD;;;;;;;;;;;OAWG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe3E;;;;;;;OAOG;IACG,OAAO,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAgBzD;;;;OAIG;IACG,eAAe,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAW3E;;;;OAIG;IACG,WAAW,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAanE,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,YAAY;IAMpB,iDAAiD;IACjD,IAAI,WAAW,IAAI,MAAM,GAAG,IAAI,CAE/B;IAED,kDAAkD;IAClD,IAAI,YAAY,IAAI,MAAM,GAAG,IAAI,CAEhC;IAED,mEAAmE;IACnE,IAAI,cAAc,IAAI,IAAI,GAAG,IAAI,CAEhC;CACF"}

package/dist/accounts/namespace.js

@@ -0,0 +1,293 @@
+"use strict";
+// ppussh/src/accounts/namespace.ts
+/**
+ * AccountsNamespace — server-side OIDC + user operations.
+ *
+ * Handles the product-backend half of the OIDC flow:
+ *   buildLoginUrl()   → build the redirect URL to send the user to Accounts (synchronous)
+ *   exchangeCode()    → trade the auth code (from callback URL) for tokens
+ *   refresh()         → rotate tokens using a refresh token
+ *   verifyToken()     → validate an incoming access token (e.g. from a request header)
+ *   logout()          → revoke a session via refresh token (POST /oauth/logout)
+ *   logoutAll()       → revoke ALL sessions via access token (POST /auth/logout)
+ *   revokeSession()   → revoke a single session by ID (DELETE /auth/sessions/{id})
+ *   getUser()         → fetch the full user profile for the stored access token
+ *   getEntitlements() → list entitlements for the authenticated user
+ *   getSessions()     → list active sessions for the authenticated user
+ *
+ * Session state:
+ * After a successful exchangeCode() or refresh() call, the client stores:
+ *   _accessToken    — attached automatically to getUser() / getEntitlements() / getSessions()
+ *   _refreshToken   — used automatically by refresh() and logout() if not passed explicitly
+ *   _tokenExpiresAt — informational; not used for auto-refresh (caller's responsibility)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccountsNamespace = void 0;
+const types_1 = require("./types");
+class AccountsNamespace {
+    constructor(transport, options) {
+        this._accessToken = null;
+        this._refreshToken = null;
+        this._tokenExpiresAt = null;
+        this._http = transport;
+        this._clientId = options.clientId;
+        this._clientSecret = options.clientSecret;
+        this._accountsUrl = options.accountsUrl;
+    }
+    // ── Login URL builder ──────────────────────────────────────────────────────
+    /**
+     * Build the URL to redirect the user's browser to the Accounts login page.
+     *
+     * This is step 2 of the OIDC flow — call this in your route handler and
+     * issue a 302 redirect to the returned URL.  The Accounts frontend handles
+     * email/password login as well as Google and GitHub social login; the
+     * product backend never needs to call social-auth endpoints directly.
+     *
+     * @param redirectUri Must exactly match the redirect_uri registered for your product.
+     * @param state       A cryptographically random string stored in the user's session
+     *                    to prevent CSRF attacks.
+     * @param opts.nextUrl Optional URL the Accounts frontend redirects to after login
+     *                     within its own domain (rarely needed).
+     * @returns The full login URL, e.g. `https://accounts.example.com/login?client_id=...`
+     */
+    buildLoginUrl(redirectUri, state, opts) {
+        const params = new URLSearchParams({
+            client_id: this._clientId,
+            redirect_uri: redirectUri,
+            state,
+        });
+        if (opts?.nextUrl) {
+            params.set("next", opts.nextUrl);
+        }
+        return `${this._accountsUrl}/login?${params.toString()}`;
+    }
+    // ── OIDC token exchange ────────────────────────────────────────────────────
+    /**
+     * Exchange the authorization code received on your callback URL for tokens.
+     *
+     * This is step 6 of the OIDC flow — called by your server after the
+     * Accounts frontend redirects the user back to your redirectUri with
+     * `?code=...&state=...` in the query string.
+     *
+     * @param code        The raw 64-char hex auth code from the callback URL.
+     * @param redirectUri Must exactly match the redirect_uri registered for your product.
+     * @returns TokenResponse — contains tokens and an embedded UserInToken.
+     *          Tokens are also stored internally for subsequent calls.
+     * @throws PpusshAuthError        If the code is invalid, expired, or already used.
+     * @throws PpusshConsentRequired  If the user has not consented to your product.
+     * @throws PpusshNetworkError     If the request fails after all retries.
+     */
+    async exchangeCode(code, redirectUri) {
+        const response = await this._http.request("POST", "/oauth/token", {
+            form: {
+                grant_type: "authorization_code",
+                code,
+                client_id: this._clientId,
+                client_secret: this._clientSecret,
+                redirect_uri: redirectUri,
+            },
+        });
+        const token = response.data;
+        this._storeTokens(token);
+        return token;
+    }
+    /**
+     * Rotate tokens using a refresh token.
+     *
+     * If refreshToken is omitted, the internally stored refresh token
+     * from the last exchangeCode() / refresh() call is used.
+     *
+     * @throws PpusshAuthError  If the refresh token is invalid, expired, or replayed.
+     *                          Note: a replayed token causes ALL sessions to be revoked
+     *                          server-side — this is a security feature, not a bug.
+     */
+    async refresh(refreshToken) {
+        const tokenToUse = refreshToken ?? this._refreshToken;
+        if (!tokenToUse) {
+            throw new Error("No refreshToken provided and none stored. " +
+                "Call exchangeCode() first or pass refreshToken explicitly.");
+        }
+        const response = await this._http.request("POST", "/oauth/token", {
+            form: {
+                grant_type: "refresh_token",
+                refresh_token: tokenToUse,
+                client_id: this._clientId,
+                client_secret: this._clientSecret,
+            },
+        });
+        const token = response.data;
+        this._storeTokens(token);
+        return token;
+    }
+    // ── Token verification ─────────────────────────────────────────────────────
+    /**
+     * Validate an access token your server received from an end-user request.
+     *
+     * Use this in your middleware / request handler to verify that the Bearer
+     * token a user sent to your product's API is valid and not expired.
+     *
+     * @param accessToken The raw JWT string from the `Authorization: Bearer ...` header.
+     * @returns VerifyTokenResult with valid, type, user_id, and email.
+     * @throws PpusshAuthError  If the token is invalid, expired, or the account is deleted.
+     */
+    async verifyToken(accessToken) {
+        const response = await this._http.request("GET", "/auth/verify-token", {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+        return response.data;
+    }
+    // ── Logout ─────────────────────────────────────────────────────────────────
+    /**
+     * Revoke a session and trigger front-channel logout to all connected products.
+     *
+     * Uses POST /oauth/logout with the refresh token — this is the standard
+     * per-session logout that also notifies downstream products via webhooks.
+     *
+     * If refreshToken is omitted, the internally stored refresh token is used.
+     * On success, stored tokens are cleared from the client instance.
+     *
+     * Logout is always safe to call — if the token is already invalid or the session
+     * doesn't exist, the Accounts server returns ok=true silently.
+     *
+     * @throws PpusshAuthError  If client_id or client_secret are invalid.
+     */
+    async logout(refreshToken) {
+        const tokenToUse = refreshToken ?? this._refreshToken;
+        if (!tokenToUse) {
+            throw new Error("No refreshToken provided and none stored. " +
+                "Call exchangeCode() first or pass refreshToken explicitly.");
+        }
+        const response = await this._http.request("POST", "/oauth/logout", {
+            json: {
+                refresh_token: tokenToUse,
+                client_id: this._clientId,
+                client_secret: this._clientSecret,
+            },
+        });
+        const result = response.data;
+        this._clearTokens();
+        return result;
+    }
+    /**
+     * Revoke **all** sessions for the current user immediately.
+     *
+     * Uses POST /auth/logout with the access token (Bearer header).
+     * Unlike logout(), this does not require a refresh token and revokes every
+     * active session across all devices — useful for "sign out everywhere" UX.
+     *
+     * On success, stored tokens are cleared from the client instance.
+     *
+     * @param accessToken JWT access token. Optional if stored internally.
+     * @throws PpusshAuthError  If the token is invalid or expired.
+     */
+    async logoutAll(accessToken) {
+        const tokenToUse = accessToken ?? this._accessToken;
+        if (!tokenToUse) {
+            throw new Error("No accessToken provided and none stored. " +
+                "Call exchangeCode() first or pass accessToken explicitly.");
+        }
+        await this._http.request("POST", "/auth/logout", {
+            headers: { Authorization: `Bearer ${tokenToUse}` },
+        });
+        this._clearTokens();
+    }
+    // ── Session management ─────────────────────────────────────────────────────
+    /**
+     * Revoke a specific session by its ID.
+     *
+     * Uses DELETE /auth/sessions/{sessionId} — the user can only revoke their
+     * own sessions.  Useful for "sign out of this device" UX in a session
+     * management screen.
+     *
+     * @param sessionId   The UUID of the session to revoke (from getSessions()).
+     * @param accessToken JWT access token. Optional if stored internally.
+     * @throws PpusshAuthError  If the token is invalid or the session does not
+     *                          belong to the authenticated user.
+     */
+    async revokeSession(sessionId, accessToken) {
+        const tokenToUse = accessToken ?? this._accessToken;
+        if (!tokenToUse) {
+            throw new Error("No accessToken provided and none stored. " +
+                "Call exchangeCode() first or pass accessToken explicitly.");
+        }
+        await this._http.request("DELETE", `/auth/sessions/${sessionId}`, {
+            headers: { Authorization: `Bearer ${tokenToUse}` },
+        });
+    }
+    // ── User profile ───────────────────────────────────────────────────────────
+    /**
+     * Fetch the full user profile for an access token.
+     *
+     * If accessToken is omitted, the internally stored token from the last
+     * exchangeCode() or refresh() is used.
+     *
+     * @throws PpusshAuthError  If the token is invalid or expired.
+     */
+    async getUser(accessToken) {
+        const tokenToUse = accessToken ?? this._accessToken;
+        if (!tokenToUse) {
+            throw new Error("No accessToken provided and none stored. " +
+                "Call exchangeCode() first or pass accessToken explicitly.");
+        }
+        const response = await this._http.request("GET", "/users/me", {
+            headers: { Authorization: `Bearer ${tokenToUse}` },
+        });
+        return response.data;
+    }
+    // ── Entitlements & sessions ────────────────────────────────────────────────
+    /**
+     * List products the user has granted consent to (their entitlements).
+     *
+     * @param accessToken JWT access token. Optional if stored internally.
+     */
+    async getEntitlements(accessToken) {
+        const tokenToUse = accessToken ?? this._accessToken;
+        if (!tokenToUse) {
+            throw new Error("No accessToken provided and none stored.");
+        }
+        const response = await this._http.request("GET", "/users/me/entitlements", {
+            headers: { Authorization: `Bearer ${tokenToUse}` },
+        });
+        return response.data;
+    }
+    /**
+     * List all active sessions for the authenticated user.
+     *
+     * @param accessToken JWT access token. Optional if stored internally.
+     */
+    async getSessions(accessToken) {
+        const tokenToUse = accessToken ?? this._accessToken;
+        if (!tokenToUse) {
+            throw new Error("No accessToken provided and none stored.");
+        }
+        const response = await this._http.request("GET", "/users/me/sessions", {
+            headers: { Authorization: `Bearer ${tokenToUse}` },
+        });
+        return response.data;
+    }
+    // ── Internal token management ──────────────────────────────────────────────
+    _storeTokens(token) {
+        this._accessToken = (0, types_1.effectiveAccessToken)(token);
+        this._refreshToken = token.refresh_token;
+        this._tokenExpiresAt = new Date(Date.now() + token.expires_in * 1000);
+    }
+    _clearTokens() {
+        this._accessToken = null;
+        this._refreshToken = null;
+        this._tokenExpiresAt = null;
+    }
+    /** The currently stored access token, if any. */
+    get accessToken() {
+        return this._accessToken;
+    }
+    /** The currently stored refresh token, if any. */
+    get refreshToken() {
+        return this._refreshToken;
+    }
+    /** UTC Date at which the stored access token expires, if known. */
+    get tokenExpiresAt() {
+        return this._tokenExpiresAt;
+    }
+}
+exports.AccountsNamespace = AccountsNamespace;
+//# sourceMappingURL=namespace.js.map