Build All PIE Connectors — Execution Plan

Backup copy of the active build plan. This file is the authoritative reference for connector build order, architecture decisions, and per-batch details.

Architecture
Connector Template Pattern
Updated Batch List
Social Media Strategy (ScrapeCreators)
Heartbeat Events Strategy
Batch Details
Per-Connector Checklist
Setup Guide Reference

Architecture

Every connector is a single .pie file with three parts:

YAML frontmatter — name, displayName, description, tier: connector, version, manifest (oauth, tool params, automation triggers, heartbeatEvents)
JavaScript handler — module.exports = { handler, onConnect } using context.oauth.fetch() for API calls
Optional widget — ===widget=== ... ===widget=== fenced HTML/JS (skip for mass-creation; add later)

Reference implementations:

OAuth + tool pattern: plugins/slack.pie
OAuth + tool + widget pattern: plugins/hubspot-crm.pie
Webhook events pattern: plugins/github.pie
ScrapeCreators + monitors: plugins/mass-creation/linkedin-researcher.pie

All new files go under plugins/mass-creation/.

Connector Template Pattern

OAuth Connector Skeleton

yaml

---
name: service-name
displayName: Service Name
description: >-
  Service integration for [capabilities]. Connect via OAuth to get started.
  Write operations require explicit confirmation. No delete operations for safety.
tier: connector
version: 1.0.0
manifest:
  trigger: auto
  oauth:
    provider: custom
    providerName: Service Name
    authorizationUrl: https://...
    tokenUrl: https://...
    scopes: [...]
    clientIdSecret: SERVICE_CLIENT_ID
    clientSecretSecret: SERVICE_CLIENT_SECRET
  developerSecrets:
    SERVICE_CLIENT_ID:
      description: OAuth Client ID
      required: true
    SERVICE_CLIENT_SECRET:
      description: OAuth Client Secret
      required: true
  tool:
    name: service_name
    description: >
      [Action catalog and usage notes]
    parameters:
      type: object
      properties:
        action:
          type: string
          enum: [list of actions]
          description: The action to perform.
      required: [action]
  automation:
    triggers:
      - type: webhook
        eventTypeField: event_type
        events:
          - name: event_name
            description: Description
    allowManualRun: true
    timeout: 120
  heartbeatEvents:
    events:
      - id: event_id
        displayName: Event Name
        matchers:
          - source: tool
            action: action_name
---

ScrapeCreators Connector Skeleton

yaml

---
name: platform-researcher
displayName: Platform Researcher
description: >-
  Research tool powered by ScrapeCreators. [capabilities].
  Costs 1 credit per API call.
tier: tool
version: 1.0.0
manifest:
  trigger: auto
  developerSecrets:
    SCRAPECREATORS_API_KEY:
      description: ScrapeCreators API key (from app.scrapecreators.com). Shared developer key.
      required: true
  automation:
    triggers:
      - type: cron
        default: '*/15 * * * *'
        description: Check monitored targets for new content
    allowManualRun: true
    timeout: 120
  database:
    tables:
      platform_monitors:
        columns:
          id: "uuid primary key default gen_random_uuid()"
          pie_user_id: "text not null default current_setting('app.user_id', true)"
          monitor_type: "text not null"
          target: "text not null"
          label: "text"
          enabled: "boolean not null default true"
          interval_minutes: "integer not null default 60"
          last_checked_at: "timestamptz"
          next_check_at: "timestamptz"
          created_at: "timestamptz default now()"
        rls: "pie_user_id"
      platform_seen_items:
        columns:
          id: "uuid primary key default gen_random_uuid()"
          pie_user_id: "text not null default current_setting('app.user_id', true)"
          monitor_id: "uuid not null references platform_monitors(id) on delete cascade"
          item_id: "text not null"
          detected_at: "timestamptz not null default now()"
        rls: "pie_user_id"
  tool:
    name: platform_researcher
    description: >
      [Tool description with action catalog]
    parameters:
      type: object
      properties:
        action:
          type: string
          enum: [research actions + create_monitor, list_monitors, pause_monitor, resume_monitor, delete_monitor]
      required: [action]
  heartbeatEvents:
    events:
      - id: new_item_detected
        displayName: New Item Detected
        matchers:
          - source: tool
            action: _poll_check
---

Updated Batch List

Batch	Connectors	Count	Auth Type	Notes
1	Google Suite (Sheets, Drive, Docs, Tasks, Meet, Analytics, Ads, Classroom)	8	`provider: google`	Shared OAuth app, different scopes per connector
2	Microsoft (Outlook, Teams, OneDrive)	3	Custom OAuth (Azure AD)	All use Graph API base URL
3	Atlassian (Jira, Confluence, Bitbucket)	3	Custom OAuth (3LO)	Shared Atlassian developer app
4	CRM (Salesforce, Pipedrive, Attio)	3	Custom OAuth each	Similar CRUD-on-entities pattern
5	PM (Linear, ClickUp, Monday, Basecamp)	4	Custom OAuth each	Task/issue CRUD pattern
6	Data (Airtable, Supabase, Coda)	3	Mix OAuth + API key	Record CRUD pattern
7	Communication (Discord, Intercom, Gong)	3	Bot tokens + OAuth	Messaging platforms
8	Scheduling/Support (Calendly, Cal.com, Zendesk, Freshdesk, Gorgias)	5	Mix OAuth + API key	Booking and helpdesk
9	E-commerce/Finance (Shopify, Stripe, QuickBooks)	3	OAuth, webhook-heavy	Payment and commerce
10	Marketing (Mailchimp, SendGrid, Brevo, ActiveCampaign)	4	API key based	Email marketing
11	Social Media (LinkedIn Researcher, Pinterest Researcher)	2	ScrapeCreators dev key	Read-only, polling monitors
12	DevOps (GitLab, Twilio, Telegram)	3	Mix	Various auth methods
13	Design (Figma, Canva, Miro)	3	OAuth	Design tool APIs
14	HR (BambooHR, Lever)	2	Mix API key + OAuth	Ahrefs removed (already exists)

Grand total: 49 new connectors

Already existing (DO NOT rebuild)

These 63 plugins already exist in plugins/ and must not be duplicated:

ahrefs-seo.pie (was in original Batch 14 — removed)
slack.pie, github.pie, notion.pie, gmail-assistant.pie, google-calendar.pie
hubspot-crm.pie, close-crm.pie, x-twitter.pie, meta-ads.pie
asana.pie, trello.pie, spotify.pie, dropbox.pie, digitalocean.pie
instagram-researcher.pie, youtube-researcher.pie, reddit-researcher.pie, tiktok-researcher.pie
linkedin-engagement.pie, facebook-marketplace-watcher.pie, facebook-ad-library-research.pie
All other existing .pie files (63 total)

Existing plugins (DO NOT TOUCH)

These ScrapeCreators-based researchers already exist and function correctly:

plugins/instagram-researcher.pie — 11 actions
plugins/youtube-researcher.pie — 11 actions
plugins/reddit-researcher.pie — 7 actions
plugins/tiktok-researcher.pie — 24 actions

New plugins (Batch 11)

Two new ScrapeCreators plugins created under plugins/mass-creation/:

linkedin-researcher.pie — 6 core research actions + 5 monitor actions:
- Research: get_profile, get_company, get_company_posts, get_post, search_ads, get_ad
- Monitor: create_monitor, list_monitors, pause_monitor, resume_monitor, delete_monitor
- Polling cron for new_post_detected heartbeat
- Database: linkedin_monitors, linkedin_seen_posts
pinterest-researcher.pie — 4 core research actions + 5 monitor actions:
- Research: search_pins, get_pin, get_user_boards, get_board
- Monitor: create_monitor, list_monitors, pause_monitor, resume_monitor, delete_monitor
- Polling cron for new_pin_detected heartbeat
- Database: pinterest_monitors, pinterest_seen_pins

Auth pattern

All ScrapeCreators plugins use a single shared developer secret:

Secret: SCRAPECREATORS_API_KEY
Header: x-api-key: {key} on requests to https://api.scrapecreators.com
No OAuth, no user-side configuration needed

Heartbeat Events Strategy

1. Webhook-based (OAuth connectors with native webhooks)

Services like GitHub, Stripe, Shopify, Jira, Slack, GitLab have native webhook support:

Declare events in automation.triggers[type=webhook].events
These automatically become subscribable heartbeat events via buildPluginHeartbeatCatalog()
Setup requires registering the PIE webhook URL in the service's dashboard

2. Tool-action-based (all connectors)

Every write action should have a corresponding heartbeat event:

Matcher: { source: 'tool', action: 'create_issue' }
Common patterns: create_*, update_*, delete_*, send_*
Read actions can also have heartbeats (e.g., profile_researched, content_searched)

3. Polling-based (ScrapeCreators + services without webhooks)

For services that don't support webhooks:

Cron automation runs every 15 minutes
Compares current data with stored "seen" records in database
Emits heartbeat events like new_post_detected, new_pin_detected
Matcher: { source: 'tool', action: '_poll_check' }

Standard heartbeat event naming

Category	Heartbeat events
Social / Research	`profile_researched`, `content_searched`, `new_post_detected`, `new_pin_detected`, `monitor_created`
CRM	`deal_created`, `contact_updated`, `deal_stage_changed`, `note_added`
Project Management	`issue_created`, `task_completed`, `sprint_started`, `comment_added`
E-commerce	`order_placed`, `product_updated`, `payment_received`, `refund_issued`
Communication	`message_sent`, `channel_created`, `reaction_added`, `dm_received`
DevOps	`push_received`, `pr_opened`, `pipeline_completed`, `issue_commented`
Support	`ticket_created`, `ticket_resolved`, `customer_replied`, `agent_assigned`
Marketing	`email_sent`, `campaign_completed`, `contact_subscribed`, `email_bounced`
Scheduling	`booking_created`, `booking_cancelled`, `event_rescheduled`
Design	`file_updated`, `comment_added`, `board_modified`
HR	`employee_updated`, `timeoff_requested`, `candidate_stage_changed`
Data	`record_created`, `record_updated`, `table_modified`

Batch Details

Batch 1: Google Suite (8 connectors)

All use provider: google with different scopes. Shared Google Cloud OAuth app.

Connector	API	Core actions
google-sheets	Sheets API v4	get_values, update_values, append_values, create_spreadsheet, list_sheets
google-drive	Drive API v3	list_files, upload_file, share_file, search_files, create_folder
google-docs	Docs API v1	create_document, get_document, update_document, insert_text
google-tasks	Tasks API v1	list_task_lists, list_tasks, create_task, complete_task, update_task
google-meet	Meet REST API	create_meeting, get_meeting, list_recordings
google-analytics	GA4 Data API	run_report, get_realtime_report, list_properties
google-ads	Google Ads API	list_campaigns, get_campaign, list_ad_groups, get_report
google-classroom	Classroom API	list_courses, create_assignment, list_submissions, get_course

Batch 2: Microsoft Suite (3 connectors)

All use Microsoft Graph API. Shared Azure AD app.

Connector	Graph resource	Core actions
outlook	/me/messages	list_messages, send_email, create_draft, list_folders, search_messages
microsoft-teams	/teams, /chats	list_channels, send_message, create_meeting, list_chats
onedrive	/me/drive	list_files, upload_file, share_file, create_folder, search_files

Batch 3: Atlassian Suite (3 connectors)

Atlassian OAuth 2.0 (3LO). Shared developer app.

Connector	API	Core actions
jira	Jira REST API v3	search_issues, create_issue, update_issue, list_boards, get_sprint
confluence	Confluence REST API v2	list_pages, create_page, update_page, search_content, list_spaces
bitbucket	Bitbucket REST API	list_repos, list_pull_requests, create_pr, list_pipelines

Batch 4: CRM (3 connectors)

Connector	Auth	Core actions
salesforce	OAuth	query_soql, create_record, update_record, list_leads, list_opportunities
pipedrive	OAuth	list_deals, create_deal, list_persons, create_activity, list_pipelines
attio	OAuth	list_records, create_record, list_lists, create_note, search_records

Batch 5: Project Management (4 connectors)

Connector	API style	Core actions
linear	GraphQL	list_issues, create_issue, update_issue, list_projects, list_cycles
clickup	REST	list_tasks, create_task, update_task, list_spaces, add_comment
monday	GraphQL	list_boards, list_items, create_item, update_item, add_update
basecamp	REST	list_projects, list_todos, create_todo, list_messages, create_message

Batch 6: Data & Productivity (3 connectors)

Connector	Auth	Core actions
airtable	OAuth	list_records, create_record, update_record, list_bases, list_tables
supabase	API key	query_table, insert_row, update_row, list_tables, run_rpc
coda	API key	list_docs, list_rows, insert_row, update_row, list_tables

Batch 7: Communication (3 connectors)

Connector	Auth	Core actions
discord	OAuth + bot	send_message, list_channels, list_guilds, add_reaction, create_channel
intercom	OAuth	list_contacts, create_contact, list_conversations, reply_conversation
gong	API key	list_calls, get_call, get_transcript, list_users

Batch 8: Scheduling & Support (5 connectors)

Connector	Auth	Core actions
calendly	OAuth	list_events, list_event_types, get_invitee, list_scheduled
cal-com	API key	list_bookings, list_event_types, get_availability
zendesk	OAuth	list_tickets, create_ticket, update_ticket, search_tickets, add_comment
freshdesk	API key	list_tickets, create_ticket, update_ticket, list_contacts
gorgias	API key	list_tickets, create_ticket, list_customers, send_message

Batch 9: E-commerce & Finance (3 connectors)

Connector	Auth	Core actions
shopify	OAuth	list_products, create_product, list_orders, list_customers, get_order
stripe	API key	list_customers, create_charge, list_subscriptions, list_invoices, create_invoice
quickbooks	OAuth	list_invoices, create_invoice, list_customers, list_payments, get_report

Batch 10: Marketing & Email (4 connectors)

Connector	Auth	Core actions
mailchimp	API key	list_campaigns, create_campaign, list_audiences, list_members, add_member
sendgrid	API key	send_email, list_contacts, create_campaign, list_campaigns
brevo	API key	send_email, list_contacts, create_campaign, list_campaigns
activecampaign	API key	list_contacts, create_contact, list_deals, create_deal, list_automations

See Social Media Strategy above.

Batch 12: DevOps & Messaging (3 connectors)

Connector	Auth	Core actions
gitlab	OAuth	list_projects, list_merge_requests, create_issue, list_pipelines
twilio	API key	send_sms, make_call, send_whatsapp, list_messages
telegram	Bot token	send_message, send_photo, list_updates, get_chat

Batch 13: Design (3 connectors)

Connector	Auth	Core actions
figma	OAuth	list_files, get_file, list_comments, export_images, list_projects
canva	OAuth	list_designs, create_design, export_design, list_templates
miro	OAuth	list_boards, list_items, create_sticky, create_frame, add_item

Batch 14: HR (2 connectors)

Connector	Auth	Core actions
bamboohr	API key	list_employees, get_employee, list_timeoff, create_timeoff_request
lever	OAuth	list_candidates, list_postings, get_candidate, list_stages

Per-Connector Checklist

For each .pie file:

[ ] YAML frontmatter with correct OAuth config (URLs, scopes from API docs)
[ ] Tool definition with full action enum and parameter schema
[ ] Webhook event declarations (where the service supports webhooks)
[ ] HeartbeatEvents for all write tool actions (create_*, send_*, update_*)
[ ] JS handler with: isConnected check, action switch, API helper, formatters, error handling
[ ] onConnect function with welcome message listing capabilities
[ ] Confirmation rule in tool description for write operations
[ ] At least one automation trigger (webhook or polling interval)
[ ] Error messages are actionable (not raw API errors)
[ ] Manifest passes schema validation

Setup Guide Reference

Full setup instructions for every connector (API keys, OAuth apps, webhook URLs, scopes) are in:

docs-site/docs/reference/connector-setup-guide.md

This includes:

ScrapeCreators shared setup (covers all social media plugins)
Per-service OAuth app creation steps
Webhook URL registration instructions
Verification/signing secret configuration
Heartbeat events reference

Build All PIE Connectors — Execution Plan ​

Table of Contents ​

Architecture ​

Connector Template Pattern ​

OAuth Connector Skeleton ​

ScrapeCreators Connector Skeleton ​

Updated Batch List ​

Already existing (DO NOT rebuild) ​

Social Media Strategy (ScrapeCreators) ​

Existing plugins (DO NOT TOUCH) ​

New plugins (Batch 11) ​

Auth pattern ​

Heartbeat Events Strategy ​

1. Webhook-based (OAuth connectors with native webhooks) ​

2. Tool-action-based (all connectors) ​

3. Polling-based (ScrapeCreators + services without webhooks) ​

Standard heartbeat event naming ​

Batch Details ​

Batch 1: Google Suite (8 connectors) ​

Batch 2: Microsoft Suite (3 connectors) ​

Batch 3: Atlassian Suite (3 connectors) ​

Batch 4: CRM (3 connectors) ​

Batch 5: Project Management (4 connectors) ​

Batch 6: Data & Productivity (3 connectors) ​

Batch 7: Communication (3 connectors) ​

Batch 8: Scheduling & Support (5 connectors) ​

Batch 9: E-commerce & Finance (3 connectors) ​

Batch 10: Marketing & Email (4 connectors) ​

Batch 11: Social Media (2 connectors) ​

Batch 12: DevOps & Messaging (3 connectors) ​

Batch 13: Design (3 connectors) ​

Batch 14: HR (2 connectors) ​

Per-Connector Checklist ​

Setup Guide Reference ​