@virusis/api-client

TypeScript API client generated with NSwag. Fetch tabanli; ApiClientConfig ile base URL ve bearer token saglayarak kullanilir. Config'i tek seferde ayarlayip tum servisleri ortak kullanmak icin setDefaultConfig + getServices / getServicesRx kullan.

Kurulum

npm install @virusis/api-client
# veya
yarn add @virusis/api-client

Hizli baslangic (tek seferde config + tum servisler):

import { ApiClientConfig, setDefaultConfig, getServices } from "@virusis/api-client";

setDefaultConfig(
  new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token"))
);

const services = getServices(); // camelCase servisler
await services.usersService.getAll();

Populer Framework Ornekleri

Angular

Merkezi config + DI servis:

import { Injectable, Inject } from "@angular/core";
import { ApiClientConfig, setDefaultConfig, getServices } from "@virusis/api-client";

@Injectable({ providedIn: "root" })
export class ApiClientService {
  services = getServices();
  constructor(@Inject("API_BASE_URL") baseUrl: string) {
    setDefaultConfig(
      new ApiClientConfig(baseUrl, () => localStorage.getItem("token"))
    );
  }
}

Provider:

providers: [{ provide: "API_BASE_URL", useValue: "https://api.example.com" }]

Component:

constructor(private api: ApiClientService) {}
ngOnInit() {
  this.api.services.usersService.getAll().then(console.log);
}

React (web)

import { useEffect, useMemo } from "react";
import { ApiClientConfig, UsersClient } from "@virusis/api-client";

export function UsersList() {
  const client = useMemo(() => new UsersClient(
    new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token"))
  ), []);

  useEffect(() => {
    client.getAll().then(console.log);
  }, [client]);

  return null;
}

Vue 3

import { ApiClientConfig, UsersClient } from "@virusis/api-client";
import { onMounted } from "vue";

const client = new UsersClient(new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token")));

onMounted(async () => {
  const users = await client.getAll();
  console.log(users);
});

React Native

import { ApiClientConfig, UsersClient } from "@virusis/api-client";

const client = new UsersClient(new ApiClientConfig("https://api.example.com", async () => {
  return await getTokenFromSecureStore();
}));
const users = await client.getAll();

Moduler import (kebab-case dosya adlari)

• Servisler (client class'lari Service alias'i ile): @virusis/api-client/clients/<controller>-service
  • Ornek: @virusis/api-client/clients/users-service
• Modeller: @virusis/api-client/models/<model>
  • Ornek: @virusis/api-client/models/user
  • Tip kullanimi: import type { user } from "@virusis/api-client/models/user";

Tek seferde config verip merkezi kullanmak (getServices / getServicesRx)

import { ApiClientConfig, setDefaultConfig, getServices, getServicesRx } from "@virusis/api-client";

setDefaultConfig(new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token")));

const services = getServices();     // Promise tabanli
await services.usersService.getAll();

const servicesRx = getServicesRx(); // Rx tabanli
servicesRx.usersService.getAll().subscribe(console.log);

Bu sayede her import'ta ApiClientConfig vermek gerekmiyor; tek seferde ayarlayip tum servisleri kullanabiliyorsun.

Tek isimden secim yapmak istersen getServicesByMode("rx")/getServicesByMode("promise"):

import { ApiClientConfig, setDefaultConfig, getServicesByMode } from "@virusis/api-client";
setDefaultConfig(new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token")));
const services = getServicesByMode("rx"); // "rx" -> Observable, "promise" -> Promise
services.authService.login().subscribe(console.log);

RxJS

Promise metotlarini Observable'a cevirmek icin:

import { ApiClientConfig, UsersClient, rxifyClient } from "@virusis/api-client";
const client = rxifyClient(new UsersClient(new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token"))));
client.getAll().subscribe(console.log);

RxJS hazir factory'ler

Tek tek tanimlamak istemiyorsan, tum client'lari otomatik Rx olarak al:

import { ApiClientConfig, createAllRxClients } from "@virusis/api-client";
const cfg = new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token"));
const services = createAllRxClients(cfg);
services.usersService.getAll().subscribe(console.log);

(Alternatif: create<Controller>ServiceRx fonksiyonlari da var.)

Tum Rx client'lari camelCase key ile almak istersen:

import { ApiClientConfig, createAllRxClientsCamel } from "@virusis/api-client";
const services = createAllRxClientsCamel(
  new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token"))
);
// services.usersService.getAll().subscribe(...)

HTTP ozellestirme (headers / credentials)

• Tum cagrilarda withCredentials, ekstra header gibi default'lar icin buildHttpWithDefaults:

import { ApiClientConfig, UsersClient, buildHttpWithDefaults } from "@virusis/api-client";

const cfg = new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token"));
const http = buildHttpWithDefaults(cfg, {
  credentials: "include",              // tarayici cookie'lerini gonder
  headers: { "X-Tenant": "acme" },     // tum isteklere ek default header
});

const users = new UsersClient(cfg, undefined, http);
await users.getAll(); // header'lar + Authorization otomatik gider

• Belirli endpoint'i ozel yonetmek istersen http.fetch'i sarmalayarak URL bazli header ekleyebilirsin:

const baseHttp = buildHttpWithDefaults(cfg, { credentials: "include" });
const http = {
  fetch: (url, init) => {
    const extra = url.toString().includes("UserViews")
      ? { headers: { "X-View": "hasVisited" } }
      : undefined;
    return baseHttp.fetch(url, { ...init, ...extra });
  },
};
const client = new UsersClient(cfg, undefined, http);

Varsayilan Authorization (Bearer) ve Accept/Content-Type header'lari ayni sekilde korunur.

Tum client'lari otomatik (Promise tabanli)

import { ApiClientConfig, createAllClientsCamel } from "@virusis/api-client";
const services = createAllClientsCamel(
  new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token"))
);
// Ornek: services.usersService.getAll().then(...)

Auth Notu

ApiClientConfig.getToken saglandiginda Authorization header otomatik eklenir.

Flutter (JS koprusu)

dist ciktilarini flutter_js vb. runtime ile yukleyip kullanabilirsin (bkz. docs/flutter.md). Kucuk bundle icin npx esbuild dist/index.js --bundle --platform=browser --outfile=dist/bundle.js.

Komutlar

• npm run generate - NSwag + stub bolme (cross-platform)
• npm run build - TypeScript build
• npm test - Vitest
• npm run ci - generate + build + test
• npm run pack:local - packages/virusis-api-client-0.1.0.tgz uretir
• npm run release - publish (NPM_TOKEN gerekli)
• npm run fetch:spec - swagger'ı (varsayılan http://localhost:5000/swagger/v1/swagger.json, SPEC_URL ile degistirilebilir) indirip specs/openapi.json kaydeder (cross-platform)
• npm run gen:python - specs/openapi.json ile Python paketi (out/python, virusis_api_client)
• npm run gen:flutter - specs/openapi.json ile Dart/Flutter paketi (dart-dio-next, out/flutter, pubName=virusis_api_client)
• npm run gen:all - python + flutter jenerasyonlarini art arda calistirir
• npm run version:auto - conventional commit log'una gore versiyon + CHANGELOG.md gunceller (tag/commit olusturmaz)

Docker

• Dev: docker compose -f .devcontainer/docker-compose.yml run --rm api-client-dev sh icinde npm run ci/npm test
• Paketleme (dev): docker compose -f .devcontainer/docker-compose.yml run --rm api-client-dev sh -c "npm run pack:local"
• Prod/publish: docker compose -f .devcontainer/docker-compose.yml run --rm -e NPM_TOKEN=... api-client-prod npm run release
• Sadece build+test prod: docker compose -f .devcontainer/docker-compose.yml run --rm api-client-prod npm run ci

Angular'da Rx (provider ile)

Service:

import { Injectable, Inject } from "@angular/core";
import { ApiClientConfig, createAllRxClientsCamel } from "@virusis/api-client";

@Injectable({ providedIn: "root" })
export class ApiClientService {
  services = createAllRxClientsCamel(
    new ApiClientConfig(this.baseUrl, () => localStorage.getItem("token"))
  );

  constructor(@Inject("API_BASE_URL") private baseUrl: string) {}
}

Module:

providers: [{ provide: "API_BASE_URL", useValue: "https://api.example.com" }]

Component:

constructor(private api: ApiClientService) {}
ngOnInit() {
  this.api.services.usersService.getAll().subscribe(console.log);
}

Modelleri kullanma

• Tum model exportlarini tek yerden almak icin:

import { getModels } from "@virusis/api-client";
const Models = getModels();
// Model tipleri
const user: Models.User = { /* ... */ };

• Rx client'larla birlikte:

import { ApiClientConfig, createAllRxClientsCamel, getModels } from "@virusis/api-client";
const cfg = new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token"));
const services = createAllRxClientsCamel(cfg);
const Models = getModels();
services.usersService.getAll().subscribe((data: Models.User[]) => console.log(data));

Base URL notu

• ApiClientConfig.baseUrl zorunlu ve mutlak olmalidir. baseUrl /api ile bitip path de /api/... ile basliyorsa otomatik tek /api/... olacak sekilde birlestirilir; iki kere /api eklenmez.