waffo-integrate

An AI coding skill for Codex, Claude Code, and Cursor that guides developers through integrating the Waffo Payment SDK into their projects and then verifying the integration end to end.

Changelog

See CHANGELOG.md for release notes. GitHub Releases are also published for each v* tag.

Install

One command (npm)

# Auto-detect: installs to Codex, Claude Code, and/or Cursor if detected
npx @waffo/waffo-integrate

# Or specify target explicitly
npx @waffo/waffo-integrate --codex
npx @waffo/waffo-integrate --agents
npx @waffo/waffo-integrate --claude
npx @waffo/waffo-integrate --cursor

Codex

The npm installer now writes to the live Codex skill roots when they are present:

• ~/.agents/skills/waffo-integrate
• ~/.codex/skills/waffo-integrate
• ~/.Codex/skills/waffo-integrate

Claude Code only

claude /install-skill waffo-com/waffo-integrate

Cursor post-install

After running npx @waffo/waffo-integrate --cursor, add to your .cursorrules (or .cursor/rules/waffo-integrate.mdc):

When the user asks to integrate Waffo SDK, read and follow the instructions in .cursor/skills/waffo-integrate/SKILL.md.
Load reference files from .cursor/skills/waffo-integrate/references/ as directed by SKILL.md.

Manual (any AI coding assistant)

Copy SKILL.md, references/, docs/, and bin/waffo-verify.js into the same skill directory. For Claude Code enforcement, also copy bin/waffo-claude-hook.js. Point your AI assistant to read SKILL.md when integrating Waffo SDK.

What it does

A guided integration flow with Step 6 verification:

1. Detects language and project status — Node.js / Java / Go / Python / PHP; existing project or new scaffold
2. Selects features and context — payments, refunds, subscriptions, currency, and checkout decisions
3. Selects framework and events — Express, Spring Boot, Gin, FastAPI, plus derived webhook handlers
4. Presents code for review — shows complete integration code before writing
5. Writes and builds — installs the SDK dependency, generates files, and runs focused checks
6. Verifies integration — phased end-to-end testing with a Markdown acceptance report

Built-in safeguards

Built-in protocol and contract rules prevent common integration mistakes:

• UUID request IDs exceeding 32-character limit
• Subscription field name confusion (currency vs orderCurrency)
• Missing required fields (payMethodType, userTerminal, goodsInfo)
• Invalid enum values (YEARLY is not a valid periodType)
• Webhook Content-Type not set (text/plain instead of application/json)
• All 5 webhook handlers must implement three-stage pattern (idempotency + lock + transaction)
• All 7 write operations must catch WaffoUnknownStatusError
• Refund currency must match original order currency
• Currency parameterization for multi-currency projects

Integration verification (Step 6)

Phased Step 6 execution with automatic fix-and-retry:

• Phase A — 核心测试：order-create、order-create-error、payment-success、payment-failure、webhook-idempotency
• Phase B1/B2 — Pay method coverage: card + non-card (minimum test set from API discovery)
• Phase C1 — Refund tests
• Phase C2 — Subscription lifecycle tests
• Phase D — Integration Quality Radar / 集成质量雷达（passive code review）+ Go-Live questionnaire + report hard gate + Markdown report

Key verification safeguards:

• payMethodConfig().inquiry() is mandatory before pay-method coverage or formal reporting
• final report generation is fail-closed behind a report hard gate
• schemaVersion 2 manifests render the report via waffo-verify . --emit report; the Claude hook byte-compares the written file against that output and refuses hand edits
• Verification Blocked Summary is used instead of a formal report when required phases or evidence are missing
• Webhook Delivery Evidence distinguishes project-side evidence from Waffo-side evidence
• Integration Quality Radar 将被动代码审查风险表达成客户可读的检查项、发现、风险级别和建议
• report overview includes Skill Version, Coverage Basis, and Report Eligibility

Progressive disclosure

Only the main SKILL.md is loaded initially. Language-specific templates, verification protocol, and reference files are loaded on demand, saving tokens.

waffo-integrate/
├── SKILL.md                              # Thin entrypoint + verification/report requirements
├── bin/
│   ├── waffo-verify.js                   # Executable integration/report validator
│   └── waffo-claude-hook.js              # Claude Code stdin hook adapter
├── references/
│   ├── api-contract.md                   # Field definitions + status handling
│   ├── node.md                           # Node.js/TypeScript templates
│   ├── java.md                           # Java/Spring Boot templates
│   ├── go.md                             # Go templates
│   ├── python.md                         # Python (FastAPI/Flask/Django) templates
│   ├── php.md                            # PHP (Laravel/Symfony/Slim) templates
│   ├── integration-verification.md       # Step 6 verification protocol
│   ├── acceptance-criteria.md            # Test cards, Playwright scripts, report template
│   ├── sandbox-knowledge.md              # Sandbox quirks (K024-K030)
│   ├── business-validation.md            # Integration Quality Radar + passive verification
│   ├── scenario-selection.md             # 产品/场景选型取舍
│   ├── glossary.md                       # 客户可读术语
│   └── troubleshooting.md                # 按症状排障指南
├── docs/
│   ├── INDEX.md                          # Knowledge base index + remote fallback
│   └── enforcement.md                    # Manifest schema + hook configuration
├── evals/
│   └── evals.json                        # 36 prompt evals, 117 assertions
└── tests/
    ├── waffo-verify.test.js              # Executable validator/hook regression tests
    ├── compile-templates.mjs             # Five-language template gate
    └── harness/                          # SDK compilers + deterministic contract assertions

Evaluation coverage

The repo currently defines 36 prompt eval scenarios and 117 assertions, plus executable validator/hook regression tests:

| Eval | Scenario | Assertions | Result | |------|----------|-----------|--------| | 1 | Node.js payment + refund | 4 | Defined | | 2 | Node.js subscription | 5 | Defined | | 3 | Java Spring Boot webhook | 5 | Defined | | 4 | Go integration verification | 7 | Defined | | 5 | Go full features (webhook auto-derive) | 4 | Defined | | 6 | Node.js payment only (no subscription filter) | 3 | Defined | | 7 | Subscription event selection guidance | 3 | Defined | | 8 | Python FastAPI payment + refund + webhook | 7 | Defined | | 9 | Block direct report generation without verification | 3 | Defined | | 10 | Require direct SDK pay-method inquiry when no helper exists | 2 | Defined | | 11 | Keep proxy/local webhook evidence from being mislabeled PASS | 2 | Defined | | 12 | Block formal report for INCOMPLETE outcome | 3 | Defined | | 13 | APP WebView 场景选型说明 | 3 | Defined | | 14 | Webhook 排障证据收集 | 3 | Defined | | 15 | Integration Quality Radar 报告段落 | 4 | Defined | | 16 | 在线文档来源优先级 | 3 | Defined | | 17 | Ask before choosing subscription mode | 3 | Defined | | 18 | Explain both subscription-mode axes | 3 | Defined | | 19 | Keep retry policy in Waffo contract config | 2 | Defined | | 20 | Block unattended subscription defaults | 3 | Defined | | 21 | Re-derive handlers from selected features | 3 | Defined | | 22 | Block reports with failed required items | 3 | Defined | | 23 | Block fabricated handler business logic | 3 | Defined | | 24 | Preserve device-wallet manual evidence | 3 | Defined | | 25 | Recover unknown status with same-key inquiry | 3 | Defined | | 26 | Generate 32-character Node request IDs | 3 | Defined | | 27 | Keep order/subscription field maps separate | 2 | Defined | | 28 | Require goodsInfo and all order redirect URLs | 3 | Defined | | 29 | Keep Java subscription templates SDK-compatible | 3 | Defined | | 30 | Keep subscription description in productInfo | 2 | Defined | | 31 | Block hand-composed report on schemaVersion 2 | 2 | Defined | | 32 | Reject invented PASS* status | 2 | Defined | | 33 | Keep Non-PASS identifier columns | 2 | Defined | | 34 | Keep one row per contracted pay method | 2 | Defined | | 35 | Reject softened compliance self-declaration | 2 | Defined | | 36 | PHP Laravel payment + refund + webhook | 7 | Defined |

Requirements

• Codex, Claude Code, Cursor, or any AI coding assistant that can read markdown instructions
• A Waffo merchant account (for Sandbox testing)

License

MIT