Inf-4: `get_country_shapes()` — fetch WB Official Boundaries parquet and return package-ready named sf list with hex grid

[EBukin]

What to build

The primary new exported function of the WB Boundaries infrastructure. get_country_shapes() fetches WB Official Boundary parquets from the WB Data Catalog, reconstructs sf geometry, runs validation, attaches the pre-computed H3 hex grid, and returns a fully package-ready named list — identical in shape to ukr_shp or rwa_shp — with no manual column renaming required.

This is the function that enables "client app in minutes": a deployer who knows an ISO-3 code can call one function and have a valid shapes.rds in seconds.

Signature

get_country_shapes(
  iso3,
  levels       = 0:2,
  level_names  = NULL,    # NULL → uses registry level_names; override with e.g. c("Country", "Province", "District")
  hex_resolution = 6L     # only resolution 6 supported in v1
)

What it does (end-to-end)

1. Validates iso3 against the bundled registry; errors with list_country_shapes() hint if not found
2. For each level in levels: reads wb_boundaries_admin{N}.parquet from WB Data Catalog using arrow::open_dataset() with predicate pushdown iso3 == <iso3> — only the target country rows are transferred
3. Reconstructs sf geometry: sf::st_as_sfc(geometry_col, crs = 4326)
4. Renames columns to package convention: pcod → admin<N>Pcod, name → admin<N>Name, attaches parent Pcod columns, ensures area column (from area_km2)
5. Assembles named list: admin0_<level_name>, admin1_<level_name>, admin2_<level_name> — names from registry level_names or level_names argument override
6. Fetches pre-computed hex parquet (wb_hex_r6/iso3={iso3}/data.parquet); attaches as admin9_Hexagon
7. Runs validate_geometries() internally; prints cli summary: "✔ 3 layers | 1 + 5 + 30 polygons + 507 hex cells | all geometries valid"
8. Returns the named list invisibly (also prints it so the user sees the structure)

Resulting 01-shapes.qmd pattern

# Option A — WB Official Boundaries (recommended for new deployments)
my_shp <- get_country_shapes(
  iso3        = "RWA",
  levels      = 0:2,
  level_names = c("Country", "Province", "District")
)
saveRDS(my_shp, "app-data/shapes.rds")

# Option B — custom boundaries (bring your own GeoJSON)
# [existing manual load + rename + spatial join code, commented out]

Dependencies

• arrow (already used in hex pipeline)
• sf, h3jsr (already present)
• No new Imports if these are already listed

Error handling

• Unknown iso3 → cli_abort() with suggestion to run list_country_shapes()
• Network failure → cli_abort() with message explaining this requires internet access and suggesting the custom-boundaries fallback (Option B in 01-shapes.qmd)
• Validation failure → surface validate_geometries() error with the structured result

Acceptance criteria

• get_country_shapes("RWA") returns a named list passing validate_geometries() with Rwanda admin0 + admin1 + admin2 + hex layers
• Column names match package convention (admin<N>Pcod, admin<N>Name, area, parent Pcods)
• admin9_Hexagon layer is present and has correct parent Pcod columns
• level_names argument overrides registry defaults
• Unknown iso3 errors with actionable message
• Offline network failure errors clearly and suggests fallback
• devtools::check() examples pass (use \dontrun{} for the live fetch)
• Unit tests mock the parquet fetch using a local fixture; test column names, geometry reconstruction, hex attachment

Blocked by

#145 (Inf-1) — parquets must exist on WB Data Catalog
#146 (Inf-2) — registry YAML must be present
#147 (Inf-3) — list_country_shapes() used in error messages