@krunal202/apple-search-ads-cli 0.1.0

package/src/commands/adgroups.js

@@ -0,0 +1,92 @@
+import { Command } from 'commander';
+import { api, apiAll } from '../api/client.js';
+import { AsaError } from '../errors.js';
+import { print } from '../output.js';
+import { mergeData, money } from './helpers.js';
+
+const base = (campaignId) => `/campaigns/${campaignId}/adgroups`;
+
+function requireCampaign(opts) {
+  if (!opts.campaign) {
+    throw new AsaError('--campaign is required (API v5 scopes ad groups under campaigns)', {
+      hint: 'Find the campaign ID with "asa campaigns list".',
+    });
+  }
+  return opts.campaign;
+}
+
+function stripUndefined(obj) {
+  for (const key of Object.keys(obj)) if (obj[key] === undefined) delete obj[key];
+  return obj;
+}
+
+export function registerAdGroups(program) {
+  const cmd = new Command('adgroups').description('Manage ad groups (scoped to a campaign)');
+
+  cmd.command('list').description('List ad groups in a campaign')
+    .requiredOption('--campaign <id>', 'campaign ID')
+    .option('--limit <n>', 'max results (1-1000)', '20')
+    .option('--offset <n>', 'result offset', '0')
+    .option('--all', 'fetch every page')
+    .action(async (opts) => {
+      if (opts.all) return print({ data: await apiAll(base(requireCampaign(opts))), error: null });
+      print(await api('GET', base(requireCampaign(opts)), { query: { limit: opts.limit, offset: opts.offset } }));
+    });
+
+  cmd.command('get').description('Get a single ad group')
+    .argument('<id>', 'ad group ID')
+    .requiredOption('--campaign <id>', 'campaign ID')
+    .action(async (id, opts) => print(await api('GET', `${base(requireCampaign(opts))}/${id}`)));
+
+  cmd.command('create').description('Create an ad group')
+    .requiredOption('--campaign <id>', 'parent campaign ID')
+    .requiredOption('--name <name>', 'ad group name')
+    .option('--bid <amount>', 'default CPT bid amount')
+    .option('--currency <code>', 'currency (required with --bid)')
+    .option('--status <status>', 'ENABLED or PAUSED', 'ENABLED')
+    .option('--start-time <iso>', 'start time (defaults to now)')
+    .option('--data <json>', 'raw JSON body, merged over the flag-built body; use for targeting dimensions, CPA goal, etc.')
+    .action(async (opts) => {
+      if (opts.bid && !opts.currency && !opts.data) {
+        throw new AsaError('--currency is required when setting --bid');
+      }
+      const body = mergeData(stripUndefined({
+        name: opts.name,
+        defaultBidAmount: money(opts.bid, opts.currency),
+        pricingModel: 'CPC',
+        status: opts.status,
+        startTime: opts.startTime ?? new Date().toISOString(),
+      }), opts.data);
+      print(await api('POST', base(requireCampaign(opts)), { body }));
+    });
+
+  cmd.command('update').description('Update an ad group')
+    .argument('<id>', 'ad group ID')
+    .requiredOption('--campaign <id>', 'campaign ID')
+    .option('--name <name>')
+    .option('--status <status>', 'ENABLED or PAUSED')
+    .option('--bid <amount>', 'default CPT bid amount')
+    .option('--currency <code>', 'currency (required with --bid)')
+    .option('--data <json>', 'raw JSON body, merged over the flag-built body')
+    .action(async (id, opts) => {
+      if (opts.bid && !opts.currency && !opts.data) {
+        throw new AsaError('--currency is required when setting --bid');
+      }
+      const body = mergeData(stripUndefined({
+        name: opts.name,
+        status: opts.status,
+        defaultBidAmount: money(opts.bid, opts.currency),
+      }), opts.data);
+      print(await api('PUT', `${base(requireCampaign(opts))}/${id}`, { body }));
+    });
+
+  cmd.command('delete').description('Delete an ad group')
+    .argument('<id>', 'ad group ID')
+    .requiredOption('--campaign <id>', 'campaign ID')
+    .action(async (id, opts) => {
+      await api('DELETE', `${base(requireCampaign(opts))}/${id}`);
+      print({ ok: true, deleted: Number(id) });
+    });
+
+  program.addCommand(cmd);
+}

package/src/commands/apps.js

@@ -0,0 +1,16 @@
+import { Command } from 'commander';
+import { api } from '../api/client.js';
+import { print } from '../output.js';
+
+export function registerApps(program) {
+  const cmd = new Command('apps').description('Look up App Store apps');
+
+  cmd.command('search').description('Search apps by name to find the adamId needed for campaign creation')
+    .argument('<query>', 'app name, e.g. "secure vpn"')
+    .option('--limit <n>', 'max results', '10')
+    .action(async (query, opts) => {
+      print(await api('GET', '/search/apps', { query: { query, limit: opts.limit } }));
+    });
+
+  program.addCommand(cmd);
+}

package/src/commands/auth.js

@@ -0,0 +1,108 @@
+import fs from 'node:fs';
+import readline from 'node:readline/promises';
+import { Command } from 'commander';
+import { api } from '../api/client.js';
+import { readJson, remove, writeJson } from '../config.js';
+import { AsaError } from '../errors.js';
+import { print } from '../output.js';
+
+async function ask(question, fallback) {
+  if (!process.stdin.isTTY) {
+    if (fallback !== undefined) return fallback;
+    throw new AsaError(`Missing required value: ${question}`, {
+      hint: 'Non-interactive shell detected. Pass all values as flags: asa login --client-id <id> --team-id <id> --key-id <id> --key-file <path-to-p8> [--org <orgId>]',
+    });
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(`${question}: `);
+    return answer.trim() || fallback;
+  } finally {
+    rl.close();
+  }
+}
+
+async function login(opts) {
+  const clientId = await ask('Client ID', opts.clientId);
+  const teamId = await ask('Team ID', opts.teamId);
+  const keyId = await ask('Key ID', opts.keyId);
+  const keyFile = await ask('Path to .p8 private key file', opts.keyFile);
+
+  if (!clientId || !teamId || !keyId || !keyFile) {
+    throw new AsaError('client ID, team ID, key ID and key file are all required', {
+      hint: 'Create credentials in Apple Search Ads → Account Settings → API. See "asa llm" for details.',
+    });
+  }
+
+  let privateKey;
+  try {
+    privateKey = fs.readFileSync(keyFile, 'utf8');
+  } catch {
+    throw new AsaError(`Cannot read private key file: ${keyFile}`);
+  }
+
+  writeJson('config.json', { clientId, teamId, keyId, privateKey, orgId: opts.org ? Number(opts.org) : undefined });
+  remove('token.json');
+
+  const acls = await api('GET', '/acls');
+  const orgs = (acls.data ?? acls).map((acl) => ({ orgId: acl.orgId, orgName: acl.orgName, role: acl.roleName ?? acl.roleNames }));
+
+  let orgId = opts.org ? Number(opts.org) : undefined;
+  if (!orgId) {
+    if (orgs.length === 0) throw new AsaError('No organizations found for these credentials');
+    orgId = orgs[0].orgId;
+    if (orgs.length > 1 && process.stdin.isTTY) {
+      const answer = await ask(`Multiple orgs available. Org ID to use [${orgs.map((o) => o.orgId).join(', ')}]`, String(orgId));
+      orgId = Number(answer);
+    }
+  }
+
+  writeJson('config.json', { clientId, teamId, keyId, privateKey, orgId });
+  print({ ok: true, message: 'Logged in', orgId, orgs });
+}
+
+function logout() {
+  remove('config.json', 'token.json', 'clipboard.json');
+  print({ ok: true, message: 'Logged out; credentials, token and clipboard removed' });
+}
+
+function whoami() {
+  const config = readJson('config.json');
+  if (!config) throw new AsaError('Not logged in', { hint: 'Run "asa login" first.' });
+  print({ clientId: config.clientId, teamId: config.teamId, keyId: config.keyId, orgId: config.orgId });
+}
+
+export function registerAuth(program) {
+  program.command('login')
+    .description('Store Apple Search Ads API credentials and select an org')
+    .option('--client-id <id>', 'API client ID')
+    .option('--team-id <id>', 'Apple team ID')
+    .option('--key-id <id>', 'API key ID')
+    .option('--key-file <path>', 'path to the .p8 private key')
+    .option('--org <orgId>', 'organization ID to activate')
+    .action(login);
+
+  program.command('logout').description('Remove stored credentials, token and clipboard').action(logout);
+  program.command('whoami').description('Show the stored credentials summary and active org').action(whoami);
+}
+
+export function registerOrgs(program) {
+  const cmd = new Command('orgs').description('List and switch organizations');
+
+  cmd.command('list').description('List orgs accessible with the current credentials')
+    .action(async () => {
+      const acls = await api('GET', '/acls');
+      print(acls.data ?? acls);
+    });
+
+  cmd.command('use').description('Set the active organization')
+    .argument('<orgId>', 'organization ID from "asa orgs list"')
+    .action(async (orgId) => {
+      const config = readJson('config.json');
+      if (!config) throw new AsaError('Not logged in', { hint: 'Run "asa login" first.' });
+      writeJson('config.json', { ...config, orgId: Number(orgId) });
+      print({ ok: true, orgId: Number(orgId) });
+    });
+
+  program.addCommand(cmd);
+}

package/src/commands/campaigns.js

@@ -0,0 +1,90 @@
+import { Command } from 'commander';
+import { api, apiAll } from '../api/client.js';
+import { AsaError } from '../errors.js';
+import { print } from '../output.js';
+import { csv, mergeData, money } from './helpers.js';
+
+export function registerCampaigns(program) {
+  const cmd = new Command('campaigns').description('Manage campaigns');
+
+  cmd.command('list').description('List campaigns')
+    .option('--limit <n>', 'max results (1-1000)', '20')
+    .option('--offset <n>', 'result offset', '0')
+    .option('--all', 'fetch every page')
+    .action(async (opts) => {
+      if (opts.all) return print({ data: await apiAll('/campaigns'), error: null });
+      print(await api('GET', '/campaigns', { query: { limit: opts.limit, offset: opts.offset } }));
+    });
+
+  cmd.command('get').description('Get a single campaign')
+    .argument('<id>', 'campaign ID')
+    .action(async (id) => print(await api('GET', `/campaigns/${id}`)));
+
+  cmd.command('create').description('Create a campaign (created PAUSED by default)')
+    .requiredOption('--name <name>', 'campaign name')
+    .requiredOption('--currency <code>', 'ISO currency, e.g. USD')
+    .requiredOption('--adam-id <id>', 'App Store app ID (numeric)')
+    .requiredOption('--countries <codes>', 'comma-separated storefront codes, e.g. US,GB')
+    .option('--budget <amount>', 'lifetime budget amount, e.g. 1000 (optional)')
+    .option('--daily-budget <amount>', 'daily budget amount')
+    .option('--status <status>', 'ENABLED or PAUSED', 'PAUSED')
+    .option('--start-time <iso>', 'start time, e.g. 2026-09-20T00:00:00.000Z')
+    .option('--end-time <iso>', 'end time')
+    .option('--data <json>', 'raw JSON body, merged over the flag-built body')
+    .action(async (opts) => {
+      const body = mergeData({
+        name: opts.name,
+        adamId: Number(opts.adamId),
+        countriesOrRegions: csv(opts.countries),
+        adChannelType: 'SEARCH',
+        supplySources: ['APPSTORE_SEARCH_RESULTS'],
+        billingEvent: 'TAPS',
+        budgetAmount: money(opts.budget, opts.currency),
+        dailyBudgetAmount: money(opts.dailyBudget, opts.currency),
+        status: opts.status,
+        startTime: opts.startTime,
+        endTime: opts.endTime,
+      }, opts.data);
+      print(await api('POST', '/campaigns', { body }));
+    });
+
+  cmd.command('update').description('Update a campaign')
+    .argument('<id>', 'campaign ID')
+    .option('--name <name>')
+    .option('--status <status>', 'ENABLED or PAUSED')
+    .option('--budget <amount>', 'lifetime budget amount')
+    .option('--daily-budget <amount>', 'daily budget amount')
+    .option('--currency <code>', 'currency (required when setting budgets)')
+    .option('--countries <codes>', 'comma-separated storefront codes')
+    .option('--start-time <iso>')
+    .option('--end-time <iso>')
+    .option('--clear-end-time', 'remove the end time')
+    .option('--data <json>', 'raw JSON body, merged over the flag-built body')
+    .action(async (id, opts) => {
+      if ((opts.budget || opts.dailyBudget) && !opts.currency && !opts.data) {
+        throw new AsaError('--currency is required when setting budgets');
+      }
+      const fields = mergeData({
+        name: opts.name,
+        status: opts.status,
+        budgetAmount: money(opts.budget, opts.currency),
+        dailyBudgetAmount: money(opts.dailyBudget, opts.currency),
+        countriesOrRegions: opts.countries ? csv(opts.countries) : undefined,
+        startTime: opts.startTime,
+        endTime: opts.clearEndTime ? null : opts.endTime,
+      }, opts.data);
+      for (const key of Object.keys(fields)) if (fields[key] === undefined) delete fields[key];
+      const body = { campaign: fields };
+      if (opts.countries) body.clearGeoTargetingOnCountryOrRegionChange = true;
+      print(await api('PUT', `/campaigns/${id}`, { body }));
+    });
+
+  cmd.command('delete').description('Delete a campaign')
+    .argument('<id>', 'campaign ID')
+    .action(async (id) => {
+      await api('DELETE', `/campaigns/${id}`);
+      print({ ok: true, deleted: Number(id) });
+    });
+
+  program.addCommand(cmd);
+}

package/src/commands/clipboard.js

@@ -0,0 +1,100 @@
+import { api } from '../api/client.js';
+import { readJson, writeJson } from '../config.js';
+import { AsaError } from '../errors.js';
+import { print } from '../output.js';
+
+const TYPES = {
+  campaign: {
+    fetch: (id) => api('GET', `/campaigns/${id}`),
+    create: (data) => api('POST', '/campaigns', { body: data }),
+  },
+  adgroup: {
+    needs: ['campaign'],
+    fetch: (id, opts) => api('GET', `/campaigns/${opts.campaign}/adgroups/${id}`),
+    create: (data, opts) => api('POST', `/campaigns/${opts.campaign ?? data.campaignId}/adgroups`, { body: data }),
+  },
+  keyword: {
+    needs: ['campaign', 'adgroup'],
+    fetch: (id, opts) => api('GET', `/campaigns/${opts.campaign}/adgroups/${opts.adgroup}/targetingkeywords/${id}`),
+    create: (data, opts) => api('POST', `/campaigns/${opts.campaign ?? data.campaignId}/adgroups/${opts.adgroup ?? data.adGroupId}/targetingkeywords/bulk`, { body: [data] }),
+  },
+};
+
+const READ_ONLY_FIELDS = [
+  'id', 'orgId', 'creationTime', 'modificationTime', 'deleted',
+  'servingStatus', 'servingStateReasons', 'displayStatus', 'computedStatus',
+];
+
+export function sanitize(data) {
+  if (data && typeof data === 'object' && data.data && typeof data.data === 'object') {
+    return sanitize(data.data);
+  }
+  const copy = { ...data };
+  for (const field of READ_ONLY_FIELDS) delete copy[field];
+  return copy;
+}
+
+async function copyResource(type, id, opts) {
+  const handler = TYPES[type];
+  if (!handler) {
+    throw new AsaError(`Unknown resource type "${type}"`, {
+      hint: `Valid types: ${Object.keys(TYPES).join(', ')}. Example: asa copy campaign 123456`,
+    });
+  }
+  for (const required of handler.needs ?? []) {
+    if (!opts[required]) {
+      throw new AsaError(`--${required} is required when copying a ${type} (API v5 scopes it under its parents)`, {
+        hint: `Example: asa copy ${type} ${id} ${(handler.needs ?? []).map((n) => `--${n} <id>`).join(' ')}`,
+      });
+    }
+  }
+  const data = sanitize(await handler.fetch(id, opts));
+  writeJson('clipboard.json', { type, sourceId: Number(id), parents: { campaign: opts.campaign, adgroup: opts.adgroup }, data });
+  print({ ok: true, copied: { type, sourceId: Number(id) }, data });
+}
+
+async function pasteResource(opts) {
+  const clipboard = readJson('clipboard.json');
+  if (!clipboard) {
+    throw new AsaError('Clipboard is empty', { hint: 'Copy something first, e.g. asa copy campaign 123456' });
+  }
+  const handler = TYPES[clipboard.type];
+  const data = {
+    ...clipboard.data,
+    name: opts.name ?? (clipboard.data.name ? `${clipboard.data.name} - Copy` : undefined),
+    status: opts.status ?? 'PAUSED',
+  };
+  for (const key of Object.keys(data)) if (data[key] === undefined) delete data[key];
+  const now = Date.now();
+  if (data.startTime && new Date(data.startTime).getTime() < now) data.startTime = new Date().toISOString();
+  if (data.endTime && new Date(data.endTime).getTime() < now) delete data.endTime;
+  const parents = {
+    campaign: opts.campaign ?? clipboard.parents?.campaign,
+    adgroup: opts.adgroup ?? clipboard.parents?.adgroup,
+  };
+  if (clipboard.type === 'adgroup' && parents.campaign) data.campaignId = Number(parents.campaign);
+  if (clipboard.type === 'keyword') {
+    if (parents.campaign) data.campaignId = Number(parents.campaign);
+    if (parents.adgroup) data.adGroupId = Number(parents.adgroup);
+  }
+  const created = await handler.create(data, parents);
+  print({ ok: true, pasted: clipboard.type, from: clipboard.sourceId, created });
+}
+
+export function registerClipboard(program) {
+  program.command('copy')
+    .description('Copy a resource to the local clipboard')
+    .argument('<type>', `resource type: ${Object.keys(TYPES).join(' | ')}`)
+    .argument('<id>', 'resource ID')
+    .option('--campaign <id>', 'campaign ID (required for adgroup and keyword)')
+    .option('--adgroup <id>', 'ad group ID (required for keyword)')
+    .action(copyResource);
+
+  program.command('paste')
+    .description('Create a new resource from the clipboard (created PAUSED unless --status is given)')
+    .option('--name <name>', 'override the copied name')
+    .option('--status <status>', 'ENABLED or PAUSED', 'PAUSED')
+    .option('--campaign <id>', 'target campaign ID when pasting an ad group or keyword (defaults to the source)')
+    .option('--adgroup <id>', 'target ad group ID when pasting a keyword (defaults to the source)')
+    .action(pasteResource);
+}

package/src/commands/guide.js

@@ -0,0 +1,9 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const guidePath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'LLM_GUIDE.md');
+
+export function printGuide() {
+  process.stdout.write(fs.readFileSync(guidePath, 'utf8'));
+}

package/src/commands/helpers.js

@@ -0,0 +1,27 @@
+import { AsaError } from '../errors.js';
+
+export function parseJsonOption(value, label) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    throw new AsaError(`Invalid JSON for ${label}`, {
+      hint: `Pass valid JSON, e.g. ${label} '{"name":"Example"}'`,
+    });
+  }
+}
+
+export function mergeData(flags, rawData) {
+  return rawData ? { ...flags, ...parseJsonOption(rawData, '--data') } : flags;
+}
+
+export function money(amount, currency) {
+  return amount !== undefined ? { amount: String(amount), currency } : undefined;
+}
+
+export function csv(value) {
+  return String(value).split(',').map((v) => v.trim()).filter(Boolean);
+}
+
+export function collect(value, previous) {
+  return previous.concat([value]);
+}

package/src/commands/keywords.js

@@ -0,0 +1,102 @@
+import { Command } from 'commander';
+import { api, apiAll } from '../api/client.js';
+import { AsaError } from '../errors.js';
+import { print } from '../output.js';
+import { mergeData, money, parseJsonOption } from './helpers.js';
+
+const MATCH_TYPES = ['BROAD', 'EXACT'];
+
+const base = (campaignId, adgroupId) => `/campaigns/${campaignId}/adgroups/${adgroupId}/targetingkeywords`;
+
+export function registerKeywords(program) {
+  const cmd = new Command('keywords').description('Manage targeting keywords within ad groups');
+
+  cmd.command('list').description('List keywords in an ad group')
+    .requiredOption('--campaign <id>', 'campaign ID')
+    .requiredOption('--adgroup <id>', 'ad group ID')
+    .option('--limit <n>', 'max results (1-1000)', '20')
+    .option('--offset <n>', 'result offset', '0')
+    .option('--all', 'fetch every page')
+    .action(async (opts) => {
+      if (opts.all) return print({ data: await apiAll(base(opts.campaign, opts.adgroup)), error: null });
+      print(await api('GET', base(opts.campaign, opts.adgroup), { query: { limit: opts.limit, offset: opts.offset } }));
+    });
+
+  cmd.command('get').description('Get a single keyword')
+    .argument('<id>', 'keyword ID')
+    .requiredOption('--campaign <id>', 'campaign ID')
+    .requiredOption('--adgroup <id>', 'ad group ID')
+    .action(async (id, opts) => print(await api('GET', `${base(opts.campaign, opts.adgroup)}/${id}`)));
+
+  cmd.command('create').description('Create keywords (always a bulk call; use --data for several)')
+    .requiredOption('--campaign <id>', 'campaign ID')
+    .requiredOption('--adgroup <id>', 'ad group ID')
+    .option('--text <text>', 'keyword text')
+    .option('--match-type <type>', 'BROAD or EXACT', 'BROAD')
+    .option('--bid <amount>', 'bid amount')
+    .option('--currency <code>', 'currency (required with --bid)')
+    .option('--status <status>', 'ENABLED or PAUSED', 'ENABLED')
+    .option('--data <json>', 'raw JSON array for bulk create, e.g. \'[{"text":"shoes","matchType":"EXACT"}]\'')
+    .action(async (opts) => {
+      let body;
+      if (opts.data) {
+        body = parseJsonOption(opts.data, '--data');
+        if (!Array.isArray(body)) body = [body];
+      } else {
+        if (!opts.text) {
+          throw new AsaError('--text is required (or pass a bulk array with --data)', {
+            hint: 'Example: asa keywords create --campaign 123 --adgroup 456 --text "running shoes" --match-type EXACT',
+          });
+        }
+        const matchType = opts.matchType.toUpperCase();
+        if (!MATCH_TYPES.includes(matchType)) {
+          throw new AsaError(`Invalid match type "${opts.matchType}"`, {
+            hint: `Valid match types: ${MATCH_TYPES.join(', ')}`,
+          });
+        }
+        body = [mergeData({
+          text: opts.text,
+          matchType,
+          bidAmount: money(opts.bid, opts.currency),
+          status: opts.status,
+        }, undefined)];
+      }
+      print(await api('POST', `${base(opts.campaign, opts.adgroup)}/bulk`, { body }));
+    });
+
+  cmd.command('update').description('Update keywords (bulk; repeat --id via --data for several)')
+    .argument('<id>', 'keyword ID')
+    .requiredOption('--campaign <id>', 'campaign ID')
+    .requiredOption('--adgroup <id>', 'ad group ID')
+    .option('--bid <amount>')
+    .option('--currency <code>', 'currency (required with --bid)')
+    .option('--status <status>', 'ENABLED or PAUSED')
+    .option('--data <json>', 'raw JSON array of keyword updates, replacing the flag-built body')
+    .action(async (id, opts) => {
+      let body;
+      if (opts.data) {
+        body = parseJsonOption(opts.data, '--data');
+        if (!Array.isArray(body)) body = [body];
+      } else {
+        const single = mergeData({
+          id: Number(id),
+          bidAmount: money(opts.bid, opts.currency),
+          status: opts.status,
+        }, undefined);
+        for (const key of Object.keys(single)) if (single[key] === undefined) delete single[key];
+        body = [single];
+      }
+      print(await api('PUT', `${base(opts.campaign, opts.adgroup)}/bulk`, { body }));
+    });
+
+  cmd.command('delete').description('Delete a keyword')
+    .argument('<id>', 'keyword ID')
+    .requiredOption('--campaign <id>', 'campaign ID')
+    .requiredOption('--adgroup <id>', 'ad group ID')
+    .action(async (id, opts) => {
+      await api('DELETE', `${base(opts.campaign, opts.adgroup)}/${id}`);
+      print({ ok: true, deleted: Number(id) });
+    });
+
+  program.addCommand(cmd);
+}

package/src/commands/memory.js

@@ -0,0 +1,69 @@
+import { apiAll } from '../api/client.js';
+import { getOrgId, readJson } from '../config.js';
+import { AsaError } from '../errors.js';
+import { addNote, clearMemory, getNotes, readActivity } from '../memory.js';
+import { print } from '../output.js';
+
+const campaignSummary = (c) => ({
+  id: c.id,
+  name: c.name,
+  status: c.status,
+  servingStatus: c.servingStatus,
+  dailyBudget: c.dailyBudgetAmount,
+  countriesOrRegions: c.countriesOrRegions,
+});
+
+async function context(opts) {
+  const orgId = getOrgId();
+  if (!orgId) throw new AsaError('Not logged in', { hint: 'Run "asa login" first.' });
+  const out = {
+    org: orgId,
+    notes: getNotes(orgId),
+    recentActivity: readActivity(orgId, Number(opts.limit)),
+  };
+  if (opts.live) {
+    const campaigns = await apiAll('/campaigns');
+    out.campaigns = campaigns.filter((c) => !c.deleted).map(campaignSummary);
+  }
+  print(out);
+}
+
+function remember(note, opts) {
+  const refs = {};
+  if (opts.campaign) refs.campaignId = Number(opts.campaign);
+  if (opts.adgroup) refs.adGroupId = Number(opts.adgroup);
+  if (opts.keyword) refs.keywordId = Number(opts.keyword);
+  const total = addNote(note, refs);
+  print({ ok: true, notes: total });
+}
+
+function memory(opts) {
+  const orgId = getOrgId();
+  if (opts.clear) {
+    clearMemory(orgId);
+    return print({ ok: true, cleared: orgId });
+  }
+  print({ org: orgId, notes: getNotes(orgId), recentActivity: readActivity(orgId, Number(opts.limit)) });
+}
+
+export function registerMemory(program) {
+  program.command('context')
+    .description('Session-start snapshot for LLM agents: notes, recent mutations, and (with --live) current campaigns')
+    .option('--live', 'include the current campaign list from the API')
+    .option('--limit <n>', 'activity entries to include', '20')
+    .action(context);
+
+  program.command('remember')
+    .description('Store a note in memory so future sessions keep the context')
+    .argument('<note>', 'free-text note, e.g. "Lowered US bids to 1/3 because of IR/RU traffic"')
+    .option('--campaign <id>', 'attach the note to a campaign')
+    .option('--adgroup <id>', 'attach the note to an ad group')
+    .option('--keyword <id>', 'attach the note to a keyword')
+    .action(remember);
+
+  program.command('memory')
+    .description('Dump (or with --clear, erase) the stored memory for the active org')
+    .option('--limit <n>', 'activity entries to include', '50')
+    .option('--clear', 'erase all memory for the active org')
+    .action(memory);
+}