@rekey.dev/node 2.0.0-rc.3 → 2.0.0-rc.4

package/dist/index.js

@@ -20,8 +20,20 @@
  * ```
  */
 // The canonical error class lives in shared-types; import it for internal use
-// and re-export below so @rekey.dev/node's public surface is unchanged.
-import { RekeyError } from '@rekey.dev/shared-types';
+// and re-export below so @rekey.dev/node's public surface is unchanged. The
+// `/error` subpath is the zod-free module the class actually lives in — same
+// class object the barrel re-exports, so `instanceof` is identical.
+import { RekeyError } from '@rekey.dev/shared-types/error';
+/**
+ * Default per-request deadline, in milliseconds. Matches the timeout the Rekey
+ * API itself uses when it POSTs your outbound webhooks.
+ *
+ * Without a deadline the effective timeout is undici's `headersTimeout` — five
+ * minutes — so a single unreachable Rekey deployment can pin one of your
+ * request handlers for that long. Ten seconds is long enough for any endpoint
+ * this SDK calls and short enough to fail a page instead of hanging it.
+ */
+export const DEFAULT_TIMEOUT_MS = 10_000;
 // RekeyError is the shared class (imported above) — re-exported so the public
 // API name is preserved and `instanceof` is consistent with @rekey.dev/react.
 export { RekeyError };
@@ -42,6 +54,25 @@ export { RekeyError };
  * ```
  */
 export { WEBHOOK_EVENTS, KNOWN_WEBHOOK_EVENTS, isKnownWebhookEvent } from '@rekey.dev/shared-types';
+/**
+ * Would `cancelSubscription`'s default (`atPeriodEnd: true`) actually leave
+ * this subscriber the rest of the period they paid for?
+ *
+ * Exported because a cancel confirmation has to say which outcome the customer
+ * is about to get, and it has to say so BEFORE the call — there is no response
+ * to read it off. It is the same function the API decides from, not a
+ * description of it, so a UI built on it cannot promise a behaviour the server
+ * does not have. See its docblock for the cases that still end immediately.
+ *
+ * @example
+ * ```ts
+ * const sub = await rekey.billing.getSubscription(token);
+ * const message = sub && cancelsAtPeriodEnd(sub)
+ *   ? `You keep access until ${sub.currentPeriodEnd}.`
+ *   : 'Cancelling takes effect straight away.';
+ * ```
+ */
+export { cancelsAtPeriodEnd } from '@rekey.dev/shared-types';
 /**
  * Top-level Rekey client. Auth and billing live as namespaces
  * (`rekey.applications`, `rekey.auth`, `rekey.billing`) so an agent
@@ -51,6 +82,9 @@ export class Rekey {
     apiUrl;
     secretKey;
     fetchImpl;
+    timeoutMs;
+    signal;
+    config;
     /** Operations on the calling Application itself. */
     applications;
     /** Auth operations — sign-in, sign-up, sessions, passkeys, magic-link. */
@@ -82,9 +116,12 @@ export class Rekey {
                 fix: 'Get a key from the Rekey panel under Application → API Keys, then pass it as `secretKey`.',
             });
         }
+        this.config = config;
         this.apiUrl = config.apiUrl.replace(/\/$/, '');
         this.secretKey = config.secretKey;
         this.fetchImpl = config.fetch ?? fetch;
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.signal = config.signal;
         this.applications = new ApplicationsClient(this);
         this.auth = new AuthClient(this);
         this.billing = new BillingClient(this);
@@ -94,9 +131,75 @@ export class Rekey {
         this.credits = new CreditsClient(this);
         this.mcp = new McpClient(this);
     }
-    /** @internal */
-    async request(method, path, body, extraHeaders) {
-        const res = await this.fetchImpl(`${this.apiUrl}${path}`, {
+    /**
+     * A clone of this client with different call options — the per-call knob for
+     * every wrapped method.
+     *
+     * Each namespace method (`billing.getPlans()`, `auth.signIn()`, …) has a
+     * fixed signature, so scoping one call is done by scoping the client rather
+     * than by threading an options argument through sixty-odd methods:
+     *
+     * @example Give one call a tighter deadline
+     * ```ts
+     * const plans = await rekey.with({ timeoutMs: 2_000 }).billing.getPlans();
+     * ```
+     *
+     * @example Tie every Rekey call to an inbound request's lifetime
+     * ```ts
+     * app.get('/me', async (req, res) => {
+     *   const scoped = rekey.with({ signal: AbortSignal.any([req.signal]) });
+     *   res.json(await scoped.auth.getCurrentUser(token));
+     * });
+     * ```
+     *
+     * Cheap — it rebuilds the namespace objects, holds no connections, and
+     * shares the same `fetch`.
+     */
+    with(options) {
+        const signal = options.signal && this.signal
+            ? AbortSignal.any([this.signal, options.signal])
+            : (options.signal ?? this.signal);
+        return new Rekey({
+            ...this.config,
+            timeoutMs: options.timeoutMs ?? this.config.timeoutMs,
+            ...(signal !== undefined && { signal }),
+        });
+    }
+    /**
+     * Call a Rekey endpoint this SDK does not wrap yet.
+     *
+     * This is a **supported** escape hatch, not an internal: when the API grows a
+     * route before the SDK does, use this instead of hand-rolling `fetch` — you
+     * keep the auth header, the `{ success, data }` unwrapping, the `RekeyError`
+     * mapping (including transport failures) and the deadline. It takes an
+     * options object precisely so a future knob does not need a new overload.
+     *
+     * Prefer a namespace method when one exists; those carry the endpoint's real
+     * types, this returns whatever `T` you claim.
+     *
+     * @example
+     * ```ts
+     * const seats = await rekey.request<{ used: number }>('GET', '/api/v1/seats');
+     *
+     * await rekey.request('POST', '/api/v1/seats', {
+     *   body: { count: 5 },
+     *   timeoutMs: 30_000,
+     * });
+     * ```
+     *
+     * @throws {RekeyError} the server's error envelope, or `REQUEST_TIMEOUT` /
+     * `REQUEST_ABORTED` / `NETWORK_ERROR` when the request never got an answer.
+     */
+    request(method, path, options) {
+        return this.send(method, path, options?.body, options?.headers, options);
+    }
+    /**
+     * @internal Positional workhorse behind {@link request}. Every wrapped method
+     * calls this; it stays positional because it is not part of the published
+     * surface (see `stripInternal` in tsconfig).
+     */
+    async send(method, path, body, extraHeaders, options) {
+        const res = await this.fetchWithDeadline(`${this.apiUrl}${path}`, {
             method,
             headers: {
                 Authorization: `Bearer ${this.secretKey}`,
@@ -104,8 +207,8 @@ export class Rekey {
                 ...extraHeaders,
             },
             ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
-        });
-        const json = (await res.json().catch(() => ({})));
+        }, method, path, options);
+        const json = (await this.readJson(res, method, path, options));
         if (!res.ok || ('success' in json && json.success === false)) {
             const requestId = res.headers.get('x-request-id') ?? undefined;
             const err = 'error' in json
@@ -130,16 +233,16 @@ export class Rekey {
      * `{ success, data }` envelope). Throws `RekeyError` on non-2xx, mapping
      * the OAuth `{ error, error_description }` body when present.
      */
-    async requestRaw(method, path, body, auth = true) {
-        const res = await this.fetchImpl(`${this.apiUrl}${path}`, {
+    async requestRaw(method, path, body, auth = true, options) {
+        const res = await this.fetchWithDeadline(`${this.apiUrl}${path}`, {
             method,
             headers: {
                 ...(auth ? { Authorization: `Bearer ${this.secretKey}` } : {}),
                 ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
             },
             ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
-        });
-        const json = (await res.json().catch(() => ({})));
+        }, method, path, options);
+        const json = (await this.readJson(res, method, path, options));
         if (!res.ok) {
             const code = typeof json.error === 'string' ? json.error : `HTTP_${res.status}`;
             const message = typeof json.error_description === 'string'
@@ -149,6 +252,82 @@ export class Rekey {
         }
         return json;
     }
+    /**
+     * @internal The one place `fetch` is called. Applies the deadline, composes
+     * the caller's signals, and turns anything the transport throws into a
+     * `RekeyError` — without this, `ECONNREFUSED` escaped as a bare `TypeError`
+     * and slipped straight through the documented
+     * `catch (e) { if (e instanceof RekeyError) … }` pattern.
+     */
+    async fetchWithDeadline(url, init, method, path, options) {
+        const deadline = createDeadline(options?.timeoutMs ?? this.timeoutMs, this.signal, options?.signal);
+        try {
+            return await this.fetchImpl(url, {
+                ...init,
+                ...(deadline.signal ? { signal: deadline.signal } : {}),
+            });
+        }
+        catch (cause) {
+            throw transportError(cause, deadline, method, path);
+        }
+    }
+    /**
+     * @internal Read the JSON body under the same deadline. A body that never
+     * finishes streaming is just as hanging as headers that never arrive, and a
+     * non-JSON body still degrades to `{}` the way it always did.
+     */
+    async readJson(res, method, path, options) {
+        try {
+            return await res.json();
+        }
+        catch (cause) {
+            if (isAbortError(cause)) {
+                throw transportError(cause, createDeadline(options?.timeoutMs ?? this.timeoutMs, this.signal, options?.signal), method, path);
+            }
+            return {};
+        }
+    }
+}
+function createDeadline(timeoutMs, clientSignal, callSignal) {
+    const callerSignals = [clientSignal, callSignal].filter((s) => s !== undefined);
+    const timer = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
+    const all = timer ? [timer, ...callerSignals] : callerSignals;
+    const signal = all.length === 0 ? undefined : all.length === 1 ? all[0] : AbortSignal.any(all);
+    return { signal, timeoutMs, timer, callerSignals };
+}
+function isAbortError(err) {
+    return (err instanceof Error && (err.name === 'AbortError' || err.name === 'TimeoutError'));
+}
+/**
+ * Map whatever `fetch` rejected with onto a `RekeyError`. Three codes, because
+ * three different things go wrong and they want different responses:
+ * `REQUEST_ABORTED` (you asked), `REQUEST_TIMEOUT` (retry / raise the limit),
+ * `NETWORK_ERROR` (check the URL, DNS, TLS).
+ */
+function transportError(cause, deadline, method, path) {
+    const where = `${method} ${path}`;
+    if (deadline.callerSignals.some((s) => s.aborted)) {
+        return new RekeyError({
+            code: 'REQUEST_ABORTED',
+            message: `${where} was aborted by the caller's AbortSignal.`,
+            fix: 'This is your own cancellation — swallow it, or check the signal you passed to `signal` / `Rekey.with({ signal })`.',
+            cause,
+        });
+    }
+    if (deadline.timer?.aborted || (isAbortError(cause) && deadline.timer !== undefined)) {
+        return new RekeyError({
+            code: 'REQUEST_TIMEOUT',
+            message: `${where} exceeded the ${deadline.timeoutMs}ms request deadline.`,
+            fix: 'Retry, or raise `timeoutMs` on the client / this call if the endpoint is legitimately slow. If it never responds, check `apiUrl` points at a reachable Rekey deployment.',
+            cause,
+        });
+    }
+    return new RekeyError({
+        code: 'NETWORK_ERROR',
+        message: `${where} failed before the server answered: ${cause instanceof Error ? cause.message : String(cause)}`,
+        fix: 'Check `apiUrl`, DNS, and that the Rekey deployment is reachable from this host. The underlying error is on `error.cause`.',
+        cause,
+    });
 }
 /**
  * MCP helpers for customers running their OWN MCP server behind Rekey auth.
@@ -165,7 +344,7 @@ class McpClient {
     async slug() {
         if (this.slugCache)
             return this.slugCache;
-        const app = await this.client.request('GET', '/api/v1/me/');
+        const app = await this.client.send('GET', '/api/v1/me/');
         this.slugCache = app.slug;
         return app.slug;
     }
@@ -208,7 +387,7 @@ class ApplicationsClient {
      * @throws {RekeyError} with `code: "API_KEY_INVALID"` if the key is wrong/revoked/expired.
      */
     me() {
-        return this.client.request('GET', '/api/v1/me/');
+        return this.client.send('GET', '/api/v1/me/');
     }
 }
 class AuthClient {
@@ -239,7 +418,7 @@ class AuthClient {
      * @throws {RekeyError} `AUTH_METHOD_DISABLED` (400) if the Application doesn't have `"password"` enabled.
      */
     signUp(input) {
-        return this.client.request('POST', '/api/v1/auth/sign-up', input);
+        return this.client.send('POST', '/api/v1/auth/sign-up', input);
     }
     /**
      * Authenticate an existing end-user with email + password.
@@ -261,7 +440,7 @@ class AuthClient {
      *   `sendVerificationEmail`), not for the password again.
      */
     signIn(input) {
-        return this.client.request('POST', '/api/v1/auth/sign-in', input);
+        return this.client.send('POST', '/api/v1/auth/sign-in', input);
     }
     /**
      * Exchange an MFA challenge token + TOTP/backup code for a real session.
@@ -275,7 +454,7 @@ class AuthClient {
      *   verify against the user's TOTP secret or remaining backup codes.
      */
     mfaVerify(input) {
-        return this.client.request('POST', '/api/v1/auth/mfa-verify', input);
+        return this.client.send('POST', '/api/v1/auth/mfa-verify', input);
     }
     /**
      * Request a magic-link sign-in email. Enumeration-safe: same response
@@ -284,7 +463,7 @@ class AuthClient {
      * is null; otherwise the raw token is returned for you to forward.
      */
     requestMagicLink(input) {
-        return this.client.request('POST', '/api/v1/auth/magic-link/request', input);
+        return this.client.send('POST', '/api/v1/auth/magic-link/request', input);
     }
     /**
      * Consume a magic-link token. Returns `SignInOutcome` — branch on
@@ -293,7 +472,7 @@ class AuthClient {
      * `mfaVerify(...)`.
      */
     verifyMagicLink(input) {
-        return this.client.request('POST', '/api/v1/auth/magic-link/verify', input);
+        return this.client.send('POST', '/api/v1/auth/magic-link/verify', input);
     }
     /**
      * Begin a passkey authentication ceremony. Returns the WebAuthn options
@@ -302,7 +481,7 @@ class AuthClient {
      * pass both back via `verifyPasskeyAuthentication(...)`.
      */
     startPasskeyAuthentication(input) {
-        return this.client.request('POST', '/api/v1/auth/passkey/authenticate/start', input ?? {});
+        return this.client.send('POST', '/api/v1/auth/passkey/authenticate/start', input ?? {});
     }
     /**
      * Complete a passkey authentication. Returns the same `SignInOutcome`
@@ -310,7 +489,7 @@ class AuthClient {
      * `mfaRequired` will always be `false` in practice.
      */
     verifyPasskeyAuthentication(input) {
-        return this.client.request('POST', '/api/v1/auth/passkey/authenticate/complete', input);
+        return this.client.send('POST', '/api/v1/auth/passkey/authenticate/complete', input);
     }
     /**
      * Begin a passkey registration ceremony for an authenticated user.
@@ -319,24 +498,29 @@ class AuthClient {
      * `verifyPasskeyRegistration(...)`.
      */
     startPasskeyRegistration(accessToken) {
-        return this.client.request('POST', '/api/v1/auth/passkey/register/start', undefined, {
+        return this.client.send('POST', '/api/v1/auth/passkey/register/start', undefined, {
             'X-Rekey-User-Token': accessToken,
         });
     }
     verifyPasskeyRegistration(accessToken, input) {
-        return this.client.request('POST', '/api/v1/auth/passkey/register/complete', input, {
+        return this.client.send('POST', '/api/v1/auth/passkey/register/complete', input, {
             'X-Rekey-User-Token': accessToken,
         });
     }
-    /** List the user's registered passkeys. */
-    listPasskeys(accessToken) {
-        return this.client.request('GET', '/api/v1/auth/passkeys', undefined, {
+    /**
+     * List the user's registered passkeys, newest first.
+     *
+     * Returns `{items, page}` — `page.total` is the number of passkeys the user
+     * has, independent of the window served.
+     */
+    listPasskeys(accessToken, page) {
+        return this.client.send('GET', `/api/v1/auth/passkeys${listQuery(page)}`, undefined, {
             'X-Rekey-User-Token': accessToken,
         });
     }
     /** Remove a passkey. Returns `{deleted: false}` if the row doesn't belong to this user. */
     deletePasskey(accessToken, credentialRowId) {
-        return this.client.request('DELETE', `/api/v1/auth/passkeys/${encodeURIComponent(credentialRowId)}`, undefined, { 'X-Rekey-User-Token': accessToken });
+        return this.client.send('DELETE', `/api/v1/auth/passkeys/${encodeURIComponent(credentialRowId)}`, undefined, { 'X-Rekey-User-Token': accessToken });
     }
     // End-user organization / team methods live on `rekey.organizations.*`
     // (OrganizationsClient) — the canonical, fuller surface. The earlier
@@ -351,7 +535,7 @@ class AuthClient {
      *   by a different Application than the calling secret key represents.
      */
     getCurrentUser(accessToken) {
-        return this.client.request('GET', '/api/v1/users/me/', undefined, {
+        return this.client.send('GET', '/api/v1/users/me/', undefined, {
             'X-Rekey-User-Token': accessToken,
         });
     }
@@ -383,7 +567,7 @@ class AuthClient {
      * @throws {RekeyError} `USER_TOKEN_INVALID` (401) if expired/forged/wrong-secret.
      */
     updateCurrentUser(accessToken, input) {
-        return this.client.request('PATCH', '/api/v1/users/me/', input, {
+        return this.client.send('PATCH', '/api/v1/users/me/', input, {
             'X-Rekey-User-Token': accessToken,
         });
     }
@@ -400,7 +584,7 @@ class AuthClient {
         // /auth/refresh returns the same shape as /auth/mfa-verify — always a
         // full session (refresh requires a prior MFA-verified session by
         // definition).
-        return this.client.request('POST', '/api/v1/auth/refresh', { refreshToken });
+        return this.client.send('POST', '/api/v1/auth/refresh', { refreshToken });
     }
     /**
      * Revoke a refresh token. Idempotent — no-op for unknown tokens. The
@@ -409,7 +593,7 @@ class AuthClient {
      * the access token from your client.
      */
     signOut(refreshToken) {
-        return this.client.request('POST', '/api/v1/auth/sign-out', { refreshToken });
+        return this.client.send('POST', '/api/v1/auth/sign-out', { refreshToken });
     }
     /**
      * Request a password reset for an email. Always succeeds — never tells you
@@ -431,7 +615,7 @@ class AuthClient {
      * ```
      */
     requestPasswordReset(input) {
-        return this.client.request('POST', '/api/v1/auth/forgot-password', input);
+        return this.client.send('POST', '/api/v1/auth/forgot-password', input);
     }
     /**
      * Consume a reset token + set a new password. Single-use. On success,
@@ -441,7 +625,7 @@ class AuthClient {
      * @throws {RekeyError} `PASSWORD_TOO_SHORT` if below the Application's `passwordMinLength`
      */
     resetPassword(input) {
-        return this.client.request('POST', '/api/v1/auth/reset-password', input);
+        return this.client.send('POST', '/api/v1/auth/reset-password', input);
     }
     /**
      * Authenticated password change. Pass the user's *current* access token.
@@ -449,7 +633,7 @@ class AuthClient {
      * are signed out.
      */
     changePassword(accessToken, input) {
-        return this.client.request('POST', '/api/v1/auth/change-password', input, {
+        return this.client.send('POST', '/api/v1/auth/change-password', input, {
             'X-Rekey-User-Token': accessToken,
         });
     }
@@ -459,7 +643,7 @@ class AuthClient {
      * — clear it client-side for full logout.
      */
     signOutEverywhere(accessToken) {
-        return this.client.request('POST', '/api/v1/auth/sign-out-everywhere', undefined, { 'X-Rekey-User-Token': accessToken });
+        return this.client.send('POST', '/api/v1/auth/sign-out-everywhere', undefined, { 'X-Rekey-User-Token': accessToken });
     }
     /**
      * Send (or re-send) an email-verification link to the current user.
@@ -471,7 +655,7 @@ class AuthClient {
      * (e.g. `https://app.example.com/verify?t={token}`).
      */
     sendVerificationEmail(accessToken, input) {
-        return this.client.request('POST', '/api/v1/auth/send-verification', input ?? {}, {
+        return this.client.send('POST', '/api/v1/auth/send-verification', input ?? {}, {
             'X-Rekey-User-Token': accessToken,
         });
     }
@@ -509,7 +693,7 @@ class AuthClient {
      * ```
      */
     resendVerificationEmail(input) {
-        return this.client.request('POST', '/api/v1/auth/resend-verification', input);
+        return this.client.send('POST', '/api/v1/auth/resend-verification', input);
     }
     /**
      * Consume an email-verification token. Single-use, 24-hour lifetime.
@@ -517,7 +701,7 @@ class AuthClient {
      * tokens are refused with `EMAIL_VERIFICATION_TOKEN_WRONG_APPLICATION`.
      */
     verifyEmail(input) {
-        return this.client.request('POST', '/api/v1/auth/verify-email', input);
+        return this.client.send('POST', '/api/v1/auth/verify-email', input);
     }
     // ---------- Active sessions ----------
     /**
@@ -525,14 +709,14 @@ class AuthClient {
      * first. Each carries the User-Agent + IP captured at issue time and an
      * `id` you can pass to `revokeSession(...)`.
      */
-    listSessions(accessToken) {
-        return this.client.request('GET', '/api/v1/auth/sessions', undefined, {
+    listSessions(accessToken, page) {
+        return this.client.send('GET', `/api/v1/auth/sessions${listQuery(page)}`, undefined, {
             'X-Rekey-User-Token': accessToken,
         });
     }
     /** Revoke one session by id. Idempotent — `{ revoked: false }` if it isn't this user's. */
     revokeSession(accessToken, sessionId) {
-        return this.client.request('DELETE', `/api/v1/auth/sessions/${encodeURIComponent(sessionId)}`, undefined, { 'X-Rekey-User-Token': accessToken });
+        return this.client.send('DELETE', `/api/v1/auth/sessions/${encodeURIComponent(sessionId)}`, undefined, { 'X-Rekey-User-Token': accessToken });
     }
     // ---------- MFA enrollment / management ----------
     //
@@ -542,7 +726,7 @@ class AuthClient {
     // (403) when the policy is "off".
     /** MFA enrollment status for the current user, plus the Application's policy. */
     mfaStatus(accessToken) {
-        return this.client.request('GET', '/api/v1/auth/mfa/status', undefined, {
+        return this.client.send('GET', '/api/v1/auth/mfa/status', undefined, {
             'X-Rekey-User-Token': accessToken,
         });
     }
@@ -552,13 +736,13 @@ class AuthClient {
      * Only SHA-256 hashes of the backup codes are stored — show them once.
      */
     mfaSetup(accessToken) {
-        return this.client.request('POST', '/api/v1/auth/mfa/setup', undefined, {
+        return this.client.send('POST', '/api/v1/auth/mfa/setup', undefined, {
             'X-Rekey-User-Token': accessToken,
         });
     }
     /** Confirm enrollment by submitting the current 6-digit TOTP code. */
     confirmMfaSetup(accessToken, code) {
-        return this.client.request('POST', '/api/v1/auth/mfa/setup-confirm', { code }, {
+        return this.client.send('POST', '/api/v1/auth/mfa/setup-confirm', { code }, {
             'X-Rekey-User-Token': accessToken,
         });
     }
@@ -567,13 +751,13 @@ class AuthClient {
      * Backup codes are single-use — consumed on success. Returns `{ ok }`.
      */
     mfaChallenge(accessToken, code) {
-        return this.client.request('POST', '/api/v1/auth/mfa/challenge', { code }, {
+        return this.client.send('POST', '/api/v1/auth/mfa/challenge', { code }, {
             'X-Rekey-User-Token': accessToken,
         });
     }
     /** Disable MFA for the current user. */
     disableMfa(accessToken) {
-        return this.client.request('POST', '/api/v1/auth/mfa/disable', undefined, {
+        return this.client.send('POST', '/api/v1/auth/mfa/disable', undefined, {
             'X-Rekey-User-Token': accessToken,
         });
     }
@@ -587,7 +771,7 @@ class AuthClient {
      * unguessable `state` and verify it on return before calling `completeOAuth`.
      */
     startOAuth(provider, state) {
-        return this.client.request('POST', `/api/v1/auth/oauth/${encodeURIComponent(provider)}/start`, { state });
+        return this.client.send('POST', `/api/v1/auth/oauth/${encodeURIComponent(provider)}/start`, { state });
     }
     /**
      * Exchange the provider `code` for a Rekey session. Returns a
@@ -595,17 +779,17 @@ class AuthClient {
      * Verify the `state` CSRF value yourself before calling.
      */
     completeOAuth(provider, code) {
-        return this.client.request('POST', `/api/v1/auth/oauth/${encodeURIComponent(provider)}/callback`, { code });
+        return this.client.send('POST', `/api/v1/auth/oauth/${encodeURIComponent(provider)}/callback`, { code });
     }
     /** List the OAuth providers linked to the current user. */
     listOAuthIdentities(accessToken) {
-        return this.client.request('GET', '/api/v1/auth/oauth/identities', undefined, {
+        return this.client.send('GET', '/api/v1/auth/oauth/identities', undefined, {
             'X-Rekey-User-Token': accessToken,
         });
     }
     /** Begin linking a provider to the *currently authenticated* user. */
     startOAuthLink(accessToken, provider, state) {
-        return this.client.request('POST', `/api/v1/auth/oauth/${encodeURIComponent(provider)}/link/start`, { state }, { 'X-Rekey-User-Token': accessToken });
+        return this.client.send('POST', `/api/v1/auth/oauth/${encodeURIComponent(provider)}/link/start`, { state }, { 'X-Rekey-User-Token': accessToken });
     }
     /**
      * Complete an OAuth link — attaches the provider identity to the current
@@ -613,14 +797,14 @@ class AuthClient {
      * when the provider account already belongs to a different user.
      */
     completeOAuthLink(accessToken, provider, code) {
-        return this.client.request('POST', `/api/v1/auth/oauth/${encodeURIComponent(provider)}/link/complete`, { code }, { 'X-Rekey-User-Token': accessToken });
+        return this.client.send('POST', `/api/v1/auth/oauth/${encodeURIComponent(provider)}/link/complete`, { code }, { 'X-Rekey-User-Token': accessToken });
     }
     /**
      * Remove a linked provider. Refuses with `OAUTH_UNLINK_WOULD_LOCK_OUT` (409)
      * if it would leave the account with no way to sign in.
      */
     unlinkOAuth(accessToken, provider) {
-        return this.client.request('DELETE', `/api/v1/auth/oauth/${encodeURIComponent(provider)}`, undefined, { 'X-Rekey-User-Token': accessToken });
+        return this.client.send('DELETE', `/api/v1/auth/oauth/${encodeURIComponent(provider)}`, undefined, { 'X-Rekey-User-Token': accessToken });
     }
 }
 function listQuery(page) {
@@ -641,47 +825,55 @@ class OrganizationsClient {
     }
     /** Create an organization; the calling user becomes the OWNER. */
     create(accessToken, input) {
-        return this.client.request('POST', '/api/v1/users/me/organizations/', input, {
+        return this.client.send('POST', '/api/v1/users/me/organizations/', input, {
             'X-Rekey-User-Token': accessToken,
         });
     }
-    /** List organizations the calling user belongs to, with their role. The
-     *  result is paginated (default 50, max 100); pass `page.offset` for more. */
+    /**
+     * List organizations the calling user belongs to, with their role.
+     *
+     * Paginated (default 50, max 100). Read `page.hasMore` / `page.total` from
+     * the result rather than guessing from `items.length`.
+     */
     listMine(accessToken, page) {
-        return this.client.request('GET', `/api/v1/users/me/organizations/${listQuery(page)}`, undefined, {
+        return this.client.send('GET', `/api/v1/users/me/organizations/${listQuery(page)}`, undefined, {
             'X-Rekey-User-Token': accessToken,
         });
     }
     /** Fetch one organization the caller belongs to. */
     get(accessToken, organizationId) {
-        return this.client.request('GET', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}`, undefined, { 'X-Rekey-User-Token': accessToken });
+        return this.client.send('GET', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}`, undefined, { 'X-Rekey-User-Token': accessToken });
     }
     /** Update org name / metadata. OWNER + ADMIN only. */
     update(accessToken, organizationId, input) {
-        return this.client.request('PATCH', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}`, input, { 'X-Rekey-User-Token': accessToken });
+        return this.client.send('PATCH', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}`, input, { 'X-Rekey-User-Token': accessToken });
     }
-    /** List members of an organization the caller belongs to. Paginated
-     *  (default 50, max 100); pass `page.offset` to page beyond the first window. */
+    /**
+     * List members of an organization the caller belongs to.
+     *
+     * Paginated (default 50, max 100). `page.total` is the org's member count,
+     * so you do not need a second call to render "3 of 40".
+     */
     listMembers(accessToken, organizationId, page) {
-        return this.client.request('GET', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}/members${listQuery(page)}`, undefined, { 'X-Rekey-User-Token': accessToken });
+        return this.client.send('GET', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}/members${listQuery(page)}`, undefined, { 'X-Rekey-User-Token': accessToken });
     }
     /**
      * Invite a user. Returns the raw token ONCE — surface via your own
      * email/share channel. OWNER + ADMIN only.
      */
     invite(accessToken, organizationId, input) {
-        return this.client.request('POST', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}/invitations`, input, { 'X-Rekey-User-Token': accessToken });
+        return this.client.send('POST', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}/invitations`, input, { 'X-Rekey-User-Token': accessToken });
     }
     /** Revoke a pending invitation. OWNER + ADMIN only. Idempotent. */
     revokeInvitation(accessToken, organizationId, invitationId) {
-        return this.client.request('POST', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}/invitations/${encodeURIComponent(invitationId)}/revoke`, undefined, { 'X-Rekey-User-Token': accessToken });
+        return this.client.send('POST', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}/invitations/${encodeURIComponent(invitationId)}/revoke`, undefined, { 'X-Rekey-User-Token': accessToken });
     }
     /**
      * Change a member's role. OWNER manages anyone; ADMIN manages MEMBER
      * only. Last-OWNER guard refuses demoting the only OWNER.
      */
     setMemberRole(accessToken, organizationId, targetEndUserId, input) {
-        return this.client.request('PATCH', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}/members/${encodeURIComponent(targetEndUserId)}`, input, { 'X-Rekey-User-Token': accessToken });
+        return this.client.send('PATCH', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}/members/${encodeURIComponent(targetEndUserId)}`, input, { 'X-Rekey-User-Token': accessToken });
     }
     /**
      * Remove a member (or self). Refuses removing the last OWNER.
@@ -691,7 +883,7 @@ class OrganizationsClient {
      * rather than assuming it is always `true`.
      */
     removeMember(accessToken, organizationId, targetEndUserId) {
-        return this.client.request('DELETE', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}/members/${encodeURIComponent(targetEndUserId)}`, undefined, { 'X-Rekey-User-Token': accessToken });
+        return this.client.send('DELETE', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}/members/${encodeURIComponent(targetEndUserId)}`, undefined, { 'X-Rekey-User-Token': accessToken });
     }
     /**
      * Self-leave. An OWNER cannot leave (payment + benefits are tied to the
@@ -699,14 +891,14 @@ class OrganizationsClient {
      * first, or demote yourself to ADMIN if there is another OWNER.
      */
     leave(accessToken, organizationId) {
-        return this.client.request('POST', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}/leave`, undefined, { 'X-Rekey-User-Token': accessToken });
+        return this.client.send('POST', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}/leave`, undefined, { 'X-Rekey-User-Token': accessToken });
     }
     /**
      * Accept an organization invitation by raw token. Refuses cross-
      * Application invitations. Idempotent if the caller is already a member.
      */
     acceptInvitation(accessToken, input) {
-        return this.client.request('POST', '/api/v1/auth/organizations/accept-invitation', input, { 'X-Rekey-User-Token': accessToken });
+        return this.client.send('POST', '/api/v1/auth/organizations/accept-invitation', input, { 'X-Rekey-User-Token': accessToken });
     }
     /**
      * Make `organizationId` the active org for this session (member-only).
@@ -717,14 +909,14 @@ class OrganizationsClient {
      * you switch again, clear it, or leave the org.
      */
     switch(accessToken, organizationId) {
-        return this.client.request('POST', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}/switch`, undefined, { 'X-Rekey-User-Token': accessToken });
+        return this.client.send('POST', `/api/v1/users/me/organizations/${encodeURIComponent(organizationId)}/switch`, undefined, { 'X-Rekey-User-Token': accessToken });
     }
     /**
      * Clear the active org — switch the session back to the personal pool.
      * Returns a fresh token pair (no active org); **store both**.
      */
     clearActive(accessToken) {
-        return this.client.request('POST', '/api/v1/users/me/organizations/clear-active-organization', undefined, { 'X-Rekey-User-Token': accessToken });
+        return this.client.send('POST', '/api/v1/users/me/organizations/clear-active-organization', undefined, { 'X-Rekey-User-Token': accessToken });
     }
 }
 class LicensesClient {
@@ -753,7 +945,7 @@ class LicensesClient {
      * ```
      */
     verify(input) {
-        return this.client.request('POST', '/api/v1/licenses/verify', input);
+        return this.client.send('POST', '/api/v1/licenses/verify', input);
     }
 }
 class UsageClient {
@@ -767,7 +959,7 @@ class UsageClient {
      * server time; pass an ISO string when ingesting historical events.
      */
     record(input) {
-        return this.client.request('POST', '/api/v1/usage/record', input);
+        return this.client.send('POST', '/api/v1/usage/record', input);
     }
     /**
      * Sum recorded quantity for a meter, optionally bounded by a time window
@@ -785,7 +977,7 @@ class UsageClient {
             params.set('endUserId', input.endUserId);
         if (input.organizationId)
             params.set('organizationId', input.organizationId);
-        return this.client.request('GET', `/api/v1/usage/aggregate?${params.toString()}`);
+        return this.client.send('GET', `/api/v1/usage/aggregate?${params.toString()}`);
     }
 }
 function creditSubjectQuery(subject) {
@@ -811,7 +1003,7 @@ class CreditsClient {
     }
     /** Current spendable balance for a subject (end-user or org); 0 if none. */
     getBalance(subject) {
-        return this.client.request('GET', `/api/v1/credits/balance?${creditSubjectQuery(subject)}`);
+        return this.client.send('GET', `/api/v1/credits/balance?${creditSubjectQuery(subject)}`);
     }
     /**
      * Deduct credits from a subject (end-user or org pool). Throws `RekeyError`
@@ -821,7 +1013,7 @@ class CreditsClient {
      * double-charges — a repeat returns the original result with `applied: false`.
      */
     consume(input) {
-        return this.client.request('POST', '/api/v1/credits/consume', input);
+        return this.client.send('POST', '/api/v1/credits/consume', input);
     }
     /**
      * Ledger entries for a subject, newest first. Pass `offset` to page back
@@ -834,7 +1026,7 @@ class CreditsClient {
             params.set('limit', String(limit));
         if (offset !== undefined)
             params.set('offset', String(offset));
-        return this.client.request('GET', `/api/v1/credits/ledger?${params.toString()}`);
+        return this.client.send('GET', `/api/v1/credits/ledger?${params.toString()}`);
     }
 }
 /**
@@ -949,7 +1141,14 @@ async function loadJwks(options, forceRefetch) {
     if (cached && !forceRefetch && Date.now() - cached.fetchedAt <= ttl)
         return cached.jwks;
     const fetchImpl = options.fetch ?? fetch;
-    const res = await fetchImpl(url);
+    const deadline = createDeadline(options.timeoutMs ?? DEFAULT_TIMEOUT_MS, undefined, options.signal);
+    let res;
+    try {
+        res = await fetchImpl(url, deadline.signal ? { signal: deadline.signal } : {});
+    }
+    catch (cause) {
+        throw transportError(cause, deadline, 'GET', url);
+    }
     if (!res.ok) {
         throw new RekeyError({
             code: 'JWKS_FETCH_FAILED',
@@ -958,7 +1157,20 @@ async function loadJwks(options, forceRefetch) {
             statusCode: res.status,
         });
     }
-    const jwks = (await res.json());
+    let jwks;
+    try {
+        jwks = (await res.json());
+    }
+    catch (cause) {
+        if (isAbortError(cause))
+            throw transportError(cause, deadline, 'GET', url);
+        throw new RekeyError({
+            code: 'JWKS_FETCH_FAILED',
+            message: `The JWKS endpoint at ${url} did not return JSON.`,
+            fix: 'Check the URL points at /.well-known/jwks.json, not an HTML error page.',
+            cause,
+        });
+    }
     if (!jwks || !Array.isArray(jwks.keys)) {
         throw new RekeyError({
             code: 'JWKS_FETCH_FAILED',
@@ -995,12 +1207,20 @@ async function loadJwks(options, forceRefetch) {
  * import { verifyAccessToken } from '@rekey.dev/node';
  *
  * const claims = await verifyAccessToken(req.headers['x-rekey-user-token'], {
+ *   applicationId: MY_APP_ID,
  *   jwksUrl: 'https://rekey.example.com/.well-known/jwks.json',
  * });
- * if (claims.applicationId !== MY_APP_ID) throw new Error('wrong app');
  * req.userId = claims.sub;
  * ```
  *
+ * `applicationId` is required and checked inside this function. The RS256
+ * keypair is deployment-wide and `eu_access` tokens carry no `iss`/`aud`, so
+ * without it a token minted for any other Application on the same deployment
+ * verifies here with a perfectly valid signature. This example used to show
+ * the comparison being done by the caller afterwards, which is precisely why
+ * it moved inside: the shortest correct path should not be the one nobody
+ * takes.
+ *
  * @throws {RekeyError} `TOKEN_ALG_NOT_RS256` — token is HS256 (app hasn't opted in) or another alg.
  * @throws {RekeyError} `TOKEN_KID_UNKNOWN` — `kid` not in the JWKS (forged, or key deleted).
  * @throws {RekeyError} `USER_TOKEN_EXPIRED` — `exp` passed; refresh the session.
@@ -1076,6 +1296,16 @@ export async function verifyAccessToken(token, options) {
     if (typeof payload.sub !== 'string' || typeof payload.applicationId !== 'string') {
         throw invalid('Token is missing the sub/applicationId claims.');
     }
+    // Bind the token to ONE Application. The signing key is deployment-wide and
+    // `eu_access` carries no `iss`/`aud`, so a token minted for a different
+    // Application on the same deployment is cryptographically valid here — on a
+    // multi-app self-host that means accepting someone else's end-user as your
+    // own. The API does compare this server-side; the SDK left it to the caller
+    // and documented it as a follow-up step, which made the shortest correct
+    // path the one nobody takes.
+    if (payload.applicationId !== options.applicationId) {
+        throw invalid('Token was issued for a different Application.');
+    }
     const nowSec = Math.floor((options.now ? options.now() : Date.now()) / 1000);
     if (typeof payload.exp !== 'number' || payload.exp <= nowSec) {
         throw new RekeyError({
@@ -1100,17 +1330,35 @@ class BillingClient {
      * `amount` is in the smallest currency unit (cents/paise/sen) — never
      * a float. Format on display: `${amount / 100} ${currency}`.
      */
-    getPlans() {
-        return this.client.request('GET', '/api/v1/billing/plans');
+    getPlans(page) {
+        return this.client.send('GET', `/api/v1/billing/plans${listQuery(page)}`);
     }
     /**
      * Fetch the current end-user's active subscription, or `null` if they
      * have none. Returns the most recent ACTIVE / PENDING / PAST_DUE row.
      *
      * Pass the user's access token (the SDK puts it in `X-Rekey-User-Token`).
+     *
+     * `opts.includeEnded` falls back to the most recent CANCELED/EXPIRED
+     * subscription **only when the answer would otherwise be null** — for a
+     * billing page that has to tell a former subscriber what they were on and
+     * when it ended, rather than showing them the same blank state as somebody
+     * who never subscribed. It can never replace a live subscription, so it is
+     * safe to add to an existing call; it is off by default all the same,
+     * because an entitlement check wants the strict question.
+     *
+     * `opts.organizationId` reads an organization's subscription instead of the
+     * user's own on an org-billed app. The caller must be a member.
      */
-    getSubscription(accessToken) {
-        return this.client.request('GET', '/api/v1/billing/subscription', undefined, {
+    getSubscription(accessToken, opts) {
+        const qs = new URLSearchParams();
+        if (opts?.organizationId)
+            qs.set('organizationId', opts.organizationId);
+        if (opts?.includeEnded)
+            qs.set('includeEnded', 'true');
+        const query = qs.toString();
+        const suffix = query ? `?${query}` : '';
+        return this.client.send('GET', `/api/v1/billing/subscription${suffix}`, undefined, {
             'X-Rekey-User-Token': accessToken,
         });
     }
@@ -1139,7 +1387,7 @@ class BillingClient {
      * ```
      */
     createCheckout(accessToken, input) {
-        return this.client.request('POST', '/api/v1/billing/checkout', input, {
+        return this.client.send('POST', '/api/v1/billing/checkout', input, {
             'X-Rekey-User-Token': accessToken,
         });
     }
@@ -1153,7 +1401,7 @@ class BillingClient {
      *   `COUPON_USER_LIMIT_REACHED`. Surface the message + fix to the user.
      */
     validateCoupon(accessToken, input) {
-        return this.client.request('POST', '/api/v1/billing/coupons/validate', input, {
+        return this.client.send('POST', '/api/v1/billing/coupons/validate', input, {
             'X-Rekey-User-Token': accessToken,
         });
     }
@@ -1171,7 +1419,7 @@ class BillingClient {
         const headers = {};
         if (country)
             headers['x-country'] = country.toUpperCase();
-        return this.client.request('GET', '/api/v1/billing/providers', undefined, headers);
+        return this.client.send('GET', '/api/v1/billing/providers', undefined, headers);
     }
     /**
      * Resolve the calling end-user's current entitlements — feature flags +
@@ -1190,7 +1438,7 @@ class BillingClient {
         const qs = opts?.organizationId
             ? `?organizationId=${encodeURIComponent(opts.organizationId)}`
             : '';
-        return this.client.request('GET', `/api/v1/billing/entitlements${qs}`, undefined, {
+        return this.client.send('GET', `/api/v1/billing/entitlements${qs}`, undefined, {
             'X-Rekey-User-Token': accessToken,
         });
     }
@@ -1219,7 +1467,7 @@ class BillingClient {
      * ```
      */
     cancelSubscription(accessToken, input) {
-        return this.client.request('POST', '/api/v1/billing/subscription/cancel', {
+        return this.client.send('POST', '/api/v1/billing/subscription/cancel', {
             // Omitted rather than sent as undefined so the API applies its own
             // default (at period end) instead of parsing a null-ish field.
             ...(input?.atPeriodEnd !== undefined && { atPeriodEnd: input.atPeriodEnd }),