@ingenx-io/valets-schema-mcp-server 0.1.1 → 0.1.2

package/data/docs/triggers/loyalty-automation.md

@@ -0,0 +1,123 @@
+---
+title: "Loyalty Automation Triggers"
+sidebar_label: "Loyalty Automation"
+sidebar_position: 1
+---
+
+# Loyalty Automation Triggers
+
+> **Decision**: D23 (locked) — Firebase owns loyalty point automation: award, expire, and validate server-side.
+> **Wave**: 3 — Server-Side Logic.
+> **Status**: Specified. Not yet implemented.
+
+These triggers run when loyalty transactions are written to Firestore. Their job is to keep `loyalty/status` counters consistent and set `pointsBalanceAfter` on each transaction.
+
+---
+
+## `onLoyaltyTransactionCreate`
+
+Fires when a new [`LoyaltyTransaction`](/models/loyalty-transaction) document is created.
+
+**Path**: `companies/{companyId}/customers/{customerId}/loyaltyTransactions/{transactionId}`
+**Event**: `onCreate`
+
+### Behavior
+
+1. Read the new `LoyaltyTransaction` document.
+2. **Atomically** update the `loyalty/status` document at `companies/{companyId}/customers/{customerId}/loyalty/status`:
+
+| Transaction type | `pointsBalance` | `totalPointsEarned` | `redeemedPoints` | `lastActivityDate` |
+|---|---|---|---|---|
+| `EARNED` | `+= pointsChange` | `+= pointsChange` | — | set to `changedAt` |
+| `BONUS` | `+= pointsChange` | `+= pointsChange` | — | set to `changedAt` |
+| `REDEEMED` | `-= pointsChange` (subtract abs value) | — | `+= pointsChange` | set to `changedAt` |
+| `ADJUSTED` | `+= pointsChange` (can be negative) | — | — | set to `changedAt` |
+| `EXPIRED` | `-= pointsChange` (subtract abs value) | — | — | set to `changedAt` |
+| `REFUND` | `+= pointsChange` | — | `-= pointsChange` | set to `changedAt` |
+
+3. Write `pointsBalanceAfter` back to the transaction document (the running balance **after** this operation).
+4. Create or initialise the `loyalty/status` document if it does not exist.
+
+### Inputs
+
+```typescript
+// onCreate event data
+interface LoyaltyTransactionCreateEvent {
+  data: LoyaltyTransaction;         // the new document
+  params: {
+    companyId: string;
+    customerId: string;
+    transactionId: string;
+  };
+}
+```
+
+### Outputs
+
+**Write 1** — Update `loyalty/status`:
+
+```typescript
+// Partial update applied to: companies/{companyId}/customers/{customerId}/loyalty/status
+{
+  pointsBalance: FieldValue.increment(delta),      // sign depends on transaction type
+  totalPointsEarned: FieldValue.increment(delta),  // only for EARNED and BONUS
+  redeemedPoints: FieldValue.increment(delta),     // only for REDEEMED; decremented for REFUND
+  lastActivityDate: FieldValue.serverTimestamp(),
+  updatedAt: FieldValue.serverTimestamp(),
+}
+```
+
+**Write 2** — Patch `pointsBalanceAfter` back on the transaction:
+
+```typescript
+// Patch applied to: companies/{companyId}/customers/{customerId}/loyaltyTransactions/{transactionId}
+{
+  pointsBalanceAfter: <computed new balance>,
+}
+```
+
+:::warning Race condition
+Both writes must be in a single **Firestore transaction** (not a batch). Using a transaction on the `loyalty/status` doc prevents two concurrent `onLoyaltyTransactionCreate` calls from producing an incorrect balance.
+:::
+
+:::note Welcome bonus
+A `BONUS` transaction with `reason: "welcome_bonus"` is created by the server when a customer first enrolls. The trigger handles it identically to `EARNED`.
+:::
+
+---
+
+## `onLoyaltyTransactionUpdate` (admin corrections only)
+
+**Path**: `companies/{companyId}/customers/{customerId}/loyaltyTransactions/{transactionId}`
+**Event**: `onUpdate`
+
+### Behavior
+
+LoyaltyTransaction documents are marked `immutable` — clients must not update them. This trigger exists only to detect accidental or admin-tool writes and **re-heal** the `loyalty/status` balance.
+
+1. Compute the delta between the old and new `pointsChange` values.
+2. Apply the delta to `loyalty/status.pointsBalance`.
+3. Log the correction to `_validation_issues` (D36 log-and-heal).
+
+:::info Scope
+Only `pointsChange` corrections trigger a re-heal. Status updates or annotation changes are ignored.
+:::
+
+---
+
+## Points Expiration (scheduled)
+
+D23 also requires server-side expiration of stale points. This is a **scheduled Cloud Function** (not a Firestore trigger).
+
+**Schedule**: Daily (configurable per company via `LoyaltyConfig.pointsExpirationDays`).
+
+### Behavior
+
+For each company with `loyaltyConfig.pointsExpirationDays` set:
+1. Query `loyaltyTransactions` where `type = EARNED` and `transactionDate` is older than `pointsExpirationDays`.
+2. For each expiring transaction, create a new `LoyaltyTransaction` with `type = EXPIRED` and `pointsChange = -(originalPointsChange)`.
+3. The `onLoyaltyTransactionCreate` trigger handles the balance update automatically.
+
+:::note
+Expiration creates a new EXPIRED transaction rather than mutating the original EARNED transaction. This preserves the immutable audit trail.
+:::