From 144a958a166ad0a8242c37eedad33b9384842866 Mon Sep 17 00:00:00 2001
From: oseovie <ovieose17@gmail.com>
Date: Thu, 21 May 2026 15:03:40 +0100
Subject: [PATCH] Add data types helper docs

---
 docs/source/data_types.rst           | 66 ++++++++++++++++++++++++++++
 docs/source/paystackease.helpers.rst |  1 +
 2 files changed, 67 insertions(+)
 create mode 100644 docs/source/data_types.rst

diff --git a/docs/source/data_types.rst b/docs/source/data_types.rst
new file mode 100644
index 0000000..2fd4d9e
--- /dev/null
+++ b/docs/source/data_types.rst
@@ -0,0 +1,66 @@
+=====================
+Data Types module
+=====================
+
+This holds Pydantic models used to validate helper data structures before
+passing them to Paystack API requests.
+
+BulkChargeItem
+---------------
+
+.. py:class:: BulkChargeItem
+
+    Bases: BaseModel
+
+    Represents a single bulk charge item for payment processing.
+
+    .. py:attribute:: authorization
+
+        The authorization code for the payment method. Must be a non-empty
+        string after stripping whitespace.
+
+    .. py:attribute:: amount
+
+        The charge amount in the smallest currency unit. Must be greater than
+        0.
+
+    .. py:attribute:: reference
+
+        A unique reference identifier for this charge. Must be a non-empty
+        string after stripping whitespace.
+
+BulkChargeListObject
+---------------------
+
+.. py:class:: BulkChargeListObject
+
+    Bases: BaseModel
+
+    Container for a list of bulk charge items with validation.
+
+    .. py:attribute:: charges
+
+        A list of validated :class:`BulkChargeItem` objects. Each item must
+        contain exactly ``authorization``, ``amount``, and ``reference`` keys.
+
+    .. py:property:: use_as_list
+
+        Convert the validated charges to a list of dictionaries for API use.
+
+**USAGE**
+
+.. code-block:: python
+
+    >>> from paystackease import BulkChargeListObject
+
+    >>> bulk_charges = BulkChargeListObject(
+    ...     charges=[
+    ...         {
+    ...             "authorization": "AUTH_12345",
+    ...             "amount": 1000,
+    ...             "reference": "REF_001",
+    ...         }
+    ...     ]
+    ... )
+    >>> bulk_charges.use_as_list
+    [{'authorization': 'AUTH_12345', 'amount': 1000, 'reference': 'REF_001'}]
diff --git a/docs/source/paystackease.helpers.rst b/docs/source/paystackease.helpers.rst
index 1dc86a2..4faa9ec 100644
--- a/docs/source/paystackease.helpers.rst
+++ b/docs/source/paystackease.helpers.rst
@@ -9,5 +9,6 @@ This contains the functionality to ease the pain of knowing what values to use.
    :maxdepth: 1
 
    convert
+   data_types
    toolkit