@krunal202/apple-search-ads-cli 0.1.0

package/src/commands/negatives.js

@@ -0,0 +1,77 @@
+import { Command } from 'commander';
+import { api, apiAll } from '../api/client.js';
+import { AsaError } from '../errors.js';
+import { print } from '../output.js';
+import { parseJsonOption } from './helpers.js';
+
+const MATCH_TYPES = ['BROAD', 'EXACT'];
+
+const base = (campaignId, adgroupId) =>
+  adgroupId
+    ? `/campaigns/${campaignId}/adgroups/${adgroupId}/negativekeywords`
+    : `/campaigns/${campaignId}/negativekeywords`;
+
+const scopeDesc = (adgroupId) => (adgroupId ? 'ad-group-level' : 'campaign-level');
+
+export function registerNegatives(program) {
+  const cmd = new Command('negatives').description('Manage negative keywords (campaign-level, or ad-group-level with --adgroup)');
+
+  cmd.command('list').description('List negative keywords')
+    .requiredOption('--campaign <id>', 'campaign ID')
+    .option('--adgroup <id>', 'ad group ID (omit for campaign-level negatives)')
+    .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('create').description('Create negative keywords (bulk via --data)')
+    .requiredOption('--campaign <id>', 'campaign ID')
+    .option('--adgroup <id>', 'ad group ID (omit for campaign-level negatives)')
+    .option('--text <text>', 'keyword text')
+    .option('--match-type <type>', 'BROAD or EXACT', 'BROAD')
+    .option('--data <json>', 'raw JSON array for bulk create, e.g. \'[{"text":"free","matchType":"BROAD"}]\'')
+    .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 negatives create --campaign 123 --text free --match-type BROAD  (${scopeDesc(opts.adgroup)})`,
+          });
+        }
+        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 = [{ text: opts.text, matchType, status: 'ACTIVE' }];
+      }
+      print(await api('POST', `${base(opts.campaign, opts.adgroup)}/bulk`, { body }));
+    });
+
+  cmd.command('delete').description('Delete negative keywords (bulk via --data)')
+    .requiredOption('--campaign <id>', 'campaign ID')
+    .option('--adgroup <id>', 'ad group ID (omit for campaign-level negatives)')
+    .option('--id <id>', 'negative keyword ID')
+    .option('--data <json>', 'raw JSON array of IDs for bulk delete, e.g. \'[123,456]\'')
+    .action(async (opts) => {
+      let ids;
+      if (opts.data) {
+        ids = parseJsonOption(opts.data, '--data');
+        if (!Array.isArray(ids)) ids = [ids];
+      } else if (opts.id) {
+        ids = [Number(opts.id)];
+      } else {
+        throw new AsaError('--id is required (or pass an ID array with --data)');
+      }
+      print(await api('POST', `${base(opts.campaign, opts.adgroup)}/delete/bulk`, { body: ids }));
+    });
+
+  program.addCommand(cmd);
+}

package/src/commands/stats.js

@@ -0,0 +1,81 @@
+import { Command } from 'commander';
+import { api } from '../api/client.js';
+import { AsaError } from '../errors.js';
+import { print } from '../output.js';
+import { collect, csv, parseJsonOption } from './helpers.js';
+
+const LEVELS = ['campaigns', 'adgroups', 'keywords', 'searchterms', 'ads'];
+const GRANULARITIES = ['HOURLY', 'DAILY', 'WEEKLY', 'MONTHLY'];
+const OPERATORS = ['EQUALS', 'IN', 'NOT_IN', 'GREATER_THAN', 'LESS_THAN', 'STARTSWITH', 'CONTAINS'];
+
+export function parseCondition(expr) {
+  const match = expr.match(/^([A-Za-z]+)=([A-Z_]+)=(.+)$/);
+  if (!match || !OPERATORS.includes(match[2])) {
+    throw new AsaError(`Invalid condition "${expr}"`, {
+      hint: `Format: field=OPERATOR=value. Operators: ${OPERATORS.join(', ')}. Example: --condition campaignId=EQUALS=123456`,
+    });
+  }
+  const [, field, operator, rawValue] = match;
+  const values = rawValue.includes(',') ? csv(rawValue) : rawValue;
+  return { field, operator, values: Array.isArray(values) ? values : [values] };
+}
+
+export function registerStats(program) {
+  program.command('stats')
+    .description('Fetch performance reports (impressions, taps, spend, installs...)')
+    .argument('<level>', `report level: ${LEVELS.join(' | ')}`)
+    .requiredOption('--start <date>', 'start date, YYYY-MM-DD')
+    .requiredOption('--end <date>', 'end date, YYYY-MM-DD')
+    .option('--campaign <id>', 'campaign ID (required for adgroups, keywords, searchterms and ads levels)')
+    .option('--granularity <g>', `one of: ${GRANULARITIES.join(', ')}`)
+    .option('--condition <expr>', 'filter as field=OPERATOR=value (repeatable)', collect, [])
+    .option('--order-by <expr>', 'sort as field=ASCENDING|DESCENDING', 'localSpend=DESCENDING')
+    .option('--group-by <fields>', 'comma-separated fields to group by, e.g. countryOrRegion')
+    .option('--include-no-metrics', 'include rows without metrics', false)
+    .option('--data <json>', 'raw JSON selector/body, merged over the flag-built body')
+    .action(async (level, opts) => {
+      if (!LEVELS.includes(level)) {
+        throw new AsaError(`Unknown report level "${level}"`, {
+          hint: `Valid levels: ${LEVELS.join(', ')}. Example: asa stats campaigns --start 2026-09-01 --end 2026-09-15`,
+        });
+      }
+      if (opts.granularity && !GRANULARITIES.includes(opts.granularity.toUpperCase())) {
+        throw new AsaError(`Invalid granularity "${opts.granularity}"`, { hint: `Valid: ${GRANULARITIES.join(', ')}` });
+      }
+      const conditions = opts.condition.map(parseCondition);
+      const orderMatch = opts.orderBy.match(/^([A-Za-z]+)=(ASCENDING|DESCENDING)$/i);
+      if (!orderMatch) {
+        throw new AsaError(`Invalid --order-by "${opts.orderBy}"`, {
+          hint: 'Format: field=ASCENDING or field=DESCENDING, e.g. --order-by localSpend=DESCENDING',
+        });
+      }
+      const base = {
+        startTime: opts.start,
+        endTime: opts.end,
+        timeZone: 'ORTZ',
+        granularity: opts.granularity?.toUpperCase(),
+        groupBy: opts.groupBy ? csv(opts.groupBy) : undefined,
+        returnRowTotals: true,
+        returnGrandTotals: true,
+        returnRecordsWithNoMetrics: opts.includeNoMetrics,
+        selector: {
+          conditions,
+          orderBy: [{ field: orderMatch[1], sortOrder: orderMatch[2].toUpperCase() }],
+        },
+      };
+      for (const key of Object.keys(base)) if (base[key] === undefined) delete base[key];
+      const body = opts.data ? { ...base, ...parseJsonOption(opts.data, '--data') } : base;
+      let resource;
+      if (level === 'campaigns') {
+        resource = '/reports/campaigns';
+      } else {
+        if (!opts.campaign) {
+          throw new AsaError(`--campaign is required for the "${level}" report level (API v5 scopes reports under campaigns)`, {
+            hint: `Example: asa stats ${level} --campaign 123 --start ${opts.start} --end ${opts.end}`,
+          });
+        }
+        resource = `/reports/campaigns/${opts.campaign}/${level}`;
+      }
+      print(await api('POST', resource, { body }));
+    });
+}

package/src/config.js

@@ -0,0 +1,35 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const configDir = process.env.ASA_CONFIG_DIR || path.join(os.homedir(), '.asa');
+
+const file = (name) => path.join(configDir, name);
+
+export function readJson(name) {
+  try {
+    return JSON.parse(fs.readFileSync(file(name), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeJson(name, data) {
+  const target = file(name);
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(target, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+}
+
+export function remove(...names) {
+  for (const name of names) fs.rmSync(file(name), { force: true });
+}
+
+export function getCredentials() {
+  return readJson('config.json');
+}
+
+export function getOrgId(override) {
+  if (override) return Number(override);
+  const config = getCredentials();
+  return config?.orgId;
+}

package/src/errors.js

@@ -0,0 +1,9 @@
+export class AsaError extends Error {
+  constructor(message, { hint, status, details } = {}) {
+    super(message);
+    this.name = 'AsaError';
+    this.hint = hint;
+    this.status = status;
+    this.details = details;
+  }
+}

package/src/memory.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { configDir, getOrgId, readJson, writeJson } from './config.js';
+
+const ACTIVITY_KEEP = 500;
+const ACTIVITY_TRIM_TO = 250;
+
+const dir = (orgId) => path.join(configDir, 'memory', String(orgId ?? 'unknown'));
+
+function appendJsonl(file, entry) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.appendFileSync(file, JSON.stringify(entry) + '\n', { mode: 0o600 });
+}
+
+function trimJsonl(file) {
+  try {
+    const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+    if (lines.length > ACTIVITY_KEEP) {
+      fs.writeFileSync(file, lines.slice(-ACTIVITY_TRIM_TO).join('\n') + '\n', { mode: 0o600 });
+    }
+  } catch { /* no file yet */ }
+}
+
+export function logActivity(entry, orgId = getOrgId()) {
+  if (!orgId) return;
+  const file = path.join(dir(orgId), 'activity.jsonl');
+  appendJsonl(file, { ts: new Date().toISOString(), ...entry });
+  trimJsonl(file);
+}
+
+export function readActivity(orgId = getOrgId(), limit = 20) {
+  try {
+    const lines = fs.readFileSync(path.join(dir(orgId), 'activity.jsonl'), 'utf8').split('\n').filter(Boolean);
+    return lines.slice(-limit).map((line) => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}
+
+export function addNote(note, refs = {}, orgId = getOrgId()) {
+  const name = path.join('memory', String(orgId), 'notes.json');
+  const notes = readJson(name) ?? [];
+  notes.push({ ts: new Date().toISOString(), note, ...refs });
+  writeJson(name, notes);
+  return notes.length;
+}
+
+export function getNotes(orgId = getOrgId()) {
+  return readJson(path.join('memory', String(orgId), 'notes.json')) ?? [];
+}
+
+export function clearMemory(orgId = getOrgId()) {
+  fs.rmSync(dir(orgId), { recursive: true, force: true });
+}

package/src/output.js

@@ -0,0 +1,17 @@
+let pretty = false;
+
+export function setPretty(value) {
+  pretty = value;
+}
+
+export function print(data) {
+  console.log(pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data));
+}
+
+export function printError(err) {
+  const body = { error: err.message };
+  if (err.status) body.status = err.status;
+  if (err.hint) body.hint = err.hint;
+  if (err.details !== undefined) body.details = err.details;
+  console.error(pretty ? JSON.stringify(body, null, 2) : JSON.stringify(body));
+}