@koda-sl/baker-cli 0.843.0 → 0.844.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +12 -16
- package/dist/{ads-5ZRD7HQW.js → ads-JFCNWMO2.js} +2 -2
- package/dist/chunk-FXN226NY.js +59 -0
- package/dist/chunk-FXN226NY.js.map +1 -0
- package/dist/cli.js +1 -1
- package/dist/{discover-SM3XTPW6.js → discover-ZIAHE6QG.js} +15 -9
- package/dist/discover-ZIAHE6QG.js.map +1 -0
- package/dist/{google-W4OMVHFC.js → google-IOBFFSRM.js} +3 -3
- package/dist/{metrics-GCBM3YDW.js → metrics-UKMUGQBU.js} +19 -9
- package/dist/metrics-UKMUGQBU.js.map +1 -0
- package/package.json +1 -1
- package/dist/chunk-DFETFPM2.js +0 -29
- package/dist/chunk-DFETFPM2.js.map +0 -1
- package/dist/discover-SM3XTPW6.js.map +0 -1
- package/dist/metrics-GCBM3YDW.js.map +0 -1
- /package/dist/{ads-5ZRD7HQW.js.map → ads-JFCNWMO2.js.map} +0 -0
- /package/dist/{google-W4OMVHFC.js.map → google-IOBFFSRM.js.map} +0 -0
package/README.md
CHANGED
|
@@ -904,14 +904,11 @@ baker ads google keywords discover --customer-id 1234567890 --seeds "running sho
|
|
|
904
904
|
{
|
|
905
905
|
"source": "keyword_planner_estimate",
|
|
906
906
|
"keyword": "student services",
|
|
907
|
-
"planner_avg_monthly_searches":
|
|
907
|
+
"planner_avg_monthly_searches": 1000,
|
|
908
908
|
"planner_competition": "LOW",
|
|
909
|
-
"planner_competition_index":
|
|
910
|
-
"
|
|
911
|
-
"
|
|
912
|
-
"planner_monthly_search_volumes": [
|
|
913
|
-
{ "year": "2025", "month": "APRIL", "monthly_searches": "590" }
|
|
914
|
-
]
|
|
909
|
+
"planner_competition_index": 4,
|
|
910
|
+
"planner_low_top_of_page_bid": 0.2,
|
|
911
|
+
"planner_high_top_of_page_bid": 0.62
|
|
915
912
|
}
|
|
916
913
|
],
|
|
917
914
|
"total_results": 10,
|
|
@@ -923,8 +920,8 @@ baker ads google keywords discover --customer-id 1234567890 --seeds "running sho
|
|
|
923
920
|
"planner_avg_monthly_searches": "ESTIMATE: average monthly searches across the whole market",
|
|
924
921
|
"planner_competition": "ESTIMATE: competition level — LOW, MEDIUM, HIGH, UNKNOWN",
|
|
925
922
|
"planner_competition_index": "ESTIMATE: competition index 0-100 (higher = more competitive)",
|
|
926
|
-
"
|
|
927
|
-
"
|
|
923
|
+
"planner_low_top_of_page_bid": "ESTIMATE: low-range top-of-page CPC bid in the account's currency",
|
|
924
|
+
"planner_high_top_of_page_bid": "ESTIMATE: high-range top-of-page CPC bid in the account's currency"
|
|
928
925
|
}
|
|
929
926
|
}
|
|
930
927
|
```
|
|
@@ -942,6 +939,7 @@ baker ads google keywords discover --customer-id 1234567890 --seeds "running sho
|
|
|
942
939
|
| `--cursor` | Pagination cursor from previous response (`next_page_token`) |
|
|
943
940
|
| `--no-cache` | Skip cache (24h TTL) |
|
|
944
941
|
| `--output` | Format: `json` \| `csv` \| `jsonl` \| `md` |
|
|
942
|
+
| `--full` | Add the 12-month breakdown (`planner_monthly_search_volumes`, numbers) to every row |
|
|
945
943
|
|
|
946
944
|
> **Note:** The response includes a `query_context` object naming the location and language used and where each came from (`location_source` / `language_source`: `flag`, `campaigns`, `account` for the account's time zone, or `default`); when a flag was left out, `hints[]` names the market too. A read of the account's targeting that fails fails the command instead of guessing a market.
|
|
947
945
|
|
|
@@ -965,14 +963,11 @@ baker ads google keywords metrics --customer-id 1234567890 --keywords "running s
|
|
|
965
963
|
{
|
|
966
964
|
"source": "keyword_planner_estimate",
|
|
967
965
|
"keyword": "running shoes",
|
|
968
|
-
"planner_avg_monthly_searches":
|
|
966
|
+
"planner_avg_monthly_searches": 1000,
|
|
969
967
|
"planner_competition": "LOW",
|
|
970
|
-
"planner_competition_index":
|
|
971
|
-
"
|
|
972
|
-
"
|
|
973
|
-
"planner_monthly_search_volumes": [
|
|
974
|
-
{ "year": "2025", "month": "APRIL", "monthly_searches": "590" }
|
|
975
|
-
]
|
|
968
|
+
"planner_competition_index": 4,
|
|
969
|
+
"planner_low_top_of_page_bid": 0.2,
|
|
970
|
+
"planner_high_top_of_page_bid": 0.62
|
|
976
971
|
}
|
|
977
972
|
]
|
|
978
973
|
},
|
|
@@ -991,6 +986,7 @@ baker ads google keywords metrics --customer-id 1234567890 --keywords "running s
|
|
|
991
986
|
| `--language` | Language code (`es`, `ca`) or language id (`keywords languages`). Default: that pair's language (every language when those campaigns set none), else the time zone country's main language (English only when neither says) |
|
|
992
987
|
| `--no-cache` | Skip cache (24h TTL) |
|
|
993
988
|
| `--output` | Format: `json` \| `csv` \| `jsonl` \| `md` |
|
|
989
|
+
| `--full` | Add the 12-month breakdown (`planner_monthly_search_volumes`, numbers) to every row |
|
|
994
990
|
|
|
995
991
|
---
|
|
996
992
|
|
|
@@ -33,7 +33,7 @@ Examples:
|
|
|
33
33
|
Full guides: __tooling__/docs/tools/baker/ads-<platform>.md (google|meta|linkedin|x|chatgpt|performance|terms)`
|
|
34
34
|
},
|
|
35
35
|
subCommands: {
|
|
36
|
-
google: () => import("./google-
|
|
36
|
+
google: () => import("./google-IOBFFSRM.js").then((m) => m.googleCommand),
|
|
37
37
|
meta: () => import("./meta-2ZQ3CWLF.js").then((m) => m.metaCommand),
|
|
38
38
|
linkedin: () => import("./linkedin-X6C6YU5N.js").then((m) => m.linkedinCommand),
|
|
39
39
|
x: () => import("./x-BADNICSG.js").then((m) => m.xCommand),
|
|
@@ -45,4 +45,4 @@ Full guides: __tooling__/docs/tools/baker/ads-<platform>.md (google|meta|linkedi
|
|
|
45
45
|
export {
|
|
46
46
|
adsCommand
|
|
47
47
|
};
|
|
48
|
-
//# sourceMappingURL=ads-
|
|
48
|
+
//# sourceMappingURL=ads-JFCNWMO2.js.map
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
// ../api/src/ads-google/keyword-provenance.ts
|
|
2
|
+
var PLANNER_SOURCE = "keyword_planner_estimate";
|
|
3
|
+
var IDENTITY_FIELDS = /* @__PURE__ */ new Set(["keyword"]);
|
|
4
|
+
var COUNT_FIELD = /^(avg_monthly_searches|competition_index)(_\d+)?$/;
|
|
5
|
+
var MICROS_FIELD = /^(low_top_of_page_bid|high_top_of_page_bid)_micros(_\d+)?$/;
|
|
6
|
+
var MONTHLY_FIELD = "monthly_search_volumes";
|
|
7
|
+
function toNumber(value) {
|
|
8
|
+
if (typeof value !== "string" || value.trim() === "") return value;
|
|
9
|
+
const n = Number(value);
|
|
10
|
+
return Number.isFinite(n) ? n : value;
|
|
11
|
+
}
|
|
12
|
+
function fromMicros(value) {
|
|
13
|
+
const n = toNumber(value);
|
|
14
|
+
return typeof n === "number" ? Math.round(n / 1e4) / 100 : n;
|
|
15
|
+
}
|
|
16
|
+
function plannerField(key, value) {
|
|
17
|
+
if (COUNT_FIELD.test(key)) return [key, toNumber(value)];
|
|
18
|
+
const micros = MICROS_FIELD.exec(key);
|
|
19
|
+
if (micros) return [`${micros[1]}${micros[2] ?? ""}`, fromMicros(value)];
|
|
20
|
+
if (key === MONTHLY_FIELD && Array.isArray(value)) {
|
|
21
|
+
return [
|
|
22
|
+
key,
|
|
23
|
+
value.map((month) => ({
|
|
24
|
+
...month,
|
|
25
|
+
year: toNumber(month.year),
|
|
26
|
+
monthly_searches: toNumber(month.monthly_searches)
|
|
27
|
+
}))
|
|
28
|
+
];
|
|
29
|
+
}
|
|
30
|
+
return [key, value];
|
|
31
|
+
}
|
|
32
|
+
function stampPlannerRows(rows, options = {}) {
|
|
33
|
+
return rows.map((row) => {
|
|
34
|
+
const stamped = { source: PLANNER_SOURCE };
|
|
35
|
+
for (const [rawKey, rawValue] of Object.entries(row)) {
|
|
36
|
+
if (rawKey === MONTHLY_FIELD && !options.full) continue;
|
|
37
|
+
const [key, value] = plannerField(rawKey, rawValue);
|
|
38
|
+
stamped[IDENTITY_FIELDS.has(key) || key.startsWith("planner_") ? key : `planner_${key}`] = value;
|
|
39
|
+
}
|
|
40
|
+
return stamped;
|
|
41
|
+
});
|
|
42
|
+
}
|
|
43
|
+
var PLANNER_FIELD_DESCRIPTIONS = {
|
|
44
|
+
source: `Always "${PLANNER_SOURCE}". These rows are Keyword Planner ESTIMATES of total market search volume, NOT this account's data. Never report them as impressions, clicks or any account metric \u2014 read those from a query against the account.`,
|
|
45
|
+
keyword: "The keyword this estimate is for",
|
|
46
|
+
planner_avg_monthly_searches: "ESTIMATE: average monthly searches across the whole market (number), last 12 months",
|
|
47
|
+
planner_competition: "ESTIMATE: competition level \u2014 LOW, MEDIUM, HIGH",
|
|
48
|
+
planner_competition_index: "ESTIMATE: competition index 0-100 (number; higher = more competitive)",
|
|
49
|
+
planner_low_top_of_page_bid: "ESTIMATE: low-range top-of-page CPC bid in the account's currency (`baker ads google currency`), e.g. 0.2",
|
|
50
|
+
planner_high_top_of_page_bid: "ESTIMATE: high-range top-of-page CPC bid in the account's currency (`baker ads google currency`), e.g. 0.62",
|
|
51
|
+
planner_monthly_search_volumes: "ESTIMATE: monthly market search volume breakdown (array of {year, month, monthly_searches}), only with --full"
|
|
52
|
+
};
|
|
53
|
+
|
|
54
|
+
export {
|
|
55
|
+
PLANNER_SOURCE,
|
|
56
|
+
stampPlannerRows,
|
|
57
|
+
PLANNER_FIELD_DESCRIPTIONS
|
|
58
|
+
};
|
|
59
|
+
//# sourceMappingURL=chunk-FXN226NY.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../../api/src/ads-google/keyword-provenance.ts"],"sourcesContent":["/**\n * Keyword Planner numbers are estimates of what the whole market searches. Account numbers are what\n * this advertiser actually got. They are different quantities with similar shapes, they end up in\n * neighbouring CSVs in /tmp, and a session once reported the first as the second — \"we already show\n * on shipbob (88 impressions)\" against an account that had never shown there once.\n *\n * A header banner does not survive `--output csv > file`, a `python3 -c` pass or 150 tool calls of\n * distance. A column name does: the only way to read one of these numbers is to name its source\n * while doing it. Every row also carries a constant `source` column, which survives any transform\n * that copies rows rather than picking fields. Stamped the same way wherever a planner row is read:\n * `baker ads google keywords discover|metrics` and Baker's engine (`agent-engine/found-ads-google`).\n */\nexport const PLANNER_SOURCE = \"keyword_planner_estimate\";\n\n/** The one field that is not an estimate — it is the term itself, so it keeps its plain name. */\nconst IDENTITY_FIELDS = new Set([\"keyword\"]);\n\n/**\n * Google answers every int64 as a JSON string and every bid in micros, and a market comparison\n * suffixes each with its geo id (`avg_monthly_searches_2076`). The agent sorts and divides these, so\n * they leave as numbers, bids in the account's currency units.\n */\nconst COUNT_FIELD = /^(avg_monthly_searches|competition_index)(_\\d+)?$/;\nconst MICROS_FIELD = /^(low_top_of_page_bid|high_top_of_page_bid)_micros(_\\d+)?$/;\nconst MONTHLY_FIELD = \"monthly_search_volumes\";\n\nexport type PlannerRow = Record<string, unknown>;\n\nexport interface PlannerRowOptions {\n /** Keep the 12-month breakdown (`--full`); without it a row is the averages alone. */\n full?: boolean;\n}\n\nfunction toNumber(value: unknown): unknown {\n if (typeof value !== \"string\" || value.trim() === \"\") return value;\n const n = Number(value);\n return Number.isFinite(n) ? n : value;\n}\n\nfunction fromMicros(value: unknown): unknown {\n const n = toNumber(value);\n return typeof n === \"number\" ? Math.round(n / 10_000) / 100 : n;\n}\n\nfunction plannerField(key: string, value: unknown): [string, unknown] {\n if (COUNT_FIELD.test(key)) return [key, toNumber(value)];\n const micros = MICROS_FIELD.exec(key);\n if (micros) return [`${micros[1]}${micros[2] ?? \"\"}`, fromMicros(value)];\n if (key === MONTHLY_FIELD && Array.isArray(value)) {\n return [\n key,\n value.map((month: Record<string, unknown>) => ({\n ...month,\n year: toNumber(month.year),\n monthly_searches: toNumber(month.monthly_searches),\n })),\n ];\n }\n return [key, value];\n}\n\nexport function stampPlannerRows(rows: readonly PlannerRow[], options: PlannerRowOptions = {}): PlannerRow[] {\n return rows.map((row) => {\n const stamped: PlannerRow = { source: PLANNER_SOURCE };\n for (const [rawKey, rawValue] of Object.entries(row)) {\n if (rawKey === MONTHLY_FIELD && !options.full) continue;\n const [key, value] = plannerField(rawKey, rawValue);\n stamped[IDENTITY_FIELDS.has(key) || key.startsWith(\"planner_\") ? key : `planner_${key}`] = value;\n }\n return stamped;\n });\n}\n\n/** Field docs for the stamped shape, stated so the estimate can never be mistaken for account data. */\nexport const PLANNER_FIELD_DESCRIPTIONS: Record<string, string> = {\n source: `Always \"${PLANNER_SOURCE}\". These rows are Keyword Planner ESTIMATES of total market search volume, NOT this account's data. Never report them as impressions, clicks or any account metric — read those from a query against the account.`,\n keyword: \"The keyword this estimate is for\",\n planner_avg_monthly_searches: \"ESTIMATE: average monthly searches across the whole market (number), last 12 months\",\n planner_competition: \"ESTIMATE: competition level — LOW, MEDIUM, HIGH\",\n planner_competition_index: \"ESTIMATE: competition index 0-100 (number; higher = more competitive)\",\n planner_low_top_of_page_bid:\n \"ESTIMATE: low-range top-of-page CPC bid in the account's currency (`baker ads google currency`), e.g. 0.2\",\n planner_high_top_of_page_bid:\n \"ESTIMATE: high-range top-of-page CPC bid in the account's currency (`baker ads google currency`), e.g. 0.62\",\n planner_monthly_search_volumes:\n \"ESTIMATE: monthly market search volume breakdown (array of {year, month, monthly_searches}), only with --full\",\n};\n"],"mappings":";AAYO,IAAM,iBAAiB;AAG9B,IAAM,kBAAkB,oBAAI,IAAI,CAAC,SAAS,CAAC;AAO3C,IAAM,cAAc;AACpB,IAAM,eAAe;AACrB,IAAM,gBAAgB;AAStB,SAAS,SAAS,OAAyB;AACzC,MAAI,OAAO,UAAU,YAAY,MAAM,KAAK,MAAM,GAAI,QAAO;AAC7D,QAAM,IAAI,OAAO,KAAK;AACtB,SAAO,OAAO,SAAS,CAAC,IAAI,IAAI;AAClC;AAEA,SAAS,WAAW,OAAyB;AAC3C,QAAM,IAAI,SAAS,KAAK;AACxB,SAAO,OAAO,MAAM,WAAW,KAAK,MAAM,IAAI,GAAM,IAAI,MAAM;AAChE;AAEA,SAAS,aAAa,KAAa,OAAmC;AACpE,MAAI,YAAY,KAAK,GAAG,EAAG,QAAO,CAAC,KAAK,SAAS,KAAK,CAAC;AACvD,QAAM,SAAS,aAAa,KAAK,GAAG;AACpC,MAAI,OAAQ,QAAO,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,EAAE,IAAI,WAAW,KAAK,CAAC;AACvE,MAAI,QAAQ,iBAAiB,MAAM,QAAQ,KAAK,GAAG;AACjD,WAAO;AAAA,MACL;AAAA,MACA,MAAM,IAAI,CAAC,WAAoC;AAAA,QAC7C,GAAG;AAAA,QACH,MAAM,SAAS,MAAM,IAAI;AAAA,QACzB,kBAAkB,SAAS,MAAM,gBAAgB;AAAA,MACnD,EAAE;AAAA,IACJ;AAAA,EACF;AACA,SAAO,CAAC,KAAK,KAAK;AACpB;AAEO,SAAS,iBAAiB,MAA6B,UAA6B,CAAC,GAAiB;AAC3G,SAAO,KAAK,IAAI,CAAC,QAAQ;AACvB,UAAM,UAAsB,EAAE,QAAQ,eAAe;AACrD,eAAW,CAAC,QAAQ,QAAQ,KAAK,OAAO,QAAQ,GAAG,GAAG;AACpD,UAAI,WAAW,iBAAiB,CAAC,QAAQ,KAAM;AAC/C,YAAM,CAAC,KAAK,KAAK,IAAI,aAAa,QAAQ,QAAQ;AAClD,cAAQ,gBAAgB,IAAI,GAAG,KAAK,IAAI,WAAW,UAAU,IAAI,MAAM,WAAW,GAAG,EAAE,IAAI;AAAA,IAC7F;AACA,WAAO;AAAA,EACT,CAAC;AACH;AAGO,IAAM,6BAAqD;AAAA,EAChE,QAAQ,WAAW,cAAc;AAAA,EACjC,SAAS;AAAA,EACT,8BAA8B;AAAA,EAC9B,qBAAqB;AAAA,EACrB,2BAA2B;AAAA,EAC3B,6BACE;AAAA,EACF,8BACE;AAAA,EACF,gCACE;AACJ;","names":[]}
|
package/dist/cli.js
CHANGED
|
@@ -694,7 +694,7 @@ Introspection: Run 'baker schema <command>' to inspect argument schemas.`
|
|
|
694
694
|
capabilities: () => import("./capabilities-KXT4LXO5.js").then((m) => m.capabilitiesCommand),
|
|
695
695
|
actions: () => import("./actions-AHJDR7X4.js").then((m) => m.actionsCommand),
|
|
696
696
|
"scheduled-agents": () => import("./scheduled-agents-CSSWJGDM.js").then((m) => m.scheduledAgentsCommand),
|
|
697
|
-
ads: () => import("./ads-
|
|
697
|
+
ads: () => import("./ads-JFCNWMO2.js").then((m) => m.adsCommand),
|
|
698
698
|
brand: () => import("./brand-SDDWXOOT.js").then((m) => m.brandCommand),
|
|
699
699
|
analytics: () => import("./analytics-VVHLX2WF.js").then((m) => m.analyticsCommand),
|
|
700
700
|
experiment: () => import("./experiment-WEWASTVO.js").then((m) => m.experimentCommand),
|
|
@@ -2,7 +2,7 @@ import {
|
|
|
2
2
|
PLANNER_FIELD_DESCRIPTIONS,
|
|
3
3
|
PLANNER_SOURCE,
|
|
4
4
|
stampPlannerRows
|
|
5
|
-
} from "./chunk-
|
|
5
|
+
} from "./chunk-FXN226NY.js";
|
|
6
6
|
import {
|
|
7
7
|
plannerMarket
|
|
8
8
|
} from "./chunk-33PPLXL7.js";
|
|
@@ -36,7 +36,7 @@ registerSchema({
|
|
|
36
36
|
command: "ads.google.keywords.discover",
|
|
37
37
|
routes: ["POST /api/ads/google/keywords/discover"],
|
|
38
38
|
effect: "read_live",
|
|
39
|
-
description: "Discover keyword ideas from seed keywords or URLs. Returns { source: \"keyword_planner_estimate\", keywords, total_results, next_page_token? }. These are Keyword Planner estimates of total market search volume, not this account's data: every row carries a source column and every metric is prefixed planner_ (planner_avg_monthly_searches, planner_competition, ...). Never report a planner_ number as impressions, clicks or any account metric \u2014 read those with `baker ads google query` against the account. With no --location/--language the read follows the location and language the account's campaigns target together, else the country of the account's time zone in its main language (the United States in English only when the account says neither); `query_context` names the market and where it came from.",
|
|
39
|
+
description: "Discover keyword ideas from seed keywords or URLs. Returns { source: \"keyword_planner_estimate\", keywords, total_results, next_page_token? }. These are Keyword Planner estimates of total market search volume, not this account's data: every row carries a source column and every metric is prefixed planner_ (planner_avg_monthly_searches, planner_competition, ...). Volumes and competition_index are numbers, bids are in the account's currency (planner_low_top_of_page_bid, planner_high_top_of_page_bid), and the 12-month breakdown (planner_monthly_search_volumes) comes only with --full. Never report a planner_ number as impressions, clicks or any account metric \u2014 read those with `baker ads google query` against the account. With no --location/--language the read follows the location and language the account's campaigns target together, else the country of the account's time zone in its main language (the United States in English only when the account says neither); `query_context` names the market and where it came from.",
|
|
40
40
|
args: {
|
|
41
41
|
"customer-id": {
|
|
42
42
|
type: "string",
|
|
@@ -62,12 +62,17 @@ registerSchema({
|
|
|
62
62
|
required: false
|
|
63
63
|
},
|
|
64
64
|
output: { type: "string", description: "Format: json|csv|jsonl|md", required: false, default: "json" },
|
|
65
|
-
"no-cache": { type: "boolean", description: "Skip cache", required: false }
|
|
65
|
+
"no-cache": { type: "boolean", description: "Skip cache", required: false },
|
|
66
|
+
full: {
|
|
67
|
+
type: "boolean",
|
|
68
|
+
description: "Add the 12-month breakdown (planner_monthly_search_volumes) to every row; without it a row is the averages alone",
|
|
69
|
+
required: false
|
|
70
|
+
}
|
|
66
71
|
}
|
|
67
72
|
});
|
|
68
|
-
function stampDiscoverResponse(data) {
|
|
73
|
+
function stampDiscoverResponse(data, options = {}) {
|
|
69
74
|
const { market: _market, ...rest } = data;
|
|
70
|
-
return { ...rest, source: PLANNER_SOURCE, keywords: stampPlannerRows(data.keywords ?? []) };
|
|
75
|
+
return { ...rest, source: PLANNER_SOURCE, keywords: stampPlannerRows(data.keywords ?? [], options) };
|
|
71
76
|
}
|
|
72
77
|
function buildDiscoverBody(customerId, args) {
|
|
73
78
|
const body = {
|
|
@@ -133,7 +138,8 @@ Examples:
|
|
|
133
138
|
limit: { type: "string", description: "Max results (default 20)", required: false },
|
|
134
139
|
cursor: { type: "string", description: "Pagination cursor from previous response", required: false },
|
|
135
140
|
"no-cache": { type: "boolean", description: "Skip cache", required: false },
|
|
136
|
-
output: { type: "string", description: "Format: json|csv|jsonl|md", required: false, default: "json" }
|
|
141
|
+
output: { type: "string", description: "Format: json|csv|jsonl|md", required: false, default: "json" },
|
|
142
|
+
full: { type: "boolean", description: "Add the 12-month breakdown to every row", required: false }
|
|
137
143
|
},
|
|
138
144
|
run: async ({ args }) => {
|
|
139
145
|
const customerId = await resolveCustomerId(args);
|
|
@@ -154,7 +160,7 @@ Examples:
|
|
|
154
160
|
writeAdsJson({
|
|
155
161
|
ok: true,
|
|
156
162
|
...plannerMarket(cached.data),
|
|
157
|
-
data: stampDiscoverResponse(cached.data),
|
|
163
|
+
data: stampDiscoverResponse(cached.data, { full: Boolean(args.full) }),
|
|
158
164
|
cached: true
|
|
159
165
|
});
|
|
160
166
|
return;
|
|
@@ -166,7 +172,7 @@ Examples:
|
|
|
166
172
|
cacheSet("keywords", cacheKey, data, 24 * 60 * 60 * 1e3);
|
|
167
173
|
}
|
|
168
174
|
const market = plannerMarket(data);
|
|
169
|
-
const stamped = stampDiscoverResponse(data);
|
|
175
|
+
const stamped = stampDiscoverResponse(data, { full: Boolean(args.full) });
|
|
170
176
|
const format = args.output || "json";
|
|
171
177
|
if (format !== "json") {
|
|
172
178
|
writeAdsOutput(stamped.keywords, format);
|
|
@@ -182,4 +188,4 @@ export {
|
|
|
182
188
|
discoverCommand,
|
|
183
189
|
stampDiscoverResponse
|
|
184
190
|
};
|
|
185
|
-
//# sourceMappingURL=discover-
|
|
191
|
+
//# sourceMappingURL=discover-ZIAHE6QG.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/commands/ads/google/keywords/discover.ts"],"sourcesContent":["import type { GoogleKeywordMarket } from \"@baker/api/ads-google/keyword-planning\";\nimport {\n PLANNER_FIELD_DESCRIPTIONS,\n PLANNER_SOURCE,\n type PlannerRow,\n type PlannerRowOptions,\n stampPlannerRows,\n} from \"@baker/api/ads-google/keyword-provenance\";\nimport { defineCommand } from \"citty\";\nimport { ApiError, apiPost } from \"../../../../client.ts\";\nimport { handleConnectionError, isNotConnectedError } from \"../../../../error-handler.ts\";\nimport { plannerMarket } from \"../../../../geo-context.ts\";\nimport { registerSchema } from \"../../../../schemas.ts\";\nimport { buildQueryCacheKey, cacheGet, cacheSet, getManagerIdForCustomer } from \"../../cache.ts\";\nimport { resolveCustomerId, writeAdsJson, writeAdsOutput } from \"../../output.ts\";\nimport type { AdsErrorEnvelope } from \"../../types.ts\";\n\nregisterSchema({\n command: \"ads.google.keywords.discover\",\n routes: [\"POST /api/ads/google/keywords/discover\"],\n effect: \"read_live\",\n description:\n \"Discover keyword ideas from seed keywords or URLs. Returns { source: \\\"keyword_planner_estimate\\\", keywords, total_results, next_page_token? }. These are Keyword Planner estimates of total market search volume, not this account's data: every row carries a source column and every metric is prefixed planner_ (planner_avg_monthly_searches, planner_competition, ...). Volumes and competition_index are numbers, bids are in the account's currency (planner_low_top_of_page_bid, planner_high_top_of_page_bid), and the 12-month breakdown (planner_monthly_search_volumes) comes only with --full. Never report a planner_ number as impressions, clicks or any account metric — read those with `baker ads google query` against the account. With no --location/--language the read follows the location and language the account's campaigns target together, else the country of the account's time zone in its main language (the United States in English only when the account says neither); `query_context` names the market and where it came from.\",\n args: {\n \"customer-id\": {\n type: \"string\",\n description:\n \"Google Ads customer ID (10 digits; dashes are fine). Falls back to BAKER_GOOGLE_ADS_CUSTOMER_ID env var.\",\n required: false,\n },\n seeds: { type: \"string\", description: \"Comma-separated seed keywords (max 10)\", required: false },\n url: { type: \"string\", description: \"URL to extract keyword ideas from\", required: false },\n location: {\n type: \"string\",\n description:\n \"Country code (es, gb) or geo target id (2724; cities and regions too) — ids from `baker ads google keywords locations`. Omitted: the location of the location/language pair most of the account's campaigns target, else the country of the account's time zone\",\n required: false,\n },\n language: {\n type: \"string\",\n description:\n \"Language code (es, ca) or language id (1003) — ids from `baker ads google keywords languages`. Omitted: the language of that pair (every language when those campaigns set none), else the time zone country's main language\",\n required: false,\n },\n limit: { type: \"string\", description: \"Max keyword ideas (default: 20, max: 100)\", required: false, default: 20 },\n cursor: {\n type: \"string\",\n description: \"Pagination cursor from previous response (next_page_token)\",\n required: false,\n },\n output: { type: \"string\", description: \"Format: json|csv|jsonl|md\", required: false, default: \"json\" },\n \"no-cache\": { type: \"boolean\", description: \"Skip cache\", required: false },\n full: {\n type: \"boolean\",\n description:\n \"Add the 12-month breakdown (planner_monthly_search_volumes) to every row; without it a row is the averages alone\",\n required: false,\n },\n },\n});\n\ntype KeywordIdea = {\n keyword: string;\n avg_monthly_searches: string;\n competition: string;\n competition_index: string;\n low_top_of_page_bid_micros: string | number;\n high_top_of_page_bid_micros: string | number;\n monthly_search_volumes: Array<{ year: string; month: string; monthly_searches: string }>;\n};\n\ntype DiscoverResponse = {\n market?: GoogleKeywordMarket;\n keywords: KeywordIdea[];\n total_results: number;\n next_page_token?: string;\n};\n\n/**\n * Every idea leaves this command carrying where it came from: a `source` column on the row and a\n * `planner_` prefix on each estimate. Keyword Planner volumes have been reported as account\n * impressions before; a name is the only label that survives a CSV in /tmp and a `python3` pass.\n */\nexport function stampDiscoverResponse(\n data: {\n keywords?: readonly PlannerRow[];\n [key: string]: unknown;\n },\n options: PlannerRowOptions = {},\n): Record<string, unknown> & { keywords: PlannerRow[] } {\n const { market: _market, ...rest } = data;\n return { ...rest, source: PLANNER_SOURCE, keywords: stampPlannerRows(data.keywords ?? [], options) };\n}\n\nfunction buildDiscoverBody(customerId: string, args: Record<string, unknown>): Record<string, unknown> {\n const body: Record<string, unknown> = {\n customerId,\n pageSize: args.limit ? Number(args.limit) : 20,\n };\n const managerId = getManagerIdForCustomer(customerId);\n if (managerId) body.managerId = managerId;\n\n const seeds = args.seeds\n ? (args.seeds as string)\n .split(\",\")\n .map((s) => s.trim())\n .filter(Boolean)\n : undefined;\n if (seeds) body.seeds = seeds;\n if (args.url) body.url = args.url;\n if (args.location) body.locationIds = [args.location as string];\n if (args.language) body.languageId = args.language;\n if (args.cursor) body.pageToken = args.cursor;\n return body;\n}\n\nfunction handleKeywordError(err: unknown): never {\n if (err instanceof ApiError) {\n if (isNotConnectedError(err.code, err.message)) {\n handleConnectionError(\"google_ads\", err.message);\n }\n const envelope: AdsErrorEnvelope = {\n ok: false,\n error: {\n code: err.code,\n message: err.message,\n fix: { action: \"reject\", explanation: err.message },\n retryable: err.code === \"RATE_LIMITED\",\n },\n };\n writeAdsJson(envelope);\n process.exit(1);\n }\n writeAdsJson({ ok: false, error: { code: \"NETWORK_ERROR\", message: \"Unexpected error\" } });\n process.exit(1);\n}\n\nexport const discoverCommand = defineCommand({\n meta: {\n name: \"discover\",\n description: `Discover new keyword ideas from seed keywords or competitor URLs.\n\nReturns Keyword Planner ESTIMATES of market search volume, not this account's numbers. Every row carries source=keyword_planner_estimate and planner_-prefixed metrics; keep those names when you quote a figure, and never present one as an impression or click count.\n\nExamples:\n baker ads google keywords discover --customer-id 1234567890 --seeds \"running shoes,athletic footwear\"\n baker ads google keywords discover --customer-id 1234567890 --url \"https://competitor.com\"\n baker ads google keywords discover --customer-id 1234567890 --seeds \"seo tools\" --location 2826 --limit 50`,\n },\n args: {\n \"customer-id\": { type: \"string\", description: \"Google Ads customer ID\", required: false },\n seeds: { type: \"string\", description: \"Comma-separated seed keywords\", required: false },\n url: { type: \"string\", description: \"URL to extract ideas from\", required: false },\n location: {\n type: \"string\",\n description:\n \"Country code (es) or geo target id — see `baker ads google keywords locations`. Default: what the account's campaigns target, else its time zone's country\",\n required: false,\n },\n language: {\n type: \"string\",\n description:\n \"Language code (es) or language id — see `baker ads google keywords languages`. Default: what the account's campaigns target, else its time zone's country\",\n required: false,\n },\n limit: { type: \"string\", description: \"Max results (default 20)\", required: false },\n cursor: { type: \"string\", description: \"Pagination cursor from previous response\", required: false },\n \"no-cache\": { type: \"boolean\", description: \"Skip cache\", required: false },\n output: { type: \"string\", description: \"Format: json|csv|jsonl|md\", required: false, default: \"json\" },\n full: { type: \"boolean\", description: \"Add the 12-month breakdown to every row\", required: false },\n },\n run: async ({ args }) => {\n const customerId = await resolveCustomerId(args);\n\n if (!args.seeds && !args.url) {\n writeAdsJson({\n ok: false,\n error: { code: \"VALIDATION_ERROR\", message: \"Provide --seeds or --url (at least one required)\" },\n });\n process.exit(1);\n }\n\n const body = buildDiscoverBody(customerId, args);\n const useCache = !args[\"no-cache\"] && !args.cursor;\n if (!useCache) body.skipCache = true;\n const cacheKey = buildQueryCacheKey(customerId, JSON.stringify(body));\n\n if (useCache) {\n const cached = cacheGet<DiscoverResponse>(\"keywords\", cacheKey);\n // An answer cached before reads named their market is a United States / English guess: read it again.\n if (cached?.data.market) {\n writeAdsJson({\n ok: true,\n ...plannerMarket(cached.data),\n data: stampDiscoverResponse(cached.data, { full: Boolean(args.full) }),\n cached: true,\n });\n return;\n }\n }\n\n try {\n const data = await apiPost<DiscoverResponse>(\"/api/ads/google/keywords/discover\", body);\n if (useCache) {\n cacheSet(\"keywords\", cacheKey, data, 24 * 60 * 60 * 1000);\n }\n\n const market = plannerMarket(data);\n const stamped = stampDiscoverResponse(data, { full: Boolean(args.full) });\n const format = (args.output as string) || \"json\";\n if (format !== \"json\") {\n writeAdsOutput(stamped.keywords, format);\n return;\n }\n\n writeAdsJson({ ok: true, data: stamped, fields: PLANNER_FIELD_DESCRIPTIONS, ...market });\n } catch (err) {\n handleKeywordError(err);\n }\n },\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAQA,SAAS,qBAAqB;AAS9B,eAAe;AAAA,EACb,SAAS;AAAA,EACT,QAAQ,CAAC,wCAAwC;AAAA,EACjD,QAAQ;AAAA,EACR,aACE;AAAA,EACF,MAAM;AAAA,IACJ,eAAe;AAAA,MACb,MAAM;AAAA,MACN,aACE;AAAA,MACF,UAAU;AAAA,IACZ;AAAA,IACA,OAAO,EAAE,MAAM,UAAU,aAAa,0CAA0C,UAAU,MAAM;AAAA,IAChG,KAAK,EAAE,MAAM,UAAU,aAAa,qCAAqC,UAAU,MAAM;AAAA,IACzF,UAAU;AAAA,MACR,MAAM;AAAA,MACN,aACE;AAAA,MACF,UAAU;AAAA,IACZ;AAAA,IACA,UAAU;AAAA,MACR,MAAM;AAAA,MACN,aACE;AAAA,MACF,UAAU;AAAA,IACZ;AAAA,IACA,OAAO,EAAE,MAAM,UAAU,aAAa,6CAA6C,UAAU,OAAO,SAAS,GAAG;AAAA,IAChH,QAAQ;AAAA,MACN,MAAM;AAAA,MACN,aAAa;AAAA,MACb,UAAU;AAAA,IACZ;AAAA,IACA,QAAQ,EAAE,MAAM,UAAU,aAAa,6BAA6B,UAAU,OAAO,SAAS,OAAO;AAAA,IACrG,YAAY,EAAE,MAAM,WAAW,aAAa,cAAc,UAAU,MAAM;AAAA,IAC1E,MAAM;AAAA,MACJ,MAAM;AAAA,MACN,aACE;AAAA,MACF,UAAU;AAAA,IACZ;AAAA,EACF;AACF,CAAC;AAwBM,SAAS,sBACd,MAIA,UAA6B,CAAC,GACwB;AACtD,QAAM,EAAE,QAAQ,SAAS,GAAG,KAAK,IAAI;AACrC,SAAO,EAAE,GAAG,MAAM,QAAQ,gBAAgB,UAAU,iBAAiB,KAAK,YAAY,CAAC,GAAG,OAAO,EAAE;AACrG;AAEA,SAAS,kBAAkB,YAAoB,MAAwD;AACrG,QAAM,OAAgC;AAAA,IACpC;AAAA,IACA,UAAU,KAAK,QAAQ,OAAO,KAAK,KAAK,IAAI;AAAA,EAC9C;AACA,QAAM,YAAY,wBAAwB,UAAU;AACpD,MAAI,UAAW,MAAK,YAAY;AAEhC,QAAM,QAAQ,KAAK,QACd,KAAK,MACH,MAAM,GAAG,EACT,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,EACnB,OAAO,OAAO,IACjB;AACJ,MAAI,MAAO,MAAK,QAAQ;AACxB,MAAI,KAAK,IAAK,MAAK,MAAM,KAAK;AAC9B,MAAI,KAAK,SAAU,MAAK,cAAc,CAAC,KAAK,QAAkB;AAC9D,MAAI,KAAK,SAAU,MAAK,aAAa,KAAK;AAC1C,MAAI,KAAK,OAAQ,MAAK,YAAY,KAAK;AACvC,SAAO;AACT;AAEA,SAAS,mBAAmB,KAAqB;AAC/C,MAAI,eAAe,UAAU;AAC3B,QAAI,oBAAoB,IAAI,MAAM,IAAI,OAAO,GAAG;AAC9C,4BAAsB,cAAc,IAAI,OAAO;AAAA,IACjD;AACA,UAAM,WAA6B;AAAA,MACjC,IAAI;AAAA,MACJ,OAAO;AAAA,QACL,MAAM,IAAI;AAAA,QACV,SAAS,IAAI;AAAA,QACb,KAAK,EAAE,QAAQ,UAAU,aAAa,IAAI,QAAQ;AAAA,QAClD,WAAW,IAAI,SAAS;AAAA,MAC1B;AAAA,IACF;AACA,iBAAa,QAAQ;AACrB,YAAQ,KAAK,CAAC;AAAA,EAChB;AACA,eAAa,EAAE,IAAI,OAAO,OAAO,EAAE,MAAM,iBAAiB,SAAS,mBAAmB,EAAE,CAAC;AACzF,UAAQ,KAAK,CAAC;AAChB;AAEO,IAAM,kBAAkB,cAAc;AAAA,EAC3C,MAAM;AAAA,IACJ,MAAM;AAAA,IACN,aAAa;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQf;AAAA,EACA,MAAM;AAAA,IACJ,eAAe,EAAE,MAAM,UAAU,aAAa,0BAA0B,UAAU,MAAM;AAAA,IACxF,OAAO,EAAE,MAAM,UAAU,aAAa,iCAAiC,UAAU,MAAM;AAAA,IACvF,KAAK,EAAE,MAAM,UAAU,aAAa,6BAA6B,UAAU,MAAM;AAAA,IACjF,UAAU;AAAA,MACR,MAAM;AAAA,MACN,aACE;AAAA,MACF,UAAU;AAAA,IACZ;AAAA,IACA,UAAU;AAAA,MACR,MAAM;AAAA,MACN,aACE;AAAA,MACF,UAAU;AAAA,IACZ;AAAA,IACA,OAAO,EAAE,MAAM,UAAU,aAAa,4BAA4B,UAAU,MAAM;AAAA,IAClF,QAAQ,EAAE,MAAM,UAAU,aAAa,4CAA4C,UAAU,MAAM;AAAA,IACnG,YAAY,EAAE,MAAM,WAAW,aAAa,cAAc,UAAU,MAAM;AAAA,IAC1E,QAAQ,EAAE,MAAM,UAAU,aAAa,6BAA6B,UAAU,OAAO,SAAS,OAAO;AAAA,IACrG,MAAM,EAAE,MAAM,WAAW,aAAa,2CAA2C,UAAU,MAAM;AAAA,EACnG;AAAA,EACA,KAAK,OAAO,EAAE,KAAK,MAAM;AACvB,UAAM,aAAa,MAAM,kBAAkB,IAAI;AAE/C,QAAI,CAAC,KAAK,SAAS,CAAC,KAAK,KAAK;AAC5B,mBAAa;AAAA,QACX,IAAI;AAAA,QACJ,OAAO,EAAE,MAAM,oBAAoB,SAAS,mDAAmD;AAAA,MACjG,CAAC;AACD,cAAQ,KAAK,CAAC;AAAA,IAChB;AAEA,UAAM,OAAO,kBAAkB,YAAY,IAAI;AAC/C,UAAM,WAAW,CAAC,KAAK,UAAU,KAAK,CAAC,KAAK;AAC5C,QAAI,CAAC,SAAU,MAAK,YAAY;AAChC,UAAM,WAAW,mBAAmB,YAAY,KAAK,UAAU,IAAI,CAAC;AAEpE,QAAI,UAAU;AACZ,YAAM,SAAS,SAA2B,YAAY,QAAQ;AAE9D,UAAI,QAAQ,KAAK,QAAQ;AACvB,qBAAa;AAAA,UACX,IAAI;AAAA,UACJ,GAAG,cAAc,OAAO,IAAI;AAAA,UAC5B,MAAM,sBAAsB,OAAO,MAAM,EAAE,MAAM,QAAQ,KAAK,IAAI,EAAE,CAAC;AAAA,UACrE,QAAQ;AAAA,QACV,CAAC;AACD;AAAA,MACF;AAAA,IACF;AAEA,QAAI;AACF,YAAM,OAAO,MAAM,QAA0B,qCAAqC,IAAI;AACtF,UAAI,UAAU;AACZ,iBAAS,YAAY,UAAU,MAAM,KAAK,KAAK,KAAK,GAAI;AAAA,MAC1D;AAEA,YAAM,SAAS,cAAc,IAAI;AACjC,YAAM,UAAU,sBAAsB,MAAM,EAAE,MAAM,QAAQ,KAAK,IAAI,EAAE,CAAC;AACxE,YAAM,SAAU,KAAK,UAAqB;AAC1C,UAAI,WAAW,QAAQ;AACrB,uBAAe,QAAQ,UAAU,MAAM;AACvC;AAAA,MACF;AAEA,mBAAa,EAAE,IAAI,MAAM,MAAM,SAAS,QAAQ,4BAA4B,GAAG,OAAO,CAAC;AAAA,IACzF,SAAS,KAAK;AACZ,yBAAmB,GAAG;AAAA,IACxB;AAAA,EACF;AACF,CAAC;","names":[]}
|
|
@@ -107,8 +107,8 @@ Examples:
|
|
|
107
107
|
baker ads google keywords languages`
|
|
108
108
|
},
|
|
109
109
|
subCommands: {
|
|
110
|
-
discover: () => import("./discover-
|
|
111
|
-
metrics: () => import("./metrics-
|
|
110
|
+
discover: () => import("./discover-ZIAHE6QG.js").then((m) => m.discoverCommand),
|
|
111
|
+
metrics: () => import("./metrics-UKMUGQBU.js").then((m) => m.metricsCommand),
|
|
112
112
|
forecast: () => import("./forecast-HXPATM6B.js").then((m) => m.forecastCommand),
|
|
113
113
|
themes: () => import("./themes-VOLV4Z6M.js").then((m) => m.themesCommand),
|
|
114
114
|
locations: () => import("./locations-VQRCHGHB.js").then((m) => m.locationsCommand),
|
|
@@ -3747,4 +3747,4 @@ Full guide: __tooling__/docs/tools/baker/ads-google.md`
|
|
|
3747
3747
|
export {
|
|
3748
3748
|
googleCommand
|
|
3749
3749
|
};
|
|
3750
|
-
//# sourceMappingURL=google-
|
|
3750
|
+
//# sourceMappingURL=google-IOBFFSRM.js.map
|
|
@@ -2,7 +2,7 @@ import {
|
|
|
2
2
|
PLANNER_FIELD_DESCRIPTIONS,
|
|
3
3
|
PLANNER_SOURCE,
|
|
4
4
|
stampPlannerRows
|
|
5
|
-
} from "./chunk-
|
|
5
|
+
} from "./chunk-FXN226NY.js";
|
|
6
6
|
import {
|
|
7
7
|
plannerMarket
|
|
8
8
|
} from "./chunk-33PPLXL7.js";
|
|
@@ -38,7 +38,7 @@ registerSchema({
|
|
|
38
38
|
command: "ads.google.keywords.metrics",
|
|
39
39
|
routes: ["POST /api/ads/google/keywords/metrics"],
|
|
40
40
|
effect: "read_live",
|
|
41
|
-
description: "Get historical market metrics for specific keywords. Returns { source: \"keyword_planner_estimate\", historical_metrics: [...] }. These are Keyword Planner estimates of total market search volume, not this account's data: every row carries a source column and every metric is prefixed planner_ (planner_avg_monthly_searches, planner_competition, ...). Never report a planner_ number as impressions, clicks or any account metric \u2014 read those with `baker ads google query` against the account. With no --location/--language the read follows the location and language the account's campaigns target together, else the country of the account's time zone in its main language (the United States in English only when the account says neither); `query_context` names the market and where it came from.",
|
|
41
|
+
description: "Get historical market metrics for specific keywords. Returns { source: \"keyword_planner_estimate\", historical_metrics: [...] }. These are Keyword Planner estimates of total market search volume, not this account's data: every row carries a source column and every metric is prefixed planner_ (planner_avg_monthly_searches, planner_competition, ...). Volumes and competition_index are numbers, bids are in the account's currency (planner_low_top_of_page_bid, planner_high_top_of_page_bid), and the 12-month breakdown (planner_monthly_search_volumes) comes only with --full. Never report a planner_ number as impressions, clicks or any account metric \u2014 read those with `baker ads google query` against the account. With no --location/--language the read follows the location and language the account's campaigns target together, else the country of the account's time zone in its main language (the United States in English only when the account says neither); `query_context` names the market and where it came from.",
|
|
42
42
|
args: {
|
|
43
43
|
"customer-id": {
|
|
44
44
|
type: "string",
|
|
@@ -57,12 +57,21 @@ registerSchema({
|
|
|
57
57
|
required: false
|
|
58
58
|
},
|
|
59
59
|
output: { type: "string", description: "Format: json|csv|jsonl|md", required: false, default: "json" },
|
|
60
|
-
"no-cache": { type: "boolean", description: "Skip cache", required: false }
|
|
60
|
+
"no-cache": { type: "boolean", description: "Skip cache", required: false },
|
|
61
|
+
full: {
|
|
62
|
+
type: "boolean",
|
|
63
|
+
description: "Add the 12-month breakdown (planner_monthly_search_volumes) to every row; without it a row is the averages alone",
|
|
64
|
+
required: false
|
|
65
|
+
}
|
|
61
66
|
}
|
|
62
67
|
});
|
|
63
|
-
function stampMetricsResponse(data) {
|
|
68
|
+
function stampMetricsResponse(data, options = {}) {
|
|
64
69
|
const { market: _market, ...rest } = data;
|
|
65
|
-
return {
|
|
70
|
+
return {
|
|
71
|
+
...rest,
|
|
72
|
+
source: PLANNER_SOURCE,
|
|
73
|
+
historical_metrics: stampPlannerRows(data.historical_metrics ?? [], options)
|
|
74
|
+
};
|
|
66
75
|
}
|
|
67
76
|
function locationFields(flag) {
|
|
68
77
|
const locations = (flag ?? "").split(",").map((l) => l.trim()).filter(Boolean);
|
|
@@ -125,7 +134,8 @@ Examples:
|
|
|
125
134
|
required: false
|
|
126
135
|
},
|
|
127
136
|
"no-cache": { type: "boolean", description: "Skip cache", required: false },
|
|
128
|
-
output: { type: "string", description: "Format: json|csv|jsonl|md", required: false, default: "json" }
|
|
137
|
+
output: { type: "string", description: "Format: json|csv|jsonl|md", required: false, default: "json" },
|
|
138
|
+
full: { type: "boolean", description: "Add the 12-month breakdown to every row", required: false }
|
|
129
139
|
},
|
|
130
140
|
run: async ({ args }) => {
|
|
131
141
|
const customerId = await resolveCustomerId(args);
|
|
@@ -152,7 +162,7 @@ Examples:
|
|
|
152
162
|
writeAdsJson({
|
|
153
163
|
ok: true,
|
|
154
164
|
...plannerMarket(cached.data),
|
|
155
|
-
data: stampMetricsResponse(cached.data),
|
|
165
|
+
data: stampMetricsResponse(cached.data, { full: Boolean(args.full) }),
|
|
156
166
|
cached: true
|
|
157
167
|
});
|
|
158
168
|
return;
|
|
@@ -164,7 +174,7 @@ Examples:
|
|
|
164
174
|
cacheSet("keywords", cacheKey, data, 24 * 60 * 60 * 1e3);
|
|
165
175
|
}
|
|
166
176
|
const market = plannerMarket(data);
|
|
167
|
-
const stamped = stampMetricsResponse(data);
|
|
177
|
+
const stamped = stampMetricsResponse(data, { full: Boolean(args.full) });
|
|
168
178
|
const format = args.output || "json";
|
|
169
179
|
if (format !== "json") {
|
|
170
180
|
writeAdsOutput(stamped.historical_metrics, format);
|
|
@@ -180,4 +190,4 @@ export {
|
|
|
180
190
|
metricsCommand,
|
|
181
191
|
stampMetricsResponse
|
|
182
192
|
};
|
|
183
|
-
//# sourceMappingURL=metrics-
|
|
193
|
+
//# sourceMappingURL=metrics-UKMUGQBU.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/commands/ads/google/keywords/metrics.ts"],"sourcesContent":["import { type GoogleKeywordMarket, MAX_COMPARED_LOCATIONS } from \"@baker/api/ads-google/keyword-planning\";\nimport {\n PLANNER_FIELD_DESCRIPTIONS,\n PLANNER_SOURCE,\n type PlannerRow,\n type PlannerRowOptions,\n stampPlannerRows,\n} from \"@baker/api/ads-google/keyword-provenance\";\nimport { defineCommand } from \"citty\";\nimport { ApiError, apiPost } from \"../../../../client.ts\";\nimport { handleConnectionError, isNotConnectedError } from \"../../../../error-handler.ts\";\nimport { plannerMarket } from \"../../../../geo-context.ts\";\nimport { registerSchema } from \"../../../../schemas.ts\";\nimport { buildQueryCacheKey, cacheGet, cacheSet, getManagerIdForCustomer } from \"../../cache.ts\";\nimport { resolveCustomerId, writeAdsJson, writeAdsOutput } from \"../../output.ts\";\nimport type { AdsErrorEnvelope } from \"../../types.ts\";\n\nregisterSchema({\n command: \"ads.google.keywords.metrics\",\n routes: [\"POST /api/ads/google/keywords/metrics\"],\n effect: \"read_live\",\n description:\n \"Get historical market metrics for specific keywords. Returns { source: \\\"keyword_planner_estimate\\\", historical_metrics: [...] }. These are Keyword Planner estimates of total market search volume, not this account's data: every row carries a source column and every metric is prefixed planner_ (planner_avg_monthly_searches, planner_competition, ...). Volumes and competition_index are numbers, bids are in the account's currency (planner_low_top_of_page_bid, planner_high_top_of_page_bid), and the 12-month breakdown (planner_monthly_search_volumes) comes only with --full. Never report a planner_ number as impressions, clicks or any account metric — read those with `baker ads google query` against the account. With no --location/--language the read follows the location and language the account's campaigns target together, else the country of the account's time zone in its main language (the United States in English only when the account says neither); `query_context` names the market and where it came from.\",\n args: {\n \"customer-id\": {\n type: \"string\",\n description:\n \"Google Ads customer ID (10 digits; dashes are fine). Falls back to BAKER_GOOGLE_ADS_CUSTOMER_ID env var.\",\n required: false,\n },\n keywords: { type: \"string\", description: \"Comma-separated keywords to analyze (max 200)\", required: true },\n location: {\n type: \"string\",\n description:\n \"Country code (es, gb) or geo target id (2724; cities and regions too) — ids from `baker ads google keywords locations`. Comma-separate up to 10 to compare markets in one call (`2076,2840`): one row per keyword, each location's metrics suffixed with its id (planner_avg_monthly_searches_2076, planner_avg_monthly_searches_2840), no monthly breakdown. Omitted: the location of the location/language pair most of the account's campaigns target, else the country of the account's time zone\",\n required: false,\n },\n language: {\n type: \"string\",\n description:\n \"Language code (es, ca) or language id (1003) — ids from `baker ads google keywords languages`. Omitted: the language of that pair (every language when those campaigns set none), else the time zone country's main language\",\n required: false,\n },\n output: { type: \"string\", description: \"Format: json|csv|jsonl|md\", required: false, default: \"json\" },\n \"no-cache\": { type: \"boolean\", description: \"Skip cache\", required: false },\n full: {\n type: \"boolean\",\n description:\n \"Add the 12-month breakdown (planner_monthly_search_volumes) to every row; without it a row is the averages alone\",\n required: false,\n },\n },\n});\n\ntype KeywordMetric = {\n keyword: string;\n avg_monthly_searches: string;\n competition: string;\n competition_index: string;\n low_top_of_page_bid_micros: string | number;\n high_top_of_page_bid_micros: string | number;\n monthly_search_volumes: Array<{ year: string; month: string; monthly_searches: string }>;\n};\n\ntype MetricsResponse = {\n market?: GoogleKeywordMarket;\n historical_metrics: KeywordMetric[];\n};\n\n/**\n * Same stamp as `keywords discover`: these are market estimates, not this account's numbers, and\n * the row has to say so in its own column names once it lands in a file.\n */\nexport function stampMetricsResponse(\n data: {\n historical_metrics?: readonly PlannerRow[];\n [key: string]: unknown;\n },\n options: PlannerRowOptions = {},\n): Record<string, unknown> & { historical_metrics: PlannerRow[] } {\n const { market: _market, ...rest } = data;\n return {\n ...rest,\n source: PLANNER_SOURCE,\n historical_metrics: stampPlannerRows(data.historical_metrics ?? [], options),\n };\n}\n\n/** One location is a plain read; a comma list is a comparison, one request per location on the backend. */\nfunction locationFields(flag: string | undefined): { locationIds?: string[]; byLocation?: true } {\n const locations = (flag ?? \"\")\n .split(\",\")\n .map((l) => l.trim())\n .filter(Boolean);\n if (locations.length > MAX_COMPARED_LOCATIONS) {\n writeAdsJson({\n ok: false,\n error: {\n code: \"VALIDATION_ERROR\",\n message: `Compare at most ${MAX_COMPARED_LOCATIONS} locations per call; split the rest into a second call.`,\n },\n });\n process.exit(1);\n }\n if (locations.length === 0) return {};\n return locations.length > 1 ? { locationIds: locations, byLocation: true } : { locationIds: locations };\n}\n\nfunction handleMetricsError(err: unknown): never {\n if (err instanceof ApiError) {\n if (isNotConnectedError(err.code, err.message)) {\n handleConnectionError(\"google_ads\", err.message);\n }\n const envelope: AdsErrorEnvelope = {\n ok: false,\n error: {\n code: err.code,\n message: err.message,\n fix: { action: \"reject\", explanation: err.message },\n retryable: err.code === \"RATE_LIMITED\",\n },\n };\n writeAdsJson(envelope);\n process.exit(1);\n }\n writeAdsJson({ ok: false, error: { code: \"NETWORK_ERROR\", message: \"Unexpected error\" } });\n process.exit(1);\n}\n\nexport const metricsCommand = defineCommand({\n meta: {\n name: \"metrics\",\n description: `Get historical search metrics for specific keywords.\n\nReturns Keyword Planner ESTIMATES of market search volume, not this account's numbers. Every row carries source=keyword_planner_estimate and planner_-prefixed metrics; keep those names when you quote a figure, and never present one as an impression or click count.\n\nExamples:\n baker ads google keywords metrics --customer-id 1234567890 --keywords \"running shoes,nike shoes,adidas shoes\"\n baker ads google keywords metrics --customer-id 1234567890 --keywords \"seo tools\" --location 2826\n baker ads google keywords metrics --customer-id 1234567890 --keywords \"seo tools,seo audit\" --location 2076,2840 --language 1000 --output md # Brazil vs US, one call`,\n },\n args: {\n \"customer-id\": { type: \"string\", description: \"Google Ads customer ID\", required: false },\n keywords: { type: \"string\", description: \"Comma-separated keywords\", required: true },\n location: {\n type: \"string\",\n description:\n \"Country code (es) or geo target id — see `baker ads google keywords locations`. Comma-separate up to 10 to compare markets in one call: one row per keyword, columns suffixed with each location id. Default: what the account's campaigns target, else its time zone's country\",\n required: false,\n },\n language: {\n type: \"string\",\n description:\n \"Language code (es) or language id — see `baker ads google keywords languages`. Default: what the account's campaigns target, else its time zone's country\",\n required: false,\n },\n \"no-cache\": { type: \"boolean\", description: \"Skip cache\", required: false },\n output: { type: \"string\", description: \"Format: json|csv|jsonl|md\", required: false, default: \"json\" },\n full: { type: \"boolean\", description: \"Add the 12-month breakdown to every row\", required: false },\n },\n run: async ({ args }) => {\n const customerId = await resolveCustomerId(args);\n\n const keywords = (args.keywords as string)\n .split(\",\")\n .map((k) => k.trim())\n .filter(Boolean);\n if (keywords.length === 0) {\n writeAdsJson({ ok: false, error: { code: \"VALIDATION_ERROR\", message: \"At least one keyword is required\" } });\n process.exit(1);\n }\n if (keywords.length > 200) {\n writeAdsJson({ ok: false, error: { code: \"VALIDATION_ERROR\", message: \"Maximum 200 keywords per request\" } });\n process.exit(1);\n }\n\n const body: Record<string, unknown> = { customerId, keywords };\n const managerId = getManagerIdForCustomer(customerId);\n if (managerId) body.managerId = managerId;\n Object.assign(body, locationFields(args.location as string | undefined));\n if (args.language) body.languageId = args.language;\n\n const useCache = !args[\"no-cache\"];\n if (!useCache) body.skipCache = true;\n const cacheKey = buildQueryCacheKey(customerId, JSON.stringify(body));\n\n if (useCache) {\n const cached = cacheGet<MetricsResponse>(\"keywords\", cacheKey);\n // An answer cached before reads named their market is a United States / English guess: read it again.\n if (cached?.data.market) {\n writeAdsJson({\n ok: true,\n ...plannerMarket(cached.data),\n data: stampMetricsResponse(cached.data, { full: Boolean(args.full) }),\n cached: true,\n });\n return;\n }\n }\n\n try {\n const data = await apiPost<MetricsResponse>(\"/api/ads/google/keywords/metrics\", body);\n\n if (useCache) {\n cacheSet(\"keywords\", cacheKey, data, 24 * 60 * 60 * 1000);\n }\n\n const market = plannerMarket(data);\n const stamped = stampMetricsResponse(data, { full: Boolean(args.full) });\n const format = (args.output as string) || \"json\";\n if (format !== \"json\") {\n writeAdsOutput(stamped.historical_metrics, format);\n return;\n }\n\n writeAdsJson({ ok: true, data: stamped, fields: PLANNER_FIELD_DESCRIPTIONS, ...market });\n } catch (err) {\n handleMetricsError(err);\n }\n },\n});\n"],"mappings":"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","names":[]}
|
package/package.json
CHANGED
package/dist/chunk-DFETFPM2.js
DELETED
|
@@ -1,29 +0,0 @@
|
|
|
1
|
-
// ../api/src/ads-google/keyword-provenance.ts
|
|
2
|
-
var PLANNER_SOURCE = "keyword_planner_estimate";
|
|
3
|
-
var IDENTITY_FIELDS = /* @__PURE__ */ new Set(["keyword"]);
|
|
4
|
-
function stampPlannerRows(rows) {
|
|
5
|
-
return rows.map((row) => {
|
|
6
|
-
const stamped = { source: PLANNER_SOURCE };
|
|
7
|
-
for (const [key, value] of Object.entries(row)) {
|
|
8
|
-
stamped[IDENTITY_FIELDS.has(key) || key.startsWith("planner_") ? key : `planner_${key}`] = value;
|
|
9
|
-
}
|
|
10
|
-
return stamped;
|
|
11
|
-
});
|
|
12
|
-
}
|
|
13
|
-
var PLANNER_FIELD_DESCRIPTIONS = {
|
|
14
|
-
source: `Always "${PLANNER_SOURCE}". These rows are Keyword Planner ESTIMATES of total market search volume, NOT this account's data. Never report them as impressions, clicks or any account metric \u2014 read those from a query against the account.`,
|
|
15
|
-
keyword: "The keyword this estimate is for",
|
|
16
|
-
planner_avg_monthly_searches: "ESTIMATE: average monthly searches across the whole market (string), last 12 months",
|
|
17
|
-
planner_competition: "ESTIMATE: competition level \u2014 LOW, MEDIUM, HIGH",
|
|
18
|
-
planner_competition_index: "ESTIMATE: competition index 0-100 as string (higher = more competitive)",
|
|
19
|
-
planner_low_top_of_page_bid_micros: "ESTIMATE: low-range top-of-page CPC bid in micros (\xF7 1,000,000 for currency)",
|
|
20
|
-
planner_high_top_of_page_bid_micros: "ESTIMATE: high-range top-of-page CPC bid in micros (\xF7 1,000,000 for currency)",
|
|
21
|
-
planner_monthly_search_volumes: "ESTIMATE: monthly market search volume breakdown (array of {year, month, monthly_searches})"
|
|
22
|
-
};
|
|
23
|
-
|
|
24
|
-
export {
|
|
25
|
-
PLANNER_SOURCE,
|
|
26
|
-
stampPlannerRows,
|
|
27
|
-
PLANNER_FIELD_DESCRIPTIONS
|
|
28
|
-
};
|
|
29
|
-
//# sourceMappingURL=chunk-DFETFPM2.js.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"sources":["../../api/src/ads-google/keyword-provenance.ts"],"sourcesContent":["/**\n * Keyword Planner numbers are estimates of what the whole market searches. Account numbers are what\n * this advertiser actually got. They are different quantities with similar shapes, they end up in\n * neighbouring CSVs in /tmp, and a session once reported the first as the second — \"we already show\n * on shipbob (88 impressions)\" against an account that had never shown there once.\n *\n * A header banner does not survive `--output csv > file`, a `python3 -c` pass or 150 tool calls of\n * distance. A column name does: the only way to read one of these numbers is to name its source\n * while doing it. Every row also carries a constant `source` column, which survives any transform\n * that copies rows rather than picking fields. Stamped the same way wherever a planner row is read:\n * `baker ads google keywords discover|metrics` and Baker's engine (`agent-engine/found-ads-google`).\n */\nexport const PLANNER_SOURCE = \"keyword_planner_estimate\";\n\n/** The one field that is not an estimate — it is the term itself, so it keeps its plain name. */\nconst IDENTITY_FIELDS = new Set([\"keyword\"]);\n\nexport type PlannerRow = Record<string, unknown>;\n\nexport function stampPlannerRows(rows: readonly PlannerRow[]): PlannerRow[] {\n return rows.map((row) => {\n const stamped: PlannerRow = { source: PLANNER_SOURCE };\n for (const [key, value] of Object.entries(row)) {\n stamped[IDENTITY_FIELDS.has(key) || key.startsWith(\"planner_\") ? key : `planner_${key}`] = value;\n }\n return stamped;\n });\n}\n\n/** Field docs for the stamped shape, stated so the estimate can never be mistaken for account data. */\nexport const PLANNER_FIELD_DESCRIPTIONS: Record<string, string> = {\n source: `Always \"${PLANNER_SOURCE}\". These rows are Keyword Planner ESTIMATES of total market search volume, NOT this account's data. Never report them as impressions, clicks or any account metric — read those from a query against the account.`,\n keyword: \"The keyword this estimate is for\",\n planner_avg_monthly_searches: \"ESTIMATE: average monthly searches across the whole market (string), last 12 months\",\n planner_competition: \"ESTIMATE: competition level — LOW, MEDIUM, HIGH\",\n planner_competition_index: \"ESTIMATE: competition index 0-100 as string (higher = more competitive)\",\n planner_low_top_of_page_bid_micros: \"ESTIMATE: low-range top-of-page CPC bid in micros (÷ 1,000,000 for currency)\",\n planner_high_top_of_page_bid_micros: \"ESTIMATE: high-range top-of-page CPC bid in micros (÷ 1,000,000 for currency)\",\n planner_monthly_search_volumes:\n \"ESTIMATE: monthly market search volume breakdown (array of {year, month, monthly_searches})\",\n};\n"],"mappings":";AAYO,IAAM,iBAAiB;AAG9B,IAAM,kBAAkB,oBAAI,IAAI,CAAC,SAAS,CAAC;AAIpC,SAAS,iBAAiB,MAA2C;AAC1E,SAAO,KAAK,IAAI,CAAC,QAAQ;AACvB,UAAM,UAAsB,EAAE,QAAQ,eAAe;AACrD,eAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,GAAG,GAAG;AAC9C,cAAQ,gBAAgB,IAAI,GAAG,KAAK,IAAI,WAAW,UAAU,IAAI,MAAM,WAAW,GAAG,EAAE,IAAI;AAAA,IAC7F;AACA,WAAO;AAAA,EACT,CAAC;AACH;AAGO,IAAM,6BAAqD;AAAA,EAChE,QAAQ,WAAW,cAAc;AAAA,EACjC,SAAS;AAAA,EACT,8BAA8B;AAAA,EAC9B,qBAAqB;AAAA,EACrB,2BAA2B;AAAA,EAC3B,oCAAoC;AAAA,EACpC,qCAAqC;AAAA,EACrC,gCACE;AACJ;","names":[]}
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/commands/ads/google/keywords/discover.ts"],"sourcesContent":["import type { GoogleKeywordMarket } from \"@baker/api/ads-google/keyword-planning\";\nimport {\n PLANNER_FIELD_DESCRIPTIONS,\n PLANNER_SOURCE,\n type PlannerRow,\n stampPlannerRows,\n} from \"@baker/api/ads-google/keyword-provenance\";\nimport { defineCommand } from \"citty\";\nimport { ApiError, apiPost } from \"../../../../client.ts\";\nimport { handleConnectionError, isNotConnectedError } from \"../../../../error-handler.ts\";\nimport { plannerMarket } from \"../../../../geo-context.ts\";\nimport { registerSchema } from \"../../../../schemas.ts\";\nimport { buildQueryCacheKey, cacheGet, cacheSet, getManagerIdForCustomer } from \"../../cache.ts\";\nimport { resolveCustomerId, writeAdsJson, writeAdsOutput } from \"../../output.ts\";\nimport type { AdsErrorEnvelope } from \"../../types.ts\";\n\nregisterSchema({\n command: \"ads.google.keywords.discover\",\n routes: [\"POST /api/ads/google/keywords/discover\"],\n effect: \"read_live\",\n description:\n \"Discover keyword ideas from seed keywords or URLs. Returns { source: \\\"keyword_planner_estimate\\\", keywords, total_results, next_page_token? }. These are Keyword Planner estimates of total market search volume, not this account's data: every row carries a source column and every metric is prefixed planner_ (planner_avg_monthly_searches, planner_competition, ...). Never report a planner_ number as impressions, clicks or any account metric — read those with `baker ads google query` against the account. With no --location/--language the read follows the location and language the account's campaigns target together, else the country of the account's time zone in its main language (the United States in English only when the account says neither); `query_context` names the market and where it came from.\",\n args: {\n \"customer-id\": {\n type: \"string\",\n description:\n \"Google Ads customer ID (10 digits; dashes are fine). Falls back to BAKER_GOOGLE_ADS_CUSTOMER_ID env var.\",\n required: false,\n },\n seeds: { type: \"string\", description: \"Comma-separated seed keywords (max 10)\", required: false },\n url: { type: \"string\", description: \"URL to extract keyword ideas from\", required: false },\n location: {\n type: \"string\",\n description:\n \"Country code (es, gb) or geo target id (2724; cities and regions too) — ids from `baker ads google keywords locations`. Omitted: the location of the location/language pair most of the account's campaigns target, else the country of the account's time zone\",\n required: false,\n },\n language: {\n type: \"string\",\n description:\n \"Language code (es, ca) or language id (1003) — ids from `baker ads google keywords languages`. Omitted: the language of that pair (every language when those campaigns set none), else the time zone country's main language\",\n required: false,\n },\n limit: { type: \"string\", description: \"Max keyword ideas (default: 20, max: 100)\", required: false, default: 20 },\n cursor: {\n type: \"string\",\n description: \"Pagination cursor from previous response (next_page_token)\",\n required: false,\n },\n output: { type: \"string\", description: \"Format: json|csv|jsonl|md\", required: false, default: \"json\" },\n \"no-cache\": { type: \"boolean\", description: \"Skip cache\", required: false },\n },\n});\n\ntype KeywordIdea = {\n keyword: string;\n avg_monthly_searches: string;\n competition: string;\n competition_index: string;\n low_top_of_page_bid_micros: number;\n high_top_of_page_bid_micros: number;\n monthly_search_volumes: Array<{ year: string; month: string; monthly_searches: string }>;\n};\n\ntype DiscoverResponse = {\n market?: GoogleKeywordMarket;\n keywords: KeywordIdea[];\n total_results: number;\n next_page_token?: string;\n};\n\n/**\n * Every idea leaves this command carrying where it came from: a `source` column on the row and a\n * `planner_` prefix on each estimate. Keyword Planner volumes have been reported as account\n * impressions before; a name is the only label that survives a CSV in /tmp and a `python3` pass.\n */\nexport function stampDiscoverResponse(data: {\n keywords?: readonly PlannerRow[];\n [key: string]: unknown;\n}): Record<string, unknown> & { keywords: PlannerRow[] } {\n const { market: _market, ...rest } = data;\n return { ...rest, source: PLANNER_SOURCE, keywords: stampPlannerRows(data.keywords ?? []) };\n}\n\nfunction buildDiscoverBody(customerId: string, args: Record<string, unknown>): Record<string, unknown> {\n const body: Record<string, unknown> = {\n customerId,\n pageSize: args.limit ? Number(args.limit) : 20,\n };\n const managerId = getManagerIdForCustomer(customerId);\n if (managerId) body.managerId = managerId;\n\n const seeds = args.seeds\n ? (args.seeds as string)\n .split(\",\")\n .map((s) => s.trim())\n .filter(Boolean)\n : undefined;\n if (seeds) body.seeds = seeds;\n if (args.url) body.url = args.url;\n if (args.location) body.locationIds = [args.location as string];\n if (args.language) body.languageId = args.language;\n if (args.cursor) body.pageToken = args.cursor;\n return body;\n}\n\nfunction handleKeywordError(err: unknown): never {\n if (err instanceof ApiError) {\n if (isNotConnectedError(err.code, err.message)) {\n handleConnectionError(\"google_ads\", err.message);\n }\n const envelope: AdsErrorEnvelope = {\n ok: false,\n error: {\n code: err.code,\n message: err.message,\n fix: { action: \"reject\", explanation: err.message },\n retryable: err.code === \"RATE_LIMITED\",\n },\n };\n writeAdsJson(envelope);\n process.exit(1);\n }\n writeAdsJson({ ok: false, error: { code: \"NETWORK_ERROR\", message: \"Unexpected error\" } });\n process.exit(1);\n}\n\nexport const discoverCommand = defineCommand({\n meta: {\n name: \"discover\",\n description: `Discover new keyword ideas from seed keywords or competitor URLs.\n\nReturns Keyword Planner ESTIMATES of market search volume, not this account's numbers. Every row carries source=keyword_planner_estimate and planner_-prefixed metrics; keep those names when you quote a figure, and never present one as an impression or click count.\n\nExamples:\n baker ads google keywords discover --customer-id 1234567890 --seeds \"running shoes,athletic footwear\"\n baker ads google keywords discover --customer-id 1234567890 --url \"https://competitor.com\"\n baker ads google keywords discover --customer-id 1234567890 --seeds \"seo tools\" --location 2826 --limit 50`,\n },\n args: {\n \"customer-id\": { type: \"string\", description: \"Google Ads customer ID\", required: false },\n seeds: { type: \"string\", description: \"Comma-separated seed keywords\", required: false },\n url: { type: \"string\", description: \"URL to extract ideas from\", required: false },\n location: {\n type: \"string\",\n description:\n \"Country code (es) or geo target id — see `baker ads google keywords locations`. Default: what the account's campaigns target, else its time zone's country\",\n required: false,\n },\n language: {\n type: \"string\",\n description:\n \"Language code (es) or language id — see `baker ads google keywords languages`. Default: what the account's campaigns target, else its time zone's country\",\n required: false,\n },\n limit: { type: \"string\", description: \"Max results (default 20)\", required: false },\n cursor: { type: \"string\", description: \"Pagination cursor from previous response\", required: false },\n \"no-cache\": { type: \"boolean\", description: \"Skip cache\", required: false },\n output: { type: \"string\", description: \"Format: json|csv|jsonl|md\", required: false, default: \"json\" },\n },\n run: async ({ args }) => {\n const customerId = await resolveCustomerId(args);\n\n if (!args.seeds && !args.url) {\n writeAdsJson({\n ok: false,\n error: { code: \"VALIDATION_ERROR\", message: \"Provide --seeds or --url (at least one required)\" },\n });\n process.exit(1);\n }\n\n const body = buildDiscoverBody(customerId, args);\n const useCache = !args[\"no-cache\"] && !args.cursor;\n if (!useCache) body.skipCache = true;\n const cacheKey = buildQueryCacheKey(customerId, JSON.stringify(body));\n\n if (useCache) {\n const cached = cacheGet<DiscoverResponse>(\"keywords\", cacheKey);\n // An answer cached before reads named their market is a United States / English guess: read it again.\n if (cached?.data.market) {\n writeAdsJson({\n ok: true,\n ...plannerMarket(cached.data),\n data: stampDiscoverResponse(cached.data),\n cached: true,\n });\n return;\n }\n }\n\n try {\n const data = await apiPost<DiscoverResponse>(\"/api/ads/google/keywords/discover\", body);\n if (useCache) {\n cacheSet(\"keywords\", cacheKey, data, 24 * 60 * 60 * 1000);\n }\n\n const market = plannerMarket(data);\n const stamped = stampDiscoverResponse(data);\n const format = (args.output as string) || \"json\";\n if (format !== \"json\") {\n writeAdsOutput(stamped.keywords, format);\n return;\n }\n\n writeAdsJson({ ok: true, data: stamped, fields: PLANNER_FIELD_DESCRIPTIONS, ...market });\n } catch (err) {\n handleKeywordError(err);\n }\n },\n});\n"],"mappings":"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","names":[]}
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/commands/ads/google/keywords/metrics.ts"],"sourcesContent":["import { type GoogleKeywordMarket, MAX_COMPARED_LOCATIONS } from \"@baker/api/ads-google/keyword-planning\";\nimport {\n PLANNER_FIELD_DESCRIPTIONS,\n PLANNER_SOURCE,\n type PlannerRow,\n stampPlannerRows,\n} from \"@baker/api/ads-google/keyword-provenance\";\nimport { defineCommand } from \"citty\";\nimport { ApiError, apiPost } from \"../../../../client.ts\";\nimport { handleConnectionError, isNotConnectedError } from \"../../../../error-handler.ts\";\nimport { plannerMarket } from \"../../../../geo-context.ts\";\nimport { registerSchema } from \"../../../../schemas.ts\";\nimport { buildQueryCacheKey, cacheGet, cacheSet, getManagerIdForCustomer } from \"../../cache.ts\";\nimport { resolveCustomerId, writeAdsJson, writeAdsOutput } from \"../../output.ts\";\nimport type { AdsErrorEnvelope } from \"../../types.ts\";\n\nregisterSchema({\n command: \"ads.google.keywords.metrics\",\n routes: [\"POST /api/ads/google/keywords/metrics\"],\n effect: \"read_live\",\n description:\n \"Get historical market metrics for specific keywords. Returns { source: \\\"keyword_planner_estimate\\\", historical_metrics: [...] }. These are Keyword Planner estimates of total market search volume, not this account's data: every row carries a source column and every metric is prefixed planner_ (planner_avg_monthly_searches, planner_competition, ...). Never report a planner_ number as impressions, clicks or any account metric — read those with `baker ads google query` against the account. With no --location/--language the read follows the location and language the account's campaigns target together, else the country of the account's time zone in its main language (the United States in English only when the account says neither); `query_context` names the market and where it came from.\",\n args: {\n \"customer-id\": {\n type: \"string\",\n description:\n \"Google Ads customer ID (10 digits; dashes are fine). Falls back to BAKER_GOOGLE_ADS_CUSTOMER_ID env var.\",\n required: false,\n },\n keywords: { type: \"string\", description: \"Comma-separated keywords to analyze (max 200)\", required: true },\n location: {\n type: \"string\",\n description:\n \"Country code (es, gb) or geo target id (2724; cities and regions too) — ids from `baker ads google keywords locations`. Comma-separate up to 10 to compare markets in one call (`2076,2840`): one row per keyword, each location's metrics suffixed with its id (planner_avg_monthly_searches_2076, planner_avg_monthly_searches_2840), no monthly breakdown. Omitted: the location of the location/language pair most of the account's campaigns target, else the country of the account's time zone\",\n required: false,\n },\n language: {\n type: \"string\",\n description:\n \"Language code (es, ca) or language id (1003) — ids from `baker ads google keywords languages`. Omitted: the language of that pair (every language when those campaigns set none), else the time zone country's main language\",\n required: false,\n },\n output: { type: \"string\", description: \"Format: json|csv|jsonl|md\", required: false, default: \"json\" },\n \"no-cache\": { type: \"boolean\", description: \"Skip cache\", required: false },\n },\n});\n\ntype KeywordMetric = {\n keyword: string;\n avg_monthly_searches: string;\n competition: string;\n competition_index: string;\n low_top_of_page_bid_micros: number;\n high_top_of_page_bid_micros: number;\n monthly_search_volumes: Array<{ year: string; month: string; monthly_searches: string }>;\n};\n\ntype MetricsResponse = {\n market?: GoogleKeywordMarket;\n historical_metrics: KeywordMetric[];\n};\n\n/**\n * Same stamp as `keywords discover`: these are market estimates, not this account's numbers, and\n * the row has to say so in its own column names once it lands in a file.\n */\nexport function stampMetricsResponse(data: {\n historical_metrics?: readonly PlannerRow[];\n [key: string]: unknown;\n}): Record<string, unknown> & { historical_metrics: PlannerRow[] } {\n const { market: _market, ...rest } = data;\n return { ...rest, source: PLANNER_SOURCE, historical_metrics: stampPlannerRows(data.historical_metrics ?? []) };\n}\n\n/** One location is a plain read; a comma list is a comparison, one request per location on the backend. */\nfunction locationFields(flag: string | undefined): { locationIds?: string[]; byLocation?: true } {\n const locations = (flag ?? \"\")\n .split(\",\")\n .map((l) => l.trim())\n .filter(Boolean);\n if (locations.length > MAX_COMPARED_LOCATIONS) {\n writeAdsJson({\n ok: false,\n error: {\n code: \"VALIDATION_ERROR\",\n message: `Compare at most ${MAX_COMPARED_LOCATIONS} locations per call; split the rest into a second call.`,\n },\n });\n process.exit(1);\n }\n if (locations.length === 0) return {};\n return locations.length > 1 ? { locationIds: locations, byLocation: true } : { locationIds: locations };\n}\n\nfunction handleMetricsError(err: unknown): never {\n if (err instanceof ApiError) {\n if (isNotConnectedError(err.code, err.message)) {\n handleConnectionError(\"google_ads\", err.message);\n }\n const envelope: AdsErrorEnvelope = {\n ok: false,\n error: {\n code: err.code,\n message: err.message,\n fix: { action: \"reject\", explanation: err.message },\n retryable: err.code === \"RATE_LIMITED\",\n },\n };\n writeAdsJson(envelope);\n process.exit(1);\n }\n writeAdsJson({ ok: false, error: { code: \"NETWORK_ERROR\", message: \"Unexpected error\" } });\n process.exit(1);\n}\n\nexport const metricsCommand = defineCommand({\n meta: {\n name: \"metrics\",\n description: `Get historical search metrics for specific keywords.\n\nReturns Keyword Planner ESTIMATES of market search volume, not this account's numbers. Every row carries source=keyword_planner_estimate and planner_-prefixed metrics; keep those names when you quote a figure, and never present one as an impression or click count.\n\nExamples:\n baker ads google keywords metrics --customer-id 1234567890 --keywords \"running shoes,nike shoes,adidas shoes\"\n baker ads google keywords metrics --customer-id 1234567890 --keywords \"seo tools\" --location 2826\n baker ads google keywords metrics --customer-id 1234567890 --keywords \"seo tools,seo audit\" --location 2076,2840 --language 1000 --output md # Brazil vs US, one call`,\n },\n args: {\n \"customer-id\": { type: \"string\", description: \"Google Ads customer ID\", required: false },\n keywords: { type: \"string\", description: \"Comma-separated keywords\", required: true },\n location: {\n type: \"string\",\n description:\n \"Country code (es) or geo target id — see `baker ads google keywords locations`. Comma-separate up to 10 to compare markets in one call: one row per keyword, columns suffixed with each location id. Default: what the account's campaigns target, else its time zone's country\",\n required: false,\n },\n language: {\n type: \"string\",\n description:\n \"Language code (es) or language id — see `baker ads google keywords languages`. Default: what the account's campaigns target, else its time zone's country\",\n required: false,\n },\n \"no-cache\": { type: \"boolean\", description: \"Skip cache\", required: false },\n output: { type: \"string\", description: \"Format: json|csv|jsonl|md\", required: false, default: \"json\" },\n },\n run: async ({ args }) => {\n const customerId = await resolveCustomerId(args);\n\n const keywords = (args.keywords as string)\n .split(\",\")\n .map((k) => k.trim())\n .filter(Boolean);\n if (keywords.length === 0) {\n writeAdsJson({ ok: false, error: { code: \"VALIDATION_ERROR\", message: \"At least one keyword is required\" } });\n process.exit(1);\n }\n if (keywords.length > 200) {\n writeAdsJson({ ok: false, error: { code: \"VALIDATION_ERROR\", message: \"Maximum 200 keywords per request\" } });\n process.exit(1);\n }\n\n const body: Record<string, unknown> = { customerId, keywords };\n const managerId = getManagerIdForCustomer(customerId);\n if (managerId) body.managerId = managerId;\n Object.assign(body, locationFields(args.location as string | undefined));\n if (args.language) body.languageId = args.language;\n\n const useCache = !args[\"no-cache\"];\n if (!useCache) body.skipCache = true;\n const cacheKey = buildQueryCacheKey(customerId, JSON.stringify(body));\n\n if (useCache) {\n const cached = cacheGet<MetricsResponse>(\"keywords\", cacheKey);\n // An answer cached before reads named their market is a United States / English guess: read it again.\n if (cached?.data.market) {\n writeAdsJson({\n ok: true,\n ...plannerMarket(cached.data),\n data: stampMetricsResponse(cached.data),\n cached: true,\n });\n return;\n }\n }\n\n try {\n const data = await apiPost<MetricsResponse>(\"/api/ads/google/keywords/metrics\", body);\n\n if (useCache) {\n cacheSet(\"keywords\", cacheKey, data, 24 * 60 * 60 * 1000);\n }\n\n const market = plannerMarket(data);\n const stamped = stampMetricsResponse(data);\n const format = (args.output as string) || \"json\";\n if (format !== \"json\") {\n writeAdsOutput(stamped.historical_metrics, format);\n return;\n }\n\n writeAdsJson({ ok: true, data: stamped, fields: PLANNER_FIELD_DESCRIPTIONS, ...market });\n } catch (err) {\n handleMetricsError(err);\n }\n },\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAOA,SAAS,qBAAqB;AAS9B,eAAe;AAAA,EACb,SAAS;AAAA,EACT,QAAQ,CAAC,uCAAuC;AAAA,EAChD,QAAQ;AAAA,EACR,aACE;AAAA,EACF,MAAM;AAAA,IACJ,eAAe;AAAA,MACb,MAAM;AAAA,MACN,aACE;AAAA,MACF,UAAU;AAAA,IACZ;AAAA,IACA,UAAU,EAAE,MAAM,UAAU,aAAa,iDAAiD,UAAU,KAAK;AAAA,IACzG,UAAU;AAAA,MACR,MAAM;AAAA,MACN,aACE;AAAA,MACF,UAAU;AAAA,IACZ;AAAA,IACA,UAAU;AAAA,MACR,MAAM;AAAA,MACN,aACE;AAAA,MACF,UAAU;AAAA,IACZ;AAAA,IACA,QAAQ,EAAE,MAAM,UAAU,aAAa,6BAA6B,UAAU,OAAO,SAAS,OAAO;AAAA,IACrG,YAAY,EAAE,MAAM,WAAW,aAAa,cAAc,UAAU,MAAM;AAAA,EAC5E;AACF,CAAC;AAqBM,SAAS,qBAAqB,MAG8B;AACjE,QAAM,EAAE,QAAQ,SAAS,GAAG,KAAK,IAAI;AACrC,SAAO,EAAE,GAAG,MAAM,QAAQ,gBAAgB,oBAAoB,iBAAiB,KAAK,sBAAsB,CAAC,CAAC,EAAE;AAChH;AAGA,SAAS,eAAe,MAAyE;AAC/F,QAAM,aAAa,QAAQ,IACxB,MAAM,GAAG,EACT,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,EACnB,OAAO,OAAO;AACjB,MAAI,UAAU,SAAS,wBAAwB;AAC7C,iBAAa;AAAA,MACX,IAAI;AAAA,MACJ,OAAO;AAAA,QACL,MAAM;AAAA,QACN,SAAS,mBAAmB,sBAAsB;AAAA,MACpD;AAAA,IACF,CAAC;AACD,YAAQ,KAAK,CAAC;AAAA,EAChB;AACA,MAAI,UAAU,WAAW,EAAG,QAAO,CAAC;AACpC,SAAO,UAAU,SAAS,IAAI,EAAE,aAAa,WAAW,YAAY,KAAK,IAAI,EAAE,aAAa,UAAU;AACxG;AAEA,SAAS,mBAAmB,KAAqB;AAC/C,MAAI,eAAe,UAAU;AAC3B,QAAI,oBAAoB,IAAI,MAAM,IAAI,OAAO,GAAG;AAC9C,4BAAsB,cAAc,IAAI,OAAO;AAAA,IACjD;AACA,UAAM,WAA6B;AAAA,MACjC,IAAI;AAAA,MACJ,OAAO;AAAA,QACL,MAAM,IAAI;AAAA,QACV,SAAS,IAAI;AAAA,QACb,KAAK,EAAE,QAAQ,UAAU,aAAa,IAAI,QAAQ;AAAA,QAClD,WAAW,IAAI,SAAS;AAAA,MAC1B;AAAA,IACF;AACA,iBAAa,QAAQ;AACrB,YAAQ,KAAK,CAAC;AAAA,EAChB;AACA,eAAa,EAAE,IAAI,OAAO,OAAO,EAAE,MAAM,iBAAiB,SAAS,mBAAmB,EAAE,CAAC;AACzF,UAAQ,KAAK,CAAC;AAChB;AAEO,IAAM,iBAAiB,cAAc;AAAA,EAC1C,MAAM;AAAA,IACJ,MAAM;AAAA,IACN,aAAa;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQf;AAAA,EACA,MAAM;AAAA,IACJ,eAAe,EAAE,MAAM,UAAU,aAAa,0BAA0B,UAAU,MAAM;AAAA,IACxF,UAAU,EAAE,MAAM,UAAU,aAAa,4BAA4B,UAAU,KAAK;AAAA,IACpF,UAAU;AAAA,MACR,MAAM;AAAA,MACN,aACE;AAAA,MACF,UAAU;AAAA,IACZ;AAAA,IACA,UAAU;AAAA,MACR,MAAM;AAAA,MACN,aACE;AAAA,MACF,UAAU;AAAA,IACZ;AAAA,IACA,YAAY,EAAE,MAAM,WAAW,aAAa,cAAc,UAAU,MAAM;AAAA,IAC1E,QAAQ,EAAE,MAAM,UAAU,aAAa,6BAA6B,UAAU,OAAO,SAAS,OAAO;AAAA,EACvG;AAAA,EACA,KAAK,OAAO,EAAE,KAAK,MAAM;AACvB,UAAM,aAAa,MAAM,kBAAkB,IAAI;AAE/C,UAAM,WAAY,KAAK,SACpB,MAAM,GAAG,EACT,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,EACnB,OAAO,OAAO;AACjB,QAAI,SAAS,WAAW,GAAG;AACzB,mBAAa,EAAE,IAAI,OAAO,OAAO,EAAE,MAAM,oBAAoB,SAAS,mCAAmC,EAAE,CAAC;AAC5G,cAAQ,KAAK,CAAC;AAAA,IAChB;AACA,QAAI,SAAS,SAAS,KAAK;AACzB,mBAAa,EAAE,IAAI,OAAO,OAAO,EAAE,MAAM,oBAAoB,SAAS,mCAAmC,EAAE,CAAC;AAC5G,cAAQ,KAAK,CAAC;AAAA,IAChB;AAEA,UAAM,OAAgC,EAAE,YAAY,SAAS;AAC7D,UAAM,YAAY,wBAAwB,UAAU;AACpD,QAAI,UAAW,MAAK,YAAY;AAChC,WAAO,OAAO,MAAM,eAAe,KAAK,QAA8B,CAAC;AACvE,QAAI,KAAK,SAAU,MAAK,aAAa,KAAK;AAE1C,UAAM,WAAW,CAAC,KAAK,UAAU;AACjC,QAAI,CAAC,SAAU,MAAK,YAAY;AAChC,UAAM,WAAW,mBAAmB,YAAY,KAAK,UAAU,IAAI,CAAC;AAEpE,QAAI,UAAU;AACZ,YAAM,SAAS,SAA0B,YAAY,QAAQ;AAE7D,UAAI,QAAQ,KAAK,QAAQ;AACvB,qBAAa;AAAA,UACX,IAAI;AAAA,UACJ,GAAG,cAAc,OAAO,IAAI;AAAA,UAC5B,MAAM,qBAAqB,OAAO,IAAI;AAAA,UACtC,QAAQ;AAAA,QACV,CAAC;AACD;AAAA,MACF;AAAA,IACF;AAEA,QAAI;AACF,YAAM,OAAO,MAAM,QAAyB,oCAAoC,IAAI;AAEpF,UAAI,UAAU;AACZ,iBAAS,YAAY,UAAU,MAAM,KAAK,KAAK,KAAK,GAAI;AAAA,MAC1D;AAEA,YAAM,SAAS,cAAc,IAAI;AACjC,YAAM,UAAU,qBAAqB,IAAI;AACzC,YAAM,SAAU,KAAK,UAAqB;AAC1C,UAAI,WAAW,QAAQ;AACrB,uBAAe,QAAQ,oBAAoB,MAAM;AACjD;AAAA,MACF;AAEA,mBAAa,EAAE,IAAI,MAAM,MAAM,SAAS,QAAQ,4BAA4B,GAAG,OAAO,CAAC;AAAA,IACzF,SAAS,KAAK;AACZ,yBAAmB,GAAG;AAAA,IACxB;AAAA,EACF;AACF,CAAC;","names":[]}
|
|
File without changes
|
|
File without changes
|