From e48ffa67ee4544177d8dc980536c8906edec501e Mon Sep 17 00:00:00 2001
From: BilalG1 <bg2002@gmail.com>
Date: Tue, 16 Sep 2025 18:24:53 -0700
Subject: [PATCH] return to options (#898)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

<!--

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 eb748cbe7775eaba8d261d014951c4140d4bfe5c. 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](https://github.com/stack-auth/stack-auth/compare/2d2a6d7cd50a3fbc85520706b6c9c107e9b7906a...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>
---
 .../src/lib/stack-app/apps/implementations/client-app-impl.ts | 4 ++--
 .../template/src/lib/stack-app/apps/interfaces/client-app.ts  | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts b/packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts
index 1bff52a88..d5432dcb1 100644
--- a/packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts
+++ b/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(" "),
       },
diff --git a/packages/template/src/lib/stack-app/apps/interfaces/client-app.ts b/packages/template/src/lib/stack-app/apps/interfaces/client-app.ts
index 925548cc8..378f5ecc3 100644
--- a/packages/template/src/lib/stack-app/apps/interfaces/client-app.ts
+++ b/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"]>>,