ankiconnect

README

ankiconnect

A lightweight Golang interface for ankiconnect. This library depends on Anki and the ankiconnect addon.

Features

• Get Anki deck names.
• Create a new deck in Anki.
• Delete a existing deck from Anki.
• Add a new card to an existing deck in Anki.

Installation

go get github.com/atselvan/ankiconnect

Usage

Anki should be running in the background with the ankiconnect addon installed for below examples to work.

Ping

client := ankiconnect.NewClient()
restErr := client.Ping()
if restErr != nil {
	log.Fatal(restErr)
}

Get Decks

client := ankiconnect.NewClient()
decks, restErr := client.Decks.GetAll()
if restErr != nil {
	log.Fatal(restErr)
}
fmt.Println(decks)

Create Deck

client := ankiconnect.NewClient()
restErr := client.Decks.Create("New Deck")
if restErr != nil {
	log.Fatal(restErr)
}

Delete Deck

client := ankiconnect.NewClient()
restErr := client.Decks.Delete("New Deck")
if restErr != nil {
	log.Fatal(restErr)
}

Create Note

client := ankiconnect.NewClient()

note := ankiconnect.Note{
	DeckName: "New Deck",
	ModelName: "Basic-a39a1",
	Fields: ankiconnect.Fields{
		Front: "Front data",
		Back: "Back data",
	},
}

restErr := client.Notes.Add(note)
if restErr != nil {
	log.Fatal(restErr)
}

Get Notes

client := ankiconnect.NewClient()

// Get the Note Ids of cards due today
nodeIds, restErr := client.Notes.Get("prop:due=0")
if restErr != nil {
	log.Fatal(restErr)
}

// Get the Note data of cards due today
notes, restErr := client.Notes.Get("prop:due=0")
if restErr != nil {
	log.Fatal(restErr)
}

Get Cards

client := ankiconnect.NewClient()

// Get the Card Ids of cards due today
nodeIds, restErr := client.Cards.Get("prop:due=0")
if restErr != nil {
	log.Fatal(restErr)
}

// Get the Card data of cards due today
notes, restErr := client.Cards.Get("prop:due=0")
if restErr != nil {
	log.Fatal(restErr)
}

Sync local data to Anki Cloud

client := ankiconnect.NewClient()

restErr := client.Sync.Trigger()
if restErr != nil {
	log.Fatal(restErr)
}

Documentation

Index

• Constants
• type Audio
• type CardTemplate
• type CardsManager
• type Client
  • func NewClient() *Client
  • func (c *Client) Ping() *errors.RestErr
  • func (c *Client) SetDecksManager(dm DecksManager) *Client
  • func (c *Client) SetHTTPClient(httpClient *resty.Client) *Client
  • func (c *Client) SetNotesManager(nm NotesManager) *Client
  • func (c *Client) SetSyncManager(sm SyncManager) *Client
  • func (c *Client) SetURL(url string) *Client
  • func (c *Client) SetVersion(version int) *Client
• type DecksManager
• type DuplicateScopeOptions
• type FieldData
• type Fields
• type MediaManager
• type Model
• type ModelsManager
• type Note
• type NotesManager
• type Options
• type ParamsCardsInfo
• type ParamsCreateDeck
• type ParamsCreateNote
• type ParamsDefault
• type ParamsDeleteDecks
• type ParamsFindCards
• type ParamsFindNotes
• type ParamsModelNames
• type ParamsNotesInfo
• type ParamsRetrieveMediaFile
• type ParamsUpdateNote
• type Picture
• type RequestPayload
• type Result
• type ResultCardsInfo
• type ResultCreateModel
• type ResultNotesInfo
• type SyncManager
• type UpdateNote
• type Video

Constants

const (
	ActionFindCards = "findCards"
	ActionCardsInfo = "cardsInfo"
)

const (
	ActionDeckNames    = "deckNames"
	ActionCreateDeck   = "createDeck"
	ActionGetDeckStats = "getDeckStats"
	ActionDeleteDecks  = "deleteDecks"
)

const (
	ActionModelNames      = "modelNames"
	ActionModelFieldNames = "modelFieldNames"
	ActionCreateModel     = "createModel"
)

const (
	ActionFindNotes        = "findNotes"
	ActionNotesInfo        = "notesInfo"
	ActionAddNote          = "addNote"
	ActionAddNotes         = "addNotes"
	ActionDeleteNotes      = "deleteNotes"
	ActionUpdateNoteFields = "updateNoteFields"
)

const (
	ActionRetrieveMedia = "retrieveMediaFile"
)

const (
	ActionSync = "sync"
)

Types

type Audio

type Audio struct {
	URL      string   `json:"url,omitempty"`
	Data     string   `json:"data,omitempty"`
	Path     string   `json:"path,omitempty"`
	Filename string   `json:"filename,omitempty"`
	SkipHash string   `json:"skipHash,omitempty"`
	Fields   []string `json:"fields,omitempty"`
}

Audio can be used to add a audio file to a Anki Note.

type CardTemplate

type CardTemplate struct {
	Name  string `json:"Name,omitempty"`
	Front string `json:"Front,omitempty"`
	Back  string `json:"Back,omitempty"`
}

CardTemplate contains the actual fields that will determine the front and back of the anki card

type CardsManager

type CardsManager interface {
	Search(query string) (*[]int64, *errors.RestErr)
	Get(query string) (*[]ResultCardsInfo, *errors.RestErr)
}

Notes manager describes the interface that can be used to perform operation on the notes in a deck.

type Client

type Client struct {
	Url     string
	Version int

	// supported interfaces
	Decks  DecksManager
	Notes  NotesManager
	Sync   SyncManager
	Cards  CardsManager
	Media  MediaManager
	Models ModelsManager
	// contains filtered or unexported fields
}

Client represents the anki connect api client.

func NewClient

func NewClient() *Client

NewClient returns a instance of Client with the default settings.

func (*Client) Ping

func (c *Client) Ping() *errors.RestErr

Ping checks if the anki connect api is online and healthy. If there is no response from the anki connect api a error will be returned.

func (*Client) SetDecksManager

func (c *Client) SetDecksManager(dm DecksManager) *Client

SetDecksManager can be used to set a custom DecksManager interface. This function is added for testing the DecksManager interface.

func (*Client) SetHTTPClient

func (c *Client) SetHTTPClient(httpClient *resty.Client) *Client

SetHTTPClient can be used set a custom httpClient.

func (*Client) SetNotesManager

func (c *Client) SetNotesManager(nm NotesManager) *Client

SetNotesManager can be used to set a custom NotesManager interface. This function is added for testing the NotesManager interface.

func (*Client) SetSyncManager

func (c *Client) SetSyncManager(sm SyncManager) *Client

SetSyncManager can be used to set a custom SyncManager interface. This function is added for testing the SyncManager interface.

func (*Client) SetURL

func (c *Client) SetURL(url string) *Client

SetURL can be used to set a custom url for the ankiconnect api.

func (*Client) SetVersion

func (c *Client) SetVersion(version int) *Client

SetVersion can be used to set a custom version for the ankiconnect api.

type DecksManager

type DecksManager interface {
	GetAll() (*[]string, *errors.RestErr)
	Create(name string) *errors.RestErr
	Delete(name string) *errors.RestErr
}

DecksManager describes the interface that can be used to perform operations on anki decks.

type DuplicateScopeOptions

type DuplicateScopeOptions struct {
	DeckName string `json:"deckName,omitempty"`
	// Will default to false
	CheckChildren bool `json:"checkChildren"`
	// Will default to false
	CheckAllModels bool `json:"checkAllModels"`
}

DuplicateScopeOptions represents the options that control the duplication of a Anki Note.

type FieldData

type FieldData struct {
	Value string `json:"value,omitempty"`
	Order int64  `json:"order,omitempty"`
}

FieldData represents the format of a field returned by ankiconnect

type Fields

type Fields map[string]string

Fields represents the main fields for a Anki Note

type MediaManager

type MediaManager interface {
	// Returns the contents of the file encoded in base64
	RetrieveMediaFile(filename string) (*string, *errors.RestErr)
}

Media describes the interface that can be used to perform operations stored media.

type Model

type Model struct {
	ModelName     string   `json:"modelName,omitempty"`
	InOrderFields []string `json:"inOrderFields,omitempty"`
	Css           string   `json:"css,omitempty"`
	// Will default to false
	IsCloze       bool           `json:"isCloze"`
	CardTemplates []CardTemplate `json:"cardTemplates,omitempty"`
}

ParamsCreateModel is used for creating a new Note type to add a new card to an existing Note type will require the implementation of updateModelTemplates

type ModelsManager

type ModelsManager interface {
	Create(model Model) *errors.RestErr
	GetAll() (*[]string, *errors.RestErr)
	GetFields(model string) (*[]string, *errors.RestErr)
}

Models Manager is used for creating various card and note types within Anki

type Note

type Note struct {
	DeckName  string    `json:"deckName,omitempty"`
	ModelName string    `json:"modelName,omitempty"`
	Fields    Fields    `json:"fields,omitempty"`
	Options   *Options  `json:"options,omitempty"`
	Tags      []string  `json:"tags,omitempty"`
	Audio     []Audio   `json:"audio,omitempty"`
	Video     []Video   `json:"video,omitempty"`
	Picture   []Picture `json:"picture,omitempty"`
}

Note represents a Anki Note.

type NotesManager

type NotesManager interface {
	Add(note Note) *errors.RestErr
	Search(query string) (*[]int64, *errors.RestErr)
	Get(query string) (*[]ResultNotesInfo, *errors.RestErr)
	Update(note UpdateNote) *errors.RestErr
}

Notes manager describes the interface that can be used to perform operation on the notes in a deck.

type Options

type Options struct {
	// Will default to false
	AllowDuplicate        bool                   `json:"allowDuplicate"`
	DuplicateScope        string                 `json:"duplicateScope,omitempty"`
	DuplicateScopeOptions *DuplicateScopeOptions `json:"duplicateScopeOptions,omitempty"`
}

Options represents note options.

type ParamsCardsInfo

type ParamsCardsInfo struct {
	Cards *[]int64 `json:"cards,omitempty"`
}

ParamsCardsInfo represents the ankiconnect API params for getting card info.

type ParamsCreateDeck

type ParamsCreateDeck struct {
	Deck string `json:"deck,omitempty"`
}

ParamsCreateDeck represents the ankiconnect API params required for creating a new deck.

type ParamsCreateNote

type ParamsCreateNote struct {
	Note *Note `json:"note,omitempty"`
}

ParamsCreateNote represents the ankiconnect API params for creating a note.

type ParamsDefault

type ParamsDefault struct{}

ParamsDefault represent the default parameters for a action to be executed by the anki connect api.

type ParamsDeleteDecks

type ParamsDeleteDecks struct {
	Decks    *[]string `json:"decks,omitempty"`
	CardsToo bool      `json:"cardsToo,omitempty"`
}

ParamsDeleteDeck represents the ankiconnect API params required for deleting one or more decks

type ParamsFindCards

type ParamsFindCards struct {
	Query string `json:"query,omitempty"`
}

type ParamsFindNotes

type ParamsFindNotes struct {
	Query string `json:"query,omitempty"`
}

ParamsGetNotes represents the ankiconnect API params for querying notes.

type ParamsModelNames

type ParamsModelNames struct {
	ModelName string `json:"modelName"`
}

ParamsModelNames represents the ankiconnect API params required for querying the Model Names avaliable

type ParamsNotesInfo

type ParamsNotesInfo struct {
	Notes *[]int64 `json:"notes,omitempty"`
}

ParamsNotesInfo represents the ankiconnect API params for getting note info.

type ParamsRetrieveMediaFile

type ParamsRetrieveMediaFile struct {
	Filename string `json:"filename,omitempty"`
}

type ParamsUpdateNote

type ParamsUpdateNote struct {
	Note *UpdateNote `json:"note,omitempty"`
}

ParamsCreateNote represents the ankiconnect API params for updating a note.

type Picture

type Picture struct {
	URL      string   `json:"url,omitempty"`
	Data     string   `json:"data,omitempty"`
	Path     string   `json:"path,omitempty"`
	Filename string   `json:"filename,omitempty"`
	SkipHash string   `json:"skipHash,omitempty"`
	Fields   []string `json:"fields,omitempty"`
}

Picture can be used to add a picture to a Anki Note.

type RequestPayload

type RequestPayload[P any] struct {
	Action  string `json:"action,omitempty"`
	Version int    `json:"version,omitempty"`
	Params  *P     `json:"params,omitempty"`
}

RequestPayload represents the request payload for anki connect api. [P any] represents a generic type that can accept any type for the Params field.

type Result

type Result[T any] struct {
	Result T      `json:"result,omitempty"`
	Error  string `json:"error,omitempty"`
}

Result is the result returned by anki connect api. The Result filed will return different typed values depending on the action hence it is defined as a generic. [T any] represents a generic type that can accept any type for the Result field.

type ResultCardsInfo

type ResultCardsInfo struct {
	Answer     string               `json:"answer,omitempty"`
	Question   string               `json:"question,omitempty"`
	DeckName   string               `json:"deckName,omitempty"`
	ModelName  string               `json:"modelName,omitempty"`
	FieldOrder int64                `json:"fieldOrder,omitempty"`
	Fields     map[string]FieldData `json:"fields,omitempty"`
	Css        string               `json:"css,omitempty"`
	CardId     int64                `json:"cardId,omitempty"`
	Interval   int64                `json:"interval,omitempty"`
	Note       int64                `json:"note,omitempty"`
	Ord        int64                `json:"ord,omitempty"`
	Type       int64                `json:"type,omitempty"`
	Queue      int64                `json:"queue,omitempty"`
	Due        int64                `json:"due,omitempty"`
	Reps       int64                `json:"reps,omitempty"`
	Lapses     int64                `json:"lapses,omitempty"`
	Left       int64                `json:"left,omitempty"`
	Mod        int64                `json:"mod,omitempty"`
}

type ResultCreateModel

type ResultCreateModel struct {
	Sortf     int64         `json:"sortf"`
	Did       int64         `json:"did"`
	LatexPre  string        `json:"latexPre"`
	LatexPost string        `json:"latexPost"`
	Mod       int64         `json:"mod"`
	Usn       int64         `json:"usn"`
	Vers      []interface{} `json:"vers"`
	Type      int64         `json:"type"`
	Css       string        `json:"css"`
	Name      string        `json:"name"`
	Flds      []struct {
		Name   string        `json:"name"`
		Ord    int64         `json:"ord"`
		Sticky bool          `json:"sticky"`
		Rtl    bool          `json:"rtl"`
		Font   string        `json:"font"`
		Size   int64         `json:"size"`
		Media  []interface{} `json:"media"`
	} `json:"flds"`
	Tmpls []struct {
		Name  string      `json:"name"`
		Ord   int64       `json:"ord"`
		Qfmt  string      `json:"qfmt"`
		Afmt  string      `json:"afmt"`
		Did   interface{} `json:"did"`
		Bqfmt string      `json:"bqfmt"`
		Bafmt string      `json:"bafmt"`
	} `json:"tmpls"`
	Tags []interface{} `json:"tags"`
	// The api description describes the id as being a "number" (eg "23443")
	// Where as in practice anki seems to return an actual int (eg 23443).
	// json.Number handles both instances
	Id  json.Number     `json:"id"`
	Req [][]interface{} `json:"req"`
}

ResultCreateModel represents the ankiconnect API result from creating a new model (Note type)

The example given has some empty arrays. Since we dont know the data types, and its not currently important we leave them as []interface{} We do not technically need this, and could replace it with a [interface{}] in Create, but it may be used later

type ResultNotesInfo

type ResultNotesInfo struct {
	NoteId    int64                `json:"noteId,omitempty"`
	ModelName string               `json:"modelName,omitempty"`
	Fields    map[string]FieldData `json:"fields,omitempty"`
	Tags      []string             `json:"tags,omitempty"`
}

ResultFindNotes represents the return value of querying notes

type SyncManager

type SyncManager interface {
	Trigger() *errors.RestErr
}

SyncManager describes the interface that can be used to perform sync operations on Anki.

type UpdateNote

type UpdateNote struct {
	Id      int64     `json:"id,omitempty"`
	Fields  Fields    `json:"fields,omitempty"`
	Audio   []Audio   `json:"audio,omitempty"`
	Video   []Video   `json:"video,omitempty"`
	Picture []Picture `json:"picture,omitempty"`
}

type Video

type Video struct {
	URL      string   `json:"url,omitempty"`
	Data     string   `json:"data,omitempty"`
	Path     string   `json:"path,omitempty"`
	Filename string   `json:"filename,omitempty"`
	SkipHash string   `json:"skipHash,omitempty"`
	Fields   []string `json:"fields,omitempty"`
}

Video can be used to add a video file to a Anki Note.