🏋️‍♂️ kinetics-js

🇺🇸 English Description | 🇹🇷 Türkçe Açıklama

🇺🇸 English

kinetics-js is an open-source, enterprise-grade Node.js SDK (Client Library) designed to seamlessly integrate nutritional data and exercise libraries into fitness, health, and wearable tech applications. It communicates securely with the centralized backend at api.armesbilisim.com.

🛡️ Enterprise-Grade Anti-Scraping Protection

To safeguard proprietary nutritional datasets and GIF assets, this SDK implements a Dynamic HMAC-SHA256 Request Signing mechanism. Every single API request automatically computes a time-sensitive cryptographic signature (X-Sign) coupled with a 30-second sliding expiration window (X-Timestamp). This completely prevents URL hijacking, replay attacks, and raw data scraping.

🌟 Key Features

• Secure Handshake Manager: Zero-config automated cryptographic signature generation.
• Zero External Dependencies: Built on native Node.js crypto and native fetch (requires Node.js v18+).
• Unified Food Search: Query thousands of commercial foods with parameterized filters returning calories, protein, carbs, and fats.
• Rich Exercise Database: Fetch curated exercise lists with dynamic, high-quality instruction gif_url assets served directly from our secure cloud network.
• Robust Error Handling: Distinguishes between network connectivity errors and server-returned HTTP status errors, making integration debugging a breeze.

📦 Installation

npm install kinetics-js

🚀 Quick Start

const Kinetics = require('kinetics-js');

const sdk = new Kinetics({
  apiKey: 'YOUR_API_KEY',
  apiSecret: 'YOUR_HMAC_SECRET_KEY',
  // baseUrl is optional - defaults to https://api.armesbilisim.com
});

// Search for food
sdk.searchFood('Pizza')
  .then(foods => {
    console.log(foods); // Array of food items
  })
  .catch(err => console.error(err));

// Search for exercises
sdk.searchExercise('Squat')
  .then(exercises => {
    console.log(exercises); // Array of exercises with gif_url
  })
  .catch(err => console.error(err));

🔒 Signature Mechanics (Under the Hood)

When an API call is made, the SDK automatically computes the request headers:

• X-Api-Key: The provided API key.
• X-Timestamp: The current Unix timestamp in seconds (Math.floor(Date.now() / 1000)).
• X-Sign: Hex-encoded HMAC-SHA256 hash using your apiSecret as the key and X-Timestamp + apiKey as the message payload.

🛠️ Advanced Error Handling

The SDK wraps server and network errors into clean JavaScript Error objects:

try {
  const result = await sdk.searchFood('Humus');
} catch (error) {
  if (error.status) {
    // The server responded with a status code outside the 2xx range (e.g. 403 Forbidden, 429 Too Many Requests)
    console.error(`API Error Code: ${error.status}`);
    console.error(`API Message:`, error.response);
  } else {
    // Network/Connection failure
    console.error(`Network Error: ${error.message}`);
  }
}

🇹🇷 Türkçe

kinetics-js, fitness, sağlık ve giyilebilir teknoloji uygulamalarına besin verilerini ve egzersiz kütüphanelerini sorunsuz bir şekilde entegre etmek için tasarlanmış, açık kaynaklı, kurumsal düzeyde bir **Node.js SDK (İstemci Kütüphanesi)**dir. api.armesbilisim.com adresindeki merkezi backend ile güvenli bir şekilde iletişim kurar.

🛡️ Kurumsal Düzeyde Anti-Scraping Koruması

Tescilli besin veri setlerini ve GIF varlıklarını korumak amacıyla bu SDK, Dinamik HMAC-SHA256 Talep İmzalama mekanizmasını uygular. Her API isteği, 30 saniyelik kayan bir son kullanma penceresi (X-Timestamp) ile birlikte zaman duyarlı bir kriptografik imza (X-Sign) otomatik olarak hesaplar. Bu, URL korsanlığını, tekrar oynatma saldırılarını ve ham veri kazımayı tamamen önler.

🌟 Temel Özellikler

• Güvenli Bağlantı Yöneticisi: Sıfır yapılandırma ile otomatik kriptografik imza oluşturma.
• Sıfır Harici Bağımlılık: Tamamen yerleşik Node.js crypto ve yerleşik fetch api üzerine inşa edilmiştir (Node.js v18+ gerektirir).
• Birleşik Besin Arama: Binlerce ticari gıdayı parametreli filtrelerle sorgulayın; kalori, protein, karbonhidrat ve yağ değerlerini döndürür.
• Zengin Egzersiz Kütüphanesi: Güvenli bulut ağımızdan doğrudan sunulan dinamik, yüksek kaliteli talimat gif_url varlıklarıyla derlenmiş egzersiz listelerini alın.
• Gelişmiş Hata Yönetimi: Bağlantı hataları ile sunucudan dönen hata kodlarını (403, 429 vb.) birbirinden ayırarak entegrasyon sürecini hızlandırır.

📦 Kurulum

npm install kinetics-js

🚀 Hızlı Başlangıç

const Kinetics = require('kinetics-js');

const sdk = new Kinetics({
  apiKey: 'YENİ_API_ANAHTARINIZ',
  apiSecret: 'YENİ_HMAC_GİZLİ_ANAHTARINIZ',
  // baseUrl isteğe bağlıdır - varsayılan: https://api.armesbilisim.com
});

// Besin ara
sdk.searchFood('Pizza')
  .then(foods => {
    console.log(foods); // Besin öğelerinin dizisi
  })
  .catch(err => console.error(err));

// Egzersiz ara
sdk.searchExercise('Squat')
  .then(exercises => {
    console.log(exercises); // gif_url içeren egzersizlerin dizisi
  })
  .catch(err => console.error(err));

🔒 İmza Mekanizması (Arka Planda Neler Dönüyor?)

Bir API isteği atıldığında, SDK otomatik olarak şu başlıkları (headers) oluşturur:

• X-Api-Key: Belirttiğiniz API anahtarı.
• X-Timestamp: İstek atıldığı andaki Unix timestamp saniye cinsinden (Math.floor(Date.now() / 1000)).
• X-Sign: apiSecret değerinizi gizli anahtar (secret key) olarak kullanarak, X-Timestamp + apiKey verisini HMAC-SHA256 ile şifreler ve hexadecimal biçimde gönderir.

🛠️ Gelişmiş Hata Yönetimi

SDK, sunucu ve bağlantı hatalarını anlamlı JavaScript Error nesnelerine sarmalar:

try {
  const result = await sdk.searchFood('Humus');
} catch (error) {
  if (error.status) {
    // Sunucu 2xx dışı bir HTTP durum kodu döndürdü (Örn: 403 Yetkisiz İstek, 429 Aşırı İstek Limiti)
    console.error(`API Hata Kodu: ${error.status}`);
    console.error(`API Yanıtı:`, error.response);
  } else {
    // Ağ / Bağlantı hatası
    console.error(`Bağlantı Hatası: ${error.message}`);
  }
}