Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/lyezinho/danbooru-sdk

Typescript SDK for Danbooru/Safebooru api.
https://github.com/lyezinho/danbooru-sdk

api api-client api-sdk danbooru safebooru sdk typescript

Last synced: 23 days ago
JSON representation

Typescript SDK for Danbooru/Safebooru api.

Awesome Lists containing this project

README 

          
# Danbooru SDK



[![CI](https://github.com/LyeZinho/danbooru-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/LyeZinho/danbooru-sdk/actions/workflows/ci.yml)



Uma SDK TypeScript completa e padronizada para a API do Danbooru/Safebooru.



## 🚀 Características



- ✅ **Totalmente tipado** com TypeScript

- 🔄 **Suporte completo** para Danbooru e Safebooru

- 📦 **Modular** - Recursos organizados em classes separadas

- 🔐 **Autenticação** integrada

- 🎯 **API padronizada** com base na documentação oficial

- ⚡ **Promise-based** com async/await

- 🛠️ **Extensível** - Fácil de customizar e estender



## 📦 Instalação



```bash

npm install danbooru-sdk

# ou

yarn add danbooru-sdk

# ou

pnpm add danbooru-sdk

```



## 📚 Documentação da SDK

A documentação completa da SDK (referência de uso, configuração e exemplos baseados no código) está em `sdk_docs/README.md` (índice da documentação localizada em `sdk_docs/`).



## 🎯 Uso Básico



### Inicialização



```typescript

import { createDanbooruClient, createSafebooruClient } from 'danbooru-sdk';



// Danbooru (requer autenticação para alguns recursos)

const danbooru = createDanbooruClient({

  baseURL: 'https://danbooru.donmai.us',

  username: 'seu-usuario',

  apiKey: 'sua-api-key',

});

// Observação: se você estiver instanciando Manualmente `new DanbooruClient(...)`,

// o campo `baseURL` também pode ser passado como `baseUrl` (alias) para compatibilidade

// com exemplos existentes (a SDK aceita ambos).

// Safebooru (versão SFW)

const safebooru = createSafebooruClient({

  // username e apiKey são opcionais

});

```



### Posts



```typescript

// Buscar posts por tags

const posts = await danbooru.posts.search('touhou rating:safe', 20);



// Listar posts com parâmetros

const posts = await danbooru.posts.list({

  tags: 'original',

  limit: 100,

  page: 1,

});



// Obter um post específico

const post = await danbooru.posts.get(123456);



// Criar um novo post (requer autenticação)

const newPost = await danbooru.posts.create({

  upload: {

    source: 'https://exemplo.com/imagem.jpg',

    rating: 's',

    tag_string: 'original solo 1girl',

  },

});



// Atualizar um post

const updatedPost = await danbooru.posts.update(123456, {

  post: {

    tag_string: 'original solo 1girl blue_hair',

  },

});



// Deletar um post

await danbooru.posts.delete(123456);

```



### Tags



```typescript

// Buscar tags

const tags = await danbooru.tags.search('touhou*', 50);



// Listar tags com filtros

const tags = await danbooru.tags.list({

  search: {

    name_matches: 'original*',

    category: TagCategory.General,

    post_count: '100..',

  },

  limit: 50,

});



// Obter uma tag específica

const tag = await danbooru.tags.get(12345);

```



### Artists



```typescript

// Buscar artistas

const artists = await danbooru.artists.search('wanke*', 20);



// Listar artistas

const artists = await danbooru.artists.list({

  search: {

    name_matches: 'artist_name',

    is_banned: false,

  },

  limit: 50,

});



// Criar um artista

const newArtist = await danbooru.artists.create({

  artist: {

    name: 'artist_name',

    other_names: ['alternate_name'],

    urls: ['https://twitter.com/artist'],

  },

});



// Atualizar um artista

const updatedArtist = await danbooru.artists.update(123, {

  artist: {

    group_name: 'art_group',

  },

});

```



### Pools



```typescript

// Buscar pools

const pools = await danbooru.pools.search('touhou*', 20);



// Listar pools

const pools = await danbooru.pools.list({

  search: {

    name_matches: 'pool_name',

    category: 'series',

  },

  limit: 50,

});



// Obter um pool

const pool = await danbooru.pools.get(12345);



// Criar um pool

const newPool = await danbooru.pools.create({

  pool: {

    name: 'My Pool',

    description: 'Pool description',

    category: 'series',

  },

});

```



### Comments



```typescript

// Listar comentários

const comments = await danbooru.comments.list({

  search: {

    post_id: 123456,

  },

  limit: 50,

});



// Criar comentário

const newComment = await danbooru.comments.create({

  comment: {

    post_id: 123456,

    body: 'Great artwork!',

  },

});



// Atualizar comentário

const updatedComment = await danbooru.comments.update(789, {

  comment: {

    body: 'Updated comment text',

  },

});



// Deletar comentário

await danbooru.comments.delete(789);

```



### Notes



```typescript

// Listar notes

const notes = await danbooru.notes.list({

  search: {

    post_id: 123456,

  },

});



// Criar note

const newNote = await danbooru.notes.create({

  note: {

    post_id: 123456,

    body: 'Translation here',

    x: 100,

    y: 100,

    width: 200,

    height: 50,

  },

});

```



### Users



```typescript

// Buscar usuários

const users = await danbooru.users.search('username*', 20);



// Listar usuários

const users = await danbooru.users.list({

  search: {

    level: UserLevel.Gold,

  },

  limit: 50,

});



// Obter usuário específico

const user = await danbooru.users.get(12345);

```



### Wiki Pages



```typescript

// Buscar páginas wiki

const pages = await danbooru.wikiPages.search('touhou', 20);



// Listar páginas wiki

const pages = await danbooru.wikiPages.list({

  search: {

    title: 'tag_name',

  },

  limit: 50,

});



// Criar página wiki

const newPage = await danbooru.wikiPages.create({

  wiki_page: {

    title: 'tag_name',

    body: 'Wiki content here',

  },

});

```



## 🔧 Configuração Avançada



### Customização do Cliente HTTP



```typescript

import { createDanbooruClient } from 'danbooru-sdk';



const client = createDanbooruClient({

  baseURL: 'https://danbooru.donmai.us',

  username: 'seu-usuario',

  apiKey: 'sua-api-key',

  timeout: 60000, // 60 segundos

  userAgent: 'MeuApp/1.0.0',

  axiosConfig: {

    // Configurações adicionais do Axios

    proxy: {

      host: 'proxy.exemplo.com',

      port: 8080,

    },

  },

});

```



### Acesso ao Cliente HTTP Interno



```typescript

const httpClient = client.getHttpClient();

const axiosInstance = httpClient.getAxiosInstance();



// Use para requisições customizadas

```



## 📚 Tipos TypeScript



A SDK inclui tipos completos para todos os recursos:



```typescript

import {

  Post,

  Tag,

  Artist,

  Pool,

  Comment,

  Note,

  User,

  WikiPage,

  PostRating,

  TagCategory,

  UserLevel,

} from 'danbooru-sdk';

```



## 🔍 Sintaxe de Busca



A SDK suporta toda a sintaxe de busca do Danbooru:



### Posts

```typescript

// Tags múltiplas

const posts = await danbooru.posts.search('touhou cirno');



// Operadores

const posts = await danbooru.posts.search('touhou -flandre_scarlet');



// Metatags

const posts = await danbooru.posts.search('rating:safe score:>10 width:>1000');



// Intervalos

const posts = await danbooru.posts.search('id:100..200');

```



### Tags

```typescript

// Wildcards

const tags = await danbooru.tags.search('touh*');



// Categorias

const tags = await danbooru.tags.list({

  search: {

    category: TagCategory.Artist,

    post_count: '100..',

  },

});

```



## 🛠️ Desenvolvimento



```bash

# Instalar dependências

npm install



# Build

npm run build



# Watch mode

npm run dev



# Lint

npm run lint



# Format

npm run format

```



## 📖 Documentação da API



Esta SDK é baseada na documentação oficial do Danbooru:

- [Documentação da API Danbooru](https://safebooru.donmai.us/wiki_pages/help:api)



## 📄 Licença



MIT © Pedro Kaleb



## 🤝 Contribuindo



Contribuições são bem-vindas! Por favor, sinta-se à vontade para abrir issues ou pull requests.



## ⚠️ Avisos



- Respeite os limites de taxa da API

- Membros: 10 requisições de escrita (burst), 1 req/s (regeneração)

- Gold: 30 requisições de escrita (burst), 2 req/s (regeneração)

- Platinum+: 60 requisições de escrita (burst), 4 req/s (regeneração)

- Requisições de leitura são ilimitadas para todos os níveis de usuário



## 🔗 Links Úteis



- [Danbooru](https://danbooru.donmai.us/)

- [Safebooru](https://safebooru.donmai.us/)

- [Testbooru](https://testbooru.donmai.us/) - Para testes da API