Adapter framework strategy: extract framework-agnostic client core (deferred) #64

Activity

1. Bccorb

   added

   enhancementNew feature or requestNew feature or request

   on Jul 19, 2026
2. Bccorb

   changed the title [-]Adapter framework strategy: extract framework-agnostic client-core[/-] [+]Adapter framework strategy: extract framework-agnostic client core (deferred)[/+] on Jul 19, 2026
3. Bccorb commented on Jul 19, 2026

   

   Bccorb

   on Jul 19, 2026

   ContributorAuthor

   More actions

   Re-scoped after a design review. The near-term actionable pieces are split out so this issue is not perpetually blocked on the large version:

   • Enforce framework-agnostic boundary in the client layer #76 enforce the framework-agnostic boundary by lint (cheap, do now, prerequisite)
   • isPlatformAuthenticatorAvailable throws during server-side rendering #77 fix the unguarded window access that blocks SSR
   • Add Next.js support #78 add Next.js support (does not depend on this issue, since Next.js is React and needs SSR safety rather than a new binding)

   The substantive change to this issue: the shared core is not primarily the HTTP client, which is already extraction-ready. It is the session state machine currently living in AuthProvider. The core should expose a framework-agnostic session store so Vue and Angular bindings cannot drift on auth state. Also noting that @seamless-auth/core is already taken by the server monorepo, so a client core needs a different name.
4. Bccorb commented on Jul 20, 2026

   

   Bccorb

   on Jul 20, 2026

   ContributorAuthor

   More actions

   Scan update, current as of the 0.5.0 release candidate. Two of the three prerequisites this issue named are now met:

   • The client layer is fully framework-agnostic and lint-enforced (Enforce framework-agnostic boundary in the client layer #76). Verified: nothing under src/client, src/fetchWithAuth.ts, src/scopedRoles.ts, or src/types.ts imports React or the router.
   • The return-shape convention is settled ([Feature]: Improve headless client ergonomics for custom UI consumers #24). All 41 request methods return SeamlessAuthResult, so adapters cannot each invent their own error handling.

   What still blocks the extraction is unchanged and is the part that actually needs design: the session state machine in AuthProvider is still React-only, and that is what Vue and Angular bindings would otherwise each reimplement and drift on.

   One newly surfaced dependency: #92 asks whether provider helpers should throw or return results. That answer propagates directly into whatever the extracted bindings expose, so it is worth settling before this work starts rather than during it.
5. Bccorb commented on Jul 29, 2026

   

   Bccorb

   on Jul 29, 2026

   ContributorAuthor

   More actions

   Decisions recorded, and phase 1 is open as #114.

   What is actually being extracted

   Confirming the re-scoped framing in the comment above: the HTTP client is not the hard part. src/client/*, src/fetchWithAuth.ts, src/scopedRoles.ts, and src/types.ts are already React-free and lint-enforced. The part a Vue composable and an Angular service would each reimplement, and drift on, is the session state machine in AuthProvider. That is what phase 1 moves.

   Both prerequisites named earlier are settled and this design inherits them: #24 fixed the client return shape, and #92 is closed with every provider helper returning a result. Nothing in the store throws.

   Decisions

   1. The store stays in this repo first, as src/session/, unexported. @seamless-auth/client gets published only once a second binding exists to validate the API. An API extracted against one consumer is a guess, and the second binding is what proves it. This also keeps Add Next.js support #78 unblocked.
   2. A failed session check no longer calls the logout endpoint. validateToken used to call logout() on any error, so a plain anonymous page load 401d on /users/me and then fired DELETE /logout for a session that does not exist. The store separates clearSession() (local) from logout() (network) and uses the former on a failed validation.
   3. Shared domain types move to @seamless-auth/types, which is the consolidation effort already underway across the other repos. No dependency is added here until that lands, so this issue does not block on it.
   4. hasSignedInBefore goes behind a SessionStoragePort, replacing the usePreviousSignIn hook. Browser, memory, and default implementations. The memory fallback is what makes the store safe to create during server-side rendering, which matters for Add Next.js support #78.

   Behaviors the extraction had to carry over

   Listing these because they are the parts that are easy to lose in a port, and they are now pinned by tests:

   • logout clears local state in a finally, so a server-side failure still leaves the UI signed out
   • updateCredential returns the credential itself, not the response wrapper
   • a failed refreshStepUpStatus clears the status to null, while a failed verification leaves it untouched
   • markSignedIn moved from a useEffect on user && isAuthenticated into the authenticated transition, so no binding has to remember to run it

   Two latent problems surfaced once the state left React and are fixed in #114: a slow session read could overwrite a newer one (switchOrganization, finishOAuthLogin, and handlePasskeyLogin all trigger a refresh, and React's batching hid the race), and snapshot references now stay stable so useSyncExternalStore cannot loop.

   Phasing

   • Phase 1 (refactor(session): move session state into a framework-agnostic store #114): the store plus the React rebinding. No public API change, so tests/authProvider.test.tsx is the contract.
   • Phase 2: direct store unit tests and documentation of the port contract. Largely covered by refactor(session): move session state into a framework-agnostic store #114 already (tests/authSession.test.ts, tests/sessionStorage.test.ts, and a node-environment SSR test).
   • Phase 3: workspace conversion and publishing @seamless-auth/client, when a second binding starts. That is packaging and CI work, not design.

   This issue stays open for phase 3.
6. Bccorb

   added a commit that references this issue on Jul 29, 2026

   refactor(session): move session state into a framework-agnostic store

   ...

   e27dcca
7. Bccorb

   added a commit that references this issue on Sep 13, 2026

   chore: split the client core into @seamless-auth/client as an npm wor…

   ...

   f8f0dfe
8. Bccorb commented on Sep 13, 2026

   

   Bccorb

   on Sep 13, 2026

   ContributorAuthor

   More actions

   Shipped in #149, with the second binding in #151. @seamless-auth/client 0.1.0 holds the framework-free client and the session store (createAuthSession: getState, subscribe, actions), @seamless-auth/react 0.13.0 is a useSyncExternalStore binding over it, and @seamless-auth/react-native 0.1.0 is the second adapter, built the way this issue describes. A Vue or Angular adapter is now a binding over the same store.
9. Bccorb

   closed this as completedon Sep 13, 2026