npm package: @imperatrona/civitai
Description: A lightweight, promise-based TypeScript client for the [Civitai API](https://civitai.com/).
Latest version: 0.0.1

# @imperatrona/civitai

A lightweight, promise-based TypeScript client for the [Civitai API](https://civitai.com/).

## Features

* **Universal Compatibility:** Works in any JavaScript environment that supports the global `fetch` API (Node.js v18+, Bun, Deno, and modern Browsers).
* **Fully Typed:** Includes comprehensive TypeScript interfaces for all API resources, models, and response metadata.
* **Zero Dependencies:** Designed to be minimal and reliable.
* **Customizable:** Supports custom `fetch` implementations and configurable authentication modes.

## Installation

You can install the package via npm:

```bash
npm install @imperatrona/civitai

```

---

## Quick Usage

```typescript
import { CivitaiClient } from '@imperatrona/civitai';

// Initialize the client
const client = new CivitaiClient({
  token: 'YOUR_API_TOKEN' 
});

async function run() {
  try {
    // Fetch a list of models
    const response = await client.models({
      limit: 10,
      sort: 'Most Downloaded'
    });

    console.log(`Found ${response.items.length} models.`);
    
    // Get details for a specific model by ID
    const model = await client.model(12345);
    console.log(`Model name: ${model.name}`);
  } catch (err) {
    console.error('API Request failed:', err);
  }
}

run();
```


### Downloading a Model

The `modelDownloadUrl` helper generates the direct download link. If you are using `authMode: 'query'` with an API token, the token is automatically appended to the URL.

```typescript
const versionId = 12345;
const downloadUrl = client.modelDownloadUrl(versionId);

console.log(`Download link: ${downloadUrl}`);

// Example: Fetching the file via fetch
const response = await fetch(downloadUrl);
const blob = await response.blob();
```

## Supported Methods

The `CivitaiClient` class provides the following methods to interact with the API:

| Method | Description |
| --- | --- |
| `creators(query?)` | Lists creators based on optional filters. |
| `images(query?)` | Retrieves image listings with optional pagination/filtering. |
| `models(query?)` | Lists models based on categories, tags, or search terms. |
| `model(id)` | Fetches detailed information for a specific model ID. |
| `modelVersion(id)` | Fetches details for a specific model version ID. |
| `modelVersionByHash(hash)` | Retrieves a model version using its unique file hash. |
| `tags(query?)` | Lists available tags and their usage counts. |
| `modelDownloadUrl(id)` | Generates a direct download URL for a model version. |

## Advanced Configuration

The `CivitaiClient` constructor accepts an optional configuration object:

| Option | Type | Description |
| --- | --- | --- |
| `token` | `string` | API Key for authenticated requests. |
| `authMode` | `'header' | 'query'` | Strategy for sending your token. Defaults to `header`. |
| `baseUrl` | `string` | Override the default API base URL. |
| `fetchFn` | `typeof fetch` | Inject a custom `fetch` implementation (e.g., to add proxies). |


## Error Handling

The client throws a `CivitaiApiError` if the API returns a non-2xx status code. You can use this to handle specific HTTP errors:

```typescript
import { CivitaiApiError } from '@imperatrona/civitai';

try {
  await client.model(999999);
} catch (err) {
  if (err instanceof CivitaiApiError) {
    console.error(`Status: ${err.status} - URL: ${err.url}`);
  }
}
```