adobe / adobe/helix-shared

Create helix-shared-edge-geo for unified geo-detection APIs

Open
#1,164 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.