Abaris Hub Node.js SDK

Sürüm: 1.2.0 Yayın Tarihi: 18 Mayıs 2025

Bu Software Development Kit (SDK), Abaris Hub API ile Node.js ve TypeScript uygulamalarınız arasında sorunsuz bir entegrasyon sağlamak üzere tasarlanmıştır. API'nin tüm özelliklerine kolayca erişim imkanı sunar ve geliştirme sürecinizi hızlandırır.

Özellikler

• Tam API Kapsamı: OpenAPI tarafından otomatik olarak üretilen servisler sayesinde tüm Abaris Hub API endpoint'lerine doğrudan erişim.
• TypeScript Desteği: Güçlü tipleme ve geliştirme sırasında otomatik tamamlama özellikleri.
• Otomatik Kimlik Doğrulama: Güvenli token tabanlı kimlik doğrulama ve otomatik token yenileme (refresh token).
• Esnek Yapılandırma: API adresi, zaman aşımı süresi ve tenant bilgisi gibi temel ayarlar için kolay yapılandırma.
• Detaylı Hata Yönetimi: API'den dönen hatalar için anlaşılır ve yönetilebilir hata nesneleri.

Kurulum

SDK'yı projenize eklemek için tercih ettiğiniz paket yöneticisini kullanabilirsiniz:

PNPM ile:

pnpm add abaris-hub-sdk

NPM ile:

npm install abaris-hub-sdk

Yarn ile:

yarn add abaris-hub-sdk

Temel Kullanım

SDK'yı projenizde kullanmaya başlamak için aşağıdaki adımları izleyin:

1. SDK'yı İçe Aktarma

import { AbarisHubSDK } from 'abaris-hub-sdk';
// Veya JavaScript için:
// const { AbarisHubSDK } = require('abaris-hub-sdk');

2. SDK Örneği Oluşturma

SDK'yı kullanmadan önce, API adresiniz ve diğer yapılandırma seçeneklerinizle bir örnek oluşturmanız gerekmektedir.

const sdk = new AbarisHubSDK({
  apiUrl: 'https://data-endpoint.com', // API sunucu adresiniz (ZORUNLU)
  tenant: 'YOUR_TENANT_ID',            // Kullanılacak tenant kimliği (örn: 'root', 'b2b_tenant')
  timeout: 30000,                      // API istekleri için zaman aşımı süresi (ms cinsinden, isteğe bağlı, varsayılan: 30000)
  debug: true                          // Hata ayıklama loglarını aktif et (isteğe bağlı, varsayılan: false)
});

Not: apiUrl parametresi zorunludur. Eğer sağlanmazsa, SDK bir hata fırlatacaktır.

3. Kimlik Doğrulama (Login)

API'nin korumalı endpoint'lerine erişmeden önce kimlik doğrulaması yapmanız gerekir.

async function authenticateUser() {
  try {
    const loginResponse = await sdk.login('YOUR_USERNAME', 'YOUR_PASSWORD');
    if (loginResponse.success) {
      console.log('Giriş başarılı!');
      console.log('Access Token:', sdk.getToken()); // Geçerli access token'ı alır
    } else {
      console.error('Giriş başarısız:', loginResponse.message);
      if (loginResponse.error) {
        // loginResponse.error.response.data gibi detaylı hata bilgisine erişebilirsiniz.
        console.error('Detaylı Hata:', loginResponse.error);
      }
    }
  } catch (error) {
    console.error('Login işlemi sırasında beklenmedik bir hata oluştu:', error);
  }
}

authenticateUser();

SDK, accessToken ve refreshToken'ı otomatik olarak yönetir. accessToken süresi dolduğunda, refreshToken kullanarak sessizce yeniler.

4. API Servislerini Kullanma

SDK, API endpoint'lerini mantıksal kategoriler (örneğin identity, catalog, finance, core) altında gruplandırır. Her kategori altında, OpenAPI tarafından üretilmiş servis sınıfları bulunur. Bu servis sınıfları, ...Endpoint ile biten statik metotlar içerir.

Örnek: Finans Servisleri - En Son Döviz Kurlarını Alma

async function getLatestExchangeRates() {
  if (!sdk.isAuthenticated()) {
    console.log('Lütfen önce giriş yapın.');
    await authenticateUser(); // Önceki adımda tanımlanan login fonksiyonu
    if (!sdk.isAuthenticated()) return; // Eğer login hala başarısızsa çık
  }

  try {
    console.log('\n💱 En Son Döviz Kurları Alınıyor...');
    const response = await sdk.finance.ExchangeRates.getLatestExchangeRatesEndpoint({
      // version: '1', // API versiyonu (isteğe bağlı, varsayılan '1')
      // rateTypes: 'ForexBuying,BanknoteSelling' // İstenen kur tipleri (isteğe bağlı)
    });

    if (!response.isError && response.data) {
      console.log('En Son Döviz Kurları:', response.data);
      // response.data bir LatestExchangeRateDto[] dizisidir.
      // Örnek: response.data.forEach(rate => console.log(rate.currency.code, rate.forexBuying));
    } else {
      console.error('Döviz kurları alınamadı:', response.message);
    }
  } catch (error) {
    console.error('Döviz kurları alınırken bir hata oluştu:', error);
  }
}

// Login olduktan sonra çağırın:
// authenticateUser().then(getLatestExchangeRates);

Örnek: Finans Servisleri - Belirli Bir Tarihteki Döviz Kurlarını Alma

async function getExchangeRatesByDate(dateString: string) {
  if (!sdk.isAuthenticated()) {
    console.log('Lütfen önce giriş yapın.');
    await authenticateUser();
    if (!sdk.isAuthenticated()) return;
  }

  try {
    console.log(`\n🗓️ ${dateString} Tarihindeki Döviz Kurları Alınıyor...`);
    const response = await sdk.finance.ExchangeRates.getExchangeRatesByDateEndpoint({
      dateString: dateString, // YYYY-MM-DD formatında
      // version: '1'
    });

    if (!response.isError && response.data) {
      console.log(`${dateString} Tarihindeki Döviz Kurları:`, response.data);
      // response.data bir ExchangeRateByDateDto[] dizisidir.
    } else {
      console.error(`${dateString} için döviz kurları alınamadı:`, response.message);
    }
  } catch (error) {
    console.error(`${dateString} için döviz kurları alınırken bir hata oluştu:`, error);
  }
}

// Örnek çağrı:
// authenticateUser().then(() => getExchangeRatesByDate('2025-10-06'));

Örnek: Kimlik Yönetimi Servisleri - Tüm Kullanıcıları Listeleme (Yetki gerektirir)

async function getAllUsers() {
  if (!sdk.isAuthenticated()) {
    console.log('Lütfen önce giriş yapın.');
    await authenticateUser();
    if (!sdk.isAuthenticated()) return;
  }

  try {
    console.log('\n👥 Tüm Kullanıcılar Listeleniyor...');
    const response = await sdk.identity.Users.getAllUsersEndpoint({
      // Sayfalama ve filtreleme parametreleri burada eklenebilir, örn:
      // pageNumber: 1,
      // pageSize: 20,
      // searchTerm: 'admin'
    });

    if (!response.isError && response.data) {
      console.log('Kullanıcılar:', response.data.items); // Kullanıcı listesi response.data.items içindedir
      console.log('Toplam Kullanıcı Sayısı:', response.data.totalCount);
    } else {
      console.error('Kullanıcılar listelenemedi:', response.message);
    }
  } catch (error) {
    console.error('Kullanıcılar listelenirken bir hata oluştu:', error);
  }
}

// authenticateUser().then(getAllUsers);

5. Servis ve Kategori Yapısı

SDK içindeki servisler şu şekilde kategorize edilmiştir:

• sdk.identity: Kullanıcılar, Roller, Token yönetimi.
  • sdk.identity.Users
  • sdk.identity.Roles
  • sdk.identity.Token
• sdk.catalog: Ürünler, Markalar, Siparişler vb.
  • sdk.catalog.Products
  • sdk.catalog.Brands
  • ...
• sdk.finance: Para Birimleri, Döviz Kurları, Ödemeler vb.
  • sdk.finance.Currencies
  • sdk.finance.ExchangeRates
  • ...
• sdk.core: Tenant'lar, Agent'lar vb. temel sistem servisleri.
  • sdk.core.Tenants
  • sdk.core.Agents
  • ...

Her bir servis (örneğin sdk.finance.Currencies), OpenAPI şemasından türetilmiş statik metotlar içerir. Örneğin:

• sdk.finance.Currencies.getAllCurrenciesEndpoint({...})
• sdk.finance.Currencies.createCurrencyEndpoint({ requestBody: {...} })
• sdk.catalog.Products.getProductByIdEndpoint({ productId: '...' })

Kullanılabilir tüm metotlar ve bekledikleri parametreler için lütfen OpenAPI tarafından üretilen ilgili servis dosyalarına (src/lib/openapi/api/services/) veya API dokümantasyonunuza başvurun.

Hata Yönetimi

Tüm ...Endpoint metotları genellikle aşağıdaki yapıda bir nesne döndürür:

interface ApiResponse<T> {
  isError: boolean;        // İşlemin başarılı olup olmadığını belirtir
  message: string;         // İşlem sonucu hakkında bilgi mesajı
  data?: T;                // Başarılı ise dönen veri (tipi endpoint'e göre değişir)
  error?: any;             // Hata oluştuysa, hata detayları
  statusCode?: number;     // HTTP durum kodu
  errors?: Record<string, string[]>; // Validasyon hataları gibi detaylı hata listesi
}

catch bloklarında ise, ağ hataları veya SDK içindeki beklenmedik durumlar yakalanır.

Gelişmiş Yapılandırma

Axios Interceptor'ları

SDK, istek ve yanıtları işlemek için Axios interceptor'larını kullanır. Bu interceptor'lar:

• Her isteğe otomatik olarak Authorization başlığını (access token ile) ekler.
• Tenant bilgisini (Abaris-Tenant başlığı) ekler.
• 401 Unauthorized yanıtı alındığında token yenileme (refresh token) işlemini tetikler.

OpenAPI Yapılandırması

SDK, OpenAPI client'ının bazı temel ayarlarını (OpenAPI.BASE, OpenAPI.TOKEN, OpenAPI.HEADERS) kendi iç mantığına göre yönetir. Bu değerleri doğrudan değiştirmeniz genellikle önerilmez.

Yayınlama

SDK'yı yayınlamak için:

npm run build
npm version patch
npm publish

Lisans

Telif Hakkı 2025 Abaris Teknoloji A.Ş. (abaris.io). Tüm hakları saklıdır. Bu SDK'nın kullanımı Abaris Hub kullanım koşullarına tabidir.