@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,436 @@
1
+ # Meta Ads OS API Reference
2
+
3
+ Use this file when a Meta workflow needs the exact OS endpoint shape for raw
4
+ Meta operations. This is not a non-OS Meta setup guide.
5
+
6
+ Runtime is OS-only:
7
+
8
+ - `OS_URL`
9
+ - `OS_API_KEY`
10
+ - `Authorization: Bearer $OS_API_KEY`
11
+
12
+ Do not ask a product agent for Meta app IDs, access tokens, page IDs, pixel IDs,
13
+ or ad account IDs. OS owns those server-side.
14
+
15
+ ## Choosing The Endpoint
16
+
17
+ Use normalized endpoints when they cover the job:
18
+
19
+ ```bash
20
+ GET $OS_URL/ads/meta/account
21
+ GET $OS_URL/ads/meta/campaigns
22
+ POST $OS_URL/ads/meta/plan
23
+ POST $OS_URL/ads/meta/apply
24
+ GET $OS_URL/ads/meta/campaigns/{campaign_id}/state
25
+ POST $OS_URL/ads/meta/campaigns/{campaign_id}/launch
26
+ POST $OS_URL/ads/meta/campaigns/{campaign_id}/pause
27
+ GET $OS_URL/ads/meta/campaigns/{campaign_id}/results
28
+ ```
29
+
30
+ For a reused configuration snapshot, add `include_configuration=true` to the
31
+ state read. For current-inclusive campaign history, use `results?period=MAXIMUM`
32
+ or the supported explicit report dates. [Monitoring](../workflows/monitoring.md)
33
+ defines the two-read safety path and native rate-limit context;
34
+ [insights](insights-reference.md) defines query windows, availability and currency.
35
+
36
+ Use raw endpoints when Meta-specific objects are needed:
37
+
38
+ ```bash
39
+ GET $OS_URL/ads/meta/raw/{path}
40
+ POST $OS_URL/ads/meta/raw/{path}
41
+ ```
42
+
43
+ The raw path is still an OS endpoint. It is allowed for Meta-specific resource
44
+ shapes, but it must not be replaced by non-OS calls.
45
+
46
+ ## Targeting Search
47
+
48
+ Use this when a Meta workflow needs platform IDs for interests, behaviors, geo,
49
+ locales, or other targeting categories.
50
+
51
+ ```bash
52
+ GET $OS_URL/ads/meta/raw/targetingsearch?q=<name>&type=adinterest&limit=25
53
+ ```
54
+
55
+ Parameters:
56
+
57
+ - `q`: search text. Some Meta search types allow it to be empty.
58
+ - `type`: Meta Graph search type. Common values include `adinterest`,
59
+ `adTargetingCategory`, `adgeolocation`, and `adlocale`.
60
+ - `limit`: result cap, 1-100. Default is 25.
61
+ - `targeting_class`: optional Meta `class` parameter, used with some
62
+ `adTargetingCategory` lookups.
63
+
64
+ The response is Meta's targeting search payload. Preserve the returned `id`,
65
+ `name`, `key`, `audience_size`, and related fields in launch artifacts, then use
66
+ the appropriate returned identifier inside the ad set `targeting` object.
67
+
68
+ Examples:
69
+
70
+ ```bash
71
+ OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/ads/meta/raw/targetingsearch?q=fitness&type=adinterest&limit=5" -s
72
+
73
+ OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/ads/meta/raw/targetingsearch?type=adTargetingCategory&targeting_class=behaviors&limit=25" -s
74
+ ```
75
+
76
+ Do not hardcode remembered targeting IDs. Resolve them through OS when the
77
+ segment depends on a concrete Meta interest, behavior, geo, or locale ID.
78
+
79
+ ## Read Operations
80
+
81
+ ```bash
82
+ GET $OS_URL/ads/meta/raw/campaigns/{campaign_id}
83
+ GET $OS_URL/ads/meta/raw/campaigns/{campaign_id}/adsets
84
+ GET $OS_URL/ads/meta/raw/campaigns/{campaign_id}/ads
85
+ GET $OS_URL/ads/meta/raw/adsets/{adset_id}
86
+ GET $OS_URL/ads/meta/raw/ads/{ad_id}
87
+ ```
88
+
89
+ Existing object reads are owner-scoped. If OS did not create/register the object
90
+ for this instance, a read or mutation can fail even when the upstream object
91
+ exists.
92
+
93
+ ## Create Campaign
94
+
95
+ For image campaign trees prefer plan/apply; see
96
+ [paused build](../workflows/build-paused.md). Raw/individual creation is for a
97
+ currently authorized operation the declarative spec cannot express, not an
98
+ approval or budget-guard bypass. The following is an illustrative request,
99
+ not a budget recommendation:
100
+
101
+ ```bash
102
+ OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/ads/meta/campaigns" -s -X POST \
103
+ -H "Content-Type: application/json" \
104
+ -d '{
105
+ "name": "2026-07-02-product-segment-offer",
106
+ "product_slug": "product-slug",
107
+ "daily_budget_usd": 12.5,
108
+ "objective": "OUTCOME_TRAFFIC",
109
+ "status": "PAUSED",
110
+ "extra": {"special_ad_categories": []}
111
+ }'
112
+ ```
113
+
114
+ The normalized route accepts dollars and converts to Meta cents.
115
+
116
+ If a raw campaign create is ever needed, pass Meta-native cents:
117
+
118
+ ```bash
119
+ POST $OS_URL/ads/meta/raw/campaigns
120
+ {
121
+ "name": "2026-07-02-product-segment-offer",
122
+ "product_slug": "product-slug",
123
+ "objective": "OUTCOME_TRAFFIC",
124
+ "status": "PAUSED",
125
+ "special_ad_categories": []
126
+ }
127
+ ```
128
+
129
+ Place budget at the requested level; do not set conflicting campaign
130
+ and ad-set budgets. The declarative spec uses `budget_level` to select one.
131
+
132
+ ## Create Ad Set
133
+
134
+ ```bash
135
+ POST $OS_URL/ads/meta/raw/adsets
136
+ {
137
+ "payload": {
138
+ "name": "PT | broad buyers | feeds+stories",
139
+ "campaign_id": "<campaign_id>",
140
+ "daily_budget": 1250,
141
+ "optimization_goal": "LANDING_PAGE_VIEWS",
142
+ "billing_event": "IMPRESSIONS",
143
+ "targeting": {
144
+ "geo_locations": {"countries": ["PT"]},
145
+ "age_min": 25,
146
+ "age_max": 54,
147
+ "publisher_platforms": ["facebook", "instagram"],
148
+ "facebook_positions": ["feed"],
149
+ "instagram_positions": ["stream", "story", "reels"]
150
+ },
151
+ "status": "PAUSED"
152
+ }
153
+ }
154
+ ```
155
+
156
+ Rules:
157
+
158
+ - `daily_budget` is Meta cents; the example `1250` is USD 12.50.
159
+ - Lifetime budgets are not supported in the default OS flow.
160
+ - Daily-budget ad sets should not include `end_time`.
161
+ - OS may inject configured pixel/dataset IDs into `promoted_object` when the
162
+ server-side Meta configuration supports it.
163
+ - Preserve the authorized targeting values.
164
+
165
+ ## Upload Image
166
+
167
+ Upload approved PNG/JPEG creative to receive `image_hash`:
168
+
169
+ ```bash
170
+ POST $OS_URL/ads/meta/raw/adimages
171
+ {
172
+ "image_base64": "<base64_png_or_jpeg>",
173
+ "filename": "creative-01.png"
174
+ }
175
+ ```
176
+
177
+ Through the Egbe connector (`egbe_write`), or when the file is already at a
178
+ public HTTPS URL, send `"image_url": "https://..."` instead of `image_base64`;
179
+ OS downloads it (PNG/JPEG, up to 30 MiB). A message carries at most 1 MiB, so
180
+ through the connector send `image_base64` only for files up to about 500 KiB.
181
+ For a larger local file (up to 10 MiB), store it first with an upload session:
182
+ `POST /uploads` `{"filename","content_type","size"}` returns `data.upload_id`;
183
+ send the bytes in order as `POST /uploads/{upload_id}/parts`
184
+ `{"content_base64":"<at most 512000 bytes>","offset":<data.received_bytes>}`;
185
+ `POST /uploads/{upload_id}/complete` returns a public `data.url`. Send that as
186
+ `image_url`.
187
+
188
+ The response is expected to include a stable `hash`. Every image ad must carry
189
+ that hash at:
190
+
191
+ ```text
192
+ creative.object_story_spec.link_data.image_hash
193
+ ```
194
+
195
+ Do not create an intended image ad without an `image_hash`.
196
+
197
+ ## Upload Video
198
+
199
+ Upload an approved completed MP4 creative to receive `video_id`:
200
+
201
+ ```bash
202
+ POST $OS_URL/ads/meta/raw/advideos
203
+ {
204
+ "video_base64": "<base64_mp4>",
205
+ "filename": "03-talking-head.mp4"
206
+ }
207
+ ```
208
+
209
+ Through the Egbe connector, or for a file already at a public HTTPS URL, send
210
+ `"video_url": "https://..."` instead of `video_base64` (MP4/MOV, up to 100 MiB).
211
+ Through the connector, a local MP4 goes through an upload session first (as
212
+ for images, up to 100 MiB); send its `data.url` as `video_url`. Sessions do not
213
+ accept MOV.
214
+
215
+ The response is expected to include a stable `video_id`. This endpoint uploads a
216
+ finished video; it does not define video generation. Use it only after an
217
+ approved OS generation capability or founder-provided asset produced the MP4.
218
+
219
+ ## Create Ad
220
+
221
+ ```bash
222
+ POST $OS_URL/ads/meta/raw/ads
223
+ {
224
+ "payload": {
225
+ "name": "angle | ai-lifestyle | creative-01.png",
226
+ "adset_id": "<adset_id>",
227
+ "creative": {
228
+ "object_story_spec": {
229
+ "link_data": {
230
+ "message": "Primary text...",
231
+ "link": "https://product.example/?utm_source=meta&utm_medium=paid_social&utm_campaign=...",
232
+ "image_hash": "<image_hash>",
233
+ "call_to_action": {
234
+ "type": "LEARN_MORE",
235
+ "value": {"link": "https://product.example/?utm_source=meta&utm_medium=paid_social&utm_campaign=..."}
236
+ }
237
+ }
238
+ }
239
+ },
240
+ "status": "PAUSED"
241
+ }
242
+ }
243
+ ```
244
+
245
+ OS injects the configured page ID when the server-side Meta configuration has
246
+ one and the payload omits it. The workflow should still record whether page or
247
+ Instagram linkage was missing as a launch limitation when relevant.
248
+
249
+ ## Update Existing Ad
250
+
251
+ Use this only when the launch state already has an ad ID and a targeted repair
252
+ is needed, such as attaching a repaired creative spec:
253
+
254
+ ```bash
255
+ POST $OS_URL/ads/meta/raw/ads/{ad_id}
256
+ {
257
+ "payload": {
258
+ "creative": {
259
+ "object_story_spec": {
260
+ "link_data": {
261
+ "link": "https://product.example/?utm_source=meta&utm_medium=paid_social&utm_campaign=...",
262
+ "image_hash": "<image_hash>",
263
+ "message": "Primary text..."
264
+ }
265
+ }
266
+ }
267
+ }
268
+ }
269
+ ```
270
+
271
+ Prefer creating clean objects in the first launch attempt. Use updates for
272
+ recovery, not as the normal happy path.
273
+
274
+ ## Update Existing Ad Set
275
+
276
+ Use this to narrow/correct `targeting` (or `name`) on a live ad set without
277
+ burning an `adset_creates` slot on a replacement:
278
+
279
+ ```bash
280
+ POST $OS_URL/ads/meta/raw/adsets/{adset_id}
281
+ {
282
+ "payload": {
283
+ "targeting": {
284
+ "geo_locations": {"countries": ["PT"]},
285
+ "age_min": 25,
286
+ "age_max": 54
287
+ }
288
+ }
289
+ }
290
+ ```
291
+
292
+ `daily_budget` and `lifetime_budget` are rejected here — use the dedicated
293
+ `POST $OS_URL/ads/meta/raw/adsets/{adset_id}/budget` route so budget changes
294
+ go through the wallet-hold guardrail. `status` is rejected too — use
295
+ `POST $OS_URL/ads/meta/raw/adsets/{adset_id}/status` so the Registry's
296
+ tracked status stays in sync with the live ad set.
297
+
298
+ ## Launch And Pause
299
+
300
+ Meta delivery requires all three levels to be active:
301
+
302
+ ```bash
303
+ POST $OS_URL/ads/meta/raw/ads/{ad_id}/status {"status": "ACTIVE"}
304
+ POST $OS_URL/ads/meta/raw/adsets/{adset_id}/status {"status": "ACTIVE"}
305
+ POST $OS_URL/ads/meta/campaigns/{campaign_id}/launch
306
+ ```
307
+
308
+ Pause in the reverse or safest practical order:
309
+
310
+ ```bash
311
+ POST $OS_URL/ads/meta/raw/ads/{ad_id}/status {"status": "PAUSED"}
312
+ POST $OS_URL/ads/meta/raw/adsets/{adset_id}/status {"status": "PAUSED"}
313
+ POST $OS_URL/ads/meta/campaigns/{campaign_id}/pause
314
+ ```
315
+
316
+ Allowed status values are `ACTIVE`, `PAUSED`, `ARCHIVED`, and `DELETED`.
317
+
318
+ ## Budget Updates
319
+
320
+ Change budget only within the current authorization. Use these dedicated routes
321
+ so wallet-hold handling is applied; ordinary ad-set update rejects budget fields.
322
+
323
+ ```bash
324
+ POST $OS_URL/ads/meta/raw/campaigns/{campaign_id}/budget {"daily_budget": 1250}
325
+ POST $OS_URL/ads/meta/raw/adsets/{adset_id}/budget {"daily_budget": 1250}
326
+ ```
327
+
328
+ Rules:
329
+
330
+ - `daily_budget` is Meta cents.
331
+ - Lifetime budgets are rejected by the OS default flow.
332
+ - Per-operation budget guardrails are enforced server-side.
333
+ - The configured `meta_ads_max_budget_cents_per_operation` is a server
334
+ per-operation limit, not a channel testing budget. Its source default is
335
+ 10,000 cents; the deployed value may differ. Resolve a returned blocker
336
+ without guessing the live value or bypassing the guard.
337
+
338
+ ## Pixels And Custom Conversions
339
+
340
+ Custom conversions are optional for traffic tests; create one when selecting a
341
+ conversion-objective campaign. The install
342
+ and event contract is `references/runtime/pixel-install.md`; the endpoints below
343
+ are the raw operations behind it.
344
+
345
+ ```bash
346
+ GET $OS_URL/ads/meta/raw/pixels
347
+ GET $OS_URL/ads/meta/raw/pixels/{pixel_id}
348
+ GET $OS_URL/ads/meta/raw/tracking?product_slug=<product_slug>
349
+
350
+ GET $OS_URL/ads/meta/raw/customconversions?offset=0&limit=50
351
+ GET $OS_URL/ads/meta/raw/customconversions/{conversion_id}
352
+ POST $OS_URL/ads/meta/raw/customconversions
353
+ Idempotency-Key: <stable-key-for-this-conversion>
354
+ {
355
+ "name": "Product - Activation",
356
+ "product_slug": "product-slug",
357
+ "event_name": "Activation",
358
+ "custom_event_type": "OTHER"
359
+ }
360
+ ```
361
+
362
+ Server-side OS configuration owns the pixel/dataset binding. Do not ask the
363
+ product agent for pixel credentials. Product code reads the pixel ID from
364
+ `NEXT_PUBLIC_META_PIXEL_ID`, populated from `/tracking` before building the app;
365
+ follow [pixel installation](pixel-install.md) for public configuration and verification.
366
+
367
+ Send the `event_parameters` returned by `/tracking` on pixel events. Conversion
368
+ creation returns the same parameters and a Meta ID. OS builds the rule from the
369
+ product and event. List/read expose only this project's registered conversions;
370
+ continue listing at `next_offset` until it is null. Retry creation with the same
371
+ key and payload; an unconfirmed outcome needs recovery by the Egbe team, not a new key.
372
+ Each list/detail item includes `eligibility.status`: `eligible`, `ineligible`
373
+ (for example, archived or changed rule), or `unavailable` (readback could not be
374
+ verified). Only `eligible` goals can be bound. Other items remain visible with
375
+ `code`, `message`, `retryable`, and `next_action`; a successful list/read is not
376
+ proof that every goal is usable.
377
+ `eligible` verifies configuration: project/product ownership, shared pixel,
378
+ the exact rule and non-archived state. `eligibility.event_matching` is
379
+ `unverified`: these reads do not verify event delivery or actual rule matches,
380
+ even when `last_fired_time` is present. A clean `/ads/meta/plan` returns the same
381
+ diagnostic in `data.conversion_eligibility` (null unless a conversion's
382
+ configuration was verified; failed checks remain in `blockers`).
383
+ Its `ok` and plan token validate the configuration, not live tracking or provider
384
+ approval. Verify instrumentation and report provider matching separately using
385
+ the [pixel checks](pixel-install.md#verification).
386
+ `POST .../pixels` is intentionally absent from the product workflow: creating a
387
+ pixel is an OS migration operation, not a product launch step.
388
+
389
+ For `OFFSITE_CONVERSIONS`, include the recorded id in the declarative spec:
390
+
391
+ ```json
392
+ {
393
+ "objective": "OUTCOME_SALES",
394
+ "optimization_goal": "OFFSITE_CONVERSIONS",
395
+ "custom_conversion_id": "<verified product conversion id>"
396
+ }
397
+ ```
398
+
399
+ Use the same `product_slug` on the campaign and conversion. OS verifies ownership,
400
+ product, shared pixel, rule and active conversion state before binding or
401
+ activation, and rechecks on apply after plan. An unverified or changed rule
402
+ blocks conversion optimization; a traffic campaign needs no conversion.
403
+ Campaign activation checks groups whose own status is `ACTIVE`; it leaves
404
+ `PAUSED`/`ARCHIVED`/`DELETED` groups unchanged. Activating an individual group
405
+ checks its goal again.
406
+
407
+ Eligibility failures return the reason and `next_action` in the OS error
408
+ `data`. With `retryable: true`, retry with backoff up to three times,
409
+ keeping the same create key/payload; report the blocker if it persists. With
410
+ `retryable: false`, address the stated cause before retrying. Campaign errors
411
+ identify the blocking group and, when available, conversion. A `plan` response
412
+ reports the same details under `blockers[].detail` instead of applying changes.
413
+
414
+ ## Common Error Classes
415
+
416
+ | Error | Meaning | Action |
417
+ |---|---|---|
418
+ | `meta_budget_guardrail_exceeded` | Budget exceeds OS guardrail | Lower budget or get Egbe admin approval |
419
+ | `meta_lifetime_budget_not_supported_use_daily_budget` | Default flow rejects lifetime budget | Use `daily_budget` in cents |
420
+ | `meta_end_time_not_supported_in_default_daily_budget_flow` | Daily-budget ad set included `end_time` | Remove `end_time` |
421
+ | owner/404 on object read or mutation | Object is not registered to this instance | Use IDs created by the current OS workflow or record blocker |
422
+ | upstream permission/configuration error | OS server-side Meta binding is not ready | Stop and report OS configuration blocker |
423
+
424
+ ## Output Discipline
425
+
426
+ Every raw operation that mutates Meta state must update durable launch artifacts:
427
+
428
+ - operation timestamp
429
+ - endpoint path
430
+ - request intent, not secrets
431
+ - returned object ID
432
+ - status after mutation
433
+ - known limitations or compromises
434
+
435
+ Do not print credentials, access tokens, page IDs, pixel IDs, or account IDs in
436
+ founder-facing summaries.
@@ -0,0 +1,51 @@
1
+ # Meta execution records
2
+
3
+ Keep requests, IDs and evidence beside the relevant campaign, normally
4
+ `egbe-docs/marketing/campaigns/meta/<campaign>/`. Reference existing input records
5
+ when available; no research, strategy or report package is required.
6
+
7
+ Through the Egbe connector without a project folder, keep these records at the
8
+ same paths in Egbe's artifact store, as `egbe-os-quickstart` →
9
+ `references/artifact-sync.md` ("Through the Egbe connector") describes. Save a
10
+ write's request record there before sending the write.
11
+
12
+ Before a write save its exact endpoint/payload, time and request identity.
13
+ For plan/apply preserve the exact spec, plan/token and authorization context;
14
+ OS derives apply idempotency from the original token. Save responses, errors,
15
+ unknown outcomes and returned IDs immediately. Never overwrite an uncertain
16
+ attempt with a new one or store credentials in these records.
17
+
18
+ `campaign-state.json` keeps `channel: meta`, the known operational `status`
19
+ and `objects.campaign_id`, `adset_ids`, `ad_ids`. Record budget, destination,
20
+ media hashes and parent mapping when part of the operation. Requested fields
21
+ are not provider readback.
22
+
23
+ `launch-readback.json` holds `observed_at` (timezone-aware), `campaign`,
24
+ `adsets` and `ads`, each with the exact `id` and returned
25
+ `effective_status`/`status`. These are the `observed` rows from the state
26
+ endpoint; retain its full response and configuration reads alongside the
27
+ projection. Do not fabricate parent IDs or other fields absent from a read.
28
+
29
+ For a status or campaign-only pause, campaign ID/readback suffice; include known
30
+ selected child IDs when checking them. For build/launch, retain the complete
31
+ selected tree. This is recovery evidence, not a universal campaign schema.
32
+
33
+ Optional local check:
34
+
35
+ ```bash
36
+ python3 scripts/validate-meta-artifacts.py --product-root <repo> \
37
+ --campaign-path egbe-docs/marketing/campaigns/meta/<campaign> \
38
+ --campaign-id <exact-id> --phase pause
39
+ ```
40
+
41
+ Supported phases: `build-paused`, `launch-ready`, `launch`, `status`,
42
+ `monitoring`, `pause`. It checks saved IDs/status/timestamps and optional
43
+ numeric/recovery values, not live ownership, consent, current API validation,
44
+ report wording or business outcomes. For pause it proves the campaign is
45
+ non-serving, not that every child is independently paused.
46
+
47
+ Preserve any existing durable business/product/launch/experiment/variant IDs
48
+ and stable UTM mapping when provided; do not replace them with scheduler IDs.
49
+ When an index is used, update it consistently with the same exact IDs rather
50
+ than switching campaigns to make a check pass. Commit/share records according
51
+ to the project's collaboration workflow, not as a prerequisite to stopping spend.
@@ -0,0 +1,187 @@
1
+ # Meta Ads Insights Reference
2
+
3
+ Use this file to read Meta campaign, ad-set and ad metrics through OS.
4
+
5
+ Platform insights and product analytics have separate sources and attribution.
6
+
7
+ ## Current OS Endpoints
8
+
9
+ Use normalized campaign results for quick checks:
10
+
11
+ ```bash
12
+ GET $OS_URL/ads/meta/campaigns/{campaign_id}/results
13
+ ```
14
+
15
+ Use raw insight endpoints for campaign, ad set, and ad-level details:
16
+
17
+ ```bash
18
+ GET $OS_URL/ads/meta/raw/campaigns/{campaign_id}/insights
19
+ GET $OS_URL/ads/meta/raw/adsets/{adset_id}/insights
20
+ GET $OS_URL/ads/meta/raw/ads/{ad_id}/insights
21
+ ```
22
+
23
+ These endpoints use a fixed field set. Without date inputs they retain the
24
+ legacy `last_30d` window, which can exclude the current account-local day.
25
+ For a campaign-lifetime safety counter, request an explicit current-inclusive
26
+ window instead of treating that default as cumulative spend:
27
+
28
+ ```bash
29
+ GET $OS_URL/ads/meta/campaigns/{campaign_id}/results?period=MAXIMUM
30
+ GET $OS_URL/ads/meta/raw/campaigns/{campaign_id}/insights?period=MAXIMUM
31
+ GET $OS_URL/ads/meta/raw/adsets/{adset_id}/insights?date_from=2026-10-31&date_to=2026-11-02
32
+ ```
33
+
34
+ Campaign results and all three raw insight routes accept `period=TODAY`,
35
+ `YESTERDAY`, `LAST_7_DAYS`, `LAST_30_DAYS` or `MAXIMUM`, OR an inclusive
36
+ `date_from`/`date_to` pair, ordered and at most 366 days. Raw insight routes also
37
+ accept the equivalent native `date_preset` names (`today`, `yesterday`,
38
+ `last_7d`, `last_30d`, `maximum`). Do not mix selections. Unsupported raw date
39
+ parameters are rejected; generic raw forwarding does not grant arbitrary Graph
40
+ API parameters, breakdowns or attribution settings.
41
+
42
+ Meta interprets periods and dates in the resource's ad account calendar. Do not
43
+ substitute the gateway's UTC date or another shared account's timezone. TODAY
44
+ is a daily counter, not a lifetime counter. MAXIMUM asks Meta for its maximum
45
+ available history through the current day; retention and reporting lag still
46
+ apply. Preserve prior counters and historical evidence.
47
+
48
+ `report.query` confirms the selected contract. `report.date_from`/`date_to` are
49
+ the actual provider-returned bounds, `calendar` is `provider_account`, and
50
+ `currency` is the native account currency. Check those bounds against the
51
+ required account-local day and campaign history. A request's inclusion of today
52
+ does not prove today's spend is final. `retrieved_at` is fetch time, not a
53
+ completeness or freshness watermark. Empty rows, missing metrics, incomplete
54
+ pagination or missing report-contract metadata for an explicit selection are
55
+ unavailable, not zero. Do not enforce a spend cap from an unverified window.
56
+ `metrics_available` means at least one requested core metric is usable; inspect
57
+ `metric_availability` for each required spend/impression/click/link-click field.
58
+ `window_available` checks that returned dates are valid and, for a custom range,
59
+ match the selected bounds. It does not certify current-day finality.
60
+
61
+ Normalized results retain `raw`, expose `report`, `provider_diagnostics` and
62
+ `metrics.inline_link_clicks`, and label native `metrics.spend`/`currency`.
63
+ `spend_usd`/`cpc_usd` are unavailable for a confirmed non-USD currency. Old
64
+ no-input clients keep their default window; a new OS talking to an older Tools
65
+ gateway refuses explicit selections that the older gateway could silently ignore.
66
+
67
+ ## Enumeration Completeness
68
+
69
+ Campaign, ad-set, and ad lists can be truncated at the provider or OS page
70
+ limit. Follow pagination only where the route supports it; otherwise record
71
+ that the child enumeration is incomplete. A full page is not evidence that
72
+ every child was returned. Label incomplete child coverage in saved results.
73
+
74
+ ## Current Field Set
75
+
76
+ Campaign insights include:
77
+
78
+ - `campaign_name`
79
+ - `impressions`
80
+ - `reach`
81
+ - `clicks`
82
+ - `inline_link_clicks`
83
+ - `spend`
84
+ - `cpc`
85
+ - `cost_per_inline_link_click`
86
+ - `ctr`
87
+ - `inline_link_click_ctr`
88
+ - `frequency`
89
+ - `actions`
90
+ - `cost_per_action_type`
91
+ - `purchase_roas`
92
+ - `date_start`
93
+ - `date_stop`
94
+
95
+ Ad set insights replace `campaign_name` with `adset_name`. Ad insights replace
96
+ it with `ad_name`.
97
+
98
+ ## Metric Meaning
99
+
100
+ | Field | Meaning |
101
+ |---|---|
102
+ | `impressions` | Total ad impressions |
103
+ | `reach` | Unique people reached |
104
+ | `frequency` | Average impressions per reached person |
105
+ | `spend` | Spend in account currency |
106
+ | `clicks` | All clicks |
107
+ | `inline_link_clicks` | Link clicks inside the ad unit |
108
+ | `ctr` | All-click CTR percentage |
109
+ | `inline_link_click_ctr` | Link-click CTR percentage |
110
+ | `cpc` | Cost per all click |
111
+ | `cost_per_inline_link_click` | Cost per link click |
112
+ | `actions` | Array of action objects: `{action_type, value}` |
113
+ | `cost_per_action_type` | Cost per action object array |
114
+ | `purchase_roas` | Return on ad spend object array |
115
+
116
+ `inline_link_clicks`, `inline_link_click_ctr`, and `cost_per_inline_link_click`
117
+ measure link interactions; all-click metrics can also include non-link engagement.
118
+
119
+ ## Common Action Types
120
+
121
+ Look for these in `actions`:
122
+
123
+ | Action type | Meaning |
124
+ |---|---|
125
+ | `landing_page_view` | Meta observed a landing page load |
126
+ | `link_click` | Link click |
127
+ | `lead` | Lead event |
128
+ | `complete_registration` | Registration completion |
129
+ | `purchase` | Purchase |
130
+ | `add_to_cart` | Add to cart |
131
+ | `initiate_checkout` | Checkout started |
132
+ | `page_engagement` | Page engagement |
133
+ | `post_engagement` | Post engagement |
134
+ | `video_view` | 3-second video view |
135
+ | `omni_purchase` | Cross-platform purchase |
136
+ | `offsite_conversion.fb_pixel_purchase` | Pixel purchase |
137
+ | `offsite_conversion.fb_pixel_lead` | Pixel lead |
138
+
139
+ Meta action names do not replace product analytics events. Product-side
140
+ canonical events still come from `/analytics/events`.
141
+
142
+ ## Fresh Object Caveat
143
+
144
+ Meta does not always return insights immediately after campaign launch or object
145
+ creation. Empty `data` can be normal for several hours after a campaign, ad set,
146
+ or ad is created.
147
+
148
+ Record creation and fetch times with empty results. Campaign-level data does not
149
+ fill missing child rows: recently created ads/ad sets can still have pending
150
+ insights inside an older campaign. An empty report does not distinguish ingestion
151
+ delay from no delivery. Read configured/effective delivery state separately.
152
+
153
+ ## Missing Fields
154
+
155
+ Even when `data` is non-empty, individual fields can be null or absent,
156
+ especially `purchase_roas`, `frequency` on fresh objects, and
157
+ `cost_per_action_type` when conversion tracking is not configured.
158
+
159
+ Record missing values as unavailable, pending, or not configured. Do not replace
160
+ them with zero.
161
+
162
+ ## Product Analytics Join
163
+
164
+ When the requested analysis needs product attribution, collect:
165
+
166
+ - UTM campaign values used in destination URLs
167
+ - OS analytics campaign visits
168
+ - engagement quality when available
169
+ - canonical events such as `cta_click`, `signup_completed`, `activated`, and
170
+ `purchase`
171
+ - tracking state: `active`, `degraded`, or `blocked`
172
+
173
+ Preserve attribution windows, event definitions and coverage for each source;
174
+ conflicting values are separate observations, not interchangeable totals.
175
+
176
+ ## Future Fields Not Yet Contracted
177
+
178
+ Meta supports useful concepts that the current OS route does not expose as
179
+ free-form controls:
180
+
181
+ - daily/weekly time increments;
182
+ - age, gender, country, platform, placement, and device breakdowns;
183
+ - explicit attribution windows;
184
+ - async reports for large datasets.
185
+
186
+ Do not claim those were checked unless the OS route used for the run actually
187
+ returned them.