{"_id":"@abdelamrah/geo-sdk","name":"@abdelamrah/geo-sdk","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@abdelamrah/geo-sdk","version":"1.0.0","description":"Headless geolocation SDK: geocoding, routing, address search via dependency injection","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./providers":{"types":"./dist/providers/index.d.ts","import":"./dist/providers/index.js"},"./package.json":"./package.json"},"repository":{"type":"git","url":"git+https://github.com/abdelaMrah/geo-sdk.git"},"bugs":{"url":"https://github.com/abdelaMrah/geo-sdk/issues"},"homepage":"https://github.com/abdelaMrah/geo-sdk#readme","publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.build.json","test":"vitest run","test:watch":"vitest","prepublishOnly":"npm run build"},"engines":{"node":">=18"},"peerDependencies":{"ioredis":">=5.0.0"},"peerDependenciesMeta":{"ioredis":{"optional":true}},"devDependencies":{"@types/node":"^22.10.0","ioredis":"^5.4.2","typescript":"^5.7.2","vitest":"^3.0.0"},"keywords":["geocoding","routing","osrm","nominatim","headless","typescript"],"license":"MIT","gitHead":"345134199762268cc99ed6ff2397ba99f4d8d0f0","_id":"@abdelamrah/geo-sdk@1.0.0","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-dJ3+KaCLGITb7jWqMZbpWvX3C/LJ6o13Gh+hpM8wa6IybXxmD/BBURnYkpRXibEuny7LTK0ztv1peHyPUENriw==","shasum":"9785be2605fb8157dff1182d05173ccafebddb2f","tarball":"https://registry.npmjs.org/@abdelamrah/geo-sdk/-/geo-sdk-1.0.0.tgz","fileCount":111,"unpackedSize":128927,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCCRTQWaOMia4rwshOGHO7y2iGbFjjkSCg4HvokuJ4nXgIgH9z3wqMSkPVE7IxhTSwI+ZYLoo0rAc4QCY9sOS1rHI0="}]},"_npmUser":{"name":"abdelamrah","email":"abdela.abdelamrah31@gmail.com"},"directories":{},"maintainers":[{"name":"abdelamrah","email":"abdela.abdelamrah31@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/geo-sdk_1.0.0_1777951280028_0.06720632531967352"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-05T03:21:19.867Z","1.0.0":"2026-05-05T03:21:20.227Z","modified":"2026-05-05T03:21:20.425Z"},"maintainers":[{"name":"abdelamrah","email":"abdela.abdelamrah31@gmail.com"}],"description":"Headless geolocation SDK: geocoding, routing, address search via dependency injection","homepage":"https://github.com/abdelaMrah/geo-sdk#readme","keywords":["geocoding","routing","osrm","nominatim","headless","typescript"],"repository":{"type":"git","url":"git+https://github.com/abdelaMrah/geo-sdk.git"},"bugs":{"url":"https://github.com/abdelaMrah/geo-sdk/issues"},"license":"MIT","readme":"# GeoEngine SDK (`@abdelamrah/geo-sdk`)\n\nSDK TypeScript **sans interface graphique** pour la géolocalisation : géocodage, géocodage inverse, itinéraires et suggestions d’adresses. Les données sont structurées en JSON ; aucune carte ni dépendance Leaflet / Mapbox / Google Maps.\n\n- **Injection de dépendances** : géocodeur, routeur et recherche sont des ports que vous implémentez ou fournissez via les adaptateurs de référence (Nominatim, OSRM).\n- **Cache optionnel** : mémoire, no-op ou Redis (`ioredis` en peer dependency optionnelle).\n- **Rate limiting HTTP partagé** : `RateLimitedFetchGate` pour sérialiser les appels et respecter une cadence (ex. 1 req/s).\n\n**Node.js ≥ 18** (fetch natif).\n\n## Installation\n\n```bash\nnpm install @abdelamrah/geo-sdk\n```\n\nPour le cache Redis ou la création automatique du client depuis une URL :\n\n```bash\nnpm install ioredis\n```\n\n## Usage rapide (composition manuelle)\n\n```ts\nimport { GeoEngine } from \"@abdelamrah/geo-sdk\";\nimport {\n  NominatimGeocoderProvider,\n  NominatimAddressSearchProvider,\n  OsrmRouterProvider,\n  RateLimitedFetchGate,\n} from \"@abdelamrah/geo-sdk/providers\";\n\nconst gate = new RateLimitedFetchGate({ minIntervalMs: 1000 });\nconst fetchLimited = gate.wrap(globalThis.fetch);\n\nconst geo = new GeoEngine({\n  geocoder: new NominatimGeocoderProvider({\n    baseUrl: \"https://nominatim.openstreetmap.org\",\n    fetch: fetchLimited,\n    headers: { \"User-Agent\": \"MonApp/1.0 (contact@example.com)\" },\n  }),\n  router: new OsrmRouterProvider({\n    baseUrl: \"https://router.project-osrm.org\",\n    fetch: fetchLimited,\n  }),\n  addressSearch: new NominatimAddressSearchProvider({\n    baseUrl: \"https://nominatim.openstreetmap.org\",\n    fetch: fetchLimited,\n    headers: { \"User-Agent\": \"MonApp/1.0 (contact@example.com)\" },\n  }),\n});\n\nawait geo.geocode(\"Oran Centre\");\nawait geo.reverseGeocode({ lat: 35.697, lng: -0.6337 });\nawait geo.route({ lng: x1, lat: y1 }, { lng: x2, lat: y2 });\nawait geo.searchAddresses(\"Or\");\n```\n\nSans `addressSearch`, `searchAddresses()` lève une erreur explicite (`ConfigurationError`). Utilisez `geo.hasAddressSearch()` pour tester la présence du port.\n\n## Variables d’environnement\n\n### Lecture complète depuis `process.env` ou Nest `ConfigService`\n\n```ts\nimport { createGeoEngineFromEnv } from \"@abdelamrah/geo-sdk\";\n\nconst { geo, disconnectRedis, config } = await createGeoEngineFromEnv({\n  configGet: (key) => configService.get<string>(key),\n});\n\nawait disconnectRedis?.(); // si Redis a été créé par la factory\n```\n\n### Surcharges camelCase (`redisUri`, URLs…) sans préfixe `GEO_ENGINE_*`\n\nPour mapper vos propres clés (`REDIS_URI`, etc.) :\n\n```ts\nimport { createGeoEngineFromInlineConfig } from \"@abdelamrah/geo-sdk\";\n\nconst { geo, disconnectRedis } = await createGeoEngineFromInlineConfig({\n  redisUri: configService.get<string>(\"REDIS_URI\"),\n  nominatimUrl: configService.get<string>(\"NOMINATIM_URL\"),\n  osrmUrl: configService.get<string>(\"OSRM_URL\"),\n  userAgent: configService.get<string>(\"APP_USER_AGENT\"),\n});\n```\n\n### Combinaison env + inline (Nest)\n\nLes champs présents dans `inline` remplacent la configuration déjà résolue depuis l’environnement :\n\n```ts\nawait createGeoEngineFromEnv({\n  configGet: (key) => configService.get<string>(key),\n  inline: {\n    redisUri: configService.get<string>(\"REDIS_URI\"),\n  },\n});\n```\n\n### Principales variables supportées (`GEO_ENGINE_*`)\n\n| Variable | Rôle |\n|----------|------|\n| `GEO_ENGINE_NOMINATIM_URL` | URL Nominatim (défaut instance publique) |\n| `GEO_ENGINE_OSRM_URL` | URL OSRM (défaut démo publique) |\n| `GEO_ENGINE_OSRM_PROFILE` | Profil routeur (ex. `driving`) |\n| `GEO_ENGINE_USER_AGENT` | Fortement recommandé pour Nominatim |\n| `GEO_ENGINE_NOMINATIM_EMAIL` | Politique / contact Nominatim |\n| `GEO_ENGINE_ENABLE_ADDRESS_SEARCH` | `true` / `false` (défaut `true`) |\n| `GEO_ENGINE_REDIS_URL` ou `REDIS_URL` | Cache Redis |\n| `GEO_ENGINE_REDIS_KEY_PREFIX` | Préfixe des clés |\n| `GEO_ENGINE_RATE_LIMIT_MS` | Intervalle minimal entre débuts de requêtes HTTP partagées (défaut `1000`, `0` = désactivé) |\n| `GEO_ENGINE_TTL_*_SECONDS` | TTL cache (`GEOCODE`, `REVERSE`, `ROUTE`, `SEARCH`) |\n\nUtilitaires : `parseGeoEngineEnv`, `mergeGeoEngineEnvFromGetter`, `GEO_ENGINE_ENV_KEYS`, `resolveGeoEngineInlineConfig`, `applyGeoEngineInlineOverrides`.\n\n## Imports\n\n- Point d’entrée principal : `@abdelamrah/geo-sdk`\n- Providers HTTP de référence : `@abdelamrah/geo-sdk/providers`\n\n## Adaptateurs cache\n\n- `NoOpCacheAdapter` — pas de cache\n- `MemoryCacheAdapter` — process unique / tests\n- `RedisCacheAdapter` — injectez un client compatible `RedisLikeClient`\n\nLes services utilisent une stratégie read-through sur les clés versionnées (`geo:v1:…`, hash SHA-256 des entrées normalisées).\n\n## Scripts (développement du package)\n\n```bash\nnpm run build\nnpm test\n```\n\n## Publier sur npm\n\n1. **Compte et scope**  \n   Le package est nommé `@abdelamrah/geo-sdk` (scope = ton compte npm `@abdelamrah`). Tu dois être connecté avec ce compte pour publier.\n\n2. **Connexion**\n\n   ```bash\n   npm login\n   npm whoami\n   ```\n\n3. **Vérifier le contenu du paquet**\n\n   ```bash\n   npm run build\n   npm pack --dry-run\n   ```\n\n4. **Publication**  \n   `publishConfig.access` est déjà réglé sur `public` pour un package scoped.\n\n   ```bash\n   npm publish\n   ```\n\n   Les versions suivantes : incrémente `version` dans `package.json` (ou `npm version patch|minor|major`) puis `npm publish`.\n\n5. **OTP (2FA)**  \n   Si l’auth à deux facteurs est activée : `npm publish --otp=CODE`.\n\n## Licence\n\nMIT — voir le fichier [LICENSE](LICENSE).\n","readmeFilename":"README.md","_rev":"1-e6703ed28da08e16a72cf4f2c6742308"}