@rekey.dev/node 2.1.0 → 2.2.0-rc.2

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 /**
- * @rekey.dev/node — server SDK for Rekey.
+ * @rekey.dev/node, server SDK for Rekey.
  *
  * One client instance per Application. Construct with the Application's
  * secret key (`rp_live_…` or `rp_test_…`) and the URL of your Rekey
- * deployment. Never ship the secret key to the browser — for browser code
+ * deployment. Never ship the secret key to the browser, for browser code
  * use `@rekey.dev/react` with the Application's public key instead.
  *
  * @example Smoke-test your credentials
@@ -19,15 +19,15 @@
  * console.log(`Connected to "${me.name}" (${me.slug})`);
  * ```
  */
-import type { ApplicationDto, AuthResultDto, ListPage, Paged, JwksDto, ChangePasswordRequest, CheckoutResultDto, ConsumeCreditsRequest, ConsumeCreditsResultDto, CreateCheckoutRequest, CreditBalanceDto, CreditLedgerEntryDto, EndUserDto, ForgotPasswordRequest, ForgotPasswordResultDto, LicenseVerifyResultDto, MfaVerifyRequest, OAuthAuthServerMetadata, OAuthIntrospectionResponse, OrganizationDto, OrganizationInvitationDto, OrganizationMemberDto, OrganizationWithRoleDto, OrganizationRoleDefDto, OrganizationRole, OrganizationBaseRole, PlanDto, ProvidersListDto, ResetPasswordRequest, SignInOutcomeDto, SignInRequest, SignUpRequest, SubscriptionDto, UsageAggregateDto, UsageRecordDto, ValidateCouponRequest, ValidateCouponResultDto } from '@rekey.dev/shared-types';
+import type { ApplicationDto, AuthResultDto, MeInclude, MeIncludedFor, ListPage, Paged, JwksDto, ChangePasswordRequest, CheckoutResultDto, ConsumeCreditsRequest, ConsumeCreditsResultDto, CreateCheckoutRequest, CreditBalanceDto, CreditLedgerEntryDto, CurrentUserDto, EndUserDto, EndUserLicenseDto, FeatureCheckDto, ForgotPasswordRequest, ForgotPasswordResultDto, LicenseVerifyResultDto, LicenseDeactivateRequest, LicenseDeactivateResultDto, DeviceDto, EndUserDeviceDto, TrialEligibilityDto, DeviceStatusType, MfaVerifyRequest, OAuthAuthServerMetadata, OAuthIntrospectionResponse, OrganizationDto, OrganizationInvitationDto, OrganizationMemberDto, OrganizationWithRoleDto, OrganizationRoleDefDto, OrganizationRole, OrganizationBaseRole, PublicPlanDto, ProvidersListDto, ResetPasswordRequest, SignInOutcomeDto, SignInRequest, DeviceBindingRequest, SignUpRequest, SubscriptionDto, UsageAggregateDto, UsageMeterCatalogueEntryDto, UsageRecordDto, UsageRemainingDto, KeyGrantCreditsRequest, SelfCreditLedgerEntryDto, ValidateCouponRequest, ValidateCouponResultDto } from '@rekey.dev/shared-types';
 import { RekeyError } from '@rekey.dev/shared-types/error';
-export type { ApplicationDto, EndUserDto, ApiKeyDto, AuthResultDto, MfaChallengeResultDto, MfaVerifyRequest, SignInOutcomeDto, SignInRequest, SignUpRequest, RefreshRequest, ForgotPasswordRequest, ForgotPasswordResultDto, ResetPasswordRequest, ChangePasswordRequest, PlanDto, SubscriptionDto, CreateCheckoutRequest, CheckoutResultDto, CouponDto, ProvidersListDto, BillingProviderInfoDto, ValidateCouponRequest, ValidateCouponResultDto, CouponDiscountTypeValue, PlanIntervalType, PlanKindType, LicenseKindType, CreditReasonType, CreditBalanceDto, CreditLedgerEntryDto, ConsumeCreditsRequest, ConsumeCreditsResultDto, OrganizationDto, OrganizationWithRoleDto, OrganizationRoleDefDto, OrganizationMemberDto, OrganizationInvitationDto, OrganizationRole, OrganizationBaseRole, LicenseDto, LicenseStatusType, LicenseVerifyResultDto, UsageRecordDto, UsageAggregateDto, SubscriptionStatusType, RekeyErrorShape, AuthConfig, BillingConfig, BillingProvider, TokenAlg, JwkRsaPublic, JwksDto, OAuthIntrospectionResponse, OAuthAuthServerMetadata, } from '@rekey.dev/shared-types';
+export type { ApplicationDto, EndUserDto, CurrentUserDto, EndUserLicenseDto, FeatureCheckDto, PublicPlanDto, PublicPlanCheckoutDto, MeInclude, MeIncluded, MeIncludedFor, MeIncludedFields, ResolvedEntitlementsDto, ApiKeyDto, AuthResultDto, MfaChallengeResultDto, MfaVerifyRequest, SignInOutcomeDto, SignInRequest, DeviceBindingRequest, SignUpRequest, RefreshRequest, ForgotPasswordRequest, ForgotPasswordResultDto, ResetPasswordRequest, ChangePasswordRequest, PlanDto, SubscriptionDto, CreateCheckoutRequest, CheckoutResultDto, CouponDto, ProvidersListDto, BillingProviderInfoDto, ValidateCouponRequest, ValidateCouponResultDto, BillingProviderCapabilities, TrialEligibilityDto, TrialEligibilityItemDto, TrialPolicyType, CouponDiscountTypeValue, PlanIntervalType, PlanKindType, LicenseKindType, CreditReasonType, CreditBalanceDto, CreditLedgerEntryDto, ConsumeCreditsRequest, ConsumeCreditsResultDto, OrganizationDto, OrganizationWithRoleDto, OrganizationRoleDefDto, OrganizationMemberDto, OrganizationInvitationDto, OrganizationRole, OrganizationBaseRole, LicenseDto, LicenseStatusType, LicenseVerifyResultDto, LicenseActivationDto, LicenseDeactivateRequest, LicenseDeactivateResultDto, DeviceDto, EndUserDeviceDto, DeviceLimitDetails, DeviceStatusType, UsageRecordDto, UsageAggregateDto, UsageRemainingDto, UsageMeterRemainingDto, UsageMeterCatalogueEntryDto, KeyGrantCreditsRequest, SelfCreditLedgerEntryDto, CreditWebhookData, SubscriptionStatusType, RekeyErrorShape, AuthConfig, BillingConfig, BillingProvider, TokenAlg, JwkRsaPublic, JwksDto, OAuthIntrospectionResponse, OAuthAuthServerMetadata, } from '@rekey.dev/shared-types';
 /**
  * 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
+ * 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.
  */
@@ -36,13 +36,13 @@ export declare const DEFAULT_TIMEOUT_MS = 10000;
 export interface RekeyConfig {
     /** Base URL of the Rekey API. e.g. `https://rekey.example.com` */
     apiUrl: string;
-    /** Secret key for one Application — `rp_live_…` or `rp_test_…`. Never ship to the browser. */
+    /** Secret key for one Application, `rp_live_…` or `rp_test_…`. Never ship to the browser. */
     secretKey: string;
     /** Optional fetch override (test stubs, custom keep-alive agents, etc.). */
     fetch?: typeof fetch;
     /**
      * Deadline for every request this client makes, in milliseconds.
-     * Default {@link DEFAULT_TIMEOUT_MS} (10 000). Pass `0` to disable — only do
+     * Default {@link DEFAULT_TIMEOUT_MS} (10 000). Pass `0` to disable, only do
      * that if something upstream of you already bounds the call.
      *
      * On expiry the promise rejects with a `RekeyError` whose code is
@@ -50,7 +50,7 @@ export interface RekeyConfig {
      */
     timeoutMs?: number | undefined;
     /**
-     * Client-wide abort signal — aborting it cancels every in-flight request
+     * Client-wide abort signal, aborting it cancels every in-flight request
      * (server shutdown, request-scoped cancellation). Composed with, not
      * replaced by, any per-call `signal`.
      */
@@ -62,7 +62,7 @@ export interface RekeyConfig {
  * addable without a new overload.
  */
 export interface RekeyRequestOptions {
-    /** JSON request body. Omit for GET/DELETE — a present body sets `Content-Type`. */
+    /** JSON request body. Omit for GET/DELETE, a present body sets `Content-Type`. */
     body?: unknown;
     /** Extra headers, merged over the SDK's own (`Authorization`, `Content-Type`). */
     headers?: Record<string, string> | undefined;
@@ -80,7 +80,7 @@ export interface RekeyCallOptions {
 }
 export { RekeyError };
 /**
- * Outbound webhook event registry — the events Rekey can POST to your app
+ * Outbound webhook event registry, the events Rekey can POST to your app
  * (verify them with `verifyWebhookSignature` below). `WEBHOOK_EVENTS` carries
  * `{ name, description }` pairs for introspection/autocomplete;
  * `KNOWN_WEBHOOK_EVENTS` is just the names. Mirrors the API's registry exactly.
@@ -89,7 +89,7 @@ export { RekeyError };
  * ```ts
  * import { WEBHOOK_EVENTS, isKnownWebhookEvent, type WebhookEventEnvelope } from '@rekey.dev/node';
  *
- * for (const e of WEBHOOK_EVENTS) console.log(`${e.name} — ${e.description}`);
+ * for (const e of WEBHOOK_EVENTS) console.log(`${e.name}, ${e.description}`);
  *
  * const event = req.body as WebhookEventEnvelope; // after verifyWebhookSignature(...)
  * if (event.type === 'subscription.activated') unlockPlan(event.data);
@@ -102,7 +102,7 @@ export type { WebhookEventType, WebhookEventEnvelope } from '@rekey.dev/shared-t
  * 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
+ * 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.
@@ -131,23 +131,27 @@ export declare class Rekey {
     private readonly config;
     /** Operations on the calling Application itself. */
     readonly applications: ApplicationsClient;
-    /** Auth operations — sign-in, sign-up, sessions, passkeys, magic-link. */
+    /** Auth operations, sign-in, sign-up, sessions, passkeys, magic-link. */
     readonly auth: AuthClient;
-    /** Billing operations — plans, checkout, subscriptions, coupons. */
+    /** Billing operations, plans, checkout, subscriptions, coupons. */
     readonly billing: BillingClient;
-    /** End-user organizations — create, invite, members, role changes. */
+    /** End-user organizations, create, invite, members, role changes. */
     readonly organizations: OrganizationsClient;
     /** License key verification + activation. */
     readonly licenses: LicensesClient;
-    /** Usage metering — record events, aggregate windows. */
+    /** Devices, list and release the machines an end-user signs in from. */
+    readonly devices: DevicesClient;
+    /** End-users, lookup by id or email, bulk import. */
+    readonly users: UsersClient;
+    /** Usage metering, record events, aggregate windows. */
     readonly usage: UsageClient;
-    /** Prepaid credits — balance reads, idempotent drawdown, ledger. */
+    /** Prepaid credits, balance reads, idempotent drawdown, ledger. */
     readonly credits: CreditsClient;
-    /** MCP — validate Rekey-issued MCP tokens from your own MCP server. */
+    /** MCP, validate Rekey-issued MCP tokens from your own MCP server. */
     readonly mcp: McpClient;
     constructor(config: RekeyConfig);
     /**
-     * A clone of this client with different call options — the per-call knob for
+     * 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
@@ -167,7 +171,7 @@ export declare class Rekey {
      * });
      * ```
      *
-     * Cheap — it rebuilds the namespace objects, holds no connections, and
+     * Cheap, it rebuilds the namespace objects, holds no connections, and
      * shares the same `fetch`.
      */
     with(options: RekeyCallOptions): Rekey;
@@ -175,7 +179,7 @@ export declare class Rekey {
      * 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
+     * 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.
@@ -200,7 +204,7 @@ export declare class Rekey {
 }
 /**
  * MCP helpers for customers running their OWN MCP server behind Rekey auth.
- * The hosted MCP server (account tools) is consumed by MCP clients directly —
+ * The hosted MCP server (account tools) is consumed by MCP clients directly,
  * this client is for the "bring your own MCP server" path: validate incoming
  * Rekey-issued tokens, and read the OAuth metadata.
  */
@@ -230,7 +234,7 @@ declare class ApplicationsClient {
     constructor(client: Rekey);
     /**
      * Verify credentials and fetch the calling Application. Use this as your
-     * SDK smoke test — if it returns, your secret key is good and you're
+     * SDK smoke test, if it returns, your secret key is good and you're
      * pointed at the right Rekey deployment.
      *
      * @example
@@ -252,7 +256,7 @@ declare class AuthClient {
      * (e.g. `getCurrentUser(accessToken)`) and a `refreshToken` to renew it.
      *
      * Unless the Application turns `authConfig.sendVerificationEmailOnSignUp`
-     * off, Rekey also emails the verification link — best-effort, so it never
+     * off, Rekey also emails the verification link, best-effort, so it never
      * fails the sign-up, and `sendVerificationEmail` re-sends on demand.
      *
      * @example
@@ -261,7 +265,7 @@ declare class AuthClient {
      *   email: 'alice@example.com',
      *   password: 'correct-horse-battery-staple',
      * });
-     * // store both in your session — the access token expires in 15 minutes
+     * // store both in your session, the access token expires in 15 minutes
      * ```
      *
      * @throws {RekeyError} `EMAIL_ALREADY_EXISTS` (409) if the email is taken in this Application.
@@ -278,14 +282,14 @@ declare class AuthClient {
      *     Prompt the user for their TOTP / backup code and call
      *     `mfaVerify({ mfaChallengeToken, code })` to receive a real session.
      *
-     * **Branch on `result.mfaRequired` before reading `accessToken`** — the
+     * **Branch on `result.mfaRequired` before reading `accessToken`**, the
      * MFA-required branch has no session tokens.
      *
-     * @throws {RekeyError} `INVALID_CREDENTIALS` (401) — single code on purpose.
+     * @throws {RekeyError} `INVALID_CREDENTIALS` (401), single code on purpose.
      *   Don't try to distinguish wrong-email from wrong-password from the SDK side either.
      * @throws {RekeyError} `EMAIL_NOT_VERIFIED` (403) when the Application sets
      *   `authConfig.requireEmailVerification` and the user hasn't confirmed their
-     *   address. The password was correct — prompt for the emailed link (or call
+     *   address. The password was correct, prompt for the emailed link (or call
      *   `sendVerificationEmail`), not for the password again.
      */
     signIn(input: SignInRequest): Promise<SignInOutcomeDto>;
@@ -316,18 +320,23 @@ declare class AuthClient {
         magicLinkToken: string | null;
     }>;
     /**
-     * Consume a magic-link token. Returns `SignInOutcome` — branch on
+     * Consume a magic-link token. Returns `SignInOutcome`, branch on
      * `mfaRequired` before reading `accessToken`. For MFA-enrolled users
      * the response carries `mfaChallengeToken` and you must complete via
      * `mfaVerify(...)`.
      */
     verifyMagicLink(input: {
         token: string;
+        /** Bind the session to a device, see docs/devices.md. */
+        device?: {
+            fingerprint: string;
+            label?: string;
+        };
     }): Promise<SignInOutcomeDto>;
     /**
      * Begin a passkey authentication ceremony. Returns the WebAuthn options
      * to forward to the browser (`navigator.credentials.get(...)`) along
-     * with `expectedChallenge` — bind the challenge to your session and
+     * with `expectedChallenge`, bind the challenge to your session and
      * pass both back via `verifyPasskeyAuthentication(...)`.
      */
     startPasskeyAuthentication(input?: {
@@ -338,12 +347,17 @@ declare class AuthClient {
     }>;
     /**
      * Complete a passkey authentication. Returns the same `SignInOutcome`
-     * shape as `signIn` — but passkeys are themselves a strong factor, so
+     * shape as `signIn`, but passkeys are themselves a strong factor, so
      * `mfaRequired` will always be `false` in practice.
      */
     verifyPasskeyAuthentication(input: {
         response: unknown;
         expectedChallenge: string;
+        /** Bind the session to a device, see docs/devices.md. */
+        device?: {
+            fingerprint: string;
+            label?: string;
+        };
     }): Promise<SignInOutcomeDto>;
     /**
      * Begin a passkey registration ceremony for an authenticated user.
@@ -366,7 +380,7 @@ declare class AuthClient {
     /**
      * List the user's registered passkeys, newest first.
      *
-     * Returns `{items, page}` — `page.total` is the number of passkeys the user
+     * Returns `{items, page}`, `page.total` is the number of passkeys the user
      * has, independent of the window served.
      */
     listPasskeys(accessToken: string, page?: ListPage): Promise<Paged<{
@@ -383,15 +397,37 @@ declare class AuthClient {
     /**
      * Resolve the end-user behind a presented access token.
      *
-     * @throws {RekeyError} `USER_TOKEN_INVALID` (401) if expired/forged/wrong-secret.
+     * Pass `include` to get more of what a backend needs to authorise the
+     * request in the same round trip: `entitlements` (as `billing.getEntitlements`
+     * returns them), `device` (the device the session is bound to, or null),
+     * `subscription` (as `billing.getSubscription` returns it), `organization`
+     * (the active organization with the caller's role) and `licenses` (as
+     * `{ items, truncated }`, the first 100 of `licenses.listMine`). With a literal list
+     * (inline or `as const`) the return type gains exactly those properties;
+     * with a list typed `MeInclude[]` they are optional, since the compiler
+     * cannot know which it holds.
+     *
+     * @example
+     * ```ts
+     * const me = await rekey.auth.getCurrentUser(accessToken, { include: ['entitlements', 'device'] });
+     * if (!me.entitlements.features.reports) throw new Forbidden();
+     * me.device?.status; // 'ACTIVE' when bound; a released or blocked device is a 401 instead
+     * ```
+     *
+     * @throws {RekeyError} `USER_TOKEN_INVALID` (401) if expired/forged/wrong-secret, or
+     *   if the session's device was released or blocked.
      * @throws {RekeyError} `USER_TOKEN_WRONG_APPLICATION` (401) if the token was issued
      *   by a different Application than the calling secret key represents.
+     * @throws {RekeyError} `VALIDATION_ERROR` (400) for an unknown `include` value.
+     * @throws {RekeyError} `BILLING_DISABLED` (403) or `API_KEY_SCOPE_INSUFFICIENT` (403)
+     *   when `entitlements`, `subscription` or `licenses` is asked for and billing is off,
+     *   or the key lacks `billing:read`.
      */
-    getCurrentUser(accessToken: string): Promise<EndUserDto & {
-        activeOrganizationId: string | null;
-    }>;
+    getCurrentUser<const L extends readonly MeInclude[] = []>(accessToken: string, options?: {
+        include?: L;
+    }): Promise<CurrentUserDto & MeIncludedFor<L>>;
     /**
-     * Update the end-user behind a presented access token — their OWN record,
+     * Update the end-user behind a presented access token, their OWN record,
      * and only ever their own: the token identifies the subject, so there is no
      * user id to pass and no way to aim this at anyone else.
      *
@@ -419,21 +455,21 @@ declare class AuthClient {
      */
     updateCurrentUser(accessToken: string, input: {
         metadata?: Record<string, unknown> | null;
-    }): Promise<EndUserDto & {
-        activeOrganizationId: string | null;
-    }>;
+    }): Promise<CurrentUserDto>;
     /**
      * Exchange a refresh token for a fresh {access, refresh} pair. The presented
-     * refresh is revoked atomically — call this **once** and store the new
+     * refresh is revoked atomically, call this **once** and store the new
      * `refreshToken` from the response immediately.
      *
      * @throws {RekeyError} `REFRESH_TOKEN_REUSED` (401) if you replay an already-used token.
      *   This is a strong signal the original was leaked; treat as compromise.
      * @throws {RekeyError} `REFRESH_TOKEN_EXPIRED` (401) after the 30-day refresh window.
      */
-    refresh(refreshToken: string): Promise<AuthResultDto>;
+    refresh(refreshToken: string, options?: {
+        device?: DeviceBindingRequest;
+    }): Promise<AuthResultDto>;
     /**
-     * Revoke a refresh token. Idempotent — no-op for unknown tokens. The
+     * Revoke a refresh token. Idempotent, no-op for unknown tokens. The
      * access token paired with this refresh remains valid until its short
      * (15 min) expiry; for true "log out everywhere" semantics, also clear
      * the access token from your client.
@@ -442,14 +478,14 @@ declare class AuthClient {
         signedOut: true;
     }>;
     /**
-     * Request a password reset for an email. Always succeeds — never tells you
+     * Request a password reset for an email. Always succeeds, never tells you
      * whether the email exists.
      *
      * **Branch on the result.** When the Application has an email transport
      * (BYO Resend/SMTP, or a deployment-wide `RESEND_DEFAULT_API_KEY`) Rekey sends
      * the mail itself and `resetToken` is null. With no transport it falls back to
-     * the original contract and hands the raw token to you — a secret-key caller
-     * only — so you can deliver it with your own provider.
+     * the original contract and hands the raw token to you, a secret-key caller
+     * only, so you can deliver it with your own provider.
      *
      * @example
      * ```ts
@@ -473,7 +509,7 @@ declare class AuthClient {
     }>;
     /**
      * Authenticated password change. Pass the user's *current* access token.
-     * On success, every refresh token for the user is revoked — other devices
+     * On success, every refresh token for the user is revoked, other devices
      * are signed out.
      */
     changePassword(accessToken: string, input: ChangePasswordRequest): Promise<{
@@ -481,8 +517,8 @@ declare class AuthClient {
     }>;
     /**
      * Revoke every refresh token for the calling user. "Sign out of all
-     * devices." The caller's access token remains valid until 15-min expiry
-     * — clear it client-side for full logout.
+     * devices." The caller's access token remains valid until 15-min expiry,
+     * clear it client-side for full logout.
      */
     signOutEverywhere(accessToken: string): Promise<{
         revokedCount: number;
@@ -503,7 +539,7 @@ declare class AuthClient {
         verificationToken: string | null;
     }>;
     /**
-     * Re-send a verification link to an address, with **no session** — the
+     * Re-send a verification link to an address, with **no session**, the
      * sessionless sibling of `sendVerificationEmail`.
      *
      * This is the route for a user locked out by
@@ -511,17 +547,17 @@ declare class AuthClient {
      * session `sendVerificationEmail` needs, so a user whose first mail never
      * arrived cannot ask for another. Takes the address instead of a token.
      *
-     * **Branch on the result**, exactly as with `requestPasswordReset` — the
+     * **Branch on the result**, exactly as with `requestPasswordReset`, the
      * contract is the same one. It never throws for an unknown address and never
      * discloses whether the address exists, is already verified, or was mailed:
      * a publishable-key caller gets one constant body whatever happened. A
-     * secret-key caller — this SDK — gets the real outcome, and the raw
+     * secret-key caller, this SDK, gets the real outcome, and the raw
      * `verificationToken` when the Application has no email transport configured,
      * so you can deliver it with your own provider.
      *
      * Pass `verifyUrl` containing `{token}` to template the link target. Unlike
      * `sendVerificationEmail`, nothing is sent and no token is minted when no
-     * link can be built at all — pass `verifyUrl`, or set the Application URL
+     * link can be built at all, pass `verifyUrl`, or set the Application URL
      * (Panel → Application → Auth). Mailing a locked-out user a verification
      * message with no button in it helps nobody.
      *
@@ -565,7 +601,7 @@ declare class AuthClient {
         userAgent: string | null;
         ip: string | null;
     }>>;
-    /** Revoke one session by id. Idempotent — `{ revoked: false }` if it isn't this user's. */
+    /** Revoke one session by id. Idempotent, `{ revoked: false }` if it isn't this user's. */
     revokeSession(accessToken: string, sessionId: string): Promise<{
         revoked: boolean;
     }>;
@@ -578,7 +614,7 @@ declare class AuthClient {
     /**
      * Begin TOTP enrollment: mints a secret (as an `otpauthUrl` for the QR) and
      * 10 single-show backup codes. **Not enrolled until `confirmMfaSetup(...)`.**
-     * Only SHA-256 hashes of the backup codes are stored — show them once.
+     * Only SHA-256 hashes of the backup codes are stored, show them once.
      */
     mfaSetup(accessToken: string): Promise<{
         otpauthUrl: string;
@@ -591,7 +627,7 @@ declare class AuthClient {
     }>;
     /**
      * Verify a TOTP or backup code as a step-up check (does NOT issue a session).
-     * Backup codes are single-use — consumed on success. Returns `{ ok }`.
+     * Backup codes are single-use, consumed on success. Returns `{ ok }`.
      */
     mfaChallenge(accessToken: string, code: string): Promise<{
         ok: boolean;
@@ -609,10 +645,16 @@ declare class AuthClient {
     }>;
     /**
      * Exchange the provider `code` for a Rekey session. Returns a
-     * `SignInOutcome` — branch on `mfaRequired` before reading `accessToken`.
+     * `SignInOutcome`, branch on `mfaRequired` before reading `accessToken`.
      * Verify the `state` CSRF value yourself before calling.
      */
-    completeOAuth(provider: string, code: string): Promise<SignInOutcomeDto>;
+    completeOAuth(provider: string, code: string, options?: {
+        /** Bind the session to a device, see docs/devices.md. */
+        device?: {
+            fingerprint: string;
+            label?: string;
+        };
+    }): Promise<SignInOutcomeDto>;
     /** List the OAuth providers linked to the current user. */
     listOAuthIdentities(accessToken: string): Promise<Array<{
         provider: string;
@@ -625,7 +667,7 @@ declare class AuthClient {
         authorizationUrl: string;
     }>;
     /**
-     * Complete an OAuth link — attaches the provider identity to the current
+     * Complete an OAuth link, attaches the provider identity to the current
      * user. Refuses on unverified provider emails (account-takeover guard) or
      * when the provider account already belongs to a different user.
      */
@@ -648,7 +690,7 @@ declare class AuthClient {
  *
  * Re-exported from `@rekey.dev/shared-types` so the SDK, the API and the panel
  * all name one shape. Every list method returns {@link Paged}, whose `page`
- * tells you whether there is another window — you no longer have to infer it
+ * tells you whether there is another window, you no longer have to infer it
  * by asking for one row more than you need.
  */
 export type { ListPage, PageMeta, Paged } from '@rekey.dev/shared-types';
@@ -706,7 +748,7 @@ declare class OrganizationsClient {
      */
     listMembers(accessToken: string, organizationId: string, page?: ListPage): Promise<Paged<OrganizationMemberDto>>;
     /**
-     * Invite a user. Returns the raw token ONCE — surface via your own
+     * Invite a user. Returns the raw token ONCE, surface via your own
      * email/share channel. OWNER + ADMIN only.
      */
     invite(accessToken: string, organizationId: string, 
@@ -745,7 +787,7 @@ declare class OrganizationsClient {
      * Remove a member (or self). Refuses removing the last OWNER.
      *
      * Idempotent: `removed` is `false` when the target was not a member (e.g.
-     * already removed) — a no-op removal is not an error. Branch on `removed`
+     * already removed), a no-op removal is not an error. Branch on `removed`
      * rather than assuming it is always `true`.
      */
     removeMember(accessToken: string, organizationId: string, targetEndUserId: string): Promise<{
@@ -753,7 +795,7 @@ declare class OrganizationsClient {
     }>;
     /**
      * Self-leave. An OWNER cannot leave (payment + benefits are tied to the
-     * owner — `ORGANIZATION_OWNER_CANNOT_LEAVE`); transfer ownership via support
+     * owner, `ORGANIZATION_OWNER_CANNOT_LEAVE`); transfer ownership via support
      * first, or demote yourself to ADMIN if there is another OWNER.
      */
     leave(accessToken: string, organizationId: string): Promise<{
@@ -774,7 +816,7 @@ declare class OrganizationsClient {
     }>;
     /**
      * Make `organizationId` the active org for this session (member-only).
-     * Returns a fresh {accessToken, refreshToken} pair carrying the active org —
+     * Returns a fresh {accessToken, refreshToken} pair carrying the active org,
      * **store both**. Subsequent entitlement reads (`billing.getEntitlements`)
      * then default to this org's view + shared pool without passing
      * `organizationId` explicitly. The active org survives token refresh until
@@ -782,7 +824,7 @@ declare class OrganizationsClient {
      */
     switch(accessToken: string, organizationId: string): Promise<AuthResultDto>;
     /**
-     * Clear the active org — switch the session back to the personal pool.
+     * Clear the active org, switch the session back to the personal pool.
      * Returns a fresh token pair (no active org); **store both**.
      */
     clearActive(accessToken: string): Promise<AuthResultDto>;
@@ -793,7 +835,7 @@ declare class LicensesClient {
     /**
      * Verify a license key + record an activation for this machine. Call
      * once at app startup; you'll get a deterministic body (`ok=false` for
-     * invalid licenses — never an HTTP error — so your software can loop
+     * invalid licenses, never an HTTP error, so your software can loop
      * on the result without try/catch noise).
      *
      * `machineFingerprint` should be a stable identifier you derive client-
@@ -815,6 +857,173 @@ declare class LicensesClient {
         machineFingerprint: string;
         label?: string;
     }): Promise<LicenseVerifyResultDto>;
+    /**
+     * Give back the seat this machine holds; call it before a re-image or on
+     * uninstall so the next machine can verify. Same deterministic body as
+     * `verify`; `released: false` means the machine held no seat.
+     *
+     * @example
+     * ```ts
+     * await rekey.licenses.deactivate({ key, machineFingerprint });
+     * ```
+     */
+    deactivate(input: LicenseDeactivateRequest): Promise<LicenseDeactivateResultDto>;
+    /**
+     * The signed-in end-user's own licences, newest first:
+     * `GET /api/v1/users/me/licenses`, authorized by their access token. In an
+     * org-billed Application whose session acts for an organization, that
+     * organization's pooled licences are included too.
+     *
+     * No raw keys: only a hash is stored, so each row carries its display
+     * `keyPrefix`. Needs `billing:read` on a secret key.
+     *
+     * @example
+     * ```ts
+     * const { items } = await rekey.licenses.listMine(accessToken);
+     * const active = items.filter((l) => l.status === 'ACTIVE');
+     * ```
+     */
+    listMine(accessToken: string, page?: ListPage): Promise<Paged<EndUserLicenseDto>>;
+}
+/**
+ * End-users' devices (docs/devices.md), both surfaces.
+ *
+ * `list` / `release` are the SERVER surface: secret key only, addressed by
+ * end-user id, because they read and mutate OTHER users' devices.
+ *
+ * `listMine` / `releaseMine` are the END-USER surface, the one
+ * `DEVICE_LIMIT_REACHED` tells you to offer. They take that user's own access
+ * token and act only on their own devices, so they are what a "your signed-in
+ * machines" screen calls, and what lets a user release a machine themselves
+ * instead of contacting support.
+ */
+declare class DevicesClient {
+    private readonly client;
+    constructor(client: Rekey);
+    /** An end-user's devices, newest activity first. Optional `status` filter. */
+    list(endUserId: string, options?: {
+        status?: DeviceStatusType;
+        limit?: number;
+        offset?: number;
+    }): Promise<Paged<DeviceDto>>;
+    /** Release a device: gives its slot back and revokes every session on it. */
+    release(deviceId: string, endUserId: string): Promise<{
+        device: DeviceDto;
+        sessionsRevoked: number;
+    }>;
+    /**
+     * The calling end-user's OWN devices, newest activity first.
+     *
+     * `GET /api/v1/users/me/devices`, authorized by the user's access token
+     * rather than by an end-user id. Operator notes (`blockedReason`) and IPs are
+     * not on this surface, which is why it resolves to `EndUserDeviceDto`.
+     *
+     * The device the current session is bound to is the one whose `id` matches
+     * the access token's `dev` claim (see {@link VerifiedAccessTokenClaims}), so
+     * a "your devices" screen can mark "this device" without a second call.
+     *
+     * @example
+     * ```ts
+     * const { items } = await rekey.devices.listMine(accessToken, { status: 'ACTIVE' });
+     * ```
+     */
+    listMine(accessToken: string, options?: {
+        status?: DeviceStatusType;
+        limit?: number;
+        offset?: number;
+    }): Promise<Paged<EndUserDeviceDto>>;
+    /**
+     * Release one of the calling end-user's own devices.
+     *
+     * This is the flow `DEVICE_LIMIT_REACHED` names: that refusal carries
+     * `details.limit` and `details.devices` (typed as `DeviceLimitDetails`), so
+     * you can show the user their machines and release one here rather than
+     * leaving them at a dead end.
+     *
+     * Gives the slot back and revokes every session minted on that device,
+     * INCLUDING the current one when it is the same device, so treat a release of
+     * `claims.dev` as a sign-out. Idempotent for an already-released device; a
+     * BLOCKED device refuses with `DEVICE_BLOCKED` (only an operator can unblock).
+     *
+     * @example
+     * ```ts
+     * try {
+     *   await rekey.auth.signIn({ email, password, device: { fingerprint } });
+     * } catch (e) {
+     *   if (e instanceof RekeyError && e.code === 'DEVICE_LIMIT_REACHED') {
+     *     const { devices } = e.details as DeviceLimitDetails;
+     *     // …let the user pick one, then, with a token from a session that has one:
+     *     await rekey.devices.releaseMine(accessToken, devices[0]!.id);
+     *   }
+     * }
+     * ```
+     */
+    releaseMine(accessToken: string, deviceId: string): Promise<{
+        device: EndUserDeviceDto;
+        sessionsRevoked: number;
+    }>;
+}
+/**
+ * Server-side end-user lookup (secret key only). `/users/me` answers "who is
+ * this token"; these answer "who is this id / email" for a backend that holds
+ * no token.
+ */
+declare class UsersClient {
+    private readonly client;
+    constructor(client: Rekey);
+    /** Exact, case-insensitive email match in the calling Application. Throws END_USER_NOT_FOUND. */
+    getByEmail(email: string): Promise<EndUserDto>;
+    /** By id, scoped to the calling Application. Throws END_USER_NOT_FOUND. */
+    get(endUserId: string): Promise<EndUserDto>;
+    /**
+     * Import up to 500 users from another auth system in one call. Password
+     * hashes (argon2id or bcrypt) are stored as given and verified as-is at
+     * sign-in; bcrypt is upgraded to argon2id on first success. Existing
+     * addresses are skipped, never updated.
+     *
+     * @example
+     * ```ts
+     * const { created, skipped } = await rekey.users.import([
+     *   { email: 'a@example.com', passwordHash: '$2b$10$…', emailVerified: true },
+     *   { email: 'b@example.com', oauthIdentities: [{ provider: 'google', providerAccountId: '1234' }] },
+     * ]);
+     * ```
+     */
+    import(users: ImportUserInput[]): Promise<ImportUsersResult>;
+}
+export interface ImportUserInput {
+    email: string;
+    /** `$argon2id$…` or `$2a$`/`$2b$`/`$2y$…`. Omit for OAuth-only users. */
+    passwordHash?: string;
+    emailVerified?: boolean;
+    role?: string;
+    metadata?: Record<string, unknown>;
+    oauthIdentities?: Array<{
+        provider: string;
+        providerAccountId: string;
+        email?: string;
+    }>;
+}
+export interface ImportUsersResult {
+    created: Array<{
+        id: string;
+        email: string;
+    }>;
+    skipped: Array<{
+        email: string;
+        reason: string;
+    }>;
+    /**
+     * OAuth identities that were NOT linked because the provider account is
+     * already attached to another end-user in this Application. The user was
+     * still created; their sign-in through that provider lands on the OTHER
+     * account until one of the two is fixed.
+     */
+    unlinked: Array<{
+        email: string;
+        provider: string;
+        providerAccountId: string;
+    }>;
 }
 declare class UsageClient {
     private readonly client;
@@ -846,9 +1055,50 @@ declare class UsageClient {
         endUserId?: string;
         organizationId?: string;
     }): Promise<UsageAggregateDto>;
+    /**
+     * The signed-in end-user's included quota, usage and remaining units this
+     * period, per meter (or one meter with `{ meter }`). Computed by the code
+     * `record` enforces with: a record of more than `remaining` is the one that
+     * is refused (402 `USAGE_QUOTA_EXCEEDED`) or, on a priced meter, charged.
+     *
+     * Reads the personal quota, or the active organization's in an Application
+     * that bills organizations; `{ organizationId }` (member-only) picks one.
+     *
+     * @example
+     * ```ts
+     * const { meters } = await rekey.usage.getRemaining(accessToken, { meter: 'api_calls' });
+     * if (meters[0].remaining === 0) showUpgradePrompt();
+     * ```
+     */
+    getRemaining(accessToken: string, opts?: {
+        meter?: string;
+        organizationId?: string;
+    }): Promise<UsageRemainingDto>;
+    /**
+     * The same answer as `getRemaining`, for a subject you name instead of one
+     * whose token you hold: `{ endUserId }`, `{ organizationId }`, or both to
+     * read the organization as that member. Secret key only.
+     */
+    getRemainingFor(subject: {
+        endUserId: string;
+        organizationId?: string;
+    } | {
+        organizationId: string;
+        endUserId?: string;
+    }, opts?: {
+        meter?: string;
+    }): Promise<UsageRemainingDto>;
+    /**
+     * The Application's usage meters: the slugs `record` takes, their units,
+     * whether each accepts records, and its fallback credit price. Secret key.
+     */
+    listMeters(opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Paged<UsageMeterCatalogueEntryDto>>;
 }
 /**
- * A credit subject — pass `endUserId` for a personal balance, or
+ * A credit subject, pass `endUserId` for a personal balance, or
  * `organizationId` for a shared org pool (owner+beneficiary billing).
  */
 export type CreditSubject = {
@@ -857,11 +1107,11 @@ export type CreditSubject = {
     organizationId: string;
 };
 /**
- * Prepaid credits — the "lead pack" / pay-as-you-go drawdown model. The
+ * Prepaid credits, the "lead pack" / pay-as-you-go drawdown model. The
  * customer's backend grants credits (by selling a CREDIT-kind plan, which
  * grants automatically on payment) and draws them down per unit consumed.
  *
- * All calls are server-to-server (secret key) and scoped to a `CreditSubject` —
+ * All calls are server-to-server (secret key) and scoped to a `CreditSubject`,
  * an end-user's personal balance, or an organization's shared pool.
  */
 declare class CreditsClient {
@@ -874,7 +1124,7 @@ declare class CreditsClient {
      * `code: "CREDITS_INSUFFICIENT"` (HTTP 402) when the balance is too low.
      *
      * Pass `idempotencyKey` (e.g. the lead id) so a retried call never
-     * double-charges — a repeat returns the original result with `applied: false`.
+     * double-charges, a repeat returns the original result with `applied: false`.
      */
     consume(input: ConsumeCreditsRequest & CreditSubject): Promise<ConsumeCreditsResultDto>;
     /**
@@ -883,8 +1133,33 @@ declare class CreditsClient {
      * subject); `limit` is capped at 200 server-side.
      */
     listLedger(subject: CreditSubject, limit?: number, offset?: number): Promise<Paged<CreditLedgerEntryDto>>;
+    /**
+     * Grant credits to an end-user or organization pool with the Application
+     * key. Needs a key minted with the elevated `credits:grant` scope named:
+     * `*` does not include it, so a default key gets 403
+     * `API_KEY_SCOPE_INSUFFICIENT`.
+     *
+     * `idempotencyKey` is required; a repeat returns the original entry with
+     * `applied: false` and grants nothing. `amount` is 1 to 1,000,000 per call.
+     *
+     * @example
+     * ```ts
+     * await rekey.credits.grant({ endUserId, amount: 500, idempotencyKey: `referral:${referralId}` });
+     * ```
+     */
+    grant(input: KeyGrantCreditsRequest): Promise<ConsumeCreditsResultDto>;
+    /**
+     * The signed-in end-user's own credit ledger, newest first (the active
+     * organization's pool in an Application that bills organizations, or the one
+     * `{ organizationId }` names, member-only). Entries carry no `metadata`.
+     */
+    listMyLedger(accessToken: string, opts?: {
+        organizationId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<Paged<SelfCreditLedgerEntryDto>>;
 }
-/** What an end-user (or org) is entitled to right now — from active subs. */
+/** What an end-user (or org) is entitled to right now, from active subs. */
 export interface EntitlementsDto {
     /** Feature flags + numeric limits, keyed by code. Gate your app on these. */
     features: Record<string, boolean | number | string>;
@@ -907,7 +1182,7 @@ export interface EntitlementsDto {
  * default 300) AND (b) the signature matches a constant-time compare.
  *
  * Use against the `X-Rekey-Signature` header and the raw request body
- * BYTES (not the parsed JSON — any reserialization breaks the HMAC).
+ * BYTES (not the parsed JSON, any reserialization breaks the HMAC).
  *
  * @example
  * ```ts
@@ -933,16 +1208,37 @@ export declare function verifyWebhookSignature(args: {
 }): boolean;
 /** Verified claims of an RS256 end-user access token. */
 export interface VerifiedAccessTokenClaims {
-    /** Always `"eu_access"` — other token types are refused. */
+    /** Always `"eu_access"`, other token types are refused. */
     typ: 'eu_access';
     /** EndUser id. */
     sub: string;
-    /** Application the token is bound to — check it against YOUR application id. */
+    /** Application the token is bound to, check it against YOUR application id. */
     applicationId: string;
     /** Active organization id, when the session is acting as an org. */
     oid?: string;
     /** Operator id when this is an impersonation session (treat with care). */
     imp?: string;
+    /**
+     * Refresh-token family this access token belongs to, the `sid` claim.
+     *
+     * Optional because the API only mints it when the session flow supplies one
+     * (see `issueUserAccessToken`), so treat an absent `sid` as "this deployment
+     * or flow did not bind one", never as a session that ended.
+     *
+     * Offline verification cannot see a revocation, the whole point of not
+     * calling the API. Use this to correlate a token with your own record of the
+     * session, so you can drop one you already know is gone.
+     */
+    sid?: string;
+    /**
+     * Device this session is bound to, the `dev` claim. Present only when the
+     * sign-in bound a device.
+     *
+     * This is the id that matches a row from `devices.listMine()`, so a client
+     * can mark "this device" in its own device list, and the id to pass to
+     * `devices.releaseMine()` to sign the CURRENT machine out.
+     */
+    dev?: string;
     /** App `tokenGeneration` at mint time (the API checks this; offline can't). */
     gen?: number;
     iat: number;
@@ -953,7 +1249,7 @@ export interface VerifyAccessTokenOptions {
      * The Application this token must belong to. **Required.**
      *
      * This helper verifies RS256 tokens against the deployment's JWKS, and the
-     * RS256 keypair is deployment-wide — `SigningKey` has no `applicationId`
+     * RS256 keypair is deployment-wide, `SigningKey` has no `applicationId`
      * column, and `eu_access` tokens carry no `iss`/`aud`. So a token minted for
      * ANY Application on the same deployment is cryptographically valid here.
      * Without this, a multi-app self-host accepts another Application's end-user
@@ -961,24 +1257,24 @@ export interface VerifyAccessTokenOptions {
      *
      * (The HS256 default path is not affected: that key is derived per
      * Application as `HMAC-SHA256(JWT_SECRET, applicationId:tokenGeneration)`, so
-     * a foreign token fails the signature. This is the RS256 opt-in only — which
+     * a foreign token fails the signature. This is the RS256 opt-in only, which
      * is exactly the path this function exists for.)
      *
      * Required rather than optional-with-a-warning: a security check nobody is
      * forced to make is one most callers will not make, and the docblock used to
-     * tell them to compare `claims.applicationId` afterwards — which made the
+     * tell them to compare `claims.applicationId` afterwards, which made the
      * shortest correct path the insecure one. 2.0.0 is not out yet, so this
      * breaks rc callers rather than a stable contract.
      */
     applicationId: string;
     /**
-     * URL of the deployment's JWKS — `https://<your-rekey>/.well-known/jwks.json`.
+     * URL of the deployment's JWKS, `https://<your-rekey>/.well-known/jwks.json`.
      * Fetched lazily and cached in-process for `cacheTtlMs` (default 5 minutes);
      * an unknown `kid` triggers one immediate refetch so freshly rotated keys
      * are picked up without waiting out the TTL.
      */
     jwksUrl?: string;
-    /** Pre-fetched key set — skips all network access. Takes precedence over `jwksUrl`. */
+    /** Pre-fetched key set, skips all network access. Takes precedence over `jwksUrl`. */
     jwks?: JwksDto;
     /** Optional fetch override (test stubs, custom agents). */
     fetch?: typeof fetch;
@@ -998,14 +1294,14 @@ export interface VerifyAccessTokenOptions {
     now?: () => number;
 }
 /**
- * Verify an end-user ACCESS token **offline** — no round-trip to the Rekey
+ * Verify an end-user ACCESS token **offline**, no round-trip to the Rekey
  * API. Works only for Applications that opted into RS256 tokens
  * (`authConfig.tokenAlg = "RS256"`, Panel → Application → Auth); the default
  * HS256 tokens are symmetric and can only be verified by the API itself
  * (use `rekey.auth.getCurrentUser(token)` for those).
  *
  * Checks performed (same posture as the API's verifier):
- *   - header `alg` must be `RS256` and `kid` must exist in the JWKS —
+ *   - header `alg` must be `RS256` and `kid` must exist in the JWKS,
  *     a strict allowlist, immune to alg-confusion;
  *   - RSA-SHA256 signature against that public key;
  *   - `exp` in the future, `typ === "eu_access"` (refresh/MFA/MCP tokens
@@ -1015,6 +1311,11 @@ export interface VerifyAccessTokenOptions {
  * user deletion. The 15-minute access lifetime bounds both; for hard
  * revocation guarantees keep using `auth.getCurrentUser`.
  *
+ * Nor can it see any server-side revocation: a locally verified token stays
+ * valid until it expires, even after sign-out everywhere, a password change,
+ * a session revoke or a device release. Call the API when immediate
+ * revocation matters.
+ *
  * Node-only (uses `node:crypto`). Returns the verified claims; throws
  * `RekeyError` on any failure.
  *
@@ -1037,24 +1338,29 @@ export interface VerifyAccessTokenOptions {
  * 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.
- * @throws {RekeyError} `USER_TOKEN_INVALID` — malformed, bad signature, or wrong `typ`.
+ * @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.
+ * @throws {RekeyError} `USER_TOKEN_INVALID`, malformed, bad signature, or wrong `typ`.
  */
 export declare function verifyAccessToken(token: string, options: VerifyAccessTokenOptions): Promise<VerifiedAccessTokenClaims>;
 declare class BillingClient {
     private readonly client;
     constructor(client: Rekey);
     /**
-     * List the calling Application's active plans. Public — pricing pages
+     * List the calling Application's active plans. Public, pricing pages
      * typically render straight from this. Application API key only; no
      * user JWT needed.
      *
-     * `amount` is in the smallest currency unit (cents/paise/sen) — never
+     * `amount` is in the smallest currency unit (cents/paise/sen), never
      * a float. Format on display: `${amount / 100} ${currency}`.
+     *
+     * `checkout.ready` is false when a buyer sent to checkout for the plan would
+     * be refused, so a pricing page can hide it. Why is on the operator plan
+     * list, not here. Keep the free tier in: with no provider connected it reads
+     * `ready: false` and still applies to every signed-in user.
      */
-    getPlans(page?: ListPage): Promise<Paged<PlanDto>>;
+    getPlans(page?: ListPage): Promise<Paged<PublicPlanDto>>;
     /**
      * Fetch the current end-user's active subscription, or `null` if they
      * have none. Returns the most recent ACTIVE / PENDING / PAST_DUE row.
@@ -1062,7 +1368,7 @@ declare class BillingClient {
      * 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
+     * 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
@@ -1079,13 +1385,22 @@ declare class BillingClient {
     /**
      * Start a hosted-checkout session. Returns the URL to redirect the user
      * to and the local PENDING Subscription row. Subscription activation
-     * happens via the provider's webhook — not synchronously here.
+     * happens via the provider's webhook, not synchronously here.
      *
      * Pass `couponCode` to apply a discount. The whole checkout fails if the
      * coupon doesn't validate (typed `RekeyError` with the precise reason).
      *
+     * A buyer who has already used their free trial is refused with
+     * `BILLING_TRIAL_ALREADY_USED` (409). The escape hatch is
+     * `allowWithoutTrial: true` AND a fresh `Idempotency-Key`, but send it only
+     * after the buyer has been told they are paying today. Read
+     * {@link getTrialEligibility} and render the paid price instead of retrying
+     * blindly: a buyer who merely abandoned a trial checkout still reads
+     * `eligible: true`, and acknowledging on their behalf charges them today for
+     * the trial the next checkout was about to grant.
+     *
      * If the Application's billing subject is **org** (Panel → Application →
-     * Billing → Subject), an individual can't hold a subscription — you MUST
+     * Billing → Subject), an individual can't hold a subscription, you MUST
      * pass `organizationId` of a team the user owns/admins. Omitting it throws
      * `RekeyError` `code: "BILLING_ORGANIZATION_REQUIRED"`.
      *
@@ -1103,6 +1418,74 @@ declare class BillingClient {
     createCheckout(accessToken: string, input: CreateCheckoutRequest & {
         couponCode?: string;
     }): Promise<CheckoutResultDto>;
+    /**
+     * Put the calling end-user on the Application's free tier
+     * (`billingConfig.defaultPlanSlug`). No payment provider is involved and none
+     * needs to be configured: the plan costs nothing.
+     *
+     * This is how a freemium product hands a new signup their included credits,
+     * licence or quota. `defaultPlanSlug` alone covers only the read-time half
+     * (feature flags and included usage); CREDIT and LICENSE entitlements are
+     * stateful and need a real subscription, which is what this creates.
+     *
+     * **Idempotent**, and the answer says which happened: `activated: true` is a
+     * first activation (201, `subscription.activated` emitted), `activated:
+     * false` means they were already entitled and nothing was written,
+     * re-provisioned or re-announced.
+     *
+     * Pass `organizationId` on an org-billed Application; the caller must be an
+     * OWNER or ADMIN of it. Omit it and the session's active organization is used.
+     *
+     * @throws {RekeyError} `BILLING_NO_FREE_PLAN` (404) when the Application
+     * nominates no default plan; `BILLING_FREE_PLAN_NOT_FREE` (409) when that
+     * plan charges money, use {@link createCheckout} instead;
+     * `BILLING_FREE_TIER_ALREADY_CLAIMED` (409) when the plan grants credits or a
+     * licence and this caller already claimed it for a different beneficiary.
+     *
+     * @example
+     * ```ts
+     * const { subscription, activated } = await rekey.billing.subscribe(accessToken);
+     * if (activated) welcomeWithStarterCredits(subscription);
+     * ```
+     */
+    subscribe(accessToken: string, input?: {
+        organizationId?: string;
+    }): Promise<{
+        subscription: SubscriptionDto;
+        activated: boolean;
+    }>;
+    /**
+     * Whether THIS buyer may start each plan's free trial, under the
+     * Application's `trialPolicy`.
+     *
+     * Read this before offering a trial: a buyer who is not eligible should be
+     * shown the paid price, not a trial that checkout refuses with
+     * `BILLING_TRIAL_ALREADY_USED`. Feed the result straight into
+     * `<PricingTable trialEligibility={…}>` from `@rekey.dev/react`.
+     *
+     * **Advisory.** The authoritative decision is taken under a lock at checkout,
+     * so two tabs can both read `eligible: true` and only one gets the trial.
+     * Treat a 409 at checkout as normal, not as a contradiction.
+     *
+     * **Provider-dependent.** `PLAN_TRIAL_MISCONFIGURED` can be the resolved
+     * provider's answer, so the response echoes `provider`; re-read this when the
+     * buyer changes processor. Pass `country` (ISO 3166-1 alpha-2) to steer the
+     * geo router the way {@link getProviders} does.
+     *
+     * @example
+     * ```ts
+     * const { items, policy } = await rekey.billing.getTrialEligibility(accessToken);
+     * const pro = items.find((i) => i.planSlug === 'pro');
+     * const label = pro?.eligible ? `Start ${pro.trialDays} days free` : 'Subscribe';
+     * ```
+     */
+    getTrialEligibility(accessToken: string, opts?: {
+        organizationId?: string;
+        planSlug?: string;
+        limit?: number;
+        offset?: number;
+        country?: string;
+    }): Promise<TrialEligibilityDto>;
     /**
      * Validate a coupon for the current user against a plan, *without*
      * applying it. Render "$50 off" on a pricing page before submit.
@@ -1116,7 +1499,7 @@ declare class BillingClient {
     /**
      * List the billing providers configured + enabled for this Application,
      * in the order the geo router would prefer them. Forward the end-user's
-     * `country` (ISO 3166-1 alpha-2) when you have it — the panel/SDK will
+     * `country` (ISO 3166-1 alpha-2) when you have it, the panel/SDK will
      * surface India-specific providers (Razorpay) for IN-country users, etc.
      *
      * Returns the resolved country (echoed back from the server's view of
@@ -1125,7 +1508,7 @@ declare class BillingClient {
      */
     getProviders(country?: string): Promise<ProvidersListDto>;
     /**
-     * Resolve the calling end-user's current entitlements — feature flags +
+     * Resolve the calling end-user's current entitlements, feature flags +
      * limits, the live credit balance, and the raw entitlement list, unioned
      * across their active subscriptions (and subscriptions of orgs they belong
      * to). Pass `{ organizationId }` (member-only) for that org's view + shared
@@ -1140,10 +1523,61 @@ declare class BillingClient {
     getEntitlements(accessToken: string, opts?: {
         organizationId?: string;
     }): Promise<EntitlementsDto>;
+    /**
+     * The same union as `getEntitlements`, for an end-user you name rather than
+     * one whose token you hold. Secret key only, for a licence server, a
+     * support tool or a batch job.
+     *
+     * @example
+     * ```ts
+     * const { features } = await rekey.billing.getEntitlementsFor(endUserId);
+     * if (features.max_devices !== undefined) capDevices(features.max_devices);
+     * ```
+     */
+    getEntitlementsFor(endUserId: string, opts?: {
+        organizationId?: string;
+    }): Promise<EntitlementsDto>;
+    /**
+     * One feature for the calling end-user: `{ key, granted, value }`, where
+     * `value` is what `features[key]` holds in `getEntitlements` (null when
+     * nothing grants it) and `granted` is `Boolean(value)`. The subject is the
+     * one `getCurrentUser(token, { include: ['entitlements'] })` resolves, or
+     * the organization you pass (member-only).
+     *
+     * @example
+     * ```ts
+     * const { value } = await rekey.billing.getFeature(accessToken, 'projects');
+     * if (typeof value === 'number' && count >= value) throw new LimitReached();
+     * ```
+     */
+    getFeature(accessToken: string, key: string, opts?: {
+        organizationId?: string;
+    }): Promise<FeatureCheckDto>;
+    /**
+     * Whether the calling end-user holds a feature: `Boolean(value)`, the test
+     * `if (features[key])` makes, so a false flag, a 0 limit and an unknown key
+     * are all `false`. Use `getFeature` to read a numeric limit.
+     *
+     * @example
+     * ```ts
+     * if (!(await rekey.billing.hasFeature(accessToken, 'reports'))) throw new Forbidden();
+     * ```
+     */
+    hasFeature(accessToken: string, key: string, opts?: {
+        organizationId?: string;
+    }): Promise<boolean>;
+    /** `getFeature` for an end-user you name. Secret key only, like `getEntitlementsFor`. */
+    getFeatureFor(endUserId: string, key: string, opts?: {
+        organizationId?: string;
+    }): Promise<FeatureCheckDto>;
+    /** `hasFeature` for an end-user you name. Secret key only. */
+    hasFeatureFor(endUserId: string, key: string, opts?: {
+        organizationId?: string;
+    }): Promise<boolean>;
     /**
      * Cancel the calling end-user's current subscription.
      *
-     * Defaults to cancelling **at period end** — the user keeps what they paid
+     * Defaults to cancelling **at period end**, the user keeps what they paid
      * for until the period they already bought runs out. A provider-backed
      * subscription therefore stays ACTIVE with `cancelAt` set, and the provider
      * webhook is what eventually terminates it; read `cancelAt` on the returned
@@ -1151,7 +1585,7 @@ declare class BillingClient {
      * `{ atPeriodEnd: false }` to end it immediately, forfeiting the remainder.
      *
      * PENDING checkouts (and anything with no provider-side record) are
-     * cancelled locally straight away regardless of the flag — there is nothing
+     * cancelled locally straight away regardless of the flag, there is nothing
      * at the provider to schedule against.
      *
      * Pass `organizationId` when the subscription belongs to a team; the caller