Metadata-Version: 2.3
Name: tap-buttondown
Version: 0.3.0
Summary: Singer.io tap for extracting data from the buttondown 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.8
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.8
Project-URL: Homepage, https://github.com/andrewjones/tap-buttondown
Provides-Extra: dev
Description-Content-Type: text/markdown

# tap-buttondown

A [Singer](https://singer.io) tap for extracting data from the [Buttondown API](https://buttondown.email/api).

## Installation

```bash
pip install tap-buttondown
```

Or run directly with `uvx`.

```bash
uvx tap-buttondown --help

# Example with CSV target
uvx tap-buttondown --config config.json | uvx --with setuptools target-csv
```

## Configuration

Create a `config.json` file with your Buttondown API key:

```json
{
  "api_key": "your_buttondown_api_key_here"
}
```

You can find your API key in your [Buttondown dashboard](https://buttondown.email/settings/api).

## Usage

### Discover available streams

```bash
tap-buttondown --config config.json --discover
```

This will output a catalog of available streams in JSON format.

### Run the tap

```bash
tap-buttondown --config config.json --catalog catalog.json
```

Or to use the default catalog:

```bash
tap-buttondown --config config.json
```

### State management

To maintain state between runs (for incremental syncs):

```bash
tap-buttondown --config config.json --state state.json
```

## Streams

### Subscribers

The `subscribers` stream extracts subscriber data from your Buttondown newsletter.

**Schema:**
- `id` (string): Unique subscriber ID
- `creation_date` (datetime): When the subscriber was created
- `email_address` (string): Subscriber email address
- `notes` (string): Notes about the subscriber
- `metadata` (object): Custom metadata
- `tags` (array): Tags associated with the subscriber
- `referrer_url` (string): Referrer URL
- `secondary_id` (integer): Secondary identifier
- `type` (string): Subscriber type (e.g., "unactivated", "regular", "undeliverable")
- `source` (string): Source of the subscription
- `utm_campaign` (string): UTM campaign parameter
- `utm_medium` (string): UTM medium parameter
- `utm_source` (string): UTM source parameter
- `referral_code` (string): Referral code
- `avatar_url` (string): Avatar URL
- `stripe_coupon` (string, nullable): Stripe coupon
- `unsubscription_date` (datetime, nullable): When the subscriber unsubscribed
- `churn_date` (datetime, nullable): When the subscriber churned
- `undeliverability_date` (datetime, nullable): When the subscriber became undeliverable
- `undeliverability_reason` (string, nullable): Reason for undeliverability
- `upgrade_date` (datetime, nullable): When the subscriber upgraded
- `unsubscription_reason` (string): Reason for unsubscription
- `transitions` (array): Transition history
- `ip_address` (string): IP address
- `last_open_date` (datetime, nullable): Last email open date
- `last_click_date` (datetime, nullable): Last email click date
- `stripe_customer_id` (string, nullable): Stripe customer ID
- `subscriber_import_id` (string, nullable): Import ID
- `risk_score` (number): Risk score
- `stripe_customer` (object, nullable): Stripe customer data

**Replication Method:** INCREMENTAL
**Replication Key:** `creation_date`

### Emails

The `emails` stream extracts email data from your Buttondown newsletter.

**Schema:**
- `id` (string): Unique email ID
- `creation_date` (datetime): When the email was created
- `modification_date` (datetime): When the email was last modified
- `publish_date` (datetime, nullable): When the email was published
- `subject` (string): Email subject line
- `body` (string): Email body content
- `status` (string): Email status (e.g., "draft", "sent", "scheduled")
- `slug` (string): URL slug for the email
- `canonical_url` (string): Canonical URL
- `email_type` (string): Type of email (e.g., "public", "private")
- `image` (string): Featured image URL
- `description` (string): Email description
- `metadata` (object): Custom metadata
- `source` (string): Source of the email
- `secondary_id` (integer, nullable): Secondary identifier
- `commenting_mode` (string): Commenting mode setting
- `absolute_url` (string): Absolute URL to the email
- `filters` (object): Email filters
- `analytics` (object, nullable): Email analytics data
- `template` (object, nullable): Email template data
- `attachments` (array): Email attachments
- `related_email_ids` (array): Related email IDs
- `featured` (boolean): Whether the email is featured
- `should_trigger_pay_per_email_billing` (boolean): Pay-per-email billing flag

**Replication Method:** INCREMENTAL
**Replication Key:** `modification_date`

## 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-buttondown --config config.json --discover

# Run sync
uv run tap-buttondown --config config.json
```

## License

This project is licensed under the MIT License.
