"""Freesound fetcher — DEFERRED (see spec §6.4).

CC-licensed sound effects / field recordings (cc0 / cc_by / cc_by_nc) via API
v2 (https://freesound.org/apiv2). Requires an API token supplied through the
FREESOUND_API_TOKEN environment variable (or the macOS Keychain). That token is
a SECRET: it is read from the environment only and must NEVER be written into a
record, a log line, or a transcript (wgl hard secrets rule, spec §9).

The Fetcher seam is wired; it raises until implemented.
"""

from __future__ import annotations

import os

from tools.ingest.base import Candidate

_DEFERRED = "deferred — see spec §6.4 (Freesound requires FREESOUND_API_TOKEN)"
TOKEN_ENV = "FREESOUND_API_TOKEN"


class FreesoundFetcher:
    archive = "freesound"

    def __init__(self, client, token: str | None = None):
        self.client = client
        # Read the secret from the environment only; never log or store it.
        self._token = token or os.environ.get(TOKEN_ENV)

    def search(self, query: str, *, limit: int) -> list[Candidate]:
        raise NotImplementedError(_DEFERRED)

    def resolve(self, identifier: str) -> Candidate:
        raise NotImplementedError(_DEFERRED)