@agnocon/piece-buttondown 0.0.5

package/src/lib/common/client.ts

@@ -0,0 +1,83 @@
+import { HttpMethod, httpClient } from '@agnocon/pieces-common';
+
+export const BUTTONDOWN_BASE_URL = 'https://api.buttondown.com/v1';
+
+type QueryValue =
+  | string
+  | number
+  | boolean
+  | Array<string | number | boolean>
+  | undefined;
+
+export interface ButtondownRequest {
+  auth: string;
+  method: HttpMethod;
+  path: string;
+  query?: Record<string, QueryValue>;
+  body?: unknown;
+  headers?: Record<string, string | undefined>;
+}
+
+export interface ButtondownPagedResponse<T> {
+  results: T[];
+  count: number;
+  next?: string | null;
+  previous?: string | null;
+}
+
+const sanitizeHeaders = (headers: Record<string, string | undefined> = {}) =>
+  Object.fromEntries(
+    Object.entries(headers).filter(([, value]) => value !== undefined)
+  );
+
+const serializeQueryParams = (
+  query?: Record<string, QueryValue>
+): Record<string, string> | undefined => {
+  if (!query) {
+    return undefined;
+  }
+
+  const result: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined) {
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      if (value.length === 0) {
+        continue;
+      }
+      result[key] = value.map((item) => String(item)).join(',');
+      continue;
+    }
+
+    result[key] = String(value);
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+};
+
+export const buttondownRequest = async <TResponse>({
+  auth,
+  method,
+  path,
+  query,
+  body,
+  headers,
+}: ButtondownRequest): Promise<TResponse> => {
+  const response = await httpClient.sendRequest<TResponse>({
+    method,
+    url: `${BUTTONDOWN_BASE_URL}${path}`,
+    headers: {
+      Authorization: `Token ${auth}`,
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      ...sanitizeHeaders(headers),
+    },
+    queryParams: serializeQueryParams(query),
+    body,
+  });
+
+  return response.body;
+};

package/src/lib/common/options.ts

@@ -0,0 +1,65 @@
+import {
+  ButtondownSubscriberType,
+  ButtondownSubscriberSource,
+  ButtondownEmailStatus,
+  ButtondownEmailType,
+} from './types';
+
+export const subscriberTypeOptions: { label: string; value: ButtondownSubscriberType }[] = [
+  { label: 'Regular', value: 'regular' },
+  { label: 'Premium', value: 'premium' },
+  { label: 'Unactivated', value: 'unactivated' },
+  { label: 'Paused', value: 'paused' },
+  { label: 'Trialed', value: 'trialed' },
+  { label: 'Upcoming', value: 'upcoming' },
+  { label: 'Churning', value: 'churning' },
+  { label: 'Churned', value: 'churned' },
+  { label: 'Unsubscribed', value: 'unsubscribed' },
+  { label: 'Undeliverable', value: 'undeliverable' },
+  { label: 'Blocked', value: 'blocked' },
+  { label: 'Complained', value: 'complained' },
+  { label: 'Gifted', value: 'gifted' },
+  { label: 'Past Due', value: 'past_due' },
+  { label: 'Removed', value: 'removed' },
+  { label: 'Unpaid', value: 'unpaid' },
+];
+
+export const subscriberSourceOptions: { label: string; value: ButtondownSubscriberSource }[] = [
+  { label: 'Admin', value: 'admin' },
+  { label: 'API', value: 'api' },
+  { label: 'Carrd', value: 'carrd' },
+  { label: 'Comment', value: 'comment' },
+  { label: 'Embedded form', value: 'embedded_form' },
+  { label: 'Hosted form', value: 'form' },
+  { label: 'Import', value: 'import' },
+  { label: 'Memberful', value: 'memberful' },
+  { label: 'Organic', value: 'organic' },
+  { label: 'Patreon', value: 'patreon' },
+  { label: 'Stripe', value: 'stripe' },
+  { label: 'User portal', value: 'user' },
+  { label: 'Zapier', value: 'zapier' },
+];
+
+export const subscriberOrderingOptions = [
+  { label: 'Newest first', value: '-creation_date' },
+  { label: 'Oldest first', value: 'creation_date' },
+  { label: 'Email address (A-Z)', value: 'email_address' },
+  { label: 'Email address (Z-A)', value: '-email_address' },
+  { label: 'Last opened (recent first)', value: '-last_open_date' },
+  { label: 'Last opened (oldest first)', value: 'last_open_date' },
+];
+
+export const emailStatusOptions: { label: string; value: ButtondownEmailStatus }[] = [
+  { label: 'Send immediately (about_to_send)', value: 'about_to_send' },
+  { label: 'Draft', value: 'draft' },
+  { label: 'Scheduled', value: 'scheduled' },
+];
+
+export const emailTypeOptions: { label: string; value: ButtondownEmailType }[] = [
+  { label: 'Public', value: 'public' },
+  { label: 'Private', value: 'private' },
+  { label: 'Premium', value: 'premium' },
+  { label: 'Free', value: 'free' },
+  { label: 'Churned', value: 'churned' },
+  { label: 'Archival', value: 'archival' },
+];

package/src/lib/common/types.ts

@@ -0,0 +1,141 @@
+export type ButtondownSubscriberType =
+  | 'blocked'
+  | 'complained'
+  | 'churning'
+  | 'churned'
+  | 'gifted'
+  | 'unactivated'
+  | 'unpaid'
+  | 'undeliverable'
+  | 'premium'
+  | 'past_due'
+  | 'paused'
+  | 'regular'
+  | 'removed'
+  | 'trialed'
+  | 'unsubscribed'
+  | 'upcoming';
+
+export type ButtondownSubscriberSource =
+  | 'admin'
+  | 'api'
+  | 'carrd'
+  | 'comment'
+  | 'embedded_form'
+  | 'form'
+  | 'import'
+  | 'memberful'
+  | 'organic'
+  | 'patreon'
+  | 'stripe'
+  | 'user'
+  | 'zapier';
+
+export interface ButtondownSubscriber {
+  id: string;
+  creation_date: string;
+  email_address: string;
+  type: ButtondownSubscriberType;
+  tags: string[];
+  metadata: Record<string, unknown>;
+  notes?: string;
+  referrer_url?: string;
+  utm_campaign?: string;
+  utm_medium?: string;
+  utm_source?: string;
+  ip_address?: string;
+  source: ButtondownSubscriberSource;
+  last_open_date?: string | null;
+  last_click_date?: string | null;
+  click_rate?: number | null;
+  open_rate?: number | null;
+  churn_date?: string | null;
+  unsubscription_date?: string | null;
+  undeliverability_date?: string | null;
+  [key: string]: unknown;
+}
+
+export interface ButtondownSubscriberInput {
+  email_address: string;
+  notes?: string;
+  metadata?: Record<string, unknown>;
+  tags?: string[];
+  referrer_url?: string;
+  utm_campaign?: string;
+  utm_medium?: string;
+  utm_source?: string;
+  referring_subscriber_id?: string;
+  type?: ButtondownSubscriberType;
+  ip_address?: string;
+}
+
+export type ButtondownEmailType =
+  | 'public'
+  | 'private'
+  | 'premium'
+  | 'free'
+  | 'churned'
+  | 'archival';
+
+export type ButtondownEmailStatus =
+  | 'draft'
+  | 'managed_by_rss'
+  | 'about_to_send'
+  | 'scheduled'
+  | 'in_flight'
+  | 'paused'
+  | 'deleted'
+  | 'errored'
+  | 'sent'
+  | 'imported'
+  | 'throttled'
+  | 'resending'
+  | 'transactional'
+  | 'suppressed';
+
+export interface ButtondownEmail {
+  id: string;
+  creation_date: string;
+  modification_date: string;
+  subject: string;
+  body: string;
+  status: ButtondownEmailStatus;
+  email_type: ButtondownEmailType;
+  publish_date?: string | null;
+  description?: string;
+  canonical_url?: string;
+  image?: string;
+  metadata?: Record<string, unknown>;
+  attachments?: string[];
+  [key: string]: unknown;
+}
+
+export interface ButtondownEmailInput {
+  subject: string;
+  body?: string;
+  status?: ButtondownEmailStatus;
+  email_type?: ButtondownEmailType;
+  publish_date?: string;
+  description?: string;
+  canonical_url?: string;
+  image?: string;
+  metadata?: Record<string, unknown>;
+  slug?: string;
+  attachments?: string[];
+  should_trigger_pay_per_email_billing?: boolean;
+}
+
+export type ButtondownWebhookEvent =
+  | 'subscriber.created'
+  | 'subscriber.confirmed'
+  | 'email.sent';
+
+export interface ButtondownWebhook {
+  id: string;
+  creation_date: string;
+  url: string;
+  event_types: ButtondownWebhookEvent[];
+  status?: 'enabled' | 'disabled';
+  description?: string;
+  signing_key?: string;
+}

package/src/lib/common/webhook.ts

@@ -0,0 +1,105 @@
+import { HttpMethod } from '@agnocon/pieces-common';
+import { createTrigger, Property, TriggerStrategy } from '@agnocon/pieces-framework';
+import { buttondownAuth } from './auth';
+import { buttondownRequest } from './client';
+import { ButtondownWebhook, ButtondownWebhookEvent } from './types';
+
+export interface ButtondownWebhookPayload {
+  event_type?: string;
+  data?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+interface CreateButtondownWebhookTriggerParams {
+  name: string;
+  displayName: string;
+  description: string;
+  aiMetadata: {
+    description: string;
+  };
+  eventType: ButtondownWebhookEvent;
+  sampleData: unknown;
+  enrich?: (params: {
+    apiKey: string;
+    payload: ButtondownWebhookPayload;
+  }) => Promise<Record<string, unknown>>;
+}
+
+export const createButtondownWebhookTrigger = ({
+  name,
+  displayName,
+  description,
+  aiMetadata,
+  eventType,
+  sampleData,
+  enrich,
+}: CreateButtondownWebhookTriggerParams) =>
+  createTrigger({
+    auth: buttondownAuth,
+    name,
+    displayName,
+    description,
+    aiMetadata,
+    type: TriggerStrategy.WEBHOOK,
+    props: {
+      webhookDescription: Property.ShortText({
+        displayName: 'Webhook Description',
+        description: 'Optional description stored with the webhook in Buttondown.',
+        required: false,
+      }),
+      signingKey: Property.ShortText({
+        displayName: 'Webhook Signing Key',
+        description: 'Optional HMAC signing key to validate webhook requests.',
+        required: false,
+      }),
+    },
+    sampleData,
+    async onEnable(context) {
+      const webhook = await buttondownRequest<ButtondownWebhook>({
+        auth: context.auth.secret_text,
+        method: HttpMethod.POST,
+        path: '/webhooks',
+        body: {
+          url: context.webhookUrl,
+          event_types: [eventType],
+          description: context.propsValue.webhookDescription,
+          signing_key: context.propsValue.signingKey,
+        },
+      });
+
+      await context.store.put('webhookId', webhook.id);
+    },
+    async onDisable(context) {
+      const webhookId = await context.store.get<string>('webhookId');
+      if (!webhookId) {
+        return;
+      }
+
+      await buttondownRequest<void>({
+        auth: context.auth.secret_text,
+        method: HttpMethod.DELETE,
+        path: `/webhooks/${webhookId}`,
+      });
+    },
+    async run(context) {
+      const payload = context.payload.body as ButtondownWebhookPayload;
+      if (payload?.event_type !== eventType) {
+        return [];
+      }
+
+      let enriched: Record<string, unknown> | undefined;
+      if (enrich) {
+        enriched = await enrich({
+          apiKey: context.auth.secret_text,
+          payload,
+        });
+      }
+
+      return [
+        {
+          ...payload,
+          ...(enriched ?? {}),
+        },
+      ];
+    },
+  });

package/src/lib/triggers/email-sent.ts

@@ -0,0 +1,39 @@
+import { HttpMethod } from '@agnocon/pieces-common';
+import { buttondownRequest } from '../common/client';
+import { createButtondownWebhookTrigger } from '../common/webhook';
+import { ButtondownEmail } from '../common/types';
+
+export const buttondownEmailSent = createButtondownWebhookTrigger({
+  name: 'buttondown_email_sent',
+  displayName: 'Email Sent',
+  description: 'Triggers when an email is sent from Buttondown.',
+  aiMetadata: {
+    description:
+      'Fires when an email is dispatched to subscribers from Buttondown. Represents a sent newsletter/email; the payload is enriched with the full email details.',
+  },
+  eventType: 'email.sent',
+  sampleData: {
+    event_type: 'email.sent',
+    data: {
+      email: 'eml_123456789',
+    },
+  },
+  enrich: async ({ apiKey, payload }) => {
+    const emailData = payload.data?.['email'];
+    let email: ButtondownEmail | undefined;
+
+    if (typeof emailData === 'string') {
+      email = await buttondownRequest<ButtondownEmail>({
+        auth: apiKey,
+        method: HttpMethod.GET,
+        path: `/emails/${encodeURIComponent(emailData)}`,
+      });
+    } else if (emailData && typeof emailData === 'object') {
+      email = emailData as ButtondownEmail;
+    }
+
+    return {
+      email,
+    };
+  },
+});

package/src/lib/triggers/new-subscriber.ts

@@ -0,0 +1,39 @@
+import { HttpMethod } from '@agnocon/pieces-common';
+import { buttondownRequest } from '../common/client';
+import { createButtondownWebhookTrigger } from '../common/webhook';
+import { ButtondownSubscriber } from '../common/types';
+
+export const buttondownNewSubscriber = createButtondownWebhookTrigger({
+  name: 'buttondown_new_subscriber',
+  displayName: 'New Subscriber',
+  description: 'Triggers when a new subscriber is created.',
+  aiMetadata: {
+    description:
+      'Fires when a subscriber is added to the Buttondown newsletter, regardless of confirmation status. Represents a newly created subscriber record; the payload is enriched with the full subscriber details.',
+  },
+  eventType: 'subscriber.created',
+  sampleData: {
+    event_type: 'subscriber.created',
+    data: {
+      subscriber: 'sub_123456789',
+    },
+  },
+  enrich: async ({ apiKey, payload }) => {
+    const subscriberData = payload.data?.['subscriber'];
+    let subscriber: ButtondownSubscriber | undefined;
+
+    if (typeof subscriberData === 'string') {
+      subscriber = await buttondownRequest<ButtondownSubscriber>({
+        auth: apiKey,
+        method: HttpMethod.GET,
+        path: `/subscribers/${encodeURIComponent(subscriberData)}`,
+      });
+    } else if (subscriberData && typeof subscriberData === 'object') {
+      subscriber = subscriberData as ButtondownSubscriber;
+    }
+
+    return {
+      subscriber,
+    };
+  },
+});

package/src/lib/triggers/subscriber-confirmed.ts

@@ -0,0 +1,39 @@
+import { HttpMethod } from '@agnocon/pieces-common';
+import { buttondownRequest } from '../common/client';
+import { createButtondownWebhookTrigger } from '../common/webhook';
+import { ButtondownSubscriber } from '../common/types';
+
+export const buttondownSubscriberConfirmed = createButtondownWebhookTrigger({
+  name: 'buttondown_subscriber_confirmed',
+  displayName: 'Subscriber Confirmed',
+  description: 'Triggers when a subscriber confirms their email.',
+  aiMetadata: {
+    description:
+      'Fires when a subscriber completes double opt-in and confirms their email address in Buttondown. Represents a subscriber transitioning to confirmed status; the payload is enriched with the full subscriber details.',
+  },
+  eventType: 'subscriber.confirmed',
+  sampleData: {
+    event_type: 'subscriber.confirmed',
+    data: {
+      subscriber: 'sub_123456789',
+    },
+  },
+  enrich: async ({ apiKey, payload }) => {
+    const subscriberData = payload.data?.['subscriber'];
+    let subscriber: ButtondownSubscriber | undefined;
+
+    if (typeof subscriberData === 'string') {
+      subscriber = await buttondownRequest<ButtondownSubscriber>({
+        auth: apiKey,
+        method: HttpMethod.GET,
+        path: `/subscribers/${encodeURIComponent(subscriberData)}`,
+      });
+    } else if (subscriberData && typeof subscriberData === 'object') {
+      subscriber = subscriberData as ButtondownSubscriber;
+    }
+
+    return {
+      subscriber,
+    };
+  },
+});