@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,233 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- # Errors
7
-
8
- The Picked API returns an error in the standard GraphQL format. This guide covers the
9
- shape of an error response, every error code, and what your code must do with each
10
- one.
11
-
12
- ## Error response shape
13
-
14
- When an operation fails, the API returns an `errors` array in the response body. Each
15
- error object holds these fields:
16
-
17
- ```json
18
- {
19
- "data": null,
20
- "errors": [
21
- {
22
- "message": "A human-readable description of the error",
23
- "path": ["mutationName"],
24
- "extensions": {
25
- "code": "ERROR_CODE"
26
- }
27
- }
28
- ]
29
- }
30
- ```
31
-
32
- | Field | Description |
33
- |-------|-------------|
34
- | `message` | A description of the error that a person can read. Put it in your log. Do not write code against it. |
35
- | `path` | The path to the field in the query that made the error. |
36
- | `extensions.code` | An error code that a machine can read. Write your code against this field. |
37
-
38
- One response can hold more than one error. The `data` field is `null` when the whole
39
- operation failed. It holds part of the data when only some fields failed.
40
-
41
- ## Authentication error codes
42
-
43
- These errors come from a session, an account, OAuth, a magic link, a password
44
- operation, or MFA. They match the `AuthErrorCode` enum in the schema.
45
-
46
- | Code | Description |
47
- |------|-------------|
48
- | `INVALID_CREDENTIALS` | The email address and the password do not match. |
49
- | `EMAIL_NOT_CONFIRMED` | The account is there, but nobody verified the email address. See [Authentication](/reference/management-api/authentication#the-mutations). |
50
- | `USER_NOT_FOUND` | There is no account with that email address. |
51
- | `USER_ALREADY_EXISTS` | An account with that email address is there already. The API returns this when you create an account. |
52
- | `WEAK_PASSWORD` | The password is not strong enough. |
53
- | `INVALID_TOKEN` | The token is invalid or malformed. This covers a verification token, a reset token, and a magic link token. |
54
- | `TOKEN_EXPIRED` | The token expired. Ask for a new one. |
55
- | `MFA_CHALLENGE_FAILED` | The MFA verification code is not correct. |
56
- | `MFA_FACTOR_NOT_FOUND` | That MFA factor is not there, or it belongs to another caller. |
57
- | `OAUTH_PROVIDER_ERROR` | The exchange with the OAuth provider, such as Google, failed. |
58
- | `RATE_LIMITED` | Too many requests in a short period. Wait, then try again. |
59
-
60
- ### Example: invalid credentials
61
-
62
- ```json
63
- {
64
- "data": {
65
- "sessionCreate": {
66
- "session": null,
67
- "requiresMfa": false,
68
- "mfaFactors": null
69
- }
70
- },
71
- "errors": [
72
- {
73
- "message": "Invalid credentials",
74
- "path": ["sessionCreate"],
75
- "extensions": {
76
- "code": "INVALID_CREDENTIALS"
77
- }
78
- }
79
- ]
80
- }
81
- ```
82
-
83
- ## Authorization error codes
84
-
85
- An authorization error happens when the caller does not hold the
86
- [scope](/reference/management-api/authorization-and-scopes) that an operation needs.
87
-
88
- | Code | Description |
89
- |------|-------------|
90
- | `UNAUTHORIZED` | The request carries no valid authentication. It has no `Authorization` header and no `x-api-key` header, or the token is invalid. |
91
- | `FORBIDDEN` | The caller is authenticated, but it does not hold the scope that the operation needs. |
92
-
93
- ### Example: the scope is not enough
94
-
95
- A caller that holds `organization/read` only tries to delete an organization. It
96
- receives this:
97
-
98
- ```json
99
- {
100
- "data": {
101
- "organizationDelete": null
102
- },
103
- "errors": [
104
- {
105
- "message": "Insufficient permissions",
106
- "path": ["organizationDelete"],
107
- "extensions": {
108
- "code": "FORBIDDEN"
109
- }
110
- }
111
- ]
112
- }
113
- ```
114
-
115
- ## Organization, member, and invitation error codes
116
-
117
- These errors come from an organization, a member operation, or an invitation. They
118
- match the `ErrorCode` enum in the schema.
119
-
120
- ### Organization errors
121
-
122
- | Code | Description |
123
- |------|-------------|
124
- | `ORGANIZATION_NOT_FOUND` | That organization is not there, or the caller cannot reach it. |
125
- | `ORGANIZATION_ALREADY_EXISTS` | An organization with that name is there already. |
126
- | `SLUG_ALREADY_EXISTS` | Another organization uses that slug already. |
127
- | `INVALID_SLUG` | The slug holds an invalid character. A slug takes lowercase letters, digits, and hyphens only. |
128
-
129
- ### Member errors
130
-
131
- | Code | Description |
132
- |------|-------------|
133
- | `MEMBER_NOT_FOUND` | That user is not a member of the organization. |
134
- | `MEMBER_ALREADY_EXISTS` | The user is a member of the organization already. |
135
- | `CANNOT_REMOVE_PRIMARY_OWNER` | You cannot remove the primary owner of an organization. |
136
- | `CANNOT_CHANGE_OWN_ROLE` | A member cannot change the role of that same member. Another owner must do it. |
137
-
138
- ### Invitation errors
139
-
140
- | Code | Description |
141
- |------|-------------|
142
- | `INVITATION_NOT_FOUND` | That invitation is not there. |
143
- | `INVITATION_EXPIRED` | The invitation expired. Nobody can accept it now. |
144
- | `INVITATION_ALREADY_ACCEPTED` | Somebody accepted the invitation already. |
145
-
146
- ### Project errors
147
-
148
- | Code | Description |
149
- |------|-------------|
150
- | `PROJECT_NOT_FOUND` | That project is not there, or the caller cannot reach it. |
151
-
152
- ### General errors
153
-
154
- | Code | Description |
155
- |------|-------------|
156
- | `VALIDATION_ERROR` | The input failed a validation rule. Read the `message` field to learn which field is invalid. |
157
- | `INTERNAL_ERROR` | The server met an unexpected error. Try the request again. Contact support when the error continues. |
158
-
159
- ## What your code must do
160
-
161
- ### Look for an error first
162
-
163
- Check every response for an `errors` array before you read `data`:
164
-
165
- ```javascript
166
- const response = await fetch('/graphql', {
167
- method: 'POST',
168
- headers: {
169
- 'Content-Type': 'application/json',
170
- 'Authorization': `Bearer ${accessToken}`,
171
- },
172
- body: JSON.stringify({ query, variables }),
173
- });
174
-
175
- const result = await response.json();
176
-
177
- if (result.errors) {
178
- for (const error of result.errors) {
179
- const code = error.extensions?.code;
180
-
181
- switch (code) {
182
- case 'UNAUTHORIZED':
183
- // Send the user to the sign-in page.
184
- break;
185
- case 'FORBIDDEN':
186
- // Show a permissions error.
187
- break;
188
- case 'RATE_LIMITED':
189
- // Wait, then try again.
190
- break;
191
- default:
192
- // Put the message in the log, or show it.
193
- console.error(error.message);
194
- }
195
- }
196
- }
197
- ```
198
-
199
- ### Refresh a token that expired
200
-
201
- A request can return `UNAUTHORIZED` while the caller holds a refresh token. Try a
202
- [session refresh](/reference/management-api/authentication#the-mutations) first. Do not treat it as a
203
- failure to sign in:
204
-
205
- ```javascript
206
- if (code === 'UNAUTHORIZED' && refreshToken) {
207
- const refreshResult = await sessionRefresh(refreshToken);
208
- if (refreshResult.session) {
209
- // Try the first request again with the new access token.
210
- } else {
211
- // Send the user to the sign-in page.
212
- }
213
- }
214
- ```
215
-
216
- ### Read data that is only part complete
217
-
218
- GraphQL can return part of the data together with an error. Take a query that reads
219
- an organization and its members. It can succeed for the organization and fail for the
220
- members, when the caller does not hold `organization_members/read`. The response then
221
- holds `data` with the organization, and `errors` for the members field. Always read
222
- both.
223
-
224
- ### Try again after a transient failure
225
-
226
- `INTERNAL_ERROR` and `RATE_LIMITED` are both transient. For `RATE_LIMITED`, use an
227
- exponential backoff before you try again. For `INTERNAL_ERROR`, one more try is
228
- usually enough.
229
-
230
- ## Related
231
-
232
- - [Authentication](/reference/management-api/authentication)
233
- - [Your first API call](/tutorials/first-api-call)
@@ -1,192 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- # Pagination
7
-
8
- The Picked API paginates every list field that can return a large result. It uses a
9
- cursor, in the Relay-style pattern. This guide covers the connection pattern and
10
- shows how to move through a result.
11
-
12
- ## Connection pattern
13
-
14
- A paginated field returns a **connection** object with this shape:
15
-
16
- ```graphql
17
- type ExampleConnection {
18
- edges: [ExampleEdge!]!
19
- pageInfo: PageInfo!
20
- totalCount: Int!
21
- }
22
-
23
- type ExampleEdge {
24
- cursor: String!
25
- node: Example!
26
- }
27
-
28
- type PageInfo {
29
- hasNextPage: Boolean!
30
- hasPreviousPage: Boolean!
31
- startCursor: String
32
- endCursor: String
33
- }
34
- ```
35
-
36
- | Field | Description |
37
- |-------|-------------|
38
- | `edges` | An ordered list of edges. Each edge holds a `cursor` and a `node`, and the `node` holds the data. |
39
- | `pageInfo.hasNextPage` | `true` when more results come after the last edge |
40
- | `pageInfo.hasPreviousPage` | `true` when results come before the first edge |
41
- | `pageInfo.startCursor` | The cursor of the first edge on the current page |
42
- | `pageInfo.endCursor` | The cursor of the last edge on the current page |
43
- | `totalCount` | The number of items on every page together |
44
-
45
- ## Forward pagination with `first` and `after`
46
-
47
- To move forward through the results, use two arguments. The `first` argument gives
48
- the page size. The `after` argument gives the cursor to start after.
49
-
50
- ### First page
51
-
52
- Leave the `after` argument out to read the first page:
53
-
54
- ```graphql
55
- query {
56
- organizations(input: { first: 10 }) {
57
- edges {
58
- cursor
59
- node {
60
- id
61
- name
62
- }
63
- }
64
- pageInfo {
65
- hasNextPage
66
- endCursor
67
- }
68
- totalCount
69
- }
70
- }
71
- ```
72
-
73
- ### Next page
74
-
75
- Pass the `endCursor` from the previous response as the `after` argument:
76
-
77
- ```graphql
78
- query {
79
- organizations(input: { first: 10, after: "cursor_from_previous_page" }) {
80
- edges {
81
- cursor
82
- node {
83
- id
84
- name
85
- }
86
- }
87
- pageInfo {
88
- hasNextPage
89
- endCursor
90
- }
91
- totalCount
92
- }
93
- }
94
- ```
95
-
96
- ## Check for more pages
97
-
98
- Read the `hasNextPage` field before you ask for the next page:
99
-
100
- - `hasNextPage: true` — more results are available. Pass `endCursor` as the `after`
101
- argument of the next request.
102
- - `hasNextPage: false` — you read every result. Stop here.
103
-
104
- ## Full paginated query example
105
-
106
- This example reads every member of an organization, one page at a time:
107
-
108
- ```graphql
109
- # Page 1
110
- query {
111
- organization(input: { slug: "my-company" }) {
112
- members(first: 20) {
113
- edges {
114
- cursor
115
- node {
116
- id
117
- userEmail
118
- role
119
- joinedAt
120
- }
121
- }
122
- pageInfo {
123
- hasNextPage
124
- endCursor
125
- }
126
- totalCount
127
- }
128
- }
129
- }
130
- ```
131
-
132
- If `pageInfo.hasNextPage` is `true`, fetch the next page:
133
-
134
- ```graphql
135
- # Page 2
136
- query {
137
- organization(input: { slug: "my-company" }) {
138
- members(first: 20, after: "cursor_from_page_1") {
139
- edges {
140
- cursor
141
- node {
142
- id
143
- userEmail
144
- role
145
- joinedAt
146
- }
147
- }
148
- pageInfo {
149
- hasNextPage
150
- endCursor
151
- }
152
- totalCount
153
- }
154
- }
155
- }
156
- ```
157
-
158
- Continue until `hasNextPage` returns `false`.
159
-
160
- ## Paginated fields
161
-
162
- These fields in the schema return a connection type. They all take the `first` and
163
- `after` arguments:
164
-
165
- | Parent Type | Field | Connection Type |
166
- |------------|-------|----------------|
167
- | `Query` | `organizations` | `OrganizationConnection` |
168
- | `User` | `organizations` | `OrganizationConnection` |
169
- | `User` | `invitations` | `ViewerInvitationConnection` |
170
- | `Organization` | `members` | `OrganizationMemberConnection` |
171
- | `Organization` | `invitations` | `OrganizationInvitationConnection` |
172
- | `Organization` | `projects` | `ProjectConnection` |
173
- | `Project` | `reports` | `ProjectReportConnection` |
174
-
175
- All of these fields accept the same `first` and `after` arguments and return the standard `edges`, `pageInfo`, and `totalCount` structure.
176
-
177
- ## Tips
178
-
179
- - **The default page size** — the API applies a default limit when you leave `first`
180
- out. Set `first` yourself to make sure that each page has the size you expect.
181
- - **A cursor is opaque** — treat a cursor string as an opaque token. Do not parse it,
182
- build it, or change it. Pass it back exactly as the API gave it.
183
- - **The order is stable** — a connection returns its results in a stable order. The
184
- same cursor always points at the same position in the result.
185
- - **Use them with other fields** — you can use the pagination arguments together with
186
- other query fields. One request that reads an organization and the first page of
187
- its members is common, and it is efficient.
188
-
189
- ## Related
190
-
191
- - [Your first API call](/tutorials/first-api-call)
192
- - [Authorization and scopes](/reference/management-api/authorization-and-scopes)
@@ -1,174 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- # Data sources
7
-
8
- PickedQL gives you four virtual tables. Each table is fast for one kind of work. It also gives you three reference tables, and those hold the options of your
9
- Picked project.
10
-
11
- ## `metrics` — data that PickedQL aggregates each day
12
-
13
- Use it for a dashboard and to study a trend. There is one row for each unique set of
14
- dimensions on each day. The dimension columns are there directly, and they need no
15
- join. Examples are `device_category`, `country_code`, and `utm_source`.
16
-
17
- ```sql
18
- SELECT device_category, control_users(), variant_users()
19
- FROM metrics
20
- WHERE project_id = 'your-project-id'
21
- GROUP BY device_category
22
- ```
23
-
24
- ## `events` — one row for each event of each user
25
-
26
- Use it for a deep study, for a funnel, and for a breakdown of your own. There is one
27
- row for each event of each user. PickedQL joins a dimension column, such as
28
- `device_category` or `country_code`, when you point at it.
29
-
30
- ```sql
31
- SELECT user_canonical_id, device_category
32
- FROM events
33
- WHERE project_id = 'your-project-id'
34
- AND variant_type = 'Control'
35
- ```
36
-
37
- ## `features` — one row for each feature flag
38
-
39
- Use it to count the users, the sessions, and the events for each feature flag and
40
- bucket. It uses parameterized functions.
41
-
42
- ```sql
43
- SELECT feature_users('homepage_test', 'control')
44
- FROM features
45
- WHERE project_id = 'your-project-id'
46
- ```
47
-
48
- ## `experience_journey` — step transitions for a sankey chart
49
-
50
- It returns one `source, target, users` row for each edge. You can put those rows
51
- directly into a sankey chart or a funnel chart. It holds the eight common table
52
- expressions that a card carried before. Those call `lagInFrame`, remove a duplicate
53
- between two steps that follow each other, and rank the top paths.
54
-
55
- Every filter goes in the **outer `WHERE`** clause. PickedQL reads each one as a
56
- parameter and puts it into the query below. Only `project_id` is necessary. The rest
57
- are optional, and each has a sensible default.
58
-
59
- | Parameter, as a WHERE key | What it does |
60
- |---|---|
61
- | `project_id` | The tenant filter. It is necessary. |
62
- | `experience_id` | Limits the rows to one `fact_events.experience_id`. |
63
- | `starting_step` | Anchors each edge at the first time that a user reaches this `step_id`. With no value, it anchors at the first `step_enter` event of that user. |
64
- | `targeting_step` | Trims the window of each user at the first time that the user reaches this `step_id`. A user who never reaches it still gives a journey, up to `num_nodes_after_start`. |
65
- | `num_nodes_after_start` | The size of the forward window from the start step. |
66
- | `num_nodes_before_target` | The size of the backward window from the target step. It needs `targeting_step`. |
67
- | `top_n_path` | Keeps the paths with the most users, and drops the rest. |
68
- | `user_cohort_event` | Limits the rows to a user with at least one `fact_events` row of this `event_type`, such as `'lead_capture'`. Use it for the paths of the users who reached a goal. |
69
- | `client_local_date` | A filter on the date. It takes `=`, `<`, `<=`, `>`, `>=`, and `BETWEEN`. PickedQL puts it into the `fact_events` read below. |
70
- | `event_timestamp` | A filter on the timestamp from the server. It takes the same operators as `client_local_date`. |
71
-
72
- When you set both `num_nodes_after_start` and `num_nodes_before_target`, both tests
73
- apply. The result is the intersection of the two.
74
-
75
- ```sql
76
- -- The "overall user journey" sankey.
77
- -- It uses a forward window. The target step is optional.
78
- SELECT source, target, users FROM experience_journey
79
- WHERE project_id = 'your-project-id'
80
- AND starting_step = 'step-start'
81
- AND targeting_step = 'step-target'
82
- AND num_nodes_after_start = 10
83
- AND client_local_date >= '2026-04-01' -- An optional range of dates.
84
- AND client_local_date <= '2026-04-30'
85
- ```
86
-
87
- ```sql
88
- -- The "paths to a target" sankey.
89
- -- It uses a backward window and it ranks the top paths.
90
- SELECT source, target, users FROM experience_journey
91
- WHERE project_id = 'your-project-id'
92
- AND experience_id = 'exp-123'
93
- AND starting_step = 'step-start'
94
- AND targeting_step = 'step-target'
95
- AND num_nodes_before_target = 5
96
- AND top_n_path = 10
97
- ```
98
-
99
- ```sql
100
- -- The "drop-off" sankey. Leave the target step out.
101
- SELECT source, target, users FROM experience_journey
102
- WHERE project_id = 'your-project-id'
103
- AND experience_id = 'exp-123'
104
- AND starting_step = 'step-start'
105
- AND num_nodes_after_start = 10
106
- ```
107
-
108
- ```sql
109
- -- A cohort sankey. It holds the users who reached the goal only.
110
- SELECT source, target, users FROM experience_journey
111
- WHERE project_id = 'your-project-id'
112
- AND starting_step = 'step-start'
113
- AND targeting_step = 'step-target'
114
- AND num_nodes_after_start = 10
115
- AND user_cohort_event = 'lead_capture' -- Users with one or more of these events.
116
- ```
117
-
118
- The columns that it returns:
119
-
120
- | Column | Type | Description |
121
- |---|---|---|
122
- | `source` | String | The start of the edge, in the form `NN. <step title>`, such as `001. Welcome screen`. PickedQL joins `steps` to find the title. |
123
- | `target` | String | The end of the edge, in the form `NN. <step title>`. |
124
- | `users` | `UInt64` | The number of different `user_canonical_id` values that went along this edge. |
125
-
126
- :::note
127
- `experience_journey` returns data that PickedQL aggregates first. It does **not**
128
- support a dimension filter such as `variant_type`, `device_category`, or
129
- `country_code`. To use one of those, query
130
- [`events`](#events--one-row-for-each-event-of-each-user) directly and build the
131
- transitions yourself.
132
- :::
133
-
134
- ## Reference tables — `steps`, `experiences`, `projects`
135
-
136
- These reference tables hold the configuration of your Picked project. They have two uses:
137
-
138
- - **PickedQL joins them onto `events`** when you point at one of their analyst
139
- columns: `step_title`, `experience_title`, `project_name`, or `project_timezone`.
140
- - **You can read them directly.** Each one then needs its own tenant filter, so that
141
- you see only the rows of a project that you can reach.
142
-
143
- | Source | The tenant filter that it needs |
144
- |---|---|
145
- | `steps` | `WHERE project_id = '<project_id>'` |
146
- | `experiences` | `WHERE project_id = '<project_id>'` |
147
- | `projects` | `WHERE id = '<project_id>'` |
148
-
149
- ```sql
150
- -- A direct query that reads the experiences of a project.
151
- SELECT id, title FROM experiences WHERE project_id = 'your-project-id'
152
-
153
- -- A direct query that reads the metadata of one project.
154
- SELECT id, name, timezone FROM projects WHERE id = 'your-project-id'
155
- ```
156
-
157
- ```sql
158
- -- Pointed at from events. PickedQL adds each LEFT JOIN for you.
159
- -- The reference tables need no separate tenant filter, because
160
- -- the event table already limits the join.
161
- SELECT experience_title, step_title, count(*)
162
- FROM events
163
- WHERE project_id = 'your-project-id'
164
- GROUP BY experience_title, step_title
165
- ```
166
-
167
- See [Schema, reference tables](/reference/pickedql/schema#steps-experiences-projects) for the full
168
- column list and the join keys.
169
-
170
- ## Related
171
-
172
- - [About PickedQL](/explanation/how-pickedql-works) — what the layer expands for you.
173
- - [Schema](/reference/pickedql/schema)
174
- - [Analytics queries](/how-to/analytics)
@@ -1,103 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- # Dimension columns
7
-
8
- Every data source has dimension columns. The `metrics` table holds them directly. On
9
- `events` and on `features`, PickedQL adds the `LEFT JOIN` that it needs when you
10
- point at one. You write no join.
11
-
12
- ## The dimensions
13
-
14
- | Source | Columns |
15
- |---|---|
16
- | `dim_variant` | `variant_type`, `ab_feature_name`, `ab_feature_value` |
17
- | `dim_device` | `device_category`, `browser_name`, `browser_version`, `os_name`, `os_version`, `platform` |
18
- | `dim_geo` | `country_code`, `country_name`, `region`, `city` |
19
- | `dim_utm` | `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` |
20
- | `dim_product` | `product_name`, `product_category`, `product_page` |
21
- | `steps` | `step_title` |
22
- | `experiences` | `experience_title` |
23
- | `projects` | `project_name`, `project_timezone` |
24
-
25
- :::warning
26
- `dim_variant` describes whether the visitor is a known user. It does **not** hold the variants
27
- of your feature flags. To count the visitors in one variant, use
28
- [`feature_users`](/reference/pickedql/virtual-functions#feature-functions-on-features-and-on-events).
29
- :::
30
-
31
- The `steps`, `experiences`, and `projects` sources are reference tables, and they come
32
- from the operational database. PickedQL joins them onto `events` and `fact_events`
33
- when you point at one of their analyst-facing columns. Each one **also** needs its own
34
- tenant filter when you query it directly:
35
-
36
- | Source | The tenant filter that it needs |
37
- |---|---|
38
- | `steps`, `experiences` | `WHERE project_id = '<project_id>'` |
39
- | `projects` | `WHERE id = '<project_id>'`, because the `id` of the row is the project ID |
40
-
41
- PickedQL also puts a tenant equality in the `ON` clause of each join that it adds.
42
- Examples are `AND st.project_id = '<project_id>'` and `AND pr.id = '<project_id>'`.
43
- ClickHouse then reads part of the dimension table and not all of it. PickedQL puts
44
- the test in `ON` and not in `WHERE`, because a test in `WHERE` would change a
45
- `LEFT JOIN` into an inner join.
46
-
47
- Each analyst-facing column name carries a prefix, such as `step_title` and
48
- `project_name`. The prefix stops a collision between two sources. Both `steps.title`
49
- and `experiences.title` are there, and you point at them as `step_title` and
50
- `experience_title`.
51
-
52
- ```sql
53
- -- Group the events by experience and by step name.
54
- -- PickedQL joins both `experiences` and `steps` for you.
55
- SELECT experience_title, step_title, count(*)
56
- FROM events
57
- WHERE project_id = 'your-project-id'
58
- GROUP BY experience_title, step_title
59
- ```
60
-
61
- An automatic join also works inside a subquery and inside a common table expression.
62
- Point at a dimension column where you need it, and PickedQL adds the `LEFT JOIN` at
63
- that level:
64
-
65
- ```sql
66
- -- Dimension columns inside a common table expression.
67
- WITH per_step AS (
68
- SELECT step_title, count(*) AS n
69
- FROM events
70
- WHERE project_id = 'your-project-id'
71
- GROUP BY step_title
72
- )
73
- SELECT * FROM per_step ORDER BY n DESC
74
-
75
- -- Dimension columns inside a nested query.
76
- SELECT step_title, n FROM (
77
- SELECT step_title, count(*) AS n FROM events
78
- WHERE project_id = 'your-project-id'
79
- GROUP BY step_title
80
- ) sub
81
- ```
82
-
83
- ## Native event columns
84
-
85
- These columns are on `events` directly, and they need no join:
86
-
87
- `event_type`, `interaction_type`, `experience_id`, `step_id`, `event_id`, `user_canonical_id`, `session_id`, `client_local_date`, `is_purchase`, `is_cart_add`, `event_meta`.
88
-
89
- Two of them take a name from the SDK. A filter on a name that does not exist gives an
90
- empty result set and not an error:
91
-
92
- | Column | The values that it holds |
93
- |---|---|
94
- | `event_type` | The name of the event, such as `step_enter` or `cart_add`. [Analytics events](/reference/sdk/analytics-events) names every one, together with the name of each custom event of your own. |
95
- | `interaction_type` | The label of the element behind the event. It falls back to `event_type` when the event has no element, so it is **not** the list of interaction types. [Analytics events](/reference/sdk/analytics-events) describes both. |
96
-
97
- ## Related
98
-
99
- - [About PickedQL](/explanation/how-pickedql-works) — why you write no join.
100
- - [Data sources](/reference/pickedql/data-sources)
101
- - [Analytics events](/reference/sdk/analytics-events) — every `event_type` value, and the
102
- contexts behind these columns.
103
- - [Analytics queries](/how-to/analytics)