Docs and/or SDK Clarification

[devjmetivier]

Our apps span multiple channels, each managing sessions with Stytch differently after authenticating through a central API. During authentication, user metadata may change, requiring session re-authentication to refresh Stytch user details.

We initially tried re-authenticating with session_jwt, but this does not return a new session_token — which makes sense per the docs. The correct approach is to pass a session_token, which returns both a new token and JWT.

However, the code in this repo doesn’t make that behavior obvious; you need to piece it together from the docs.

stytch-node/types/lib/b2c/sessions.d.ts

Lines 738 to 755 in 52f99b4

	/**
	* Authenticate a session token or session JWT and retrieve associated session data. If
	* `session_duration_minutes` is included, update the lifetime of the session to be that many minutes from
	* now. All timestamps are formatted according to the RFC 3339 standard and are expressed in UTC, e.g.
	* `2021-12-29T12:33:09Z`. This endpoint requires exactly one `session_jwt` or `session_token` as part of
	* the request. If both are included, you will receive a `too_many_session_arguments` error.
	*
	* You may provide a JWT that needs to be refreshed and is expired according to its `exp` claim. A new JWT
	* will be returned if both the signature and the underlying Session are still valid. See our
	* [How to use Stytch Session JWTs](https://stytch.com/docs/guides/sessions/using-jwts) guide for more
	* information.
	* @param data {@link SessionsAuthenticateRequest}
	* @returns {@link SessionsAuthenticateResponse}
	* @async
	* @throws A {@link StytchError} on a non-2xx response from the Stytch API
	* @throws A {@link RequestError} when the Stytch API cannot be reached
	*/
	authenticate(data: SessionsAuthenticateRequest): Promise<SessionsAuthenticateResponse>;

So the ask is that this language be changed to describe this behavior for others who may run into a similar case described above? Here would be my suggested edit:

/**
* Authenticate a session token or session JWT and retrieve associated session data. If
* `session_duration_minutes` is included, update the lifetime of the session to be that many minutes from
* now. All timestamps are formatted according to the RFC 3339 standard and are expressed in UTC, e.g.
* `2021-12-29T12:33:09Z`. This endpoint requires exactly one `session_jwt` or `session_token` as part of
* the request. If both are included, you will receive a `too_many_session_arguments` error.
*
* You may provide a JWT that needs to be refreshed and is expired according to its `exp` claim. A new JWT
* will be returned if both the signature and the underlying Session are still valid. See our
* [How to use Stytch Session JWTs](https://stytch.com/docs/guides/sessions/using-jwts) guide for more
* information.
*
* Note: Passing a `session_jwt` returns only a refreshed JWT. Passing a `session_token` returns both a new
* session token and a new JWT.
*
* @param data {@link SessionsAuthenticateRequest}
* @returns {@link SessionsAuthenticateResponse}
* @async
* @throws A {@link StytchError} on a non-2xx response from the Stytch API
* @throws A {@link RequestError} when the Stytch API cannot be reached
*/