@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.
- package/LICENSE +4 -0
- package/README.md +124 -2
- package/index.js +5 -0
- package/package.json +55 -4
- package/plugin.js +230 -0
- package/session-log.js +315 -0
- package/skills/.egbe-catalog/manifest.json +1 -0
- package/skills/egbe-os-analytics/SKILL.md +499 -0
- package/skills/egbe-os-analytics/canonical-events.v1.json +256 -0
- package/skills/egbe-os-analytics/references/session-funnel.md +130 -0
- package/skills/egbe-os-analytics/references/workflows/activation-tracking.md +147 -0
- package/skills/egbe-os-analytics/references/workflows/landing-click-tracking.md +209 -0
- package/skills/egbe-os-analytics/references/workflows/payment-lifecycle-tracking.md +122 -0
- package/skills/egbe-os-analytics/references/workflows/product-funnel-tracking.md +77 -0
- package/skills/egbe-os-analytics/references/workflows/signup-lifecycle-tracking.md +208 -0
- package/skills/egbe-os-analytics/scripts/umami_funnel.py +927 -0
- package/skills/egbe-os-apollo-lead-finder/SKILL.md +135 -0
- package/skills/egbe-os-apollo-lead-finder/references/operations.md +240 -0
- package/skills/egbe-os-apollo-lead-finder/scripts/enrich.js +6 -0
- package/skills/egbe-os-apollo-lead-finder/scripts/enrich.sh +4 -0
- package/skills/egbe-os-apollo-lead-finder/scripts/find-leads.js +6 -0
- package/skills/egbe-os-apollo-lead-finder/scripts/find-leads.sh +4 -0
- package/skills/egbe-os-apollo-lead-finder/scripts/lib/apollo-client.js +343 -0
- package/skills/egbe-os-apollo-lead-finder/scripts/lib/connection-identity.js +17 -0
- package/skills/egbe-os-apollo-lead-finder/scripts/lib/helpers.js +127 -0
- package/skills/egbe-os-apollo-lead-finder/scripts/lib/places-filters.js +217 -0
- package/skills/egbe-os-apollo-lead-finder/scripts/lib/sourcing.js +153 -0
- package/skills/egbe-os-apollo-lead-finder/scripts/places-leads.js +653 -0
- package/skills/egbe-os-apollo-lead-finder/scripts/places-leads.sh +4 -0
- package/skills/egbe-os-apollo-lead-finder/scripts/search.js +6 -0
- package/skills/egbe-os-apollo-lead-finder/scripts/search.sh +4 -0
- package/skills/egbe-os-campaign-landing-page/SKILL.md +95 -0
- package/skills/egbe-os-campaign-landing-page/agents/openai.yaml +4 -0
- package/skills/egbe-os-campaign-landing-page/references/leads-calendar-and-tracking.md +66 -0
- package/skills/egbe-os-campaign-landing-page/references/os-wiring.md +58 -0
- package/skills/egbe-os-campaign-landing-page/references/qa.md +40 -0
- package/skills/egbe-os-campaign-landing-page/references/routing.md +32 -0
- package/skills/egbe-os-db/SKILL.md +174 -0
- package/skills/egbe-os-deploy/SKILL.md +412 -0
- package/skills/egbe-os-design/SKILL.md +182 -0
- package/skills/egbe-os-design-landing-page/SKILL.md +117 -0
- package/skills/egbe-os-design-landing-page/agents/openai.yaml +4 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/.dockerignore +11 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/AGENTS.md +31 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/Dockerfile +21 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/eslint.config.mjs +18 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/next.config.ts +11 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/package.json +36 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/postcss.config.mjs +7 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/public/.gitkeep +1 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/sentry.edge.config.ts +13 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/sentry.server.config.ts +13 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/global-error.tsx +19 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/globals.css +22 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/layout.tsx +21 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/page.tsx +3 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/privacy/page.tsx +28 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/src/components/egbe-analytics.tsx +39 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/src/instrumentation-client.ts +15 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/src/instrumentation.ts +13 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/src/lib/egbe-observability.generated.ts +20 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/src/lib/utils.ts +6 -0
- package/skills/egbe-os-design-landing-page/assets/scaffold/tsconfig.json +34 -0
- package/skills/egbe-os-design-landing-page/references/application-preparation.md +44 -0
- package/skills/egbe-os-design-landing-page/references/page-inputs.md +22 -0
- package/skills/egbe-os-destination-readiness/SKILL.md +132 -0
- package/skills/egbe-os-destination-readiness/references/checks.md +130 -0
- package/skills/egbe-os-destination-readiness/references/network-requirements.md +34 -0
- package/skills/egbe-os-destination-readiness/references/report.md +116 -0
- package/skills/egbe-os-domains/SKILL.md +189 -0
- package/skills/egbe-os-errors/SKILL.md +259 -0
- package/skills/egbe-os-git/SKILL.md +275 -0
- package/skills/egbe-os-git/references/issues.md +33 -0
- package/skills/egbe-os-google-ads/SKILL.md +163 -0
- package/skills/egbe-os-google-ads/references/artifacts.md +133 -0
- package/skills/egbe-os-google-ads/references/campaigns.md +157 -0
- package/skills/egbe-os-google-ads/references/conversions.md +153 -0
- package/skills/egbe-os-google-ads/references/delivery.md +128 -0
- package/skills/egbe-os-google-ads/references/keyword-ideas.md +40 -0
- package/skills/egbe-os-google-ads/references/reporting.md +105 -0
- package/skills/egbe-os-google-ads/references/search-assets.md +219 -0
- package/skills/egbe-os-google-ads/references/server-conversions.md +119 -0
- package/skills/egbe-os-google-auth/SKILL.md +285 -0
- package/skills/egbe-os-google-auth/agents/openai.yaml +4 -0
- package/skills/egbe-os-gtm-knowledge/SKILL.md +151 -0
- package/skills/egbe-os-images/SKILL.md +163 -0
- package/skills/egbe-os-images/references/stock-images.md +21 -0
- package/skills/egbe-os-instantly-campaign-launcher/SKILL.md +127 -0
- package/skills/egbe-os-instantly-campaign-launcher/references/instantly-ops.md +260 -0
- package/skills/egbe-os-instantly-campaign-launcher/references/observation-and-scheduling.md +188 -0
- package/skills/egbe-os-instantly-campaign-launcher/references/reply-handling.md +116 -0
- package/skills/egbe-os-instantly-campaign-launcher/references/run-spec-template.json +65 -0
- package/skills/egbe-os-instantly-campaign-launcher/references/run-state.md +145 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/conclude-campaign.js +158 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/install-crons.js +956 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/launch-campaign.js +2008 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/campaign-metrics.js +124 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/confirmed-opt-outs.js +208 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/connection-identity.js +17 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/create-once.js +23 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/gtm-identity.js +125 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/helpers.js +545 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/html-body.js +266 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/instantly-client.js +328 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/outreach-db.js +370 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/recipient-exclusion/index.js +86 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/replenish-test-harness.js +53 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/reply-queue.js +67 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/run-config.js +103 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/sender-selection.js +105 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/monitor-campaign.js +607 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/outreach-report.js +147 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/replenish-leads.js +619 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/reply-worker.js +258 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/run-cron-job.js +32 -0
- package/skills/egbe-os-instantly-campaign-launcher/scripts/send-reply.js +260 -0
- package/skills/egbe-os-linkedin-ads/SKILL.md +114 -0
- package/skills/egbe-os-linkedin-ads/references/destination-requirements.md +30 -0
- package/skills/egbe-os-linkedin-ads/references/runtime/api-reference.md +154 -0
- package/skills/egbe-os-linkedin-ads/references/runtime/artifacts.md +63 -0
- package/skills/egbe-os-linkedin-ads/references/workflows/build-paused.md +44 -0
- package/skills/egbe-os-linkedin-ads/references/workflows/conversions.md +88 -0
- package/skills/egbe-os-linkedin-ads/references/workflows/launch-and-pause.md +49 -0
- package/skills/egbe-os-linkedin-ads/references/workflows/monitoring.md +35 -0
- package/skills/egbe-os-linkedin-ads/references/workflows/readiness.md +63 -0
- package/skills/egbe-os-linkedin-ads/references/workflows/targeting-and-creative.md +52 -0
- package/skills/egbe-os-llm/SKILL.md +160 -0
- package/skills/egbe-os-mail/SKILL.md +180 -0
- package/skills/egbe-os-me/SKILL.md +119 -0
- package/skills/egbe-os-meta-ads/SKILL.md +114 -0
- package/skills/egbe-os-meta-ads/references/creative/creative-specs.md +15 -0
- package/skills/egbe-os-meta-ads/references/creative/talking-head.md +35 -0
- package/skills/egbe-os-meta-ads/references/destination-requirements.md +30 -0
- package/skills/egbe-os-meta-ads/references/runtime/api-reference.md +436 -0
- package/skills/egbe-os-meta-ads/references/runtime/artifacts.md +51 -0
- package/skills/egbe-os-meta-ads/references/runtime/insights-reference.md +187 -0
- package/skills/egbe-os-meta-ads/references/runtime/pixel-install.md +196 -0
- package/skills/egbe-os-meta-ads/references/runtime/shared-analytics-attribution.md +16 -0
- package/skills/egbe-os-meta-ads/references/workflows/build-paused.md +36 -0
- package/skills/egbe-os-meta-ads/references/workflows/launch-ready.md +16 -0
- package/skills/egbe-os-meta-ads/references/workflows/launch.md +23 -0
- package/skills/egbe-os-meta-ads/references/workflows/monitoring.md +72 -0
- package/skills/egbe-os-meta-ads/references/workflows/pause.md +17 -0
- package/skills/egbe-os-meta-ads/references/workflows/recovery.md +23 -0
- package/skills/egbe-os-meta-ads/scripts/check-pixel.py +229 -0
- package/skills/egbe-os-meta-ads/scripts/validate-meta-artifacts.py +187 -0
- package/skills/egbe-os-notifications/SKILL.md +78 -0
- package/skills/egbe-os-openai-ads/SKILL.md +149 -0
- package/skills/egbe-os-openai-ads/references/creative/chat-card.md +51 -0
- package/skills/egbe-os-openai-ads/references/destination-requirements.md +29 -0
- package/skills/egbe-os-openai-ads/references/runtime/api-reference.md +219 -0
- package/skills/egbe-os-openai-ads/references/runtime/artifacts.md +169 -0
- package/skills/egbe-os-openai-ads/references/workflows/build-paused.md +40 -0
- package/skills/egbe-os-openai-ads/references/workflows/conversions.md +40 -0
- package/skills/egbe-os-openai-ads/references/workflows/creative-assembly.md +24 -0
- package/skills/egbe-os-openai-ads/references/workflows/launch.md +27 -0
- package/skills/egbe-os-openai-ads/references/workflows/monitoring.md +54 -0
- package/skills/egbe-os-openai-ads/references/workflows/pause.md +22 -0
- package/skills/egbe-os-openai-ads/references/workflows/readiness.md +37 -0
- package/skills/egbe-os-openai-ads/references/workflows/tracking.md +32 -0
- package/skills/egbe-os-openai-ads/scripts/validate-openai-artifacts.py +271 -0
- package/skills/egbe-os-organic-trend-watch/SKILL.md +139 -0
- package/skills/egbe-os-organic-trend-watch/agents/openai.yaml +4 -0
- package/skills/egbe-os-organic-trend-watch/references/analysis-and-adaptation.md +54 -0
- package/skills/egbe-os-organic-trend-watch/references/collection-and-analysis.md +117 -0
- package/skills/egbe-os-organic-trend-watch/references/output-contract.md +133 -0
- package/skills/egbe-os-organic-trend-watch/references/provider-contract.md +169 -0
- package/skills/egbe-os-organic-trend-watch/references/runtime-contract.md +204 -0
- package/skills/egbe-os-organic-trend-watch/references/visual-analysis-prompt.md +17 -0
- package/skills/egbe-os-organic-trend-watch/scripts/_analysis.py +612 -0
- package/skills/egbe-os-organic-trend-watch/scripts/_contract.py +1133 -0
- package/skills/egbe-os-organic-trend-watch/scripts/_provider_inputs.py +165 -0
- package/skills/egbe-os-organic-trend-watch/scripts/analyze-visual-evidence.py +315 -0
- package/skills/egbe-os-organic-trend-watch/scripts/build-provider-inputs.py +88 -0
- package/skills/egbe-os-organic-trend-watch/scripts/connection_identity.py +22 -0
- package/skills/egbe-os-organic-trend-watch/scripts/egbe_artifacts.py +24 -0
- package/skills/egbe-os-organic-trend-watch/scripts/finalize-receipt.py +106 -0
- package/skills/egbe-os-organic-trend-watch/scripts/normalize-videos.py +647 -0
- package/skills/egbe-os-organic-trend-watch/scripts/prepare-visual-evidence.py +324 -0
- package/skills/egbe-os-organic-trend-watch/scripts/render-result.py +30 -0
- package/skills/egbe-os-organic-trend-watch/scripts/run-apify.py +723 -0
- package/skills/egbe-os-organic-trend-watch/scripts/run-state.py +192 -0
- package/skills/egbe-os-organic-trend-watch/scripts/validate-context.py +27 -0
- package/skills/egbe-os-organic-trend-watch/scripts/validate-runtime.py +137 -0
- package/skills/egbe-os-payments/SKILL.md +215 -0
- package/skills/egbe-os-payments/agents/openai.yaml +4 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/.egbe/scaffolds/billing-nextjs-subscription.v1.json +5 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/AGENTS.append.md +13 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/db/migrations/1000_egbe_billing.sql +66 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/package.fragment.json +12 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/scripts/billing-sync.mjs +162 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/account/billing/error.tsx +11 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/account/billing/loading.tsx +8 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/account/billing/page.tsx +121 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/billing/checkout/route.ts +102 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/billing/portal/route.ts +54 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/billing/status/route.ts +22 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/payments/webhook/route.ts +65 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/components/egbe-billing/plan-badge.tsx +16 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/billing-sync.test.mjs +58 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/catalog.ts +82 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/checkout-payload.ts +47 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/foundation-contract.test.mjs +59 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/lifecycle.d.ts +16 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/lifecycle.mjs +82 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/lifecycle.test.mjs +94 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/os-client.ts +96 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/plans.json +17 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/repository.ts +325 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/signature.d.ts +6 -0
- package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/signature.mjs +22 -0
- package/skills/egbe-os-payments/references/contracts/plan-catalog.md +46 -0
- package/skills/egbe-os-payments/references/security/durable-verification.md +64 -0
- package/skills/egbe-os-payments/references/security/server-integration.md +26 -0
- package/skills/egbe-os-payments/references/security/webhook-and-entitlements.md +152 -0
- package/skills/egbe-os-payments/references/ux/billing-experience.md +47 -0
- package/skills/egbe-os-payments/references/workflows/account-billing.md +64 -0
- package/skills/egbe-os-payments/references/workflows/discounts-and-promotion-codes.md +265 -0
- package/skills/egbe-os-payments/references/workflows/one-time-purchase.md +75 -0
- package/skills/egbe-os-payments/references/workflows/product-checkout.md +355 -0
- package/skills/egbe-os-payments/references/workflows/subscription-lifecycle.md +55 -0
- package/skills/egbe-os-playbook/SKILL.md +79 -0
- package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/email-outreach.md +91 -0
- package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/google-search.md +40 -0
- package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/linkedin.md +24 -0
- package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/meta.md +23 -0
- package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/openai.md +15 -0
- package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/reddit.md +56 -0
- package/skills/egbe-os-playbook/playbooks/market-and-acquisition/choose-test.md +73 -0
- package/skills/egbe-os-playbook/playbooks/market-and-acquisition/evaluate.md +91 -0
- package/skills/egbe-os-playbook/playbooks/market-and-acquisition/market.md +96 -0
- package/skills/egbe-os-playbook/playbooks/market-and-acquisition/run-test.md +111 -0
- package/skills/egbe-os-playbook/playbooks/market-and-acquisition.md +56 -0
- package/skills/egbe-os-playbook/playbooks/product/business-loop.md +141 -0
- package/skills/egbe-os-playbook/playbooks/product/collaboration.md +26 -0
- package/skills/egbe-os-playbook/playbooks/product/deliver.md +75 -0
- package/skills/egbe-os-playbook/playbooks/product/diagnose.md +80 -0
- package/skills/egbe-os-playbook/playbooks/product/evaluate.md +67 -0
- package/skills/egbe-os-playbook/playbooks/product/experience.md +132 -0
- package/skills/egbe-os-playbook/playbooks/product/loop-examples.md +67 -0
- package/skills/egbe-os-playbook/playbooks/product/offer.md +65 -0
- package/skills/egbe-os-playbook/playbooks/product/value.md +91 -0
- package/skills/egbe-os-playbook/playbooks/product.md +67 -0
- package/skills/egbe-os-playbook/references/catalog.md +127 -0
- package/skills/egbe-os-playbook/references/changes.md +167 -0
- package/skills/egbe-os-playbook/scripts/playbook-changes.py +6 -0
- package/skills/egbe-os-playbook/scripts/playbook_changes/__init__.py +1 -0
- package/skills/egbe-os-playbook/scripts/playbook_changes/cli.py +57 -0
- package/skills/egbe-os-playbook/scripts/playbook_changes/operations.py +137 -0
- package/skills/egbe-os-playbook/scripts/playbook_changes/protocol.py +132 -0
- package/skills/egbe-os-playbook/scripts/playbook_changes/storage.py +180 -0
- package/skills/egbe-os-playbook/scripts/playbook_changes/transport.py +113 -0
- package/skills/egbe-os-product-auth/SKILL.md +151 -0
- package/skills/egbe-os-product-auth/agents/openai.yaml +4 -0
- package/skills/egbe-os-product-auth/assets/db/README.md +102 -0
- package/skills/egbe-os-product-auth/assets/db/create-validation-session.mjs +223 -0
- package/skills/egbe-os-product-auth/assets/db/migrate.mjs +64 -0
- package/skills/egbe-os-product-auth/assets/db/migrations/0001_auth.sql +33 -0
- package/skills/egbe-os-product-auth/assets/db/migrations/0002_auth_identities.sql +16 -0
- package/skills/egbe-os-product-auth/assets/scaffolds/product-auth-database/AGENTS.append.md +17 -0
- package/skills/egbe-os-product-auth/assets/scaffolds/product-auth-database/package.fragment.json +10 -0
- package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/AGENTS.append.md +9 -0
- package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/package.fragment.json +13 -0
- package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/db.ts +31 -0
- package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/identity.ts +94 -0
- package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/index.ts +3 -0
- package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/session.ts +91 -0
- package/skills/egbe-os-product-auth/references/contracts/live-auth-interface.md +108 -0
- package/skills/egbe-os-product-auth/references/frameworks/nextjs.md +34 -0
- package/skills/egbe-os-product-auth/references/security/session-and-credentials.md +73 -0
- package/skills/egbe-os-product-auth/references/ux/auth-experience.md +58 -0
- package/skills/egbe-os-product-auth/references/workflows/account-recovery.md +22 -0
- package/skills/egbe-os-product-auth/references/workflows/build-auth.md +212 -0
- package/skills/egbe-os-product-auth/references/workflows/google.md +34 -0
- package/skills/egbe-os-product-auth/references/workflows/passwordless-email.md +65 -0
- package/skills/egbe-os-product-build/SKILL.md +111 -0
- package/skills/egbe-os-product-build/agents/openai.yaml +4 -0
- package/skills/egbe-os-product-build/references/capabilities.md +25 -0
- package/skills/egbe-os-product-build/references/engineering.md +72 -0
- package/skills/egbe-os-product-build/references/execution.md +55 -0
- package/skills/egbe-os-product-build/references/foundations.md +93 -0
- package/skills/egbe-os-product-build/references/interface-quality.md +32 -0
- package/skills/egbe-os-product-build/references/workflows/private-review-handoff.md +86 -0
- package/skills/egbe-os-product-build/scripts/scaffold.py +296 -0
- package/skills/egbe-os-product-demo-video/SKILL.md +118 -0
- package/skills/egbe-os-product-demo-video/references/recording.md +32 -0
- package/skills/egbe-os-product-market-research/SKILL.md +159 -0
- package/skills/egbe-os-product-market-research/agents/openai.yaml +4 -0
- package/skills/egbe-os-product-market-research/references/catalog.v1.json +177 -0
- package/skills/egbe-os-product-market-research/references/config/channel-footprint-sources.v1.json +99 -0
- package/skills/egbe-os-product-market-research/references/config/creative-taxonomy.v1.json +367 -0
- package/skills/egbe-os-product-market-research/references/contracts/creative-video.md +75 -0
- package/skills/egbe-os-product-market-research/references/contracts/funnel-teardown.md +235 -0
- package/skills/egbe-os-product-market-research/references/contracts/geography-comparison.md +71 -0
- package/skills/egbe-os-product-market-research/references/contracts/lifecycle-capture.md +119 -0
- package/skills/egbe-os-product-market-research/references/contracts/research-artifacts.md +520 -0
- package/skills/egbe-os-product-market-research/references/contracts/walk-mechanics.v2.json +18 -0
- package/skills/egbe-os-product-market-research/references/prompts/acquisition-channels.md +137 -0
- package/skills/egbe-os-product-market-research/references/prompts/acquisition-channels.user.md +4 -0
- package/skills/egbe-os-product-market-research/references/prompts/competitive-landscape.md +118 -0
- package/skills/egbe-os-product-market-research/references/prompts/competitive-landscape.user.md +4 -0
- package/skills/egbe-os-product-market-research/references/prompts/demand-validation.md +154 -0
- package/skills/egbe-os-product-market-research/references/prompts/demand-validation.user.md +4 -0
- package/skills/egbe-os-product-market-research/references/prompts/market-size-and-dynamics.md +100 -0
- package/skills/egbe-os-product-market-research/references/prompts/market-size-and-dynamics.user.md +4 -0
- package/skills/egbe-os-product-market-research/references/prompts/pricing-and-monetization.md +126 -0
- package/skills/egbe-os-product-market-research/references/prompts/pricing-and-monetization.user.md +4 -0
- package/skills/egbe-os-product-market-research/references/prompts/target-audience.md +98 -0
- package/skills/egbe-os-product-market-research/references/prompts/target-audience.user.md +4 -0
- package/skills/egbe-os-product-market-research/references/prompts/unit-economics.md +217 -0
- package/skills/egbe-os-product-market-research/references/prompts/unit-economics.user.md +4 -0
- package/skills/egbe-os-product-market-research/references/prompts/value-proposition.md +113 -0
- package/skills/egbe-os-product-market-research/references/prompts/value-proposition.user.md +4 -0
- package/skills/egbe-os-product-market-research/references/workflows/acquisition-channels.md +27 -0
- package/skills/egbe-os-product-market-research/references/workflows/channel-footprint.md +163 -0
- package/skills/egbe-os-product-market-research/references/workflows/community-demand.md +100 -0
- package/skills/egbe-os-product-market-research/references/workflows/competitive-landscape.md +27 -0
- package/skills/egbe-os-product-market-research/references/workflows/competitor-ads.md +82 -0
- package/skills/egbe-os-product-market-research/references/workflows/competitor-set.md +300 -0
- package/skills/egbe-os-product-market-research/references/workflows/creative-patterns.md +228 -0
- package/skills/egbe-os-product-market-research/references/workflows/demand-validation.md +27 -0
- package/skills/egbe-os-product-market-research/references/workflows/fleet-prior.md +80 -0
- package/skills/egbe-os-product-market-research/references/workflows/funnel-teardown.md +184 -0
- package/skills/egbe-os-product-market-research/references/workflows/geography-comparison.md +84 -0
- package/skills/egbe-os-product-market-research/references/workflows/keyword-economics.md +122 -0
- package/skills/egbe-os-product-market-research/references/workflows/lifecycle-capture.md +218 -0
- package/skills/egbe-os-product-market-research/references/workflows/local-research.md +55 -0
- package/skills/egbe-os-product-market-research/references/workflows/market-size-and-dynamics.md +27 -0
- package/skills/egbe-os-product-market-research/references/workflows/preview.md +175 -0
- package/skills/egbe-os-product-market-research/references/workflows/pricing-and-monetization.md +27 -0
- package/skills/egbe-os-product-market-research/references/workflows/recommendations.md +35 -0
- package/skills/egbe-os-product-market-research/references/workflows/review-mining.md +76 -0
- package/skills/egbe-os-product-market-research/references/workflows/target-audience.md +27 -0
- package/skills/egbe-os-product-market-research/references/workflows/tiktok-reels-market-trends.md +46 -0
- package/skills/egbe-os-product-market-research/references/workflows/unit-economics.md +27 -0
- package/skills/egbe-os-product-market-research/references/workflows/value-proposition.md +27 -0
- package/skills/egbe-os-product-market-research/scripts/build-organic-trend-context.py +167 -0
- package/skills/egbe-os-product-market-research/scripts/build-preview-context.py +91 -0
- package/skills/egbe-os-product-market-research/scripts/build-research-query.py +225 -0
- package/skills/egbe-os-product-market-research/scripts/channel-footprint-model.py +294 -0
- package/skills/egbe-os-product-market-research/scripts/connection_identity.py +22 -0
- package/skills/egbe-os-product-market-research/scripts/creative-model.py +364 -0
- package/skills/egbe-os-product-market-research/scripts/creative-selection.py +113 -0
- package/skills/egbe-os-product-market-research/scripts/creative-semantics.py +365 -0
- package/skills/egbe-os-product-market-research/scripts/creative-video.py +542 -0
- package/skills/egbe-os-product-market-research/scripts/egbe_artifacts.py +24 -0
- package/skills/egbe-os-product-market-research/scripts/finalize-organic-trend-watch.py +304 -0
- package/skills/egbe-os-product-market-research/scripts/funnel-email-review.py +97 -0
- package/skills/egbe-os-product-market-research/scripts/funnel-model.py +966 -0
- package/skills/egbe-os-product-market-research/scripts/funnel_features.py +50 -0
- package/skills/egbe-os-product-market-research/scripts/geography-comparison-contract.py +172 -0
- package/skills/egbe-os-product-market-research/scripts/geography-comparison.py +169 -0
- package/skills/egbe-os-product-market-research/scripts/keyword-forecast.py +61 -0
- package/skills/egbe-os-product-market-research/scripts/keyword-locale-publication.py +136 -0
- package/skills/egbe-os-product-market-research/scripts/lifecycle-start.py +190 -0
- package/skills/egbe-os-product-market-research/scripts/persist-research-report.py +63 -0
- package/skills/egbe-os-product-market-research/scripts/research-artifact-io.py +281 -0
- package/skills/egbe-os-product-market-research/scripts/research-evidence.py +496 -0
- package/skills/egbe-os-product-market-research/scripts/research-policy.py +33 -0
- package/skills/egbe-os-product-market-research/scripts/research-section-runtime.py +343 -0
- package/skills/egbe-os-product-market-research/scripts/research-section-workflow.py +288 -0
- package/skills/egbe-os-product-market-research/scripts/research_integrity.py +122 -0
- package/skills/egbe-os-product-market-research/scripts/review-research-completion.py +306 -0
- package/skills/egbe-os-product-market-research/scripts/run-acquisition-channels.py +72 -0
- package/skills/egbe-os-product-market-research/scripts/run-channel-footprint.py +2258 -0
- package/skills/egbe-os-product-market-research/scripts/run-community-demand.py +1603 -0
- package/skills/egbe-os-product-market-research/scripts/run-competitive-landscape.py +66 -0
- package/skills/egbe-os-product-market-research/scripts/run-competitor-ads.py +1156 -0
- package/skills/egbe-os-product-market-research/scripts/run-competitor-set.py +2514 -0
- package/skills/egbe-os-product-market-research/scripts/run-creative-patterns.py +2042 -0
- package/skills/egbe-os-product-market-research/scripts/run-demand-validation.py +72 -0
- package/skills/egbe-os-product-market-research/scripts/run-fleet-prior.py +652 -0
- package/skills/egbe-os-product-market-research/scripts/run-funnel-teardown.py +493 -0
- package/skills/egbe-os-product-market-research/scripts/run-keyword-economics.py +1443 -0
- package/skills/egbe-os-product-market-research/scripts/run-lifecycle-capture.py +1543 -0
- package/skills/egbe-os-product-market-research/scripts/run-market-size-and-dynamics.py +66 -0
- package/skills/egbe-os-product-market-research/scripts/run-os-research.py +311 -0
- package/skills/egbe-os-product-market-research/scripts/run-pricing-and-monetization.py +71 -0
- package/skills/egbe-os-product-market-research/scripts/run-review-mining.py +1051 -0
- package/skills/egbe-os-product-market-research/scripts/run-target-audience.py +66 -0
- package/skills/egbe-os-product-market-research/scripts/run-unit-economics.py +71 -0
- package/skills/egbe-os-product-market-research/scripts/run-value-proposition.py +67 -0
- package/skills/egbe-os-product-market-research/scripts/upsert-markdown-section.py +156 -0
- package/skills/egbe-os-product-market-research/scripts/walk-funnels.py +249 -0
- package/skills/egbe-os-product-market-research/scripts/write-preview.py +710 -0
- package/skills/egbe-os-product-market-research/scripts/write-recommendations.py +272 -0
- package/skills/egbe-os-product-report/SKILL.md +150 -0
- package/skills/egbe-os-product-report/references/artifacts.md +84 -0
- package/skills/egbe-os-product-report/references/brief.md +34 -0
- package/skills/egbe-os-product-report/references/daily.md +76 -0
- package/skills/egbe-os-product-report/references/sources.md +68 -0
- package/skills/egbe-os-product-routines/SKILL.md +166 -0
- package/skills/egbe-os-product-routines/references/catalog.md +22 -0
- package/skills/egbe-os-product-routines/references/continuation-check.md +41 -0
- package/skills/egbe-os-product-routines/references/product-reporting.md +163 -0
- package/skills/egbe-os-product-routines/references/run-preset.md +32 -0
- package/skills/egbe-os-quickstart/scripts/egbe-curl.py +357 -0
- package/skills/egbe-os-quiz-funnel/SKILL.md +152 -0
- package/skills/egbe-os-quiz-funnel/agents/openai.yaml +4 -0
- package/skills/egbe-os-quiz-funnel/assets/engine/quiz-engine.d.mts +224 -0
- package/skills/egbe-os-quiz-funnel/assets/engine/quiz-engine.mjs +652 -0
- package/skills/egbe-os-quiz-funnel/assets/engine/quiz-engine.test.mjs +764 -0
- package/skills/egbe-os-quiz-funnel/assets/engine/quiz-history.d.mts +31 -0
- package/skills/egbe-os-quiz-funnel/assets/engine/quiz-history.mjs +87 -0
- package/skills/egbe-os-quiz-funnel/assets/engine/quiz-history.test.mjs +265 -0
- package/skills/egbe-os-quiz-funnel/assets/engine/quiz-reference.test.mjs +254 -0
- package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/QUIZ.md +195 -0
- package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/quiz.json +421 -0
- package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/quiz.public.json +369 -0
- package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/validation.json +21 -0
- package/skills/egbe-os-quiz-funnel/assets/reference/index.html +26 -0
- package/skills/egbe-os-quiz-funnel/assets/reference/quiz-bootstrap.js +31 -0
- package/skills/egbe-os-quiz-funnel/assets/reference/quiz-early-actions.mjs +11 -0
- package/skills/egbe-os-quiz-funnel/assets/reference/quiz-first-screen.mjs +32 -0
- package/skills/egbe-os-quiz-funnel/assets/reference/quiz-page.mjs +480 -0
- package/skills/egbe-os-quiz-funnel/assets/reference/quiz.css +264 -0
- package/skills/egbe-os-quiz-funnel/references/competitor-teardown.md +159 -0
- package/skills/egbe-os-quiz-funnel/references/conversion-handoff.md +156 -0
- package/skills/egbe-os-quiz-funnel/references/implementation.md +207 -0
- package/skills/egbe-os-quiz-funnel/references/inputs.md +37 -0
- package/skills/egbe-os-quiz-funnel/references/measurement.md +122 -0
- package/skills/egbe-os-quiz-funnel/references/spec-contract.md +335 -0
- package/skills/egbe-os-quiz-funnel/references/verification.md +101 -0
- package/skills/egbe-os-quiz-funnel/references/walk-mechanics.v2.json +18 -0
- package/skills/egbe-os-quiz-funnel/scripts/compile-quiz-spec.py +1869 -0
- package/skills/egbe-os-quiz-funnel/scripts/prepare-research-identity.py +66 -0
- package/skills/egbe-os-reddit-ads/SKILL.md +121 -0
- package/skills/egbe-os-reddit-ads/assets/static-banners/bold-statement/schema.json +41 -0
- package/skills/egbe-os-reddit-ads/assets/static-banners/bold-statement/template.html +106 -0
- package/skills/egbe-os-reddit-ads/assets/static-banners/data-proof/schema.json +61 -0
- package/skills/egbe-os-reddit-ads/assets/static-banners/data-proof/template.html +151 -0
- package/skills/egbe-os-reddit-ads/assets/static-banners/honest-breakdown/schema.json +91 -0
- package/skills/egbe-os-reddit-ads/assets/static-banners/honest-breakdown/template.html +185 -0
- package/skills/egbe-os-reddit-ads/assets/static-banners/question-hook/schema.json +51 -0
- package/skills/egbe-os-reddit-ads/assets/static-banners/question-hook/template.html +121 -0
- package/skills/egbe-os-reddit-ads/assets/static-banners/reddit-post-style/schema.json +87 -0
- package/skills/egbe-os-reddit-ads/assets/static-banners/reddit-post-style/template.html +212 -0
- package/skills/egbe-os-reddit-ads/references/creative/html-to-png-pipeline.md +123 -0
- package/skills/egbe-os-reddit-ads/references/creative/static-banner-qa.md +12 -0
- package/skills/egbe-os-reddit-ads/references/creative/static-banner-system.md +16 -0
- package/skills/egbe-os-reddit-ads/references/destination-requirements.md +36 -0
- package/skills/egbe-os-reddit-ads/references/runtime/api-reference.md +435 -0
- package/skills/egbe-os-reddit-ads/references/runtime/artifacts.md +57 -0
- package/skills/egbe-os-reddit-ads/references/runtime/monitoring.md +64 -0
- package/skills/egbe-os-reddit-ads/references/runtime/pixel-and-tracking.md +49 -0
- package/skills/egbe-os-reddit-ads/references/runtime/policies.md +19 -0
- package/skills/egbe-os-reddit-ads/references/runtime/shared-analytics-attribution.md +14 -0
- package/skills/egbe-os-reddit-ads/references/workflows/build-paused.md +35 -0
- package/skills/egbe-os-reddit-ads/references/workflows/launch-ready.md +19 -0
- package/skills/egbe-os-reddit-ads/references/workflows/launch.md +32 -0
- package/skills/egbe-os-reddit-ads/references/workflows/readiness.md +9 -0
- package/skills/egbe-os-reddit-ads/scripts/capture-ad.sh +178 -0
- package/skills/egbe-os-reddit-ads/scripts/validate-reddit-artifacts.py +187 -0
- package/skills/egbe-os-report-ui/SKILL.md +133 -0
- package/skills/egbe-os-report-ui/assets/egbe-wordmark.svg +9 -0
- package/skills/egbe-os-report-ui/assets/examples/components.html +417 -0
- package/skills/egbe-os-report-ui/assets/examples/editorial.html +209 -0
- package/skills/egbe-os-report-ui/assets/scaffold.html +179 -0
- package/skills/egbe-os-report-ui/references/components.md +209 -0
- package/skills/egbe-os-research/SKILL.md +125 -0
- package/skills/egbe-os-saas-unit-economics/SKILL.md +188 -0
- package/skills/egbe-os-scrape/SKILL.md +160 -0
- package/skills/egbe-os-search/SKILL.md +182 -0
- package/skills/egbe-os-search/references/google-places.md +81 -0
- package/skills/egbe-os-support/SKILL.md +149 -0
- package/skills/egbe-os-telemetry/SKILL.md +344 -0
- package/skills/egbe-os-telemetry/references/harnesses/claude-code.md +97 -0
- package/skills/egbe-os-telemetry/references/harnesses/codex.md +22 -0
- package/skills/egbe-os-telemetry/references/harnesses/hermes.md +39 -0
- package/skills/egbe-os-telemetry/references/harnesses/openclaw.md +139 -0
- package/skills/egbe-os-telemetry/references/harnesses/opencode.md +28 -0
- package/skills/egbe-os-tools/SKILL.md +180 -0
- package/skills/egbe-os-tools/references/theona.md +26 -0
- package/skills/egbe-os-wallet/SKILL.md +181 -0
- package/skills/egbe-setup/EGBE.md +484 -0
- package/skills/egbe-setup/SKILL.md +116 -0
- package/skills/egbe-setup/references/project.md +80 -0
- package/state.js +37 -0
- 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.
|