@mojaksebastian/allegro-client 1.0.4 → 1.0.5

package/README.md

@@ -1,49 +1,57 @@
 @mojaksebastian/allegro-client
 
-A lightweight and flexible Allegro REST API client for Node.js. It features automatic OAuth2 token management and a pluggable storage system for tokens (Redis, Database, File System, etc.).
-Key Features
+Wydajny i skalowalny klient Allegro REST API dla środowiska Node.js, oferujący pełną automatyzację procesu autoryzacji OAuth2 oraz abstrakcję warstwy przechowywania tokenów.
+Główne cechy rozwiązania
 
-    Automatic Token Refresh: No more manual handling of access_token expiration. The client automatically refreshes tokens before they expire.
+    Automatyczna retencja tokenów: System monitoruje czas wygasania sesji i odświeża tokeny przed ich unieważnieniem.
 
-    Device Flow Support: Built-in strategy for DeviceFlow, ideal for CLI tools, scripts, and server-side applications.
+    Abstrakcja warstwy Storage: Implementacja interfejsu ITokenStorage pozwala na delegowanie zapisu sesji do dowolnego silnika (Redis, SQL, NoSQL, FileSystem).
 
-    Pluggable Storage: Use the ITokenStorage interface to persist tokens wherever you want.
+    Zgodność ze standardem ESM: Paczka zoptymalizowana pod nowoczesne środowiska Node.js (20+) oraz moduły ECMAScript.
 
-    First-class TypeScript Support: Fully typed configuration and responses for a seamless developer experience.
+    Silne typowanie: Kompletne definicje TypeScript dla konfiguracji, strategii oraz interfejsów magazynowania danych.
 
-    Sandbox & Production: Easy switching between environments with a single flag.
+Instalacja
 
-Installation
+Paczka jest dostępna w rejestrze NPM. Można ją zainstalować za pomocą preferowanego menedżera pakietów:
 Bash
 
 npm install @mojaksebastian/allegro-client
 
-Quick Start (DeviceFlow + Default FileStorage)
+Szybki Start
+
+Poniższy przykład prezentuje podstawową konfigurację z wykorzystaniem strategii DeviceFlow oraz domyślnego magazynu plikowego.
 TypeScript
 
 import AllegroClient from "@mojaksebastian/allegro-client";
 
-const client = new AllegroClient({
+const config = {
   credentials: {
-    clientId: "YOUR_CLIENT_ID",
-    clientSecret: "YOUR_CLIENT_SECRET",
+    clientId: process.env.ALLEGRO_CLIENT_ID,
+    clientSecret: process.env.ALLEGRO_CLIENT_SECRET,
   },
   strategy: "DeviceFlow",
-  env: "sandbox" // or "production"
-});
-
-async function run() {
-  // Automatically reads from file or initiates Device Flow if needed
-  const token = await client.getAccessToken();
-  console.log("Your access token:", token);
+  env: "sandbox" // Opcje: "production" | "sandbox"
+};
+
+const allegro = new AllegroClient(config);
+
+async function initialize() {
+  try {
+    const accessToken = await allegro.getAccessToken();
+    console.log("Autoryzacja zakończona sukcesem.");
+    return accessToken;
+  } catch (error) {
+    console.error("Błąd autoryzacji:", error.message);
+  }
 }
 
-run();
+initialize();
 
-Advanced: Custom Storage (e.g., Redis)
+Implementacja własnego magazynu danych (ITokenStorage)
 
-You can implement the ITokenStorage interface to store tokens in a production-grade database. This is essential for serverless environments (like AWS Lambda or Vercel) where the file system is ephemeral.
-Redis Implementation Example
+Architektura biblioteki pozwala na wstrzyknięcie własnej klasy zarządzającej danymi sesyjnymi. Jest to rozwiązanie zalecane dla środowisk rozproszonych i bezstanowych (Serverless).
+Przykład: Integracja z Redis
 TypeScript
 
 import { ITokenStorage, IAllegroTokens } from "@mojaksebastian/allegro-client";
@@ -52,44 +60,59 @@ import { createClient } from "redis";
 export class RedisTokenStorage implements ITokenStorage {
   private client = createClient({ url: 'redis://localhost:6379' });
 
-  async save(tokens: IAllegroTokens) {
+  private async connect() {
     if (!this.client.isOpen) await this.client.connect();
-    await this.client.set("allegro_tokens", JSON.stringify(tokens));
   }
 
-  async read() {
-    if (!this.client.isOpen) await this.client.connect();
-    const data = await this.client.get("allegro_tokens");
+  async save(tokens: IAllegroTokens): Promise<void> {
+    await this.connect();
+    await this.client.set("allegro_session", JSON.stringify(tokens));
+  }
+
+  async read(): Promise<IAllegroTokens | null> {
+    await this.connect();
+    const data = await this.client.get("allegro_session");
     return data ? JSON.parse(data) : null;
   }
 
-  async clear() {
-    if (!this.client.isOpen) await this.client.connect();
-    await this.client.del("allegro_tokens");
+  async clear(): Promise<void> {
+    await this.connect();
+    await this.client.del("allegro_session");
   }
 }
 
-// Usage:
-const client = new AllegroClient({
-  credentials: { clientId: "...", clientSecret: "..." },
-  storage: new RedisTokenStorage(),
-  strategy: "DeviceFlow"
+// Inicjalizacja klienta z wykorzystaniem Redis
+const allegro = new AllegroClient({
+  ...config,
+  storage: new RedisTokenStorage()
 });
 
-Configuration (IAllegroClientConfig)
-| Property | Type | Description |
-| :--- | :--- | :--- |
-| `credentials` | `IAuthCredentials` | Object containing `clientId` and `clientSecret`. |
-| `strategy` | `Tstrategy` | Authentication strategy. Supported: `"DeviceFlow"`. |
-| `env` | `"production" \| "sandbox"` | Target environment (defaults to `"production"`). |
-| `storage` | `ITokenStorage` | (Optional) Custom storage instance. Defaults to `FileTokenStorage`. |
+Specyfikacja techniczna
+Interfejs konfiguracji (IAllegroClientConfig)
+Właściwość	Typ	Wymagane	Opis
+credentials	IAuthCredentials	Tak	Obiekt zawierający clientId oraz clientSecret.
+strategy	Tstrategy	Tak	Wybrana strategia autoryzacji (np. "DeviceFlow").
+env	"production" | "sandbox"	Nie	Środowisko Allegro (Domyślnie: "production").
+storage	ITokenStorage	Nie	Instancja klasy zarządzającej zapisem (Domyślnie: FileTokenStorage).
+Metody klasy AllegroClient
+
+    getAccessToken(): Promise<string> – Zwraca aktywny token dostępowy. Jeśli token wygasł lub nie istnieje, inicjuje proces odświeżania lub autoryzacji.
+
+    clearSession(): Promise<void> – Usuwa dane sesyjne z przypisanego magazynu.
 
-This package uses ESM and requires Node.js v20 or higher.
+Rozwój projektu
+
+Biblioteka wymaga Node.js w wersji 20.x lub wyższej.
 Bash
 
-npm run build   # Compiles TS to JS (dist folder)
-npm run dev     # Runs the project in development mode
+# Kompilacja kodu źródłowego (TypeScript -> JavaScript)
+npm run build
+
+# Uruchomienie skryptów w trybie deweloperskim
+npm run dev
+
+Licencja
 
-License
+Projekt dystrybuowany na warunkach licencji MIT. Szczegóły znajdują się w pliku LICENSE.
 
-MIT
+Autor: mojaksebastian

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mojaksebastian/allegro-client",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Allegro REST API Client with automatic token refresh. Fetches tokens from allegro and serves them to the user. Supports both the production and sandbox enviroments",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",