API Reference

Authentication

login(locale)

Generate a login URL for the Audible PKCE OAuth flow.

const { loginUrl, session, cookies } = await login('fr')

Parameters:

Name	Type	Description
locale	AudibleLocale	The Audible marketplace to authenticate against

Returns: Promise<{ loginUrl: string, session: AuthSession, cookies: AudibleCookie[] }>

---

register(authorizationCode, session)

Complete device registration using the authorization code from the OAuth callback.

const credentials = await register(code, session)
console.log(`Authenticated! Expires: ${credentials.expiresAt}`)

Parameters:

Name	Type	Description
authorizationCode	string	The code from the OAuth callback URL
session	AuthSession	The session returned by login()

Returns: Promise<AudibleCredentials>

Throws: Error if registration fails (invalid code, expired session, etc.)

---

refresh(credentials)

Manually refresh an access token. Usually not needed — all API functions auto-refresh credentials before each call.

const updated = await refresh(credentials)
console.log(`New expiration: ${updated.expiresAt}`)

Parameters:

Name	Type	Description
credentials	AudibleCredentials	Current credentials with a valid refreshToken

Returns: Promise<AudibleCredentials> — New credentials with updated accessToken and expiresAt

Throws: Error if the refresh token is invalid

---

Data Fetching

library(credentials)

Fetch the user’s entire Audible library with automatic pagination. Credentials are auto-refreshed before the call.

const { items } = await library(credentials)

// Each item has full details: rating, categories, listening progress, etc.
items.map((book) => {
  const rating = book.rating?.overallDistribution
  console.log(`${book.title} — ${rating?.averageRating?.toFixed(1)}/5`)
  if (book.listeningStatus?.finishedAt) {
    console.log(`  Finished on ${book.listeningStatus.finishedAt.toLocaleDateString()}`)
  }
})

Parameters:

Name	Type	Description
credentials	AudibleCredentials	Valid credentials

Returns: Promise<{ items: AudibleItem[], credentials: AudibleCredentials }>

Pagination is automatic — all items are fetched (50 per page).

---

wishlist(credentials)

Fetch the user’s entire Audible wishlist with automatic pagination. Credentials are auto-refreshed before the call.

const { items } = await wishlist(credentials)

items.map((book) =>
  console.log(`${book.title} — ${book.durationMinutes} min — ${book.publisher}`)
)

Parameters:

Name	Type	Description
credentials	AudibleCredentials	Valid credentials

Returns: Promise<{ items: AudibleItem[], credentials: AudibleCredentials }>

---

catalog(credentials, options)

Search the Audible catalog by category with optional filters. Credentials are auto-refreshed before the call.

// Science Fiction sorted by relevance (default sort)
const { items } = await catalog(credentials, {
  category: 'science-fiction',
  limit: 20,
})

// Or using raw category ID
const { items: items2 } = await catalog(credentials, {
  categoryId: '21229020031',
  limit: 20,
})

items.map((book, i) => {
  const r = book.rating?.overallDistribution
  console.log(
    `${i + 1}. ${book.title} — ${r?.averageRating?.toFixed(1)}/5 (${r?.numRatings} votes)`
  )
})

Parameters:

Name	Type	Default	Description
credentials	AudibleCredentials	—	Valid credentials
options.category	AudibleGenre	—	Genre name, resolved per locale
options.categoryId	string	—	Raw category ID (alternative to category)
options.sortBy	string	'Relevance'	Sort order (see below)
options.limit	number | 'all'	50	Max results to return. Use 'all' to fetch everything
options.keywords	string	—	Search term filter
options.author	string	—	Filter by author name
options.narrator	string	—	Filter by narrator name

API sorts (fast) — single request, returns limit items: 'Relevance' (default), 'BestSellers', 'AvgRating', 'ReleaseDate', '-ReleaseDate', 'Title'

Client sort (slow): 'MostVoted' — fetches ALL pages (up to 1000 items), sorts by votes desc then rating desc, returns limit items. Can take 10-60 seconds on large categories.

Returns: Promise<{ items: AudibleItem[], credentials: AudibleCredentials }>

---

verify(credentials)

Verify that credentials are valid by making a minimal API call. Credentials are auto-refreshed before the call.

try {
  await verify(credentials)
  console.log('Connected')
} catch {
  console.log('Credentials invalid')
}

Parameters:

Name	Type	Description
credentials	AudibleCredentials	Credentials to verify

Returns: Promise<void>

Throws: Error if credentials are invalid or expired

---

Configuration

AUDIBLE_LOCALES

A record mapping each AudibleLocale to its marketplace configuration.

import { AUDIBLE_LOCALES } from 'audible-api-ts'

AUDIBLE_LOCALES['fr']
// { domain: 'fr', marketplaceId: 'A2728XDNODOQ8T', countryCode: 'fr' }

AUDIBLE_LOCALES['com']
// { domain: 'com', marketplaceId: 'AF2M0KC94RCEA', countryCode: 'us' }

Type: Record<AudibleLocale, LocaleConfig>