/* * Copyright (C) 2023-2024 Yomitan Authors * Copyright (C) 2016-2022 Yomichan Authors * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see <https://www.gnu.org/licenses/>. */ import {ExtensionError} from '../core/extension-error.js'; import {parseJson} from '../core/json.js'; import {getRootDeckName} from '../data/anki-util.js'; /** * This class controls communication with Anki via the AnkiConnect plugin. */ export class AnkiConnect { /** * Creates a new instance. */ constructor() { /** @type {boolean} */ this._enabled = false; /** @type {?string} */ this._server = null; /** @type {number} */ this._localVersion = 2; /** @type {number} */ this._remoteVersion = 0; /** @type {?Promise<number>} */ this._versionCheckPromise = null; /** @type {?string} */ this._apiKey = null; } /** * Gets the URL of the AnkiConnect server. * @type {?string} */ get server() { return this._server; } /** * Assigns the URL of the AnkiConnect server. * @param {string} value The new server URL to assign. */ set server(value) { this._server = value; } /** * Gets whether or not server communication is enabled. * @type {boolean} */ get enabled() { return this._enabled; } /** * Sets whether or not server communication is enabled. * @param {boolean} value The enabled state. */ set enabled(value) { this._enabled = value; } /** * Gets the API key used when connecting to AnkiConnect. * The value will be `null` if no API key is used. * @type {?string} */ get apiKey() { return this._apiKey; } /** * Sets the API key used when connecting to AnkiConnect. * @param {?string} value The API key to use, or `null` if no API key should be used. */ set apiKey(value) { this._apiKey = value; } /** * Checks whether a connection to AnkiConnect can be established. * @returns {Promise<boolean>} `true` if the connection was made, `false` otherwise. */ async isConnected() { try { await this._getVersion(); return true; } catch (e) { return false; } } /** * Gets the AnkiConnect API version number. * @returns {Promise<?number>} The version number */ async getVersion() { if (!this._enabled) { return null; } await this._checkVersion(); return await this._getVersion(); } /** * @param {import('anki').Note} note * @returns {Promise<?import('anki').NoteId>} */ async addNote(note) { if (!this._enabled) { return null; } await this._checkVersion(); const result = await this._invoke('addNote', {note}); if (result !== null && typeof result !== 'number') { throw this._createUnexpectedResultError('number|null', result); } return result; } /** * @param {import('anki').Note[]} notes * @returns {Promise<boolean[]>} */ async canAddNotes(notes) { if (!this._enabled) { return []; } await this._checkVersion(); const result = await this._invoke('canAddNotes', {notes}); return this._normalizeArray(result, notes.length, 'boolean'); } /** * @param {import('anki').Note[]} notes * @returns {Promise<({ canAdd: true } | { canAdd: false, error: string })[]>} */ async canAddNotesWithErrorDetail(notes) { if (!this._enabled) { return []; } await this._checkVersion(); const result = await this._invoke('canAddNotesWithErrorDetail', {notes}); return this._normalizeCanAddNotesWithErrorDetailArray(result, notes.length); } /** * @param {import('anki').NoteId[]} noteIds * @returns {Promise<(?import('anki').NoteInfo)[]>} */ async notesInfo(noteIds) { if (!this._enabled) { return []; } await this._checkVersion(); const result = await this._invoke('notesInfo', {notes: noteIds}); return this._normalizeNoteInfoArray(result); } /** * @returns {Promise<string[]>} */ async getDeckNames() { if (!this._enabled) { return []; } await this._checkVersion(); const result = await this._invoke('deckNames', {}); return this._normalizeArray(result, -1, 'string'); } /** * @returns {Promise<string[]>} */ async getModelNames() { if (!this._enabled) { return []; } await this._checkVersion(); const result = await this._invoke('modelNames', {}); return this._normalizeArray(result, -1, 'string'); } /** * @param {string} modelName * @returns {Promise<string[]>} */ async getModelFieldNames(modelName) { if (!this._enabled) { return []; } await this._checkVersion(); const result = await this._invoke('modelFieldNames', {modelName}); return this._normalizeArray(result, -1, 'string'); } /** * @param {string} query * @returns {Promise<import('anki').CardId[]>} */ async guiBrowse(query) { if (!this._enabled) { return []; } await this._checkVersion(); const result = await this._invoke('guiBrowse', {query}); return this._normalizeArray(result, -1, 'number'); } /** * @param {import('anki').NoteId} noteId * @returns {Promise<import('anki').CardId[]>} */ async guiBrowseNote(noteId) { return await this.guiBrowse(`nid:${noteId}`); } /** * @param {import('anki').NoteId[]} noteIds * @returns {Promise<import('anki').CardId[]>} */ async guiBrowseNotes(noteIds) { return await this.guiBrowse(`nid:${noteIds.join(',')}`); } /** * Opens the note editor GUI. * @param {import('anki').NoteId} noteId The ID of the note. * @returns {Promise<void>} Nothing is returned. */ async guiEditNote(noteId) { await this._invoke('guiEditNote', {note: noteId}); } /** * Stores a file with the specified base64-encoded content inside Anki's media folder. * @param {string} fileName The name of the file. * @param {string} content The base64-encoded content of the file. * @returns {Promise<?string>} The actual file name used to store the file, which may be different; or `null` if the file was not stored. * @throws {Error} An error is thrown is this object is not enabled. */ async storeMediaFile(fileName, content) { if (!this._enabled) { throw new Error('AnkiConnect not enabled'); } await this._checkVersion(); const result = await this._invoke('storeMediaFile', {filename: fileName, data: content}); if (result !== null && typeof result !== 'string') { throw this._createUnexpectedResultError('string|null', result); } return result; } /** * Finds notes matching a query. * @param {string} query Searches for notes matching a query. * @returns {Promise<import('anki').NoteId[]>} An array of note IDs. * @see https://docs.ankiweb.net/searching.html */ async findNotes(query) { if (!this._enabled) { return []; } await this._checkVersion(); const result = await this._invoke('findNotes', {query}); return this._normalizeArray(result, -1, 'number'); } /** * @param {import('anki').Note[]} notes * @returns {Promise<import('anki').NoteId[][]>} */ async findNoteIds(notes) { if (!this._enabled) { return []; } await this._checkVersion(); const actions = []; const actionsTargetsList = []; /** @type {Map<string, import('anki').NoteId[][]>} */ const actionsTargetsMap = new Map(); /** @type {import('anki').NoteId[][]} */ const allNoteIds = []; for (const note of notes) { const query = this._getNoteQuery(note); let actionsTargets = actionsTargetsMap.get(query); if (typeof actionsTargets === 'undefined') { actionsTargets = []; actionsTargetsList.push(actionsTargets); actionsTargetsMap.set(query, actionsTargets); actions.push({action: 'findNotes', params: {query}}); } /** @type {import('anki').NoteId[]} */ const noteIds = []; allNoteIds.push(noteIds); actionsTargets.push(noteIds); } const result = await this._invokeMulti(actions); for (let i = 0, ii = Math.min(result.length, actionsTargetsList.length); i < ii; ++i) { const noteIds = /** @type {number[]} */ (this._normalizeArray(result[i], -1, 'number')); for (const actionsTargets of actionsTargetsList[i]) { for (const noteId of noteIds) { actionsTargets.push(noteId); } } } return allNoteIds; } /** * @param {import('anki').CardId[]} cardIds * @returns {Promise<boolean>} */ async suspendCards(cardIds) { if (!this._enabled) { return false; } await this._checkVersion(); const result = await this._invoke('suspend', {cards: cardIds}); return typeof result === 'boolean' && result; } /** * @param {string} query * @returns {Promise<import('anki').CardId[]>} */ async findCards(query) { if (!this._enabled) { return []; } await this._checkVersion(); const result = await this._invoke('findCards', {query}); return this._normalizeArray(result, -1, 'number'); } /** * @param {import('anki').NoteId} noteId * @returns {Promise<import('anki').CardId[]>} */ async findCardsForNote(noteId) { return await this.findCards(`nid:${noteId}`); } /** * Gets information about the AnkiConnect APIs available. * @param {string[]} scopes A list of scopes to get information about. * @param {?string[]} actions A list of actions to check for * @returns {Promise<import('anki').ApiReflectResult>} Information about the APIs. */ async apiReflect(scopes, actions = null) { const result = await this._invoke('apiReflect', {scopes, actions}); if (!(typeof result === 'object' && result !== null)) { throw this._createUnexpectedResultError('object', result); } const {scopes: resultScopes, actions: resultActions} = /** @type {import('core').SerializableObject} */ (result); const resultScopes2 = /** @type {string[]} */ (this._normalizeArray(resultScopes, -1, 'string', ', field scopes')); const resultActions2 = /** @type {string[]} */ (this._normalizeArray(resultActions, -1, 'string', ', field scopes')); return { scopes: resultScopes2, actions: resultActions2 }; } /** * Checks whether a specific API action exists. * @param {string} action The action to check for. * @returns {Promise<boolean>} Whether or not the action exists. */ async apiExists(action) { const {actions} = await this.apiReflect(['actions'], [action]); return actions.includes(action); } /** * Checks if a specific error object corresponds to an unsupported action. * @param {Error} error An error object generated by an API call. * @returns {boolean} Whether or not the error indicates the action is not supported. */ isErrorUnsupportedAction(error) { if (error instanceof ExtensionError) { const {data} = error; if (typeof data === 'object' && data !== null && /** @type {import('core').SerializableObject} */ (data).apiError === 'unsupported action') { return true; } } return false; } // Private /** * @returns {Promise<void>} */ async _checkVersion() { if (this._remoteVersion < this._localVersion) { if (this._versionCheckPromise === null) { const promise = this._getVersion(); promise .catch(() => {}) .finally(() => { this._versionCheckPromise = null; }); this._versionCheckPromise = promise; } this._remoteVersion = await this._versionCheckPromise; if (this._remoteVersion < this._localVersion) { throw new Error('Extension and plugin versions incompatible'); } } } /** * @param {string} action * @param {import('core').SerializableObject} params * @returns {Promise<unknown>} */ async _invoke(action, params) { /** @type {import('anki').MessageBody} */ const body = {action, params, version: this._localVersion}; if (this._apiKey !== null) { body.key = this._apiKey; } let response; try { if (this._server === null) { throw new Error('Server URL is null'); } response = await fetch(this._server, { method: 'POST', mode: 'cors', cache: 'default', credentials: 'omit', headers: { 'Content-Type': 'application/json' }, redirect: 'follow', referrerPolicy: 'no-referrer', body: JSON.stringify(body) }); } catch (e) { const error = new ExtensionError('Anki connection failure'); error.data = {action, params, originalError: e}; throw error; } if (!response.ok) { const error = new ExtensionError(`Anki connection error: ${response.status}`); error.data = {action, params, status: response.status}; throw error; } let responseText = null; /** @type {unknown} */ let result; try { responseText = await response.text(); result = parseJson(responseText); } catch (e) { const error = new ExtensionError('Invalid Anki response'); error.data = {action, params, status: response.status, responseText, originalError: e}; throw error; } if (typeof result === 'object' && result !== null && !Array.isArray(result)) { const apiError = /** @type {import('core').SerializableObject} */ (result).error; if (typeof apiError !== 'undefined') { const error = new ExtensionError(`Anki error: ${apiError}`); error.data = {action, params, status: response.status, apiError: typeof apiError === 'string' ? apiError : `${apiError}`}; throw error; } } return result; } /** * @param {{action: string, params: import('core').SerializableObject}[]} actions * @returns {Promise<unknown[]>} */ async _invokeMulti(actions) { const result = await this._invoke('multi', {actions}); if (!Array.isArray(result)) { throw this._createUnexpectedResultError('array', result); } return result; } /** * @param {string} text * @returns {string} */ _escapeQuery(text) { return text.replace(/"/g, ''); } /** * @param {import('anki').NoteFields} fields * @returns {string} */ _fieldsToQuery(fields) { const fieldNames = Object.keys(fields); if (fieldNames.length === 0) { return ''; } const key = fieldNames[0]; return `"${key.toLowerCase()}:${this._escapeQuery(fields[key])}"`; } /** * @param {import('anki').Note} note * @returns {?('collection'|'deck'|'deck-root')} */ _getDuplicateScopeFromNote(note) { const {options} = note; if (typeof options === 'object' && options !== null) { const {duplicateScope} = options; if (typeof duplicateScope !== 'undefined') { return duplicateScope; } } return null; } /** * @param {import('anki').Note} note * @returns {string} */ _getNoteQuery(note) { let query = ''; switch (this._getDuplicateScopeFromNote(note)) { case 'deck': query = `"deck:${this._escapeQuery(note.deckName)}" `; break; case 'deck-root': query = `"deck:${this._escapeQuery(getRootDeckName(note.deckName))}" `; break; } query += this._fieldsToQuery(note.fields); return query; } /** * @returns {Promise<number>} */ async _getVersion() { const version = await this._invoke('version', {}); return typeof version === 'number' ? version : 0; } /** * @param {string} message * @param {unknown} data * @returns {ExtensionError} */ _createError(message, data) { const error = new ExtensionError(message); error.data = data; return error; } /** * @param {string} expectedType * @param {unknown} result * @param {string} [context] * @returns {ExtensionError} */ _createUnexpectedResultError(expectedType, result, context) { return this._createError(`Unexpected type${typeof context === 'string' ? context : ''}: expected ${expectedType}, received ${this._getTypeName(result)}`, result); } /** * @param {unknown} value * @returns {string} */ _getTypeName(value) { if (value === null) { return 'null'; } return Array.isArray(value) ? 'array' : typeof value; } /** * @template [T=unknown] * @param {unknown} result * @param {number} expectedCount * @param {'boolean'|'string'|'number'} type * @param {string} [context] * @returns {T[]} * @throws {Error} */ _normalizeArray(result, expectedCount, type, context) { if (!Array.isArray(result)) { throw this._createUnexpectedResultError(`${type}[]`, result, context); } if (expectedCount < 0) { expectedCount = result.length; } else if (expectedCount !== result.length) { throw this._createError(`Unexpected result array size${context}: expected ${expectedCount}, received ${result.length}`, result); } for (let i = 0; i < expectedCount; ++i) { const item = /** @type {unknown} */ (result[i]); if (typeof item !== type) { throw this._createError(`Unexpected result type at index ${i}${context}: expected ${type}, received ${this._getTypeName(item)}`, result); } } return /** @type {T[]} */ (result); } /** * @param {unknown} result * @param {number} expectedCount * @returns {import('anki-connect.js').CanAddResult[]} * @throws {Error} */ _normalizeCanAddNotesWithErrorDetailArray(result, expectedCount) { if (!Array.isArray(result)) { throw this._createUnexpectedResultError('array', result, ''); } if (expectedCount !== result.length) { throw this._createError(`Unexpected result array size: expected ${expectedCount}, received ${result.length}`, result); } /** @type {import('anki-connect.js').CanAddResult[]} */ const result2 = []; for (let i = 0; i < expectedCount; ++i) { const item = /** @type {unknown} */ (result[i]); if (item === null || typeof item !== 'object') { throw this._createError(`Unexpected result type at index ${i}: expected object, received ${this._getTypeName(item)}`, result); } const {canAdd, error} = /** @type {{[key: string]: unknown}} */ (item); if (typeof canAdd !== 'boolean') { throw this._createError(`Unexpected result type at index ${i}, field canAdd: expected boolean, received ${this._getTypeName(canAdd)}`, result); } if (canAdd && typeof error !== 'undefined') { throw this._createError(`Unexpected result type at index ${i}, field error: expected undefined, received ${this._getTypeName(error)}`, result); } if (!canAdd && typeof error !== 'string') { throw this._createError(`Unexpected result type at index ${i}, field error: expected string, received ${this._getTypeName(error)}`, result); } if (canAdd) { result2.push({canAdd}); } else if (typeof error === 'string') { const item2 = { canAdd, error }; result2.push(item2); } } return result2; } /** * @param {unknown} result * @returns {(?import('anki').NoteInfo)[]} * @throws {Error} */ _normalizeNoteInfoArray(result) { if (!Array.isArray(result)) { throw this._createUnexpectedResultError('array', result, ''); } /** @type {(?import('anki').NoteInfo)[]} */ const result2 = []; for (let i = 0, ii = result.length; i < ii; ++i) { const item = /** @type {unknown} */ (result[i]); if (item === null || typeof item !== 'object') { throw this._createError(`Unexpected result type at index ${i}: expected Notes.NoteInfo, received ${this._getTypeName(item)}`, result); } const {noteId} = /** @type {{[key: string]: unknown}} */ (item); if (typeof noteId !== 'number') { result2.push(null); continue; } const {tags, fields, modelName, cards} = /** @type {{[key: string]: unknown}} */ (item); if (typeof modelName !== 'string') { throw this._createError(`Unexpected result type at index ${i}, field modelName: expected string, received ${this._getTypeName(modelName)}`, result); } if (typeof fields !== 'object' || fields === null) { throw this._createError(`Unexpected result type at index ${i}, field fields: expected string, received ${this._getTypeName(fields)}`, result); } const tags2 = /** @type {string[]} */ (this._normalizeArray(tags, -1, 'string', ', field tags')); const cards2 = /** @type {number[]} */ (this._normalizeArray(cards, -1, 'number', ', field cards')); /** @type {{[key: string]: import('anki').NoteFieldInfo}} */ const fields2 = {}; for (const [key, fieldInfo] of Object.entries(fields)) { if (typeof fieldInfo !== 'object' || fieldInfo === null) { continue; } const {value, order} = fieldInfo; if (typeof value !== 'string' || typeof order !== 'number') { continue; } fields2[key] = {value, order}; } /** @type {import('anki').NoteInfo} */ const item2 = { noteId, tags: tags2, fields: fields2, modelName, cards: cards2 }; result2.push(item2); } return result2; } }