feat: jira.js/webhooks types what Jira posts to you

Everything else in this library calls Jira. A webhook is the other
direction, and until now there was no way to say what arrives — which is
all issue #294 ever asked for.

Fifty-seven events as a union discriminated by `webhookEvent`, sixteen
payload shapes behind it, and the headers Jira attaches. Types only: the
subpath compiles to `export {}` and the browser bundle does not move.

No parser and no signature check. A webhook body is shaped by the site
that sent it — custom fields under generated keys, whatever an installed
app adds — so a schema strict enough to be worth having would reject
bodies that are valid elsewhere. Verifying `x-hub-signature` is the
caller's, because a signature check that compares the wrong way quietly
is worse than none and there is nothing here to test one against.

How much of this Atlassian documents is written into the types. One
complete payload is published, the one for issue events; that group is
built from it and from a capture of a real delivery, and is the only one
whose entity is required. Every other group names its entity optionally,
after the entity the event concerns, and says so where you hover it.

Headers are lower-cased, as Node delivers them, and every value is typed
as the string an HTTP header is — the retry count included, which the
issue typed as a number.

check:consumers learns that a subpath can be types only: an empty runtime
namespace is now the expected answer for jira.js/webhooks and a populated
one is the failure. Its type probe imports both types under bundler and
nodenext resolution.

Author: MrRefactoring

CHANGELOG.md

@@ -76,6 +76,28 @@ Three long-standing requests, all of them the same shape: the client had no seam
 
   OAuth 2.0 is absent from the config type on purpose: the API refuses it, as it refuses Forge apps, and a compile error says so earlier than a 401 would. A deleted team answers **410** rather than 404 on the next read — the id stays known and reports itself as gone.
 
+* **`jira.js/webhooks` types what Jira posts to you.** Everything else in this library calls Jira; a webhook is the other direction, and until now there was no way to say what arrives. Fifty-seven events as a union discriminated by `webhookEvent`, sixteen payload shapes, and the headers Jira attaches. Closes [#294](https://github.com/MrRefactoring/jira.js/issues/294).
+
+  ```ts
+  import type { WebhookHeaders, WebhookPayload } from 'jira.js/webhooks';
+
+  app.post('/jira', (request, response) => {
+    const payload = request.body as WebhookPayload;
+
+    switch (payload.webhookEvent) {
+      case 'jira:issue_created':
+        console.log(payload.issue.key);
+        break;
+    }
+
+    response.sendStatus(200);
+  });
+  ```
+
+  Types only — the subpath compiles to `export {}` and adds nothing to a bundle. There is no parser and no signature check: a webhook body is shaped by the site that sent it, custom fields and installed apps included, so a schema strict enough to be worth having would reject bodies that are perfectly valid elsewhere.
+
+  How much is documented is worth stating plainly, because the types say it too. Atlassian publishes one complete payload, the one for issue events; that group is written from it and from a capture of a real delivery, and is the only one whose entity is required. Every other group names its entity optionally, after the entity the event concerns. The headers are lower-cased, as they arrive, and every value is typed as the string an HTTP header is — the retry count included.
+
 * **Six more types and schemas are exported from `jira.js/core`.** `authBasicSchema`, `authBearerSchema` and `authOAuth2ServerSchema` beside the `authSchema` that was already there, and the types `CommonClientConfig`, `ParsedClientConfig` and `ErrorKind`. Each was already part of a public type's definition while being unreachable from outside the package — you could receive a `ClientConfig` but not name what it was built from.
 
 * **`getTenantContext` resolves a site's `cloudId`, `orgId` and host name.** Atlassian publishes no REST endpoint for any of the three, and `orgId` in particular names the organization above your site rather than the site itself. The call goes to the GraphQL gateway, which is the documented way to ask, and it takes the client you already built, so it inherits its proxy, retries and custom `fetch`.

README.md

@@ -141,6 +141,7 @@ The documentation includes:
 - **Jira Service Management Data Center API**: self-hosted requests, queues and organizations, from `createServiceDeskServerClient`
 - **Assets API**: objects, schemas, types and AQL — `createAssetsClient` on Cloud, `createAssetsServerClient` self-hosted
 - **Teams API**: teams, their members and external links, at organization level — `createTeamsClient`
+- **Webhook types**: the events, payloads and headers Jira posts to *you* — `jira.js/webhooks`, types only, no client
 
 There is one platform surface, generated from Jira's v3 specification. `Version2Client` and `Version3Client` are gone — the difference between them was never the endpoints, it was rich text. Rich-text fields still accept a wiki-markup **string**: that write is routed through Jira's v2 endpoint, which parses the markup server-side, and the result is read back so what you get is a real [Atlassian Document Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/) document.
 

context7.json

@@ -37,6 +37,7 @@
     "Replace the transport with `fetch` in the client configuration \u2014 `(url, init) => Promise<Response>` \u2014 to log, trace, proxy or record. It is used for the OAuth 2.0 token calls too, so a wrapper that logs request bodies will see `client_secret`. `headers` in the same configuration adds constant headers; note it overrides the `Authorization` the client derives from `auth`.",
     "An expired or revoked API token does not always fail the request: roughly a quarter of Jira operations can be reached anonymously, and there Jira answers 2xx as the anonymous user, reporting the refusal only in `X-Seraph-LoginReason`. Since 6.3 the client throws `AuthError` whenever that header says the credentials were refused, whatever the status, and `error.status` records the status that actually arrived.",
     "Teams are organization-level, not site-level, so `createTeamsClient` operations take an `orgId` parameter rather than reading it from the client configuration \u2014 one account can administer several organizations. Resolve it with `getTenantContext(client)` from `jira.js/core`, which returns `{ cloudId, orgId, hostName }`; Atlassian publishes no REST endpoint for any of the three. The Teams API refuses OAuth 2.0 and Forge apps, so its config type accepts only basic and bearer auth. `getTenantContext` is Cloud-only and throws `ConfigError` under OAuth 2.0 (3LO), where there is no fixed host to ask about.",
+    "Webhooks go the other way \u2014 Jira posts to a server of yours \u2014 so `jira.js/webhooks` is types only and compiles to nothing: `WebhookPayload` is a union of fifty-seven events discriminated by `webhookEvent`, and `WebhookHeaders` types the headers in lower case, as Node delivers them, with every value a string including the retry count. Cast the parsed body and headers; there is no parser and no signature verification, because a webhook body is shaped by the site that sent it. Atlassian documents only the issue payload, so that is the one group whose entity is required \u2014 everywhere else the entity field is optional.",
     "Request parameter types live one level below the surface: `import type { CreateIssue } from 'jira.js/cloud/parameters'`. Response types come from the surface itself (`jira.js/cloud`). They are split because a parameter and a model occasionally share a name."
   ],
   "url": "https://context7.com/mrrefactoring/jira.js",

docs/.vitepress/config.ts

@@ -23,6 +23,7 @@ const guideSidebar = (prefix = '') => [
       { text: 'Assets', link: `${prefix}/guide/assets` },
       { text: 'Teams', link: `${prefix}/guide/teams` },
       { text: prefix ? 'Контекст тенанта' : 'Tenant Context', link: `${prefix}/guide/tenant-context` },
+      { text: prefix ? 'Вебхуки' : 'Webhooks', link: `${prefix}/guide/webhooks` },
       { text: prefix ? 'Обработка ошибок' : 'Error Handling', link: `${prefix}/guide/error-handling` },
       { text: prefix ? 'Валидация ответов' : 'Response Validation', link: `${prefix}/guide/response-validation` },
       { text: 'Tree-Shaking', link: `${prefix}/guide/tree-shaking` },

docs/guide/webhooks.md

@@ -0,0 +1,124 @@
+# Webhooks
+
+Everything else in this library calls Jira. A webhook is Jira calling you: you register a URL, something happens on the
+site, and a `POST` arrives at a server of yours. There is nothing here to call and no client to build — what was
+missing was the shape of what arrives, and that is what `jira.js/webhooks` is.
+
+```typescript
+import type { WebhookHeaders, WebhookPayload } from 'jira.js/webhooks';
+
+app.post('/jira', (request, response) => {
+  const headers = request.headers as WebhookHeaders;
+  const payload = request.body as WebhookPayload;
+
+  switch (payload.webhookEvent) {
+    case 'jira:issue_created':
+      console.log(payload.issue.key, 'created by', payload.user?.displayName);
+      break;
+
+    case 'sprint_started':
+      console.log(payload.sprint?.name, 'started');
+      break;
+  }
+
+  response.sendStatus(200);
+});
+```
+
+The subpath is types only. It compiles to `export {}`, adds nothing to a bundle, and works the same with Express,
+Fastify, Hono, a Lambda handler or a bare `node:http` server.
+
+## The payload
+
+`WebhookPayload` is a union discriminated by `webhookEvent`, so a `switch` narrows each branch to exactly one payload.
+Handle every case and the `default` narrows to `never`, which is how you make an unhandled event a compile error:
+
+```typescript
+default: {
+  const unhandled: never = payload;
+
+  throw new Error(`unhandled webhook event: ${JSON.stringify(unhandled)}`);
+}
+```
+
+Fifty-seven events across sixteen groups: issue, issue property, worklog, comment, attachment, issue link, issue type,
+project, version, filter, user, the site-wide `option_*` toggles, sprint, board, the two app-access refusals, and a
+failed Jira expression. Each group has its own exported type — `IssueWebhookPayload`, `SprintWebhookPayload` and so on
+— if you want to name one directly.
+
+Every payload carries three things:
+
+| | |
+|---|---|
+| `timestamp` | when Jira raised the event, in milliseconds since the epoch |
+| `webhookEvent` | the event, and the field to switch on |
+| `matchedWebhookIds` | which registrations this delivery answered — only on webhooks registered through the REST API |
+
+## What is documented, and what is not
+
+Worth knowing before you trust a field: **Atlassian publishes one complete payload**, the one for issue events. Of
+everything else it says only that a callback carries "information about the entity associated with the event".
+
+So the issue payload here is written from that example and from a capture of a real delivery. It is the only one with
+a required entity:
+
+```typescript
+case 'jira:issue_updated':
+  payload.issue;                   // Issue — always there
+  payload.issue_event_type_name;   // 'issue_updated', 'issue_commented', 'issue_generic'…
+  payload.changelog;               // what changed
+  payload.comment;                 // set when the update was someone commenting
+  break;
+```
+
+`issue_event_type_name` is finer-grained than `webhookEvent` — an edit, a comment and a transition all arrive as
+`jira:issue_updated` and are told apart only there. It is typed as a plain string on purpose: a site administrator can
+add issue events, so the set is not closed.
+
+Every other group names its entity **optionally**, after the entity the event concerns rather than from a
+specification: `sprint` on a sprint event, `board` on a board event, `worklog`, `attachment`, `project`, `version`,
+`filter`. Nothing here could verify those against Atlassian's documentation, so the type makes you check, and the
+declaration says as much where you hover it.
+
+## The headers
+
+Lower-cased, because that is how they arrive — Node lower-cases every incoming header name and so does every framework
+built on it. Every value is a string, including the retry count: an HTTP header has no numbers in it.
+
+| header | |
+|---|---|
+| `x-atlassian-webhook-identifier` | unique for this delivery within the site, and unchanged across retries — record it to recognise a webhook you have already handled |
+| `x-atlassian-webhook-flow` | `Primary` for the event itself, thirty seconds; `Secondary` for the fallout of a bulk or cascading change, fifteen minutes |
+| `x-atlassian-webhook-retry` | how many retries so far; absent on the first attempt |
+| `x-atlassian-webhook-trace` | whatever a Connect app attached to the request that caused the event |
+| `x-hub-signature` | `sha256=…`, present only on a webhook registered with a secret |
+
+Deleting an issue is the clearest illustration of the flow header: `jira:issue_deleted` goes out as `Primary`, and
+every dependent `comment_deleted`, `attachment_deleted` and `issuelink_deleted` follows as `Secondary`, possibly
+minutes later.
+
+## What this does not do
+
+**It does not parse.** The casts above are the interface, deliberately. A webhook body is shaped by the site that sent
+it — custom fields under generated keys in `issue.fields`, whatever an installed app adds, a Data Center release that
+differs from Cloud — and a schema strict enough to be worth having would reject bodies that are perfectly valid
+somewhere else. Elsewhere in this library a response is validated because the API documents it; here there is nothing
+to validate against.
+
+**It does not verify signatures.** `x-hub-signature` is the only thing that proves a request came from Jira rather
+than from whoever found your URL, and checking it is yours to do. This library does not, because a signature check
+that quietly compares the wrong way is worse than none, and there is nothing here to test one against.
+
+## Registering one
+
+Two ways, and they behave differently:
+
+- **The admin page**, `https://your-domain.atlassian.net/plugins/servlet/webhooks`. What most people mean by a Jira
+  webhook. Registered by a person, lives until someone removes it.
+- **The REST API**, `POST /rest/api/3/webhook` — Connect and OAuth 2.0 apps only, and the registration expires after
+  thirty days unless `refreshWebhooks` extends it. These are the deliveries that carry `matchedWebhookIds`, and this
+  library covers the endpoints: `jira.webhooks.registerDynamicWebhooks`, `getDynamicWebhooksForApp`,
+  `refreshWebhooks`, `deleteWebhookById`.
+
+Atlassian's own reference is
+[Webhooks](https://developer.atlassian.com/cloud/jira/platform/webhooks/) on the Jira Cloud platform.