@andypai/agent-kanban 0.3.7 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andypai/agent-kanban",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "description": "Agent-friendly kanban board CLI. Manage tasks via bash commands, parse structured JSON output.",
   "homepage": "https://github.com/abpai/agent-kanban#readme",
   "repository": {

package/src/__tests__/webhook-events.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from 'bun:test'
+
+import { extractWebhookMeta, webhookEventStatus, webhookEventsEnabled } from '../webhook-events'
+
+describe('webhookEventStatus', () => {
+  test('handled -> accepted', () => {
+    expect(webhookEventStatus({ handled: true })).toBe('accepted')
+  })
+  test('unhandled -> skipped', () => {
+    expect(webhookEventStatus({ handled: false })).toBe('skipped')
+    expect(webhookEventStatus({ handled: false, message: 'Unsupported event' })).toBe('skipped')
+  })
+  test('unauthorized -> error (regardless of handled)', () => {
+    expect(webhookEventStatus({ handled: false, unauthorized: true })).toBe('error')
+    expect(webhookEventStatus({ handled: true, unauthorized: true })).toBe('error')
+  })
+})
+
+describe('webhookEventsEnabled', () => {
+  test('enabled by default / when unset', () => {
+    expect(webhookEventsEnabled({})).toBe(true)
+    expect(webhookEventsEnabled({ KANBAN_WEBHOOK_EVENTS: 'on' })).toBe(true)
+    expect(webhookEventsEnabled({ KANBAN_WEBHOOK_EVENTS: '1' })).toBe(true)
+  })
+  test('disabled by explicit off values', () => {
+    for (const v of ['0', 'false', 'off', 'no', 'OFF', ' false ']) {
+      expect(webhookEventsEnabled({ KANBAN_WEBHOOK_EVENTS: v })).toBe(false)
+    }
+  })
+})
+
+describe('extractWebhookMeta', () => {
+  test('jira: webhookEvent + issue.key', () => {
+    const body = JSON.stringify({ webhookEvent: 'jira:issue_updated', issue: { key: 'SMTS-7' } })
+    expect(extractWebhookMeta('jira', body)).toEqual({
+      eventType: 'jira:issue_updated',
+      externalRef: 'SMTS-7',
+    })
+  })
+  test('jira: tolerates a missing issue', () => {
+    expect(
+      extractWebhookMeta('jira', JSON.stringify({ webhookEvent: 'jira:issue_deleted' })),
+    ).toEqual({
+      eventType: 'jira:issue_deleted',
+    })
+  })
+  test('linear: type.action + data.identifier', () => {
+    const body = JSON.stringify({
+      type: 'Issue',
+      action: 'update',
+      data: { id: 'uuid-1', identifier: 'SMTS-9' },
+    })
+    expect(extractWebhookMeta('linear', body)).toEqual({
+      eventType: 'Issue.update',
+      externalRef: 'SMTS-9',
+    })
+  })
+  test('linear: falls back to data.id when identifier is absent', () => {
+    const body = JSON.stringify({ type: 'Issue', action: 'remove', data: { id: 'uuid-2' } })
+    expect(extractWebhookMeta('linear', body)).toEqual({
+      eventType: 'Issue.remove',
+      externalRef: 'uuid-2',
+    })
+  })
+  test('invalid / non-object body -> {}', () => {
+    expect(extractWebhookMeta('jira', 'not json')).toEqual({})
+    expect(extractWebhookMeta('jira', '"a string"')).toEqual({})
+    expect(extractWebhookMeta('linear', 'null')).toEqual({})
+  })
+  test('unknown provider -> {}', () => {
+    expect(extractWebhookMeta('local', JSON.stringify({ webhookEvent: 'x' }))).toEqual({})
+  })
+})

package/src/providers/postgres-jira.ts

@@ -34,6 +34,12 @@ import {
   type WebhookRequest,
   type WebhookResult,
 } from '../webhooks'
+import {
+  ensureWebhookEventsSchema,
+  extractWebhookMeta,
+  recordWebhookEvent,
+  webhookEventStatus,
+} from '../webhook-events'
 
 const FULL_RECONCILE_INTERVAL_MS = 5 * 60_000
 
@@ -230,6 +236,7 @@ export class PostgresJiraProvider implements KanbanProvider {
     await this.sql`
       CREATE INDEX IF NOT EXISTS jira_activity_created_at_idx ON jira_activity(created_at DESC)
     `
+    await ensureWebhookEventsSchema(this.sql)
   }
 
   private async setMeta(key: string, value: string): Promise<void> {
@@ -1127,6 +1134,28 @@ export class PostgresJiraProvider implements KanbanProvider {
   }
 
   async handleWebhook(payload: WebhookRequest): Promise<WebhookResult> {
+    const meta = extractWebhookMeta('jira', payload.rawBody)
+    let result: WebhookResult
+    try {
+      result = await this.handleWebhookInner(payload)
+    } catch (err) {
+      void recordWebhookEvent(this.sql, {
+        provider: 'jira',
+        ...meta,
+        status: 'error',
+        detail: { error: err instanceof Error ? err.message : String(err) },
+      })
+      throw err
+    }
+    void recordWebhookEvent(this.sql, {
+      provider: 'jira',
+      ...meta,
+      status: webhookEventStatus(result),
+    })
+    return result
+  }
+
+  private async handleWebhookInner(payload: WebhookRequest): Promise<WebhookResult> {
     const secret = process.env['JIRA_WEBHOOK_SECRET']
     if (secret) {
       const sig = headerLower(payload.headers, 'x-hub-signature')

package/src/providers/postgres-linear.ts

@@ -14,6 +14,12 @@ import type {
 } from '../types'
 import { DEFAULT_POLLING_SYNC_INTERVAL_MS } from '../sync-config'
 import { headerLower, verifyHmacSha256, type WebhookRequest, type WebhookResult } from '../webhooks'
+import {
+  ensureWebhookEventsSchema,
+  extractWebhookMeta,
+  recordWebhookEvent,
+  webhookEventStatus,
+} from '../webhook-events'
 import { LINEAR_CAPABILITIES } from './capabilities'
 import { unsupportedOperation } from './errors'
 import { LinearClient, type LinearComment } from './linear-client'
@@ -255,6 +261,7 @@ export class PostgresLinearProvider implements KanbanProvider {
     await this.sql`
       CREATE INDEX IF NOT EXISTS linear_activity_created_at_idx ON linear_activity(created_at DESC)
     `
+    await ensureWebhookEventsSchema(this.sql)
   }
 
   private async setMeta(key: string, value: string): Promise<void> {
@@ -979,6 +986,28 @@ export class PostgresLinearProvider implements KanbanProvider {
   }
 
   async handleWebhook(payload: WebhookRequest): Promise<WebhookResult> {
+    const meta = extractWebhookMeta('linear', payload.rawBody)
+    let result: WebhookResult
+    try {
+      result = await this.handleWebhookInner(payload)
+    } catch (err) {
+      void recordWebhookEvent(this.sql, {
+        provider: 'linear',
+        ...meta,
+        status: 'error',
+        detail: { error: err instanceof Error ? err.message : String(err) },
+      })
+      throw err
+    }
+    void recordWebhookEvent(this.sql, {
+      provider: 'linear',
+      ...meta,
+      status: webhookEventStatus(result),
+    })
+    return result
+  }
+
+  private async handleWebhookInner(payload: WebhookRequest): Promise<WebhookResult> {
     const secret = process.env['LINEAR_WEBHOOK_SECRET']
     if (secret) {
       const sig = headerLower(payload.headers, 'linear-signature')

package/src/webhook-events.ts

@@ -0,0 +1,135 @@
+/**
+ * `webhook_events` — a small, generically-named receipts table that the Postgres
+ * providers append to on every received webhook. It is *not* used by agent-kanban
+ * itself; it exists so an external consumer (Garage Band's Studio "Webhooks"
+ * panel) can show "did the sidecar receive/process a tracker webhook, and when".
+ *
+ * Ownership: agent-kanban owns and creates this table; consumers read it
+ * read-only. Columns a consumer can rely on:
+ *   id           bigserial   — newest-first tie-breaker (required by readers'
+ *                              `ORDER BY received_at DESC, id DESC`)
+ *   received_at  timestamptz — when the webhook hit the sidecar
+ *   provider     text        — 'jira' | 'linear'
+ *   event_type   text|null   — Jira's `webhookEvent`, or Linear's `type.action`
+ *   external_ref text|null   — tracker key when derivable from the body
+ *   status       text        — 'accepted' (handled) | 'skipped' (unhandled) |
+ *                              'error' (unauthorized or threw)
+ *   detail       jsonb       — emit-time-controlled; never raw secrets/payloads
+ *                              (currently only `{ error }` on error rows)
+ *
+ * Best-effort by design: a receipt write must never fail or slow a webhook, and
+ * the whole feature no-ops when `KANBAN_WEBHOOK_EVENTS` is off, so it is safe to
+ * ship before any consumer exists.
+ */
+
+import type { JSONValue, Sql } from 'postgres'
+
+import type { TrackerProvider } from './tracker-config'
+import type { WebhookResult } from './webhooks'
+
+export type WebhookEventStatus = 'accepted' | 'skipped' | 'error'
+
+export interface WebhookEventRecord {
+  provider: TrackerProvider
+  eventType?: string | undefined
+  externalRef?: string | undefined
+  status: WebhookEventStatus
+  detail?: Record<string, unknown> | undefined
+}
+
+/** `KANBAN_WEBHOOK_EVENTS` toggles the receipts table; enabled unless explicitly off. */
+export function webhookEventsEnabled(
+  env: Record<string, string | undefined> = process.env,
+): boolean {
+  const value = env['KANBAN_WEBHOOK_EVENTS']?.trim().toLowerCase()
+  return value !== '0' && value !== 'false' && value !== 'off' && value !== 'no'
+}
+
+/** Idempotent — call from a Postgres provider's schema bootstrap. */
+export async function ensureWebhookEventsSchema(sql: Sql): Promise<void> {
+  if (!webhookEventsEnabled()) return
+  await sql`
+    CREATE TABLE IF NOT EXISTS webhook_events (
+      id           bigserial   PRIMARY KEY,
+      received_at  timestamptz NOT NULL DEFAULT now(),
+      provider     text        NOT NULL,
+      event_type   text,
+      external_ref text,
+      status       text        NOT NULL,
+      detail       jsonb       NOT NULL DEFAULT '{}'::jsonb
+    )
+  `
+  await sql`
+    CREATE INDEX IF NOT EXISTS webhook_events_received_at_idx
+      ON webhook_events (received_at DESC, id DESC)
+  `
+}
+
+export function webhookEventStatus(result: WebhookResult): WebhookEventStatus {
+  if (result.unauthorized) return 'error'
+  return result.handled ? 'accepted' : 'skipped'
+}
+
+/** Append a receipt. Swallows every error — a logging miss must never fail the webhook. */
+export async function recordWebhookEvent(sql: Sql, record: WebhookEventRecord): Promise<void> {
+  if (!webhookEventsEnabled()) return
+  try {
+    await sql`
+      INSERT INTO webhook_events (provider, event_type, external_ref, status, detail)
+      VALUES (
+        ${record.provider},
+        ${record.eventType ?? null},
+        ${record.externalRef ?? null},
+        ${record.status},
+        ${sql.json((record.detail ?? {}) as JSONValue)}
+      )
+    `
+  } catch (err) {
+    console.warn('[webhook-events] failed to record receipt:', err)
+  }
+}
+
+/** Light, provider-shaped peek at the raw body for a receipt's `event_type` / `external_ref`. */
+export function extractWebhookMeta(
+  providerType: TrackerProvider,
+  rawBody: string,
+): { eventType?: string; externalRef?: string } {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(rawBody)
+  } catch {
+    return {}
+  }
+  if (typeof parsed !== 'object' || parsed === null) return {}
+  const body = parsed as Record<string, unknown>
+
+  if (providerType === 'jira') {
+    const eventType = typeof body['webhookEvent'] === 'string' ? body['webhookEvent'] : undefined
+    const externalRef = nestedString(body['issue'], 'key')
+    return withDefined({ eventType, externalRef })
+  }
+  if (providerType === 'linear') {
+    const type = typeof body['type'] === 'string' ? body['type'] : undefined
+    const action = typeof body['action'] === 'string' ? body['action'] : undefined
+    const eventType = type && action ? `${type}.${action}` : (type ?? action)
+    const externalRef = nestedString(body['data'], 'identifier') ?? nestedString(body['data'], 'id')
+    return withDefined({ eventType, externalRef })
+  }
+  return {}
+}
+
+function nestedString(container: unknown, key: string): string | undefined {
+  if (typeof container !== 'object' || container === null) return undefined
+  const value = (container as Record<string, unknown>)[key]
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+function withDefined(meta: { eventType?: string | undefined; externalRef?: string | undefined }): {
+  eventType?: string
+  externalRef?: string
+} {
+  return {
+    ...(meta.eventType ? { eventType: meta.eventType } : {}),
+    ...(meta.externalRef ? { externalRef: meta.externalRef } : {}),
+  }
+}