███████╗████████╗ █████╗ ██████╗     ██╗    ██╗ █████╗ ██████╗ ███████╗     █████╗ ██████╗ ██╗
██╔════╝╚══██╔══╝██╔══██╗██╔══██╗    ██║    ██║██╔══██╗██╔══██╗██╔════╝    ██╔══██╗██╔══██╗██║
███████╗   ██║   ███████║██████╔╝    ██║ █╗ ██║███████║██████╔╝███████╗    ███████║██████╔╝██║
╚════██║   ██║   ██╔══██║██╔══██╗    ██║███╗██║██╔══██║██╔══██╗╚════██║    ██╔══██║██╔═══╝ ██║
███████║   ██║   ██║  ██║██║  ██║    ╚███╔███╔╝██║  ██║██║  ██║███████║    ██║  ██║██║     ██║
╚══════╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝     ╚══╝╚══╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝    ╚═╝  ╚═╝╚═╝     ╚═╝
                                   ███████╗██████╗ ██╗  ██╗
                                   ██╔════╝██╔══██╗██║ ██╔╝
                                   ███████╗██║  ██║█████╔╝ 
                                   ╚════██║██║  ██║██╔═██╗ 
                                   ███████║██████╔╝██║  ██╗
                                   ╚══════╝╚═════╝ ╚═╝  ╚═╝
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄

A TypeScript SDK for the Star Wars API — fully typed, with support for pagination, filtering, and cross-resource search.

📦 npm: https://www.npmjs.com/package/swapi-ts-sdk
🚀 API: https://star-wars-api-9o3y.onrender.com
📖 API Docs: https://star-wars-api-9o3y.onrender.com/docs

✨ Features

• 🎬 Films — Episodes I–IX, Rogue One & Solo
• 👤 Characters — from Luke Skywalker to Grogu
• 🪐 Planets — Tatooine to Exegol
• 🧬 Species — Human to Ewok to Dathomirian
• 🚀 Starships — Millennium Falcon to the Supremacy
• 🚗 Vehicles — AT-AT to Podracer
• 🔍 Cross-resource search — query across all resources at once
• 📄 Pagination & filtering on every endpoint
• 🔷 Fully typed — complete TypeScript interfaces for all resources

📦 Installation

npm install swapi-ts-sdk

🚀 Quick Start

import { ApiClient } from 'swapi-ts-sdk'

const client = ApiClient.getInstance()

// List characters
const characters = await client.characters.list()

// Get a single film
const film = await client.films.read(4)

// Search across all resources
const results = await client.search.search({ q: 'Skywalker' })

💡 Usage Examples

Pagination

// Page 1, 10 results (default)
const page1 = await client.characters.list()

// Page 2, 20 results per page
const page2 = await client.characters.list({ page: 2, limit: 20 })

// First 5 films
const films = await client.films.list({ page: 1, limit: 5 })

Filtering

// Search characters by name
const luke = await client.characters.list({ name: 'Luke' })

// Filter by gender and paginate
const chars = await client.characters.list({ gender: 'female', page: 1, limit: 10 })

// Filter planets by climate
const deserts = await client.planets.list({ climate: 'arid' })

// Filter starships by class and manufacturer
const destroyers = await client.starships.list({ starshipClass: 'Star Destroyer' })

// Filter films by director
const lucasFilms = await client.films.list({ director: 'George Lucas' })

Single Resource

// Get a character by ID (with relations)
const character = await client.characters.read(1)

// Get a film with full cast & relations
const film = await client.films.read(4)

// Get a planet
const planet = await client.planets.read(1)

Cross-resource Search

// Search across all resources
const all = await client.search.search({ q: 'Skywalker' })

// Search within a specific resource type
const ships = await client.search.search({ q: 'Falcon', type: 'starships' })

Response Format

List endpoints return:

{
  "data": [...],
  "meta": {
    "total": 101,
    "page": 1,
    "limit": 10,
    "totalPages": 11
  }
}

🌐 Available Endpoints

| Property | Methods | Description | |----------|---------|-------------| | client.characters | list(params?), read(id) | Star Wars characters | | client.films | list(params?), read(id) | Star Wars films | | client.planets | list(params?), read(id) | Planets | | client.species | list(params?), read(id) | Species | | client.starships | list(params?), read(id) | Starships | | client.vehicles | list(params?), read(id) | Vehicles | | client.search | search({ q, type? }) | Cross-resource search | | client.status | get() | API and database health check |

Query Parameters

All list() methods support:

| Param | Type | Description | |-------|------|-------------| | page | number | Page number (default: 1) | | limit | number | Results per page (default: 10, max: 100) |

Additional filters per endpoint:

| Endpoint | Filter Params | |----------|---------------| | characters | name, gender, homeworldId, speciesId | | films | title, director | | planets | name, climate, terrain | | species | name, classification | | starships | name, starshipClass, manufacturer | | vehicles | name, vehicleClass, manufacturer | | search | q (required), type (optional) |

⚙️ Configuration

By default the SDK points to the live API. To use a local or custom instance, set the HOST_API environment variable:

HOST_API=http://localhost:3000

Or pass the host directly when constructing the client:

const client = new ApiClient('http://localhost:3000')

🏗️ Tech Stack

| Layer | Technology | |-------|------------| | Language | TypeScript | | HTTP Client | Fetch API (native) | | Package Manager | npm | | Backed by | Star Wars API |

📜 License

MIT