# Athena JS Auth SDK Bindings

This doc explains the auth binding map used in this repo and how it maps to Athena Auth HTTP routes.

## Scope and Base Path

All endpoint paths below are relative to your auth base path (`AuthConfig.base_path`).

Example:

- base path `/api/auth` + route `/sign-in/social` -> `/api/auth/sign-in/social`

Canonical namespace docs are split by unit under [`docs/auth/`](./auth/README.md).

Canonical raw map is [`sdk-api-bindings.md`](../sdk-api-bindings.md).

## SDK Surface Notes

There are two naming surfaces you may see:

1. The binding map in this repository (`createClient().auth...` style, see `sdk-api-bindings.md`)
2. The current `athena-js` typed auth client docs (`createAuthClient(...)` + namespaces like `auth.account.*`, `auth.signIn.*`, `auth.refresh.token()`)

Both target the same Athena Auth routes.

## Naming Normalization

Admin email template bindings are now documented in the nested namespace form:

- `createClient().auth.admin.email.template.create()`
- `createClient().auth.admin.email.template.delete()`
- `createClient().auth.admin.email.template.get()`
- `createClient().auth.admin.email.template.list()`
- `createClient().auth.admin.email.template.update()`

Route mappings are unchanged (`/admin/email-template/*`).

## Social/OAuth2 and Account Bindings

### `createClient().auth.social.link()` -> `POST /link-social`

- Purpose: Start provider linking flow for an already-authenticated user.
- Auth: session required.
- Body:
  - `provider: string` (required)
  - `callbackURL?: string`
  - `scopes?: string[]`
- Response: redirect payload with provider auth URL.
- Change: if `callbackURL` is present, it must already be registered through the admin OAuth client registry for the same provider; arbitrary callback URLs are rejected.

### `createClient().auth.account.list()` -> `GET /list-accounts`

- Purpose: List linked accounts for current user.
- Auth: session required.
- Response: array of linked accounts (provider, accountId, timestamps, scopes).

### `createClient().auth.deleteUser.callback()` -> `GET /delete-user/callback`

- Purpose: Confirm token-based delete flow callback.
- Auth: no session required; token proves intent.
- Query:
  - `token: string` (required)
- Response: success payload when deletion completes.

### `createClient().auth.account.unlink()` -> `POST /unlink-account`

- Purpose: Unlink provider from current user.
- Auth: session required.
- Body:
  - `providerId: string` (required)
- Response: `{ status: true }` on success.
- Guardrails: server blocks unlinking the last auth method unless configured to allow it.

### `createClient().auth.refreshToken()` -> `POST /refresh-token`

- Purpose: Refresh provider token for a linked OAuth account.
- Auth: session required.
- Body:
  - `providerId: string` (required)
- Response:
  - `accessToken?`
  - `accessTokenExpiresAt?`
  - `refreshToken?`
  - `scope?`

### `createClient().auth.getAccessToken()` -> `POST /get-access-token`

- Purpose: Fetch stored access token bundle for a linked provider account.
- Auth: session required.
- Body:
  - `providerId: string` (required)
- Response:
  - `accessToken?`
  - `accessTokenExpiresAt?`
  - `scope?`

### `createClient().auth.ok()` -> `GET /ok`

- Purpose: health/parity success endpoint.
- Auth: not required.
- Response: `{ ok: true }`.

### `createClient().auth.error()` -> `GET /error`

- Purpose: parity failure-shape endpoint.
- Auth: not required.
- Response: `{ ok: false }`.

## User-Level Sign-In/Sign-Up Bindings

### `createClient().auth.signIn.social()` -> `POST /sign-in/social`

- Purpose: start social sign-in OAuth flow.
- Body:
  - `provider: string` (required)
  - `callbackURL?: string`
  - `scopes?: string[]`
- Response: redirect payload (`{ url, redirect: true }`).
- Change: the request body did not add fields, but non-empty `callbackURL` values are now rejected unless they exactly match an active registered OAuth client entry for that provider.

## Admin OAuth Client Registry Bindings

### `createClient().auth.admin.oauthClient.create()` -> `POST /admin/oauth-client/create`

- Purpose: register an app-facing callback allowlist entry for social OAuth callers.
- Body:
  - `clientName: string` (required)
  - `provider: string` (required)
  - `redirectUris: string[]` (required, at least one)
  - `description?: string`
  - `responseType?: string`
  - `grantType?: string`
  - `tokenAuthenticationMethod?: string`
  - `clientUrl?: string`
  - `scopes?: string[]`
  - `isActive?: boolean`
  - `metadata?: object`

### `createClient().auth.admin.oauthClient.list()` -> `GET /admin/oauth-client/list`

- Purpose: inspect the current callback allowlist entries used by social OAuth.

## SDK Migration Notes

- If your SDK already sends `callbackURL` for `signIn.social()` or `social.link()`, no payload rename is needed.
- What changed is validation: those `callbackURL` values must now be pre-registered.
- If a typed SDK surface exposes admin helpers, it should add `admin.oauthClient.create()` and `admin.oauthClient.list()`.
- If a given SDK does not expose those helpers yet, it can still call the raw admin routes directly until the typed wrapper is added.

### `createClient().auth.signIn.email()` -> `POST /sign-in/email`

- Purpose: email/password sign-in.
- Body:
  - `email: string` (required)
  - `password: string` (required)
  - `callbackURL?: string`
  - `rememberMe?: boolean`
- Response: sign-in payload with token/session, or a 2FA redirect payload when enabled.

### `createClient().auth.signIn.username()` -> `POST /sign-in/username`

- Purpose: username/password sign-in.
- Body:
  - `username: string` (required)
  - `password: string` (required)
  - `rememberMe?: boolean`
- Response: same shape family as email sign-in (success or 2FA redirect).

### `createClient().auth.signUp.email()` -> `POST /sign-up/email`

- Purpose: user registration with email/password.
- Body:
  - `name: string` (required)
  - `email: string` (required)
  - `password: string` (required)
  - `username?: string`
  - `displayUsername?: string`
  - `callbackURL?: string`
- Response: sign-up payload; token/session presence depends on server `auto_sign_in` config.

## Mapping to Current `athena-js` Typed Auth Client

From Context7 docs (`/xylex-group/athena-js`), equivalent modern method names are:

| Binding map name | Current typed client equivalent |
|---|---|
| `auth.social.link()` | `auth.account.link(input)` |
| `auth.account.list()` | `auth.account.list()` |
| `auth.account.unlink()` | `auth.account.unlink(input)` |
| `auth.getAccessToken()` | `auth.account.token(input)` |
| `auth.refreshToken()` | `auth.refresh.token()` |
| `auth.signIn.social()` | `auth.signIn.social(input)` |
| `auth.signIn.email()` | `auth.signIn.email(input)` |
| `auth.signIn.username()` | `auth.signIn.username(input)` |
| `auth.signUp.email()` | `auth.signUp.email(input)` |

If you standardize one naming style across apps, keep this table as the compatibility map.
