# 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.