@egbe-ai/opencode 0.0.0-stage → 0.1.8

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.
Files changed (479) hide show
  1. package/LICENSE +4 -0
  2. package/README.md +124 -2
  3. package/index.js +5 -0
  4. package/package.json +55 -4
  5. package/plugin.js +230 -0
  6. package/session-log.js +315 -0
  7. package/skills/.egbe-catalog/manifest.json +1 -0
  8. package/skills/egbe-os-analytics/SKILL.md +499 -0
  9. package/skills/egbe-os-analytics/canonical-events.v1.json +256 -0
  10. package/skills/egbe-os-analytics/references/session-funnel.md +130 -0
  11. package/skills/egbe-os-analytics/references/workflows/activation-tracking.md +147 -0
  12. package/skills/egbe-os-analytics/references/workflows/landing-click-tracking.md +209 -0
  13. package/skills/egbe-os-analytics/references/workflows/payment-lifecycle-tracking.md +122 -0
  14. package/skills/egbe-os-analytics/references/workflows/product-funnel-tracking.md +77 -0
  15. package/skills/egbe-os-analytics/references/workflows/signup-lifecycle-tracking.md +208 -0
  16. package/skills/egbe-os-analytics/scripts/umami_funnel.py +927 -0
  17. package/skills/egbe-os-apollo-lead-finder/SKILL.md +135 -0
  18. package/skills/egbe-os-apollo-lead-finder/references/operations.md +240 -0
  19. package/skills/egbe-os-apollo-lead-finder/scripts/enrich.js +6 -0
  20. package/skills/egbe-os-apollo-lead-finder/scripts/enrich.sh +4 -0
  21. package/skills/egbe-os-apollo-lead-finder/scripts/find-leads.js +6 -0
  22. package/skills/egbe-os-apollo-lead-finder/scripts/find-leads.sh +4 -0
  23. package/skills/egbe-os-apollo-lead-finder/scripts/lib/apollo-client.js +343 -0
  24. package/skills/egbe-os-apollo-lead-finder/scripts/lib/connection-identity.js +17 -0
  25. package/skills/egbe-os-apollo-lead-finder/scripts/lib/helpers.js +127 -0
  26. package/skills/egbe-os-apollo-lead-finder/scripts/lib/places-filters.js +217 -0
  27. package/skills/egbe-os-apollo-lead-finder/scripts/lib/sourcing.js +153 -0
  28. package/skills/egbe-os-apollo-lead-finder/scripts/places-leads.js +653 -0
  29. package/skills/egbe-os-apollo-lead-finder/scripts/places-leads.sh +4 -0
  30. package/skills/egbe-os-apollo-lead-finder/scripts/search.js +6 -0
  31. package/skills/egbe-os-apollo-lead-finder/scripts/search.sh +4 -0
  32. package/skills/egbe-os-campaign-landing-page/SKILL.md +95 -0
  33. package/skills/egbe-os-campaign-landing-page/agents/openai.yaml +4 -0
  34. package/skills/egbe-os-campaign-landing-page/references/leads-calendar-and-tracking.md +66 -0
  35. package/skills/egbe-os-campaign-landing-page/references/os-wiring.md +58 -0
  36. package/skills/egbe-os-campaign-landing-page/references/qa.md +40 -0
  37. package/skills/egbe-os-campaign-landing-page/references/routing.md +32 -0
  38. package/skills/egbe-os-db/SKILL.md +174 -0
  39. package/skills/egbe-os-deploy/SKILL.md +412 -0
  40. package/skills/egbe-os-design/SKILL.md +182 -0
  41. package/skills/egbe-os-design-landing-page/SKILL.md +117 -0
  42. package/skills/egbe-os-design-landing-page/agents/openai.yaml +4 -0
  43. package/skills/egbe-os-design-landing-page/assets/scaffold/.dockerignore +11 -0
  44. package/skills/egbe-os-design-landing-page/assets/scaffold/AGENTS.md +31 -0
  45. package/skills/egbe-os-design-landing-page/assets/scaffold/Dockerfile +21 -0
  46. package/skills/egbe-os-design-landing-page/assets/scaffold/eslint.config.mjs +18 -0
  47. package/skills/egbe-os-design-landing-page/assets/scaffold/next.config.ts +11 -0
  48. package/skills/egbe-os-design-landing-page/assets/scaffold/package.json +36 -0
  49. package/skills/egbe-os-design-landing-page/assets/scaffold/postcss.config.mjs +7 -0
  50. package/skills/egbe-os-design-landing-page/assets/scaffold/public/.gitkeep +1 -0
  51. package/skills/egbe-os-design-landing-page/assets/scaffold/sentry.edge.config.ts +13 -0
  52. package/skills/egbe-os-design-landing-page/assets/scaffold/sentry.server.config.ts +13 -0
  53. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/global-error.tsx +19 -0
  54. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/globals.css +22 -0
  55. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/layout.tsx +21 -0
  56. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/page.tsx +3 -0
  57. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/privacy/page.tsx +28 -0
  58. package/skills/egbe-os-design-landing-page/assets/scaffold/src/components/egbe-analytics.tsx +39 -0
  59. package/skills/egbe-os-design-landing-page/assets/scaffold/src/instrumentation-client.ts +15 -0
  60. package/skills/egbe-os-design-landing-page/assets/scaffold/src/instrumentation.ts +13 -0
  61. package/skills/egbe-os-design-landing-page/assets/scaffold/src/lib/egbe-observability.generated.ts +20 -0
  62. package/skills/egbe-os-design-landing-page/assets/scaffold/src/lib/utils.ts +6 -0
  63. package/skills/egbe-os-design-landing-page/assets/scaffold/tsconfig.json +34 -0
  64. package/skills/egbe-os-design-landing-page/references/application-preparation.md +44 -0
  65. package/skills/egbe-os-design-landing-page/references/page-inputs.md +22 -0
  66. package/skills/egbe-os-destination-readiness/SKILL.md +132 -0
  67. package/skills/egbe-os-destination-readiness/references/checks.md +130 -0
  68. package/skills/egbe-os-destination-readiness/references/network-requirements.md +34 -0
  69. package/skills/egbe-os-destination-readiness/references/report.md +116 -0
  70. package/skills/egbe-os-domains/SKILL.md +189 -0
  71. package/skills/egbe-os-errors/SKILL.md +259 -0
  72. package/skills/egbe-os-git/SKILL.md +275 -0
  73. package/skills/egbe-os-git/references/issues.md +33 -0
  74. package/skills/egbe-os-google-ads/SKILL.md +163 -0
  75. package/skills/egbe-os-google-ads/references/artifacts.md +133 -0
  76. package/skills/egbe-os-google-ads/references/campaigns.md +157 -0
  77. package/skills/egbe-os-google-ads/references/conversions.md +153 -0
  78. package/skills/egbe-os-google-ads/references/delivery.md +128 -0
  79. package/skills/egbe-os-google-ads/references/keyword-ideas.md +40 -0
  80. package/skills/egbe-os-google-ads/references/reporting.md +105 -0
  81. package/skills/egbe-os-google-ads/references/search-assets.md +219 -0
  82. package/skills/egbe-os-google-ads/references/server-conversions.md +119 -0
  83. package/skills/egbe-os-google-auth/SKILL.md +285 -0
  84. package/skills/egbe-os-google-auth/agents/openai.yaml +4 -0
  85. package/skills/egbe-os-gtm-knowledge/SKILL.md +151 -0
  86. package/skills/egbe-os-images/SKILL.md +163 -0
  87. package/skills/egbe-os-images/references/stock-images.md +21 -0
  88. package/skills/egbe-os-instantly-campaign-launcher/SKILL.md +127 -0
  89. package/skills/egbe-os-instantly-campaign-launcher/references/instantly-ops.md +260 -0
  90. package/skills/egbe-os-instantly-campaign-launcher/references/observation-and-scheduling.md +188 -0
  91. package/skills/egbe-os-instantly-campaign-launcher/references/reply-handling.md +116 -0
  92. package/skills/egbe-os-instantly-campaign-launcher/references/run-spec-template.json +65 -0
  93. package/skills/egbe-os-instantly-campaign-launcher/references/run-state.md +145 -0
  94. package/skills/egbe-os-instantly-campaign-launcher/scripts/conclude-campaign.js +158 -0
  95. package/skills/egbe-os-instantly-campaign-launcher/scripts/install-crons.js +956 -0
  96. package/skills/egbe-os-instantly-campaign-launcher/scripts/launch-campaign.js +2008 -0
  97. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/campaign-metrics.js +124 -0
  98. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/confirmed-opt-outs.js +208 -0
  99. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/connection-identity.js +17 -0
  100. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/create-once.js +23 -0
  101. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/gtm-identity.js +125 -0
  102. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/helpers.js +545 -0
  103. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/html-body.js +266 -0
  104. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/instantly-client.js +328 -0
  105. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/outreach-db.js +370 -0
  106. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/recipient-exclusion/index.js +86 -0
  107. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/replenish-test-harness.js +53 -0
  108. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/reply-queue.js +67 -0
  109. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/run-config.js +103 -0
  110. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/sender-selection.js +105 -0
  111. package/skills/egbe-os-instantly-campaign-launcher/scripts/monitor-campaign.js +607 -0
  112. package/skills/egbe-os-instantly-campaign-launcher/scripts/outreach-report.js +147 -0
  113. package/skills/egbe-os-instantly-campaign-launcher/scripts/replenish-leads.js +619 -0
  114. package/skills/egbe-os-instantly-campaign-launcher/scripts/reply-worker.js +258 -0
  115. package/skills/egbe-os-instantly-campaign-launcher/scripts/run-cron-job.js +32 -0
  116. package/skills/egbe-os-instantly-campaign-launcher/scripts/send-reply.js +260 -0
  117. package/skills/egbe-os-linkedin-ads/SKILL.md +114 -0
  118. package/skills/egbe-os-linkedin-ads/references/destination-requirements.md +30 -0
  119. package/skills/egbe-os-linkedin-ads/references/runtime/api-reference.md +154 -0
  120. package/skills/egbe-os-linkedin-ads/references/runtime/artifacts.md +63 -0
  121. package/skills/egbe-os-linkedin-ads/references/workflows/build-paused.md +44 -0
  122. package/skills/egbe-os-linkedin-ads/references/workflows/conversions.md +88 -0
  123. package/skills/egbe-os-linkedin-ads/references/workflows/launch-and-pause.md +49 -0
  124. package/skills/egbe-os-linkedin-ads/references/workflows/monitoring.md +35 -0
  125. package/skills/egbe-os-linkedin-ads/references/workflows/readiness.md +63 -0
  126. package/skills/egbe-os-linkedin-ads/references/workflows/targeting-and-creative.md +52 -0
  127. package/skills/egbe-os-llm/SKILL.md +160 -0
  128. package/skills/egbe-os-mail/SKILL.md +180 -0
  129. package/skills/egbe-os-me/SKILL.md +119 -0
  130. package/skills/egbe-os-meta-ads/SKILL.md +114 -0
  131. package/skills/egbe-os-meta-ads/references/creative/creative-specs.md +15 -0
  132. package/skills/egbe-os-meta-ads/references/creative/talking-head.md +35 -0
  133. package/skills/egbe-os-meta-ads/references/destination-requirements.md +30 -0
  134. package/skills/egbe-os-meta-ads/references/runtime/api-reference.md +436 -0
  135. package/skills/egbe-os-meta-ads/references/runtime/artifacts.md +51 -0
  136. package/skills/egbe-os-meta-ads/references/runtime/insights-reference.md +187 -0
  137. package/skills/egbe-os-meta-ads/references/runtime/pixel-install.md +196 -0
  138. package/skills/egbe-os-meta-ads/references/runtime/shared-analytics-attribution.md +16 -0
  139. package/skills/egbe-os-meta-ads/references/workflows/build-paused.md +36 -0
  140. package/skills/egbe-os-meta-ads/references/workflows/launch-ready.md +16 -0
  141. package/skills/egbe-os-meta-ads/references/workflows/launch.md +23 -0
  142. package/skills/egbe-os-meta-ads/references/workflows/monitoring.md +72 -0
  143. package/skills/egbe-os-meta-ads/references/workflows/pause.md +17 -0
  144. package/skills/egbe-os-meta-ads/references/workflows/recovery.md +23 -0
  145. package/skills/egbe-os-meta-ads/scripts/check-pixel.py +229 -0
  146. package/skills/egbe-os-meta-ads/scripts/validate-meta-artifacts.py +187 -0
  147. package/skills/egbe-os-notifications/SKILL.md +78 -0
  148. package/skills/egbe-os-openai-ads/SKILL.md +149 -0
  149. package/skills/egbe-os-openai-ads/references/creative/chat-card.md +51 -0
  150. package/skills/egbe-os-openai-ads/references/destination-requirements.md +29 -0
  151. package/skills/egbe-os-openai-ads/references/runtime/api-reference.md +219 -0
  152. package/skills/egbe-os-openai-ads/references/runtime/artifacts.md +169 -0
  153. package/skills/egbe-os-openai-ads/references/workflows/build-paused.md +40 -0
  154. package/skills/egbe-os-openai-ads/references/workflows/conversions.md +40 -0
  155. package/skills/egbe-os-openai-ads/references/workflows/creative-assembly.md +24 -0
  156. package/skills/egbe-os-openai-ads/references/workflows/launch.md +27 -0
  157. package/skills/egbe-os-openai-ads/references/workflows/monitoring.md +54 -0
  158. package/skills/egbe-os-openai-ads/references/workflows/pause.md +22 -0
  159. package/skills/egbe-os-openai-ads/references/workflows/readiness.md +37 -0
  160. package/skills/egbe-os-openai-ads/references/workflows/tracking.md +32 -0
  161. package/skills/egbe-os-openai-ads/scripts/validate-openai-artifacts.py +271 -0
  162. package/skills/egbe-os-organic-trend-watch/SKILL.md +139 -0
  163. package/skills/egbe-os-organic-trend-watch/agents/openai.yaml +4 -0
  164. package/skills/egbe-os-organic-trend-watch/references/analysis-and-adaptation.md +54 -0
  165. package/skills/egbe-os-organic-trend-watch/references/collection-and-analysis.md +117 -0
  166. package/skills/egbe-os-organic-trend-watch/references/output-contract.md +133 -0
  167. package/skills/egbe-os-organic-trend-watch/references/provider-contract.md +169 -0
  168. package/skills/egbe-os-organic-trend-watch/references/runtime-contract.md +204 -0
  169. package/skills/egbe-os-organic-trend-watch/references/visual-analysis-prompt.md +17 -0
  170. package/skills/egbe-os-organic-trend-watch/scripts/_analysis.py +612 -0
  171. package/skills/egbe-os-organic-trend-watch/scripts/_contract.py +1133 -0
  172. package/skills/egbe-os-organic-trend-watch/scripts/_provider_inputs.py +165 -0
  173. package/skills/egbe-os-organic-trend-watch/scripts/analyze-visual-evidence.py +315 -0
  174. package/skills/egbe-os-organic-trend-watch/scripts/build-provider-inputs.py +88 -0
  175. package/skills/egbe-os-organic-trend-watch/scripts/connection_identity.py +22 -0
  176. package/skills/egbe-os-organic-trend-watch/scripts/egbe_artifacts.py +24 -0
  177. package/skills/egbe-os-organic-trend-watch/scripts/finalize-receipt.py +106 -0
  178. package/skills/egbe-os-organic-trend-watch/scripts/normalize-videos.py +647 -0
  179. package/skills/egbe-os-organic-trend-watch/scripts/prepare-visual-evidence.py +324 -0
  180. package/skills/egbe-os-organic-trend-watch/scripts/render-result.py +30 -0
  181. package/skills/egbe-os-organic-trend-watch/scripts/run-apify.py +723 -0
  182. package/skills/egbe-os-organic-trend-watch/scripts/run-state.py +192 -0
  183. package/skills/egbe-os-organic-trend-watch/scripts/validate-context.py +27 -0
  184. package/skills/egbe-os-organic-trend-watch/scripts/validate-runtime.py +137 -0
  185. package/skills/egbe-os-payments/SKILL.md +215 -0
  186. package/skills/egbe-os-payments/agents/openai.yaml +4 -0
  187. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/.egbe/scaffolds/billing-nextjs-subscription.v1.json +5 -0
  188. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/AGENTS.append.md +13 -0
  189. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/db/migrations/1000_egbe_billing.sql +66 -0
  190. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/package.fragment.json +12 -0
  191. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/scripts/billing-sync.mjs +162 -0
  192. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/account/billing/error.tsx +11 -0
  193. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/account/billing/loading.tsx +8 -0
  194. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/account/billing/page.tsx +121 -0
  195. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/billing/checkout/route.ts +102 -0
  196. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/billing/portal/route.ts +54 -0
  197. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/billing/status/route.ts +22 -0
  198. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/payments/webhook/route.ts +65 -0
  199. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/components/egbe-billing/plan-badge.tsx +16 -0
  200. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/billing-sync.test.mjs +58 -0
  201. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/catalog.ts +82 -0
  202. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/checkout-payload.ts +47 -0
  203. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/foundation-contract.test.mjs +59 -0
  204. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/lifecycle.d.ts +16 -0
  205. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/lifecycle.mjs +82 -0
  206. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/lifecycle.test.mjs +94 -0
  207. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/os-client.ts +96 -0
  208. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/plans.json +17 -0
  209. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/repository.ts +325 -0
  210. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/signature.d.ts +6 -0
  211. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/signature.mjs +22 -0
  212. package/skills/egbe-os-payments/references/contracts/plan-catalog.md +46 -0
  213. package/skills/egbe-os-payments/references/security/durable-verification.md +64 -0
  214. package/skills/egbe-os-payments/references/security/server-integration.md +26 -0
  215. package/skills/egbe-os-payments/references/security/webhook-and-entitlements.md +152 -0
  216. package/skills/egbe-os-payments/references/ux/billing-experience.md +47 -0
  217. package/skills/egbe-os-payments/references/workflows/account-billing.md +64 -0
  218. package/skills/egbe-os-payments/references/workflows/discounts-and-promotion-codes.md +265 -0
  219. package/skills/egbe-os-payments/references/workflows/one-time-purchase.md +75 -0
  220. package/skills/egbe-os-payments/references/workflows/product-checkout.md +355 -0
  221. package/skills/egbe-os-payments/references/workflows/subscription-lifecycle.md +55 -0
  222. package/skills/egbe-os-playbook/SKILL.md +79 -0
  223. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/email-outreach.md +91 -0
  224. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/google-search.md +40 -0
  225. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/linkedin.md +24 -0
  226. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/meta.md +23 -0
  227. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/openai.md +15 -0
  228. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/reddit.md +56 -0
  229. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/choose-test.md +73 -0
  230. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/evaluate.md +91 -0
  231. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/market.md +96 -0
  232. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/run-test.md +111 -0
  233. package/skills/egbe-os-playbook/playbooks/market-and-acquisition.md +56 -0
  234. package/skills/egbe-os-playbook/playbooks/product/business-loop.md +141 -0
  235. package/skills/egbe-os-playbook/playbooks/product/collaboration.md +26 -0
  236. package/skills/egbe-os-playbook/playbooks/product/deliver.md +75 -0
  237. package/skills/egbe-os-playbook/playbooks/product/diagnose.md +80 -0
  238. package/skills/egbe-os-playbook/playbooks/product/evaluate.md +67 -0
  239. package/skills/egbe-os-playbook/playbooks/product/experience.md +132 -0
  240. package/skills/egbe-os-playbook/playbooks/product/loop-examples.md +67 -0
  241. package/skills/egbe-os-playbook/playbooks/product/offer.md +65 -0
  242. package/skills/egbe-os-playbook/playbooks/product/value.md +91 -0
  243. package/skills/egbe-os-playbook/playbooks/product.md +67 -0
  244. package/skills/egbe-os-playbook/references/catalog.md +127 -0
  245. package/skills/egbe-os-playbook/references/changes.md +167 -0
  246. package/skills/egbe-os-playbook/scripts/playbook-changes.py +6 -0
  247. package/skills/egbe-os-playbook/scripts/playbook_changes/__init__.py +1 -0
  248. package/skills/egbe-os-playbook/scripts/playbook_changes/cli.py +57 -0
  249. package/skills/egbe-os-playbook/scripts/playbook_changes/operations.py +137 -0
  250. package/skills/egbe-os-playbook/scripts/playbook_changes/protocol.py +132 -0
  251. package/skills/egbe-os-playbook/scripts/playbook_changes/storage.py +180 -0
  252. package/skills/egbe-os-playbook/scripts/playbook_changes/transport.py +113 -0
  253. package/skills/egbe-os-product-auth/SKILL.md +151 -0
  254. package/skills/egbe-os-product-auth/agents/openai.yaml +4 -0
  255. package/skills/egbe-os-product-auth/assets/db/README.md +102 -0
  256. package/skills/egbe-os-product-auth/assets/db/create-validation-session.mjs +223 -0
  257. package/skills/egbe-os-product-auth/assets/db/migrate.mjs +64 -0
  258. package/skills/egbe-os-product-auth/assets/db/migrations/0001_auth.sql +33 -0
  259. package/skills/egbe-os-product-auth/assets/db/migrations/0002_auth_identities.sql +16 -0
  260. package/skills/egbe-os-product-auth/assets/scaffolds/product-auth-database/AGENTS.append.md +17 -0
  261. package/skills/egbe-os-product-auth/assets/scaffolds/product-auth-database/package.fragment.json +10 -0
  262. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/AGENTS.append.md +9 -0
  263. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/package.fragment.json +13 -0
  264. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/db.ts +31 -0
  265. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/identity.ts +94 -0
  266. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/index.ts +3 -0
  267. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/session.ts +91 -0
  268. package/skills/egbe-os-product-auth/references/contracts/live-auth-interface.md +108 -0
  269. package/skills/egbe-os-product-auth/references/frameworks/nextjs.md +34 -0
  270. package/skills/egbe-os-product-auth/references/security/session-and-credentials.md +73 -0
  271. package/skills/egbe-os-product-auth/references/ux/auth-experience.md +58 -0
  272. package/skills/egbe-os-product-auth/references/workflows/account-recovery.md +22 -0
  273. package/skills/egbe-os-product-auth/references/workflows/build-auth.md +212 -0
  274. package/skills/egbe-os-product-auth/references/workflows/google.md +34 -0
  275. package/skills/egbe-os-product-auth/references/workflows/passwordless-email.md +65 -0
  276. package/skills/egbe-os-product-build/SKILL.md +111 -0
  277. package/skills/egbe-os-product-build/agents/openai.yaml +4 -0
  278. package/skills/egbe-os-product-build/references/capabilities.md +25 -0
  279. package/skills/egbe-os-product-build/references/engineering.md +72 -0
  280. package/skills/egbe-os-product-build/references/execution.md +55 -0
  281. package/skills/egbe-os-product-build/references/foundations.md +93 -0
  282. package/skills/egbe-os-product-build/references/interface-quality.md +32 -0
  283. package/skills/egbe-os-product-build/references/workflows/private-review-handoff.md +86 -0
  284. package/skills/egbe-os-product-build/scripts/scaffold.py +296 -0
  285. package/skills/egbe-os-product-demo-video/SKILL.md +118 -0
  286. package/skills/egbe-os-product-demo-video/references/recording.md +32 -0
  287. package/skills/egbe-os-product-market-research/SKILL.md +159 -0
  288. package/skills/egbe-os-product-market-research/agents/openai.yaml +4 -0
  289. package/skills/egbe-os-product-market-research/references/catalog.v1.json +177 -0
  290. package/skills/egbe-os-product-market-research/references/config/channel-footprint-sources.v1.json +99 -0
  291. package/skills/egbe-os-product-market-research/references/config/creative-taxonomy.v1.json +367 -0
  292. package/skills/egbe-os-product-market-research/references/contracts/creative-video.md +75 -0
  293. package/skills/egbe-os-product-market-research/references/contracts/funnel-teardown.md +235 -0
  294. package/skills/egbe-os-product-market-research/references/contracts/geography-comparison.md +71 -0
  295. package/skills/egbe-os-product-market-research/references/contracts/lifecycle-capture.md +119 -0
  296. package/skills/egbe-os-product-market-research/references/contracts/research-artifacts.md +520 -0
  297. package/skills/egbe-os-product-market-research/references/contracts/walk-mechanics.v2.json +18 -0
  298. package/skills/egbe-os-product-market-research/references/prompts/acquisition-channels.md +137 -0
  299. package/skills/egbe-os-product-market-research/references/prompts/acquisition-channels.user.md +4 -0
  300. package/skills/egbe-os-product-market-research/references/prompts/competitive-landscape.md +118 -0
  301. package/skills/egbe-os-product-market-research/references/prompts/competitive-landscape.user.md +4 -0
  302. package/skills/egbe-os-product-market-research/references/prompts/demand-validation.md +154 -0
  303. package/skills/egbe-os-product-market-research/references/prompts/demand-validation.user.md +4 -0
  304. package/skills/egbe-os-product-market-research/references/prompts/market-size-and-dynamics.md +100 -0
  305. package/skills/egbe-os-product-market-research/references/prompts/market-size-and-dynamics.user.md +4 -0
  306. package/skills/egbe-os-product-market-research/references/prompts/pricing-and-monetization.md +126 -0
  307. package/skills/egbe-os-product-market-research/references/prompts/pricing-and-monetization.user.md +4 -0
  308. package/skills/egbe-os-product-market-research/references/prompts/target-audience.md +98 -0
  309. package/skills/egbe-os-product-market-research/references/prompts/target-audience.user.md +4 -0
  310. package/skills/egbe-os-product-market-research/references/prompts/unit-economics.md +217 -0
  311. package/skills/egbe-os-product-market-research/references/prompts/unit-economics.user.md +4 -0
  312. package/skills/egbe-os-product-market-research/references/prompts/value-proposition.md +113 -0
  313. package/skills/egbe-os-product-market-research/references/prompts/value-proposition.user.md +4 -0
  314. package/skills/egbe-os-product-market-research/references/workflows/acquisition-channels.md +27 -0
  315. package/skills/egbe-os-product-market-research/references/workflows/channel-footprint.md +163 -0
  316. package/skills/egbe-os-product-market-research/references/workflows/community-demand.md +100 -0
  317. package/skills/egbe-os-product-market-research/references/workflows/competitive-landscape.md +27 -0
  318. package/skills/egbe-os-product-market-research/references/workflows/competitor-ads.md +82 -0
  319. package/skills/egbe-os-product-market-research/references/workflows/competitor-set.md +300 -0
  320. package/skills/egbe-os-product-market-research/references/workflows/creative-patterns.md +228 -0
  321. package/skills/egbe-os-product-market-research/references/workflows/demand-validation.md +27 -0
  322. package/skills/egbe-os-product-market-research/references/workflows/fleet-prior.md +80 -0
  323. package/skills/egbe-os-product-market-research/references/workflows/funnel-teardown.md +184 -0
  324. package/skills/egbe-os-product-market-research/references/workflows/geography-comparison.md +84 -0
  325. package/skills/egbe-os-product-market-research/references/workflows/keyword-economics.md +122 -0
  326. package/skills/egbe-os-product-market-research/references/workflows/lifecycle-capture.md +218 -0
  327. package/skills/egbe-os-product-market-research/references/workflows/local-research.md +55 -0
  328. package/skills/egbe-os-product-market-research/references/workflows/market-size-and-dynamics.md +27 -0
  329. package/skills/egbe-os-product-market-research/references/workflows/preview.md +175 -0
  330. package/skills/egbe-os-product-market-research/references/workflows/pricing-and-monetization.md +27 -0
  331. package/skills/egbe-os-product-market-research/references/workflows/recommendations.md +35 -0
  332. package/skills/egbe-os-product-market-research/references/workflows/review-mining.md +76 -0
  333. package/skills/egbe-os-product-market-research/references/workflows/target-audience.md +27 -0
  334. package/skills/egbe-os-product-market-research/references/workflows/tiktok-reels-market-trends.md +46 -0
  335. package/skills/egbe-os-product-market-research/references/workflows/unit-economics.md +27 -0
  336. package/skills/egbe-os-product-market-research/references/workflows/value-proposition.md +27 -0
  337. package/skills/egbe-os-product-market-research/scripts/build-organic-trend-context.py +167 -0
  338. package/skills/egbe-os-product-market-research/scripts/build-preview-context.py +91 -0
  339. package/skills/egbe-os-product-market-research/scripts/build-research-query.py +225 -0
  340. package/skills/egbe-os-product-market-research/scripts/channel-footprint-model.py +294 -0
  341. package/skills/egbe-os-product-market-research/scripts/connection_identity.py +22 -0
  342. package/skills/egbe-os-product-market-research/scripts/creative-model.py +364 -0
  343. package/skills/egbe-os-product-market-research/scripts/creative-selection.py +113 -0
  344. package/skills/egbe-os-product-market-research/scripts/creative-semantics.py +365 -0
  345. package/skills/egbe-os-product-market-research/scripts/creative-video.py +542 -0
  346. package/skills/egbe-os-product-market-research/scripts/egbe_artifacts.py +24 -0
  347. package/skills/egbe-os-product-market-research/scripts/finalize-organic-trend-watch.py +304 -0
  348. package/skills/egbe-os-product-market-research/scripts/funnel-email-review.py +97 -0
  349. package/skills/egbe-os-product-market-research/scripts/funnel-model.py +966 -0
  350. package/skills/egbe-os-product-market-research/scripts/funnel_features.py +50 -0
  351. package/skills/egbe-os-product-market-research/scripts/geography-comparison-contract.py +172 -0
  352. package/skills/egbe-os-product-market-research/scripts/geography-comparison.py +169 -0
  353. package/skills/egbe-os-product-market-research/scripts/keyword-forecast.py +61 -0
  354. package/skills/egbe-os-product-market-research/scripts/keyword-locale-publication.py +136 -0
  355. package/skills/egbe-os-product-market-research/scripts/lifecycle-start.py +190 -0
  356. package/skills/egbe-os-product-market-research/scripts/persist-research-report.py +63 -0
  357. package/skills/egbe-os-product-market-research/scripts/research-artifact-io.py +281 -0
  358. package/skills/egbe-os-product-market-research/scripts/research-evidence.py +496 -0
  359. package/skills/egbe-os-product-market-research/scripts/research-policy.py +33 -0
  360. package/skills/egbe-os-product-market-research/scripts/research-section-runtime.py +343 -0
  361. package/skills/egbe-os-product-market-research/scripts/research-section-workflow.py +288 -0
  362. package/skills/egbe-os-product-market-research/scripts/research_integrity.py +122 -0
  363. package/skills/egbe-os-product-market-research/scripts/review-research-completion.py +306 -0
  364. package/skills/egbe-os-product-market-research/scripts/run-acquisition-channels.py +72 -0
  365. package/skills/egbe-os-product-market-research/scripts/run-channel-footprint.py +2258 -0
  366. package/skills/egbe-os-product-market-research/scripts/run-community-demand.py +1603 -0
  367. package/skills/egbe-os-product-market-research/scripts/run-competitive-landscape.py +66 -0
  368. package/skills/egbe-os-product-market-research/scripts/run-competitor-ads.py +1156 -0
  369. package/skills/egbe-os-product-market-research/scripts/run-competitor-set.py +2514 -0
  370. package/skills/egbe-os-product-market-research/scripts/run-creative-patterns.py +2042 -0
  371. package/skills/egbe-os-product-market-research/scripts/run-demand-validation.py +72 -0
  372. package/skills/egbe-os-product-market-research/scripts/run-fleet-prior.py +652 -0
  373. package/skills/egbe-os-product-market-research/scripts/run-funnel-teardown.py +493 -0
  374. package/skills/egbe-os-product-market-research/scripts/run-keyword-economics.py +1443 -0
  375. package/skills/egbe-os-product-market-research/scripts/run-lifecycle-capture.py +1543 -0
  376. package/skills/egbe-os-product-market-research/scripts/run-market-size-and-dynamics.py +66 -0
  377. package/skills/egbe-os-product-market-research/scripts/run-os-research.py +311 -0
  378. package/skills/egbe-os-product-market-research/scripts/run-pricing-and-monetization.py +71 -0
  379. package/skills/egbe-os-product-market-research/scripts/run-review-mining.py +1051 -0
  380. package/skills/egbe-os-product-market-research/scripts/run-target-audience.py +66 -0
  381. package/skills/egbe-os-product-market-research/scripts/run-unit-economics.py +71 -0
  382. package/skills/egbe-os-product-market-research/scripts/run-value-proposition.py +67 -0
  383. package/skills/egbe-os-product-market-research/scripts/upsert-markdown-section.py +156 -0
  384. package/skills/egbe-os-product-market-research/scripts/walk-funnels.py +249 -0
  385. package/skills/egbe-os-product-market-research/scripts/write-preview.py +710 -0
  386. package/skills/egbe-os-product-market-research/scripts/write-recommendations.py +272 -0
  387. package/skills/egbe-os-product-report/SKILL.md +150 -0
  388. package/skills/egbe-os-product-report/references/artifacts.md +84 -0
  389. package/skills/egbe-os-product-report/references/brief.md +34 -0
  390. package/skills/egbe-os-product-report/references/daily.md +76 -0
  391. package/skills/egbe-os-product-report/references/sources.md +68 -0
  392. package/skills/egbe-os-product-routines/SKILL.md +166 -0
  393. package/skills/egbe-os-product-routines/references/catalog.md +22 -0
  394. package/skills/egbe-os-product-routines/references/continuation-check.md +41 -0
  395. package/skills/egbe-os-product-routines/references/product-reporting.md +163 -0
  396. package/skills/egbe-os-product-routines/references/run-preset.md +32 -0
  397. package/skills/egbe-os-quickstart/scripts/egbe-curl.py +357 -0
  398. package/skills/egbe-os-quiz-funnel/SKILL.md +152 -0
  399. package/skills/egbe-os-quiz-funnel/agents/openai.yaml +4 -0
  400. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-engine.d.mts +224 -0
  401. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-engine.mjs +652 -0
  402. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-engine.test.mjs +764 -0
  403. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-history.d.mts +31 -0
  404. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-history.mjs +87 -0
  405. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-history.test.mjs +265 -0
  406. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-reference.test.mjs +254 -0
  407. package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/QUIZ.md +195 -0
  408. package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/quiz.json +421 -0
  409. package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/quiz.public.json +369 -0
  410. package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/validation.json +21 -0
  411. package/skills/egbe-os-quiz-funnel/assets/reference/index.html +26 -0
  412. package/skills/egbe-os-quiz-funnel/assets/reference/quiz-bootstrap.js +31 -0
  413. package/skills/egbe-os-quiz-funnel/assets/reference/quiz-early-actions.mjs +11 -0
  414. package/skills/egbe-os-quiz-funnel/assets/reference/quiz-first-screen.mjs +32 -0
  415. package/skills/egbe-os-quiz-funnel/assets/reference/quiz-page.mjs +480 -0
  416. package/skills/egbe-os-quiz-funnel/assets/reference/quiz.css +264 -0
  417. package/skills/egbe-os-quiz-funnel/references/competitor-teardown.md +159 -0
  418. package/skills/egbe-os-quiz-funnel/references/conversion-handoff.md +156 -0
  419. package/skills/egbe-os-quiz-funnel/references/implementation.md +207 -0
  420. package/skills/egbe-os-quiz-funnel/references/inputs.md +37 -0
  421. package/skills/egbe-os-quiz-funnel/references/measurement.md +122 -0
  422. package/skills/egbe-os-quiz-funnel/references/spec-contract.md +335 -0
  423. package/skills/egbe-os-quiz-funnel/references/verification.md +101 -0
  424. package/skills/egbe-os-quiz-funnel/references/walk-mechanics.v2.json +18 -0
  425. package/skills/egbe-os-quiz-funnel/scripts/compile-quiz-spec.py +1869 -0
  426. package/skills/egbe-os-quiz-funnel/scripts/prepare-research-identity.py +66 -0
  427. package/skills/egbe-os-reddit-ads/SKILL.md +121 -0
  428. package/skills/egbe-os-reddit-ads/assets/static-banners/bold-statement/schema.json +41 -0
  429. package/skills/egbe-os-reddit-ads/assets/static-banners/bold-statement/template.html +106 -0
  430. package/skills/egbe-os-reddit-ads/assets/static-banners/data-proof/schema.json +61 -0
  431. package/skills/egbe-os-reddit-ads/assets/static-banners/data-proof/template.html +151 -0
  432. package/skills/egbe-os-reddit-ads/assets/static-banners/honest-breakdown/schema.json +91 -0
  433. package/skills/egbe-os-reddit-ads/assets/static-banners/honest-breakdown/template.html +185 -0
  434. package/skills/egbe-os-reddit-ads/assets/static-banners/question-hook/schema.json +51 -0
  435. package/skills/egbe-os-reddit-ads/assets/static-banners/question-hook/template.html +121 -0
  436. package/skills/egbe-os-reddit-ads/assets/static-banners/reddit-post-style/schema.json +87 -0
  437. package/skills/egbe-os-reddit-ads/assets/static-banners/reddit-post-style/template.html +212 -0
  438. package/skills/egbe-os-reddit-ads/references/creative/html-to-png-pipeline.md +123 -0
  439. package/skills/egbe-os-reddit-ads/references/creative/static-banner-qa.md +12 -0
  440. package/skills/egbe-os-reddit-ads/references/creative/static-banner-system.md +16 -0
  441. package/skills/egbe-os-reddit-ads/references/destination-requirements.md +36 -0
  442. package/skills/egbe-os-reddit-ads/references/runtime/api-reference.md +435 -0
  443. package/skills/egbe-os-reddit-ads/references/runtime/artifacts.md +57 -0
  444. package/skills/egbe-os-reddit-ads/references/runtime/monitoring.md +64 -0
  445. package/skills/egbe-os-reddit-ads/references/runtime/pixel-and-tracking.md +49 -0
  446. package/skills/egbe-os-reddit-ads/references/runtime/policies.md +19 -0
  447. package/skills/egbe-os-reddit-ads/references/runtime/shared-analytics-attribution.md +14 -0
  448. package/skills/egbe-os-reddit-ads/references/workflows/build-paused.md +35 -0
  449. package/skills/egbe-os-reddit-ads/references/workflows/launch-ready.md +19 -0
  450. package/skills/egbe-os-reddit-ads/references/workflows/launch.md +32 -0
  451. package/skills/egbe-os-reddit-ads/references/workflows/readiness.md +9 -0
  452. package/skills/egbe-os-reddit-ads/scripts/capture-ad.sh +178 -0
  453. package/skills/egbe-os-reddit-ads/scripts/validate-reddit-artifacts.py +187 -0
  454. package/skills/egbe-os-report-ui/SKILL.md +133 -0
  455. package/skills/egbe-os-report-ui/assets/egbe-wordmark.svg +9 -0
  456. package/skills/egbe-os-report-ui/assets/examples/components.html +417 -0
  457. package/skills/egbe-os-report-ui/assets/examples/editorial.html +209 -0
  458. package/skills/egbe-os-report-ui/assets/scaffold.html +179 -0
  459. package/skills/egbe-os-report-ui/references/components.md +209 -0
  460. package/skills/egbe-os-research/SKILL.md +125 -0
  461. package/skills/egbe-os-saas-unit-economics/SKILL.md +188 -0
  462. package/skills/egbe-os-scrape/SKILL.md +160 -0
  463. package/skills/egbe-os-search/SKILL.md +182 -0
  464. package/skills/egbe-os-search/references/google-places.md +81 -0
  465. package/skills/egbe-os-support/SKILL.md +149 -0
  466. package/skills/egbe-os-telemetry/SKILL.md +344 -0
  467. package/skills/egbe-os-telemetry/references/harnesses/claude-code.md +97 -0
  468. package/skills/egbe-os-telemetry/references/harnesses/codex.md +22 -0
  469. package/skills/egbe-os-telemetry/references/harnesses/hermes.md +39 -0
  470. package/skills/egbe-os-telemetry/references/harnesses/openclaw.md +139 -0
  471. package/skills/egbe-os-telemetry/references/harnesses/opencode.md +28 -0
  472. package/skills/egbe-os-tools/SKILL.md +180 -0
  473. package/skills/egbe-os-tools/references/theona.md +26 -0
  474. package/skills/egbe-os-wallet/SKILL.md +181 -0
  475. package/skills/egbe-setup/EGBE.md +484 -0
  476. package/skills/egbe-setup/SKILL.md +116 -0
  477. package/skills/egbe-setup/references/project.md +80 -0
  478. package/state.js +37 -0
  479. package/update.js +361 -0
@@ -0,0 +1,128 @@
1
+ # Delivery state, launch and pause
2
+
3
+ Use the returned campaign ref and current provider state. Do not infer that a
4
+ campaign is live from a successful write or an ENABLED campaign flag.
5
+
6
+ ## Inspect
7
+
8
+ ```http
9
+ GET /ads/google/campaigns/{ref}/children
10
+ GET /ads/google/campaigns/{ref}/readback?expect=ENABLED
11
+ ```
12
+
13
+ Children returns the current campaign, geo_targets, ad_groups, keywords,
14
+ negative_keywords, ads and responsive_search_ads under `data.raw`.
15
+ Readback adds `data.delivering` and `data.drift` (also in raw).
16
+
17
+ `delivering: true` means the campaign can serve and at least one complete
18
+ group → one of its keywords → one of its ads is ENABLED and eligible according
19
+ to Google's primary_status. It is capability to serve, not proof impressions
20
+ have already occurred. PENDING review or NOT_ELIGIBLE ads cannot establish that
21
+ path. Intentionally paused siblings do not block a different eligible path.
22
+
23
+ Drift identifies concrete blockers, including level, ID, status, expected status,
24
+ group and primary_status when relevant. If delivering is absent/null, state is
25
+ unconfirmed, not false or true.
26
+
27
+ Compare the observed objects, destinations, targeting and budget with the intended
28
+ operation. Unexpected serving objects or another product's destination require
29
+ attention, not silent adoption or broad activation. Report them and follow the
30
+ user's stop instructions.
31
+
32
+ ## Launch or resume
33
+
34
+ ```http
35
+ POST /ads/google/campaigns/{ref}/launch
36
+ Content-Type: application/json
37
+ ```
38
+
39
+ ```json
40
+ {"children":"auto"}
41
+ ```
42
+
43
+ Check the current paused campaign, serving inputs and destination against the
44
+ authorized activation scope. This operation does not create missing objects.
45
+
46
+ The provider applies the selected campaign/child status changes in one atomic
47
+ mutation. Child modes are:
48
+
49
+ - `auto` (default): enable children only if there is no CONFIGURED ENABLED
50
+ group → keyword → ad path. This test is about status, not review eligibility;
51
+ an enabled but pending-review path still preserves all current child choices.
52
+ - `keep`: change only the campaign flag; preserve every child as-is. Use this
53
+ for a requested resume that must not re-enable intentionally paused children,
54
+ including when all serving paths were paused.
55
+ - `activate`: explicitly enable all nonremoved groups, positive keywords and
56
+ ads. This is broad activation, not a substitute for a selected keyword/ad edit.
57
+
58
+ Negative keywords have no serving status and are not changed. If auto finds no
59
+ configured path, it can enable every child, including previously paused ones:
60
+ choose the mode from the actual intended change, not just the endpoint default.
61
+
62
+ The launch response carries delivering/drift. Independently verify
63
+ `GET .../readback?expect=ENABLED`. Report pending review as pending, not live.
64
+ Structural PAUSED/missing-object drift needs a scoped repair; it does not justify
65
+ blind campaign-wide activation. Preserve deliberately disabled objects.
66
+
67
+ ## Pause
68
+
69
+ ```http
70
+ POST /ads/google/campaigns/{ref}/pause
71
+ GET /ads/google/campaigns/{ref}/readback?expect=PAUSED
72
+ ```
73
+
74
+ Pause changes the campaign only. Enabled children under a paused campaign are
75
+ harmless and are NOT drift for expect=PAUSED; do not spend extra writes pausing
76
+ them. The default readback expectation is ENABLED, so use PAUSED explicitly.
77
+
78
+ The pause response says whether fresh provider state confirms the stop:
79
+
80
+ - `data.status_confirmed: true`, `confirmation: "readback"`: the campaign's
81
+ configured status reads PAUSED. This also settles a pause request that itself
82
+ failed (`write_outcome` `unknown` or `rejected`, details in `write_error`);
83
+ do not resend it.
84
+ - `status_confirmed: false`, `confirmation: "pause_not_confirmed"`: the stop is
85
+ not established. `configured_status` is what the readback showed, or null when
86
+ it failed (`readback_error`). A failed request keeps its HTTP error status with
87
+ `data.error: "pause_not_confirmed"`. Treat the campaign as possibly serving and
88
+ follow `data.next_action`.
89
+
90
+ Pausing an already paused campaign changes nothing, so resending a pause after
91
+ `pause_not_confirmed` cannot enable anything; it does use mutate quota. Prefer a
92
+ fresh `readback?expect=PAUSED` first when the failure was temporary.
93
+
94
+ Record a successful pause's actual confirmation time, not a planned deadline.
95
+ If the cause of a confirmed stop is unknown, say unknown rather than infer
96
+ manual stop or budget exhaustion. A failed pause or stopped monitor is not
97
+ proof the campaign stopped. Preserve the observed reason in the campaign result
98
+ rather than replacing it when balances or time later change.
99
+
100
+ Launch/pause have no durable idempotency receipt through these routes. Repeating
101
+ campaign status still sends a mutation and uses quota. A failed post-write
102
+ readback can return delivering=null after successful mutation. After an uncertain
103
+ launch response, read state and reconcile before repeating the requested change.
104
+
105
+ ## Set all child statuses
106
+
107
+ ```http
108
+ POST /ads/google/campaigns/{ref}/children/status
109
+ Content-Type: application/json
110
+ ```
111
+
112
+ ```json
113
+ {"status":"PAUSED"}
114
+ ```
115
+
116
+ This changes every nonremoved group, positive keyword and ad, not just missing
117
+ or newly created objects. It does not change the campaign. Use only when that
118
+ whole scope is intended; use [Search asset controls](search-assets.md) for exact
119
+ keywords or one RSA. Matching child statuses skip provider work/quota increment.
120
+ There is no durable operation receipt. The response is mutation results, not a
121
+ post-write delivery verdict; obtain fresh readback afterwards. Never replay an
122
+ old enable after a later intentional pause.
123
+
124
+ ## State versus performance
125
+
126
+ Read metrics using [Reporting](reporting.md); a fresh configuration check is not
127
+ a campaign performance result. These launch routes do not install a total-spend
128
+ cap, future pause or monitoring job.
@@ -0,0 +1,40 @@
1
+ # Keyword ideas
2
+
3
+ Use `POST /ads/google/keyword-ideas` to read provider keyword suggestions and
4
+ historical metrics. This operation does not create campaign keywords.
5
+
6
+ ```http
7
+ POST /ads/google/keyword-ideas
8
+ Content-Type: application/json
9
+ ```
10
+
11
+ ```json
12
+ {
13
+ "keywords": ["contract review software"],
14
+ "pageUrl": "https://product.example",
15
+ "geoTargets": ["geoTargetConstants/2826"],
16
+ "language": "languageConstants/1000"
17
+ }
18
+ ```
19
+
20
+ Use the requested seeds and market, not this example.
21
+ At least keywords or pageUrl is needed. There are three distinct seed modes:
22
+ keywords only, URL only, and combined keyword-and-URL. A keyword-only response
23
+ may repeat the submitted seeds without useful expansion; URL ideas can be
24
+ generic. Do not invent missing ideas. Supplying both uses the combined seed,
25
+ not two independently aggregated queries.
26
+
27
+ Supply geo constants and language deliberately. The provider currently defaults
28
+ an omitted/empty geography to the US and omitted language to English. This is
29
+ an API default, not a recommendation or a campaign-targeting setting. Keyword
30
+ research does not apply locations to a campaign.
31
+
32
+ The OS response includes `data.ideas` and the provider response in `data.raw`.
33
+ Retain relevant rows with their query, geography/language, source and retrieval
34
+ time. No separate keyword-plan file is required.
35
+
36
+ Historical search volume and top-of-page low/high bids describe the provider's
37
+ observed market. Read monetary units as returned; micros are millionths of the
38
+ account currency, not an FX conversion. Historical bid ranges are not a
39
+ guaranteed actual CPC, traffic forecast or executable starting bid. The endpoint
40
+ does not set a bid or campaign budget.
@@ -0,0 +1,105 @@
1
+ # Performance, diagnostics and product attribution
2
+
3
+ Reporting is read-only. Use the requested date range and exact campaign ref;
4
+ these calls do not change bids, budget, targeting or delivery.
5
+
6
+ ## Campaign results
7
+
8
+ ```http
9
+ GET /ads/google/campaigns/{ref}/results?period=TODAY
10
+ GET /ads/google/campaigns/{ref}/results?date_from=2026-01-01&date_to=2026-01-31
11
+ ```
12
+
13
+ Choose either a period (TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS) or both dates,
14
+ not both forms. Omission defaults to LAST_30_DAYS, excluding today. Dates are
15
+ inclusive account-local calendar dates, ordered, at most 366 days and not in the
16
+ future. TODAY includes the whole account-local day, not only time since a bid
17
+ change. Keep a timestamped baseline when a before/after comparison is needed.
18
+
19
+ Read `data.metrics`, resolved dates, account timezone, `data_status`,
20
+ `retrieved_at` and `freshness`. Monetary amounts use the returned currency,
21
+ not assumed USD. Same-day figures can lag; fetch time is not a completeness
22
+ watermark. Actual reported zero, no_rows, missing metric and failed query are
23
+ different states. Never replace unknown/missing values or errors with zero.
24
+
25
+ Search impression share fields in metrics are ratios, not percentages or counts:
26
+
27
+ - `search_impression_share`: received / estimated eligible Search impressions.
28
+ - `search_rank_lost_impression_share`: estimated share lost to Ad Rank.
29
+ - `search_budget_lost_impression_share`: estimated share lost to budget.
30
+
31
+ Inspect `data.metric_availability[field]`. Available values may genuinely be
32
+ zero. Unavailable values are null with a reason such as not_reported, no_rows or
33
+ invalid_provider_value. Below_threshold means share <10%; above_threshold means
34
+ the relevant lost share >90%, with the boundary in `threshold`.
35
+ These bounded values are null, not exact measurements. Raw provider sentinels
36
+ 0.0999/0.9001 must not become exact 9.99%/90.01% claims. Unit is ratio.
37
+
38
+ Overall data_status=available describes the basic metrics; individual share
39
+ metrics can still be unavailable. Search shares update daily and can lag 1–2
40
+ days. Unknown freshness.provider_data_through does not establish completeness.
41
+
42
+ ## Search terms and current diagnostics
43
+
44
+ ```http
45
+ GET /ads/google/campaigns/{ref}/search-terms?period=LAST_30_DAYS
46
+ GET /ads/google/campaigns/{ref}/diagnostics
47
+ GET /ads/google/campaigns/{ref}/children
48
+ ```
49
+
50
+ Search terms uses its own period query; do not assume the campaign results
51
+ date_from/date_to interface exists on it. Its provider response is in
52
+ `data.raw`. Record unavailable term evidence; raw GAQL is not an exposed
53
+ alternative. Diagnostics returns directly in `data`:
54
+
55
+ - Campaign status, primary_status, primary_status_reasons and availability.
56
+ A valid empty reason list differs from unavailable; UNKNOWN remains unknown.
57
+ - Configured/effective keyword CPC and inheritance source; absent/inherited
58
+ configured bids are not zero.
59
+ - Ad review/approval and policy topics.
60
+ - Current keyword quality_info: quality_score (1–10), expected_ctr,
61
+ ad_relevance and landing_page_experience. Components use ABOVE_AVERAGE,
62
+ AVERAGE or BELOW_AVERAGE when reported.
63
+ - Per-field availability, nulls and reasons not_reported, unspecified, unknown
64
+ or invalid_provider_value; raw_value can retain a provider sentinel.
65
+ - UTC retrieved_at and account currency/timezone.
66
+
67
+ Current quality_info differs from historical quality metrics in term reports.
68
+ An unavailable overall score does not erase available components, and missing
69
+ historical data does not prove that current scores are absent. A failure is
70
+ an error, not an empty list. LIMITED/BUDGET_CONSTRAINED and quality buckets are
71
+ provider diagnostics, not product-sales measurements.
72
+
73
+ For delivery status use [Delivery](delivery.md). An eligible enabled path,
74
+ observed impressions and campaign-attributed product outcomes are different
75
+ pieces of evidence.
76
+
77
+ ## Product analytics
78
+
79
+ Read the current analytics capability and canonical events:
80
+
81
+ ```http
82
+ GET /analytics/skill
83
+ GET /analytics/events
84
+ GET /analytics/{product_slug}/tracking
85
+ GET /analytics/{product_slug}/campaigns?period=all
86
+ GET /analytics/{product_slug}/stats?period=24h
87
+ ```
88
+
89
+ Preserve the campaign's stable attribution: utm_source=google,
90
+ utm_medium=paid_search, utm_campaign equal to its channel-qualified slug,
91
+ useful utm_content and utm_term when available. These are not product event names
92
+ or experiment IDs. Keep existing durable business/product/launch/experiment/
93
+ variant identity separate when supplied; do not invent it or change it to fit
94
+ a campaign name.
95
+
96
+ Use canonical events from /analytics/events, not new channel-specific event
97
+ names. Do not emit synthetic product events to prove readiness. Google clicks
98
+ are not product visits or conversions. If only site-wide product signals are
99
+ available, label them non-attributed; never present them as exact campaign
100
+ outcomes. Missing tracking, unavailable metrics and pending data are not zeros.
101
+
102
+ Label saved observations with their actual date when live reads are unavailable;
103
+ they are not current provider state. Preserve useful results as described in
104
+ [Campaign records](artifacts.md). For metrics of one conversion action, see
105
+ [Conversions](conversions.md).
@@ -0,0 +1,219 @@
1
+ # Search objects and ads
2
+
3
+ Read the selected campaign's `/children` before adding or changing objects.
4
+ Use returned IDs and preserve unrelated objects. These operations require owned
5
+ campaign/group targets and configured mutation quota; credentials alone do not
6
+ authorize new advertising.
7
+
8
+ ## Create Search assets
9
+
10
+ ```http
11
+ POST /ads/google/campaigns/{ref}/search-assets
12
+ Idempotency-Key: <stable key for this exact batch>
13
+ Content-Type: application/json
14
+ ```
15
+
16
+ ```json
17
+ {
18
+ "geoTargets": ["geoTargetConstants/2840"],
19
+ "adGroups": [{
20
+ "name": "Contract review",
21
+ "cpcBidMicros": 2500000,
22
+ "status": "PAUSED",
23
+ "keywords": [{"text": "contract review software", "matchType": "PHRASE", "status": "PAUSED"}],
24
+ "negativeKeywords": [{"text": "login", "matchType": "PHRASE"}],
25
+ "responsiveSearchAds": [{
26
+ "finalUrls": ["https://product.example/?utm_source=google&utm_medium=paid_search&utm_campaign=google-search-001&utm_content=contract-review"],
27
+ "headlines": ["Review Contracts Faster", "Find Risky Clauses", "Clear Contract Insights"],
28
+ "descriptions": ["Check contract risks before signing.", "Review legal documents with clear next steps."],
29
+ "status": "PAUSED"
30
+ }]
31
+ }]
32
+ }
33
+ ```
34
+
35
+ All choices are illustrative. During new-campaign preparation, create serving
36
+ objects PAUSED. For additions to an existing campaign, use the status required
37
+ by the authorized operation. Never create real objects, even PAUSED ones, or
38
+ enable objects merely to probe an API schema. Resolve an unclear request format
39
+ before sending a write. A new campaign needs explicit intended geo criteria and
40
+ complete groups, keywords, ads and destinations before launch.
41
+
42
+ This endpoint performs budget/geos/groups/keywords/negatives/ads sequentially,
43
+ not atomically. A failure may leave earlier objects created; releasing a wallet
44
+ hold does not roll them back. `adGroups[].id` selects an existing group rather
45
+ than upserting it. The current schema still requires that group's `name` and
46
+ `cpcBidMicros`, but supplying an id does NOT update its name, bid or status.
47
+ Use [campaign bid controls](campaigns.md) for actual bid changes.
48
+
49
+ `prohibited_category_guardrail:<category>` is an Egbe content-filter rejection,
50
+ not a Google moderation result. The filter scans ad copy and positive keywords;
51
+ negative keywords remain exclusions. Explicit completed advice disclaimers such
52
+ as `Estimates only, not medical advice` are allowed, but other prohibited claims
53
+ in the same payload still block the request. Report a suspected false positive
54
+ with the submitted text; do not remove a truthful disclaimer to evade the filter.
55
+ Passing this check does not establish provider approval or category eligibility.
56
+
57
+ Use a key for the exact batch. The successful-response cache is process-local,
58
+ temporary (default 15 minutes) and keyed by key plus payload, not durable
59
+ exactly-once. It does not serialize concurrent requests; changed payload is a
60
+ cache miss, not a guaranteed 409. After a timeout, partial failure, restart or
61
+ cache expiry, read children and reconcile exact IDs/text/match types before
62
+ creating anything else. Never replay a whole uncertain batch blindly.
63
+
64
+ Inspect `data.raw.results` and `data.raw.readback`, then obtain fresh readback.
65
+ Save confirmed IDs before clearing the unfinished operation. Do not substitute
66
+ local desired state for provider evidence.
67
+
68
+ ## Granular creates
69
+
70
+ Use these only for identified missing or intended additional objects:
71
+
72
+ | Endpoint suffix under /ads/google/campaigns/{ref} | Body |
73
+ | --- | --- |
74
+ | POST /geo-targets | `{"geoTargets":["geoTargetConstants/2840"]}` |
75
+ | POST /ad-groups | `{"adGroups":[{"name":"Contract review","cpcBidMicros":2500000,"status":"PAUSED"}]}` |
76
+ | POST /ad-groups/{group}/keywords | `{"keywords":[{"text":"contract review software","matchType":"PHRASE","status":"PAUSED"}]}` |
77
+ | POST /ad-groups/{group}/negative-keywords | `{"negativeKeywords":[{"text":"login","matchType":"PHRASE"}]}` |
78
+ | POST /ad-groups/{group}/responsive-search-ads | `{"responsiveSearchAds":[...]}` using the ad shape above |
79
+
80
+ These are create-only, not upserts. Geo-target reads are available at
81
+ `GET /ads/google/campaigns/{ref}/geo-targets`. Use targeting PATCH for replacing
82
+ targeting categories, not an additive geo POST.
83
+
84
+ Only the positive-keyword POST and combined search-assets currently forward
85
+ Idempotency-Key through OS. Granular geo, group, negative and RSA POSTs do NOT;
86
+ do not assume adding a header protects them from duplicates. After uncertain
87
+ creation reconcile readback before any repeat. The older granular responses
88
+ wrap `results`/`readback` in `data.raw`; positive-keyword creation returns
89
+ those fields directly in `data`.
90
+
91
+ Positive keyword batches accept 1–100 entries. `matchType` is PHRASE (default),
92
+ EXACT or BROAD; use plain text without quote/bracket notation.
93
+ `cpcBidMicros` is a positive integer in account-currency micros; omit or null
94
+ to inherit the group bid. Explicit ENABLED affects only that new keyword and
95
+ must fit the requested operation; it does not enable campaign/group ancestors.
96
+ Explicit group/keyword bids must also satisfy configured gateway CPC bounds;
97
+ do not alter the requested bid just to pass a rejection.
98
+ Negatives have no provider status and remain exclusions; do not try to pause
99
+ them with positive-keyword status or campaign child status.
100
+
101
+ ## Change selected positive keyword statuses
102
+
103
+ ```http
104
+ PATCH /ads/google/campaigns/{ref}/ad-groups/{group}/keywords/status
105
+ Content-Type: application/json
106
+ ```
107
+
108
+ ```json
109
+ {"keyword_ids":["111","222"],"status":"PAUSED"}
110
+ ```
111
+
112
+ Supply 1–100 unique IDs and ENABLED or PAUSED. All must be positive keywords
113
+ in that owned campaign/group; foreign, missing or negative IDs fail before any
114
+ mutation. Other keywords, ancestors, ads, bids and budget remain unchanged.
115
+
116
+ This is desired-state assignment, not replay of an old operation. No key is
117
+ required; matching statuses skip mutation. Do not retry an obsolete instruction
118
+ after a later intentional change. Inspect `data.keywords`, `updated`,
119
+ `readback` and `verified`; on a 409 mismatch inspect children first.
120
+ Verification is not policy approval or proof of impressions.
121
+
122
+ ## Read or edit an existing RSA
123
+
124
+ GET then PATCH the exact owned ad:
125
+
126
+ ```http
127
+ GET /ads/google/campaigns/{ref}/ad-groups/{group}/responsive-search-ads/{ad}
128
+ PATCH /ads/google/campaigns/{ref}/ad-groups/{group}/responsive-search-ads/{ad}
129
+ Idempotency-Key: <stable key for this text change>
130
+ ```
131
+
132
+ ```json
133
+ {
134
+ "headlines": [
135
+ {"text":"Find Your Community","pinned_field":"HEADLINE_1"},
136
+ {"text":"Explore Relevant Groups"},
137
+ {"text":"Start With Your Product"}
138
+ ]
139
+ }
140
+ ```
141
+
142
+ PATCH accepts only headlines and/or descriptions. A supplied list replaces that
143
+ whole list; omit the other to preserve it, do not send null. Headlines: 3–15,
144
+ at most 30 characters each. Descriptions: 2–4, at most 90. Text must be unique
145
+ and nonblank within its list. Google also applies language and policy rules.
146
+
147
+ GET returns text assets with optional `pinned_field`. Preserve pins on retained
148
+ assets; omission/null means unpinned. Headline pins are HEADLINE_1–HEADLINE_3,
149
+ description pins DESCRIPTION_1–DESCRIPTION_2. Creation takes strings rather
150
+ than this PATCH object shape; apply pins to a new paused ad with PATCH.
151
+
152
+ The edit preserves ID, URLs, status, settings, bids and budget. A creative shared
153
+ with another group is rejected to avoid changing other placements. Inspect
154
+ `data.ad`, `verified` and `policy_summary`; edited ads may need review.
155
+ Retry interruption with the same key/payload. On 409 inspect the exact ad and
156
+ diagnostic; do not create replacements or change keys to bypass uncertainty.
157
+
158
+ ## Change one RSA's status or replace it
159
+
160
+ ```http
161
+ PATCH /ads/google/campaigns/{ref}/ad-groups/{group}/responsive-search-ads/{ad}/status
162
+ Idempotency-Key: <stable key for this status change>
163
+ Content-Type: application/json
164
+ ```
165
+
166
+ ```json
167
+ {"status":"ENABLED"}
168
+ ```
169
+
170
+ Only ENABLED/PAUSED is accepted; this changes the selected group/ad association,
171
+ even if the creative is shared. It cannot edit URLs/content, enable ancestors,
172
+ change bids/budget or approve policy. Inspect the exact returned `ad` and
173
+ `verified`. A wallet with depleted/unknown availability blocks a new ENABLED
174
+ mutation; funded holds are respected. PAUSED does not require wallet availability.
175
+ An already-matching status skips provider mutation, wallet admission and quota
176
+ increment. Confirmed mutations have a durable quota receipt.
177
+
178
+ Retry an interrupted status request with the same key and payload for
179
+ reconciliation. Changed payload conflicts; uncertain outcome, drift or a
180
+ readback mismatch may return 409 even after a successful mutation. Inspect the
181
+ exact ad, do not bypass with new keys or resume an obsolete status operation.
182
+
183
+ When replacing an ad is requested, preserve its group, exact destination query,
184
+ copy, pins, targeting and budgets unless the requested change says otherwise.
185
+ Create the replacement PAUSED in the same group, reconcile its exact ID, then
186
+ inspect policy review. Wait for REVIEWED and APPROVED; APPROVED_LIMITED needs
187
+ inspection of policyTopicEntries to establish that restrictions fit the campaign.
188
+ Missing/pending/disapproved data is not approval. Never enable ancestors merely
189
+ to force review or resume a safety stop for this procedure.
190
+
191
+ For the agreed cutover, after acceptable policy review, enable only the replacement
192
+ with the exact status endpoint; verify it, then pause the old ad. Respect any
193
+ additional authorization conditions on the cutover. These two writes are not atomic:
194
+ do not promise zero overlap or delivery. A support ticket or destination approval
195
+ alone is not authorization for advertising writes.
196
+
197
+ ## Destination and attribution
198
+
199
+ Preserve the actual intended destination and query string. Use canonical product
200
+ analytics attribution: `utm_source=google`, `utm_medium=paid_search`, stable
201
+ channel-qualified `utm_campaign`, useful `utm_content` and, when available,
202
+ `utm_term`. Keep `utm_campaign` stable across the plan and product analytics,
203
+ not an unrelated experiment ID. See [Reporting](reporting.md).
204
+
205
+ For a visitor-path audit use the installed destination-readiness skill, available
206
+ at `GET /skills/destination-readiness`. For Google, compare displayed/final/mobile
207
+ domain and actual redirect chain. A later disclosed booking/payment CTA is not
208
+ automatically an initial ad-domain mismatch. Browser success does not prove
209
+ AdsBot or target-region access. A useful page with an external CTA is not
210
+ automatically a prohibited bridge page. Check observed identity, security and
211
+ collection issues against the applicable current official policy, not spelling
212
+ differences between brand and disclosed operator.
213
+
214
+ Policy sources: [destination requirements](https://support.google.com/adspolicy/answer/6368661?hl=en),
215
+ [misleading representation](https://support.google.com/adspolicy/answer/15936666?hl=en),
216
+ [data collection](https://support.google.com/adspolicy/answer/6020956?hl=en).
217
+ Read the relevant current section before attributing a failure. Report exact URL,
218
+ evidence and repair/recheck condition; distinguish visitor defects, policy risk
219
+ and confirmed provider rejection. No local audit grants Google approval.
@@ -0,0 +1,119 @@
1
+ # Server-confirmed conversion delivery
2
+
3
+ Use when a backend confirms the actual outcome, possibly after the browser has
4
+ closed. This is optional; no product scaffold or direct Google credential is
5
+ required. It does not change campaign goals, bidding, budget or status.
6
+
7
+ ## Setup and runtime access
8
+
9
+ Use the agent's ads-scoped access for action discovery/creation and goal changes
10
+ in [Conversions](conversions.md). Choose an enabled owned UPLOAD_CLICKS action
11
+ (created with delivery_method=server). Its tag=null is expected.
12
+
13
+ The deployed product keeps its server-only product-runtime OS_API_KEY.
14
+ The existing analytics scope permits reading a known action, sending
15
+ conversion-events (including validate-only), and reading an owned event receipt.
16
+ These also accept ads but still enforce ownership. Save the selected refs at
17
+ setup; runtime does not need action listing or management. Do not replace its
18
+ key with an agent key or request broad ads access just for delivery.
19
+
20
+ ## Capture and persist the actual outcome
21
+
22
+ Capture the real gclid from the ad arrival and retain it through existing
23
+ attribution/auth/order persistence so the backend can retrieve it after
24
+ redirects, login or browser exit. UTMs are not a GCLID. Never manufacture one.
25
+
26
+ On the authoritative successful outcome, persist an immutable delivery intent:
27
+ stable non-PII transaction_id, real outcome timestamp, campaign/action refs,
28
+ saved click, values and applicable consent state. For payments, use verified
29
+ paid-state transition, not checkout creation, return-page visit or failed payment.
30
+ Repeated webhooks reuse the same outcome ID. Do not block fulfillment on Google.
31
+
32
+ Use the product's existing durable persistence/retry mechanism. Per-user clicks,
33
+ events, delivery intents and receipts belong to product runtime storage, NOT
34
+ Git, campaign.json or the agent's campaign-operation record. Do not use an
35
+ in-memory fire-and-forget call or create a second permanent event system here.
36
+
37
+ ## Validate, then deliver
38
+
39
+ ```http
40
+ POST /ads/google/conversion-events
41
+ Idempotency-Key: <stable key for this outcome>
42
+ Content-Type: application/json
43
+ ```
44
+
45
+ ```json
46
+ {
47
+ "campaign_ref":"1234567890:456",
48
+ "conversion_ref":"1234567890:77",
49
+ "transaction_id":"order-42",
50
+ "gclid":"REPLACE_WITH_SAVED_REAL_GCLID",
51
+ "event_timestamp":"2026-09-08T10:00:00Z",
52
+ "ad_user_data":"CONSENT_GRANTED",
53
+ "ad_personalization":"CONSENT_DENIED",
54
+ "value":19.99,
55
+ "currency":"EUR",
56
+ "validate_only":true
57
+ }
58
+ ```
59
+
60
+ Use actual outcome values. The consent values above illustrate API syntax, not
61
+ a default grant. OS does not collect consent or infer it. Send the product's
62
+ applicable explicit state using CONSENT_GRANTED/CONSENT_DENIED (bare
63
+ GRANTED/DENIED is invalid); denied ad_user_data prevents upload. Do not change
64
+ a denied/unknown state merely to pass validation. Optional ad_personalization
65
+ is never defaulted to granted; DENIED allows measurement without personalization.
66
+ Browser consent-mode syntax is different; do not copy these enums into gtag.
67
+
68
+ Timestamp must include timezone and not be future. Value/currency are optional
69
+ but paired; finite nonnegative amount uses that uppercase ISO currency, not
70
+ implicit USD. transaction_id accepts 1–64 letters, digits, underscore, dot, colon
71
+ or hyphen; never include email or PII. This API supports GCLID, not email/phone
72
+ matching, GBRAID/WBRAID or conversion adjustments.
73
+
74
+ validate_only=true calls Google validation without importing or consuming a real
75
+ receipt. It does not prove attribution. After an authorized actual outcome,
76
+ send the same body with validate_only=false (default). Preserve original values
77
+ on retries. No Google provider token or SDK belongs in the product.
78
+
79
+ ## Receipts and retries
80
+
81
+ HTTP 200 is a receipt response. Inspect `data.status`:
82
+
83
+ - validated: validation only, nothing imported.
84
+ - submitted: Google returned a request ID; processing is not yet verified.
85
+ - retryable: repeat the identical POST after retry_after_seconds. Persist the
86
+ receipt and obey the delay. OS does not run a background resend. An ambiguous
87
+ timeout may already have been accepted; retain the same transaction ID.
88
+ - rejected/exhausted: stop delivery retries and surface receipt, last_error and
89
+ error_fields. The current service allows five attempts with durable backoff.
90
+ Fix configuration/access before retries; do not rotate IDs/keys to bypass it.
91
+
92
+ OS also deduplicates by project/action/transaction when a caller changes its key.
93
+ Changed payload under that transaction or key conflicts. Do not alter timestamp
94
+ or amount during retries or invent a new transaction to bypass an uncertain
95
+ result. Ads management working does not prove separate Data Manager access.
96
+
97
+ ```http
98
+ GET /ads/google/conversion-events/{receipt}
99
+ ```
100
+
101
+ Use the returned OS receipt, not a Google request ID. Diagnostics can report
102
+ processing, processed, failed or partial_success with error/warning reasons and
103
+ counts. status_available=false means diagnostics unavailable, not zero
104
+ conversions. checked_at is status-fetch time, not reporting completeness.
105
+ processed means processing succeeded, NOT proven attribution. Inspect asynchronous
106
+ rejections (including click not found, recent click, duplicates); do not
107
+ automatically mint replacement events.
108
+
109
+ Use the selected-action conversion-report for actual reporting. A secondary
110
+ action may appear in all_conversions rather than conversions unless selected
111
+ in campaign goals. Processing and reporting can lag; do not poll indefinitely.
112
+
113
+ ## Integration checks
114
+
115
+ Verify that an authoritative successful outcome has the saved click and one
116
+ durable intent, and a failed outcome has none. Replay the same webhook/POST and
117
+ confirm the same receipt without another upload. Validate-only must not prevent
118
+ a later real send. Check processing diagnostics and the action report separately.
119
+ A synthetic click or successful HTTP response is not evidence of real attribution.