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

package/data/docs/models/analytics-event.md

@@ -0,0 +1,533 @@
+---
+title: "AnalyticsEvent"
+sidebar_label: "AnalyticsEvent"
+sidebar_position: 4
+---
+
+# AnalyticsEvent
+
+<details>
+<summary>Example JSON</summary>
+
+```json
+{
+  "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
+}
+```
+
+</details>
+
+
+- [1. Property `id`](#id)
+- [2. Property `companyId`](#companyId)
+- [3. Property `siteId`](#siteId)
+- [4. Property `eventId`](#eventId)
+- [5. Property `eventName`](#eventName)
+- [6. Property `timestamp`](#timestamp)
+- [7. Property `serverTimestamp`](#serverTimestamp)
+  - [7.1. Property `_seconds`](#serverTimestamp__seconds)
+  - [7.2. Property `_nanoseconds`](#serverTimestamp__nanoseconds)
+- [8. Property `sessionId`](#sessionId)
+- [9. Property `userId`](#userId)
+  - [9.1. Property `item 0`](#userId_anyOf_i0)
+  - [9.2. Property `item 1`](#userId_anyOf_i1)
+- [10. Property `properties`](#properties)
+  - [10.1. Property `additionalProperties`](#properties_additionalProperties)
+- [11. Property `context`](#context)
+  - [11.1. Property `url`](#context_url)
+  - [11.2. Property `origin`](#context_origin)
+  - [11.3. Property `hostname`](#context_hostname)
+  - [11.4. Property `page`](#context_page)
+  - [11.5. Property `title`](#context_title)
+  - [11.6. Property `referrer`](#context_referrer)
+  - [11.7. Property `deviceType`](#context_deviceType)
+  - [11.8. Property `platform`](#context_platform)
+  - [11.9. Property `screenWidth`](#context_screenWidth)
+  - [11.10. Property `screenHeight`](#context_screenHeight)
+  - [11.11. Property `appVersion`](#context_appVersion)
+  - [11.12. Property `online`](#context_online)
+  - [11.13. Property `locale`](#context_locale)
+  - [11.14. Property `timezone`](#context_timezone)
+  - [11.15. Property `utm`](#context_utm)
+    - [11.15.1. Property `item 0`](#context_utm_anyOf_i0)
+      - [11.15.1.1. Property `source`](#context_utm_anyOf_i0_source)
+      - [11.15.1.2. Property `medium`](#context_utm_anyOf_i0_medium)
+      - [11.15.1.3. Property `campaign`](#context_utm_anyOf_i0_campaign)
+      - [11.15.1.4. Property `term`](#context_utm_anyOf_i0_term)
+      - [11.15.1.5. Property `content`](#context_utm_anyOf_i0_content)
+    - [11.15.2. Property `item 1`](#context_utm_anyOf_i1)
+- [12. Property `userTraits`](#userTraits)
+  - [12.1. Property `additionalProperties`](#userTraits_additionalProperties)
+
+|                           |                               |
+| ------------------------- | ----------------------------- |
+| **Type**                  | `object`                      |
+| **Required**              | No                            |
+| **Additional properties** | Not allowed                   |
+| **Defined in**            | #/definitions/analytics-event |
+
+**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.
+
+| Property                               | Pattern | Type           | Deprecated | Definition                           | Title/Description                                                                                                |
+| -------------------------------------- | ------- | -------------- | ---------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| - [id](#id )                           | No      | string or null | No         | -                                    | (Read-only) Firestore document ID. Equal to eventId.                                                             |
+| + [companyId](#companyId )             | No      | string         | No         | -                                    | (Immutable) FK → Company document ID.                                                                            |
+| + [siteId](#siteId )                   | No      | string         | No         | -                                    | (Immutable) FK → Site document ID (D40 sub-tenant scope).                                                        |
+| + [eventId](#eventId )                 | No      | string         | No         | -                                    | (Immutable) Client-generated UUID. Matches document ID.                                                          |
+| + [eventName](#eventName )             | No      | string         | No         | -                                    | Event name. Free string; canonical vocabulary is encouraged (see CANONICAL_ANALYTICS_EVENT_NAMES).               |
+| + [timestamp](#timestamp )             | No      | string         | No         | -                                    | Client-side ISO 8601 — "when it happened on device". Can diverge from serverTimestamp for queued offline events. |
+| + [serverTimestamp](#serverTimestamp ) | No      | object         | No         | In #/definitions/firestore-timestamp | (Read-only) Firestore serverTimestamp() — authoritative for ordering.                                            |
+| + [sessionId](#sessionId )             | No      | string         | No         | -                                    | 30-minute rolling session identifier.                                                                            |
+| + [userId](#userId )                   | No      | Combination    | No         | -                                    | Stable user ID if identified; explicitly null (not omitted) for anonymous sessions — simplifies querying.        |
+| + [properties](#properties )           | No      | object         | No         | -                                    | Free-form event-specific payload. Contract is at the event-name level. PII posture: follow-up issue pending.     |
+| + [context](#context )                 | No      | object         | No         | -                                    | Environment context at event time (nested per D40).                                                              |
+| - [userTraits](#userTraits )           | No      | object or null | No         | -                                    | Optional — included only when includeUserTraits: true on the write. PII posture: follow-up issue pending.        |
+
+## <a name="id"></a>1. Property `id`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Read-only) Firestore document ID. Equal to eventId.
+
+:::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.
+
+:::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="siteId"></a>3. Property `siteId`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) FK → Site document ID (D40 sub-tenant scope).
+
+:::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="eventId"></a>4. Property `eventId`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) Client-generated UUID. Matches document ID.
+
+:::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="eventName"></a>5. Property `eventName`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Event name. Free string; canonical vocabulary is encouraged (see CANONICAL_ANALYTICS_EVENT_NAMES).
+
+## <a name="timestamp"></a>6. Property `timestamp`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Client-side ISO 8601 — "when it happened on device". Can diverge from serverTimestamp for queued offline events.
+
+## <a name="serverTimestamp"></a>7. Property `serverTimestamp`
+
+|                           |                                   |
+| ------------------------- | --------------------------------- |
+| **Type**                  | `object`                          |
+| **Required**              | Yes                               |
+| **Additional properties** | Not allowed                       |
+| **Defined in**            | #/definitions/firestore-timestamp |
+
+**Description:** (Read-only) Firestore serverTimestamp() — authoritative for ordering.
+
+| Property                                         | Pattern | Type    | Deprecated | Definition | Title/Description |
+| ------------------------------------------------ | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#serverTimestamp__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#serverTimestamp__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+### <a name="serverTimestamp__seconds"></a>7.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+### <a name="serverTimestamp__nanoseconds"></a>7.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="sessionId"></a>8. Property `sessionId`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** 30-minute rolling session identifier.
+
+## <a name="userId"></a>9. Property `userId`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | Yes              |
+| **Additional properties** | Any type allowed |
+
+**Description:** Stable user ID if identified; explicitly null (not omitted) for anonymous sessions — simplifies querying.
+
+| Any of(Option)             |
+| -------------------------- |
+| [item 0](#userId_anyOf_i0) |
+| [item 1](#userId_anyOf_i1) |
+
+### <a name="userId_anyOf_i0"></a>9.1. Property `item 0`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+### <a name="userId_anyOf_i1"></a>9.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+## <a name="properties"></a>10. Property `properties`
+
+|                           |                                                                                         |
+| ------------------------- | --------------------------------------------------------------------------------------- |
+| **Type**                  | `object`                                                                                |
+| **Required**              | Yes                                                                                     |
+| **Additional properties** | [Each additional property must conform to the schema](#properties_additionalProperties) |
+
+**Description:** Free-form event-specific payload. Contract is at the event-name level. PII posture: follow-up issue pending.
+
+| Property                                | Pattern | Type   | Deprecated | Definition | Title/Description |
+| --------------------------------------- | ------- | ------ | ---------- | ---------- | ----------------- |
+| - [](#properties_additionalProperties ) | No      | object | No         | -          | -                 |
+
+### <a name="properties_additionalProperties"></a>10.1. Property `additionalProperties`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `object`         |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+## <a name="context"></a>11. Property `context`
+
+|                           |             |
+| ------------------------- | ----------- |
+| **Type**                  | `object`    |
+| **Required**              | Yes         |
+| **Additional properties** | Not allowed |
+
+**Description:** Environment context at event time (nested per D40).
+
+| Property                                 | Pattern | Type             | Deprecated | Definition | Title/Description                                        |
+| ---------------------------------------- | ------- | ---------------- | ---------- | ---------- | -------------------------------------------------------- |
+| - [url](#context_url )                   | No      | string           | No         | -          | Full URL at event time.                                  |
+| - [origin](#context_origin )             | No      | string           | No         | -          | Protocol + host.                                         |
+| - [hostname](#context_hostname )         | No      | string           | No         | -          | Hostname only — useful for deployment identification.    |
+| - [page](#context_page )                 | No      | string           | No         | -          | Current route/pathname.                                  |
+| - [title](#context_title )               | No      | string           | No         | -          | Page title.                                              |
+| - [referrer](#context_referrer )         | No      | string           | No         | -          | Referrer URL.                                            |
+| - [deviceType](#context_deviceType )     | No      | enum (of string) | No         | -          | -                                                        |
+| - [platform](#context_platform )         | No      | string           | No         | -          | OS/platform string.                                      |
+| - [screenWidth](#context_screenWidth )   | No      | integer          | No         | -          | Viewport width (flattened from screen.width).            |
+| - [screenHeight](#context_screenHeight ) | No      | integer          | No         | -          | Viewport height (flattened from screen.height).          |
+| - [appVersion](#context_appVersion )     | No      | string           | No         | -          | Consuming app version.                                   |
+| - [online](#context_online )             | No      | boolean          | No         | -          | Connectivity state at event time.                        |
+| - [locale](#context_locale )             | No      | string           | No         | -          | User locale.                                             |
+| - [timezone](#context_timezone )         | No      | string           | No         | -          | IANA timezone.                                           |
+| - [utm](#context_utm )                   | No      | Combination      | No         | -          | UTM parameters; null when not a campaign-landed session. |
+
+### <a name="context_url"></a>11.1. Property `url`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+**Description:** Full URL at event time.
+
+### <a name="context_origin"></a>11.2. Property `origin`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+**Description:** Protocol + host.
+
+### <a name="context_hostname"></a>11.3. Property `hostname`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+**Description:** Hostname only — useful for deployment identification.
+
+### <a name="context_page"></a>11.4. Property `page`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+**Description:** Current route/pathname.
+
+### <a name="context_title"></a>11.5. Property `title`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+**Description:** Page title.
+
+### <a name="context_referrer"></a>11.6. Property `referrer`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+**Description:** Referrer URL.
+
+### <a name="context_deviceType"></a>11.7. Property `deviceType`
+
+|              |                    |
+| ------------ | ------------------ |
+| **Type**     | `enum (of string)` |
+| **Required** | No                 |
+
+Must be one of:
+* "mobile"
+* "tablet"
+* "desktop"
+
+### <a name="context_platform"></a>11.8. Property `platform`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+**Description:** OS/platform string.
+
+### <a name="context_screenWidth"></a>11.9. Property `screenWidth`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | No        |
+
+**Description:** Viewport width (flattened from screen.width).
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+### <a name="context_screenHeight"></a>11.10. Property `screenHeight`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | No        |
+
+**Description:** Viewport height (flattened from screen.height).
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+### <a name="context_appVersion"></a>11.11. Property `appVersion`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+**Description:** Consuming app version.
+
+### <a name="context_online"></a>11.12. Property `online`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `boolean` |
+| **Required** | No        |
+
+**Description:** Connectivity state at event time.
+
+### <a name="context_locale"></a>11.13. Property `locale`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+**Description:** User locale.
+
+### <a name="context_timezone"></a>11.14. Property `timezone`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+**Description:** IANA timezone.
+
+### <a name="context_utm"></a>11.15. Property `utm`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** UTM parameters; null when not a campaign-landed session.
+
+| Any of(Option)                  |
+| ------------------------------- |
+| [item 0](#context_utm_anyOf_i0) |
+| [item 1](#context_utm_anyOf_i1) |
+
+#### <a name="context_utm_anyOf_i0"></a>11.15.1. Property `item 0`
+
+|                           |             |
+| ------------------------- | ----------- |
+| **Type**                  | `object`    |
+| **Required**              | No          |
+| **Additional properties** | Not allowed |
+
+| Property                                      | Pattern | Type   | Deprecated | Definition | Title/Description |
+| --------------------------------------------- | ------- | ------ | ---------- | ---------- | ----------------- |
+| - [source](#context_utm_anyOf_i0_source )     | No      | string | No         | -          | -                 |
+| - [medium](#context_utm_anyOf_i0_medium )     | No      | string | No         | -          | -                 |
+| - [campaign](#context_utm_anyOf_i0_campaign ) | No      | string | No         | -          | -                 |
+| - [term](#context_utm_anyOf_i0_term )         | No      | string | No         | -          | -                 |
+| - [content](#context_utm_anyOf_i0_content )   | No      | string | No         | -          | -                 |
+
+##### <a name="context_utm_anyOf_i0_source"></a>11.15.1.1. Property `source`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+##### <a name="context_utm_anyOf_i0_medium"></a>11.15.1.2. Property `medium`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+##### <a name="context_utm_anyOf_i0_campaign"></a>11.15.1.3. Property `campaign`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+##### <a name="context_utm_anyOf_i0_term"></a>11.15.1.4. Property `term`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+##### <a name="context_utm_anyOf_i0_content"></a>11.15.1.5. Property `content`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+#### <a name="context_utm_anyOf_i1"></a>11.15.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+## <a name="userTraits"></a>12. Property `userTraits`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `object or null` |
+| **Required** | No               |
+
+**Description:** Optional — included only when includeUserTraits: true on the write. PII posture: follow-up issue pending.
+
+| Property                                | Pattern | Type   | Deprecated | Definition | Title/Description |
+| --------------------------------------- | ------- | ------ | ---------- | ---------- | ----------------- |
+| - [](#userTraits_additionalProperties ) | No      | object | No         | -          | -                 |
+
+### <a name="userTraits_additionalProperties"></a>12.1. Property `additionalProperties`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `object`         |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:54 +0000