From c459c52ebf80b439a1b875392a183e0b7a534be6 Mon Sep 17 00:00:00 2001 From: MRagabMob Date: Wed, 14 Oct 2026 13:56:07 +0300 Subject: [PATCH] Improve Replit setup for Paymob skill and MCP --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- AGENTS.md | 4 + README.md | 107 ++++++++++---- scripts/package_skill.py | 28 +++- scripts/validate.py | 6 +- skills/paymob-integration/SKILL.md | 13 +- .../references/intention-api.md | 2 +- .../references/mcp-server.md | 12 ++ .../paymob-integration/references/replit.md | 130 ++++++++++++++++++ universal-prompt.md | 9 ++ 12 files changed, 278 insertions(+), 39 deletions(-) create mode 100644 skills/paymob-integration/references/replit.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 1d144d9..c55e36c 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -14,7 +14,7 @@ "repo": "PaymobAccept/Paymob-AI-Integration-Skill" }, "description": "Build and verify secure Paymob payment flows across Egypt, UAE, KSA, and Oman.", - "version": "3.4.0" + "version": "3.4.1" } ] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 4515ab5..6cee121 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "paymob-integration", "description": "Expert, workflow-driven guidance for integrating the Paymob payment gateway across Egypt, UAE, KSA, and Oman. Routes by platform (Shopify apps / prebuilt e-commerce plugins vs custom build), onboarding, web/API (Intention API + Unified Checkout + Pixel SDK), and native Mobile SDKs. Covers all 3 HMAC types (transaction, card token, subscription), transaction inquiry/reconciliation, subscriptions, saved cards (CIT/MIT), Auth/Capture, refunds/void, split features, and convenience fees, and ships corrected ready-to-use code for Node.js, Python, PHP, .NET, Ruby, and frontend. Bundles Paymob's official MCP server for live account actions. Covers post-integration management too: go-live readiness, Dashboard operations, monitoring and reconciliation, diagnostics with the Paymob Integration Wizard (Code Lab, HMAC Signature Troubleshooter, Store Check, Mobe), and redacted support tickets. Includes /paymob-test-cards, /paymob-explain-error, /paymob-check-hmac, /paymob-go-live-check, and /paymob-support-ticket slash commands. Triggers even when no provider is named for a regional payment request.", - "version": "3.4.0", + "version": "3.4.1", "author": { "name": "Paymob Support", "email": "mohamedragab@paymob.com" diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index df397ee..a889747 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "paymob-integration", - "version": "3.4.0", + "version": "3.4.1", "description": "Integrate, verify, and operate Paymob payments across Egypt, UAE, KSA, and Oman: secure checkout, webhooks, reconciliation, go-live, diagnostics, support tickets, and optional live account tools.", "author": { "name": "Paymob Support", diff --git a/AGENTS.md b/AGENTS.md index 9ccd13e..ea1f747 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,6 +15,10 @@ This repository is a portable **skill** that makes any AI coding agent an expert For broad integrations or audits, delegate independent read-only tasks such as codebase mapping, current-doc verification, and security review. Subagents receive no Paymob credentials, do not use authenticated Paymob tools, and return findings only with file/line references. Keep one primary agent responsible for requirements, final edits, tests, and every live action. If edits must be delegated, give agents exclusive non-overlapping paths and merge through the primary agent. +## Replit and other hosted builders + +For Replit, read `skills/paymob-integration/references/replit.md` (or `references/replit.md` relative to the installed skill). Verify the skill import separately from payment connector availability. A missing connector alone does not establish an API prohibition; inspect the backend and enforced host restrictions. Use Replit Secrets, verify test/production `APP_URL` origins and public webhook reachability, and keep MCP optional. Preserve the user's provider choice and existing project rules, including the project-root `replit.md`; explain an enforced host restriction without trying to bypass it. Missing credentials permit scaffolding and local mocked tests, not authenticated API calls or a claim that payments work. + ## Non-negotiable rules 1. **Intention API only.** Create payments with `POST {base_url}/v1/intention/`. Never use or suggest the legacy 3-step flow (auth token → order → payment key). diff --git a/README.md b/README.md index 92ba1c9..d9cd808 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Paymob Integration Skill for AI Agents -![version](https://img.shields.io/badge/version-3.4.0-blue) +![version](https://img.shields.io/badge/version-3.4.1-blue) ![license](https://img.shields.io/badge/license-MIT-green) -![works with](https://img.shields.io/badge/works%20with-Claude%20%C2%B7%20Lovable%20%C2%B7%20Cursor%20%C2%B7%20Windsurf%20%C2%B7%20Copilot%20%C2%B7%20Codex-8A2BE2) +![works with](https://img.shields.io/badge/works%20with-Claude%20%C2%B7%20Replit%20%C2%B7%20Lovable%20%C2%B7%20Cursor%20%C2%B7%20Windsurf%20%C2%B7%20Copilot%20%C2%B7%20Codex-8A2BE2) ![regions](https://img.shields.io/badge/regions-EGY%20%C2%B7%20UAE%20%C2%B7%20KSA%20%C2%B7%20OMN-orange) [![Cursor Directory](https://img.shields.io/badge/Cursor%20Directory-listed-000000)](https://cursor.directory/plugins/paymob-integration) @@ -10,7 +10,7 @@ Give any AI coding agent expert, **workflow-driven** knowledge of the [Paymob](https://paymob.com) payment gateway across **Egypt, UAE, KSA, and Oman**. The agent routes the developer by platform, walks through onboarding, and produces correct, copy-ready code for accepting cards, mobile wallets, BNPLs, Apple Pay, Google Pay, kiosk, and bank installments — on any tech stack. -Ships as a native **Codex/ChatGPT plugin**, a **Claude Code/Cowork plugin**, a tested **Lovable workspace skill**, and a portable prompt (`universal-prompt.md`) + `AGENTS.md` for Cursor, Windsurf, GitHub Copilot, Gemini, and other agents. +Ships as a native **Codex/ChatGPT plugin**, a **Claude Code/Cowork plugin**, a tested **Lovable workspace skill**, a standard skill folder for **Replit GitHub import**, and a portable prompt (`universal-prompt.md`) + `AGENTS.md` for Cursor, Windsurf, GitHub Copilot, Gemini, and other agents. Replit guidance is checked against official documentation; a successful Replit import and payment flow must be verified in the user's project. > **Where it's listed.** Published on the [Cursor Directory](https://cursor.directory/plugins/paymob-integration). Not yet listed in Anthropic's plugin directory, OpenAI's, or Lovable's marketplace, and the Paymob MCP server is not yet in a vendor connector registry — so if you search one of those for "Paymob" and find nothing, that's expected rather than a mistake on your end. No listing is required either way: every method below installs straight from this repo (or its release ZIP), and the Claude Code path registers this repo as a *custom* marketplace. @@ -22,28 +22,28 @@ It's all plain Markdown — any AI assistant can use it. Find your tool below; m > **Using an “Upload skill” screen?** Do not upload GitHub's full repository ZIP. Build or download the dedicated `paymob-integration.zip` described under [Skill upload](#skill-upload-claudeai--chatgpt--lovable); it contains one top-level skill folder and leaves every plugin/editor entry point unchanged. -### 1. Any AI agent → just ask it to install the skill (easiest, recommended) +### 1. Agents with skill-install support → ask them to install the skill -No CLI, no downloads, no config files. Paste this to your agent: +For agents that support fetching and installing skills, paste this: ```text Install the Paymob integration skill from https://github.com/PaymobAccept/Paymob-AI-Integration-Skill/tree/main/skills/paymob-integration ``` -The agent fetches the skill and puts it wherever its own convention expects. Tested on both: +Install behavior depends on the host. The documented standalone install locations are: | Agent | What you get | |---|---| | **OpenAI Codex** | Uses its `$skill-installer`; installs to `~/.codex/skills/paymob-integration` | -| **Claude Code** | Installs as a personal skill in `~/.claude/skills/paymob-integration/`, plus the three slash commands in `~/.claude/commands/` | +| **Claude Code** | Standalone skill in `~/.claude/skills/paymob-integration/`; use the full plugin for commands and MCP | **Keep the `/tree/main/skills/paymob-integration` part of the URL.** The repository root is a multi-agent plugin package, not a standalone skill directory — an agent pointed at the bare root can install the wrong tree. -**Then start a fresh session.** Skills and commands are read at session start, so they won't show up in the session that installed them. This is the most common reason people think the install failed. +**Verify the installation.** Ask the agent to read the installed `SKILL.md` and one task-specific reference. Reload/start a fresh session if that host requires it. Replit's GitHub import is described below; merely pasting a URL into chat does not prove the skill was installed or loaded. Two things this path deliberately does *not* do: -- **It doesn't register the Paymob MCP server**, so there's no live account access (payment links, transactions, balances, settlements). Agents leave it out on purpose — it's a persistent config change pointing at a live financial service. To get it, use the Claude Code plugin install (item 8 below), which bundles it, or add it yourself per [Live access](#live-access--paymob-mcp-server). +- **It doesn't register the Paymob MCP server or install Claude slash commands.** The selected folder contains only the skill and its references/metadata; the repository-root commands and MCP configuration are separate. Use the [full Claude plugin](#9-claude-code--cowork--install-the-full-plugin) for those, or configure optional MCP separately per [Live access](#live-access--paymob-mcp-server). MCP is not required to implement the app's checkout backend. - **It doesn't namespace the skill.** Install it this way *and* as a plugin and you'll have two `paymob-integration` skills with identical descriptions; disable one to clear the ambiguity. ### 2. OpenAI Codex → install the standalone skill @@ -56,7 +56,18 @@ Use $skill-installer to install https://github.com/PaymobAccept/Paymob-AI-Integr Targeting the `skills/paymob-integration` subdirectory is required; the repository root is a multi-agent plugin package, not a standalone skill directory. The standalone skill includes all references. Add the optional live Paymob server separately with `codex mcp add paymob --url https://mcp.paymob.com/mcp`. -### 3. Lovable → import the tested workspace skill +### 3. Replit → import the skill from GitHub + +1. In Replit Agent, select **+ → Use a skill → Add from GitHub**. +2. Paste `https://github.com/PaymobAccept/Paymob-AI-Integration-Skill/tree/main/skills/paymob-integration`. +3. Select **Preview skills**, select **paymob-integration**, then **Import**. +4. Select the imported skill and ask Agent to read its `SKILL.md`, `references/replit.md`, and the reference matching your backend. A preview only checks structure; verify the agent can actually read the supporting files. + +The skill adds guidance; it does not add Paymob to Replit's built-in payment connector catalog or connect MCP. If the payment picker offers Stripe/Whop, ask Agent to inspect whether a custom external API integration is permitted rather than assuming a missing catalog entry prohibits it. Respect an enforced host restriction and preserve the user's provider choice. + +See [Replit setup and troubleshooting](#replit) for project-level installation, Secrets, callback URLs, and a verification prompt. This route is **documentation-verified, not an end-to-end Replit payment certification**. + +### 4. Lovable → import the tested workspace skill Lovable **Tested successfully with Lovable Workspace Skills.** @@ -68,7 +79,7 @@ Targeting the `skills/paymob-integration` subdirectory is required; the reposito You need a workspace owner, admin, or editor role to import a custom skill. Although Lovable also supports public GitHub imports, use the release ZIP for this repository: Lovable accepts `SKILL.md` only at the repository root or inside one wrapping folder, while this multi-agent plugin intentionally keeps it at `skills/paymob-integration/SKILL.md`. -### 4. Cursor → install from the Cursor Directory +### 5. Cursor → install from the Cursor Directory Listed at **[cursor.directory/plugins/paymob-integration](https://cursor.directory/plugins/paymob-integration)**. Open the listing and use **Add to Cursor** on the component you want: @@ -80,27 +91,27 @@ Listed at **[cursor.directory/plugins/paymob-integration](https://cursor.directo The commands read the skill's reference files at run time, so install the **Skill** component alongside them — on its own, a command will correctly refuse to answer rather than guess at a field order it cannot read. -### 5. Coding agents → drop in `AGENTS.md` +### 6. Coding agents → drop in `AGENTS.md` [`AGENTS.md`](https://agents.md) is an open standard that coding agents read **automatically** from your project's root folder. Natively supported by **OpenAI Codex, Cursor, GitHub Copilot, Windsurf, Gemini CLI, Aider, Zed, Jules, Devin, Factory, Amp, RooCode, Warp, JetBrains Junie**, and more. -**One step** — copy this repo's [`AGENTS.md`](AGENTS.md) into the root of *your* project: +First inspect any existing project rules. If the project has no `AGENTS.md`, download this repo's entrypoint into the project root: ```bash # run this from your project's root folder -curl -O https://raw.githubusercontent.com/PaymobAccept/Paymob-AI-Integration-Skill/main/AGENTS.md +test ! -e AGENTS.md && curl -fL https://raw.githubusercontent.com/PaymobAccept/Paymob-AI-Integration-Skill/main/AGENTS.md -o AGENTS.md ``` -- Already have an `AGENTS.md`? Just paste this one's contents into it under a `## Paymob` heading. +- Already have an `AGENTS.md`? Merge the relevant Paymob routing/rules into it under a `## Paymob` heading; never overwrite the project's own instructions. In Replit, preserve the project-root `replit.md` too. - Now ask your agent in plain English — *"Add Paymob card payments to my checkout"* — and it follows the Paymob rules automatically. -### 6. Chat assistants (ChatGPT · Gemini · Claude.ai · Copilot Chat …) → paste `universal-prompt.md` +### 7. Chat assistants (ChatGPT · Gemini · Claude.ai · Copilot Chat …) → use `universal-prompt.md` 1. Open [`universal-prompt.md`](universal-prompt.md) and **copy the whole file**. -2. Paste it into the assistant's **system prompt** / **custom instructions** (ChatGPT: *Settings → Personalization → Custom instructions*; Gemini: a *Gem*; Claude.ai: a *Project*'s instructions). +2. Provide it as project context or an attached instruction file. Use a system/custom-instruction field only if its size limit accepts the whole file; do not truncate payment or security rules to fit. 3. Describe what you're building. It's fully self-contained — no other files needed. -### 7. Prefer a pinned editor rules file? (optional) +### 8. Prefer a pinned editor rules file? (optional) If you'd rather use your editor's native rules file instead of `AGENTS.md`, save [`universal-prompt.md`](universal-prompt.md) as: @@ -111,7 +122,7 @@ If you'd rather use your editor's native rules file instead of `AGENTS.md`, save | GitHub Copilot | `.github/copilot-instructions.md` | | Cline · Continue · Roo | the tool's rules / context file | -### 8. Claude Code / Cowork → install the full plugin +### 9. Claude Code / Cowork → install the full plugin Pick this over item 1 when you want the **bundled live Paymob MCP server** (see [below](#live-access--paymob-mcp-server)) and namespaced plugin commands. Add this repository as a marketplace, then install the plugin: @@ -139,7 +150,7 @@ When you ask the agent for help integrating Paymob, it provides: - **Capabilities menu** — ask "what can you do?" and get a short list of what fits your platform, plus a one-line next step after each milestone. - **Complete Intention API knowledge** — the only official payment-creation flow, with Unified Checkout (redirect) and the Pixel SDK (embedded), plus no-code Payment Links. - **Native Mobile SDK flow** — iOS / Android / Flutter / React Native, keeping the Secret Key off the device. -- **Corrected, copy-ready code in your stack** — Node.js/TypeScript/NestJS, Python/Django/Flask/FastAPI, PHP/Laravel, .NET/C#, Ruby/Rails, and React/Next.js/Vue. +- **Stack-specific adaptation templates** — Node.js/TypeScript/NestJS, Python/Django/Flask/FastAPI, PHP/Laravel, .NET/C#, Ruby/Rails, and React/Next.js/Vue. Reuse your framework bootstrap and implement the required durable persistence adapters; the skill is not a runnable application by itself. - **All 3 HMAC types** — transaction, card token, and subscription — with exact field orders, SHA-512, and timing-safe comparison. - **Reconciliation** — a Transaction Inquiry fallback for callbacks that never arrive, stuck "pending" orders, and admin lookups. - **Core & advanced features** — subscriptions, saved cards (CIT/MIT), Auth/Capture, refund/void, split features, convenience fees. @@ -209,6 +220,8 @@ Once the plugin is installed, these slash commands give direct access to the mos [`paymob-integration.zip`](https://github.com/PaymobAccept/Paymob-AI-Integration-Skill/releases/latest/download/paymob-integration.zip) +**Check the release tag against the version badge above.** The latest published release can lag `main`; importing a GitHub folder reads the selected source ref, while a release download reads that tagged snapshot. After maintainers merge an update, publish the matching version tag before advertising the release ZIP as current. Existing installations should be updated/re-imported deliberately, not assumed to follow `main` automatically. + GitHub's **Code → Download ZIP** file is the full **multi-agent plugin repository**, so its canonical `SKILL.md` is intentionally nested at `skills/paymob-integration/SKILL.md`. That source archive is for cloning and plugin installation, not skill-upload screens. To build the same upload package from a local checkout: @@ -223,6 +236,7 @@ Then upload `dist/paymob-integration.zip`. Its structure is: paymob-integration.zip └── paymob-integration/ ├── SKILL.md + ├── LICENSE ├── agents/ └── references/ ``` @@ -233,7 +247,7 @@ This packaging step only copies the canonical skill into an ignored `dist/` arch A root-level copy, symlink, or shortcut to `SKILL.md` is intentionally not used: upload services may not follow links, while a copied file would create a second source of truth that can drift. -### Ask your AI agent (any agent, no CLI) +### Ask an agent with skill-install support Paste this to the agent you already use: @@ -241,10 +255,52 @@ Paste this to the agent you already use: Install the Paymob integration skill from https://github.com/PaymobAccept/Paymob-AI-Integration-Skill/tree/main/skills/paymob-integration ``` -Verified on OpenAI Codex (installs via `$skill-installer` to `~/.codex/skills/paymob-integration`) and Claude Code (installs as a personal skill in `~/.claude/skills/paymob-integration/` plus the slash commands in `~/.claude/commands/`). Start a fresh session afterwards — skills and commands are read at session start. +Standalone skill paths are documented for OpenAI Codex (`~/.codex/skills/paymob-integration`) and Claude Code (`~/.claude/skills/paymob-integration/`). The folder-only install does not include repository-root slash commands or MCP setup; use the full Claude plugin for those. Verify file access and reload/start a fresh session if required by the host. Keep the `/tree/main/skills/paymob-integration` subdirectory in the URL; the repository root is a multi-agent plugin package, not a standalone skill directory. This path installs the skill only — it does not register the Paymob MCP server, so use the plugin install below if you want live account access. +### Replit + +Use the [GitHub import steps](#3-replit--import-the-skill-from-github) above. For a project-level filesystem install, copy the **complete** `skills/paymob-integration` folder into `.agents/skills/paymob-integration/`, retaining `SKILL.md`, `agents/`, and every reference file. Workspace-managed imports may expose a host-provided location instead. Preserve existing skills and project rules. Replit requires no new plugin manifest or root-level duplicate `SKILL.md` for the standard folder import. + +Check installation first: + +```text +Use the imported paymob-integration skill. Read SKILL.md, references/replit.md, +and the backend reference matching this project. Report which files you read +and whether this app has a backend. Do not request credentials or modify the app yet. +``` + +Then request implementation: + +```text +I want Paymob for this app. Check whether a custom external API integration is +permitted here, separately from the built-in connector catalog. Follow the skill's +custom web/API route using the existing backend and durable database, Replit Secrets, +and a reachable HTTPS callback URL. Confirm country, account status, methods, and +test credentials first. Missing credentials permit scaffolding and mocked tests only. +If an enforced host restriction blocks Paymob, explain the exact blocker and supported +next step; do not bypass it or substitute another provider without my choice. +``` + +Full agent instructions: [`references/replit.md`](skills/paymob-integration/references/replit.md). MCP is optional; importing the skill does not authenticate a Paymob account. Review published-app secrets and `APP_URL` separately from the test workspace. Replit documentation sources and the distinction between structural checks and host runtime testing are listed in that reference. + +**Want the MCP account tools too?** [Add Paymob MCP to Replit](https://replit.com/integrations?mcp=eyJkaXNwbGF5TmFtZSI6IlBheW1vYiIsImJhc2VVcmwiOiJodHRwczovL21jcC5wYXltb2IuY29tL21jcCJ9), then confirm the connection in Replit. This documented install link contains only the public endpoint, not credentials. Manual setup and secure-authentication limitations are in [`references/mcp-server.md`](skills/paymob-integration/references/mcp-server.md). + +You can start both steps with one request: + +```text +Set up the Paymob integration skill from +https://github.com/PaymobAccept/Paymob-AI-Integration-Skill/tree/main/skills/paymob-integration +and connect Paymob MCP at https://mcp.paymob.com/mcp using Replit's supported setup flow. +Verify skill/reference loading and MCP tool discovery separately. If settings require +my action, show me the import steps and Add to Replit link. Guide secure test-account +authentication without requesting keys in chat. Report which steps succeeded or remain +blocked. Do not create payments, move money, or deploy as part of setup. +``` + +This is a combined setup request, not an automatically authenticated single-command install. Replit may still require import/connection confirmation and merchant authentication; the Paymob MCP connection has not been runtime-tested here. + ### OpenAI Codex (standalone skill) In a Codex task, ask: @@ -270,7 +326,7 @@ Add `PaymobAccept/Paymob-AI-Integration-Skill` as a custom marketplace source, t ### Cursor (Cursor Directory) -Listed at [cursor.directory/plugins/paymob-integration](https://cursor.directory/plugins/paymob-integration). Use **Add to Cursor** on the listing for the skill, the `paymob` MCP server, and the three commands. +Listed at [cursor.directory/plugins/paymob-integration](https://cursor.directory/plugins/paymob-integration). Use **Add to Cursor** on the listing for the skill, the `paymob` MCP server, and the available commands. Install the **Skill** component alongside the commands. Each command resolves the skill's reference files at run time and stops rather than answering from memory if it can't reach them, so a command installed on its own is safe but inert. @@ -333,9 +389,9 @@ Paymob-AI-Integration-Skill/ ├── universal-prompt.md # Portable prompt (Cursor, Windsurf, Copilot, ChatGPT, Gemini, …) ├── .mcp.json # Bundled Paymob MCP server (auto-registers when the plugin is enabled) ├── .codex-plugin/ -│ └── plugin.json # Codex/ChatGPT plugin manifest (v3.4.0) +│ └── plugin.json # Codex/ChatGPT plugin manifest (v3.4.1) ├── .claude-plugin/ -│ ├── plugin.json # Claude Code plugin manifest (v3.4.0) +│ ├── plugin.json # Claude Code plugin manifest (v3.4.1) │ └── marketplace.json # Claude custom marketplace catalog ├── commands/ # Claude Code slash commands (additive, Claude-only) │ ├── paymob-test-cards.md # /paymob-test-cards — sandbox test cards/wallets @@ -349,6 +405,7 @@ Paymob-AI-Integration-Skill/ │ ├── agents/ │ │ └── openai.yaml # Codex UI, invocation, and MCP metadata │ └── references/ +│ ├── replit.md # Replit import verification, host restrictions, Secrets, callback setup │ ├── shopify-apps.md # Paymob Shopify apps (on-site / off-site / BNPL) + install path │ ├── intention-api.md # Create Intention spec, Unified Checkout, common errors │ ├── mobile-sdks.md # Native SDK flow (iOS / Android / Flutter / React Native) diff --git a/scripts/package_skill.py b/scripts/package_skill.py index 005bb30..d82d3a8 100644 --- a/scripts/package_skill.py +++ b/scripts/package_skill.py @@ -20,6 +20,19 @@ def source_files() -> list[Path]: return sorted(path for path in SKILL_DIR.rglob("*") if path.is_file()) +def archive_sources() -> dict[str, Path]: + """Map package paths to canonical sources, including the MIT notice.""" + entries = { + PurePosixPath(ARCHIVE_ROOT, *path.relative_to(SKILL_DIR).parts).as_posix(): path + for path in source_files() + } + license_path = ROOT / "LICENSE" + if not license_path.is_file(): + raise ValueError("Repository LICENSE is required for standalone distribution") + entries[f"{ARCHIVE_ROOT}/LICENSE"] = license_path + return entries + + def build_archive(output: Path) -> None: """Create a deterministic ZIP with one top-level skill folder.""" output = output.resolve() @@ -28,9 +41,7 @@ def build_archive(output: Path) -> None: output.parent.mkdir(parents=True, exist_ok=True) with zipfile.ZipFile(output, "w", compression=zipfile.ZIP_DEFLATED) as archive: - for source in source_files(): - relative = source.relative_to(SKILL_DIR) - archive_name = PurePosixPath(ARCHIVE_ROOT, *relative.parts).as_posix() + for archive_name, source in sorted(archive_sources().items()): info = zipfile.ZipInfo(archive_name, FIXED_TIMESTAMP) info.compress_type = zipfile.ZIP_DEFLATED info.create_system = 3 @@ -41,14 +52,17 @@ def build_archive(output: Path) -> None: def archive_errors(archive_path: Path) -> list[str]: """Return structural or content errors for an upload archive.""" errors: list[str] = [] - expected = { - PurePosixPath(ARCHIVE_ROOT, *path.relative_to(SKILL_DIR).parts).as_posix() - for path in source_files() - } + sources = archive_sources() + expected = set(sources) try: with zipfile.ZipFile(archive_path) as archive: names = {name for name in archive.namelist() if not name.endswith("/")} bad_entries = archive.testzip() + if len(archive.namelist()) != len(set(archive.namelist())): + errors.append("Archive contains duplicate entries") + for name in sorted(names & expected): + if archive.read(name) != sources[name].read_bytes(): + errors.append(f"Archive content differs from its canonical source: {name}") except (FileNotFoundError, zipfile.BadZipFile) as exc: return [f"Cannot read archive: {exc}"] diff --git a/scripts/validate.py b/scripts/validate.py index b7d1650..b9c2cc7 100644 --- a/scripts/validate.py +++ b/scripts/validate.py @@ -306,6 +306,10 @@ def validate_install_docs(version: str, errors: list[str]) -> None: "Settings → Skills", "choose the **ZIP** tab", "/paymob-integration", + "### Replit", + "Preview skills", + ".agents/skills/paymob-integration/", + "references/replit.md", ) for command in required: if command not in readme: @@ -634,4 +638,4 @@ def main() -> int: if __name__ == "__main__": - sys.exit(main()) \ No newline at end of file + sys.exit(main()) diff --git a/skills/paymob-integration/SKILL.md b/skills/paymob-integration/SKILL.md index 46ea800..c01f7a3 100644 --- a/skills/paymob-integration/SKILL.md +++ b/skills/paymob-integration/SKILL.md @@ -60,6 +60,10 @@ After a successful first integration or test payment, end with **one line** of r ## Step -1 — Check the platform first +**Running in Replit?** Read `references/replit.md` first. Verify the skill was imported and its references are readable; inspect the existing app backend and host restrictions before choosing an integration route. A missing payment connector is not by itself proof that a custom Paymob API integration is prohibited. Respect an enforced host restriction, explain the exact blocker, and never substitute another provider without the user's choice. + +**Resolve references from the installed skill folder.** A folder-only install includes this file and `references/`, but not the repository-root `AGENTS.md`, Claude commands, or MCP registration. If a referenced file is missing, fetch that specific file from `https://raw.githubusercontent.com/PaymobAccept/Paymob-AI-Integration-Skill/main/skills/paymob-integration/references/`. If retrieval is unavailable, name the missing file and stop the affected task rather than inventing API details or declaring Paymob unsupported. Prefer a complete skill import to relying on remote fallback. + Before anything else, find out **what the store is built on**. If it's not already obvious from context, ask: > "Is your store on Shopify or another e-commerce platform (WooCommerce, Magento, Odoo, …), is this a custom-built site/app, or do you just want to share payment links without a website?" @@ -116,7 +120,7 @@ Route based on the answer: | Not registered with Paymob, or registered but verification/business docs incomplete | **Phase 1: Onboarding** (below) | | Already registered, has credentials and Integration ID(s) | Skip to **Step 0.5** (below) | -Do not proceed to writing integration code until Phase 1 is confirmed complete (see exit criteria below) — the agent will not have a Secret Key or Integration ID to use otherwise. +Until Phase 1 is complete, allow scaffolding, environment-variable placeholders, and local mocked tests. Do not make authenticated Paymob API requests or claim a working end-to-end integration without the required test credentials and Integration IDs. --- @@ -151,9 +155,12 @@ Do not proceed to writing integration code until Phase 1 is confirmed complete ( PAYMOB_API_KEY= PAYMOB_HMAC_SECRET= PAYMOB_INTEGRATION_ID_CARD= + PAYMOB_BASE_URL= + APP_URL= # add one var per enabled payment method (wallet, kiosk, etc.) ``` (`PAYMOB_API_KEY` is only needed for the Transaction Inquiry / reconciliation flow — see `references/transaction-inquiry.md`.) + `APP_URL` is the merchant app's externally reachable HTTPS origin, used to build callback and redirect URLs; it is not the Paymob regional base URL. Verify test and production origins separately. On hosted platforms, use their environment-variable/Secrets facility instead of requiring a local `.env` file. **Exit criteria for Phase 1:** merchant has Secret Key, Public Key, HMAC Secret, and at least one Integration ID (Test mode is enough to proceed). Then continue below. @@ -290,6 +297,8 @@ Rules for this phase: ## Reference files +- `references/replit.md` — Replit install verification, skill/connector/MCP separation, host restrictions, Secrets, callback URLs, and test checkpoint; read first when running in Replit + **Integration paths & security (current as of 2026-06; post-integration checked 2026-09):** - `references/shopify-apps.md` — Paymob's Shopify apps (on-site, off-site, Sympl, valU), install links, which to recommend when - `references/intention-api.md` — Create Intention endpoint, request/response fields, Unified Checkout redirect, common errors @@ -299,7 +308,7 @@ Rules for this phase: - `references/test-credentials.md` — Sandbox test cards, wallet numbers, OTPs - `references/testing-guide.md` — Test checkpoint, which test details to show per payment method, and how to test each integration type (custom web, Pixel, mobile, Shopify, plugins, Payment Links) -**Ready-to-use code (corrected, copy-ready):** +**Stack-specific adaptation templates:** Retain the merchant's framework bootstrap and implement the required durable persistence adapters; these snippets are not standalone runnable apps. - `references/code-nodejs.md` — Node.js / TypeScript / Express / NestJS - `references/code-python.md` — Python / Django / Flask / FastAPI - `references/code-php.md` — PHP / Laravel diff --git a/skills/paymob-integration/references/intention-api.md b/skills/paymob-integration/references/intention-api.md index b923114..7de19cb 100644 --- a/skills/paymob-integration/references/intention-api.md +++ b/skills/paymob-integration/references/intention-api.md @@ -126,7 +126,7 @@ Paymob's servers POST to `notification_url` from the internet, so the URL must b | Goal | Use as `notification_url` | Notes | |---|---|---| | **See the raw callback** (payload shape, `hmac` query param, redirect params) | `https://hooks.paymob.com/` — Paymob's own webhook inspector | The user opens `https://hooks.paymob.com`, copies the unique Hook URL it shows, and pastes it back to the agent (the agent cannot generate one). It shows POST, GET, and PUT requests live, so it also works as `redirection_url`. **No retention** — keep the page open while the test payment runs, or the request is not seen. Paste the captured payload into the Integration Wizard's HMAC Signature Troubleshooter (`https://wizard.paymob.com/`) to confirm the HMAC logic. | -| **Test the merchant's own webhook handler end to end** | A tunnel to the local server (e.g. `ngrok http 3000`, `cloudflared tunnel --url http://localhost:3000`) or a deployed preview URL | Hosted builders (Replit, Lovable, Vercel/Netlify previews) already expose a public HTTPS URL — use it. Tunnel URLs usually change on restart; update `notification_url` when they do. | +| **Test the merchant's own webhook handler end to end** | A tunnel to the local server (e.g. `ngrok http 3000`, `cloudflared tunnel --url http://localhost:3000`) or an externally reachable test deployment | Hosted builders may supply a preview HTTPS URL, but verify an external POST reaches the actual handler without login, an access interstitial, or a frontend HTML fallback. A preview may sleep, stop, or change URL; prefer a stable test deployment. Update `notification_url` and `APP_URL` whenever the origin changes. For Replit, read `replit.md`. | | **Live** | The merchant's own production HTTPS endpoint | Never leave a hooks.paymob.com or tunnel URL in live config. | hooks.paymob.com **only displays** requests — it does not forward them to the merchant's server, so their HMAC verification and order-update code never runs. Seeing a callback there proves Paymob sends it; it does **not** complete Phase 3 testing, which needs the merchant's own handler to receive, verify, and process the callback. diff --git a/skills/paymob-integration/references/mcp-server.md b/skills/paymob-integration/references/mcp-server.md index 86ee319..7cf772c 100644 --- a/skills/paymob-integration/references/mcp-server.md +++ b/skills/paymob-integration/references/mcp-server.md @@ -44,6 +44,18 @@ Add to the project's `.mcp.json` (or the client's MCP config): Add the same object to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global). +### Replit — connect separately from skill import + +[Add Paymob MCP to Replit](https://replit.com/integrations?mcp=eyJkaXNwbGF5TmFtZSI6IlBheW1vYiIsImJhc2VVcmwiOiJodHRwczovL21jcC5wYXltb2IuY29tL21jcCJ9) + +This link uses Replit's documented install-link format and contains only the server name and public endpoint. It does not install the Paymob skill, supply credentials, or prove account access. Confirm the connection in Replit; its security scanner and workspace permissions still apply. + +For manual setup: open Replit Integrations, find the MCP Servers settings, select **+ Add MCP server**, enter display name **Paymob** and URL `https://mcp.paymob.com/mcp`, then select **Test & save**. Do not assume Replit reads the repository-root `.mcp.json` when importing a skill. Read `replit.md` for the combined skill/MCP setup request. + +After connection, verify tool discovery and read the server's current help without account credentials. Only then authenticate a test account through a host-supported secure input/runtime mechanism. Never put API keys in the install URL, a committed file, or ordinary chat. If the credential-setup tool cannot receive keys securely in this host, report that limitation; server registration alone is not authenticated account readiness. Replit connection/authentication behavior with this Paymob server has not been tested here. + +Sources: [Replit Connect via MCP](https://docs.replit.com/build/connect-via-mcp), [Replit MCP install-link format](https://docs.replit.com/features/mcp/overview). + --- ## Authenticating (per session) diff --git a/skills/paymob-integration/references/replit.md b/skills/paymob-integration/references/replit.md new file mode 100644 index 0000000..f518ac0 --- /dev/null +++ b/skills/paymob-integration/references/replit.md @@ -0,0 +1,130 @@ +# Paymob in Replit + +Read this when the agent runs in Replit, the project is hosted there, or a payment-provider picker refuses Paymob. Preserve the merchant's existing framework and provider choice. + +## Contents + +- [Verify installation](#verify-installation) +- [Separate the three integration layers](#separate-the-three-integration-layers) +- [Start skill and MCP setup with one request](#start-skill-and-mcp-setup-with-one-request) +- [Handle a missing connector](#handle-a-missing-connector) +- [Configure the existing app](#configure-the-existing-app) +- [Verify callbacks and persistence](#verify-callbacks-and-persistence) +- [Run the test checkpoint](#run-the-test-checkpoint) +- [Official sources and validation status](#official-sources-and-validation-status) + +## Verify installation + +1. In Replit Agent, open **+ → Use a skill**, then **Add from GitHub**. +2. Paste the public skill folder URL: + `https://github.com/PaymobAccept/Paymob-AI-Integration-Skill/tree/main/skills/paymob-integration` +3. Select **Preview skills**, select **paymob-integration**, then **Import**. Preview checks structure; it does not prove the agent loaded the instructions. +4. Select the imported skill for the task. For a project-level copy, the expected entrypoint is `.agents/skills/paymob-integration/SKILL.md`, with `references/` beside it. Workspace imports can be managed by the host instead of appearing at that project path; use the host-provided skill location. +5. Ask the agent to read this guide, `intention-api.md`, and the backend reference matching the project; report which files it actually read without requesting secrets. If the host cannot read supporting files, import the complete skill folder or use the canonical skill's scoped reference-fetch fallback. + +An instruction to "use" a GitHub URL is not proof of installation. If GitHub import is unavailable in the workspace, copy the complete `skills/paymob-integration` folder from a reviewed checkout into the project's `.agents/skills/`; preserve existing skills and ask the agent to read the resulting entrypoint explicitly. + +Do not replace the project's root `replit.md` or `AGENTS.md`. An optional short section can be appended to `replit.md` after reviewing the existing file: + +```markdown +## Paymob payments +Use the imported paymob-integration skill and its Replit reference for Paymob tasks. +Keep credentials in Replit Secrets, use the existing backend and durable database, +and start with test mode. Check host restrictions separately from connector availability. +``` + +Keep that section as a router, not a second copy of API specs. Update/re-import the skill deliberately; do not assume an installed copy tracks GitHub `main`. Compare a release tag with the repository version before using the release ZIP because a published release can lag source. + +## Separate the three integration layers + +| Layer | Purpose | Needed for custom app code? | +|---|---|---| +| Paymob integration skill | Instructions and API/code references | Use it for guidance | +| Replit built-in payment connector | Replit's managed provider setup | Not the same as custom API code; check actual host restrictions | +| Paymob MCP account tools | Agent actions on a merchant account | Optional; not required to write the checkout backend | + +Importing this skill does not register a payment connector, install Claude slash commands, or connect the Paymob MCP server. Do not require MCP authentication to scaffold or integrate the app's backend. Use `mcp-server.md` only when the user explicitly needs supported account-tool operations; do not assume a repository-root `.mcp.json` is automatically honored by Replit. + +## Start skill and MCP setup with one request + +If the user wants both integration guidance and MCP account tools, start with one setup request: + +```text +Set up the Paymob integration skill and Paymob MCP for this Replit project. +Import the complete skill from: +https://github.com/PaymobAccept/Paymob-AI-Integration-Skill/tree/main/skills/paymob-integration +Verify SKILL.md and its supporting references are readable. +Connect the remote MCP server https://mcp.paymob.com/mcp through Replit's supported +custom MCP flow; if you cannot change those settings, show me the Add to Replit link. +Verify tool discovery and current server help first. Guide me through secure test-account +authentication if this host supports it; never ask for keys in chat or put them in URLs. +Report skill installation, MCP connection, and account authentication as separate statuses. +Do not create payment objects, move money, or deploy anything as part of this setup. +``` + +Use [Add Paymob MCP to Replit](https://replit.com/integrations?mcp=eyJkaXNwbGF5TmFtZSI6IlBheW1vYiIsImJhc2VVcmwiOiJodHRwczovL21jcC5wYXltb2IuY29tL21jcCJ9) to open the supported connection flow, or follow the manual MCP settings steps in `mcp-server.md`. The link contains no credentials. + +This is **one starting instruction, not a verified one-command installer**. Replit may require the user to import the skill, confirm the MCP connection, or authenticate separately; permissions and its security scanner still apply. Do not claim "fully connected" unless skill loading, MCP tool discovery, and secure test-account authentication have each been verified. A working MCP connection does not by itself prove the app's payment flow works. + +## Handle a missing connector + +If Agent says "Paymob is not available; choose Stripe or Whop": + +1. Confirm the user's requested provider remains Paymob. Dismissing another-provider picker alone does not cancel that request. +2. Inspect the actual app: backend availability, framework, payment code, persistent storage, and deployment type. A frontend-only artifact needs a permitted backend before it can hold secret keys or create intentions. +3. Distinguish **no built-in catalog entry**, **skill not loaded**, **missing backend**, **missing test credentials**, **network failure**, and **enforced host restriction**. Do not report one as another. +4. If custom external API code is permitted, follow the skill's custom web/API branch with `intention-api.md`, `hmac-verification.md`, and the matching backend/frontend references. Preserve the app's stack. +5. If Replit enforces a payment-provider restriction, stop the affected operation, identify the host message/rule and impact, and explain the supported next step (Replit support or a permitted external backend). Do not bypass the restriction, claim the skill overrides it, or replace Paymob without the user's choice. + +Replit's public docs distinguish external API integrations from connectors and document built-in monetization providers. They do not establish that every custom payment provider is permitted by every Agent mode or plan. State that uncertainty; an imported skill cannot grant capabilities the host withholds. + +## Configure the existing app + +First confirm merchant country, enabled methods, account status, and usable **test-mode** credentials. While these are missing, scaffold routes/configuration, order/payment-attempt schemas, and local mocked tests; do not make authenticated requests. + +Use **Replit Secrets** for sensitive values. Let the user enter values in the UI; check presence only, never echo secrets or dump the process environment. Host-injected environment variables do not require a `.env` file or dotenv initialization. + +| Variable | Use | +|---|---| +| `PAYMOB_SECRET_KEY` | Server-side Intention/payment actions; test key initially | +| `PAYMOB_PUBLIC_KEY` | Checkout public key matching test mode | +| `PAYMOB_HMAC_SECRET` | Server-side webhook verification | +| `PAYMOB_INTEGRATION_ID_CARD` | Test Integration ID for cards; add one per enabled method | +| `PAYMOB_API_KEY` | Only when implementing Transaction Inquiry/reconciliation | +| `PAYMOB_BASE_URL` | Merchant region's Paymob origin; see the canonical regional table | +| `APP_URL` | Merchant app's external HTTPS origin; different from the Paymob origin | + +Never place the Secret Key, API Key, or HMAC Secret in frontend/public variables such as `VITE_*`, `NEXT_PUBLIC_*`, or a browser bundle. Review published-app secrets separately under **Publishing → Adjust settings → Production app secrets**; test and production credentials, Integration IDs, and origins must match their intended mode. + +Treat the stack examples as adaptation templates: retain the app/router bootstrap and implement the required database persistence adapters. Installing the skill does not supply an executable payment backend or database schema automatically. + +## Verify callbacks and persistence + +- Build the checkout amount and currency from an owned server-side order record. Authorize checkout and status lookup for the requesting user. +- Configure `notification_url` to the actual backend webhook route and `redirection_url` to the completion page. Derive both from the intended `APP_URL`; keep callback and redirect responsibilities separate. +- Verify an unauthenticated external POST reaches that route. An unsigned test request should receive a controlled rejection and change no order state; a GET that returns a homepage is not evidence of a functioning callback. Account for access controls, sleeping previews, route/SPA fallbacks, and changed origins. +- Validate payload shape before signature extraction. Verify the current documented HMAC fields and SHA-512 comparison before any payment-state mutation; use `hmac-verification.md` and the current live docs. +- Persist the server-created Paymob payment attempt and bind the signed Paymob `order.id` to the owned local order. Do not let unsigned `merchant_order_id` alone select a fulfillment target. Compare signed amount, currency, integration/account, and test/live mode with the stored attempt, and distinguish sale/capture from auth, refund, and void before marking an order paid. +- Use durable database constraints, atomic state transitions, and the fulfillment outbox described by the skill. Do not store orders or callback deduplication only in workspace files or process memory. +- Keep logs redacted. Never log credential values, full customer details, or whole live callback payloads by default. Do not automatically retry an intention after a timeout with an unknown outcome; reconcile it first. + +## Run the test checkpoint + +Separate evidence of installation from evidence of working payments: + +1. **Installation:** confirm the imported skill and required references are readable. +2. **Offline behavior:** test missing credentials, malformed/invalid-HMAC callbacks, amount/currency/order mismatches, unsigned-reference tampering, duplicate callbacks, and auth/refund/void classification. No real credentials are needed. +3. **Integration test:** follow `testing-guide.md`, obtain the user's test-mode checkpoint, create a test intention from the owned server-side order, launch Unified Checkout, and observe the app's own verified callback and durable state update. A mocked flow or hooks.paymob.com display is not proof of this. +4. **Go-live:** use `post-integration.md`; confirm merchant activation and production configuration. A working test payment does not authorize live account writes or deployment. + +## Official sources and validation status + +Documentation checked **2026-10-14**: + +- [Replit Agent Skills](https://docs.replit.com/features/agent/skills) — GitHub imports and project skill structure. +- [Replit Agent Integrations](https://docs.replit.com/features/integrations/overview) — connectors versus external APIs. +- [Replit Monetization](https://docs.replit.com/features/monetization/overview) — built-in payment providers. +- [Replit Secrets](https://docs.replit.com/core-concepts/project-editor/app-setup/secrets) — injected environment variables and published-app secrets. +- [Replit project instructions](https://docs.replit.com/features/project-setup/replit-dot-md) — preserve and extend the root project instructions. + +These instructions are documentation-verified. Repository validation and offline checks do not establish successful Replit UI import, Agent policy acceptance, or end-to-end Paymob payments. Record those host-specific results separately when tested. diff --git a/universal-prompt.md b/universal-prompt.md index 8a03e1f..9b624be 100644 --- a/universal-prompt.md +++ b/universal-prompt.md @@ -29,6 +29,14 @@ Before writing custom code, check the merchant's platform: After installing a Shopify app, turn on its **test mode** button, pay a test order, then turn it off before going live. For plugins, set the plugin to **Test Mode** with test keys and **Test** Integration IDs first. WooCommerce merchants can also run **Store Check** on `https://wizard.paymob.com/` (deeper check via the Paymob Wizard Connector plugin: `https://wizard.paymob.com/store-doctor/downloads/paymob-wizard-connector.zip` — a diagnostic helper, not the payment plugin). +## REPLIT AND HOSTED BUILDERS + +Treat a custom Replit web app as the custom web/backend path. First verify the Paymob skill was imported, then inspect the existing backend and enforced host restrictions. A skill teaches integration; it does not register a built-in payment connector or authenticate MCP. A missing connector alone does not establish an API prohibition. If custom external API code is permitted, use the existing server, database, and framework. If an enforced host rule prevents it, explain the exact blocker without trying to bypass it or substituting another provider without the user's choice. Dismissing a Stripe/Whop picker does not by itself cancel a Paymob request. + +Use Replit Secrets for sensitive environment variables; never request values in chat or print them. Configure `PAYMOB_BASE_URL` for the merchant region and `APP_URL` as the app's externally reachable HTTPS origin. Verify test and published-app settings separately. Replit injects environment variables; no local `.env` loader is needed there. Keep the Secret Key and HMAC Secret out of public frontend variables. + +Before testing callbacks, verify an external POST reaches the actual webhook route without login, an access interstitial, or a frontend HTML fallback. Prefer a stable test deployment; a preview can sleep, change URL, or require access. Persist orders, Paymob payment-attempt mappings, callback deduplication, and fulfillment outbox records in the app's durable database. Missing credentials allow scaffolding and local mocked tests, not authenticated API calls or a claim that payments work. Only after usable test credentials are configured, continue to the test payment checkpoint below. MCP is optional for integration code. + ## ONBOARDING (no Paymob account yet) Send the merchant to the onboarding link tagged for the agent you're running in. Use `?partner=claude` in Claude, `codex` in Codex, `replit` in Replit, `lovable` in Lovable, and `aiflow` in any other agent: `https://onboarding.paymob.com/auth/country-selection/?partner=`. If that link errors, use the fallback `https://accept.paymob.com/portal2/en/register`. Document verification can take about 3 business days. Test credentials are often available sooner. The Integration Wizard (`https://wizard.paymob.com/`) gives a personalized roadmap. @@ -54,6 +62,7 @@ Default to Egypt unless the user specifies a region. Use **test-mode** keys + te | PAYMOB_API_KEY | Only for the Transaction Inquiry / reconciliation auth-token flow | | PAYMOB_INTEGRATION_ID_CARD | One Integration ID per enabled payment method (card, wallet, kiosk, …) | | PAYMOB_BASE_URL | Your region's base URL | +| APP_URL | Your app's externally reachable HTTPS origin for webhook and redirect URLs; configure test and production separately | ## PAYMENT CREATION FLOW