// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
// This file is automatically generated. DO NOT EDIT

/**
 * Service is the Wails-bound surface for the review UI.  All
 * exported methods become TypeScript stubs that the frontend calls.
 * @module
 */

// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore: Unused imports
import { Call as $Call, CancellablePromise as $CancellablePromise } from "@wailsio/runtime";

// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore: Unused imports
import * as $models from "./models.js";

/**
 * AckLibraryWarning records that the user has seen the first-
 * time-apply irreversibility warning for this library.
 */
export function AckLibraryWarning(libraryID: number): $CancellablePromise<void> {
    return $Call.ByID(1523853598, libraryID);
}

/**
 * Apply runs the apply pipeline for the given group + chosen
 * release MBID.  Uses the cached candidate list from the last
 * GetCandidates / GetCandidatesForPasteURL call so the user
 * always applies the exact release they saw in the UI.
 * Empty releaseMBID picks the top-scored candidate.
 */
export function Apply(groupKey: string, releaseMBID: string): $CancellablePromise<$models.ApplyResultView | null> {
    return $Call.ByID(2015906074, groupKey, releaseMBID);
}

/**
 * ApplyAsync dispatches an Apply for the given group in a
 * background goroutine and returns immediately.  Progress is
 * reported to the frontend via three Wails events:
 * 
 *   - AutotagApplyStarted   {groupKey, total}
 *   - AutotagApplyProgress  {groupKey, current, total, succeeded, failed}
 *   - AutotagApplyFinished  {groupKey, succeeded, failed, error}
 * 
 * The candidate list and locals are snapshot synchronously before
 * returning so a concurrent GetCandidates can't shuffle the
 * selected release out from under the running job.  Returns
 * ErrApplyInFlight when a job for the same groupKey is already
 * running; otherwise nil.  Job-level errors land in the Finished
 * event payload, not the return value.
 */
export function ApplyAsync(groupKey: string, releaseMBID: string): $CancellablePromise<void> {
    return $Call.ByID(2246879134, groupKey, releaseMBID);
}

/**
 * ClearCompletedEntries marks every confirmed item in the given
 * library (or all libraries when libraryID = 0) as cleared.  The
 * rows stay in the table — so a re-scan of the same folder
 * won't bounce them back into 'pending' — but they no longer
 * appear in the review queue.  Returns the number of rows
 * affected so the frontend can show a quick toast.
 */
export function ClearCompletedEntries(libraryID: number): $CancellablePromise<void> {
    return $Call.ByID(1606786204, libraryID);
}

/**
 * GetCandidateCoverArt is the lazy-load entrypoint for cover art
 * when the user picks a non-top candidate.  Goes through the
 * CAA-only chain (disk cache → network) — never the local
 * library-by-name index, since that index conflates embedded ID3
 * art with externally-fetched art and the embedded path produces
 * stale or wrong-version covers for autotag review.
 */
export function GetCandidateCoverArt(releaseMBID: string, releaseGroupMBID: string): $CancellablePromise<string> {
    return $Call.ByID(1410264131, releaseMBID, releaseGroupMBID);
}

/**
 * GetCandidates runs the scorer for a group and returns the full
 * candidate list (ordered best-first) along with the local tracks.
 * Caches the scored candidate list so Apply can operate on the
 * exact release the user saw — even if a concurrent rescore would
 * have shuffled the ranking.  Also writes the top candidate's
 * score back to the tagging_items row so the sidebar's match-%
 * pill and the score-desc list sort reflect the freshly-computed
 * ranking instead of the scanner's pre-review estimate.
 */
export function GetCandidates(groupKey: string): $CancellablePromise<$models.ScoreView | null> {
    return $Call.ByID(873001524, groupKey);
}

/**
 * GetCandidatesForPasteURL resolves a MusicBrainz release-or-
 * release-group URL into a ScoreView by fetching the pasted entity
 * from MB, running track alignment against the local group, and
 * prepending a fully-scored candidate to the existing list.  The
 * pasted candidate's provenance is "paste" so the UI can label it.
 */
export function GetCandidatesForPasteURL(groupKey: string, mbReleaseURL: string): $CancellablePromise<$models.ScoreView | null> {
    return $Call.ByID(2470223543, groupKey, mbReleaseURL);
}

/**
 * GetLocalCoverArt returns a data-URI for the artwork associated
 * with the group's local files, so the review UI can show "what the
 * folder already looks like" beside the fetched candidate art.
 * It first checks each file for embedded ID3/Vorbis pictures, then
 * falls back to a sidecar cover image (cover.jpg, folder.png, …)
 * sitting in the album directory.  Untagged folders carry one or the
 * other far more often than they have a DB release-group cover, so we
 * read the files directly.  Returns "" when nothing is found.
 */
export function GetLocalCoverArt(groupKey: string): $CancellablePromise<string> {
    return $Call.ByID(2603982821, groupKey);
}

/**
 * GetNextPending returns the next pending tagging item after the
 * internal cursor, or nil when the queue is empty.  Advances the
 * cursor on success.
 */
export function GetNextPending(): $CancellablePromise<$models.PendingItem | null> {
    return $Call.ByID(1751929138);
}

/**
 * GetPendingFolder returns the tagging item for a specific group
 * key — used by the sidebar after the user clicks an entry, so
 * the header can render even when the cursor-based queue iteration
 * hasn't visited that key yet.
 */
export function GetPendingFolder(groupKey: string): $CancellablePromise<$models.PendingItem | null> {
    return $Call.ByID(3455545217, groupKey);
}

/**
 * LeaveAsIs is the "local tags are correct, don't rescore"
 * acknowledgement — bumps status to 'confirmed' without touching
 * any files.
 */
export function LeaveAsIs(groupKey: string): $CancellablePromise<void> {
    return $Call.ByID(3897348801, groupKey);
}

/**
 * ListPendingFolders returns every tagging item in the given
 * library (or all libraries when libraryID = 0) that has not been
 * explicitly cleared.  Includes items in all review states —
 * pending, skipped, and confirmed — so the sidebar can group
 * them into sections (the user wanted skipped/completed to stay
 * visible at the bottom rather than vanish).  Sorted by score
 * descending so the UI surfaces the most confident matches first
 * (NULL scores fall to the bottom); the frontend re-groups by
 * status for display.
 */
export function ListPendingFolders(libraryID: number): $CancellablePromise<$models.PendingItem[] | null> {
    return $Call.ByID(617511590, libraryID);
}

/**
 * RetagGroup flips a group back to 'pending' so the user can
 * re-review after an apply or skip.  Drops the durably-cached
 * candidate list too, so the next open recomputes against fresh
 * MusicBrainz data rather than reusing the stale stored result.
 */
export function RetagGroup(groupKey: string): $CancellablePromise<void> {
    return $Call.ByID(2552507548, groupKey);
}

/**
 * SearchCandidates runs an in-app MusicBrainz search — the "suggest a
 * new candidate" escape hatch when the automatic cascade misses.
 * kind is "recording" (title + artist, for singletons) or anything
 * else (album + artist release-group search).  Returns lightweight
 * hits; SelectSearchCandidate resolves the picked one into a scored
 * candidate.
 */
export function SearchCandidates(kind: string, query: string, artist: string): $CancellablePromise<$models.SearchHitView[] | null> {
    return $Call.ByID(4062823000, kind, query, artist);
}

/**
 * SelectSearchCandidate resolves a picked search hit into a fully-
 * scored candidate and splices it to the top of the group's candidate
 * list — the same shape as the paste-URL path, so Apply works
 * unchanged.  A "recording" hit is resolved to a representative
 * release first.
 */
export function SelectSearchCandidate(groupKey: string, kind: string, mbid: string): $CancellablePromise<$models.ScoreView | null> {
    return $Call.ByID(2540832563, groupKey, kind, mbid);
}

/**
 * Skip marks the current group as skipped — it stays in the
 * queue but renders in the "Skipped" section at the bottom of
 * the sidebar, separate from pending items, so the user can
 * revisit it later if they change their mind.
 */
export function Skip(groupKey: string): $CancellablePromise<void> {
    return $Call.ByID(1248497081, groupKey);
}

/**
 * SplitMixedFolder is the "this folder is a pile of unrelated
 * tracks" escape hatch: it partitions the group's local tracks via
 * autotag.SplitPlan — tag-matched sub-albums (see
 * autotag.ClusterByAlbumArtist) plus a one-track cluster for every
 * track that didn't share an (album, album-artist) pair with
 * anything else — and carves each piece out into its own synthetic
 * tagging group, reassigning just those audio_files rows (no files
 * move on disk).  Every track leaves the original group; nothing is
 * left behind to be scored as "extra tracks" of whichever piece
 * happens to match first.  The synthetic groups are scored with
 * relaxed missing-track handling (rank.go, recommend.go), since
 * they're expected to be an incomplete subset of whatever release
 * they belong to.
 * 
 * Returns the resulting PendingItems — the leftover original group
 * first (if anything remains in it), then the new synthetic groups
 * — so the frontend can splice them into the sidebar without a full
 * reload.  Errors with errNothingToSplit when the folder is already
 * one coherent unit (SplitPlan produces a single cluster covering
 * every track); callers should treat that as "nothing to show", not
 * a failure.
 */
export function SplitMixedFolder(groupKey: string): $CancellablePromise<$models.PendingItem[] | null> {
    return $Call.ByID(3640008069, groupKey);
}

/**
 * StartAutotagQueue resets the cursor for a new review session
 * and kicks off the background prefetch worker so sidebar pills
 * populate while the user reviews the first folder.  Cancels any
 * previous prefetch (library filter may have changed).  Pass
 * libraryID=0 to cover all libraries.
 */
export function StartAutotagQueue(libraryID: number): $CancellablePromise<void> {
    return $Call.ByID(568310002, libraryID);
}

/**
 * StartBackgroundPrefetch kicks off (or restarts) the prefetch
 * worker over all libraries.  Called from app startup hooks so
 * unscored pending items get their match-% backfilled while the
 * user does other things — by the time they navigate to the
 * autotag page, the sidebar pills are already populated.
 * Idempotent: items with an existing score are skipped, so it's
 * safe to call after every library scan and on every app launch.
 */
export function StartBackgroundPrefetch(): $CancellablePromise<void> {
    return $Call.ByID(428378477);
}

/**
 * WritesInFlight reports whether an apply is currently rewriting tags
 * on disk. Quitting mid-apply leaves a folder half-retagged, so the app
 * asks before closing (errors.p4).
 */
export function WritesInFlight(): $CancellablePromise<boolean> {
    return $Call.ByID(1561223347);
}
