@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
@@ -4,11 +4,22 @@
4
4
  url, priorityLabel, branchName, timestamps); `*Archive` / `*Unarchive` stamp or clear
5
5
  `archivedAt`; `organization` answers the viewer's workspace. Everything persists through the
6
6
  contract, so a body the schema refuses is the vendor's 400.
7
+
8
+ Issue and comment writes send Linear's data change webhook (`action`, `type`, `data`, `url`,
9
+ `updatedFrom` on update) to each subscription that wants the resource type and holds the team.
7
10
  """
8
11
 
9
12
  import re
10
13
 
11
14
  PRIORITY_LABELS = {0: "No priority", 1: "Urgent", 2: "High", 3: "Medium", 4: "Low"}
15
+ WEBHOOK_DEFAULTS = {
16
+ "allPublicTeams": False,
17
+ "archivedAt": None,
18
+ "creatorId": None,
19
+ "enabled": True,
20
+ "label": None,
21
+ "teamId": None,
22
+ }
12
23
 
13
24
 
14
25
  def _nullable(prop):
@@ -87,6 +98,7 @@ def issue_create(ctx, args, query, body):
87
98
  created = ctx.insert("linear_issues", _complete(ctx, "linear_issues", row))
88
99
  for label_id in label_ids:
89
100
  ctx.insert("linear_issue_labels", {"issueId": created["id"], "labelId": label_id})
101
+ _notify(ctx, "create", "linear_issues", created)
90
102
  return 200, created
91
103
 
92
104
 
@@ -108,7 +120,9 @@ def comment_create(ctx, args, query, body):
108
120
  "createdAt": now,
109
121
  "updatedAt": now,
110
122
  }
111
- return 200, ctx.insert("linear_comments", _complete(ctx, "linear_comments", row))
123
+ created = ctx.insert("linear_comments", _complete(ctx, "linear_comments", row))
124
+ _notify(ctx, "create", "linear_comments", created)
125
+ return 200, created
112
126
 
113
127
 
114
128
  def _one(ctx, args):
@@ -117,6 +131,76 @@ def _one(ctx, args):
117
131
  return entity, row
118
132
 
119
133
 
134
+ def updated(ctx, args, query, body):
135
+ entity, row = _one(ctx, args)
136
+ if row is None:
137
+ return ctx.not_found()
138
+ patch = {"updatedAt": ctx.now(), **(body if isinstance(body, dict) else {})}
139
+ written = ctx.update(entity, {"id": row["id"]}, patch)
140
+ _notify(ctx, "update", entity, written, _previous(row, written))
141
+ return 200, written
142
+
143
+
144
+ def removed(ctx, args, query, body):
145
+ entity, row = _one(ctx, args)
146
+ if row is None:
147
+ return ctx.not_found()
148
+ ctx.delete(entity, {"id": row["id"]})
149
+ _notify(ctx, "remove", entity, row)
150
+ return 200, None
151
+
152
+
153
+ def webhook_create(ctx, args, query, body):
154
+ body = dict(body) if isinstance(body, dict) else {}
155
+ if not body.get("url"):
156
+ return ctx.invalid("url is required")
157
+ now = ctx.now()
158
+ row = {
159
+ **WEBHOOK_DEFAULTS,
160
+ **body,
161
+ "id": body.get("id") or ctx.uuid(),
162
+ "secret": body.get("secret") or ctx.uuid().replace("-", "") + ctx.uuid().replace("-", ""),
163
+ "createdAt": now,
164
+ "updatedAt": now,
165
+ }
166
+ return 200, ctx.insert("linear_webhooks", row)
167
+
168
+
169
+ def _previous(before, after):
170
+ return {name: before.get(name) for name, value in after.items() if before.get(name) != value}
171
+
172
+
173
+ def _issue_team(ctx, row):
174
+ return row.get("teamId")
175
+
176
+
177
+ def _comment_team(ctx, row):
178
+ issue = ctx.get("linear_issues", {"id": row["issueId"]}) if row.get("issueId") else None
179
+ return issue["teamId"] if issue else None
180
+
181
+
182
+ RESOURCES = {"linear_issues": ("Issue", _issue_team), "linear_comments": ("Comment", _comment_team)}
183
+
184
+
185
+ def _notify(ctx, action, entity, row, previous=None):
186
+ resource, team_of = RESOURCES[entity]
187
+ organizations = ctx.rows("linear_organizations")
188
+ payload = {
189
+ "action": action,
190
+ "type": resource,
191
+ "actor": None,
192
+ "createdAt": ctx.now(),
193
+ "data": row,
194
+ "url": row.get("url"),
195
+ "organizationId": organizations[0]["id"] if organizations else None,
196
+ "webhookTimestamp": int(ctx.clock() * 1000),
197
+ }
198
+ if previous is not None:
199
+ payload["updatedFrom"] = previous
200
+ team = team_of(ctx, row)
201
+ ctx.deliver(resource, payload, scope={"teamId": team} if team else None)
202
+
203
+
120
204
  def archive(ctx, args, query, body):
121
205
  entity, row = _one(ctx, args)
122
206
  if row is None:
@@ -1,25 +1,13 @@
1
- # Linear, served REST-shaped from the schema world.
2
- #
3
- # Linear's API is one GraphQL endpoint (POST https://api.linear.app/graphql). This world
4
- # serves the documented root queries and mutations of the pinned SDL as HTTP routes, one
5
- # per root field, named after that field in snake_case: `issues` -> GET /issues, `issue(id)` -> GET
6
- # /issues/{id}, `issueCreate` -> POST /issues, `issueUpdate` -> PATCH /issues/{id},
7
- # `issueDelete` -> DELETE /issues/{id}, `issueArchive` -> POST /issues/{id}/archive. A by-id
8
- # query whose name a mutation also uses (`projectUpdate`, `initiativeUpdate`) is `<name>_get`.
9
- # The paths are this world's, not the vendor's; the entities, fields, argument names,
10
- # auth header, page size and error body follow the vendor documents in provenance.json.
11
1
 
12
2
  [connector]
13
3
  slug = "linear"
14
4
  base_url = "https://api.linear.app"
15
5
 
16
- # linear.app/developers/graphql: personal API keys go in `Authorization: <API_KEY>`.
17
6
  [auth]
18
7
  scheme = "header"
19
8
  name = "Authorization"
20
9
  secret_env = "LINEAR_API_KEY"
21
10
 
22
- # linear.app/developers/rate-limiting: 2,500 requests per hour per API key.
23
11
  [capture]
24
12
  requests_per_minute = 40
25
13
  timeout_seconds = 30
@@ -31,7 +19,6 @@ cursor_field = "endCursor"
31
19
  hash = ["email", "name", "displayName", "initials", "description", "body", "bodyData", "avatarUrl", "domains", "externalIds", "phone", "url", "gitBranchFormat"]
32
20
  drop = ["secret", "templateData"]
33
21
 
34
- # Connections answer `{nodes, endCursor}` paged by `first`/`after` (default 50 records).
35
22
  [api]
36
23
  envelope = "nodes"
37
24
  hits_key = ""
@@ -49,10 +36,15 @@ invalid_status = 400
49
36
  invalid = '{"errors": [{"message": "Argument Validation Error"}]}'
50
37
  handlers = "api/handlers.py"
51
38
 
52
- # The browsable UI over these routes: `gateway worlds schema compile` generates
53
- # ui/static (index.html, app.js, contract.json) from the contract; a session
54
- # opened with `--surface ui` serves it and `--surface browser` drives it. Set
55
- # `generated = false` to hand-write ui/static instead.
39
+ [webhooks]
40
+ subscriptions = "linear_webhooks"
41
+ url = "url"
42
+ events = "resourceTypes"
43
+ secret = "secret"
44
+ enabled = "enabled"
45
+ scope = { teamId = "teamId" }
46
+ signing = "linear"
47
+
56
48
  [ui]
57
49
  static = "ui/static"
58
50
  entry = "/"
@@ -699,9 +691,8 @@ method = "PATCH"
699
691
  path = "/issues/{id}"
700
692
  entity = "linear_issues"
701
693
  [operations.api]
702
- action = "update"
703
- status = 200
704
- single = true
694
+ action = "handler"
695
+ handler = "updated"
705
696
  filter = { id = "id" }
706
697
 
707
698
  [[operations]]
@@ -710,8 +701,8 @@ method = "DELETE"
710
701
  path = "/issues/{id}"
711
702
  entity = "linear_issues"
712
703
  [operations.api]
713
- action = "delete"
714
- status = 200
704
+ action = "handler"
705
+ handler = "removed"
715
706
  filter = { id = "id" }
716
707
 
717
708
  [[operations]]
@@ -870,9 +861,8 @@ method = "PATCH"
870
861
  path = "/comments/{id}"
871
862
  entity = "linear_comments"
872
863
  [operations.api]
873
- action = "update"
874
- status = 200
875
- single = true
864
+ action = "handler"
865
+ handler = "updated"
876
866
  filter = { id = "id" }
877
867
 
878
868
  [[operations]]
@@ -881,8 +871,8 @@ method = "DELETE"
881
871
  path = "/comments/{id}"
882
872
  entity = "linear_comments"
883
873
  [operations.api]
884
- action = "delete"
885
- status = 200
874
+ action = "handler"
875
+ handler = "removed"
886
876
  filter = { id = "id" }
887
877
 
888
878
  [[operations]]
@@ -1476,10 +1466,8 @@ method = "POST"
1476
1466
  path = "/webhooks"
1477
1467
  entity = "linear_webhooks"
1478
1468
  [operations.api]
1479
- action = "create"
1480
- status = 200
1481
- single = true
1482
- generate = { "id" = "uuid", "createdAt" = "now", "updatedAt" = "now" }
1469
+ action = "handler"
1470
+ handler = "webhook_create"
1483
1471
 
1484
1472
  [[operations]]
1485
1473
  name = "webhook_update"
@@ -74,13 +74,16 @@
74
74
  {
75
75
  "kind": "docs",
76
76
  "url": "https://linear.app/developers/webhooks",
77
- "version": "public page fetched 2026-09-15 (unversioned)",
78
- "sha256": "9b3c40e50c959d38ddbec2fd1b033cf29b92ad8be85161051cf4dd5df8033dc1",
79
- "bytes": 769613,
80
- "verified_at": "2026-09-15",
77
+ "version": "public page fetched 2026-10-10 (unversioned; first read 2026-09-15 at sha256 9b3c40e50c959d38ddbec2fd1b033cf29b92ad8be85161051cf4dd5df8033dc1)",
78
+ "sha256": "c4a4396cc544f32984868594be677a5938e054bce728b0d6650232738d0e1704",
79
+ "bytes": 753703,
80
+ "verified_at": "2026-10-10",
81
81
  "verification": "Fetched the HTML and computed SHA-256.",
82
82
  "used_for": [
83
- "the Webhook entity's documented purpose and resource types; webhook payloads mirror the GraphQL entities (no separate payload schema is modelled)"
83
+ "the Webhook entity's documented purpose and resource types; webhook payloads mirror the GraphQL entities (no separate payload schema is modelled)",
84
+ "the data change payload: action create/update/remove, type, actor (nullable), createdAt, data, url, updatedFrom on update, organizationId, webhookTimestamp in milliseconds",
85
+ "Linear-Delivery, Linear-Event and Linear-Signature (hex HMAC-SHA256 of the raw body under the webhook's secret)",
86
+ "webhookCreate takes teamId or allPublicTeams: true, url and resourceTypes"
84
87
  ]
85
88
  }
86
89
  ],
@@ -126,8 +129,9 @@
126
129
  "path": "connector.toml",
127
130
  "interface": "REST-shaped routes of this world (not vendor paths); the vendor exposes only POST https://api.linear.app/graphql",
128
131
  "operations": 150,
129
- "by_action": { "read": 55, "create": 24, "update": 28, "delete": 23, "handler": 20 },
130
- "handlers": ["issue_create", "comment_create", "archive", "unarchive", "organization"],
132
+ "by_action": { "read": 55, "create": 23, "update": 26, "delete": 21, "handler": 25 },
133
+ "handlers": ["issue_create", "comment_create", "archive", "unarchive", "organization", "updated", "removed", "webhook_create"],
134
+ "webhooks": "[webhooks] over linear_webhooks (url, resourceTypes, secret, enabled; scope teamId), signing linear; issue_create, comment_create and the updated/removed handlers on issues and comments deliver Linear's data change payload with the resource type (Issue, Comment) as the event type",
131
135
  "entities_without_routes": {
132
136
  "linear_roadmaps": "every roadmap root query and mutation carries @deprecated in the pinned SDL (use initiatives); the entity stays because RoadmapToProject mutations are not deprecated and reference it"
133
137
  }
@@ -137,6 +141,12 @@
137
141
  "WorkflowStateType, Issue.priority bounds and the description-derived uniqueness constraints come from field descriptions, not GraphQL types; User.email and Issue.identifier uniqueness come from the brief; the live API was not queried to confirm enforcement",
138
142
  "the 90 remaining Node types (agents, releases, notifications, custom views, favorites, integrations, OAuth, audit, drafts, history, search results, etc.) are not modelled",
139
143
  "live introspection of https://api.linear.app/graphql was not run (no credential); the SDL is the SDK's published copy at the pinned commit",
140
- "webhook payload shapes are not modelled as entities; only the Webhook resource is"
144
+ "webhook payload shapes are not modelled as entities; only the Webhook resource is",
145
+ "a delivered payload's data is the stored row; Linear's live payload may nest related objects (team, state, labels) the row carries as ids",
146
+ "actor is always null: the world has no viewer to name as the user behind an API key",
147
+ "webhookId is not in the payload: one event's body is signed alike for every subscription, so it cannot name each one; Linear-Timestamp is not sent by the linear signer",
148
+ "the generated secret's format (64 hex characters) and webhookCreate's defaults (enabled true per WebhookCreateInput; allPublicTeams false) for fields the input leaves out",
149
+ "issue and comment archive/unarchive send no webhook: the docs do not say which action Linear sends for them",
150
+ "allPublicTeams is not checked against Team.private: a webhook with no teamId receives every team's events"
141
151
  ]
142
152
  }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "linear_webhooks": [
3
3
  {
4
- "allPublicTeams": false,
4
+ "allPublicTeams": true,
5
5
  "archivedAt": null,
6
6
  "createdAt": "2026-03-02T09:00:00.000Z",
7
7
  "creatorId": "6d9fa919-d264-5efd-b52e-a58dd3a7acb7",
@@ -12,10 +12,26 @@
12
12
  "Issue",
13
13
  "Comment"
14
14
  ],
15
- "secret": null,
16
- "teamId": "cf85bd5a-a2bb-513e-ba81-6dea4c6c5074",
15
+ "secret": "example-issue-sync-signing-secret",
16
+ "teamId": null,
17
17
  "updatedAt": "2026-03-02T09:00:00.000Z",
18
18
  "url": "https://hooks.example.com/linear"
19
+ },
20
+ {
21
+ "allPublicTeams": false,
22
+ "archivedAt": null,
23
+ "createdAt": "2026-04-14T15:30:00.000Z",
24
+ "creatorId": "404e9b3b-5fd4-5f5c-8763-c8ff12f89e8b",
25
+ "enabled": false,
26
+ "id": "0b6f2c1e-4a7d-5e93-9c48-2d1f7a6b3e05",
27
+ "label": "Growth comment digest",
28
+ "resourceTypes": [
29
+ "Comment"
30
+ ],
31
+ "secret": "example-growth-digest-signing-secret",
32
+ "teamId": "2993d931-e0b1-5ff4-b3b9-1e7a012ea0bb",
33
+ "updatedAt": "2026-05-01T08:00:00.000Z",
34
+ "url": "https://digest.example.org/linear/comments"
19
35
  }
20
36
  ]
21
37
  }
@@ -0,0 +1,71 @@
1
+ """Linear's data change webhooks, end to end: register a webhook, write an issue, and read what the
2
+ session's feed says each receiver got.
3
+
4
+ Runs under ``gateway worlds test`` with ``WORLD_URL`` (the served world, the ``default`` scenario
5
+ seeded) and ``WORLD_API_KEY`` in the environment.
6
+ """
7
+
8
+ import hashlib
9
+ import hmac
10
+ import json
11
+ import os
12
+ import urllib.request
13
+
14
+ import pytest
15
+
16
+ URL = os.environ["WORLD_URL"]
17
+ KEY = os.environ["WORLD_API_KEY"]
18
+ PLATFORM = "cf85bd5a-a2bb-513e-ba81-6dea4c6c5074"
19
+ RECEIVER = "https://receiver.example.org/linear"
20
+ SECRET = "example-receiver-signing-secret"
21
+
22
+
23
+ def call(method, path, body=None):
24
+ request = urllib.request.Request(
25
+ URL + path,
26
+ method=method,
27
+ data=None if body is None else json.dumps(body).encode(),
28
+ headers={"Authorization": KEY, "Content-Type": "application/json"},
29
+ )
30
+ with urllib.request.urlopen(request) as reply:
31
+ raw = reply.read()
32
+ return json.loads(raw) if raw else None
33
+
34
+
35
+ def head():
36
+ return call("POST", "/__session/webhooks", {"tail": True, "subscriptions": False})["next"]
37
+
38
+
39
+ def received_after(seq):
40
+ page = call("POST", "/__session/webhooks", {"after": seq, "subscriptions": False})
41
+ return [d for d in page["deliveries"] if d["url"] == RECEIVER]
42
+
43
+
44
+ @pytest.fixture(scope="module", autouse=True)
45
+ def receiver():
46
+ return call("POST", "/webhooks", {"url": RECEIVER, "secret": SECRET, "resourceTypes": ["Issue"], "allPublicTeams": True})
47
+
48
+
49
+ def test_a_registered_webhook_receives_the_issue_signed_with_its_secret():
50
+ seq = head()
51
+ issue = call("POST", "/issues", {"teamId": PLATFORM, "title": "Receiver acknowledges late"})
52
+
53
+ (delivery,) = received_after(seq)
54
+ payload = delivery["payload"].encode()
55
+ assert delivery["headers"]["linear-signature"] == hmac.new(SECRET.encode(), payload, hashlib.sha256).hexdigest()
56
+ assert delivery["headers"]["linear-event"] == "Issue"
57
+ body = json.loads(payload)
58
+ assert (body["action"], body["type"], body["data"]["id"]) == ("create", "Issue", issue["id"])
59
+ assert body["url"] == issue["url"]
60
+
61
+
62
+ def test_an_issue_update_names_what_it_changed_and_a_comment_does_not_reach_an_issue_only_webhook():
63
+ issue = call("POST", "/issues", {"teamId": PLATFORM, "title": "Receiver drops retries"})
64
+ seq = head()
65
+ call("PATCH", f"/issues/{issue['id']}", {"priority": 1})
66
+ call("POST", "/comments", {"issueId": issue["id"], "body": "Reproduced."})
67
+
68
+ (delivery,) = received_after(seq)
69
+ body = json.loads(delivery["payload"])
70
+ assert body["action"] == "update"
71
+ assert body["updatedFrom"]["priority"] == issue["priority"]
@@ -44,6 +44,7 @@ base_url = "https://instance.service-now.com"
44
44
  # is the other supported scheme and is registered per instance. No credential
45
45
  # ships with the template; the served world accepts the host's session credential.
46
46
  scheme = "basic"
47
+ credential = "password"
47
48
  secret_env = "SERVICENOW_BASIC_AUTH"
48
49
 
49
50
  [capture]
@@ -98,7 +99,7 @@ not_found_status = 404
98
99
  invalid_status = 400
99
100
 
100
101
  [ui]
101
- # Rishi's pixel-faithful Next Experience twin, built from twins/servicenow/ui with
102
+ # The Next Experience twin, built from twins/servicenow/ui with
102
103
  # no source edits. `generated = false`: ui/static is a build artifact of that
103
104
  # directory, not the generated page, so compile leaves it alone. The SPA calls the api at the same origin
104
105
  # under /__world-api, which the World Host rewrites onto the routes below.
@@ -109,8 +110,6 @@ entry = "/"
109
110
  api_path = "/__world-api"
110
111
  generated = false
111
112
 
112
- # ------------------------------------------------------- the Table API (vendor)
113
-
114
113
  [[operations]]
115
114
  name = "list_table_records"
116
115
  path = "/api/now/table/{tableName}"
@@ -192,8 +191,6 @@ handler = "delete_table_record"
192
191
  status = 204
193
192
  sample = { tableName = "incident_task", sys_id = "eaaefd673662a9417c46de3a53e6b147" }
194
193
 
195
- # ------------------------------- the Next Experience shell (what the ui calls)
196
-
197
194
  [[operations]]
198
195
  name = "get_me"
199
196
  path = "/api/now/ui/me"
@@ -0,0 +1,54 @@
1
+ """How a world answers browsers: ``[api] cors = true`` says the vendor's API serves pages on any
2
+ origin, so a preflight is answered and every answer names any origin; without it a world sends
3
+ no CORS header and an OPTIONS request is routed like any other method."""
4
+
5
+ from __future__ import annotations
6
+
7
+ import re
8
+ from dataclasses import dataclass
9
+
10
+ ALLOW_ORIGIN = "Access-Control-Allow-Origin"
11
+ REQUESTED_HEADERS = "access-control-request-headers"
12
+ HEADER_NAMES = re.compile(r"[!#$%&'*+.^_`|~0-9A-Za-z-]+(?:[ \t]*,[ \t]*[!#$%&'*+.^_`|~0-9A-Za-z-]+)*")
13
+ MAX_REQUESTED_CHARS = 1024
14
+
15
+ Preflight = tuple[int, None, dict[str, str]]
16
+
17
+
18
+ @dataclass(frozen=True)
19
+ class Cors:
20
+ """A vendor whose API serves no browser."""
21
+
22
+ @staticmethod
23
+ def of(declared: bool, methods: tuple[str, ...]) -> Cors:
24
+ """The world's CORS: :class:`OpenCors` over ``methods`` when declared, else none."""
25
+ return OpenCors(methods) if declared else Cors()
26
+
27
+ def preflight(self, method: str, headers: dict[str, str]) -> Preflight | None:
28
+ return None
29
+
30
+ def carried(self, extra: dict[str, str] | None) -> dict[str, str] | None:
31
+ return extra
32
+
33
+
34
+ @dataclass(frozen=True)
35
+ class OpenCors(Cors):
36
+ """A vendor whose API answers pages on any origin, without credentials. A preflight is
37
+ answered before any credential is checked, since a browser sends none with it: it names the
38
+ methods the world serves and, when they are a list of header names, the headers the page
39
+ asked to send. It reads nothing and writes nothing. Every other answer exposes its headers
40
+ (``Link``, the page headers) to the page."""
41
+
42
+ methods: tuple[str, ...]
43
+
44
+ def preflight(self, method: str, headers: dict[str, str]) -> Preflight | None:
45
+ if method != "OPTIONS":
46
+ return None
47
+ allowed = {ALLOW_ORIGIN: "*", "Access-Control-Allow-Methods": ", ".join(self.methods)}
48
+ requested = headers.get(REQUESTED_HEADERS, "")
49
+ if len(requested) <= MAX_REQUESTED_CHARS and HEADER_NAMES.fullmatch(requested):
50
+ allowed["Access-Control-Allow-Headers"] = requested
51
+ return 204, None, allowed
52
+
53
+ def carried(self, extra: dict[str, str] | None) -> dict[str, str] | None:
54
+ return {**(extra or {}), ALLOW_ORIGIN: "*", "Access-Control-Expose-Headers": "*"}