@recursiv/sdk 0.7.50 → 0.7.51

package/dist/resources/app-subscriptions.d.ts

@@ -9,9 +9,32 @@ export interface AppSubscriptionPortalResult {
 }
 export interface AppSubscriptionStatusResult {
     tier: string;
-    status: 'active' | 'past_due' | 'canceled' | 'none';
+    /** 'legacy' is a membership carried over from a previous platform, with no subscription here. */
+    status: 'active' | 'past_due' | 'canceled' | 'none' | 'legacy';
     active: boolean;
     currentPeriodEnd: string | null;
+    /** Where the entitlement comes from: a Stripe subscription here, or the legacy import. */
+    source?: 'stripe' | 'legacy';
+}
+export interface AppSubscriptionTierChangePreview {
+    /** The plan the preview prices. */
+    tier: string;
+    /** The plan the member pays for now. */
+    currentTier: string;
+    /** Prorated charge (positive) or credit (negative) for the rest of this period, in minor units. */
+    prorationAmount: number;
+    /** What the next invoice totals with the change applied, in minor units. */
+    amountDue: number;
+    currency: string;
+    /** Pass to `changeTier` so the charge matches this preview exactly. */
+    prorationDate: number;
+    nextPaymentAt: string | null;
+}
+export interface AppSubscriptionTierChangeResult {
+    tier: string;
+    previousTier: string;
+    status: 'active' | 'past_due' | 'canceled';
+    currentPeriodEnd: string | null;
 }
 /**
  * Per-app-user consumer subscriptions (e.g. Plus/Pro) billed through the app's
@@ -20,13 +43,42 @@ export interface AppSubscriptionStatusResult {
 export declare class AppSubscriptionsResource {
     private client;
     constructor(client: HttpClient);
-    /** Start a Stripe Checkout for the current user to subscribe to a plan tier ('plus' | 'pro'). */
+    /**
+     * Start a Stripe Checkout for the current user to subscribe to a plan tier ('plus' | 'pro').
+     * Answers 409 `subscription_exists` when the member already has a subscription:
+     * use `changeTier` for them instead, so they are never billed twice.
+     */
     checkout(input: {
         tier: string;
         return_url: string;
     }): Promise<{
         data: AppSubscriptionCheckoutResult;
     }>;
+    /**
+     * Price a switch of the current member's plan to `tier`, prorated, without changing anything.
+     * Errors (409) name why a switch cannot run: `no_subscription`, `already_on_tier`,
+     * `subscription_not_active`, `subscription_canceling`, `legacy_membership`.
+     */
+    previewTierChange(input: {
+        tier: string;
+    }): Promise<{
+        data: AppSubscriptionTierChangePreview;
+    }>;
+    /**
+     * Switch the current member's existing subscription to `tier`, prorated, in place.
+     * Never opens a second subscription. Pass `proration_date` from `previewTierChange`
+     * to charge exactly what the preview showed. A switch to a lower plan takes effect
+     * now: the unused time on the higher plan is credited, and that plan ends at once.
+     * Not retried automatically: on an
+     * unclear failure, read `status()` before trying again (a repeat answers 409
+     * `already_on_tier` rather than charging twice).
+     */
+    changeTier(input: {
+        tier: string;
+        proration_date?: number;
+    }): Promise<{
+        data: AppSubscriptionTierChangeResult;
+    }>;
     /** Open the current app user's Stripe Billing Portal for this project. */
     createPortalSession(input: {
         return_url: string;

package/dist/resources/app-subscriptions.js

@@ -7,10 +7,34 @@ export class AppSubscriptionsResource {
     constructor(client) {
         this.client = client;
     }
-    /** Start a Stripe Checkout for the current user to subscribe to a plan tier ('plus' | 'pro'). */
+    /**
+     * Start a Stripe Checkout for the current user to subscribe to a plan tier ('plus' | 'pro').
+     * Answers 409 `subscription_exists` when the member already has a subscription:
+     * use `changeTier` for them instead, so they are never billed twice.
+     */
     checkout(input) {
         return this.client.post('/app-subscriptions/checkout', input);
     }
+    /**
+     * Price a switch of the current member's plan to `tier`, prorated, without changing anything.
+     * Errors (409) name why a switch cannot run: `no_subscription`, `already_on_tier`,
+     * `subscription_not_active`, `subscription_canceling`, `legacy_membership`.
+     */
+    previewTierChange(input) {
+        return this.client.get('/app-subscriptions/change-tier/preview', { tier: input.tier });
+    }
+    /**
+     * Switch the current member's existing subscription to `tier`, prorated, in place.
+     * Never opens a second subscription. Pass `proration_date` from `previewTierChange`
+     * to charge exactly what the preview showed. A switch to a lower plan takes effect
+     * now: the unused time on the higher plan is credited, and that plan ends at once.
+     * Not retried automatically: on an
+     * unclear failure, read `status()` before trying again (a repeat answers 409
+     * `already_on_tier` rather than charging twice).
+     */
+    changeTier(input) {
+        return this.client.post('/app-subscriptions/change-tier', input, { retry: false });
+    }
     /** Open the current app user's Stripe Billing Portal for this project. */
     createPortalSession(input) {
         return this.client.post('/app-subscriptions/portal', input);

package/dist/resources/auth.d.ts

@@ -17,6 +17,73 @@ export interface SignInInput {
     email: string;
     password: string;
 }
+export interface UsernameSignInInput {
+    /** The member's handle, without the leading @. Matching is case-insensitive. */
+    username: string;
+    password: string;
+}
+/** The customer app a keyless auth call is made for (see `signIn`). */
+export interface AppContext {
+    projectId?: string;
+    organizationId?: string;
+}
+export interface ResetPasswordInput {
+    /** The new password. Must meet the server's password policy. */
+    newPassword: string;
+    /** The reset token from the link in the reset email. */
+    token: string;
+}
+/**
+ * How a two-factor change is confirmed. An account with a password sends
+ * `password`. An account with no password (OTP-only) sends `emailCode`, the
+ * six digits from `requestTwoFactorEmailCode` (or `settings.requestConfirmationCode('two_factor')`).
+ */
+export interface TwoFactorConfirmation {
+    password?: string;
+    emailCode?: string;
+}
+/** Public facts about a registered OAuth (MCP) client, for a consent screen. */
+export interface OAuthClientInfo {
+    client_id: string;
+    /** Chosen by whoever registered the client. Show it as a claim, next to the redirect host. */
+    name: string | null;
+    icon: string | null;
+    type: 'public' | 'web';
+    disabled: boolean;
+    /** Hosts the client may send the member back to. This is the fact to show. */
+    redirect_hosts: string[];
+    /** Present when `redirectUri` was passed: whether the client registered it. */
+    redirect_uri_registered?: boolean;
+    scopes_supported: string[];
+    /** Present when `scope` was passed: the requested scopes this server grants, and the rest. */
+    requested_scopes?: string[];
+    unsupported_scopes?: string[];
+}
+/**
+ * The `details` of the `two_factor_required` error a password sign-in throws
+ * for a two-factor account. The challenge is single-use, lives ten minutes
+ * and allows five codes.
+ */
+export interface TwoFactorChallenge {
+    /** Pass to `completeTwoFactorSignIn`. Null only from a server older than this field. */
+    twoFactorToken: string | null;
+    /** Second factors the server offers for this account, e.g. `['totp']`. Backup codes always work. */
+    methods: string[];
+}
+export interface CompleteTwoFactorSignInInput {
+    /** From the `two_factor_required` error's `details.twoFactorToken`. */
+    twoFactorToken: string;
+    /** The six digits from the authenticator app, or one backup code. */
+    code: string;
+    /** `backup_code` for a backup code. Defaults to `totp`. */
+    method?: 'totp' | 'backup_code';
+}
+export interface TwoFactorEnrollment {
+    /** otpauth:// URI for an authenticator app (render it as a QR code). */
+    totpURI: string;
+    /** One-time backup codes. Shown once; ask the member to save them. */
+    backupCodes: string[];
+}
 export interface SendOtpInput {
     email: string;
 }
@@ -143,6 +210,16 @@ export declare class AuthResource {
         projectId?: string;
         organizationId?: string;
     }): Promise<AuthSession>;
+    /**
+     * 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`.
+     */
+    signInWithUsername(input: UsernameSignInInput, appContext?: AppContext): Promise<AuthSession>;
     /**
      * Send a one-time password to an email address.
      * Works for both new and existing users — no password required.
@@ -180,12 +257,21 @@ export declare 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.
      */
     forgetPassword(input: {
         email: string;
         redirectTo?: string;
-    }): Promise<{
+    }, appContext?: AppContext): Promise<{
+        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.
+     */
+    resetPassword(input: ResetPasswordInput, appContext?: AppContext): Promise<{
         success: true;
     }>;
     /**
@@ -231,6 +317,17 @@ export declare class AuthResource {
         user: AuthSession['user'];
         session: AuthSession;
     }>;
+    /**
+     * `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.
+     */
+    signInWithUsernameAndCreateKey(credentials: UsernameSignInInput, keyInput: CreateApiKeyInput): Promise<{
+        apiKey: string;
+        apiKeyId: string;
+        user: AuthSession['user'];
+        session: AuthSession;
+    }>;
     /**
      * Complete mobile auth flow: sign up → create API key → return key.
      *
@@ -246,6 +343,10 @@ export declare 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.
      */
     legacyHandoff(legacyToken: string, appContext?: {
         projectId?: string;
@@ -275,6 +376,101 @@ export declare class AuthResource {
         user: AuthSession['user'];
         session: AuthSession;
     }>;
+    /**
+     * 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.
+     */
+    exchangeSessionForCookie(sessionToken: string): Promise<{
+        user: {
+            id: string;
+            name: string | null;
+            username: string | null;
+            image: string | null;
+        };
+    }>;
+    /**
+     * 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.
+     */
+    getOAuthClientInfo(input: {
+        clientId: string;
+        redirectUri?: string;
+        scope?: string;
+    }): Promise<OAuthClientInfo>;
+    /**
+     * 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).
+     */
+    completeTwoFactorSignIn(input: CompleteTwoFactorSignInInput): Promise<AuthSession>;
+    /**
+     * `completeTwoFactorSignIn`, then the app API key, exactly like
+     * `signInAndCreateKey`: the second half of a `*AndCreateKey` sign-in that
+     * threw `two_factor_required`.
+     */
+    completeTwoFactorSignInAndCreateKey(input: CompleteTwoFactorSignInInput, keyInput: CreateApiKeyInput): Promise<{
+        apiKey: string;
+        apiKeyId: string;
+        user: AuthSession['user'];
+        session: AuthSession;
+    }>;
+    private sessionRequest;
+    private static confirmationBody;
+    /**
+     * 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.
+     */
+    requestTwoFactorEmailCode(sessionToken: string, appContext?: AppContext): Promise<{
+        expiresAt: string;
+    }>;
+    /**
+     * 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.
+     */
+    enableTwoFactor(input: TwoFactorConfirmation & {
+        issuer?: string;
+    }, sessionToken: string): Promise<TwoFactorEnrollment & {
+        sessionToken: string;
+    }>;
+    /**
+     * Confirm enrollment with a code from the authenticator app. This is the
+     * call that turns two-factor on.
+     */
+    verifyTwoFactor(input: {
+        code: string;
+    }, sessionToken: string): Promise<{
+        sessionToken: string;
+    }>;
+    /** Turn two-factor off. Confirmed with the password, or an email code for accounts without one. */
+    disableTwoFactor(input: TwoFactorConfirmation, sessionToken: string): Promise<{
+        sessionToken: string;
+    }>;
+    /** Replace the backup codes. The old ones stop working. */
+    regenerateTwoFactorBackupCodes(input: TwoFactorConfirmation, sessionToken: string): Promise<{
+        backupCodes: string[];
+    }>;
     /**
      * The key-mint leg of the `*AndCreateKey` flows. When the mint fails, the
      * caller receives only the thrown error — the session created one step