:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(warehouse_sources): add four more medusa endpoint tables (#123047)
Tom Owers14e2dcf32001
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.mdindex c352ab283d2a..db9c02320663 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md@@ -7734,19 +7734,19 @@ Note: Read the vendor SDK's controller docs (32 controllers) and enumerated the## Medusa — gaps-Today (13): `Claims`, `CustomerGroups`, `Customers`, `DraftOrders`, `Exchanges`, `InventoryItems`, `Orders`, `PriceLists`, `Products`, `ProductVariants`, `Regions`, `Returns`, `StockLocations`+Today (17): `Claims`, `CustomerGroups`, `Customers`, `DraftOrders`, `Exchanges`, `InventoryItems`, `Orders`, `Payments`, `PriceLists`, `ProductCategories`, `Products`, `ProductVariants`, `Promotions`, `Regions`, `Reservations`, `Returns`, `StockLocations`Diffed against: <https://raw.githubusercontent.com/medusajs/medusa/develop/www/apps/api-reference/specs/admin/openapi.yaml>- [x] `Stock locations (GET /admin/stock-locations)` — resolve location_id on returns and support stock analysis by warehouse (high). Added as `StockLocations`.- [x] `Claims (GET /admin/claims)` — resolve claim_id on returns and analyze reasons for after-sale claims (high). Added as `Claims`.- [x] `Exchanges (GET /admin/exchanges)` — resolve exchange_id on returns and measure replacement activity (high). Added as `Exchanges`.-- [ ] `Payments (GET /admin/payments)` — track captured and refunded payments for revenue reconciliation (high)+- [x] `Payments (GET /admin/payments)` — track captured and refunded payments for revenue reconciliation (high). Added as `Payments`.- [x] `Inventory items (GET /admin/inventory-items)` — measure available, reserved, and stocked quantities, including nested location levels (high). Added as `InventoryItems` (full refresh: the list route has no timestamp filters).-- [ ] `Reservations (GET /admin/reservations)` — analyze inventory commitments and their impact on available stock (medium)-- [ ] `Promotions (GET /admin/promotions)` — compare discount rules with order revenue and promotional performance (medium)+- [x] `Reservations (GET /admin/reservations)` — analyze inventory commitments and their impact on available stock (medium). Added as `Reservations`.+- [x] `Promotions (GET /admin/promotions)` — compare discount rules with order revenue and promotional performance (medium). Added as `Promotions`.- [ ] `Campaigns (GET /admin/campaigns)` — measure promotion budgets and campaign usage (medium)-- [ ] `Product categories (GET /admin/product-categories)` — group catalog performance by category hierarchy (medium)+- [x] `Product categories (GET /admin/product-categories)` — group catalog performance by category hierarchy (medium). Added as `ProductCategories`.Note: Parsed the official v2 OpenAPI root and fetched referenced path files to verify GET methods. Checked official query defaults: products already embed types, collections, tags, and sales channels, so duplicate lookups are excluded. Inventory lists include location levels; no collection route exists for fulfillments. Excluded auth, keys, settings, and uploads; route availability depends on the deployed Medusa version.diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/canonical_descriptions.py b/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/canonical_descriptions.pyindex a844b91cd06e..cffae190cd52 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/canonical_descriptions.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/canonical_descriptions.py@@ -187,4 +187,73 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {**_TIMESTAMPS,},},+ "Reservations": {+ "description": "A quantity of an inventory item held at a stock location, usually for an order line item.",+ "docs_url": "https://docs.medusajs.com/api/admin#reservations",+ "columns": {+ "id": "Unique identifier of the reservation.",+ "line_item_id": "ID of the line item the reservation is for.",+ "location_id": "ID of the stock location the quantity is reserved from.",+ "inventory_item_id": "ID of the reserved inventory item.",+ "quantity": "Reserved quantity.",+ "external_id": "ID of the reservation in an external system.",+ "description": "Description of the reservation.",+ "created_by": "ID of the user who created the reservation.",+ "metadata": "Key-value pairs of custom data.",+ **_TIMESTAMPS,+ },+ },+ "Payments": {+ "description": "A payment processed through a payment provider, with its authorized, captured, and refunded amounts.",+ "docs_url": "https://docs.medusajs.com/api/admin#payments",+ "columns": {+ "id": "Unique identifier of the payment.",+ "amount": "Amount of the payment.",+ "currency_code": "Three-letter ISO currency code of the payment.",+ "provider_id": "ID of the payment provider that processed the payment.",+ "captured_at": "Date the payment was captured.",+ "canceled_at": "Date the payment was canceled.",+ "payment_collection_id": "ID of the payment collection the payment belongs to.",+ "payment_session_id": "ID of the payment session the payment was created from.",+ "metadata": "Key-value pairs of custom data.",+ "captures": "Captures made against the payment.",+ "refunds": "Refunds made against the payment.",+ **_TIMESTAMPS,+ },+ },+ "Promotions": {+ "description": "A discount that applies to carts automatically or through a code, with its rules and usage.",+ "docs_url": "https://docs.medusajs.com/api/admin#promotions",+ "columns": {+ "id": "Unique identifier of the promotion.",+ "code": "Code customers enter to apply the promotion.",+ "type": "Type of the promotion: standard or buyget.",+ "status": "Status of the promotion.",+ "is_automatic": "Whether the promotion applies to a cart automatically when it matches the rules.",+ "is_tax_inclusive": "Whether the promotion applies after tax is calculated.",+ "campaign_id": "ID of the campaign the promotion belongs to.",+ "application_method": "How the discount is applied: its type, target, value, and allocation.",+ "rules": "Conditions a cart must match for the promotion to apply.",+ "limit": "Maximum number of times the promotion can be used.",+ "used": "Number of times the promotion has been used.",+ "metadata": "Key-value pairs of custom data.",+ **_TIMESTAMPS,+ },+ },+ "ProductCategories": {+ "description": "A category in the product catalog, which can nest under a parent category.",+ "docs_url": "https://docs.medusajs.com/api/admin#product-categories",+ "columns": {+ "id": "Unique identifier of the product category.",+ "name": "Name of the category.",+ "description": "Description of the category.",+ "handle": "Unique handle of the category.",+ "parent_category_id": "ID of the parent category.",+ "rank": "Rank of the category among its sibling categories.",+ "is_active": "Whether the category is active. Inactive categories are hidden in the storefront.",+ "is_internal": "Whether the category is internal. Internal categories are only visible to admin users.",+ "metadata": "Key-value pairs of custom data.",+ **_TIMESTAMPS,+ },+ },}diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/medusa.py b/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/medusa.pyindex 03eaf71c0ce0..e8f83ec14ddd 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/medusa.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/medusa.py@@ -237,15 +237,19 @@ def get_resource(raise ValueError(f"Medusa endpoint '{config.name}' has no incremental field '{incremental_field_name}'")cursor_field = config.incremental_field_name+ params: dict[str, Any] = {+ # Explicit ascending sort: it keeps offset page boundaries stable while rows are+ # inserted mid-sync, and on incremental runs it matches sort_mode="asc" so the+ # watermark checkpoints correctly. `created_at` is immutable, so a full refresh+ # sorts on it; incremental runs sort on the cursor field itself.+ "order": cursor_field,+ }+ if config.extra_fields:+ params["fields"] = ",".join(f"+{field}" for field in config.extra_fields)+endpoint: Endpoint = {"path": f"/admin{config.path}",- "params": {- # Explicit ascending sort: it keeps offset page boundaries stable while rows are- # inserted mid-sync, and on incremental runs it matches sort_mode="asc" so the- # watermark checkpoints correctly. `created_at` is immutable, so a full refresh- # sorts on it; incremental runs sort on the cursor field itself.- "order": cursor_field,- },+ "params": params,"paginator": MedusaPaginator(),"data_selector": config.data_selector,}diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/settings.pyindex 1a7681ab1faf..5897f2daf9fb 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/settings.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/settings.py@@ -58,6 +58,9 @@ class MedusaEndpointConfig:# incremental runs. None means the list route documents no timestamp filters, so the# endpoint is full refresh only.incremental_field_name: str | None = "updated_at"+ # Columns to add to the route's default response fields via `fields=+a,+b`. Needed where the+ # defaults omit the timestamps the cursor and the partition key read.+ extra_fields: tuple[str, ...] = ()@propertydef incremental_fields(self) -> list[IncrementalField]:@@ -92,6 +95,17 @@ MEDUSA_ENDPOINTS: dict[str, MedusaEndpointConfig] = {"InventoryItems": MedusaEndpointConfig(name="InventoryItems", path="/inventory-items", data_selector="inventory_items", incremental_field_name=None),+ "Reservations": MedusaEndpointConfig(name="Reservations", path="/reservations", data_selector="reservations"),+ "Payments": MedusaEndpointConfig(+ name="Payments",+ path="/payments",+ data_selector="payments",+ extra_fields=("created_at", "updated_at", "canceled_at", "provider_id", "metadata"),+ ),+ "Promotions": MedusaEndpointConfig(name="Promotions", path="/promotions", data_selector="promotions"),+ "ProductCategories": MedusaEndpointConfig(+ name="ProductCategories", path="/product-categories", data_selector="product_categories"+ ),}ENDPOINTS = tuple(MEDUSA_ENDPOINTS)diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/tests/test_medusa.py b/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/tests/test_medusa.pyindex 9c31e3c36179..5f9c3ee8f536 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/tests/test_medusa.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/medusa/tests/test_medusa.py@@ -107,6 +107,22 @@ class TestMedusaTransport:assert endpoint["incremental"]["start_param"] == "updated_at[$gte]"assert endpoint["incremental"]["cursor_path"] == "updated_at"+ @pytest.mark.parametrize(+ ("endpoint", "expected_fields"),+ [+ ("Orders", None),+ # The payments list route omits its timestamps by default; without them the cursor and+ # the partition key have nothing to read.+ ("Payments", "+created_at,+updated_at,+canceled_at,+provider_id,+metadata"),+ ],+ )+ def test_requests_extra_fields_only_where_defaults_omit_them(+ self, endpoint: str, expected_fields: str | None+ ) -> None:+ resource = cast(dict[str, Any], get_resource(MEDUSA_ENDPOINTS[endpoint], should_use_incremental_field=False))++ assert resource["endpoint"]["params"].get("fields") == expected_fields+@pytest.mark.parametrize("endpoint", ["PriceLists", "InventoryItems"])def test_incremental_rejected_for_endpoint_without_timestamp_filters(self, endpoint: str) -> None:with pytest.raises(ValueError, match="does not support incremental"):