Add MFA Session Params (#293)

* bump totp/otp

* package bump

* minor

lib/b2b/otp_sms.ts

@@ -139,6 +139,9 @@ export interface B2BOTPSmsSendRequest {
    *
    */
   locale?: "en" | "es" | "pt-br" | string;
+  intermediate_session_token?: string;
+  session_token?: string;
+  session_jwt?: string;
 }
 
 // Response type for `otps.sms.send`.
@@ -193,6 +196,9 @@ export class Sms {
    * [bills the costs of international OTPs](https://stytch.com/pricing) and understand how to protect your
    * app against [toll fraud](https://stytch.com/docs/guides/passcodes/toll-fraud/overview).
    *
+   * Even when international SMS is enabled, we do not support sending SMS to countries on our
+   * [Unsupported countries list](https://stytch.com/docs/guides/passcodes/unsupported-countries).
+   *
    * __Note:__ SMS to phone numbers outside of the US and Canada is disabled by default for customers who did
    * not use SMS prior to October 2023. If you're interested in sending international SMS, please reach out
    * to [[email protected]](mailto:[email protected]?subject=Enable%20international%20SMS).

lib/b2b/totps.ts

@@ -10,62 +10,204 @@ import { Member, Organization } from "./organizations";
 import { MemberSession } from "./sessions";
 import { request } from "../shared";
 
+// Request type for `totps.authenticate`.
 export interface B2BTOTPsAuthenticateRequest {
+  /**
+   * Globally unique UUID that identifies a specific Organization. The `organization_id` is critical to
+   * perform operations on an Organization, so be sure to preserve this value.
+   */
   organization_id: string;
+  /**
+   * Globally unique UUID that identifies a specific Member. The `member_id` is critical to perform
+   * operations on a Member, so be sure to preserve this value.
+   */
   member_id: string;
+  // The code to authenticate.
   code: string;
+  /**
+   * The Intermediate Session Token. This token does not necessarily belong to a specific instance of a
+   * Member, but represents a bag of factors that may be converted to a member session.
+   *     The token can be used with the
+   * [OTP SMS Authenticate endpoint](https://stytch.com/docs/b2b/api/authenticate-otp-sms) to complete an MFA
+   * flow;
+   *     the
+   * [Exchange Intermediate Session endpoint](https://stytch.com/docs/b2b/api/exchange-intermediate-session)
+   * to join a specific Organization that allows the factors represented by the intermediate session token;
+   *     or the
+   * [Create Organization via Discovery endpoint](https://stytch.com/docs/b2b/api/create-organization-via-discovery) to create a new Organization and Member.
+   */
   intermediate_session_token?: string;
+  // A secret token for a given Stytch Session.
   session_token?: string;
+  // The JSON Web Token (JWT) for a given Stytch Session.
   session_jwt?: string;
+  /**
+   * Set the session lifetime to be this many minutes from now. This will start a new session if one doesn't
+   * already exist,
+   *   returning both an opaque `session_token` and `session_jwt` for this session. Remember that the
+   * `session_jwt` will have a fixed lifetime of
+   *   five minutes regardless of the underlying session duration, and will need to be refreshed over time.
+   *
+   *   This value must be a minimum of 5 and a maximum of 527040 minutes (366 days).
+   *
+   *   If a `session_token` or `session_jwt` is provided then a successful authentication will continue to
+   * extend the session this many minutes.
+   *
+   *   If the `session_duration_minutes` parameter is not specified, a Stytch session will be created with a
+   * 60 minute duration. If you don't want
+   *   to use the Stytch session product, you can ignore the session fields in the response.
+   */
   session_duration_minutes?: number;
+  /**
+   * Add a custom claims map to the Session being authenticated. Claims are only created if a Session is
+   * initialized by providing a value in
+   *   `session_duration_minutes`. Claims will be included on the Session object and in the JWT. To update a
+   * key in an existing Session, supply a new value. To
+   *   delete a key, supply a null value. Custom claims made with reserved claims (`iss`, `sub`, `aud`,
+   * `exp`, `nbf`, `iat`, `jti`) will be ignored.
+   *   Total custom claims size cannot exceed four kilobytes.
+   */
   session_custom_claims?: Record<string, any>; // eslint-disable-line @typescript-eslint/no-explicit-any
+  /**
+   * Optionally sets the Member’s MFA enrollment status upon a successful authentication. If the
+   * Organization’s MFA policy is `REQUIRED_FOR_ALL`, this field will be ignored. If this field is not passed
+   * in, the Member’s `mfa_enrolled` boolean will not be affected. The options are:
+   *
+   *   `enroll` – sets the Member's `mfa_enrolled` boolean to `true`. The Member will be required to complete
+   * an MFA step upon subsequent logins to the Organization.
+   *
+   *   `unenroll` –  sets the Member's `mfa_enrolled` boolean to `false`. The Member will no longer be
+   * required to complete MFA steps when logging in to the Organization.
+   *
+   */
   set_mfa_enrollment?: string;
+  /**
+   * If passed will set the authenticated method to the default MFA method. Completing an MFA authentication
+   * flow for the first time for a Member will implicitly set the method to the default MFA method. This
+   * option can be used to update the default MFA method if multiple are being used.
+   */
   set_default_mfa?: boolean;
 }
 
+// Response type for `totps.authenticate`.
 export interface B2BTOTPsAuthenticateResponse {
+  /**
+   * Globally unique UUID that is returned with every API call. This value is important to log for debugging
+   * purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.
+   */
   request_id: string;
+  // Globally unique UUID that identifies a specific Member.
   member_id: string;
+  // The [Member object](https://stytch.com/docs/b2b/api/member-object)
   member: Member;
+  // The [Organization object](https://stytch.com/docs/b2b/api/organization-object).
   organization: Organization;
+  // A secret token for a given Stytch Session.
   session_token: string;
+  // The JSON Web Token (JWT) for a given Stytch Session.
   session_jwt: string;
+  /**
+   * The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g.
+   * 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.
+   */
   status_code: number;
+  // The [Session object](https://stytch.com/docs/b2b/api/session-object).
   member_session?: MemberSession;
 }
 
+// Request type for `totps.create`.
 export interface B2BTOTPsCreateRequest {
+  /**
+   * Globally unique UUID that identifies a specific Organization. The `organization_id` is critical to
+   * perform operations on an Organization, so be sure to preserve this value.
+   */
   organization_id: string;
+  /**
+   * Globally unique UUID that identifies a specific Member. The `member_id` is critical to perform
+   * operations on a Member, so be sure to preserve this value.
+   */
   member_id: string;
+  /**
+   * The expiration for the TOTP registration. If the newly created TOTP registration is not authenticated
+   * within this time frame the member will have to restart the registration flow. Defaults to 60 (1 hour)
+   * with a minimum of 5 and a maximum of 1440.
+   */
   expiration_minutes?: number;
+  intermediate_session_token?: string;
+  session_token?: string;
+  session_jwt?: string;
 }
 
+// Response type for `totps.create`.
 export interface B2BTOTPsCreateResponse {
+  /**
+   * Globally unique UUID that is returned with every API call. This value is important to log for debugging
+   * purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.
+   */
   request_id: string;
+  // Globally unique UUID that identifies a specific Member.
   member_id: string;
+  // The unique ID for a TOTP instance.
   totp_registration_id: string;
+  // The TOTP secret key shared between the authenticator app and the server used to generate TOTP codes.
   secret: string;
+  // The QR code image encoded in base64.
   qr_code: string;
+  // An array of recovery codes that can be used to recover a Member's account.
   recovery_codes: string[];
+  // The [Member object](https://stytch.com/docs/b2b/api/member-object)
   member: Member;
+  // The [Organization object](https://stytch.com/docs/b2b/api/organization-object).
   organization: Organization;
+  /**
+   * The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g.
+   * 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.
+   */
   status_code: number;
 }
 
+// Request type for `totps.migrate`.
 export interface B2BTOTPsMigrateRequest {
+  /**
+   * Globally unique UUID that identifies a specific Organization. The `organization_id` is critical to
+   * perform operations on an Organization, so be sure to preserve this value.
+   */
   organization_id: string;
+  /**
+   * Globally unique UUID that identifies a specific Member. The `member_id` is critical to perform
+   * operations on a Member, so be sure to preserve this value.
+   */
   member_id: string;
+  // The TOTP secret key shared between the authenticator app and the server used to generate TOTP codes.
   secret: string;
+  /**
+   * An existing set of recovery codes to be imported into Stytch to be used to authenticate in place of the
+   * secondary MFA method.
+   */
   recovery_codes: string[];
 }
 
+// Response type for `totps.migrate`.
 export interface B2BTOTPsMigrateResponse {
+  /**
+   * Globally unique UUID that is returned with every API call. This value is important to log for debugging
+   * purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.
+   */
   request_id: string;
+  // Globally unique UUID that identifies a specific Member.
   member_id: string;
+  // The [Member object](https://stytch.com/docs/b2b/api/member-object)
   member: Member;
+  // The [Organization object](https://stytch.com/docs/b2b/api/organization-object).
   organization: Organization;
+  // The unique ID for a TOTP instance.
   totp_registration_id: string;
+  // An array of recovery codes that can be used to recover a Member's account.
   recovery_codes: string[];
+  /**
+   * The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g.
+   * 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.
+   */
   status_code: number;
 }
 
@@ -77,6 +219,8 @@ export class TOTPs {
   }
 
   /**
+   * Create a new TOTP instance for a Member. The Member can use the authenticator application of their
+   * choice to scan the QR code or enter the secret.
    * @param data {@link B2BTOTPsCreateRequest}
    * @returns {@link B2BTOTPsCreateResponse}
    * @async
@@ -94,6 +238,7 @@ export class TOTPs {
   }
 
   /**
+   * Authenticate a Member provided TOTP.
    * @param data {@link B2BTOTPsAuthenticateRequest}
    * @returns {@link B2BTOTPsAuthenticateResponse}
    * @async
@@ -113,6 +258,8 @@ export class TOTPs {
   }
 
   /**
+   * Migrate an existing TOTP instance for a Member. Recovery codes are not required and will be minted for
+   * the Member if not provided.
    * @param data {@link B2BTOTPsMigrateRequest}
    * @returns {@link B2BTOTPsMigrateResponse}
    * @async

package.json

@@ -1,6 +1,6 @@
 {
   "name": "stytch",
-  "version": "10.2.0",
+  "version": "10.3.0",
   "description": "A wrapper for the Stytch API",
   "types": "./types/lib/index.d.ts",
   "main": "./dist/index.js",