gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/schema/connectors/kandji/scope.toml

@@ -0,0 +1,120 @@
+# Scope for the kandji (Iru Endpoint Management) template.
+#
+# Hand-transcribed from the vendor's published API documentation; the `docs`
+# importer does not exist yet (skill tooling table, A2/A3). This file records
+# what the model covers and why everything else is out, so a future importer
+# run can reproduce the same selection.
+
+[source]
+kind = "docs"
+url = "https://api-docs.kandji.io/"
+resolved_url = "https://api-docs.iru.com/"
+collection = "336d6648-e062-4cbd-a70a-2a0c276cd4ad"
+collection_url = "https://api-docs.iru.com/api/collections/15284493/TzCTZkBe?segregateAuth=true&versionTag=latest"
+collection_sha256 = "cc323f7dd4052a6a6fa7882d8a45596b0144f5b31a8d890c7c77c3e1a9882119"
+
+# Entities in the model, with the vendor operation each was transcribed from.
+[entities.kandji_devices]
+operations = ["GET /api/v1/devices", "GET /api/v1/devices/{device_id}"]
+key = ["device_id"]
+reason = "The connector's subject: enrolled hardware and its blueprint and user assignment."
+
+[entities.kandji_blueprints]
+operations = ["GET /api/v1/blueprints", "GET /api/v1/blueprints/{blueprint_id}"]
+key = ["id"]
+reason = "Every device carries a blueprint_id; assignment is the write this world models."
+
+[entities.kandji_library_items]
+operations = [
+  "GET /api/v1/blueprints/{blueprint_id}/list-library-items",
+  "GET /api/v1/devices/{device_id}/library-items",
+]
+key = ["id"]
+reason = "What a blueprint delivers to a device. The definition read supplies id/name; the device-status read supplies type and optional status/audit fields after item_id is mapped to the definition id."
+
+[entities.kandji_blueprint_items]
+operations = [
+  "GET /api/v1/blueprints/{blueprint_id}/list-library-items",
+  "POST /api/v1/blueprints/{blueprint_id}/assign-library-item",
+]
+key = ["blueprint_id", "library_item_id"]
+reason = "Blueprint-to-library-item is many-to-many; modelled as its own entity, including the optional assignment_node_id accepted for Assignment Maps."
+
+[entities.kandji_users]
+operations = ["GET /api/v1/users", "GET /api/v1/users/{user_id}"]
+key = ["id"]
+reason = "Directory-integration users; the target of a device's user assignment."
+
+[entities.kandji_tags]
+operations = ["GET /api/v1/tags", "POST /api/v1/tags"]
+key = ["id"]
+reason = "Tags are a first-class tenant object with their own CRUD endpoints."
+
+[entities.kandji_device_tags]
+operations = ["GET /api/v1/devices", "PATCH /api/v1/devices/{device_id}"]
+key = ["device_id", "tag_id"]
+reason = "Device-to-tag is many-to-many; the vendor denormalizes it as a name array on the device, which this model normalizes."
+
+[entities.kandji_device_apps]
+operations = ["GET /api/v1/devices/{device_id}/apps"]
+key = ["device_id", "bundle_id"]
+reason = "Installed-app inventory for the Mac/iPhone/iPad response form, including every field in that returned app section. Windows and Android use incompatible key/property sets and are excluded below."
+
+# Fields carried on an entity that the vendor returns in a different shape.
+[key_overrides]
+"kandji_library_items.id" = "GET .../list-library-items returns id directly; GET .../devices/{device_id}/library-items calls the same identifier item_id. Status fields are optional because the definition form returns only id/name."
+"kandji_device_apps.device_id" = "Supplied by the response envelope; the nested Apple-family app objects do not repeat it."
+"kandji_device_tags.tag_id" = "Resolved from the tag names the device response carries; the vendor exposes tag ids only through GET /api/v1/tags."
+
+[relationship_hints]
+"kandji_devices.blueprint_id" = "kandji_blueprints.id"
+"kandji_devices./user/id" = "kandji_users.id; the non-object empty-string branch is treated as an absent optional relationship."
+"kandji_blueprint_items.blueprint_id" = "kandji_blueprints.id"
+"kandji_blueprint_items.library_item_id" = "kandji_library_items.id"
+"kandji_device_tags.device_id" = "kandji_devices.device_id"
+"kandji_device_tags.tag_id" = "kandji_tags.id"
+"kandji_device_apps.device_id" = "kandji_devices.device_id"
+
+# The device user remains vendor-shaped. The nested relationship resolves only
+# on the object branch; the vendor's empty-string sentinel remains unassigned.
+polymorphic = ["kandji_devices.user: DeviceUser object or the vendor's empty-string unassigned sentinel"]
+
+[compiler_limitations]
+"kandji_devices.user.id" = "Declared as /user/id -> kandji_users; the compiler treats the empty-string branch as absent without flattening the vendor object."
+"kandji_device_apps" = "The endpoint has Apple, Windows, and Android object forms with different identifiers. Entity roots cannot use composition and primary keys cannot vary by branch, so this base subset models only the Apple-family form keyed by (device_id, bundle_id)."
+"kandji_library_items" = "The device-status form is per-device, but the fixed eight-entity base subset has no separate device-library-status entity. Only its scalar status/audit fields are retained as optional definition fields; nested computer, blueprint, and edr_status sections are excluded."
+
+# Everything the vendor publishes that this template deliberately leaves out.
+[exclusions]
+"GET /api/v1/devices/{device_id} Windows/Android additions" = "api_level, full_software_version, and security_patch_level are tenant-enablement-dependent additions. The base summary keeps the fields common to the documented device forms; add these through a future expanded base version."
+"GET /api/v1/devices/{device_id}/details" = "Hundreds of platform-conditional inventory fields (hardware, network, security, volumes); a per-platform detail model is its own template-sized job and none of it is needed to reason about assignment."
+"GET /api/v1/prism/*" = "Prism is a reporting projection over device details, not a distinct source of record; modelling it would duplicate the detail model."
+"GET /api/v1/devices/{device_id}/parameters" = "Compliance parameter results; depends on the detail model above."
+"GET /api/v1/devices/{device_id}/status" = "Derived roll-up of library-item and parameter status."
+"GET /api/v1/devices/{device_id}/activity" = "Event stream; event entities are a separate scope decision, and the world has no clock control yet."
+"GET /api/v1/devices/{device_id}/notes" = "Free-text annotations, orthogonal to the assignment model."
+"GET /api/v1/devices/{device_id}/commands" = "MDM command queue; this world models state, not in-flight commands."
+"POST /api/v1/devices/{device_id}/action/*" = "Device actions have side effects on real hardware with no state this model holds."
+"GET /api/v1/devices/{device_id}/secrets/*" = "FileVault keys, bypass codes and unlock pins; secrets never enter a shared template."
+"GET /api/v1/devices/{device_id}/apps Windows and Android forms" = "The forms use product_code/name and package_name rather than bundle_id and have disjoint properties. The compiler cannot express their polymorphic keys on one entity; this subset retains the complete Apple-family app form."
+"GET /api/v1/devices/{device_id}/library-items nested sections" = "computer, blueprint, and edr_status are omitted rather than flattened. Faithfully modelling per-device status needs a ninth device-library-status entity, a shared-scope change for a later model version."
+"GET /api/v1/library/custom-apps|ipa-apps|custom-profiles|custom-scripts" = "Per-type library item detail; the shared definition/status projection is what blueprint assignment needs, and the vendor publishes no single list-all endpoint."
+"GET /api/v1/integrations/apple/ade/*" = "Automated Device Enrollment tokens and pre-enrollment devices; a distinct lifecycle that overlaps Apple Business Manager."
+"GET /api/v1/threat-details, /api/v1/behavioral-detections" = "EDR findings; a security-event model, not device management state."
+"GET /api/v1/vulnerability-management/*" = "CVE and detection data sourced from outside the tenant's own device model."
+"GET /api/v1/audit/events" = "Audit log; event entity, same reasoning as device activity."
+"GET /api/v1/settings/licensing" = "Single tenant-wide settings object with no relationships."
+"GET /api/v1/self-service/categories" = "Self Service presentation metadata."
+
+[sandbox]
+availability = "Account-team provisioned only; no sandbox or tenant credentials were available for this reconstruction."
+seedable = ["blueprints", "library items", "users", "tags"]
+not_seedable = ["devices"]
+round_trip = "skipped: no authorized tenant"
+goldens = "none: no tenant capture and no customer data may be committed"
+
+[fidelity]
+shape = "base"
+label = "subset"
+mimic = false
+reason = "Primary vendor examples support the authored fields, but Windows/Android app forms, platform detail, sandbox replay, and goldens remain absent."