# Calendar Weekly Context API

API udostępnia derived payload kalendarzowy pod późniejsze użycie w zbiorczym payloadzie LLM.

To API:

- nie generuje summary tekstowych
- nie wywołuje LLM
- zwraca tylko dane z kalendarza i agregaty rule-based

## Endpoint

```text
/calendar/merged/api/weekly-context.php
```

## Tryby zapytania

### 1. Query po `week_iso`

```text
/calendar/merged/api/weekly-context.php?market=PL&week_iso=2026-W14
```

### 2. Query po dokładnym zakresie dat

```text
/calendar/merged/api/weekly-context.php?market=PL&date_from=2026-03-30&date_to=2026-04-05
```

## Parametry

### Wymagane

- `market`
  - kod rynku, np. `PL`, `CO`, `BA`, `GB`
  - alias `UK` jest akceptowany i normalizowany do `GB`

### Wariant A: tydzień ISO

- `week_iso`
  - format: `YYYY-Www`
  - przykład: `2026-W14`

### Wariant B: dokładny zakres

- `date_from`
  - format: `YYYY-MM-DD`
- `date_to`
  - format: `YYYY-MM-DD`

Zasady dla zakresu dat:

- `date_to >= date_from`
- obie daty muszą należeć do tego samego roku kalendarzowego

### Opcjonalne

- `save=1`
  - działa tylko dla wariantu `week_iso`
  - zapisuje payload do:
    - `data/calendar/weekly_llm_inputs/{MARKET}/{YEAR}/{WEEK_ISO}.json`
- `include`
  - opcjonalny filtr odpowiedzi
  - dozwolone wartości:
    - `all`
    - `flights`
    - `travel`
  - domyślnie: `all`

## Przykłady

### Week ISO

```bash
curl "https://news.netkam.online/calendar/merged/api/weekly-context.php?market=PL&week_iso=2026-W14"
```

### Week ISO + save

```bash
curl "https://news.netkam.online/calendar/merged/api/weekly-context.php?market=PL&week_iso=2026-W14&save=1"
```

### Exact range

```bash
curl "https://news.netkam.online/calendar/merged/api/weekly-context.php?market=PL&date_from=2026-03-30&date_to=2026-04-05"
```

### Flights only

```bash
curl "https://news.netkam.online/calendar/merged/api/weekly-context.php?market=PL&week_iso=2026-W14&include=flights"
```

### Travel only

```bash
curl "https://news.netkam.online/calendar/merged/api/weekly-context.php?market=PL&week_iso=2026-W14&include=travel"
```

## Response Shape

Top-level:

```json
{
  "market": "PL",
  "summary_scope": "week_market",
  "input_version": "weekly_llm_payload_v1",
  "schema_version": "weekly_calendar_context_v1",
  "generated_at": "2026-04-03T00:00:00Z",
  "week_iso": "2026-W14",
  "date_from": "2026-03-30",
  "date_to": "2026-04-05",
  "calendar_context": {},
  "commercial_calendar_context": null,
  "ads_context": null,
  "product_context": null,
  "sales_context": null,
  "pricing_context": null,
  "search_context": null,
  "supply_context": null,
  "confidence_inputs": {},
  "llm_constraints": {}
}
```

## `summary_scope`

Możliwe wartości:

- `week_market`
  - gdy zapytanie dotyczy pełnego tygodnia ISO
- `date_range_market`
  - gdy zapytanie dotyczy arbitralnego zakresu dat

## `include`

### `include=all`

Zwraca pełny payload.

### `include=flights`

Zostawia:

- metadane top-level
- minimalny kontekst eventów
- `commercial_calendar_context.payday.flights_signal` dla `UK`
- `product_impact.flights`
- `priority_events.flights`
- `aggregated_impacts.flights`
- `time_off`, `timing_effects` i podstawowy `travel_signal`, żeby nie stracić kontekstu lotniczego

### `include=travel`

Zostawia:

- metadane top-level
- `commercial_calendar_context.payday.travel_signal` dla `UK`
- `time_off`
- `travel_signal`
- `timing_effects`
- `week_flags`
- `time_off_summary`
- `dominant_patterns`

Pomija agregaty stricte produktowe.

## Błędy

### `invalid_market`

Brak parametru `market` albo nieobsługiwany kod rynku.

### `missing_range`

Brak:

- `week_iso`

oraz jednocześnie brak:

- `date_from`
- `date_to`

### `invalid_week_iso`

`week_iso` nie ma formatu `YYYY-Www`.

### `invalid_date_range`

Zakres dat jest niepoprawny:

- zły format
- `date_to < date_from`
- daty w różnych latach

### `invalid_include`

`include` nie jest jedną z dozwolonych wartości:

- `all`
- `flights`
- `travel`

## Implementacja

Endpoint:

- [weekly-context.php](/var/www/news.netkam.online/calendar/merged/api/weekly-context.php)

Builder:

- [weekly_calendar_context.php](/var/www/news.netkam.online/calendar/merged/lib/calendar/summary/weekly_calendar_context.php)

Preview UI:

- [weekly-contexts.php](/var/www/news.netkam.online/calendar/merged/weekly-contexts.php)