@indemn/cli 1.7.8 → 1.7.9

package/src/sdk/campaigns.ts

@@ -1,7 +1,7 @@
 import type { IndemnClient } from './client.js';
 import { CliError, EXIT } from '../core/runtime.js';
 
-/** Paths of the campaigns service the CLI may read. Everything else, and every write, is refused. */
+/** Paths of the campaigns service the CLI may read. Everything else is refused. */
 const READABLE = [
   /^\/campaigns$/,
   /^\/campaigns\/[\w-]+$/,
@@ -11,12 +11,44 @@ const READABLE = [
   /^\/templates\/[\w-]+\/versions$/,
   /^\/template-skills$/,
   /^\/template-skills\/[\w-]+$/,
+  /^\/books$/,
+  /^\/books\/[\w-]+$/,
 ];
 
+type WriteMethod = 'POST' | 'PUT' | 'PATCH';
+/** What the CLI may change: campaigns and their drafts (touchpoints live there), publish and status, templates
+ *  (each change a new version), template skills and books. Never sending or resolving anything, book runs,
+ *  uploads, test ticks or enrollments, and no deletes: those act on real customers or cannot be undone. */
+const WRITABLE: Array<[WriteMethod, RegExp]> = [
+  ['POST', /^\/campaigns$/],
+  ['PUT', /^\/campaigns\/[\w-]+\/draft$/],
+  ['POST', /^\/campaigns\/[\w-]+\/(publish|status)$/],
+  ['POST', /^\/templates$/],
+  ['POST', /^\/templates\/[\w-]+\/versions$/],
+  ['POST', /^\/template-skills$/],
+  ['PUT', /^\/template-skills\/[\w-]+$/],
+  ['POST', /^\/books$/],
+  ['PATCH', /^\/books\/[\w-]+\/source$/],
+  ['PUT', /^\/books\/[\w-]+\/(field-map|identity-keys|display)$/],
+];
+
+export type CampaignStatus = 'draft' | 'running' | 'paused' | 'archived';
+/** A touchpoint in a campaign's draft, found by its key. */
+export type Touchpoint = { key: string } & Record<string, unknown>;
+type Draft = { audience?: unknown; touchpoints?: Touchpoint[]; escalation_policy?: unknown; channel_policy?: unknown };
+type Envelope = { total?: number; items?: Array<Record<string, unknown>> };
+// A template version is whole: a change starts from the latest version's content.
+const TEMPLATE_CONTENT = ['subject', 'body', 'html', 'uses_variables', 'selection_tags', 'skills', 'batch_row'];
+const given = <T extends object>(o: T) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined)) as Partial<T>;
+type Variable = { key: string; required?: boolean; example?: unknown };
+// Templates declare the variables they read as {key, required, example}; given as keys, a key the template already
+// declares keeps its entry.
+const declare = (keys: string[] | undefined, current: Variable[] = []) => keys?.map((key) => current.find((v) => v.key === key) ?? { key });
+
 /**
- * Campaigns, READ-ONLY by design, through copilot's proxy to the campaigns
- * service. The CLI never publishes a campaign, sends a communication or
- * triggers a book sync; those act on real customers.
+ * Campaigns through copilot's proxy to the campaigns service: reads, and
+ * writes to configuration only (WRITABLE). The CLI never sends a
+ * communication, runs a book sync or deletes; those act on real customers.
  */
 export class CampaignsSDK {
   constructor(private client: IndemnClient) {}
@@ -26,6 +58,11 @@ export class CampaignsSDK {
     return this.client.copilotGet<T>(`/organization/:org_id/campaigns-service${path}`, query);
   }
 
+  private async write<T>(method: WriteMethod, path: string, body: unknown): Promise<T> {
+    if (!WRITABLE.some(([m, r]) => m === method && r.test(path))) throw new CliError(`Campaigns ${method} ${path} is not allowed from the CLI.`, EXIT.NEEDS_INPUT);
+    return this.client.copilotRequestRaw<T>(method, `/organization/:org_id/campaigns-service${path}`, body);
+  }
+
   list(filter: { status?: string; solutionId?: string; limit?: number; skip?: number } = {}): Promise<{ total?: number; items?: unknown[] }> {
     const q: Record<string, string> = { limit: String(Math.min(filter.limit ?? 50, 500)), skip: String(filter.skip ?? 0) };
     if (filter.status) q.status = filter.status;
@@ -57,4 +94,88 @@ export class CampaignsSDK {
   templateSkills(solutionId?: string): Promise<unknown> {
     return this.read('/template-skills', solutionId ? { solution_id: solutionId } : undefined);
   }
+
+  templateSkill(id: string): Promise<{ name?: string; instructions?: string }> {
+    return this.read(`/template-skills/${id}`);
+  }
+
+  books(filter: { solutionId?: string; limit?: number } = {}): Promise<Envelope> {
+    const q: Record<string, string> = { limit: String(Math.min(filter.limit ?? 50, 200)) };  // the service allows 200
+    if (filter.solutionId) q.solution_id = filter.solutionId;
+    return this.read('/books', q);
+  }
+
+  book(id: string): Promise<{ name?: string }> {
+    return this.read(`/books/${id}`);
+  }
+
+  createCampaign(input: { solution_id: string; book_id: string; name: string; campaign_type: string; entry?: string; closes?: string }): Promise<{ id: string }> {
+    return this.write('POST', '/campaigns', given(input));
+  }
+
+  /** Change parts of the draft; the rest of it (its touchpoints among it) stays as it is. */
+  async updateDraft(id: string, parts: Omit<Draft, 'touchpoints'>): Promise<Draft> {
+    const { draft } = await this.read<{ draft?: Draft }>(`/campaigns/${id}`);
+    return this.write('PUT', `/campaigns/${id}/draft`, { ...draft, ...given(parts) });
+  }
+
+  /** Add a touchpoint, or change the one with its key (only the fields given). A new one drafts unless told to
+   *  send; a template given without a version is pinned to its latest. */
+  async setTouchpoint(id: string, touchpoint: Touchpoint): Promise<Draft> {
+    const { draft } = await this.read<{ draft?: Draft }>(`/campaigns/${id}`);
+    const current = draft?.touchpoints ?? [];
+    const existing = current.find((t) => t.key === touchpoint.key);
+    const tp: Touchpoint = { ...(existing ?? { terminal_action: 'draft' }), ...given(touchpoint), key: touchpoint.key };
+    if (typeof touchpoint.template_id === 'string' && touchpoint.template_version_n === undefined) {
+      tp.template_version_n = Number((await this.latestTemplateVersion(touchpoint.template_id))?.version_n ?? 1);
+    }
+    const touchpoints = existing ? current.map((t) => (t.key === tp.key ? tp : t)) : [...current, tp];
+    return this.write('PUT', `/campaigns/${id}/draft`, { ...draft, touchpoints });
+  }
+
+  publish(id: string, changeSummary?: string): Promise<unknown> {
+    return this.write('POST', `/campaigns/${id}/publish`, { change_summary: changeSummary ?? '' });
+  }
+
+  setStatus(id: string, status: CampaignStatus): Promise<unknown> {
+    return this.write('POST', `/campaigns/${id}/status`, { status });
+  }
+
+  createTemplate(input: Record<string, unknown> & { uses_variables?: string[] }): Promise<unknown> {
+    return this.write('POST', '/templates', given({ ...input, uses_variables: declare(input.uses_variables) }));
+  }
+
+  private async latestTemplateVersion(id: string): Promise<Record<string, unknown> | undefined> {
+    return (await this.read<Envelope>(`/templates/${id}/versions`)).items?.[0];  // newest first
+  }
+
+  /** A new version of the template: its latest one with the changes given. */
+  async updateTemplate(id: string, changes: Record<string, unknown> & { uses_variables?: string[] }): Promise<unknown> {
+    const latest = (await this.latestTemplateVersion(id)) ?? {};
+    const kept = Object.fromEntries(TEMPLATE_CONTENT.filter((k) => k in latest).map((k) => [k, latest[k]]));
+    return this.write('POST', `/templates/${id}/versions`, { ...kept, ...given({ ...changes, uses_variables: declare(changes.uses_variables, latest.uses_variables as Variable[]) }) });
+  }
+
+  createTemplateSkill(input: { solution_id?: string; key: string; name: string; instructions: string }): Promise<unknown> {
+    return this.write('POST', '/template-skills', input);
+  }
+
+  async updateTemplateSkill(id: string, changes: { name?: string; instructions?: string }): Promise<unknown> {
+    const skill = await this.templateSkill(id);
+    return this.write('PUT', `/template-skills/${id}`, { name: skill.name, instructions: skill.instructions, ...given(changes) });
+  }
+
+  createBook(input: { solution_id: string; name: string; schema_id?: string; source?: unknown }): Promise<{ id: string }> {
+    return this.write('POST', '/books', given(input));
+  }
+
+  /** Change the parts of a book that are given, each its own call in the service. Keys are the book's schema
+   *  keys; identity keys change only while the book has no records. */
+  async updateBook(id: string, changes: { source?: unknown; field_map?: unknown[]; identity_keys?: string[]; display?: unknown }): Promise<unknown> {
+    if (changes.source !== undefined) await this.write('PATCH', `/books/${id}/source`, { source: changes.source });
+    if (changes.field_map !== undefined) await this.write('PUT', `/books/${id}/field-map`, { field_map: changes.field_map });
+    if (changes.identity_keys !== undefined) await this.write('PUT', `/books/${id}/identity-keys`, { identity_keys: changes.identity_keys });
+    if (changes.display !== undefined) await this.write('PUT', `/books/${id}/display`, { display: changes.display });
+    return this.book(id);
+  }
 }

package/test/mcp/__snapshots__/tools-snapshot.test.ts.snap

@@ -111,10 +111,15 @@ exports[`MCP tool list > gives every tool a title and annotations 1`] = `
   "platform_list",
   "platform_save",
   "promote_prod_call",
+  "publish_campaign",
   "reimport_kb_source",
   "remove_holiday",
   "run_evaluation",
   "run_simulation",
+  "save_book",
+  "save_campaign",
+  "save_campaign_template",
+  "save_template_skill",
   "save_ticket_rule",
   "scrape_url",
   "search_phone_numbers",
@@ -122,10 +127,12 @@ exports[`MCP tool list > gives every tool a title and annotations 1`] = `
   "set_agent_transcriber",
   "set_agent_voice",
   "set_business_hours",
+  "set_campaign_status",
   "set_config",
   "set_org_admin_settings",
   "set_org_timezone",
   "set_prompt",
+  "set_touchpoint",
   "simulation_status",
   "test_function",
   "transfer_agent_owner",

package/test/mcp/campaigns.test.ts

@@ -0,0 +1,165 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { on, recordFetch, type RecordedCall, type Responder } from '../helpers/fetch-recorder.js';
+import { cleanEnv } from '../helpers/config-home.js';
+import { connectPair } from '../helpers/mcp-pair.js';
+import { IndemnClient } from '../../src/sdk/client.js';
+import { registerTools } from '../../src/mcp/tools.js';
+import { TOOL_META } from '../../src/mcp/tool-meta.js';
+
+const ORG = 'aaaaaaaaaaaaaaaaaaaaaaaa';
+const solutionsOn = on('GET', `/organization/${ORG}/configurations`, { json: { enableSolutions: true } });
+const approve = () => ({ action: 'accept' as const, content: { confirm: true } });
+async function pair(elicit: () => { action: 'accept' | 'decline'; content?: Record<string, unknown> } = approve) {
+  cleanEnv();
+  const client = new IndemnClient({ apiKey: `ind_dev_${'a'.repeat(64)}`, orgId: ORG, environment: 'dev' });
+  return connectPair((server) => { registerTools(server, client); }, { elicit });
+}
+const fetches = (responders: Responder[]) => recordFetch([solutionsOn, ...responders]);
+const writes = (calls: RecordedCall[]) => calls.filter((c) => c.method !== 'GET').map((c) => `${c.method} ${c.url.split('campaigns-service')[1]}`);
+const draft = { audience: null, touchpoints: [], escalation_policy: {}, channel_policy: {} };
+const campaign = { id: 'c1', name: 'GL renewals', status: 'draft', current_version_n: null, draft };
+
+describe('campaign tools', () => {
+  let p: Awaited<ReturnType<typeof pair>> | undefined;
+  afterEach(async () => { await p?.close(); p = undefined; });
+
+  it('with Solutions off, reads and changes are refused before any card or call, saying how to turn it on', async () => {
+    const { calls } = recordFetch([on('GET', '/configurations', { json: { enableSolutions: false } })]);
+    p = await pair();
+    for (const [name, args] of [['get_campaigns', { what: 'list' }], ['save_campaign', { solution_id: 's1', book_id: 'b1', name: 'X', campaign_type: 'renewal' }]] as const) {
+      const res = await p.call(name, args);
+      expect(res.isError).toBe(true);
+      expect(String(res.body)).toMatch(/Solutions is not turned on.*set_org_admin_settings.*Nothing was changed/);
+    }
+    expect(p.questions).toHaveLength(0);
+    expect(calls.filter((c) => c.url.includes('campaigns-service'))).toHaveLength(0);
+  });
+
+  it('save_campaign without an id creates, asking first by name; confirm and empty fields never reach the service', async () => {
+    const { calls } = fetches([on('GET', '/campaigns-service/books/b1', { json: { id: 'b1', name: 'GL book' } }), on('POST', '/campaigns-service/campaigns', { json: campaign })]);
+    p = await pair();
+    const res = await p.call('save_campaign', { solution_id: 's1', book_id: 'b1', name: 'GL renewals', campaign_type: 'renewal', closes: '', confirm: true });
+    expect(res.isError).toBe(false);
+    expect(p.questions[0].message).toContain('create campaign "GL renewals" as a draft; it sends nothing until it is published and started');
+    expect(writes(calls)).toEqual(['POST /campaigns']);
+    expect(calls.find((c) => c.method === 'POST')!.body).toEqual({ solution_id: 's1', book_id: 'b1', name: 'GL renewals', campaign_type: 'renewal' });
+  });
+
+  it('a create missing what it needs is answered at once: no card, no call', async () => {
+    const { calls } = fetches([]);
+    p = await pair();
+    const res = await p.call('save_campaign', { name: 'GL renewals' });
+    expect(res.isError).toBe(true);
+    expect(String(res.body)).toContain('To create a campaign also give solution_id, book_id, campaign_type');
+    expect(p.questions).toHaveLength(0);
+    expect(writes(calls)).toEqual([]);
+  });
+
+  it('save_campaign with an id changes only the draft parts given, by name on the card', async () => {
+    const touchpoints = [{ key: 't1', channel: 'email' }];
+    const { calls } = fetches([
+      on('GET', '/campaigns-service/campaigns/c1', { json: { ...campaign, draft: { ...draft, touchpoints } } }),
+      on('PUT', '/campaigns-service/campaigns/c1/draft', (c) => ({ json: c.body })),
+    ]);
+    p = await pair();
+    const res = await p.call('save_campaign', { campaign_id: 'c1', audience: '{"field":"status","op":"eq","value":"active"}' });
+    expect(res.isError).toBe(false);
+    expect(p.questions[0].message).toContain('change the audience in the draft of campaign "GL renewals"');
+    expect(calls.find((c) => c.method === 'PUT')!.body).toEqual({ ...draft, touchpoints, audience: { field: 'status', op: 'eq', value: 'active' } });
+  });
+
+  it('set_touchpoint takes flat fields and rules as JSON text, and drafts unless told to send', async () => {
+    const { calls } = fetches([
+      on('GET', '/campaigns-service/campaigns/c1', { json: campaign }),
+      on('PUT', '/campaigns-service/campaigns/c1/draft', (c) => ({ json: c.body })),
+    ]);
+    p = await pair();
+    const res = await p.call('set_touchpoint', { campaign_id: 'c1', key: 't1_60', channel: 'email', when: '{"field":"derived.days_out","op":"lte","value":60}' });
+    expect(res.isError).toBe(false);
+    expect((calls.find((c) => c.method === 'PUT')!.body as typeof draft).touchpoints).toEqual([{ key: 't1_60', channel: 'email', terminal_action: 'draft', when: { field: 'derived.days_out', op: 'lte', value: 60 } }]);
+    expect(p.questions[0].message).toContain('touchpoint "t1_60" in the draft of campaign "GL renewals" (email)');
+  });
+
+  it('starting a campaign is its own approval and says it reaches customers; a decline changes nothing', async () => {
+    const { calls } = fetches([on('GET', '/campaigns-service/campaigns/c1', { json: campaign }), on('POST', '/status', { json: { ...campaign, status: 'running' } })]);
+    p = await pair(() => ({ action: 'decline' }));
+    await p.call('set_campaign_status', { campaign_id: 'c1', status: 'running' });
+    expect(p.questions[0].message).toMatch(/START campaign "GL renewals".*reach real customers/);
+    expect(writes(calls)).toEqual([]);
+  });
+
+  it("the service's refusal reaches the person as it is", async () => {
+    fetches([
+      on('GET', '/campaigns-service/campaigns/c1', { json: campaign }),
+      on('POST', '/status', { status: 409, json: { detail: 'cannot start a campaign that has never published a version' } }),
+    ]);
+    p = await pair();
+    const res = await p.call('set_campaign_status', { campaign_id: 'c1', status: 'running' });
+    expect(res.isError).toBe(true);
+    expect(String(res.body)).toContain('never published a version');
+  });
+
+  it('an id that names nothing gets no card', async () => {
+    const { calls } = fetches([on('GET', '/campaigns-service/campaigns/nope', { status: 404, json: { detail: 'not found' } })]);
+    p = await pair();
+    const res = await p.call('publish_campaign', { campaign_id: 'nope' });
+    expect(String(res.body)).toContain('Not found: campaign nope');
+    expect(p.questions).toHaveLength(0);
+    expect(writes(calls)).toEqual([]);
+  });
+
+  it('save_campaign_template with an id saves a new version from the latest one, named on the card', async () => {
+    const { calls } = fetches([
+      on('GET', '/campaigns-service/templates/tpl1/versions', { json: { items: [{ version_n: 1, subject: 'Renewal', body: 'Old', uses_variables: [] }] } }),
+      on('GET', '/campaigns-service/templates/tpl1', { json: { id: 'tpl1', name: 'GL reminder' } }),
+      on('POST', '/campaigns-service/templates/tpl1/versions', (c) => ({ json: { version_n: 2, ...(c.body as object) } })),
+    ]);
+    p = await pair();
+    const res = await p.call('save_campaign_template', { template_id: 'tpl1', body: 'New', subject: '' });
+    expect(res.isError).toBe(false);
+    expect(calls.find((c) => c.method === 'POST')!.body).toEqual({ subject: 'Renewal', body: 'New', uses_variables: [] });  // "" kept the subject
+    expect(p.questions[0].message).toContain('new version of template "GL reminder" (body)');
+  });
+
+  it('save_template_skill creates and changes, by name on the card', async () => {
+    const { calls } = fetches([
+      on('GET', '/campaigns-service/template-skills/sk1', { json: { id: 'sk1', name: 'Tone', instructions: 'Brief.' } }),
+      (c) => (c.method === 'GET' ? undefined : { json: { id: 'sk1' } }),
+    ]);
+    p = await pair();
+    await p.call('save_template_skill', { solution_id: 's1', key: 'tone', name: 'Tone', instructions: 'Brief.' });
+    await p.call('save_template_skill', { template_skill_id: 'sk1', instructions: 'Warm.' });
+    expect(writes(calls)).toEqual(['POST /template-skills', 'PUT /template-skills/sk1']);
+    expect(calls.filter((c) => c.method !== 'GET').map((c) => c.body)).toEqual([{ solution_id: 's1', key: 'tone', name: 'Tone', instructions: 'Brief.' }, { name: 'Tone', instructions: 'Warm.' }]);
+    expect(p.questions[1].message).toContain('change template skill "Tone" (instructions)');
+  });
+
+  it('save_book changes only the parts given; a create whose change is refused says the book exists', async () => {
+    const { calls } = fetches([
+      on('GET', '/campaigns-service/books/b1', { json: { id: 'b1', name: 'GL book' } }),
+      on('POST', '/campaigns-service/books', { json: { id: 'b2', name: 'New book' } }),
+      on('PUT', '/books/b2/display', { status: 400, json: { detail: 'display names keys absent from the schema: no.such' } }),
+      (c) => (c.method === 'GET' ? undefined : { json: { id: 'b1' } }),
+    ]);
+    p = await pair();
+    const res = await p.call('save_book', { book_id: 'b1', identity_keys: ['policy.number'], display: '{"primary":["policy.number"],"secondary":["insured.name"]}' });
+    expect(res.isError).toBe(false);
+    expect(p.questions[0].message).toContain('change book "GL book": identity keys to policy.number; display to primary policy.number; secondary insured.name.');
+    const made = await p.call('save_book', { solution_id: 's1', name: 'New book', display: '{"primary":["no.such"]}' });
+    expect(String(made.body)).toMatch(/The book was created \(id b2\), but .*no\.such.*do not create it again/);
+    expect(writes(calls)).toEqual(['PUT /books/b1/identity-keys', 'PUT /books/b1/display', 'POST /books', 'PUT /books/b2/display']);
+  });
+
+  it('a book change card shows the new values', () => {
+    expect(TOOL_META.save_book.describe!({ book_id: 'b1', source: { kind: 'upload' }, field_map: [{ source_path: 'Policy #', schema_key: 'policy.number' }, { source_path: 'Insured', schema_key: 'insured.name' }] }))
+      .toBe('This will change book b1: source to upload; field map to Policy # → policy.number, Insured → insured.name.');
+  });
+
+  it('get_campaigns reads books', async () => {
+    const { calls } = fetches([on('GET', '/campaigns-service/books', { json: { total: 1, items: [{ id: 'b1', name: 'GL book' }] } })]);
+    p = await pair();
+    const res = await p.call('get_campaigns', { what: 'books', solution_id: 's1' });
+    expect(res.isError).toBe(false);
+    expect(calls.some((c) => c.method === 'GET' && c.url.includes('/campaigns-service/books?') && c.url.includes('solution_id=s1'))).toBe(true);
+  });
+});

package/test/mcp/tools-snapshot.test.ts

@@ -17,7 +17,7 @@ describe('MCP tool list', () => {
       expect(typeof tool.annotations?.readOnlyHint, tool.name).toBe('boolean');
     }
     expect(tools.map((t) => t.name).sort()).toMatchSnapshot();
-    expect(tools).toHaveLength(141); // +numbers // +set_agent_transcriber // +set_org_admin_settings // +remove_holiday // +create_sandbox_org
+    expect(tools).toHaveLength(148); // +7 campaign tools // +numbers // +set_agent_transcriber // +set_org_admin_settings // +remove_holiday // +create_sandbox_org
     const props = (name: string) => Object.keys((tools.find((t) => t.name === name)!.inputSchema as { properties?: object }).properties ?? {});
     for (const name of ['list_agents', 'delete_agent', 'set_prompt', 'list_org_members', 'list_channels', 'chat_with_agent']) {
       expect(props(name), name).toContain('org_id');
@@ -26,7 +26,7 @@ describe('MCP tool list', () => {
       expect(props(name), name).not.toContain('org_id');
     }
     // Writes that change what customers get or reach outside ask first on every host (a dry run, then confirm).
-    for (const name of ['delete_agent', 'create_function', 'test_function', 'add_kb_data', 'scrape_url', 'upload_kb_file']) {
+    for (const name of ['delete_agent', 'create_function', 'test_function', 'add_kb_data', 'scrape_url', 'upload_kb_file', 'save_campaign', 'set_touchpoint', 'publish_campaign', 'set_campaign_status', 'save_campaign_template', 'save_template_skill', 'save_book']) {
       expect(props(name), name).toContain('confirm');
     }
     // The person chooses how much of a website is crawled: only scrape_url crawls, and it needs their choice.

package/test/sdk/campaigns.test.ts

@@ -1,14 +1,15 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { readFileSync } from 'node:fs';
-import { on, recordFetch } from '../helpers/fetch-recorder.js';
+import { on, recordFetch, type RecordedCall } from '../helpers/fetch-recorder.js';
 import { cleanEnv, useTempHome } from '../helpers/config-home.js';
 import { jwtExpiringIn } from '../helpers/jwt.js';
 import { IndemnClient } from '../../src/sdk/client.js';
 import { CampaignsSDK } from '../../src/sdk/campaigns.js';
 
 const ORG = 'aaaaaaaaaaaaaaaaaaaaaaaa';
+const base = `/api/organization/${ORG}/campaigns-service`;
+const seen = (calls: RecordedCall[]) => calls.map((c) => `${c.method} ${new URL(c.url).pathname.replace(base, '')}`);
 
-describe('campaigns are read-only', () => {
+describe('campaigns: reads, and writes to configuration only', () => {
   let home: ReturnType<typeof useTempHome>;
   beforeEach(() => {
     cleanEnv();
@@ -18,26 +19,83 @@ describe('campaigns are read-only', () => {
   });
   afterEach(() => home.cleanup());
 
-  it('has no write call in the campaigns module', () => {
-    const src = readFileSync(new URL('../../src/sdk/campaigns.ts', import.meta.url), 'utf8');
-    expect(src).not.toMatch(/copilot(Post|Put|Delete|RequestRaw|PostForm|Binary)/);
-  });
-
-  it('reads through the org proxy with GET only', async () => {
+  it('reads through the org proxy with GET, books included', async () => {
     const { calls } = recordFetch([on('GET', '/campaigns-service/', { json: { total: 0, limit: 50, skip: 0, items: [] } })]);
     const sdk = new CampaignsSDK(new IndemnClient());
-    await sdk.list(); await sdk.detail('c1', 'forecast', 30); await sdk.templates(); await sdk.template('t1', true);
-    expect(calls.map((c) => `${c.method} ${new URL(c.url).pathname}`)).toEqual([
-      `GET /api/organization/${ORG}/campaigns-service/campaigns`,
-      `GET /api/organization/${ORG}/campaigns-service/campaigns/c1/forecast`,
-      `GET /api/organization/${ORG}/campaigns-service/templates`,
-      `GET /api/organization/${ORG}/campaigns-service/templates/t1/versions`,
-    ]);
+    await sdk.list(); await sdk.detail('c1', 'forecast', 30); await sdk.templates(); await sdk.template('t1', true); await sdk.books(); await sdk.book('b1');
+    expect(seen(calls)).toEqual(['GET /campaigns', 'GET /campaigns/c1/forecast', 'GET /templates', 'GET /templates/t1/versions', 'GET /books', 'GET /books/b1']);
   });
 
-  it('refuses a path outside the readable list', async () => {
+  it('never sends, runs, uploads, ticks or deletes: those paths are refused before any call', async () => {
     const { calls } = recordFetch();
-    await expect(new CampaignsSDK(new IndemnClient()).get('c1/../../communications/x/send')).rejects.toThrow(/not readable/);
+    const sdk = new CampaignsSDK(new IndemnClient());
+    await expect(sdk.get('c1/../../communications/x/send')).rejects.toThrow(/not readable/);
+    const write = (sdk as unknown as { write: (m: string, p: string, b?: unknown) => Promise<unknown> }).write.bind(sdk);
+    for (const [method, path] of [['POST', '/communications/x/send'], ['POST', '/work-items/w/resolve'], ['POST', '/books/b/runs'], ['POST', '/books/b/uploads'],
+      ['POST', '/campaigns/c/test-tick'], ['POST', '/campaigns/c/candidates/evaluate'], ['POST', '/enrollments/e/close'], ['POST', '/activity'],
+      ['DELETE', '/campaigns/c'], ['PUT', '/campaigns/c'], ['POST', '/campaigns/c/../../communications/x/send']]) {
+      await expect(write(method, path, {})).rejects.toThrow(/not allowed from the CLI/);
+    }
     expect(calls).toHaveLength(0);
   });
+
+  it('a touchpoint is added, or merged into the one with its key; a template given without a version is pinned to its latest', async () => {
+    const draft = { audience: { field: 'status', op: 'eq', value: 'active' }, touchpoints: [{ key: 't1', channel: 'email', terminal_action: 'draft', when: { field: 'derived.days_out', op: 'lte', value: 60 } }], escalation_policy: { then: 'create_work_item' }, channel_policy: {} };
+    const { calls } = recordFetch([
+      on('GET', '/campaigns/c1', { json: { id: 'c1', name: 'Renewals', status: 'draft', draft } }),
+      on('GET', '/templates/tpl1/versions', { json: { total: 2, items: [{ version_n: 2, subject: 'S2', body: 'B2' }, { version_n: 1 }] } }),
+      on('PUT', '/campaigns/c1/draft', (c) => ({ json: c.body })),
+    ]);
+    const sdk = new CampaignsSDK(new IndemnClient());
+    await sdk.setTouchpoint('c1', { key: 't2', channel: 'email', when: { field: 'derived.days_out', op: 'lte', value: 30 }, template_id: 'tpl1' });
+    await sdk.setTouchpoint('c1', { key: 't1', when: { field: 'derived.days_out', op: 'lte', value: 45 } });
+    const puts = calls.filter((c) => c.method === 'PUT').map((c) => c.body as typeof draft);
+    expect(puts[0].touchpoints).toEqual([draft.touchpoints[0], { key: 't2', channel: 'email', terminal_action: 'draft', when: { field: 'derived.days_out', op: 'lte', value: 30 }, template_id: 'tpl1', template_version_n: 2 }]);
+    expect(puts[0].audience).toEqual(draft.audience);  // the rest of the draft is kept
+    expect(puts[1].touchpoints).toEqual([{ ...draft.touchpoints[0], when: { field: 'derived.days_out', op: 'lte', value: 45 } }]);
+  });
+
+  it('a draft change keeps its touchpoints; a template change starts from its latest version', async () => {
+    const draft = { audience: null, touchpoints: [{ key: 't1', channel: 'email' }], escalation_policy: {}, channel_policy: {} };
+    const { calls } = recordFetch([
+      on('GET', '/campaigns/c1', { json: { id: 'c1', draft } }),
+      on('PUT', '/campaigns/c1/draft', (c) => ({ json: c.body })),
+      on('GET', '/templates/tpl1/versions', { json: { items: [{ version_n: 3, subject: 'Hi {{ contact.first_name }}', body: 'Old body', html: '', uses_variables: [{ key: 'contact.first_name', required: true, example: 'Ana' }], selection_tags: {}, skills: {}, batch_row: '', published_by: 'u0' }] } }),
+      on('POST', '/templates/tpl1/versions', (c) => ({ json: { version_n: 4, ...(c.body as object) } })),
+    ]);
+    const sdk = new CampaignsSDK(new IndemnClient());
+    await sdk.updateDraft('c1', { audience: { field: 'status', op: 'eq', value: 'active' } });
+    await sdk.updateTemplate('tpl1', { body: 'New body {{ record.policy.number }}', uses_variables: ['contact.first_name', 'record.policy.number'], change_summary: 'shorter' });
+    expect(calls.find((c) => c.method === 'PUT')!.body).toEqual({ ...draft, audience: { field: 'status', op: 'eq', value: 'active' } });
+    // Variables given as keys: a key already declared keeps its entry, a new one is declared as {key}.
+    expect(calls.find((c) => c.method === 'POST')!.body).toEqual({ subject: 'Hi {{ contact.first_name }}', body: 'New body {{ record.policy.number }}', html: '', uses_variables: [{ key: 'contact.first_name', required: true, example: 'Ana' }, { key: 'record.policy.number' }], selection_tags: {}, skills: {}, batch_row: '', change_summary: 'shorter' });
+  });
+
+  it('writes each configuration call with its method, path and body', async () => {
+    const { calls } = recordFetch([
+      on('GET', '/template-skills/s1', { json: { id: 's1', name: 'Tone', instructions: 'Be brief.' } }),
+      on('GET', '/books/b1', { json: { id: 'b1', name: 'Book' } }),
+      (c) => (c.method === 'GET' ? undefined : { json: { id: 'x' } }),
+    ]);
+    const sdk = new CampaignsSDK(new IndemnClient());
+    await sdk.createCampaign({ solution_id: 's', book_id: 'b', name: 'N', campaign_type: 'renewal' });
+    await sdk.publish('c1', 'first');
+    await sdk.setStatus('c1', 'paused');
+    await sdk.createTemplate({ solution_id: 's', name: 'T', channel: 'email', subject: 'S', body: 'B {{ record.account.name }}', uses_variables: ['record.account.name'] });
+    await sdk.createTemplateSkill({ solution_id: 's', key: 'tone', name: 'Tone', instructions: 'Be brief.' });
+    await sdk.updateTemplateSkill('s1', { instructions: 'Be warm.' });
+    await sdk.createBook({ solution_id: 's', name: 'Book' });
+    await sdk.updateBook('b1', { source: { kind: 'upload' }, identity_keys: ['policy.number'], display: { primary: ['policy.number'], secondary: ['insured.name'] } });
+    const writes = calls.filter((c) => c.method !== 'GET');
+    expect(seen(writes)).toEqual([
+      'POST /campaigns', 'POST /campaigns/c1/publish', 'POST /campaigns/c1/status', 'POST /templates', 'POST /template-skills',
+      'PUT /template-skills/s1', 'POST /books', 'PATCH /books/b1/source', 'PUT /books/b1/identity-keys', 'PUT /books/b1/display',
+    ]);
+    expect(writes.map((c) => c.body)).toEqual([
+      { solution_id: 's', book_id: 'b', name: 'N', campaign_type: 'renewal' }, { change_summary: 'first' }, { status: 'paused' },
+      { solution_id: 's', name: 'T', channel: 'email', subject: 'S', body: 'B {{ record.account.name }}', uses_variables: [{ key: 'record.account.name' }] }, { solution_id: 's', key: 'tone', name: 'Tone', instructions: 'Be brief.' },
+      { name: 'Tone', instructions: 'Be warm.' }, { solution_id: 's', name: 'Book' }, { source: { kind: 'upload' } },  // the service reads body.source
+      { identity_keys: ['policy.number'] }, { display: { primary: ['policy.number'], secondary: ['insured.name'] } },
+    ]);
+  });
 });