Create helix-shared-edge-geo for unified geo-detection APIs
- Dominant language
- JavaScript
- Stars
- 15
- Forks
- 16
- Avg merge
- 23h 18m
- Merged PRs (30d)
- 14
Description
## Background
PR [#77](https://github.com/adobe/helix-deploy-plugin-edge/pull/77) documents API differences between Fastly Compute and Cloudflare Workers. [Comment](https://github.com/adobe/helix-deploy-plugin-edge/pull/77#issuecomment-3554569809) identifies `helix-shared-edge-geo` as a needed wrapper/plugin for unifying geo-detection APIs.
## Problem
Fastly and Cloudflare expose geolocation differently:
**Fastly**: `getGeolocationForIpAddress(ip)` returns object with properties like `country_code`, `latitude` (number), `as_number`
**Cloudflare**: `request.cf` object with properties like `country`, `latitude` (string), `asn`
Key differences:
- Access pattern (function vs object property)
- IP lookup (explicit vs automatic request IP only)
- Property naming (`country_code` vs `country`, `as_number` vs `asn`)
- Type inconsistencies (numbers vs strings for coordinates)
## Proposal
Create `@adobe/helix-shared-edge-geo` package that:
1. Provides unified interface for geolocation data
2. Normalizes property names and types across platforms
3. Handles platform-specific constraints (Cloudflare only supports request IP, Fastly supports arbitrary IP lookup)
4. Returns consistent null values for missing data
## API Surface
```javascript
interface UnifiedGeolocation {
country: string | null;
countryCode: string | null;
city: string | null;
region: string | null;
regionCode: string | null;
continent: string | null;
postalCode: string | null;
latitude: number | null;
longitude: number | null;
timezone: string | null;
metroCode: string | null;
asn: number | null;
asOrganization: string | null;
}
```
## Implementation
Follow helix-universal adapter pattern from [PR #426](https://github.com/adobe/helix-universal/pull/426). Export geo adapter that wraps platform-specific APIs and normalizes output.
## Reference
Full API analysis: [environment-geo.md](https://github.com/adobe/helix-deploy-plugin-edge/blob/compat/docs/api-unification/environment-geo.md)
Contributor guide
Research direction
Start by reading docs/api-unification/environment-geo.md and the helix-universal adapter pattern referenced from PR #426, then compare the Fastly and Cloudflare APIs described here. Done means creating @adobe/helix-shared-edge-geo with the proposed unified interface, normalized names and types, platform-specific constraints, and consistent null values.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- api, backend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100