@skelm/integrations 0.4.2 → 0.4.3

package/README.md

@@ -49,6 +49,60 @@ export default pipeline({
 })
 ```
 
+## GitHub REST helpers
+
+For PR-review and webhook-management workflows the package also exports
+standalone REST helpers that take a plain `GitHubAuth` and don't require an
+integration instance. They are the recommended path for PR-review pipelines
+that previously shelled out to the `gh` CLI.
+
+```ts
+import {
+  postPullRequestReview,
+  postIssueComment,
+  registerWebhook,
+  deleteWebhook,
+  getAuthenticatedUser,
+  GitHubApiError,
+} from '@skelm/integrations'
+
+const auth = { token: process.env.GITHUB_TOKEN! }
+
+// Post a review against a PR.
+await postPullRequestReview({
+  auth,
+  owner: 'octo',
+  repo: 'demo',
+  number: 42,
+  event: 'REQUEST_CHANGES',      // 'APPROVE' | 'REQUEST_CHANGES' | 'COMMENT'
+  body: 'See inline comments.',
+  comments: [{ path: 'src/x.ts', line: 12, body: 'nit: rename' }],
+})
+
+// Drop a follow-up issue comment.
+await postIssueComment({ auth, owner: 'octo', repo: 'demo', number: 42, body: 'pong' })
+
+// Register a webhook (returns the hook id for later cleanup).
+const hook = await registerWebhook({
+  auth, owner: 'octo', repo: 'demo',
+  url: 'https://gateway.example/hooks/gh',
+  secret: process.env.GITHUB_WEBHOOK_SECRET,
+  events: ['pull_request', 'issue_comment', 'pull_request_review'],
+})
+await deleteWebhook({ auth, owner: 'octo', repo: 'demo', hookId: hook.id })
+```
+
+Failed calls raise `GitHubApiError` with `status`, `method`, `path`, and the
+parsed response body. The helpers warn to stderr when GitHub's
+`X-RateLimit-Remaining` drops below 10 % of the quota so operators see
+throttling coming before it bites.
+
+The `GitHubIntegration` class wires the same helpers through
+`performHealthCheck` (`GET /user`), `setupWebhook` (`POST /hooks`),
+`cleanupWebhook` (`DELETE /hooks/:id`), and `sendNotification` (routes to
+`POST /issues/:n/comments` by default, or to `POST /pulls/:n/reviews` when
+`options.kind === 'pr-review'`).
+
 ## Built-in connectors
 
 | Connector       | Status     | Trigger types                                              |

package/dist/github-pr-trigger.d.ts

@@ -0,0 +1,107 @@
+export type GitHubPrEventKind = 'opened' | 'synchronize' | 'reopened' | 'closed' | 'review_requested' | 'commented' | 'submitted';
+export interface GitHubPrTriggerSpec {
+    /** Trigger id. Used by the coordinator's registration. */
+    readonly id: string;
+    /** Workflow id this trigger fires. */
+    readonly workflowId: string;
+    /** Webhook path the gateway should listen on (e.g. `/hooks/github/prs`). */
+    readonly path: string;
+    /**
+     * Optional HMAC shared secret. When set, the helper verifies GitHub's
+     * `x-hub-signature-256` header against an HMAC of the raw body. Mismatches
+     * raise a permission denial; missing headers raise an error.
+     */
+    readonly secret?: string;
+    /** Subset of GitHub PR-related event kinds to forward. Default: every kind below. */
+    readonly events?: readonly GitHubPrEventKind[];
+    /** Filters applied to the normalized payload before firing the pipeline. */
+    readonly filter?: {
+        readonly dropBotAuthors?: boolean;
+        readonly repos?: readonly string[];
+    };
+    /**
+     * Dedupe TTL in milliseconds. Defaults to 24 h (matches GitHub's
+     * redelivery window). The header is fixed to `X-GitHub-Delivery`.
+     */
+    readonly dedupeTtlMs?: number;
+}
+export interface GitHubPrPayload {
+    /** Normalized event kind. */
+    readonly kind: GitHubPrEventKind;
+    /** PR identity + key fields needed for diff/review pipelines. */
+    readonly pr: {
+        readonly owner: string;
+        readonly repo: string;
+        readonly number: number;
+        readonly headSha: string;
+        readonly baseSha: string;
+        readonly author: string;
+        readonly labels: readonly string[];
+    };
+    /** Author classification. PR-review agents typically skip bot-authored PRs. */
+    readonly authorIsBot: boolean;
+    /** Original GitHub event name (e.g. 'pull_request', 'issue_comment', …). */
+    readonly githubEvent: string;
+    /** Original GitHub action (e.g. 'opened', 'synchronize', …). */
+    readonly action: string;
+    /** Raw webhook payload, in case the pipeline needs fields beyond the normalized ones. */
+    readonly raw: unknown;
+}
+/**
+ * Translate a GitHub webhook delivery into the normalized payload, or null
+ * when the delivery is not PR-related or fails the spec's filter.
+ *
+ * `githubEvent` is the value of the `x-github-event` header
+ * (`pull_request`, `issue_comment`, `pull_request_review`,
+ * `pull_request_review_comment`). The function inspects `body.action` and
+ * the PR fields to map onto `GitHubPrEventKind`.
+ */
+export declare function normalizeGitHubPrEvent(githubEvent: string, body: unknown, spec?: Pick<GitHubPrTriggerSpec, 'events' | 'filter'>): GitHubPrPayload | null;
+/**
+ * Verify GitHub's `x-hub-signature-256` HMAC against the raw body. The
+ * comparison itself is constant-time (`timingSafeEqual`), but the *bytes*
+ * passed as `rawBody` must match what GitHub signed — and a parsed-then-
+ * re-stringified JSON body generally won't, because JSON serialization
+ * isn't round-trip-stable (whitespace, key ordering, unicode escapes).
+ * For exact verification operators should configure a raw-body shim and
+ * pass the original request bytes here.
+ */
+export declare function verifyGitHubSignature(rawBody: string, signature: string, secret: string): boolean;
+/**
+ * Minimal coordinator surface the helper needs. Matches the public methods
+ * of `gateway.managers.triggers` (TriggerCoordinator) so callers can pass
+ * the manager directly without a wrapper type.
+ */
+export interface GitHubPrTriggerCoordinator {
+    register(spec: {
+        kind: 'webhook';
+        id: string;
+        workflowId: string;
+        path: string;
+        method?: string;
+        secret?: string;
+        dedupe?: {
+            header: string;
+            ttlMs?: number;
+        };
+    }, overlap?: 'skip' | 'queue' | 'cancel', options?: {
+        input?: unknown;
+    }): unknown;
+}
+/**
+ * Translate a declarative `GitHubPrTriggerSpec` into a registered webhook
+ * trigger on the coordinator. Returns a `normalize()` function the caller
+ * (typically the gateway's dispatcher) can apply to incoming webhook
+ * payloads to produce the `GitHubPrPayload` the pipeline expects as input.
+ *
+ * The dispatcher is responsible for routing the normalized payload to the
+ * pipeline's run; integrators usually do this by registering a
+ * `pre-dispatch` hook that calls `normalize()` on the raw webhook envelope
+ * captured in `payload.body`.
+ */
+export declare function registerGitHubPrTrigger(coordinator: GitHubPrTriggerCoordinator, spec: GitHubPrTriggerSpec): {
+    normalize(rawWebhookPayload: {
+        body: unknown;
+        headers: Record<string, string>;
+    }): GitHubPrPayload | null;
+};

package/dist/github-pr-trigger.js

@@ -0,0 +1,170 @@
+/**
+ * `github-pr` trigger primitive.
+ *
+ * Wraps the gateway's `webhook` trigger + dedupe + integration event mapping
+ * into a single declarative shape: a pipeline file declares
+ *
+ *   triggers: [{ kind: 'github-pr', path: '/hooks/gh-pr', events: [...], filter: {...} }]
+ *
+ * and `registerGitHubPrTrigger()` translates that into a webhook trigger on
+ * the coordinator with `X-GitHub-Delivery` dedupe enabled and an onFire
+ * wrapper that normalizes the GitHub webhook payload into a stable
+ * `GitHubPrPayload` shape before dispatching the pipeline run.
+ *
+ * Filtering (dropBotAuthors, repos allowlist, event kinds) is applied
+ * pre-dispatch; rejected deliveries respond 200 (so GitHub doesn't retry)
+ * but don't fire the pipeline.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+const ALL_EVENT_KINDS = [
+    'opened',
+    'synchronize',
+    'reopened',
+    'closed',
+    'review_requested',
+    'commented',
+    'submitted',
+];
+/**
+ * Translate a GitHub webhook delivery into the normalized payload, or null
+ * when the delivery is not PR-related or fails the spec's filter.
+ *
+ * `githubEvent` is the value of the `x-github-event` header
+ * (`pull_request`, `issue_comment`, `pull_request_review`,
+ * `pull_request_review_comment`). The function inspects `body.action` and
+ * the PR fields to map onto `GitHubPrEventKind`.
+ */
+export function normalizeGitHubPrEvent(githubEvent, body, spec) {
+    const b = body;
+    if (b === null || typeof b !== 'object')
+        return null;
+    const action = typeof b.action === 'string' ? b.action : '';
+    // Map (event, action) → kind. Reject events that aren't PR-related.
+    const kind = mapKind(githubEvent, action);
+    if (kind === null)
+        return null;
+    // The PR object lives under different paths depending on the event:
+    //  - pull_request:                 b.pull_request
+    //  - pull_request_review:          b.pull_request
+    //  - pull_request_review_comment:  b.pull_request
+    //  - issue_comment (on a PR):      b.issue (with b.issue.pull_request set)
+    const pr = b.pull_request ?? extractPrFromIssue(b);
+    if (pr === undefined)
+        return null;
+    const head = pr.head ?? {};
+    const base = pr.base ?? {};
+    const baseRepo = base.repo ?? {};
+    const owner = baseRepo.owner?.login ?? '';
+    const repo = baseRepo.name ?? '';
+    const number = pr.number;
+    const headSha = head.sha ?? '';
+    const baseSha = base.sha ?? '';
+    const user = pr.user ?? {};
+    const author = user.login ?? '';
+    const authorIsBot = user.type === 'Bot';
+    const labelsRaw = Array.isArray(pr.labels) ? pr.labels : [];
+    const labels = labelsRaw.map((l) => l.name ?? '').filter((s) => s !== '');
+    const payload = {
+        kind,
+        pr: { owner, repo, number, headSha, baseSha, author, labels },
+        authorIsBot,
+        githubEvent,
+        action,
+        raw: body,
+    };
+    if (!passesFilter(payload, spec))
+        return null;
+    return payload;
+}
+function mapKind(githubEvent, action) {
+    if (githubEvent === 'pull_request') {
+        if (action === 'opened')
+            return 'opened';
+        if (action === 'synchronize')
+            return 'synchronize';
+        if (action === 'reopened')
+            return 'reopened';
+        if (action === 'closed')
+            return 'closed';
+        if (action === 'review_requested')
+            return 'review_requested';
+        return null;
+    }
+    if (githubEvent === 'pull_request_review' && action === 'submitted')
+        return 'submitted';
+    if (githubEvent === 'pull_request_review_comment')
+        return 'commented';
+    if (githubEvent === 'issue_comment')
+        return 'commented';
+    return null;
+}
+function extractPrFromIssue(body) {
+    const issue = body.issue;
+    if (issue === undefined)
+        return undefined;
+    if (issue.pull_request === undefined)
+        return undefined;
+    return issue;
+}
+function passesFilter(payload, spec) {
+    const events = spec?.events ?? ALL_EVENT_KINDS;
+    if (!events.includes(payload.kind))
+        return false;
+    const filter = spec?.filter;
+    if (filter?.dropBotAuthors === true && payload.authorIsBot)
+        return false;
+    if (filter?.repos !== undefined && filter.repos.length > 0) {
+        const slug = `${payload.pr.owner}/${payload.pr.repo}`;
+        if (!filter.repos.includes(slug))
+            return false;
+    }
+    return true;
+}
+/**
+ * Verify GitHub's `x-hub-signature-256` HMAC against the raw body. The
+ * comparison itself is constant-time (`timingSafeEqual`), but the *bytes*
+ * passed as `rawBody` must match what GitHub signed — and a parsed-then-
+ * re-stringified JSON body generally won't, because JSON serialization
+ * isn't round-trip-stable (whitespace, key ordering, unicode escapes).
+ * For exact verification operators should configure a raw-body shim and
+ * pass the original request bytes here.
+ */
+export function verifyGitHubSignature(rawBody, signature, secret) {
+    if (!signature.startsWith('sha256='))
+        return false;
+    const provided = signature.slice('sha256='.length);
+    const computed = createHmac('sha256', secret).update(rawBody).digest('hex');
+    if (provided.length !== computed.length)
+        return false;
+    return timingSafeEqual(Buffer.from(provided, 'hex'), Buffer.from(computed, 'hex'));
+}
+/**
+ * Translate a declarative `GitHubPrTriggerSpec` into a registered webhook
+ * trigger on the coordinator. Returns a `normalize()` function the caller
+ * (typically the gateway's dispatcher) can apply to incoming webhook
+ * payloads to produce the `GitHubPrPayload` the pipeline expects as input.
+ *
+ * The dispatcher is responsible for routing the normalized payload to the
+ * pipeline's run; integrators usually do this by registering a
+ * `pre-dispatch` hook that calls `normalize()` on the raw webhook envelope
+ * captured in `payload.body`.
+ */
+export function registerGitHubPrTrigger(coordinator, spec) {
+    coordinator.register({
+        kind: 'webhook',
+        id: spec.id,
+        workflowId: spec.workflowId,
+        path: spec.path,
+        method: 'POST',
+        ...(spec.secret !== undefined && { secret: spec.secret }),
+        dedupe: { header: 'X-GitHub-Delivery', ttlMs: spec.dedupeTtlMs ?? 24 * 60 * 60 * 1000 },
+    });
+    return {
+        normalize(rawWebhookPayload) {
+            const event = rawWebhookPayload.headers['x-github-event'] ?? rawWebhookPayload.headers['X-GitHub-Event'];
+            if (typeof event !== 'string' || event === '')
+                return null;
+            return normalizeGitHubPrEvent(event, rawWebhookPayload.body, spec);
+        },
+    };
+}

package/dist/github.d.ts

@@ -1,15 +1,126 @@
+/**
+ * Error raised by the GitHub REST helpers when an API call fails with a
+ * non-2xx status. `status` is the HTTP status code; `body` is the parsed
+ * JSON body if present, otherwise the raw text.
+ */
+export declare class GitHubApiError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    readonly body: unknown;
+    readonly name = "GitHubApiError";
+    constructor(status: number, method: string, path: string, body: unknown);
+}
+/** Credentials accepted by the standalone REST helpers. */
+export interface GitHubAuth {
+    readonly token: string;
+    readonly apiBase?: string;
+}
+interface GitHubRequest {
+    readonly auth: GitHubAuth;
+    readonly method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+    readonly path: string;
+    readonly body?: unknown;
+    /** Per-request timeout in ms; default 30s. A hung GitHub edge cannot
+     *  hold a gateway request handler indefinitely. */
+    readonly timeoutMs?: number;
+}
+/**
+ * Make a JSON-bodied GitHub REST call. Returns the parsed JSON response;
+ * throws `GitHubApiError` on non-2xx responses. Warns to stderr when the
+ * remaining rate-limit budget drops below 10 % so operators see throttling
+ * coming before it bites.
+ */
+export declare function githubFetch<T = unknown>(req: GitHubRequest): Promise<T>;
+/** Verify a credential by calling `GET /user`. Returns true on 200. */
+export declare function getAuthenticatedUser(auth: GitHubAuth): Promise<{
+    login: string;
+    id: number;
+}>;
+export interface RegisterWebhookParams {
+    readonly auth: GitHubAuth;
+    readonly owner: string;
+    readonly repo: string;
+    readonly url: string;
+    readonly secret?: string;
+    readonly events?: readonly string[];
+    readonly active?: boolean;
+}
+export interface GitHubHook {
+    readonly id: number;
+    readonly url: string;
+}
+/** Register a webhook on `owner/repo`. Returns the created hook's id + url. */
+export declare function registerWebhook(params: RegisterWebhookParams): Promise<GitHubHook>;
+export interface DeleteWebhookParams {
+    readonly auth: GitHubAuth;
+    readonly owner: string;
+    readonly repo: string;
+    readonly hookId: number;
+}
+export declare function deleteWebhook(params: DeleteWebhookParams): Promise<void>;
+export interface PostIssueCommentParams {
+    readonly auth: GitHubAuth;
+    readonly owner: string;
+    readonly repo: string;
+    readonly number: number;
+    readonly body: string;
+}
+export declare function postIssueComment(params: PostIssueCommentParams): Promise<{
+    id: number;
+    htmlUrl: string;
+}>;
+export interface PullRequestReviewComment {
+    readonly path: string;
+    readonly body: string;
+    /** Single-line comment (line in the diff hunk). */
+    readonly line?: number;
+    /** Side of the diff: 'LEFT' for the base, 'RIGHT' for the head (default). */
+    readonly side?: 'LEFT' | 'RIGHT';
+    /** For multi-line comments: starting line in the same side. */
+    readonly start_line?: number;
+    readonly start_side?: 'LEFT' | 'RIGHT';
+}
+export interface PostPullRequestReviewParams {
+    readonly auth: GitHubAuth;
+    readonly owner: string;
+    readonly repo: string;
+    readonly number: number;
+    readonly event: 'APPROVE' | 'REQUEST_CHANGES' | 'COMMENT';
+    readonly body?: string;
+    readonly comments?: readonly PullRequestReviewComment[];
+    /** Commit SHA the review applies to. Defaults to the PR's current head. */
+    readonly commitId?: string;
+}
+/**
+ * Post a pull request review (the call PR-review agents most need).
+ *
+ * `event` maps to GitHub's review action: APPROVE / REQUEST_CHANGES /
+ * COMMENT. Body is the summary; per-line `comments` are inline review
+ * comments anchored to the diff.
+ */
+export declare function postPullRequestReview(params: PostPullRequestReviewParams): Promise<{
+    id: number;
+    htmlUrl: string;
+}>;
 /**
  * GitHub integration for skelm pipelines.
  *
  * Supports:
  * - Issue/PR triggers
- * - Webhook event handling
+ * - Webhook event handling (real REST: POST /repos/:owner/:repo/hooks)
  * - Repository polling
- * - Notifications via issue/PR comments
+ * - Notifications via issue/PR comments and PR reviews
+ *
+ * For PR-review pipelines, prefer the standalone `postPullRequestReview()`,
+ * `postIssueComment()`, and `registerWebhook()` helpers — they accept a
+ * `GitHubAuth` directly and do not require an integration instance.
  */
 export declare const GitHubIntegration: import("@skelm/integration-sdk").IntegrationClass<{
     token: string;
     ownerId: string;
     repoName: string;
+    apiBase?: string | undefined;
 }>;
 export type GitHubIntegrationType = InstanceType<typeof GitHubIntegration>;
+export {};

package/dist/github.js

@@ -1,18 +1,166 @@
 import { defineIntegration } from '@skelm/integration-sdk';
 import { z } from 'zod';
+const DEFAULT_API_BASE = 'https://api.github.com';
+const SKELM_USER_AGENT = 'skelm-integrations/1.0';
 const githubCredentialsSchema = z.object({
     token: z.string().min(1, 'GitHub token is required'),
     ownerId: z.string().min(1, 'GitHub ownerId is required'),
     repoName: z.string().min(1, 'GitHub repoName is required'),
+    apiBase: z.string().url().optional(),
 });
+/**
+ * Error raised by the GitHub REST helpers when an API call fails with a
+ * non-2xx status. `status` is the HTTP status code; `body` is the parsed
+ * JSON body if present, otherwise the raw text.
+ */
+export class GitHubApiError extends Error {
+    status;
+    method;
+    path;
+    body;
+    name = 'GitHubApiError';
+    constructor(status, method, path, body) {
+        super(`GitHub ${method} ${path} failed with ${status}: ${formatBody(body)}`);
+        this.status = status;
+        this.method = method;
+        this.path = path;
+        this.body = body;
+    }
+}
+function formatBody(body) {
+    if (typeof body === 'string')
+        return body;
+    if (body && typeof body === 'object' && 'message' in body) {
+        return String(body.message);
+    }
+    try {
+        return JSON.stringify(body);
+    }
+    catch {
+        return String(body);
+    }
+}
+const DEFAULT_GITHUB_TIMEOUT_MS = 30_000;
+/**
+ * Make a JSON-bodied GitHub REST call. Returns the parsed JSON response;
+ * throws `GitHubApiError` on non-2xx responses. Warns to stderr when the
+ * remaining rate-limit budget drops below 10 % so operators see throttling
+ * coming before it bites.
+ */
+export async function githubFetch(req) {
+    const base = req.auth.apiBase ?? DEFAULT_API_BASE;
+    const url = `${base}${req.path}`;
+    const headers = {
+        Accept: 'application/vnd.github+json',
+        Authorization: `Bearer ${req.auth.token}`,
+        'User-Agent': SKELM_USER_AGENT,
+        'X-GitHub-Api-Version': '2022-11-28',
+    };
+    if (req.body !== undefined)
+        headers['Content-Type'] = 'application/json';
+    const init = {
+        method: req.method,
+        headers,
+        signal: AbortSignal.timeout(req.timeoutMs ?? DEFAULT_GITHUB_TIMEOUT_MS),
+        ...(req.body !== undefined && { body: JSON.stringify(req.body) }),
+    };
+    const res = await fetch(url, init);
+    const remaining = Number(res.headers.get('x-ratelimit-remaining'));
+    const limit = Number(res.headers.get('x-ratelimit-limit'));
+    if (Number.isFinite(remaining) && Number.isFinite(limit) && limit > 0) {
+        if (remaining / limit < 0.1) {
+            process.stderr.write(`[github-integration] rate limit warning: ${remaining}/${limit} remaining for ${req.method} ${req.path}\n`);
+        }
+    }
+    const text = await res.text();
+    const parsed = text.length > 0 ? safeJsonParse(text) : undefined;
+    if (!res.ok) {
+        throw new GitHubApiError(res.status, req.method, req.path, parsed ?? text);
+    }
+    return parsed;
+}
+function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** Verify a credential by calling `GET /user`. Returns true on 200. */
+export async function getAuthenticatedUser(auth) {
+    return await githubFetch({ auth, method: 'GET', path: '/user' });
+}
+/** Register a webhook on `owner/repo`. Returns the created hook's id + url. */
+export async function registerWebhook(params) {
+    const body = {
+        name: 'web',
+        active: params.active ?? true,
+        events: params.events ?? ['*'],
+        config: {
+            url: params.url,
+            content_type: 'json',
+            ...(params.secret !== undefined && { secret: params.secret }),
+        },
+    };
+    const hook = await githubFetch({
+        auth: params.auth,
+        method: 'POST',
+        path: `/repos/${params.owner}/${params.repo}/hooks`,
+        body,
+    });
+    return { id: hook.id, url: hook.url };
+}
+export async function deleteWebhook(params) {
+    await githubFetch({
+        auth: params.auth,
+        method: 'DELETE',
+        path: `/repos/${params.owner}/${params.repo}/hooks/${params.hookId}`,
+    });
+}
+export async function postIssueComment(params) {
+    const res = await githubFetch({
+        auth: params.auth,
+        method: 'POST',
+        path: `/repos/${params.owner}/${params.repo}/issues/${params.number}/comments`,
+        body: { body: params.body },
+    });
+    return { id: res.id, htmlUrl: res.html_url };
+}
+/**
+ * Post a pull request review (the call PR-review agents most need).
+ *
+ * `event` maps to GitHub's review action: APPROVE / REQUEST_CHANGES /
+ * COMMENT. Body is the summary; per-line `comments` are inline review
+ * comments anchored to the diff.
+ */
+export async function postPullRequestReview(params) {
+    const body = {
+        event: params.event,
+        ...(params.body !== undefined && { body: params.body }),
+        ...(params.commitId !== undefined && { commit_id: params.commitId }),
+        ...(params.comments !== undefined && { comments: params.comments }),
+    };
+    const res = await githubFetch({
+        auth: params.auth,
+        method: 'POST',
+        path: `/repos/${params.owner}/${params.repo}/pulls/${params.number}/reviews`,
+        body,
+    });
+    return { id: res.id, htmlUrl: res.html_url };
+}
 /**
  * GitHub integration for skelm pipelines.
  *
  * Supports:
  * - Issue/PR triggers
- * - Webhook event handling
+ * - Webhook event handling (real REST: POST /repos/:owner/:repo/hooks)
  * - Repository polling
- * - Notifications via issue/PR comments
+ * - Notifications via issue/PR comments and PR reviews
+ *
+ * For PR-review pipelines, prefer the standalone `postPullRequestReview()`,
+ * `postIssueComment()`, and `registerWebhook()` helpers — they accept a
+ * `GitHubAuth` directly and do not require an integration instance.
  */
 export const GitHubIntegration = defineIntegration({
     id: 'github',
@@ -24,25 +172,51 @@ export const GitHubIntegration = defineIntegration({
         canSendNotifications: true,
     },
     credentialsSchema: githubCredentialsSchema,
-    async validateCredentials(creds) {
-        // Warn on unexpected token formats but don't hard-fail — fine-grained
-        // tokens don't share the ghp_/gho_ prefixes.
-        const { token } = creds;
-        if (!token.startsWith('ghp_') && !token.startsWith('gho_') && !token.startsWith('github_')) {
-            console.warn('GitHub token does not match expected patterns (ghp_/gho_/github_)');
-        }
+    async validateCredentials(_creds) {
+        // Token-prefix sniffing produced false positives (fine-grained tokens,
+        // GitHub Apps, enterprise issuers all use shapes that do not match
+        // ghp_/gho_/github_). Validation now defers to performHealthCheck,
+        // which makes a real API call.
     },
     async performHealthCheck(creds) {
-        // In production: call GET /user or GET /repos/:owner/:repo
-        return typeof creds.token === 'string' && creds.token.length > 0;
+        try {
+            const auth = {
+                token: creds.token,
+                ...(creds.apiBase !== undefined && { apiBase: creds.apiBase }),
+            };
+            await getAuthenticatedUser(auth);
+            return true;
+        }
+        catch (err) {
+            if (err instanceof GitHubApiError)
+                return false;
+            throw err;
+        }
     },
-    async setupWebhook(_creds, config, webhook) {
-        // In production: POST /repos/:owner/:repo/hooks
-        console.log(`GitHub webhook would be registered at ${webhook.path} for ${config.name}`);
+    async setupWebhook(creds, config, webhook) {
+        const auth = {
+            token: creds.token,
+            ...(creds.apiBase !== undefined && { apiBase: creds.apiBase }),
+        };
+        const hook = await registerWebhook({
+            auth,
+            owner: creds.ownerId,
+            repo: creds.repoName,
+            url: webhook.path,
+            ...(webhook.secret !== undefined && { secret: webhook.secret }),
+            events: webhook.events ?? ['*'],
+        });
+        webhook.hookId = hook.id;
     },
-    async cleanupWebhook() {
-        // In production: DELETE /repos/:owner/:repo/hooks/:hook_id
-        console.log('GitHub webhook would be unregistered');
+    async cleanupWebhook(creds, _config, webhook) {
+        const hookId = webhook.hookId;
+        if (hookId === undefined)
+            return;
+        const auth = {
+            token: creds.token,
+            ...(creds.apiBase !== undefined && { apiBase: creds.apiBase }),
+        };
+        await deleteWebhook({ auth, owner: creds.ownerId, repo: creds.repoName, hookId });
     },
     async eventToRunInput(event, creds) {
         const { event: eventType, payload } = event;
@@ -70,8 +244,45 @@ export const GitHubIntegration = defineIntegration({
         }
         return null;
     },
-    async sendNotification(message, options) {
-        // In production: POST /repos/:owner/:repo/issues/:issue_number/comments
-        console.log(`GitHub notification: ${message}`, options);
+    /**
+     * Route a notification to the right REST call based on `options.kind`:
+     *   - kind: 'issue-comment' (default) — POST /issues/:n/comments
+     *   - kind: 'pr-review' — POST /pulls/:n/reviews (use `event`, optional `comments[]`)
+     *
+     * Both kinds require `options.number`. `pr-review` also accepts
+     * `event` ('APPROVE' | 'REQUEST_CHANGES' | 'COMMENT', default COMMENT) and
+     * an optional `comments` array of inline review comments.
+     */
+    async sendNotification(message, options, creds) {
+        const opts = (options ?? {});
+        const number = typeof opts.number === 'number' ? opts.number : undefined;
+        if (number === undefined) {
+            throw new Error('GitHub sendNotification requires options.number (issue or PR number)');
+        }
+        const auth = {
+            token: creds.token,
+            ...(creds.apiBase !== undefined && { apiBase: creds.apiBase }),
+        };
+        const owner = typeof opts.owner === 'string' ? opts.owner : creds.ownerId;
+        const repo = typeof opts.repo === 'string' ? opts.repo : creds.repoName;
+        const kind = typeof opts.kind === 'string' ? opts.kind : 'issue-comment';
+        if (kind === 'pr-review') {
+            const eventRaw = typeof opts.event === 'string' ? opts.event : 'COMMENT';
+            const event = eventRaw === 'APPROVE' || eventRaw === 'REQUEST_CHANGES' ? eventRaw : 'COMMENT';
+            const comments = Array.isArray(opts.comments)
+                ? opts.comments
+                : undefined;
+            await postPullRequestReview({
+                auth,
+                owner,
+                repo,
+                number,
+                event,
+                body: message,
+                ...(comments !== undefined && { comments }),
+            });
+            return;
+        }
+        await postIssueComment({ auth, owner, repo, number, body: message });
     },
 });

package/dist/index.d.ts

@@ -8,7 +8,9 @@
 export type { RunInput, IntegrationConfig, WebhookConfig, RateLimitConfig, IntegrationCapabilities, Integration, GitHubConfig, GitHubWebhookEvent, GitHubIssueTrigger, SlackConfig, SlackWebhookEvent, JiraConfig, JiraIssueTrigger, IMAPConfig, EmailTrigger, TelegramConfig, TelegramWebhookEvent, TelegramMessageTrigger, } from '@skelm/integration-sdk';
 export { IntegrationBase, defineIntegration, createIntegrationPlugin, } from '@skelm/integration-sdk';
 export type { DefineIntegrationOptions, IntegrationClass } from '@skelm/integration-sdk';
-export { GitHubIntegration } from './github.js';
+export { GitHubIntegration, GitHubApiError, githubFetch, getAuthenticatedUser, registerWebhook, deleteWebhook, postIssueComment, postPullRequestReview, type GitHubAuth, type GitHubHook, type RegisterWebhookParams, type DeleteWebhookParams, type PostIssueCommentParams, type PostPullRequestReviewParams, type PullRequestReviewComment, } from './github.js';
+export { registerGitHubPrTrigger, normalizeGitHubPrEvent, verifyGitHubSignature, type GitHubPrEventKind, type GitHubPrPayload, type GitHubPrTriggerSpec, type GitHubPrTriggerCoordinator, } from './github-pr-trigger.js';
+export { MsGraphIntegration, getMsGraphValidationToken, verifyMsGraphClientState, type MsGraphIntegrationType, } from './ms-graph.js';
 export { SlackIntegration, verifySlackSignature } from './slack.js';
 export { TelegramIntegration, telegramUpdateToInput, type CreateTelegramTriggerSourceOptions, type TelegramGetUpdatesOptions, type TelegramMessageInput, type TelegramSendMessageOptions, type TelegramTriggerSource, } from './telegram.js';
 export { IntegrationRegistry } from './registry.js';

package/dist/index.js

@@ -7,7 +7,9 @@
  */
 export { IntegrationBase, defineIntegration, createIntegrationPlugin, } from '@skelm/integration-sdk';
 // Built-in integration implementations
-export { GitHubIntegration } from './github.js';
+export { GitHubIntegration, GitHubApiError, githubFetch, getAuthenticatedUser, registerWebhook, deleteWebhook, postIssueComment, postPullRequestReview, } from './github.js';
+export { registerGitHubPrTrigger, normalizeGitHubPrEvent, verifyGitHubSignature, } from './github-pr-trigger.js';
+export { MsGraphIntegration, getMsGraphValidationToken, verifyMsGraphClientState, } from './ms-graph.js';
 export { SlackIntegration, verifySlackSignature } from './slack.js';
 export { TelegramIntegration, telegramUpdateToInput, } from './telegram.js';
 // Integration registry

package/dist/ms-graph.d.ts

@@ -0,0 +1,19 @@
+export declare const MsGraphIntegration: import("@skelm/integration-sdk").IntegrationClass<{
+    tenantId: string;
+    clientId: string;
+    clientState: string;
+}>;
+/**
+ * Pull the Microsoft Graph subscription validation token from a request URL
+ * if present. Graph sends a GET (or POST) to the webhook URL with a
+ * `validationToken` query parameter and expects the raw token echoed back
+ * within 10 seconds with `Content-Type: text/plain`.
+ */
+export declare function getMsGraphValidationToken(url: string): string | null;
+/**
+ * Verify that a Graph change notification's embedded `clientState` matches
+ * the expected secret. Notifications without a `clientState` are rejected;
+ * Graph always includes one when the subscription was created with it set.
+ */
+export declare function verifyMsGraphClientState(notification: unknown, expected: string): boolean;
+export type MsGraphIntegrationType = InstanceType<typeof MsGraphIntegration>;

package/dist/ms-graph.js

@@ -0,0 +1,84 @@
+import { defineIntegration } from '@skelm/integration-sdk';
+import { z } from 'zod';
+/**
+ * Microsoft Graph integration for skelm pipelines.
+ *
+ * Built around the Graph change-notification webhook flow:
+ *   1. Graph posts a one-shot validation request with `?validationToken=…`;
+ *      the gateway echoes the token verbatim within 10 seconds. See
+ *      `getMsGraphValidationToken()`.
+ *   2. After the subscription is live, Graph POSTs change notifications
+ *      whose body is `{ value: [{ subscriptionId, clientState, resource,
+ *      changeType, resourceData, ... }] }`. Verify the embedded
+ *      `clientState` matches the secret stored at subscription time using
+ *      `verifyMsGraphClientState()`.
+ *
+ * The integration declares `canReceiveWebhooks` but does not register the
+ * subscription with Graph itself — that's deployment-specific and best done
+ * by the pipeline owning the lifecycle.
+ */
+const msGraphCredentialsSchema = z.object({
+    /** Azure AD tenant id (used by the pipeline for outbound Graph calls). */
+    tenantId: z.string().min(1, 'Microsoft Graph tenantId is required'),
+    /** Azure AD app/client id. */
+    clientId: z.string().min(1, 'Microsoft Graph clientId is required'),
+    /**
+     * Shared `clientState` value the subscription was created with. Echoed
+     * back by Graph on every notification; rejecting mismatches blocks
+     * spoofed callers from your webhook URL.
+     */
+    clientState: z.string().min(1, 'Microsoft Graph clientState is required'),
+});
+export const MsGraphIntegration = defineIntegration({
+    id: 'ms-graph',
+    name: 'Microsoft Graph',
+    capabilities: {
+        canTrigger: true,
+        canReceiveWebhooks: true,
+        canPoll: false,
+        canSendNotifications: false,
+    },
+    credentialsSchema: msGraphCredentialsSchema,
+    async performHealthCheck(creds) {
+        return (typeof creds.tenantId === 'string' &&
+            creds.tenantId.length > 0 &&
+            typeof creds.clientId === 'string' &&
+            creds.clientId.length > 0);
+    },
+    async eventToRunInput(event, creds) {
+        const body = event;
+        if (!Array.isArray(body.value) || body.value.length === 0)
+            return null;
+        const valid = body.value.filter((n) => verifyMsGraphClientState(n, creds.clientState));
+        if (valid.length === 0)
+            return null;
+        return { notifications: valid };
+    },
+});
+/**
+ * Pull the Microsoft Graph subscription validation token from a request URL
+ * if present. Graph sends a GET (or POST) to the webhook URL with a
+ * `validationToken` query parameter and expects the raw token echoed back
+ * within 10 seconds with `Content-Type: text/plain`.
+ */
+export function getMsGraphValidationToken(url) {
+    try {
+        const parsed = new URL(url, 'http://127.0.0.1');
+        const token = parsed.searchParams.get('validationToken');
+        return token === null || token === '' ? null : token;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Verify that a Graph change notification's embedded `clientState` matches
+ * the expected secret. Notifications without a `clientState` are rejected;
+ * Graph always includes one when the subscription was created with it set.
+ */
+export function verifyMsGraphClientState(notification, expected) {
+    if (notification === null || typeof notification !== 'object')
+        return false;
+    const cs = notification.clientState;
+    return typeof cs === 'string' && cs === expected;
+}

package/dist/slack.d.ts

@@ -13,8 +13,18 @@ export declare const SlackIntegration: import("@skelm/integration-sdk").Integrat
     channelId?: string | undefined;
 }>;
 /**
- * Verify a Slack webhook signature.
- * Call this in your webhook handler before processing the event.
+ * Verify a Slack webhook signature. Computes the expected `v0=` HMAC-SHA256
+ * over `v0:<timestamp>:<rawBody>` using `signingSecret` and compares it to
+ * `signature` in constant time. The caller is responsible for rejecting
+ * stale timestamps (Slack's recommended replay window is 5 minutes).
+ *
+ * **BREAKING (vs. the pre-0.5 stub):** argument order changed to
+ * `(rawBody, signature, timestamp, secret)` — commonly-tampered values
+ * lead, matching how the gateway calls this from `control-routes.ts`. The
+ * pre-0.5 stub took `(signingSecret, timestamp, body, signature)` and
+ * always returned `true` regardless of inputs; callers using the old
+ * order will now silently get `false`. All four params are `string`, so
+ * TypeScript cannot catch the migration — audit your call sites.
  */
-export declare function verifySlackSignature(signingSecret: string, timestamp: string, body: string, signature: string): boolean;
+export declare function verifySlackSignature(rawBody: string, signature: string, timestamp: string, secret: string): boolean;
 export type SlackIntegrationType = InstanceType<typeof SlackIntegration>;

package/dist/slack.js

@@ -1,3 +1,4 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
 import { defineIntegration } from '@skelm/integration-sdk';
 import { z } from 'zod';
 const slackCredentialsSchema = z.object({
@@ -90,13 +91,26 @@ export const SlackIntegration = defineIntegration({
     },
 });
 /**
- * Verify a Slack webhook signature.
- * Call this in your webhook handler before processing the event.
+ * Verify a Slack webhook signature. Computes the expected `v0=` HMAC-SHA256
+ * over `v0:<timestamp>:<rawBody>` using `signingSecret` and compares it to
+ * `signature` in constant time. The caller is responsible for rejecting
+ * stale timestamps (Slack's recommended replay window is 5 minutes).
+ *
+ * **BREAKING (vs. the pre-0.5 stub):** argument order changed to
+ * `(rawBody, signature, timestamp, secret)` — commonly-tampered values
+ * lead, matching how the gateway calls this from `control-routes.ts`. The
+ * pre-0.5 stub took `(signingSecret, timestamp, body, signature)` and
+ * always returned `true` regardless of inputs; callers using the old
+ * order will now silently get `false`. All four params are `string`, so
+ * TypeScript cannot catch the migration — audit your call sites.
  */
-export function verifySlackSignature(signingSecret, timestamp, body, signature) {
-    // In production: use crypto.createHmac('sha256', signingSecret)
-    console.log(`Signature verification: timestamp=${timestamp}, signature=${signature}`);
-    void signingSecret;
-    void body;
-    return true;
+export function verifySlackSignature(rawBody, signature, timestamp, secret) {
+    const expected = `v0=${createHmac('sha256', secret)
+        .update(`v0:${timestamp}:${rawBody}`)
+        .digest('hex')}`;
+    const left = Buffer.from(signature, 'utf8');
+    const right = Buffer.from(expected, 'utf8');
+    if (left.length !== right.length)
+        return false;
+    return timingSafeEqual(left, right);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skelm/integrations",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Third-party integrations for skelm pipelines",
   "license": "MIT",
   "author": "Scott Glover <scottgl@gmail.com>",
@@ -46,8 +46,8 @@
     "clean": "rm -rf dist tsconfig.tsbuildinfo"
   },
   "dependencies": {
-    "@skelm/core": "^0.4.2",
-    "@skelm/integration-sdk": "^0.4.2",
+    "@skelm/core": "^0.4.3",
+    "@skelm/integration-sdk": "^0.4.3",
     "zod": "^4.4.2"
   },
   "devDependencies": {