refactor: Implement WriteResult pattern for WriterService (#4)

* feat: Add webhook sender for time tracking entries (#3)

* feat: Add webhook sender for time tracking entries

- Introduce WriterService interface for pluggable entry writers
- Add WebhookSender that POSTs entries to configurable endpoint
- Support Bearer token authentication via TT_WEBHOOK_BEARER_TOKEN
- Extend CsvEntryData with id and userEmail for consistent tracking
- Refactor EventHook to iterate over multiple writers (CSV first, then webhook)

Configuration:
- TT_WEBHOOK_URL: Webhook endpoint (required to enable)
- TT_WEBHOOK_BEARER_TOKEN: Optional authentication token

* docs: add webhook documentation and bump version to 1.3.0

- Add CHANGELOG entry for v1.3.0 with webhook feature details
- Document webhook configuration in README (TT_WEBHOOK_URL, TT_WEBHOOK_BEARER_TOKEN)
- Add webhook payload example and WriterService extension guide
- Update environment variables table with webhook variables
- Bump version from 1.2.0 to 1.3.0

* fix(docs): correct webhook payload example to match actual implementation

- Use snake_case field names (start_date, issue_key, etc.)
- Add all 23 fields including token breakdown
- Fix model format to include provider prefix

* refactor: Implement WriteResult pattern for WriterService

BREAKING CHANGE: WriterService.write() now returns Promise<WriteResult>
instead of Promise<void>

Changes:
- Add WriteResult interface { writer, success, error? }
- CsvWriter: Returns WriteResult with try/catch error handling
- WebhookSender: Remove toast handler, return WriteResult
- Plugin: Remove setToastHandler() call (no longer needed)
- EventHook: Collect WriteResults, show combined status toast
- track-time tool: Refactor to use WriterService architecture
  - Uses CsvWriter and WebhookSender directly
  - Manual entries have tokenUsage: { input: 0, ... } and cost: 0
  - Response includes writers: WriteResult[] array

Benefits:
- Consistent error handling across all writers
- Single combined toast shows all writer statuses
- Tool responses include detailed writer results
- Better separation of concerns (no toast logic in writers)

* docs: Update CHANGELOG and README for WriteResult pattern

- CHANGELOG: Document WriteResult interface and breaking change
- README: Update WriterService interface documentation with WriteResult

Author: wagnert

CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0] - 2026-03-05
+
+### Added
+
+- **Webhook support** for time tracking entries via `WebhookSender` service
+- `WriterService` interface for pluggable output writers (extensible architecture)
+- `WriteResult` interface: `{ writer: string, success: boolean, error?: string }`
+- New environment variables for webhook configuration:
+  - `TT_WEBHOOK_URL` - Webhook endpoint URL (optional, webhook disabled if not set)
+  - `TT_WEBHOOK_BEARER_TOKEN` - Bearer token for webhook authentication (optional)
+- Tool response now includes `writers: WriteResult[]` array for detailed status
+
+### Changed
+
+- **BREAKING:** `WriterService.write()` now returns `Promise<WriteResult>` instead of `Promise<void>`
+- `EventHook` now accepts an array of `WriterService` implementations
+- `EventHook` collects `WriteResult[]` and shows combined status toast
+- UUID is generated once in `EventHook` and passed to all writers (consistent ID across CSV and webhook)
+- `CsvWriter` refactored to implement `WriterService` interface, returns `WriteResult`
+- `WebhookSender` returns `WriteResult` (toast handler removed, consolidated in `EventHook`)
+- `CsvEntryData` extended with `id` and `userEmail` fields
+- `track-time` tool refactored to use `WriterService` architecture directly
+
+### Technical
+
+- Both CSV and webhook are triggered on each `session.idle` event
+- CSV is written first (as backup), then webhook is called
+- Consistent error handling across all writers
+- Single combined toast shows all writer statuses (e.g., "csv: ✓, webhook: ✗")
+- Webhook payload matches CSV entry structure (JSON format)
+
 ## [1.2.0] - 2026-03-01
 
 ### Added

README.md

@@ -295,6 +295,83 @@ Without whitelist (default):
 id,start_date,end_date,user,ticket_name,issue_key,account_key,start_time,end_time,duration_seconds,tokens_used,tokens_remaining,story_points,description,notes
 ```
 
+## Webhook Integration
+
+The plugin can send time tracking entries to a webhook endpoint in addition to writing them to CSV. This enables real-time integration with external systems.
+
+### Configuration
+
+Set the following environment variables in `.opencode/.env`:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `TT_WEBHOOK_URL` | No | Webhook endpoint URL. If not set, webhook is disabled. |
+| `TT_WEBHOOK_BEARER_TOKEN` | No | Bearer token for webhook authentication. If set, adds `Authorization: Bearer <token>` header. |
+
+Example `.opencode/.env`:
+
+```env
+TT_WEBHOOK_URL=https://your-api.example.com/time-tracking
+TT_WEBHOOK_BEARER_TOKEN=your-secret-token
+```
+
+### Behavior
+
+- **Dual output:** Both CSV and webhook are triggered on each session idle event
+- **Order:** CSV is written first (as backup), then webhook is called
+- **Failure handling:** Webhook failures show a toast notification but don't block CSV writing
+- **Consistent ID:** The same UUID is used for both CSV entry and webhook payload
+
+### Webhook Payload
+
+The webhook receives a POST request with `Content-Type: application/json`. The payload matches the CSV entry structure (snake_case field names):
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "start_date": "2026-03-05",
+  "end_date": "2026-03-05",
+  "user": "your@email.com",
+  "ticket_name": "",
+  "issue_key": "PROJ-123",
+  "account_key": "TD_DEVELOPMENT",
+  "start_time": "09:00:00",
+  "end_time": "09:15:00",
+  "duration_seconds": 900,
+  "tokens_used": 2800,
+  "tokens_remaining": "",
+  "story_points": "",
+  "description": "Implemented webhook sender service",
+  "notes": "",
+  "model": "anthropic/claude-sonnet-4-20250514",
+  "agent": "@developer",
+  "tokens_input": 1500,
+  "tokens_output": 800,
+  "tokens_reasoning": 0,
+  "tokens_cache_read": 500,
+  "tokens_cache_write": 0,
+  "cost": 0.027
+}
+```
+
+### Extending with Custom Writers
+
+The plugin uses a `WriterService` interface for output. You can implement custom writers by following the interface:
+
+```typescript
+interface WriteResult {
+  writer: string;      // e.g., "csv", "webhook"
+  success: boolean;
+  error?: string;      // Only present if success === false
+}
+
+interface WriterService {
+  write(data: CsvEntryData): Promise<WriteResult>;
+}
+```
+
+Each writer returns a `WriteResult` indicating success or failure. The `EventHook` collects all results and shows a combined toast notification (e.g., "Time tracked: 5 min, 1000 tokens for PROJ-123 (webhook: failed)").
+
 ## Sync Features
 
 The plugin provides several sync commands to export time tracking data to external systems.
@@ -325,6 +402,8 @@ All sync-related secrets should be configured in `.opencode/.env` (loaded by `op
 | Variable | Required | Used by | Description |
 |----------|----------|---------|-------------|
 | `OPENCODE_USER_EMAIL` | Yes | All | User email for CSV entries and file naming |
+| `TT_WEBHOOK_URL` | No | Webhook | Webhook endpoint URL (disabled if not set) |
+| `TT_WEBHOOK_BEARER_TOKEN` | No | Webhook | Bearer token for webhook authentication |
 | `TT_SOURCE_CALENDAR_ID` | No | Booking-Proposal | Source calendar for meeting integration |
 | `TT_BOOKING_CALENDAR_ID` | For Calendar Sync | Calendar Sync | Target calendar for booking events |
 | `TT_DRIVE_FOLDER_ID` | For Drive Sync | Drive Sync | Google Drive folder ID for CSV upload |
@@ -336,6 +415,10 @@ Example `.opencode/.env`:
 ```env
 OPENCODE_USER_EMAIL=t.wagner@techdivision.com
 
+# Webhook Integration (optional)
+TT_WEBHOOK_URL=https://your-api.example.com/time-tracking
+TT_WEBHOOK_BEARER_TOKEN=your-secret-token
+
 # Google Calendar Sync
 TT_SOURCE_CALENDAR_ID=t.wagner@techdivision.com
 TT_BOOKING_CALENDAR_ID=c_abc123@group.calendar.google.com

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techdivision/opencode-plugin-time-tracking",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Automatic time tracking plugin for OpenCode. Tracks session duration and tool usage, writing entries to a CSV file compatible with Jira worklog sync incl. commands, skills and agents.",
   "type": "module",
   "main": "src/Plugin.ts",

src/Plugin.ts

@@ -14,9 +14,12 @@ import { CsvWriter } from "./services/CsvWriter"
 import { SessionManager } from "./services/SessionManager"
 import { TicketExtractor } from "./services/TicketExtractor"
 import { TicketResolver } from "./services/TicketResolver"
+import { WebhookSender } from "./services/WebhookSender"
 import { createEventHook } from "./hooks/EventHook"
 import { createToolExecuteAfterHook } from "./hooks/ToolExecuteAfterHook"
 
+import type { WriterService } from "./types/WriterService"
+
 /**
  * OpenCode Time Tracking Plugin
  *
@@ -61,9 +64,13 @@ export const plugin: Plugin = async ({
 
   const sessionManager = new SessionManager()
   const csvWriter = new CsvWriter(config, directory)
+  const webhookSender = new WebhookSender()
   const ticketExtractor = new TicketExtractor(client, config.valid_projects)
   const ticketResolver = new TicketResolver(config, ticketExtractor)
 
+  // Writers are called in order: CSV first (backup), then webhook
+  const writers: WriterService[] = [csvWriter, webhookSender]
+
   // Ensure CSV file has a valid header at startup
   await csvWriter.ensureHeader()
 
@@ -72,7 +79,7 @@ export const plugin: Plugin = async ({
       sessionManager,
       ticketExtractor
     ),
-    event: createEventHook(sessionManager, csvWriter, client, ticketResolver, config),
+    event: createEventHook(sessionManager, writers, client, ticketResolver, config),
   }
 
   return hooks

src/hooks/EventHook.ts

@@ -2,15 +2,18 @@
  * @fileoverview Event hook for session lifecycle and token tracking.
  */
 
+import { randomUUID } from "crypto"
+
 import type { AssistantMessage, Event, Message } from "@opencode-ai/sdk"
 
-import type { CsvWriter } from "../services/CsvWriter"
 import type { SessionManager } from "../services/SessionManager"
 import type { TicketResolver } from "../services/TicketResolver"
+import type { CsvEntryData } from "../types/CsvEntryData"
 import type { MessagePartUpdatedProperties } from "../types/MessagePartUpdatedProperties"
 import type { MessageWithParts } from "../types/MessageWithParts"
 import type { OpencodeClient } from "../types/OpencodeClient"
 import type { TimeTrackingConfig } from "../types/TimeTrackingConfig"
+import type { WriteResult, WriterService } from "../types/WriterService"
 
 import { AgentMatcher } from "../utils/AgentMatcher"
 import { DescriptionGenerator } from "../utils/DescriptionGenerator"
@@ -65,27 +68,33 @@ async function extractSummaryTitle(
  * Creates the event hook for session lifecycle management.
  *
  * @param sessionManager - The session manager instance
- * @param csvWriter - The CSV writer instance
+ * @param writers - Array of writer services to persist entries (e.g., CsvWriter, WebhookSender)
  * @param client - The OpenCode SDK client
+ * @param ticketResolver - The ticket resolver instance
+ * @param config - The time tracking configuration
  * @returns The event hook function
  *
  * @remarks
  * Handles three types of events:
  *
  * 1. **message.updated** - Tracks model from assistant messages
  * 2. **message.part.updated** - Tracks token usage from step-finish parts
- * 3. **session.idle** - Finalizes and exports the session
+ * 3. **session.idle** - Finalizes and exports the session via all writers
+ *
+ * Writers are called in order. Each writer handles its own errors internally,
+ * so a failure in one writer does not affect others.
  *
  * @example
  * ```typescript
+ * const writers: WriterService[] = [csvWriter, webhookSender]
  * const hooks: Hooks = {
- *   event: createEventHook(sessionManager, csvWriter, client),
+ *   event: createEventHook(sessionManager, writers, client, ticketResolver, config),
  * }
  * ```
  */
 export function createEventHook(
   sessionManager: SessionManager,
-  csvWriter: CsvWriter,
+  writers: WriterService[],
   client: OpencodeClient,
   ticketResolver: TicketResolver,
   config: TimeTrackingConfig
@@ -219,37 +228,48 @@ export function createEventHook(
       // Resolve ticket and account key with fallback hierarchy
       const resolved = await ticketResolver.resolve(sessionID, agentString)
 
-      try {
-        await csvWriter.write({
-          ticket: resolved.ticket,
-          accountKey: resolved.accountKey,
-          startTime: session.startTime,
-          endTime,
-          durationSeconds,
-          description,
-          notes: `Auto-tracked: ${toolSummary}`,
-          tokenUsage: session.tokenUsage,
-          cost: session.cost,
-          model: modelString,
-          agent: resolved.primaryAgent ?? agentString,
-        })
+      // Build entry data once, shared across all writers
+      const entryData: CsvEntryData = {
+        id: randomUUID(),
+        userEmail: config.user_email,
+        ticket: resolved.ticket,
+        accountKey: resolved.accountKey,
+        startTime: session.startTime,
+        endTime,
+        durationSeconds,
+        description,
+        notes: `Auto-tracked: ${toolSummary}`,
+        tokenUsage: session.tokenUsage,
+        cost: session.cost,
+        model: modelString,
+        agent: resolved.primaryAgent ?? agentString,
+      }
 
-        const minutes = Math.round(durationSeconds / 60)
+      // Call all writers in order (CSV first, then webhook, etc.)
+      // Collect results for combined status reporting
+      const results: WriteResult[] = []
+      for (const writer of writers) {
+        const result = await writer.write(entryData)
+        results.push(result)
+      }
 
-        await client.tui.showToast({
-          body: {
-            message: `Time tracked: ${minutes} min, ${totalTokens} tokens${resolved.ticket ? ` for ${resolved.ticket}` : ""}`,
-            variant: "success",
-          },
-        })
-      } catch {
-        await client.tui.showToast({
-          body: {
-            message: "Time Tracking: Failed to save entry",
-            variant: "error",
-          },
-        })
+      // Build combined toast message with writer status
+      const minutes = Math.round(durationSeconds / 60)
+      const failedWriters = results.filter((r) => !r.success)
+
+      let message = `Time tracked: ${minutes} min, ${totalTokens} tokens${resolved.ticket ? ` for ${resolved.ticket}` : ""}`
+
+      if (failedWriters.length > 0) {
+        const failedNames = failedWriters.map((r) => r.writer).join(", ")
+        message += ` (${failedNames}: failed)`
       }
+
+      await client.tui.showToast({
+        body: {
+          message,
+          variant: failedWriters.length > 0 ? "warning" : "success",
+        },
+      })
     }
   }
 }