@recursiv/sdk 0.7.50 → 0.7.52

package/dist/resources/auth.js

@@ -1,4 +1,4 @@
-import { AuthenticationError, RecursivError, ValidationError } from '../errors.js';
+import { AuthenticationError, RateLimitError, RecursivError, ValidationError } from '../errors.js';
 /**
  * Better Auth's anti-CSRF middleware requires an Origin header when the
  * request carries cookies or otherwise looks browser-initiated. We only
@@ -21,6 +21,42 @@ const needsExplicitOrigin = !isBrowser && !isReactNative;
 function originHeader(baseOrigin) {
     return needsExplicitOrigin ? { Origin: baseOrigin } : {};
 }
+/**
+ * The customer-app headers a keyless auth request carries so the server
+ * resolves the right network (user lookup) and brands emails for the app.
+ */
+function appContextHeaders(appContext) {
+    return {
+        ...(appContext?.projectId ? { 'x-recursiv-app-project': appContext.projectId } : {}),
+        ...(appContext?.organizationId ? { 'x-recursiv-app-organization': appContext.organizationId } : {}),
+    };
+}
+/**
+ * Better Auth answers a password sign-in for a two-factor account with
+ * `{ twoFactorRedirect: true }` and no session. Say so, instead of the
+ * generic "no session token" the caller would otherwise get, and hand over
+ * the challenge: the server returns it as `twoFactorToken` (Better Auth
+ * otherwise keeps it only in a cookie this SDK cannot carry). The error's
+ * `details` is a `TwoFactorChallenge`; pass its `twoFactorToken` and the code
+ * to `completeTwoFactorSignIn`.
+ */
+function throwIfTwoFactorRequired(data) {
+    const body = data;
+    if (body?.twoFactorRedirect === true) {
+        const details = {
+            twoFactorToken: typeof body.twoFactorToken === 'string' ? body.twoFactorToken : null,
+            methods: Array.isArray(body.twoFactorMethods)
+                ? body.twoFactorMethods.filter((m) => typeof m === 'string')
+                : [],
+        };
+        throw new AuthenticationError({
+            type: 'auth_error',
+            message: 'This account has two-factor authentication on. Complete the second step to sign in.',
+            code: 'two_factor_required',
+            details,
+        });
+    }
+}
 /**
  * Extract the server's actual error code + message from an error body.
  *
@@ -257,6 +293,69 @@ export class AuthResource {
             }));
         }
         const data = await res.json();
+        throwIfTwoFactorRequired(data);
+        const token = this.extractToken(res, data);
+        if (!token) {
+            throw new RecursivError(0, {
+                type: 'auth_error',
+                message: 'No session token returned from sign in',
+                code: 'no_token',
+            });
+        }
+        return {
+            token,
+            user: {
+                id: data.user?.id,
+                name: data.user?.name,
+                email: data.user?.email,
+                image: data.user?.image ?? null,
+            },
+        };
+    }
+    /**
+     * Sign in with a username (handle) and password.
+     *
+     * Handles are unique per network, not globally, so pass the customer app's
+     * `appContext` when the API is reached through a shared hostname: the server
+     * resolves the handle on that app's network and never on another. Returns a
+     * session token, like `signIn`. A two-factor account throws
+     * `two_factor_required`; finish with `completeTwoFactorSignIn`.
+     */
+    async signInWithUsername(input, appContext) {
+        const res = await this.fetchWithTimeout(`${this.baseOrigin}/api/auth/sign-in/username`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...originHeader(this.baseOrigin),
+                ...appContextHeaders(appContext),
+            },
+            body: JSON.stringify({ username: input.username.trim().replace(/^@/, ''), password: input.password }),
+        });
+        let data = null;
+        try {
+            data = await res.json();
+        }
+        catch {
+            data = null;
+        }
+        if (!res.ok) {
+            // 401 is a wrong handle or password; 422 is a handle that cannot exist.
+            // Both mean the same thing to the person typing, and neither may say
+            // which half was wrong.
+            if (res.status === 401 || res.status === 403 || res.status === 422) {
+                throw new AuthenticationError(serverError(data, {
+                    type: 'auth_error',
+                    message: 'Invalid username or password',
+                    code: 'invalid_credentials',
+                }));
+            }
+            throw new RecursivError(res.status, serverError(data, {
+                type: 'auth_error',
+                message: `Sign in failed: HTTP ${res.status}`,
+                code: 'signin_failed',
+            }));
+        }
+        throwIfTwoFactorRequired(data);
         const token = this.extractToken(res, data);
         if (!token) {
             throw new RecursivError(0, {
@@ -418,15 +517,20 @@ export class AuthResource {
      * whether the email exists, to avoid leaking account existence.
      *
      * Sends the client's API key (when configured) so the server can brand the
-     * reset email for YOUR org — same surface-scoped rule as `sendOtp`.
+     * reset email for YOUR org — same surface-scoped rule as `sendOtp`. Keyless
+     * apps pass `appContext` (same shape as `sendOtp`) for the same effect.
      */
-    async forgetPassword(input) {
+    async forgetPassword(input, appContext) {
         const res = await this.fetchWithTimeout(`${this.baseOrigin}/api/auth/request-password-reset`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
                 ...originHeader(this.baseOrigin),
                 ...this.client.apiKeyAuthHeader(),
+                // Same as sendOtp: a keyless app names itself so the reset email is
+                // branded for it and the address is looked up on its network, not the
+                // platform default.
+                ...appContextHeaders(appContext),
             },
             body: JSON.stringify({
                 email: input.email,
@@ -447,6 +551,50 @@ export class AuthResource {
         }
         return { success: true };
     }
+    /**
+     * Set a new password with the token from a password reset email (the
+     * `token` your reset screen receives). Every existing session and API key
+     * for the account is revoked by the server, so sign in again afterwards.
+     */
+    async resetPassword(input, appContext) {
+        const res = await this.fetchWithTimeout(`${this.baseOrigin}/api/auth/reset-password`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...originHeader(this.baseOrigin),
+                ...appContextHeaders(appContext),
+            },
+            body: JSON.stringify({ newPassword: input.newPassword, token: input.token }),
+        });
+        if (!res.ok) {
+            let body = {};
+            try {
+                body = await res.json();
+            }
+            catch { }
+            const info = serverErrorInfo(body);
+            if (res.status === 400 && (info.code === 'INVALID_TOKEN' || info.code === 'INVALID_TOKEN_OR_EXPIRED')) {
+                throw new ValidationError(serverError(body, {
+                    type: 'validation_error',
+                    message: 'This reset link is invalid or has expired. Request a new one.',
+                    code: 'invalid_reset_token',
+                }));
+            }
+            if (res.status === 400 || res.status === 422) {
+                throw new ValidationError(serverError(body, {
+                    type: 'validation_error',
+                    message: 'The new password was not accepted.',
+                    code: 'invalid_password',
+                }));
+            }
+            throw new RecursivError(res.status, serverError(body, {
+                type: 'auth_error',
+                message: `Password reset failed: HTTP ${res.status}`,
+                code: 'reset_password_failed',
+            }));
+        }
+        return { success: true };
+    }
     /**
      * Get current session info using a session token.
      * Returns null if the session is invalid or expired.
@@ -577,6 +725,19 @@ export class AuthResource {
         const key = await this.createApiKeyOrRetireSession(keyInput, session);
         return { apiKey: key.key, apiKeyId: key.id, user: session.user, session };
     }
+    /**
+     * `signInWithUsername`, then the app API key, exactly like `signInAndCreateKey`.
+     * The key's project/organization is forwarded as the sign-in's app context,
+     * so the handle is resolved on the app's network.
+     */
+    async signInWithUsernameAndCreateKey(credentials, keyInput) {
+        const session = await this.signInWithUsername(credentials, {
+            projectId: keyInput.projectId,
+            organizationId: keyInput.organizationId,
+        });
+        const key = await this.createApiKeyOrRetireSession(keyInput, session);
+        return { apiKey: key.key, apiKeyId: key.id, user: session.user, session };
+    }
     /**
      * Complete mobile auth flow: sign up → create API key → return key.
      *
@@ -597,6 +758,10 @@ export class AuthResource {
      * Exchange a legacy Minds session (the OAuth access token or minds_sess JWT
      * the legacy mobile app stored) for a session on this stack. Only answers
      * during the cutover window; every failure means "show the OTP screen".
+     *
+     * A legacy token is single-use: after one successful exchange the server
+     * answers `legacy_token_used`, so erase the stored legacy token as soon as
+     * this resolves and never retry it.
      */
     async legacyHandoff(legacyToken, appContext) {
         const res = await this.fetchWithTimeout(`${this.baseOrigin}/api/auth/legacy-handoff`, {
@@ -660,6 +825,235 @@ export class AuthResource {
         const key = await this.createApiKeyOrRetireSession(keyInput, session);
         return { apiKey: key.key, apiKeyId: key.id, user: session.user, session };
     }
+    // ── OAuth consent (MCP bridge) ──
+    /**
+     * Set the API-origin session cookie from a session token this client
+     * already holds, so a browser can continue an OAuth authorize request
+     * (`/api/auth/mcp/authorize`) without signing in again: the one-tap
+     * "Continue as @handle". Browser only in effect: the cookie is stored by the
+     * browser because the request is sent with `credentials: 'include'`.
+     * Returns the account the cookie now signs in.
+     */
+    async exchangeSessionForCookie(sessionToken) {
+        const res = await this.fetchWithTimeout(`${this.baseOrigin}/api/auth/session-cookie`, {
+            method: 'POST',
+            credentials: 'include',
+            headers: {
+                ...originHeader(this.baseOrigin),
+                Authorization: `Bearer ${sessionToken}`,
+            },
+        });
+        let data = null;
+        try {
+            data = await res.json();
+        }
+        catch {
+            data = null;
+        }
+        if (!res.ok) {
+            const error = serverError(data, {
+                type: 'auth_error',
+                message: `Could not continue with this session: HTTP ${res.status}`,
+                code: 'session_cookie_failed',
+            });
+            if (res.status === 401 || res.status === 403)
+                throw new AuthenticationError(error);
+            throw new RecursivError(res.status, error);
+        }
+        return { user: data.user };
+    }
+    /**
+     * Public facts about the OAuth client behind an authorize request: its name,
+     * icon, redirect hosts, whether `redirectUri` is one it registered, and which
+     * requested scopes are granted. No authentication needed.
+     */
+    async getOAuthClientInfo(input) {
+        const query = new URLSearchParams({ client_id: input.clientId });
+        if (input.redirectUri !== undefined)
+            query.set('redirect_uri', input.redirectUri);
+        if (input.scope !== undefined)
+            query.set('scope', input.scope);
+        const res = await this.fetchWithTimeout(`${this.baseOrigin}/api/auth/mcp/client-info?${query}`, { method: 'GET' });
+        let data = null;
+        try {
+            data = await res.json();
+        }
+        catch {
+            data = null;
+        }
+        if (!res.ok) {
+            throw new RecursivError(res.status, serverError(data, {
+                type: res.status === 404 ? 'not_found' : 'api_error',
+                message: res.status === 404 ? 'No OAuth client is registered with that client_id' : `Client lookup failed: HTTP ${res.status}`,
+                code: res.status === 404 ? 'client_not_found' : 'client_info_failed',
+            }));
+        }
+        return data;
+    }
+    // ── Two-factor sign-in ──
+    /**
+     * Finish a password sign-in on a two-factor account. `signIn`,
+     * `signInWithUsername` and their `*AndCreateKey` forms throw
+     * `AuthenticationError` with code `two_factor_required`; its `details` is a
+     * `TwoFactorChallenge`. Send its `twoFactorToken` with the code the member
+     * types. Returns the session, like `signIn`.
+     *
+     * Errors keep the server's code: `INVALID_CODE` / `INVALID_BACKUP_CODE` (a
+     * wrong code: ask again), `INVALID_TWO_FACTOR_COOKIE` (the challenge expired
+     * or was used: sign in again), `TOO_MANY_ATTEMPTS_REQUEST_NEW_CODE` (five
+     * wrong codes on this challenge: sign in again), and
+     * `ACCOUNT_TEMPORARILY_LOCKED` (too many wrong codes on the account: wait
+     * `retryAfter` seconds).
+     */
+    async completeTwoFactorSignIn(input) {
+        const path = input.method === 'backup_code' ? '/two-factor/verify-backup-code' : '/two-factor/verify-totp';
+        const res = await this.fetchWithTimeout(`${this.baseOrigin}/api/auth${path}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...originHeader(this.baseOrigin),
+            },
+            body: JSON.stringify({ code: input.code.trim(), twoFactorToken: input.twoFactorToken }),
+        });
+        let data = null;
+        try {
+            data = await res.json();
+        }
+        catch {
+            data = null;
+        }
+        if (!res.ok) {
+            const retryAfter = Number(res.headers.get('retry-after'));
+            const error = serverError(data, {
+                type: 'auth_error',
+                message: res.status === 401 ? 'That code is not right' : `Two-factor sign-in failed: HTTP ${res.status}`,
+                code: res.status === 401 ? 'invalid_two_factor_code' : 'two_factor_sign_in_failed',
+                ...(Number.isFinite(retryAfter) && retryAfter > 0 ? { retry_after: retryAfter } : {}),
+            });
+            if (res.status === 401)
+                throw new AuthenticationError(error);
+            if (res.status === 429)
+                throw new RateLimitError(error);
+            if (res.status === 400 || res.status === 422)
+                throw new ValidationError(error);
+            throw new RecursivError(res.status, error);
+        }
+        const token = this.extractToken(res, data);
+        if (!token) {
+            throw new RecursivError(0, {
+                type: 'auth_error',
+                message: 'No session token returned from two-factor sign in',
+                code: 'no_token',
+            });
+        }
+        return {
+            token,
+            user: {
+                id: data.user?.id,
+                name: data.user?.name,
+                email: data.user?.email,
+                image: data.user?.image ?? null,
+            },
+        };
+    }
+    /**
+     * `completeTwoFactorSignIn`, then the app API key, exactly like
+     * `signInAndCreateKey`: the second half of a `*AndCreateKey` sign-in that
+     * threw `two_factor_required`.
+     */
+    async completeTwoFactorSignInAndCreateKey(input, keyInput) {
+        const session = await this.completeTwoFactorSignIn(input);
+        const key = await this.createApiKeyOrRetireSession(keyInput, session);
+        return { apiKey: key.key, apiKeyId: key.id, user: session.user, session };
+    }
+    // ── Two-factor (TOTP) ──
+    //
+    // These run against Better Auth with the member's SESSION token (the
+    // `session.token` from sign-in), not the API key. Verify (the call that
+    // turns two-factor on) and disable replace the session server-side, and the
+    // token passed in stops working. Every method that can rotate it returns
+    // the live `sessionToken`: store it.
+    async sessionRequest(path, body, sessionToken, fallback, appContext) {
+        const res = await this.fetchWithTimeout(`${this.baseOrigin}/api/auth${path}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...originHeader(this.baseOrigin),
+                ...appContextHeaders(appContext),
+                Authorization: `Bearer ${sessionToken}`,
+                Cookie: `better-auth.session_token=${sessionToken}`,
+            },
+            body: JSON.stringify(body ?? {}),
+        });
+        let data = null;
+        try {
+            data = await res.json();
+        }
+        catch {
+            data = null;
+        }
+        if (!res.ok) {
+            const error = serverError(data, { type: 'auth_error', message: fallback.message, code: fallback.code });
+            if (res.status === 401)
+                throw new AuthenticationError({ ...error, code: error.code || 'session_required' });
+            if (res.status === 400 || res.status === 422)
+                throw new ValidationError(error);
+            throw new RecursivError(res.status, error);
+        }
+        return data;
+    }
+    static confirmationBody(input) {
+        return {
+            ...(input.password ? { password: input.password } : {}),
+            ...(input.emailCode ? { emailCode: input.emailCode.trim() } : {}),
+        };
+    }
+    /**
+     * Email a two-factor confirmation code to an account that has no password.
+     * An account with a password answers `PASSWORD_REQUIRED`: it confirms with
+     * the password instead. Pass the app's `appContext` (as for `sendOtp`) when
+     * the API is reached through a shared hostname, so the email carries the
+     * app's brand rather than the platform's.
+     */
+    async requestTwoFactorEmailCode(sessionToken, appContext) {
+        const data = await this.sessionRequest('/two-factor/request-email-code', {}, sessionToken, { message: 'Could not send a confirmation code', code: 'two_factor_email_code_failed' }, appContext);
+        return { expiresAt: data.expiresAt };
+    }
+    /**
+     * Start two-factor enrollment. Returns the authenticator URI and backup
+     * codes; two-factor is not on until `verifyTwoFactor` accepts a code from
+     * the authenticator.
+     *
+     * An account with no password answers `PASSWORD_REQUIRED_FOR_TWO_FACTOR`
+     * unless the server enables code-only enrollment: its sign-ins (email
+     * code, passkey, social) do not ask for the second factor yet.
+     */
+    async enableTwoFactor(input, sessionToken) {
+        const data = await this.sessionRequest('/two-factor/enable', { ...AuthResource.confirmationBody(input), ...(input.issuer ? { issuer: input.issuer } : {}) }, sessionToken, { message: 'Could not start two-factor setup', code: 'two_factor_enable_failed' });
+        return {
+            totpURI: data.totpURI,
+            backupCodes: Array.isArray(data.backupCodes) ? data.backupCodes : [],
+            sessionToken: data?.session?.token || sessionToken,
+        };
+    }
+    /**
+     * Confirm enrollment with a code from the authenticator app. This is the
+     * call that turns two-factor on.
+     */
+    async verifyTwoFactor(input, sessionToken) {
+        const data = await this.sessionRequest('/two-factor/verify-totp', { code: input.code.trim() }, sessionToken, { message: 'That code is not right', code: 'invalid_two_factor_code' });
+        return { sessionToken: data?.session?.token || data?.token || sessionToken };
+    }
+    /** Turn two-factor off. Confirmed with the password, or an email code for accounts without one. */
+    async disableTwoFactor(input, sessionToken) {
+        const data = await this.sessionRequest('/two-factor/disable', AuthResource.confirmationBody(input), sessionToken, { message: 'Could not turn off two-factor', code: 'two_factor_disable_failed' });
+        return { sessionToken: data?.session?.token || sessionToken };
+    }
+    /** Replace the backup codes. The old ones stop working. */
+    async regenerateTwoFactorBackupCodes(input, sessionToken) {
+        const data = await this.sessionRequest('/two-factor/generate-backup-codes', AuthResource.confirmationBody(input), sessionToken, { message: 'Could not create new backup codes', code: 'two_factor_backup_codes_failed' });
+        return { backupCodes: Array.isArray(data?.backupCodes) ? data.backupCodes : [] };
+    }
     /**
      * The key-mint leg of the `*AndCreateKey` flows. When the mint fails, the
      * caller receives only the thrown error — the session created one step

package/dist/resources/boosts.d.ts

@@ -0,0 +1,170 @@
+import type { HttpClient } from '../client.js';
+import type { PaginatedResponse, SingleResponse } from '../types.js';
+/** Campaign lifecycle axis. */
+export type BoostStatus = 'active' | 'paused' | 'completed' | 'refunded';
+/** Campaign moderation axis. A campaign delivers only when `active` AND `approved`. */
+export type BoostReviewStatus = 'pending' | 'approved' | 'rejected';
+export type BoostRejectionReason = 'against_policy' | 'wrong_audience' | 'payment' | 'reported' | 'post_removed';
+export type BoostLedgerKind = 'grant' | 'topup' | 'spend' | 'refund';
+/** A promoted-post campaign. Money is micro-USD (1 USD = 1,000,000). */
+export interface BoostCampaign {
+    id: string;
+    post_id: string;
+    booster_user_id: string;
+    /** Bid: micro-USD per 1000 impressions. */
+    cpm_micros: number;
+    budget_micros: number;
+    spent_micros: number;
+    impressions_target: number;
+    impressions_served: number;
+    status: BoostStatus;
+    review_status: BoostReviewStatus;
+    rejection_reason: BoostRejectionReason | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface BoostLedgerEntry {
+    id: string;
+    campaign_id: string | null;
+    /** Positive credits the balance, negative debits it. */
+    delta_micros: number;
+    kind: BoostLedgerKind;
+    note: string | null;
+    created_at: string;
+}
+export interface BoostTopupLimits {
+    /** Whether this app sells boost credit (always true on a `topup` response). */
+    available: boolean;
+    min_cents: number;
+    max_cents: number;
+    currency: 'usd';
+}
+export interface BoostBalance {
+    balance_micros: number;
+    /** The 50 most recent balance movements, newest first. */
+    ledger: BoostLedgerEntry[];
+}
+/** The boost credit the key's app includes with its paid plans. */
+export interface BoostPlanCredit {
+    /** Micro-USD each paid billing period of a plan adds, by tier key (e.g. `plus`, `pro`). */
+    per_period_micros: Record<string, number>;
+    /** What your current plan on this app adds each paid period; 0 without one. */
+    current_micros: number;
+    /** When your next paid period starts and adds `current_micros`; null when none is due. */
+    next_grant_at: string | null;
+    /**
+     * Plan credit you owe: taken back after your plan dropped or ended inside a period, but already
+     * spent. Your next plan credit repays it before adding anything. 0 when nothing is owed
+     * (absent from older servers).
+     */
+    owed_micros?: number;
+}
+export interface BoostBalanceResponse extends SingleResponse<BoostBalance> {
+    /** `plan_credit` is null when the app's plans include no boost credit (absent from older servers). */
+    meta: {
+        min_cpm_micros: number;
+        topup?: BoostTopupLimits;
+        plan_credit?: BoostPlanCredit | null;
+    };
+}
+export interface BoostCampaignResponse extends SingleResponse<BoostCampaign> {
+    meta?: {
+        min_cpm_micros?: number;
+        refunded_micros?: number;
+    };
+}
+export interface BoostEventResult {
+    recorded: boolean;
+    duplicate: boolean;
+    campaign_status: BoostStatus;
+    spent_micros: number;
+    impressions_served: number;
+}
+export interface BoostTopupCheckout {
+    /** Stripe Checkout URL to open. */
+    url: string;
+    /** Pass to `confirmTopup` when the member returns (the return URL also carries it as `session_id`). */
+    session_id: string;
+}
+export interface BoostTopupConfirmation {
+    /** `credited` now, `already_credited` earlier (webhook or a previous confirm), or `unpaid` so far. */
+    status: 'credited' | 'already_credited' | 'unpaid';
+    credited_micros: number;
+    balance_micros: number | null;
+}
+/**
+ * Boost: pay to promote your own post into the For You feed. CPM campaigns
+ * funded from a prepaid balance with an append-only ledger. Top-ups run on the
+ * app's own Stripe account and need a project-scoped key.
+ */
+export declare class BoostsResource {
+    private client;
+    constructor(client: HttpClient);
+    /**
+     * Create a campaign for one of your own posts. Debits `budget_micros` from your balance
+     * (402 `insufficient_balance` when it cannot). Starts `pending` review.
+     * Not retried automatically, so a slow response cannot fund two campaigns.
+     */
+    create(input: {
+        post_id: string;
+        cpm_micros: number;
+        budget_micros: number;
+    }): Promise<BoostCampaignResponse>;
+    /** Your campaigns, newest first, with spend and impressions. */
+    mine(params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResponse<BoostCampaign>>;
+    /**
+     * Your balance, recent ledger, the CPM floor, the top-up limits, and the boost credit your
+     * plan on this app adds each paid period (`meta.plan_credit`, a `grant` ledger row per period).
+     */
+    balance(): Promise<BoostBalanceResponse>;
+    /** Pause one of your active campaigns. */
+    pause(campaignId: string): Promise<BoostCampaignResponse>;
+    /** Resume one of your paused campaigns. */
+    resume(campaignId: string): Promise<BoostCampaignResponse>;
+    /** Cancel a campaign and refund its unspent budget to your balance (`meta.refunded_micros`). */
+    cancel(campaignId: string): Promise<BoostCampaignResponse>;
+    /** Report an impression or click on a boosted feed entry. Idempotent per viewer per UTC day. */
+    recordEvent(campaignId: string, kind: 'impression' | 'click'): Promise<SingleResponse<BoostEventResult>>;
+    /**
+     * Buy boost credit: opens a one-time Stripe Checkout for `amount_cents` (USD) on the app's
+     * own Stripe account. The balance is credited once the payment succeeds. Limits are in
+     * `balance().meta.topup`. Requires a project-scoped key with `billing:write`.
+     * `return_url` keeps its own query and fragment; `topup=success&session_id=<id>` or
+     * `topup=cancelled` is added to its query (to the fragment's query for a hash route).
+     */
+    topup(input: {
+        amount_cents: number;
+        return_url: string;
+    }): Promise<SingleResponse<BoostTopupCheckout> & {
+        meta: {
+            topup: BoostTopupLimits;
+        };
+    }>;
+    /**
+     * Credit a paid top-up when the member returns from Checkout. Safe to call repeatedly
+     * and alongside the webhook: a session credits the balance once.
+     */
+    confirmTopup(sessionId: string): Promise<SingleResponse<BoostTopupConfirmation>>;
+    /** Campaigns waiting for review, oldest first (admin). */
+    listPendingReview(params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResponse<BoostCampaign>>;
+    /** Approve or reject a campaign (admin). Rejecting refunds the unspent budget. */
+    review(campaignId: string, input: {
+        action: 'approve' | 'reject';
+        reason?: BoostRejectionReason;
+    }): Promise<BoostCampaignResponse>;
+    /** Grant balance to a user (admin). */
+    grant(input: {
+        user_id: string;
+        amount_micros: number;
+        note?: string;
+    }): Promise<SingleResponse<{
+        user_id: string;
+        balance_micros: number;
+    }>>;
+}