Skip to content
audible-api-ts

Types Reference

AudibleLocale

Section titled “AudibleLocale”

String union of all supported Audible marketplace identifiers.

type AudibleLocale =
  | 'fr' | 'com' | 'co.uk' | 'de' | 'it'
  | 'es' | 'ca' | 'com.au' | 'in' | 'co.jp'

AudibleCredentials

Section titled “AudibleCredentials”

Credentials obtained after device registration. Used for all API calls.

type AudibleCredentials = {
  accessToken: string       // Bearer token (expires)
  refreshToken: string      // Long-lived refresh token
  adpToken: string          // MAC DMS token for request signing
  devicePrivateKey: string  // RSA private key for signing
  serial: string            // Device serial (UUID, no dashes)
  locale: AudibleLocale     // Marketplace locale
  expiresAt: Date           // Access token expiration
}

AudibleItem

Section titled “AudibleItem”

An audiobook returned by library(), wishlist(), and catalog().

type AudibleItem = {
  // Identity
  asin: string                    // "B08G9PRS1K"
  title: string                   // "Primal Hunter"
  subtitle?: string               // "Primal Hunter, Tome 4"
  isbn?: string                   // "9791036645624"
  sku?: string                    // "BK_LIZZ_002036FR"


  // People
  authors: string[]               // ["Zogarth"]
  narrators: string[]             // ["Sébastien Mortamet"]


  // Content
  durationMinutes: number         // 1770
  publisher?: string              // "Lizzie"
  language?: string               // "french"
  releaseDate?: Date              // 2026-03-12
  coverUrl?: string               // "https://m.media-amazon.com/..."
  summary?: string                // Full HTML description
  description?: string            // Extended product description (HTML)
  merchandisingSummary?: string   // Short HTML summary
  copyright?: string              // "©2026 Zogarth..."
  formatType?: string             // "unabridged"
  contentType?: string            // "Product"
  contentDeliveryType?: string    // "MultiPartBook"
  programParticipation?: string   // "Audible Original"


  // Classification
  series?: { name: string; position?: number }
  categories: CategoryLadder[]
  keywords: string[]              // ["Science_Fiction_Fantasy", ...]


  // Ratings
  rating?: AudibleRating


  // Listening (library only)
  listeningStatus?: ListeningStatus
  purchaseDate?: Date
  dateAdded?: Date


  // Relationships
  relationships: AudibleRelationship[]


  // Images
  productImages: Record<string, string>      // { "500": "https://..." }
  socialMediaImages: Record<string, string>  // { "facebook": "https://..." }


  // Flags
  isAdultProduct: boolean
}

AudibleRating

Section titled “AudibleRating”

Full rating data with three dimensions: overall, performance (narrator), and story.

type AudibleRating = {
  numReviews: number
  overallDistribution?: RatingDistribution
  performanceDistribution?: RatingDistribution
  storyDistribution?: RatingDistribution
}

Example:

const rating = book.rating
// rating.overallDistribution?.averageRating  → 4.8
// rating.overallDistribution?.numRatings     → 156
// rating.performanceDistribution?.averageRating → 4.7
// rating.storyDistribution?.averageRating       → 4.9

RatingDistribution

Section titled “RatingDistribution”

Star distribution for a single rating dimension.

type RatingDistribution = {
  averageRating: number           // 4.759
  displayAverageRating: string    // "4.8"
  displayStars: number            // 5
  numRatings: number              // 156
  numFiveStarRatings: number      // 127
  numFourStarRatings: number      // 25
  numThreeStarRatings: number     // 2
  numTwoStarRatings: number       // 0
  numOneStarRatings: number       // 2
}

ListeningStatus

Section titled “ListeningStatus”

Listening progress for a library item.

type ListeningStatus = {
  finishedAt?: Date              // When the user finished listening
  isFinished?: boolean           // Whether the book is marked as finished
  percentComplete?: number       // 0-100
  timeRemainingSeconds?: number  // Seconds left to listen
}

Example:

const status = book.listeningStatus
// status?.percentComplete       → 5
// status?.timeRemainingSeconds  → 100890 (28 hours)
// status?.finishedAt            → undefined (not finished yet)

CategoryLadder

Section titled “CategoryLadder”

A genre classification path from root to leaf.

type CategoryLadder = {
  root: string                   // "Genres"
  categories: AudibleCategory[]  // Path from broad to specific
}


type AudibleCategory = {
  id: string    // "21228885031"
  name: string  // "Science-Fiction et fantasy"
}

Example:

book.categories
// [
//   {
//     root: "Genres",
//     categories: [
//       { id: "21228885031", name: "Science-Fiction et fantasy" },
//       { id: "21229021031", name: "Fantasy" },
//       { id: "21229712031", name: "Action et aventure" }
//     ]
//   }
// ]

AudibleRelationship

Section titled “AudibleRelationship”

A link to another Audible product (series parent, book components, etc.).

type AudibleRelationship = {
  asin: string                  // "B0DW8WDHFT"
  relationshipToProduct: string // "parent" or "child"
  relationshipType: string      // "series" or "component"
  title?: string                // "Primal Hunter"
  sort?: string                 // "4" (position)
  url?: string                  // "/pd/Primal-Hunter-Livre-Audio/B0DW8WDHFT"
}

CatalogOptions

Section titled “CatalogOptions”

Options for catalog().

type CatalogOptions = {
  category?: AudibleGenre  // genre name, resolved per locale
  categoryId?: string      // or raw category ID
  sortBy?:
    | 'MostVoted'          // client sort — slow, fetches all pages
    | 'BestSellers'
    | 'AvgRating'
    | 'Relevance'          // default
    | 'ReleaseDate'
    | '-ReleaseDate'
    | 'Title'
  limit?: number | 'all'  // max results to return (default 50)
  keywords?: string
  author?: string
  narrator?: string
}

Example:

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


// Most voted — ⚠️ slow, fetches all pages then sorts client-side (10-60s)
await catalog(credentials, {
  category: 'science-fiction',
  sortBy: 'MostVoted',
  limit: 20,
})


// Latest releases
await catalog(credentials, {
  category: 'science-fiction',
  sortBy: '-ReleaseDate',
})


// Raw category ID with keyword search
await catalog(credentials, {
  categoryId: '21229020031',
  sortBy: 'Relevance',
  keywords: 'space opera',
})

AudibleGenre

Section titled “AudibleGenre”

String union of available genre names for catalog search. Resolved to locale-specific category IDs automatically.

type AudibleGenre =
  // Main genres
  | 'science-fiction'
  | 'fantasy'
  | 'science-fiction-fantasy'
  | 'thriller'
  | 'mystery'
  | 'horror'
  | 'romance'
  | 'historical-fiction'
  | 'literary-fiction'
  | 'biography'
  | 'history'
  | 'business'
  | 'self-help'
  | 'science'
  | 'children'
  | 'young-adult'
  | 'comedy'
  | 'erotica'
  | 'religion'
  | 'sports'
  | 'travel'
  | 'lgbtq'


  // Science Fiction sub-genres
  | 'science-fiction/space-opera'
  | 'science-fiction/cyberpunk'
  | 'science-fiction/dystopian'


  // Fantasy sub-genres
  | 'fantasy/epic'
  | 'fantasy/dragons'
  | 'fantasy/urban-paranormal'


  // Thriller sub-genres
  | 'thriller/suspense'
  | 'thriller/psychological'


  // Mystery sub-genres
  | 'mystery/detective'
  | 'mystery/noir'


  // Romance sub-genres
  | 'romance/historical'
  | 'romance/paranormal'
  | 'romance/comedy'


  // Literary Fiction sub-genres
  | 'literary-fiction/classics'
  | 'literary-fiction/world-literature'

Example:

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


// Works on any locale — the library resolves the correct category ID
const { items } = await catalog(credentials, { category: 'thriller' })


// Sub-genres use slash notation for more specific results
const { items: spaceOpera } = await catalog(credentials, {
  category: 'science-fiction/space-opera',
})

AuthSession

Section titled “AuthSession”

PKCE session data. Returned by login(), passed to register().

type AuthSession = {
  codeVerifier: string     // PKCE code verifier
  serial: string           // Device serial
  locale: AudibleLocale    // Marketplace locale
  createdAt: Date          // When the session was created
}

AudibleCookie

Section titled “AudibleCookie”

A cookie to set in the browser before redirecting to the login URL.

type AudibleCookie = {
  name: string    // "frc", "map-md", or "amzn-app-id"
  value: string   // Cookie value
  domain: string  // ".amazon.fr"
}

LocaleConfig

Section titled “LocaleConfig”

Configuration for a specific Audible marketplace.

type LocaleConfig = {
  domain: string        // "fr"
  marketplaceId: string // "A2728XDNODOQ8T"
  countryCode: string   // "fr"
}

Accessible via the AUDIBLE_LOCALES constant.