@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,196 @@
|
|
|
1
|
+
# Meta Pixel Install Contract
|
|
2
|
+
|
|
3
|
+
The Meta pixel is the ad network's own view of the product. OS analytics defines
|
|
4
|
+
canonical product events (see
|
|
5
|
+
`references/runtime/shared-analytics-attribution.md`); the pixel exists so Meta
|
|
6
|
+
can optimize delivery and so campaign reports have a channel-side conversion.
|
|
7
|
+
|
|
8
|
+
One shared pixel serves every egbe product. Products are separated by the
|
|
9
|
+
destination URL and by a product-scoped payload on every event — never by a
|
|
10
|
+
per-product pixel and never by a product-specific event name.
|
|
11
|
+
|
|
12
|
+
## Pixel ID
|
|
13
|
+
|
|
14
|
+
Read `GET /ads/meta/raw/tracking?product_slug=<product_slug>` with the project
|
|
15
|
+
OS credentials. It returns `pixel_id` and `event_parameters`; no provider
|
|
16
|
+
credentials are needed. Save the public pixel ID as `NEXT_PUBLIC_META_PIXEL_ID`
|
|
17
|
+
in the app's public configuration. If Next.js inlines it, supply it before the
|
|
18
|
+
build (for example through an imported public JSON config), not only through
|
|
19
|
+
deploy runtime `env`. See `egbe-os-deploy` for build-time configuration. No deploy helper
|
|
20
|
+
installs the pixel or injects this value automatically.
|
|
21
|
+
|
|
22
|
+
- Read the ID from the configured `NEXT_PUBLIC_META_PIXEL_ID` value in product code.
|
|
23
|
+
- Never hardcode a pixel ID, and never add a hardcoded fallback. Sending to the
|
|
24
|
+
wrong dataset is worse than sending nothing: the custom conversions live on
|
|
25
|
+
one pixel only.
|
|
26
|
+
- If the env var is missing, render no pixel and report `pixel_state`
|
|
27
|
+
`not_configured` in `tracking.json`.
|
|
28
|
+
|
|
29
|
+
## Placement
|
|
30
|
+
|
|
31
|
+
Install the base snippet in the shared root layout so it loads on every page —
|
|
32
|
+
landing, signup, checkout, and in-product. Installing it only on the landing
|
|
33
|
+
page is insufficient.
|
|
34
|
+
|
|
35
|
+
Initialize the pixel only (`fbq('init', id)`). Do not put
|
|
36
|
+
`fbq('track','PageView')` inside the base snippet: page views are fired
|
|
37
|
+
explicitly so single-page navigations are counted and non-funnel pages can be
|
|
38
|
+
excluded.
|
|
39
|
+
|
|
40
|
+
## Event Contract
|
|
41
|
+
|
|
42
|
+
Read `GET /ads/meta/raw/tracking?product_slug=<product_slug>` once during setup.
|
|
43
|
+
Save the returned `event_parameters` in the product's public tracking config and
|
|
44
|
+
in `tracking.json`; send them on every pixel event. They contain `content_name`
|
|
45
|
+
and `product_name` (the slug), plus `egbe_product_id` (the stable product identity
|
|
46
|
+
returned by OS). This distinguishes even identical slugs in different projects.
|
|
47
|
+
The read creates no Meta resources and also works for traffic campaigns.
|
|
48
|
+
|
|
49
|
+
```javascript
|
|
50
|
+
fbq('trackCustom', 'Activation', { ...eventParameters, activation_type: 'first_item_created' });
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
| OS analytics event | Meta browser event | Type |
|
|
54
|
+
|---|---|---|
|
|
55
|
+
| page open on a public funnel path | `PageView` | standard |
|
|
56
|
+
| `activated` | `Activation` | custom (`trackCustom`) |
|
|
57
|
+
| `signup_completed` | `Lead` | standard |
|
|
58
|
+
| `purchase` | `Purchase` (with `value`, `currency`) | standard |
|
|
59
|
+
|
|
60
|
+
Use these exact names for every product. Do not invent product-specific event
|
|
61
|
+
names such as `<Product>Activation` or `Signup_<slug>`: a shared name plus
|
|
62
|
+
the returned event parameters mean one custom conversion shape works for the whole fleet and
|
|
63
|
+
products stay comparable.
|
|
64
|
+
|
|
65
|
+
### PageView
|
|
66
|
+
|
|
67
|
+
Fire on real opens of the public funnel paths, including client-side route
|
|
68
|
+
changes between them. Track the last path a PageView was sent for rather than a
|
|
69
|
+
once-per-mount flag, otherwise SPA navigation silently undercounts.
|
|
70
|
+
|
|
71
|
+
### Activation
|
|
72
|
+
|
|
73
|
+
The event name stays `Activation`; its product-specific meaning is recorded
|
|
74
|
+
in `activation_type` and the tracking notes. Implement the definition chosen
|
|
75
|
+
for the product/test, firing only after that action actually succeeds.
|
|
76
|
+
Deduplicate according to that event's intended counting unit so route changes,
|
|
77
|
+
retries and remounts do not invent additional actions.
|
|
78
|
+
|
|
79
|
+
If its definition differs from the canonical `activated` event, record that
|
|
80
|
+
difference explicitly. Installing tracking must not silently change the supplied
|
|
81
|
+
event definition, product access requirements or campaign objective.
|
|
82
|
+
|
|
83
|
+
### Delivery
|
|
84
|
+
|
|
85
|
+
The pixel loader is asynchronous. Retry until `window.fbq` is a function
|
|
86
|
+
(short interval, bounded attempts) instead of dropping the event on a fast
|
|
87
|
+
hydration. Pixel calls are best-effort and must never break the product flow.
|
|
88
|
+
|
|
89
|
+
## Source diagnostic before publication
|
|
90
|
+
|
|
91
|
+
Run the bundled checker against the product source and a JSON file containing
|
|
92
|
+
only the public pixel configuration:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
python3 <meta-ads-skill>/scripts/check-pixel.py --root <product-root> \
|
|
96
|
+
--pixel-config <public-config.json>
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
It flags literal pixel IDs in code, missing configuration reads, missing
|
|
100
|
+
PageView/Activation calls and product identity parameters. Lead and Purchase
|
|
101
|
+
checks apply when signup/payment paths exist. It recognizes simple constants
|
|
102
|
+
and shared event senders; inspect findings against the actual implementation
|
|
103
|
+
when a different delivery abstraction is used. A JSON public config containing
|
|
104
|
+
the OS-provided ID is legitimate; a copied ID or hardcoded fallback in code is
|
|
105
|
+
not.
|
|
106
|
+
|
|
107
|
+
This is a focused source diagnostic, not an automatic deploy gate or proof of
|
|
108
|
+
network delivery. Verify the actual journey and product-scoped payload in the
|
|
109
|
+
browser as described below, including any signup/purchase steps the app owns.
|
|
110
|
+
A product without signup or payments does not need artificial Lead/Purchase
|
|
111
|
+
steps to pass a checker.
|
|
112
|
+
|
|
113
|
+
## Custom Conversion
|
|
114
|
+
|
|
115
|
+
The browser events and their slug parameters are sufficient for Events Manager,
|
|
116
|
+
product reporting, and traffic campaigns. A custom conversion is an optional,
|
|
117
|
+
finite account-level resource: do not create one at product deploy or for a
|
|
118
|
+
traffic experiment. Only if a conversion-objective campaign is deliberately
|
|
119
|
+
introduced, create (or reuse) one to select that product's `Activation` as the
|
|
120
|
+
campaign optimization goal:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/ads/meta/raw/customconversions" -sS -X POST \
|
|
124
|
+
-H "Content-Type: application/json" \
|
|
125
|
+
-H "Idempotency-Key: <stable-key-for-this-conversion>" \
|
|
126
|
+
-d '{
|
|
127
|
+
"name": "<Product> — Activation",
|
|
128
|
+
"product_slug": "<product_slug>",
|
|
129
|
+
"event_name": "Activation",
|
|
130
|
+
"custom_event_type": "OTHER"
|
|
131
|
+
}'
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Record the returned conversion id and `event_parameters` in `tracking.json`.
|
|
135
|
+
OS builds the product-scoped rule and verifies it against Meta. Reuse the same
|
|
136
|
+
Idempotency-Key and body on retry. If the outcome is unconfirmed, retain the key
|
|
137
|
+
and report the blocker for Egbe team recovery.
|
|
138
|
+
|
|
139
|
+
For a conversion-objective campaign, pass that exact id as
|
|
140
|
+
`CampaignSpec.custom_conversion_id`. The OS creates the ad set's
|
|
141
|
+
`promoted_object` itself, using the configured shared pixel plus this id; do
|
|
142
|
+
not supply a pixel id from product code or an artifact. The gateway rejects a
|
|
143
|
+
conversion optimization request without a custom conversion or with a different
|
|
144
|
+
pixel.
|
|
145
|
+
|
|
146
|
+
## Verification
|
|
147
|
+
|
|
148
|
+
Do not report the pixel as working from code inspection alone:
|
|
149
|
+
|
|
150
|
+
1. Load the live URL and confirm a request to
|
|
151
|
+
`https://www.facebook.com/tr/?id=<pixel_id>&ev=PageView` carrying
|
|
152
|
+
`cd[content_name]=<product_slug>` and `cd[egbe_product_id]` matching OS tracking config.
|
|
153
|
+
2. Perform the activation action on the live site and confirm a request with
|
|
154
|
+
`ev=Activation` and the product-scoped payload.
|
|
155
|
+
3. Read `GET $OS_URL/ads/meta/raw/pixels` and check `last_fired_time`.
|
|
156
|
+
|
|
157
|
+
These browser checks establish outgoing instrumentation, not Meta receipt or
|
|
158
|
+
custom-conversion matching. Record the evidence separately. `eligible` on the
|
|
159
|
+
conversion verifies its configuration only; `eligibility.event_matching` stays
|
|
160
|
+
`unverified`, and a clean plan does not upgrade that result.
|
|
161
|
+
|
|
162
|
+
If the actual event request lacks `content_name` or `egbe_product_id`, the
|
|
163
|
+
product-scoped rule cannot match that event. Report tracking as `degraded`, naming
|
|
164
|
+
the missing fields and observed pixel/event. Source code passing an object to
|
|
165
|
+
`fbq` does not establish what the browser sent. Do not mark the conversion as
|
|
166
|
+
working from `eligible`, `plan.ok`, a shared-pixel timestamp or an event name alone.
|
|
167
|
+
Use authorized provider diagnostics, when available, to distinguish receipt from
|
|
168
|
+
actual conversion matching. If that evidence is unavailable, report matching as
|
|
169
|
+
unverified. Missing parameters alone do not establish a category restriction;
|
|
170
|
+
check the evidence before naming a provider-side cause. Preserve the product
|
|
171
|
+
rule: event-only or caller-authored domain rules are not supported alternatives.
|
|
172
|
+
|
|
173
|
+
Two traps when reading Events Manager:
|
|
174
|
+
|
|
175
|
+
- A newly introduced custom event name does not appear as its own row
|
|
176
|
+
immediately — allow up to about an hour before concluding it is missing. The
|
|
177
|
+
Test events tab shows it instantly and is the only instrument that separates
|
|
178
|
+
"not delivered" from "not displayed yet".
|
|
179
|
+
- The `Integration` column aggregates every source that ever sent that event
|
|
180
|
+
name across the whole dataset. A browser event can show as `Conversions API`
|
|
181
|
+
because some other property sends the same name server-side. Never use that
|
|
182
|
+
column as evidence about a specific product's events.
|
|
183
|
+
- `last_fired_time` on pixels and custom conversions is unreliable on a shared
|
|
184
|
+
account: it stays empty on conversions that are in fact matching. Confirm in
|
|
185
|
+
Events Manager, not from that field.
|
|
186
|
+
|
|
187
|
+
## Tracking State
|
|
188
|
+
|
|
189
|
+
| State | Meaning |
|
|
190
|
+
|---|---|
|
|
191
|
+
| `verified` | outgoing PageView and the product's conversion event observed live with the configured pixel and both product parameters; provider receipt and conversion matching are reported separately |
|
|
192
|
+
| `degraded` | pixel installed but a required event or product parameter is missing, or a planned conversion goal cannot be verified |
|
|
193
|
+
| `not_configured` | no pixel ID in the app environment |
|
|
194
|
+
|
|
195
|
+
Conversion optimization needs a verified eligible product-scoped custom
|
|
196
|
+
conversion; a traffic campaign does not require creating that resource.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Meta attribution
|
|
2
|
+
|
|
3
|
+
Read `/analytics/events` and the product's `/analytics/<slug>/tracking`
|
|
4
|
+
contract. Use canonical product event names; put channel/product details in
|
|
5
|
+
payloads and UTMs. Do not create synthetic product events as readiness proof.
|
|
6
|
+
|
|
7
|
+
Destination URLs retain stable `utm_source=meta`, `utm_medium=paid_social`,
|
|
8
|
+
`utm_campaign=<campaign slug/id>` and meaningful `utm_content`.
|
|
9
|
+
Use `utm_term` when needed for audience/placement. Do not put secrets or direct
|
|
10
|
+
personal identifiers in UTMs.
|
|
11
|
+
|
|
12
|
+
Read platform results and product stats/campaigns separately. Compare compatible
|
|
13
|
+
windows and attribution scope; site-wide observations are not campaign-attributed
|
|
14
|
+
conversions. Missing UTM slicing, delayed events and unconfigured tracking must
|
|
15
|
+
remain explicit, not zero. Pixel/platform events support network optimization;
|
|
16
|
+
the product event contract is maintained by analytics.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Build a paused Meta tree
|
|
2
|
+
|
|
3
|
+
Read the [API](../runtime/api-reference.md) and save
|
|
4
|
+
[execution records](../runtime/artifacts.md). Resolve existing IDs or uncertain
|
|
5
|
+
attempts before creating. Do not recreate objects to repair local documentation.
|
|
6
|
+
|
|
7
|
+
Prepare the requested `CampaignSpec`: `name`, `product_slug`,
|
|
8
|
+
`objective`, `optimization_goal`, positive `daily_budget_usd`,
|
|
9
|
+
`budget_level` (`campaign` or `adset`), `destination_url`, `segment`,
|
|
10
|
+
`destination_language`, `destination_language_locales`, `targeting` and
|
|
11
|
+
`creatives`. Each image creative has an uploaded Meta `image_ref` hash,
|
|
12
|
+
`headline`, `primary_text` and supported `cta`. Resolve locale IDs through
|
|
13
|
+
targeting search and include matching IDs in `targeting.locales`.
|
|
14
|
+
Conversion optimization requires the verified product `custom_conversion_id`.
|
|
15
|
+
|
|
16
|
+
1. `POST /ads/meta/plan` validates without Meta writes, quota consumption or a
|
|
17
|
+
wallet hold. Resolve returned blockers, not by probing creates.
|
|
18
|
+
2. Preserve the exact clean spec, returned plan and token. Check targeting,
|
|
19
|
+
assets and budget against the authorized inputs. The token does not
|
|
20
|
+
establish consent. A clean plan verifies configuration; its conversion
|
|
21
|
+
eligibility does not prove live event matching. Use the
|
|
22
|
+
[pixel checks](../runtime/pixel-install.md#verification) for tracking evidence.
|
|
23
|
+
3. Apply only with required approval and current authorization:
|
|
24
|
+
`POST /ads/meta/apply` with `{"spec": {...}, "plan_token": "...", "approved": true}`.
|
|
25
|
+
OS derives the retry key from this token. Exactly one ad set is supported
|
|
26
|
+
because there is no per-ad ad-set mapping.
|
|
27
|
+
4. Save campaign/ad-set/ad IDs immediately. Apply contains campaign-level
|
|
28
|
+
readback only. Read `/ads/meta/campaigns/{id}/state?expect=PAUSED` plus
|
|
29
|
+
raw configuration to verify parent IDs, budget, media and destination.
|
|
30
|
+
Keep requested values separate from observations.
|
|
31
|
+
|
|
32
|
+
Per-operation budget guards and wallet reserves are server-owned. Do not impose
|
|
33
|
+
a local daily cap or bypass a rejected budget via raw calls.
|
|
34
|
+
Apply compensation is best-effort, not proof of an empty account.
|
|
35
|
+
After timeout or `apply_rolled_back`, use [recovery](recovery.md) before
|
|
36
|
+
re-planning. The tree stays PAUSED; building does not activate it.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Read-only Meta launch checks
|
|
2
|
+
|
|
3
|
+
Inspect exact selected campaign/child IDs, not name-matched substitutes.
|
|
4
|
+
No provider mutation, create, repair or schema probing belongs in this check.
|
|
5
|
+
|
|
6
|
+
Read the authorized configuration and saved IDs; refresh
|
|
7
|
+
`/ads/meta/campaigns/{id}/state?expect=PAUSED` and raw configuration needed
|
|
8
|
+
to compare targeting, budget, media and destination to the requested values. Verify paused
|
|
9
|
+
state and parent IDs; image ads need image hashes, video ads also need thumbnails.
|
|
10
|
+
Check account access, destination and measurement required by the chosen
|
|
11
|
+
objective; see [pixel](../runtime/pixel-install.md) and
|
|
12
|
+
[attribution](../runtime/shared-analytics-attribution.md).
|
|
13
|
+
|
|
14
|
+
Report mismatches/unavailable reads explicitly. Missing objects require separately
|
|
15
|
+
authorized build/repair, not a write disguised as readiness. Activate through
|
|
16
|
+
[launch](launch.md) only when currently authorized.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Activate or resume Meta objects
|
|
2
|
+
|
|
3
|
+
Use current authorization and exact selected IDs. Refresh
|
|
4
|
+
[read-only checks](launch-ready.md); do not create during activation.
|
|
5
|
+
Preserve audience, destination, assets, objective and budget.
|
|
6
|
+
|
|
7
|
+
Activate selected ads, then ad sets, then campaign:
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
POST /ads/meta/raw/ads/{ad_id}/status {"status":"ACTIVE"}
|
|
11
|
+
POST /ads/meta/raw/adsets/{adset_id}/status {"status":"ACTIVE"}
|
|
12
|
+
POST /ads/meta/campaigns/{campaign_id}/launch
|
|
13
|
+
GET /ads/meta/campaigns/{campaign_id}/state?expect=ACTIVE
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Save mutation responses and timestamped live readback. Only the state response
|
|
17
|
+
establishes configured tree state; report `drift` when partial.
|
|
18
|
+
`delivering:true` is an all-levels-ACTIVE check, not observed spend/impressions.
|
|
19
|
+
Do not invent launch/restart time from intent or a later monitoring observation.
|
|
20
|
+
|
|
21
|
+
After an ambiguous response read first. Do not recreate or toggle to clear
|
|
22
|
+
uncertainty. Report unconfirmed state and the required recovery read.
|
|
23
|
+
Activation does not install a monitoring job or scheduled pause.
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Read Meta state and metrics
|
|
2
|
+
|
|
3
|
+
Resolve the approved campaign, ad-set and ad cohorts from the saved plan,
|
|
4
|
+
including intentionally paused or retired objects and the existing stop latch.
|
|
5
|
+
A read never authorizes restarting a safety pause.
|
|
6
|
+
|
|
7
|
+
For a running safety check, reuse two observations:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
GET $OS_URL/ads/meta/campaigns/{id}/state?include_configuration=true
|
|
11
|
+
GET $OS_URL/ads/meta/campaigns/{id}/results?period=MAXIMUM
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
The state response's `configuration` contains the campaign and fully paginated
|
|
15
|
+
ad-set/ad details with `complete=true`; `observed_at` and `provider_diagnostics`
|
|
16
|
+
accompany that snapshot.
|
|
17
|
+
Reuse it for the approved configuration checks (budget, targeting, creative and
|
|
18
|
+
URL identity) and exact cohort statuses; do not GET every object again for each
|
|
19
|
+
assertion. Preserve the frozen checks: missing fields or incomplete enumeration
|
|
20
|
+
remain uncertainty. A retired PAUSED ad is not an unexpected pause in an approved
|
|
21
|
+
ACTIVE ad, and it must not be restarted to make the whole-tree verdict green.
|
|
22
|
+
The existing `delivering` flag tests whether the entire returned tree is ACTIVE;
|
|
23
|
+
it does not prove impressions or override the approved cohort map.
|
|
24
|
+
|
|
25
|
+
Use the chosen-window report once for all spend, impression and link-click
|
|
26
|
+
checks. Check `metric_availability` for every field needed by the existing guard;
|
|
27
|
+
one available metric does not make the others available. MAXIMUM is suitable for a lifetime counter; choose an explicit range
|
|
28
|
+
when the approved counter has another scope. Check `report.query`, returned
|
|
29
|
+
bounds, native currency, availability and the actual account-local day before
|
|
30
|
+
comparing with the existing stop thresholds. Do not reset counters or use TODAY
|
|
31
|
+
as a replacement for a lifetime cap. Empty data is unknown. A configured ACTIVE
|
|
32
|
+
tree does not resolve missing or delayed metrics.
|
|
33
|
+
|
|
34
|
+
`configuration.campaign.account_id` identifies the actual campaign account.
|
|
35
|
+
Retain verified account currency/timezone with that identity. The generic
|
|
36
|
+
`/ads/meta/account` describes the currently configured fleet account, which may
|
|
37
|
+
differ for a legacy campaign; do not borrow its timezone for another account.
|
|
38
|
+
If matching account context is unavailable, retain the safety stop and request
|
|
39
|
+
the missing read-only account context.
|
|
40
|
+
|
|
41
|
+
On a one-page tree these two observations use four Graph reads: campaign,
|
|
42
|
+
ad sets, ads, and insights. Extra pages increase this; inspect the actual
|
|
43
|
+
`provider_diagnostics.request_count` rather than equating one OS request to one
|
|
44
|
+
Meta call. The full configuration read is bounded and fails unavailable on
|
|
45
|
+
cycles, invalid continuation or exhausted pagination; partial trees never count
|
|
46
|
+
as a verified configuration.
|
|
47
|
+
|
|
48
|
+
On Meta code 17/subcode 2446079 or HTTP 429, save the error and its safe usage
|
|
49
|
+
context. OS retains the native HTTP status (including 400), with machine-readable
|
|
50
|
+
`data.error=meta_api_rate_limited`, native codes and any `retry_after_seconds`.
|
|
51
|
+
Honor a returned Retry-After before another diagnostic read. Native usage fields
|
|
52
|
+
and `estimated_time_to_regain_access` are observations, not an absolute allowance
|
|
53
|
+
or a recovery promise; an absent retry hint or a zero native estimate does not
|
|
54
|
+
certify that another call is safe. Do not blindly retry, perform another complete
|
|
55
|
+
audit to explain the same throttle, or toggle the campaign. Preserve the existing
|
|
56
|
+
pause-only response to uncertain status/cost coverage and verify the stop through
|
|
57
|
+
its established recovery path.
|
|
58
|
+
|
|
59
|
+
There is no universal supported five-minute cadence. Account for pagination,
|
|
60
|
+
other shared-identity traffic, observed usage and the approved safety requirement
|
|
61
|
+
when scheduling the next read. Once a stop is confirmed and latched, avoid
|
|
62
|
+
repeated full-tree/configuration polling; retain required stop verification,
|
|
63
|
+
late-cost reconciliation and the approved next check. Do not disable those
|
|
64
|
+
obligations or loosen thresholds to reduce calls.
|
|
65
|
+
|
|
66
|
+
[Insights](../runtime/insights-reference.md) defines window/currency/availability;
|
|
67
|
+
[attribution](../runtime/shared-analytics-attribution.md) covers separately sourced
|
|
68
|
+
product outcomes. Preserve request windows, observation times and limitations.
|
|
69
|
+
|
|
70
|
+
These are read operations. For an explicitly requested change use its write
|
|
71
|
+
endpoint and save the response/readback. A metrics read does not establish a new
|
|
72
|
+
activation timestamp. Preserve missing metrics as unavailable, not zero.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Pause Meta delivery
|
|
2
|
+
|
|
3
|
+
An exact owned campaign ID is enough to start. Read selected child IDs through
|
|
4
|
+
OS if needed; missing local campaign records do not block an authorized pause.
|
|
5
|
+
|
|
6
|
+
Pause through `POST /ads/meta/campaigns/{campaign_id}/pause`; when the task
|
|
7
|
+
includes the whole tree, also pause selected ads/ad sets through status routes.
|
|
8
|
+
Do not archive/delete as a substitute.
|
|
9
|
+
|
|
10
|
+
Read `/ads/meta/campaigns/{id}/state?expect=PAUSED` and preserve statuses/drift.
|
|
11
|
+
A parent pause can stop serving while children remain configured ACTIVE: report
|
|
12
|
+
what actually changed, not that every child paused. Failed readback leaves
|
|
13
|
+
confirmation pending.
|
|
14
|
+
|
|
15
|
+
Save actual confirmation time, IDs, receipts and known stop reason beside the
|
|
16
|
+
campaign. Do not substitute the planned deadline for factual time or infer a
|
|
17
|
+
past stop's cause. Missing analytics must not block stopping spend.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Meta uncertain-write recovery
|
|
2
|
+
|
|
3
|
+
Preserve exact request/spec, original plan token, IDs, timestamps, error and
|
|
4
|
+
last readback. An uncertain write is not a failed write.
|
|
5
|
+
|
|
6
|
+
After timeout or `409 apply_rolled_back`, do not re-plan first: OS derives
|
|
7
|
+
apply idempotency from the token and a new token can build a duplicate.
|
|
8
|
+
Inspect owned campaigns and exact returned IDs through state/raw reads.
|
|
9
|
+
Rollback attempts deletion, but failed deletes are ignored. An empty owned
|
|
10
|
+
list does not prove no unregistered provider object exists.
|
|
11
|
+
|
|
12
|
+
Reuse an unambiguously confirmed complete paused tree. Keep partial objects
|
|
13
|
+
paused while reconciling. Remove proven leftovers only when cleanup is authorized,
|
|
14
|
+
via per-level status routes; preserve evidence. Unclear identity/ownership needs
|
|
15
|
+
Egbe team reconciliation, not guessing from names or another create.
|
|
16
|
+
|
|
17
|
+
Once reconciliation confirms no surviving tree, retry the same payload/token if
|
|
18
|
+
usable; if expired, re-plan only after that confirmation. Repair local validation
|
|
19
|
+
failures locally, never with another campaign.
|
|
20
|
+
|
|
21
|
+
Resolve real locale/interest IDs for targeting errors; do not remove language
|
|
22
|
+
restrictions to bypass blockers. Missing binding, permissions or regulated-market
|
|
23
|
+
fields are explicit configuration/validation blockers.
|
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Focused Meta source diagnostic; live event delivery still requires browser verification."""
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
import argparse
|
|
5
|
+
import json
|
|
6
|
+
import os
|
|
7
|
+
import re
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
def read_text(path: Path, limit: int = 300_000) -> str:
|
|
12
|
+
return path.read_text(encoding="utf-8", errors="replace")[:limit]
|
|
13
|
+
|
|
14
|
+
META_PIXEL_LITERAL_PATTERNS = (
|
|
15
|
+
re.compile(r'''(?is)\b(?:NEXT_PUBLIC_)?META_PIXEL_ID\b[^\n;]{0,120}?["']\d{10,20}["']'''),
|
|
16
|
+
re.compile(r'''(?is)\bfbq\s*\(\s*["']init["']\s*,\s*["']\d{10,20}["']'''),
|
|
17
|
+
re.compile(r'''(?is)(?:facebook\.com/tr/\?id=|[?&]id=)["']?\d{10,20}\b'''),
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
# A direct `fbq('track'|'trackCustom', <name>, ...)` call. Do not widen this
|
|
21
|
+
# to arbitrary functions accepting `track`: generic analytics clients use the
|
|
22
|
+
# same calling convention and must not satisfy the Meta delivery contract.
|
|
23
|
+
META_PIXEL_DIRECT_CALL_PATTERN = re.compile(
|
|
24
|
+
r'''(?is)\b(?:window\s*\.\s*)?fbq\s*\(\s*["'](track|trackCustom)["']\s*,\s*([A-Za-z0-9_$."']+)'''
|
|
25
|
+
)
|
|
26
|
+
# Products may route calls through a retry/dedupe helper. A helper only counts
|
|
27
|
+
# when its body forwards its first two parameters to `fbq(method, event, ...)`.
|
|
28
|
+
# Function declarations cover the normal exported helper shape; arrow helpers
|
|
29
|
+
# are included because many product frontends use them instead.
|
|
30
|
+
META_PIXEL_FUNCTION_DECL_PATTERN = re.compile(
|
|
31
|
+
r'''(?im)\b(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*\(([^)]*)\)\s*\{'''
|
|
32
|
+
)
|
|
33
|
+
META_PIXEL_ARROW_DECL_PATTERN = re.compile(
|
|
34
|
+
r'''(?im)\b(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(?:async\s*)?\(([^)]*)\)\s*=>\s*\{'''
|
|
35
|
+
)
|
|
36
|
+
META_PIXEL_FORWARD_CALL_PATTERN = re.compile(
|
|
37
|
+
r'''(?is)\b(?:window\s*\.\s*)?fbq\s*\(\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*,\s*([A-Za-z_$][A-Za-z0-9_$]*)'''
|
|
38
|
+
)
|
|
39
|
+
# `const NAME = "value"` so a constant used as an event name can be resolved.
|
|
40
|
+
META_PIXEL_CONST_PATTERN = re.compile(
|
|
41
|
+
r'''(?m)^\s*(?:const|let|var)\s+([A-Za-z0-9_$]+)\s*(?::[^=\n]+)?=\s*["']([^"'\n]+)["']'''
|
|
42
|
+
)
|
|
43
|
+
# `from "x"`, `import "x"`, `require("x")` — used to follow a delivery module
|
|
44
|
+
# into the helper that builds its payload.
|
|
45
|
+
META_PIXEL_IMPORT_PATTERN = re.compile(
|
|
46
|
+
r'''(?is)\b(?:from|import|require\s*\()\s*["']([^"'\n]+)["']'''
|
|
47
|
+
)
|
|
48
|
+
# A product has a signup funnel / takes money — used to decide whether the
|
|
49
|
+
# matching Meta event is required, since not every product has either.
|
|
50
|
+
# Matched against whole path segments, not substrings: "register" as a
|
|
51
|
+
# substring also hits `register-service-worker.ts`, and demanding a Lead event
|
|
52
|
+
# from a product with no signup at all would block a correct deploy.
|
|
53
|
+
SIGNUP_PATH_SEGMENTS = frozenset({"signup", "sign-up", "signups", "register"})
|
|
54
|
+
PAYMENT_PATH_SEGMENTS = frozenset({"checkout", "billing", "payment", "payments"})
|
|
55
|
+
PAYMENT_ENV_HINTS = ("PAYMENTS_API_KEY", "STRIPE_SECRET_KEY", "PAYMENT_WEBHOOK_SECRET")
|
|
56
|
+
|
|
57
|
+
def _closing_brace(text: str, opening_brace: int) -> int:
|
|
58
|
+
"""Return the matching brace for a shallow JS function body, if present."""
|
|
59
|
+
depth = 0
|
|
60
|
+
for index in range(opening_brace, len(text)):
|
|
61
|
+
if text[index] == "{":
|
|
62
|
+
depth += 1
|
|
63
|
+
elif text[index] == "}":
|
|
64
|
+
depth -= 1
|
|
65
|
+
if depth == 0:
|
|
66
|
+
return index
|
|
67
|
+
return -1
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def meta_pixel_wrapper_names(text: str) -> set[str]:
|
|
71
|
+
"""Names of helpers demonstrably forwarding `(method, event)` to `fbq`."""
|
|
72
|
+
wrappers: set[str] = set()
|
|
73
|
+
for pattern in (META_PIXEL_FUNCTION_DECL_PATTERN, META_PIXEL_ARROW_DECL_PATTERN):
|
|
74
|
+
for match in pattern.finditer(text):
|
|
75
|
+
params = re.findall(r"[A-Za-z_$][A-Za-z0-9_$]*", match.group(2))
|
|
76
|
+
if len(params) < 2:
|
|
77
|
+
continue
|
|
78
|
+
end = _closing_brace(text, match.end() - 1)
|
|
79
|
+
if end < 0:
|
|
80
|
+
continue
|
|
81
|
+
body = text[match.end():end]
|
|
82
|
+
if any(method == params[0] and event == params[1]
|
|
83
|
+
for method, event in META_PIXEL_FORWARD_CALL_PATTERN.findall(body)):
|
|
84
|
+
wrappers.add(match.group(1))
|
|
85
|
+
return wrappers
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def _meta_pixel_call_pattern(function_name: str) -> re.Pattern[str]:
|
|
89
|
+
return re.compile(
|
|
90
|
+
rf'''(?is)\b{re.escape(function_name)}\s*\(\s*["'](track|trackCustom)["']\s*,\s*([A-Za-z0-9_$."']+)'''
|
|
91
|
+
)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def meta_pixel_events_sent(text: str) -> set[str]:
|
|
95
|
+
"""Event names a source file actually hands to fbq.
|
|
96
|
+
|
|
97
|
+
The name is often a constant (`fbq("trackCustom", ACTIVATION_EVENT, ...)`),
|
|
98
|
+
so resolve identifiers against the string constants declared in the same
|
|
99
|
+
text before giving up on a match.
|
|
100
|
+
"""
|
|
101
|
+
constants = dict(META_PIXEL_CONST_PATTERN.findall(text))
|
|
102
|
+
sent: set[str] = set()
|
|
103
|
+
call_patterns = [META_PIXEL_DIRECT_CALL_PATTERN]
|
|
104
|
+
call_patterns.extend(_meta_pixel_call_pattern(name) for name in meta_pixel_wrapper_names(text))
|
|
105
|
+
for pattern in call_patterns:
|
|
106
|
+
for _method, raw in pattern.findall(text):
|
|
107
|
+
argument = raw.strip()
|
|
108
|
+
if argument[:1] in {'"', "'"}:
|
|
109
|
+
sent.add(argument.strip("\"'"))
|
|
110
|
+
elif argument in constants:
|
|
111
|
+
sent.add(constants[argument])
|
|
112
|
+
return sent
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def meta_pixel_delivery_scope(files: list[Path], texts: list[str], depth: int = 3) -> str:
|
|
116
|
+
"""Text of the modules that take part in Meta event delivery.
|
|
117
|
+
|
|
118
|
+
Starts from the files that hand an event to the pixel and follows their
|
|
119
|
+
local imports. The contract asks products to share one payload helper, and
|
|
120
|
+
that helper legitimately lives in its own module — so scoping to files that
|
|
121
|
+
literally contain `fbq` would fail a compliant split, while scanning the
|
|
122
|
+
whole frontend would pass on an unrelated file that merely names the field.
|
|
123
|
+
"""
|
|
124
|
+
keys = [path.with_suffix("").as_posix().lower() for path in files]
|
|
125
|
+
wrapper_names = set().union(*(meta_pixel_wrapper_names(body) for body in texts))
|
|
126
|
+
selected = {
|
|
127
|
+
index for index, body in enumerate(texts)
|
|
128
|
+
if META_PIXEL_DIRECT_CALL_PATTERN.search(body)
|
|
129
|
+
or any(_meta_pixel_call_pattern(name).search(body) for name in wrapper_names)
|
|
130
|
+
}
|
|
131
|
+
frontier = set(selected)
|
|
132
|
+
for _ in range(depth):
|
|
133
|
+
discovered: set[int] = set()
|
|
134
|
+
for index in frontier:
|
|
135
|
+
for specifier in META_PIXEL_IMPORT_PATTERN.findall(texts[index]):
|
|
136
|
+
tail = specifier.strip().rstrip("/")
|
|
137
|
+
tail = re.sub(r"\.(m|c)?[jt]sx?$", "", tail)
|
|
138
|
+
tail = re.sub(r"^(?:\.{1,2}/)+", "", tail)
|
|
139
|
+
tail = re.sub(r"^[@~]/", "", tail).lower()
|
|
140
|
+
if not tail:
|
|
141
|
+
continue
|
|
142
|
+
for other, key in enumerate(keys):
|
|
143
|
+
if other not in selected and (key == tail or key.endswith("/" + tail)):
|
|
144
|
+
discovered.add(other)
|
|
145
|
+
if not discovered:
|
|
146
|
+
break
|
|
147
|
+
selected |= discovered
|
|
148
|
+
frontier = discovered
|
|
149
|
+
return "\n".join(texts[index] for index in sorted(selected))
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def check_meta_pixel_wiring(files: list[Path], env_json: dict[str, Any]) -> list[str]:
|
|
153
|
+
"""Keep every product on the gateway-owned Meta dataset and event shape.
|
|
154
|
+
|
|
155
|
+
This is deliberately a source contract, not proof that Meta received the
|
|
156
|
+
event; the Meta skill verifies the live browser request later. It catches
|
|
157
|
+
the deploy-time failure modes that matter here: a copied literal pixel id,
|
|
158
|
+
and a funnel the ad network cannot see past.
|
|
159
|
+
|
|
160
|
+
`PageView` and `Activation` are required of every product. `Lead` and
|
|
161
|
+
`Purchase` are required only when the product actually has a signup funnel
|
|
162
|
+
or takes money — demanding them everywhere would fail honest products that
|
|
163
|
+
have neither.
|
|
164
|
+
"""
|
|
165
|
+
frontend = [
|
|
166
|
+
path for path in files
|
|
167
|
+
if path.suffix.lower() in {".astro", ".html", ".js", ".jsx", ".ts", ".tsx"}
|
|
168
|
+
]
|
|
169
|
+
texts = [read_text(path, limit=300_000) for path in frontend]
|
|
170
|
+
text = "\n".join(texts)
|
|
171
|
+
failures: list[str] = []
|
|
172
|
+
if any(pattern.search(text) for pattern in META_PIXEL_LITERAL_PATTERNS):
|
|
173
|
+
failures.append("meta_pixel:hardcoded_id:read_NEXT_PUBLIC_META_PIXEL_ID_without_fallback")
|
|
174
|
+
|
|
175
|
+
# The gateway may intentionally be unconfigured in local/test installs. In
|
|
176
|
+
# that case only prohibit literals; do not require browser tracking code.
|
|
177
|
+
if not str(env_json.get("NEXT_PUBLIC_META_PIXEL_ID") or "").strip():
|
|
178
|
+
return failures
|
|
179
|
+
if "NEXT_PUBLIC_META_PIXEL_ID" not in text:
|
|
180
|
+
failures.append("meta_pixel:missing_env_wiring:read_NEXT_PUBLIC_META_PIXEL_ID")
|
|
181
|
+
|
|
182
|
+
sent = meta_pixel_events_sent(text)
|
|
183
|
+
segments = {
|
|
184
|
+
segment
|
|
185
|
+
for path in files
|
|
186
|
+
for segment in path.with_suffix("").as_posix().lower().split("/")
|
|
187
|
+
}
|
|
188
|
+
required = {
|
|
189
|
+
"PageView": "meta_pixel:missing_pageview_event:fbq_track_PageView",
|
|
190
|
+
"Activation": "meta_pixel:missing_activation_event:fbq_trackCustom_Activation",
|
|
191
|
+
}
|
|
192
|
+
if segments & SIGNUP_PATH_SEGMENTS:
|
|
193
|
+
required["Lead"] = "meta_pixel:missing_lead_event:fbq_track_Lead_on_signup_completed"
|
|
194
|
+
takes_money = bool(segments & PAYMENT_PATH_SEGMENTS) or any(
|
|
195
|
+
hint in key.upper() for key in env_json for hint in PAYMENT_ENV_HINTS
|
|
196
|
+
)
|
|
197
|
+
if takes_money:
|
|
198
|
+
required["Purchase"] = "meta_pixel:missing_purchase_event:fbq_track_Purchase_on_payment"
|
|
199
|
+
for event, failure in required.items():
|
|
200
|
+
if event not in sent:
|
|
201
|
+
failures.append(failure)
|
|
202
|
+
|
|
203
|
+
# Scope the payload check to the delivery modules and what they import,
|
|
204
|
+
# so a shared payload helper in its own module still counts.
|
|
205
|
+
pixel_text = meta_pixel_delivery_scope(frontend, texts)
|
|
206
|
+
for parameter in ("content_name", "product_name", "egbe_product_id"):
|
|
207
|
+
if parameter not in pixel_text:
|
|
208
|
+
failures.append(f"meta_pixel:events_missing_{parameter}")
|
|
209
|
+
return failures
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
def main() -> int:
|
|
214
|
+
parser = argparse.ArgumentParser(description=__doc__)
|
|
215
|
+
parser.add_argument("--root", type=Path, default=Path("."))
|
|
216
|
+
parser.add_argument("--pixel-config", type=Path, required=True, help="JSON with public NEXT_PUBLIC_META_PIXEL_ID; never a secret env file")
|
|
217
|
+
args = parser.parse_args()
|
|
218
|
+
if not args.root.is_dir():
|
|
219
|
+
parser.error("root must be an existing product directory")
|
|
220
|
+
files = []
|
|
221
|
+
for current, dirs, names in os.walk(args.root):
|
|
222
|
+
dirs[:] = [d for d in dirs if d not in {".git", ".next", ".agents", ".claude", "egbe-docs", "node_modules", "dist", "build", "coverage"}]
|
|
223
|
+
files.extend(Path(current) / name for name in names if Path(name).suffix in {".js", ".jsx", ".ts", ".tsx", ".html", ".astro"})
|
|
224
|
+
failures = check_meta_pixel_wiring(files, json.loads(args.pixel_config.read_text()))
|
|
225
|
+
print(json.dumps({"findings": failures, "delivery_verified": False}, indent=2))
|
|
226
|
+
return 1 if failures else 0
|
|
227
|
+
|
|
228
|
+
if __name__ == "__main__":
|
|
229
|
+
raise SystemExit(main())
|