first commit

docs/api-stack/api/api-auth-better-auth/src/provider/route-translation.md

@@ -0,0 +1,75 @@
+# `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.