From ccbaf5ff8c359ca55a272da2b81ed3bc3b7d4dcf Mon Sep 17 00:00:00 2001
From: Xoconoch <github@cordovault.com>
Date: Wed, 11 Jun 2025 11:43:10 -0600
Subject: [PATCH] enhance documentation

---
 docs/callback_examples.md | 214 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 214 insertions(+)

diff --git a/docs/callback_examples.md b/docs/callback_examples.md
index e3d5ca3..c3c4080 100644
--- a/docs/callback_examples.md
+++ b/docs/callback_examples.md
@@ -2,6 +2,15 @@
 
 This document provides examples for all possible callback JSON objects as generated by `deezspot`. These examples are based on the dataclasses defined in `deezspot/models/callback/`.
 
+## Naming Convention
+
+The data models in `deezspot/models/callback/` follow a specific naming convention to clarify the context of nested objects. The pattern is generally `childContext1Context2...Object`. This reads as "A `child` object representation when nested inside a `Context1` object, which itself is in a `Context2` context, and so on."
+
+For example:
+
+*   `playlistTrackObject`: This represents a `playlist` object within a `track` reporting context. It's a simplified version of a full `playlistObject` and is used as the parent for a track being processed as part of a playlist operation.
+*   `artistAlbumTrackPlaylistObject`: This represents an `artist` object, nested within an `album` object, which is inside a `track` object that is part of a `playlist`. This shows the full hierarchy of contexts.
+
 ## `trackCallbackObject` Examples
 
 A `trackCallbackObject` is sent to provide updates on the status of a single track's processing.
@@ -83,6 +92,211 @@ Indicates that the track processing is starting.
 }
 ```
 
+### Track with Parent Context
+
+When a track is processed as part of a larger operation (like downloading an album or playlist), the `parent` field in the `trackCallbackObject` will be populated. This provides context about the containing entity. `current_track` and `total_tracks` will also be populated accordingly.
+
+#### Parent: `albumTrackObject`
+
+This example shows a track being processed as part of an album download. The `parent` is an `albumTrackObject`, which provides a summary of the album. The `current_track` and `total_tracks` fields reflect the progress within that album.
+
+```json
+{
+  "track": {
+    "type": "track",
+    "title": "Bohemian Rhapsody",
+    "disc_number": 1,
+    "track_number": 7,
+    "duration_ms": 354320,
+    "explicit": false,
+    "genres": [
+      "Rock"
+    ],
+    "album": {
+      "type": "albumTrack",
+      "album_type": "album",
+      "title": "A Night at the Opera",
+      "release_date": {
+        "year": 1975,
+        "month": 11,
+        "day": 21
+      },
+      "total_tracks": 12,
+      "genres": [
+        "Rock"
+      ],
+      "images": [
+        {
+          "height": 640,
+          "url": "https://i.scdn.co/image/ab67616d0000b273e3b3b3b3b3b3b3b3b3b3b3b3",
+          "width": 640
+        }
+      ],
+      "ids": {
+        "spotify": "6l8GvAOfAccdwJAIF13j3m",
+        "deezer": "11223344"
+      },
+      "artists": [
+        {
+          "type": "artistAlbumTrack",
+          "name": "Queen",
+          "ids": {
+            "spotify": "1dfeR4HaWDbWqFHLkxsg1d",
+            "deezer": "412"
+          }
+        }
+      ]
+    },
+    "artists": [
+      {
+        "type": "artistTrack",
+        "name": "Queen",
+        "ids": {
+          "spotify": "1dfeR4HaWDbWqFHLkxsg1d",
+          "deezer": "412"
+        }
+      }
+    ],
+    "ids": {
+      "spotify": "4u7EnebtmKWzANvK9IClu8",
+      "deezer": "9876543",
+      "isrc": "GBUM71021259"
+    }
+  },
+  "status_info": {
+    "status": "initializing",
+    "ids": {
+      "spotify": "4u7EnebtmKWzANvK9IClu8"
+    },
+    "convert_to": "flac",
+    "bitrate": "1411"
+  },
+  "current_track": 2,
+  "total_tracks": 12,
+  "parent": {
+    "type": "albumTrack",
+    "album_type": "album",
+    "title": "A Night at the Opera",
+    "release_date": {
+      "year": 1975,
+      "month": 11,
+      "day": 21
+    },
+    "total_tracks": 12,
+    "genres": [
+      "Rock"
+    ],
+    "images": [
+      {
+        "height": 640,
+        "url": "https://i.scdn.co/image/ab67616d0000b273e3b3b3b3b3b3b3b3b3b3b3b3",
+        "width": 640
+      }
+    ],
+    "ids": {
+      "spotify": "6l8GvAOfAccdwJAIF13j3m",
+      "deezer": "11223344"
+    },
+    "artists": [
+      {
+        "type": "artistAlbumTrack",
+        "name": "Queen",
+        "ids": {
+          "spotify": "1dfeR4HaWDbWqFHLkxsg1d",
+          "deezer": "412"
+        }
+      }
+    ]
+  }
+}
+```
+
+#### Parent: `playlistTrackObject`
+
+This example shows a track being processed as part of a playlist download. The `parent` is a `playlistTrackObject`, which provides a summary of the playlist.
+
+```json
+{
+  "track": {
+    "type": "track",
+    "title": "Stairway to Heaven",
+    "disc_number": 1,
+    "track_number": 4,
+    "duration_ms": 482830,
+    "explicit": false,
+    "genres": [
+      "Rock"
+    ],
+    "album": {
+      "type": "albumTrack",
+      "album_type": "album",
+      "title": "Led Zeppelin IV",
+      "release_date": {
+        "year": 1971,
+        "month": 11,
+        "day": 8
+      },
+      "total_tracks": 8,
+      "genres": [
+        "Rock",
+        "Hard Rock"
+      ],
+      "images": [],
+      "ids": {
+        "spotify": "1J8mRIzSgWvztCMj2Y3GJc"
+      },
+      "artists": [
+        {
+          "type": "artistAlbumTrack",
+          "name": "Led Zeppelin",
+          "ids": {
+            "spotify": "36QJpDe2go2KgaRleHCDls"
+          }
+        }
+      ]
+    },
+    "artists": [
+      {
+        "type": "artistTrack",
+        "name": "Led Zeppelin",
+        "ids": {
+          "spotify": "36QJpDe2go2KgaRleHCDls"
+        }
+      }
+    ],
+    "ids": {
+      "spotify": "5CQ30WqJwcep0pYcV4AMNc",
+      "isrc": "US-AT2-00-00435"
+    }
+  },
+  "status_info": {
+    "status": "initializing",
+    "ids": {
+      "spotify": "5CQ30WqJwcep0pYcV4AMNc"
+    },
+    "convert_to": "mp3",
+    "bitrate": "320"
+  },
+  "current_track": 5,
+  "total_tracks": 50,
+  "parent": {
+    "type": "playlistTrack",
+    "title": "Classic Rock Anthems",
+    "description": "The greatest rock songs of all time.",
+    "owner": {
+      "name": "Spotify",
+      "type": "user",
+      "ids": {
+        "spotify": "spotify"
+      }
+    },
+    "ids": {
+      "spotify": "37i9dQZF1DX1rVvRgjX59F"
+    }
+  }
+}
+```
+
 ### Status: `skipped`
 
 Indicates that the track was skipped.