singer-tap-kit 0.1.0__tar.gz

singer_tap_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andrew Jones
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

singer_tap_kit-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.3
+Name: singer-tap-kit
+Version: 0.1.0
+Summary: Singer.io tap for extracting data from the Kit API
+Author: Andrew Jones
+Author-email: Andrew Jones <andrew@andrew-jones.com>
+License: MIT License
+         
+         Copyright (c) 2025 Andrew Jones
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Requires-Dist: singer-python>=5.13.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: pytest>=7.0.0 ; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10.0 ; extra == 'dev'
+Requires-Python: >=3.9
+Project-URL: Homepage, https://github.com/andrewjones/tap-kit
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# tap-kit
+
+A [Singer](https://singer.io) tap for extracting data from the [Kit API](https://developers.kit.com/).
+
+## Installation
+
+```bash
+pip install singer-tap-kit
+```
+
+Or run directly with `uvx`.
+
+```bash
+uvx --from singer-tap-kit tap-kit --help
+
+# Example with CSV target
+uvx --from singer-tap-kit tap-kit --config config.json | uvx --with setuptools target-csv
+```
+
+## Configuration
+
+Create a `config.json` file with your Kit v4 API key:
+
+```json
+{
+  "api_key": "your_kit_v4_api_key_here",
+  "start_date": "2024-01-01T00:00:00Z"
+}
+```
+
+- `api_key` (required): Your Kit v4 API key, sent as the `X-Kit-Api-Key` header.
+- `start_date` (optional): ISO 8601 timestamp used as the initial incremental bookmark.
+
+You can find your API key in your [Kit API settings](https://app.kit.com/account_settings/developer_settings).
+
+## Usage
+
+### Discover available streams
+
+```bash
+tap-kit --config config.json --discover
+```
+
+This will output a catalog of available streams in JSON format.
+
+### Run the tap
+
+```bash
+tap-kit --config config.json --catalog catalog.json
+```
+
+Or to use the default catalog:
+
+```bash
+tap-kit --config config.json
+```
+
+### State management
+
+To maintain state between runs (for incremental syncs):
+
+```bash
+tap-kit --config config.json --state state.json
+```
+
+## Streams
+
+Stats are modelled as their own snapshot streams (`broadcast_stats`,
+`subscriber_stats`) rather than merged into the entity records. Engagement metrics
+change over time, so each sync stamps every stat row with a `synced_at` timestamp
+and uses a composite primary key of `[id, synced_at]`. This captures a point-in-time
+snapshot per run: on append-style targets every run adds rows; on merge/upsert
+targets (e.g. BigQuery MERGE on key properties) the new `synced_at` inserts rather
+than overwriting. Partition the snapshot tables on `synced_at` in your warehouse.
+
+### Broadcasts
+
+The `broadcasts` stream extracts broadcast entity data from your Kit account.
+
+**Schema:**
+- `id` (integer): Unique broadcast ID
+- `publication_id` (integer, nullable): Publication ID
+- `created_at` (datetime): When the broadcast was created
+- `subject` (string, nullable): Broadcast subject line
+- `preview_text` (string, nullable): Inbox preview text
+- `description` (string, nullable): Broadcast description
+- `content` (string, nullable): Broadcast content
+- `public` (boolean, nullable): Whether the broadcast is public
+- `published_at` (datetime, nullable): When the broadcast was published
+- `send_at` (datetime, nullable): When the broadcast was/will be sent
+- `thumbnail_alt` (string, nullable): Thumbnail alt text
+- `thumbnail_url` (string, nullable): Thumbnail URL
+- `public_url` (string, nullable): Public URL for the broadcast
+- `email_address` (string, nullable): Sender email address
+- `email_template` (object, nullable): Email template (id, name)
+- `subscriber_filter` (array/object, nullable): Subscriber targeting filter
+- `status` (string, nullable): Broadcast status
+
+**Replication Method:** INCREMENTAL
+**Replication Key:** `created_at`
+**Primary Key:** `id`
+
+### Broadcast Stats
+
+The `broadcast_stats` stream snapshots delivery/engagement stats for every
+broadcast, fetched in bulk from the `/broadcasts/stats` batch endpoint.
+
+**Schema:**
+- `id` (integer): Broadcast ID
+- `synced_at` (datetime): Snapshot timestamp for this sync run
+- `recipients` (integer, nullable): Number of recipients
+- `open_rate` (number, nullable): Email open rate
+- `emails_opened` (integer, nullable): Number of emails opened
+- `click_rate` (number, nullable): Email click rate
+- `unsubscribe_rate` (number, nullable): Unsubscribe rate
+- `unsubscribes` (integer, nullable): Number of unsubscribes
+- `total_clicks` (integer, nullable): Total number of clicks
+- `show_total_clicks` (boolean, nullable): Whether to show total clicks
+- `status` (string, nullable): Broadcast status
+- `progress` (number, nullable): Send progress percentage
+- `open_tracking_disabled` (boolean, nullable): Whether open tracking is off
+- `click_tracking_disabled` (boolean, nullable): Whether click tracking is off
+
+**Replication Method:** FULL_TABLE
+**Primary Key:** `id`, `synced_at`
+
+### Subscribers
+
+The `subscribers` stream extracts subscriber data from your Kit account.
+
+**Schema:**
+- `id` (integer): Unique subscriber ID
+- `first_name` (string, nullable): Subscriber first name
+- `email_address` (string): Subscriber email address
+- `state` (string, nullable): Subscriber state (e.g., "active", "inactive")
+- `created_at` (datetime): When the subscriber was created
+- `fields` (object, nullable): Custom fields
+
+**Replication Method:** INCREMENTAL
+**Replication Key:** `created_at`
+
+### Subscriber Stats
+
+The `subscriber_stats` stream snapshots per-subscriber engagement stats.
+
+**Schema:**
+- `id` (integer): Subscriber ID
+- `synced_at` (datetime): Snapshot timestamp for this sync run
+- `sent` (integer, nullable): Emails sent
+- `opened` (integer, nullable): Emails opened
+- `clicked` (integer, nullable): Emails clicked
+- `bounced` (integer, nullable): Emails bounced
+- `open_rate` (number, nullable): Open rate
+- `click_rate` (number, nullable): Click rate
+- `last_sent` (datetime, nullable): Last send timestamp
+- `last_opened` (datetime, nullable): Last open timestamp
+- `last_clicked` (datetime, nullable): Last click timestamp
+- `sends_since_last_open` (integer, nullable): Sends since last open
+- `sends_since_last_click` (integer, nullable): Sends since last click
+
+**Replication Method:** FULL_TABLE
+**Primary Key:** `id`, `synced_at`
+
+**Note:** This stream makes one API call per subscriber. Kit rate-limits to 120
+requests per rolling 60 seconds, so large subscriber lists will sync slowly; the
+tap automatically retries on rate-limit (HTTP 429) responses.
+
+## Development
+
+This project is managed with `uv`.
+
+### Setup
+
+1. Clone the repository
+1. Create a `config.json` file with your API key
+
+### Testing
+
+```bash
+# Discover streams
+uv run tap-kit --config config.json --discover
+
+# Run sync
+uv run tap-kit --config config.json
+```
+
+## License
+
+This project is licensed under the MIT License.

singer_tap_kit-0.1.0/README.md

@@ -0,0 +1,189 @@
+# tap-kit
+
+A [Singer](https://singer.io) tap for extracting data from the [Kit API](https://developers.kit.com/).
+
+## Installation
+
+```bash
+pip install singer-tap-kit
+```
+
+Or run directly with `uvx`.
+
+```bash
+uvx --from singer-tap-kit tap-kit --help
+
+# Example with CSV target
+uvx --from singer-tap-kit tap-kit --config config.json | uvx --with setuptools target-csv
+```
+
+## Configuration
+
+Create a `config.json` file with your Kit v4 API key:
+
+```json
+{
+  "api_key": "your_kit_v4_api_key_here",
+  "start_date": "2024-01-01T00:00:00Z"
+}
+```
+
+- `api_key` (required): Your Kit v4 API key, sent as the `X-Kit-Api-Key` header.
+- `start_date` (optional): ISO 8601 timestamp used as the initial incremental bookmark.
+
+You can find your API key in your [Kit API settings](https://app.kit.com/account_settings/developer_settings).
+
+## Usage
+
+### Discover available streams
+
+```bash
+tap-kit --config config.json --discover
+```
+
+This will output a catalog of available streams in JSON format.
+
+### Run the tap
+
+```bash
+tap-kit --config config.json --catalog catalog.json
+```
+
+Or to use the default catalog:
+
+```bash
+tap-kit --config config.json
+```
+
+### State management
+
+To maintain state between runs (for incremental syncs):
+
+```bash
+tap-kit --config config.json --state state.json
+```
+
+## Streams
+
+Stats are modelled as their own snapshot streams (`broadcast_stats`,
+`subscriber_stats`) rather than merged into the entity records. Engagement metrics
+change over time, so each sync stamps every stat row with a `synced_at` timestamp
+and uses a composite primary key of `[id, synced_at]`. This captures a point-in-time
+snapshot per run: on append-style targets every run adds rows; on merge/upsert
+targets (e.g. BigQuery MERGE on key properties) the new `synced_at` inserts rather
+than overwriting. Partition the snapshot tables on `synced_at` in your warehouse.
+
+### Broadcasts
+
+The `broadcasts` stream extracts broadcast entity data from your Kit account.
+
+**Schema:**
+- `id` (integer): Unique broadcast ID
+- `publication_id` (integer, nullable): Publication ID
+- `created_at` (datetime): When the broadcast was created
+- `subject` (string, nullable): Broadcast subject line
+- `preview_text` (string, nullable): Inbox preview text
+- `description` (string, nullable): Broadcast description
+- `content` (string, nullable): Broadcast content
+- `public` (boolean, nullable): Whether the broadcast is public
+- `published_at` (datetime, nullable): When the broadcast was published
+- `send_at` (datetime, nullable): When the broadcast was/will be sent
+- `thumbnail_alt` (string, nullable): Thumbnail alt text
+- `thumbnail_url` (string, nullable): Thumbnail URL
+- `public_url` (string, nullable): Public URL for the broadcast
+- `email_address` (string, nullable): Sender email address
+- `email_template` (object, nullable): Email template (id, name)
+- `subscriber_filter` (array/object, nullable): Subscriber targeting filter
+- `status` (string, nullable): Broadcast status
+
+**Replication Method:** INCREMENTAL
+**Replication Key:** `created_at`
+**Primary Key:** `id`
+
+### Broadcast Stats
+
+The `broadcast_stats` stream snapshots delivery/engagement stats for every
+broadcast, fetched in bulk from the `/broadcasts/stats` batch endpoint.
+
+**Schema:**
+- `id` (integer): Broadcast ID
+- `synced_at` (datetime): Snapshot timestamp for this sync run
+- `recipients` (integer, nullable): Number of recipients
+- `open_rate` (number, nullable): Email open rate
+- `emails_opened` (integer, nullable): Number of emails opened
+- `click_rate` (number, nullable): Email click rate
+- `unsubscribe_rate` (number, nullable): Unsubscribe rate
+- `unsubscribes` (integer, nullable): Number of unsubscribes
+- `total_clicks` (integer, nullable): Total number of clicks
+- `show_total_clicks` (boolean, nullable): Whether to show total clicks
+- `status` (string, nullable): Broadcast status
+- `progress` (number, nullable): Send progress percentage
+- `open_tracking_disabled` (boolean, nullable): Whether open tracking is off
+- `click_tracking_disabled` (boolean, nullable): Whether click tracking is off
+
+**Replication Method:** FULL_TABLE
+**Primary Key:** `id`, `synced_at`
+
+### Subscribers
+
+The `subscribers` stream extracts subscriber data from your Kit account.
+
+**Schema:**
+- `id` (integer): Unique subscriber ID
+- `first_name` (string, nullable): Subscriber first name
+- `email_address` (string): Subscriber email address
+- `state` (string, nullable): Subscriber state (e.g., "active", "inactive")
+- `created_at` (datetime): When the subscriber was created
+- `fields` (object, nullable): Custom fields
+
+**Replication Method:** INCREMENTAL
+**Replication Key:** `created_at`
+
+### Subscriber Stats
+
+The `subscriber_stats` stream snapshots per-subscriber engagement stats.
+
+**Schema:**
+- `id` (integer): Subscriber ID
+- `synced_at` (datetime): Snapshot timestamp for this sync run
+- `sent` (integer, nullable): Emails sent
+- `opened` (integer, nullable): Emails opened
+- `clicked` (integer, nullable): Emails clicked
+- `bounced` (integer, nullable): Emails bounced
+- `open_rate` (number, nullable): Open rate
+- `click_rate` (number, nullable): Click rate
+- `last_sent` (datetime, nullable): Last send timestamp
+- `last_opened` (datetime, nullable): Last open timestamp
+- `last_clicked` (datetime, nullable): Last click timestamp
+- `sends_since_last_open` (integer, nullable): Sends since last open
+- `sends_since_last_click` (integer, nullable): Sends since last click
+
+**Replication Method:** FULL_TABLE
+**Primary Key:** `id`, `synced_at`
+
+**Note:** This stream makes one API call per subscriber. Kit rate-limits to 120
+requests per rolling 60 seconds, so large subscriber lists will sync slowly; the
+tap automatically retries on rate-limit (HTTP 429) responses.
+
+## Development
+
+This project is managed with `uv`.
+
+### Setup
+
+1. Clone the repository
+1. Create a `config.json` file with your API key
+
+### Testing
+
+```bash
+# Discover streams
+uv run tap-kit --config config.json --discover
+
+# Run sync
+uv run tap-kit --config config.json
+```
+
+## License
+
+This project is licensed under the MIT License.

singer_tap_kit-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "singer-tap-kit"
+version = "0.1.0"
+description = "Singer.io tap for extracting data from the Kit API"
+readme = "README.md"
+authors = [
+    { name = "Andrew Jones", email = "andrew@andrew-jones.com" }
+]
+license = { file = "LICENSE" }
+classifiers = [
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "singer-python>=5.13.0",
+    "requests>=2.31.0",
+    "python-dateutil>=2.8.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/andrewjones/tap-kit"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-mock>=3.10.0",
+]
+
+[project.scripts]
+tap-kit = "tap_kit:main"
+
+[build-system]
+requires = ["uv_build>=0.8.4,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "tap_kit"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.12.9",
+]

singer_tap_kit-0.1.0/src/tap_kit/__init__.py

@@ -0,0 +1,446 @@
+import json
+import sys
+import time
+from datetime import datetime, timezone
+from typing import Dict, Any, List, Optional
+import requests
+from singer import get_bookmark, write_record, write_schema, get_logger, parse_args
+from singer.catalog import Catalog, CatalogEntry, Schema
+
+
+REQUIRED_CONFIG_KEYS = ["api_key"]
+CONFIG = {}
+STATE = {}
+LOGGER = get_logger()
+
+DEFAULT_PER_PAGE = 500
+MAX_RATE_LIMIT_RETRIES = 5
+
+STREAM_CONFIG = {
+    "broadcasts": {
+        "replication_method": "INCREMENTAL",
+        "replication_key": "created_at",
+        "key_properties": ["id"],
+    },
+    "broadcast_stats": {
+        "replication_method": "FULL_TABLE",
+        "replication_key": None,
+        "key_properties": ["id", "synced_at"],
+    },
+    "subscribers": {
+        "replication_method": "INCREMENTAL",
+        "replication_key": "created_at",
+        "key_properties": ["id"],
+    },
+    "subscriber_stats": {
+        "replication_method": "FULL_TABLE",
+        "replication_key": None,
+        "key_properties": ["id", "synced_at"],
+    },
+}
+
+
+def utc_now() -> str:
+    """Current UTC time as an ISO 8601 string, used to stamp stat snapshots."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+class KitAPI:
+    """Client for the Kit v4 API"""
+
+    def __init__(self, api_key: str):
+        self.api_key = api_key
+        self.base_url = "https://api.kit.com/v4"
+        self.headers = {
+            "X-Kit-Api-Key": api_key,
+            "Accept": "application/json",
+        }
+
+    def _get(
+        self, path: str, params: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """GET a path, retrying on rate limit (HTTP 429)."""
+        url = f"{self.base_url}{path}"
+
+        for attempt in range(MAX_RATE_LIMIT_RETRIES + 1):
+            response = requests.get(url, headers=self.headers, params=params)
+
+            if response.status_code == 429 and attempt < MAX_RATE_LIMIT_RETRIES:
+                retry_after = response.headers.get("Retry-After")
+                wait = float(retry_after) if retry_after else 2**attempt
+                LOGGER.warning(
+                    f"Rate limited on {path}, retrying in {wait}s "
+                    f"(attempt {attempt + 1}/{MAX_RATE_LIMIT_RETRIES})"
+                )
+                time.sleep(wait)
+                continue
+
+            response.raise_for_status()
+            return response.json()
+
+        response.raise_for_status()
+        return response.json()
+
+    def list_broadcasts(
+        self, after: Optional[str] = None, per_page: int = DEFAULT_PER_PAGE
+    ) -> Dict[str, Any]:
+        """Fetch a page of broadcasts."""
+        params = {"per_page": per_page}
+        if after:
+            params["after"] = after
+        return self._get("/broadcasts", params)
+
+    def list_broadcast_stats(
+        self, after: Optional[str] = None, per_page: int = DEFAULT_PER_PAGE
+    ) -> Dict[str, Any]:
+        """Fetch a page of broadcast stats (batch endpoint)."""
+        params = {"per_page": per_page}
+        if after:
+            params["after"] = after
+        return self._get("/broadcasts/stats", params)
+
+    def list_subscribers(
+        self, after: Optional[str] = None, per_page: int = DEFAULT_PER_PAGE
+    ) -> Dict[str, Any]:
+        """Fetch a page of subscribers."""
+        params = {"per_page": per_page}
+        if after:
+            params["after"] = after
+        return self._get("/subscribers", params)
+
+    def get_subscriber_stats(self, subscriber_id: int) -> Dict[str, Any]:
+        """Fetch stats for a single subscriber."""
+        return self._get(f"/subscribers/{subscriber_id}/stats")
+
+
+def load_schemas() -> Dict[str, Schema]:
+    """Define schemas for each stream."""
+    schemas = {}
+
+    broadcast_schema = {
+        "type": "object",
+        "properties": {
+            "id": {"type": "integer"},
+            "publication_id": {"type": ["null", "integer"]},
+            "created_at": {"type": "string", "format": "date-time"},
+            "subject": {"type": ["null", "string"]},
+            "preview_text": {"type": ["null", "string"]},
+            "description": {"type": ["null", "string"]},
+            "content": {"type": ["null", "string"]},
+            "public": {"type": ["null", "boolean"]},
+            "published_at": {"type": ["null", "string"], "format": "date-time"},
+            "send_at": {"type": ["null", "string"], "format": "date-time"},
+            "thumbnail_alt": {"type": ["null", "string"]},
+            "thumbnail_url": {"type": ["null", "string"]},
+            "public_url": {"type": ["null", "string"]},
+            "email_address": {"type": ["null", "string"]},
+            "email_template": {"type": ["null", "object"]},
+            "subscriber_filter": {"type": ["null", "array", "object"]},
+            "status": {"type": ["null", "string"]},
+        },
+    }
+
+    broadcast_stats_schema = {
+        "type": "object",
+        "properties": {
+            "id": {"type": "integer"},
+            "synced_at": {"type": "string", "format": "date-time"},
+            "recipients": {"type": ["null", "integer"]},
+            "open_rate": {"type": ["null", "number"]},
+            "emails_opened": {"type": ["null", "integer"]},
+            "click_rate": {"type": ["null", "number"]},
+            "unsubscribe_rate": {"type": ["null", "number"]},
+            "unsubscribes": {"type": ["null", "integer"]},
+            "total_clicks": {"type": ["null", "integer"]},
+            "show_total_clicks": {"type": ["null", "boolean"]},
+            "status": {"type": ["null", "string"]},
+            "progress": {"type": ["null", "number"]},
+            "open_tracking_disabled": {"type": ["null", "boolean"]},
+            "click_tracking_disabled": {"type": ["null", "boolean"]},
+        },
+    }
+
+    subscriber_schema = {
+        "type": "object",
+        "properties": {
+            "id": {"type": "integer"},
+            "first_name": {"type": ["null", "string"]},
+            "email_address": {"type": "string"},
+            "state": {"type": ["null", "string"]},
+            "created_at": {"type": "string", "format": "date-time"},
+            "fields": {"type": ["null", "object"]},
+        },
+    }
+
+    subscriber_stats_schema = {
+        "type": "object",
+        "properties": {
+            "id": {"type": "integer"},
+            "synced_at": {"type": "string", "format": "date-time"},
+            "sent": {"type": ["null", "integer"]},
+            "opened": {"type": ["null", "integer"]},
+            "clicked": {"type": ["null", "integer"]},
+            "bounced": {"type": ["null", "integer"]},
+            "open_rate": {"type": ["null", "number"]},
+            "click_rate": {"type": ["null", "number"]},
+            "last_sent": {"type": ["null", "string"], "format": "date-time"},
+            "last_opened": {"type": ["null", "string"], "format": "date-time"},
+            "last_clicked": {"type": ["null", "string"], "format": "date-time"},
+            "sends_since_last_open": {"type": ["null", "integer"]},
+            "sends_since_last_click": {"type": ["null", "integer"]},
+        },
+    }
+
+    schemas["broadcasts"] = Schema.from_dict(broadcast_schema)
+    schemas["broadcast_stats"] = Schema.from_dict(broadcast_stats_schema)
+    schemas["subscribers"] = Schema.from_dict(subscriber_schema)
+    schemas["subscriber_stats"] = Schema.from_dict(subscriber_stats_schema)
+
+    return schemas
+
+
+def discover() -> Catalog:
+    """Discover available streams and schemas."""
+    schemas = load_schemas()
+    streams = []
+
+    for stream_id, schema in schemas.items():
+        stream_settings = STREAM_CONFIG[stream_id]
+        replication_method = stream_settings["replication_method"]
+        replication_key = stream_settings["replication_key"]
+        key_properties = stream_settings["key_properties"]
+
+        metadata_entry = {
+            "inclusion": "available",
+            "table-key-properties": key_properties,
+            "schema-name": stream_id,
+        }
+        if replication_key:
+            metadata_entry["valid-replication-keys"] = [replication_key]
+
+        stream_metadata = [{"metadata": metadata_entry, "breadcrumb": []}]
+
+        catalog_entry = CatalogEntry(
+            stream=stream_id,
+            tap_stream_id=stream_id,
+            schema=schema,
+            key_properties=key_properties,
+            replication_key=replication_key,
+            metadata=stream_metadata,
+            replication_method=replication_method,
+        )
+
+        streams.append(catalog_entry)
+
+    return Catalog(streams)
+
+
+def sync_broadcasts(
+    config: Dict[str, Any], state: Dict[str, Any], catalog: Catalog
+) -> None:
+    """Sync broadcasts stream (entity records, no stats)."""
+    api = KitAPI(config["api_key"])
+
+    broadcasts_catalog = catalog.get_stream("broadcasts")
+    if not broadcasts_catalog:
+        LOGGER.error("Broadcasts stream not found in catalog")
+        return
+
+    get_bookmark(
+        state,
+        "broadcasts",
+        broadcasts_catalog.replication_key,
+        config.get("start_date"),
+    )
+
+    write_schema(
+        "broadcasts",
+        broadcasts_catalog.schema.to_dict(),
+        key_properties=broadcasts_catalog.key_properties,
+    )
+
+    after = None
+    total_records = 0
+
+    while True:
+        response = api.list_broadcasts(after=after)
+        broadcasts = response.get("broadcasts") or []
+
+        for broadcast in broadcasts:
+            write_record("broadcasts", broadcast)
+            total_records += 1
+
+        pagination = response.get("pagination") or {}
+        if not pagination.get("has_next_page"):
+            break
+        after = pagination.get("end_cursor")
+        if not after:
+            break
+
+    LOGGER.info(f"Synced {total_records} broadcast records")
+
+
+def sync_broadcast_stats(
+    config: Dict[str, Any], catalog: Catalog, synced_at: str
+) -> None:
+    """Sync broadcast_stats snapshot stream via the batch stats endpoint."""
+    api = KitAPI(config["api_key"])
+
+    stats_catalog = catalog.get_stream("broadcast_stats")
+    if not stats_catalog:
+        LOGGER.error("Broadcast_stats stream not found in catalog")
+        return
+
+    write_schema(
+        "broadcast_stats",
+        stats_catalog.schema.to_dict(),
+        key_properties=stats_catalog.key_properties,
+    )
+
+    after = None
+    total_records = 0
+
+    while True:
+        response = api.list_broadcast_stats(after=after)
+        broadcasts = response.get("broadcasts") or []
+
+        for broadcast in broadcasts:
+            stats = broadcast.get("stats") or {}
+            record = {"id": broadcast["id"], "synced_at": synced_at, **stats}
+            write_record("broadcast_stats", record)
+            total_records += 1
+
+        pagination = response.get("pagination") or {}
+        if not pagination.get("has_next_page"):
+            break
+        after = pagination.get("end_cursor")
+        if not after:
+            break
+
+    LOGGER.info(f"Synced {total_records} broadcast_stats records")
+
+
+def sync_subscribers(
+    config: Dict[str, Any], state: Dict[str, Any], catalog: Catalog
+) -> List[int]:
+    """Sync subscribers stream. Returns the list of subscriber ids seen."""
+    api = KitAPI(config["api_key"])
+
+    subscribers_catalog = catalog.get_stream("subscribers")
+    if not subscribers_catalog:
+        LOGGER.error("Subscribers stream not found in catalog")
+        return []
+
+    get_bookmark(
+        state,
+        "subscribers",
+        subscribers_catalog.replication_key,
+        config.get("start_date"),
+    )
+
+    write_schema(
+        "subscribers",
+        subscribers_catalog.schema.to_dict(),
+        key_properties=subscribers_catalog.key_properties,
+    )
+
+    after = None
+    total_records = 0
+    subscriber_ids: List[int] = []
+
+    while True:
+        response = api.list_subscribers(after=after)
+        subscribers = response.get("subscribers") or []
+
+        for subscriber in subscribers:
+            write_record("subscribers", subscriber)
+            subscriber_ids.append(subscriber["id"])
+            total_records += 1
+
+        pagination = response.get("pagination") or {}
+        if not pagination.get("has_next_page"):
+            break
+        after = pagination.get("end_cursor")
+        if not after:
+            break
+
+    LOGGER.info(f"Synced {total_records} subscriber records")
+    return subscriber_ids
+
+
+def sync_subscriber_stats(
+    config: Dict[str, Any],
+    catalog: Catalog,
+    subscriber_ids: List[int],
+    synced_at: str,
+) -> None:
+    """Sync subscriber_stats snapshot stream (one API call per subscriber)."""
+    api = KitAPI(config["api_key"])
+
+    stats_catalog = catalog.get_stream("subscriber_stats")
+    if not stats_catalog:
+        LOGGER.error("Subscriber_stats stream not found in catalog")
+        return
+
+    write_schema(
+        "subscriber_stats",
+        stats_catalog.schema.to_dict(),
+        key_properties=stats_catalog.key_properties,
+    )
+
+    total_records = 0
+
+    for subscriber_id in subscriber_ids:
+        try:
+            response = api.get_subscriber_stats(subscriber_id)
+        except requests.exceptions.RequestException as e:
+            LOGGER.warning(f"Error fetching stats for subscriber {subscriber_id}: {e}")
+            continue
+
+        subscriber = response.get("subscriber") or {}
+        stats = subscriber.get("stats") or {}
+        record = {
+            "id": subscriber.get("id", subscriber_id),
+            "synced_at": synced_at,
+            **stats,
+        }
+        write_record("subscriber_stats", record)
+        total_records += 1
+
+    LOGGER.info(f"Synced {total_records} subscriber_stats records")
+
+
+def sync(config: Dict[str, Any], state: Dict[str, Any], catalog: Catalog) -> None:
+    """Sync all selected streams."""
+    stream_ids = {stream.tap_stream_id for stream in catalog.streams}
+    synced_at = utc_now()
+
+    if "broadcasts" in stream_ids:
+        sync_broadcasts(config, state, catalog)
+
+    if "broadcast_stats" in stream_ids:
+        sync_broadcast_stats(config, catalog, synced_at)
+
+    if "subscribers" in stream_ids or "subscriber_stats" in stream_ids:
+        subscriber_ids = sync_subscribers(config, state, catalog)
+        if "subscriber_stats" in stream_ids:
+            sync_subscriber_stats(config, catalog, subscriber_ids, synced_at)
+
+
+def main() -> None:
+    """Main entry point."""
+    args = parse_args(REQUIRED_CONFIG_KEYS)
+
+    config = args.config
+    state = args.state
+    catalog = args.catalog if args.catalog else discover()
+
+    if args.discover:
+        catalog = discover()
+        json.dump(catalog.to_dict(), sys.stdout, indent=2)
+    else:
+        sync(config, state, catalog)
+
+
+if __name__ == "__main__":
+    main()