Setting the file. One moment.
Canvas SDK D · Querying Canvas Data · PostHog/skills · Skills Docs
Back to the top of the page — line 106
This file
Number 102.1
Position 1 of 1
Type TypeScript
Size 7 KB
Lines 204 references/ canvas-sdk.d.ts
TypeScript · 204 lines · 7 KB
15 export interface CanvasSeriesResult {
16 /** Per-interval values, aligned with `days`. */
17 data : number []
18 /** ISO dates for each interval. */
19 days : string []
20 /** Human labels for each interval. */
21 labels : string []
22 /** Sum across the window, which is the usual KPI total. */
23 count ?: number
24 /** Single-value total for aggregated displays. */
25 aggregated_value ?: number
26 /** Series label. */
27 label ?: string
28 /** Set when the query has a compare period; match on this, never on index. */
29 compare_label ?: 'current' | 'previous'
30 }
31
32 /**
33 * Result of `ph.loadInsight` and `ph.query`. The element shape depends on the
34 * query kind, which is why `results` is not narrowed here:
35 * - Trends-style (typed insight nodes): series objects, so cast to
36 * `CanvasSeriesResult[]`. `columns` is empty.
37 * - SQL: rows, each an array of cell values in `columns` order.
38 * Funnels, retention, and paths return their own PostHog-native shapes.
39 */
40 export interface CanvasDataResult {
41 columns : string []
42 results : unknown []
43 }
44
45 export interface CanvasDateRange {
46 date_from ?: string | null
47 date_to ?: string | null
48 }
49
50 export interface CanvasLoadInsightOptions {
51 /** Re-scope the saved insight to this window (a saved SQL insight may ignore it). */
52 dateRange ?: CanvasDateRange
53 /**
54 * Values for a SQL insight's `{variables.name}` placeholders, keyed by code
55 * name. The host rejects a variable the insight doesn't use.
56 */
57 variables ?: Record < string , unknown >
58 /** Cache lifetime in whole seconds, 30–86400. */
59 refresh ?: number
60 }
61
62 export interface CanvasQueryOptions {
63 /** Cache lifetime in whole seconds, 30–86400. */
64 refresh ?: number
65 }
66
67 /** "user" (default) is private to the viewer; "shared" is one value per canvas, team-visible. */
68 export type CanvasStateScope = 'user' | 'shared'
69
70 export interface CanvasStateEntry {
71 scope : CanvasStateScope
72 key : string
73 value : unknown
74 updatedAt ?: string
75 }
76
77 export interface CanvasState {
78 /** Resolves to the stored JSON value, or null when unset. */
79 get ( key : string , options ?: { scope ?: CanvasStateScope }) : Promise < unknown >
80 /**
81 * Stores a JSON value (64 KB serialized cap, 256 keys per scope). Setting
82 * null deletes the key.
83 */
84 set ( key : string , value : unknown , options ?: { scope ?: CanvasStateScope }) : Promise <{ ok : boolean }>
85 list ( options ?: { scope ?: CanvasStateScope }) : Promise < CanvasStateEntry []>
86 }
87
88 export interface CanvasActions {
89 /**
90 * Write into PostHog as the viewer; the result shape depends on the verb.
91 * Every verb must be declared in `capabilities.posthog.actions`, and calls
92 * belong on an explicit user gesture (a button), never on load or render.
93 */
94 invoke ( verb : string , payload ?: Record < string , unknown >) : Promise < unknown >
95 }
96
97 export type CanvasConnectorCallStatus =
98 | 'ok'
99 | 'not_connected'
100 | 'needs_reauth'
101 | 'blocked'
102 | 'tool_missing'
103 | 'write_blocked'
104 | 'upstream_error'
105
106 export interface CanvasConnectorCallResult {
107 status : CanvasConnectorCallStatus
108 /** The tool output when status is "ok"; MCP tools return { content, structured_content, is_error }. */
109 result : Record < string , unknown > | null
110 /** Human-readable explanation for a non-ok status. */
111 detail : string
112 /** True when the result exceeded the size cap and was cut to a preview. */
113 truncated : boolean
114 /** Settings path where the viewer connects the provider, when that would help. */
115 connect_path : string | null
116 }
117
118 export interface CanvasConnectorCallOptions {
119 /** Cache lifetime in whole seconds, 30–86400. Defaults to 60. */
120 refresh ?: number
121 }
122
123 export interface CanvasConnectors {
124 /**
125 * Read live third-party data with the viewer's own connection. `provider` is
126 * "github" or "mcp:<server host>"; declare every provider and tool in
127 * `capabilities.connectors`. Never rejects for a missing connection: check
128 * `status` and offer `connect(provider)`.
129 */
130 call (
131 provider : string ,
132 tool : string ,
133 args ?: Record < string , unknown >,
134 options ?: CanvasConnectorCallOptions
135 ) : Promise < CanvasConnectorCallResult >
136 /** Open the settings page where the viewer connects the provider. Call from a click. */
137 connect ( provider : string ) : void
138 }
139
140 export interface CanvasAgentRequestResult {
141 requestOutcome : 'signaled' | 'new_run' | 'already_queued' | 'reported'
142 taskId : string
143 }
144
145 export interface CanvasAgent {
146 /**
147 * Ask the canvas's authoring agent for a change. The host shows the exact
148 * prompt and asks the viewer to approve before anything is dispatched.
149 * Requires `capabilities.posthog.agentRequests`.
150 */
151 request ( prompt : string ) : Promise < CanvasAgentRequestResult >
152 }
153
154 /** In-app navigation. Only these four targets exist. */
155 export interface CanvasNavigate {
156 toTask ( taskId : string ) : void
157 toNewTask ( options ?: { prompt ?: string ; repository ?: string }) : void
158 toCanvas ( canvasId : string ) : void
159 toNewCanvas () : void
160 }
161
162 export interface CanvasSdk {
163 /**
164 * PREFERRED data path: load a saved insight by short id and render its stored
165 * result. Declare the short id in `capabilities.posthog.insights`.
166 */
167 loadInsight ( shortId : string , options ?: CanvasLoadInsightOptions ) : Promise < CanvasDataResult >
168 /**
169 * Run a typed query node (`{ kind: "TrendsQuery", … }`, preferred, because numbers
170 * match the PostHog UI) or an inline HogQL string (escape hatch). Requires
171 * `capabilities.posthog.inlineQueries` in a published canvas.
172 */
173 query (
174 query : Record < string , unknown > | string ,
175 params ?: Record < string , unknown >,
176 options ?: CanvasQueryOptions
177 ) : Promise < CanvasDataResult >
178 /**
179 * Send an analytics event (properties capped at 16 KB serialized). Declare
180 * each event name in `capabilities.posthog.captureEvents`.
181 */
182 capture ( event : string , properties ?: Record < string , unknown >, distinctId ?: string ) : Promise <{ ok : boolean }>
183 /** Open a PostHog HTTPS URL or a GitHub PR HTTPS URL from a user click. */
184 openExternal ( url : string ) : void
185 state : CanvasState
186 actions : CanvasActions
187 agent : CanvasAgent
188 connectors : CanvasConnectors
189 /**
190 * Frozen per-placement config parsed at boot. Published/component runtime
191 * only; undefined in the edit-mode preview.
192 */
193 config ?: Readonly < Record < string , unknown >>
194 /** Available in current preview and published runtimes; older builds may omit it. */
195 navigate ?: CanvasNavigate
196 }
197
198 /**
199 * The canvas's PostHog bridge, the same object as the `window.ph` global. Both
200 * are installed on the document, so a `?worker` bundle cannot reach them.
201 */
202 export declare const ph : CanvasSdk
203 declare const defaultPh : CanvasSdk
204 export default defaultPh