gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/schema/connectors/apple-business-manager/handlers.py

@@ -0,0 +1,17 @@
+"""Read-only tools over Apple Business Manager organization devices.
+
+The depth template intentionally ships no production-write mimic because Apple
+offers no sandbox; all broad entities are available through ``gateway_env.store``.
+"""
+
+from gateway_env import store, tool
+
+
+@tool(name="list_org_devices")
+def list_org_devices():
+    return store.list("abm_org_devices")
+
+
+@tool(name="get_org_device")
+def get_org_device(id):
+    return store.get("abm_org_devices", {"id": id})

gatewaysdk/environment/schema/connectors/apple-business-manager/parity.json

@@ -0,0 +1,28 @@
+{
+  "version": 1,
+  "connector": "apple-business-manager",
+  "status": "subset",
+  "world_tools": ["get_org_device", "list_org_devices"],
+  "registration": {
+    "mode": "schema_only",
+    "provider": "none",
+    "managed_tool_allowlist": []
+  },
+  "surfaces": [
+    {
+      "name": "Apple Business Manager API",
+      "kind": "official_api",
+      "auth": "OAuth 2 client credentials with ES256 client assertion",
+      "manifest_validation": "documentation_only",
+      "supported_world_tools": ["get_org_device", "list_org_devices"],
+      "limitations": [
+        "No first-party MCP server or static MCP manifest was identified.",
+        "Gateway does not yet implement organization API-account and private-key authentication.",
+        "The world returns entities rather than JSON:API transport envelopes."
+      ],
+      "evidence": [
+        "https://developer.apple.com/documentation/applebusinessmanagerapi"
+      ]
+    }
+  ]
+}

gatewaysdk/environment/schema/connectors/apple-business-manager/provenance.json

@@ -0,0 +1,233 @@
+{
+  "connector": "apple-business-manager",
+  "shape": "base",
+  "label": "subset",
+  "generated_at": "2026-09-06T22:27:40Z",
+  "authored_by": "connector-template-author; hand-authored from pinned Apple DocC JSON because no importer exists",
+  "source": {
+    "kind": "docs",
+    "format": "vendor-docc-json",
+    "url": "https://developer.apple.com/documentation/applebusinessapi",
+    "version": "Apple Business API 2.4 (2026-08-26 changelog)",
+    "sha256": "2db67973e8a5661fd1ad114edafa7e07b09c1daf066bfffe0b5515fd2546c9e7",
+    "retrieved_at": "2026-09-06T21:25:00Z",
+    "note": "Apple publishes no downloadable OAS URL. These are the machine-readable vendor documents rendered by developer.apple.com.",
+    "documents": [
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi.json",
+        "sha256": "2db67973e8a5661fd1ad114edafa7e07b09c1daf066bfffe0b5515fd2546c9e7"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/apple-school-and-business-manager-api/apple-school-manager-and-apple-business-api-changelog.json",
+        "sha256": "ec880e21e4c019d4220fcefdc7e5f01812f36a0fb87221fa1bb371750efa51e9"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/orgdevice/attributes-data.dictionary.json",
+        "sha256": "7906c33a8d312663f8952ff68a2f1197f70a00e7858c00d2ee6c0f8d7f489ce8"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/orgdevice/relationships-data.dictionary.json",
+        "sha256": "9cdb50cfce67a7e4301d65da74f173c1972220be1d9e268103b34c5f2f6b3508"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/applecarecoverage/attributes-data.dictionary.json",
+        "sha256": "0884aa17689f0fcbc01e06c157548ce1c3f9e44dda4827ddcf5c28a9aa161323"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/applecarecoveragestatus.json",
+        "sha256": "b807e0798eb817c7e5e9a674c706f691d8077574ea1608efed7562f0c1a96300"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/applecarecoveragepaymenttype.json",
+        "sha256": "11ce37a44d56ac5cbb2f12869cb709e074b39e41dc03b0de1db9771bf45403ee"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/get-all-applecare-coverage-for-an-orgdevice.json",
+        "sha256": "db97e44de0055908a1128ccb2cb68737941455ea5b33ec80ae3e41cc59622c37"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/mdmdevice/attributes-data.dictionary.json",
+        "sha256": "02685ac7842bfcd047dcfd26d36bfbd30392b4c49c146efaa31b6562d1e0b4e3"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/mdmdevicedetail/attributes-data.dictionary.json",
+        "sha256": "47ecd2aefa8982acce6ec8eac4bb1cd1f1a5acda984f9440456b4fa058bab18b"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/get-apple-mdm-enrolled-devices.json",
+        "sha256": "7727008e4ab577ff3c0ad28d77ed63d9342b3a2077bb3d5d6ce01812d2bafa6e"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/get-the-details-for-apple-mdm-enrolled-device.json",
+        "sha256": "a422e0da6499ce7d8ce96f3a5e72ff461f317b8daada127b368a000775530682"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/deviceerasestatus.json",
+        "sha256": "ea0fffd8fe4bf36c86d1b94195deaec0421a167952950aae9e4eee05cce79242"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/devicelockstatus.json",
+        "sha256": "9033edb204fe440a35fb51cd2c34be8a3e3f55380352c0503e251e4862dfbe45"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/lostmodestatus.json",
+        "sha256": "1f10f04522ca6152ff105c20884aff614c0025e2ec56cb5159b7ad60827572c0"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/mdmserver/attributes-data.dictionary.json",
+        "sha256": "8afa43350224afc3050c32aa476780ac85056fd83927e95a5334fa1dae32cc3b"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/mdmserverstatus.json",
+        "sha256": "bb764715e852054c444e0f592892aa8c6cfd42f4176ee698ce7de0a4023b4b70"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/mdmserverproductfamily.json",
+        "sha256": "e68adf180c1f3519aeec2218fe3af6b4a10a543f74a11ce36e6cb5f3dd905c2b"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/orgdeviceactivity/attributes-data.dictionary.json",
+        "sha256": "903caf5ffa61222fac512ce1dc3318582f354bae130fe650a670fa7e05601f3a"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/orgdeviceactivitycreaterequest/data-data.dictionary/relationships-data.dictionary.json",
+        "sha256": "b851d9a2092e576fdd845609ce526973c00f5585a487348bb29340309aa93af3"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/user/attributes-data.dictionary.json",
+        "sha256": "e4c7c293f2feca6f90215107455c47ac18267fbbc5204b8a4aa7ead695075811"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/userstatus.json",
+        "sha256": "e4d6518e1483b6679704aef2f36e3eb95910e1893e0b69ccfff8daf696ecae9a"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/userphonenumbertype.json",
+        "sha256": "aeb450659fb72dc801ccec89deba8a992d3f35475dd60fa20b746cf5041b6786"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/usergroup/attributes-data.dictionary.json",
+        "sha256": "31911d11ebc15acc19ef013ba854208826288921c82624c6592f6cb3638d263d"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/usergroup/relationships-data.dictionary.json",
+        "sha256": "67d0903c57c3a74578fda8908739f22d45fbf2b010562b3cedca20bd6a510d00"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/usergrouptype.json",
+        "sha256": "229b19f93d1156802700f0d8889ebb92e3829fdc583513c35450d8c5e7d067ba"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/usergroupstatus.json",
+        "sha256": "b0e73af8716135940c5d7601adadca7301966012c4cc1e4dcb55ad996bf58ad4"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/organizationalunit/attributes-data.dictionary.json",
+        "sha256": "8202c6ef66f257c859d9e00fcb7b46f2105c21cfcab0d1e2542edde925dac718"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/organizationalunit/relationships-data.dictionary.json",
+        "sha256": "2aa6636ff60e7e6e9016e5086b8b7bb29673d6bee0d3f674e179843949f40e7e"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/blueprint/attributes-data.dictionary.json",
+        "sha256": "bd2714aacc986e03532fcf9e803ac4ad4463f8bcdf1ebb43459e43d9ece8e948"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/blueprint/relationships-data.dictionary.json",
+        "sha256": "808b014c3c1248e88302bb2d653706d26ff9e4b68b4e889a0083f2e685dc393f"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/blueprintstatus.json",
+        "sha256": "2e09f0580b50dc7ad6213fb2b721835989e32dff46e71de365c60d2f22a3e61e"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/configurationcommon.json",
+        "sha256": "0e968f28bd1f9b873d11e3c1b945290c96054e3ff5f3004c15a01c8780b6ad35"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/configurationcustomsetting.json",
+        "sha256": "542674dc488da67dcc10ac65d490fd86793271b935fe603765f5ab4cf004ec6c"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/customsettingsvalues.json",
+        "sha256": "5936a5ccba1feda237981d5a0f15ce9b2c226354b30f78be5460321a9fa36bdd"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/configurationtype.json",
+        "sha256": "0d4873fc9a854a754377e3f35676110c82ed77ef4447d86a397a98a476fee32f"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/configurationplatform.json",
+        "sha256": "e29b4fcd8c85162b968f20a7a8e84c26a1108f0d7d088330517bde30570ab349"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/get-configurations.json",
+        "sha256": "082b2435861c2adf99b43dd8bd9f07fdb1b333f3038b902562ad0e680fa6d848"
+      },
+      {
+        "url": "https://developer.apple.com/tutorials/data/documentation/applebusinessapi/get-configuration-information.json",
+        "sha256": "b014d53e90179739b3b0114339452d1ebd9337f52cbb8da728312ae5cd80c0e8"
+      }
+    ]
+  },
+  "world_hash": "e82af371927662648c6e9854aed422becdb72b46c886e4cb755b31f6ed1672bb",
+  "scope_hash": "c33a06e32ecb6d06f18e6f4b61b4e98e92540ca11f265a841968f4b650b3406f",
+  "coverage": {
+    "entities": 18,
+    "recursive_fields": 159,
+    "areas": [
+      "organization devices",
+      "AppleCare coverage",
+      "Apple MDM enrolled-device summary and detail reads",
+      "device management services and assignment",
+      "organization-device activities and device linkage",
+      "users",
+      "user groups and membership",
+      "organizational units and membership",
+      "blueprints",
+      "configurations",
+      "blueprint configuration/device/user/user-group linkages"
+    ],
+    "excluded": [
+      "apps and packages",
+      "blueprint app/package linkages",
+      "audit events",
+      "write request bodies and behavior",
+      "JSON:API transport envelopes"
+    ]
+  },
+  "label_reasons": [
+    "The model is a broad read-only subset, not the full API: apps, packages, audit-event variants, and write behavior are excluded.",
+    "Apple has no developer sandbox. No tenant round trip or golden replay ran; both are skipped, not passed.",
+    "Nested scalar relationships are enforced where they resolve to one target. Array traversal and vendor-unasserted uniqueness remain outside this contract."
+  ],
+  "fidelity_decisions": [
+    "Resource id and type retain Apple requiredness; attributes remains optional so sparse fieldset responses validate.",
+    "MdmDevice and MdmDeviceDetail are two read forms for the same endpoint ID and use union-properties/intersection-required; both declared type literals validate.",
+    "ConfigurationCommon and ConfigurationCustomSetting fields share nested attributes. customSettingsValues accepts null collection form or the documented detail object; attributes.type is required only when attributes is present.",
+    "Only DocC possibleValues/allowedValues blocks become enums. Prose-only lists for organization-device, MDM-server type, and activity statuses remain open strings.",
+    "AppleCare nullable example values are nullable rather than merely optional.",
+    "Linkage endpoint context is represented with snake_case containment IDs; all vendor-owned fields retain casing and nesting.",
+    "The prior assignedDateTime field and write handler were removed: Apple linkage responses declare no timestamp, and the former value was invented from activity creation time."
+  ],
+  "fields_excluded": [
+    "OrgDevice.Attributes.eid: peripheral identifier outside this subset.",
+    "OrgDevice.Attributes.purchaseSourceId/purchaseSourceUid: the schema dictionary and GET example disagree; accepting only either spelling would reject another vendor-declared read form."
+  ],
+  "compiler_limitations": [
+    "Nested enrolledUserId and user-group ouId relationships are enforced without flattening. User roleOuList[].ouId remains unenforced because paths do not traverse arrays; serialNumber and serverName uniqueness is not asserted without vendor evidence.",
+    "MdmDevice and MdmDeviceDetail resource type correlation with their respective attribute subsets cannot be expressed as a keyed entity union; the union accepts the vendor properties and both declared discriminators."
+  ],
+  "checks": {
+    "schema_compile": "passed on /home/ubuntu/apple-business-manager-connector-verify; domain hash 0e874cb3cb01192e9bf7070c6779fc1a9ab8ef49cbdd30a2c419ec5f47a00109",
+    "schema_check": "passed on /home/ubuntu/apple-business-manager-connector-verify; domain hash 0e874cb3cb01192e9bf7070c6779fc1a9ab8ef49cbdd30a2c419ec5f47a00109",
+    "tenant_round_trip": "skipped: no sandbox",
+    "golden_replay": "skipped: no syntheticized capture"
+  },
+  "data": {
+    "synthetic": true,
+    "vendor_or_customer_data": "none",
+    "fixtures": "none: connector template layout does not support fixture data"
+  }
+}

gatewaysdk/environment/schema/connectors/apple-business-manager/scope.toml

@@ -0,0 +1,112 @@
+# Apple Business Manager base read-only subset, reconstructed from Apple Business API 2.4 DocC JSON.
+
+[source]
+kind = "docs"
+api = "Apple Business API"
+version = "2.4"
+base_url = "https://api-business.apple.com/v1"
+machine_readable = "vendor-docc-json"
+
+[coverage]
+label = "subset"
+entity_count = 18
+recursive_field_count = 159
+round_trip = "skipped: Apple provides no developer sandbox; our ABM organization is production"
+golden_replay = "skipped: no syntheticized tenant capture is available"
+
+[allowlist]
+abm_org_devices = "OrgDevice, with nested attributes"
+abm_applecare_coverages = "AppleCareCoverage scoped by org device"
+abm_mdm_devices = "union-properties/intersection-required model of MdmDevice and MdmDeviceDetail reads"
+abm_mdm_servers = "MdmServer"
+abm_device_assignments = "OrgDevice assignedServer linkage"
+abm_activities = "OrgDeviceActivity read resource"
+abm_activity_devices = "OrgDeviceActivity create-request devices linkage"
+abm_users = "User, including nested roleOuList and phoneNumbers"
+abm_user_groups = "UserGroup"
+abm_user_group_memberships = "UserGroup users linkage"
+abm_organizational_units = "OrganizationalUnit"
+abm_organizational_unit_memberships = "OrganizationalUnit users linkage"
+abm_blueprints = "Blueprint"
+abm_configurations = "ConfigurationCommon plus ConfigurationCustomSetting read forms"
+abm_blueprint_configurations = "Blueprint configurations linkage"
+abm_blueprint_devices = "Blueprint orgDevices linkage"
+abm_blueprint_users = "Blueprint users linkage"
+abm_blueprint_user_groups = "Blueprint userGroups linkage"
+
+[keys]
+abm_org_devices = ["id"]
+abm_applecare_coverages = ["org_device_id", "id"]
+abm_mdm_devices = ["id"]
+abm_mdm_servers = ["id"]
+abm_device_assignments = ["device_id", "mdm_server_id"]
+abm_activities = ["id"]
+abm_activity_devices = ["activity_id", "device_id"]
+abm_users = ["id"]
+abm_user_groups = ["id"]
+abm_user_group_memberships = ["user_group_id", "user_id"]
+abm_organizational_units = ["id"]
+abm_organizational_unit_memberships = ["organizational_unit_id", "user_id"]
+abm_blueprints = ["id"]
+abm_configurations = ["id"]
+abm_blueprint_configurations = ["blueprint_id", "configuration_id"]
+abm_blueprint_devices = ["blueprint_id", "device_id"]
+abm_blueprint_users = ["blueprint_id", "user_id"]
+abm_blueprint_user_groups = ["blueprint_id", "user_group_id"]
+
+[requiredness]
+resource_roots = "Only id and type are required, matching Apple's declarations and sparse-fieldset reads."
+attributes = "Nested attributes sections are optional. Configuration attributes requires type only when the whole section is present."
+linkages = "Endpoint containment IDs and linkage IDs are required because they form the linkage fact."
+
+[relationships]
+represented = [
+  "AppleCareCoverage -> OrgDevice endpoint containment",
+  "OrgDevice -> MdmServer assignedServer",
+  "OrgDeviceActivity -> OrgDevice devices",
+  "MdmDevice.attributes.enrolledUserId -> User",
+  "UserGroup.attributes.ouId -> OrganizationalUnit",
+  "UserGroup -> User memberships",
+  "OrganizationalUnit -> User memberships",
+  "Blueprint -> Configuration, OrgDevice, User, and UserGroup linkages",
+]
+nested_not_enforced = [
+  "User.attributes.roleOuList[].ouId -> abm_organizational_units",
+]
+
+[compiler_limitations]
+nested_relationships = "Nested scalar paths are supported and enrolledUserId/ouId are enforced. roleOuList[].ouId remains unenforced because relationship paths do not traverse arrays."
+nested_uniqueness = "Nested scalar uniqueness is supported, but serialNumber and serverName are not declared unique by the pinned DocC schemas and are therefore not asserted."
+mdm_read_forms = "MdmDevice and MdmDeviceDetail share one entity keyed by endpoint ID; the schema uses the union of properties and intersection of required fields, with both declared resource type values."
+configuration_read_forms = "Collection reads return customSettingsValues as null; detail reads may return the nested object. Both validate."
+
+[excluded]
+App = "Content metadata is outside this identity/device/configuration subset; consequently blueprint app linkage is excluded."
+Package = "Package metadata is outside this subset; consequently blueprint package linkage is excluded."
+AuditEvent = "The large polymorphic audit-event family is a separate event model and is not represented as state."
+BlueprintApps = "Target App entity is excluded; no unresolved relationship is fabricated."
+BlueprintPackages = "Target Package entity is excluded; no unresolved relationship is fabricated."
+transport = "JSON:API links, meta, paging, and response envelopes are transport rather than persisted entities."
+write_requests = "Create/update request bodies and side effects are excluded from this read-only subset; vendor writes are real production writes without a sandbox."
+
+[fields_excluded]
+"OrgDevice.Attributes.eid" = "Peripheral cellular identifier omitted from this subset; IMEI and MEID remain represented."
+"OrgDevice.Attributes.purchaseSourceId" = "Apple's declared dictionary says purchaseSourceId while its own GET example emits purchaseSourceUid. Neither spelling is accepted until vendor evidence resolves the conflict; accepting one would reject the other legal read form."
+"*.links" = "JSON:API transport."
+"*.meta" = "JSON:API paging transport."
+
+[enum_policy]
+declared = "Closed enums come only from DocC possibleValues or allowedValues blocks."
+open_strings = ["OrgDevice.productFamily", "OrgDevice.status", "OrgDevice.purchaseSourceType", "MdmServer.serverType", "OrgDeviceActivity.status", "OrgDeviceActivity.subStatus"]
+reason = "Apple lists these values only in prose, so closing them would over-constrain future legal vendor values."
+
+[sandbox]
+available = false
+tenant_requirement = "A consenting Apple Business Manager production organization with real Apple devices is required for round-trip evidence."
+seed_policy = "Do not seed: Apple exposes writes, but they affect production and Apple provides no developer sandbox."
+customer_data = "none committed"
+
+[tools]
+mode = "read-only"
+served = ["list_org_devices", "get_org_device"]
+write_tools = "none: assign_devices was removed because its prior flattened request shape and invented assignedDateTime were not vendor-faithful"