@ingenx-io/valets-schema-mcp-server 0.1.3 → 0.1.4

package/data/static/schemas.json

@@ -1,8 +1,300 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "description": "@valets/schema \u2014 consolidated schema bundle",
-  "generated": "2026-04-06T19:27:48.749605+00:00",
+  "generated": "2026-04-18T21:21:09.696794+00:00",
   "schemas": {
+    "allowed-user": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "readOnly": true,
+          "description": "(Read-only) Firestore document ID = contact identifier (email or E.164 phone), URL-escaped.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "companyId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Company document ID."
+        },
+        "siteId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Site document ID (D40 sub-tenant scope)."
+        },
+        "contact": {
+          "type": "string",
+          "description": "Email or E.164 phone number. Canonical identifier for this user within the site."
+        },
+        "tier": {
+          "type": "string",
+          "description": "Access tier. Free string per site (ING-304 open question \u2014 tier values are site-specific today)."
+        },
+        "amount": {
+          "type": "number",
+          "description": "Amount paid. Generalized from amount_xof per D40 decision."
+        },
+        "currency": {
+          "default": "XOF",
+          "description": "Currency code (ISO 4217). Defaults to XOF for legacy SR-Single parity.",
+          "type": "string"
+        },
+        "transactionId": {
+          "type": "string",
+          "description": "Payment provider transaction ID (e.g. Wave)."
+        },
+        "paidAt": {
+          "$ref": "#/definitions/firestore-timestamp",
+          "description": "RFC3339Nano UTC when payment was completed."
+        }
+      },
+      "required": [
+        "companyId",
+        "siteId",
+        "contact",
+        "tier",
+        "amount",
+        "currency",
+        "transactionId",
+        "paidAt"
+      ],
+      "additionalProperties": false,
+      "description": "AllowedUser model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/allowed_users/{contactId}. Authoritative paid-access allowlist. Upsert semantics \u2014 tier upgrades overwrite. Source of truth for access checks and referral code resolution.",
+      "example": {
+        "id": null,
+        "companyId": "comp_xyz789",
+        "siteId": "sit_ref123",
+        "contact": "contact",
+        "tier": "Gold",
+        "amount": 45000,
+        "currency": "XOF",
+        "transactionId": "tra_ref123",
+        "paidAt": "pai_ref123"
+      }
+    },
+    "analytics-event": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "readOnly": true,
+          "description": "(Read-only) Firestore document ID. Equal to eventId.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "companyId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Company document ID."
+        },
+        "siteId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Site document ID (D40 sub-tenant scope)."
+        },
+        "eventId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) Client-generated UUID. Matches document ID."
+        },
+        "eventName": {
+          "type": "string",
+          "description": "Event name. Free string; canonical vocabulary is encouraged (see CANONICAL_ANALYTICS_EVENT_NAMES)."
+        },
+        "timestamp": {
+          "type": "string",
+          "description": "Client-side ISO 8601 \u2014 \"when it happened on device\". Can diverge from serverTimestamp for queued offline events."
+        },
+        "serverTimestamp": {
+          "$ref": "#/definitions/firestore-timestamp",
+          "description": "(Read-only) Firestore serverTimestamp() \u2014 authoritative for ordering.",
+          "readOnly": true
+        },
+        "sessionId": {
+          "type": "string",
+          "description": "30-minute rolling session identifier."
+        },
+        "userId": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Stable user ID if identified; explicitly null (not omitted) for anonymous sessions \u2014 simplifies querying."
+        },
+        "properties": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {},
+          "description": "Free-form event-specific payload. Contract is at the event-name level. PII posture: follow-up issue pending."
+        },
+        "context": {
+          "type": "object",
+          "properties": {
+            "url": {
+              "description": "Full URL at event time.",
+              "type": "string"
+            },
+            "origin": {
+              "description": "Protocol + host.",
+              "type": "string"
+            },
+            "hostname": {
+              "description": "Hostname only \u2014 useful for deployment identification.",
+              "type": "string"
+            },
+            "page": {
+              "description": "Current route/pathname.",
+              "type": "string"
+            },
+            "title": {
+              "description": "Page title.",
+              "type": "string"
+            },
+            "referrer": {
+              "description": "Referrer URL.",
+              "type": "string"
+            },
+            "deviceType": {
+              "type": "string",
+              "enum": [
+                "mobile",
+                "tablet",
+                "desktop"
+              ]
+            },
+            "platform": {
+              "description": "OS/platform string.",
+              "type": "string"
+            },
+            "screenWidth": {
+              "description": "Viewport width (flattened from screen.width).",
+              "type": "integer",
+              "minimum": -9007199254740991,
+              "maximum": 9007199254740991
+            },
+            "screenHeight": {
+              "description": "Viewport height (flattened from screen.height).",
+              "type": "integer",
+              "minimum": -9007199254740991,
+              "maximum": 9007199254740991
+            },
+            "appVersion": {
+              "description": "Consuming app version.",
+              "type": "string"
+            },
+            "online": {
+              "description": "Connectivity state at event time.",
+              "type": "boolean"
+            },
+            "locale": {
+              "description": "User locale.",
+              "type": "string"
+            },
+            "timezone": {
+              "description": "IANA timezone.",
+              "type": "string"
+            },
+            "utm": {
+              "description": "UTM parameters; null when not a campaign-landed session.",
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "source": {
+                      "type": "string"
+                    },
+                    "medium": {
+                      "type": "string"
+                    },
+                    "campaign": {
+                      "type": "string"
+                    },
+                    "term": {
+                      "type": "string"
+                    },
+                    "content": {
+                      "type": "string"
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          },
+          "additionalProperties": false,
+          "description": "Environment context at event time (nested per D40)."
+        },
+        "userTraits": {
+          "description": "Optional \u2014 included only when includeUserTraits: true on the write. PII posture: follow-up issue pending.",
+          "type": [
+            "object",
+            "null"
+          ],
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {}
+        }
+      },
+      "required": [
+        "companyId",
+        "siteId",
+        "eventId",
+        "eventName",
+        "timestamp",
+        "serverTimestamp",
+        "sessionId",
+        "userId",
+        "properties",
+        "context"
+      ],
+      "additionalProperties": false,
+      "description": "AnalyticsEvent model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_events/{eventId}. Append-only, immutable product/behavior event stream. Event names are free strings; canonical vocabulary in CANONICAL_ANALYTICS_EVENT_NAMES.",
+      "example": {
+        "id": null,
+        "companyId": "comp_xyz789",
+        "siteId": "sit_ref123",
+        "eventId": "eve_ref123",
+        "eventName": "eventName",
+        "timestamp": "timestamp",
+        "serverTimestamp": "serverTimestamp",
+        "sessionId": "ses_ref123",
+        "userId": "use_ref123",
+        "properties": {},
+        "context": {},
+        "userTraits": null
+      }
+    },
+    "attention-status": {
+      "type": "string",
+      "enum": [
+        "ACTIVE",
+        "STALE",
+        "ON_HOLD",
+        "ESCALATED"
+      ],
+      "description": "Operational attention status for Order and Booking (D39). Controls home-page queue assignment. Server-owned \u2014 set via triggers or callable fn only.",
+      "x-note": "ACTIVE = normal urgent queue (default). STALE = idle past threshold, moved to review queue \u2014 excluded from pendingOrdersCount. ON_HOLD = intentionally paused by manager via callable fn. ESCALATED = ignored past second threshold.",
+      "x-see": {
+        "decisions": [
+          "D39"
+        ]
+      },
+      "x-when": "Set by server automation or callable fn. Mobile and Dashboard read this field; never write it directly. ON_HOLD is the only human-initiated transition \u2014 goes through a dedicated callable function.",
+      "x-status": "proposed"
+    },
     "booking": {
       "type": "object",
       "properties": {
@@ -1961,6 +2253,122 @@
       ],
       "description": "Loyalty point transaction type (D07). SCREAMING_SNAKE past tense."
     },
+    "magic-link-request": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "readOnly": true,
+          "description": "(Read-only) Firestore document ID. 16-byte random hex.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "companyId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Company document ID."
+        },
+        "siteId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Site document ID (D40 sub-tenant scope)."
+        },
+        "email": {
+          "type": "string",
+          "description": "Populated if identifier is email; empty string if phone. Mutually exclusive with phone per document."
+        },
+        "phone": {
+          "type": "string",
+          "description": "Populated if identifier is E.164 format (starts with +); empty string if email."
+        },
+        "ip": {
+          "type": "string",
+          "description": "Client IP from X-Forwarded-For or RemoteAddr."
+        },
+        "allowed": {
+          "type": "boolean",
+          "description": "Whether the user passed the access control check."
+        },
+        "link": {
+          "type": "string",
+          "description": "Magic-link URL \u2014 non-empty only when DEV_MODE=true; empty in production (audit integrity)."
+        },
+        "tier": {
+          "type": "string",
+          "description": "Access tier selected by the user. Free string per site (ING-304 open question \u2014 tier values are site-specific today)."
+        },
+        "authStatusReason": {
+          "type": "string",
+          "description": "Outcome reason code: whitelist | allowed_users | payment_redirect | payment_complete | not_allowed | redirected_to_payment."
+        },
+        "referredBy": {
+          "type": "string",
+          "description": "Contact identifier of the referrer, resolved from submitted referral_code; empty if none."
+        },
+        "requestedAt": {
+          "$ref": "#/definitions/firestore-timestamp",
+          "description": "RFC3339Nano UTC at request time."
+        },
+        "verifyReason": {
+          "description": "Verify outcome reason: mirrors authStatusReason on success, or link_expired | link_invalid | not_allowed.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "verified": {
+          "description": "Whether the verify attempt succeeded.",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "verifiedAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "RFC3339Nano UTC at verify time."
+        }
+      },
+      "required": [
+        "companyId",
+        "siteId",
+        "email",
+        "phone",
+        "ip",
+        "allowed",
+        "link",
+        "tier",
+        "authStatusReason",
+        "referredBy",
+        "requestedAt"
+      ],
+      "additionalProperties": false,
+      "description": "MagicLinkRequest model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/magic_link_requests/{requestId}. Authentication audit log \u2014 every request is logged regardless of outcome. Two-stage write: Log() then LogVerify().",
+      "example": {
+        "id": null,
+        "companyId": "comp_xyz789",
+        "siteId": "sit_ref123",
+        "email": "amadou@example.com",
+        "phone": "+225 07 00 11 22",
+        "ip": "ip",
+        "allowed": true,
+        "link": "link",
+        "tier": "Gold",
+        "authStatusReason": "Customer request",
+        "referredBy": "referredBy",
+        "requestedAt": "requestedAt",
+        "verifyReason": null,
+        "verified": null,
+        "verifiedAt": "verifiedAt"
+      }
+    },
     "metrics-current": {
       "type": "object",
       "properties": {
@@ -3550,6 +3958,31 @@
       ],
       "description": "Payment lifecycle status (D01 amended). Used by Order, Sale/Purchase, Booking."
     },
+    "pending-issue": {
+      "type": "string",
+      "enum": [
+        "PAYMENT_PROOF_PENDING",
+        "PAYMENT_PROOF_REJECTED",
+        "AMOUNT_DISCREPANCY",
+        "RETURN_UNRESOLVED",
+        "OVERDUE_DELIVERY",
+        "SESSION_OVERDUE",
+        "PAYMENT_INCOMPLETE",
+        "CANCELLATION_REQUESTED",
+        "UNREFUNDED_CANCELLATION",
+        "UPCOMING_UNPAID",
+        "NO_SHOW_UNRESOLVED"
+      ],
+      "description": "Specific detected conditions on an Order or Booking requiring human action (D39). Stored as an array \u2014 multiple issues can be active simultaneously. Server-owned.",
+      "x-note": "Shared: PAYMENT_PROOF_PENDING (proof uploaded, awaiting review), PAYMENT_PROOF_REJECTED (proof rejected, needs resubmission), AMOUNT_DISCREPANCY (amountPaid does not reconcile with amount/paymentStatus). Order-only: RETURN_UNRESOLVED (return/exchange stuck), OVERDUE_DELIVERY (estimatedDeliveryDate past, not yet delivered). Booking-only: SESSION_OVERDUE (session date passed, status not updated), PAYMENT_INCOMPLETE (sessions completed but payment not recorded), CANCELLATION_REQUESTED (cancellation not actioned), UNREFUNDED_CANCELLATION (cancelled with amountPaid > 0 and no refund), UPCOMING_UNPAID (session within 48h, payment not recorded), NO_SHOW_UNRESOLVED (no-show without follow-up).",
+      "x-see": {
+        "decisions": [
+          "D39"
+        ]
+      },
+      "x-when": "Set and cleared by server automation or triggers. Never affects pendingOrdersCount or pendingBookingsCount \u2014 orthogonal to urgency. Multiple values can be active at once (stored as PendingIssue[] on Order/Booking).",
+      "x-status": "proposed"
+    },
     "return-status": {
       "type": "string",
       "enum": [
@@ -3688,6 +4121,83 @@
       ],
       "description": "Per-date/per-slot booking session status (D19). Dashboard is sole writer; Mobile is read-only."
     },
+    "site-payment": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "readOnly": true,
+          "description": "(Read-only) Firestore document ID, auto-generated.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "companyId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Company document ID."
+        },
+        "siteId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Site document ID (D40 sub-tenant scope)."
+        },
+        "contact": {
+          "type": "string",
+          "description": "Email or E.164 phone number. Matches AllowedUser.contact."
+        },
+        "sessionId": {
+          "type": "string",
+          "description": "Payment provider checkout session ID (e.g. Wave). Usable for dedup across dual writes."
+        },
+        "transactionId": {
+          "type": "string",
+          "description": "Payment provider transaction ID."
+        },
+        "tier": {
+          "type": "string",
+          "description": "Access tier. Free string per site (ING-304 open question)."
+        },
+        "amount": {
+          "type": "number",
+          "description": "Amount paid. Generalized from amount_xof per D40 decision."
+        },
+        "currency": {
+          "default": "XOF",
+          "description": "Currency code (ISO 4217). Defaults to XOF for legacy SR-Single parity.",
+          "type": "string"
+        },
+        "paidAt": {
+          "$ref": "#/definitions/firestore-timestamp",
+          "description": "RFC3339Nano UTC when payment was completed."
+        }
+      },
+      "required": [
+        "companyId",
+        "siteId",
+        "contact",
+        "sessionId",
+        "transactionId",
+        "tier",
+        "amount",
+        "currency",
+        "paidAt"
+      ],
+      "additionalProperties": false,
+      "description": "SitePayment model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/payments/{paymentId}. Immutable append-only transaction ledger. Distinct from AllowedUser (access state) and CustomerPayment (D22 \u2014 customer-level billing).",
+      "example": {
+        "id": null,
+        "companyId": "comp_xyz789",
+        "siteId": "sit_ref123",
+        "contact": "contact",
+        "sessionId": "ses_ref123",
+        "transactionId": "tra_ref123",
+        "tier": "Gold",
+        "amount": 45000,
+        "currency": "XOF",
+        "paidAt": "pai_ref123"
+      }
+    },
     "ticket": {
       "type": "object",
       "properties": {
@@ -3846,24 +4356,6 @@
       ],
       "description": "Event ticket status (D32). VALID = active and unused."
     },
-    "attention-status": {
-      "type": "string",
-      "enum": [
-        "ACTIVE",
-        "STALE",
-        "ON_HOLD",
-        "ESCALATED"
-      ],
-      "description": "Operational attention status for Order and Booking (D39). Controls home-page queue assignment. Server-owned \u2014 set via triggers or callable fn only.",
-      "x-note": "ACTIVE = normal urgent queue (default). STALE = idle past threshold, moved to review queue \u2014 excluded from pendingOrdersCount. ON_HOLD = intentionally paused by manager via callable fn. ESCALATED = ignored past second threshold.",
-      "x-see": {
-        "decisions": [
-          "D39"
-        ]
-      },
-      "x-when": "Set by server automation or callable fn. Mobile and Dashboard read this field; never write it directly. ON_HOLD is the only human-initiated transition \u2014 goes through a dedicated callable function.",
-      "x-status": "proposed"
-    },
     "payment-summary": {
       "type": "object",
       "properties": {
@@ -4025,31 +4517,6 @@
       "additionalProperties": false,
       "description": "Aggregated payment totals by method for a given period. Collection: companies/{companyId}/paymentSummaries/{period}. Server-owned \u2014 all fields are set by Cloud Function triggers on Order.payments[] and CustomerPayment writes. Clients must never write to this collection.",
       "x-status": "proposed"
-    },
-    "pending-issue": {
-      "type": "string",
-      "enum": [
-        "PAYMENT_PROOF_PENDING",
-        "PAYMENT_PROOF_REJECTED",
-        "AMOUNT_DISCREPANCY",
-        "RETURN_UNRESOLVED",
-        "OVERDUE_DELIVERY",
-        "SESSION_OVERDUE",
-        "PAYMENT_INCOMPLETE",
-        "CANCELLATION_REQUESTED",
-        "UNREFUNDED_CANCELLATION",
-        "UPCOMING_UNPAID",
-        "NO_SHOW_UNRESOLVED"
-      ],
-      "description": "Specific detected conditions on an Order or Booking requiring human action (D39). Stored as an array \u2014 multiple issues can be active simultaneously. Server-owned.",
-      "x-note": "Shared: PAYMENT_PROOF_PENDING (proof uploaded, awaiting review), PAYMENT_PROOF_REJECTED (proof rejected, needs resubmission), AMOUNT_DISCREPANCY (amountPaid does not reconcile with amount/paymentStatus). Order-only: RETURN_UNRESOLVED (return/exchange stuck), OVERDUE_DELIVERY (estimatedDeliveryDate past, not yet delivered). Booking-only: SESSION_OVERDUE (session date passed, status not updated), PAYMENT_INCOMPLETE (sessions completed but payment not recorded), CANCELLATION_REQUESTED (cancellation not actioned), UNREFUNDED_CANCELLATION (cancelled with amountPaid > 0 and no refund), UPCOMING_UNPAID (session within 48h, payment not recorded), NO_SHOW_UNRESOLVED (no-show without follow-up).",
-      "x-see": {
-        "decisions": [
-          "D39"
-        ]
-      },
-      "x-when": "Set and cleared by server automation or triggers. Never affects pendingOrdersCount or pendingBookingsCount \u2014 orthogonal to urgency. Multiple values can be active at once (stored as PendingIssue[] on Order/Booking).",
-      "x-status": "proposed"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingenx-io/valets-schema-mcp-server",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "MCP server exposing @valets/schema documentation to AI agents",
   "type": "module",
   "main": "index.js",