@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,41 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to render an unpublished preview
7
-
8
- This guide shows you how to render draft content on your server. Your server cannot read
9
- the query string of the browser, so you must pass the token yourself.
10
-
11
- ## 1. Get the token
12
-
13
- The management API holds the preview token of a workspace in the `previewToken` field. The
14
- preview action in the dashboard also makes one for you.
15
-
16
- ## 2. Read the config with the token
17
-
18
- ```bash
19
- curl "https://api.picked.app/api/v1/projects/proj_123?preview_token=<token>"
20
- ```
21
-
22
- A preview response returns `versionId: null`. An invalid token returns `401`.
23
-
24
- ## 3. Pass the same token to `serialize()`
25
-
26
- ```ts
27
- const snapshot = await serialize(client, {
28
- projectConfig,
29
- attributes: { location: { pathname: '/promo' } },
30
- previewToken,
31
- })
32
- ```
33
-
34
- Use the same token for both requests. The configuration and the content then come from the same
35
- preview.
36
-
37
- ## Related
38
-
39
- - [About the two APIs](/explanation/the-two-apis) — how a preview stays out of the search
40
- index.
41
- - [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling).
@@ -1,53 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to reuse a section
7
-
8
- This guide shows you how to define a common structure one time and use it in more than
9
- one Model.
10
-
11
- ## 1. Create the section
12
-
13
- 1. Click **Pages** in the sidebar.
14
- 2. Click **Page Sections**.
15
- 3. Click **New block**.
16
- 4. Enter a **Name** and a **Key**.
17
- 5. Add your fields.
18
- 6. Click **Create block**.
19
-
20
- The **Category** is **Section** already, because you opened the list from **Page
21
- Sections**.
22
-
23
- ## 2. Accept the section in a Model
24
-
25
- 1. Open a page layout or a step layout.
26
- 2. Add a **Page Sections** field to the schema.
27
- 3. Click **Save**.
28
-
29
- The field now accepts any Block of the Section category. Make the field repeatable to
30
- build a page from a list of sections.
31
-
32
- If you want one section at a fixed place instead of a list, add a **Content block** field.
33
- Set its **Block category** to the **Section** category.
34
-
35
- ## 3. Choose the section in an entry
36
-
37
- 1. Open a content entry that uses the Model.
38
- 2. Find the field that you added.
39
- 3. Choose your Block.
40
- 4. Fill in the fields of the Block.
41
- 5. Click **Save**.
42
-
43
- :::warning
44
- An edit to a Block does not migrate the entries that use it. Check each affected content
45
- entry again, and correct every field error before you publish.
46
- :::
47
-
48
- ## Related
49
-
50
- - [About the content model](/explanation/the-content-model) — why a schema change does not
51
- migrate your data.
52
- - [Blocks](/reference/dashboard/content/blocks) — the reference.
53
- - [Models](/reference/dashboard/content/models) — every field type.
@@ -1,28 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to reuse a step, a field, or an action
7
-
8
- This guide shows you how to use one step, field, action, or condition in more than one
9
- flow. All four belong to the project, and not to the experience that you made them in.
10
-
11
- ## Steps
12
-
13
- 1. Open the flow builder for the second experience.
14
- 2. Find the step, the action, or the condition in the library on the left.
15
- 3. Drag it onto the canvas, or onto a step node for a field.
16
-
17
- The same one now appears in both flows.
18
-
19
- :::warning
20
- A change to the options applies at every place that uses it. Check the other flows before
21
- you change a shared step, field, action, or condition.
22
- :::
23
-
24
- ## Related
25
-
26
- - [Steps](/reference/dashboard/steps) — the step options.
27
- - [Fields](/reference/dashboard/fields) — the field options.
28
- - [Actions](/reference/dashboard/actions) — the action options.
@@ -1,26 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to roll back a published version
7
-
8
- This guide shows you how to make an earlier published version live again. Your current
9
- draft does not change.
10
-
11
- ## Steps
12
-
13
- 1. Open **Publish history** from the project sidebar.
14
- 2. Find the version that you want to restore.
15
- 3. Click **Restore**.
16
- 4. Read the diff preview. It compares the current live version against the one that you
17
- chose.
18
- 5. Click **Restore this version** to confirm.
19
-
20
- The restored version is live immediately.
21
-
22
- ## Related
23
-
24
- - [About workspaces and versions](/explanation/workspaces-and-versions) — why a roll-back
25
- changes no data.
26
- - [Publish history](/reference/dashboard/workspace-versioning) — the version list.
@@ -1,49 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to run an A/B test
7
-
8
- This guide shows you how to split your traffic with a feature flag and read the result in
9
- your application.
10
-
11
- Read [About feature flag allocation](/explanation/feature-flag-allocation) first. The
12
- point at which you read the feature flag decides when a visitor enters the test.
13
-
14
- ## 1. Create the feature flag
15
-
16
- 1. Open your project.
17
- 2. Click **Feature flags** in the sidebar.
18
- 3. Click **New feature flag**.
19
- 4. Enter a name.
20
- 5. Click **Create feature flag**.
21
-
22
- You cannot change the key after you create the feature flag.
23
-
24
- ## 2. Set the allocation
25
-
26
- Open the detail page of the feature flag and set these controls:
27
-
28
- 1. Turn **Enabled** on. A feature flag that is off allocates nobody.
29
- 2. Set **Weight** to the percentage of visitors that you want in the test.
30
- 3. Enter a **Description** that says what the feature flag tests.
31
-
32
- ## 3. Read the feature flag in your application
33
-
34
- See [How to read a feature flag](/how-to/read-a-feature-flag). Read it at the point where
35
- the decision matters, and not at startup.
36
-
37
- ## 4. Change the weight later
38
-
39
- 1. Change **Weight** on the detail page.
40
- 2. Increment the version.
41
-
42
- The new weight then applies to a visitor with a cached decision. Leave the version as it
43
- is to apply the new weight only to a visitor who is not allocated yet.
44
-
45
- ## Related
46
-
47
- - [About feature flag allocation](/explanation/feature-flag-allocation) — why two feature
48
- flags at the same weight give four groups, not two.
49
- - [Feature flags](/reference/dashboard/features) — the controls.
@@ -1,125 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to run code on a form submission
7
-
8
- This guide shows you how to act on a step submission. Pass your callbacks to `useStep()`
9
- in React, or to `getStep()` in Svelte.
10
-
11
- ## What the SDK does on submit
12
-
13
- 1. It collects the field values from the HTML form.
14
- 2. It runs each `onBeforeSubmit` callback, one after another.
15
- 3. It checks each required field and each validation rule.
16
- 4. It commits the responses to the experience state.
17
- 5. It fires `form_submit_success` or `form_submit_error` on the event bus.
18
- 6. It runs your `onSuccess` or `onError` callback.
19
- 7. It moves to the next step.
20
-
21
- ## Change the data before it is stored
22
-
23
- :::code-group
24
-
25
- ```tsx [React]
26
- const { form } = useStep({
27
- onBeforeSubmit: async (data) => ({
28
- ...data,
29
- 'email-address': String(data['email-address']).toLowerCase(),
30
- }),
31
- })
32
- ```
33
-
34
- ```svelte [Svelte]
35
- <script lang="ts">
36
- const { form } = getStep({
37
- onBeforeSubmit: async (data) => ({
38
- ...data,
39
- 'email-address': String(data['email-address']).toLowerCase(),
40
- }),
41
- })
42
- </script>
43
- ```
44
-
45
- :::
46
-
47
- :::warning
48
- An `onBeforeSubmit` callback that throws aborts the submit before the SDK commits
49
- anything, and the step does not advance. Use it for a transform and for a check. Put a
50
- side effect, such as an analytics call, in `onSuccess`.
51
- :::
52
-
53
- ## Act on the outcome
54
-
55
- :::code-group
56
-
57
- ```tsx [React]
58
- const { form } = useStep({
59
- onSuccess: ({ data }) => analytics.track('lead_captured', data),
60
- onError: (errors) => console.error('Validation errors:', errors),
61
- })
62
- ```
63
-
64
- ```svelte [Svelte]
65
- <script lang="ts">
66
- const { form } = getStep({
67
- onSuccess: ({ data }) => analytics.track('lead_captured', data),
68
- onError: (errors) => console.error('Validation errors:', errors),
69
- })
70
- </script>
71
- ```
72
-
73
- :::
74
-
75
- A callback belongs to the component that passes it, and the SDK releases it when that
76
- component unmounts. An `onSuccess` callback that throws cannot stop the flow. The SDK
77
- reports the failure as `form_submit_callback_error`.
78
-
79
- ## Choose the next step yourself
80
-
81
- Call `stopNavigation()` inside `onSuccess`, then move where you want:
82
-
83
- :::code-group
84
-
85
- ```tsx [React]
86
- const experience = useExperience()
87
-
88
- const { form } = useStep({
89
- onSuccess: ({ data, stopNavigation }) => {
90
- stopNavigation()
91
- if (data['plan-type'] === 'enterprise') {
92
- experience.goToStepById('enterprise-contact')
93
- } else {
94
- experience.goToNextStep()
95
- }
96
- },
97
- })
98
- ```
99
-
100
- ```svelte [Svelte]
101
- <script lang="ts">
102
- const experience = getExperience()
103
-
104
- const { form } = getStep({
105
- onSuccess: ({ data, stopNavigation }) => {
106
- stopNavigation()
107
- if (data['plan-type'] === 'enterprise') {
108
- experience.goToStepById('enterprise-contact')
109
- } else {
110
- experience.goToNextStep()
111
- }
112
- },
113
- })
114
- </script>
115
- ```
116
-
117
- :::
118
-
119
- `goToStepById()` takes a step `id`. `goToStepByKey()` takes the key of the step. When no
120
- step matches, the call does nothing.
121
-
122
- ## Related
123
-
124
- - [How to render a step form](/how-to/render-a-step-form).
125
- - [SDK steps](/reference/sdk/steps) — the `form` object.
@@ -1,81 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to server-render a page
7
-
8
- This guide shows you how to render a Picked Page on your server and hydrate it in the
9
- browser. You need a published Page and a server that renders React or Svelte.
10
-
11
- ## 1. Make the snapshot
12
-
13
- Create one client for each request, then call `serialize()`:
14
-
15
- ```ts
16
- import { createClient } from 'picked'
17
- import { serialize } from '@picked/client/server'
18
-
19
- const client = createClient(options)
20
-
21
- const snapshot = await serialize(client, {
22
- projectConfig,
23
- attributes: { location: { pathname: url.pathname } },
24
- })
25
- ```
26
-
27
- :::warning
28
- Give `serialize()` one client for each request. It does not support two calls at the same
29
- time on one client.
30
- :::
31
-
32
- ## 2. Embed the snapshot
33
-
34
- ```ts
35
- const html = `
36
- <div id="root">${appHtml}</div>
37
- <script>window.__PICKED__ = ${JSON.stringify(snapshot)}</script>
38
- `
39
- ```
40
-
41
- ## 3. Seed the client and render the slot
42
-
43
- :::code-group
44
-
45
- ```tsx [React]
46
- import { PickedProvider, ExperienceSlot } from '@picked/react'
47
-
48
- export function Page({ snapshot }) {
49
- return (
50
- <PickedProvider options={options} snapshot={snapshot}>
51
- <ExperienceSlot name="page" />
52
- </PickedProvider>
53
- )
54
- }
55
- ```
56
-
57
- ```svelte [Svelte]
58
- <script lang="ts">
59
- import { ExperienceSlot, setPickedContext } from '@picked/svelte'
60
-
61
- const { snapshot } = $props()
62
- setPickedContext({ options, snapshot })
63
- </script>
64
-
65
- <ExperienceSlot name="page" />
66
- ```
67
-
68
- :::
69
-
70
- The provider seeds the client at once, so the server HTML and the first paint match.
71
-
72
- ## 4. Point the experience at the slot
73
-
74
- Set the target selector of your Page experience to `.picked-slot-page`, then publish.
75
-
76
- ## Related
77
-
78
- - [About server-side rendering](/explanation/why-server-side-rendering) — why the
79
- snapshot carries condition results.
80
- - [Server snapshot](/reference/sdk/ssr/serialize) — every parameter.
81
- - [Your first server-rendered page](/tutorials/first-server-rendered-page).
@@ -1,32 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to set a Content Security Policy
7
-
8
- This guide shows you how to let the Picked SDK load its resources under a CSP.
9
-
10
- ## Steps
11
-
12
- Add the Picked domains to your policy.
13
-
14
- As an HTTP header:
15
-
16
- ```
17
- Content-Security-Policy: connect-src 'self' https://api.picked.app https://evnts.pckd.dev; img-src 'self' https://img.picked-content.com;
18
- ```
19
-
20
- Or as a `<meta>` tag:
21
-
22
- ```html
23
- <meta
24
- http-equiv="Content-Security-Policy"
25
- content="connect-src 'self' https://api.picked.app https://evnts.pckd.dev; img-src 'self' https://img.picked-content.com;"
26
- />
27
- ```
28
-
29
- ## Related
30
-
31
- - [Content Security Policy](/reference/sdk/content-security-policy) — what each domain is
32
- for.
@@ -1,69 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to set up MFA
7
-
8
- This guide shows you how to add a second factor to an account. Every MFA mutation needs
9
- authentication.
10
-
11
- ## 1. Add a factor
12
-
13
- ```graphql
14
- mutation {
15
- mfaFactorEnroll(input: {
16
- factorType: PHONE
17
- phone: "+15551234567"
18
- friendlyName: "My Phone"
19
- }) {
20
- factor { id factorType status }
21
- }
22
- }
23
- ```
24
-
25
- A new factor has the status `UNVERIFIED`.
26
-
27
- ## 2. Send a challenge
28
-
29
- ```graphql
30
- mutation {
31
- mfaChallengeSend(input: { factorId: "factor-id" }) {
32
- challengeId
33
- }
34
- }
35
- ```
36
-
37
- This sends a code to the telephone number of the factor.
38
-
39
- ## 3. Verify the challenge
40
-
41
- ```graphql
42
- mutation {
43
- mfaChallengeVerify(input: {
44
- factorId: "factor-id"
45
- challengeId: "challenge-id"
46
- code: "123456"
47
- }) {
48
- session { accessToken refreshToken aal }
49
- }
50
- }
51
- ```
52
-
53
- The session moves to `AAL2`, and the factor status changes to `VERIFIED`.
54
-
55
- ## Remove a factor
56
-
57
- ```graphql
58
- mutation {
59
- mfaFactorUnenroll(input: { factorId: "factor-id" }) {
60
- success
61
- }
62
- }
63
- ```
64
-
65
- ## Related
66
-
67
- - [Authorization and scopes](/reference/management-api/authorization-and-scopes) — which
68
- operations need `AAL2`.
69
- - [Authentication](/reference/management-api/authentication) — every mutation.
@@ -1,122 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to switch workspaces
7
-
8
- This guide shows you how to point your local tooling at a different project or workspace.
9
- Your application then renders that workspace's content and types on your machine. It expects
10
- a `picked.config.ts` and the [CLI](/reference/tools/cli).
11
-
12
- Your tooling reads the project and surface named in the committed `picked.config.ts`. The
13
- CLI writes your choice to `.picked/settings.json` instead. That file is per-developer and
14
- Git ignores it, so the committed default stays as it is and one command puts it back.
15
-
16
- See [Workspaces](/reference/dashboard/workspaces) for what Live, Draft, and Archived mean.
17
-
18
- ## 1. Sign in
19
-
20
- ```bash
21
- picked login
22
- ```
23
-
24
- This opens your browser for a one-time OAuth sign-in and stores a session under
25
- `~/.picked/`. Confirm it with `picked whoami`. See
26
- [CLI authentication](/how-to/authenticate-the-cli).
27
-
28
- ## 2. Find a workspace
29
-
30
- ```bash
31
- picked workspace list
32
- ```
33
-
34
- ```
35
- Acme Corp. (acme-corporation)
36
- Storefront [proj_a1b2]
37
- Default Storefront [LIVE] (live)
38
- Checkout rework [DRAFT]
39
- ```
40
-
41
- Note the **project id** (`proj_a1b2`) and the name or the id of the workspace you want.
42
-
43
- ## 3. Switch to the draft
44
-
45
- ```bash
46
- picked workspace use --project proj_a1b2 --workspace ws_draft
47
- ```
48
-
49
- ```
50
- Active workspace: Checkout rework [DRAFT] in project proj_a1b2 (source: preview)
51
- Generated types at /app/src/picked-env.d.ts
52
- ```
53
-
54
- A command that names **one specific workspace** (draft, live, or archived):
55
-
56
- - writes the selection (and its [preview token](/reference/delivery-api/preview-caching-crawling)) to
57
- `.picked/settings.json`,
58
- - switches the resolved `source` to `preview` for that project, and
59
- - regenerates `picked-env.d.ts` from that workspace's schema (skip with `--no-generate`).
60
-
61
- To browse instead, run `picked workspace use` with no flags. The interactive picker lists
62
- every project, with **Published (live version)** and each of its workspaces.
63
-
64
- ## 4. See the draft in your app
65
-
66
- Both readers of the selection use `.picked/settings.json` with no change to your
67
- configuration:
68
-
69
- - **Type generation** now reads the draft schema. Rerun `picked generate types` after more
70
- edits.
71
- - The **[Vite plugin](/reference/tools/vite-plugin)** reads the draft's configuration and
72
- content in development and in a build. It sends the preview token to the
73
- [Delivery API](/reference/delivery-api). Restart the dev server to apply a switch.
74
-
75
- Your application renders the unpublished draft on your machine, with types.
76
-
77
- ## 5. Switch back to live
78
-
79
- ```bash
80
- picked workspace use --project proj_a1b2
81
- ```
82
-
83
- A command that names a project with no `--workspace`, or **Published (live version)** in the
84
- picker, discards the preview token and returns `source` to `published`. To confirm what is
85
- active:
86
-
87
- ```bash
88
- picked status
89
- ```
90
-
91
- ```
92
- Config default: project proj_a1b2 (source: published)
93
- Active selection: none (using the config default).
94
- ```
95
-
96
- ## CI and headless runs
97
-
98
- `.picked/settings.json` is a local, per-developer file. Do not commit it. To choose one
99
- workspace in CI with no selection file, set the environment directly:
100
-
101
- ```bash
102
- PICKED_PROJECT_ID=proj_a1b2 \
103
- PICKED_PREVIEW_TOKEN="$DRAFT_TOKEN" \
104
- picked generate types --check
105
- ```
106
-
107
- `PICKED_PREVIEW_TOKEN` applies only when the resolved `source` is `preview`. See the
108
- [CLI environment variables](/reference/tools/cli#environment-variables) for the full
109
- precedence order.
110
-
111
- :::note
112
- A preview token is a long-lived credential for one workspace. Keep it out of the version
113
- control system, as you do with each other credential. Git ignores `.picked/settings.json`
114
- for this reason, because `picked workspace use` writes a token there.
115
- :::
116
-
117
- ## Related
118
-
119
- - [CLI](/reference/tools/cli) — every command and flag.
120
- - [Workspaces](/reference/dashboard/workspaces) — Live, Draft, and Archived states.
121
- - [Type generation](/reference/sdk/type-generation) — how the schema becomes types.
122
- - [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling) — preview tokens on the Delivery API.
@@ -1,73 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- import { Screenshot } from '../../../components/Screenshot'
7
-
8
- # How to upload and use an asset
9
-
10
- This guide shows you how to put a file in the asset library and point at it from your
11
- content.
12
-
13
- ## 1. Add the field to a layout
14
-
15
- Two field types point at the library:
16
-
17
- - An **Asset** field takes an image, a video, or a document.
18
- - An **HTML** field takes a `.html` file.
19
-
20
- Add one of them to a page layout or a step layout.
21
-
22
- ## 2. Choose a file
23
-
24
- 1. Open the content entry.
25
- 2. Click **Choose file** on the asset field. On a field that holds a value already, click
26
- **Replace**.
27
- 3. Open the **Upload** tab to add a new file.
28
- 4. Open the **Library** tab to use a file that is there already.
29
- 5. Choose your asset.
30
-
31
- <Screenshot
32
- route="/{orgSlug}/{projectId}/design-systems/new"
33
- wait='button:has-text("Upload file")'
34
- click='button:has-text("Upload file")'
35
- selector="[role=dialog]"
36
- alt="The asset picker modal on the Picked dashboard, with the Library tab, its search box, its type filter, and its Sort menu"
37
- renderWidth={1072}
38
- renderHeight={790}
39
- />
40
-
41
- <Screenshot
42
- route="/{orgSlug}/{projectId}/design-systems/new"
43
- wait='button:has-text("Upload file")'
44
- click='button:has-text("Upload file")'
45
- selector="[role=dialog]"
46
- alt="The asset picker modal on the Picked dashboard, with the Library tab, its search box, its type filter, and its Sort menu"
47
- renderWidth={1072}
48
- renderHeight={790}
49
- />
50
-
51
- The detail panel on the right shows the kind, the dimensions, the size, and the upload
52
- date.
53
-
54
- ## 3. Find an asset in a large library
55
-
56
- The **Library** tab has three controls, and the server applies each one across the whole
57
- library:
58
-
59
- - **Search by name** narrows the list by file name while you type.
60
- - The type filter narrows the list to one media type. **All types** is the default.
61
- - **Sort** orders the list by **Name**, **Date created**, or **Date updated**.
62
-
63
- Click **Load more** at the bottom to read the next page of results.
64
-
65
- :::tip
66
- Each row has an **Open in new tab** control. Use it to check an asset again before you
67
- choose it. Your choice in the picker stays as it is.
68
- :::
69
-
70
- ## Related
71
-
72
- - [Asset library](/reference/dashboard/content/asset-library) — the limits, the file
73
- types, and how Picked serves an uploaded file.