Danbooru SDK

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

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

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

// 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

// 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

// 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

// 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

// 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

// 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

// 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

// 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

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

const httpClient = client.getHttpClient();
const axiosInstance = httpClient.getAxiosInstance();

// Use para requisições customizadas

📚 Tipos TypeScript

A SDK inclui tipos completos para todos os recursos:

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

// 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

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

// Categorias
const tags = await danbooru.tags.list({
  search: {
    category: TagCategory.Artist,
    post_count: '100..',
  },
});

🛠️ Desenvolvimento

# 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

📄 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
• Safebooru
• Testbooru - Para testes da API