feat(auth): optionally sign in after signup (#118)

* feat(auth): optionally sign in after signup

* fix(auth): preserve signup session ownership

Author: swkeever

README.md

@@ -255,9 +255,19 @@ Pass a user ID to enforce that user's Row-Level Security policies. Omit
 The helper preserves libpq connection syntax, including hostless and multi-host
 targets, and leaves unrelated query values unchanged.
 
-`sign_up()` returns an immutable acknowledgement and never creates or replaces a session. The
-response is identical for new and existing email addresses. Call `sign_in()` separately after the
-account is ready to establish a session.
+`sign_up()` returns an immutable acknowledgement without changing the session by default.
+The signup acknowledgement is identical for new and existing email addresses. Pass
+`sign_in_when_allowed=True` to follow it with `sign_in()` only when confirmation is not required:
+
+```python
+result = client.auth.sign_up(
+    email="new-user@example.com", password="secret", sign_in_when_allowed=True
+)
+session = result.session  # None when no follow-up sign-in ran.
+```
+
+A successful follow-up stores the session and emits the normal sign-in event. A failed
+follow-up raises its usual typed error; it does not undo the successful signup.
 
 `get_session()` reads immutable local state. It does not refresh or validate the token.
 

src/volcano_sdk/auth.py

@@ -9,6 +9,7 @@
 import threading
 from collections.abc import Mapping
 from contextlib import suppress
+from dataclasses import replace
 from datetime import datetime
 from http import HTTPStatus
 from typing import TYPE_CHECKING, Literal, Protocol, TypeVar, cast
@@ -520,8 +521,10 @@ def sign_up(
         email: str,
         password: str,
         metadata: Mapping[str, object] | None = None,
+        sign_in_when_allowed: bool = False,
     ) -> SignUpResult:
-        """Create an account without creating or replacing a local session."""
+        """Sign up, optionally signing in when confirmation is not required."""
+        generation, _ = self._client._capture_session()
         transport = cast("AuthSignUpTransport", self._client._transport)
         response = invoke(
             transport.auth_signup,
@@ -530,7 +533,11 @@ def sign_up(
             password=password,
             metadata=dict(metadata or {}),
         )
-        return _sign_up_result_from_payload(response_payload(response, 201))
+        result = _sign_up_result_from_payload(response_payload(response, 201))
+        if sign_in_when_allowed and not result.confirmation_required:
+            session = self._sign_in_for_generation(email, password, generation)
+            return replace(result, session=session)
+        return result
 
     def sign_in_anonymously(
         self,
@@ -971,6 +978,13 @@ def update_user(
     def sign_in(self, *, email: str, password: str) -> Session:
         """Sign in a user and store the returned session."""
         generation, _ = self._client._capture_session()
+        return self._sign_in_for_generation(email, password, generation)
+
+    def _sign_in_for_generation(
+        self, email: str, password: str, generation: int
+    ) -> Session:
+        if self._client._capture_session()[0] != generation:
+            raise SessionChangedError
         response = invoke(
             self._client._transport.auth_signin,
             authorization=self._client._anon_token(),

src/volcano_sdk/models.py

@@ -159,10 +159,11 @@ class OAuthProviderTokenStatus:
 
 @dataclass(frozen=True, slots=True)
 class SignUpResult:
-    """Session-less acknowledgement returned after sign-up."""
+    """Sign-up acknowledgement with an optional follow-up sign-in session."""
 
     confirmation_required: bool
     message: str
+    session: Session | None = field(default=None, repr=False)
 
 
 @dataclass(frozen=True, slots=True)

tests/unit/test_state.py

@@ -168,6 +168,7 @@ def _linked_oauth_providers() -> AuthListOAuthProvidersResponse200:
 
 class StateTransport:
     on_signin: Callable[[], None] | None = None
+    on_signup: Callable[[], None] | None = None
 
     def __init__(self) -> None:
         self.next_access_token = "access-1"
@@ -343,6 +344,8 @@ def auth_signin(self, **kwargs: Any) -> Response:
     def auth_signup(self, **kwargs: Any) -> Response:
         self.authorizations.append(("signup", kwargs["authorization"]))
         self.signup_calls.append(kwargs)
+        if self.on_signup is not None:
+            self.on_signup()
         return self.signup_response
 
     def auth_signup_anonymous(self, **kwargs: Any) -> Response:
@@ -1181,6 +1184,75 @@ def test_sign_up_uses_empty_metadata_without_creating_a_session() -> None:
     assert transport.signup_calls[0]["metadata"] == {}
 
 
+@pytest.mark.parametrize("confirmation_required", [True, False])
+@pytest.mark.parametrize("sign_in_when_allowed", [True, False])
+def test_sign_up_only_signs_in_when_opted_in_and_allowed(
+    *, confirmation_required: bool, sign_in_when_allowed: bool
+) -> None:
+    transport = StateTransport()
+    transport.signup_response = Response(
+        201, {"confirmation_required": confirmation_required, "message": "Accepted"}
+    )
+    client = VolcanoClient(anon_key="anon", _transport=transport)
+    result = client.auth.sign_up(
+        email="new@example.com",
+        password="secret",
+        sign_in_when_allowed=sign_in_when_allowed,
+    )
+
+    signed_in = sign_in_when_allowed and not confirmation_required
+    assert (result.session is not None) is signed_in
+    assert result.session is client.auth.get_session()
+    assert result.confirmation_required is confirmation_required
+    assert result.message == "Accepted"
+    assert transport.authorizations == [("signup", "anon")] + (
+        [("auth", "anon")] if signed_in else []
+    )
+
+
+@pytest.mark.parametrize("replace_during", ["signup", "signin"])
+def test_signup_followup_does_not_replace_a_newer_session(replace_during: str) -> None:
+    transport = StateTransport()
+    transport.signup_response = Response(
+        201, {"confirmation_required": False, "message": "Accepted"}
+    )
+    client = VolcanoClient(anon_key="anon", _transport=transport)
+    replacement = Session("replacement", "refresh", "other")
+
+    def replace_session() -> None:
+        client.auth.set_session(replacement)
+
+    if replace_during == "signup":
+        transport.on_signup = replace_session
+    else:
+        transport.on_signin = replace_session
+    with pytest.raises(SessionChangedError):
+        client.auth.sign_up(
+            email="new@example.com", password="secret", sign_in_when_allowed=True
+        )
+    assert client.auth.get_session() == replacement
+
+
+def test_sign_up_surfaces_followup_signin_failure_without_changing_session() -> None:
+    transport = StateTransport()
+    client = VolcanoClient(anon_key="anon", _transport=transport)
+    established = client.auth.sign_in(email="user@example.com", password="secret")
+    transport.signup_response = Response(
+        201, {"confirmation_required": False, "message": "Accepted"}
+    )
+
+    def reject_signin() -> None:
+        message = "Sign-in rejected"
+        raise AuthenticationError(message)
+
+    transport.on_signin = reject_signin
+    with pytest.raises(AuthenticationError, match="Sign-in rejected"):
+        client.auth.sign_up(
+            email="new@example.com", password="secret", sign_in_when_allowed=True
+        )
+    assert client.auth.get_session() is established
+
+
 def test_sign_up_raises_typed_errors_without_changing_session() -> None:
     transport = StateTransport()
     client = VolcanoClient(anon_key="anon", _transport=transport)