@agnocon/piece-buttondown 0.0.5

package/dist/lib/triggers/subscriber-confirmed.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buttondownSubscriberConfirmed = void 0;
+const tslib_1 = require("tslib");
+// Vendored from Activepieces packages/pieces/community/buttondown/src/lib/triggers/subscriber-confirmed.ts (MIT).
+// Generated by packages/scripts/vendor-ap.mjs - do not edit by hand.
+const pieces_common_1 = require("@agnocon/pieces-common");
+const client_1 = require("../common/client");
+const webhook_1 = require("../common/webhook");
+exports.buttondownSubscriberConfirmed = (0, webhook_1.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: (_a) => tslib_1.__awaiter(void 0, [_a], void 0, function* ({ apiKey, payload }) {
+        var _b;
+        const subscriberData = (_b = payload.data) === null || _b === void 0 ? void 0 : _b['subscriber'];
+        let subscriber;
+        if (typeof subscriberData === 'string') {
+            subscriber = yield (0, client_1.buttondownRequest)({
+                auth: apiKey,
+                method: pieces_common_1.HttpMethod.GET,
+                path: `/subscribers/${encodeURIComponent(subscriberData)}`,
+            });
+        }
+        else if (subscriberData && typeof subscriberData === 'object') {
+            subscriber = subscriberData;
+        }
+        return {
+            subscriber,
+        };
+    }),
+});
+//# sourceMappingURL=subscriber-confirmed.js.map

package/dist/lib/triggers/subscriber-confirmed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriber-confirmed.js","sourceRoot":"","sources":["../../../src/lib/triggers/subscriber-confirmed.ts"],"names":[],"mappings":";;;;AAAA,kHAAkH;AAClH,qEAAqE;AACrE,0DAAoD;AACpD,6CAAqD;AACrD,+CAAmE;AAGtD,QAAA,6BAA6B,GAAG,IAAA,wCAA8B,EAAC;IAC1E,IAAI,EAAE,iCAAiC;IACvC,WAAW,EAAE,sBAAsB;IACnC,WAAW,EAAE,kDAAkD;IAC/D,UAAU,EAAE;QACV,WAAW,EACT,sNAAsN;KACzN;IACD,SAAS,EAAE,sBAAsB;IACjC,UAAU,EAAE;QACV,UAAU,EAAE,sBAAsB;QAClC,IAAI,EAAE;YACJ,UAAU,EAAE,eAAe;SAC5B;KACF;IACD,MAAM,EAAE,KAA4B,EAAE,oDAAvB,EAAE,MAAM,EAAE,OAAO,EAAE;;QAChC,MAAM,cAAc,GAAG,MAAA,OAAO,CAAC,IAAI,0CAAG,YAAY,CAAC,CAAC;QACpD,IAAI,UAA4C,CAAC;QAEjD,IAAI,OAAO,cAAc,KAAK,QAAQ,EAAE,CAAC;YACvC,UAAU,GAAG,MAAM,IAAA,0BAAiB,EAAuB;gBACzD,IAAI,EAAE,MAAM;gBACZ,MAAM,EAAE,0BAAU,CAAC,GAAG;gBACtB,IAAI,EAAE,gBAAgB,kBAAkB,CAAC,cAAc,CAAC,EAAE;aAC3D,CAAC,CAAC;QACL,CAAC;aAAM,IAAI,cAAc,IAAI,OAAO,cAAc,KAAK,QAAQ,EAAE,CAAC;YAChE,UAAU,GAAG,cAAsC,CAAC;QACtD,CAAC;QAED,OAAO;YACL,UAAU;SACX,CAAC;IACJ,CAAC,CAAA;CACF,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@agnocon/piece-buttondown",
+  "version": "0.0.5",
+  "description": "AgnoCon buttondown connector",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE.MIT-AP"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "vendor": "node ../scripts/vendor-ap.mjs piece-buttondown"
+  },
+  "dependencies": {
+    "@agnocon/core-utils": "0.2.0",
+    "@agnocon/piece-types": "0.3.1",
+    "@agnocon/pieces-common": "0.12.8",
+    "@agnocon/pieces-framework": "0.36.0",
+    "tslib": "2.6.2"
+  },
+  "devDependencies": {
+    "@types/node": "20.17.6",
+    "typescript": "5.5.4"
+  },
+  "license": "MIT",
+  "agnocon": {
+    "originVersion": "0.0.5"
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "tag": "latest"
+  },
+  "keywords": [
+    "agnocon",
+    "connector"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+import { createPiece } from '@agnocon/pieces-framework';
+import { PieceCategory } from '@agnocon/pieces-framework';
+import { buttondownAuth } from './lib/common/auth';
+import { createSubscriber } from './lib/actions/create-subscriber';
+import { listSubscribers } from './lib/actions/list-subscribers';
+import { sendEmail } from './lib/actions/send-email';
+import { customApiCall } from './lib/actions/custom-api-call';
+import { buttondownNewSubscriber } from './lib/triggers/new-subscriber';
+import { buttondownSubscriberConfirmed } from './lib/triggers/subscriber-confirmed';
+import { buttondownEmailSent } from './lib/triggers/email-sent';
+
+export const buttondown = createPiece({
+  displayName: 'Buttondown',
+  description: 'Automate your Buttondown newsletter workflows.',
+  auth: buttondownAuth,
+  minimumSupportedRelease: '0.36.1',
+  logoUrl: 'https://cdn.activepieces.com/pieces/buttondown.png',
+  authors: ['jacksbox-cassandra'],
+  categories: [PieceCategory.MARKETING, PieceCategory.COMMUNICATION],
+  actions: [createSubscriber, listSubscribers, sendEmail, customApiCall],
+  triggers: [
+    buttondownNewSubscriber,
+    buttondownSubscriberConfirmed,
+    buttondownEmailSent,
+  ],
+});

package/src/lib/actions/create-subscriber.ts

@@ -0,0 +1,171 @@
+import { HttpMethod } from '@agnocon/pieces-common';
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { buttondownAuth } from '../common/auth';
+import { buttondownRequest } from '../common/client';
+import { subscriberTypeOptions } from '../common/options';
+import {
+  ButtondownSubscriber,
+  ButtondownSubscriberInput,
+  ButtondownSubscriberType,
+} from '../common/types';
+
+export const createSubscriber = createAction({
+  auth: buttondownAuth,
+  name: 'createSubscriber',
+  displayName: 'Create Subscriber',
+  description: 'Create a new subscriber in Buttondown.',
+  audience: 'both',
+  aiMetadata: {
+    description:
+      'Adds a subscriber to a Buttondown newsletter by email address, with optional tags, metadata, UTM attribution, and referral data. Use "regular" subscriber type to skip double opt-in. Not idempotent: each call creates a subscriber; control duplicate-email handling via collision behavior (default keeps the existing subscriber, or overwrite/merge tags).',
+    idempotent: false,
+  },
+  props: {
+    email: Property.ShortText({
+      displayName: 'Email Address',
+      required: true,
+      description: 'The email address of the subscriber.',
+    }),
+    type: Property.StaticDropdown({
+      displayName: 'Subscriber Type',
+      description:
+        'Set the subscriber status. Use "regular" to bypass double opt-in.',
+      required: false,
+      options: {
+        options: subscriberTypeOptions,
+      },
+    }),
+    notes: Property.LongText({
+      displayName: 'Internal Notes',
+      required: false,
+    }),
+    tags: Property.Array({
+      displayName: 'Tags',
+      description: 'Add one or more tags to assign to the subscriber.',
+      required: false,
+      properties: {
+        tag: Property.ShortText({
+          displayName: 'Tag',
+          required: true,
+        }),
+      },
+    }),
+    metadata: Property.Json({
+      displayName: 'Metadata',
+      description: 'Custom metadata to store on the subscriber (JSON object).',
+      required: false,
+    }),
+    referrerUrl: Property.ShortText({
+      displayName: 'Referrer URL',
+      required: false,
+    }),
+    utmSource: Property.ShortText({
+      displayName: 'UTM Source',
+      required: false,
+    }),
+    utmMedium: Property.ShortText({
+      displayName: 'UTM Medium',
+      required: false,
+    }),
+    utmCampaign: Property.ShortText({
+      displayName: 'UTM Campaign',
+      required: false,
+    }),
+    referringSubscriberId: Property.ShortText({
+      displayName: 'Referring Subscriber ID',
+      description: 'ID of the subscriber who referred this contact.',
+      required: false,
+    }),
+    ipAddress: Property.ShortText({
+      displayName: 'IP Address',
+      description:
+        'The original IP address of the subscriber. Helps Buttondown evaluate spam.',
+      required: false,
+    }),
+    collisionBehavior: Property.StaticDropdown({
+      displayName: 'Collision Behavior',
+      description:
+        'Control how Buttondown handles duplicate email addresses. Leave empty to keep the existing subscriber.',
+      required: false,
+      options: {
+        options: [
+          { label: 'Overwrite existing subscriber', value: 'overwrite' },
+          { label: 'Merge tags with existing subscriber', value: 'add' },
+        ],
+      },
+    }),
+    bypassFirewall: Property.Checkbox({
+      displayName: 'Bypass Firewall',
+      description:
+        'Set to true when the request originates from a trusted internal system without the subscriber\'s IP address.',
+      required: false,
+      defaultValue: false,
+    }),
+  },
+  async run({ auth, propsValue }) {
+    const payload: ButtondownSubscriberInput = {
+      email_address: propsValue.email,
+    };
+
+    if (propsValue.notes) {
+      payload.notes = propsValue.notes;
+    }
+
+    const tags = (propsValue.tags as Array<{ tag?: string }> | undefined)
+      ?.map((entry) => entry?.tag?.trim())
+      .filter((tag): tag is string => !!tag);
+    if (tags && tags.length > 0) {
+      payload.tags = tags;
+    }
+
+    if (propsValue.metadata) {
+      if (typeof propsValue.metadata !== 'object' || Array.isArray(propsValue.metadata)) {
+        throw new Error('Metadata must be a JSON object.');
+      }
+      payload.metadata = propsValue.metadata as Record<string, unknown>;
+    }
+
+    if (propsValue.referrerUrl) {
+      payload.referrer_url = propsValue.referrerUrl;
+    }
+
+    if (propsValue.utmSource) {
+      payload.utm_source = propsValue.utmSource;
+    }
+
+    if (propsValue.utmMedium) {
+      payload.utm_medium = propsValue.utmMedium;
+    }
+
+    if (propsValue.utmCampaign) {
+      payload.utm_campaign = propsValue.utmCampaign;
+    }
+
+    if (propsValue.referringSubscriberId) {
+      payload.referring_subscriber_id = propsValue.referringSubscriberId;
+    }
+
+    if (propsValue.type) {
+      payload.type = propsValue.type as ButtondownSubscriberType;
+    }
+
+    if (propsValue.ipAddress) {
+      payload.ip_address = propsValue.ipAddress;
+    }
+
+    const headers: Record<string, string | undefined> = {
+      'X-Buttondown-Collision-Behavior': propsValue.collisionBehavior as string | undefined,
+      'X-Buttondown-Bypass-Firewall': propsValue.bypassFirewall ? 'true' : undefined,
+    };
+
+    const subscriber = await buttondownRequest<ButtondownSubscriber>({
+      auth: auth.secret_text,
+      method: HttpMethod.POST,
+      path: '/subscribers',
+      body: payload,
+      headers,
+    });
+
+    return subscriber;
+  },
+});

package/src/lib/actions/custom-api-call.ts

@@ -0,0 +1,11 @@
+import { createCustomApiCallAction } from '@agnocon/pieces-common';
+import { buttondownAuth } from '../common/auth';
+import { BUTTONDOWN_BASE_URL } from '../common/client';
+
+export const customApiCall = createCustomApiCallAction({
+  auth: buttondownAuth,
+  baseUrl: () => BUTTONDOWN_BASE_URL,
+  authMapping: async (auth) => ({
+    Authorization: `Token ${auth.secret_text}`,
+  }),
+});

package/src/lib/actions/list-subscribers.ts

@@ -0,0 +1,125 @@
+import { HttpMethod } from '@agnocon/pieces-common';
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { buttondownAuth } from '../common/auth';
+import { buttondownRequest, ButtondownPagedResponse } from '../common/client';
+import {
+  subscriberTypeOptions,
+  subscriberSourceOptions,
+  subscriberOrderingOptions,
+} from '../common/options';
+import { ButtondownSubscriber } from '../common/types';
+
+export const listSubscribers = createAction({
+  auth: buttondownAuth,
+  name: 'listSubscribers',
+  displayName: 'List Subscribers',
+  description: 'Retrieve subscribers from Buttondown.',
+  audience: 'both',
+  aiMetadata: {
+    description:
+      'Lists subscribers from a Buttondown newsletter, optionally filtered by type, source, tags, email substring, or referrer URL; with no filters it returns all subscribers. Use to look up or enumerate subscribers. Read-only and idempotent. Returns one page (default 100); pass the returned cursor to page through results.',
+    idempotent: true,
+  },
+  props: {
+    limit: Property.Number({
+      displayName: 'Page Size',
+      description: 'Maximum number of subscribers to return (1-1000).',
+      required: false,
+      defaultValue: 100,
+    }),
+    cursor: Property.ShortText({
+      displayName: 'Cursor',
+      description:
+        'Provide the cursor value from a previous response to fetch the next page.',
+      required: false,
+    }),
+    type: Property.StaticDropdown({
+      displayName: 'Subscriber Type',
+      required: false,
+      options: {
+        options: subscriberTypeOptions,
+      },
+    }),
+    source: Property.StaticDropdown({
+      displayName: 'Source',
+      required: false,
+      options: {
+        options: subscriberSourceOptions,
+      },
+    }),
+    tags: Property.Array({
+      displayName: 'Tags',
+      description: 'Filter by subscribers who have at least one of these tags.',
+      required: false,
+      properties: {
+        tag: Property.ShortText({
+          displayName: 'Tag',
+          required: true,
+        }),
+      },
+    }),
+    emailAddress: Property.ShortText({
+      displayName: 'Email Contains',
+      description: 'Return subscribers whose email address contains this value.',
+      required: false,
+    }),
+    referrerUrl: Property.ShortText({
+      displayName: 'Referrer URL Contains',
+      required: false,
+    }),
+    ordering: Property.StaticDropdown({
+      displayName: 'Ordering',
+      required: false,
+      options: {
+        options: subscriberOrderingOptions,
+      },
+    }),
+  },
+  async run({ auth, propsValue }) {
+    const query: Record<string, string | number | boolean | (string | number | boolean)[] | undefined> = {};
+
+    if (propsValue.limit) {
+      query['page_size'] = propsValue.limit;
+    }
+
+    if (propsValue.cursor) {
+      query['cursor'] = propsValue.cursor;
+    }
+
+    if (propsValue.type) {
+      query['type'] = [propsValue.type];
+    }
+
+    if (propsValue.source) {
+      query['source'] = [propsValue.source];
+    }
+
+    const tags = (propsValue.tags as Array<{ tag?: string }> | undefined)
+      ?.map((entry) => entry.tag?.trim())
+      .filter((tag): tag is string => !!tag);
+    if (tags && tags.length > 0) {
+      query['tag'] = tags;
+    }
+
+    if (propsValue.emailAddress) {
+      query['email_address'] = propsValue.emailAddress;
+    }
+
+    if (propsValue.referrerUrl) {
+      query['referrer_url'] = propsValue.referrerUrl;
+    }
+
+    if (propsValue.ordering) {
+      query['ordering'] = propsValue.ordering;
+    }
+
+    const response = await buttondownRequest<ButtondownPagedResponse<ButtondownSubscriber>>({
+      auth: auth.secret_text,
+      method: HttpMethod.GET,
+      path: '/subscribers',
+      query,
+    });
+
+    return response;
+  },
+});

package/src/lib/actions/send-email.ts

@@ -0,0 +1,162 @@
+import { HttpMethod } from '@agnocon/pieces-common';
+import { createAction, Property } from '@agnocon/pieces-framework';
+import { buttondownAuth } from '../common/auth';
+import { buttondownRequest } from '../common/client';
+import { emailStatusOptions, emailTypeOptions } from '../common/options';
+import {
+  ButtondownEmail,
+  ButtondownEmailInput,
+  ButtondownEmailStatus,
+  ButtondownEmailType,
+} from '../common/types';
+
+export const sendEmail = createAction({
+  auth: buttondownAuth,
+  name: 'sendEmail',
+  displayName: 'Send Email',
+  description: 'Send an email to your Buttondown subscribers.',
+  audience: 'both',
+  aiMetadata: {
+    description:
+      'Creates an email in Buttondown from a subject and Markdown/HTML body, then handles it per the chosen delivery status (e.g. send now vs. schedule for a future publish date, or save as draft). Use to broadcast a newsletter or queue one for later. A publish date is required when status is scheduled. Not idempotent: each call creates and may dispatch a new email.',
+    idempotent: false,
+  },
+  props: {
+    subject: Property.ShortText({
+      displayName: 'Subject',
+      required: true,
+    }),
+    body: Property.LongText({
+      displayName: 'Body',
+      description:
+        'Write your email content in Markdown or HTML. Buttondown will detect the format automatically.',
+      required: true,
+    }),
+    status: Property.StaticDropdown({
+      displayName: 'Delivery Status',
+      description: 'Choose how Buttondown should treat this email after creation.',
+      required: false,
+      defaultValue: 'about_to_send',
+      options: {
+        options: emailStatusOptions,
+      },
+    }),
+    publishDate: Property.DateTime({
+      displayName: 'Publish Date',
+      description: 'Required when scheduling an email. Use ISO 8601 format.',
+      required: false,
+    }),
+    emailType: Property.StaticDropdown({
+      displayName: 'Email Type',
+      required: false,
+      defaultValue: 'public',
+      options: {
+        options: emailTypeOptions,
+      },
+    }),
+    description: Property.LongText({
+      displayName: 'Description',
+      required: false,
+    }),
+    canonicalUrl: Property.ShortText({
+      displayName: 'Canonical URL',
+      required: false,
+    }),
+    image: Property.ShortText({
+      displayName: 'Primary Image URL',
+      required: false,
+    }),
+    slug: Property.ShortText({
+      displayName: 'Slug',
+      description: 'Override the automatic slug used for the archive URL.',
+      required: false,
+    }),
+    metadata: Property.Json({
+      displayName: 'Metadata',
+      description: 'Custom metadata to attach to the email (JSON object).',
+      required: false,
+    }),
+    attachments: Property.Array({
+      displayName: 'Attachment IDs',
+      description: 'IDs of attachments uploaded via the Buttondown API.',
+      required: false,
+      properties: {
+        id: Property.ShortText({
+          displayName: 'Attachment ID',
+          required: true,
+        }),
+      },
+    }),
+    triggerBilling: Property.Checkbox({
+      displayName: 'Trigger Pay-per-email Billing',
+      description:
+        'Enable when this email should count against pay-per-email billing for paid subscribers.',
+      required: false,
+      defaultValue: false,
+    }),
+  },
+  async run({ auth, propsValue }) {
+    const status = (propsValue.status as ButtondownEmailStatus | undefined) ?? 'about_to_send';
+
+    if (status === 'scheduled' && !propsValue.publishDate) {
+      throw new Error('Publish date is required when scheduling an email.');
+    }
+
+    const payload: ButtondownEmailInput = {
+      subject: propsValue.subject,
+      body: propsValue.body,
+      status,
+    };
+
+    if (propsValue.publishDate) {
+      payload.publish_date = propsValue.publishDate;
+    }
+
+    if (propsValue.emailType) {
+      payload.email_type = propsValue.emailType as ButtondownEmailType;
+    }
+
+    if (propsValue.description) {
+      payload.description = propsValue.description;
+    }
+
+    if (propsValue.canonicalUrl) {
+      payload.canonical_url = propsValue.canonicalUrl;
+    }
+
+    if (propsValue.image) {
+      payload.image = propsValue.image;
+    }
+
+    if (propsValue.slug) {
+      payload.slug = propsValue.slug;
+    }
+
+    if (propsValue.metadata) {
+      if (typeof propsValue.metadata !== 'object' || Array.isArray(propsValue.metadata)) {
+        throw new Error('Metadata must be provided as a JSON object.');
+      }
+      payload.metadata = propsValue.metadata as Record<string, unknown>;
+    }
+
+    const attachments = (propsValue.attachments as Array<{ id?: string }> | undefined)
+      ?.map((entry) => entry.id?.trim())
+      .filter((id): id is string => !!id);
+    if (attachments && attachments.length > 0) {
+      payload.attachments = attachments;
+    }
+
+    if (propsValue.triggerBilling) {
+      payload.should_trigger_pay_per_email_billing = true;
+    }
+
+    const email = await buttondownRequest<ButtondownEmail>({
+      auth: auth.secret_text,
+      method: HttpMethod.POST,
+      path: '/emails',
+      body: payload,
+    });
+
+    return email;
+  },
+});

package/src/lib/common/auth.ts

@@ -0,0 +1,58 @@
+import { HttpMethod, httpClient } from '@agnocon/pieces-common';
+import { PieceAuth } from '@agnocon/pieces-framework';
+import { BUTTONDOWN_BASE_URL } from './client';
+
+interface ButtondownPingResponse {
+  newsletter?: string;
+}
+
+interface ButtondownError {
+  detail?: string;
+  error?: string;
+  message?: string;
+}
+
+export const buttondownAuth = PieceAuth.SecretText({
+  displayName: 'API Key',
+  description:
+    'Create an API key from https://buttondown.com/keys and paste it here.',
+  required: true,
+  validate: async ({ auth }) => {
+    if (!auth) {
+      return {
+        valid: false,
+        error: 'API key is required.',
+      };
+    }
+
+    try {
+      await httpClient.sendRequest<ButtondownPingResponse>({
+        method: HttpMethod.GET,
+        url: `${BUTTONDOWN_BASE_URL}/newsletters`,
+        headers: {
+          Authorization: `Token ${auth}`,
+        },
+      });
+      return {
+        valid: true,
+      };
+    } catch (unknownError: unknown) {
+      const error = unknownError as {
+        response?: { status?: number; body?: ButtondownError };
+        message?: string;
+      };
+      const status = error.response?.status;
+      const body = error.response?.body ?? {};
+      const message =
+        body.detail ??
+        body.error ??
+        body.message ??
+        (status === 401 ? 'Invalid API key.' : 'Failed to verify the API key.');
+
+      return {
+        valid: false,
+        error: message,
+      };
+    }
+  },
+});