return to options (#898)

<!--

Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md

-->

<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR adds an optional `returnTo` parameter to the `signInWithOAuth`
function in the Stack Auth SDK. This allows developers to specify a
custom redirect URL after OAuth authentication instead of always using
the default OAuth callback URL. The change updates both the interface
definition and the implementation to support this new optional
parameter.

⏱️ Estimated Review Time: 0h 15m

<details>
<summary>💡 Review Order Suggestion</summary>

| Order | File Path |
|-------|-----------|
| 1 |
`packages/template/src/lib/stack-app/apps/interfaces/client-app.ts` |
| 2 |
`packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts`
|
</details>



<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->

----

> [!IMPORTANT]
> Add optional `returnTo` parameter to `signInWithOAuth` for custom
redirect URLs in `client-app-impl.ts` and update interface in
`client-app.ts`.
> 
>   - **Behavior**:
> - `signInWithOAuth` in `client-app-impl.ts` now accepts an optional
`options` parameter with `returnTo` for custom redirect URLs.
> - Default redirect URL is `this.urls.oauthCallback` if `returnTo` is
not provided.
>   - **Interfaces**:
> - Updated `signInWithOAuth` signature in `client-app.ts` to include
optional `options` parameter with `returnTo`.
> 
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for eb748cb. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>

<!-- ELLIPSIS_HIDDEN -->

<!-- RECURSEML_ANALYSIS:START -->
## Review by RecurseML

_🔍 Review performed on
[2d2a6d7..eb748cb](2d2a6d7...eb748cbe7775eaba8d261d014951c4140d4bfe5c)_

✨ No bugs found, your code is sparkling clean

<details>
<summary>✅ Files analyzed, no issues (2)</summary>

•
`packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts`
  • `packages/template/src/lib/stack-app/apps/interfaces/client-app.ts`
</details>

[![Need help? Join our
Discord](https://img.shields.io/badge/Need%20help%3F%20Join%20our%20Discord-5865F2?style=plastic&logo=discord&logoColor=white)](https://discord.gg/n3SsVDAW6U)
<!-- RECURSEML_ANALYSIS:END -->

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* signInWithOAuth now accepts an optional options parameter with
returnTo, allowing apps to override the post-login redirect URL.
* Defaults remain unchanged; if returnTo isn’t provided, the existing
OAuth callback is used.
* Backwards compatible: existing calls without options continue to work.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>

Author: BilalG1

packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts

@@ -1597,7 +1597,7 @@ export class _StackClientAppImplIncomplete<HasTokenStore extends boolean, Projec
     return res;
   }
 
-  async signInWithOAuth(provider: ProviderType) {
+  async signInWithOAuth(provider: ProviderType, options?: { returnTo?: string }) {
     if (typeof window === "undefined") {
       throw new Error("signInWithOAuth can currently only be called in a browser environment");
     }
@@ -1608,7 +1608,7 @@ export class _StackClientAppImplIncomplete<HasTokenStore extends boolean, Projec
       this._interface,
       {
         provider,
-        redirectUrl: this.urls.oauthCallback,
+        redirectUrl: options?.returnTo ?? this.urls.oauthCallback,
         errorRedirectUrl: this.urls.error,
         providerScope: this._oauthScopesOnSignIn[provider]?.join(" "),
       },

packages/template/src/lib/stack-app/apps/interfaces/client-app.ts

@@ -38,7 +38,7 @@ export type StackClientApp<HasTokenStore extends boolean = boolean, ProjectId ex
 
     readonly urls: Readonly<HandlerUrls>,
 
-    signInWithOAuth(provider: string): Promise<void>,
+    signInWithOAuth(provider: string, options?: { returnTo?: string }): Promise<void>,
     signInWithCredential(options: { email: string, password: string, noRedirect?: boolean }): Promise<Result<undefined, KnownErrors["EmailPasswordMismatch"] | KnownErrors["InvalidTotpCode"]>>,
     signUpWithCredential(options: { email: string, password: string, noRedirect?: boolean, verificationCallbackUrl?: string }): Promise<Result<undefined, KnownErrors["UserWithEmailAlreadyExists"] | KnownErrors["PasswordRequirementsNotMet"]>>,
     signInWithPasskey(): Promise<Result<undefined, KnownErrors["PasskeyAuthenticationFailed"]| KnownErrors["InvalidTotpCode"] | KnownErrors["PasskeyWebAuthnError"]>>,