@axeptio/geo-compliance

ISO 3166-2 validation, country/subdivision group definitions, and CLDR-backed i18n for Axeptio's cookie-banner platform.

Status

Wave 1 complete — all five modules implemented and tested. 248 tests passing; CommonJS + ESM + types all build. Ready to be consumed by caas-api and caas-styleguide once the package is pushed to GitHub and added as a submodule.

Consumers

• caas-api (backend, Node): write-path validation, publish-time group expansion and specificity pre-computation, audit script.
• caas-styleguide (Admin Console, React/TS): GeoTargetField UI controls, validation, localized labels.

Not consumed by widget-client. The SDK reads pre-computed targets from the published config payload — it doesn't import this package. The SDK keeps its zero-new-dependency posture; bundle-size constraints (loaded on hundreds of thousands of sites) forbid centralizing runtime logic here.

Modules

| Module | Purpose | Status | |---|---|---| | defaults | Symbolic constants (locale list, viewer-unknown sentinel, placeholders, specificity scores). Each under non-regression test per in-a-box/CLAUDE.md. | ✅ 14 tests | | iso31662 | Country + subdivision validation (strict via membership; lenient via regex). | ✅ 66 tests | | groups | Country groups (EEA_UK_CH, EEA, EU) and subdivision groups (CCPA_STATES). Expansion + nesting precedence. | ✅ 55 tests | | target | GeoTarget discriminated union, matches, specificity, projectForPublish, overlap detection. | ✅ 54 tests | | i18n | Localized country (CLDR), subdivision (hand-authored for CA/US CCPA + iso-3166-2 fallback), group names (hand-authored). EN/FR/ES/IT/PT. | ✅ 59 tests |

Build

yarn install
yarn build         # CommonJS + ESM + types
yarn test          # jest, *.node-test.ts
yarn lint          # tsc --noEmit
yarn format:fix    # prettier

The prebuild step runs scripts/generate.mjs to regenerate CLDR-derived JSON committed to src/generated/.

Design principles

1. Strict on write, lenient on read. Reads of existing data never crash; writes enforce ISO 3166-2 membership. See in-a-box/CLAUDE.md "You may change non-conforming code only during refactoring."
2. Symbolic defaults. No magic numbers or string literals scattered through code; every constant lives in src/defaults.ts with a non-regression test.
3. Greenfield groups, no migration. Group definitions land in data/groups.supplemental.json; existing cookies docs never carried a group, so there's no data to migrate.
4. Domain separation. Geo only. Regulation (gdpr, ccpa, etc.) lives elsewhere — see the plan's "Relationship to regulation management" section.

Curated groups (MVP)

| Code | Kind | Members | Notes | |---|---|---|---| | EU | country | 27 ISO 3166-1 codes | EU member states. | | EEA | country | 30 codes | EU + IS, NO, LI. | | EEA_UK_CH | country | 32 codes | EEA + UK + CH. The Google CMP grouping. | | CCPA_STATES | subdivision | ISO 3166-2 codes under US-* | Membership flagged for legal review. |

Curated nesting precedence: smaller membership wins (EU > EEA > EEA_UK_CH).

Repository status

Stand-alone package. Once published, will be added as a git submodule under in-a-box/geo-compliance/ following the existing monorepo pattern.