# `route-translation`

## Purpose

Translation table mapping every entry in `PROVIDER_ROUTE_SURFACE` (the
canonical 9-route foundation surface) to the matching Better-Auth-native
sub-path. The wrapper presents the canonical names outward while Better-Auth
still drives the heavy lifting at its idiomatic paths
(`/sign-up/email`, `/sign-in/email`, `/oauth2/sign-in/:providerId`, ...).
Without this translation a host built on the foundation contracts would
need to know Better-Auth-specific URLs — which would defeat the purpose of
the abstract `auth.provider` capability.

## Features

- Single immutable map keyed by `ProviderRouteName`.
- Carries both `nativePath` and `nativeMethod` so the wrapper can rewrite
  the request method too (some translations flip GET → POST).
- `buildNativeUrl` helper rewrites the canonical request URL onto
  Better-Auth's base URL, resolving `:provider` / `:token` params and
  preserving the query string.

## Usage: Basic

```ts
import { ROUTE_TRANSLATION, buildNativeUrl } from "@suaveplan/api-auth-better-auth";

const target = ROUTE_TRANSLATION.login;
// → { nativePath: "/sign-in/email", nativeMethod: "POST" }

const url = buildNativeUrl({
    baseUrl: "https://api.example.com",
    nativePath: target.nativePath,
    params: {},
    search: "redirect=/home",
});
// → URL { https://api.example.com/sign-in/email?redirect=/home }
```

## Usage: Advanced

```ts
import { buildNativeUrl, ROUTE_TRANSLATION } from "@suaveplan/api-auth-better-auth";

// OAuth callback — the canonical `/oauth/:provider/callback?code=xxx&state=yyy`
// is rewritten to Better-Auth's `/oauth2/callback/:provider?...` surface.
const target = ROUTE_TRANSLATION["oauth.callback"];
const native = buildNativeUrl({
    baseUrl: "https://api.example.com",
    nativePath: target.nativePath,
    params: { provider: "github" },
    search: "code=xxx&state=yyy",
});
// → URL { https://api.example.com/oauth2/callback/github?code=xxx&state=yyy }
```

## API Reference

| Export | Shape | Purpose |
| ------ | ----- | ------- |
| `NativeRoute` | interface | `{ nativePath, nativeMethod }` |
| `ROUTE_TRANSLATION` | `Readonly<Record<ProviderRouteName, NativeRoute>>` | Canonical → native map |
| `buildNativeUrl(args)` | function | Rewrite the canonical URL onto Better-Auth's base URL |

## Implementation Notes

`Object.freeze` on the outer record + a `Readonly<...>` cast — but not on
the inner entries because each entry is already a frozen literal authored
inline. Decided against `as const` on the outer block so the indexed key
narrowing stays type-friendly under `noPropertyAccessFromIndexSignature`.
`buildNativeUrl` runs `:param` substitution before constructing the URL so
malformed param values can't break out of the path; `encodeURIComponent`
defends against `/` injection in the `:provider` slot. Query string
preservation is critical for OAuth — the entire upstream callback payload
(`code`, `state`, `scope`, …) needs to land on Better-Auth's handler verbatim.