Integración de API de Buttondown

Una integración completa de TypeScript para el servicio de boletín informativo Buttondown, que proporciona una interfaz CLI y un servidor de Protocolo de contexto de modelo (MCP) para administrar boletines informativos, borradores y análisis.

Características

• Interfaces múltiples :

  • Interfaz de línea de comandos (CLI) para interacción directa

  • Servidor de Protocolo de Contexto de Modelo (MCP) para la integración de IA/LLM

  • API programática de TypeScript para integraciones personalizadas

• Funcionalidad principal :

  • Gestión de borradores de correo electrónico (crear, actualizar, eliminar)

  • Sistema de programación de correo electrónico

  • Recuperación y formato de análisis

  • Gestión de listas

  • Gestión de etiquetas

• Seguridad :

  • Integración de 1Password para la gestión de claves API

  • Soporte de variables de entorno

  • Manejo seguro de credenciales

• Experiencia de desarrollador :

  • Compatibilidad total con TypeScript

  • Definiciones de tipos completas

  • Tipos basados en respuestas de API reales

  • Utilidades de prueba integradas

Related MCP server: Buttondown MCP Server

Instalación

# Install using pnpm (recommended)
pnpm install

# Or using npm
npm install

# Or using yarn
yarn install

Configuración

La clave API se puede proporcionar de dos maneras:

1. Variable de entorno:

   export BUTTONDOWN_API_KEY=your_api_key

2. CLI de 1Password (recomendado):

   • Guarde su clave API en 1Password en op://Development/Buttondown API/notesPlain

   • La integración lo recuperará automáticamente cuando sea necesario.

Uso

Interfaz CLI

# List all emails
buttondown emails list

# Create a new draft
buttondown draft create <file>

# Schedule an email
buttondown schedule set <draft-id> <relative-time>

# Get analytics
buttondown analytics get <draft-id>

Servidor MCP

1. Iniciar el servidor:

   pnpm mcp:start

2. Comenzar con el inspector (para desarrollo):

   pnpm mcp:inspect

Herramientas MCP disponibles:

• list_emails : enumera todos los correos electrónicos con filtrado de estado opcional

  {
    "status": "draft" // Optional: "draft", "scheduled", "sent"
  }

• create_draft : Crea un nuevo borrador de correo electrónico

  {
    "content": "Email content in markdown",
    "title": "Optional email subject"
  }

• get_analytics : Obtener análisis para un correo electrónico específico

  {
    "draftId": "email-id-here"
  }

• schedule_draft : Programar un correo electrónico para enviar

  {
    "draftId": "email-id-here",
    "scheduledTime": "2024-03-27T10:00:00Z"
  }

Uso programático

import { ButtondownAPI } from "api-integrator";

// Initialize the client
const api = new ButtondownAPI(); // Will use 1Password or env var

// List drafts
const drafts = await api.getDrafts();

// Create a draft
const draft = await api.createEmail({
  subject: "My Newsletter",
  body: "Content here",
  status: "draft",
});

// Schedule an email
const scheduled = await api.scheduleEmail(draft.id, "2024-03-27T10:00:00Z");

// Get analytics
const analytics = await api.getEmailStats(draft.id);

Desarrollo

# Build the project
pnpm build

# Run tests
pnpm test

# Start MCP server in development mode
pnpm mcp:inspect

# Build MCP server
pnpm mcp:build

Pruebas

El proyecto incluye varios tipos de pruebas:

• Pruebas unitarias para la funcionalidad principal

• Pruebas de integración para interacciones de API

• Pruebas de comandos CLI

• Pruebas del servidor MCP

Ejecutar pruebas con:

pnpm test

Estructura del proyecto

.
├── src/
│   ├── api/          # Core API client
│   ├── cli/          # CLI implementation
│   ├── mcp/          # MCP server
│   ├── types/        # TypeScript definitions
│   └── utils/        # Shared utilities
├── tests/            # Test files
├── api-responses/    # Cached API responses
└── memory-bank/      # Project documentation

Contribuyendo

1. Bifurcar el repositorio

2. Crea tu rama de funciones ( git checkout -b feature/amazing-feature )

3. Confirme sus cambios ( git commit -m 'Add some amazing feature' )

4. Empujar a la rama ( git push origin feature/amazing-feature )

5. Abrir una solicitud de extracción

Licencia

Licencia ISC - Ver LICENCIA para más detalles

Expresiones de gratitud

• Buttondown por su excelente servicio de newsletter

• Protocolo de contexto modelo para el marco de integración de IA