nobetci-eczane-api 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mehmet Erdoğan (eczaneler.org)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+# 💊 Nöbetçi Eczane API (SDK)
+
+Türkiye ve KKTC genelindeki tüm güncel nöbetçi eczane verilerine, il/ilçe sorgularına ve konum (enlem/boylam) bazlı en yakın eczane lokasyonlarına programatik erişim sağlayan resmi **TypeScript & JavaScript** istemcisi.
+
+[![npm version](https://img.shields.io/npm/v/nobetci-eczane-api.svg?style=flat-square&color=dc2626)](https://www.npmjs.com/package/nobetci-eczane-api)
+[![license](https://img.shields.io/npm/l/nobetci-eczane-api.svg?style=flat-square)](https://github.com/mehmeterdogan/nobetci-eczane-api/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-success.svg?style=flat-square)](https://bundlephobia.com/package/nobetci-eczane-api)
+
+---
+
+## ✨ Özellikler
+
+* 🛡️ **%100 Tip Güvenliği:** TypeScript ile yazılmıştır. Tam otomatik tamamlama ve tip referansı.
+* 🚀 **Sıfır Dış Bağımlılık (0 Dependency):** Yerel `fetch` kullanır; bundle boyutunu şişirmez (< 8 KB).
+* 🌐 **Evrensel (Universal/Isomorphic):** Node.js 18+, Next.js (App Router & Pages Router), React, Vue, Svelte, Cloudflare Workers ve Edge Runtime uyumlu.
+* 🔄 **Hem ESM Hem CommonJS:** `import` ve `require()` desteği.
+* 📍 **Konum Bazlı Mesafe Hesabı:** Harita ve navigasyon entegrasyonu için optimize koordinat ve mesafe desteği.
+* ⚡ **Akıllı Önbellek & Yüksek Hız:** Milisaniye seviyesinde yanıt süreleri.
+
+---
+
+## 📦 Kurulum
+
+```bash
+# npm ile
+npm install nobetci-eczane-api
+
+# yarn ile
+yarn add nobetci-eczane-api
+
+# pnpm ile
+pnpm add nobetci-eczane-api
+```
+
+---
+
+## 🔑 Hızlı Başlangıç
+
+API anahtarınızı [Eczaneler.ORG](https://eczaneler.org/nobetci-eczane-api) üzerinden veya Telegram ([@mehmeterdogannet](https://t.me/mehmeterdogannet)) üzerinden ücretsiz test anahtarı alarak temin edebilirsiniz.
+
+### TypeScript / ES Modules (Next.js, Vite, Node 18+)
+
+```typescript
+import { EczaneAPI } from 'nobetci-eczane-api';
+
+const api = new EczaneAPI({
+  apiKey: process.env.ECZANE_API_KEY!
+});
+
+async function main() {
+  // 1. İstanbul'daki (34) nöbetçi eczaneleri çek
+  const { data: istanbulNobetciler } = await api.getSentryByCity(34, { limit: 25 });
+  console.log('İstanbul Nöbetçi Eczaneleri:', istanbulNobetciler);
+
+  // 2. Kadıköy'deki (440) nöbetçi eczaneleri çek
+  const { data: kadikoyNobetciler } = await api.getSentryByDistrict(34, 440);
+  console.log('Kadıköy Nöbetçi Eczaneleri:', kadikoyNobetciler);
+
+  // 3. Konumuma en yakın 5 nöbetçi eczane
+  const { data: enYakinlar } = await api.getNearby({
+    lat: 41.0082,
+    lon: 28.9784,
+    isSentry: true,
+    limit: 5
+  });
+  console.log('En Yakın Eczaneler:', enYakinlar);
+}
+
+main();
+```
+
+### CommonJS (Node.js)
+
+```javascript
+const { EczaneAPI } = require('nobetci-eczane-api');
+
+const api = new EczaneAPI({
+  apiKey: 'SENIN_API_ANAHTARIN'
+});
+
+api.getSentryByCity('ankara')
+  .then(response => console.log(response.data))
+  .catch(err => console.error(err));
+```
+
+---
+
+## 📖 API Metodları Referansı
+
+### 1. `getSentryPharmacies(options?)`
+Türkiye genelinde o gün nöbetçi olan tüm eczaneleri sayfalı listeler.
+
+```typescript
+const result = await api.getSentryPharmacies({ page: 1, limit: 50 });
+console.log(`Toplam ${result.pagination?.total} nöbetçi eczane listelendi.`);
+```
+
+### 2. `getSentryByCity(city, options?)`
+Belirtilen ildeki nöbetçi eczaneleri listeler. `city` parametresi plaka ID'si (`34`) veya slug (`"istanbul"`) olabilir.
+
+```typescript
+const response = await api.getSentryByCity('izmir', { limit: 30 });
+```
+
+### 3. `getSentryByDistrict(city, district, options?)`
+Belirtilen ilçedeki nöbetçi eczaneleri listeler.
+
+```typescript
+const response = await api.getSentryByDistrict(34, 440); // 34: İstanbul, 440: Kadıköy
+// Veya slug ile:
+const response2 = await api.getSentryByDistrict('istanbul', 'besiktas');
+```
+
+### 4. `getNearby(options)`
+Kullanıcının koordinatlarına göre en yakından uzağa doğru eczaneleri listeler.
+
+```typescript
+const response = await api.getNearby({
+  lat: 41.0082,
+  lon: 28.9784,
+  isSentry: true, // Sadece nöbetçiler (opsiyonel, varsayılan: true)
+  limit: 10       // Maksimum 50
+});
+```
+
+### 5. `getCities()` & `getDistricts(cityId)`
+Sistemdeki tüm il ve ilçe ID/Slug listesini getirir.
+
+```typescript
+const { data: iller } = await api.getCities();
+const { data: ilceler } = await api.getDistricts(34);
+```
+
+### 6. `getAccountInfo()`
+Kalan kullanım, kota, kayıt ve yetki durumunu kontrol eder.
+
+```typescript
+const account = await api.getAccountInfo();
+console.log(`Hesap Durumu: ${account.status}, Kalan Gün: ${account.remaining_days}`);
+```
+
+### 7. `updateWhitelist(ips)`
+API erişimi için dinamik IP Whitelist tanımını günceller.
+
+```typescript
+await api.updateWhitelist('5.132.*');
+```
+
+### 8. `getAllPharmacies(options?)` (Premium)
+Türkiye'deki tüm aktif eczane verilerine (+30.000) erişim sağlar.
+
+```typescript
+const result = await api.getAllPharmacies({ page: 1, limit: 50 });
+```
+
+---
+
+## 🛡️ Hata Yönetimi (Error Handling)
+
+SDK, standart HTTP hatalarını yakalayıp özel hata sınıflarına dönüştürür:
+
+```typescript
+import { 
+  EczaneAPI, 
+  AuthenticationError, 
+  RateLimitError, 
+  InvalidRequestError,
+  EczaneAPIError 
+} from 'nobetci-eczane-api';
+
+try {
+  const data = await api.getSentryByCity(34);
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('API anahtarı hatalı veya geçersiz.');
+  } else if (error instanceof RateLimitError) {
+    console.error(`İstek limiti aşıldı! Sıfırlanma süresi: ${error.resetInSeconds}s`);
+  } else if (error instanceof InvalidRequestError) {
+    console.error('Geçersiz parametre:', error.message);
+  } else if (error instanceof EczaneAPIError) {
+    console.error(`API Hatası [${error.status}]:`, error.message);
+  }
+}
+```
+
+---
+
+## ⚡ Next.js App Router Entegrasyon Örneği
+
+```typescript
+// app/api/nobetci-eczaneler/route.ts
+import { NextResponse } from 'next/server';
+import { EczaneAPI } from 'nobetci-eczane-api';
+
+const api = new EczaneAPI({
+  apiKey: process.env.ECZANE_API_KEY!
+});
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const city = searchParams.get('city') || '34';
+
+  try {
+    const result = await api.getSentryByCity(city);
+    return NextResponse.json(result);
+  } catch (error: any) {
+    return NextResponse.json(
+      { error: error.message },
+      { status: error.status || 500 }
+    );
+  }
+}
+```
+
+---
+
+## 📄 Lisans
+
+Bu kütüphane [MIT Lisansı](LICENSE) altında sunulmaktadır.
+
+## 💬 Destek ve İletişim
+
+* **Dokümantasyon:** [eczaneler.org/nobetci-eczane-api](https://eczaneler.org/nobetci-eczane-api)
+* **Telegram Destek:** [@mehmeterdogannet](https://t.me/mehmeterdogannet)
+* **Web Sitesi:** [eczaneler.org](https://eczaneler.org)

package/dist/index.d.mts

@@ -0,0 +1,321 @@
+/**
+ * Nöbetçi Eczane API TypeScript Types & Interfaces
+ */
+/**
+ * Coğrafi koordinat nesnesi
+ */
+interface Coordinates {
+    lat: number;
+    lng: number;
+}
+/**
+ * Eczane veri modeli (Nöbetçi ve Standart)
+ */
+interface Pharmacy {
+    id: number;
+    city_id: number;
+    district_id: number;
+    name: string;
+    phone: string;
+    city: string;
+    district: string;
+    locality?: string;
+    address: string;
+    address_description?: string;
+    sentry_date?: string;
+    is_sentry: boolean;
+    workingHours?: string;
+    note?: string;
+    status?: string;
+    coordinates: Coordinates;
+    map_link: string;
+    /** Konum bazlı aramalarda kullanıcıya olan mesafe (km cinsinden) */
+    distance?: number;
+}
+/**
+ * Sayfalama (Pagination) meta nesnesi
+ */
+interface PaginationMeta {
+    total: number;
+    per_page: number;
+    current_page: number;
+    total_pages: number;
+    has_more: boolean;
+    prev_page: number | null;
+    next_page: number | null;
+}
+/**
+ * Standart API liste yanıtı
+ */
+interface ApiResponse<T = Pharmacy[]> {
+    status?: string;
+    city_id?: number;
+    district_id?: number;
+    data: T;
+    pagination?: PaginationMeta;
+}
+/**
+ * İl Veri Modeli
+ */
+interface City {
+    id: number;
+    name: string;
+    slug: string;
+    plate: string | number;
+}
+/**
+ * İlçe Veri Modeli
+ */
+interface District {
+    id: number;
+    city_id: number;
+    name: string;
+    slug: string;
+}
+/**
+ * API Hesap & Kota Durumu Modeli
+ */
+interface AccountInfo {
+    api_key: string;
+    status: string;
+    registered_at?: string;
+    expires_at?: string;
+    remaining_days?: number;
+    allowed_ips?: string[];
+    rate_limit?: {
+        limit: number;
+        remaining: number;
+        reset_in_seconds?: number;
+    };
+}
+/**
+ * IP Whitelist Güncelleme Yanıt Modeli
+ */
+interface WhitelistUpdateResponse {
+    status: 'success' | 'error';
+    message: string;
+    allowed_ips?: string[];
+}
+/**
+ * Sayfalama ve limit parametreleri
+ */
+interface PaginationOptions {
+    /** Sayfa numarası (varsayılan: 1) */
+    page?: number;
+    /** Sayfa başına kayıt sayısı (1 - 50, varsayılan: 25) */
+    limit?: number;
+    /** Özel AbortSignal (istek iptali için) */
+    signal?: AbortSignal;
+}
+/**
+ * Konum bazlı en yakın eczane arama parametreleri
+ */
+interface NearbyOptions {
+    /** Kullanıcı enlemi (Latitude) */
+    lat: number;
+    /** Kullanıcı boylamı (Longitude) */
+    lon: number;
+    /** Yalnızca nöbetçi eczaneler mi aransın? (varsayılan: true) */
+    isSentry?: boolean;
+    /** Maksimum döndürülecek eczane sayısı (varsayılan: 10, maks: 50) */
+    limit?: number;
+    /** Arama yarıçapı kilometre cinsinden (opsiyonel) */
+    radius?: number;
+    /** Özel AbortSignal (istek iptali için) */
+    signal?: AbortSignal;
+}
+/**
+ * SDK Yapılandırma Seçenekleri
+ */
+interface EczaneAPIOptions {
+    /** Eczaneler.ORG v2 REST API Anahtarı */
+    apiKey: string;
+    /** Özel API Base URL (Varsayılan: https://eczaneler.org/api/v2) */
+    baseUrl?: string;
+    /** İstek zaman aşımı süresi milisaniye cinsinden (varsayılan: 10000ms - 10s) */
+    timeout?: number;
+    /** Özel HTTP istek başlıkları */
+    headers?: Record<string, string>;
+}
+
+/**
+ * Eczaneler.ORG v2 REST API İstemcisi
+ */
+declare class EczaneAPI {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly customHeaders;
+    /**
+     * Yeni bir EczaneAPI istemcisi örneği oluşturur
+     * @param options Yapılandırma ayarları
+     *
+     * @example
+     * ```typescript
+     * import { EczaneAPI } from 'nobetci-eczane-api';
+     *
+     * const api = new EczaneAPI({
+     *   apiKey: 'SENIN_API_ANAHTARIN'
+     * });
+     * ```
+     */
+    constructor(options: EczaneAPIOptions | string);
+    /**
+     * Türkiye genelinde o gün nöbetçi olan tüm eczaneleri listeler
+     *
+     * @param options Sayfalama ve limit ayarları (?page=1&limit=25)
+     * @returns Sayfalanmış nöbetçi eczane listesi
+     *
+     * @example
+     * ```typescript
+     * const result = await api.getSentryPharmacies({ page: 1, limit: 50 });
+     * console.log(`Toplam ${result.pagination?.total} nöbetçi eczane bulundu.`);
+     * ```
+     */
+    getSentryPharmacies(options?: PaginationOptions): Promise<ApiResponse<Pharmacy[]>>;
+    /**
+     * Belirtilen ildeki nöbetçi eczaneleri listeler
+     *
+     * @param city İl adı / slug'ı (örn: "istanbul", "ankara") VEYA Plaka/Şehir ID (örn: 34, 6)
+     * @param options Sayfalama ve limit ayarları
+     * @returns İldeki nöbetçi eczane listesi
+     *
+     * @example
+     * ```typescript
+     * // Şehir ID (34 - İstanbul) ile nöbetçileri çekme
+     * const result = await api.getSentryByCity(34, { limit: 50 });
+     *
+     * // Slug ile çekme
+     * const izmir = await api.getSentryByCity('izmir');
+     * ```
+     */
+    getSentryByCity(city: string | number, options?: PaginationOptions): Promise<ApiResponse<Pharmacy[]>>;
+    /**
+     * Belirtilen ilçedeki nöbetçi eczaneleri listeler
+     *
+     * @param city İl slug veya ID (örn: "istanbul" veya 34)
+     * @param district İlçe slug veya ID (örn: "kadikoy" veya 440)
+     * @param options Sayfalama ve limit ayarları
+     * @returns İlçedeki nöbetçi eczane listesi
+     *
+     * @example
+     * ```typescript
+     * const result = await api.getSentryByDistrict(34, 440);
+     * // Veya slug ile:
+     * const result2 = await api.getSentryByDistrict('istanbul', 'kadikoy');
+     * ```
+     */
+    getSentryByDistrict(city: string | number, district: string | number, options?: PaginationOptions): Promise<ApiResponse<Pharmacy[]>>;
+    /**
+     * Coğrafi koordinatlara (enlem / boylam) göre en yakın eczaneleri mesafeye göre sıralı getirir
+     *
+     * @param options Enlem (lat), boylam (lon), isSentry ve limit ayarları
+     * @returns En yakından uzağa sıralanmış eczane listesi
+     *
+     * @example
+     * ```typescript
+     * const result = await api.getNearby({
+     *   lat: 41.0082,
+     *   lon: 28.9784,
+     *   isSentry: true,
+     *   limit: 10
+     * });
+     * ```
+     */
+    getNearby(options: NearbyOptions): Promise<ApiResponse<Pharmacy[]>>;
+    /**
+     * Desteklenen tüm il listesini döner
+     *
+     * @example
+     * ```typescript
+     * const { data: cities } = await api.getCities();
+     * ```
+     */
+    getCities(signal?: AbortSignal): Promise<ApiResponse<City[]>>;
+    /**
+     * Belirtilen ile ait ilçe listesini döner
+     *
+     * @param cityId İl ID (örn: 34 - İstanbul)
+     *
+     * @example
+     * ```typescript
+     * const { data: districts } = await api.getDistricts(34);
+     * ```
+     */
+    getDistricts(cityId: number, signal?: AbortSignal): Promise<ApiResponse<District[]>>;
+    /**
+     * API anahtarınıza ait kalan kullanım, kota ve yetki bilgilerini döner
+     *
+     * @example
+     * ```typescript
+     * const account = await api.getAccountInfo();
+     * console.log(`Kalan süre: ${account.remaining_days} gün`);
+     * ```
+     */
+    getAccountInfo(signal?: AbortSignal): Promise<AccountInfo>;
+    /**
+     * Dinamik IP Whitelist tanımını günceller
+     *
+     * @param ips İzin verilecek IP adresi veya maskesi (örn: "5.132.*" veya "195.175.20.10")
+     *
+     * @example
+     * ```typescript
+     * const res = await api.updateWhitelist('5.132.*');
+     * ```
+     */
+    updateWhitelist(ips: string, signal?: AbortSignal): Promise<WhitelistUpdateResponse>;
+    /**
+     * Türkiye'deki tüm eczaneleri (nöbetçi olmayanlar dahil +30.000) sayfalı olarak döner (Premium Servis)
+     *
+     * @param options Sayfalama ve limit ayarları
+     *
+     * @example
+     * ```typescript
+     * const result = await api.getAllPharmacies({ page: 1, limit: 50 });
+     * ```
+     */
+    getAllPharmacies(options?: PaginationOptions): Promise<ApiResponse<Pharmacy[]>>;
+    /**
+     * Merkezi HTTP İstek Yürütücüsü (Native fetch)
+     */
+    private request;
+    /**
+     * HTTP Hata Durumlarını Özelleştirilmiş Hata Sınıflarına Çevirir
+     */
+    private handleHttpError;
+    /**
+     * Sayfalama query string oluşturucu
+     */
+    private buildPaginationQuery;
+}
+
+/**
+ * Nöbetçi Eczane API Özel Hata Sınıfları
+ */
+declare class EczaneAPIError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly details?: unknown;
+    constructor(message: string, status?: number, code?: string, details?: unknown);
+}
+declare class AuthenticationError extends EczaneAPIError {
+    constructor(message?: string);
+}
+declare class ForbiddenError extends EczaneAPIError {
+    constructor(message?: string);
+}
+declare class NotFoundError extends EczaneAPIError {
+    constructor(message?: string);
+}
+declare class RateLimitError extends EczaneAPIError {
+    readonly resetInSeconds?: number;
+    constructor(message?: string, resetInSeconds?: number);
+}
+declare class InvalidRequestError extends EczaneAPIError {
+    constructor(message?: string, details?: unknown);
+}
+declare class TimeoutError extends EczaneAPIError {
+    constructor(message?: string);
+}
+
+export { type AccountInfo, type ApiResponse, AuthenticationError, type City, type Coordinates, type District, EczaneAPI, EczaneAPIError, type EczaneAPIOptions, ForbiddenError, InvalidRequestError, type NearbyOptions, NotFoundError, type PaginationMeta, type PaginationOptions, type Pharmacy, RateLimitError, TimeoutError, type WhitelistUpdateResponse, EczaneAPI as default };