CodeCow/stack
1
0
Fork 0
mirror of https://github.com/stack-auth/stack.git synced 2026-06-13 21:01:21 +08:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity
4db4885abb
stack/sdks/spec
History
Mantra 9d1eee8ab8
Add useCliAuthConfirmation hook and customizable cliAuthConfirm URL target (#1388) 
## Summary
- Extract CLI auth confirmation into a `useCliAuthConfirmation()` hook
(status / error / isLoading / authorize / retry) so custom pages don't
have to reimplement the protocol; `CliAuthConfirmation` now consumes the
hook.
- Make `cliAuthConfirm` a first-class handler URL target — resolved via
`resolveHandlerUrls`, customizable per project, and used by
`promptCliLogin` through a new `buildCliAuthConfirmUrl()` helper.
- Move `StackContext` to its own module so the hook can be unit-tested
with a test double without tripping the client-version sentinel;
register `cliAuthConfirm` in custom-page prompts and the dev-tool
components tab; export the hook + types from `@stackframe/stack`.

## Test plan
- [ ] `pnpm typecheck`
- [ ] `pnpm lint`
- [ ] `pnpm --filter @stackframe/stack test cli-auth-confirm
url-targets`
- [ ] Manually verify default `/handler/cli-auth-confirm` flow + a
project with a custom `cliAuthConfirm` URL

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

* **New Features**
* Adds a CLI authentication confirmation page with clear states
(invalid, authorizing, redirecting, success, error), retry action, and
flows for signed-in and anonymous users.
* CLI login URL generation now derives from the configured handler
target and app base, improving reliability.
* CLI confirmation page exposed in the components/dev UI for previewing.

* **Tests**
* End-to-end and unit tests covering confirmation behaviors and URL
generation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-04-28 15:29:46 -07:00
..
src Add useCliAuthConfirmation hook and customizable cliAuthConfirm URL target (#1388) 2026-04-28 15:29:46 -07:00
package.json chore: update package versions 2026-04-20 19:06:56 -07:00
README.md [Fix] [Feat] Update OAuth Sign-In and Get Token Functions to Work (#1130) 2026-01-28 02:17:27 +00:00

README.md

Stack Auth SDK Specification

This folder contains the specification for Stack Auth's SDKs.

When writing this specification, try to write imperative pseudocode as much as possible (be explicit about what things are named, etc.).

Notation

The spec files use the following notation:

Notation Meaning
[authenticated] Include access token, handle 401 refresh
[server-only] Requires secretServerKey
[BROWSER-LIKE] Requires browser or browser-like environment (browser, WebView, in-app browser). On mobile, open an in-app browser (ASWebAuthenticationSession on iOS, Custom Tabs on Android). On desktop, open the system browser with a registered URL scheme.
[BROWSER-ONLY] Strictly requires browser environment (DOM, window object)
[CLI-ONLY] Only in languages/platforms with an interactive terminal
[JS-ONLY] Only available in the JavaScript SDK
{ field, field } Request body (JSON)
"Does not error" Function handles errors internally
"Errors: ..." Lists possible errors with code/message

See _utilities.spec.md for more details.

Language Adaptation

The languages should adapt:

  • Naming conventions: camelCase (JS), snake_case (Python), PascalCase (Go), etc.
  • Async patterns: Promises (JS), async/await (Python), goroutines (Go)
  • Error handling: Exceptions vs Result types (language preference)
  • Parameter conventions: Objects vs. kwargs, etc.
  • Framework hooks: Eg. for React, add use* equivalents to get*/list* methods
  • Everything else, wherever it makes sense: Every language is unique and the patterns will differ. If you have to decide between what's idiomatic in a language vs. what was done in the Stack Auth SDK for other languages, use the idiomatic pattern.

Implementation Notes

Object Construction

When constructing SDK objects (User, Team, etc.) from API responses:

  1. Map naming conventions to your language's naming convention
  2. Objects should hold a reference to the SDK client for making API calls
  3. Objects can be mutable or immutable based on language conventions
  4. update() methods should update local properties after successful API call

Caching

Normal functions should not cache. Some frameworks, like React, have hooks that require caching; for these, require explicit guidance.

Pagination

Most list* methods support pagination:

  • Request with cursor and limit query params
  • Response includes pagination: { next_cursor?: string }
  • next_cursor is null or absent when no more pages
  • Default limit is typically 100
  • Note that not all backend APIs support pagination, and some just return all items at once.

Date/Time Formats

  • API uses milliseconds since epoch for timestamps (e.g., signed_up_at_millis)
  • Convert to your language's native Date/DateTime type