{"_id":"@abdoseadaa/country-flags","name":"@abdoseadaa/country-flags","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@abdoseadaa/country-flags","version":"1.0.0","description":"TypeScript SDK for the Country Flags API — ISO country codes, flags, cities, and dialling codes.","type":"module","main":"./dist/index.cjs","module":"./dist/index.mjs","types":"./dist/index.d.mts","exports":{".":{"import":{"types":"./dist/index.d.mts","default":"./dist/index.mjs"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"scripts":{"build":"tsup && node -e \"require('fs').copyFileSync('dist/index.d.ts','dist/index.d.mts')\"","dev":"tsup --watch","typecheck":"tsc --noEmit"},"keywords":["iso","countries","flags","cities","phone-codes","sdk"],"author":{"name":"abdoseadaa"},"license":"MIT","devDependencies":{"tsup":"^8.0.0","typescript":"^5.5.0"},"engines":{"node":">=18"},"gitHead":"af1b66d0a964572d9dd1d5896518cd31083bfbe4","_id":"@abdoseadaa/country-flags@1.0.0","_nodeVersion":"22.20.0","_npmVersion":"11.10.1","dist":{"integrity":"sha512-7SKc6u129QFaiJX/pEws1zZ33fYM/hf3lmV+42Rg34iIss2S7t5pAgtUlTU6X6pUCLtMMIiPgex51FcrIZWp4A==","shasum":"58b1de23adf55d04476897caf7d6980d8d8c0a9d","tarball":"https://registry.npmjs.org/@abdoseadaa/country-flags/-/country-flags-1.0.0.tgz","fileCount":7,"unpackedSize":24281,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGeb3/hXu1fONtqhsKIMIpelW8SeGm4bLKB3o/QexVnSAiEAnhc9wg2KEdQtF196iaIdJgYSQlI3Em6G8SaqhVbE5os="}]},"_npmUser":{"name":"abdoseadaa","email":"abdom.seada@gmail.com"},"directories":{},"maintainers":[{"name":"abdoseadaa","email":"abdom.seada@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/country-flags_1.0.0_1780759194856_0.5181960131285448"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-06T15:19:54.689Z","1.0.0":"2026-06-06T15:19:54.970Z","modified":"2026-06-06T15:19:55.170Z"},"maintainers":[{"name":"abdoseadaa","email":"abdom.seada@gmail.com"}],"description":"TypeScript SDK for the Country Flags API — ISO country codes, flags, cities, and dialling codes.","keywords":["iso","countries","flags","cities","phone-codes","sdk"],"author":{"name":"abdoseadaa"},"license":"MIT","readme":"# @abdoseadaa/country-flags\n\nTypeScript SDK for the [Country Flags API](https://iso.api.gbstr.io) — ISO country codes, SVG flags, city data, and dialling codes.\n\n- Universal: works in **Node.js 18+** and modern **browsers**\n- Zero dependencies — uses the native `fetch` API\n- Dual ESM + CJS output with full TypeScript declarations\n- Default instance points to `https://iso.api.gbstr.io` — no config needed\n\n## Install\n\n```bash\nnpm install @abdoseadaa/country-flags\n```\n\n## Quick start\n\n```typescript\nimport ISO from '@abdoseadaa/country-flags';\n\n// List countries\nconst { data, total } = await ISO.getCountries({ search: 'egypt', limit: 5 });\n\n// Get a flag URL (sync — no HTTP call)\nconst url = ISO.getFlagUrl('EG');           // https://iso.api.gbstr.io/v1/flags/EG\n\n// Fetch SVG markup\nconst svg = await ISO.getFlagSvg('EG');\n\n// Cities for a country\nconst cities = await ISO.getCities('EG', { search: 'cairo' });\n\n// Countries with dialling codes + flag URLs\nconst phones = await ISO.getPhoneCodes();\n\n// Health check\nconst health = await ISO.getHealth();\n```\n\n## Custom base URL\n\nPoint to a self-hosted instance or local dev server:\n\n```typescript\nimport { CountryFlagsClient } from '@abdoseadaa/country-flags';\n\nconst client = new CountryFlagsClient({ baseUrl: 'http://localhost:54032' });\nconst { data } = await client.getCountries();\n```\n\n## API Reference\n\n### `ISO` (default export)\n\nAll methods are also available on `CountryFlagsClient` instances.\n\n---\n\n#### `ISO.getHealth()`\n\n```typescript\ngetHealth(): Promise<HealthResponse>\n```\n\nReturns server status and uptime.\n\n```typescript\nconst { status, uptime, timestamp } = await ISO.getHealth();\n```\n\n---\n\n#### `ISO.getCountries(params?)`\n\n```typescript\ngetCountries(params?: CountriesParams): Promise<ListResponse<Country>>\n```\n\n| Param | Type | Description |\n|-------|------|-------------|\n| `limit` | `number` | Max results to return (default: 20) |\n| `skip` | `number` | Results to skip for pagination (default: 0) |\n| `search` | `string` | Search by country name |\n| `region` | `string` | Filter by region (e.g. `\"Asia\"`, `\"Europe\"`) |\n\n```typescript\nconst { data, total } = await ISO.getCountries({ region: 'Europe', limit: 10 });\n```\n\n---\n\n#### `ISO.getFlagUrl(code, style?)`\n\n```typescript\ngetFlagUrl(code: string, style?: string): string\n```\n\n**Synchronous** — constructs and returns the flag URL without making an HTTP call.\n\n```typescript\nconst url = ISO.getFlagUrl('GB');         // https://iso.api.gbstr.io/v1/flags/GB\nconst flat = ISO.getFlagUrl('GB-ENG');   // sub-national flag\n```\n\n---\n\n#### `ISO.getFlagSvg(code, style?)`\n\n```typescript\ngetFlagSvg(code: string, style?: string): Promise<string>\n```\n\nFetches and returns the raw SVG markup for a flag.\n\n```typescript\nconst svg = await ISO.getFlagSvg('US');\ndocument.getElementById('flag')!.innerHTML = svg;\n```\n\n---\n\n#### `ISO.getCities(code, params?)`\n\n```typescript\ngetCities(code: string, params?: CitiesParams): Promise<ListResponse<City>>\n```\n\n| Param | Type | Description |\n|-------|------|-------------|\n| `limit` | `number` | Max results to return (default: 40) |\n| `skip` | `number` | Results to skip for pagination (default: 0) |\n| `search` | `string` | Search by city name |\n\n```typescript\nconst { data, total } = await ISO.getCities('DE', { search: 'berlin' });\n```\n\n---\n\n#### `ISO.getPhoneCodes()`\n\n```typescript\ngetPhoneCodes(): Promise<ListResponse<PhoneCode>>\n```\n\nReturns all countries that have a dialling code, sorted alphabetically. Each entry includes `flagUrl`.\n\n```typescript\nconst { data } = await ISO.getPhoneCodes();\n// data[0] → { code: 'AF', name: 'Afghanistan', callingCode: '+93', flagUrl: '...' }\n```\n\n---\n\n## Types\n\n```typescript\ntype CountryCode =\n  | 'AF' | 'AX' | 'AL' | 'DZ' | 'AS' | 'AD' | /* ... all 250+ codes */ | 'ZW';\n\ninterface Country {\n  code: CountryCode;\n  name: string;\n  region: string;\n  subregion: string;\n  callingCode: string | null;\n  capital: string | null;\n  currency: string | null;\n  languages: string[];\n  flagUrl: string;\n}\n\ninterface City {\n  name: string;\n  lat: number;\n  lng: number;\n  country: CountryCode;\n  admin1?: string;\n  admin2?: string;\n  population?: number;\n}\n\ninterface PhoneCode {\n  code: CountryCode;\n  name: string;\n  callingCode: string;\n  flagUrl: string;\n}\n\ninterface HealthResponse {\n  status: string;\n  uptime: number;\n  timestamp: string;\n}\n\ninterface ListResponse<T> {\n  data: T[];\n  total: number;\n}\n\ninterface CountriesParams {\n  limit?: number;\n  skip?: number;\n  search?: string;\n  region?: string;\n}\n\ninterface CitiesParams {\n  limit?: number;\n  skip?: number;\n  search?: string;\n}\n\ninterface ClientOptions {\n  baseUrl?: string;\n}\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-21f86dde0109e780e815d4a2d54a7679"}