Initial release v1.4.0

Author: AudD

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: tests + clippy + fmt
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        rust: ['1.75.0', 'stable', 'beta']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ matrix.rust }}
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: rustfmt
+        if: matrix.rust == 'stable'
+        run: cargo fmt --check
+      - name: clippy
+        if: matrix.rust == 'stable'
+        run: cargo clippy --all-targets -- -D warnings
+      - name: cargo build
+        run: cargo build
+      - name: cargo test
+        run: cargo test --all-features --no-fail-fast
+      - name: cargo doc
+        if: matrix.rust == 'stable'
+        run: cargo doc --no-deps --all-features
+        env:
+          RUSTDOCFLAGS: -D warnings

.github/workflows/contract.yml

@@ -0,0 +1,45 @@
+name: Contract tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '0 6 * * *'  # daily at 06:00 UTC
+  repository_dispatch:
+    types: [openapi-updated]
+
+jobs:
+  contract:
+    name: validate parser against latest audd-openapi fixtures
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: audd-rust
+      - name: Check out audd-openapi
+        uses: actions/checkout@v4
+        with:
+          repository: AudDMusic/audd-openapi
+          path: audd-openapi
+          ref: main
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: audd-rust
+      - name: Run contract tests
+        working-directory: audd-rust
+        env:
+          AUDD_OPENAPI_FIXTURES: ${{ github.workspace }}/audd-openapi/fixtures
+        run: cargo test --test contract -- --nocapture
+      - name: Open issue on failure (dispatched runs only)
+        if: failure() && github.event_name == 'repository_dispatch'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TRIGGER_SHA: ${{ github.event.client_payload.trigger_sha }}
+        run: |
+          gh issue create \
+            --title "Contract drift: audd-openapi spec change broke parser" \
+            --body "An openapi-updated dispatch (trigger SHA: $TRIGGER_SHA) caused contract tests to fail. Investigate and update parsers." \
+            --label "contract-drift" || true

.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'audd-rust/v*'
+
+permissions:
+  contents: read
+  id-token: write
+  attestations: write
+
+jobs:
+  publish:
+    name: cargo publish
+    runs-on: ubuntu-latest
+    environment: crates-io
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Verify the crate builds
+        run: cargo build --release
+      - name: cargo package (sanity)
+        run: cargo package --no-verify
+      - name: Generate Sigstore attestations
+        uses: actions/attest-build-provenance@v1
+        with:
+          subject-path: 'target/package/audd-*.crate'
+      - name: cargo publish
+        run: cargo publish --token ${{ secrets.CRATES_IO_TOKEN }}

.gitignore

@@ -0,0 +1,4 @@
+/target
+/Cargo.lock
+**/*.rs.bk
+.DS_Store

CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.4.0] - 2026-05-05
+
+### Changed
+
+- Brand rename across all PascalCase types: the main client and its sibling
+  types now spell the brand as `AudD`. `AudD`, `AudDBuilder`, `AudDError`,
+  `AudDEvent`. The crate name `audd` (lowercase) and the `AUDD_API_TOKEN`
+  environment variable are unchanged.
+
+## [1.3.0] - 2026-05-05
+
+Coordinated v1.3.0 stable release across the audd-sdks family. No breaking
+changes; the version bump signals API stability across all nine SDKs.
+
+The full v0.3.0 polish — env-var auto-pickup, streaming/preview helpers
+with metadata fallback, `onEvent` inspection hook, thread-safe token
+rotation, plus per-language work (JPMS module-info, Kotlin `Flow<LongpollEvent>`,
+Swift `Sendable` + DocC, .NET AOT/source-gen + `IServiceCollection`, Rust
+TLS feature flags + `Serialize`, PHP PSR-3 logger, Python `__repr__` +
+`pretty_print()`, Go `slog` example) is now the v1.3.0 baseline.
+
+## [0.3.0] - 2026-05-05
+
+### Added
+
+- TLS-backend feature flags. `default = ["rustls-tls"]` keeps the v0.2 behavior
+  (pure-Rust TLS + Mozilla CA bundle) intact for existing users; opt into
+  `native-tls` (system OpenSSL — corp CA bundles, OpenSSL FIPS, etc.) or
+  `vendored-openssl` (static OpenSSL build, no `libssl-dev` required) by
+  setting `default-features = false` and naming the backend explicitly. See
+  the README's "Choosing a TLS backend" section.
+- `Serialize` derive on every public model — `RecognitionResult`,
+  `AppleMusicMetadata`, `SpotifyMetadata`, `DeezerMetadata`, `NapsterMetadata`,
+  `MusicBrainzEntry`, `EnterpriseMatch`, `EnterpriseChunkResult`, `Stream`,
+  `StreamCallbackPayload`, `StreamCallbackResult`, `StreamCallbackResultEntry`,
+  `StreamCallbackNotification`, `LyricsResult`, `RecognitionMatch`,
+  `StreamingProvider`, `AudDEvent`, `EventKind`. Round-trip recognition
+  results into your own logs / queues / databases without a manual mapper.
+  `RecognitionMatch` serializes as a serde-tagged enum
+  (`{"kind": "public" | "custom", "result": ...}`); `StreamingProvider` /
+  `EventKind` serialize to their wire-name strings.
+
+### Changed
+
+- `reqwest` is now pulled with `default-features = false` plus the
+  SDK-managed feature gate. The `multipart` / `json` / `stream` feature set
+  is unchanged from v0.2.
+
+## [0.2.0] - 2026-05-05
+
+### Added
+
+- `AUDD_API_TOKEN` environment-variable fallback in `AudD::new` /
+  `AudD::builder().build()` and a new `AudD::from_env()` constructor. When the
+  token argument is empty and `AUDD_API_TOKEN` is unset, `build()` returns
+  `AudDError::Configuration` pointing at <https://dashboard.audd.io>.
+- `RecognitionResult::streaming_url(StreamingProvider)`,
+  `RecognitionResult::streaming_urls()`, `RecognitionResult::preview_url()`,
+  `EnterpriseMatch::streaming_url`, and `EnterpriseMatch::streaming_urls` —
+  resolution prefers a direct URL from the relevant metadata block, falling
+  back to the `lis.tn` `?<provider>` redirect helper. New `StreamingProvider`
+  enum (`Spotify` / `AppleMusic` / `Deezer` / `Napster` / `YouTube`).
+- `AudD::set_api_token(&str)` thread-safe rotation backed by `Arc<RwLock>`
+  on both the standard and enterprise transports. Rejects empty tokens with
+  `AudDError::Configuration`. `AudD::api_token()` now returns `String`.
+- `AudD::on_event(...)` inspection hook with `AudDEvent` (`kind`, `method`,
+  `url`, `request_id`, `http_status`, `elapsed`, `error_code`, `extras`).
+  Hook panics caught by `std::panic::catch_unwind`. `api_token` and request /
+  response bodies are never included.
+
+### Changed
+
+- New `AudDError::Configuration` variant for construction-time misuse.
+
+### Removed
+
+- Stale `advanced_lyrics` example target reference (per directive: no
+  ready-made find-lyrics example).
+
+## [0.1.0] - 2026-05-04
+
+### Added
+
+- First public release of the official Rust SDK for the AudD music recognition API.
+- Async-only client (`AudD`) backed by `reqwest` + `tokio`.
+- `recognize` (URL / path / bytes / async reader) returning `Option<RecognitionResult>`.
+- `recognize_enterprise` returning `Vec<EnterpriseMatch>` with hour-long timeouts.
+- `streams.*` namespace covering set/get callback URL, add/list/set_url/delete, longpoll
+  with default-on preflight (and `skip_callback_check` opt-out), `derive_longpoll_category`,
+  and `parse_callback`.
+- `custom_catalog.add` with override-message handling for code 904.
+- `advanced.find_lyrics` and `advanced.raw_request` escape hatch.
+- Tokenless `LongpollConsumer` (top-level export) with READ-class retries, configurable
+  `max_attempts` and `backoff_factor`, and HTTP-vs-JSON error distinction.
+- `AudDError` typed error enum with `is_authentication()` / `is_quota()` / etc. helpers,
+  branded-message extraction, and code-51 deprecation pass-through (emitted via `tracing::warn!`).
+- Forward-compatible models — every type carries `#[serde(flatten)] extras` and
+  `raw_response`.
+- Per-attempt source re-opener pattern (`prepare_source`) so retries always send a fresh
+  multipart body.
+- `RecognitionMatch` enum (`Public` / `Custom`) for exhaustive pattern matching.
+- Built against [audd-openapi](https://github.com/AudDMusic/audd-openapi) v0.1.0 fixtures.

Cargo.toml

@@ -0,0 +1,82 @@
+[package]
+name = "audd"
+version = "1.4.0"
+edition = "2021"
+rust-version = "1.75"
+license = "MIT"
+description = "Official Rust SDK for the AudD music recognition API"
+repository = "https://github.com/AudDMusic/audd-rust"
+homepage = "https://audd.io"
+documentation = "https://docs.rs/audd"
+keywords = ["audd", "music", "recognition", "audio", "fingerprint"]
+categories = ["api-bindings", "multimedia::audio"]
+readme = "README.md"
+exclude = ["tests/integration*", ".github/*"]
+
+[features]
+# `rustls-tls` is the default and matches the v0.2 behavior (Mozilla CA bundle,
+# pure-Rust TLS stack). Opt out with `default-features = false` and enable
+# `native-tls` (or `vendored-openssl`) when you need OpenSSL — corp environments
+# with custom CA trust stores, OpenSSL FIPS, etc.
+default = ["rustls-tls"]
+rustls-tls = ["reqwest/rustls-tls"]
+native-tls = ["reqwest/native-tls"]
+# Statically links a vendored copy of OpenSSL — useful when the build host
+# lacks `libssl-dev` / pkg-config OpenSSL headers but you still need the
+# OpenSSL TLS stack at runtime.
+vendored-openssl = ["reqwest/native-tls", "reqwest/native-tls-vendored"]
+# Opt-in live-API integration tests; gate via env var AUDD_API_TOKEN.
+integration = []
+
+[dependencies]
+reqwest = { version = "0.12", default-features = false, features = ["multipart", "json", "stream"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tokio = { version = "1", features = ["rt-multi-thread", "macros", "fs", "io-util", "sync", "time"] }
+thiserror = "1"
+tracing = "0.1"
+futures-core = "0.3"
+async-stream = "0.3"
+tokio-util = { version = "0.7", features = ["io"] }
+md5 = "0.7"
+url = "2"
+
+[dev-dependencies]
+tokio = { version = "1", features = ["rt-multi-thread", "macros", "fs", "io-util", "sync", "time", "test-util"] }
+tokio-test = "0.4"
+wiremock = "0.6"
+serde_json = "1"
+tempfile = "3"
+futures-util = "0.3"
+
+[[example]]
+name = "recognize_url"
+path = "examples/recognize_url.rs"
+
+[[example]]
+name = "recognize_file"
+path = "examples/recognize_file.rs"
+
+[[example]]
+name = "recognize_enterprise"
+path = "examples/recognize_enterprise.rs"
+
+[[example]]
+name = "streams_setup"
+path = "examples/streams_setup.rs"
+
+[[example]]
+name = "streams_longpoll"
+path = "examples/streams_longpoll.rs"
+
+[[example]]
+name = "streams_callback_handler"
+path = "examples/streams_callback_handler.rs"
+
+[[example]]
+name = "custom_catalog_add"
+path = "examples/custom_catalog_add.rs"
+
+[[example]]
+name = "tokenless_longpoll"
+path = "examples/tokenless_longpoll.rs"

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AudD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.