add all root documents + tests

Author: khvn26

src/flagsmith_models/__init__.py

@@ -3,12 +3,12 @@
 The schemas are written to DynamoDB documents by Core, and read by Edge.
 """
 
-from datetime import datetime
 from typing import Literal, TypeAlias
-from uuid import UUID
 
 from typing_extensions import NotRequired, TypedDict
 
+from flagsmith_models.types import DateTimeStr, UUIDStr
+
 FeatureType = Literal["STANDARD", "MULTIVARIATE"]
 """Represents the type of a Flagsmith feature. Multivariate features include multiple weighted values."""
 
@@ -79,7 +79,7 @@ class MultivariateFeatureStateValue(TypedDict):
 
     id: NotRequired[int | None]
     """Unique identifier for the multivariate feature state value in Core. TODO: document why and when this can be `None`."""
-    mv_fs_value_uuid: NotRequired[UUID]
+    mv_fs_value_uuid: NotRequired[UUIDStr]
     """The UUID for this multivariate feature state value. Should be used if `id` is `None`."""
     percentage_allocation: float
     """The percentage allocation for this multivariate feature state value. Should be between or equal to 0 and 100."""
@@ -105,7 +105,7 @@ class FeatureState(TypedDict):
     """The value for this feature state."""
     django_id: NotRequired[int | None]
     """Unique identifier for the feature state in Core. TODO: document why and when this can be `None`."""
-    featurestate_uuid: NotRequired[UUID]
+    featurestate_uuid: NotRequired[UUIDStr]
     """The UUID for this feature state. Should be used if `django_id` is `None`. If not set, should be generated."""
     feature_segment: NotRequired[FeatureSegment | None]
     """Segment override data, if this feature state is for a segment override."""
@@ -193,7 +193,7 @@ class Project(TypedDict):
     """List of feature IDs that are skipped when the SDK API serves flags for a public client-side key."""
     enable_realtime_updates: NotRequired[bool]
     """Whether the SDK API should use real-time updates. Defaults to `False`. Not currently used neither by SDK APIs nor by SDKs themselves."""
-    hide_disabled_flags: NotRequired[bool]
+    hide_disabled_flags: NotRequired[bool | None]
     """Whether the SDK API should hide disabled flags for this project. Defaults to `False`."""
 
 
@@ -222,43 +222,89 @@ class Webhook(TypedDict):
     """Secret used to sign webhook payloads."""
 
 
+class _EnvironmentFields(TypedDict):
+    """Common fields for Environment documents."""
+
+    name: NotRequired[str]
+    """Environment name. TODO: Can we drop NotRequired and adjust test data?"""
+    updated_at: NotRequired[DateTimeStr | None]
+    """Last updated timestamp. If not set, current timestamp should be assumed."""
+
+    project: Project
+    """Project-specific data for this environment."""
+    feature_states: list[FeatureState]
+    """List of feature states representing the environment defaults."""
+
+    allow_client_traits: NotRequired[bool]
+    """Whether the SDK API should allow clients to set traits for this environment. Identical to project-level's `persist_trait_data` setting. Defaults to `True`."""
+    hide_sensitive_data: NotRequired[bool]
+    """Whether the SDK API should hide sensitive data for this environment. Defaults to `False`."""
+    hide_disabled_flags: NotRequired[bool | None]
+    """Whether the SDK API should hide disabled flags for this environment. If `None`, the SDK API should fall back to project-level setting."""
+    use_identity_composite_key_for_hashing: NotRequired[bool]
+    """Whether the SDK API should set `$.identity.key` in engine evaluation context to identity's composite key. Defaults to `False`."""
+    use_identity_overrides_in_local_eval: NotRequired[bool]
+    """Whether the SDK API should return identity overrides as part of the environment document. Defaults to `False`."""
+
+    amplitude_config: NotRequired[Integration | None]
+    """Amplitude integration configuration."""
+    dynatrace_config: NotRequired[DynatraceIntegration | None]
+    """Dynatrace integration configuration."""
+    heap_config: NotRequired[Integration | None]
+    """Heap integration configuration."""
+    mixpanel_config: NotRequired[Integration | None]
+    """Mixpanel integration configuration."""
+    rudderstack_config: NotRequired[Integration | None]
+    """RudderStack integration configuration."""
+    segment_config: NotRequired[Integration | None]
+    """Segment integration configuration."""
+    webhook_config: NotRequired[Webhook | None]
+    """Webhook configuration."""
+
+
 ### Root document schemas below. Indexed fields are marked as **INDEXED** in the docstrings. ###
 
 
 class EnvironmentAPIKey(TypedDict):
-    """Represents a server-side API key for a Flagsmith environment."""
+    """Represents a server-side API key for a Flagsmith environment.
+
+    **DynamoDB table**: `flagsmith_environment_api_key`
+    """
 
     id: int
     """Unique identifier for the environment API key in Core. **INDEXED**."""
     key: str
     """The server-side API key string, e.g. `"ser.xxxxxxxxxxxxx"`. **INDEXED**."""
-    created_at: datetime
+    created_at: DateTimeStr
     """Creation timestamp."""
     name: str
     """Name of the API key."""
     client_api_key: str
     """The corresponding public client-side API key."""
-    expires_at: NotRequired[datetime | None]
+    expires_at: NotRequired[DateTimeStr | None]
     """Expiration timestamp. If `None`, the key does not expire."""
     active: bool
     """Whether the key is active. Defaults to `True`."""
 
 
 class Identity(TypedDict):
-    """Represents a Flagsmith identity within an environment. Carries traits and feature overrides."""
+    """Represents a Flagsmith identity within an environment. Carries traits and feature overrides.
+
+    **DynamoDB table**: `flagsmith_identities`
+    """
 
     identifier: str
     """Unique identifier for the identity. **INDEXED**."""
     environment_api_key: str
     """API key of the environment this identity belongs to. Used to scope the identity within a specific environment. **INDEXED**."""
-    identity_uuid: UUID
+    identity_uuid: UUIDStr
     """The UUID for this identity. **INDEXED**."""
     composite_key: str
     """A composite key combining the environment and identifier. **INDEXED**.
 
     Generated as: `{environment_api_key}_{identifier}`.
     """
-    created_date: datetime
+    created_date: DateTimeStr
     """Creation timestamp."""
     identity_features: NotRequired[list[FeatureState]]
     """List of identity overrides for this identity."""
@@ -268,45 +314,50 @@ class Identity(TypedDict):
     """Unique identifier for the identity in Core. TODO: document why and when this can be `None`."""
 
 
-class Environment(TypedDict):
-    """Represents a Flagsmith environment. Carries all necessary data for flag evaluation within the environment."""
+class Environment(_EnvironmentFields):
+    """Represents a Flagsmith environment. Carries all necessary data for flag evaluation within the environment.
+
+    **DynamoDB table**: `flagsmith_environments`
+    """
 
     id: int
     """Unique identifier for the environment in Core. **INDEXED**."""
     api_key: str
     """Public client-side API key for the environment. **INDEXED**."""
-    name: NotRequired[str]
-    """Environment name. TODO: Can we drop NotRequired and adjust test data?"""
-    updated_at: NotRequired[datetime | None]
-    """Last updated timestamp. If not set, current timestamp should be assumed."""
 
-    project: Project
-    """Project-specific data for this environment."""
-    feature_states: list[FeatureState]
-    """List of feature states representing the environment defaults."""
 
-    allow_client_traits: NotRequired[bool]
-    """Whether the SDK API should allow clients to set traits for this environment. Identical to project-level's `persist_trait_data` setting. Defaults to `True`."""
-    hide_sensitive_data: NotRequired[bool]
-    """Whether the SDK API should hide sensitive data for this environment. Defaults to `False`."""
-    hide_disabled_flags: NotRequired[bool]
-    """Whether the SDK API should hide disabled flags for this environment. If `None`, the SDK API should fall back to project-level setting."""
-    use_identity_composite_key_for_hashing: NotRequired[bool]
-    """Whether the SDK API should set `$.identity.key` in engine evaluation context to identity's composite key. Defaults to `False`."""
-    use_identity_overrides_in_local_eval: NotRequired[bool]
-    """Whether the SDK API should return identity overrides as part of the environment document. Defaults to `False`."""
+class EnvironmentV2Meta(_EnvironmentFields):
+    """Represents a Flagsmith environment. Carries all necessary data for flag evaluation within the environment.
 
-    amplitude_config: NotRequired[Integration]
-    """Amplitude integration configuration."""
-    dynatrace_config: NotRequired[DynatraceIntegration]
-    """Dynatrace integration configuration."""
-    heap_config: NotRequired[Integration]
-    """Heap integration configuration."""
-    mixpanel_config: NotRequired[Integration]
-    """Mixpanel integration configuration."""
-    rudderstack_config: NotRequired[Integration]
-    """RudderStack integration configuration."""
-    segment_config: NotRequired[Integration]
-    """Segment integration configuration."""
-    webhook_config: NotRequired[Webhook]
-    """Webhook configuration."""
+    **DynamoDB table**: `flagsmith_environments_v2`
+    """
+
+    environment_id: str
+    """Unique identifier for the environment in Core. **INDEXED**."""
+    environment_api_key: str
+    """Public client-side API key for the environment. **INDEXED**."""
+    document_key: Literal["_META"]
+    """The fixed document key for the environment v2 document. Always `"_META"`. **INDEXED**."""
+
+    id: int
+    """Unique identifier for the environment in Core. Exists for compatibility with the API environment document schema."""
+
+
+class EnvironmentV2IdentityOverride(TypedDict):
+    """Represents an identity override.
+
+    **DynamoDB table**: `flagsmith_environments_v2`
+    """
+
+    environment_id: str
+    """Unique identifier for the environment in Core. **INDEXED**."""
+    document_key: str
+    """The document key for this identity override, formatted as `identity_override:{feature Core ID}:{identity UUID}`. **INDEXED**."""
+    environment_api_key: str
+    """Public client-side API key for the environment. **INDEXED**."""
+    identifier: str
+    """Unique identifier for the identity. **INDEXED**."""
+    identity_uuid: str
+    """The UUID for this identity. **INDEXED**."""
+    feature_state: FeatureState
+    """The feature state override for this identity."""

src/flagsmith_models/types.py

@@ -0,0 +1,7 @@
+from typing import TypeAlias
+
+UUIDStr: TypeAlias = str
+"""A string representing a UUID."""
+
+DateTimeStr: TypeAlias = str
+"""A string representing a date and time in ISO 8601 format."""

tests/integration/flagsmith_models/data/flagsmith_environment_api_key.json

@@ -0,0 +1,9 @@
+{
+    "key": "ser.ZSwVCQrCGpXXKdvVsVxoie",
+    "active": true,
+    "client_api_key": "pQuzvsMLQoOVAwITrTWDQJ",
+    "created_at": "2023-04-21T13:11:13.913178+00:00",
+    "expires_at": null,
+    "id": 907,
+    "name": "TestKey"
+}

…n/flagsmith_models/data/environment.json …_models/data/flagsmith_environments.jsontests/integration/flagsmith_models/data/environment.json renamed to tests/integration/flagsmith_models/data/flagsmith_environments.json tests/integration/flagsmith_models/data/environment.json renamed to tests/integration/flagsmith_models/data/flagsmith_environments.json

@@ -0,0 +1,108 @@
+{
+    "environment_id": "49268",
+    "document_key": "_META",
+    "allow_client_traits": true,
+    "amplitude_config": null,
+    "dynatrace_config": null,
+    "environment_api_key": "AQ9T6LixPqYMJkuqGJy3t2",
+    "feature_states": [
+        {
+            "django_id": 577621,
+            "enabled": true,
+            "feature": {
+                "id": 100298,
+                "name": "test_feature",
+                "type": "MULTIVARIATE"
+            },
+            "featurestate_uuid": "42d7805e-a9ac-401c-a7b7-d6583ac5a365",
+            "feature_segment": null,
+            "feature_state_value": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+            "multivariate_feature_state_values": [
+                {
+                    "id": 185130,
+                    "multivariate_feature_option": {
+                        "id": 20919,
+                        "value": "second"
+                    },
+                    "mv_fs_value_uuid": "0b02ce41-9965-4c61-8b96-c8d76e3d4a27",
+                    "percentage_allocation": 10
+                },
+                {
+                    "id": 48717,
+                    "multivariate_feature_option": {
+                        "id": 14004,
+                        "value": true
+                    },
+                    "mv_fs_value_uuid": "cb05f49c-de1f-44f1-87eb-c3b55d473063",
+                    "percentage_allocation": 30
+                }
+            ]
+        },
+        {
+            "django_id": 1041292,
+            "enabled": false,
+            "feature": {
+                "id": 172422,
+                "name": "feature",
+                "type": "STANDARD"
+            },
+            "featurestate_uuid": "58b7b954-1b75-493a-82df-5be0efeedd2a",
+            "feature_segment": null,
+            "feature_state_value": 3,
+            "multivariate_feature_state_values": []
+        }
+    ],
+    "heap_config": null,
+    "hide_disabled_flags": null,
+    "hide_sensitive_data": false,
+    "id": 49268,
+    "identity_overrides": [],
+    "mixpanel_config": null,
+    "name": "Development",
+    "project": {
+        "enable_realtime_updates": false,
+        "hide_disabled_flags": false,
+        "id": 19368,
+        "name": "Example Project",
+        "organisation": {
+            "feature_analytics": false,
+            "id": 13,
+            "name": "Flagsmith",
+            "persist_trait_data": true,
+            "stop_serving_flags": false
+        },
+        "segments": [
+            {
+                "feature_states": [],
+                "id": 44126,
+                "name": "test",
+                "rules": [
+                    {
+                        "conditions": [],
+                        "rules": [
+                            {
+                                "conditions": [
+                                    {
+                                        "operator": "EQUAL",
+                                        "property_": "test",
+                                        "value": "test"
+                                    }
+                                ],
+                                "rules": [],
+                                "type": "ANY"
+                            }
+                        ],
+                        "type": "ALL"
+                    }
+                ]
+            }
+        ],
+        "server_key_only_feature_ids": []
+    },
+    "rudderstack_config": null,
+    "segment_config": null,
+    "updated_at": "2025-11-16T13:28:31.244331+00:00",
+    "use_identity_composite_key_for_hashing": true,
+    "use_identity_overrides_in_local_eval": false,
+    "webhook_config": null
+}

tests/integration/flagsmith_models/data/flagsmith_environments_v2:_META.json

@@ -0,0 +1,29 @@
+{
+    "composite_key": "pQuzvsMLQoOVAwITrTWDQJ_57c6edf1bbf145a1a23ea287ce44877f",
+    "created_date": "2024-03-19T09:41:22.974595+00:00",
+    "django_id": null,
+    "environment_api_key": "pQuzvsMLQoOVAwITrTWDQJ",
+    "identifier": "57c6edf1bbf145a1a23ea287ce44877f",
+    "identity_features": [
+        {
+            "django_id": null,
+            "enabled": true,
+            "feature": {
+                "id": 67,
+                "name": "test_feature",
+                "type": "STANDARD"
+            },
+            "featurestate_uuid": "20988957-d345-424e-9abc-1dc5a814da48",
+            "feature_segment": null,
+            "feature_state_value": null,
+            "multivariate_feature_state_values": []
+        }
+    ],
+    "identity_traits": [
+        {
+            "trait_key": "test_trait",
+            "trait_value": 42
+        }
+    ],
+    "identity_uuid": "118ecfc9-5234-4218-8af8-dd994dbfedc0"
+}