@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.
- package/README.md +4 -3
- package/dist/cli.js +3005 -1401
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +2996 -1392
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.js +128 -37
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +126 -35
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.d.mts +1 -1
- package/dist/hooks/index.d.ts +1 -1
- package/dist/hooks/index.js +124 -11
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +124 -11
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
- package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
- package/dist/{index-mJhG3vZU.d.mts → index-Di9nNqOY.d.mts} +26 -3
- package/dist/{index-DUHmS74p.d.ts → index-LA-PMRJT.d.ts} +26 -3
- package/dist/index.d.mts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +1078 -260
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1040 -251
- package/dist/index.mjs.map +1 -1
- package/dist/replay/index.d.mts +1 -1
- package/dist/replay/index.d.ts +1 -1
- package/dist/replay/index.js.map +1 -1
- package/dist/replay/index.mjs.map +1 -1
- package/dist/traces/index.js +125 -34
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +123 -32
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +1 -1
- package/dist/tracing/index.d.ts +1 -1
- package/dist/tracing/index.js +7 -1
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +7 -1
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +819 -438
- package/dist/worlds/index.d.ts +819 -438
- package/dist/worlds/index.js +912 -236
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +908 -232
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +1 -1
- package/runtime/gatewaysdk/environment/_bundle.py +4 -6
- package/runtime/gatewaysdk/environment/_materialize.py +5 -25
- package/runtime/gatewaysdk/environment/_world.py +82 -66
- package/runtime/gatewaysdk/environment/backing.py +20 -24
- package/runtime/gatewaysdk/environment/core.py +1 -16
- package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
- package/runtime/gatewaysdk/environment/runtime.py +45 -2
- package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
- package/runtime/gatewaysdk/environment/schema/api.py +198 -474
- package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
- package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +1 -0
- package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
- package/runtime/gatewaysdk/environment/schema/call_capture.py +321 -0
- package/runtime/gatewaysdk/environment/schema/call_log.py +276 -18
- package/runtime/gatewaysdk/environment/schema/call_redaction.py +207 -19
- package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
- package/runtime/gatewaysdk/environment/schema/compiler.py +4 -1
- package/runtime/gatewaysdk/environment/schema/conform.py +38 -35
- package/runtime/gatewaysdk/environment/schema/connector.py +94 -152
- package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
- package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +2 -1
- package/runtime/gatewaysdk/environment/schema/connectors/github/api/handlers.py +217 -58
- package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +10 -19
- package/runtime/gatewaysdk/environment/schema/connectors/github/scenarios/default/seed/github_webhooks.json +10 -2
- package/runtime/gatewaysdk/environment/schema/connectors/github/tests/webhooks.json +47 -0
- package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +21 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/api/handlers.py +185 -18
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/connector.toml +29 -14
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +43 -12
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/scenarios/default/seed/jamf_webhooks.json +2 -2
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +4 -17
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/tests/webhooks.json +107 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/vendor-openapi.json +1 -1
- package/runtime/gatewaysdk/environment/schema/connectors/linear/api/handlers.py +85 -1
- package/runtime/gatewaysdk/environment/schema/connectors/linear/connector.toml +19 -31
- package/runtime/gatewaysdk/environment/schema/connectors/linear/provenance.json +18 -8
- package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json +19 -3
- package/runtime/gatewaysdk/environment/schema/connectors/linear/tests/test_webhooks.py +71 -0
- package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
- package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
- package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
- package/runtime/gatewaysdk/environment/schema/data.py +14 -13
- package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
- package/runtime/gatewaysdk/environment/schema/database/guard.py +45 -37
- package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
- package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
- package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
- package/runtime/gatewaysdk/environment/schema/door.py +899 -0
- package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
- package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +52 -5
- package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
- package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
- package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
- package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
- package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
- package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
- package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
- package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
- package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
- package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
- package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
- package/runtime/gatewaysdk/environment/schema/journal.py +438 -0
- package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
- package/runtime/gatewaysdk/environment/schema/local.py +32 -116
- package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +20 -5
- package/runtime/gatewaysdk/environment/schema/platform.py +29 -234
- package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
- package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
- package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
- package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +136 -176
- package/runtime/gatewaysdk/environment/schema/scaffold.py +2 -1
- package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
- package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
- package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +3 -3
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +50 -28
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +20 -22
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +25 -25
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +71 -7
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
- package/runtime/gatewaysdk/environment/schema/snapshot.py +150 -30
- package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
- package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
- package/runtime/gatewaysdk/environment/schema/tools_world.py +103 -203
- package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
- package/runtime/gatewaysdk/environment/schema/verbs.py +38 -36
- package/runtime/gatewaysdk/environment/schema/webhooks.py +687 -0
- package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
- package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
- package/runtime/gatewaysdk/environment/schema/world_host.py +970 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +83 -11
- package/runtime/gatewaysdk/environment/world.py +1 -1
- package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
- package/skills/agents/connector-template-author.md +5 -1
- package/skills/benchmarks-getting-started/SKILL.md +8 -9
- package/skills/connector-schema-authoring/CONNECTORS.md +3 -3
- package/skills/connector-schema-authoring/SKILL.md +50 -28
- package/skills/connector-schema-authoring/connector-worlds.md +282 -18
- package/skills/connector-schema-authoring/world-schema.md +7 -6
- package/skills/world-data-ingestion/ROWS.md +12 -8
- package/skills/world-data-ingestion/SKILL.md +20 -22
- package/skills/worlds-getting-started/SKILL.md +25 -25
- package/skills/worlds-getting-started/references/cli-mcp-map.md +24 -16
- package/skills/worlds-getting-started/references/gotchas.md +71 -7
- 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
|
-
|
|
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
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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 = "
|
|
703
|
-
|
|
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 = "
|
|
714
|
-
|
|
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 = "
|
|
874
|
-
|
|
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 = "
|
|
885
|
-
|
|
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 = "
|
|
1480
|
-
|
|
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
|
|
78
|
-
"sha256": "
|
|
79
|
-
"bytes":
|
|
80
|
-
"verified_at": "2026-
|
|
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":
|
|
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
|
}
|
package/runtime/gatewaysdk/environment/schema/connectors/linear/scenarios/default/seed/webhooks.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"linear_webhooks": [
|
|
3
3
|
{
|
|
4
|
-
"allPublicTeams":
|
|
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":
|
|
16
|
-
"teamId":
|
|
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
|
-
#
|
|
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": "*"}
|