@withgateway/sdk 0.4.0 → 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 (94) hide show
  1. package/dist/cli.js +1128 -783
  2. package/dist/cli.js.map +1 -1
  3. package/dist/cli.mjs +1130 -785
  4. package/dist/cli.mjs.map +1 -1
  5. package/dist/files/index.js +47 -18
  6. package/dist/files/index.js.map +1 -1
  7. package/dist/files/index.mjs +47 -18
  8. package/dist/files/index.mjs.map +1 -1
  9. package/dist/{index-mJhG3vZU.d.mts → index-Di9nNqOY.d.mts} +26 -3
  10. package/dist/{index-DUHmS74p.d.ts → index-LA-PMRJT.d.ts} +26 -3
  11. package/dist/index.d.mts +3 -3
  12. package/dist/index.d.ts +3 -3
  13. package/dist/index.js +179 -43
  14. package/dist/index.js.map +1 -1
  15. package/dist/index.mjs +176 -43
  16. package/dist/index.mjs.map +1 -1
  17. package/dist/replay/index.d.mts +1 -1
  18. package/dist/replay/index.d.ts +1 -1
  19. package/dist/replay/index.js.map +1 -1
  20. package/dist/replay/index.mjs.map +1 -1
  21. package/dist/traces/index.js +47 -18
  22. package/dist/traces/index.js.map +1 -1
  23. package/dist/traces/index.mjs +47 -18
  24. package/dist/traces/index.mjs.map +1 -1
  25. package/dist/tracing/index.d.mts +1 -1
  26. package/dist/tracing/index.d.ts +1 -1
  27. package/dist/tracing/index.js +1 -1
  28. package/dist/tracing/index.js.map +1 -1
  29. package/dist/tracing/index.mjs +1 -1
  30. package/dist/tracing/index.mjs.map +1 -1
  31. package/dist/worlds/index.d.mts +184 -85
  32. package/dist/worlds/index.d.ts +184 -85
  33. package/dist/worlds/index.js +176 -43
  34. package/dist/worlds/index.js.map +1 -1
  35. package/dist/worlds/index.mjs +176 -43
  36. package/dist/worlds/index.mjs.map +1 -1
  37. package/package.json +1 -1
  38. package/runtime/gatewaysdk/environment/_bundle.py +4 -6
  39. package/runtime/gatewaysdk/environment/_world.py +24 -1
  40. package/runtime/gatewaysdk/environment/runtime.py +45 -2
  41. package/runtime/gatewaysdk/environment/schema/api.py +24 -3
  42. package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
  43. package/runtime/gatewaysdk/environment/schema/call_capture.py +13 -1
  44. package/runtime/gatewaysdk/environment/schema/call_log.py +46 -0
  45. package/runtime/gatewaysdk/environment/schema/call_redaction.py +6 -0
  46. package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
  47. package/runtime/gatewaysdk/environment/schema/conform.py +32 -8
  48. package/runtime/gatewaysdk/environment/schema/connector.py +5 -0
  49. package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +2 -1
  50. package/runtime/gatewaysdk/environment/schema/connectors/github/api/handlers.py +217 -58
  51. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +9 -19
  52. package/runtime/gatewaysdk/environment/schema/connectors/github/scenarios/default/seed/github_webhooks.json +10 -2
  53. package/runtime/gatewaysdk/environment/schema/connectors/github/tests/webhooks.json +47 -0
  54. package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +21 -0
  55. package/runtime/gatewaysdk/environment/schema/connectors/jamf/api/handlers.py +185 -18
  56. package/runtime/gatewaysdk/environment/schema/connectors/jamf/connector.toml +29 -14
  57. package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +43 -12
  58. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scenarios/default/seed/jamf_webhooks.json +2 -2
  59. package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +4 -17
  60. package/runtime/gatewaysdk/environment/schema/connectors/jamf/tests/webhooks.json +107 -0
  61. package/runtime/gatewaysdk/environment/schema/connectors/jamf/vendor-openapi.json +1 -1
  62. package/runtime/gatewaysdk/environment/schema/connectors/linear/api/handlers.py +85 -1
  63. package/runtime/gatewaysdk/environment/schema/connectors/linear/connector.toml +19 -31
  64. package/runtime/gatewaysdk/environment/schema/connectors/linear/provenance.json +18 -8
  65. package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json +19 -3
  66. package/runtime/gatewaysdk/environment/schema/connectors/linear/tests/test_webhooks.py +71 -0
  67. package/runtime/gatewaysdk/environment/schema/database/guard.py +2 -1
  68. package/runtime/gatewaysdk/environment/schema/handler_errors.py +27 -1
  69. package/runtime/gatewaysdk/environment/schema/journal.py +4 -3
  70. package/runtime/gatewaysdk/environment/schema/local.py +1 -0
  71. package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
  72. package/runtime/gatewaysdk/environment/schema/platform.py +16 -219
  73. package/runtime/gatewaysdk/environment/schema/runtime.py +7 -0
  74. package/runtime/gatewaysdk/environment/schema/scaffold.py +2 -1
  75. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  76. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +19 -22
  77. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +7 -9
  78. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +3 -3
  79. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +14 -11
  80. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +36 -5
  81. package/runtime/gatewaysdk/environment/schema/snapshot.py +2 -2
  82. package/runtime/gatewaysdk/environment/schema/tools_world.py +19 -0
  83. package/runtime/gatewaysdk/environment/schema/verbs.py +6 -0
  84. package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
  85. package/runtime/gatewaysdk/environment/schema/world_host.py +20 -3
  86. package/runtime/gatewaysdk/environment/schema/world_tests.py +74 -0
  87. package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
  88. package/skills/connector-schema-authoring/SKILL.md +19 -22
  89. package/skills/connector-schema-authoring/connector-worlds.md +153 -11
  90. package/skills/connector-schema-authoring/world-schema.md +7 -6
  91. package/skills/world-data-ingestion/SKILL.md +7 -9
  92. package/skills/worlds-getting-started/SKILL.md +3 -3
  93. package/skills/worlds-getting-started/references/cli-mcp-map.md +14 -11
  94. package/skills/worlds-getting-started/references/gotchas.md +36 -5
@@ -17,6 +17,7 @@ Conventions the world commits to:
17
17
  * Pagination is not emulated: list routes answer every matching row.
18
18
  """
19
19
 
20
+ # file limit exception: [api] handlers loads one module per world, and this one answers all 203 GitHub routes the template serves
20
21
  from __future__ import annotations
21
22
 
22
23
  import hashlib
@@ -70,8 +71,6 @@ CODE_ALERTS = "github_code_scanning_alerts"
70
71
  DEPENDABOT_ALERTS = "github_dependabot_alerts"
71
72
  SECRET_ALERTS = "github_secret_scanning_alerts"
72
73
 
73
- # World-only projections of nested vendor scalars (the relationship fields); kept in step
74
- # with the nested object whenever a handler writes one.
75
74
  PROJECTIONS: dict[str, dict[str, str]] = {
76
75
  ORG_MEMBERSHIPS: {"org_id": "organization.id", "user_id": "user.id"},
77
76
  TEAMS: {"org_id": "organization.id", "parent_id": "parent.id"},
@@ -115,15 +114,13 @@ PROJECTIONS: dict[str, dict[str, str]] = {
115
114
  GIST_COMMENTS: {"user_id": "user.id"},
116
115
  CODE_ALERTS: {"dismissed_by_id": "dismissed_by.id"},
117
116
  DEPENDABOT_ALERTS: {"dismissed_by_id": "dismissed_by.id"},
117
+ WEBHOOKS: {"config_url": "config.url", "config_secret": "config.secret"},
118
118
  }
119
119
 
120
120
  REVIEW_EVENTS = {"APPROVE": "APPROVED", "REQUEST_CHANGES": "CHANGES_REQUESTED", "COMMENT": "COMMENTED"}
121
121
  SHA = re.compile(r"^[0-9a-f]{7,40}$")
122
122
 
123
123
 
124
- # ---------------------------------------------------------------- reading rows
125
-
126
-
127
124
  def _dig(row: Any, path: str) -> Any:
128
125
  for part in path.split("."):
129
126
  row = row.get(part) if isinstance(row, dict) else None
@@ -278,9 +275,6 @@ def _org_rows(ctx, entity: str, org: dict) -> list[dict]:
278
275
  return [row for row in ctx.rows(entity) if row["repo_id"] in ids]
279
276
 
280
277
 
281
- # ---------------------------------------------------------------- writing rows
282
-
283
-
284
278
  def _schema(ctx, entity: str) -> dict:
285
279
  return ctx.state.contract.entities[entity]["schema"]
286
280
 
@@ -389,9 +383,22 @@ def _merged(schema: dict) -> dict:
389
383
  return merged
390
384
 
391
385
 
386
+ def _hook_subscription(row: dict) -> dict:
387
+ events = list(row.get("events") or [])
388
+ return {"delivery_events": [] if "*" in events else [*events, "ping"]}
389
+
390
+
391
+ DERIVED = {WEBHOOKS: _hook_subscription}
392
+
393
+
394
+ def _projections(entity: str, row: dict) -> dict:
395
+ flat = {field: _dig(row, path) for field, path in PROJECTIONS.get(entity, {}).items()}
396
+ derive = DERIVED.get(entity)
397
+ return {**flat, **(derive(row) if derive else {})}
398
+
399
+
392
400
  def _project(entity: str, row: dict) -> dict:
393
- for field, path in PROJECTIONS.get(entity, {}).items():
394
- row[field] = _dig(row, path)
401
+ row.update(_projections(entity, row))
395
402
  return row
396
403
 
397
404
 
@@ -413,7 +420,8 @@ def _patch(ctx, entity: str, row: dict, body: Any, allowed: tuple[str, ...] | No
413
420
  if "updated_at" in props:
414
421
  patch.setdefault("updated_at", ctx.now())
415
422
  merged = _shape(ctx, entity, {**row, **patch})
416
- changed = {k: v for k, v in merged.items() if k in patch or k in PROJECTIONS.get(entity, {}) or k == "updated_at"}
423
+ projected = _projections(entity, merged)
424
+ changed = {k: v for k, v in merged.items() if k in patch or k in projected or k == "updated_at"}
417
425
  return ctx.update(entity, ctx.key_of(entity, row), changed)
418
426
 
419
427
 
@@ -455,7 +463,49 @@ def _gone(ctx, entity: str, row: dict):
455
463
  return 204, None
456
464
 
457
465
 
458
- # ---------------------------------------------------------------- users
466
+ ORG_SIMPLE = (
467
+ "login",
468
+ "id",
469
+ "node_id",
470
+ "url",
471
+ "repos_url",
472
+ "events_url",
473
+ "hooks_url",
474
+ "issues_url",
475
+ "members_url",
476
+ "public_members_url",
477
+ "avatar_url",
478
+ "description",
479
+ )
480
+ MASKED_SECRET = "********"
481
+ ZEN = "Keep it logically awesome."
482
+ NO_SHA = "0" * 40
483
+
484
+
485
+ def _deliver(ctx, event: str, repo: dict, body: dict, **scope: Any) -> None:
486
+ """One GitHub event about ``repo``: the payload GitHub sends, to every hook on that repository."""
487
+ repository = REPOSITORY_FORMS.get(event, dict)(_vendor(ctx, REPOS, repo))
488
+ payload = {**body, "repository": repository, "sender": _simple_user(_actor(ctx))}
489
+ org = _first(_where(ctx.rows(ORGS), login=repo["owner"]["login"]))
490
+ if org is not None:
491
+ payload["organization"] = {k: org[k] for k in ORG_SIMPLE if k in org}
492
+ ctx.deliver(event, payload, scope={"repo": str(repo["id"]), **scope})
493
+
494
+
495
+ def _reactions(url: str) -> dict:
496
+ counts = ("+1", "-1", "laugh", "confused", "heart", "hooray", "eyes", "rocket")
497
+ return {"url": f"{url}/reactions", "total_count": 0, **{name: 0 for name in counts}}
498
+
499
+
500
+ def _changes(before: dict, after: dict, fields: tuple[str, ...]) -> dict:
501
+ return {field: {"from": before.get(field)} for field in fields if before.get(field) != after.get(field)}
502
+
503
+
504
+ def _actions(before: dict, after: dict, changes: dict) -> list[tuple[str, dict]]:
505
+ """The ``action``s GitHub sends for one update: ``edited`` with what changed, then a state move."""
506
+ edited = [("edited", {"changes": changes})] if changes else []
507
+ moved = {("open", "closed"): "closed", ("closed", "open"): "reopened"}.get((before["state"], after["state"]))
508
+ return edited + ([(moved, {})] if moved else [])
459
509
 
460
510
 
461
511
  def list_user_orgs(ctx, args, query, body):
@@ -487,9 +537,6 @@ def list_user_gists(ctx, args, query, body):
487
537
  return _where(ctx.rows(GISTS), owner_id=user["id"])
488
538
 
489
539
 
490
- # ---------------------------------------------------------------- organizations
491
-
492
-
493
540
  def update_organization(ctx, args, query, body):
494
541
  org = _org(ctx, args)
495
542
  if org is None:
@@ -713,9 +760,6 @@ def get_org_installation(ctx, args, query, body):
713
760
  return ctx.not_found() if row is None else row
714
761
 
715
762
 
716
- # ---------------------------------------------------------------- teams
717
-
718
-
719
763
  def _team_simple(team: dict) -> dict:
720
764
  keys = (
721
765
  "id",
@@ -882,9 +926,6 @@ def remove_team_repo(ctx, args, query, body):
882
926
  return _gone(ctx, TEAM_REPOS, row)
883
927
 
884
928
 
885
- # ---------------------------------------------------------------- repositories
886
-
887
-
888
929
  def update_repo(ctx, args, query, body):
889
930
  repo = _repo(ctx, args)
890
931
  if repo is None:
@@ -1021,6 +1062,77 @@ def _git_ref(ctx, repo: dict, ref: str) -> dict | None:
1021
1062
  return _first(_in_repo(ctx, REFS, repo, ref=ref if ref.startswith("refs/") else f"refs/{ref}"))
1022
1063
 
1023
1064
 
1065
+ def _ancestry(ctx, repo: dict, shas: list[str]) -> list[dict]:
1066
+ """Every commit row reachable from ``shas`` through ``parents``, newest first."""
1067
+ commits = {row["sha"]: row for row in _in_repo(ctx, COMMITS, repo)}
1068
+ seen: dict[str, dict] = {}
1069
+ queue = [sha for sha in shas if sha in commits]
1070
+ while queue:
1071
+ sha = queue.pop(0)
1072
+ if sha in seen:
1073
+ continue
1074
+ seen[sha] = commits[sha]
1075
+ queue.extend(parent["sha"] for parent in commits[sha].get("parents") or [] if parent["sha"] in commits)
1076
+ return list(seen.values())
1077
+
1078
+
1079
+ def _git_person(git: dict, user: dict | None) -> dict:
1080
+ person = {"name": git.get("name"), "email": git.get("email")}
1081
+ return {**person, "username": user["login"]} if user and user.get("login") else person
1082
+
1083
+
1084
+ def _pushed_commit(repo: dict, row: dict) -> dict:
1085
+ git = row["commit"]
1086
+ files = row.get("files") or []
1087
+ named = {status: [f["filename"] for f in files if f.get("status") == status] for status in ("added", "removed")}
1088
+ return {
1089
+ "id": row["sha"],
1090
+ "tree_id": git["tree"]["sha"],
1091
+ "distinct": True,
1092
+ "message": git["message"],
1093
+ "timestamp": git["committer"]["date"],
1094
+ "url": f"{WEB}/{repo['full_name']}/commit/{row['sha']}",
1095
+ "author": _git_person(git["author"], row.get("author")),
1096
+ "committer": _git_person(git["committer"], row.get("committer")),
1097
+ **named,
1098
+ "modified": [f["filename"] for f in files if f.get("status") not in named],
1099
+ }
1100
+
1101
+
1102
+ def _push_repository(repository: dict) -> dict:
1103
+ org = repository.get("organization")
1104
+ pushed = {k: v for k, v in repository.items() if k != "organization"}
1105
+ return {**pushed, **({"organization": org["login"]} if isinstance(org, dict) else {})}
1106
+
1107
+
1108
+ REPOSITORY_FORMS = {"push": _push_repository}
1109
+
1110
+
1111
+ def _deliver_push(ctx, repo: dict, ref: str, before: str | None, after: str | None) -> None:
1112
+ """``push`` for a ref the Git refs API moved: the commits ``after`` brings that ``before``
1113
+ (for a new ref, every other ref) did not already reach."""
1114
+ others = [row["object"]["sha"] for row in _in_repo(ctx, REFS, repo) if row["ref"] != ref]
1115
+ known = {row["sha"] for row in _ancestry(ctx, repo, [before] if before else others)}
1116
+ reached = _ancestry(ctx, repo, [after] if after else [])
1117
+ head = reached[0] if reached and reached[0]["sha"] == after else None
1118
+ old, new = before or NO_SHA, after or NO_SHA
1119
+ actor = _actor(ctx)
1120
+ body = {
1121
+ "ref": ref,
1122
+ "before": old,
1123
+ "after": new,
1124
+ "created": before is None,
1125
+ "deleted": after is None,
1126
+ "forced": bool(before and after) and before not in {row["sha"] for row in reached},
1127
+ "base_ref": None,
1128
+ "compare": f"{WEB}/{repo['full_name']}/compare/{old[:12]}...{new[:12]}",
1129
+ "commits": [_pushed_commit(repo, row) for row in reversed(reached) if row["sha"] not in known],
1130
+ "head_commit": _pushed_commit(repo, head) if head else None,
1131
+ "pusher": {"name": actor["login"], "email": actor.get("email")},
1132
+ }
1133
+ _deliver(ctx, "push", repo, body)
1134
+
1135
+
1024
1136
  def create_git_ref(ctx, args, query, body):
1025
1137
  repo = _repo(ctx, args)
1026
1138
  if repo is None:
@@ -1029,7 +1141,8 @@ def create_git_ref(ctx, args, query, body):
1029
1141
  return ctx.invalid("ref must start with refs/ and sha is required")
1030
1142
  if _git_ref(ctx, repo, body["ref"]):
1031
1143
  return ctx.invalid("Reference already exists")
1032
- if _resolve_sha(ctx, repo, body["sha"]) is None:
1144
+ sha = _resolve_sha(ctx, repo, body["sha"])
1145
+ if sha is None:
1033
1146
  return ctx.invalid("Object does not exist")
1034
1147
  full = repo["full_name"]
1035
1148
  row = {
@@ -1039,7 +1152,9 @@ def create_git_ref(ctx, args, query, body):
1039
1152
  "object": {"type": "commit", "sha": body["sha"], "url": f"{API}/repos/{full}/git/commits/{body['sha']}"},
1040
1153
  "repo_id": repo["id"],
1041
1154
  }
1042
- return 201, _insert(ctx, REFS, row)
1155
+ created = _insert(ctx, REFS, row)
1156
+ _deliver_push(ctx, repo, created["ref"], None, sha)
1157
+ return 201, created
1043
1158
 
1044
1159
 
1045
1160
  def get_git_ref(ctx, args, query, body):
@@ -1063,10 +1178,13 @@ def update_git_ref(ctx, args, query, body):
1063
1178
  return ctx.not_found()
1064
1179
  if not isinstance(body, dict) or not body.get("sha"):
1065
1180
  return ctx.invalid("sha is required")
1066
- if _resolve_sha(ctx, repo, body["sha"]) is None:
1181
+ sha = _resolve_sha(ctx, repo, body["sha"])
1182
+ if sha is None:
1067
1183
  return ctx.invalid("Object does not exist")
1068
1184
  target = {**row["object"], "sha": body["sha"], "url": f"{API}/repos/{repo['full_name']}/git/commits/{body['sha']}"}
1069
- return _patch(ctx, REFS, row, {}, object=target)
1185
+ updated = _patch(ctx, REFS, row, {}, object=target)
1186
+ _deliver_push(ctx, repo, row["ref"], row["object"]["sha"], sha)
1187
+ return updated
1070
1188
 
1071
1189
 
1072
1190
  def delete_git_ref(ctx, args, query, body):
@@ -1074,7 +1192,9 @@ def delete_git_ref(ctx, args, query, body):
1074
1192
  row = None if repo is None else _git_ref(ctx, repo, args["ref"])
1075
1193
  if row is None:
1076
1194
  return ctx.not_found()
1077
- return _gone(ctx, REFS, row)
1195
+ gone = _gone(ctx, REFS, row)
1196
+ _deliver_push(ctx, repo, row["ref"], row["object"]["sha"], None)
1197
+ return gone
1078
1198
 
1079
1199
 
1080
1200
  def list_commits(ctx, args, query, body):
@@ -1482,9 +1602,17 @@ def delete_release_asset(ctx, args, query, body):
1482
1602
  return _gone(ctx, ASSETS, row)
1483
1603
 
1484
1604
 
1605
+ def _hook_answer(ctx, row: dict) -> dict:
1606
+ hook = _vendor(ctx, WEBHOOKS, row)
1607
+ config = dict(hook.get("config") or {})
1608
+ if config.get("secret"):
1609
+ config["secret"] = MASKED_SECRET
1610
+ return {**hook, "config": config}
1611
+
1612
+
1485
1613
  def list_webhooks(ctx, args, query, body):
1486
1614
  _, rows = _repo_rows(ctx, args, WEBHOOKS)
1487
- return rows
1615
+ return rows if isinstance(rows, tuple) else [_hook_answer(ctx, row) for row in rows]
1488
1616
 
1489
1617
 
1490
1618
  def create_webhook(ctx, args, query, body):
@@ -1512,12 +1640,14 @@ def create_webhook(ctx, args, query, body):
1512
1640
  "last_response": {"code": None, "status": "unused", "message": None},
1513
1641
  "repo_id": repo["id"],
1514
1642
  }
1515
- return 201, _insert(ctx, WEBHOOKS, row)
1643
+ hook = _hook_answer(ctx, _insert(ctx, WEBHOOKS, row))
1644
+ _deliver(ctx, "ping", repo, {"zen": ZEN, "hook_id": ident, "hook": hook}, hook=str(ident))
1645
+ return 201, hook
1516
1646
 
1517
1647
 
1518
1648
  def get_webhook(ctx, args, query, body):
1519
1649
  _, row = _repo_row(ctx, args, WEBHOOKS, id=args["hook_id"])
1520
- return ctx.not_found() if row is None else row
1650
+ return ctx.not_found() if row is None else _hook_answer(ctx, row)
1521
1651
 
1522
1652
 
1523
1653
  def update_webhook(ctx, args, query, body):
@@ -1529,7 +1659,17 @@ def update_webhook(ctx, args, query, body):
1529
1659
  events = [e for e in events if e not in body.get("remove_events", [])] + [
1530
1660
  e for e in body.get("add_events", []) if e not in events
1531
1661
  ]
1532
- return _patch(ctx, WEBHOOKS, row, body, ("config", "active"), events=events)
1662
+ if isinstance(body.get("config"), dict):
1663
+ body = {**body, "config": _kept_config(row.get("config") or {}, body["config"])}
1664
+ return _hook_answer(ctx, _patch(ctx, WEBHOOKS, row, body, ("config", "active"), events=events))
1665
+
1666
+
1667
+ def _kept_config(stored: dict, sent: dict) -> dict:
1668
+ """A PATCH keeps what it does not name, and the masked secret it was shown keeps the real one."""
1669
+ merged = {**stored, **sent}
1670
+ if sent.get("secret") == MASKED_SECRET:
1671
+ merged["secret"] = stored.get("secret")
1672
+ return merged
1533
1673
 
1534
1674
 
1535
1675
  def delete_webhook(ctx, args, query, body):
@@ -1544,9 +1684,6 @@ def list_stargazers(ctx, args, query, body):
1544
1684
  return rows
1545
1685
 
1546
1686
 
1547
- # ---------------------------------------------------------------- actions and checks
1548
-
1549
-
1550
1687
  def _counted(rows: Any, key: str) -> Any:
1551
1688
  if rows is None or isinstance(rows, tuple):
1552
1689
  return rows
@@ -1714,9 +1851,6 @@ def update_check_run(ctx, args, query, body):
1714
1851
  )
1715
1852
 
1716
1853
 
1717
- # ---------------------------------------------------------------- labels and milestones
1718
-
1719
-
1720
1854
  def list_labels(ctx, args, query, body):
1721
1855
  _, rows = _repo_rows(ctx, args, LABELS)
1722
1856
  return rows
@@ -1847,9 +1981,6 @@ def list_milestone_labels(ctx, args, query, body):
1847
1981
  return _full_labels(ctx, repo, list(seen.values()))
1848
1982
 
1849
1983
 
1850
- # ---------------------------------------------------------------- issues
1851
-
1852
-
1853
1984
  ISSUE_FILTERS = {
1854
1985
  "state": "state",
1855
1986
  "assignee": "assignee.login",
@@ -1936,9 +2067,16 @@ def create_issue(ctx, args, query, body):
1936
2067
  "created_at": now,
1937
2068
  "updated_at": now,
1938
2069
  "author_association": "MEMBER",
2070
+ "reactions": _reactions(f"{API}/repos/{full}/issues/{number}"),
1939
2071
  "repo_id": repo["id"],
1940
2072
  }
1941
- return 201, _insert(ctx, ISSUES, row)
2073
+ created = _insert(ctx, ISSUES, row)
2074
+ _deliver_issue(ctx, repo, "opened", created)
2075
+ return 201, created
2076
+
2077
+
2078
+ def _deliver_issue(ctx, repo: dict, action: str, issue: dict, **extra: Any) -> None:
2079
+ _deliver(ctx, "issues", repo, {"action": action, **extra, "issue": _vendor(ctx, ISSUES, issue)})
1942
2080
 
1943
2081
 
1944
2082
  def _issue(ctx, args):
@@ -1972,7 +2110,10 @@ def update_issue(ctx, args, query, body):
1972
2110
  if body.get("state") == "open" and row["state"] != "open":
1973
2111
  extra["closed_at"] = None
1974
2112
  extra["state_reason"] = "reopened"
1975
- return _patch(ctx, ISSUES, row, body, ("title", "body", "state"), **extra)
2113
+ updated = _patch(ctx, ISSUES, row, body, ("title", "body", "state"), **extra)
2114
+ for action, detail in _actions(row, updated, _changes(row, updated, ("title", "body"))):
2115
+ _deliver_issue(ctx, repo, action, updated, **detail)
2116
+ return updated
1976
2117
 
1977
2118
 
1978
2119
  def lock_issue(ctx, args, query, body):
@@ -2128,11 +2269,23 @@ def create_issue_comment(ctx, args, query, body):
2128
2269
  "issue_url": issue["url"],
2129
2270
  "author_association": "MEMBER",
2130
2271
  "html_url": f"{issue['html_url']}#issuecomment-{ident}",
2272
+ "performed_via_github_app": None,
2273
+ "reactions": _reactions(f"{API}/repos/{full}/issues/comments/{ident}"),
2131
2274
  "repo_id": repo["id"],
2132
2275
  "issue_number": issue["number"],
2133
2276
  }
2134
2277
  created = _insert(ctx, ISSUE_COMMENTS, row)
2135
- _patch(ctx, ISSUES, issue, {}, comments=issue["comments"] + 1)
2278
+ commented = _patch(ctx, ISSUES, issue, {}, comments=issue["comments"] + 1)
2279
+ _deliver(
2280
+ ctx,
2281
+ "issue_comment",
2282
+ repo,
2283
+ {
2284
+ "action": "created",
2285
+ "issue": _vendor(ctx, ISSUES, commented),
2286
+ "comment": _vendor(ctx, ISSUE_COMMENTS, created),
2287
+ },
2288
+ )
2136
2289
  return 201, created
2137
2290
 
2138
2291
 
@@ -2153,9 +2306,6 @@ def list_issue_events(ctx, args, query, body):
2153
2306
  return _in_repo(ctx, ISSUE_EVENTS, repo, issue__number=issue["number"])
2154
2307
 
2155
2308
 
2156
- # ---------------------------------------------------------------- pull requests
2157
-
2158
-
2159
2309
  PULL_FILTERS = {"state": "state", "head": "head.label", "base": "base.ref"}
2160
2310
 
2161
2311
 
@@ -2262,7 +2412,21 @@ def create_pull_request(ctx, args, query, body):
2262
2412
  "changed_files": 0,
2263
2413
  "repo_id": repo["id"],
2264
2414
  }
2265
- return 201, _insert(ctx, PULLS, row)
2415
+ created = _insert(ctx, PULLS, row)
2416
+ _deliver_pull(ctx, repo, "opened", created)
2417
+ return 201, created
2418
+
2419
+
2420
+ def _deliver_pull(ctx, repo: dict, action: str, pull: dict, **extra: Any) -> None:
2421
+ body = {"action": action, "number": pull["number"], **extra, "pull_request": _vendor(ctx, PULLS, pull)}
2422
+ _deliver(ctx, "pull_request", repo, body)
2423
+
2424
+
2425
+ def _pull_changes(before: dict, after: dict) -> dict:
2426
+ changes = _changes(before, after, ("title", "body"))
2427
+ moved = before["base"]["ref"] != after["base"]["ref"]
2428
+ base = {"ref": {"from": before["base"]["ref"]}, "sha": {"from": before["base"]["sha"]}}
2429
+ return {**changes, **({"base": base} if moved else {})}
2266
2430
 
2267
2431
 
2268
2432
  def get_pull_request(ctx, args, query, body):
@@ -2285,7 +2449,10 @@ def update_pull_request(ctx, args, query, body):
2285
2449
  extra["closed_at"] = ctx.now()
2286
2450
  if body.get("state") == "open" and row["state"] != "open":
2287
2451
  extra["closed_at"] = None
2288
- return _patch(ctx, PULLS, row, body, ("title", "body", "state", "maintainer_can_modify"), **extra)
2452
+ updated = _patch(ctx, PULLS, row, body, ("title", "body", "state", "maintainer_can_modify"), **extra)
2453
+ for action, detail in _actions(row, updated, _pull_changes(row, updated)):
2454
+ _deliver_pull(ctx, repo, action, updated, **detail)
2455
+ return updated
2289
2456
 
2290
2457
 
2291
2458
  def list_pull_request_commits(ctx, args, query, body):
@@ -2301,7 +2468,7 @@ def check_pull_request_merged(ctx, args, query, body):
2301
2468
 
2302
2469
 
2303
2470
  def merge_pull_request(ctx, args, query, body):
2304
- _, row = _pull(ctx, args)
2471
+ repo, row = _pull(ctx, args)
2305
2472
  if row is None:
2306
2473
  return ctx.not_found()
2307
2474
  if row["merged"] or row["state"] != "open":
@@ -2314,7 +2481,7 @@ def merge_pull_request(ctx, args, query, body):
2314
2481
  }
2315
2482
  now = ctx.now()
2316
2483
  sha = _sha("merge", row["id"], now)
2317
- _patch(
2484
+ merged = _patch(
2318
2485
  ctx,
2319
2486
  PULLS,
2320
2487
  row,
@@ -2328,6 +2495,7 @@ def merge_pull_request(ctx, args, query, body):
2328
2495
  mergeable=None,
2329
2496
  mergeable_state="unknown",
2330
2497
  )
2498
+ _deliver_pull(ctx, repo, "closed", merged)
2331
2499
  return {"sha": sha, "merged": True, "message": "Pull Request successfully merged"}
2332
2500
 
2333
2501
 
@@ -2531,9 +2699,6 @@ def delete_review_comment(ctx, args, query, body):
2531
2699
  return _gone(ctx, REVIEW_COMMENTS, row)
2532
2700
 
2533
2701
 
2534
- # ---------------------------------------------------------------- security alerts
2535
-
2536
-
2537
2702
  def list_code_scanning_alerts(ctx, args, query, body):
2538
2703
  _, rows = _repo_rows(
2539
2704
  ctx,
@@ -2683,9 +2848,6 @@ def update_secret_scanning_alert(ctx, args, query, body):
2683
2848
  return _patch(ctx, SECRET_ALERTS, row, {}, **patch)
2684
2849
 
2685
2850
 
2686
- # ---------------------------------------------------------------- gists
2687
-
2688
-
2689
2851
  def create_gist(ctx, args, query, body):
2690
2852
  if not isinstance(body, dict) or not isinstance(body.get("files"), dict) or not body["files"]:
2691
2853
  return ctx.invalid("files is required")
@@ -2822,9 +2984,6 @@ def delete_gist_comment(ctx, args, query, body):
2822
2984
  return _gone(ctx, GIST_COMMENTS, row)
2823
2985
 
2824
2986
 
2825
- # ---------------------------------------------------------------- apps and search
2826
-
2827
-
2828
2987
  def delete_installation(ctx, args, query, body):
2829
2988
  row = _first(_where(ctx.rows(INSTALLATIONS), id=args["installation_id"]))
2830
2989
  if row is None:
@@ -1,15 +1,3 @@
1
- # GitHub REST API served from the world's store.
2
- #
3
- # Paths, methods and status codes come from github/rest-api-description
4
- # (descriptions/api.github.com/api.github.com.json) at the commit pinned in
5
- # provenance.json; vendor-openapi.json is that document trimmed to these paths.
6
- # Declarative reads filter on row fields. Routes that address a repository by
7
- # {owner}/{repo} (rows carry repo_id), every write and every computed answer run
8
- # in api/handlers.py. The acting identity for writes is the first github_users row
9
- # (the world has no token-to-user binding). Pagination is not emulated: list routes
10
- # answer every matching row and accept per_page/page without slicing.
11
- # `sample*` values point the conformance run at rows of scenarios/default.
12
-
13
1
  [connector]
14
2
  slug = "github"
15
3
  base_url = "https://api.github.com"
@@ -19,9 +7,6 @@ scheme = "bearer"
19
7
  prefixes = ["Bearer", "token"]
20
8
  secret_env = "GITHUB_TOKEN"
21
9
 
22
- # email is the PII a capture sees on commit authors, users and organizations; `secret`
23
- # is the leaked credential a secret-scanning alert carries and a webhook's shared secret.
24
- # Logins, avatar URLs and display names stay clear: they are the values routes filter on.
25
10
  [redact]
26
11
  hash = ["email"]
27
12
  drop = ["secret"]
@@ -36,15 +21,20 @@ invalid = '{"message": "Validation Failed", "documentation_url": "https://docs.g
36
21
  invalid_status = 422
37
22
  handlers = "api/handlers.py"
38
23
 
39
- # The browsable UI over these routes: `gateway worlds schema compile` generates
40
- # ui/static (index.html, app.js, contract.json) from the contract; a session
41
- # opened with `--surface ui` serves it and `--surface browser` drives it. Set
42
- # `generated = false` to hand-write ui/static instead.
43
24
  [ui]
44
25
  static = "ui/static"
45
26
  entry = "/"
46
27
  generated = true
47
28
 
29
+ [webhooks]
30
+ subscriptions = "github_webhooks"
31
+ url = "config_url"
32
+ events = "delivery_events"
33
+ secret = "config_secret"
34
+ enabled = "active"
35
+ scope = { repo = "repo_id", hook = "id" }
36
+ signing = "github"
37
+
48
38
  [[operations]]
49
39
  name = "list_users"
50
40
  path = "/users"
@@ -12,7 +12,8 @@
12
12
  "config": {
13
13
  "url": "https://hooks.example.com/github",
14
14
  "content_type": "json",
15
- "insecure_ssl": "0"
15
+ "insecure_ssl": "0",
16
+ "secret": "example-hook-secret-13001"
16
17
  },
17
18
  "updated_at": "2026-03-02T09:00:00Z",
18
19
  "created_at": "2026-01-15T09:00:00Z",
@@ -25,7 +26,14 @@
25
26
  "status": "active",
26
27
  "message": "OK"
27
28
  },
28
- "repo_id": 3001
29
+ "repo_id": 3001,
30
+ "config_url": "https://hooks.example.com/github",
31
+ "config_secret": "example-hook-secret-13001",
32
+ "delivery_events": [
33
+ "push",
34
+ "pull_request",
35
+ "ping"
36
+ ]
29
37
  }
30
38
  ]
31
39
  }
@@ -0,0 +1,47 @@
1
+ {
2
+ "group": "github webhooks",
3
+ "scenario": "default",
4
+ "cases": [
5
+ {
6
+ "name": "a repository hook registers with its secret masked",
7
+ "request": {
8
+ "method": "POST",
9
+ "path": "/repos/acme-widgets/scratchpad/hooks",
10
+ "body": {
11
+ "name": "web",
12
+ "events": ["issues"],
13
+ "config": {"url": "https://receiver.example.org/github", "content_type": "json", "secret": "example-hook-secret"}
14
+ }
15
+ },
16
+ "expect": {
17
+ "status": 201,
18
+ "json": {"type": "Repository", "active": true, "events": ["issues"], "config": {"secret": "********"}}
19
+ }
20
+ },
21
+ {
22
+ "name": "an issue opens on the hooked repository",
23
+ "request": {"method": "POST", "path": "/repos/acme-widgets/scratchpad/issues", "body": {"title": "Webhook smoke"}},
24
+ "expect": {"status": 201, "json": {"title": "Webhook smoke", "state": "open"}}
25
+ },
26
+ {
27
+ "name": "an issue without a title is refused",
28
+ "request": {"method": "POST", "path": "/repos/acme-widgets/scratchpad/issues", "body": {"body": "no title"}},
29
+ "expect": {"status": 422}
30
+ },
31
+ {
32
+ "name": "the hook was pinged, then heard the issue open, and nothing for the refusal",
33
+ "request": {"method": "POST", "path": "/__session/webhooks", "body": {"after": 0}},
34
+ "expect": {
35
+ "status": 200,
36
+ "length": {"path": "deliveries", "eq": 2},
37
+ "json": {
38
+ "deliveries": [
39
+ {"eventType": "ping", "url": "https://receiver.example.org/github", "headers": {"x-github-event": "ping"}},
40
+ {"eventType": "issues", "url": "https://receiver.example.org/github", "headers": {"x-github-event": "issues"}}
41
+ ]
42
+ },
43
+ "contains": ["{\\\"action\\\":\\\"opened\\\",\\\"issue\\\":", "x-hub-signature-256"]
44
+ }
45
+ }
46
+ ]
47
+ }
@@ -3145,6 +3145,27 @@
3145
3145
  "repo_id": {
3146
3146
  "type": "integer",
3147
3147
  "description": "Repository containment key: the id of the repository the REST route addresses by {owner}/{repo}."
3148
+ },
3149
+ "config_url": {
3150
+ "type": [
3151
+ "string",
3152
+ "null"
3153
+ ],
3154
+ "description": "Direct projection of `config.url`, the receiver the world's `[webhooks]` delivers to; the nested vendor object stays intact."
3155
+ },
3156
+ "config_secret": {
3157
+ "type": [
3158
+ "string",
3159
+ "null"
3160
+ ],
3161
+ "description": "Direct projection of `config.secret`, the key the world's `[webhooks]` signs `X-Hub-Signature-256` with; the nested vendor object stays intact."
3162
+ },
3163
+ "delivery_events": {
3164
+ "type": "array",
3165
+ "items": {
3166
+ "type": "string"
3167
+ },
3168
+ "description": "Direct projection of `events` as the world's `[webhooks]` reads it: empty for `*` (every event), otherwise `events` plus `ping`, which GitHub sends a new hook whatever it subscribes to."
3148
3169
  }
3149
3170
  },
3150
3171
  "required": [