go_vndb/README.md

go_vndb

go_vndb is a Go wrapper for the VNDB Kana API at https://api.vndb.org/kana.

It supports:

• custom http.Client
• custom base URL
• token authentication
• composable field selection helpers
• typed models for the major Kana endpoints

Install

go get git.nyne.dev/o/go_vndb

Quick Start

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"time"

	govndb "git.nyne.dev/o/go_vndb"
)

func main() {
	client := govndb.New(
		govndb.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
	)

	ctx := context.Background()
	response, err := client.QueryVNs(ctx, govndb.QueryRequest{
		Filters: []any{"id", "=", "v17"},
		Results: 1,
	}.WithFields(
		govndb.FieldName("title"),
		govndb.FieldGroup("image", govndb.FieldName("url")),
	))
	if err != nil {
		log.Fatal(err)
	}

	for _, vn := range response.Results {
		fmt.Println(vn.ID, vn.Title)
	}
}

Authentication

client := govndb.New(
	govndb.WithToken("your-vndb-token"),
)

Field Selection

Kana requires all fields to be selected explicitly. You can either pass the raw string:

req := govndb.QueryRequest{
	Fields: "title,image{url,dims},developers{id,name}",
}

or build it with helpers:

req := govndb.QueryRequest{}.WithFields(
	govndb.FieldName("title"),
	govndb.FieldGroup("image",
		govndb.FieldName("url"),
		govndb.FieldName("dims"),
	),
	govndb.FieldGroup("developers",
		govndb.FieldName("id"),
		govndb.FieldName("name"),
	),
)

If Fields is omitted, the wrapper automatically uses the endpoint's default full field set. This makes the typed helpers usable without manually specifying a field list, but it can request a large payload.

Typed Queries

The wrapper includes typed helpers for the common Kana endpoints:

• QueryVNs()
• QueryReleases()
• QueryProducers()
• QueryCharacters()
• QueryStaff()
• QueryTags()
• QueryTraits()
• QueryQuotes()
• QueryUList()
• Stats()
• User()
• AuthInfo()
• UListLabels()

All typed query helpers return QueryResponse[T].

Convenience Helpers

For common VN lookup flows, the package also exposes a few direct helpers:

• GetVN(vnid string) returns a VN with core fields: id, title, alttitle, released, image{id,url}, description, rating, tags{id,name,category}, developers{id,name,original}
• GetVNRating(vnid string) returns only the VN rating and yields nil when the VN has no rating yet
• GetVNCharacters(vnid string) returns the VN's characters with id, name, original, image{id,url}, vns{role}
• SearchVN(keyword string) returns id, title, alttitle

Package-level usage:

vn, err := govndb.GetVN("v17")
rating, err := govndb.GetVNRating("v17")
characters, err := govndb.GetVNCharacters("v17")
results, err := govndb.SearchVN("saya")

If you need custom transport, auth, or base URL, use the same helpers on Client:

client := govndb.New(
	govndb.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
)

vn, err := client.GetVN(context.Background(), "v17")
rating, err := client.GetVNRating(context.Background(), "v17")
characters, err := client.GetVNCharacters(context.Background(), "v17")
results, err := client.SearchVN(context.Background(), "saya")

Tests

Unit tests:

go test ./...

The repository also includes integration tests that call VNDB directly. Public endpoints run without authentication. Authenticated tests require VNDB_TOKEN.

set VNDB_TOKEN=your-token
go test ./...

Use short mode to skip network-backed tests:

go test -short ./...