@gemmein/mcp 0.3.0 → 0.5.0

package/dist/index.js

@@ -291,7 +291,7 @@ const TOOLS = [
     },
     {
         name: "explain_relay",
-        description: "Call while WRITING or FIXING gemmein/relays/<name>.json — before `gemmein sync` carries it to the cloud. A relay is one trigger (receiver: a provider's webhook; schedule: a clock; data_change: a record changing) and up to ten actions in Gemmein's own verbs (write_record, grant_access, revoke_access, email_person, call_url) — route, map, authorise, never compute. Pass the definition JSON; the answer is the English sentence the dashboard shows (\"When gocardless-paid receives an event where event_type is confirmed → grant Pro, email the person, call https://…\") or the ONE refusal sentence the cloud would answer, naming the field and the fix. Offline and read-only: nothing is created. Two checks run only in the cloud and are stated in the answer (the API's own hosts; the address's resolved network at call time).",
+        description: "Call while WRITING or FIXING gemmein/relays/<name>.json — before `gemmein sync` carries it to the cloud. A relay is one trigger (receiver: a provider's webhook; schedule: a clock; data_change: a record changing) and up to ten actions in Gemmein's own verbs (write_record, grant_access, revoke_access, grant_credits, email_person, call_url) — route, map, authorise, never compute. Pass the definition JSON; the answer is the English sentence the dashboard shows (\"When gocardless-paid receives an event where event_type is confirmed → grant Pro, email the person, call https://…\") or the ONE refusal sentence the cloud would answer, naming the field and the fix. Offline and read-only: nothing is created. Two checks run only in the cloud and are stated in the answer (the API's own hosts; the address's resolved network at call time).",
         annotations: { title: "Explain relay (validate offline)", readOnlyHint: true },
         inputSchema: {
             type: "object",

package/dist/relays.js

@@ -34,9 +34,13 @@ const DURATION_RE = /^(\d{1,4})([hdw])$/;
 const MAX_MAP_ENTRIES = 20;
 const MAX_WHEN_ENTRIES = 20;
 const RECORD_KINDS = ["created", "updated", "deleted"];
-const ACTION_TYPES = ["write_record", "grant_access", "revoke_access", "email_person", "call_url"];
+const ACTION_TYPES = ["write_record", "grant_access", "revoke_access", "email_person", "call_url", "grant_credits", "fulfil_product", "refund_product"];
+/** W9.5 — mirrors apps/api/src/relays/schema.ts. */
+const PRODUCT_NAME_RE = /^[a-z0-9][a-z0-9 _.-]{0,39}$/i;
+// W9.3: a relay may grant a person up to 10,000 credits per action.
+const MAX_RELAY_CREDITS = 10000;
 const SCHEMES = ["hmac_sha256_header", "stripe", "svix", "shared_token"];
-const PERSON_ACTIONS = new Set(["grant_access", "revoke_access", "email_person"]);
+const PERSON_ACTIONS = new Set(["grant_access", "grant_credits", "revoke_access", "email_person", "fulfil_product", "refund_product"]);
 const ENTITLEMENT_KEY = /^access:[a-z0-9][a-z0-9._-]{0,63}$/;
 const RESERVED_FIELD_NAMES = new Set([
     "id", "appId", "app_id", "environmentId", "environment_id", "userId", "user_id", "ownerId", "ownerUserId", "owner_user_id",
@@ -296,6 +300,40 @@ function validateAction(raw, index, triggerKind) {
             const reason = optionalString(a, "reason", what, 200);
             return { type: "grant_access", entitlement, ...(expiresAt !== undefined ? { expiresAt } : {}), ...(reason !== undefined ? { reason } : {}) };
         }
+        case "grant_credits": {
+            // W9.3 — mirrors apps/api/src/relays/schema.ts (the lockstep test
+            // holds them equal): a whole number of credits, 1..10,000, and an
+            // optional reason the owner reads in the ledger.
+            rejectUnknownKeys(a, ["type", "amount", "reason"], what);
+            const amount = a.amount;
+            if (typeof amount !== "number" || !Number.isInteger(amount) || amount < 1 || amount > MAX_RELAY_CREDITS) {
+                refuse(`${what}.amount must be a whole number from 1 to ${MAX_RELAY_CREDITS.toLocaleString("en-GB")} credits`);
+            }
+            const reason = optionalString(a, "reason", what, 200);
+            return { type: "grant_credits", amount, ...(reason !== undefined ? { reason } : {}) };
+        }
+        case "fulfil_product":
+        case "refund_product": {
+            // W9.5 — mirrors apps/api/src/relays/schema.ts (the lockstep test holds
+            // them equal): the product is a NAME, never a template; the payment
+            // reference may be a template, because it comes out of the event.
+            rejectUnknownKeys(a, ["type", "product", "ref"], what);
+            const product = a.product;
+            if (typeof product !== "string" || !PRODUCT_NAME_RE.test(product.trim())) {
+                refuse(`${what}.product must be a product name (1-40 letters, numbers, spaces, or -_.)`);
+            }
+            const rawRef = a.ref;
+            // A written ref that is empty is not the absent ref: absent means "make
+            // one from the event id", and a blank string would silently take that
+            // road instead of the one the founder wrote. Refused here.
+            if (rawRef !== undefined &&
+                rawRef !== null &&
+                (typeof rawRef !== "string" || rawRef.trim() === "" || rawRef.length > 200)) {
+                refuse(`${what}.ref must be text of at most 200 characters (templates allowed)`);
+            }
+            const ref = typeof rawRef === "string" ? rawRef : undefined;
+            return { type: a.type, product: product.trim(), ...(ref !== undefined ? { ref } : {}) };
+        }
         case "revoke_access": {
             rejectUnknownKeys(a, ["type", "entitlement"], what);
             return { type: "revoke_access", entitlement: validateEntitlementInput(a.entitlement, what) };
@@ -385,6 +423,9 @@ export function describeRelay(def) {
         switch (a.type) {
             case "write_record": return `write a ${a.collection} record${a.to === "person" ? " for the person" : ""}`;
             case "grant_access": return `grant ${entitlementWords(a.entitlement)}`;
+            case "grant_credits": return `grant ${a.amount} credit${a.amount === 1 ? "" : "s"}`;
+            case "fulfil_product": return `fulfil ${a.product}`;
+            case "refund_product": return `refund ${a.product}`;
             case "revoke_access": return `revoke ${entitlementWords(a.entitlement)}`;
             case "email_person": return "email the person";
             case "call_url": return `call ${a.url}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemmein/mcp",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "mcpName": "com.gemmein/mcp",
   "description": "Gemmein MCP server \u2014 gives coding agents the Gemmein guide, API reference, rule/error explainers, and a live integration check (reaffirm) as tools. Read-only: it never creates, edits, or deletes anything.",
   "license": "MIT",
@@ -34,7 +34,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@gemmein/sdk": "^0.6.0",
+    "@gemmein/sdk": "^0.8.0",
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "author": "Gemmein Limited",