@synap-core/workspace-templates 0.12.0 → 0.23.0

package/capabilities/posthog-analytics.capability.json

@@ -0,0 +1,258 @@
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",
+  "meta": {
+    "slug": "posthog-analytics",
+    "name": "PostHog — Product Analytics",
+    "description": "Read your product analytics from PostHog: event volume over time, recent events, the people behind them, and your saved insights. Read-only, and locked to one project at install. Needs a PostHog personal API key with read scopes; the phc_ project token will not work.",
+    "tags": [
+      "capability"
+    ],
+    "isPublic": true,
+    "syncByDefault": true
+  },
+  "spec": {
+    "key": "posthog-analytics",
+    "name": "PostHog Analytics",
+    "description": "Read the pod's product analytics out of PostHog. The apps already SEND events in (the `phc_…` project token is ingest-only); this capability is the read half — event volume over time, recent events, the people behind them, and the saved insights that already exist. It installs ONE authenticated HTTP tool whose `baseUrl` pins the host AND the project id at install time, so no caller (human or agent) can aim the credential at another project, and every verb is a fixed GET read with typed parameters — never a passthrough query language. PRECONDITION: a PostHog PERSONAL API KEY with query:read/insight:read/event:read/person:read. The `phc_…` project token will be rejected by every verb here (it 401s on reads). A missing or invalid key fails loudly; it is never reported as 'no data'.",
+    "params": [
+      {
+        "name": "personalApiKey",
+        "label": "PostHog Personal API Key",
+        "type": "text",
+        "required": true,
+        "description": "A PostHog PERSONAL API KEY (PostHog → Settings → Personal API keys) with query:read, insight:read, event:read and person:read. Stored server-encrypted in the vault; never persisted in this template. The `phc_…` project token used by the client apps is INGEST-ONLY and is rejected by every read."
+      },
+      {
+        "name": "analyticsHost",
+        "label": "PostHog host",
+        "type": "text",
+        "required": true,
+        "default": "https://analytics.synap.live",
+        "description": "Origin of the PostHog instance — e.g. https://analytics.synap.live (self-hosted) or https://us.posthog.com (Cloud). Baked into the installed tool's baseUrl."
+      },
+      {
+        "name": "projectId",
+        "label": "PostHog project id",
+        "type": "text",
+        "required": true,
+        "default": "2",
+        "description": "Numeric id of the PostHog project that belongs to THIS pod (2 for the Synap org). Baked into the installed tool's baseUrl and deliberately NOT a call parameter, so no verb can read a different project."
+      }
+    ],
+    "vault": [
+      {
+        "ref": "posthogPersonalApiKey",
+        "name": "{{name}} PostHog Personal API Key",
+        "value": "{{personalApiKey}}",
+        "type": "api_key",
+        "description": "PostHog Personal API Key, read scopes only. The analytics belong to the pod, so this is pod-wide: every pod member and every agent reads the same project through this one secret."
+      }
+    ],
+    "tools": [
+      {
+        "name": "posthog_api",
+        "kind": "api",
+        "description": "Authenticated READ access to the pod's PostHog project. `config.baseUrl` pins host + project id at install time; `config.auth` injects the vaulted Personal API Key as `Authorization: Bearer <key>`. Nothing outside this capability should execute it directly.",
+        "credentialRef": "posthogPersonalApiKey",
+        "executor": "is-agent",
+        "config": {
+          "baseUrl": "{{analyticsHost}}/api/projects/{{projectId}}",
+          "auth": {
+            "in": "header",
+            "name": "Authorization",
+            "prefix": "Bearer "
+          }
+        }
+      }
+    ],
+    "skills": [
+      {
+        "name": "posthog_get_event_trend",
+        "intent": "fetch_record",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "Event volume over time for ONE named event — the number a landing page or a feature is judged by. Reads PostHog's trend insight, so the series is computed server-side rather than by paging raw events. Args: { event: string (required, e.g. \"$pageview\" or \"signup_completed\"), dateFrom?: string (default \"-7d\"), interval?: string (default \"day\") }.",
+        "requires": [
+          "posthog_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "event": "string",
+          "dateFrom": "string?",
+          "interval": "string?"
+        },
+        "providerSpec": {
+          "tool": "posthog_api",
+          "method": "GET",
+          "pathTemplate": "/insights/trend/",
+          "query": {
+            "events": "[{\"id\":\"{{event}}\",\"type\":\"events\"}]",
+            "date_from": "{{dateFrom}}",
+            "interval": "{{interval}}"
+          },
+          "responseShape": {
+            "collectionPath": "result",
+            "collectionAs": "series",
+            "item": {
+              "label": "label",
+              "count": "count",
+              "data": "data"
+            },
+            "scalar": {
+              "count": "@count",
+              "interval": "interval"
+            }
+          },
+          "paramMapping": {
+            "dateFrom": {
+              "default": "-7d"
+            },
+            "interval": {
+              "default": "day"
+            }
+          }
+        }
+      },
+      {
+        "name": "posthog_list_recent_events",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "The most recent raw events, newest first — what is actually arriving right now, with each event's name, timestamp, distinct_id and properties. Use this to confirm instrumentation works before trusting any aggregate. Args: { limit?: number (default 20, max 100) }.",
+        "requires": [
+          "posthog_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "limit": "number?"
+        },
+        "providerSpec": {
+          "tool": "posthog_api",
+          "method": "GET",
+          "pathTemplate": "/events/",
+          "query": {
+            "limit": "{{limit}}"
+          },
+          "responseShape": {
+            "collectionPath": "results",
+            "collectionAs": "events",
+            "item": {
+              "event": "event",
+              "timestamp": "timestamp",
+              "distinctId": "distinct_id",
+              "url": "properties.$current_url"
+            },
+            "scalar": {
+              "count": "@count",
+              "next": "next"
+            }
+          },
+          "paramMapping": {
+            "limit": {
+              "default": 20,
+              "clampMin": 1,
+              "clampMax": 100
+            }
+          }
+        }
+      },
+      {
+        "name": "posthog_list_persons",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "The people behind the events — PostHog person records with their distinct ids and properties. Use it to answer \"who are my users\", not just \"how many\". Args: { limit?: number (default 20, max 100), search?: string }.",
+        "requires": [
+          "posthog_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "limit": "number?",
+          "search": "string?"
+        },
+        "providerSpec": {
+          "tool": "posthog_api",
+          "method": "GET",
+          "pathTemplate": "/persons/",
+          "query": {
+            "limit": "{{limit}}",
+            "search": "{{search}}"
+          },
+          "responseShape": {
+            "collectionPath": "results",
+            "collectionAs": "persons",
+            "item": {
+              "id": "id",
+              "name": "name",
+              "createdAt": "created_at",
+              "distinctIds": "distinct_ids"
+            },
+            "scalar": {
+              "count": "count"
+            }
+          },
+          "paramMapping": {
+            "limit": {
+              "default": 20,
+              "clampMin": 1,
+              "clampMax": 100
+            }
+          }
+        }
+      },
+      {
+        "name": "posthog_list_saved_insights",
+        "intent": "list_records",
+        "kind": "declarative",
+        "scope": "pod",
+        "description": "The insights and dashboards already saved in this project. Read this FIRST when asked an analytics question — a saved insight is the project's own agreed definition of a metric, and reusing it beats inventing a new query. Args: { limit?: number (default 20, max 100) }.",
+        "requires": [
+          "posthog_api"
+        ],
+        "executionMode": "sync",
+        "timeoutSeconds": 30,
+        "parameters": {
+          "limit": "number?"
+        },
+        "providerSpec": {
+          "tool": "posthog_api",
+          "method": "GET",
+          "pathTemplate": "/insights/",
+          "query": {
+            "limit": "{{limit}}"
+          },
+          "responseShape": {
+            "collectionPath": "results",
+            "collectionAs": "insights",
+            "item": {
+              "id": "id",
+              "name": "name",
+              "description": "description",
+              "createdAt": "created_at",
+              "filters": "filters"
+            },
+            "scalar": {
+              "count": "count"
+            }
+          },
+          "paramMapping": {
+            "limit": {
+              "default": 20,
+              "clampMin": 1,
+              "clampMax": 100
+            }
+          }
+        }
+      }
+    ],
+    "provides": [
+      "list_records",
+      "fetch_record"
+    ]
+  },
+  "dependencies": []
+}