Outcome
Read the granted workspace summary with active SKU count, location count, all-time movement count and seven UTC-day movement/net quantity series. Widget totals differ from the dashboard movement count capped at 100.
Before you start
- Verify the authenticated identity, exact environment and pinned approved organization context before preparing an action.
- The published application permission is workspace:read. Discover a granted Inventory workspace and bind that exact resource. Supplied identifiers do not grant access.
Discover the target
topolo whoami --json
topolo actions get app_topolo_inventory.widget.get --detail --json
topolo resources topolo-inventory --json
topolo workspaces list topolo-inventory --json
- Select the exact granted workspace id as INVENTORY_WORKSPACE_ID. Fixture ids authorize no live operation.
Request
GET /api/widget
Save action input as payload.json. Inspect the plan for the exact path, query and body. Set INVENTORY_WORKSPACE_ID from granted resource discovery.
Inspect and test this action in the signed action console, then perform the verification below.
Input fields
Supply an empty input object; credential and resource context are separate.
View the complete input schema in the action console. The same schema is available through CLI and MCP action discovery.
Effects
- The shared widget handler verifies identity and canonical workspace grants; it does not initialize the app-local mirror.
- Active SKU and location counts come from core D1; movement counts and series come from movements D1. All review statuses are counted. Seven UTC dates are zero-filled and current partial-day data is included.
- A resolved workspace returns ready even with zero data; no granted workspace returns an empty state and no metrics. Private cache max-age is 15 seconds.
Interpret the response
Use response path $.workspace.id for workspace. An empty list does not discover a target.
Check the workspace id matches the intended granted target and inspect widget state before using metrics. The movements metric counts the entire ledger; movement_volume_7d and net_quantity_change_7d cover seven UTC calendar dates. Counts do not prove notification delivery.
The success schema was checked against captured handler responses. Delegated Auth profile and canonical widget context fields can vary; exact Inventory projections and all six raw SQL export stores are source-reviewed. Error examples retain their actual refusal shapes.
View the complete success schema in the action console. The worked examples below retain complete captured responses; action discovery supplies the exact schema.
Worked examples
Captured exported Worker responses use both real local SQLite D1 databases with all six committed migrations, synthetic Auth/workspace grants and simulated Notify/Nexus/archive transport. They prove local handler shapes and scoped behavior, not live authorization, notification delivery, metering acceptance or environment deployment. Large 100-row list/capped-dashboard captures are retained in local evidence; committed tests verify those limits while worked guides use smaller complete responses. Refused examples demonstrate boundaries and must not be executed as successful workflows.
Successful request
Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Notify/Nexus/archive transport. No live delivery, billing or environment deployment proof. Captured scenario: empty granted workspace widget.
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_inventory.widget.get --data @payload.json --json
topolo actions plan app_topolo_inventory.widget.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_inventory.widget.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json
MCP tool and arguments:
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_inventory.widget.get",
"input": {},
"resourceType": "workspace",
"resourceId": "<identifier returned by granted resource discovery>"
}
}
Captured local response · HTTP 200:
{
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_inventory",
"serviceName": "Inventory",
"generatedAt": "2026-10-04T05:46:35.874Z",
"widgets": [
{
"id": "inventory.workspace-summary",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Inventory operations",
"description": "SKU and location footprint with seven-day stock movement volume and net quantity change.",
"contexts": [
"organization",
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_inventory_fixture",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-04T05:46:35.855Z",
"lastSuccessfulAt": "2026-10-04T05:46:35.855Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 60,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": true,
"fields": [
{
"key": "metricKeys",
"label": "Measures",
"type": "multi-select",
"required": true,
"options": [
{
"value": "skus",
"label": "SKUs"
},
{
"value": "locations",
"label": "Locations"
},
{
"value": "movements",
"label": "Movements"
},
{
"value": "movements_7d",
"label": "Movements · 7 days"
},
{
"value": "net_quantity_change_7d",
"label": "Net quantity change · 7 days"
}
]
}
],
"defaults": {
"metricKeys": [
"skus",
"locations",
"movements_7d",
"net_quantity_change_7d"
]
}
},
"drilldowns": [
{
"id": "inventory",
"label": "View inventory",
"href": "/dashboard/inventory"
}
],
"controls": [
{
"id": "create-inventory-item",
"label": "Create inventory item",
"actionId": "app_topolo_inventory.items.create",
"resourceType": "workspace",
"resourceId": "ws_inventory_fixture",
"input": {},
"requiresConfirmation": true,
"destructive": false,
"effects": [
"Creates an inventory item in the active workspace at zero quantity on hand.",
"Derives the SKU from the name when sku is omitted, upper-cased and slugified.",
"Creates the workspace mirror row if this is the first record in the workspace."
],
"verification": [
"Expect 201 and read the created id from $.item.id.",
"Confirm $.item.quantityOnHand is 0 — a new item holds no stock until a movement is recorded.",
"Call items.list and confirm the SKU appears exactly once."
],
"recovery": {
"mode": "compensating_action",
"actionId": "app_topolo_inventory.items.archive",
"instructions": "Archive an item created in error. Items are never hard-deleted because their movement history explains every later quantity."
}
}
],
"localization": {
"locale": "en",
"titleKey": "inventory.widget.title",
"descriptionKey": "inventory.widget.summary"
},
"accessibility": {
"label": "Inventory workspace metrics",
"description": "SKU and location footprint with seven-day stock movement volume and net quantity change."
},
"contribution": {
"summary": "Inventory footprint and seven-day stock movement for the selected workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Inventory workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "skus",
"label": "SKUs",
"description": "Active inventory items in the selected workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "locations",
"label": "Locations",
"description": "Inventory locations in the selected workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "movements",
"label": "Movements",
"description": "Stock movements recorded in the selected workspace.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
},
{
"key": "movements_7d",
"label": "Movements · 7 days",
"description": "Stock movements recorded during the current seven-day period.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
},
{
"key": "net_quantity_change_7d",
"label": "Net quantity change · 7 days",
"description": "Net units added to or removed from inventory during the current seven-day period.",
"unit": "units",
"semantic": "gauge",
"aggregation": "sum"
}
],
"seriesDefinitions": [
{
"key": "movement_volume_7d",
"label": "Daily stock movements",
"metricKey": "movements_7d",
"unit": "count"
},
{
"key": "net_quantity_change_7d",
"label": "Daily net quantity change",
"metricKey": "net_quantity_change_7d",
"unit": "units"
}
],
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"description": "The Inventory workspace whose stock data is included.",
"valueType": "string"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"description": "Whether the measure describes catalogue footprint or stock movement.",
"valueType": "string"
}
],
"lifecycleStages": [],
"events": [],
"datasets": [
{
"id": "inventory_footprint",
"label": "Inventory footprint",
"description": "Active SKU and location footprint in the selected workspace.",
"grain": "One aggregate row per Inventory workspace and footprint measure.",
"metricKeys": [
"skus",
"locations"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"inventory_measure"
],
"eventKeys": [],
"actionIds": [
"create-inventory-item"
]
},
{
"id": "stock_movement",
"label": "Stock movement",
"description": "All-time movement count plus daily movement volume and net quantity change for the current seven-day period.",
"grain": "One aggregate row per Inventory workspace and movement measure, with daily series where declared.",
"metricKeys": [
"movements",
"movements_7d",
"net_quantity_change_7d"
],
"seriesKeys": [
"movement_volume_7d",
"net_quantity_change_7d"
],
"dimensionKeys": [
"workspace_scope",
"inventory_measure"
],
"eventKeys": [],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"line",
"area",
"bar",
"table",
"actions"
],
"defaultVisualization": "area"
},
"metrics": [
{
"key": "skus",
"label": "SKUs",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T05:46:35.855Z",
"end": "2026-10-04T05:46:35.855Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"value": "footprint"
}
]
},
{
"key": "locations",
"label": "Locations",
"value": 0,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T05:46:35.855Z",
"end": "2026-10-04T05:46:35.855Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"value": "footprint"
}
]
},
{
"key": "movements",
"label": "Movements",
"value": 0,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-04T05:46:35.855Z",
"end": "2026-10-04T05:46:35.855Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"value": "movement"
}
]
},
{
"key": "movements_7d",
"label": "Movements · 7 days",
"value": 0,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-09-28T00:00:00.000Z",
"end": "2026-10-04T05:46:35.855Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"value": "movement"
}
],
"series": {
"id": "movement_volume_7d",
"label": "Daily stock movements",
"unit": "count",
"points": [
{
"timestamp": "2026-09-28T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-09-29T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-09-30T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-01T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-02T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-03T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-04T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
}
]
}
},
{
"key": "net_quantity_change_7d",
"label": "Net quantity change · 7 days",
"value": 0,
"unit": "units",
"semantic": "gauge",
"aggregation": "sum",
"period": {
"start": "2026-09-28T00:00:00.000Z",
"end": "2026-10-04T05:46:35.855Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"value": "movement"
}
],
"series": {
"id": "net_quantity_change_7d",
"label": "Daily net quantity change",
"unit": "units",
"points": [
{
"timestamp": "2026-09-28T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-09-29T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-09-30T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-01T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-02T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-03T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-04T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
}
]
}
}
],
"appId": "app_topolo_inventory",
"serviceName": "Inventory",
"lastUpdated": "2026-10-04T05:46:35.874Z"
}
],
"workspace": {
"id": "ws_inventory_fixture",
"name": "Fixture inventory"
},
"workspaces": [
{
"id": "ws_inventory_fixture",
"name": "Fixture inventory",
"isDefault": true
}
]
}
HTTP 200. Check the workspace id matches the intended granted target and inspect widget state before using metrics. The movements metric counts the entire ledger; movement_volume_7d and net_quantity_change_7d cover seven UTC calendar dates. Counts do not prove notification delivery.
Another supported request
Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Notify/Nexus/archive transport. No live delivery, billing or environment deployment proof. Captured scenario: populated widget counts all movements.
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_inventory.widget.get --data @payload.json --json
topolo actions plan app_topolo_inventory.widget.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_inventory.widget.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json
MCP tool and arguments:
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_inventory.widget.get",
"input": {},
"resourceType": "workspace",
"resourceId": "<identifier returned by granted resource discovery>"
}
}
Captured local response · HTTP 200:
{
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_inventory",
"serviceName": "Inventory",
"generatedAt": "2026-10-04T05:46:37.297Z",
"widgets": [
{
"id": "inventory.workspace-summary",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Inventory operations",
"description": "SKU and location footprint with seven-day stock movement volume and net quantity change.",
"contexts": [
"organization",
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_inventory_fixture",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-04T05:46:37.281Z",
"lastSuccessfulAt": "2026-10-04T05:46:37.281Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 60,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": true,
"fields": [
{
"key": "metricKeys",
"label": "Measures",
"type": "multi-select",
"required": true,
"options": [
{
"value": "skus",
"label": "SKUs"
},
{
"value": "locations",
"label": "Locations"
},
{
"value": "movements",
"label": "Movements"
},
{
"value": "movements_7d",
"label": "Movements · 7 days"
},
{
"value": "net_quantity_change_7d",
"label": "Net quantity change · 7 days"
}
]
}
],
"defaults": {
"metricKeys": [
"skus",
"locations",
"movements_7d",
"net_quantity_change_7d"
]
}
},
"drilldowns": [
{
"id": "inventory",
"label": "View inventory",
"href": "/dashboard/inventory"
}
],
"controls": [
{
"id": "create-inventory-item",
"label": "Create inventory item",
"actionId": "app_topolo_inventory.items.create",
"resourceType": "workspace",
"resourceId": "ws_inventory_fixture",
"input": {},
"requiresConfirmation": true,
"destructive": false,
"effects": [
"Creates an inventory item in the active workspace at zero quantity on hand.",
"Derives the SKU from the name when sku is omitted, upper-cased and slugified.",
"Creates the workspace mirror row if this is the first record in the workspace."
],
"verification": [
"Expect 201 and read the created id from $.item.id.",
"Confirm $.item.quantityOnHand is 0 — a new item holds no stock until a movement is recorded.",
"Call items.list and confirm the SKU appears exactly once."
],
"recovery": {
"mode": "compensating_action",
"actionId": "app_topolo_inventory.items.archive",
"instructions": "Archive an item created in error. Items are never hard-deleted because their movement history explains every later quantity."
}
}
],
"localization": {
"locale": "en",
"titleKey": "inventory.widget.title",
"descriptionKey": "inventory.widget.summary"
},
"accessibility": {
"label": "Inventory workspace metrics",
"description": "SKU and location footprint with seven-day stock movement volume and net quantity change."
},
"contribution": {
"summary": "Inventory footprint and seven-day stock movement for the selected workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Inventory workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "skus",
"label": "SKUs",
"description": "Active inventory items in the selected workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "locations",
"label": "Locations",
"description": "Inventory locations in the selected workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "movements",
"label": "Movements",
"description": "Stock movements recorded in the selected workspace.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
},
{
"key": "movements_7d",
"label": "Movements · 7 days",
"description": "Stock movements recorded during the current seven-day period.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
},
{
"key": "net_quantity_change_7d",
"label": "Net quantity change · 7 days",
"description": "Net units added to or removed from inventory during the current seven-day period.",
"unit": "units",
"semantic": "gauge",
"aggregation": "sum"
}
],
"seriesDefinitions": [
{
"key": "movement_volume_7d",
"label": "Daily stock movements",
"metricKey": "movements_7d",
"unit": "count"
},
{
"key": "net_quantity_change_7d",
"label": "Daily net quantity change",
"metricKey": "net_quantity_change_7d",
"unit": "units"
}
],
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"description": "The Inventory workspace whose stock data is included.",
"valueType": "string"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"description": "Whether the measure describes catalogue footprint or stock movement.",
"valueType": "string"
}
],
"lifecycleStages": [],
"events": [],
"datasets": [
{
"id": "inventory_footprint",
"label": "Inventory footprint",
"description": "Active SKU and location footprint in the selected workspace.",
"grain": "One aggregate row per Inventory workspace and footprint measure.",
"metricKeys": [
"skus",
"locations"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"inventory_measure"
],
"eventKeys": [],
"actionIds": [
"create-inventory-item"
]
},
{
"id": "stock_movement",
"label": "Stock movement",
"description": "All-time movement count plus daily movement volume and net quantity change for the current seven-day period.",
"grain": "One aggregate row per Inventory workspace and movement measure, with daily series where declared.",
"metricKeys": [
"movements",
"movements_7d",
"net_quantity_change_7d"
],
"seriesKeys": [
"movement_volume_7d",
"net_quantity_change_7d"
],
"dimensionKeys": [
"workspace_scope",
"inventory_measure"
],
"eventKeys": [],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"line",
"area",
"bar",
"table",
"actions"
],
"defaultVisualization": "area"
},
"metrics": [
{
"key": "skus",
"label": "SKUs",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T05:46:37.281Z",
"end": "2026-10-04T05:46:37.281Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"value": "footprint"
}
]
},
{
"key": "locations",
"label": "Locations",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T05:46:37.281Z",
"end": "2026-10-04T05:46:37.281Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"value": "footprint"
}
]
},
{
"key": "movements",
"label": "Movements",
"value": 2,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-04T05:46:37.281Z",
"end": "2026-10-04T05:46:37.281Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"value": "movement"
}
]
},
{
"key": "movements_7d",
"label": "Movements · 7 days",
"value": 2,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-09-28T00:00:00.000Z",
"end": "2026-10-04T05:46:37.281Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"value": "movement"
}
],
"series": {
"id": "movement_volume_7d",
"label": "Daily stock movements",
"unit": "count",
"points": [
{
"timestamp": "2026-09-28T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-09-29T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-09-30T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-01T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-02T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-03T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-04T00:00:00.000Z",
"value": 2,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
}
]
}
},
{
"key": "net_quantity_change_7d",
"label": "Net quantity change · 7 days",
"value": 0,
"unit": "units",
"semantic": "gauge",
"aggregation": "sum",
"period": {
"start": "2026-09-28T00:00:00.000Z",
"end": "2026-10-04T05:46:37.281Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"value": "movement"
}
],
"series": {
"id": "net_quantity_change_7d",
"label": "Daily net quantity change",
"unit": "units",
"points": [
{
"timestamp": "2026-09-28T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-09-29T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-09-30T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-01T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-02T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-03T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-04T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
}
]
}
}
],
"appId": "app_topolo_inventory",
"serviceName": "Inventory",
"lastUpdated": "2026-10-04T05:46:37.297Z"
}
],
"workspace": {
"id": "ws_inventory_fixture",
"name": "Fixture inventory"
},
"workspaces": [
{
"id": "ws_inventory_fixture",
"name": "Fixture inventory",
"isDefault": true
}
]
}
HTTP 200. Check the workspace id matches the intended granted target and inspect widget state before using metrics. The movements metric counts the entire ledger; movement_volume_7d and net_quantity_change_7d cover seven UTC calendar dates. Counts do not prove notification delivery.
Another supported request
Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Notify/Nexus/archive transport. No live delivery, billing or environment deployment proof. Captured scenario: widget counts all 106 movements.
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_inventory.widget.get --data @payload.json --json
topolo actions plan app_topolo_inventory.widget.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_inventory.widget.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json
MCP tool and arguments:
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_inventory.widget.get",
"input": {},
"resourceType": "workspace",
"resourceId": "<identifier returned by granted resource discovery>"
}
}
Captured local response · HTTP 200:
{
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_inventory",
"serviceName": "Inventory",
"generatedAt": "2026-10-04T05:46:38.919Z",
"widgets": [
{
"id": "inventory.workspace-summary",
"version": "3.0.0",
"type": "stats",
"presentation": {
"title": "Inventory operations",
"description": "SKU and location footprint with seven-day stock movement volume and net quantity change.",
"contexts": [
"organization",
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_inventory_fixture",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-04T05:46:38.906Z",
"lastSuccessfulAt": "2026-10-04T05:46:38.906Z"
},
"refresh": {
"intervalSeconds": 60,
"timeoutSeconds": 10,
"maxAgeSeconds": 60,
"staleWhileRevalidateSeconds": 120
},
"configuration": {
"allowMultipleInstances": true,
"fields": [
{
"key": "metricKeys",
"label": "Measures",
"type": "multi-select",
"required": true,
"options": [
{
"value": "skus",
"label": "SKUs"
},
{
"value": "locations",
"label": "Locations"
},
{
"value": "movements",
"label": "Movements"
},
{
"value": "movements_7d",
"label": "Movements · 7 days"
},
{
"value": "net_quantity_change_7d",
"label": "Net quantity change · 7 days"
}
]
}
],
"defaults": {
"metricKeys": [
"skus",
"locations",
"movements_7d",
"net_quantity_change_7d"
]
}
},
"drilldowns": [
{
"id": "inventory",
"label": "View inventory",
"href": "/dashboard/inventory"
}
],
"controls": [
{
"id": "create-inventory-item",
"label": "Create inventory item",
"actionId": "app_topolo_inventory.items.create",
"resourceType": "workspace",
"resourceId": "ws_inventory_fixture",
"input": {},
"requiresConfirmation": true,
"destructive": false,
"effects": [
"Creates an inventory item in the active workspace at zero quantity on hand.",
"Derives the SKU from the name when sku is omitted, upper-cased and slugified.",
"Creates the workspace mirror row if this is the first record in the workspace."
],
"verification": [
"Expect 201 and read the created id from $.item.id.",
"Confirm $.item.quantityOnHand is 0 — a new item holds no stock until a movement is recorded.",
"Call items.list and confirm the SKU appears exactly once."
],
"recovery": {
"mode": "compensating_action",
"actionId": "app_topolo_inventory.items.archive",
"instructions": "Archive an item created in error. Items are never hard-deleted because their movement history explains every later quantity."
}
}
],
"localization": {
"locale": "en",
"titleKey": "inventory.widget.title",
"descriptionKey": "inventory.widget.summary"
},
"accessibility": {
"label": "Inventory workspace metrics",
"description": "SKU and location footprint with seven-day stock movement volume and net quantity change."
},
"contribution": {
"summary": "Inventory footprint and seven-day stock movement for the selected workspace.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Inventory workspace",
"supportsMultiple": false
},
"metricDefinitions": [
{
"key": "skus",
"label": "SKUs",
"description": "Active inventory items in the selected workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "locations",
"label": "Locations",
"description": "Inventory locations in the selected workspace.",
"unit": "count",
"semantic": "gauge",
"aggregation": "last"
},
{
"key": "movements",
"label": "Movements",
"description": "Stock movements recorded in the selected workspace.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
},
{
"key": "movements_7d",
"label": "Movements · 7 days",
"description": "Stock movements recorded during the current seven-day period.",
"unit": "count",
"semantic": "counter",
"aggregation": "count"
},
{
"key": "net_quantity_change_7d",
"label": "Net quantity change · 7 days",
"description": "Net units added to or removed from inventory during the current seven-day period.",
"unit": "units",
"semantic": "gauge",
"aggregation": "sum"
}
],
"seriesDefinitions": [
{
"key": "movement_volume_7d",
"label": "Daily stock movements",
"metricKey": "movements_7d",
"unit": "count"
},
{
"key": "net_quantity_change_7d",
"label": "Daily net quantity change",
"metricKey": "net_quantity_change_7d",
"unit": "units"
}
],
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"description": "The Inventory workspace whose stock data is included.",
"valueType": "string"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"description": "Whether the measure describes catalogue footprint or stock movement.",
"valueType": "string"
}
],
"lifecycleStages": [],
"events": [],
"datasets": [
{
"id": "inventory_footprint",
"label": "Inventory footprint",
"description": "Active SKU and location footprint in the selected workspace.",
"grain": "One aggregate row per Inventory workspace and footprint measure.",
"metricKeys": [
"skus",
"locations"
],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope",
"inventory_measure"
],
"eventKeys": [],
"actionIds": [
"create-inventory-item"
]
},
{
"id": "stock_movement",
"label": "Stock movement",
"description": "All-time movement count plus daily movement volume and net quantity change for the current seven-day period.",
"grain": "One aggregate row per Inventory workspace and movement measure, with daily series where declared.",
"metricKeys": [
"movements",
"movements_7d",
"net_quantity_change_7d"
],
"seriesKeys": [
"movement_volume_7d",
"net_quantity_change_7d"
],
"dimensionKeys": [
"workspace_scope",
"inventory_measure"
],
"eventKeys": [],
"actionIds": []
}
],
"compatibleVisualizations": [
"number",
"line",
"area",
"bar",
"table",
"actions"
],
"defaultVisualization": "area"
},
"metrics": [
{
"key": "skus",
"label": "SKUs",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T05:46:38.906Z",
"end": "2026-10-04T05:46:38.906Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"value": "footprint"
}
]
},
{
"key": "locations",
"label": "Locations",
"value": 1,
"unit": "count",
"semantic": "gauge",
"aggregation": "last",
"period": {
"start": "2026-10-04T05:46:38.906Z",
"end": "2026-10-04T05:46:38.906Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"value": "footprint"
}
]
},
{
"key": "movements",
"label": "Movements",
"value": 106,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-10-04T05:46:38.906Z",
"end": "2026-10-04T05:46:38.906Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"value": "movement"
}
]
},
{
"key": "movements_7d",
"label": "Movements · 7 days",
"value": 106,
"unit": "count",
"semantic": "counter",
"aggregation": "count",
"period": {
"start": "2026-09-28T00:00:00.000Z",
"end": "2026-10-04T05:46:38.906Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"value": "movement"
}
],
"series": {
"id": "movement_volume_7d",
"label": "Daily stock movements",
"unit": "count",
"points": [
{
"timestamp": "2026-09-28T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-09-29T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-09-30T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-01T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-02T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-03T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-04T00:00:00.000Z",
"value": 106,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
}
]
}
},
{
"key": "net_quantity_change_7d",
"label": "Net quantity change · 7 days",
"value": -103,
"unit": "units",
"semantic": "gauge",
"aggregation": "sum",
"period": {
"start": "2026-09-28T00:00:00.000Z",
"end": "2026-10-04T05:46:38.906Z",
"timezone": "UTC"
},
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
},
{
"key": "inventory_measure",
"label": "Inventory measure",
"value": "movement"
}
],
"series": {
"id": "net_quantity_change_7d",
"label": "Daily net quantity change",
"unit": "units",
"points": [
{
"timestamp": "2026-09-28T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-09-29T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-09-30T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-01T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-02T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-03T00:00:00.000Z",
"value": 0,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
},
{
"timestamp": "2026-10-04T00:00:00.000Z",
"value": -103,
"dimensions": [
{
"key": "workspace_scope",
"label": "Inventory workspace",
"value": "Fixture inventory"
}
]
}
]
}
}
],
"appId": "app_topolo_inventory",
"serviceName": "Inventory",
"lastUpdated": "2026-10-04T05:46:38.919Z"
}
],
"workspace": {
"id": "ws_inventory_fixture",
"name": "Fixture inventory"
},
"workspaces": [
{
"id": "ws_inventory_fixture",
"name": "Fixture inventory",
"isDefault": true
}
]
}
HTTP 200. Check the workspace id matches the intended granted target and inspect widget state before using metrics. The movements metric counts the entire ledger; movement_volume_7d and net_quantity_change_7d cover seven UTC calendar dates. Counts do not prove notification delivery.
Verify the result
- Check the workspace id matches the intended granted target and inspect widget state before using metrics.
- The movements metric counts the entire ledger; movement_volume_7d and net_quantity_change_7d cover seven UTC calendar dates. Counts do not prove notification delivery.
Errors and recovery
invalid_action_input(HTTP 400): Correct only the exact fields reported by the published schema validator. An invalid input can be refused before its handler.action_permission_required(HTTP 403): Stop when the verified credential lacks the published action permission. Resource identifiers and organization ownership do not grant that permission.
Auth, action-input validation and platform resource resolution can refuse a request before its handler. Retain the exact error, request id and context; requesting another context is not a legitimate way to bypass a refusal.
Recovery boundary
The read does not change local inventory records. No local rollback is needed; do not perform a mutation merely to reverse a read.
Related actions
- Get Inventory dashboard: Read active items, locations, low-stock items and recent ledger entries in the granted workspace. movementCount is the length of the latest 100 movement rows, and recentMovements contains at most ten.
Evidence
Captured exported Worker responses use both real local SQLite D1 databases with all six committed migrations, synthetic Auth/workspace grants and simulated Notify/Nexus/archive transport. They prove local handler shapes and scoped behavior, not live authorization, notification delivery, metering acceptance or environment deployment. Large 100-row list/capped-dashboard captures are retained in local evidence; committed tests verify those limits while worked guides use smaller complete responses. Capture digests and test scenarios are retained in the source fixture records.