62 lines
2.3 KiB
Markdown
62 lines
2.3 KiB
Markdown
# 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.
|