chore(release): 0.37.0 — mailchimp campaign-loop actions (reports, content, segments) (#92)

Adds the actions that close a generate→send→measure→optimize email loop on the
existing Mailchimp connector:
- reports.get / reports.list — opens, clicks, unsubscribes, abuse_reports
  (complaint guardrail) and ecommerce revenue (reward signal).
- campaigns.set-content — campaigns.create only makes an empty shell; this PUTs
  the generated email body in.
- segments.list — target a slice and carve out a control/holdout slice.

reports.*/segments.list are reads; campaigns.set-content is an idempotent PUT
mutation. campaigns.create/send already shipped in the write-side fanout.

typecheck clean; full suite 4061 pass; build green.

(These changes were first merged to the stale `main` branch as #91; this lands
them on `develop` — the real release line — and cuts 0.37.0.)

Author: drewstone

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-integrations",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "Vendor-neutral integration contracts and runtime helpers for sandbox and agent apps.",
   "homepage": "https://github.com/tangle-network/agent-integrations#readme",
   "repository": {

src/connectors/adapters/__tests__/mailchimp.test.ts

@@ -46,18 +46,38 @@ describe('mailchimp adapter', () => {
       'campaigns.create',
       'campaigns.list',
       'campaigns.send',
+      'campaigns.set-content',
       'lists.get',
       'lists.list',
       'members.delete-permanent',
       'members.get',
       'members.search',
       'members.update-tags',
       'members.upsert',
+      'reports.get',
+      'reports.list',
+      'segments.list',
     ])
     const readers = mailchimpConnector.manifest.capabilities.filter((c) => c.class === 'read').map((c) => c.name).sort()
     const mutators = mailchimpConnector.manifest.capabilities.filter((c) => c.class === 'mutation').map((c) => c.name).sort()
-    expect(readers).toEqual(['campaigns.list', 'lists.get', 'lists.list', 'members.get', 'members.search'])
-    expect(mutators).toEqual(['campaigns.create', 'campaigns.send', 'members.delete-permanent', 'members.update-tags', 'members.upsert'])
+    expect(readers).toEqual([
+      'campaigns.list',
+      'lists.get',
+      'lists.list',
+      'members.get',
+      'members.search',
+      'reports.get',
+      'reports.list',
+      'segments.list',
+    ])
+    expect(mutators).toEqual([
+      'campaigns.create',
+      'campaigns.send',
+      'campaigns.set-content',
+      'members.delete-permanent',
+      'members.update-tags',
+      'members.upsert',
+    ])
   })
 
   it('exposes both executeRead and executeMutation handlers', () => {
@@ -129,6 +149,49 @@ describe('mailchimp adapter', () => {
     expect(url.pathname).toBe('/3.0/campaigns/camp_99/actions/send')
     expect(init.method).toBe('POST')
   })
+
+  it('reads a campaign performance report (the loop feedback signal) by campaign id', async () => {
+    const fetchMock = mockFetch({
+      id: 'camp_99',
+      opens: { open_rate: 0.41 },
+      clicks: { click_rate: 0.12 },
+      unsubscribed: 3,
+      abuse_reports: 0,
+      ecommerce: { total_orders: 18, total_revenue: 2940.5 },
+    })
+    const invocation: ConnectorInvocation = {
+      source,
+      capabilityName: 'reports.get',
+      args: { campaignId: 'camp_99' },
+      idempotencyKey: 'report_1',
+    }
+
+    await mailchimpConnector.executeRead!(invocation)
+
+    const [url, init] = fetchMock.mock.calls[0] as [URL, RequestInit]
+    expect(url.origin).toBe('https://us20.api.mailchimp.com')
+    expect(url.pathname).toBe('/3.0/reports/camp_99')
+    expect((init as RequestInit).headers).toMatchObject({ authorization: 'Bearer mc_token_xyz' })
+  })
+
+  it('sets draft campaign content with PUT against the content endpoint and forwards the body verbatim', async () => {
+    const fetchMock = mockFetch({ html: '<h1>Hi</h1>' })
+    const contentBody = { html: '<h1>Hi {{FNAME}}</h1><p>New drop.</p>' }
+    const invocation: ConnectorInvocation = {
+      source,
+      capabilityName: 'campaigns.set-content',
+      args: { campaignId: 'camp_99', fields: contentBody },
+      idempotencyKey: 'content_1',
+    }
+
+    const result = await mailchimpConnector.executeMutation!(invocation)
+    expect(result.status).toBe('committed')
+
+    const [url, init] = fetchMock.mock.calls[0] as [URL, RequestInit]
+    expect(url.pathname).toBe('/3.0/campaigns/camp_99/content')
+    expect(init.method).toBe('PUT')
+    expect(JSON.parse(String(init.body))).toEqual(contentBody)
+  })
 })
 
 function mockFetch(body: unknown, init: { status?: number; headers?: Record<string, string> } = {}) {

src/connectors/adapters/mailchimp.ts

@@ -1,8 +1,11 @@
 import { declarativeRestConnector } from './declarative-rest.js'
 
 /**
- * Mailchimp Marketing API v3.0 — audience/list management, member upsert,
- * campaign send. Auth is OAuth2 with a per-account datacenter prefix; after
+ * Mailchimp Marketing API v3.0 — audience/list/segment management, member
+ * upsert, campaign create/content/send, and campaign performance reports
+ * (the open/click/unsubscribe/abuse rates plus ecommerce revenue that close a
+ * generate→send→measure→optimize loop). Auth is OAuth2 with a per-account
+ * datacenter prefix; after
  * the token exchange callers MUST hit `https://login.mailchimp.com/oauth2/metadata`
  * with the access token and persist `api_endpoint` (e.g. `https://us20.api.mailchimp.com`)
  * into the data source `metadata.apiEndpoint` field. The declarative REST
@@ -62,6 +65,26 @@ export const mailchimpConnector = declarativeRestConnector({
       },
       request: { method: 'GET', path: '/3.0/lists/{listId}' },
     },
+    {
+      name: 'segments.list',
+      class: 'read',
+      description:
+        'List the segments of a Mailchimp audience. Use a segment id in `campaigns.create` recipients to target a slice — and to carve out a control/holdout slice for measuring true lift.',
+      parameters: {
+        type: 'object',
+        properties: {
+          listId: { type: 'string' },
+          count: { type: 'number' },
+          offset: { type: 'number' },
+        },
+        required: ['listId'],
+      },
+      request: {
+        method: 'GET',
+        path: '/3.0/lists/{listId}/segments',
+        query: { count: '{count}', offset: '{offset}' },
+      },
+    },
     {
       name: 'members.search',
       class: 'read',
@@ -219,5 +242,68 @@ export const mailchimpConnector = declarativeRestConnector({
       cas: 'native-idempotency',
       externalEffect: true,
     },
+    {
+      name: 'campaigns.set-content',
+      class: 'mutation',
+      description:
+        'Set the content of a draft Mailchimp campaign. `campaigns.create` only makes an empty shell — this puts the generated email body in. Body matches the v3.0 campaign-content schema, e.g. `{ html }` or `{ plain_text }` or `{ template: { id, sections } }`.',
+      parameters: {
+        type: 'object',
+        properties: {
+          campaignId: { type: 'string' },
+          fields: {
+            type: 'object',
+            description: 'Campaign content body; typically `{ html }`. PUT replaces the content wholesale.',
+          },
+        },
+        required: ['campaignId', 'fields'],
+      },
+      request: {
+        method: 'PUT',
+        path: '/3.0/campaigns/{campaignId}/content',
+        body: '{fields}',
+      },
+      cas: 'native-idempotency',
+    },
+    {
+      name: 'reports.list',
+      class: 'read',
+      description:
+        'List campaign performance reports. Each entry carries the open/click/unsubscribe/abuse rates and (when an ecommerce store is connected) revenue — the feedback signal the optimizer reads to learn what worked.',
+      parameters: {
+        type: 'object',
+        properties: {
+          count: { type: 'number' },
+          offset: { type: 'number' },
+          type: { type: 'string', description: 'Filter by campaign type, e.g. regular, plaintext, rss.' },
+          since_send_time: {
+            type: 'string',
+            description: 'ISO 8601 lower bound on send time, e.g. 2026-06-01T00:00:00Z — read only recent sends.',
+          },
+        },
+      },
+      request: {
+        method: 'GET',
+        path: '/3.0/reports',
+        query: {
+          count: '{count}',
+          offset: '{offset}',
+          type: '{type}',
+          since_send_time: '{since_send_time}',
+        },
+      },
+    },
+    {
+      name: 'reports.get',
+      class: 'read',
+      description:
+        'Read the performance report for one sent campaign: opens, clicks, unsubscribes, abuse_reports (the complaint signal), bounces, list_stats, and ecommerce { total_orders, total_spent, total_revenue }. This is the reward+guardrail signal for the optimization loop.',
+      parameters: {
+        type: 'object',
+        properties: { campaignId: { type: 'string' } },
+        required: ['campaignId'],
+      },
+      request: { method: 'GET', path: '/3.0/reports/{campaignId}' },
+    },
   ],
 })