@picked/client 0.0.1-dev.1788925875333 → 0.0.1-dev.1793753513002

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (226) hide show
  1. package/LICENSE +1 -0
  2. package/README.md +34 -158
  3. package/dist/.tsbuildinfo +1 -1
  4. package/dist/api-ZkaFvphK.cjs +1 -0
  5. package/dist/{api-DbMJli3H.js → api-nJ3O-8r5.js} +1 -1
  6. package/dist/cjs/form/index.js +1 -1
  7. package/dist/cjs/index.js +2 -2
  8. package/dist/cjs/logic-engine.js +1 -0
  9. package/dist/cjs/plugins/dom-observer/index.js +1 -1
  10. package/dist/cjs/plugins/dynamic-experiences/index.js +1 -1
  11. package/dist/cjs/plugins/experience-browser-storage/index.js +1 -1
  12. package/dist/cjs/plugins/responses-browser-storage/index.js +1 -1
  13. package/dist/cjs/plugins/telemetry/index.js +1 -1
  14. package/dist/cjs/server/index.js +1 -1
  15. package/dist/cjs/storage.js +1 -0
  16. package/dist/dom-7g2LZCIp.cjs +1 -0
  17. package/dist/{dom-BqcToNL0.js → dom-v6ulxr_z.js} +1 -5
  18. package/dist/esm/form/index.js +5 -16
  19. package/dist/esm/index.js +576 -615
  20. package/dist/esm/logic-engine.js +208 -0
  21. package/dist/esm/plugins/dom-observer/index.js +1 -1
  22. package/dist/esm/plugins/dynamic-experiences/index.js +4 -4
  23. package/dist/esm/plugins/experience-browser-storage/index.js +12 -10
  24. package/dist/esm/plugins/responses-browser-storage/index.js +2 -6
  25. package/dist/esm/plugins/telemetry/index.js +26 -15
  26. package/dist/esm/preview/index.js +1 -2
  27. package/dist/esm/server/index.js +47 -43
  28. package/dist/esm/storage.js +1 -0
  29. package/dist/experience-instance-4D6Yk-h0.js +774 -0
  30. package/dist/experience-instance-D2FAkiPx.cjs +1 -0
  31. package/dist/plugin-B1kexnbX.js +256 -0
  32. package/dist/plugin-Bnmk8pN8.cjs +1 -0
  33. package/dist/preview-channel-BMOEreho.cjs +1 -0
  34. package/dist/{preview-channel-CSr96XAo.js → preview-channel-CLXVoL_j.js} +2 -5
  35. package/dist/{version-VvasRUfR.js → preview-unavailable-BaHYVZQD.js} +100 -61
  36. package/dist/preview-unavailable-ClBw_DDY.cjs +1 -0
  37. package/dist/provider-BFdnIgeH.cjs +1 -0
  38. package/dist/provider-C98VWkEj.js +115 -0
  39. package/dist/{rules-logic-HesIUCu6.js → rules-logic-9hh8y_1b.js} +1 -1
  40. package/dist/rules-logic-VUbvWqdi.cjs +1 -0
  41. package/dist/types/data-source/preview-unavailable.d.ts +18 -0
  42. package/dist/types/data-source/preview-unavailable.d.ts.map +1 -0
  43. package/dist/types/data-source/provider.d.ts +5 -0
  44. package/dist/types/data-source/provider.d.ts.map +1 -1
  45. package/dist/types/data-source/request-observer.d.ts +21 -8
  46. package/dist/types/data-source/request-observer.d.ts.map +1 -1
  47. package/dist/types/entities/action/action.d.ts +94 -23
  48. package/dist/types/entities/action/action.d.ts.map +1 -1
  49. package/dist/types/entities/experience/experience.d.ts +8 -0
  50. package/dist/types/entities/experience/experience.d.ts.map +1 -1
  51. package/dist/types/entities/experience-instance/experience-instance.d.ts +14 -1
  52. package/dist/types/entities/experience-instance/experience-instance.d.ts.map +1 -1
  53. package/dist/types/exports.d.ts +1 -0
  54. package/dist/types/exports.d.ts.map +1 -1
  55. package/dist/types/index.d.ts +2 -2
  56. package/dist/types/index.d.ts.map +1 -1
  57. package/dist/types/lifecycle/rules-logic.d.ts.map +1 -1
  58. package/dist/types/logic-engine.d.ts +9 -0
  59. package/dist/types/logic-engine.d.ts.map +1 -1
  60. package/dist/types/picked.d.ts +38 -8
  61. package/dist/types/picked.d.ts.map +1 -1
  62. package/dist/types/plugins/dynamic-experiences/index.d.ts +1 -0
  63. package/dist/types/plugins/dynamic-experiences/index.d.ts.map +1 -1
  64. package/dist/types/plugins/dynamic-experiences/plugin.d.ts.map +1 -1
  65. package/dist/types/plugins/dynamic-experiences/types.d.ts +5 -2
  66. package/dist/types/plugins/dynamic-experiences/types.d.ts.map +1 -1
  67. package/dist/types/plugins/experience-browser-storage/plugin.d.ts.map +1 -1
  68. package/dist/types/plugins/telemetry/plugin.d.ts +2 -0
  69. package/dist/types/plugins/telemetry/plugin.d.ts.map +1 -1
  70. package/dist/types/schema-registry.d.ts +34 -0
  71. package/dist/types/schema-registry.d.ts.map +1 -1
  72. package/dist/types/server/serialize.d.ts +1 -0
  73. package/dist/types/server/serialize.d.ts.map +1 -1
  74. package/dist/types/storage.d.ts +6 -0
  75. package/dist/types/storage.d.ts.map +1 -0
  76. package/dist/types/typed-content.d.ts +14 -1
  77. package/dist/types/typed-content.d.ts.map +1 -1
  78. package/dist/types/utils/events.d.ts +4 -0
  79. package/dist/types/utils/events.d.ts.map +1 -1
  80. package/dist/types/utils/node-tree/min-max-steps-to-leaf.d.ts +16 -6
  81. package/dist/types/utils/node-tree/min-max-steps-to-leaf.d.ts.map +1 -1
  82. package/dist/types/utils/node-tree/min-max-steps-to-origin.d.ts +18 -7
  83. package/dist/types/utils/node-tree/min-max-steps-to-origin.d.ts.map +1 -1
  84. package/dist/types/utils/node-tree/next-reachable-step-nodes.d.ts +30 -6
  85. package/dist/types/utils/node-tree/next-reachable-step-nodes.d.ts.map +1 -1
  86. package/dist/types/utils/node-tree/node-adjacency.d.ts +50 -0
  87. package/dist/types/utils/node-tree/node-adjacency.d.ts.map +1 -0
  88. package/dist/types/utils/node-tree/node-tree-index.d.ts +57 -0
  89. package/dist/types/utils/node-tree/node-tree-index.d.ts.map +1 -0
  90. package/dist/types/utils/rules-logic.d.ts +3 -2
  91. package/dist/types/utils/rules-logic.d.ts.map +1 -1
  92. package/dist/types/utils/search-params.d.ts +20 -0
  93. package/dist/types/utils/search-params.d.ts.map +1 -1
  94. package/package.json +39 -13
  95. package/dist/api-qiqq8lgz.cjs +0 -1
  96. package/dist/docs/_root.css +0 -101
  97. package/dist/docs/explanation/conditions-and-the-logic-engine.md +0 -94
  98. package/dist/docs/explanation/content-references.md +0 -99
  99. package/dist/docs/explanation/feature-flag-allocation.md +0 -218
  100. package/dist/docs/explanation/how-picked-works.md +0 -124
  101. package/dist/docs/explanation/how-pickedql-works.md +0 -76
  102. package/dist/docs/explanation/pages-and-flows.md +0 -64
  103. package/dist/docs/explanation/the-content-model.md +0 -87
  104. package/dist/docs/explanation/the-two-apis.md +0 -68
  105. package/dist/docs/explanation/why-server-side-rendering.md +0 -76
  106. package/dist/docs/explanation/workspaces-and-versions.md +0 -71
  107. package/dist/docs/how-to/add-a-step-field-or-action.md +0 -43
  108. package/dist/docs/how-to/analytics/index.md +0 -316
  109. package/dist/docs/how-to/archive-or-delete-a-workspace.md +0 -46
  110. package/dist/docs/how-to/authenticate-the-cli.md +0 -97
  111. package/dist/docs/how-to/authenticate-with-a-magic-link.md +0 -40
  112. package/dist/docs/how-to/authenticate-with-a-password.md +0 -51
  113. package/dist/docs/how-to/authenticate-with-an-api-key.md +0 -51
  114. package/dist/docs/how-to/authenticate-with-oauth.md +0 -40
  115. package/dist/docs/how-to/build-a-flow.md +0 -83
  116. package/dist/docs/how-to/connect-the-mcp-server.md +0 -38
  117. package/dist/docs/how-to/create-a-content-entry.md +0 -48
  118. package/dist/docs/how-to/create-a-project.md +0 -29
  119. package/dist/docs/how-to/create-an-experience.md +0 -42
  120. package/dist/docs/how-to/create-and-revoke-an-api-key.md +0 -42
  121. package/dist/docs/how-to/debug-with-the-chrome-extension.md +0 -57
  122. package/dist/docs/how-to/define-a-page-layout.md +0 -46
  123. package/dist/docs/how-to/fill-and-publish-a-page.md +0 -66
  124. package/dist/docs/how-to/install-the-gtm-template.md +0 -84
  125. package/dist/docs/how-to/install-the-sdk.md +0 -93
  126. package/dist/docs/how-to/install-the-vite-plugin.md +0 -69
  127. package/dist/docs/how-to/invite-and-remove-members.md +0 -34
  128. package/dist/docs/how-to/point-one-entry-at-another.md +0 -61
  129. package/dist/docs/how-to/preview-a-workspace.md +0 -28
  130. package/dist/docs/how-to/publish-a-workspace.md +0 -30
  131. package/dist/docs/how-to/read-a-feature-flag.md +0 -113
  132. package/dist/docs/how-to/read-a-referenced-entry.md +0 -109
  133. package/dist/docs/how-to/register-a-component.md +0 -55
  134. package/dist/docs/how-to/register-an-action-handler.md +0 -67
  135. package/dist/docs/how-to/render-a-step-form.md +0 -131
  136. package/dist/docs/how-to/render-an-unpublished-preview.md +0 -41
  137. package/dist/docs/how-to/reuse-a-section.md +0 -53
  138. package/dist/docs/how-to/reuse-a-step-field-or-action.md +0 -28
  139. package/dist/docs/how-to/roll-back-a-published-version.md +0 -26
  140. package/dist/docs/how-to/run-an-ab-test.md +0 -49
  141. package/dist/docs/how-to/run-code-on-a-form-submission.md +0 -125
  142. package/dist/docs/how-to/server-render-a-page.md +0 -81
  143. package/dist/docs/how-to/set-a-content-security-policy.md +0 -32
  144. package/dist/docs/how-to/set-up-mfa.md +0 -69
  145. package/dist/docs/how-to/switch-workspaces.md +0 -122
  146. package/dist/docs/how-to/upload-and-use-an-asset.mdx +0 -73
  147. package/dist/docs/how-to/validate-a-field.md +0 -52
  148. package/dist/docs/how-to/write-a-condition.md +0 -45
  149. package/dist/docs/how-to/write-a-predicate.md +0 -60
  150. package/dist/docs/index.md +0 -59
  151. package/dist/docs/reference/dashboard/actions.mdx +0 -53
  152. package/dist/docs/reference/dashboard/api-keys.mdx +0 -38
  153. package/dist/docs/reference/dashboard/conditions.mdx +0 -42
  154. package/dist/docs/reference/dashboard/content/asset-library.mdx +0 -63
  155. package/dist/docs/reference/dashboard/content/blocks.mdx +0 -57
  156. package/dist/docs/reference/dashboard/content/content-entries.mdx +0 -95
  157. package/dist/docs/reference/dashboard/content/models.mdx +0 -108
  158. package/dist/docs/reference/dashboard/content/pages.mdx +0 -61
  159. package/dist/docs/reference/dashboard/experiences.mdx +0 -51
  160. package/dist/docs/reference/dashboard/features.mdx +0 -154
  161. package/dist/docs/reference/dashboard/fields.mdx +0 -106
  162. package/dist/docs/reference/dashboard/flow-builder/canvas.mdx +0 -58
  163. package/dist/docs/reference/dashboard/flow-builder/condition-builder.md +0 -57
  164. package/dist/docs/reference/dashboard/flow-builder/keyboard-shortcuts.md +0 -72
  165. package/dist/docs/reference/dashboard/flow-builder/nodes.md +0 -63
  166. package/dist/docs/reference/dashboard/projects.mdx +0 -44
  167. package/dist/docs/reference/dashboard/reports.mdx +0 -43
  168. package/dist/docs/reference/dashboard/steps.mdx +0 -37
  169. package/dist/docs/reference/dashboard/team-management.md +0 -29
  170. package/dist/docs/reference/dashboard/workspace-versioning.mdx +0 -30
  171. package/dist/docs/reference/dashboard/workspaces.mdx +0 -76
  172. package/dist/docs/reference/delivery-api/experience-content.md +0 -152
  173. package/dist/docs/reference/delivery-api/index.md +0 -45
  174. package/dist/docs/reference/delivery-api/preview-caching-crawling.md +0 -79
  175. package/dist/docs/reference/delivery-api/project-config.md +0 -65
  176. package/dist/docs/reference/delivery-api/workspace-schema.md +0 -85
  177. package/dist/docs/reference/glossary.md +0 -181
  178. package/dist/docs/reference/management-api/authentication.md +0 -74
  179. package/dist/docs/reference/management-api/authorization-and-scopes.md +0 -285
  180. package/dist/docs/reference/management-api/error-handling.md +0 -233
  181. package/dist/docs/reference/management-api/pagination.md +0 -192
  182. package/dist/docs/reference/pickedql/data-sources.md +0 -174
  183. package/dist/docs/reference/pickedql/dimensions.md +0 -103
  184. package/dist/docs/reference/pickedql/filtering.md +0 -64
  185. package/dist/docs/reference/pickedql/index.md +0 -18
  186. package/dist/docs/reference/pickedql/schema.md +0 -172
  187. package/dist/docs/reference/pickedql/virtual-functions.md +0 -248
  188. package/dist/docs/reference/sdk/actions.md +0 -30
  189. package/dist/docs/reference/sdk/analytics-events.md +0 -445
  190. package/dist/docs/reference/sdk/conditions.md +0 -147
  191. package/dist/docs/reference/sdk/content-security-policy.md +0 -21
  192. package/dist/docs/reference/sdk/content.md +0 -213
  193. package/dist/docs/reference/sdk/experiences.md +0 -51
  194. package/dist/docs/reference/sdk/features.md +0 -256
  195. package/dist/docs/reference/sdk/fields.md +0 -255
  196. package/dist/docs/reference/sdk/index.md +0 -68
  197. package/dist/docs/reference/sdk/plugins/create-experience.md +0 -123
  198. package/dist/docs/reference/sdk/plugins/dynamic-experiences.md +0 -74
  199. package/dist/docs/reference/sdk/plugins/index.md +0 -29
  200. package/dist/docs/reference/sdk/plugins/window-object.md +0 -25
  201. package/dist/docs/reference/sdk/predicates.md +0 -43
  202. package/dist/docs/reference/sdk/ssr/index.md +0 -33
  203. package/dist/docs/reference/sdk/ssr/rendering-and-hydration.md +0 -103
  204. package/dist/docs/reference/sdk/ssr/serialize.md +0 -80
  205. package/dist/docs/reference/sdk/ssr/slots-and-placements.md +0 -59
  206. package/dist/docs/reference/sdk/steps.md +0 -86
  207. package/dist/docs/reference/sdk/type-generation.md +0 -196
  208. package/dist/docs/reference/tools/chrome-extension.md +0 -16
  209. package/dist/docs/reference/tools/cli.md +0 -146
  210. package/dist/docs/reference/tools/image-optimisation-service.md +0 -104
  211. package/dist/docs/reference/tools/mcp.md +0 -90
  212. package/dist/docs/reference/tools/vite-plugin.md +0 -163
  213. package/dist/docs/tutorials/first-api-call.md +0 -228
  214. package/dist/docs/tutorials/first-experience-in-the-dashboard.mdx +0 -143
  215. package/dist/docs/tutorials/first-experience.mdx +0 -254
  216. package/dist/docs/tutorials/first-server-rendered-page.mdx +0 -186
  217. package/dist/dom-DlLH3FxV.cjs +0 -1
  218. package/dist/experience-instance-DGk11d8a.js +0 -563
  219. package/dist/experience-instance-Dej3P1sE.cjs +0 -1
  220. package/dist/plugin-BcLaCLm1.cjs +0 -1
  221. package/dist/plugin-De_BJSwE.js +0 -194
  222. package/dist/preview-channel-Cx0e6fye.cjs +0 -1
  223. package/dist/provider-C_9u0yGJ.cjs +0 -1
  224. package/dist/provider-ovM-CBX_.js +0 -98
  225. package/dist/rules-logic-CGZIYgAI.cjs +0 -1
  226. package/dist/version-BvLZaTMC.cjs +0 -1
@@ -1,316 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to run an analytics query
7
-
8
- This guide gives you a query for each common analytics question. Copy one, put your own
9
- project ID in the `WHERE` clause, and run it.
10
-
11
- Every query must carry a tenant filter. See
12
- [About PickedQL](/explanation/how-pickedql-works) for why, and
13
- [Data sources](/reference/pickedql/data-sources) for every table.
14
-
15
- ## Daily A/B test trend
16
-
17
- ```sql
18
- SELECT
19
- project_local_date,
20
- control_users() AS control,
21
- variant_users() AS variant
22
- FROM metrics
23
- WHERE project_id = '{{ your project ID }}'
24
- AND project_local_date >= '2026-04-01'
25
- GROUP BY project_local_date
26
- ORDER BY project_local_date
27
- ```
28
-
29
- **Result:**
30
-
31
- | project_local_date | control | variant |
32
- | ----------------- | ------- | ------- |
33
- | 2026-04-11 | 4361 | 101 |
34
- | 2026-04-12 | 4178 | 126 |
35
- | 2026-04-13 | 5008 | 176 |
36
-
37
- ## Conversion rate uplift by date
38
-
39
- ```sql
40
- SELECT
41
- project_local_date,
42
- control_conversion_rate() AS control_conversion_rate,
43
- variant_conversion_rate() AS variant_conversion_rate,
44
- conversion_rate_uplift() AS conversion_rate_uplift_pct
45
- FROM metrics
46
- WHERE project_id = '{{ your project ID }}'
47
- AND project_local_date >= '2026-04-01'
48
- GROUP BY project_local_date
49
- ORDER BY project_local_date
50
- ```
51
-
52
- **Result:**
53
-
54
- | project_local_date | control_conversion_rate | variant_conversion_rate | conversion_rate_uplift_pct |
55
- | ----------------- | ----------------------- | ----------------------- | -------------------------- |
56
- | 2026-04-01 | 0.0322 | 0.0349 | 0.0349 |
57
- | 2026-04-02 | 0.0398 | 0.0416 | 0.0416 |
58
- | 2026-04-03 | 0.0462 | 0 | -0.0001 |
59
-
60
- ## Custom conversion rate definition
61
-
62
- Override the default conversion, which counts a `purchase` event, with your own
63
- numerator and denominator. Use this when a form submission, a lead capture, or
64
- another event of your own defines a conversion.
65
-
66
- ```sql
67
- -- Lead capture conversion: form submissions / lead-capture step entries
68
- SELECT
69
- project_local_date,
70
- control_conversion_rate(
71
- numerator='event_type=form_submit_success',
72
- denominator='step_id=lead-capture-step'
73
- ) AS control_lead_cr,
74
- variant_conversion_rate(
75
- numerator='event_type=form_submit_success',
76
- denominator='step_id=lead-capture-step'
77
- ) AS variant_lead_cr
78
- FROM events
79
- WHERE project_id = '{{ your project ID }}'
80
- AND client_local_date >= '2026-04-01'
81
- GROUP BY project_local_date
82
- ORDER BY project_local_date
83
- ```
84
-
85
- You can also combine multiple events with `OR` and group with parentheses:
86
-
87
- ```sql
88
- -- A `checkout_complete` event or an `order_create` event counts as a conversion.
89
- SELECT
90
- control_conversion_rate(
91
- 'event_type=checkout_complete OR event_type=order_create'
92
- ) AS control_cr,
93
- variant_conversion_rate(
94
- 'event_type=checkout_complete OR event_type=order_create'
95
- ) AS variant_cr
96
- FROM events
97
- WHERE project_id = '{{ your project ID }}'
98
- ```
99
-
100
- ## Your own segment with `control_users` and `variant_users`
101
-
102
- On `events`, four functions take an optional filter string: `control_users`,
103
- `variant_users`, `control_sessions`, and `variant_sessions`. The filter counts only a
104
- user or a session that matches your expression. It applies together with the
105
- `variant_type` filter that PickedQL adds.
106
-
107
- ```sql
108
- -- The control users who fired an `app_initialize` event, by step.
109
- SELECT
110
- step_id,
111
- control_users('event_type=app_initialize') AS control_initialized,
112
- variant_users('event_type=app_initialize') AS variant_initialized
113
- FROM events
114
- WHERE project_id = '{{ your project ID }}'
115
- AND client_local_date >= '2026-04-01'
116
- GROUP BY step_id
117
- ORDER BY control_initialized DESC
118
- ```
119
-
120
- The named form (`filter=`) is also supported:
121
-
122
- ```sql
123
- SELECT control_users(filter='event_type=form_submit AND step_id=lead-capture') FROM events
124
- WHERE project_id = '{{ your project ID }}'
125
- ```
126
-
127
- ## Conversion rate from nested virtual functions
128
-
129
- The numerator and the denominator can come from different segments. An example is the
130
- control users who fired an event of your own, divided by **all** users and not by the
131
- control users alone. For that, pass a virtual function call directly as an argument
132
- of the conversion rate:
133
-
134
- ```sql
135
- -- The control users who fired `app_initialize`, over all users of every variant.
136
- SELECT
137
- control_conversion_rate(
138
- control_users('event_type=app_initialize'),
139
- all_users()
140
- ) AS control_initialize_rate
141
- FROM events
142
- WHERE project_id = '{{ your project ID }}'
143
- AND client_local_date >= '2026-04-01'
144
- ```
145
-
146
- ## A/B test by device
147
-
148
- ```sql
149
- SELECT
150
- device_category,
151
- control_users() AS control,
152
- variant_users() AS variant
153
- FROM metrics
154
- WHERE project_id = '{{ your project ID }}'
155
- GROUP BY device_category
156
- ```
157
-
158
- **Result:**
159
-
160
- | device_category | control | variant |
161
- | --------------- | ------- | ------- |
162
- | Phone | 193430 | 1723 |
163
- | Desktop | 23423 | 309 |
164
- | Tablet | 13294 | 65 |
165
-
166
- ## Daily A/B test trend by device
167
-
168
- Combine date and device dimensions to spot device-specific trends:
169
-
170
- ```sql
171
- SELECT
172
- project_local_date,
173
- device_category,
174
- control_users() AS control,
175
- variant_users() AS variant
176
- FROM metrics
177
- WHERE project_id = '{{ your project ID }}'
178
- AND project_local_date >= '2026-04-01'
179
- GROUP BY project_local_date, device_category
180
- ORDER BY project_local_date, device_category
181
- ```
182
-
183
- **Result:**
184
-
185
- | project_local_date | device_category | control | variant |
186
- | ----------------- | --------------- | ------- | ------- |
187
- | 2026-04-13 | Tablet | 175 | 2 |
188
- | 2026-04-14 | Desktop | 37 | 1 |
189
- | 2026-04-14 | Phone | 244 | 1 |
190
-
191
- ## Purchase by UTM source
192
-
193
- ```sql
194
- SELECT
195
- utm_source,
196
- all_users() AS users,
197
- all_purchase_users() AS purchasers
198
- FROM metrics
199
- WHERE project_id = '{{ your project ID }}'
200
- GROUP BY utm_source
201
- ```
202
-
203
- **Result:**
204
-
205
- | utm_source | users | purchasers |
206
- | ---------- | ------ | ---------- |
207
- | `meta` | 12031 | 101 |
208
- | `fb` | 3656 | 31 |
209
- | `an` | 100366 | 299 |
210
-
211
- ## Step funnel for variant users
212
-
213
- Count unique variant users per step to understand the conversion funnel:
214
-
215
- ```sql
216
- SELECT
217
- step_id,
218
- variant_users() AS variant
219
- FROM metrics
220
- WHERE project_id = '{{ your project ID }}'
221
- AND project_local_date >= '2026-04-01'
222
- GROUP BY step_id
223
- ORDER BY variant DESC
224
- ```
225
-
226
- **Result:**
227
-
228
- | step_id | variant |
229
- | ------------------------------ | ------- |
230
- | `who-are-you-protecting-step` | 1093 |
231
- | `about-yourself-step` | 533 |
232
- | `date-of-birth-step` | 435 |
233
- | `employment-status-step` | 408 |
234
- | `nicotine-usage-step` | 407 |
235
- | `coverage-motivation-step` | 405 |
236
- | `lead-capture-step` | 398 |
237
-
238
-
239
- ## Sankey — overall user journey
240
-
241
- A forward window from the starting step. A user who never reaches `targeting_step`
242
- still gives edges, up to `num_nodes_after_start`.
243
-
244
- ```sql
245
- SELECT source, target, users FROM experience_journey
246
- WHERE project_id = '{{ your project ID }}'
247
- AND starting_step = '{{ starting step ID }}'
248
- AND targeting_step = '{{ target step ID }}'
249
- AND num_nodes_after_start = 10
250
- ```
251
-
252
- **Result:**
253
-
254
- | source | target | users |
255
- | ------------------------- | ------------------------- | ----- |
256
- | `001. step-start` | `002. step-questionnaire-1` | 182 |
257
- | `002. step-questionnaire-1` | `003. step-quote` | 144 |
258
- | `003. step-quote` | `004. step-target` | 121 |
259
-
260
- ## Sankey — the top paths to a target step
261
-
262
- A backward window anchored at the target. It also ranks the paths and keeps the ones
263
- with the most users.
264
-
265
- ```sql
266
- SELECT source, target, users FROM experience_journey
267
- WHERE project_id = '{{ your project ID }}'
268
- AND experience_id = '{{ experience ID }}'
269
- AND starting_step = '{{ starting step ID }}'
270
- AND targeting_step = '{{ target step ID }}'
271
- AND num_nodes_before_target = 5
272
- AND top_n_path = 10
273
- ```
274
-
275
- ## Sankey — drop-off view
276
-
277
- Starts at `starting_step` and emits every consecutive transition until `num_nodes_after_start` steps later (no target).
278
-
279
- ```sql
280
- SELECT source, target, users FROM experience_journey
281
- WHERE project_id = '{{ your project ID }}'
282
- AND experience_id = '{{ experience ID }}'
283
- AND starting_step = '{{ starting step ID }}'
284
- AND num_nodes_after_start = 10
285
- ```
286
-
287
- ## List all control users for mobile (user-level)
288
-
289
- Use `events` when you need data at the individual user level:
290
-
291
- ```sql
292
- SELECT
293
- device_category,
294
- user_canonical_id
295
- FROM events
296
- WHERE project_id = '{{ your project ID }}'
297
- AND device_category = 'Mobile'
298
- AND variant_type = 'Control'
299
- ```
300
-
301
- **Result:**
302
-
303
- | device_category | user_canonical_id |
304
- | --------------- | ------------------------------------ |
305
- | Mobile | `019cc336-5a6a-7c32-b638-cdcc983b3e70` |
306
- | Mobile | `019cc336-5a6a-7d8f-994c-69bc28e5f550` |
307
- | Mobile | `019cc80f-503c-7181-b2c6-986b1f76d496` |
308
-
309
- ## Related
310
-
311
- - [About PickedQL](/explanation/how-pickedql-works) — what the layer expands for you.
312
- - [Virtual functions](/reference/pickedql/virtual-functions) — every function.
313
- - [Dimensions](/reference/pickedql/dimensions) — every dimension column.
314
- - [Analytics events](/reference/sdk/analytics-events) — every `event_type` value that a
315
- filter can use.
316
- - [Reports](/reference/dashboard/reports) — the same data as an embedded dashboard.
@@ -1,46 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to archive or delete a workspace
7
-
8
- This guide shows you how to take a draft workspace out of use. Archive it when you want
9
- to keep it. Delete it only when you are certain, because you cannot reverse a delete.
10
-
11
- You cannot archive or delete a live workspace. Make a different workspace live first.
12
-
13
- ## Archive a workspace
14
-
15
- 1. Open the workspace settings page.
16
- 2. Click **Archive workspace** in the page header.
17
- 3. Confirm in the modal.
18
-
19
- The workspace leaves the default list. It stays editable.
20
-
21
- ## Unarchive a workspace
22
-
23
- 1. Open the workspace settings page.
24
- 2. Click **Unarchive workspace** in the page header.
25
-
26
- ## Delete a workspace
27
-
28
- 1. Open the workspace settings page.
29
- 2. Click **Delete workspace**.
30
- 3. Confirm in the modal.
31
-
32
- Picked removes the workspace, and everything in it, permanently.
33
-
34
- ## Rename a workspace
35
-
36
- 1. Open the workspace settings page.
37
- 2. Change the **Workspace name** field.
38
- 3. Click **Save changes**.
39
-
40
- A name is unique inside a project. The dashboard rejects a duplicate name.
41
-
42
- ## Related
43
-
44
- - [About workspaces and versions](/explanation/workspaces-and-versions) — why Picked keeps
45
- these two operations separate.
46
- - [Workspaces](/reference/dashboard/workspaces) — the settings reference.
@@ -1,97 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to authenticate the CLI
7
-
8
- This guide shows you how to install the `picked` command and sign it in. Commands that read
9
- your organizations, projects, and workspaces then know who you are. It expects a Picked
10
- account and a project directory to work in.
11
-
12
- ## 1. Install the CLI
13
-
14
- :::code-group
15
-
16
- ```bash [npm]
17
- npm install picked
18
- ```
19
-
20
- ```bash [pnpm]
21
- pnpm add picked
22
- ```
23
-
24
- ```bash [yarn]
25
- yarn add picked
26
- ```
27
-
28
- :::
29
-
30
- The binary is `picked`. Run it from the directory that holds your `picked.config.ts`, so it
31
- reads your configuration and writes your selection next to it.
32
-
33
- ## 2. Sign in
34
-
35
- ```bash
36
- picked login
37
- ```
38
-
39
- The command opens your browser for a one-time sign-in and prints your identity:
40
-
41
- ```
42
- Opening your browser to sign in...
43
- https://api.picked.app/…/oauth/authorize?…
44
- Logged in as you@example.com (https://api.picked.app)
45
- ```
46
-
47
- The CLI stores the session in `~/.picked/auth/<origin>.json`. It refreshes the session as it nears expiry.
48
-
49
- ## 3. Confirm the session
50
-
51
- ```bash
52
- picked whoami
53
- ```
54
-
55
- ```
56
- you@example.com (https://api.picked.app)
57
- ```
58
-
59
- Each command acts on the API origin your current directory resolves to, and on no other. To
60
- end the session for that origin:
61
-
62
- ```bash
63
- picked logout
64
- ```
65
-
66
- ```
67
- Logged out of https://api.picked.app.
68
- ```
69
-
70
- ## Run the CLI in CI
71
-
72
- `picked generate types` reads the workspace schema, not your account, so CI needs no
73
- session for it. A workspace you read with `source: 'preview'` needs that workspace's token.
74
- Run `picked workspace use` once on your machine, then give CI the two values it wrote:
75
-
76
- ```bash
77
- PICKED_PROJECT_ID=your-project-id \
78
- PICKED_PREVIEW_TOKEN=$YOUR_CI_SECRET \
79
- picked generate types --check
80
- ```
81
-
82
- `picked workspace list` and `picked workspace use` read your organizations and projects, so
83
- those two do need a session. Run them on your machine, where a browser can sign you in.
84
-
85
- :::note
86
- This is a developer session for local tooling. It is not the same as an
87
- [API key](/reference/dashboard/api-keys), which authenticates server-to-server delivery and
88
- management calls, or [dashboard sign-in](/reference/management-api/authentication). Use an
89
- API key for an application; use `picked login` for the CLI on your machine.
90
- :::
91
-
92
- ## Related
93
-
94
- - [CLI](/reference/tools/cli) — every command, flag, and environment variable.
95
- - [How to switch workspaces](/how-to/switch-workspaces) — the draft-preview workflow.
96
- - [How to create and revoke an API key](/how-to/create-and-revoke-an-api-key) — credentials
97
- for applications.
@@ -1,40 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to authenticate with a magic link
7
-
8
- This guide shows you how to sign a user in through an email address, with no password.
9
-
10
- ## 1. Send the link
11
-
12
- ```graphql
13
- mutation {
14
- magicLinkSend(input: {
15
- email: "user@example.com"
16
- redirectUrl: "https://app.example.com/auth/verify"
17
- }) {
18
- success
19
- }
20
- }
21
- ```
22
-
23
- The user receives an email, and the link in it holds a token.
24
-
25
- ## 2. Verify the token
26
-
27
- ```graphql
28
- mutation {
29
- magicLinkVerify(input: {
30
- email: "user@example.com"
31
- token: "token-from-magic-link"
32
- }) {
33
- session { accessToken refreshToken }
34
- }
35
- }
36
- ```
37
-
38
- ## Related
39
-
40
- - [Authentication](/reference/management-api/authentication) — every mutation.
@@ -1,51 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to authenticate with a password
7
-
8
- This guide shows you how to get an access token from an email address and a password.
9
-
10
- ## 1. Create a session
11
-
12
- ```graphql
13
- mutation {
14
- sessionCreate(input: {
15
- email: "user@example.com"
16
- password: "secure-password"
17
- }) {
18
- session { accessToken refreshToken expiresAt }
19
- requiresMfa
20
- }
21
- }
22
- ```
23
-
24
- When `requiresMfa` is `true`, complete the challenge first. See
25
- [How to set up MFA](/how-to/set-up-mfa).
26
-
27
- ## 2. Send the token
28
-
29
- ```
30
- Authorization: Bearer <accessToken>
31
- ```
32
-
33
- ## 3. Refresh before it expires
34
-
35
- The `expiresAt` field gives the time at which the access token expires.
36
-
37
- ```graphql
38
- mutation {
39
- sessionRefresh(input: { refreshToken: "v1.refresh-token..." }) {
40
- session { accessToken refreshToken expiresAt }
41
- }
42
- }
43
- ```
44
-
45
- The API invalidates the earlier refresh token. This mutation needs no `Authorization`
46
- header.
47
-
48
- ## Related
49
-
50
- - [Authentication](/reference/management-api/authentication) — every mutation.
51
- - [Your first API call](/tutorials/first-api-call).
@@ -1,51 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to authenticate with an API key
7
-
8
- This guide shows you how to authenticate a server-to-server integration. An API key gives
9
- access for a long time, inside a set of scopes.
10
-
11
- ## 1. Create the key
12
-
13
- Only a user with a session can create a key. Another API key cannot.
14
-
15
- ```graphql
16
- mutation {
17
- apiKeyCreate(input: {
18
- organizationId: "org-id"
19
- name: "CI/CD Pipeline Key"
20
- projectId: "project-id"
21
- scopes: [ORGANIZATION_READ, ORGANIZATION_PROJECTS_READ]
22
- }) {
23
- apiKey
24
- }
25
- }
26
- ```
27
-
28
- The response holds the full key one time only. Keep it in a secure place.
29
-
30
- The scopes that you ask for must all be scopes of the user who creates the key.
31
-
32
- ## 2. Send the key
33
-
34
- ```
35
- x-api-key: pk_live_abc123...
36
- ```
37
-
38
- ## 3. Revoke the key
39
-
40
- ```graphql
41
- mutation {
42
- apiKeyRevoke(input: { keyId: "key-id", organizationId: "org-id" })
43
- }
44
- ```
45
-
46
- ## Related
47
-
48
- - [Authorization and scopes](/reference/management-api/authorization-and-scopes) — every
49
- scope.
50
- - [How to create and revoke an API key](/how-to/create-and-revoke-an-api-key) — the
51
- dashboard path.
@@ -1,40 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to authenticate with OAuth
7
-
8
- This guide shows you how to sign a user in through Google.
9
-
10
- ## 1. Get the authorization URL
11
-
12
- ```graphql
13
- mutation {
14
- oauthAuthorize(input: {
15
- provider: GOOGLE
16
- redirectUrl: "https://app.example.com/auth/callback"
17
- scopes: ["openid", "email", "profile"]
18
- }) {
19
- url
20
- }
21
- }
22
- ```
23
-
24
- ## 2. Send the user to that URL
25
-
26
- Google authenticates the user and sends them back with a `code` parameter.
27
-
28
- ## 3. Exchange the code
29
-
30
- ```graphql
31
- mutation {
32
- oauthCallback(input: { provider: GOOGLE, code: "auth-code-from-google" }) {
33
- session { accessToken refreshToken expiresAt }
34
- }
35
- }
36
- ```
37
-
38
- ## Related
39
-
40
- - [Authentication](/reference/management-api/authentication) — every mutation.