travel-promos-argentina

使用 Anduin Promos API 查看来自阿根廷的旅行促销。 当用户请求阿根廷的旅行促销、航班促销、 酒店或套餐、当天最优惠价格、巴西/美国/欧洲促销、 按分数或最新空中促销活动排名。

# Travel Promos Argentina

Consulta promociones de viajes (vuelos, hoteles y paquetes) y permite filtrarlas y ordenarlas localmente.

## API Overview

- **Base URL**: `https://anduin.ferminrp.com`
- **Auth**: None required
- **Response format**: JSON
- **Endpoint principal**: `/api/v1/promos`
- **OpenAPI**: `https://anduin.ferminrp.com/docs/openapi.json`
- **Fuente upstream**: `data.source`
- **Timestamps relevantes**:
  - `data.lastUpdated` (actualizacion de promos)
  - `timestamp` (respuesta del servicio)
- **Query params documentados para `/api/v1/promos`**: ninguno
- **Nota**: los query params probados (`category`, `destinationCountry`, `limit`, `q`) no filtran en origen; filtrar localmente con `jq` (verificado sobre la respuesta actual del endpoint).

## Endpoint

- `GET /api/v1/promos`

Ejemplos de uso:

```bash
curl -s "https://anduin.ferminrp.com/api/v1/promos" | jq '.'
curl -s "https://anduin.ferminrp.com/api/v1/promos" | jq '.data.promos[0:5]'
curl -s "https://anduin.ferminrp.com/api/v1/promos" | jq '.data.promos | map(select(.category == "vuelos"))'
curl -s "https://anduin.ferminrp.com/api/v1/promos" | jq '.data.promos | map(select(.category == "autos"))'
curl -s "https://anduin.ferminrp.com/api/v1/promos" | jq '.data.promos | map(select(.destinationCountry == "brazil"))'
curl -s "https://anduin.ferminrp.com/api/v1/promos" | jq '.data.promos | sort_by(.date) | reverse | .[0:10]'
curl -s "https://anduin.ferminrp.com/api/v1/promos" | jq '.data.promos | sort_by(-.score) | .[0:10]'
```

## Campos clave

- Top-level:
  - `success` (bool)
  - `timestamp` (ISO datetime)
- `data`:
  - `lastUpdated` (ISO datetime)
  - `source` (URL de origen)
  - `totalPromos` (int)
  - `promos` (array)
- `promos[]`:
  - `id`, `date`, `title`, `permalink`, `thumbnailUrl`
  - `destinationCountry` (puede ser `null`)
  - `category`
  - `score` (numerico para ranking, puede no venir si falla clasificacion AI)
- Valores dinamicos observados hoy (ejemplos, no lista cerrada):
  - `category`: `vuelos`, `hoteles`, `autos`, `paquetes`, `asistencia`, `otros`
  - `destinationCountry`: `brazil`, `united_states`, `spain`, `dominican_republic`, `aruba`, `mexico`, `japan`, `portugal`, `europe`, `null`
- Semantica adicional:
  - `permalink` se construye dinamicamente como `/links/viajes/:id` sobre el host de la request

## Workflow

1. Detectar intencion del usuario:
   - Listado general
   - Filtro por categoria o pais
   - Ranking por score
   - Ultimas promos
2. Consultar endpoint unico con `curl -s`.
3. Validar `success == true` y existencia de `data.promos`.
4. Aplicar filtros y orden localmente con `jq`:
   - Por `category`
   - Por `destinationCountry`
   - Por texto en `title` o `id` cuando aplique
   - Por `date` o `score`
5. Responder primero con snapshot:
   - Cantidad total (`totalPromos`)
   - `lastUpdated`
   - Top 3 promos por score o relevancia
6. Luego mostrar tabla corta (top 5/10):
   - `date | category | destinationCountry | score | title`
7. Incluir solo `permalink` para promos mostradas.
8. Mantener respuesta informativa, sin consejos financieros ni garantias de disponibilidad.

## Error Handling

- **HTTP no exitoso**:
  - Informar codigo HTTP y endpoint consultado.
- **404 (`No promos data available`)**:
  - Informar que no hay datos cacheados de promos en este momento.
- **`success: false`**:
  - Mostrar payload de error si existe.
- **JSON inesperado**:
  - Mostrar minimo crudo util y aclarar inconsistencia.
- **Red o timeout**:
  - Reintentar hasta 2 veces con espera corta.
- **`promos` vacio**:
  - Informar "no hay promociones disponibles actualmente".

## Presenting Results

- Formato por defecto:
  - Resumen ejecutivo + tabla corta
- Priorizar:
  - Recencia (`date`)
  - Relevancia (`score`)
  - Claridad de destino y categoria
- Aclarar timestamps (`lastUpdated` y/o `timestamp`) y la fuente externa (`data.source`).
- No emitir recomendaciones de compra; solo informar promociones disponibles.

## Out of Scope

Esta skill no debe hacer en v1:

- Scraping directo de sitios externos
- Automatizacion de reserva o compra
- Alertas push, notificaciones o tracking de cambios
- Uso de endpoints distintos de `/api/v1/promos`

---

## 中文说明

# 阿根廷旅行促销

查询旅行促销（机票、酒店和套餐），并允许在本地对其进行筛选和排序。

## API 概览

- **Base URL**：`https://anduin.ferminrp.com`
- **认证**：无需
- **响应格式**：JSON
- **主端点**：`/api/v1/promos`
- **OpenAPI**：`https://anduin.ferminrp.com/docs/openapi.json`
- **上游来源**：`data.source`
- **相关时间戳**：
  - `data.lastUpdated`（促销更新时间）
  - `timestamp`（服务响应时间）
- **`/api/v1/promos` 的已记录查询参数**：无
- **注意**：测试过的查询参数（`category`、`destinationCountry`、`limit`、`q`）不会在源端过滤；请用 `jq` 在本地过滤（已在端点当前响应上验证）。

## 端点

- `GET /api/v1/promos`

使用示例：

```bash
curl -s "https://anduin.ferminrp.com/api/v1/promos" | jq '.'
curl -s "https://anduin.ferminrp.com/api/v1/promos" | jq '.data.promos[0:5]'
curl -s "https://anduin.ferminrp.com/api/v1/promos" | jq '.data.promos | map(select(.category == "vuelos"))'
curl -s "https://anduin.ferminrp.com/api/v1/promos" | jq '.data.promos | map(select(.category == "autos"))'
curl -s "https://anduin.ferminrp.com/api/v1/promos" | jq '.data.promos | map(select(.destinationCountry == "brazil"))'
curl -s "https://anduin.ferminrp.com/api/v1/promos" | jq '.data.promos | sort_by(.date) | reverse | .[0:10]'
curl -s "https://anduin.ferminrp.com/api/v1/promos" | jq '.data.promos | sort_by(-.score) | .[0:10]'
```

## 关键字段

- 顶层：
  - `success` (bool)
  - `timestamp` (ISO datetime)
- `data`：
  - `lastUpdated` (ISO datetime)
  - `source`（来源 URL）
  - `totalPromos` (int)
  - `promos`（数组）
- `promos[]`：
  - `id`、`date`、`title`、`permalink`、`thumbnailUrl`
  - `destinationCountry`（可能为 `null`）
  - `category`
  - `score`（用于排名的数值，如果 AI 分类失败可能不会出现）
- 今日观察到的动态值（示例，非封闭列表）：
  - `category`：`vuelos`、`hoteles`、`autos`、`paquetes`、`asistencia`、`otros`
  - `destinationCountry`：`brazil`、`united_states`、`spain`、`dominican_republic`、`aruba`、`mexico`、`japan`、`portugal`、`europe`、`null`
- 附加语义：
  - `permalink` 基于请求的主机动态构建为 `/links/viajes/:id`

## 工作流

1. 检测用户意图：
   - 通用列表
   - 按类别或国家筛选
   - 按 score 排名
   - 最新促销
2. 用 `curl -s` 查询唯一端点。
3. 校验 `success == true` 以及 `data.promos` 是否存在。
4. 用 `jq` 在本地应用筛选和排序：
   - 按 `category`
   - 按 `destinationCountry`
   - 适用时按 `title` 或 `id` 中的文本
   - 按 `date` 或 `score`
5. 首先以快照响应：
   - 总数量（`totalPromos`）
   - `lastUpdated`
   - 按 score 或相关性排列的前 3 个促销
6. 然后显示简短表格（前 5/10 个）：
   - `date | category | destinationCountry | score | title`
7. 仅为所展示的促销包含 `permalink`。
8. 保持响应具有信息性，不提供财务建议，也不保证可用性。

## 错误处理

- **HTTP 不成功**：
  - 报告 HTTP 代码和所查询的端点。
- **404（`No promos data available`）**：
  - 告知此刻没有缓存的促销数据。
- **`success: false`**：
  - 如果存在则显示错误负载。
- **意外 JSON**：
  - 显示有用的最小化原始数据并阐明不一致。
- **网络或超时**：
  - 最多重试 2 次，带短暂等待。
- **`promos` 为空**：
  - 告知"目前没有可用的促销"。

## 呈现结果

- 默认格式：
  - 执行摘要 + 简短表格
- 优先考虑：
  - 时效性（`date`）
  - 相关性（`score`）
  - 目的地与类别的清晰度
- 阐明时间戳（`lastUpdated` 和/或 `timestamp`）以及外部来源（`data.source`）。
- 不发出购买建议；仅告知可用的促销。

## 范围之外

本技能在 v1 中不应做：

- 直接抓取外部网站
- 自动化预订或购买
- 推送警报、通知或变更追踪
- 使用 `/api/v1/promos` 以外的端点