workbuddy_skills/open-design/design-templates/live-dashboard/references/connectors.md

Connectors

live-dashboard is a Live Artifact. The values it shows are not hard-coded — they are polled from a connector at runtime. The OD daemon (0.4.0+) ships a Composio connector catalog and a connectors.json contract that artifacts emit alongside index.html.

When inputs.connector === mock (or the daemon cannot resolve the configured connector), the artifact falls back to seeded sample data. This keeps screenshots, the picker preview, and offline use working.

Status — relationship to design-templates/live-artifact/.

The canonical, currently-shipping live-artifact contract lives in design-templates/live-artifact/SKILL.md: it is file-shaped (artifact.json + template.html + data.json + provenance.json) and CLI-shaped on the agent side (the agent calls "$OD_NODE_BIN" "$OD_BIN" tools live-artifacts {create,update} and tools connectors {list,execute} rather than HTTP). The renderer is scalar-only html_template_v1 (apps/daemon/src/live-artifacts/render.ts).

live-dashboard is a complementary browser-runtime variant: the artifact is rendered as a single self-contained HTML page, and the live behaviors (refresh-on-open, manual Refresh, auto-refresh, stale pill) run in-page rather than at template-render time. Polling therefore needs an HTTP shape, which is what the rest of this file describes (POST /api/od/connectors/poll).

Treat the HTTP shape below as a forward-looking proposal that sits alongside the file/CLI contract: the daemon does not yet expose POST /api/od/connectors/poll (apps/daemon/src/server.ts / apps/daemon/src/live-artifacts/), so out-of-the-box the artifact renders against the seeded sample data and the Refresh button only tweens the fixture. When the daemon-team route lands, only seedNextChange() in the template needs to be replaced with the poll() helper documented here — the connectors.json shape is already a usable declarative source-of-truth that downstream tooling (the live-artifact CLI, MCP wrappers, audit logs) can read today.

---

connectors.json schema

Emit one connectors.json at the project root next to index.html:

{
  "schema": "od.connector/1",
  "primary": "notion",
  "freshness": {
    "auto_refresh_seconds": 30,
    "warn_after_seconds": 90,
    "fail_after_seconds": 600
  },
  "bindings": {
    "notion": {
      "provider": "composio.notion",
      "auth_ref": "media-config.json#notion.token",
      "reads": [
        {
          "id": "tasks_active",
          "endpoint": "databases.{id}.query",
          "params": { "id": "${notion.tasks_db_id}",
                      "filter": { "property": "Status", "status": { "does_not_equal": "Done" } },
                      "sorts":  [{ "property": "Updated", "direction": "descending" }] },
          "shape": "task[]"
        },
        {
          "id": "kpi_total",
          "endpoint": "databases.{id}.query",
          "params": { "id": "${notion.tasks_db_id}", "page_size": 1 },
          "extract": "$.metadata.total_count",
          "shape": "integer"
        },
        {
          "id": "activity_recent",
          "endpoint": "search",
          "params": { "filter": { "property": "object", "value": "page" },
                      "sort":   { "direction": "descending", "timestamp": "last_edited_time" },
                      "page_size": 8 },
          "shape": "activity[]"
        }
      ],
      "events": [
        { "id": "task_changed", "type": "page.updated", "selector": "$.tasks_db_id" }
      ]
    }
  }
}

The shape is intentionally close to Notion's REST API — the daemon's connector adapter rewrites endpoint and params into the live provider call. Other connectors (Linear, Stripe, Posthog) follow the same shape with provider-specific endpoint strings.

---

Resolution order (what the daemon does)

1. Read connectors.json from the artifact dir.

2. Look up bindings[primary].provider in the Composio catalog.

3. Resolve auth_ref against the daemon-owned media configuration. The narrow OD_MEDIA_CONFIG_DIR override applies to media-config.json only; otherwise the daemon must derive the file from its already-resolved RUNTIME_DATA_DIR. Do not infer a path from the project cwd or restate one here. Before changing this lookup, read root AGENTS.md → Daemon data directory contract and apps/daemon/src/media/config.ts.

   The artifact never opens any of these paths itself — it always goes through the daemon poll endpoint, and the daemon enforces the correct lookup order. Never read tokens from the artifact.

4. For each reads[].endpoint, the daemon constructs the live HTTP request with the resolved auth and substitutes ${...} placeholders from the resolved media-config.json#<provider>.* values.

5. Cache responses for freshness.auto_refresh_seconds. The Refresh button issues an explicit poll that bypasses the cache.

---

Wiring inside index.html

The artifact does not call Composio directly. It calls the OD daemon's local proxy:

async function poll(readId) {
  const res = await fetch(`/api/od/connectors/poll`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ project: "<project_id>", read: readId })
  });
  if (!res.ok) throw new Error(`poll ${readId} failed: ${res.status}`);
  return res.json();
}

<project_id> is injected by the daemon at render time via a <meta name="od:project" content="..."> tag. The artifact reads it once on mount.

---

Fallback behavior

• On fetch error: keep the previously-rendered values, swap the live-pill to amber Stale · <ago>, write a small grey hint into the footer (Source: Notion · last good poll 4 min ago).
• On inputs.connector === mock: skip poll() entirely, use the seedMock() function in index.html. The live-pill displays Sample data in grey with no dot animation.
• On 401/403: surface a one-time toast Reconnect Notion in Settings → Connectors and stop further polls until the next manual Refresh.

---

Provider-specific cheat sheet

Connector	provider	Shape of one row	Typical KPI
Notion	composio.notion	task = {title, status, assignee, due, prio, updated}	total tasks · done this week · members · review
Linear	composio.linear	issue = {title, state, assignee, priority, updated}	backlog · in progress · blocked · cycle progress
Stripe	composio.stripe	event = {type, amount, customer, created}	MRR · churn · new subs · refunds
Posthog	composio.posthog	event = {name, distinct_id, $current_url, ts}	DAU · signups · feature adoption · errors

Do not invent per-provider shapes. If the user wants something not in this table, fall back to mock and surface a footer hint asking the user to extend the connector catalog.