google-service/README.md

# google-service

Node.js TypeScript sluzba pro komunikaci s Google API za AppFactory reverse proxy.

## Endpointy

- `GET /`
- `GET /health`
- `GET /docs`
- `GET /openapi.json`
- `GET /google/discovery/apis`
- `GET /google/discovery/apis/{api}/{version}/rest`
- `POST /google/oauth/token`
- `GET /google/oauth/scopes`
- `GET /google/oauth/authorize-url`
- `POST /google/oauth/service-account-token`
- `POST /google/oauth/revoke`
- `GET /google/oauth/tokeninfo`
- `GET|POST|PATCH|DELETE /google/calendar/...`
- `GET|POST|PUT /google/sheets/...`
- `POST /google/sheets/write-by-url`
- `GET|POST|PATCH|DELETE /google/drive/...`
- `GET|POST /google/gmail/...`
- `GET|POST /google/docs/...`
- `GET|POST /google/slides/...`
- `GET|POST /google/forms/...`
- `GET|POST|PATCH|DELETE /google/people/...`
- `GET|POST|PATCH|DELETE /google/tasks/...`
- `POST /google/request`

## Konfigurace

Volitelne environment variables:

- `ROOT_PATH` - verejny prefix za AppFactory proxy, napr. `/apps/google-service`
- `PORT` - port aplikace, vychozi hodnota je `3000`
- `GOOGLE_CLIENT_ID` a `GOOGLE_CLIENT_SECRET` - OAuth client pro authorization code a refresh token flow
- `GOOGLE_SERVICE_ACCOUNT_EMAIL`, `GOOGLE_PRIVATE_KEY`, `GOOGLE_SCOPES` - service account JWT flow
- `GOOGLE_API_KEY` - API key pro Google API, ktere ji podporuji

Secrets se nevraci v zadnem endpointu a neloguji se.

## Credentials ve Swaggeru

`GET /google/configuration` vraci prehled podporovanych env promennych a jejich request alternativ. Nevraci hodnoty secrets.

Env promenne lze nahradit primo v requestu:

- `GOOGLE_CLIENT_ID`: `clientId` nebo `X-Google-Client-Id`
- `GOOGLE_CLIENT_SECRET`: `clientSecret` nebo `X-Google-Client-Secret`
- `GOOGLE_REDIRECT_URI`: `redirectUri` nebo `X-Google-Redirect-Uri`
- `GOOGLE_SERVICE_ACCOUNT_EMAIL`: `serviceAccountEmail` nebo `X-Google-Service-Account-Email`
- `GOOGLE_PRIVATE_KEY`: `privateKey` nebo `X-Google-Private-Key`
- `GOOGLE_SCOPES`: `scope`, `scopes` nebo `X-Google-Scopes`
- `GOOGLE_ACCESS_TOKEN`: `Authorization: Bearer <token>`, `accessToken`, `accessTokenEnv`, `X-Google-Access-Token`, `X-Google-Access-Token-Env`
- `GOOGLE_API_KEY`: `apiKey`, `apiKeyEnv`, `X-Google-Api-Key`, `X-Google-Api-Key-Env`

## Obecne volani Google API

`POST /google/request` umi volat libovolny HTTPS endpoint na Google domene. Autorizace muze jit pres:

- `Authorization: Bearer <token>` header na requestu do sluzby
- `X-Google-Access-Token` header
- `X-Google-Access-Token-Env` header, napr. `GOOGLE_ACCESS_TOKEN`
- `X-Google-Api-Key` nebo `X-Google-Api-Key-Env` header
- `accessToken` v body
- `accessTokenEnv` v body, napr. `GOOGLE_ACCESS_TOKEN`
- `GOOGLE_API_KEY`, `apiKey` nebo `apiKeyEnv` pro endpointy podporujici API key

Priklad:

```json
{
  "method": "GET",
  "baseUrl": "https://www.googleapis.com",
  "path": "/drive/v3/files",
  "query": {
    "pageSize": 10
  },
  "accessTokenEnv": "GOOGLE_ACCESS_TOKEN"
}
```

## Konkretni Google API wrappery

Sluzba ma konkretni endpointy pro bezne Google produkty, aby klient nemusel skladat cilove Google URL sam:

- Calendar: kalendare, eventy, presun eventu
- Sheets: spreadsheet metadata, batch update, cteni hodnot, update hodnot, append, batch clear
- Drive: soubory, export, opravneni
- Gmail: profil, zpravy, odeslani zpravy, labels
- Docs: vytvoreni dokumentu, nacteni dokumentu, batch update
- Slides: vytvoreni prezentace, nacteni prezentace, batch update
- Forms: vytvoreni formulare, nacteni formulare, batch update, responses
- People: connections, kontakt, vytvoreni/uprava/smazani kontaktu
- Tasks: task lists, tasky, uprava/smazani tasku

Autorizace je stejna jako u obecne proxy: `Authorization: Bearer <token>`, pripadne `accessToken`, `accessTokenEnv`, `apiKey` nebo `apiKeyEnv` v JSON body.

Priklad vytvoreni udalosti:

```json
POST /google/calendar/calendars/primary/events
{
  "summary": "Schuzka",
  "start": {
    "dateTime": "2026-06-15T10:00:00+02:00"
  },
  "end": {
    "dateTime": "2026-06-15T11:00:00+02:00"
  }
}
```

Priklad append do Google Sheets:

```json
POST /google/sheets/spreadsheets/{spreadsheetId}/values/append?range=Sheet1!A1
{
  "majorDimension": "ROWS",
  "values": [
    ["A", "B", "C"]
  ]
}
```

Priklad zapisu do Google Sheets podle URL a nazvu listu:

```json
POST /google/sheets/write-by-url
{
  "spreadsheetUrl": "https://docs.google.com/spreadsheets/d/1abcDEFghiJKLmnopQRstuVWXyz/edit#gid=0",
  "sheetName": "Objednavky",
  "startCell": "A1",
  "mode": "append",
  "valueInputOption": "USER_ENTERED",
  "values": [
    ["Datum", "Zakaznik", "Castka"],
    ["2026-06-15", "ACME", 1234]
  ]
}
```

`mode=append` prida radky pod existujici data. `mode=update` prepise bunky od `startCell`.

## OAuth postup

1. Zavolej `GET /google/oauth/scopes` a vyber scopes podle sluzeb.
2. Zavolej `GET /google/oauth/authorize-url?redirectUri=<callback>&scopes=<scopes>`.
3. Otevri `authorizationUrl` z odpovedi v prohlizeci.
4. Google presmeruje na `redirectUri?code=...`.
5. Vymen code pres `POST /google/oauth/token`.
6. Access token posilej jako `Authorization: Bearer <access_token>`.

Priklad vymeny code:

```json
{
  "grantType": "authorization_code",
  "code": "code-from-google-redirect",
  "redirectUri": "https://example.test/oauth/callback"
}
```

## Kde vzit ID

- `calendarId`: `GET /google/calendar/calendars`, hlavni kalendar lze volat jako `primary`.
- `spreadsheetId`: `GET /google/sheets/spreadsheets`, hodnota je `files[].id`.
- `sheetId`: `GET /google/sheets/spreadsheets/{spreadsheetId}/sheets`, hodnota je `sheets[].properties.sheetId`.
- A1 range pro Sheets hodnoty: pouzij `sheets[].properties.title`, napr. `Sheet1!A1:B10`.
- `fileId`: `GET /google/drive/files`, hodnota je `files[].id`.
- `messageId`: `GET /google/gmail/messages`, hodnota je `messages[].id`.
- `documentId`, `presentationId`: u Docs/Slides jde o ID Drive souboru.