AI Connections builder POC [Dont Close]

claude.md

@@ -0,0 +1,4 @@
+# Steps to create a new cloud mode destination
+
+- create a mapping spec [refer](./docs/create_mapping_spec_doc.md)
+- Create a github issue for [this repo](https://github.com/segmentio/action-destinations) with title: "New Cloud Destination: <Destination Name>" and add the mapping spec in the issue description.

docs/create_mapping_spec_doc.md

@@ -0,0 +1,30 @@
+# Steps to create a new cloud mode destination mapping spec
+
+- Understand what a cloud mode Action Destination is.
+
+  - Read:
+    - https://segment.com/docs/connections/destinations/
+    - https://segment.com/docs/connections/destinations/actions/
+    - [./create.md](./create.md)
+    - [Action Destination](.../README.md#action-destinations)
+
+- Read through API documentation of the partner destination
+  - Also read about that partner api from:
+    - https://hightouch.com/docs/destinations
+    - https://www.rudderstack.com/docs/destinations/overview/
+- Decide what actions we want to build based on destination type: ([refer](./destination-types.md))
+  - conversions
+  - audience destinations
+  - analytics destination
+  - crm destinations
+- Decide approptiate Authentication Strategy ([refer](./authentication.md))
+  - oauth
+  - api key
+  - basic auth
+- Do we need to support batching? If so, what's the batch size and batch byte? ([refer](../README.md#batching-requests))
+- For each action, define mappings with default values and required fields (refer to [input fields](../README.md#input-fields), [default value](../README.md#default-values), [dynamic fields](../README.md#dynamic-fields))
+- Use conditional validations wherever possible ([refer](../README.md#conditional-fields))
+- Decide if we need to use hooks ([refer](../README.md#action-hooks))
+- does batch API support multistatus or not? ([refer](./multistatus.md))
+- Errors exposed by destination API and how they map with Segment Error types ([refer](./error-handling.md))
+- Create Mapping Spec Doc <md document> (refer [a sample spec doc](./sample-mapping-spec-doc.md))

docs/destination-types.md

@@ -0,0 +1,65 @@
+# Compare conversions api vs analytics api vs audience api vs crm api with respect to CDP destinations
+
+Here is a structured comparison of **Conversions API**, **Analytics API**, **Audience API**, and **CRM API** with respect to their roles as CDP (Customer Data Platform) destinations:
+
+---
+
+## 1. Conversions API
+
+- **Purpose:** Sends conversion event data (such as purchases, sign-ups, etc.) from servers, websites, apps, or CRM systems directly to advertising platforms (e.g., Meta, Pinterest).
+- **CDP Role:** Enables seamless server-to-server data sharing, forming a direct link between CDP-collected conversion events and the target marketing/ad platform.
+- **Value:** Optimizes ad targeting, improves attribution, allows more granular reporting, and increases ad ROAS by syncing rich, first-party conversion data.
+- **Data Granularity:** High—includes hashed email, IP address, click ID, etc. More identifiers mean improved match rates.
+- **Integration Complexity:** Usually requires API setup, may be simplified by native integrations or CDP extensions.
+
+---
+
+## 2. Analytics API
+
+- **Purpose:** Pulls data such as sessions, source/medium/campaign, event details, and revenue metrics from analytics tools (e.g., Google Analytics) into CDP.
+- **CDP Role:** CDPs use Analytics API feeds for last-touch attribution, campaign reporting, and user journey analysis.
+- **Value:** Enhances understanding of campaign effectiveness and user pathways. CDPs map analytics data into their internal entities for normalized reporting.
+- **Data Granularity:** Includes dimensions (date, source, medium, campaign, ad group) and metrics (revenue, etc.). Used for mapping events to promotion, campaign, dispatch, and message entities.
+- **Integration Complexity:** Often configured in CDP UI; mapping requires technical setup, may support historical backfill.
+
+---
+
+## 3. Audience API
+
+- **Purpose:** Syncs defined user segments ("audiences") or computed traits from the CDP to external destinations (advertising, marketing automation, personalization tools).
+- **CDP Role:** Basis for activating campaigns based on real-time segmentation, precision targeting, and dynamic personalization.
+- **Value:** Enables cross-channel activation, syncs audiences/user lists, supports computed traits and account-level audiences for B2B.
+- **Data Granularity:** User traits and segmentation lists. Syncs as boolean user-property or user-list; can backfill or send new user data.
+- **Integration Complexity:** Generally accessible via UI-driven configuration; may support CSV export or automation via API.
+
+---
+
+## 4. CRM API
+
+- **Purpose:** Transfers customer profiles, events, transactions, and attributes from CRM platforms to destinations (email, SMS, ad networks, personalization engines).
+- **CDP Role:** A CDP acts as an orchestrator that connects CRM data (often the richest source of first-party customer information) to marketing and analytics destinations for 360° customer views.
+- **Value:** Powers advanced personalization, lifecycle marketing, and holistic attribution by ensuring CRM updates are reflected in all downstream channels.
+- **Data Granularity:** High—may include demographic, behavioral, transactional, and engagement data across touchpoints.
+- **Integration Complexity:** May require custom connectors, but many CDPs provide native CRM integrations for popular platforms.
+
+---
+
+## Feature Comparison Table
+
+| API             | CDP Destination Role         | Data Type \& Granularity     | Primary Use Case                     | Integration Complexity             |
+| :-------------- | :--------------------------- | :--------------------------- | :----------------------------------- | :--------------------------------- |
+| Conversions API | Sync conversion events       | High (event + identifiers)   | Ad attribution, targeting, ROAS      | Medium (native extension or setup) |
+| Analytics API   | Sync campaign analytics      | Medium (event, session, rev) | Attribution, campaign reporting      | Medium (mapping/custom setup)      |
+| Audience API    | Sync user segments/audiences | Medium (traits/user lists)   | Segmentation, audience activation    | Low (UI/API, CSV export)           |
+| CRM API         | Sync rich customer data      | High (profile, history)      | Personalization, lifecycle marketing | Medium (native/custom)             |
+
+---
+
+## Summary
+
+- **Conversions API**: Best for tracking and improving paid campaign outcomes between CDP and ad platforms, focusing on conversion events.
+- **Analytics API**: Ideal for bringing detailed campaign analytics into the CDP for attribution and reporting.
+- **Audience API**: Powers personalized multi-channel marketing by syncing detailed audience segments to external platforms and destinations.
+- **CRM API**: Enables the most comprehensive, personalized marketing experiences by sharing full customer histories across destinations.
+
+All APIs are integral for different CDP destination needs—they complement each other based on the type and granularity of data, with the Audience API often being the "activation" layer, and CRM API representing the unified customer source.