gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/schema/connectors/jira/handlers.py

@@ -0,0 +1,28 @@
+"""Jira world tools; every mutation goes through the schema store."""
+
+from gateway_env import store, tool
+
+
+@tool(name="search_issues")
+def search_issues(project_key, status=None):
+    issues = [i for i in store.list("jira_issues") if i["project_key"] == project_key]
+    return [i for i in issues if status is None or i["status"] == status]
+
+
+@tool(name="transition_issue")
+def transition_issue(transition):
+    issue = store.get("jira_issues", {"key": transition["issue_key"]})
+    if issue is None or issue["status"] != transition["from_status"]:
+        raise ValueError("invalid_transition: the issue is not in from_status")
+    store.insert("jira_transitions", transition, source={"record": "tool.transition_issue"})
+    return store.update(
+        "jira_issues",
+        {"key": transition["issue_key"]},
+        {"status": transition["to_status"]},
+        source={"record": "tool.transition_issue"},
+    )
+
+
+@tool(name="add_comment")
+def add_comment(comment):
+    return store.insert("jira_comments", comment, source={"record": "tool.add_comment"})

gatewaysdk/environment/schema/connectors/jira/world.json

@@ -0,0 +1,389 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:gateway:connector:jira",
+  "$defs": {
+    "Project": {
+      "type": "object",
+      "properties": {
+        "key": {
+          "$ref": "base.json#/$defs/Label"
+        },
+        "name": {
+          "$ref": "base.json#/$defs/Label"
+        },
+        "lead_id": {
+          "$ref": "base.json#/$defs/Id"
+        }
+      },
+      "required": [
+        "key",
+        "name",
+        "lead_id"
+      ],
+      "additionalProperties": false
+    },
+    "User": {
+      "type": "object",
+      "properties": {
+        "account_id": {
+          "$ref": "base.json#/$defs/Id"
+        },
+        "display_name": {
+          "$ref": "base.json#/$defs/Label"
+        },
+        "email": {
+          "anyOf": [
+            {
+              "$ref": "base.json#/$defs/Email"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "account_id",
+        "display_name"
+      ],
+      "additionalProperties": false
+    },
+    "Issue": {
+      "type": "object",
+      "properties": {
+        "key": {
+          "$ref": "base.json#/$defs/Label"
+        },
+        "project_key": {
+          "$ref": "base.json#/$defs/Label"
+        },
+        "summary": {
+          "$ref": "base.json#/$defs/Label"
+        },
+        "description": {
+          "anyOf": [
+            {
+              "$ref": "base.json#/$defs/Text"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "issue_type": {
+          "type": "string",
+          "enum": [
+            "Task",
+            "Bug",
+            "Story",
+            "Epic"
+          ]
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "To Do",
+            "In Progress",
+            "In Review",
+            "Done"
+          ]
+        },
+        "priority": {
+          "type": "string",
+          "enum": [
+            "Lowest",
+            "Low",
+            "Medium",
+            "High",
+            "Highest"
+          ]
+        },
+        "assignee_id": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "reporter_id": {
+          "$ref": "base.json#/$defs/Id"
+        },
+        "created_at": {
+          "$ref": "base.json#/$defs/Timestamp"
+        }
+      },
+      "required": [
+        "key",
+        "project_key",
+        "summary",
+        "issue_type",
+        "status",
+        "priority",
+        "reporter_id",
+        "created_at"
+      ],
+      "additionalProperties": false
+    },
+    "Comment": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "$ref": "base.json#/$defs/Id"
+        },
+        "issue_key": {
+          "$ref": "base.json#/$defs/Label"
+        },
+        "author_id": {
+          "$ref": "base.json#/$defs/Id"
+        },
+        "body": {
+          "$ref": "base.json#/$defs/Text"
+        },
+        "created_at": {
+          "$ref": "base.json#/$defs/Timestamp"
+        }
+      },
+      "required": [
+        "id",
+        "issue_key",
+        "author_id",
+        "body",
+        "created_at"
+      ],
+      "additionalProperties": false
+    },
+    "Transition": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "$ref": "base.json#/$defs/Id"
+        },
+        "issue_key": {
+          "$ref": "base.json#/$defs/Label"
+        },
+        "actor_id": {
+          "$ref": "base.json#/$defs/Id"
+        },
+        "from_status": {
+          "type": "string",
+          "enum": [
+            "To Do",
+            "In Progress",
+            "In Review",
+            "Done"
+          ]
+        },
+        "to_status": {
+          "type": "string",
+          "enum": [
+            "To Do",
+            "In Progress",
+            "In Review",
+            "Done"
+          ]
+        },
+        "at": {
+          "$ref": "base.json#/$defs/Timestamp"
+        }
+      },
+      "required": [
+        "id",
+        "issue_key",
+        "actor_id",
+        "from_status",
+        "to_status",
+        "at"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "x-gateway": {
+    "version": 1,
+    "domain_version": "1.0.0",
+    "package": {
+      "id": "gateway-connector-jira",
+      "version": "1.0.0"
+    },
+    "entities": {
+      "jira_projects": {
+        "schema": {
+          "$ref": "#/$defs/Project"
+        },
+        "primary_key": [
+          "key"
+        ],
+        "unique": [],
+        "relationships": [
+          {
+            "fields": [
+              "lead_id"
+            ],
+            "target": "jira_users",
+            "on_delete": "restrict"
+          }
+        ]
+      },
+      "jira_users": {
+        "schema": {
+          "$ref": "#/$defs/User"
+        },
+        "primary_key": [
+          "account_id"
+        ],
+        "unique": [],
+        "relationships": []
+      },
+      "jira_issues": {
+        "schema": {
+          "$ref": "#/$defs/Issue"
+        },
+        "primary_key": [
+          "key"
+        ],
+        "unique": [],
+        "relationships": [
+          {
+            "fields": [
+              "project_key"
+            ],
+            "target": "jira_projects",
+            "on_delete": "restrict"
+          },
+          {
+            "fields": [
+              "assignee_id"
+            ],
+            "target": "jira_users",
+            "on_delete": "restrict"
+          },
+          {
+            "fields": [
+              "reporter_id"
+            ],
+            "target": "jira_users",
+            "on_delete": "restrict"
+          }
+        ]
+      },
+      "jira_comments": {
+        "schema": {
+          "$ref": "#/$defs/Comment"
+        },
+        "primary_key": [
+          "id"
+        ],
+        "unique": [],
+        "relationships": [
+          {
+            "fields": [
+              "issue_key"
+            ],
+            "target": "jira_issues",
+            "on_delete": "restrict"
+          },
+          {
+            "fields": [
+              "author_id"
+            ],
+            "target": "jira_users",
+            "on_delete": "restrict"
+          }
+        ]
+      },
+      "jira_transitions": {
+        "schema": {
+          "$ref": "#/$defs/Transition"
+        },
+        "primary_key": [
+          "id"
+        ],
+        "unique": [],
+        "relationships": [
+          {
+            "fields": [
+              "issue_key"
+            ],
+            "target": "jira_issues",
+            "on_delete": "restrict"
+          },
+          {
+            "fields": [
+              "actor_id"
+            ],
+            "target": "jira_users",
+            "on_delete": "restrict"
+          }
+        ]
+      }
+    },
+    "tools": {
+      "search_issues": {
+        "input": {
+          "type": "object",
+          "properties": {
+            "project_key": {
+              "$ref": "base.json#/$defs/Label"
+            },
+            "status": {
+              "type": "string",
+              "enum": [
+                "To Do",
+                "In Progress",
+                "In Review",
+                "Done"
+              ]
+            }
+          },
+          "required": [
+            "project_key"
+          ],
+          "additionalProperties": false
+        },
+        "output": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Issue"
+          }
+        },
+        "description": "Issues in a project, optionally by status."
+      },
+      "transition_issue": {
+        "input": {
+          "type": "object",
+          "properties": {
+            "transition": {
+              "$ref": "#/$defs/Transition"
+            }
+          },
+          "required": [
+            "transition"
+          ],
+          "additionalProperties": false
+        },
+        "output": {
+          "$ref": "#/$defs/Issue"
+        },
+        "description": "Record a transition and move the issue to its target status."
+      },
+      "add_comment": {
+        "input": {
+          "type": "object",
+          "properties": {
+            "comment": {
+              "$ref": "#/$defs/Comment"
+            }
+          },
+          "required": [
+            "comment"
+          ],
+          "additionalProperties": false
+        },
+        "output": {
+          "$ref": "#/$defs/Comment"
+        },
+        "description": "Comment on an existing issue."
+      }
+    }
+  }
+}

gatewaysdk/environment/schema/connectors/kandji/handlers.py

@@ -0,0 +1,38 @@
+"""Kandji (Iru) world tools; every mutation goes through the schema store.
+
+Error strings are the vendor's own. The Iru Endpoint Management API documents a
+single 404 body for a resource that is not in the tenant, and the device PATCH
+endpoint (the operation ``assign_blueprint`` mirrors) declares no narrower code.
+"""
+
+from gateway_env import store, tool
+
+NOT_FOUND = "Unable to locate the resource in the Iru tenant."
+
+
+@tool(name="list_devices")
+def list_devices(blueprint_id=None):
+    devices = store.list("kandji_devices")
+    if blueprint_id is None:
+        return devices
+    return [d for d in devices if d["blueprint_id"] == blueprint_id]
+
+
+@tool(name="get_device")
+def get_device(device_id):
+    return store.get("kandji_devices", {"device_id": device_id})
+
+
+@tool(name="assign_blueprint")
+def assign_blueprint(device_id, blueprint_id):
+    if store.get("kandji_devices", {"device_id": device_id}) is None:
+        raise ValueError(NOT_FOUND)
+    blueprint = store.get("kandji_blueprints", {"id": blueprint_id})
+    if blueprint is None:
+        raise ValueError(NOT_FOUND)
+    return store.update(
+        "kandji_devices",
+        {"device_id": device_id},
+        {"blueprint_id": blueprint_id, "blueprint_name": blueprint["name"]},
+        source={"record": "tool.assign_blueprint"},
+    )

gatewaysdk/environment/schema/connectors/kandji/parity.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "connector": "kandji",
+  "status": "subset",
+  "world_tools": ["assign_blueprint", "get_device", "list_devices"],
+  "registration": {
+    "mode": "remote_mcp",
+    "provider": "user_configured",
+    "managed_tool_allowlist": []
+  },
+  "surfaces": [
+    {
+      "name": "Iru MCP",
+      "kind": "official_remote_mcp",
+      "auth": "X-API-Key and X-MCP-Profile request headers",
+      "manifest_validation": "credential_required",
+      "supported_world_tools": [
+        "assign_blueprint",
+        "get_device",
+        "list_devices"
+      ],
+      "limitations": [
+        "The endpoint and tools/list manifest are tenant-specific.",
+        "Exact input and output parity requires a credentialed tenant bind."
+      ],
+      "evidence": ["https://support.kandji.io/kb/iru-mcp-server"]
+    }
+  ]
+}

gatewaysdk/environment/schema/connectors/kandji/provenance.json

@@ -0,0 +1,152 @@
+{
+  "slug": "kandji",
+  "shape": "base",
+  "label": "subset",
+  "authored_by": "connector-template-author (hand-transcribed; the `docs` importer does not exist yet)",
+  "generated_at": "2026-09-06T22:27:40Z",
+  "scope_hash": "sha256:eb8c426ef2725a17cb521cc2cd43b76888c28e592a3be65d1138a6488a077640",
+  "world_sha256": "sha256:6f54db6b55824c487385349e3d49fd07f4cb11e09bbbe008e4d002cbea85f435",
+  "source": [
+    {
+      "kind": "docs",
+      "url": "https://api-docs.kandji.io/",
+      "version": "fetched 2026-09-06; redirects to https://api-docs.iru.com/ (Kandji is now Iru)",
+      "sha256": "178c0db4d02acc3801f8f40960effa6aa68811e9b8b533b87b223dc4b23aa523",
+      "note": "Documentation shell pinned as fetched bytes. The entity evidence is the vendor Postman collection rendered by this shell."
+    },
+    {
+      "kind": "postman",
+      "url": "https://api-docs.iru.com/api/collections/15284493/TzCTZkBe?segregateAuth=true&versionTag=latest",
+      "version": "fetched 2026-09-06; collection _postman_id 336d6648-e062-4cbd-a70a-2a0c276cd4ad; the response declares no updatedAt or immutable version",
+      "sha256": "cc323f7dd4052a6a6fa7882d8a45596b0144f5b31a8d890c7c77c3e1a9882119",
+      "note": "Primary vendor evidence. Fields, returned nesting, empty-string sentinels, blueprint type values, and library-item status values are transcribed from its endpoint descriptions and example responses."
+    },
+    {
+      "kind": "openapi",
+      "url": "https://raw.githubusercontent.com/MScottBlake/kandji-openapi/46fa742a831ee84405b3c03a8911ad0510a9310a/openapi.json",
+      "version": "community conversion at commit 46fa742a831ee84405b3c03a8911ad0510a9310a (main verified at that commit on 2026-09-06)",
+      "sha256": "dde0e566da4fe526396b78e7364497b7c6660e9af52a0054f7a0851950b3b8c1",
+      "note": "Cross-check only. This is not a vendor OpenAPI declaration and contributed no fields."
+    }
+  ],
+  "source_verification": {
+    "performed_at": "2026-09-06T21:24:58Z",
+    "commands": [
+      "curl -fsSL \"https://api-docs.kandji.io/\" | sha256sum",
+      "curl -fsSL \"https://api-docs.iru.com/api/collections/15284493/TzCTZkBe?segregateAuth=true&versionTag=latest\" | sha256sum",
+      "curl -fsSL \"https://raw.githubusercontent.com/MScottBlake/kandji-openapi/46fa742a831ee84405b3c03a8911ad0510a9310a/openapi.json\" | sha256sum",
+      "git ls-remote \"https://github.com/MScottBlake/kandji-openapi\" refs/heads/main"
+    ],
+    "result": "All three fetched byte streams matched the hashes recorded above; refs/heads/main resolved to 46fa742a831ee84405b3c03a8911ad0510a9310a."
+  },
+  "entity_sources": {
+    "kandji_devices": "GET /api/v1/devices and GET /api/v1/devices/{device_id}; the common high-level response fields are retained, including nested user and tags",
+    "kandji_blueprints": "GET /api/v1/blueprints and GET /api/v1/blueprints/{blueprint_id}",
+    "kandji_library_items": "GET /api/v1/blueprints/{blueprint_id}/list-library-items for id/name plus GET /api/v1/devices/{device_id}/library-items for optional type/status/audit fields",
+    "kandji_blueprint_items": "GET /api/v1/blueprints/{blueprint_id}/list-library-items and POST /api/v1/blueprints/{blueprint_id}/assign-library-item",
+    "kandji_users": "GET /api/v1/users and GET /api/v1/users/{user_id}",
+    "kandji_tags": "GET /api/v1/tags and POST /api/v1/tags",
+    "kandji_device_tags": "GET /api/v1/devices (tags array) and PATCH /api/v1/devices/{device_id} (tags request body)",
+    "kandji_device_apps": "GET /api/v1/devices/{device_id}/apps, Mac and iPad example responses"
+  },
+  "enums": {
+    "kandji_devices.platform": {
+      "values": ["Mac", "iPhone", "iPad", "AppleTV", "Windows", "Android"],
+      "evidence": "Each literal is a vendor example-response platform value. The vendor calls the endpoint polymorphic but does not publish a closed allowed-values block.",
+      "confidence": "example-derived; completeness unverified"
+    },
+    "kandji_blueprints.type": {
+      "values": ["classic", "map"],
+      "evidence": "GET Blueprint annotates `type` with `values - classic or map`; Create Blueprint repeats `type: map` for an Assignment Map.",
+      "confidence": "vendor-declared values"
+    },
+    "kandji_library_items.status": {
+      "values": ["AVAILABLE", "CACHED", "CHANGE_PENDING", "DOWNLOADING", "ERROR", "EXCLUDED", "INCOMPATIBLE", "INSTALLING", "PASS", "PENDING", "failed", "pending", "success"],
+      "evidence": "The vendor's Get Device Library Items description has a dedicated `Possible library item status values` table. Values and casing are preserved in table order.",
+      "confidence": "vendor-declared value block"
+    },
+    "kandji_library_items.type": {
+      "values": null,
+      "evidence": "The vendor publishes examples but no closed type list, so this field remains an open string rather than an invented enum."
+    }
+  },
+  "errors": {
+    "format": "The vendor documents a response-code table and endpoint-specific bodies. Examples are JSON strings or arrays of strings; there is no fixed detail/error object envelope.",
+    "codes": {
+      "400": "Bad Request, including command-state and JSON parse examples",
+      "401": "Unauthorized",
+      "403": "Forbidden",
+      "404": "Unable to locate the resource in the Iru tenant.",
+      "415": "Unsupported Media Type",
+      "500": "Internal server error",
+      "503": "Service unavailable"
+    },
+    "modelled": {
+      "assign_blueprint": "Raises the vendor's documented 404 text for an unknown device_id or blueprint_id."
+    },
+    "not_modelled": [
+      "The library-item assignment 400 bodies are documented but no assignment tool is shipped."
+    ]
+  },
+  "modelling_notes": [
+    "Device.user preserves the vendor's nested {email, name, id, is_archived} object and its documented empty-string unassigned sentinel. /user/id relates assigned devices to kandji_users without flattening; the sentinel is treated as absent.",
+    "Device.last_check_in preserves the vendor's empty-string never-checked-in sentinel instead of accepting undocumented JSON null.",
+    "Device lost_mode_status is optional because List Devices returns it while the documented Get Mac and Get iPad examples omit it; fields common to those read forms remain required.",
+    "Blueprint.enrollment_code is one optionality unit at the endpoint level: when the required section is returned, both code and is_active are required within it.",
+    "LibraryItem uses union properties across the definition and per-device status reads. Only id and name are required because they are the definition form; type/status/audit fields are optional. The status read's item_id maps to the definition id.",
+    "DeviceApp carries every field in the vendor's Apple-family nested app section. device_id comes from the response envelope; the app object itself remains otherwise unflattened.",
+    "first_enrollment and last_enrollment remain plain strings because the vendor examples use a space separator and are not RFC 3339 date-time values.",
+    "Blueprint name uniqueness is vendor-declared by Create Blueprint. Device serial, user email, and tag name uniqueness were removed because the vendor does not declare those constraints."
+  ],
+  "compiler_limitations": [
+    "The /user/id relationship resolves through the object branch while the documented empty-string branch remains an unassigned sentinel.",
+    "Entity roots and primary keys cannot vary by response branch. Windows and Android app objects use product_code/name and package_name instead of bundle_id, so this eight-entity base subset models only the complete Apple-family app form.",
+    "A faithful per-device library-item status relation would require a separate ninth entity. The fixed base subset retains the scalar status/audit fields as optional library-item properties and omits nested computer, blueprint, and edr_status sections."
+  ],
+  "unverified": [
+    {
+      "item": "kandji_devices.platform completeness",
+      "why": "Six values are evidenced by vendor examples, but no closed vendor value block exists."
+    },
+    {
+      "item": "Live-tenant requiredness and distributions",
+      "why": "No authorized Kandji/Iru sandbox or tenant was available. Requiredness is the intersection of the documented read examples plus the vendor statement that visible polymorphic fields are present."
+    },
+    {
+      "item": "Round trip and goldens",
+      "why": "Skipped because no authorized tenant was available; no customer data was used or committed."
+    }
+  ],
+  "coverage": {
+    "entities": 8,
+    "recursive_fields": 85,
+    "field_count_method": "For each x-gateway entity schema, count every object property recursively after resolving local/base $ref and descending object properties, array items, and allOf/anyOf/oneOf branches.",
+    "field_counts": {
+      "kandji_devices": 26,
+      "kandji_blueprints": 11,
+      "kandji_library_items": 11,
+      "kandji_blueprint_items": 3,
+      "kandji_users": 16,
+      "kandji_tags": 2,
+      "kandji_device_tags": 2,
+      "kandji_device_apps": 14
+    },
+    "vendor_sections_in_scope": ["Device Information summary", "Blueprints", "Library-item definition/status subset", "Users", "Tags", "Apple-family installed apps"],
+    "vendor_sections_excluded": ["Windows/Android app forms", "platform-specific device summary additions", "Device Actions", "Device Secrets", "Automated Device Enrollment integrations", "Prism", "Threats", "Vulnerabilities", "Audit Log", "Settings"],
+    "reasons": "See scope.toml [exclusions] and [compiler_limitations]."
+  },
+  "sandbox": {
+    "availability": "Account-team provisioned; none available for this work",
+    "devices_seedable": false,
+    "round_trip": "skipped",
+    "goldens": "none"
+  },
+  "fixtures": {
+    "records": null,
+    "note": "No fixture was added. The connector template layout does not copy connector-local data files, and no customer data was available or used."
+  },
+  "surface": {
+    "mcp": null,
+    "note": "No MCP surface is declared, so parity does not apply."
+  }
+}