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

package/data/docs/models/customer-payment.md

@@ -0,0 +1,392 @@
+---
+title: "CustomerPayment"
+sidebar_label: "CustomerPayment"
+sidebar_position: 4
+---
+
+# CustomerPayment
+
+<details>
+<summary>Example JSON</summary>
+
+```json
+{
+  "id": null,
+  "companyId": "comp_xyz789",
+  "customerId": "cus_ref123",
+  "customerName": null,
+  "amount": 45000,
+  "currency": "XOF",
+  "paymentDate": "paymentDate",
+  "paymentMethod": "paymentMethod",
+  "referenceNumber": "PAY-2026-0099",
+  "allocatedAmount": 30000,
+  "unappliedAmount": 15000,
+  "status": "status",
+  "notes": null,
+  "recordedBy": "staff_k0f1",
+  "recordedByName": null,
+  "createdAt": "createdAt",
+  "updatedAt": "updatedAt"
+}
+```
+
+</details>
+
+
+- [1. Property `id`](#id)
+- [2. Property `companyId`](#companyId)
+- [3. Property `customerId`](#customerId)
+- [4. Property `customerName`](#customerName)
+- [5. Property `amount`](#amount)
+- [6. Property `currency`](#currency)
+- [7. Property `paymentDate`](#paymentDate)
+  - [7.1. Property `_seconds`](#paymentDate__seconds)
+  - [7.2. Property `_nanoseconds`](#paymentDate__nanoseconds)
+- [8. Property `paymentMethod`](#paymentMethod)
+- [9. Property `referenceNumber`](#referenceNumber)
+- [10. Property `allocatedAmount`](#allocatedAmount)
+- [11. Property `unappliedAmount`](#unappliedAmount)
+- [12. Property `status`](#status)
+- [13. Property `notes`](#notes)
+- [14. Property `recordedBy`](#recordedBy)
+- [15. Property `recordedByName`](#recordedByName)
+- [16. Property `createdAt`](#createdAt)
+  - [16.1. Property `_seconds`](#paymentDate__seconds)
+  - [16.2. Property `_nanoseconds`](#paymentDate__nanoseconds)
+- [17. Property `updatedAt`](#updatedAt)
+  - [17.1. Property `firestore-timestamp`](#updatedAt_anyOf_i0)
+  - [17.2. Property `item 1`](#updatedAt_anyOf_i1)
+
+|                           |                                |
+| ------------------------- | ------------------------------ |
+| **Type**                  | `object`                       |
+| **Required**              | No                             |
+| **Additional properties** | Not allowed                    |
+| **Defined in**            | #/definitions/customer-payment |
+
+**Description:** CustomerPayment model (D22). Collection: companies/\{companyId\}/customerPayments/\{paymentId\}. Dashboard-only today; Mobile read in Wave 2, write in Wave 4 (trusted-party workflow).
+
+| Property                               | Pattern | Type             | Deprecated | Definition                               | Title/Description                                                                                           |
+| -------------------------------------- | ------- | ---------------- | ---------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| - [id](#id )                           | No      | string or null   | No         | -                                        | (Read-only) Firestore document ID. Note: optional in current schema — some legacy docs may lack this field. |
+| + [companyId](#companyId )             | No      | string           | No         | -                                        | (Immutable) FK → Company document ID. Scopes all queries.                                                   |
+| + [customerId](#customerId )           | No      | string           | No         | -                                        | (Immutable) FK → Customer.id (Firestore doc ID). Links payment to customer. Set at creation.                |
+| - [customerName](#customerName )       | No      | string or null   | No         | -                                        | (Denormalized) From Customer.name at write time.                                                            |
+| + [amount](#amount )                   | No      | number           | No         | -                                        | -                                                                                                           |
+| + [currency](#currency )               | No      | const            | No         | -                                        | Currency code. Locked to XOF (West African CFA franc) for now.                                              |
+| + [paymentDate](#paymentDate )         | No      | object           | No         | In #/definitions/firestore-timestamp     | Firestore Timestamp serialized representation                                                               |
+| + [paymentMethod](#paymentMethod )     | No      | enum (of string) | No         | In #/definitions/payment-method          | Unified payment method set with African + global methods (D02).                                             |
+| + [referenceNumber](#referenceNumber ) | No      | string           | No         | -                                        | Unique payment reference (receipt number, transaction ID, etc.).                                            |
+| + [allocatedAmount](#allocatedAmount ) | No      | number           | No         | -                                        | (Read-only) Total amount allocated to bookings/orders/purchases via allocations. Server-calculated.         |
+| + [unappliedAmount](#unappliedAmount ) | No      | number           | No         | -                                        | (Read-only) Remaining unallocated amount (amount - allocatedAmount). Server-calculated.                     |
+| + [status](#status )                   | No      | enum (of string) | No         | In #/definitions/customer-payment-status | Customer payment lifecycle status (D22). Tracks allocation progress of received payments.                   |
+| - [notes](#notes )                     | No      | string or null   | No         | -                                        | -                                                                                                           |
+| + [recordedBy](#recordedBy )           | No      | string           | No         | -                                        | (Immutable) FK → User/staff UID who recorded the payment. Required audit field (D22/IG-7).                  |
+| - [recordedByName](#recordedByName )   | No      | string or null   | No         | -                                        | (Immutable, Denormalized) From User display name at creation time.                                          |
+| + [createdAt](#createdAt )             | No      | object           | No         | In #/definitions/firestore-timestamp     | (Read-only) Server-generated creation timestamp.                                                            |
+| - [updatedAt](#updatedAt )             | No      | Combination      | No         | -                                        | (Read-only) Server-generated update timestamp.                                                              |
+
+## <a name="id"></a>1. Property `id`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Read-only) Firestore document ID. Note: optional in current schema — some legacy docs may lack this field.
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## <a name="companyId"></a>2. Property `companyId`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) FK → Company document ID. Scopes all queries.
+
+:::info Immutable
+Set at creation only. This field cannot be modified after the document is created. Include it in CREATE payloads; omit it (or leave unchanged) in UPDATE payloads.
+:::
+
+## <a name="customerId"></a>3. Property `customerId`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) FK → Customer.id (Firestore doc ID). Links payment to customer. Set at creation.
+
+:::info Immutable
+Set at creation only. This field cannot be modified after the document is created. Include it in CREATE payloads; omit it (or leave unchanged) in UPDATE payloads.
+:::
+
+## <a name="customerName"></a>4. Property `customerName`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Denormalized) From Customer.name at write time.
+
+## <a name="amount"></a>5. Property `amount`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `number` |
+| **Required** | Yes      |
+
+## <a name="currency"></a>6. Property `currency`
+
+|              |         |
+| ------------ | ------- |
+| **Type**     | `const` |
+| **Required** | Yes     |
+
+**Description:** Currency code. Locked to XOF (West African CFA franc) for now.
+
+Specific value: `"XOF"`
+
+## <a name="paymentDate"></a>7. Property `paymentDate`
+
+|                           |                                   |
+| ------------------------- | --------------------------------- |
+| **Type**                  | `object`                          |
+| **Required**              | Yes                               |
+| **Additional properties** | Not allowed                       |
+| **Defined in**            | #/definitions/firestore-timestamp |
+
+**Description:** Firestore Timestamp serialized representation
+
+| Property                                     | Pattern | Type    | Deprecated | Definition | Title/Description |
+| -------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#paymentDate__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#paymentDate__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+### <a name="paymentDate__seconds"></a>7.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+### <a name="paymentDate__nanoseconds"></a>7.2. Property `_nanoseconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+## <a name="paymentMethod"></a>8. Property `paymentMethod`
+
+|                |                              |
+| -------------- | ---------------------------- |
+| **Type**       | `enum (of string)`           |
+| **Required**   | Yes                          |
+| **Defined in** | #/definitions/payment-method |
+
+**Description:** Unified payment method set with African + global methods (D02).
+
+Must be one of:
+* "CASH"
+* "CREDIT_CARD"
+* "ORANGE_MONEY"
+* "WAVE"
+* "MTN_MONEY"
+* "MOOV_MONEY"
+* "BANK_TRANSFER"
+* "PAYPAL"
+* "STRIPE"
+* "OTHER"
+
+## <a name="referenceNumber"></a>9. Property `referenceNumber`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Unique payment reference (receipt number, transaction ID, etc.).
+
+## <a name="allocatedAmount"></a>10. Property `allocatedAmount`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `number` |
+| **Required** | Yes      |
+
+**Description:** (Read-only) Total amount allocated to bookings/orders/purchases via allocations. Server-calculated.
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## <a name="unappliedAmount"></a>11. Property `unappliedAmount`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `number` |
+| **Required** | Yes      |
+
+**Description:** (Read-only) Remaining unallocated amount (amount - allocatedAmount). Server-calculated.
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## <a name="status"></a>12. Property `status`
+
+|                |                                       |
+| -------------- | ------------------------------------- |
+| **Type**       | `enum (of string)`                    |
+| **Required**   | Yes                                   |
+| **Defined in** | #/definitions/customer-payment-status |
+
+**Description:** Customer payment lifecycle status (D22). Tracks allocation progress of received payments.
+
+Must be one of:
+* "PENDING"
+* "CONFIRMED"
+* "PARTIALLY_APPLIED"
+* "FULLY_APPLIED"
+* "REFUNDED"
+* "CANCELLED"
+
+## <a name="notes"></a>13. Property `notes`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+## <a name="recordedBy"></a>14. Property `recordedBy`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) FK → User/staff UID who recorded the payment. Required audit field (D22/IG-7).
+
+:::info Immutable
+Set at creation only. This field cannot be modified after the document is created. Include it in CREATE payloads; omit it (or leave unchanged) in UPDATE payloads.
+:::
+
+## <a name="recordedByName"></a>15. Property `recordedByName`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Immutable, Denormalized) From User display name at creation time.
+
+:::info Immutable
+Set at creation only. This field cannot be modified after the document is created. Include it in CREATE payloads; omit it (or leave unchanged) in UPDATE payloads.
+:::
+
+## <a name="createdAt"></a>16. Property `createdAt`
+
+|                           |                                   |
+| ------------------------- | --------------------------------- |
+| **Type**                  | `object`                          |
+| **Required**              | Yes                               |
+| **Additional properties** | Not allowed                       |
+| **Defined in**            | #/definitions/firestore-timestamp |
+
+**Description:** (Read-only) Server-generated creation timestamp.
+
+| Property                                     | Pattern | Type    | Deprecated | Definition | Title/Description |
+| -------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#paymentDate__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#paymentDate__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+### <a name="paymentDate__seconds"></a>16.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+### <a name="paymentDate__nanoseconds"></a>16.2. Property `_nanoseconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## <a name="updatedAt"></a>17. Property `updatedAt`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** (Read-only) Server-generated update timestamp.
+
+| Any of(Option)                             |
+| ------------------------------------------ |
+| [firestore-timestamp](#updatedAt_anyOf_i0) |
+| [item 1](#updatedAt_anyOf_i1)              |
+
+### <a name="updatedAt_anyOf_i0"></a>17.1. Property `firestore-timestamp`
+
+|                           |                             |
+| ------------------------- | --------------------------- |
+| **Type**                  | `object`                    |
+| **Required**              | No                          |
+| **Additional properties** | Not allowed                 |
+| **Same definition as**    | [paymentDate](#paymentDate) |
+
+**Description:** Firestore Timestamp serialized representation
+
+### <a name="updatedAt_anyOf_i1"></a>17.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-06 at 19:27:48 +0000
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## Related Decisions
+
+| Decision | Title |
+|---|---|
+| **D22** | Mobile customer payment feature scope |