mirror of
https://github.com/koala73/worldmonitor.git
synced 2026-04-25 17:14:57 +02:00
fcbb8bc0a1
* feat(proto): generate unified worldmonitor.openapi.yaml bundle Adds a third protoc-gen-openapiv3 invocation that merges every service into a single docs/api/worldmonitor.openapi.yaml spanning all 68 RPCs, using the new bundle support shipped in sebuf 0.11.0 (SebastienMelki/sebuf#158). Per-service YAML/JSON files are untouched and continue to back the Mintlify docs in docs/docs.json. The bundle runs with strategy: all and bundle_only=true so only the aggregate file is emitted, avoiding duplicate-output conflicts with the existing per-service generator. Requires protoc-gen-openapiv3 >= v0.11.0 locally: go install github.com/SebastienMelki/sebuf/cmd/protoc-gen-openapiv3@v0.11.0 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(proto): bump sebuf to v0.11.0 and document unified OpenAPI bundle - Makefile: SEBUF_VERSION v0.7.0 → v0.11.0 (required for bundle support). - proto/buf.gen.yaml: point bundle_server at https://api.worldmonitor.app. - CONTRIBUTING.md: new "OpenAPI Output" section covering per-service specs vs the unified worldmonitor.openapi.yaml bundle, plus a note that all three sebuf plugins must be installed from the pinned version. - AGENTS.md: clarify that `make generate` also produces the unified spec and requires sebuf v0.11.0. - CHANGELOG.md: Unreleased entry announcing the bundle and version bump. Also regenerates the bundle with the updated server URL. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(codegen): regenerate TS client/server with sebuf v0.11.0 Mechanical output of the bumped protoc-gen-ts-client and protoc-gen-ts-server. Two behavioral improvements roll in from sebuf: - Proto enum fields now use the proper `*_UNSPECIFIED` sentinel in default-value checks instead of the empty string, so generated query-string serializers correctly omit enum params only when they actually equal the proto default. - `repeated string` query params now serialize via `forEach(v => params.append(...))` instead of being coerced through `String(req.field)`, matching the existing `parseStringArray()` contract on the server side. All files also drop the `// @ts-nocheck` header that earlier sebuf versions emitted — 0.11.0 output type-checks cleanly under our tsconfig. No hand edits. Reproduce with `make install-plugins && make generate`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(proto): bump sebuf v0.11.0 → v0.11.1, realign tests with repeated-param wire format - Bump SEBUF_VERSION to v0.11.1, pulling in the OpenAPI fix for repeated scalar query params (SebastienMelki/sebuf#161). `repeated string` fields now emit `type: array` + `items.type: string` + `style: form` + `explode: true` instead of `type: string`, so SDK generators consuming the unified bundle produce correct array clients. - Regenerate all 12 OpenAPI specs (unified bundle + Aviation, Economic, Infrastructure, Market, Trade per-service). TS client/server codegen is byte-identical to v0.11.0 — only the OpenAPI emitter was out of sync. - Update three tests that asserted the pre-v0.11 comma-joined wire format (`symbols=AAPL,MSFT`) to match the current repeated-param form (`symbols=AAPL&symbols=MSFT`) produced by `params.append(...)`: - tests/market-service-symbol-casing.test.mjs (2 cases: getAll) - tests/stock-analysis-history.test.mts - tests/stock-backtest.test.mts Locally: test:data 6619/6619 pass, typecheck clean, lint exit 0. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Apply suggestions from code review Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
665 lines
27 KiB
YAML
665 lines
27 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: TradeService API
|
|
version: 1.0.0
|
|
paths:
|
|
/api/trade/v1/get-trade-restrictions:
|
|
get:
|
|
tags:
|
|
- TradeService
|
|
summary: GetTradeRestrictions
|
|
description: Get quantitative restrictions and export controls.
|
|
operationId: GetTradeRestrictions
|
|
parameters:
|
|
- name: countries
|
|
in: query
|
|
description: WTO member codes to filter by. Empty = all.
|
|
required: false
|
|
style: form
|
|
explode: true
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
- name: limit
|
|
in: query
|
|
description: Max results to return (server caps at 100).
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
format: int32
|
|
responses:
|
|
"200":
|
|
description: Successful response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GetTradeRestrictionsResponse'
|
|
"400":
|
|
description: Validation error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ValidationError'
|
|
default:
|
|
description: Error response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
/api/trade/v1/get-tariff-trends:
|
|
get:
|
|
tags:
|
|
- TradeService
|
|
summary: GetTariffTrends
|
|
description: Get tariff rate timeseries for a country pair.
|
|
operationId: GetTariffTrends
|
|
parameters:
|
|
- name: reporting_country
|
|
in: query
|
|
description: WTO member code of reporting country (e.g. "840" = US).
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: partner_country
|
|
in: query
|
|
description: WTO member code of partner country (e.g. "156" = China).
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: product_sector
|
|
in: query
|
|
description: Product sector filter (HS chapter). Empty = aggregate.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: years
|
|
in: query
|
|
description: Number of years to look back (default 10, max 30).
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
format: int32
|
|
responses:
|
|
"200":
|
|
description: Successful response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GetTariffTrendsResponse'
|
|
"400":
|
|
description: Validation error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ValidationError'
|
|
default:
|
|
description: Error response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
/api/trade/v1/get-trade-flows:
|
|
get:
|
|
tags:
|
|
- TradeService
|
|
summary: GetTradeFlows
|
|
description: Get bilateral merchandise trade flows.
|
|
operationId: GetTradeFlows
|
|
parameters:
|
|
- name: reporting_country
|
|
in: query
|
|
description: WTO member code of reporting country.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: partner_country
|
|
in: query
|
|
description: WTO member code of partner country.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: years
|
|
in: query
|
|
description: Number of years to look back (default 10, max 30).
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
format: int32
|
|
responses:
|
|
"200":
|
|
description: Successful response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GetTradeFlowsResponse'
|
|
"400":
|
|
description: Validation error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ValidationError'
|
|
default:
|
|
description: Error response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
/api/trade/v1/get-trade-barriers:
|
|
get:
|
|
tags:
|
|
- TradeService
|
|
summary: GetTradeBarriers
|
|
description: Get SPS/TBT barrier notifications.
|
|
operationId: GetTradeBarriers
|
|
parameters:
|
|
- name: countries
|
|
in: query
|
|
description: WTO member codes to filter by. Empty = all.
|
|
required: false
|
|
style: form
|
|
explode: true
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
- name: measure_type
|
|
in: query
|
|
description: 'Filter by measure type: "SPS", "TBT", or empty for both.'
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: limit
|
|
in: query
|
|
description: Max results to return (server caps at 100).
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
format: int32
|
|
responses:
|
|
"200":
|
|
description: Successful response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GetTradeBarriersResponse'
|
|
"400":
|
|
description: Validation error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ValidationError'
|
|
default:
|
|
description: Error response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
/api/trade/v1/get-customs-revenue:
|
|
get:
|
|
tags:
|
|
- TradeService
|
|
summary: GetCustomsRevenue
|
|
description: Get US customs duties revenue (Treasury MTS data, seeded by Railway).
|
|
operationId: GetCustomsRevenue
|
|
responses:
|
|
"200":
|
|
description: Successful response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GetCustomsRevenueResponse'
|
|
"400":
|
|
description: Validation error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ValidationError'
|
|
default:
|
|
description: Error response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
/api/trade/v1/list-comtrade-flows:
|
|
get:
|
|
tags:
|
|
- TradeService
|
|
summary: ListComtradeFlows
|
|
description: List UN Comtrade strategic commodity flows with anomaly detection.
|
|
operationId: ListComtradeFlows
|
|
parameters:
|
|
- name: reporter_code
|
|
in: query
|
|
description: UN Comtrade reporter code (e.g. "842" = US, "156" = China). Empty returns all reporters.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: cmd_code
|
|
in: query
|
|
description: HS commodity code (e.g. "2709" = crude oil). Empty returns all commodities.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- name: anomalies_only
|
|
in: query
|
|
description: If true, only return flows with a year-over-year change exceeding 30%.
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
responses:
|
|
"200":
|
|
description: Successful response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ListComtradeFlowsResponse'
|
|
"400":
|
|
description: Validation error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ValidationError'
|
|
default:
|
|
description: Error response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
components:
|
|
schemas:
|
|
Error:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
description: Error message (e.g., 'user not found', 'database connection failed')
|
|
description: Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize.
|
|
FieldViolation:
|
|
type: object
|
|
properties:
|
|
field:
|
|
type: string
|
|
description: The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key')
|
|
description:
|
|
type: string
|
|
description: Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing')
|
|
required:
|
|
- field
|
|
- description
|
|
description: FieldViolation describes a single validation error for a specific field.
|
|
ValidationError:
|
|
type: object
|
|
properties:
|
|
violations:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/FieldViolation'
|
|
description: List of validation violations
|
|
required:
|
|
- violations
|
|
description: ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong.
|
|
GetTradeRestrictionsRequest:
|
|
type: object
|
|
properties:
|
|
countries:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: WTO member codes to filter by. Empty = all.
|
|
limit:
|
|
type: integer
|
|
format: int32
|
|
description: Max results to return (server caps at 100).
|
|
description: Request for quantitative restriction data.
|
|
GetTradeRestrictionsResponse:
|
|
type: object
|
|
properties:
|
|
restrictions:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/TradeRestriction'
|
|
fetchedAt:
|
|
type: string
|
|
description: ISO 8601 timestamp when data was fetched from WTO.
|
|
upstreamUnavailable:
|
|
type: boolean
|
|
description: True if upstream fetch failed and results may be stale/empty.
|
|
description: Response containing trade restrictions and fetch metadata.
|
|
TradeRestriction:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique restriction identifier from WTO.
|
|
reportingCountry:
|
|
type: string
|
|
description: ISO 3166-1 alpha-3 or WTO member code of reporting country.
|
|
affectedCountry:
|
|
type: string
|
|
description: Country affected by the restriction.
|
|
productSector:
|
|
type: string
|
|
description: Product sector or HS chapter description.
|
|
measureType:
|
|
type: string
|
|
description: 'Measure classification: "QR", "EXPORT_BAN", "IMPORT_BAN", "LICENSING".'
|
|
description:
|
|
type: string
|
|
description: Human-readable description of the measure.
|
|
status:
|
|
type: string
|
|
description: 'Current status: "IN_FORCE", "TERMINATED", "NOTIFIED".'
|
|
notifiedAt:
|
|
type: string
|
|
description: ISO 8601 date when measure was notified.
|
|
sourceUrl:
|
|
type: string
|
|
description: WTO source document URL (must be http/https protocol).
|
|
description: Quantitative restriction or export control measure notified to WTO.
|
|
GetTariffTrendsRequest:
|
|
type: object
|
|
properties:
|
|
reportingCountry:
|
|
type: string
|
|
description: WTO member code of reporting country (e.g. "840" = US).
|
|
partnerCountry:
|
|
type: string
|
|
description: WTO member code of partner country (e.g. "156" = China).
|
|
productSector:
|
|
type: string
|
|
description: Product sector filter (HS chapter). Empty = aggregate.
|
|
years:
|
|
type: integer
|
|
format: int32
|
|
description: Number of years to look back (default 10, max 30).
|
|
description: Request for tariff timeseries data.
|
|
GetTariffTrendsResponse:
|
|
type: object
|
|
properties:
|
|
datapoints:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/TariffDataPoint'
|
|
fetchedAt:
|
|
type: string
|
|
description: ISO 8601 timestamp when data was fetched from WTO.
|
|
upstreamUnavailable:
|
|
type: boolean
|
|
description: True if upstream fetch failed and results may be stale/empty.
|
|
effectiveTariffRate:
|
|
$ref: '#/components/schemas/EffectiveTariffRate'
|
|
description: Response containing tariff trend datapoints.
|
|
TariffDataPoint:
|
|
type: object
|
|
properties:
|
|
reportingCountry:
|
|
type: string
|
|
description: WTO member code of reporting country.
|
|
partnerCountry:
|
|
type: string
|
|
description: WTO member code of partner country.
|
|
productSector:
|
|
type: string
|
|
description: Product sector or HS chapter.
|
|
year:
|
|
type: integer
|
|
format: int32
|
|
description: Year of observation.
|
|
tariffRate:
|
|
type: number
|
|
format: double
|
|
description: Applied MFN tariff rate (percentage).
|
|
boundRate:
|
|
type: number
|
|
format: double
|
|
description: WTO bound tariff rate (percentage).
|
|
indicatorCode:
|
|
type: string
|
|
description: WTO indicator code used for this datapoint.
|
|
description: Single tariff data point for a reporter-partner-product combination.
|
|
EffectiveTariffRate:
|
|
type: object
|
|
properties:
|
|
sourceName:
|
|
type: string
|
|
description: Source name for the effective-rate estimate.
|
|
sourceUrl:
|
|
type: string
|
|
description: Canonical source URL for the estimate/methodology.
|
|
observationPeriod:
|
|
type: string
|
|
description: Human-readable observation period (for example "December 2025").
|
|
updatedAt:
|
|
type: string
|
|
description: ISO 8601 date when the source page was last updated, if known.
|
|
tariffRate:
|
|
type: number
|
|
format: double
|
|
description: Effective tariff rate (percentage).
|
|
description: Current effective tariff estimate for countries with coverage beyond WTO MFN baselines.
|
|
GetTradeFlowsRequest:
|
|
type: object
|
|
properties:
|
|
reportingCountry:
|
|
type: string
|
|
description: WTO member code of reporting country.
|
|
partnerCountry:
|
|
type: string
|
|
description: WTO member code of partner country.
|
|
years:
|
|
type: integer
|
|
format: int32
|
|
description: Number of years to look back (default 10, max 30).
|
|
description: Request for bilateral trade flow data.
|
|
GetTradeFlowsResponse:
|
|
type: object
|
|
properties:
|
|
flows:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/TradeFlowRecord'
|
|
fetchedAt:
|
|
type: string
|
|
description: ISO 8601 timestamp when data was fetched from WTO.
|
|
upstreamUnavailable:
|
|
type: boolean
|
|
description: True if upstream fetch failed and results may be stale/empty.
|
|
description: Response containing trade flow records.
|
|
TradeFlowRecord:
|
|
type: object
|
|
properties:
|
|
reportingCountry:
|
|
type: string
|
|
description: WTO member code of reporting country.
|
|
partnerCountry:
|
|
type: string
|
|
description: WTO member code of partner country.
|
|
year:
|
|
type: integer
|
|
format: int32
|
|
description: Year of observation.
|
|
exportValueUsd:
|
|
type: number
|
|
format: double
|
|
description: Merchandise export value in millions USD.
|
|
importValueUsd:
|
|
type: number
|
|
format: double
|
|
description: Merchandise import value in millions USD.
|
|
yoyExportChange:
|
|
type: number
|
|
format: double
|
|
description: Year-over-year export change (percentage).
|
|
yoyImportChange:
|
|
type: number
|
|
format: double
|
|
description: Year-over-year import change (percentage).
|
|
productSector:
|
|
type: string
|
|
description: Product sector or HS chapter.
|
|
description: Bilateral trade flow record for a reporting-partner pair.
|
|
GetTradeBarriersRequest:
|
|
type: object
|
|
properties:
|
|
countries:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: WTO member codes to filter by. Empty = all.
|
|
measureType:
|
|
type: string
|
|
description: 'Filter by measure type: "SPS", "TBT", or empty for both.'
|
|
limit:
|
|
type: integer
|
|
format: int32
|
|
description: Max results to return (server caps at 100).
|
|
description: Request for SPS/TBT trade barrier notifications.
|
|
GetTradeBarriersResponse:
|
|
type: object
|
|
properties:
|
|
barriers:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/TradeBarrier'
|
|
fetchedAt:
|
|
type: string
|
|
description: ISO 8601 timestamp when data was fetched from WTO.
|
|
upstreamUnavailable:
|
|
type: boolean
|
|
description: True if upstream fetch failed and results may be stale/empty.
|
|
description: Response containing trade barrier notifications.
|
|
TradeBarrier:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique barrier notification identifier.
|
|
notifyingCountry:
|
|
type: string
|
|
description: Country that notified the measure.
|
|
title:
|
|
type: string
|
|
description: Title of the notification.
|
|
measureType:
|
|
type: string
|
|
description: 'Measure classification: "SPS" or "TBT".'
|
|
productDescription:
|
|
type: string
|
|
description: Product description or affected goods.
|
|
objective:
|
|
type: string
|
|
description: Stated objective of the measure.
|
|
status:
|
|
type: string
|
|
description: Status of the notification.
|
|
dateDistributed:
|
|
type: string
|
|
description: ISO 8601 date when notification was distributed.
|
|
sourceUrl:
|
|
type: string
|
|
description: WTO source document URL (must be http/https protocol).
|
|
description: SPS or TBT trade barrier notification.
|
|
GetCustomsRevenueRequest:
|
|
type: object
|
|
GetCustomsRevenueResponse:
|
|
type: object
|
|
properties:
|
|
months:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/CustomsRevenueMonth'
|
|
fetchedAt:
|
|
type: string
|
|
upstreamUnavailable:
|
|
type: boolean
|
|
CustomsRevenueMonth:
|
|
type: object
|
|
properties:
|
|
recordDate:
|
|
type: string
|
|
fiscalYear:
|
|
type: integer
|
|
format: int32
|
|
calendarYear:
|
|
type: integer
|
|
format: int32
|
|
calendarMonth:
|
|
type: integer
|
|
format: int32
|
|
monthlyAmountBillions:
|
|
type: number
|
|
format: double
|
|
fytdAmountBillions:
|
|
type: number
|
|
format: double
|
|
description: Monthly US customs duties revenue from Treasury MTS data.
|
|
ListComtradeFlowsRequest:
|
|
type: object
|
|
properties:
|
|
reporterCode:
|
|
type: string
|
|
description: UN Comtrade reporter code (e.g. "842" = US, "156" = China). Empty returns all reporters.
|
|
cmdCode:
|
|
type: string
|
|
description: HS commodity code (e.g. "2709" = crude oil). Empty returns all commodities.
|
|
anomaliesOnly:
|
|
type: boolean
|
|
description: If true, only return flows with a year-over-year change exceeding 30%.
|
|
description: ListComtradeFlowsRequest filters strategic commodity trade flows.
|
|
ListComtradeFlowsResponse:
|
|
type: object
|
|
properties:
|
|
flows:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ComtradeFlowRecord'
|
|
fetchedAt:
|
|
type: string
|
|
description: ISO 8601 timestamp when data was seeded.
|
|
upstreamUnavailable:
|
|
type: boolean
|
|
description: True if seeded data is missing or stale.
|
|
description: ListComtradeFlowsResponse contains strategic commodity trade flows.
|
|
ComtradeFlowRecord:
|
|
type: object
|
|
properties:
|
|
reporterCode:
|
|
type: string
|
|
description: UN Comtrade reporter code.
|
|
reporterName:
|
|
type: string
|
|
description: Reporter country name.
|
|
partnerCode:
|
|
type: string
|
|
description: Partner country code ("000" = world total).
|
|
partnerName:
|
|
type: string
|
|
description: Partner country name.
|
|
cmdCode:
|
|
type: string
|
|
description: HS commodity code.
|
|
cmdDesc:
|
|
type: string
|
|
description: Commodity description.
|
|
year:
|
|
type: integer
|
|
format: int32
|
|
description: Reporting year.
|
|
tradeValueUsd:
|
|
type: number
|
|
format: double
|
|
description: Trade value in USD.
|
|
netWeightKg:
|
|
type: number
|
|
format: double
|
|
description: Net weight in kg.
|
|
yoyChange:
|
|
type: number
|
|
format: double
|
|
description: Year-over-year change (ratio, e.g. 0.35 = +35%).
|
|
isAnomaly:
|
|
type: boolean
|
|
description: True if the YoY change exceeds the anomaly threshold (30%).
|
|
description: ComtradeFlowRecord is a single bilateral commodity flow record.
|