first commit

docs/testkit/testing/testing-integration-oauth-mock/src/shapes/github.md

@@ -0,0 +1,61 @@
+# GitHub user shape
+
+## Purpose
+
+`buildGithubUser` produces a userinfo payload that closely mirrors the
+`GET https://api.github.com/user` response GitHub serves to OAuth apps.
+Adapters in the wider ecosystem (Better-Auth, next-auth, passport-github)
+read fields by their GitHub-canonical names — `id`, `login`,
+`avatar_url`, `node_id` — and this builder exists so those adapters can
+exercise their full mapping logic against the mock IdP without writing
+GitHub-specific assertions into every test.
+
+The default payload is opinionated enough to be useful straight out of
+the box while remaining trivial to override per call when a test needs
+particular id/login pairs to drive primary-key-style scenarios.
+
+## Features
+
+- Canonical GitHub field set: `id`, `login`, `email`, `avatar_url`,
+  `name`, `node_id`, `type: "User"`, `site_admin`.
+- String `id` coerced to number; falls back to `0` on unparseable input.
+- Explicit `null` name supported (org-style users).
+- Extra unknown claims preserved on the output object.
+- Frozen return value.
+
+## Usage: Basic
+
+```ts
+import { buildGithubUser } from "@suaveplan/testing-integration-oauth-mock/shapes";
+
+const u = buildGithubUser({ id: 1, login: "octocat" });
+```
+
+## Usage: Advanced
+
+Compose with the `primeUser` lever to drive role-based assertions:
+
+```ts
+import { createMockOauthIdp } from "@suaveplan/testing-integration-oauth-mock";
+
+const idp = await createMockOauthIdp({ userShape: "github" });
+idp.primeUser({ id: 9000, login: "ghost", site_admin: true });
+```
+
+## API Reference
+
+- `interface GithubUser` — canonical GitHub-shaped output.
+- `interface PrimedGithubInput` — partial caller input. Numeric or
+  string `id` accepted.
+- `function buildGithubUser(input?: PrimedGithubInput): GithubUser`.
+
+## Implementation Notes
+
+`id` is normalised to `number` because the GitHub adapter ecosystem
+treats it as the primary key — letting it be a `string` here would
+silently break downstream `===` checks. Unparseable string ids deliberately
+collapse to `0` rather than `NaN` so JSON serialisation remains lossless;
+tests that care about that edge can pass a number directly. `name` is
+left explicitly nullable to model GitHub's organisation-style accounts.
+The default `node_id` interpolation uses a recognisable static prefix so
+test failures involving node-id mismatches are easy to spot in diffs.