@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,181 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- # Glossary
7
-
8
- Every term that Picked uses, and what each one means. The dashboard, the API, and the SDK
9
- sometimes use different words for the same thing. This page gives the word that the
10
- documentation uses, and it names the others.
11
-
12
- ## Accounts and access
13
-
14
- | Term | What it is |
15
- | --- | --- |
16
- | **Organization** | The top level. It holds your projects, your members, and your settings. You can belong to more than one. |
17
- | **Member** | A person in an organization. Each member holds one role. |
18
- | **Role** | What a member can reach. It decides whether a member can create a project, edit an experience, or read a report. |
19
- | **API key** | A credential for a server-to-server integration. It belongs to an organization, it can belong to one project, and it carries scopes. |
20
- | **Scope** | One permission, written `resource/action`, such as `organization/read`. A scope decides which operations a caller can do. |
21
- | **Session** | The result of a sign-in. It holds an access token, a refresh token, and the time at which the access token expires. |
22
- | **User** | A person who signs in to the Picked dashboard. A user is not a visitor. |
23
- | **Invitation** | An offer to join an organization, sent to an email address. It waits until the person accepts it. |
24
- | **MFA factor** | A second credential on an account, such as a telephone number. |
25
-
26
- ## Projects and versions
27
-
28
- | Term | What it is |
29
- | --- | --- |
30
- | **Project** | One site or one application. Each project has its own experiences, content, and configuration. |
31
- | **Project configuration** | The published settings of a project: its experiences and steps, and the content link on each step. The Delivery API serves it, and the SDK reads it. The SDK parameter is `projectConfig`. |
32
- | **Workspace** | One version of the configuration of a project. You hold a change in a workspace, see a preview of it, and publish it. |
33
- | **Draft** | A workspace that no visitor sees. |
34
- | **Live** | The workspace whose snapshot the SDK serves. Each project has exactly one. |
35
- | **Archived** | A draft that you put to one side. It is still editable, and it is out of the default list. |
36
- | **Version** | An immutable snapshot of a workspace, made when you publish. The **Publish history** page lists them. |
37
- | **Preview** | A view of an unpublished workspace on your own site. It reaches your browser only. |
38
- | **Preview environment** | A named target that a preview opens against. |
39
- | **Project settings** | The settings of one project, which you edit in the dashboard. These are not the project configuration that the Delivery API serves. |
40
-
41
- ## Experiences
42
-
43
- | Term | What it is |
44
- | --- | --- |
45
- | **Experience** | Personalized content that Picked serves to a visitor. It is a Flow or a Page. |
46
- | **Flow** | An interactive experience of more than one step, which the browser renders. |
47
- | **Page** | A standalone experience that your server renders from a content entry, for content that a search engine must read. |
48
- | **Step** | One screen that a visitor sees. It holds fields. |
49
- | **Field** | A data input inside a step. It collects a name, an email address, a preference, or a choice. |
50
- | **Field option** | One choice in a field that has a fixed set of choices. Each option carries a value, and it can carry a condition. |
51
- | **Action** | A side effect that starts when the flow reaches it. Your application registers a handler for it. |
52
- | **Condition** | A rule that decides whether a visitor sees something, or which branch a flow takes. |
53
- | **Predicate** | A function that you register on the client, so a condition can read data that only your application holds. |
54
- | **Response** | A value that a visitor sends through a field. |
55
- | **Origin** | The node where every flow starts. |
56
- | **Node** | One part of a flow on the canvas: an origin, a step, an action, or a condition. |
57
- | **Handle** | A connection point on a node. An input handle is on the left, an output handle on the right. |
58
- | **Key** | The stable identifier of a step, a field, an action, or a condition. Your application and your API calls both use it. You set it one time, and you cannot change it. |
59
- | **Layout name** | The name of the component that renders a step, such as `card` or `modal`. |
60
- | **Target** | The element that an experience renders against, found by its target selector. |
61
-
62
- ## Feature flags
63
-
64
- | Term | What it is |
65
- | --- | --- |
66
- | **Feature flag** | A control that decides which visitors see a change, so you can run an A/B test or release in stages. The API type is `Feature`. |
67
- | **Weight** | The percentage of visitors that Picked allocates to a feature flag, from 0 to 100. |
68
- | **Allocation** | The act that puts a visitor in a feature flag. It happens when something first reads the bucket. |
69
- | **Bucket** | The value a feature flag resolves to for one visitor. |
70
- | **Exposure** | The moment a visitor enters a test. It is the same moment as the allocation. |
71
- | **Version** | A number on a feature flag that forms part of the cache key. It is not part of the allocation. |
72
-
73
- ## Content
74
-
75
- | Term | What it is |
76
- | --- | --- |
77
- | **Model** | A reusable schema that sets which fields a piece of content can hold. The API type is `ContentModel`. The dashboard lists them under **CMS**, at **Models**. |
78
- | **Block** | A reusable schema fragment that you put inside one or more Models. The API type is `ContentBlock`. The dashboard lists them under **CMS**, at **Blocks**. |
79
- | **Content entry** | One instance of a Model, filled with real values. The dashboard lists them under **CMS**, at **Content entries**. |
80
- | **Category** | The role of a Model or a Block. It is fixed when you create the record. |
81
- | **Page layout** | A Model with the Page layout category. It sets which fields a Page can hold. |
82
- | **Step layout** | A Model with the Step layout category. It sets which fields one Step inside a Flow can hold. |
83
- | **Section** | A Block with the Section category. A **Page Sections** field accepts it. |
84
- | **General content** | A Model or a Block with no category. It has no layout role, and nothing renders its entries directly. |
85
- | **Reference** | A field that points one content entry at another. The pointer holds the id of the target, and not a copy of it. |
86
- | **Target Model** | The Model whose entries a Reference field accepts. It holds a Key. **Any Model** sets no limit. |
87
- | **Entry title** | The name that the entries list shows. It is the first single-line text field of the entry, and it falls back to the entry id. |
88
- | **Asset** | A file that your content points at: an image, a video, a document, or HTML. |
89
- | **Asset library** | The project-level store that holds your assets. |
90
- | **Design system** | A set of shared design decisions for a project. |
91
- | **Content schema** | The set of fields that a Model or a Block defines. |
92
- | **Asset version** | One file that somebody uploaded for an asset. The library keeps the earlier versions. |
93
- | **Validation error** | A report that one field in a content entry does not match its schema. It carries the path to the exact field. |
94
-
95
- ## The SDK
96
-
97
- | Term | What it is |
98
- | --- | --- |
99
- | **Client** | The object that `createClient()` returns. It holds your configuration and runs the experiences. |
100
- | **Plugin** | A piece of behaviour that you pass to the `plugins` array of the client. |
101
- | **Component name** | The identifier that points an experience at a component in your application. |
102
- | **Adapter** | The function that lets the client render a framework component: `adaptReactComponent` or `adaptSvelteComponent`. |
103
- | **Slot** | A named mount point, rendered by `<ExperienceSlot name="…" />`. It maps to the `.picked-slot-<name>` selector. |
104
- | **Placement** | Where an experience renders against its target: `replace`, `before`, `prepend`, `append`, or `after`. |
105
- | **Target selector** | The selector that an experience renders into. |
106
- | **Content index** | The store of every content record that the client holds, keyed by id. `useContent(id)` and `useReference()` read it. |
107
- | **Snapshot** | The plain JSON that `serialize()` returns on your server, and that seeds the client in the browser. |
108
- | **Precondition** | A gate that decides whether Picked starts at all. |
109
- | **Visitor** | The person on your site. Picked gives each one a stable ID. A visitor is not a user. |
110
- | **Framework plugin** | The plugin that lets the client render a React or a Svelte component. |
111
-
112
- ## APIs and analytics
113
-
114
- | Term | What it is |
115
- | --- | --- |
116
- | **Delivery API** | The public, anonymous, read-only REST API that serves your published configuration and content. |
117
- | **Management API** | The authenticated GraphQL API that controls your projects, experiences, and content. |
118
- | **Preview token** | A token that lets a Delivery API request read unpublished content. |
119
- | **PickedQL** | The SQL query language for your Picked analytics data. |
120
- | **Virtual table** | A table name in PickedQL, such as `metrics`, that maps to the real tables below it. |
121
- | **Virtual function** | A short function in PickedQL, such as `control_users()`, that expands to a full aggregate expression. |
122
- | **Dimension** | A column that PickedQL joins for you, such as `device_category`. |
123
- | **Report** | An embedded analytics dashboard or question, attached to a project. |
124
-
125
- ## Tools
126
-
127
- | Term | What it is |
128
- | --- | --- |
129
- | **MCP connection** | A link between a Picked project and an AI tool, over the Model Context Protocol. The dashboard calls this **MCP connections**. |
130
- | **Integration** | A connection between Picked and another service. |
131
- | **Tag ID** | The identifier of a project, which the template for Google Tag Manager uses. |
132
-
133
- ## Verbs
134
-
135
- The actions that Picked names, and what each one does. Where an API mutation uses the
136
- word exactly, the table says so.
137
-
138
- ### You act on the dashboard
139
-
140
- | Verb | What it does |
141
- | --- | --- |
142
- | **Create** | Makes a new record. |
143
- | **Update** | Changes a record that exists. |
144
- | **Delete** | Removes a record permanently. You cannot reverse it. |
145
- | **Publish** | Makes an immutable snapshot of a workspace and serves it to your visitors. |
146
- | **Archive** | Moves a draft workspace out of the default list. It stays editable. |
147
- | **Unarchive** | Returns an archived workspace to the default list. |
148
- | **Duplicate** | Copies a workspace, and everything in it, into a new draft. |
149
- | **Restore** | Moves the live pointer of a project to an earlier version. It changes no data. |
150
- | **Preview** | Opens your site with an unpublished workspace applied, for your browser only. |
151
- | **Invite** | Sends an invitation to join an organization. |
152
- | **Revoke** | Invalidates an API key or an invitation immediately. |
153
- | **Install** | Connects an integration to your project. |
154
-
155
- ### Picked acts on a visitor
156
-
157
- | Verb | What it does |
158
- | --- | --- |
159
- | **Allocate** | Puts a visitor in a feature flag. |
160
- | **Resolve** | Gives a feature flag its bucket for one visitor. The first read resolves it. |
161
- | **Decide** | Runs the `decide` function of a feature flag. |
162
- | **Evaluate** | Runs a condition against the current state. |
163
- | **Invoke** | Calls a predicate from inside a condition. |
164
- | **Serve** | Sends published content to a visitor. |
165
-
166
- ### Your code acts on the SDK
167
-
168
- | Verb | What it does |
169
- | --- | --- |
170
- | **Register** | Adds a component, an action, a predicate, or a feature flag to the client. |
171
- | **Start** | Runs the client. `start()` is idempotent. |
172
- | **Adapt** | Wraps a framework component so the client can render it. |
173
- | **Serialize** | Builds a snapshot on your server, with `serialize()`. |
174
- | **Seed** | Gives the client a snapshot, so the first render matches the server. |
175
- | **Hydrate** | Takes over the server markup in the browser. |
176
- | **Render** | Puts a component into the page. |
177
-
178
- ## Related
179
-
180
- - [About how Picked works](/explanation/how-picked-works) — how these parts fit together.
181
- - [Projects](/reference/dashboard/projects) — the dashboard surface.
@@ -1,74 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- # Authentication
7
-
8
- The Picked API supports four ways to authenticate. They are a session from an email
9
- address and a password, an OAuth provider, a magic link, and an API key. This guide
10
- covers each one. It also covers how to control a session and how to use multi-factor
11
- authentication (MFA).
12
-
13
- ## Use a session
14
-
15
- After the caller has a session, it puts the access token in the `Authorization`
16
- header of every request that needs authentication:
17
-
18
- ```
19
- Authorization: Bearer <accessToken>
20
- ```
21
-
22
- The `expiresAt` field of the session gives the time at which the access token
23
- expires. The caller must refresh the session before that time.
24
-
25
- ### Authenticator assurance levels
26
-
27
- The session holds an `aal` field, and it gives the strength of the authentication:
28
-
29
- | Level | Meaning |
30
- |-------|---------|
31
- | `AAL1` | One factor: an email address and a password, OAuth, or a magic link |
32
- | `AAL2` | More than one factor: the user completed an MFA challenge |
33
-
34
- Some operations need `AAL2`. When a caller at `AAL1` tries one of them, the API
35
- returns an authorization error.
36
-
37
- ## The mutations
38
-
39
- | Mutation | What it does |
40
- | --- | --- |
41
- | `sessionCreate` | Authenticates an email address and a password. Returns a session, or `requiresMfa`. |
42
- | `sessionRefresh` | Exchanges a refresh token for a new session. Needs no `Authorization` header. |
43
- | `accountCreate` | Creates an account. `metadata` takes any JSON. |
44
- | `accountVerifyEmail` | Completes email verification with the token from the email. |
45
- | `accountResendVerification` | Sends the verification email again. |
46
- | `oauthAuthorize` | Returns the authorization URL for a provider. Google is supported. |
47
- | `oauthCallback` | Exchanges an OAuth code for a session. |
48
- | `magicLinkSend` | Sends a sign-in link to an email address. |
49
- | `magicLinkVerify` | Exchanges a magic-link token for a session. |
50
- | `passwordResetSend` | Sends a password reset email. |
51
- | `passwordReset` | Completes a reset with the token from the email. |
52
- | `passwordUpdate` | Changes a password. Needs authentication. |
53
- | `mfaFactorEnroll` | Adds an MFA factor. A new factor is `UNVERIFIED`. |
54
- | `mfaChallengeSend` | Sends a code to the telephone number of the factor. |
55
- | `mfaChallengeVerify` | Verifies a challenge. Moves the session to `AAL2`. |
56
- | `mfaFactorUnenroll` | Removes an MFA factor. |
57
- | `apiKeyCreate` | Creates an API key. Only a user with a session can call it. |
58
- | `apiKeyRevoke` | Invalidates a key immediately. |
59
-
60
- ## Credentials
61
-
62
- | Credential | Header |
63
- | --- | --- |
64
- | Session access token | `Authorization: Bearer <accessToken>` |
65
- | API key | `x-api-key: pk_live_abc123...` |
66
-
67
- ## Related
68
-
69
- - [How to authenticate with a password](/how-to/authenticate-with-a-password)
70
- - [How to authenticate with OAuth](/how-to/authenticate-with-oauth)
71
- - [How to authenticate with a magic link](/how-to/authenticate-with-a-magic-link)
72
- - [How to set up MFA](/how-to/set-up-mfa)
73
- - [How to authenticate with an API key](/how-to/authenticate-with-an-api-key)
74
- - [Authorization and scopes](/reference/management-api/authorization-and-scopes)
@@ -1,285 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- # Authorization and scopes
7
-
8
- The Picked API controls access with scopes. Every authenticated caller carries a set
9
- of scopes, and those scopes decide which operations the caller can do. A caller is
10
- either a user with a session or an API key. This guide covers the scopes, the roles,
11
- and how the API resolves a permission.
12
-
13
- ## The format of a scope name
14
-
15
- A scope has the form `resource/action`:
16
-
17
- ```
18
- organization/read
19
- organization_members/create
20
- organization_projects/delete
21
- ```
22
-
23
- - **resource** — a lowercase name. It uses an underscore between words, as in
24
- `organization_members` and `organization_api_keys`.
25
- - **action** — one of `create`, `read`, `update`, or `delete`.
26
-
27
- The GraphQL schema holds the scopes in the `Scope` enum. There they are uppercase
28
- with an underscore between words, as in `ORGANIZATION_READ` and
29
- `ORGANIZATION_MEMBERS_CREATE`. The two forms name the same scope.
30
-
31
- ## Full scope list
32
-
33
- These are the scopes:
34
-
35
- ### Organization
36
-
37
- | Scope | GraphQL Enum | Description |
38
- |-------|-------------|-------------|
39
- | `organization/create` | `ORGANIZATION_CREATE` | Create an organization |
40
- | `organization/read` | `ORGANIZATION_READ` | Read the detail of an organization |
41
- | `organization/update` | `ORGANIZATION_UPDATE` | Update the name, the slug, and the settings of an organization |
42
- | `organization/delete` | `ORGANIZATION_DELETE` | Delete an organization |
43
-
44
- ### Organization members
45
-
46
- | Scope | GraphQL Enum | Description |
47
- |-------|-------------|-------------|
48
- | `organization_members/create` | `ORGANIZATION_MEMBERS_CREATE` | Add a member to an organization |
49
- | `organization_members/read` | `ORGANIZATION_MEMBERS_READ` | Read the member list of an organization |
50
- | `organization_members/update` | `ORGANIZATION_MEMBERS_UPDATE` | Update the role of a member |
51
- | `organization_members/delete` | `ORGANIZATION_MEMBERS_DELETE` | Remove a member from an organization |
52
-
53
- ### Organization invitations
54
-
55
- | Scope | GraphQL Enum | Description |
56
- |-------|-------------|-------------|
57
- | `organization_invitations/create` | `ORGANIZATION_INVITATIONS_CREATE` | Send an invitation to join an organization |
58
- | `organization_invitations/read` | `ORGANIZATION_INVITATIONS_READ` | Read the invitations that wait for an answer |
59
- | `organization_invitations/delete` | `ORGANIZATION_INVITATIONS_DELETE` | Revoke an invitation that waits for an answer |
60
-
61
- ### Organization projects
62
-
63
- | Scope | GraphQL Enum | Description |
64
- |-------|-------------|-------------|
65
- | `organization_projects/create` | `ORGANIZATION_PROJECTS_CREATE` | Create a project |
66
- | `organization_projects/read` | `ORGANIZATION_PROJECTS_READ` | Read the detail of a project |
67
- | `organization_projects/update` | `ORGANIZATION_PROJECTS_UPDATE` | Update the settings of a project |
68
- | `organization_projects/delete` | `ORGANIZATION_PROJECTS_DELETE` | Delete a project |
69
-
70
- ### Organization API keys
71
-
72
- | Scope | GraphQL Enum | Description |
73
- |-------|-------------|-------------|
74
- | `organization_api_keys/create` | `ORGANIZATION_API_KEYS_CREATE` | Create an API key |
75
- | `organization_api_keys/read` | `ORGANIZATION_API_KEYS_READ` | Read the API keys. This gives the prefix only, and not the full key. |
76
- | `organization_api_keys/delete` | `ORGANIZATION_API_KEYS_DELETE` | Revoke an API key |
77
-
78
- ### Organization integrations
79
-
80
- | Scope | GraphQL Enum | Description |
81
- |-------|-------------|-------------|
82
- | `organization_integrations/create` | `ORGANIZATION_INTEGRATIONS_CREATE` | Set up an integration |
83
- | `organization_integrations/read` | `ORGANIZATION_INTEGRATIONS_READ` | Read the options of an integration |
84
- | `organization_integrations/update` | `ORGANIZATION_INTEGRATIONS_UPDATE` | Change the settings of an integration |
85
- | `organization_integrations/delete` | `ORGANIZATION_INTEGRATIONS_DELETE` | Remove an integration |
86
-
87
- ### Organization reports
88
-
89
- | Scope | GraphQL Enum | Description |
90
- |-------|-------------|-------------|
91
- | `organization_reports/create` | `ORGANIZATION_REPORTS_CREATE` | Create a report |
92
- | `organization_reports/read` | `ORGANIZATION_REPORTS_READ` | Read a report |
93
- | `organization_reports/update` | `ORGANIZATION_REPORTS_UPDATE` | Update the settings of a report |
94
- | `organization_reports/delete` | `ORGANIZATION_REPORTS_DELETE` | Delete a report |
95
-
96
- ## Roles
97
-
98
- Each member of an organization holds one of two roles:
99
-
100
- ### Owner
101
-
102
- An owner has full control inside the organization. These are the default scopes of an
103
- owner:
104
-
105
- - All `organization/*` scopes (`read`, `update`, `delete`)
106
- - All `organization_members/*` scopes
107
- - All `organization_invitations/*` scopes
108
- - `organization_projects/read`, `organization_projects/update`, `organization_projects/delete`
109
- - All `organization_api_keys/*` scopes
110
- - All `organization_integrations/*` scopes
111
- - `organization_reports/read`
112
-
113
- ### Member
114
-
115
- A member can reach most things, but cannot delete the organization and cannot control
116
- another member. These are the default scopes of a member:
117
-
118
- - `organization/read`, `organization/update`
119
- - `organization_members/read`
120
- - `organization_invitations/read`
121
- - `organization_projects/read`, `organization_projects/update`, `organization_projects/delete`
122
- - All `organization_api_keys/*` scopes
123
- - All `organization_integrations/*` scopes
124
- - `organization_reports/read`
125
-
126
- These are the differences between an owner and a member:
127
-
128
- | Capability | Owner | Member |
129
- |-----------|-------|--------|
130
- | Delete the organization | Yes | No |
131
- | Invite new members | Yes | No |
132
- | Remove members | Yes | No |
133
- | Update member roles | Yes | No |
134
- | Revoke invitations | Yes | No |
135
- | Control projects and integrations | Yes | Yes |
136
- | Control API keys | Yes | Yes |
137
- | Read reports | Yes | Yes |
138
-
139
- ## How scopes are resolved
140
-
141
- When an authenticated request reaches the API, the API resolves the scopes like this:
142
-
143
- 1. **A user with a session** — the API finds the role of that caller in the target
144
- organization. It then gives the caller the default scopes of that role.
145
- 2. **A request with an API key** — the API uses the scopes that the key received when
146
- somebody created it. Those scopes are always scopes of the user who created the
147
- key.
148
-
149
- Most queries and mutations point at one organization. For those, the caller must hold
150
- the scope inside that organization. For a root-level operation such as
151
- `organizationCreate`, the API resolves the scope at the account level.
152
-
153
- When the caller does not hold the scope that an operation needs, the API returns an
154
- authorization error with the code `FORBIDDEN`. See [Errors](/reference/management-api/error-handling).
155
-
156
- ## Operations and required scopes
157
-
158
- This table gives the scope that each common operation needs:
159
-
160
- ### Queries
161
-
162
- | Query | Required Scope |
163
- |-------|---------------|
164
- | `organization` | `organization/read` |
165
- | `organizations` | `organization/read` |
166
- | `project` | `organization_projects/read` |
167
- | `apiKeys` | `organization_api_keys/read` |
168
- | `shopifyWebhooks` | `organization_integrations/read` |
169
- | `shopifyMetafieldConfigs` | `organization_integrations/read` |
170
- | `shopifyProduct` / `shopifyProducts` | `organization_integrations/read` |
171
- | `report` | `organization_reports/read` |
172
-
173
- ### Mutations
174
-
175
- | Mutation | Required Scope |
176
- |----------|---------------|
177
- | `organizationCreate` | `organization/create` |
178
- | `organizationUpdate` | `organization/update` |
179
- | `organizationDelete` | `organization/delete` |
180
- | `organizationMemberInvite` | `organization_invitations/create` |
181
- | `organizationInvitationRevoke` | `organization_invitations/delete` |
182
- | `organizationMemberRemove` | `organization_members/delete` |
183
- | `organizationMemberRoleUpdate` | `organization_members/update` |
184
- | `projectCreate` | `organization_projects/create` |
185
- | `apiKeyCreate` | `organization_api_keys/create` |
186
- | `apiKeyRevoke` | `organization_api_keys/delete` |
187
- | `shopifyWebhookCreate` | `organization_integrations/create` |
188
- | `shopifyWebhookUpdate` | `organization_integrations/update` |
189
- | `shopifyWebhookDelete` | `organization_integrations/delete` |
190
- | `shopifyMetafieldConfigCreate` | `organization_integrations/create` |
191
- | `shopifyMetafieldConfigUpdate` | `organization_integrations/update` |
192
- | `shopifyMetafieldConfigDelete` | `organization_integrations/delete` |
193
- | `reportCreate` | `organization_reports/create` |
194
- | `reportUpdate` | `organization_reports/update` |
195
- | `reportDelete` | `organization_reports/delete` |
196
-
197
- Some mutations do not require organization-level scopes because they operate on the caller's own data:
198
-
199
- | Mutation | Requirement |
200
- |----------|------------|
201
- | `sessionCreate` / `sessionRefresh` | No authentication required |
202
- | `accountCreate` / `accountVerifyEmail` | No authentication required |
203
- | `oauthAuthorize` / `oauthCallback` | No authentication required |
204
- | `magicLinkSend` / `magicLinkVerify` | No authentication required |
205
- | `passwordResetSend` / `passwordReset` | No authentication required |
206
- | `passwordUpdate` | Authenticated session (no specific scope) |
207
- | `organizationInvitationAccept` / `organizationInvitationDecline` | Authenticated session (no specific scope) |
208
- | `mfaFactorEnroll` / `mfaChallengeSend` / `mfaChallengeVerify` / `mfaFactorUnenroll` | Authenticated session (no specific scope) |
209
-
210
- ## Read your scopes
211
-
212
- ### Root-level scopes
213
-
214
- The `viewerScopes` query returns the root-level scopes for the authenticated caller:
215
-
216
- ```graphql
217
- query {
218
- viewerScopes
219
- }
220
- ```
221
-
222
- Response:
223
-
224
- ```json
225
- {
226
- "data": {
227
- "viewerScopes": [
228
- "ORGANIZATION_CREATE"
229
- ]
230
- }
231
- }
232
- ```
233
-
234
- ### Organization-level scopes
235
-
236
- Each `Organization` object exposes a `viewerScopes` field that returns the scopes the caller has within that specific organization:
237
-
238
- ```graphql
239
- query {
240
- organization(input: { slug: "my-company" }) {
241
- id
242
- name
243
- viewerScopes
244
- }
245
- }
246
- ```
247
-
248
- Response:
249
-
250
- ```json
251
- {
252
- "data": {
253
- "organization": {
254
- "id": "org_abc123",
255
- "name": "My Company",
256
- "viewerScopes": [
257
- "ORGANIZATION_READ",
258
- "ORGANIZATION_UPDATE",
259
- "ORGANIZATION_MEMBERS_READ",
260
- "ORGANIZATION_PROJECTS_READ",
261
- "ORGANIZATION_PROJECTS_UPDATE",
262
- "ORGANIZATION_PROJECTS_DELETE",
263
- "ORGANIZATION_API_KEYS_CREATE",
264
- "ORGANIZATION_API_KEYS_READ",
265
- "ORGANIZATION_API_KEYS_DELETE",
266
- "ORGANIZATION_INTEGRATIONS_CREATE",
267
- "ORGANIZATION_INTEGRATIONS_READ",
268
- "ORGANIZATION_INTEGRATIONS_UPDATE",
269
- "ORGANIZATION_INTEGRATIONS_DELETE",
270
- "ORGANIZATION_REPORTS_READ"
271
- ]
272
- }
273
- }
274
- }
275
- ```
276
-
277
- Use this to build a UI that changes with the permissions of the caller. An example is
278
- a **Delete Organization** button that the UI hides when the caller does not hold
279
- `ORGANIZATION_DELETE`.
280
-
281
- ## Related
282
-
283
- - [Authentication](/reference/management-api/authentication)
284
- - [How to authenticate with an API key](/how-to/authenticate-with-an-api-key)
285
- - [API keys](/reference/dashboard/api-keys) — the dashboard surface.