docs and tests for daisychain connector

Author: austinweisgrau

docs/daisychain.rst

@@ -0,0 +1,68 @@
+Daisychain
+==========
+
+********
+Overview
+********
+
+`Daisychain <https://www.daisychain.app/>`_ is a digital organizing automation tool that allows organizers to string together automated digital outreach steps, similar to Zapier but designed specifically for digital organizing. The Parsons connector provides methods for finding contacts and triggering events through the Daisychain API.
+
+This connector implements the ``people/match`` and ``actions`` endpoints of the Daisychain API, allowing you to find existing people records and post actions that can trigger automations.
+
+.. note::
+  Authentication
+    The Daisychain API uses API token authentication. You can generate your API token from your Daisychain account settings.
+
+***********
+Quick Start
+***********
+
+To instantiate the class, you can either pass in the API token as an argument or set the ``DAISYCHAIN_API_TOKEN`` environmental variable.
+
+.. code-block:: python
+
+   from parsons import Daisychain
+
+   # First approach: Use API credentials via environmental variables
+   dc = Daisychain()
+
+   # Second approach: Pass API credentials as arguments
+   dc = Daisychain(api_token='MY_API_TOKEN')
+
+You can then call various endpoints:
+
+.. code-block:: python
+
+    # Find a person by email address
+    people = dc.find_person(email_address='person@example.com')
+
+    # Find a person by phone number
+    people = dc.find_person(phone_number='+15555551234')
+
+    # Find a person by email and phone (AND logic)
+    people = dc.find_person(email_address='person@example.com', phone_number='+15555551234')
+
+    # Post an action to trigger an automation
+    # This will create a new person if they don't exist, or associate the action with an existing person
+    person_id = dc.post_action(
+        email_address='person@example.com',
+        phone_number='+15555551234',
+        first_name='Jane',
+        last_name='Doe',
+        email_opt_in=True,
+        sms_opt_in=True,
+        action_data={'type': 'petition_signature', 'petition_id': '12345'}
+    )
+
+    # Use action_data with custom fields to trigger specific automations
+    # The action_data can contain any JSON and be matched in Daisychain automation builder
+    person_id = dc.post_action(
+        email_address='volunteer@example.com',
+        action_data={'event_type': 'volunteer_signup', 'event_id': 'canvass_2024'}
+    )
+
+***
+API
+***
+.. autoclass :: parsons.Daisychain
+   :inherited-members:

docs/index.rst

@@ -198,6 +198,7 @@ Indices and tables
    controlshift
    copper
    crowdtangle
+   daisychain
    databases
    donorbox
    empower

test/test_daisychain/__init__.py

@@ -0,0 +1 @@
+# Empty init file for test module

test/test_daisychain/test_daisychain.py

@@ -0,0 +1,141 @@
+import unittest
+
+import pytest
+import requests_mock
+
+from parsons import Daisychain
+
+
+class TestDaisychain(unittest.TestCase):
+    def setUp(self):
+        self.api_token = "test_api_token"
+        self.connector = Daisychain(api_token=self.api_token)
+
+    def test_initialization(self):
+        """Test that Daisychain initializes with correct API token header."""
+        assert self.connector.connection.headers["X-API-Token"] == self.api_token
+        assert self.connector.connection.uri == "https://go.daisychain.app/api/v1/"
+
+    @requests_mock.Mocker()
+    def test_find_person_email(self, mocker):
+        """Test finding a person by email address."""
+        expected_response = {
+            "people": [
+                {
+                    "id": "person123",
+                    "email": "test@example.com",
+                    "first_name": "Test",
+                    "last_name": "User",
+                }
+            ]
+        }
+
+        mocker.post("https://go.daisychain.app/api/v1/people/match", json=expected_response)
+
+        result = self.connector.find_person(email_address="test@example.com")
+
+        assert result == expected_response["people"]
+        assert len(result) == 1
+        assert result[0]["email"] == "test@example.com"
+
+    @requests_mock.Mocker()
+    def test_find_person_phone(self, mocker):
+        """Test finding a person by phone number."""
+        expected_response = {
+            "people": [
+                {
+                    "id": "person456",
+                    "phone_number": "+15555551234",
+                    "first_name": "Jane",
+                    "last_name": "Doe",
+                }
+            ]
+        }
+
+        mocker.post("https://go.daisychain.app/api/v1/people/match", json=expected_response)
+
+        result = self.connector.find_person(phone_number="+15555551234")
+
+        assert result == expected_response["people"]
+        assert result[0]["phone_number"] == "+15555551234"
+
+    @requests_mock.Mocker()
+    def test_find_person_email_and_phone(self, mocker):
+        """Test finding a person by both email and phone."""
+        expected_response = {
+            "people": [
+                {
+                    "id": "person789",
+                    "email": "combo@example.com",
+                    "phone_number": "+15555559999",
+                    "first_name": "Combo",
+                    "last_name": "Test",
+                }
+            ]
+        }
+
+        mocker.post("https://go.daisychain.app/api/v1/people/match", json=expected_response)
+
+        result = self.connector.find_person(
+            email_address="combo@example.com", phone_number="+15555559999"
+        )
+
+        assert result == expected_response["people"]
+
+    def test_find_person_requires_parameter(self):
+        """Test that find_person requires at least one parameter."""
+        with pytest.raises(AssertionError):
+            self.connector.find_person()
+
+    @requests_mock.Mocker()
+    def test_post_action_minimal(self, mocker):
+        """Test posting an action with minimal data."""
+        expected_response = {"person": {"id": "person123"}}
+
+        mocker.post("https://go.daisychain.app/api/v1/actions", json=expected_response)
+
+        person_id = self.connector.post_action(email_address="test@example.com")
+
+        assert person_id == "person123"
+
+    @requests_mock.Mocker()
+    def test_post_action_full(self, mocker):
+        """Test posting an action with full person data."""
+        expected_response = {"person": {"id": "person456"}}
+
+        mocker.post("https://go.daisychain.app/api/v1/actions", json=expected_response)
+
+        person_id = self.connector.post_action(
+            email_address="test@example.com",
+            phone_number="+15555551234",
+            first_name="Jane",
+            last_name="Doe",
+            addresses=[{"city": "New York", "state": "NY"}],
+            email_opt_in=True,
+            sms_opt_in=True,
+            action_data={"type": "petition_signature", "petition_id": "12345"},
+        )
+
+        assert person_id == "person456"
+
+    @requests_mock.Mocker()
+    def test_post_action_custom_data(self, mocker):
+        """Test posting an action with custom action data."""
+        expected_response = {"person": {"id": "person789"}}
+
+        mocker.post("https://go.daisychain.app/api/v1/actions", json=expected_response)
+
+        custom_data = {
+            "event_type": "volunteer_signup",
+            "event_id": "canvass_2024",
+            "custom_field": "custom_value",
+        }
+
+        person_id = self.connector.post_action(phone_number="+15555559999", action_data=custom_data)
+
+        assert person_id == "person789"
+
+    def test_post_action_requires_contact(self):
+        """Test that post_action requires at least email or phone."""
+        with pytest.raises(AssertionError):
+            self.connector.post_action(first_name="Test", last_name="User")