patchwork-os 0.2.0-alpha.34 → 0.2.0-alpha.36

package/templates/recipes/webhook/README.md

@@ -0,0 +1,70 @@
+# Webhook recipe templates
+
+> **Anything that can send HTTP can trigger your AI.** iPhone Shortcut, Stream
+> Deck, Home Assistant, NFC tag, cron job, monitoring tool, another service —
+> if it can POST a body, it can drive a Patchwork recipe.
+
+Five starter templates demonstrating common webhook-triggered workflows. Each
+file is a copy-and-adjust starting point.
+
+## Templates
+
+| File | Purpose | Likely trigger sources |
+|---|---|---|
+| [`capture-thought.yaml`](capture-thought.yaml) | Append a thought to today's journal. | iOS Shortcut + Siri, Stream Deck, NFC tag |
+| [`morning-brief.yaml`](morning-brief.yaml) | On-demand morning digest (vs. the cron version). | iOS Shortcut on first unlock, Apple Watch complication |
+| [`meeting-prep.yaml`](meeting-prep.yaml) | Brief on attendees + context before the next meeting. | Calendar webhook, Apple Calendar event-start automation |
+| [`incident-intake.yaml`](incident-intake.yaml) | Catch-all for monitoring → Linear + Slack alert. | PagerDuty, Sentry, Datadog, uptime checkers |
+| [`customer-escalation.yaml`](customer-escalation.yaml) | Enrich a flagged support ticket with CRM data and post to Slack. | Intercom, Zendesk, HelpScout, Front |
+
+## Install
+
+```sh
+cp templates/recipes/webhook/capture-thought.yaml ~/.patchwork/recipes/
+patchwork stop
+patchwork start
+```
+
+The dashboard's [Recipes page](http://localhost:3000/dashboard/recipes) will
+show the recipe with its full webhook URL + a copyable curl example as soon as
+the bridge picks up the new file.
+
+## Triggering from common sources
+
+### iOS Shortcut
+1. Shortcuts app → New Shortcut → Add action **Get Contents of URL**
+2. Method: `POST`. URL: `http://YOUR-MAC.local:3101/hooks/<path>` (or via Tailscale / your reverse proxy if remote)
+3. Headers: `Content-Type: application/json`
+4. Request Body → JSON → fill in payload fields the recipe expects
+5. Add a Siri phrase ("Hey Siri, capture thought")
+
+### Stream Deck
+- Action: **HTTP Request** plugin
+- Method: POST, URL as above, body matching the recipe's payload conventions
+
+### Home Assistant
+- `automation` block → `service: rest_command.<your-name>` → `url: http://patchwork-bridge:3101/hooks/<path>`
+
+### Plain curl
+Each template includes a runnable `curl` example in its docstring — paste it
+into a script, a cron job, or your monitoring tool's webhook config.
+
+## Payload conventions
+
+Every recipe references the request body via `{{payload.<field>}}`. The
+convention shown in each template's docstring is suggestive, not mandatory —
+you can change field names freely; the bridge passes the full JSON body
+through.
+
+## Security notes
+
+- Webhook endpoints are unauthenticated by default and bound to localhost
+  (`127.0.0.1`). Anything that needs the bridge from another machine should
+  go through a reverse proxy with auth (Tailscale, Caddy + Basic Auth,
+  Cloudflare Tunnel + Access).
+- The receiving recipe's tools still go through your delegation policy — see
+  [`templates/policies/`](../../policies/) for tier presets.
+- Don't trust payload contents blindly. The agent step in
+  `customer-escalation.yaml` and `meeting-prep.yaml` reads the body but
+  doesn't auto-act on it; final actions go through Slack/Linear with their
+  own auth scopes.

package/templates/recipes/webhook/capture-thought.yaml

@@ -0,0 +1,26 @@
+name: capture-thought
+description: |
+  Append a thought to your daily journal from anywhere that can POST HTTP.
+
+  Suggested triggers:
+    - iOS Shortcut (Hey Siri, "capture thought") — see docs/triggers
+    - Stream Deck button
+    - NFC tag near your desk
+    - curl from another script
+
+  Example request:
+    curl -X POST http://localhost:3101/hooks/capture-thought \
+      -H 'Content-Type: application/json' \
+      -d '{"text":"the auth refresh path needs a circuit breaker"}'
+
+trigger:
+  type: webhook
+  path: /capture-thought
+
+steps:
+  - tool: file.append
+    path: ~/.patchwork/journal/{{date}}.md
+    content: "- {{time}}  {{payload.text}}\n"
+
+output:
+  path: ~/.patchwork/journal/{{date}}.md

package/templates/recipes/webhook/customer-escalation.yaml

@@ -0,0 +1,49 @@
+name: customer-escalation
+description: |
+  When a customer support tool flags a high-priority ticket, enrich it with
+  HubSpot CRM data and ping the right Slack channel with full context. The
+  human still decides how to respond — this just shaves the lookup time.
+
+  Suggested triggers:
+    - Intercom webhook (conversation.tagged-priority)
+    - Zendesk webhook (ticket priority changed)
+    - HelpScout / Front custom rule
+    - manual paste from CSAT dashboards via curl
+
+  Payload conventions:
+    customer_email   the contact email (required — used for HubSpot lookup)
+    ticket_url       deep link back to the support tool
+    summary          short description of what they said
+
+  Example request:
+    curl -X POST http://localhost:3101/hooks/customer-escalation \
+      -H 'Content-Type: application/json' \
+      -d '{"customer_email":"jane@bigco.com","ticket_url":"https://app.intercom.com/conversations/9876","summary":"Says checkout has been broken for 3 days"}'
+
+trigger:
+  type: webhook
+  path: /customer-escalation
+
+steps:
+  - tool: hubspot.find_contact
+    email: "{{payload.customer_email}}"
+    into: contact
+  - tool: hubspot.list_recent_deals
+    contact_id: "{{contact.id}}"
+    max: 3
+    into: deals
+  - agent:
+      prompt: |
+        Compose a Slack alert for the customer-success team. Keep it under
+        12 lines. Include: customer name + company, tier (from contact.tier
+        if present), recent deal context, what they said, and the ticket
+        link. End with a single suggested first move.
+
+        Contact: {{contact}}
+        Deals:   {{deals}}
+        Summary: {{payload.summary}}
+        Ticket:  {{payload.ticket_url}}
+      into: alert
+  - tool: slack.post_message
+    channel: "#customer-success"
+    text: "{{alert}}"

package/templates/recipes/webhook/incident-intake.yaml

@@ -0,0 +1,46 @@
+name: incident-intake
+description: |
+  Convert any external incident signal into a Linear issue + Slack alert.
+  Designed as the catch-all webhook your monitoring stack POSTs to so on-call
+  has one place to look.
+
+  Suggested triggers:
+    - PagerDuty webhook
+    - Sentry alert webhook
+    - Datadog monitor
+    - GitHub Actions failure
+    - external uptime checker
+
+  Payload conventions (all optional except `title`):
+    title       short summary, becomes the Linear issue title
+    severity    "critical" | "high" | "medium" | "low" (default: "high")
+    source      "pagerduty" | "sentry" | "datadog" | ...
+    url         deep link back to the source incident page
+    body        extra detail (markdown ok)
+
+  Example request:
+    curl -X POST http://localhost:3101/hooks/incident-intake \
+      -H 'Content-Type: application/json' \
+      -d '{"title":"checkout p99 over 2s","severity":"high","source":"datadog","url":"https://app.datadoghq.com/monitor/123"}'
+
+trigger:
+  type: webhook
+  path: /incident-intake
+
+steps:
+  - tool: linear.create_issue
+    title: "[{{payload.severity}}] {{payload.title}}"
+    description: |
+      Source: {{payload.source}}
+      Link: {{payload.url}}
+
+      {{payload.body}}
+    priority: 1
+    into: issue
+  - tool: slack.post_message
+    channel: "#incidents"
+    text: |
+      :rotating_light: New incident: *{{payload.title}}*
+      Severity: {{payload.severity}}
+      Source: {{payload.source}} — {{payload.url}}
+      Linear: {{issue.url}}

package/templates/recipes/webhook/meeting-prep.yaml

@@ -0,0 +1,48 @@
+name: meeting-prep
+description: |
+  Two minutes before any meeting starts, post a brief on the attendees and
+  recent context (recent email threads, related Linear issues, last meeting
+  notes). Drops the brief into ~/.patchwork/inbox/ and pings you on Slack.
+
+  Suggested triggers:
+    - Calendar webhook ("notify before event") — most reliable
+    - Apple Watch / iOS Shortcut tied to a calendar reminder
+    - Home Assistant routine fired by Apple Calendar event start
+
+  Example request (with attendees + topic in payload):
+    curl -X POST http://localhost:3101/hooks/meeting-prep \
+      -H 'Content-Type: application/json' \
+      -d '{"attendees":["alex@example.com","sam@example.com"],"topic":"Q3 planning"}'
+
+trigger:
+  type: webhook
+  path: /meeting-prep
+
+steps:
+  - tool: gmail.search_threads
+    query: "from:({{payload.attendees}}) newer_than:7d"
+    max: 10
+    into: recent_threads
+  - tool: linear.search_issues
+    query: "{{payload.topic}}"
+    max: 5
+    into: related_issues
+  - agent:
+      prompt: |
+        You are about to walk into a meeting. Produce a 10-line briefing.
+
+        Topic: {{payload.topic}}
+        Attendees: {{payload.attendees}}
+        Recent email threads with attendees: {{recent_threads}}
+        Related Linear issues: {{related_issues}}
+
+        Output sections: Context, Open questions, Suggested first move.
+      into: brief
+  - tool: file.write
+    path: ~/.patchwork/inbox/meeting-{{date}}-{{time}}.md
+    content: |
+      # Meeting prep — {{payload.topic}}
+      {{brief}}
+
+output:
+  path: ~/.patchwork/inbox/meeting-{{date}}-{{time}}.md

package/templates/recipes/webhook/morning-brief.yaml

@@ -0,0 +1,57 @@
+name: morning-brief-webhook
+description: |
+  On-demand morning brief — fires the moment you POST. Pair this with an
+  iOS Shortcut on your home screen ("Brief me") so you get the digest
+  whenever you're ready, not on a fixed cron schedule.
+
+  For the scheduled (cron) version, see ../morning-brief.yaml.
+
+  Suggested triggers:
+    - iOS Shortcut on first phone unlock
+    - Apple Watch complication tap
+    - Home Assistant motion sensor at the kitchen counter
+    - Stream Deck "morning routine" macro
+
+  Example request:
+    curl -X POST http://localhost:3101/hooks/morning-brief
+
+trigger:
+  type: webhook
+  path: /morning-brief
+
+steps:
+  - tool: gmail.fetch_unread
+    since: 24h
+    max: 30
+    into: messages
+  - tool: github.list_issues
+    assignee: "@me"
+    max: 10
+    into: issues
+  - tool: linear.list_issues
+    assignee: "@me"
+    state: "started,unstarted"
+    max: 15
+    into: linear_issues
+  - tool: calendar.list_events
+    days_ahead: 1
+    max: 10
+    into: calendar
+  - agent:
+      prompt: |
+        Write a 12-line morning brief from this data, in plain English,
+        prioritising what needs attention today.
+
+        Email (unread, 24h):  {{messages}}
+        GitHub issues (mine): {{issues}}
+        Linear (mine):        {{linear_issues}}
+        Calendar (next 24h):  {{calendar}}
+      into: brief
+  - tool: file.write
+    path: ~/.patchwork/inbox/morning-brief-{{date}}.md
+    content: |
+      # Morning brief — {{date}}
+      {{brief}}
+
+output:
+  path: ~/.patchwork/inbox/morning-brief-{{date}}.md