@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/mtn-momo-integration/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: mtn-momo-integration
+description: Builds and reviews direct integrations with the MTN Mobile Money (MoMo) Open API from momodeveloper.mtn.com, including Collection request-to-pay, Disbursement transfers and refunds, API user and access token handling, X-Reference-Id idempotency, unsigned callbacks confirmed by status checks, and sandbox testing for MTN markets such as Ghana, Uganda and Cameroon. Use when integrating MTN MoMo directly rather than through Paystack or another aggregator, calling requesttopay or disbursement endpoints, handling MoMo callbacks, or debugging MoMo API errors such as 401, 409 or INVALID_CALLBACK_URL_HOST.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to sandbox.momodeveloper.mtn.com or the production MoMo API. The sandbox setup script needs Node 18+. Examples are TypeScript; the rules apply to any backend language.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/requires: "node"
+  kete-loom/owner: "Kete-org"
+---
+
+# MTN MoMo integration
+
+Build a MoMo payment flow that can't be faked, never charges or pays out twice, and still settles when a callback never arrives. This skill is for the MTN MoMo Open API called directly. If the project pays through Paystack, Flutterwave or another aggregator, follow that provider's flow instead.
+
+## Ground rules
+
+1. **Credentials stay on the server.** The subscription key, API user, API key and access token are all secrets. Read them from the environment, never ship them to a browser or app, and keep one set per product: Collection, Disbursement and Remittance each have their own subscription key.
+2. **One fresh UUID v4 `X-Reference-Id` per attempt, stored before you call.** It is the transaction's ID. MoMo rejects a reused ID with `409 RESOURCE_ALREADY_EXIST`, so a timed-out request can be retried with the **same** ID safely: a 409 means the first attempt was created, so check its status. A new attempt by the customer gets a new ID.
+3. **Callbacks are not signed and are sent once, with no retry.** Never give value because a callback arrived or because of what its body says. Treat it as a hint to run a status check, and poll the status endpoint as well, because some callbacks never arrive.
+4. **Only a status check confirms money moved.** `GET .../requesttopay/{referenceId}` (or `/transfer/{id}`) returns `200` even when the payment failed. Give value only when `status` is `SUCCESSFUL` **and** the amount and currency equal what you stored.
+5. **Fulfilment is idempotent.** Mark the order paid with a guarded update (`UPDATE ... WHERE status = 'pending'`) keyed on the reference, so a callback, a poll and a retry arriving together still fulfil once.
+6. **The server decides the price.** Compute the amount from your own records. `amount` is a string; build it from integer minor units, never from float arithmetic.
+7. **Sandbox first, in EUR.** The sandbox only accepts `EUR` and target environment `sandbox`. Production uses the market's currency and its own target environment (for example `mtnghana` with `GHS`).
+
+## Flow (Collection: request to pay)
+
+```
+client ──(order id, phone number)──▶ server: create order + payment row with a new UUID (status PENDING)
+server ──POST /collection/v1_0/requesttopay (X-Reference-Id = that UUID)──▶ MoMo: 202 Accepted
+customer approves the prompt on their phone (about 5 minutes before it times out)
+MoMo ──callback (PUT or POST, unsigned)──▶ server: return 200 at once, then run a status check
+server ──GET /collection/v1_0/requesttopay/{id}──▶ SUCCESSFUL + amount/currency match → fulfil once
+background job: poll PENDING payments with backoff until final, or time them out
+```
+
+The client never learns the result from MoMo directly. It asks your server, which reports the stored status.
+
+## Implementation steps
+
+1. **Configure** environment variables for the base URL, target environment, currency, and each product's subscription key, API user and API key. In sandbox, create the API user and key with `scripts/sandbox-setup.js` (see `references/sandbox-and-go-live.md`). In production, they come from MTN's partner portal for your market, not from the API.
+2. **Get an access token** per product with `POST /{product}/token/`, using Basic auth (`apiUser:apiKey`), the subscription key and **no body**. Cache it and refresh it before `expires_in` runs out instead of requesting one per payment.
+3. **Request to pay** with the headers and body in `references/api.md`. Validate the phone number first: digits only, with the country code (for example `233...` in Ghana). `payerMessage` and `payeeNote` are at most 160 characters; avoid apostrophes and other special characters, which MoMo rejects with 400.
+4. **Handle callbacks and polling** exactly as `references/callbacks.md` describes: accept both PUT and POST, put a per-transaction token in the callback path, respond 200 fast, and confirm every result with a status check.
+5. **Map failures** to clear messages using the reason codes in `references/api.md`: unknown number, not enough funds, approval rejected, timed out (`EXPIRED`, `COULD_NOT_PERFORM_TRANSACTION`), limit reached. Let the customer retry with a new reference.
+6. **Payouts and refunds** (Disbursement) follow the same rules: a new UUID per transfer, store it first, confirm by status. Production Disbursement also requires your server's IP to be whitelisted, otherwise calls fail with `403`.
+7. **Persist** for each payment: the reference UUID, order id, expected amount and currency, phone number, status, `financialTransactionId`, failure reason, and timestamps. Reconcile against MoMo's status regularly.
+
+## Reviewing an existing integration
+
+Check each ground rule, then look for these common bugs:
+
+- Fulfilment triggered by the callback body, or by the 202 from request to pay.
+- A new `X-Reference-Id` generated on retry, which can charge the customer twice, or the same ID reused for a new attempt, which fails with 409.
+- No polling fallback, so payments stay PENDING forever when a callback is lost.
+- Status treated as success because the HTTP response was 200.
+- A token requested for every call, or a Collection key used against Disbursement (401).
+- Callback host that differs from the API user's `providerCallbackHost`, uses plain HTTP, or uses an IP address (`INVALID_CALLBACK_URL_HOST`).
+- Sandbox values (`EUR`, `sandbox`) left in production configuration, or production credentials used in the sandbox.
+- Amounts built with floats, or a price taken from the client.
+
+## Before you finish
+
+The API reference at momodeveloper.mtn.com is the final word on field names and behaviour; this skill gives the rules and the shape. Production base URLs and market currencies vary by country, so confirm them with MTN for the market you go live in. Then test in the sandbox with the test numbers in `references/sandbox-and-go-live.md`: a successful payment, a failure, a rejection, an expired approval, a callback that never arrives (polling must settle it), a duplicate callback, and a retried request after a simulated timeout (must not charge twice).

package/skills/mtn-momo-integration/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Integrate the MTN MoMo Open API so customers in Ghana can pay with request to pay",
+    "Our momodeveloper sandbox keeps returning 401 when I call /collection/token/",
+    "MoMo callbacks never reach our server and payments stay PENDING forever",
+    "Add payouts to agents' mobile money wallets using the MTN MoMo disbursement API",
+    "Why does requesttopay return 409 when we retry after a timeout?"
+  ],
+  "should_not_trigger": [
+    "Let users pay with MTN MoMo through Paystack in the mobile app",
+    "My Paystack webhook says invalid signature every time, can you fix it?",
+    "Integrate M-Pesa STK push with the Safaricom Daraja API",
+    "Write a market report on mobile money adoption in Uganda",
+    "Add Stripe checkout to the pricing page"
+  ]
+}

package/skills/mtn-momo-integration/references/api.md

@@ -0,0 +1,153 @@
+# MTN MoMo Open API reference
+
+Read this when writing or reviewing the HTTP calls. Checked against the API reference on momodeveloper.mtn.com in October 2026; confirm against the current reference before shipping.
+
+## Base URLs and target environments
+
+| Environment | Base URL | `X-Target-Environment` |
+|---|---|---|
+| Sandbox | `https://sandbox.momodeveloper.mtn.com` | `sandbox` (currency must be `EUR`) |
+| Production | `https://proxy.momoapi.mtn.com` (stated by MTN on its developer community forum, not in the API reference; confirm with MTN for your market) | the market value below |
+
+Paths are prefixed by product: `/collection`, `/disbursement`, `/remittance`. Sandbox provisioning (`/v1_0/apiuser`) has no product prefix.
+
+Production target environments documented by MTN: `mtnuganda`, `mtnghana`, `mtnivorycoast`, `mtnzambia`, `mtncameroon`, `mtnbenin`, `mtncongo`, `mtnswaziland`, `mtnguineaconakry`, `mtnsouthafrica`, `mtnliberia`, `mtnsouthsudan`, `mtnnigeria`, `mtnrwanda`. A wrong value fails with `NOT_ALLOWED_TARGET_ENVIRONMENT`.
+
+Currencies by market, from MTN's community forum (confirm before going live): Uganda `UGX`, Ghana `GHS`, Côte d'Ivoire `XOF`, Zambia `ZMW`, Cameroon `XAF`, Benin `XOF`, Congo `XAF`, Eswatini `SZL`, Guinea `GNF`, South Africa `ZAR`, Liberia `LRD`.
+
+## Authentication
+
+- **Subscription key**: header `Ocp-Apim-Subscription-Key`. Each product has its own primary and secondary key; either works. A key from the wrong product gives 401.
+- **API user and API key**: sandbox users are created with the API (see `sandbox-and-go-live.md`). Production users are created in the partner portal for your market. Sandbox users only work in the sandbox.
+- **Access token**: `POST /{product}/token/` with `Authorization: Basic base64(apiUser:apiKey)`, the subscription key, and **no body** (a body gives 400). The response is `{ "access_token": "...", "token_type": "...", "expires_in": <seconds> }`. Send it as `Authorization: Bearer <access_token>`, cache it per product, and refresh it shortly before `expires_in` ends.
+- `bc-authorize` and `/oauth2/token/` exist for consent-based calls such as `/oauth2/v1_0/userinfo`. Request to pay, transfers, balance and basic user info use the plain token above.
+
+## Request to pay (Collection)
+
+`POST /collection/v1_0/requesttopay`
+
+| Header | Value |
+|---|---|
+| `Authorization` | `Bearer <access_token>` |
+| `X-Reference-Id` | a new UUID v4 you stored first; it becomes the transaction ID |
+| `X-Target-Environment` | `sandbox` or the market value |
+| `Ocp-Apim-Subscription-Key` | the Collection subscription key |
+| `X-Callback-Url` | optional; HTTPS on the API user's callback host |
+| `Content-Type` | `application/json` |
+
+```json
+{
+  "amount": "25.50",
+  "currency": "GHS",
+  "externalId": "order_8f2c1a",
+  "payer": { "partyIdType": "MSISDN", "partyId": "233241234567" },
+  "payerMessage": "Order 8f2c1a",
+  "payeeNote": "Order 8f2c1a"
+}
+```
+
+- `amount` is a string in the currency's major unit. Build it from integer minor units with `formatAmount` below, which knows that UGX, XOF, XAF and GNF have no decimals. MTN doesn't document whether every market accepts decimals, so confirm the format with a small real payment before going live.
+- `partyIdType` is `MSISDN`, `EMAIL` or `PARTY_CODE`. An MSISDN includes the country code; MTN's examples use digits only, without `+`.
+- `externalId` is your reference for reconciliation; it doesn't need to be unique.
+- `payerMessage` and `payeeNote`: at most 160 characters, no apostrophes or special characters.
+
+Responses: `202 Accepted` with no body (the payment is now PENDING). `409 RESOURCE_ALREADY_EXIST` if the `X-Reference-Id` was used before. `400` for a bad body, `401` for a bad key or token, `500` with a reason code for environment, currency or callback-host errors.
+
+```ts
+import { randomUUID } from 'node:crypto';
+
+const MOMO = process.env.MOMO_BASE_URL!; // https://sandbox.momodeveloper.mtn.com
+const ENV = process.env.MOMO_TARGET_ENVIRONMENT!; // sandbox | mtnghana | ...
+const KEY = process.env.MOMO_COLLECTION_SUBSCRIPTION_KEY!;
+
+export async function requestToPay(order: { id: string; amountMinor: number; currency: string; msisdn: string }) {
+  const referenceId = randomUUID();
+  await db.payments.insert({ referenceId, orderId: order.id, amountMinor: order.amountMinor, currency: order.currency, status: 'PENDING' });
+  const res = await fetch(`${MOMO}/collection/v1_0/requesttopay`, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${await collectionToken()}`,
+      'x-reference-id': referenceId,
+      'x-target-environment': ENV,
+      'ocp-apim-subscription-key': KEY,
+      'x-callback-url': callbackUrl(referenceId),
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify({
+      amount: formatAmount(order.amountMinor, order.currency),
+      currency: order.currency,
+      externalId: order.id,
+      payer: { partyIdType: 'MSISDN', partyId: order.msisdn },
+      payerMessage: `Order ${order.id}`,
+      payeeNote: `Order ${order.id}`,
+    }),
+  });
+  // 409 on a retry with the same referenceId means the first attempt was created: check its status instead.
+  if (res.status !== 202 && res.status !== 409) throw new Error(`requesttopay failed: ${res.status} ${await res.text()}`);
+  return referenceId;
+}
+
+// Money as integer minor units, converted with integer maths only. Intl knows each currency's ISO decimals (GHS 2, UGX 0).
+const decimals = (currency: string) => new Intl.NumberFormat('en', { style: 'currency', currency }).resolvedOptions().maximumFractionDigits ?? 2;
+
+export function formatAmount(minor: number, currency: string): string {
+  const d = decimals(currency);
+  if (d === 0) return String(minor);
+  const s = String(minor).padStart(d + 1, '0');
+  return `${s.slice(0, -d)}.${s.slice(-d)}`; // 2550 GHS -> "25.50"
+}
+
+// MoMo may echo "25.5" or "25.50": compare in minor units, not as strings.
+export function toMinor(amount: string, currency: string): number {
+  const d = decimals(currency);
+  const [whole, frac = ''] = amount.split('.');
+  if (!/^\d+$/.test(whole) || !/^\d*$/.test(frac) || frac.length > d) return NaN;
+  return Number(whole) * 10 ** d + Number(frac.padEnd(d, '0') || 0);
+}
+```
+
+If the request times out or returns 5xx, retry it with the **same** `referenceId` and headers. Never generate a new one for the same attempt.
+
+## Status
+
+`GET /collection/v1_0/requesttopay/{referenceId}` with the same auth headers (no callback header). Returns `200` whatever the outcome:
+
+```json
+{
+  "amount": "25.50",
+  "currency": "GHS",
+  "financialTransactionId": "1234567890",
+  "externalId": "order_8f2c1a",
+  "payer": { "partyIdType": "MSISDN", "partyId": "233241234567" },
+  "status": "FAILED",
+  "reason": { "code": "NOT_ENOUGH_FUNDS", "message": "..." }
+}
+```
+
+`status` is `PENDING`, `SUCCESSFUL` or `FAILED`. An unknown reference gives `404 RESOURCE_NOT_FOUND`.
+
+## Reason codes
+
+| Code | Tell the customer |
+|---|---|
+| `PAYER_NOT_FOUND` | This number isn't registered for MoMo |
+| `NOT_ENOUGH_FUNDS` (also often `INTERNAL_PROCESSING_ERROR`) | Not enough money in the wallet |
+| `PAYER_LIMIT_REACHED` | The wallet's limit was reached |
+| `APPROVAL_REJECTED`, `PAYMENT_NOT_APPROVED`, `TRANSACTION_CANCELED` | The payment was declined on the phone |
+| `EXPIRED`, `COULD_NOT_PERFORM_TRANSACTION` | The approval timed out (about 5 minutes) |
+| `PAYEE_NOT_ALLOWED_TO_RECEIVE`, `NOT_ALLOWED` | Merchant-side problem: log it and alert, don't blame the customer |
+| `NOT_ALLOWED_TARGET_ENVIRONMENT`, `INVALID_CURRENCY`, `INVALID_CALLBACK_URL_HOST` | Configuration error on your side |
+| `SERVICE_UNAVAILABLE` | Try again later |
+
+## Disbursement and refunds
+
+- **Transfer (payout)**: `POST /disbursement/v1_0/transfer`, same headers as request to pay with the Disbursement key and token. The body uses `payee` instead of `payer`. `202` or `409`. Status: `GET /disbursement/v1_0/transfer/{referenceId}`.
+- **Refund**: `POST /disbursement/v1_0/refund` (or `/v2_0/refund`) with `amount`, `currency`, `externalId`, `payerMessage`, `payeeNote` and `referenceIdToRefund` (the request-to-pay UUID). Status: `GET /disbursement/v1_0/refund/{referenceId}`. The v1 and v2 endpoints take the same body; MTN documents v1 callbacks as POST and v2 as PUT.
+- **Deposit**: `/disbursement/v1_0/deposit` and `/v2_0/deposit`, same body shape as a transfer.
+- Production Disbursement calls need your server's IP whitelisted with MTN, or they fail with `403`.
+
+## Other endpoints
+
+- `GET /{product}/v1_0/account/balance` returns `{ "availableBalance": "...", "currency": "..." }`.
+- `GET /{product}/v1_0/accountholder/msisdn/{msisdn}/active` returns `{ "result": true }`. The type is lowercase. It shows the account exists and is active, not that it can pay a given amount.
+- `GET /{product}/v1_0/accountholder/msisdn/{msisdn}/basicuserinfo` returns the holder's name. Useful to show "Pay Ama Mensah?" before a payout.

package/skills/mtn-momo-integration/references/callbacks.md

@@ -0,0 +1,92 @@
+# Callbacks and status polling
+
+Read this when building or reviewing the callback endpoint or the code that settles PENDING payments.
+
+## What MoMo guarantees, and what it doesn't
+
+- Callbacks are **not signed** and carry no authentication. Anyone who learns the URL can call it.
+- MoMo sends each callback **once, with no retry**. If your server is down or slow, it is lost.
+- The documentation is inconsistent about the method (PUT for most, POST for v1 deposit and refund), so **accept both**.
+- The body looks like the status response, but you must not trust it.
+- The callback URL must be **HTTPS on port 443**, on the host registered as the API user's `providerCallbackHost` (a hostname, not an IP address), or MoMo rejects the request with `INVALID_CALLBACK_URL_HOST`. The certificate must chain to a common public CA (for example Let's Encrypt, DigiCert, Sectigo, Google or Amazon), or delivery can fail.
+- Only path parameters are allowed in the callback URL, not query strings.
+
+So a callback only tells you "check this reference now". The status check decides.
+
+## Callback URL with a per-transaction token
+
+Make each callback URL unguessable by putting a token derived from the reference in the path:
+
+```ts
+import crypto from 'node:crypto';
+
+const SECRET = process.env.MOMO_CALLBACK_SECRET!; // random, server-side only
+const tokenFor = (referenceId: string) => crypto.createHmac('sha256', SECRET).update(referenceId).digest('hex');
+
+export const callbackUrl = (referenceId: string) =>
+  `https://pay.example.com/momo/callback/${referenceId}/${tokenFor(referenceId)}`;
+```
+
+## Callback handler (Express)
+
+```ts
+app.all('/momo/callback/:referenceId/:token', (req, res) => {
+  if (req.method !== 'PUT' && req.method !== 'POST') return res.sendStatus(405);
+  const { referenceId, token } = req.params;
+  const expected = tokenFor(referenceId);
+  const valid = token.length === expected.length && crypto.timingSafeEqual(Buffer.from(token), Buffer.from(expected));
+  if (!valid) return res.sendStatus(404);
+
+  res.sendStatus(200); // respond first; MoMo won't retry, but it shouldn't wait on you either
+  queue.add('momo-settle', { referenceId }); // settle from a status check, never from req.body
+});
+```
+
+## Settling a payment
+
+One function settles a payment, and both the callback job and the poller call it:
+
+```ts
+export async function settle(referenceId: string) {
+  const payment = await db.payments.findByReference(referenceId);
+  if (!payment || payment.status !== 'PENDING') return; // unknown, or already final
+
+  const res = await fetch(`${MOMO}/collection/v1_0/requesttopay/${referenceId}`, {
+    headers: {
+      authorization: `Bearer ${await collectionToken()}`,
+      'x-target-environment': ENV,
+      'ocp-apim-subscription-key': KEY,
+    },
+  });
+  if (!res.ok) throw new Error(`status check failed: ${res.status}`); // the poller will retry
+  const s = await res.json();
+
+  if (s.status === 'PENDING') return;
+  const matches = s.currency === payment.currency && toMinor(s.amount, s.currency) === payment.amountMinor;
+  if (s.status === 'SUCCESSFUL' && matches) {
+    // Guarded update: only one caller wins, so fulfilment happens once.
+    const won = await db.payments.update({ referenceId, status: 'PENDING' }, { status: 'SUCCESSFUL', financialTransactionId: s.financialTransactionId });
+    if (won) await fulfilOrder(payment.orderId);
+  } else {
+    await db.payments.update({ referenceId, status: 'PENDING' }, { status: 'FAILED', reason: s.reason?.code ?? (matches ? 'UNKNOWN' : 'AMOUNT_MISMATCH') });
+  }
+}
+```
+
+An amount or currency mismatch on a `SUCCESSFUL` payment is not a normal failure: flag it for a person to review rather than refunding or fulfilling automatically.
+
+## Polling fallback
+
+Run a background job for payments still PENDING:
+
+- First check about 10 seconds after the 202, then back off (for example 10s, 20s, 40s, 60s, then every 60s).
+- The customer has about 5 minutes to approve. After about 10 minutes, keep checking at a slower rate (every 15 minutes) for a few hours rather than marking the payment failed straight away, because MoMo may still settle it.
+- Never create a new request to pay for the same attempt while one is PENDING.
+- The client's "Check status" button should call `settle` (rate-limited), not MoMo directly.
+
+## Tests
+
+- A callback with a wrong token returns 404 and settles nothing.
+- A callback whose body says SUCCESSFUL while the status check says FAILED results in FAILED.
+- The same callback delivered twice, plus a poll at the same moment, fulfils once.
+- No callback at all: the poller settles the payment.

package/skills/mtn-momo-integration/references/sandbox-and-go-live.md

@@ -0,0 +1,51 @@
+# Sandbox setup, test numbers and going live
+
+Read this when setting up a sandbox, writing tests, or preparing for production.
+
+## Create a sandbox API user and key
+
+1. Sign up at momodeveloper.mtn.com and subscribe to the product you need (Collection, Disbursement or Remittance). Copy its **primary key** from your profile.
+2. Run the setup script (`<skill-dir>` is the folder holding this skill's SKILL.md), with the subscription key in the environment and your callback host (the hostname that will receive callbacks; it must be a hostname you control, served over HTTPS):
+
+   ```
+   MOMO_SUBSCRIPTION_KEY=... node <skill-dir>/scripts/sandbox-setup.js --callback-host pay.example.com
+   ```
+
+   It creates an API user (`POST /v1_0/apiuser` with a new UUID), generates its API key (`POST /v1_0/apiuser/{id}/apikey`), checks that the pair can get a Collection token, and prints `MOMO_API_USER` and `MOMO_API_KEY` lines for your `.env`. Pass `--product disbursement` or `--product remittance` to check the token against another product, using that product's subscription key.
+3. Store the API key immediately. MoMo can't show it again; if it's lost, run the script again for a new user.
+
+The sandbox only accepts target environment `sandbox` and currency `EUR`.
+
+## Sandbox test numbers
+
+For request to pay (and deposit and request to withdraw), the payer's MSISDN decides the result. Any other number succeeds.
+
+| MSISDN | Result |
+|---|---|
+| `46733123450` | Failed |
+| `46733123451` | Rejected |
+| `46733123452` | Expired |
+| `46733123453` | Ongoing (stays PENDING) |
+| `46733123454` | Delayed |
+| `46733123455` | Not found |
+| `46733123456` | Payee not allowed to receive |
+| `46733123457` | Not allowed |
+| `46733123458` | Not allowed target environment |
+| `46733123459` | Invalid callback URL host |
+| `46733123460` | Invalid currency |
+| `46733123461` | Internal processing error |
+| `46733123462` | Service unavailable |
+| `46733123463` | Could not perform transaction |
+
+For the account-holder `active` check, `46733123450` is not found, `…451` not active, `…452` not allowed, `…453` not allowed target environment, `…454` internal processing error and `…455` service unavailable. Refund outcomes are selected by the refund amount (1 to 13); see MTN's sandbox use cases page.
+
+Use `46733123453` (Ongoing) and a stopped callback endpoint to test that polling settles a payment.
+
+## Going live
+
+- Complete MTN's go-live process for your market. Production API users and keys are created in that market's partner portal; sandbox users don't work there.
+- Switch the base URL, target environment (for example `mtnghana`) and currency (for example `GHS`) together, from configuration, not code.
+- Register your production callback host in the partner portal and make sure the certificate chains to a common public CA.
+- For Disbursement, get your server's outbound IP addresses whitelisted, or payouts fail with `403`.
+- Confirm the amount format your market accepts (whole units or decimals) with a small real payment.
+- Keep sandbox and production credentials in separate secret stores so one can't be used for the other.

package/skills/mtn-momo-integration/scripts/sandbox-setup.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+'use strict';
+
+// Creates an MTN MoMo sandbox API user and API key, then checks they can get an access token.
+// Sandbox only: production API users come from MTN's partner portal.
+//
+//   MOMO_SUBSCRIPTION_KEY=<product primary key> node sandbox-setup.js --callback-host pay.example.com [--product collection]
+//
+// Prints MOMO_API_USER / MOMO_API_KEY lines for your .env. The subscription key is never printed.
+
+const crypto = require('crypto');
+
+const SANDBOX = 'https://sandbox.momodeveloper.mtn.com';
+const PRODUCTS = ['collection', 'disbursement', 'remittance'];
+
+function parseArgs(argv) {
+  const opts = { product: 'collection' };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--callback-host') opts.callbackHost = argv[++i];
+    else if (argv[i] === '--product') opts.product = argv[++i];
+    else throw new Error(`unknown argument ${argv[i]}`);
+  }
+  if (!opts.callbackHost) throw new Error('--callback-host is required (a hostname such as pay.example.com)');
+  // MoMo matches callback URLs against this host, and rejects IPs: a bare hostname only.
+  if (!/^(?=.{1,253}$)([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/i.test(opts.callbackHost)) {
+    throw new Error(`--callback-host must be a bare hostname like pay.example.com, not "${opts.callbackHost}"`);
+  }
+  if (!PRODUCTS.includes(opts.product)) throw new Error(`--product must be one of ${PRODUCTS.join(', ')}`);
+  return opts;
+}
+
+async function call(fetchImpl, url, init, expected) {
+  const res = await fetchImpl(url, init);
+  const text = await res.text();
+  if (res.status !== expected) throw new Error(`${init.method} ${url.replace(SANDBOX, '')} returned ${res.status}: ${text.slice(0, 300) || '(empty body)'}`);
+  return text ? JSON.parse(text) : null;
+}
+
+async function setup({ subscriptionKey, callbackHost, product = 'collection', fetchImpl = fetch, uuid = crypto.randomUUID }) {
+  if (!subscriptionKey) throw new Error('set MOMO_SUBSCRIPTION_KEY to the primary key of the product you subscribed to');
+  const apiUser = uuid();
+  const key = { 'ocp-apim-subscription-key': subscriptionKey };
+
+  await call(fetchImpl, `${SANDBOX}/v1_0/apiuser`, {
+    method: 'POST',
+    headers: { ...key, 'x-reference-id': apiUser, 'content-type': 'application/json' },
+    body: JSON.stringify({ providerCallbackHost: callbackHost }),
+  }, 201);
+
+  const { apiKey } = await call(fetchImpl, `${SANDBOX}/v1_0/apiuser/${apiUser}/apikey`, { method: 'POST', headers: key }, 201);
+
+  // No body on the token call: MoMo rejects one with 400.
+  const basic = Buffer.from(`${apiUser}:${apiKey}`).toString('base64');
+  const token = await call(fetchImpl, `${SANDBOX}/${product}/token/`, { method: 'POST', headers: { ...key, authorization: `Basic ${basic}` } }, 200);
+  if (!token || !token.access_token) throw new Error('token call succeeded but returned no access_token');
+
+  return { apiUser, apiKey, expiresIn: token.expires_in };
+}
+
+async function main(argv, env = process.env) {
+  try {
+    const opts = parseArgs(argv);
+    const r = await setup({ subscriptionKey: env.MOMO_SUBSCRIPTION_KEY, ...opts });
+    console.log(`# MoMo sandbox API user for ${opts.callbackHost} (token check against ${opts.product} passed${r.expiresIn ? `, expires_in ${r.expiresIn}s` : ''})`);
+    console.log('# Store these now: MoMo cannot show this API key again.');
+    console.log(`MOMO_BASE_URL=${SANDBOX}`);
+    console.log('MOMO_TARGET_ENVIRONMENT=sandbox');
+    console.log(`MOMO_API_USER=${r.apiUser}`);
+    console.log(`MOMO_API_KEY=${r.apiKey}`);
+    return 0;
+  } catch (e) {
+    console.error(`sandbox-setup: ${e.message}`);
+    return 1;
+  }
+}
+
+if (require.main === module) main(process.argv.slice(2)).then((code) => (process.exitCode = code));
+
+module.exports = { parseArgs, setup, main };

package/skills/mysql-patterns/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: mysql-patterns
+description: MySQL and MariaDB on InnoDB, covering clustered primary keys and secondary index design, reading EXPLAIN and EXPLAIN ANALYZE output, utf8mb4 character sets and collations, REPEATABLE READ with gap and next-key locks, deadlock diagnosis, online DDL algorithms, and stale reads from lagging replicas. Use when creating or tuning MySQL or MariaDB tables, a MySQL query is slow, emoji or accented text is mangled, InnoDB lock waits or deadlocks appear, or reads from a replica return outdated data.
+license: MIT
+compatibility: Any Agent Skills host. Running queries needs the mysql or mariadb client and a reachable server; never point it at production without the user's say-so.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: data
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "mysql"
+  kete-loom/owner: "Kete-org"
+---
+
+# MySQL and MariaDB patterns
+
+InnoDB stores each table as a btree ordered by its primary key, so key choice drives everything else. Design for that, check every query with `EXPLAIN`, and assume replicas are behind. For step-by-step live schema changes use the `database-migrations` skill; for PostgreSQL use `postgres-patterns`.
+
+## 0. Before you start
+
+1. Identify the server: `SELECT VERSION();`. MySQL and MariaDB have diverged (optimizer, JSON, defaults, replication syntax). Check that product's docs for its version before giving version-specific advice.
+2. Check the engine: `SHOW TABLE STATUS WHERE Name = 't';`. Everything here assumes InnoDB. If you find MyISAM, tell the user: it has no transactions or row locks.
+3. Ask which environment you may query. `EXPLAIN ANALYZE` **executes** the statement.
+
+## 1. Schema rules for InnoDB
+
+- Primary key: short and monotonic, usually `BIGINT UNSIGNED AUTO_INCREMENT`. Every secondary index stores the primary key, so a wide PK makes every index wide. Random UUID v4 PKs scatter inserts across pages; if you need UUIDs, store them as `BINARY(16)` and prefer a time-ordered variant.
+- Always declare a primary key. Without one InnoDB invents a hidden one you can't use, and row-based replication of updates gets slow.
+- Money: `DECIMAL(p, s)` or integer minor units, never `FLOAT`/`DOUBLE`.
+- Time: `DATETIME` for business dates you store in UTC; `TIMESTAMP` converts through the session time zone and has a 2038 upper limit. Pick one convention and set the connection time zone explicitly.
+- Booleans are `TINYINT(1)`; enumerations a lookup table or `ENUM` only if the set truly never changes.
+- Turn on strict mode (`sql_mode` containing `STRICT_TRANS_TABLES`), so bad data errors instead of being silently truncated. Check the server's current value before assuming.
+- Declare foreign keys: InnoDB creates an index on the FK column if none exists, and enforces the reference.
+
+## 2. Character sets and collations
+
+1. Use `utf8mb4` everywhere: server, database, table, column **and** connection. `utf8`/`utf8mb3` stores at most 3 bytes per character, so emoji and some CJK characters fail or turn into `?`.
+2. Check all layers:
+   ```sql
+   SHOW VARIABLES LIKE 'character_set_%';
+   SHOW VARIABLES LIKE 'collation_%';
+   SHOW CREATE TABLE t;
+   ```
+   The driver must also connect with `utf8mb4` (connection option `charset=utf8mb4` or the driver's equivalent).
+3. Collation decides equality and sorting: `_ci` is case-insensitive, `_as`/`_ai` accent sensitive or insensitive, `_bin` byte-exact. A unique index on a `_ci` column rejects `Bob` when `bob` exists. Use a `_bin` or `_cs` collation where case matters (tokens, codes).
+4. Joining columns with different charsets or collations disables index use on one side and can raise `Illegal mix of collations`. Make them match.
+5. Converting a table (`ALTER TABLE t CONVERT TO CHARACTER SET utf8mb4 COLLATE ...`) rebuilds it and can lengthen index keys. Plan it as a migration, not a quick fix.
+
+## 3. Index design
+
+1. Composite index order: equality columns first, then one range or sort column. `(tenant_id, status, created_at)` serves `WHERE tenant_id = ? AND status = ? ORDER BY created_at`.
+2. Leftmost prefix rule: an index on `(a, b, c)` helps queries on `a`, `a, b` and `a, b, c`, not `b` alone.
+3. A covering index (all selected columns in the index) shows `Using index` in `EXPLAIN` and skips the table lookup.
+4. Don't index low-cardinality columns alone (`is_active`). Put them inside a composite after a selective column.
+5. Long strings: prefix indexes (`col(32)`) save space but cannot cover a query or serve `ORDER BY` fully.
+6. Remove duplicates: `(a)` is redundant when `(a, b)` exists. `sys.schema_redundant_indexes` and `sys.schema_unused_indexes` list candidates on MySQL; confirm across all replicas before dropping.
+
+## 4. Read a plan
+
+Run `EXPLAIN <query>` (or `EXPLAIN FORMAT=TREE`, and `EXPLAIN ANALYZE` on servers that support it, on a copy). Key columns and red flags: `references/explain.md`.
+
+Quick rules: `type = ALL` on a big table, `rows` far above the result size, `Using filesort` or `Using temporary` on a hot query, and `key = NULL` when you expected an index all need a fix. Common causes: a function or implicit cast on the indexed column, a leading `%` in `LIKE`, a charset mismatch in a join, or an `OR` across different columns.
+
+After any change, re-run the same `EXPLAIN` and the query itself, and report both.
+
+## 5. Transactions and locking
+
+- Default isolation is `REPEATABLE READ`. Plain `SELECT` reads a consistent snapshot; locking reads (`SELECT ... FOR UPDATE`, `FOR SHARE`), `UPDATE` and `DELETE` see the latest committed rows and take **next-key locks** (row plus the gap before it).
+- An `UPDATE` or `DELETE` whose `WHERE` isn't served by an index locks every row it scans, which can be the whole table. Index the predicate of every write statement.
+- Gap locks make "check if exists, then insert" deadlock under load. Use a unique key with `INSERT ... ON DUPLICATE KEY UPDATE`, or `INSERT IGNORE` only when silently dropping the row is truly fine.
+- Job queues: `SELECT ... FOR UPDATE SKIP LOCKED` (MySQL 8.0+, MariaDB 10.6+).
+- Deadlocks are normal under concurrency: the app must catch error 1213 and retry the transaction. Lock wait timeouts are error 1205 (`innodb_lock_wait_timeout`).
+- Diagnose with `SHOW ENGINE INNODB STATUS\G` (section `LATEST DETECTED DEADLOCK`) and, on MySQL 8, `performance_schema.data_locks` and `sys.innodb_lock_waits`.
+- Keep transactions short. Autocommit off in a driver plus a forgotten commit holds locks and undo history indefinitely.
+
+## 6. Replication lag
+
+- Replicas apply changes after the source commits. Lag can be seconds or more during big writes or DDL.
+- Read-your-writes: after a user writes, read their data from the source (for a short window, or per session), not a replica.
+- Never use a replica read to decide a write (balance checks, uniqueness, "already processed?").
+- One huge `UPDATE`/`DELETE` replicates as one huge event and stalls replicas. Batch it (see `database-migrations`).
+- Measure lag with `SHOW REPLICA STATUS\G` (`SHOW SLAVE STATUS` on older servers) or a heartbeat table such as `pt-heartbeat`; `Seconds_Behind_Source` (`Seconds_Behind_Master` on older servers and MariaDB) is `NULL` when a replication thread is stopped and only measures against the relay log, so it can read 0 while the I/O thread is behind.
+
+## 7. Online schema changes
+
+Prefer `ALTER TABLE ..., ALGORITHM=INSTANT` or `ALGORITHM=INPLACE, LOCK=NONE` and let the server refuse if it can't. Stating the algorithm makes the statement fail instead of quietly copying the table. Details, plus when to reach for `gh-ost` or `pt-online-schema-change`: `references/online-ddl.md`.
+
+## Never
+
+- Never run DDL, `OPTIMIZE TABLE` or bulk writes on production without the user's explicit go-ahead.
+- Never "fix" charset problems by changing only the column; check connection and client too.
+- Never build SQL by concatenating user input; use placeholders.
+- Never disable `foreign_key_checks` or `unique_checks` outside a controlled bulk load you then verify.
+
+## Report back
+
+For tuning: the query, the `EXPLAIN` before and after (key, type, rows, Extra), the change, and the timing difference. For design: the `CREATE TABLE`, the charset and collation chosen, and one line per index naming the query it serves.

package/skills/mysql-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Emoji are being saved as ???? in our MySQL database, what charset settings do I need?",
+    "EXPLAIN shows type ALL and Using filesort on this MySQL query, how should I index it?",
+    "We get Deadlock found when trying to get lock (1213) on InnoDB during concurrent inserts",
+    "Users don't see their own updates right after saving because we read from a MySQL replica",
+    "Design the InnoDB tables for a MariaDB-backed booking system, what primary keys should I use?"
+  ],
+  "should_not_trigger": [
+    "Tune this PostgreSQL query, the EXPLAIN ANALYZE shows a nested loop with millions of rows",
+    "Write a Rails migration that drops a column safely across two deploys",
+    "Check this PR for N+1 queries and dangerous migrations before I merge",
+    "How do I configure PgBouncer transaction pooling for a Postgres cluster?",
+    "Set up a Redis cache with expiry for session data"
+  ]
+}

package/skills/mysql-patterns/references/explain.md

@@ -0,0 +1,34 @@
+# Reading MySQL EXPLAIN
+
+## Traditional EXPLAIN columns
+
+| Column | Meaning | Watch for |
+|---|---|---|
+| `type` | access method, best to worst: `system`, `const`, `eq_ref`, `ref`, `range`, `index`, `ALL` | `ALL` (full table scan) or `index` (full index scan) on a large table |
+| `possible_keys` | indexes the optimizer considered | `NULL`: no usable index for this predicate |
+| `key` | index chosen | `NULL` while `possible_keys` is set: optimizer judged the index not selective, or stats are stale |
+| `key_len` | bytes of the index key used | shorter than expected: only the leftmost columns are used; a range stopped the rest |
+| `rows` | estimated rows examined | far larger than the result |
+| `filtered` | % of rows kept after the condition | low % with high `rows`: index doesn't match the filter |
+| `Extra` | notes | `Using filesort`, `Using temporary`, `Using where` on a scan; `Using index` is good (covering) |
+
+## EXPLAIN ANALYZE and FORMAT=TREE
+
+`EXPLAIN FORMAT=TREE` shows the iterator tree. `EXPLAIN ANALYZE` runs the query and adds `actual time=first..last rows=N loops=L`. Compare estimated rows with actual rows; times are per loop. MariaDB's equivalent is `ANALYZE <statement>` (and `ANALYZE FORMAT=JSON`). Check which your server supports.
+
+## Common fixes
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `key = NULL`, `WHERE DATE(created_at) = ?` | function on column | range: `created_at >= ? AND created_at < ?` |
+| `key = NULL`, `WHERE phone = 233201234567` on a `VARCHAR` | implicit numeric cast | pass a string |
+| join not using index | charset or collation mismatch between columns | align both columns |
+| `Using filesort` with `ORDER BY created_at LIMIT 20` | index doesn't end in the sort column | composite `(filter_cols..., created_at)` |
+| `Using temporary` for `GROUP BY` | no index in group order | index on group columns, or accept for rare queries |
+| estimate way off | stale stats | `ANALYZE TABLE t;` (cheap on InnoDB) |
+| deep pagination slow | `OFFSET` reads and discards rows | keyset: `WHERE id > ? ORDER BY id LIMIT 20` |
+
+## Finding slow queries
+
+- Slow query log: `slow_query_log = ON`, `long_query_time = 1`, then summarise with `pt-query-digest`.
+- MySQL 8 `sys.statements_with_runtimes_in_95th_percentile` and `performance_schema.events_statements_summary_by_digest` rank statements by total time.