Audnexus

<p align="center"> <a href="" rel="noopener"> <img width=200px height=200px src="../assets/logos/logo.png?raw=true" alt="Project logo"></a> </p> <h3 align="center">audnexus</h3> <div align="center">

</div>

---

<p align="center"> An audiobook data aggregation API, combining multiple sources of data into one, consistent source. <br> </p>

📝 Table of Contents

• About
• Getting Started
• Running the tests
• Error Handling
• Usage
• Deployment
• Built Using
• TODO
• Contributing
• Authors
• Acknowledgments

🧐 About <a name = "about"></a>

Nexus - noun: a connection or series of connections linking two or more things.

Looking around for audiobook metadata, we realized there's no solid (or open) single source of truth. Further, some solutions had community curated data, only to close their API. As such, this project has been created to enable development to include multiple sources of audiobook content in one response.

This project also makes integration into existing media servers very streamlined. Since all data can be returned with 1-2 API calls, there's little to no overhead processing on the client side. This enables rapid development of stable client plugins. Audnexus serves as a provider during the interim of waiting for a community driven audiobook database, at which time audnexus will be a seeder for such a database.

🏁 Getting Started <a name = "getting_started"></a>

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Prerequisites

• There are 3 ways to deploy this project:
  • Coolify - Self-hosted PaaS platform with automatic deployments from Git
  • Docker Swarm - Docker Compose stack with Traefik reverse proxy
  • Directly, via pnpm run or pm2
    • Mongo 4 or greater
    • Node/NPM 16 or greater
    • Redis
  • Registered Audible device keys, ADP_TOKEN and PRIVATE_KEY, for chapters. You will need Python and audible for this. More on that here

Installing locally

• Install Mongo, Node and Redis on your system
• pnpm install from project directory to get dependencies

Required environment variables:

• MONGODB_URI: MongoDB connection URL (e.g., mongodb://localhost:27017/audnexus)

Optional environment variables:

• Set ADP_TOKEN and PRIVATE_KEY for the chapters endpoint
• Configure other optional variables as described in the Deployment section

Then start the server:

pnpm run watch-debug

Test an API call with

http://localhost:3000/books/${ASIN}

🔧 Running the tests <a name = "tests"></a>

Tests for this project use the Jest framework. Tests can be done locally in a dev environment:

• pnpm test

After the tests have run, you may also browse the test coverage. This is generated in coverage/lcov-report/index.html under the project directory.

⚠️ Error Handling <a name = "error_handling"></a>

The API returns structured error responses with error codes, HTTP status codes, and detailed messages.

Error Response Format

All errors follow this structure. The details field is optional and may be omitted or set to null:

{
	"error": {
		"code": "ERROR_CODE",
		"message": "Human-readable error message",
		"details": null
	}
}

Error Codes

| Code | HTTP Status | Description | | ----------------------- | ----------- | ----------------------------------------------------------------------------------------- | | CONTENT_TYPE_MISMATCH | 400 | Content type doesn't match the requested endpoint (e.g., podcast ASIN on /books endpoint) | | VALIDATION_ERROR | 422 | Schema validation failed | | REGION_UNAVAILABLE | 404 | Content not available in the requested region | | NOT_FOUND | 404 | Generic not found error | | BAD_REQUEST | 400 | Bad request | | RATE_LIMIT_EXCEEDED | 429 | Too many requests — client has exceeded allowed request rate |

Example Error Responses

Content Type Mismatch (Podcast on Book endpoint):

{
	"error": {
		"code": "CONTENT_TYPE_MISMATCH",
		"message": "Item is a podcast, not a book. ASIN: B017V4U2VQ",
		"details": {
			"asin": "B017V4U2VQ",
			"requestedType": "book",
			"actualType": "PodcastParent"
		}
	}
}

Region Unavailable:

{
	"error": {
		"code": "REGION_UNAVAILABLE",
		"message": "Item not available in region 'us' for ASIN: B12345",
		"details": {
			"asin": "B12345"
		}
	}
}

Validation Error:

{
	"error": {
		"code": "VALIDATION_ERROR",
		"message": "Schema validation failed for request",
		"details": {
			"field": "asin",
			"issue": "Invalid ASIN format"
		}
	}
}

Not Found:

{
	"error": {
		"code": "NOT_FOUND",
		"message": "Book with ASIN B12345 not found",
		"details": {
			"asin": "B12345",
			"endpoint": "/books"
		}
	}
}

Bad Request:

{
	"error": {
		"code": "BAD_REQUEST",
		"message": "Invalid request parameters",
		"details": {
			"parameter": "region",
			"issue": "Unsupported region 'xx'"
		}
	}
}

Rate Limit Exceeded:

{
	"error": {
		"code": "RATE_LIMIT_EXCEEDED",
		"message": "Too many requests — client has exceeded allowed request rate",
		"details": {
			"retryAfterSeconds": 60
		}
	}
}

🎈 Usage <a name="usage"></a>

API usage documentation can be read here: https://audnex.us/

Pre-rendered HTML documentation is also included in docs/index.html.

HTML can be re-generated from the spec, using:

pnpm run build-docs

🚀 Deployment <a name = "deployment"></a>

Coolify Deployment

Audnexus can be deployed to Coolify, a self-hosted open-source alternative to Vercel.

Setup Steps:

1. Connect repository to Coolify:

   • In Coolify, create a new application
   • Select "Git" and connect your GitHub repository
   • Select the branch (e.g., main or develop)

2. Configure environment variables:

   • Set up the following environment variables in Coolify:

   Core Configuration:

   • MONGODB_URI: MongoDB connection URL (e.g., mongodb://mongo:27017/audnexus) [required]
   • REDIS_URL: Redis connection URL (e.g., redis://redis:6379) [optional]
   • HOST: Server host address (default: 0.0.0.0)
   • PORT: Server port (default: 3000)
   • LOG_LEVEL: Log level - trace, debug, info, warn, error, fatal (default: info)
   • TRUSTED_PROXIES: Comma-separated list of trusted proxy IPs/CIDR ranges (optional)
   • DEFAULT_REGION: Default region for batch processing (default: us)

   Audible API Configuration:

   • ADP_TOKEN: Audible ADP_TOKEN value (optional, for chapters endpoint)
   • PRIVATE_KEY: Audible PRIVATE_KEY value (optional, for chapters endpoint)

   Rate Limiting:

   • MAX_REQUESTS: Max requests per minute per source (default: 100)

   Update Scheduling:

   • UPDATE_INTERVAL: Update interval in days (default: 30)
   • UPDATE_THRESHOLD: Minimum days before checking updates again (default: 7)

   Performance Tuning:

   • MAX_CONCURRENT_REQUESTS: HTTP connection pool size for concurrent API calls (default: 50)
   • SCHEDULER_CONCURRENCY: Max concurrent scheduler operations (default: 5)
   • SCHEDULER_MAX_PER_REGION: Hard cap for max per-region concurrency in batch processing (default: 5)
   • HTTP_MAX_SOCKETS: Maximum HTTP sockets (hard limit: 50, default: 50) - values above 50 will be clamped to 50
   • HTTP_TIMEOUT_MS: HTTP request timeout in milliseconds (default: 30000)

   Feature Flags (Boolean - supports true, True, TRUE, 1):

   • USE_PARALLEL_SCHEDULER: Enable parallel UpdateScheduler (default: false) - HIGH RISK, requires testing
   • USE_CONNECTION_POOLING: Enable HTTP connection pooling for API calls (default: true)
   • USE_COMPACT_JSON: Use compact JSON format in Redis (default: true)
   • USE_SORTED_KEYS: Sort object keys in responses (adds O(n log n) overhead, default: false)
   • CIRCUIT_BREAKER_ENABLED: Enable circuit breaker pattern for external API calls (default: true)
   • METRICS_ENABLED: Enable performance metrics collection and /metrics endpoint (default: true)

   Metrics Endpoint Security:

   • METRICS_AUTH_TOKEN: Authentication token for /metrics endpoint (optional)
   • METRICS_ALLOWED_IPS: Comma-separated list of allowed IPs/CIDR ranges for /metrics (supports CIDR notation, optional)