@withgateway/sdk 0.3.3 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (158) hide show
  1. package/README.md +4 -3
  2. package/dist/cli.js +3005 -1401
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2996 -1392
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +128 -37
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +126 -35
  9. package/dist/files/index.mjs.map +1 -1
  10. package/dist/hooks/index.d.mts +1 -1
  11. package/dist/hooks/index.d.ts +1 -1
  12. package/dist/hooks/index.js +124 -11
  13. package/dist/hooks/index.js.map +1 -1
  14. package/dist/hooks/index.mjs +124 -11
  15. package/dist/hooks/index.mjs.map +1 -1
  16. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  17. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  18. package/dist/{index-mJhG3vZU.d.mts → index-Di9nNqOY.d.mts} +26 -3
  19. package/dist/{index-DUHmS74p.d.ts → index-LA-PMRJT.d.ts} +26 -3
  20. package/dist/index.d.mts +4 -4
  21. package/dist/index.d.ts +4 -4
  22. package/dist/index.js +1078 -260
  23. package/dist/index.js.map +1 -1
  24. package/dist/index.mjs +1040 -251
  25. package/dist/index.mjs.map +1 -1
  26. package/dist/replay/index.d.mts +1 -1
  27. package/dist/replay/index.d.ts +1 -1
  28. package/dist/replay/index.js.map +1 -1
  29. package/dist/replay/index.mjs.map +1 -1
  30. package/dist/traces/index.js +125 -34
  31. package/dist/traces/index.js.map +1 -1
  32. package/dist/traces/index.mjs +123 -32
  33. package/dist/traces/index.mjs.map +1 -1
  34. package/dist/tracing/index.d.mts +1 -1
  35. package/dist/tracing/index.d.ts +1 -1
  36. package/dist/tracing/index.js +7 -1
  37. package/dist/tracing/index.js.map +1 -1
  38. package/dist/tracing/index.mjs +7 -1
  39. package/dist/tracing/index.mjs.map +1 -1
  40. package/dist/worlds/index.d.mts +819 -438
  41. package/dist/worlds/index.d.ts +819 -438
  42. package/dist/worlds/index.js +912 -236
  43. package/dist/worlds/index.js.map +1 -1
  44. package/dist/worlds/index.mjs +908 -232
  45. package/dist/worlds/index.mjs.map +1 -1
  46. package/package.json +1 -1
  47. package/runtime/gatewaysdk/environment/_bundle.py +4 -6
  48. package/runtime/gatewaysdk/environment/_materialize.py +5 -25
  49. package/runtime/gatewaysdk/environment/_world.py +82 -66
  50. package/runtime/gatewaysdk/environment/backing.py +20 -24
  51. package/runtime/gatewaysdk/environment/core.py +1 -16
  52. package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
  53. package/runtime/gatewaysdk/environment/runtime.py +45 -2
  54. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  55. package/runtime/gatewaysdk/environment/schema/api.py +198 -474
  56. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  57. package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
  58. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  59. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  60. package/runtime/gatewaysdk/environment/schema/call_capture.py +321 -0
  61. package/runtime/gatewaysdk/environment/schema/call_log.py +276 -18
  62. package/runtime/gatewaysdk/environment/schema/call_redaction.py +207 -19
  63. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  64. package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
  65. package/runtime/gatewaysdk/environment/schema/conform.py +38 -35
  66. package/runtime/gatewaysdk/environment/schema/connector.py +94 -152
  67. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  68. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +2 -1
  69. package/runtime/gatewaysdk/environment/schema/connectors/github/api/handlers.py +217 -58
  70. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +10 -19
  71. package/runtime/gatewaysdk/environment/schema/connectors/github/scenarios/default/seed/github_webhooks.json +10 -2
  72. package/runtime/gatewaysdk/environment/schema/connectors/github/tests/webhooks.json +47 -0
  73. package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +21 -0
  74. package/runtime/gatewaysdk/environment/schema/connectors/jamf/api/handlers.py +185 -18
  75. package/runtime/gatewaysdk/environment/schema/connectors/jamf/connector.toml +29 -14
  76. package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +43 -12
  77. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scenarios/default/seed/jamf_webhooks.json +2 -2
  78. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +4 -17
  79. package/runtime/gatewaysdk/environment/schema/connectors/jamf/tests/webhooks.json +107 -0
  80. package/runtime/gatewaysdk/environment/schema/connectors/jamf/vendor-openapi.json +1 -1
  81. package/runtime/gatewaysdk/environment/schema/connectors/linear/api/handlers.py +85 -1
  82. package/runtime/gatewaysdk/environment/schema/connectors/linear/connector.toml +19 -31
  83. package/runtime/gatewaysdk/environment/schema/connectors/linear/provenance.json +18 -8
  84. package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json +19 -3
  85. package/runtime/gatewaysdk/environment/schema/connectors/linear/tests/test_webhooks.py +71 -0
  86. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  87. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  88. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  89. package/runtime/gatewaysdk/environment/schema/data.py +14 -13
  90. package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
  91. package/runtime/gatewaysdk/environment/schema/database/guard.py +45 -37
  92. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  93. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
  94. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  95. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  96. package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
  97. package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
  98. package/runtime/gatewaysdk/environment/schema/handler_errors.py +52 -5
  99. package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
  100. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  101. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  102. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  103. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  104. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  105. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  106. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  107. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  108. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  109. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  110. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  111. package/runtime/gatewaysdk/environment/schema/journal.py +438 -0
  112. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  113. package/runtime/gatewaysdk/environment/schema/local.py +32 -116
  114. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
  115. package/runtime/gatewaysdk/environment/schema/platform.py +29 -234
  116. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  117. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  118. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  119. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  120. package/runtime/gatewaysdk/environment/schema/runtime.py +136 -176
  121. package/runtime/gatewaysdk/environment/schema/scaffold.py +2 -1
  122. package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
  123. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  124. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  125. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
  126. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  127. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +50 -28
  128. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
  129. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +20 -22
  130. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +25 -25
  131. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
  132. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +71 -7
  133. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  134. package/runtime/gatewaysdk/environment/schema/snapshot.py +150 -30
  135. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  136. package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
  137. package/runtime/gatewaysdk/environment/schema/tools_world.py +103 -203
  138. package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
  139. package/runtime/gatewaysdk/environment/schema/verbs.py +38 -36
  140. package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
  141. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  142. package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
  143. package/runtime/gatewaysdk/environment/schema/world_host.py +970 -0
  144. package/runtime/gatewaysdk/environment/schema/world_tests.py +83 -11
  145. package/runtime/gatewaysdk/environment/world.py +1 -1
  146. package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
  147. package/skills/agents/connector-template-author.md +5 -1
  148. package/skills/benchmarks-getting-started/SKILL.md +8 -9
  149. package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  150. package/skills/connector-schema-authoring/SKILL.md +50 -28
  151. package/skills/connector-schema-authoring/connector-worlds.md +282 -18
  152. package/skills/connector-schema-authoring/world-schema.md +7 -6
  153. package/skills/world-data-ingestion/ROWS.md +12 -8
  154. package/skills/world-data-ingestion/SKILL.md +20 -22
  155. package/skills/worlds-getting-started/SKILL.md +25 -25
  156. package/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
  157. package/skills/worlds-getting-started/references/gotchas.md +71 -7
  158. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
@@ -11,11 +11,12 @@ relationships are enforced on the vendor's own routes. Error bodies follow ``Api
11
11
  from __future__ import annotations
12
12
 
13
13
  import re
14
- from typing import Any
14
+ import xml.etree.ElementTree as ElementTree
15
+ from xml.parsers import expat
16
+ from typing import Any, Callable
15
17
 
16
18
  BASE = "https://yourserver.jamfcloud.com/api"
17
19
 
18
- #: operation name -> how its handler reads the store (generated with the template's routes)
19
20
  ROUTES: dict[str, dict[str, Any]] = {
20
21
  "list_computers": {"entity": "jamf_computers"},
21
22
  "create_computer": {
@@ -346,7 +347,6 @@ ROUTES: dict[str, dict[str, Any]] = {
346
347
  "list_byo_profiles": {"entity": "jamf_byo_profiles", "singular": "byoprofile", "size": True, "many": False},
347
348
  }
348
349
 
349
- #: Classic API list summaries: operation -> (summary field -> row path)
350
350
  CLASSIC_SUMMARY: dict[str, dict[str, str]] = {
351
351
  "list_policies": {"id": "id", "name": "name"},
352
352
  "list_policies_by_category": {"id": "id", "name": "name"},
@@ -405,7 +405,6 @@ CLASSIC_SUMMARY: dict[str, dict[str, str]] = {
405
405
  "list_byo_profiles": {"id": "id", "name": "name"},
406
406
  }
407
407
 
408
- #: InventoryListMobileDevice fields (GET static-group-membership) that a MobileDeviceDetailsGetV2 row carries
409
408
  INVENTORY_LIST_FIELDS: list[str] = [
410
409
  "udid",
411
410
  "assetTag",
@@ -430,9 +429,6 @@ INVENTORY_LIST_FIELDS: list[str] = [
430
429
  ]
431
430
 
432
431
 
433
- # ---------------------------------------------------------------- helpers
434
-
435
-
436
432
  def error(status: int, description: str, field: str = "", code: str = "", id: str = "0") -> tuple[int, dict]:
437
433
  return status, {
438
434
  "httpStatus": status,
@@ -617,9 +613,6 @@ def body_dict(body: Any) -> dict:
617
613
  return body if isinstance(body, dict) else {}
618
614
 
619
615
 
620
- # ---------------------------------------------------------------- Jamf Pro API: generic
621
-
622
-
623
616
  def pro_page(ctx, args, query, body):
624
617
  cfg = ROUTES[ctx.operation.name]
625
618
  rows = selected(ctx, cfg, args, query)
@@ -681,8 +674,6 @@ def pro_delete_group(ctx, args, query, body):
681
674
  return 204, None
682
675
 
683
676
 
684
- # ---------------------------------------------------------------- computer groups
685
-
686
677
  COMPUTER_GROUPS = "jamf_computer_groups"
687
678
  COMPUTER_MEMBERS = "jamf_computer_group_members"
688
679
  MOBILE_GROUPS = "jamf_mobile_device_groups"
@@ -824,9 +815,6 @@ def computer_smart_group_membership(ctx, args, query, body):
824
815
  return {"members": [int(m) if m.lstrip("-").isdigit() else m for m in members]}
825
816
 
826
817
 
827
- # ---------------------------------------------------------------- mobile device groups
828
-
829
-
830
818
  def mobile_assignment(ctx, group: dict) -> dict:
831
819
  return {
832
820
  "groupId": str(group["id"]),
@@ -970,9 +958,6 @@ def mobile_device_static_group_membership(ctx, args, query, body):
970
958
  return page(listed, query)
971
959
 
972
960
 
973
- # ---------------------------------------------------------------- Classic API
974
-
975
-
976
961
  def classic_list(ctx, args, query, body):
977
962
  """``GET /JSSResource/<resource>``: the documented list items, ``{size, <resource>: summary}``."""
978
963
  cfg = ROUTES[ctx.operation.name]
@@ -985,3 +970,185 @@ def classic_list(ctx, args, query, body):
985
970
  if cfg["many"]:
986
971
  return [{**size, cfg["singular"]: summaries}]
987
972
  return [{**size, cfg["singular"]: summary} for summary in summaries]
973
+
974
+
975
+ WEBHOOKS = "jamf_webhooks"
976
+ JSON_RECEIVER = "application/json"
977
+ CLASSIC_XML = "text/xml;charset=UTF-8"
978
+ MAX_WEBHOOK_XML_BYTES = 64 << 10
979
+ WEBHOOK_DEFAULTS = {
980
+ "content_type": "text/xml",
981
+ "connection_timeout": 5,
982
+ "read_timeout": 2,
983
+ "authentication_type": "NONE",
984
+ "enable_display_fields_for_group_object": False,
985
+ }
986
+ COMPUTER_ADDED = {
987
+ "alternateMacAddress": "hardware.altMacAddress",
988
+ "deviceName": "general.name",
989
+ "emailAddress": "userAndLocation.email",
990
+ "ipAddress": "general.lastIpAddress",
991
+ "macAddress": "hardware.macAddress",
992
+ "model": "hardware.model",
993
+ "osBuild": "operatingSystem.build",
994
+ "osVersion": "operatingSystem.version",
995
+ "phone": "userAndLocation.phone",
996
+ "position": "userAndLocation.position",
997
+ "realName": "userAndLocation.realname",
998
+ "reportedIpAddress": "general.lastReportedIp",
999
+ "room": "userAndLocation.room",
1000
+ "serialNumber": "hardware.serialNumber",
1001
+ "udid": "udid",
1002
+ "username": "userAndLocation.username",
1003
+ "managementId": "general.managementId",
1004
+ }
1005
+
1006
+
1007
+ def _flag(text: str) -> bool:
1008
+ return {"true": True, "false": False}[text.strip().lower()]
1009
+
1010
+
1011
+ def _display_fields(element: ElementTree.Element) -> list[dict]:
1012
+ return [{"display_field": {"name": field.findtext("name", "")}} for field in element.findall("display_field")]
1013
+
1014
+
1015
+ class WebhookXml:
1016
+ """A Classic API ``<webhook>`` write body, read as the stored row's fields."""
1017
+
1018
+ READERS: dict[str, Callable[[ElementTree.Element], Any]] = {
1019
+ "name": lambda element: (element.text or "").strip(),
1020
+ "enabled": lambda element: _flag(element.text or ""),
1021
+ "url": lambda element: (element.text or "").strip(),
1022
+ "content_type": lambda element: (element.text or "").strip(),
1023
+ "event": lambda element: (element.text or "").strip(),
1024
+ "connection_timeout": lambda element: int(element.text or ""),
1025
+ "read_timeout": lambda element: int(element.text or ""),
1026
+ "authentication_type": lambda element: (element.text or "").strip(),
1027
+ "username": lambda element: element.text or "",
1028
+ "password": lambda element: element.text or "",
1029
+ "enable_display_fields_for_group_object": lambda element: _flag(element.text or ""),
1030
+ "display_fields": _display_fields,
1031
+ }
1032
+
1033
+ def __init__(self, root: ElementTree.Element):
1034
+ self.root = root
1035
+
1036
+ @classmethod
1037
+ def read(cls, raw: bytes) -> WebhookXml | None:
1038
+ if len(raw) > MAX_WEBHOOK_XML_BYTES:
1039
+ return None
1040
+ try:
1041
+ root = _parsed(raw)
1042
+ except (expat.ExpatError, DeclarationRefused, ValueError, LookupError):
1043
+ return None
1044
+ return cls(root) if root.tag == "webhook" else None
1045
+
1046
+ def fields(self, stored: dict) -> dict | None:
1047
+ written = {name: self.root.find(name) for name in self.READERS}
1048
+ try:
1049
+ found = {name: self.READERS[name](element) for name, element in written.items() if element is not None}
1050
+ except (KeyError, ValueError):
1051
+ return None
1052
+ additions = self.root.find("display_field_additions")
1053
+ if additions is None:
1054
+ return found
1055
+ listed = found.get("display_fields", stored.get("display_fields") or [])
1056
+ return {**found, "display_fields": [*listed, *_display_fields(additions)]}
1057
+
1058
+
1059
+ class DeclarationRefused(Exception):
1060
+ pass
1061
+
1062
+
1063
+ def _refuse(*_: Any) -> None:
1064
+ raise DeclarationRefused
1065
+
1066
+
1067
+ def _parsed(raw: bytes) -> ElementTree.Element:
1068
+ """Refuses any DOCTYPE or entity declaration in whatever encoding the body declares, before a
1069
+ single entity can expand; a byte pattern over the raw body misses a UTF-16 one."""
1070
+ builder = ElementTree.TreeBuilder()
1071
+ parser = expat.ParserCreate()
1072
+ parser.StartDoctypeDeclHandler = _refuse
1073
+ parser.EntityDeclHandler = _refuse
1074
+ parser.StartElementHandler = builder.start
1075
+ parser.EndElementHandler = builder.end
1076
+ parser.CharacterDataHandler = builder.data
1077
+ parser.Parse(raw, True)
1078
+ return builder.close()
1079
+
1080
+
1081
+ def classic_id(resource: str, id: Any) -> tuple[int, bytes, dict]:
1082
+ xml = f'<?xml version="1.0" encoding="UTF-8"?><{resource}><id>{id}</id></{resource}>'
1083
+ return 201, xml.encode("utf-8"), {"Content-Type": CLASSIC_XML}
1084
+
1085
+
1086
+ def stored_webhook(ctx, id: str) -> dict | None:
1087
+ return next((row for row in ctx.rows(WEBHOOKS) if str(row["id"]) == id), None)
1088
+
1089
+
1090
+ def create_webhook(ctx, args, query, body):
1091
+ written = WebhookXml.read(ctx.raw)
1092
+ numeric = args["id"].isascii() and args["id"].isdigit() and len(args["id"]) <= 9
1093
+ fields = None if written is None or not numeric else written.fields({})
1094
+ if fields is None:
1095
+ return ctx.invalid()
1096
+ id = int(args["id"]) or next_id(ctx, WEBHOOKS, as_string=False)
1097
+ created = ctx.insert(WEBHOOKS, {**WEBHOOK_DEFAULTS, **fields, "id": id})
1098
+ return classic_id("webhook", created["id"])
1099
+
1100
+
1101
+ def update_webhook(ctx, args, query, body):
1102
+ stored = stored_webhook(ctx, args["id"])
1103
+ if stored is None:
1104
+ return ctx.not_found()
1105
+ written = WebhookXml.read(ctx.raw)
1106
+ fields = None if written is None else written.fields(stored)
1107
+ if fields is None:
1108
+ return ctx.invalid()
1109
+ ctx.update(WEBHOOKS, ctx.key_of(WEBHOOKS, stored), fields)
1110
+ return classic_id("webhook", stored["id"])
1111
+
1112
+
1113
+ class JamfWebhookEvent:
1114
+ """One Jamf Pro webhook event: each subscription to it gets its own body naming that webhook,
1115
+ as Jamf sends it. Jamf posts XML to a ``text/xml`` subscription, which this world cannot
1116
+ send, so only ``application/json`` subscriptions receive one."""
1117
+
1118
+ def __init__(self, name: str, event: dict):
1119
+ self.name = name
1120
+ self.event = event
1121
+
1122
+ def deliver(self, ctx) -> None:
1123
+ stamp = int(ctx.clock() * 1000)
1124
+ for hook in ctx.rows(WEBHOOKS):
1125
+ if hook.get("event") == self.name and hook.get("content_type") == JSON_RECEIVER:
1126
+ ctx.deliver(self.name, self.body(hook, stamp), scope={"webhook": hook["id"]})
1127
+
1128
+ def body(self, hook: dict, stamp: int) -> dict:
1129
+ webhook = {"eventTimestamp": stamp, "id": hook["id"], "name": hook["name"], "webhookEvent": self.name}
1130
+ return {"event": self.event, "webhook": webhook}
1131
+
1132
+
1133
+ def named(ctx, entity: str, id: Any) -> str:
1134
+ row = next((row for row in ctx.rows(entity) if id is not None and str(row.get("id")) == str(id)), None)
1135
+ return "" if row is None else row.get("name") or ""
1136
+
1137
+
1138
+ def computer_added(ctx, computer: dict) -> dict:
1139
+ located = computer.get("userAndLocation") or {}
1140
+ event = {name: dig(computer, path) or "" for name, path in COMPUTER_ADDED.items()}
1141
+ return {
1142
+ **event,
1143
+ "building": named(ctx, "jamf_buildings", located.get("buildingId")),
1144
+ "department": named(ctx, "jamf_departments", located.get("departmentId")),
1145
+ "jssID": int(computer["id"]) if str(computer["id"]).isdigit() else computer["id"],
1146
+ "userDirectoryID": "",
1147
+ }
1148
+
1149
+
1150
+ def create_computer(ctx, args, query, body):
1151
+ answer = pro_create_href(ctx, args, query, body)
1152
+ computer = ctx.get("jamf_computers", {"id": answer[1]["id"]})
1153
+ JamfWebhookEvent("ComputerAdded", computer_added(ctx, computer)).deliver(ctx)
1154
+ return answer
@@ -1,10 +1,3 @@
1
- # Jamf Pro connection: the Jamf Pro API (/api/v1..v4) and the Classic API (/JSSResource) of one instance,
2
- # served from the world's store. Routes are the ones the pinned developer.jamf.com reference documents
3
- # (Jamf Pro 11.32.0); paths, methods and response shapes follow that document, see provenance.json.
4
- #
5
- # base_url is the instance root: Pro routes are relative to <base>/api, Classic routes to <base>/JSSResource.
6
- # The world serves both families on one origin, the way one Jamf Pro instance does.
7
-
8
1
  [connector]
9
2
  slug = "jamf"
10
3
  base_url = "https://yourserver.jamfcloud.com"
@@ -25,8 +18,6 @@ hash = ["userAndLocation.email", "userAndLocation.phone", "userAndLocation.realn
25
18
  drop = ["plainPassword", "serviceToken", "read_only_password_sha256", "read_write_password_sha256", "ssh_password_sha256", "http_password_sha256", "password_sha256"]
26
19
  preserve = []
27
20
 
28
- # Jamf Pro pages by number ({totalCount, results}, no cursor); every list route below is a handler that
29
- # renders that shape itself, so the declarative envelope only names the keys and never emits a cursor.
30
21
  [api]
31
22
  envelope = "results"
32
23
  hits_key = "totalCount"
@@ -40,10 +31,14 @@ unauthorized = '{"httpStatus": 401, "errors": [{"code": "UNAUTHORIZED", "descrip
40
31
  error_content_type = "application/json"
41
32
  handlers = "api/handlers.py"
42
33
 
43
- # The browsable UI over these routes: `gateway worlds schema compile` generates
44
- # ui/static (index.html, app.js, contract.json) from the contract; a session
45
- # opened with `--surface ui` serves it and `--surface browser` drives it. Set
46
- # `generated = false` to hand-write ui/static instead.
34
+ [webhooks]
35
+ subscriptions = "jamf_webhooks"
36
+ url = "url"
37
+ events = "event"
38
+ enabled = "enabled"
39
+ scope = { webhook = "id" }
40
+ signing = "none"
41
+
47
42
  [ui]
48
43
  static = "ui/static"
49
44
  entry = "/"
@@ -75,7 +70,7 @@ path = "/api/v1/computers-inventory"
75
70
  entity = "jamf_computers"
76
71
  [operations.api]
77
72
  action = "handler"
78
- handler = "pro_create_href"
73
+ handler = "create_computer"
79
74
  status = 201
80
75
 
81
76
  [[operations]]
@@ -2016,6 +2011,26 @@ entity = "jamf_webhooks"
2016
2011
  filter = { id = "id" }
2017
2012
  single = true
2018
2013
 
2014
+ [[operations]]
2015
+ name = "create_webhook_by_id"
2016
+ method = "POST"
2017
+ path = "/JSSResource/webhooks/id/{id}"
2018
+ entity = "jamf_webhooks"
2019
+ [operations.api]
2020
+ action = "handler"
2021
+ handler = "create_webhook"
2022
+ status = 201
2023
+
2024
+ [[operations]]
2025
+ name = "update_webhook_by_id"
2026
+ method = "PUT"
2027
+ path = "/JSSResource/webhooks/id/{id}"
2028
+ entity = "jamf_webhooks"
2029
+ [operations.api]
2030
+ action = "handler"
2031
+ handler = "update_webhook"
2032
+ status = 201
2033
+
2019
2034
  [[operations]]
2020
2035
  name = "delete_webhook_by_id"
2021
2036
  method = "DELETE"
@@ -41,6 +41,13 @@
41
41
  "sha256": "0d32b982b4539d3cc93703178f5fbb734554176e5433552ca9d2b2e1e825c677",
42
42
  "bytes": 28566,
43
43
  "used_for": "Classic computer inventory endpoints deprecated from Jamf Pro 11.15.0; the world reads computers through the Pro API only"
44
+ },
45
+ {
46
+ "url": "https://developer.jamf.com/jamf-pro/docs/webhooks-1.md",
47
+ "sha256": "aef5e6d12419ccee1bc62d03e5b8811d6b1a7c85707d5fec1106eb173182bcd7",
48
+ "bytes": 40536,
49
+ "fetched_at": "2026-10-10",
50
+ "used_for": "webhook events, when each fires, and their JSON payloads ({event, webhook: {eventTimestamp, id, name, webhookEvent}}); [webhooks] in connector.toml and api/handlers.py JamfWebhookEvent"
44
51
  }
45
52
  ],
46
53
  "aggregates": [
@@ -5605,7 +5612,12 @@
5605
5612
  "page": "createwebhookbyid.md",
5606
5613
  "sha256": "a41f4e5633344f1681633150d9fe5f64c5f738399ea5ca97fff08a1e50d2ffbd",
5607
5614
  "bytes": 4100,
5608
- "served": false
5615
+ "served": true,
5616
+ "refetched_2026_10_10": {
5617
+ "sha256": "72bde6c1a074535f464a0b5825bc0da6783c10ed39bfc62c42ddba6a20f4afe6",
5618
+ "bytes": 3990,
5619
+ "used_for": "the path item copied into vendor-openapi.json; the page changed since the 2026-09-15 aggregate, its OpenAPI fragment did not"
5620
+ }
5609
5621
  },
5610
5622
  {
5611
5623
  "page": "deleteaccountbyid.md",
@@ -9103,7 +9115,12 @@
9103
9115
  "page": "updatewebhookbyid.md",
9104
9116
  "sha256": "2fa528e5895f3e5acafcfe7b35bbf7289f7a8e0e231920120189c0ffd845040a",
9105
9117
  "bytes": 4331,
9106
- "served": false
9118
+ "served": true,
9119
+ "refetched_2026_10_10": {
9120
+ "sha256": "bf3dab82a56a512d076592f04592ebe6445d946f8b5a9a222ce198ebb40f6c75",
9121
+ "bytes": 4221,
9122
+ "used_for": "the path item copied into vendor-openapi.json; the page changed since the 2026-09-15 aggregate, its OpenAPI fragment did not"
9123
+ }
9107
9124
  },
9108
9125
  {
9109
9126
  "page": "updatewebhookbyname.md",
@@ -9164,17 +9181,18 @@
9164
9181
  },
9165
9182
  "vendor_openapi": {
9166
9183
  "file": "vendor-openapi.json",
9167
- "sha256": "85641ff67cab8e106fc9e5da1324a5d3089475a08b198ea9be20a52571c9d96d",
9168
- "bytes": 430828,
9184
+ "sha256": "a33db8d391547e74fc4699031e089320cbae19babc5298e47e92e5d346ecd13e",
9185
+ "bytes": 432031,
9169
9186
  "paths": 159,
9170
- "operations": 302,
9187
+ "operations": 304,
9171
9188
  "schemas": 288,
9172
9189
  "trimmed": true,
9173
9190
  "trim_method": "From the two merged aggregates, keep exactly the path+method pairs connector.toml serves (Pro paths under /api, Classic paths under /JSSResource) and, transitively, every components.schemas entry those operations reference; drop every other path and schema. Nothing kept is edited. `servers` lists the two base paths of one instance. The aggregates themselves are not committed (2.5 MB); their hashes are above.",
9174
9191
  "untrimmed_sha256": {
9175
9192
  "jamf_pro_api_merged": "41bf9f7fd44deef558be292cbeec533e3a02f85433310efcbbea728da7286243",
9176
9193
  "classic_api_merged": "2d205cc57d5ee7da5e7a34785c7da44e74c1b662b8cca5b23743d4ef2e8fdfa7"
9177
- }
9194
+ },
9195
+ "added_2026_10_10": "POST and PUT /webhooks/id/{id} (createWebhookById, updateWebhookById) copied unedited from the refetched reference pages above."
9178
9196
  },
9179
9197
  "coverage": {
9180
9198
  "entity_count": 66,
@@ -9274,11 +9292,11 @@
9274
9292
  "excluded": "See scope.toml [exclusions] and [unserved] for the documented routes and families this world does not hold."
9275
9293
  },
9276
9294
  "connection": {
9277
- "operations": 302,
9295
+ "operations": 304,
9278
9296
  "jamf_pro_api": 178,
9279
- "classic_api": 124,
9297
+ "classic_api": 126,
9280
9298
  "by_action": {
9281
- "handler": 110,
9299
+ "handler": 112,
9282
9300
  "read": 90,
9283
9301
  "delete": 77,
9284
9302
  "update": 25
@@ -9286,8 +9304,17 @@
9286
9304
  "auth": "oauth2 client credentials at POST /api/oauth/token (Jamf Pro API Clients); the world mints bearer tokens the same way",
9287
9305
  "documented_but_unserved": {
9288
9306
  "jamf_pro_api_operations": 645,
9289
- "classic_api_operations": 489,
9307
+ "classic_api_operations": 487,
9290
9308
  "note": "Listed per path family in scope.toml [unserved]. None is faked: a request to one of them gets the world's 404."
9309
+ },
9310
+ "webhooks": {
9311
+ "subscriptions": "jamf_webhooks (Classic API webhooks: one event per webhook in `event`, `enabled`, `url`)",
9312
+ "signing": "none: Jamf Pro does not sign webhooks; BASIC authentication_type sends the receiver's own username and password, which this world does not carry",
9313
+ "events_delivered": {
9314
+ "ComputerAdded": "POST /api/v1/computers-inventory (create_computer), to each application/json subscription to ComputerAdded, each body naming its own webhook id and name"
9315
+ },
9316
+ "events_not_delivered": "every other event in the enum: its cause (device check-in, inventory submission, enrollment, MDM commands, policy runs, smart-group recalculation, server start/stop, patch feed, SCEP) is not modelled by a served route. RestAPIOperation is not delivered: its objectTypeName, restAPIOperationType and authorizedUsername values are not documented.",
9317
+ "seeded_subscriptions": "the three seeded rows are disabled so a session's deliveries go only to webhooks the agent registers or enables"
9291
9318
  }
9292
9319
  },
9293
9320
  "errors": {
@@ -9409,9 +9436,13 @@
9409
9436
  "No per-instance /api/schema was available; public embedded OpenAPI fragments are pinned instead. A tenant's schema may add or remove fields with its Jamf Pro version.",
9410
9437
  "No Jamf sandbox or trial credentials were available: tenant round trip, mutation verification against a live instance, audit against pulled records, and golden replay were skipped.",
9411
9438
  "Classic API: the pinned pages type list responses as arrays of wrappers (see errors.typing_mismatches); live envelopes were not observed.",
9412
- "Classic API writes (POST/PUT with XML bodies) are not served; the documented Classic DELETE by id/name routes are.",
9439
+ "Classic API writes (POST/PUT with XML bodies) are served only for webhooks by id; the other documented Classic DELETE by id/name routes are served, their writes are not. The webhook write answer `<webhook><id>N</id></webhook>` (201, text/xml) follows the Classic API overview's 'respond with the ID'; the reference pages document 201 with no body.",
9413
9440
  "Serial-number, UDID, extension-attribute-name, username, and Classic resource-name uniqueness are not declared by the pinned pages and are not asserted. Group-name uniqueness is asserted because the create endpoints document 'Duplicate group name' as 422.",
9414
- "Paths under /api/v1/computers-inventory/{id}/... (attachments, filevault, erase, recovery-lock) and other action/workflow routes are not served; see scope.toml [unserved]."
9441
+ "Paths under /api/v1/computers-inventory/{id}/... (attachments, filevault, erase, recovery-lock) and other action/workflow routes are not served; see scope.toml [unserved].",
9442
+ "ComputerAdded is documented for a newly enrolled computer; that Jamf Pro fires it for a record created through POST /api/v1/computers-inventory is not documented.",
9443
+ "Jamf sends a text/xml subscription the <JSSEvent> XML payload; this world sends only JSON, so a text/xml subscription receives nothing.",
9444
+ "ComputerAdded fields the world has no value for (userDirectoryID, and any the created record leaves unset) are sent as empty strings; Jamf's value for an unset field is not documented.",
9445
+ "smart_group_id (in the create/update samples) and updateWebhookByName are not served; unknown elements in a webhook body are ignored."
9415
9446
  ],
9416
9447
  "fidelity": {
9417
9448
  "label": "subset",
@@ -3,7 +3,7 @@
3
3
  {
4
4
  "id": 1,
5
5
  "name": "Aurora name 1",
6
- "enabled": true,
6
+ "enabled": false,
7
7
  "url": "https://example.com/jamf_webhooks/url/1",
8
8
  "content_type": "text/xml",
9
9
  "event": "ComputerAdded",
@@ -47,7 +47,7 @@
47
47
  {
48
48
  "id": 3,
49
49
  "name": "Cobalt name 3",
50
- "enabled": true,
50
+ "enabled": false,
51
51
  "url": "https://example.com/jamf_webhooks/url/3",
52
52
  "content_type": "text/xml",
53
53
  "event": "ComputerInventoryCompleted",
@@ -1,12 +1,8 @@
1
- # Scope of the Jamf model: what the world holds and serves, and what the pinned documents describe that it
2
- # does not. Generated with provenance.json from the pinned developer.jamf.com reference pages
3
- # (Jamf Pro API 11.32.0, Classic API 11.32.0); see provenance.json for every page hash.
4
-
5
1
  [source]
6
2
  kind = "docs"
7
3
  jamf_pro_api_version = "11.32.0"
8
4
  classic_api_version = "11.32.0"
9
- instance_spec = "none" # https://<instance>.jamfcloud.com/api/schema needs an instance
5
+ instance_spec = "none"
10
6
  shape = "mixed"
11
7
  evidence_reverified = "2026-09-15"
12
8
  pro_operations_documented = 823
@@ -14,8 +10,6 @@ pro_operations_served = 178
14
10
  classic_operations_documented = 613
15
11
  classic_operations_served = 124
16
12
 
17
- # ---------------------------------------------------------------- entity allowlist
18
-
19
13
  [[entities]]
20
14
  name = "jamf_computers"
21
15
  vendor = "ComputerInventory (GET /v1/computers-inventory, GET/PATCH /v1/computers-inventory-detail/{id})"
@@ -399,12 +393,12 @@ routes = 5
399
393
 
400
394
  [[entities]]
401
395
  name = "jamf_webhooks"
402
- vendor = "webhook (GET /webhooks, GET/DELETE /webhooks/id/{id}, GET/DELETE /webhooks/name/{name})"
396
+ vendor = "webhook (GET /webhooks, GET/POST/PUT/DELETE /webhooks/id/{id}, GET/DELETE /webhooks/name/{name})"
403
397
  api = "classic"
404
398
  primary_key = ["id"]
405
399
  unique = []
406
400
  fields = 16
407
- routes = 5
401
+ routes = 7
408
402
 
409
403
  [[entities]]
410
404
  name = "jamf_mac_applications"
@@ -615,8 +609,6 @@ relationships = ["groupId -> jamf_mobile_device_groups", "mobileDeviceId -> jamf
615
609
  fields = 2
616
610
  routes = 1
617
611
 
618
- # ------------------------------------------------------------------- key handling
619
-
620
612
  [key_overrides]
621
613
  pro_ids = "Jamf Pro API response schemas mark id readOnly and often declare no required properties; the id is promoted to required (minLength 1) because gateway-world/1 needs a direct, required, non-null key."
622
614
  classic_ids = "Classic resources nest id under general.id; the root id holds the same value the documented list item {id, name} carries."
@@ -632,8 +624,6 @@ jamf_mobile_device_group_members = ["groupId -> jamf_mobile_device_groups.id", "
632
624
  [polymorphic]
633
625
  fields = []
634
626
 
635
- # ----------------------------------------------------------------------- exclusions
636
-
637
627
  [exclusions]
638
628
  "collected extension-attribute values" = "ComputerInventory section extensionAttributes arrays and MobileDeviceDetailsGetV2.extensionAttributes are tenant data; definitions are entities, values are not."
639
629
  "Classic computer inventory (/computers, /computerreports, ...)" = "Deprecated from Jamf Pro 11.15.0 per the pinned deprecation page; computers are read through /api/v1/computers-inventory."
@@ -642,9 +632,6 @@ fields = []
642
632
  "secrets in write DTOs" = "VolumePurchasingLocation.serviceToken and SupervisionIdentity.password are accepted by the create/update handlers and never stored; Classic distribution-point and directory-binding password hashes are dropped on capture ([redact].drop)."
643
633
  "action and workflow endpoints" = "Command, erase, redeploy, recovery-lock, attachment, history, export, CSV and search-execution routes are documented but not served; they act on state a schema world does not hold."
644
634
 
645
- # Documented path families with at least one operation the world does not serve, with the count of unserved
646
- # operations in each. A request to any of them gets the world's 404; none is faked.
647
-
648
635
  [unserved.jamf_pro_api]
649
636
  "/api/auth" = 1
650
637
  "/api/auth/current" = 1
@@ -885,7 +872,7 @@ fields = []
885
872
  "/JSSResource/vppaccounts" = 5
886
873
  "/JSSResource/vppassignments" = 5
887
874
  "/JSSResource/vppinvitations" = 6
888
- "/JSSResource/webhooks" = 3
875
+ "/JSSResource/webhooks" = 1
889
876
 
890
877
  [compiler_limitations]
891
878
  group_variants = "Static and smart groups share one entity per platform, distinguished by smartGroup / isSmartGroup; the documented static-groups and smart-groups route families filter on it."
@@ -0,0 +1,107 @@
1
+ {
2
+ "group": "jamf webhooks",
3
+ "scenario": "default",
4
+ "cases": [
5
+ {
6
+ "name": "a webhook is created from its Classic XML body",
7
+ "request": {
8
+ "method": "POST",
9
+ "path": "/JSSResource/webhooks/id/0",
10
+ "headers": {"Content-Type": "text/xml"},
11
+ "body": "<webhook><name>Enrolled Macs</name><enabled>true</enabled><url>https://receiver.example.org/jamf</url><content_type>application/json</content_type><event>ComputerAdded</event></webhook>"
12
+ },
13
+ "expect": {
14
+ "status": 201,
15
+ "contains": "<webhook><id>4</id></webhook>",
16
+ "headers": {"content-type": "text/xml;charset=UTF-8"}
17
+ }
18
+ },
19
+ {
20
+ "name": "the created webhook reads back with Jamf's defaults",
21
+ "request": {"method": "GET", "path": "/JSSResource/webhooks/id/4"},
22
+ "expect": {
23
+ "status": 200,
24
+ "json": {
25
+ "id": 4,
26
+ "name": "Enrolled Macs",
27
+ "event": "ComputerAdded",
28
+ "enabled": true,
29
+ "connection_timeout": 5,
30
+ "read_timeout": 2,
31
+ "authentication_type": "NONE"
32
+ }
33
+ }
34
+ },
35
+ {
36
+ "name": "an update changes only the fields it names",
37
+ "request": {
38
+ "method": "PUT",
39
+ "path": "/JSSResource/webhooks/id/4",
40
+ "headers": {"Content-Type": "text/xml"},
41
+ "body": "<webhook><read_timeout>4</read_timeout><display_field_additions><display_field><name>IP Address</name></display_field></display_field_additions></webhook>"
42
+ },
43
+ "expect": {"status": 201, "contains": "<webhook><id>4</id></webhook>"}
44
+ },
45
+ {
46
+ "name": "the update reads back",
47
+ "request": {"method": "GET", "path": "/JSSResource/webhooks/id/4"},
48
+ "expect": {
49
+ "status": 200,
50
+ "json": {
51
+ "name": "Enrolled Macs",
52
+ "read_timeout": 4,
53
+ "display_fields": [{"display_field": {"name": "IP Address"}}]
54
+ }
55
+ }
56
+ },
57
+ {
58
+ "name": "an update to an unknown webhook is not found",
59
+ "request": {
60
+ "method": "PUT",
61
+ "path": "/JSSResource/webhooks/id/404",
62
+ "headers": {"Content-Type": "text/xml"},
63
+ "body": "<webhook><enabled>false</enabled></webhook>"
64
+ },
65
+ "expect": {"status": 404}
66
+ },
67
+ {
68
+ "name": "a body that is not a webhook is refused",
69
+ "request": {
70
+ "method": "POST",
71
+ "path": "/JSSResource/webhooks/id/0",
72
+ "headers": {"Content-Type": "text/xml"},
73
+ "body": "<policy><name>Not a webhook</name></policy>"
74
+ },
75
+ "expect": {"status": 400}
76
+ },
77
+ {
78
+ "name": "a body declaring entities is refused",
79
+ "request": {
80
+ "method": "POST",
81
+ "path": "/JSSResource/webhooks/id/0",
82
+ "headers": {"Content-Type": "text/xml"},
83
+ "body": "<!DOCTYPE webhook [<!ENTITY name \"Expanded\">]><webhook><name>&name;</name><url>https://receiver.example.org/jamf</url><event>ComputerAdded</event></webhook>"
84
+ },
85
+ "expect": {"status": 400}
86
+ },
87
+ {
88
+ "name": "a webhook with no event is refused",
89
+ "request": {
90
+ "method": "POST",
91
+ "path": "/JSSResource/webhooks/id/0",
92
+ "headers": {"Content-Type": "text/xml"},
93
+ "body": "<webhook><name>No event</name><url>https://receiver.example.org/jamf</url></webhook>"
94
+ },
95
+ "expect": {"status": 400}
96
+ },
97
+ {
98
+ "name": "a computer created through the Pro API answers its href",
99
+ "request": {
100
+ "method": "POST",
101
+ "path": "/api/v1/computers-inventory",
102
+ "body": {"udid": "00000000-0000-4000-8000-0000000000aa", "general": {"name": "Lab Mac 9"}}
103
+ },
104
+ "expect": {"status": 201, "json": {"id": "4"}}
105
+ }
106
+ ]
107
+ }