@paymos/mcp 1.4.1 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,17 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [1.5.1] - 2026-11-13
6
+
7
+ - fix(plugins,publicweb): SDK webhook credit recipes, CMS recovery, redirects and CSP logs (audit 2026-11-13)
8
+
9
+ ## [1.5.0] - 2026-11-07
10
+
11
+ - feat(publicweb,docs,blazor,mcp): add MCP prompt tab to code snippets and compact /contacts header
12
+ - docs(sdk): backfill published mirror changelogs across SDKs and MCP
13
+ - chore: sync Spec Forge 1.6.1, MCP integration recommendation, webhook alert hold, and social agent runs
14
+ - docs(refunds): publish merchant refunds API reference and guides across 6 locales
15
+
5
16
  ## [1.4.1] - 2026-11-02
6
17
 
7
18
  - docs: regenerate merged documentation on shared node
package/README.md CHANGED
@@ -176,6 +176,7 @@ The server still reads `PAYMOS_API_KEY_ID`, `PAYMOS_API_SECRET`, and optional `P
176
176
 
177
177
  | Tool | Purpose |
178
178
  |---|---|
179
+ | `recommend_payment_integration` | Recommend invoices, payment channels, or both from the merchant’s payment flow. Explain the fit and relevant lifecycle. When information is missing, return a targeted question instead of choosing. Respect an explicit merchant choice. |
179
180
  | `create_invoice` | Create a sandbox invoice; idempotent per `external_order_id`; returns `payment_url` |
180
181
  | `get_invoice` | Fetch the current invoice state |
181
182
  | `list_invoices` | Fetch one cursor page of invoices, with filters |
package/dist/index.js CHANGED
@@ -544,7 +544,7 @@ var DOC_RESOURCES = [
544
544
  <p>Use an official server SDK below. It serializes the request, creates the exact
545
545
  HMAC signature, sets the timestamp headers, applies safe retries, and returns a
546
546
  typed response. Manual signing is documented separately in <a href="/docs/authentication">Authentication</a>.</p>
547
- <div class="code-tab-group"><div class="code-tab-bar"><button type="button" class="code-tab-btn active" data-tab-idx="0" data-code-lang="curl">cURL</button><button type="button" class="code-tab-btn" data-tab-idx="1" data-code-lang="javascript"><i class="devicon-javascript-plain colored"></i> JavaScript</button><button type="button" class="code-tab-btn" data-tab-idx="2" data-code-lang="python"><i class="devicon-python-plain colored"></i> Python</button><button type="button" class="code-tab-btn" data-tab-idx="3" data-code-lang="php"><i class="devicon-php-plain colored"></i> PHP</button><button type="button" class="code-tab-btn" data-tab-idx="4" data-code-lang="go"><i class="devicon-go-plain colored"></i> Go</button><button type="button" class="code-tab-btn" data-tab-idx="5" data-code-lang="csharp"><i class="devicon-csharp-plain colored"></i> C#</button><button type="button" class="code-tab-btn" data-tab-idx="6" data-code-lang="java"><i class="devicon-java-plain colored"></i> Java</button><button type="button" class="code-tab-btn" data-tab-idx="7" data-code-lang="ruby"><i class="devicon-ruby-plain colored"></i> Ruby</button><button type="button" class="code-tab-btn" data-tab-idx="8" data-code-lang="rust"><i class="devicon-rust-original colored"></i> Rust</button></div><div class="code-tab-panel active" data-code-lang="curl"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="curl"><code><span class="line"><span style="color:#E06C75">API_KEY_ID</span><span style="color:#56B6C2">=</span><span style="color:#98C379">"pk_live_xxxxxxxxxxxx"</span></span>
547
+ <div class="code-tab-group"><div class="code-tab-bar"><button type="button" class="code-tab-btn active" data-tab-idx="0" data-code-lang="curl">cURL</button><button type="button" class="code-tab-btn" data-tab-idx="1" data-code-lang="mcp">MCP</button><button type="button" class="code-tab-btn" data-tab-idx="2" data-code-lang="javascript"><i class="devicon-javascript-plain colored"></i> JavaScript</button><button type="button" class="code-tab-btn" data-tab-idx="3" data-code-lang="python"><i class="devicon-python-plain colored"></i> Python</button><button type="button" class="code-tab-btn" data-tab-idx="4" data-code-lang="php"><i class="devicon-php-plain colored"></i> PHP</button><button type="button" class="code-tab-btn" data-tab-idx="5" data-code-lang="go"><i class="devicon-go-plain colored"></i> Go</button><button type="button" class="code-tab-btn" data-tab-idx="6" data-code-lang="csharp"><i class="devicon-csharp-plain colored"></i> C#</button><button type="button" class="code-tab-btn" data-tab-idx="7" data-code-lang="java"><i class="devicon-java-plain colored"></i> Java</button><button type="button" class="code-tab-btn" data-tab-idx="8" data-code-lang="ruby"><i class="devicon-ruby-plain colored"></i> Ruby</button><button type="button" class="code-tab-btn" data-tab-idx="9" data-code-lang="rust"><i class="devicon-rust-original colored"></i> Rust</button></div><div class="code-tab-panel active" data-code-lang="curl"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="curl"><code><span class="line"><span style="color:#E06C75">API_KEY_ID</span><span style="color:#56B6C2">=</span><span style="color:#98C379">"pk_live_xxxxxxxxxxxx"</span></span>
548
548
  <span class="line"><span style="color:#E06C75">API_SECRET</span><span style="color:#56B6C2">=</span><span style="color:#98C379">"sk_live_xxxxxxxxxxxx"</span></span>
549
549
  <span class="line"><span style="color:#E06C75">BODY</span><span style="color:#56B6C2">=</span><span style="color:#98C379">'{"project_id":"prj_xxxxxxxxxxxx","amount":"100.00","currency":"USD","external_order_id":"order-123","client_id":"customer-456"}'</span></span>
550
550
  <span class="line"></span>
@@ -558,6 +558,15 @@ typed response. Manual signing is documented separately in <a href="/docs/authen
558
558
  <span class="line"><span style="color:#D19A66"> -H</span><span style="color:#98C379"> "X-Request-Timestamp: </span><span style="color:#E06C75">$TS</span><span style="color:#98C379">"</span><span style="color:#56B6C2"> \\</span></span>
559
559
  <span class="line"><span style="color:#D19A66"> -H</span><span style="color:#98C379"> "Content-Type: application/json"</span><span style="color:#56B6C2"> \\</span></span>
560
560
  <span class="line"><span style="color:#D19A66"> -d</span><span style="color:#98C379"> "</span><span style="color:#E06C75">$BODY</span><span style="color:#98C379">"</span></span>
561
+ <span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="mcp"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="mcp"><code><span class="line"><span style="color:#ABB2BF">Setup once in terminal: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">npx -y @paymos/mcp setup</span><span style="color:#E5C07B">\`</span></span>
562
+ <span class="line"></span>
563
+ <span class="line"><span style="color:#ABB2BF">Prompt:</span></span>
564
+ <span class="line"><span style="color:#ABB2BF">Read </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">paymos://docs/hosted-checkout</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> and integrate Paymos invoice</span></span>
565
+ <span class="line"><span style="color:#ABB2BF">creation into my backend using the official SDK for this project's</span></span>
566
+ <span class="line"><span style="color:#ABB2BF">stack. Then use </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">@paymos/mcp</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> in sandbox to call </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">create_invoice</span><span style="color:#E5C07B">\`</span></span>
567
+ <span class="line"><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">\`</span><span style="color:#98C379">project_id</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">prj_xxxxxxxxxxxx</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">amount</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">"100.00"</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">currency</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">:</span></span>
568
+ <span class="line"><span style="color:#E5C07B">\`</span><span style="color:#98C379">"USD"</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">external_order_id</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">"order-123"</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">) and run</span></span>
569
+ <span class="line"><span style="color:#E5C07B">\`</span><span style="color:#98C379">simulate_invoice_payment</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">\`</span><span style="color:#98C379">stage</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">"paid"</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">) to verify the flow.</span></span>
561
570
  <span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="javascript"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="javascript"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">Paymos</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">externalOrderId</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@paymos/sdk'</span><span style="color:#ABB2BF">;</span></span>
562
571
  <span class="line"></span>
563
572
  <span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> paymos</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> new</span><span style="color:#61AFEF"> Paymos</span><span style="color:#ABB2BF">({</span></span>
@@ -734,7 +743,7 @@ typed response. Manual signing is documented separately in <a href="/docs/authen
734
743
  <pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="json"><code><span class="line"><span style="color:#ABB2BF">{</span></span>
735
744
  <span class="line"><span style="color:#E06C75"> "event_id"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"evt_J7EEYeL9pZJukfj2c5OQ44"</span><span style="color:#ABB2BF">,</span></span>
736
745
  <span class="line"><span style="color:#E06C75"> "event_type"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"invoice.paid"</span><span style="color:#ABB2BF">,</span></span>
737
- <span class="line"><span style="color:#E06C75"> "version"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">2</span><span style="color:#ABB2BF">,</span></span>
746
+ <span class="line"><span style="color:#E06C75"> "version"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1</span><span style="color:#ABB2BF">,</span></span>
738
747
  <span class="line"><span style="color:#E06C75"> "occurred_at"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1739281200</span><span style="color:#ABB2BF">,</span></span>
739
748
  <span class="line"><span style="color:#E06C75"> "data"</span><span style="color:#ABB2BF">: {</span></span>
740
749
  <span class="line"><span style="color:#E06C75"> "invoice_id"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"inv_5CcyDYmMUGtzYL10q0Iimr"</span><span style="color:#ABB2BF">,</span></span>
@@ -783,13 +792,21 @@ typed response. Manual signing is documented separately in <a href="/docs/authen
783
792
  <span class="line"></span></code></pre>
784
793
  <p>Verify the <code>X-Webhook-Signature</code> header and fulfill the order.</p>
785
794
  <div class="callout callout--danger"><svg class="callout__icon" viewBox="0 0 20 20" fill="none" stroke="currentColor" aria-hidden="true"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.6" d="M10 2.5a7.5 7.5 0 1 0 0 15 7.5 7.5 0 0 0 0-15ZM7 7l6 6m0-6-6 6"></path></svg><div class="callout__body"><p>Never fulfill an order from a browser event (<code>paymos:succeeded</code> or iframe <code>postMessage</code>). Only the signed server-side webhook is authoritative \u2014 browser signals can be spoofed.</p></div></div>
786
- <div class="code-tab-group"><div class="code-tab-bar"><button type="button" class="code-tab-btn active" data-tab-idx="0" data-code-lang="javascript"><i class="devicon-javascript-plain colored"></i> JavaScript</button><button type="button" class="code-tab-btn" data-tab-idx="1" data-code-lang="python"><i class="devicon-python-plain colored"></i> Python</button><button type="button" class="code-tab-btn" data-tab-idx="2" data-code-lang="php"><i class="devicon-php-plain colored"></i> PHP</button><button type="button" class="code-tab-btn" data-tab-idx="3" data-code-lang="go"><i class="devicon-go-plain colored"></i> Go</button><button type="button" class="code-tab-btn" data-tab-idx="4" data-code-lang="csharp"><i class="devicon-csharp-plain colored"></i> C#</button><button type="button" class="code-tab-btn" data-tab-idx="5" data-code-lang="java"><i class="devicon-java-plain colored"></i> Java</button><button type="button" class="code-tab-btn" data-tab-idx="6" data-code-lang="ruby"><i class="devicon-ruby-plain colored"></i> Ruby</button><button type="button" class="code-tab-btn" data-tab-idx="7" data-code-lang="rust"><i class="devicon-rust-original colored"></i> Rust</button></div><div class="code-tab-panel active" data-code-lang="javascript"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="javascript"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">WebhookVerifier</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@paymos/sdk'</span><span style="color:#ABB2BF">;</span></span>
795
+ <div class="code-tab-group"><div class="code-tab-bar"><button type="button" class="code-tab-btn active" data-tab-idx="0" data-code-lang="javascript"><i class="devicon-javascript-plain colored"></i> JavaScript</button><button type="button" class="code-tab-btn" data-tab-idx="1" data-code-lang="mcp">MCP</button><button type="button" class="code-tab-btn" data-tab-idx="2" data-code-lang="python"><i class="devicon-python-plain colored"></i> Python</button><button type="button" class="code-tab-btn" data-tab-idx="3" data-code-lang="php"><i class="devicon-php-plain colored"></i> PHP</button><button type="button" class="code-tab-btn" data-tab-idx="4" data-code-lang="go"><i class="devicon-go-plain colored"></i> Go</button><button type="button" class="code-tab-btn" data-tab-idx="5" data-code-lang="csharp"><i class="devicon-csharp-plain colored"></i> C#</button><button type="button" class="code-tab-btn" data-tab-idx="6" data-code-lang="java"><i class="devicon-java-plain colored"></i> Java</button><button type="button" class="code-tab-btn" data-tab-idx="7" data-code-lang="ruby"><i class="devicon-ruby-plain colored"></i> Ruby</button><button type="button" class="code-tab-btn" data-tab-idx="8" data-code-lang="rust"><i class="devicon-rust-original colored"></i> Rust</button></div><div class="code-tab-panel active" data-code-lang="javascript"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="javascript"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">WebhookVerifier</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@paymos/sdk'</span><span style="color:#ABB2BF">;</span></span>
787
796
  <span class="line"></span>
788
797
  <span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> verifier</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> new</span><span style="color:#61AFEF"> WebhookVerifier</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">process</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">env</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">PAYMOS_WEBHOOK_SECRET</span><span style="color:#ABB2BF">);</span></span>
789
798
  <span class="line"></span>
790
799
  <span class="line"><span style="color:#7F848E;font-style:italic">// Keep the body as a Buffer until verification succeeds.</span></span>
791
800
  <span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> event</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> verifier</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">constructEvent</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">signatureHeader</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">rawBody</span><span style="color:#ABB2BF">);</span></span>
792
801
  <span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">eventId</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">eventType</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">data</span><span style="color:#ABB2BF">);</span></span>
802
+ <span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="mcp"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="mcp"><code><span class="line"><span style="color:#ABB2BF">Setup once in terminal: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">npx -y @paymos/mcp setup</span><span style="color:#E5C07B">\`</span></span>
803
+ <span class="line"></span>
804
+ <span class="line"><span style="color:#ABB2BF">Prompt:</span></span>
805
+ <span class="line"><span style="color:#ABB2BF">Read </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">paymos://docs/webhooks</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> and add a Paymos webhook endpoint to my</span></span>
806
+ <span class="line"><span style="color:#ABB2BF">backend that verifies </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">X-Webhook-Signature</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> over the unparsed raw</span></span>
807
+ <span class="line"><span style="color:#ABB2BF">request body using </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">WebhookVerifier</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> from the official SDK and</span></span>
808
+ <span class="line"><span style="color:#ABB2BF">deduplicates deliveries by </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">event_id</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">. Use </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">@paymos/mcp</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> tool</span></span>
809
+ <span class="line"><span style="color:#E5C07B">\`</span><span style="color:#98C379">verify_webhook_signature</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> to test valid and tampered signatures.</span></span>
793
810
  <span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="python"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="python"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> os</span></span>
794
811
  <span class="line"></span>
795
812
  <span class="line"><span style="color:#C678DD">from</span><span style="color:#ABB2BF"> paymos </span><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> WebhookVerifier</span></span>
@@ -1017,6 +1034,10 @@ typed response. Manual signing is documented separately in <a href="/docs/authen
1017
1034
  <p>Sandbox withdrawals don't settle on a real chain. Mark a pending sandbox withdrawal as completed to exercise your full payout flow:</p>
1018
1035
  <div class="api-endpoint-badge"><span class="api-method-badge api-method-post">POST</span><span class="api-endpoint-badge__path">/v1/sandbox/withdrawals/:withdrawal_id/simulate-completion</span></div>
1019
1036
  <p>No request body. Authenticate it like any other <code>/v1</code> call with your Payout key; it acts on sandbox withdrawals only. It transitions the withdrawal to <code>completed</code> and emits the same <code>withdrawal.completed</code> webhook as a real on-chain payout, so your reconciliation path stays identical between sandbox and production.</p>
1037
+ <h2 id="simulating-refunds">Simulating refunds</h2>
1038
+ <p>Create a sandbox refund first with <a href="/docs/refunds/create"><code>POST /v1/refunds</code></a> using your sandbox Payment key (<code>pk_test_</code>), then drive it to a terminal status:</p>
1039
+ <div class="api-endpoint-badge"><span class="api-method-badge api-method-post">POST</span><span class="api-endpoint-badge__path">/v1/sandbox/refunds/:withdrawal_id/simulate</span></div>
1040
+ <div class="callout callout--info"><svg class="callout__icon" viewBox="0 0 20 20" fill="none" stroke="currentColor" aria-hidden="true"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.6" d="M10 2.5a7.5 7.5 0 1 0 0 15 7.5 7.5 0 0 0 0-15Zm0 6.5v5m0-7.5h.01"></path></svg><div class="callout__body"><p>Body: <code>{ "status": "completed" }</code> \u2014 <code>status</code> is one of <code>completed</code>, <code>failed</code>, or <code>cancelled</code>. Sign it with your sandbox Payment key (<code>pk_test_</code>). It updates the sandbox ledger and emits the corresponding <code>withdrawal.completed</code>, <code>withdrawal.failed</code>, or <code>withdrawal.cancelled</code> webhook with the full refund payload. See <a href="/docs/refunds/simulate">Simulate Refund</a> for the full contract.</p></div></div>
1020
1041
  <h2 id="simulating-channel-deposits">Simulating channel deposits</h2>
1021
1042
  <p>Sandbox payment channels derive their addresses locally and watch no chain, so deposits are created explicitly:</p>
1022
1043
  <div class="api-endpoint-badge"><span class="api-method-badge api-method-post">POST</span><span class="api-endpoint-badge__path">/v1/sandbox/payment-channels/:payment_channel_id/simulate-deposit</span></div>
@@ -1170,13 +1191,82 @@ function registerResources(server) {
1170
1191
  }
1171
1192
  }
1172
1193
 
1194
+ // src/integration-recommendation.ts
1195
+ import { z as z2 } from "zod";
1196
+ var INTEGRATION_INSTRUCTIONS = "When helping a developer choose a payment integration, call recommend_payment_integration with scenario order_checkout, repeat_deposits, both, or unsure. Respect the merchant\u2019s stated preference; do not replace an explicit choice. Explain why the recommended flow fits their needs and identify missing information. Use unsure when the need is unclear; ask whether the customer will pay for each order, repeatedly top up an account, or do both. This MCP server calls sandbox only and rejects live and payout credentials. Check availability in the target environment.";
1197
+ var GUIDE = `Choose the flow before creating a payment resource.
1198
+
1199
+ Use an invoice when your customer pays for a specific order. An invoice has a set amount, an expiry, and payment statuses; its hosted checkout gives the customer a page to pay that invoice.
1200
+
1201
+ Choose a payment channel for repeated customer deposits. It belongs to one payer and keeps a permanent address per supported network. The channel sets no amount or expiry and has no terminal payment status. Each credited transfer becomes a separate deposit, so track deposits individually when crediting the customer\u2019s account. Transfers below the minimum deposit are not credited or returned.
1202
+
1203
+ You can use both in the same integration. For example, use invoices for purchases and a payment channel for account top-ups. If the intended flow is unclear, ask: \u201CWill your customer pay for each order, repeatedly top up an account, or do both?\u201D
1204
+
1205
+ Test the chosen flow in sandbox. This MCP server calls sandbox only and rejects live and payout credentials. Create sandbox and production channels separately, and check availability in the target environment. Sandbox addresses are synthetic; each deposit simulation creates a new test deposit rather than updating an earlier simulation.
1206
+
1207
+ Credit channel deposits only after confirmation. Verify webhook signatures and require \`confirmed\` with \`is_final\` before crediting a deposit. Webhooks can repeat or arrive out of order: deduplicate deliveries by \`event_id\` and prevent duplicate credit for the same deposit.
1208
+
1209
+ Use the confirmed-deposit feed to reconcile deposits. Save every returned \`next_cursor\`, even on empty pages, and inspect \`blocked\` when present. \`confirmed_from\` bounds the first poll and forms part of the cursor\u2019s fingerprint; keep its value unchanged when continuing with that cursor. Feed cursors expire 24 hours after issue, so poll at least daily. If a cursor expires, restart with a bounded \`confirmed_from\` and retain deposit deduplication.
1210
+
1211
+ Start with the flow you chose. The recommendation needs no credentials; API calls need test credentials.
1212
+
1213
+ For invoices, call \`create_invoice\` with \`project_id\`, \`external_order_id\`, \`amount\` as a decimal string, and \`currency\`. Save the invoice\u2019s link to your order, and use the returned \`payment_url\` for checkout. Test a payment with \`simulate_invoice_payment\`, passing \`invoice_id\` and \`stage\`.
1214
+
1215
+ For payment channels, call \`create_payment_channel\` with \`project_id\` and your customer\u2019s \`external_id\`. Save the channel\u2019s link to that customer. Check the returned networks and addresses; an address may still be provisioning. Call \`get_payment_channel\` again to check readiness and addresses. Call \`simulate_payment_channel_deposit\` with \`payment_channel_id\`, \`amount\` as a decimal string, \`currency\`, and \`network\`; \`stage\` is optional. Read any deposit status with \`get_payment_channel_deposit\`, or use \`list_payment_channel_deposits\` for the confirmed-deposit feed.
1216
+
1217
+ If you chose both, follow both paths. Before changing an order or customer balance, verify webhook signatures, apply the flow\u2019s confirmation checks, and deduplicate events. Credit channel deposits only when \`confirmed\` and \`is_final\`.`;
1218
+ var RECOMMENDATIONS = {
1219
+ order_checkout: {
1220
+ recommendation: "invoice",
1221
+ summary: "Use an invoice for each order: it has a set amount, an expiry, payment statuses, and hosted checkout. Explain how this fits the order flow while respecting the merchant\u2019s stated preference."
1222
+ },
1223
+ repeat_deposits: {
1224
+ recommendation: "payment_channel",
1225
+ summary: "Use a payment channel for repeated deposits from one payer to reusable addresses per network. Track credited deposits separately; transfers below the minimum are not credited or returned. The channel sets no amount or expiry."
1226
+ },
1227
+ both: {
1228
+ recommendation: "both",
1229
+ summary: "Use invoices for individual orders and payment channels for repeated account top-ups. Explain which customer action uses each flow, and respect any preference the merchant has already stated."
1230
+ },
1231
+ unsure: {
1232
+ recommendation: "unsure",
1233
+ summary: "Do not choose a flow yet. Ask: \u201CWill your customer pay for each order, repeatedly top up an account, or do both?\u201D Use the answer and the merchant\u2019s preferences to guide the recommendation."
1234
+ }
1235
+ };
1236
+ function registerIntegrationRecommendation(server) {
1237
+ server.registerTool(
1238
+ "recommend_payment_integration",
1239
+ {
1240
+ title: "Recommend a payment integration",
1241
+ description: "Recommend invoices, payment channels, or both from the merchant\u2019s payment flow. Explain the fit and relevant lifecycle. When information is missing, return a targeted question instead of choosing. Respect an explicit merchant choice.",
1242
+ inputSchema: {
1243
+ scenario: z2.enum(["order_checkout", "repeat_deposits", "both", "unsure"]).optional().describe("Choose order_checkout for payment per order, repeat_deposits for repeated customer account top-ups, or both when both flows are needed. Use unsure when the payment flow is unclear; ask whether the customer pays for each order, repeatedly tops up an account, or does both. Respect the merchant\u2019s explicit choice.")
1244
+ },
1245
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
1246
+ },
1247
+ async ({ scenario }) => {
1248
+ const selected = scenario ?? "unsure";
1249
+ return {
1250
+ content: [{
1251
+ type: "text",
1252
+ text: JSON.stringify({ scenario: selected, ...RECOMMENDATIONS[selected], guide: GUIDE }, null, 2)
1253
+ }]
1254
+ };
1255
+ }
1256
+ );
1257
+ }
1258
+
1173
1259
  // src/version.ts
1174
- var MCP_VERSION = "1.4.1";
1260
+ var MCP_VERSION = "1.5.1";
1175
1261
 
1176
1262
  // src/server.ts
1177
1263
  function buildServer(gateway) {
1178
- const server = new McpServer({ name: "paymos", version: MCP_VERSION });
1264
+ const server = new McpServer(
1265
+ { name: "paymos", version: MCP_VERSION },
1266
+ { instructions: INTEGRATION_INSTRUCTIONS }
1267
+ );
1179
1268
  registerTools(server, gateway);
1269
+ registerIntegrationRecommendation(server);
1180
1270
  registerResources(server);
1181
1271
  return server;
1182
1272
  }
@@ -1184,27 +1274,85 @@ function buildServer(gateway) {
1184
1274
  // src/setup.ts
1185
1275
  import {
1186
1276
  chmodSync,
1187
- closeSync as closeSync2,
1277
+ closeSync as closeSync3,
1188
1278
  constants as constants2,
1189
1279
  existsSync,
1190
- fstatSync as fstatSync2,
1280
+ fstatSync as fstatSync3,
1191
1281
  linkSync,
1192
- lstatSync as lstatSync2,
1193
- mkdirSync,
1194
- openSync as openSync2,
1282
+ lstatSync as lstatSync3,
1283
+ mkdirSync as mkdirSync2,
1284
+ openSync as openSync3,
1195
1285
  readFileSync as readFileSync2,
1196
1286
  renameSync,
1197
- unlinkSync,
1287
+ unlinkSync as unlinkSync2,
1198
1288
  writeFileSync
1199
1289
  } from "fs";
1200
1290
  import { randomUUID } from "crypto";
1201
1291
  import { homedir } from "os";
1202
- import { dirname, isAbsolute, join, resolve } from "path";
1292
+ import { dirname as dirname2, isAbsolute, join, resolve } from "path";
1203
1293
  import { createInterface } from "readline";
1204
1294
  import { Writable } from "stream";
1205
1295
  import { isDeepStrictEqual } from "util";
1206
1296
  import { applyEdits, modify, parse as parseJson, parseTree } from "jsonc-parser";
1207
1297
  import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
1298
+
1299
+ // src/setup-lock.ts
1300
+ import { closeSync as closeSync2, fstatSync as fstatSync2, lstatSync as lstatSync2, mkdirSync, openSync as openSync2, unlinkSync } from "fs";
1301
+ import { dirname } from "path";
1302
+ var LOCK_SUFFIX = ".paymos-setup.lock";
1303
+ var STALE_LOCK_MS = 3e4;
1304
+ var DestinationBusyError = class extends Error {
1305
+ constructor() {
1306
+ super("Another setup is publishing to this destination.");
1307
+ this.name = "DestinationBusyError";
1308
+ }
1309
+ };
1310
+ function acquire(lock, now) {
1311
+ for (let attempt = 0; ; attempt++) {
1312
+ let fd;
1313
+ try {
1314
+ fd = openSync2(lock, "wx", 384);
1315
+ } catch (cause) {
1316
+ if (cause.code !== "EEXIST") throw cause;
1317
+ if (attempt > 0 || !removeIfStale(lock, now)) throw new DestinationBusyError();
1318
+ continue;
1319
+ }
1320
+ try {
1321
+ const stat = fstatSync2(fd);
1322
+ return { ino: stat.ino, dev: stat.dev };
1323
+ } finally {
1324
+ closeSync2(fd);
1325
+ }
1326
+ }
1327
+ }
1328
+ function removeIfStale(lock, now) {
1329
+ try {
1330
+ if (now() - lstatSync2(lock).mtimeMs < STALE_LOCK_MS) return false;
1331
+ unlinkSync(lock);
1332
+ return true;
1333
+ } catch (cause) {
1334
+ return cause.code === "ENOENT";
1335
+ }
1336
+ }
1337
+ function release(lock, mine) {
1338
+ try {
1339
+ const stat = lstatSync2(lock);
1340
+ if (stat.ino === mine.ino && stat.dev === mine.dev) unlinkSync(lock);
1341
+ } catch {
1342
+ }
1343
+ }
1344
+ function withDestinationLock(destination, action, now = Date.now) {
1345
+ const lock = destination + LOCK_SUFFIX;
1346
+ mkdirSync(dirname(lock), { recursive: true, mode: 448 });
1347
+ const mine = acquire(lock, now);
1348
+ try {
1349
+ return action();
1350
+ } finally {
1351
+ release(lock, mine);
1352
+ }
1353
+ }
1354
+
1355
+ // src/setup.ts
1208
1356
  var SETUP_CLIENTS = [
1209
1357
  "codex",
1210
1358
  "claude-code",
@@ -1297,18 +1445,18 @@ function defaultConfigPath(client, env, context) {
1297
1445
  function snapshot(path) {
1298
1446
  let fd;
1299
1447
  try {
1300
- const stat = lstatSync2(path);
1448
+ const stat = lstatSync3(path);
1301
1449
  if (stat.isSymbolicLink()) error("symlink");
1302
1450
  if (!stat.isFile() || stat.size > 4194304) error("configFile");
1303
- fd = openSync2(path, constants2.O_RDONLY | (constants2.O_NOFOLLOW ?? 0));
1304
- if (fstatSync2(fd).ino !== stat.ino) error("changed");
1451
+ fd = openSync3(path, constants2.O_RDONLY | (constants2.O_NOFOLLOW ?? 0));
1452
+ if (fstatSync3(fd).ino !== stat.ino) error("changed");
1305
1453
  return { path, content: readFileSync2(fd, "utf8") };
1306
1454
  } catch (cause) {
1307
1455
  if (cause.code === "ENOENT") return { path, content: null };
1308
1456
  if (cause instanceof Error && Object.values(SETUP_COPY.errors).includes(cause.message)) throw cause;
1309
1457
  return error("configFile");
1310
1458
  } finally {
1311
- if (fd !== void 0) closeSync2(fd);
1459
+ if (fd !== void 0) closeSync3(fd);
1312
1460
  }
1313
1461
  }
1314
1462
  function assertUnchanged(before) {
@@ -1381,20 +1529,20 @@ function planClientConfig(client, original, credentialsPath, platform) {
1381
1529
  return next;
1382
1530
  }
1383
1531
  function writeConfig(before, content) {
1384
- mkdirSync(dirname(before.path), { recursive: true, mode: 448 });
1385
- const temp = join(dirname(before.path), `.paymos-${randomUUID()}.tmp`);
1532
+ mkdirSync2(dirname2(before.path), { recursive: true, mode: 448 });
1533
+ const temp = join(dirname2(before.path), `.paymos-${randomUUID()}.tmp`);
1386
1534
  let created = false;
1387
1535
  try {
1388
1536
  writeFileSync(temp, content, { encoding: "utf8", mode: 384, flag: "wx" });
1389
1537
  created = true;
1390
1538
  if (process.platform !== "win32") chmodSync(temp, 384);
1391
- const identity = lstatSync2(temp);
1539
+ const identity = lstatSync3(temp);
1392
1540
  assertUnchanged(before);
1393
1541
  if (before.content === null) linkSync(temp, before.path);
1394
1542
  else renameSync(temp, before.path);
1395
1543
  return { ino: identity.ino, dev: identity.dev };
1396
1544
  } finally {
1397
- if (created && existsSync(temp)) unlinkSync(temp);
1545
+ if (created && existsSync(temp)) unlinkSync2(temp);
1398
1546
  }
1399
1547
  }
1400
1548
  async function ask(io, label, secret = false) {
@@ -1476,17 +1624,20 @@ async function runSetup(argv, env = process.env, io = terminalIO(), context = {
1476
1624
  }
1477
1625
  let createdKeys;
1478
1626
  try {
1479
- assertUnchanged(before);
1480
- assertUnchanged(beforeKeys);
1481
- if (stored === void 0) {
1482
- createdKeys = writeConfig(beforeKeys, JSON.stringify(credentials, null, 2) + "\n");
1483
- }
1484
- if (before.content !== next) writeConfig(before, next);
1627
+ withDestinationLock(configPath, () => {
1628
+ assertUnchanged(before);
1629
+ assertUnchanged(beforeKeys);
1630
+ if (stored === void 0) {
1631
+ createdKeys = writeConfig(beforeKeys, JSON.stringify(credentials, null, 2) + "\n");
1632
+ }
1633
+ if (before.content !== next) writeConfig(before, next);
1634
+ });
1485
1635
  } catch (cause) {
1636
+ if (cause instanceof DestinationBusyError) error("changed");
1486
1637
  if (createdKeys !== void 0) {
1487
1638
  try {
1488
- const stat = lstatSync2(credentialsPath);
1489
- if (!stat.isSymbolicLink() && stat.ino === createdKeys.ino && stat.dev === createdKeys.dev && isDeepStrictEqual(readCredentialFile(credentialsPath), credentials)) unlinkSync(credentialsPath);
1639
+ const stat = lstatSync3(credentialsPath);
1640
+ if (!stat.isSymbolicLink() && stat.ino === createdKeys.ino && stat.dev === createdKeys.dev && isDeepStrictEqual(readCredentialFile(credentialsPath), credentials)) unlinkSync2(credentialsPath);
1490
1641
  } catch {
1491
1642
  }
1492
1643
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@paymos/mcp",
3
- "version": "1.4.1",
3
+ "version": "1.5.1",
4
4
  "description": "Official Paymos MCP server: a local stdio server that lets coding agents (Claude Code, Cursor, custom LLM bots) build and verify a merchant integration against the Paymos sandbox without reading docs.",
5
5
  "keywords": [
6
6
  "paymos",