# Google Emulator (service host)

Create an instance:
curl -s -X POST https://google.emulators.dev/_emulate/instances
# Hosted deployments create instances lazily when the returned URL is first used. The instance URL is a capability: anyone who has it can read and modify the instance, so save the returned URLs. Never store real secrets in an emulator.
# The server generates an unguessable name. An optional {"instance":"<prefix>"} body adds a readable prefix.

Then use the returned providerBaseUrl / controlBaseUrl. Example below uses a sample instance.
# Google Emulator

Stateful Google OAuth, OpenID Connect, Gmail, Calendar, and Drive emulator.

Provider base URL: https://google.your-instance.emulators.dev
Control base URL: https://google.your-instance.emulators.dev/_emulate

Supported surfaces:
- REST API: partial at /
- OAuth 2.0 flow: supported at /o/oauth2/v2
- OpenID Connect: supported at /.well-known

Control endpoints:
- https://google.your-instance.emulators.dev/_emulate/manifest
- https://google.your-instance.emulators.dev/_emulate/coverage
- https://google.your-instance.emulators.dev/_emulate/connections
- https://google.your-instance.emulators.dev/_emulate/state
- https://google.your-instance.emulators.dev/_emulate/ledger
- https://google.your-instance.emulators.dev/_emulate/faults
- POST https://google.your-instance.emulators.dev/_emulate/credentials
- POST https://google.your-instance.emulators.dev/_emulate/seed
- POST https://google.your-instance.emulators.dev/_emulate/reset

Fault injection:
Arm a one-shot provider failure with a glob pathPattern, then inspect /ledger for faulted: true.
curl -s -X POST https://google.your-instance.emulators.dev/_emulate/faults \
  -H "content-type: application/json" \
  -d '{"match":{"method":"GET","pathPattern":"/v1/*"},"response":{"status":503,"body":{"error":"temporary"}}}'

Connect:

## googleapis (TypeScript)
import { google } from "googleapis";

const auth = new google.auth.OAuth2({
  clientId: "<client_id>",
  clientSecret: "<client_secret>",
});
auth.setCredentials({ access_token: "<token>" });

const gmail = google.gmail({
  version: "v1",
  auth,
  rootUrl: "https://google.your-instance.emulators.dev/",
});

const { data } = await gmail.users.messages.list({ userId: "me" });

## OpenID discovery (fetch)
const discovery = await fetch(
  "https://google.your-instance.emulators.dev/.well-known/openid-configuration",
).then((r) => r.json());

// discovery.authorization_endpoint, discovery.token_endpoint, etc.
const userinfo = await fetch(discovery.userinfo_endpoint, {
  headers: { authorization: "Bearer <token>" },
}).then((r) => r.json());

## Google API base URL (env)
GOOGLE_BASE_URL=https://google.your-instance.emulators.dev
GOOGLE_CLIENT_ID=<client_id>
GOOGLE_CLIENT_SECRET=<client_secret>
GOOGLE_ACCESS_TOKEN=<token>

## curl
curl -s https://google.your-instance.emulators.dev/gmail/v1/users/me/messages -H "authorization: Bearer <token>"

## Base URL (env)
GOOGLE_BASE_URL=https://google.your-instance.emulators.dev

## Create a credential
curl -s -X POST https://google.your-instance.emulators.dev/_emulate/credentials \
  -H "content-type: application/json" \
  -d '{"type":"oauth-authorization-code"}'

## Inspect requests
curl -s https://google.your-instance.emulators.dev/_emulate/ledger