@egbe-ai/opencode 0.0.0-stage → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (479) hide show
  1. package/LICENSE +4 -0
  2. package/README.md +124 -2
  3. package/index.js +5 -0
  4. package/package.json +55 -4
  5. package/plugin.js +230 -0
  6. package/session-log.js +315 -0
  7. package/skills/.egbe-catalog/manifest.json +1 -0
  8. package/skills/egbe-os-analytics/SKILL.md +499 -0
  9. package/skills/egbe-os-analytics/canonical-events.v1.json +256 -0
  10. package/skills/egbe-os-analytics/references/session-funnel.md +130 -0
  11. package/skills/egbe-os-analytics/references/workflows/activation-tracking.md +147 -0
  12. package/skills/egbe-os-analytics/references/workflows/landing-click-tracking.md +209 -0
  13. package/skills/egbe-os-analytics/references/workflows/payment-lifecycle-tracking.md +122 -0
  14. package/skills/egbe-os-analytics/references/workflows/product-funnel-tracking.md +77 -0
  15. package/skills/egbe-os-analytics/references/workflows/signup-lifecycle-tracking.md +208 -0
  16. package/skills/egbe-os-analytics/scripts/umami_funnel.py +927 -0
  17. package/skills/egbe-os-apollo-lead-finder/SKILL.md +135 -0
  18. package/skills/egbe-os-apollo-lead-finder/references/operations.md +240 -0
  19. package/skills/egbe-os-apollo-lead-finder/scripts/enrich.js +6 -0
  20. package/skills/egbe-os-apollo-lead-finder/scripts/enrich.sh +4 -0
  21. package/skills/egbe-os-apollo-lead-finder/scripts/find-leads.js +6 -0
  22. package/skills/egbe-os-apollo-lead-finder/scripts/find-leads.sh +4 -0
  23. package/skills/egbe-os-apollo-lead-finder/scripts/lib/apollo-client.js +343 -0
  24. package/skills/egbe-os-apollo-lead-finder/scripts/lib/connection-identity.js +17 -0
  25. package/skills/egbe-os-apollo-lead-finder/scripts/lib/helpers.js +127 -0
  26. package/skills/egbe-os-apollo-lead-finder/scripts/lib/places-filters.js +217 -0
  27. package/skills/egbe-os-apollo-lead-finder/scripts/lib/sourcing.js +153 -0
  28. package/skills/egbe-os-apollo-lead-finder/scripts/places-leads.js +653 -0
  29. package/skills/egbe-os-apollo-lead-finder/scripts/places-leads.sh +4 -0
  30. package/skills/egbe-os-apollo-lead-finder/scripts/search.js +6 -0
  31. package/skills/egbe-os-apollo-lead-finder/scripts/search.sh +4 -0
  32. package/skills/egbe-os-campaign-landing-page/SKILL.md +95 -0
  33. package/skills/egbe-os-campaign-landing-page/agents/openai.yaml +4 -0
  34. package/skills/egbe-os-campaign-landing-page/references/leads-calendar-and-tracking.md +66 -0
  35. package/skills/egbe-os-campaign-landing-page/references/os-wiring.md +58 -0
  36. package/skills/egbe-os-campaign-landing-page/references/qa.md +40 -0
  37. package/skills/egbe-os-campaign-landing-page/references/routing.md +32 -0
  38. package/skills/egbe-os-db/SKILL.md +174 -0
  39. package/skills/egbe-os-deploy/SKILL.md +412 -0
  40. package/skills/egbe-os-design/SKILL.md +182 -0
  41. package/skills/egbe-os-design-landing-page/SKILL.md +117 -0
  42. package/skills/egbe-os-design-landing-page/agents/openai.yaml +4 -0
  43. package/skills/egbe-os-design-landing-page/assets/scaffold/.dockerignore +11 -0
  44. package/skills/egbe-os-design-landing-page/assets/scaffold/AGENTS.md +31 -0
  45. package/skills/egbe-os-design-landing-page/assets/scaffold/Dockerfile +21 -0
  46. package/skills/egbe-os-design-landing-page/assets/scaffold/eslint.config.mjs +18 -0
  47. package/skills/egbe-os-design-landing-page/assets/scaffold/next.config.ts +11 -0
  48. package/skills/egbe-os-design-landing-page/assets/scaffold/package.json +36 -0
  49. package/skills/egbe-os-design-landing-page/assets/scaffold/postcss.config.mjs +7 -0
  50. package/skills/egbe-os-design-landing-page/assets/scaffold/public/.gitkeep +1 -0
  51. package/skills/egbe-os-design-landing-page/assets/scaffold/sentry.edge.config.ts +13 -0
  52. package/skills/egbe-os-design-landing-page/assets/scaffold/sentry.server.config.ts +13 -0
  53. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/global-error.tsx +19 -0
  54. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/globals.css +22 -0
  55. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/layout.tsx +21 -0
  56. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/page.tsx +3 -0
  57. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/privacy/page.tsx +28 -0
  58. package/skills/egbe-os-design-landing-page/assets/scaffold/src/components/egbe-analytics.tsx +39 -0
  59. package/skills/egbe-os-design-landing-page/assets/scaffold/src/instrumentation-client.ts +15 -0
  60. package/skills/egbe-os-design-landing-page/assets/scaffold/src/instrumentation.ts +13 -0
  61. package/skills/egbe-os-design-landing-page/assets/scaffold/src/lib/egbe-observability.generated.ts +20 -0
  62. package/skills/egbe-os-design-landing-page/assets/scaffold/src/lib/utils.ts +6 -0
  63. package/skills/egbe-os-design-landing-page/assets/scaffold/tsconfig.json +34 -0
  64. package/skills/egbe-os-design-landing-page/references/application-preparation.md +44 -0
  65. package/skills/egbe-os-design-landing-page/references/page-inputs.md +22 -0
  66. package/skills/egbe-os-destination-readiness/SKILL.md +132 -0
  67. package/skills/egbe-os-destination-readiness/references/checks.md +130 -0
  68. package/skills/egbe-os-destination-readiness/references/network-requirements.md +34 -0
  69. package/skills/egbe-os-destination-readiness/references/report.md +116 -0
  70. package/skills/egbe-os-domains/SKILL.md +189 -0
  71. package/skills/egbe-os-errors/SKILL.md +259 -0
  72. package/skills/egbe-os-git/SKILL.md +275 -0
  73. package/skills/egbe-os-git/references/issues.md +33 -0
  74. package/skills/egbe-os-google-ads/SKILL.md +163 -0
  75. package/skills/egbe-os-google-ads/references/artifacts.md +133 -0
  76. package/skills/egbe-os-google-ads/references/campaigns.md +157 -0
  77. package/skills/egbe-os-google-ads/references/conversions.md +153 -0
  78. package/skills/egbe-os-google-ads/references/delivery.md +128 -0
  79. package/skills/egbe-os-google-ads/references/keyword-ideas.md +40 -0
  80. package/skills/egbe-os-google-ads/references/reporting.md +105 -0
  81. package/skills/egbe-os-google-ads/references/search-assets.md +219 -0
  82. package/skills/egbe-os-google-ads/references/server-conversions.md +119 -0
  83. package/skills/egbe-os-google-auth/SKILL.md +285 -0
  84. package/skills/egbe-os-google-auth/agents/openai.yaml +4 -0
  85. package/skills/egbe-os-gtm-knowledge/SKILL.md +151 -0
  86. package/skills/egbe-os-images/SKILL.md +163 -0
  87. package/skills/egbe-os-images/references/stock-images.md +21 -0
  88. package/skills/egbe-os-instantly-campaign-launcher/SKILL.md +127 -0
  89. package/skills/egbe-os-instantly-campaign-launcher/references/instantly-ops.md +260 -0
  90. package/skills/egbe-os-instantly-campaign-launcher/references/observation-and-scheduling.md +188 -0
  91. package/skills/egbe-os-instantly-campaign-launcher/references/reply-handling.md +116 -0
  92. package/skills/egbe-os-instantly-campaign-launcher/references/run-spec-template.json +65 -0
  93. package/skills/egbe-os-instantly-campaign-launcher/references/run-state.md +145 -0
  94. package/skills/egbe-os-instantly-campaign-launcher/scripts/conclude-campaign.js +158 -0
  95. package/skills/egbe-os-instantly-campaign-launcher/scripts/install-crons.js +956 -0
  96. package/skills/egbe-os-instantly-campaign-launcher/scripts/launch-campaign.js +2008 -0
  97. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/campaign-metrics.js +124 -0
  98. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/confirmed-opt-outs.js +208 -0
  99. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/connection-identity.js +17 -0
  100. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/create-once.js +23 -0
  101. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/gtm-identity.js +125 -0
  102. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/helpers.js +545 -0
  103. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/html-body.js +266 -0
  104. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/instantly-client.js +328 -0
  105. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/outreach-db.js +370 -0
  106. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/recipient-exclusion/index.js +86 -0
  107. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/replenish-test-harness.js +53 -0
  108. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/reply-queue.js +67 -0
  109. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/run-config.js +103 -0
  110. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/sender-selection.js +105 -0
  111. package/skills/egbe-os-instantly-campaign-launcher/scripts/monitor-campaign.js +607 -0
  112. package/skills/egbe-os-instantly-campaign-launcher/scripts/outreach-report.js +147 -0
  113. package/skills/egbe-os-instantly-campaign-launcher/scripts/replenish-leads.js +619 -0
  114. package/skills/egbe-os-instantly-campaign-launcher/scripts/reply-worker.js +258 -0
  115. package/skills/egbe-os-instantly-campaign-launcher/scripts/run-cron-job.js +32 -0
  116. package/skills/egbe-os-instantly-campaign-launcher/scripts/send-reply.js +260 -0
  117. package/skills/egbe-os-linkedin-ads/SKILL.md +114 -0
  118. package/skills/egbe-os-linkedin-ads/references/destination-requirements.md +30 -0
  119. package/skills/egbe-os-linkedin-ads/references/runtime/api-reference.md +154 -0
  120. package/skills/egbe-os-linkedin-ads/references/runtime/artifacts.md +63 -0
  121. package/skills/egbe-os-linkedin-ads/references/workflows/build-paused.md +44 -0
  122. package/skills/egbe-os-linkedin-ads/references/workflows/conversions.md +88 -0
  123. package/skills/egbe-os-linkedin-ads/references/workflows/launch-and-pause.md +49 -0
  124. package/skills/egbe-os-linkedin-ads/references/workflows/monitoring.md +35 -0
  125. package/skills/egbe-os-linkedin-ads/references/workflows/readiness.md +63 -0
  126. package/skills/egbe-os-linkedin-ads/references/workflows/targeting-and-creative.md +52 -0
  127. package/skills/egbe-os-llm/SKILL.md +160 -0
  128. package/skills/egbe-os-mail/SKILL.md +180 -0
  129. package/skills/egbe-os-me/SKILL.md +119 -0
  130. package/skills/egbe-os-meta-ads/SKILL.md +114 -0
  131. package/skills/egbe-os-meta-ads/references/creative/creative-specs.md +15 -0
  132. package/skills/egbe-os-meta-ads/references/creative/talking-head.md +35 -0
  133. package/skills/egbe-os-meta-ads/references/destination-requirements.md +30 -0
  134. package/skills/egbe-os-meta-ads/references/runtime/api-reference.md +436 -0
  135. package/skills/egbe-os-meta-ads/references/runtime/artifacts.md +51 -0
  136. package/skills/egbe-os-meta-ads/references/runtime/insights-reference.md +187 -0
  137. package/skills/egbe-os-meta-ads/references/runtime/pixel-install.md +196 -0
  138. package/skills/egbe-os-meta-ads/references/runtime/shared-analytics-attribution.md +16 -0
  139. package/skills/egbe-os-meta-ads/references/workflows/build-paused.md +36 -0
  140. package/skills/egbe-os-meta-ads/references/workflows/launch-ready.md +16 -0
  141. package/skills/egbe-os-meta-ads/references/workflows/launch.md +23 -0
  142. package/skills/egbe-os-meta-ads/references/workflows/monitoring.md +72 -0
  143. package/skills/egbe-os-meta-ads/references/workflows/pause.md +17 -0
  144. package/skills/egbe-os-meta-ads/references/workflows/recovery.md +23 -0
  145. package/skills/egbe-os-meta-ads/scripts/check-pixel.py +229 -0
  146. package/skills/egbe-os-meta-ads/scripts/validate-meta-artifacts.py +187 -0
  147. package/skills/egbe-os-notifications/SKILL.md +78 -0
  148. package/skills/egbe-os-openai-ads/SKILL.md +149 -0
  149. package/skills/egbe-os-openai-ads/references/creative/chat-card.md +51 -0
  150. package/skills/egbe-os-openai-ads/references/destination-requirements.md +29 -0
  151. package/skills/egbe-os-openai-ads/references/runtime/api-reference.md +219 -0
  152. package/skills/egbe-os-openai-ads/references/runtime/artifacts.md +169 -0
  153. package/skills/egbe-os-openai-ads/references/workflows/build-paused.md +40 -0
  154. package/skills/egbe-os-openai-ads/references/workflows/conversions.md +40 -0
  155. package/skills/egbe-os-openai-ads/references/workflows/creative-assembly.md +24 -0
  156. package/skills/egbe-os-openai-ads/references/workflows/launch.md +27 -0
  157. package/skills/egbe-os-openai-ads/references/workflows/monitoring.md +54 -0
  158. package/skills/egbe-os-openai-ads/references/workflows/pause.md +22 -0
  159. package/skills/egbe-os-openai-ads/references/workflows/readiness.md +37 -0
  160. package/skills/egbe-os-openai-ads/references/workflows/tracking.md +32 -0
  161. package/skills/egbe-os-openai-ads/scripts/validate-openai-artifacts.py +271 -0
  162. package/skills/egbe-os-organic-trend-watch/SKILL.md +139 -0
  163. package/skills/egbe-os-organic-trend-watch/agents/openai.yaml +4 -0
  164. package/skills/egbe-os-organic-trend-watch/references/analysis-and-adaptation.md +54 -0
  165. package/skills/egbe-os-organic-trend-watch/references/collection-and-analysis.md +117 -0
  166. package/skills/egbe-os-organic-trend-watch/references/output-contract.md +133 -0
  167. package/skills/egbe-os-organic-trend-watch/references/provider-contract.md +169 -0
  168. package/skills/egbe-os-organic-trend-watch/references/runtime-contract.md +204 -0
  169. package/skills/egbe-os-organic-trend-watch/references/visual-analysis-prompt.md +17 -0
  170. package/skills/egbe-os-organic-trend-watch/scripts/_analysis.py +612 -0
  171. package/skills/egbe-os-organic-trend-watch/scripts/_contract.py +1133 -0
  172. package/skills/egbe-os-organic-trend-watch/scripts/_provider_inputs.py +165 -0
  173. package/skills/egbe-os-organic-trend-watch/scripts/analyze-visual-evidence.py +315 -0
  174. package/skills/egbe-os-organic-trend-watch/scripts/build-provider-inputs.py +88 -0
  175. package/skills/egbe-os-organic-trend-watch/scripts/connection_identity.py +22 -0
  176. package/skills/egbe-os-organic-trend-watch/scripts/egbe_artifacts.py +24 -0
  177. package/skills/egbe-os-organic-trend-watch/scripts/finalize-receipt.py +106 -0
  178. package/skills/egbe-os-organic-trend-watch/scripts/normalize-videos.py +647 -0
  179. package/skills/egbe-os-organic-trend-watch/scripts/prepare-visual-evidence.py +324 -0
  180. package/skills/egbe-os-organic-trend-watch/scripts/render-result.py +30 -0
  181. package/skills/egbe-os-organic-trend-watch/scripts/run-apify.py +723 -0
  182. package/skills/egbe-os-organic-trend-watch/scripts/run-state.py +192 -0
  183. package/skills/egbe-os-organic-trend-watch/scripts/validate-context.py +27 -0
  184. package/skills/egbe-os-organic-trend-watch/scripts/validate-runtime.py +137 -0
  185. package/skills/egbe-os-payments/SKILL.md +215 -0
  186. package/skills/egbe-os-payments/agents/openai.yaml +4 -0
  187. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/.egbe/scaffolds/billing-nextjs-subscription.v1.json +5 -0
  188. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/AGENTS.append.md +13 -0
  189. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/db/migrations/1000_egbe_billing.sql +66 -0
  190. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/package.fragment.json +12 -0
  191. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/scripts/billing-sync.mjs +162 -0
  192. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/account/billing/error.tsx +11 -0
  193. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/account/billing/loading.tsx +8 -0
  194. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/account/billing/page.tsx +121 -0
  195. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/billing/checkout/route.ts +102 -0
  196. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/billing/portal/route.ts +54 -0
  197. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/billing/status/route.ts +22 -0
  198. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/payments/webhook/route.ts +65 -0
  199. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/components/egbe-billing/plan-badge.tsx +16 -0
  200. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/billing-sync.test.mjs +58 -0
  201. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/catalog.ts +82 -0
  202. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/checkout-payload.ts +47 -0
  203. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/foundation-contract.test.mjs +59 -0
  204. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/lifecycle.d.ts +16 -0
  205. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/lifecycle.mjs +82 -0
  206. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/lifecycle.test.mjs +94 -0
  207. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/os-client.ts +96 -0
  208. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/plans.json +17 -0
  209. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/repository.ts +325 -0
  210. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/signature.d.ts +6 -0
  211. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/signature.mjs +22 -0
  212. package/skills/egbe-os-payments/references/contracts/plan-catalog.md +46 -0
  213. package/skills/egbe-os-payments/references/security/durable-verification.md +64 -0
  214. package/skills/egbe-os-payments/references/security/server-integration.md +26 -0
  215. package/skills/egbe-os-payments/references/security/webhook-and-entitlements.md +152 -0
  216. package/skills/egbe-os-payments/references/ux/billing-experience.md +47 -0
  217. package/skills/egbe-os-payments/references/workflows/account-billing.md +64 -0
  218. package/skills/egbe-os-payments/references/workflows/discounts-and-promotion-codes.md +265 -0
  219. package/skills/egbe-os-payments/references/workflows/one-time-purchase.md +75 -0
  220. package/skills/egbe-os-payments/references/workflows/product-checkout.md +355 -0
  221. package/skills/egbe-os-payments/references/workflows/subscription-lifecycle.md +55 -0
  222. package/skills/egbe-os-playbook/SKILL.md +79 -0
  223. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/email-outreach.md +91 -0
  224. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/google-search.md +40 -0
  225. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/linkedin.md +24 -0
  226. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/meta.md +23 -0
  227. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/openai.md +15 -0
  228. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/reddit.md +56 -0
  229. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/choose-test.md +73 -0
  230. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/evaluate.md +91 -0
  231. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/market.md +96 -0
  232. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/run-test.md +111 -0
  233. package/skills/egbe-os-playbook/playbooks/market-and-acquisition.md +56 -0
  234. package/skills/egbe-os-playbook/playbooks/product/business-loop.md +141 -0
  235. package/skills/egbe-os-playbook/playbooks/product/collaboration.md +26 -0
  236. package/skills/egbe-os-playbook/playbooks/product/deliver.md +75 -0
  237. package/skills/egbe-os-playbook/playbooks/product/diagnose.md +80 -0
  238. package/skills/egbe-os-playbook/playbooks/product/evaluate.md +67 -0
  239. package/skills/egbe-os-playbook/playbooks/product/experience.md +132 -0
  240. package/skills/egbe-os-playbook/playbooks/product/loop-examples.md +67 -0
  241. package/skills/egbe-os-playbook/playbooks/product/offer.md +65 -0
  242. package/skills/egbe-os-playbook/playbooks/product/value.md +91 -0
  243. package/skills/egbe-os-playbook/playbooks/product.md +67 -0
  244. package/skills/egbe-os-playbook/references/catalog.md +127 -0
  245. package/skills/egbe-os-playbook/references/changes.md +167 -0
  246. package/skills/egbe-os-playbook/scripts/playbook-changes.py +6 -0
  247. package/skills/egbe-os-playbook/scripts/playbook_changes/__init__.py +1 -0
  248. package/skills/egbe-os-playbook/scripts/playbook_changes/cli.py +57 -0
  249. package/skills/egbe-os-playbook/scripts/playbook_changes/operations.py +137 -0
  250. package/skills/egbe-os-playbook/scripts/playbook_changes/protocol.py +132 -0
  251. package/skills/egbe-os-playbook/scripts/playbook_changes/storage.py +180 -0
  252. package/skills/egbe-os-playbook/scripts/playbook_changes/transport.py +113 -0
  253. package/skills/egbe-os-product-auth/SKILL.md +151 -0
  254. package/skills/egbe-os-product-auth/agents/openai.yaml +4 -0
  255. package/skills/egbe-os-product-auth/assets/db/README.md +102 -0
  256. package/skills/egbe-os-product-auth/assets/db/create-validation-session.mjs +223 -0
  257. package/skills/egbe-os-product-auth/assets/db/migrate.mjs +64 -0
  258. package/skills/egbe-os-product-auth/assets/db/migrations/0001_auth.sql +33 -0
  259. package/skills/egbe-os-product-auth/assets/db/migrations/0002_auth_identities.sql +16 -0
  260. package/skills/egbe-os-product-auth/assets/scaffolds/product-auth-database/AGENTS.append.md +17 -0
  261. package/skills/egbe-os-product-auth/assets/scaffolds/product-auth-database/package.fragment.json +10 -0
  262. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/AGENTS.append.md +9 -0
  263. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/package.fragment.json +13 -0
  264. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/db.ts +31 -0
  265. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/identity.ts +94 -0
  266. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/index.ts +3 -0
  267. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/session.ts +91 -0
  268. package/skills/egbe-os-product-auth/references/contracts/live-auth-interface.md +108 -0
  269. package/skills/egbe-os-product-auth/references/frameworks/nextjs.md +34 -0
  270. package/skills/egbe-os-product-auth/references/security/session-and-credentials.md +73 -0
  271. package/skills/egbe-os-product-auth/references/ux/auth-experience.md +58 -0
  272. package/skills/egbe-os-product-auth/references/workflows/account-recovery.md +22 -0
  273. package/skills/egbe-os-product-auth/references/workflows/build-auth.md +212 -0
  274. package/skills/egbe-os-product-auth/references/workflows/google.md +34 -0
  275. package/skills/egbe-os-product-auth/references/workflows/passwordless-email.md +65 -0
  276. package/skills/egbe-os-product-build/SKILL.md +111 -0
  277. package/skills/egbe-os-product-build/agents/openai.yaml +4 -0
  278. package/skills/egbe-os-product-build/references/capabilities.md +25 -0
  279. package/skills/egbe-os-product-build/references/engineering.md +72 -0
  280. package/skills/egbe-os-product-build/references/execution.md +55 -0
  281. package/skills/egbe-os-product-build/references/foundations.md +93 -0
  282. package/skills/egbe-os-product-build/references/interface-quality.md +32 -0
  283. package/skills/egbe-os-product-build/references/workflows/private-review-handoff.md +86 -0
  284. package/skills/egbe-os-product-build/scripts/scaffold.py +296 -0
  285. package/skills/egbe-os-product-demo-video/SKILL.md +118 -0
  286. package/skills/egbe-os-product-demo-video/references/recording.md +32 -0
  287. package/skills/egbe-os-product-market-research/SKILL.md +159 -0
  288. package/skills/egbe-os-product-market-research/agents/openai.yaml +4 -0
  289. package/skills/egbe-os-product-market-research/references/catalog.v1.json +177 -0
  290. package/skills/egbe-os-product-market-research/references/config/channel-footprint-sources.v1.json +99 -0
  291. package/skills/egbe-os-product-market-research/references/config/creative-taxonomy.v1.json +367 -0
  292. package/skills/egbe-os-product-market-research/references/contracts/creative-video.md +75 -0
  293. package/skills/egbe-os-product-market-research/references/contracts/funnel-teardown.md +235 -0
  294. package/skills/egbe-os-product-market-research/references/contracts/geography-comparison.md +71 -0
  295. package/skills/egbe-os-product-market-research/references/contracts/lifecycle-capture.md +119 -0
  296. package/skills/egbe-os-product-market-research/references/contracts/research-artifacts.md +520 -0
  297. package/skills/egbe-os-product-market-research/references/contracts/walk-mechanics.v2.json +18 -0
  298. package/skills/egbe-os-product-market-research/references/prompts/acquisition-channels.md +137 -0
  299. package/skills/egbe-os-product-market-research/references/prompts/acquisition-channels.user.md +4 -0
  300. package/skills/egbe-os-product-market-research/references/prompts/competitive-landscape.md +118 -0
  301. package/skills/egbe-os-product-market-research/references/prompts/competitive-landscape.user.md +4 -0
  302. package/skills/egbe-os-product-market-research/references/prompts/demand-validation.md +154 -0
  303. package/skills/egbe-os-product-market-research/references/prompts/demand-validation.user.md +4 -0
  304. package/skills/egbe-os-product-market-research/references/prompts/market-size-and-dynamics.md +100 -0
  305. package/skills/egbe-os-product-market-research/references/prompts/market-size-and-dynamics.user.md +4 -0
  306. package/skills/egbe-os-product-market-research/references/prompts/pricing-and-monetization.md +126 -0
  307. package/skills/egbe-os-product-market-research/references/prompts/pricing-and-monetization.user.md +4 -0
  308. package/skills/egbe-os-product-market-research/references/prompts/target-audience.md +98 -0
  309. package/skills/egbe-os-product-market-research/references/prompts/target-audience.user.md +4 -0
  310. package/skills/egbe-os-product-market-research/references/prompts/unit-economics.md +217 -0
  311. package/skills/egbe-os-product-market-research/references/prompts/unit-economics.user.md +4 -0
  312. package/skills/egbe-os-product-market-research/references/prompts/value-proposition.md +113 -0
  313. package/skills/egbe-os-product-market-research/references/prompts/value-proposition.user.md +4 -0
  314. package/skills/egbe-os-product-market-research/references/workflows/acquisition-channels.md +27 -0
  315. package/skills/egbe-os-product-market-research/references/workflows/channel-footprint.md +163 -0
  316. package/skills/egbe-os-product-market-research/references/workflows/community-demand.md +100 -0
  317. package/skills/egbe-os-product-market-research/references/workflows/competitive-landscape.md +27 -0
  318. package/skills/egbe-os-product-market-research/references/workflows/competitor-ads.md +82 -0
  319. package/skills/egbe-os-product-market-research/references/workflows/competitor-set.md +300 -0
  320. package/skills/egbe-os-product-market-research/references/workflows/creative-patterns.md +228 -0
  321. package/skills/egbe-os-product-market-research/references/workflows/demand-validation.md +27 -0
  322. package/skills/egbe-os-product-market-research/references/workflows/fleet-prior.md +80 -0
  323. package/skills/egbe-os-product-market-research/references/workflows/funnel-teardown.md +184 -0
  324. package/skills/egbe-os-product-market-research/references/workflows/geography-comparison.md +84 -0
  325. package/skills/egbe-os-product-market-research/references/workflows/keyword-economics.md +122 -0
  326. package/skills/egbe-os-product-market-research/references/workflows/lifecycle-capture.md +218 -0
  327. package/skills/egbe-os-product-market-research/references/workflows/local-research.md +55 -0
  328. package/skills/egbe-os-product-market-research/references/workflows/market-size-and-dynamics.md +27 -0
  329. package/skills/egbe-os-product-market-research/references/workflows/preview.md +175 -0
  330. package/skills/egbe-os-product-market-research/references/workflows/pricing-and-monetization.md +27 -0
  331. package/skills/egbe-os-product-market-research/references/workflows/recommendations.md +35 -0
  332. package/skills/egbe-os-product-market-research/references/workflows/review-mining.md +76 -0
  333. package/skills/egbe-os-product-market-research/references/workflows/target-audience.md +27 -0
  334. package/skills/egbe-os-product-market-research/references/workflows/tiktok-reels-market-trends.md +46 -0
  335. package/skills/egbe-os-product-market-research/references/workflows/unit-economics.md +27 -0
  336. package/skills/egbe-os-product-market-research/references/workflows/value-proposition.md +27 -0
  337. package/skills/egbe-os-product-market-research/scripts/build-organic-trend-context.py +167 -0
  338. package/skills/egbe-os-product-market-research/scripts/build-preview-context.py +91 -0
  339. package/skills/egbe-os-product-market-research/scripts/build-research-query.py +225 -0
  340. package/skills/egbe-os-product-market-research/scripts/channel-footprint-model.py +294 -0
  341. package/skills/egbe-os-product-market-research/scripts/connection_identity.py +22 -0
  342. package/skills/egbe-os-product-market-research/scripts/creative-model.py +364 -0
  343. package/skills/egbe-os-product-market-research/scripts/creative-selection.py +113 -0
  344. package/skills/egbe-os-product-market-research/scripts/creative-semantics.py +365 -0
  345. package/skills/egbe-os-product-market-research/scripts/creative-video.py +542 -0
  346. package/skills/egbe-os-product-market-research/scripts/egbe_artifacts.py +24 -0
  347. package/skills/egbe-os-product-market-research/scripts/finalize-organic-trend-watch.py +304 -0
  348. package/skills/egbe-os-product-market-research/scripts/funnel-email-review.py +97 -0
  349. package/skills/egbe-os-product-market-research/scripts/funnel-model.py +966 -0
  350. package/skills/egbe-os-product-market-research/scripts/funnel_features.py +50 -0
  351. package/skills/egbe-os-product-market-research/scripts/geography-comparison-contract.py +172 -0
  352. package/skills/egbe-os-product-market-research/scripts/geography-comparison.py +169 -0
  353. package/skills/egbe-os-product-market-research/scripts/keyword-forecast.py +61 -0
  354. package/skills/egbe-os-product-market-research/scripts/keyword-locale-publication.py +136 -0
  355. package/skills/egbe-os-product-market-research/scripts/lifecycle-start.py +190 -0
  356. package/skills/egbe-os-product-market-research/scripts/persist-research-report.py +63 -0
  357. package/skills/egbe-os-product-market-research/scripts/research-artifact-io.py +281 -0
  358. package/skills/egbe-os-product-market-research/scripts/research-evidence.py +496 -0
  359. package/skills/egbe-os-product-market-research/scripts/research-policy.py +33 -0
  360. package/skills/egbe-os-product-market-research/scripts/research-section-runtime.py +343 -0
  361. package/skills/egbe-os-product-market-research/scripts/research-section-workflow.py +288 -0
  362. package/skills/egbe-os-product-market-research/scripts/research_integrity.py +122 -0
  363. package/skills/egbe-os-product-market-research/scripts/review-research-completion.py +306 -0
  364. package/skills/egbe-os-product-market-research/scripts/run-acquisition-channels.py +72 -0
  365. package/skills/egbe-os-product-market-research/scripts/run-channel-footprint.py +2258 -0
  366. package/skills/egbe-os-product-market-research/scripts/run-community-demand.py +1603 -0
  367. package/skills/egbe-os-product-market-research/scripts/run-competitive-landscape.py +66 -0
  368. package/skills/egbe-os-product-market-research/scripts/run-competitor-ads.py +1156 -0
  369. package/skills/egbe-os-product-market-research/scripts/run-competitor-set.py +2514 -0
  370. package/skills/egbe-os-product-market-research/scripts/run-creative-patterns.py +2042 -0
  371. package/skills/egbe-os-product-market-research/scripts/run-demand-validation.py +72 -0
  372. package/skills/egbe-os-product-market-research/scripts/run-fleet-prior.py +652 -0
  373. package/skills/egbe-os-product-market-research/scripts/run-funnel-teardown.py +493 -0
  374. package/skills/egbe-os-product-market-research/scripts/run-keyword-economics.py +1443 -0
  375. package/skills/egbe-os-product-market-research/scripts/run-lifecycle-capture.py +1543 -0
  376. package/skills/egbe-os-product-market-research/scripts/run-market-size-and-dynamics.py +66 -0
  377. package/skills/egbe-os-product-market-research/scripts/run-os-research.py +311 -0
  378. package/skills/egbe-os-product-market-research/scripts/run-pricing-and-monetization.py +71 -0
  379. package/skills/egbe-os-product-market-research/scripts/run-review-mining.py +1051 -0
  380. package/skills/egbe-os-product-market-research/scripts/run-target-audience.py +66 -0
  381. package/skills/egbe-os-product-market-research/scripts/run-unit-economics.py +71 -0
  382. package/skills/egbe-os-product-market-research/scripts/run-value-proposition.py +67 -0
  383. package/skills/egbe-os-product-market-research/scripts/upsert-markdown-section.py +156 -0
  384. package/skills/egbe-os-product-market-research/scripts/walk-funnels.py +249 -0
  385. package/skills/egbe-os-product-market-research/scripts/write-preview.py +710 -0
  386. package/skills/egbe-os-product-market-research/scripts/write-recommendations.py +272 -0
  387. package/skills/egbe-os-product-report/SKILL.md +150 -0
  388. package/skills/egbe-os-product-report/references/artifacts.md +84 -0
  389. package/skills/egbe-os-product-report/references/brief.md +34 -0
  390. package/skills/egbe-os-product-report/references/daily.md +76 -0
  391. package/skills/egbe-os-product-report/references/sources.md +68 -0
  392. package/skills/egbe-os-product-routines/SKILL.md +166 -0
  393. package/skills/egbe-os-product-routines/references/catalog.md +22 -0
  394. package/skills/egbe-os-product-routines/references/continuation-check.md +41 -0
  395. package/skills/egbe-os-product-routines/references/product-reporting.md +163 -0
  396. package/skills/egbe-os-product-routines/references/run-preset.md +32 -0
  397. package/skills/egbe-os-quickstart/scripts/egbe-curl.py +357 -0
  398. package/skills/egbe-os-quiz-funnel/SKILL.md +152 -0
  399. package/skills/egbe-os-quiz-funnel/agents/openai.yaml +4 -0
  400. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-engine.d.mts +224 -0
  401. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-engine.mjs +652 -0
  402. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-engine.test.mjs +764 -0
  403. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-history.d.mts +31 -0
  404. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-history.mjs +87 -0
  405. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-history.test.mjs +265 -0
  406. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-reference.test.mjs +254 -0
  407. package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/QUIZ.md +195 -0
  408. package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/quiz.json +421 -0
  409. package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/quiz.public.json +369 -0
  410. package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/validation.json +21 -0
  411. package/skills/egbe-os-quiz-funnel/assets/reference/index.html +26 -0
  412. package/skills/egbe-os-quiz-funnel/assets/reference/quiz-bootstrap.js +31 -0
  413. package/skills/egbe-os-quiz-funnel/assets/reference/quiz-early-actions.mjs +11 -0
  414. package/skills/egbe-os-quiz-funnel/assets/reference/quiz-first-screen.mjs +32 -0
  415. package/skills/egbe-os-quiz-funnel/assets/reference/quiz-page.mjs +480 -0
  416. package/skills/egbe-os-quiz-funnel/assets/reference/quiz.css +264 -0
  417. package/skills/egbe-os-quiz-funnel/references/competitor-teardown.md +159 -0
  418. package/skills/egbe-os-quiz-funnel/references/conversion-handoff.md +156 -0
  419. package/skills/egbe-os-quiz-funnel/references/implementation.md +207 -0
  420. package/skills/egbe-os-quiz-funnel/references/inputs.md +37 -0
  421. package/skills/egbe-os-quiz-funnel/references/measurement.md +122 -0
  422. package/skills/egbe-os-quiz-funnel/references/spec-contract.md +335 -0
  423. package/skills/egbe-os-quiz-funnel/references/verification.md +101 -0
  424. package/skills/egbe-os-quiz-funnel/references/walk-mechanics.v2.json +18 -0
  425. package/skills/egbe-os-quiz-funnel/scripts/compile-quiz-spec.py +1869 -0
  426. package/skills/egbe-os-quiz-funnel/scripts/prepare-research-identity.py +66 -0
  427. package/skills/egbe-os-reddit-ads/SKILL.md +121 -0
  428. package/skills/egbe-os-reddit-ads/assets/static-banners/bold-statement/schema.json +41 -0
  429. package/skills/egbe-os-reddit-ads/assets/static-banners/bold-statement/template.html +106 -0
  430. package/skills/egbe-os-reddit-ads/assets/static-banners/data-proof/schema.json +61 -0
  431. package/skills/egbe-os-reddit-ads/assets/static-banners/data-proof/template.html +151 -0
  432. package/skills/egbe-os-reddit-ads/assets/static-banners/honest-breakdown/schema.json +91 -0
  433. package/skills/egbe-os-reddit-ads/assets/static-banners/honest-breakdown/template.html +185 -0
  434. package/skills/egbe-os-reddit-ads/assets/static-banners/question-hook/schema.json +51 -0
  435. package/skills/egbe-os-reddit-ads/assets/static-banners/question-hook/template.html +121 -0
  436. package/skills/egbe-os-reddit-ads/assets/static-banners/reddit-post-style/schema.json +87 -0
  437. package/skills/egbe-os-reddit-ads/assets/static-banners/reddit-post-style/template.html +212 -0
  438. package/skills/egbe-os-reddit-ads/references/creative/html-to-png-pipeline.md +123 -0
  439. package/skills/egbe-os-reddit-ads/references/creative/static-banner-qa.md +12 -0
  440. package/skills/egbe-os-reddit-ads/references/creative/static-banner-system.md +16 -0
  441. package/skills/egbe-os-reddit-ads/references/destination-requirements.md +36 -0
  442. package/skills/egbe-os-reddit-ads/references/runtime/api-reference.md +435 -0
  443. package/skills/egbe-os-reddit-ads/references/runtime/artifacts.md +57 -0
  444. package/skills/egbe-os-reddit-ads/references/runtime/monitoring.md +64 -0
  445. package/skills/egbe-os-reddit-ads/references/runtime/pixel-and-tracking.md +49 -0
  446. package/skills/egbe-os-reddit-ads/references/runtime/policies.md +19 -0
  447. package/skills/egbe-os-reddit-ads/references/runtime/shared-analytics-attribution.md +14 -0
  448. package/skills/egbe-os-reddit-ads/references/workflows/build-paused.md +35 -0
  449. package/skills/egbe-os-reddit-ads/references/workflows/launch-ready.md +19 -0
  450. package/skills/egbe-os-reddit-ads/references/workflows/launch.md +32 -0
  451. package/skills/egbe-os-reddit-ads/references/workflows/readiness.md +9 -0
  452. package/skills/egbe-os-reddit-ads/scripts/capture-ad.sh +178 -0
  453. package/skills/egbe-os-reddit-ads/scripts/validate-reddit-artifacts.py +187 -0
  454. package/skills/egbe-os-report-ui/SKILL.md +133 -0
  455. package/skills/egbe-os-report-ui/assets/egbe-wordmark.svg +9 -0
  456. package/skills/egbe-os-report-ui/assets/examples/components.html +417 -0
  457. package/skills/egbe-os-report-ui/assets/examples/editorial.html +209 -0
  458. package/skills/egbe-os-report-ui/assets/scaffold.html +179 -0
  459. package/skills/egbe-os-report-ui/references/components.md +209 -0
  460. package/skills/egbe-os-research/SKILL.md +125 -0
  461. package/skills/egbe-os-saas-unit-economics/SKILL.md +188 -0
  462. package/skills/egbe-os-scrape/SKILL.md +160 -0
  463. package/skills/egbe-os-search/SKILL.md +182 -0
  464. package/skills/egbe-os-search/references/google-places.md +81 -0
  465. package/skills/egbe-os-support/SKILL.md +149 -0
  466. package/skills/egbe-os-telemetry/SKILL.md +344 -0
  467. package/skills/egbe-os-telemetry/references/harnesses/claude-code.md +97 -0
  468. package/skills/egbe-os-telemetry/references/harnesses/codex.md +22 -0
  469. package/skills/egbe-os-telemetry/references/harnesses/hermes.md +39 -0
  470. package/skills/egbe-os-telemetry/references/harnesses/openclaw.md +139 -0
  471. package/skills/egbe-os-telemetry/references/harnesses/opencode.md +28 -0
  472. package/skills/egbe-os-tools/SKILL.md +180 -0
  473. package/skills/egbe-os-tools/references/theona.md +26 -0
  474. package/skills/egbe-os-wallet/SKILL.md +181 -0
  475. package/skills/egbe-setup/EGBE.md +484 -0
  476. package/skills/egbe-setup/SKILL.md +116 -0
  477. package/skills/egbe-setup/references/project.md +80 -0
  478. package/state.js +37 -0
  479. package/update.js +361 -0
@@ -0,0 +1,325 @@
1
+ import "server-only";
2
+
3
+ import type { PoolClient } from "pg";
4
+
5
+ import { productDatabase, queryProductDatabase } from "@/lib/egbe-product";
6
+
7
+ import { billingPlan } from "./catalog";
8
+ import { shouldApplyPaymentEvent } from "./lifecycle.mjs";
9
+
10
+ export type BillingState = {
11
+ accountId: string;
12
+ planKey: string;
13
+ status: "free" | "trialing" | "active" | "past_due" | "canceling" | "paused" | "canceled";
14
+ customerId: string | null;
15
+ subscriptionId: string | null;
16
+ priceId: string | null;
17
+ currentPeriodEnd: Date | null;
18
+ cancelAtPeriodEnd: boolean;
19
+ lastEventCreated: number;
20
+ };
21
+
22
+ export type BillingEvent = {
23
+ id: string;
24
+ type: string;
25
+ created: number;
26
+ data?: { object?: Record<string, unknown> };
27
+ livemode?: boolean;
28
+ };
29
+
30
+ export type CheckoutAttempt = {
31
+ id: string;
32
+ idempotencyKey: string;
33
+ planKey: string;
34
+ returnPath: string;
35
+ attribution: Record<string, unknown>;
36
+ };
37
+
38
+ export type BillingTransition = {
39
+ subscription_status: BillingState["status"];
40
+ access: "grant" | "preserve" | "revoke";
41
+ plan_key?: string | null;
42
+ customer_id?: string | null;
43
+ subscription_id?: string | null;
44
+ price_id?: string | null;
45
+ current_period_end?: string | null;
46
+ cancel_at_period_end?: boolean;
47
+ };
48
+
49
+ const FREE_STATE = (accountId: string): BillingState => ({
50
+ accountId,
51
+ planKey: "free",
52
+ status: "free",
53
+ customerId: null,
54
+ subscriptionId: null,
55
+ priceId: null,
56
+ currentPeriodEnd: null,
57
+ cancelAtPeriodEnd: false,
58
+ lastEventCreated: 0,
59
+ });
60
+
61
+ export async function readBillingState(accountId: string): Promise<BillingState> {
62
+ const result = await queryProductDatabase<{
63
+ account_id: string;
64
+ plan_key: string;
65
+ subscription_status: BillingState["status"];
66
+ provider_customer_id: string | null;
67
+ provider_subscription_id: string | null;
68
+ provider_price_id: string | null;
69
+ current_period_end: Date | null;
70
+ cancel_at_period_end: boolean;
71
+ last_event_created: string | number;
72
+ }>("select * from account_billing where account_id = $1", [accountId]);
73
+ const row = result.rows[0];
74
+ if (!row) return FREE_STATE(accountId);
75
+ return {
76
+ accountId: row.account_id,
77
+ planKey: row.plan_key,
78
+ status: row.subscription_status,
79
+ customerId: row.provider_customer_id,
80
+ subscriptionId: row.provider_subscription_id,
81
+ priceId: row.provider_price_id,
82
+ currentPeriodEnd: row.current_period_end,
83
+ cancelAtPeriodEnd: row.cancel_at_period_end,
84
+ lastEventCreated: Number(row.last_event_created),
85
+ };
86
+ }
87
+
88
+ export async function providerPriceForPlan(planKey: string): Promise<string> {
89
+ const result = await queryProductDatabase<{ provider_price_id: string }>(
90
+ "select provider_price_id from billing_provider_bindings where plan_key = $1",
91
+ [planKey],
92
+ );
93
+ const priceId = result.rows[0]?.provider_price_id;
94
+ if (!priceId) throw new Error(`Billing plan ${planKey} has not been synchronized`);
95
+ return priceId;
96
+ }
97
+
98
+ export async function getOrCreateCheckoutAttempt(
99
+ accountId: string,
100
+ planKey: string,
101
+ returnPath: string,
102
+ attribution: Record<string, unknown>,
103
+ ): Promise<CheckoutAttempt> {
104
+ const result = await queryProductDatabase<{
105
+ id: string;
106
+ idempotency_key: string;
107
+ plan_key: string;
108
+ return_path: string;
109
+ attribution: Record<string, unknown>;
110
+ }>(
111
+ `insert into billing_checkout_attempts (account_id, plan_key, return_path, attribution)
112
+ values ($1, $2, $3, $4::jsonb)
113
+ on conflict (account_id, plan_key) where status in ('pending', 'created')
114
+ do update set updated_at = now()
115
+ returning id, idempotency_key, plan_key, return_path, attribution`,
116
+ [accountId, planKey, returnPath, JSON.stringify(attribution)],
117
+ );
118
+ const row = result.rows[0];
119
+ if (!row?.idempotency_key?.trim()) throw new Error("Checkout attempt has no idempotency identity");
120
+ return {
121
+ id: row.id,
122
+ idempotencyKey: row.idempotency_key,
123
+ planKey: row.plan_key,
124
+ returnPath: row.return_path,
125
+ attribution: row.attribution,
126
+ };
127
+ }
128
+
129
+ export async function recordCheckoutSession(attemptId: string, sessionId: string): Promise<void> {
130
+ await queryProductDatabase(
131
+ `update billing_checkout_attempts
132
+ set status = 'created', provider_session_id = $2, updated_at = now()
133
+ where id = $1`,
134
+ [attemptId, sessionId],
135
+ );
136
+ }
137
+
138
+ function eventObject(event: BillingEvent): Record<string, unknown> {
139
+ return event.data?.object ?? {};
140
+ }
141
+
142
+ function nestedRecord(value: unknown): Record<string, unknown> {
143
+ return value && typeof value === "object" ? (value as Record<string, unknown>) : {};
144
+ }
145
+
146
+ function providerId(value: unknown): string {
147
+ if (typeof value === "string") return value.trim();
148
+ return String(nestedRecord(value).id ?? "").trim();
149
+ }
150
+
151
+ function eventPriceId(object: Record<string, unknown>): string {
152
+ const direct = providerId(object.price);
153
+ if (direct) return direct;
154
+ const items = nestedRecord(object.items);
155
+ const rows = Array.isArray(items.data) ? items.data : [];
156
+ const first = nestedRecord(rows[0]);
157
+ return providerId(first.price);
158
+ }
159
+
160
+ async function resolveEventAccount(client: PoolClient, event: BillingEvent): Promise<string> {
161
+ const object = eventObject(event);
162
+ const direct = String(object.client_reference_id ?? "").trim();
163
+ if (direct) return direct;
164
+ const customer = providerId(object.customer);
165
+ const subscription = providerId(object.subscription) || providerId(object.id);
166
+ const result = await client.query<{ account_id: string }>(
167
+ `select account_id from account_billing
168
+ where ($1 <> '' and provider_customer_id = $1)
169
+ or ($2 <> '' and provider_subscription_id = $2)
170
+ limit 1`,
171
+ [customer, subscription],
172
+ );
173
+ const accountId = result.rows[0]?.account_id;
174
+ if (!accountId) throw new Error("Payment event is not bound to a product account");
175
+ return accountId;
176
+ }
177
+
178
+ export async function readBillingStateForEvent(event: BillingEvent): Promise<BillingState> {
179
+ const object = eventObject(event);
180
+ const direct = String(object.client_reference_id ?? "").trim();
181
+ if (direct) return readBillingState(direct);
182
+ const customer = providerId(object.customer);
183
+ const subscription = providerId(object.subscription) || providerId(object.id);
184
+ const result = await queryProductDatabase<{ account_id: string }>(
185
+ `select account_id from account_billing
186
+ where ($1 <> '' and provider_customer_id = $1)
187
+ or ($2 <> '' and provider_subscription_id = $2)
188
+ limit 1`,
189
+ [customer, subscription],
190
+ );
191
+ const accountId = result.rows[0]?.account_id;
192
+ if (!accountId) throw new Error("Payment event is not bound to a product account");
193
+ return readBillingState(accountId);
194
+ }
195
+
196
+ export async function applyLiveBillingEvent(
197
+ event: BillingEvent,
198
+ transition: BillingTransition,
199
+ ): Promise<{ duplicate: boolean; stale: boolean; accountId?: string }> {
200
+ const client = await productDatabase().connect();
201
+ try {
202
+ await client.query("begin");
203
+ const inserted = await client.query(
204
+ `insert into processed_payment_events (event_id, event_type, event_created)
205
+ values ($1, $2, $3) on conflict do nothing returning event_id`,
206
+ [event.id, event.type, event.created],
207
+ );
208
+ if (!inserted.rowCount) {
209
+ await client.query("rollback");
210
+ return { duplicate: true, stale: false };
211
+ }
212
+ const accountId = await resolveEventAccount(client, event);
213
+ const object = eventObject(event);
214
+ const metadata = nestedRecord(object.metadata);
215
+ const customerId = providerId(object.customer) || null;
216
+ const subscriptionId = providerId(object.subscription) || null;
217
+ const priceId = eventPriceId(object) || null;
218
+ const locked = await client.query<{ last_event_created: string | number }>(
219
+ "select last_event_created from account_billing where account_id = $1 for update",
220
+ [accountId],
221
+ );
222
+ const previousCreated = Number(locked.rows[0]?.last_event_created ?? 0);
223
+ if (!shouldApplyPaymentEvent(previousCreated, event.created)) {
224
+ await client.query(
225
+ "update processed_payment_events set account_id = $2 where event_id = $1",
226
+ [event.id, accountId],
227
+ );
228
+ await client.query("commit");
229
+ return { duplicate: false, stale: true, accountId };
230
+ }
231
+ let boundPlanKey = "";
232
+ if (priceId) {
233
+ const binding = await client.query<{ plan_key: string }>(
234
+ "select plan_key from billing_provider_bindings where provider_price_id = $1",
235
+ [priceId],
236
+ );
237
+ boundPlanKey = binding.rows[0]?.plan_key ?? "";
238
+ }
239
+ const planKey = String(boundPlanKey || transition.plan_key || metadata.plan_key || "free");
240
+ await client.query(
241
+ `insert into account_billing (
242
+ account_id, plan_key, subscription_status, provider_customer_id,
243
+ provider_subscription_id, provider_price_id, current_period_end,
244
+ cancel_at_period_end, last_event_id, last_event_created
245
+ ) values ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)
246
+ on conflict (account_id) do update set
247
+ plan_key = excluded.plan_key,
248
+ subscription_status = excluded.subscription_status,
249
+ provider_customer_id = coalesce(excluded.provider_customer_id, account_billing.provider_customer_id),
250
+ provider_subscription_id = coalesce(excluded.provider_subscription_id, account_billing.provider_subscription_id),
251
+ provider_price_id = coalesce(excluded.provider_price_id, account_billing.provider_price_id),
252
+ current_period_end = coalesce(excluded.current_period_end, account_billing.current_period_end),
253
+ cancel_at_period_end = excluded.cancel_at_period_end,
254
+ last_event_id = excluded.last_event_id,
255
+ last_event_created = excluded.last_event_created,
256
+ updated_at = now()`,
257
+ [
258
+ accountId,
259
+ planKey,
260
+ transition.subscription_status,
261
+ transition.customer_id ?? customerId,
262
+ transition.subscription_id ?? subscriptionId,
263
+ transition.price_id ?? priceId,
264
+ transition.current_period_end ?? null,
265
+ transition.cancel_at_period_end ?? false,
266
+ event.id,
267
+ event.created,
268
+ ],
269
+ );
270
+ if (transition.access === "grant") {
271
+ await client.query(
272
+ "update entitlement_grants set revoked_at = coalesce(revoked_at, now()) where account_id = $1 and source like 'subscription:%' and source <> $2",
273
+ [accountId, `subscription:${planKey}`],
274
+ );
275
+ for (const capability of billingPlan(planKey).entitlements) {
276
+ await client.query(
277
+ `insert into entitlement_grants (account_id, capability, source, active_until)
278
+ values ($1, $2, $3, $4)
279
+ on conflict (account_id, capability, source) do update set
280
+ active_until = excluded.active_until, revoked_at = null`,
281
+ [accountId, capability, `subscription:${planKey}`, transition.current_period_end ?? null],
282
+ );
283
+ }
284
+ } else if (transition.access === "revoke") {
285
+ await client.query(
286
+ "update entitlement_grants set revoked_at = coalesce(revoked_at, now()) where account_id = $1 and source like 'subscription:%'",
287
+ [accountId],
288
+ );
289
+ }
290
+ const checkoutAttemptId = String(metadata.checkout_attempt_id ?? "").trim();
291
+ if (checkoutAttemptId) {
292
+ await client.query(
293
+ `update billing_checkout_attempts
294
+ set status = 'completed', updated_at = now()
295
+ where id = $1 and account_id = $2`,
296
+ [checkoutAttemptId, accountId],
297
+ );
298
+ }
299
+ await client.query(
300
+ "update processed_payment_events set account_id = $2 where event_id = $1",
301
+ [event.id, accountId],
302
+ );
303
+ await client.query("commit");
304
+ return { duplicate: false, stale: false, accountId };
305
+ } catch (error) {
306
+ await client.query("rollback").catch(() => undefined);
307
+ throw error;
308
+ } finally {
309
+ client.release();
310
+ }
311
+ }
312
+
313
+ export async function hasEntitlement(accountId: string, capability: string): Promise<boolean> {
314
+ const result = await queryProductDatabase(
315
+ `select 1 from entitlement_grants
316
+ where account_id = $1 and capability = $2 and revoked_at is null
317
+ and active_from <= now()
318
+ and (active_until is null or active_until > now())
319
+ limit 1`,
320
+ [accountId, capability],
321
+ );
322
+ if (result.rowCount) return true;
323
+ const state = await readBillingState(accountId);
324
+ return state.status === "free" && billingPlan("free").entitlements.includes(capability);
325
+ }
@@ -0,0 +1,6 @@
1
+ export function verifyPaymentSignature(
2
+ rawBody: string,
3
+ header: string | null,
4
+ secret: string,
5
+ nowSeconds?: number,
6
+ ): number;
@@ -0,0 +1,22 @@
1
+ import { createHmac, timingSafeEqual } from "node:crypto";
2
+
3
+ export function verifyPaymentSignature(rawBody, header, secret, nowSeconds = Math.floor(Date.now() / 1000)) {
4
+ const parts = String(header || "").split(",").map((part) => part.trim());
5
+ const timestamps = parts.filter((part) => part.startsWith("t="));
6
+ const signatures = parts.filter((part) => part.startsWith("v1="));
7
+ if (timestamps.length !== 1 || signatures.length !== 1) throw new Error("Malformed payment signature");
8
+ const timestampText = timestamps[0].slice(2);
9
+ const signature = signatures[0].slice(3);
10
+ if (!/^\d{10,}$/.test(timestampText) || !/^[0-9a-f]{64}$/.test(signature)) {
11
+ throw new Error("Malformed payment signature");
12
+ }
13
+ const timestamp = Number(timestampText);
14
+ if (timestamp > nowSeconds + 60 || nowSeconds - timestamp > 300) {
15
+ throw new Error("Stale payment signature");
16
+ }
17
+ const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
18
+ if (!timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(signature, "hex"))) {
19
+ throw new Error("Invalid payment signature");
20
+ }
21
+ return timestamp;
22
+ }
@@ -0,0 +1,46 @@
1
+ # Plan Catalog Contract
2
+
3
+ Define one server-owned catalog and import it wherever the product needs plan
4
+ information. Do not duplicate pricing arrays between landing, checkout, and the
5
+ account area.
6
+
7
+ Each plan needs:
8
+
9
+ - stable `plan_key` used in product routes and forms;
10
+ - display name and customer-facing feature summary;
11
+ - billing kind: `free`, `one_time`, or `subscription`;
12
+ - amount in cents, currency, and recurring interval when applicable;
13
+ - provider product and price ids for paid plans;
14
+ - the entitlements granted by the plan;
15
+ - whether the plan is selectable, current, or retired.
16
+
17
+ The browser may submit `plan_key`. The server resolves all provider ids and
18
+ amounts from the catalog. Reject unknown, retired, or mismatched plans. Never
19
+ accept an arbitrary Stripe price, customer, success URL, webhook path, or
20
+ entitlement list from the browser.
21
+
22
+ Create provider products and prices once with stable idempotency keys such as:
23
+
24
+ ```text
25
+ catalog:<product-slug>:<plan-key>:product:v1
26
+ catalog:<product-slug>:<plan-key>:price:<amount>:<currency>:<interval>
27
+ ```
28
+
29
+ Attach stable product routing metadata when creating provider products and
30
+ prices:
31
+
32
+ ```json
33
+ {
34
+ "plan_key": "pro",
35
+ "payment_gateway_app_slug": "product-slug",
36
+ "payment_gateway_webhook_path": "/api/payments/webhook"
37
+ }
38
+ ```
39
+
40
+ This metadata is provider readback for lifecycle routing. Do not rely on a
41
+ browser checkout run or a previously created Checkout Session to rediscover the
42
+ webhook target.
43
+
44
+ If pricing changes, create a new Stripe price and update the catalog binding;
45
+ do not mutate historical price meaning. Confirm the resulting product and price
46
+ through `GET /payments/evidence`.
@@ -0,0 +1,64 @@
1
+ # Verify durable payment effects without a charge
2
+
3
+ Use this for the product's actual paid promise, whether a one-time purchase or
4
+ subscription. Do not add subscription periods or quota machinery to a product
5
+ that does not promise them. Reuse its existing authentication, persistence and
6
+ payment implementation; this is verification, not a parallel billing system.
7
+
8
+ ## Keep three proofs distinct
9
+
10
+ - Checkout validation and signed receipts prove configuration and binding.
11
+ - Signed gateway simulations prove signature handling and reducer behavior;
12
+ their test-event branch must remain side-effect free in production.
13
+ - Durable integration tests prove the event transaction, stored entitlement
14
+ and actual protected Product consumer. Neither of the first two proves this.
15
+
16
+ ## Exercise the implementation against isolated durable state
17
+
18
+ Use a disposable test database or equivalent isolated persistence boundary, with
19
+ the normal migrations, transaction implementation, account/session resolver and
20
+ Product enforcement code. Establish isolation before sending any event. Keep
21
+ provider calls, real customer data, production credentials and production
22
+ storage outside this test. An unavailable isolated test mechanism is a concrete
23
+ verification gap, not permission to mutate production or invent success.
24
+
25
+ 1. Record the code revision and configuration differences from the deployed
26
+ product. Reuse its private validation identity pattern. Create only the
27
+ minimum synthetic accounts, checkout binding and data in this isolated store.
28
+ Keep access material private and identify all activity as testing.
29
+ 2. Confirm the real protected action denies the unpaid account. Exercise the
30
+ normal signed-event entry and durable transaction path using locally signed
31
+ fixtures and a test-only secret in the isolated application. A production-like
32
+ event fixture may reach that path only here; never strip test markers from a
33
+ gateway event, change production test behavior or send a forged live event
34
+ to the deployed receiver. Block external provider/analytics delivery.
35
+ 3. Read back the committed event, correct account/offer mapping and entitlement
36
+ through the actual persistence adapter. Reopen the connection or restart the
37
+ test application, then verify the promised Product action, delivery and return
38
+ access through its normal authorization path. Do not replace writes or access
39
+ checks with mocks, a boolean preview flag or a test-only grant shortcut.
40
+ 4. Verify a different account and signed-out access remain denied. Replay the
41
+ same event and check that no extra entitlement, order or delivered unit is
42
+ created. Exercise the product's actual refund/revocation policy and applicable
43
+ ordering, concurrency and period/usage boundaries.
44
+ 5. Force a persistence failure at the transaction boundary. Verify rollback and
45
+ a retryable error, then retry and observe one committed result. A successful
46
+ response before the durable commit is a failure even when the reducer passes.
47
+
48
+ Delete only the disposable test resources through the test environment's normal
49
+ cleanup. Retain bounded assertions, revision, isolation and cleanup evidence;
50
+ never raw credentials or invented customer/revenue totals.
51
+
52
+ ## Verify the deployed boundary separately
53
+
54
+ On the deployed revision, retain the normal account-entry, unpaid access-denial,
55
+ checkout validate-only binding and signed no-side-effect simulation checks.
56
+ Confirm that the deployed consumer uses the implementation exercised above;
57
+ document configuration differences and any unverified live dependencies. An
58
+ owner-only preview can separately prove the proposed output is usable, but
59
+ cannot prove paid entitlement persistence or payment-driven fulfillment.
60
+
61
+ Report exactly which environment each observation covers. Isolated integration
62
+ success is not a live payment, a production transaction observation or revenue.
63
+ Missing deployed configuration, real delivery dependencies or independent
64
+ handoff evidence remain open; a local test does not close them by assertion.
@@ -0,0 +1,26 @@
1
+ # Server Integration And Credentials
2
+
3
+ The deployed product backend uses the same canonical OS contract as every other
4
+ product capability: server-only `OS_URL` and `OS_API_KEY`. Site Gateway injects
5
+ the product-purpose identity authoritatively; the agent must not receive, mint,
6
+ copy, rename, or deploy it.
7
+
8
+ The product webhook secret proves webhook authenticity and is not an OS access
9
+ credential. Obtain the current product secret from
10
+ `GET /payments/webhook-secret` with the current workload credential and pass
11
+ only `EGBE_PAYMENT_WEBHOOK_SECRET` as a server-only runtime environment value
12
+ through the active Egbe OS deployment mechanism. Capture the response without
13
+ printing it. Never write the secret to source, a repository env file, or a
14
+ durable workflow artifact.
15
+
16
+ The deployment mechanism may authoritatively set or refresh the same value with
17
+ the current product secret. This is intentional and does not change the agent
18
+ workflow.
19
+
20
+ Never place these values in source, browser bundles, logs, analytics payloads,
21
+ or `NEXT_PUBLIC_*` variables. Product routes must call OS from the server.
22
+
23
+ The deploy mechanism preserves the secret during code-only redeploys. A later
24
+ full env update must keep the current product webhook secret. Product OS
25
+ credential rotation is owned by the platform and takes effect on the next
26
+ deployment.
@@ -0,0 +1,152 @@
1
+ # Webhook And Entitlement Security
2
+
3
+ ## Verify the signature
4
+
5
+ The webhook route must read the exact raw request body before JSON parsing.
6
+ Verify `x-egbe-payment-signature` as HMAC-SHA256 over
7
+ `<timestamp>.<raw-body>`, compare in constant time, and reject stale timestamps.
8
+ Parse the comma-separated `t=<unix>,v1=<hex>` fields explicitly. Reject missing,
9
+ duplicate, malformed and non-hex signatures, and signatures timestamped more than
10
+ 60 seconds in the future (clock-skew allowance) or older than five minutes;
11
+ never compare the expected digest with the entire header string or sign only the
12
+ raw body.
13
+
14
+ ## Gateway preflight and one-time test acknowledgements
15
+
16
+ Checkout validation and creation send a signed, non-mutating preflight to the
17
+ product receiver. It contains `checkout.session.completed`, `livemode: false`,
18
+ `data.object.metadata.egbe_test: "1"` and `x-egbe-payment-test: 1`; preflight also
19
+ sets `x-egbe-payment-preflight: 1`. Its session, customer and reference are
20
+ synthetic, and its current payload uses `mode: "subscription"` even for a
21
+ one-time checkout. Do not require those values to match a real order or offer.
22
+
23
+ After successful signature verification, a one-time receiver acknowledges these
24
+ marked gateway test events with HTTP 200 before real order/session lookup or
25
+ amount/mode validation. Return bounded JSON with `contract_version: 1`,
26
+ `test_event: true`, `accepted: true`, the received `event_id` and `event_type`,
27
+ and `side_effects_applied: false`. Do not invent a subscription transition or
28
+ write event/order state, grant access, deliver anything or emit analytics.
29
+ Test/preflight headers never bypass signature verification. An unmarked live
30
+ event always follows the real order, amount and durable-application checks.
31
+
32
+ This one-time test acknowledgement may be stateless: repeating the same signed
33
+ marked event can return the same acknowledgement. A `duplicate` field is not
34
+ required here. The gateway's bounded readback normalizes an omitted field to
35
+ `duplicate: false`; that value alone is not a failed one-time acknowledgement.
36
+ The subscription simulation's duplicate flag and transition requirements below
37
+ do not apply to this contract. Independently verify real one-time event
38
+ deduplication, retry and delivery through isolated durable integration; repeated
39
+ non-mutating acknowledgements do not prove those behaviors.
40
+
41
+ A `404` or `405` response is interpreted as a missing receiver and blocks
42
+ checkout with `409`; returning order-not-found for this synthetic probe is
43
+ therefore incorrect. This acknowledgement proves only the receiver/signature
44
+ boundary, not one-time fulfillment. Verify that separately through the
45
+ [one-time purchase workflow](../workflows/one-time-purchase.md).
46
+
47
+ ## Subscription application and simulation
48
+
49
+ Subscription receivers use the test adapter below, not the one-time acknowledgement.
50
+ The normalized statuses and simulated transitions here are the subscription
51
+ contract; they do not implement or prove one-time order/payment/delivery state.
52
+
53
+ Use one pure transition reducer for both simulated and live subscription events. The reducer
54
+ accepts the verified event plus current billing state and returns a bounded
55
+ transition with the resulting `subscription_status`; any additional internal
56
+ decision name is product-owned. The reducer does not write to storage or call
57
+ analytics/provider APIs itself.
58
+
59
+ Process each event in this order:
60
+
61
+ 1. Reject an invalid signature.
62
+ 2. Detect a duplicate `event.id`. A duplicate is reported explicitly and never
63
+ applies the transition twice; no particular internal action name is required.
64
+ 3. Resolve the local account from the stored checkout/account reference and
65
+ owned customer/subscription mapping. Do not grant by email alone.
66
+ 4. Compute the normalized transition with the pure reducer.
67
+ 5. For `livemode: false`, `metadata.egbe_test`, or
68
+ `x-egbe-payment-test: 1`, return the bounded test contract below before any
69
+ local or imported persistence, entitlement, revenue, or analytics operation.
70
+ 6. For a live event, insert `event.id`, apply the transition, and commit in one
71
+ durable transaction before returning success.
72
+
73
+ The simulated response contract is:
74
+
75
+ ```json
76
+ {
77
+ "contract_version": 1,
78
+ "test_event": true,
79
+ "accepted": true,
80
+ "duplicate": false,
81
+ "event_id": "evt_...",
82
+ "event_type": "checkout.session.completed",
83
+ "transition": {
84
+ "subscription_status": "active"
85
+ },
86
+ "side_effects_applied": false
87
+ }
88
+ ```
89
+
90
+ Invalid signatures, and signatures timestamped more than 60 seconds in the
91
+ future or older than five minutes, return a 4xx response before the reducer.
92
+ For a duplicate simulated event, return `duplicate: true`, report the bounded
93
+ subscription state, and apply no side effects. Never trust a client-supplied
94
+ transition.
95
+
96
+ ## Simulated Lifecycle Scenarios
97
+
98
+ The signed Payment Gateway simulation marks each event with
99
+ `metadata.egbe_lifecycle_test_scenario`. This marker is valid only after the
100
+ normal signature check and only for a test event. It is not a live billing
101
+ input and must never replace the durable account state for a live webhook.
102
+
103
+ For a test event, use the marker to choose one bounded in-memory pre-event
104
+ state before calling the same pure reducer used by live delivery:
105
+
106
+ - `checkout`: a free account;
107
+ - `renewal`: an existing active paid subscription bound to the event customer
108
+ and subscription ids;
109
+ - `payment_failed`, `canceled`, and `refunded`: an existing active paid
110
+ subscription bound to those ids.
111
+
112
+ The Payment Gateway also supplies canonical renewal fields for `renewal`,
113
+ including `billing_reason: "subscription_cycle"` and a future invoice period.
114
+ Do not persist this synthetic state. Its only purpose is to exercise the same
115
+ reducer branch that a live event with durable state would use. Unknown or
116
+ missing scenarios should use the normal free test state, never arbitrary
117
+ metadata supplied by a caller.
118
+
119
+ Keep this adapter small and explicit. The webhook route should first verify the
120
+ raw signed event, then determine whether it is a marked test event. Only then
121
+ may it select `testLifecycleState(event, scenario)` instead of loading the
122
+ normal durable state; both paths call the same reducer and shape the same
123
+ response. The test adapter must not run before signature verification, write
124
+ to the database, or be reachable from an unmarked live event.
125
+
126
+ Return a retryable server error when a valid live event cannot be committed.
127
+ Do not return success and defer the only durable write to best-effort work.
128
+
129
+ Recommended normalized statuses are `free`, `trialing`, `active`, `past_due`,
130
+ `canceling`, `paused`, and `canceled`. Store provider customer, subscription,
131
+ price, current-period, cancellation, and last-event fields needed to explain
132
+ the state.
133
+
134
+ Access checks use server-side entitlements, not URL flags, browser state, plan
135
+ labels, or the Stripe success return. Preserve access through the paid period
136
+ when cancellation is scheduled; revoke or downgrade when the effective provider
137
+ state requires it.
138
+
139
+ Keep event transitions distinct:
140
+
141
+ - paid checkout confirms the account/customer mapping and grants the selected
142
+ entitlement;
143
+ - paid renewal extends active access;
144
+ - payment failure records `past_due` plus the product's warning/grace policy and
145
+ never grants new access;
146
+ - subscription deletion/cancellation records the effective end state and
147
+ revokes or downgrades at the correct time;
148
+ - refund records the adjustment and applies the explicit product refund policy,
149
+ never an unconditional paid-access transition.
150
+
151
+ Do not group failure, cancellation, and refund cases under the same active-state
152
+ branch as successful payment events.