@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,43 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- import { Screenshot } from '../../../../components/Screenshot'
7
-
8
- # Reports
9
-
10
- A report is an embedded Metabase dashboard or question, attached to a Picked project. Use
11
- a report to see how your visitors move through your experiences and your feature flags.
12
-
13
- <Screenshot
14
- route="/{orgSlug}/{projectId}/reports"
15
- alt="The reports list for a project on the Picked dashboard"
16
- />
17
-
18
- ## Report options
19
-
20
- | Option | Description |
21
- | --- | --- |
22
- | **Report name** | The name that the reports list shows. |
23
- | **Description** | An optional note about what the report shows. |
24
- | **Metabase report type** | `Dashboard` or `Question`. |
25
- | **Metabase report ID** | The numeric ID from the Metabase URL. |
26
- | **Display order** | Optional. It controls the position of the report in the list. |
27
-
28
- The create form has a link that opens the report, so you can check that the ID is
29
- correct before you save.
30
-
31
- ## Permissions
32
-
33
- A member needs permission in the organization to create, edit, or delete a report. The
34
- dashboard hides those actions from a member without it.
35
-
36
- ## Delete a report
37
-
38
- Open the report settings page and click **Delete report**. You cannot reverse a delete.
39
-
40
- ## Related
41
-
42
- - [Analytics queries](/how-to/analytics) — query the same data with SQL.
43
- - [About PickedQL](/explanation/how-pickedql-works) — what the query layer expands.
@@ -1,37 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- import { Screenshot } from '../../../../components/Screenshot'
7
-
8
- # Steps
9
-
10
- A step is one screen or card that a visitor sees during an experience. Each step
11
- holds one or more fields. A field collects data or shows content.
12
-
13
- <Screenshot
14
- route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/steps"
15
- alt="The steps list for a workspace on the Picked dashboard"
16
- />
17
-
18
- ## Set up a step
19
-
20
- **Name**: The name that the dashboard shows. Your visitors do not see it.
21
-
22
- **Key**: The identifier that your application uses for this step. Your
23
- visitors do not see it.
24
-
25
- **Layout Name**: The name of the component layout that renders this step. Examples
26
- are `card`, `modal`, and `fullscreen`.
27
-
28
- A step can also carry a **Step Layout**. A step layout is a reusable CMS schema, and
29
- it gives the step a Content Entry. See [Models](/reference/dashboard/content/models).
30
-
31
- ## Related
32
-
33
- - [How to add a step, a field, an action, or a condition](/how-to/add-a-step-field-or-action)
34
-
35
- - [How to build a flow](/how-to/build-a-flow) — add a step and assign fields to it.
36
- - [How to reuse a step, a field, or an action](/how-to/reuse-a-step-field-or-action)
37
- - [Models](/reference/dashboard/content/models) — the step layout schema.
@@ -1,29 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- # Team management
7
-
8
- Control who can reach your organization and what each person can do. An organization
9
- is the top-level container for your projects and members.
10
-
11
- ## Organizations
12
-
13
- An organization groups your projects, your members, and your settings. You can belong
14
- to more than one organization.
15
-
16
- To move between organizations, use the organization control at the top of the
17
- sidebar.
18
-
19
- ## Roles and permissions
20
-
21
- Each member holds a role, and the role controls what the member can reach. A role
22
- decides whether a member can create a project, edit an experience, control other
23
- members, or read a report.
24
-
25
- Give each member the smallest role that the work of that member needs.
26
-
27
- ## Related
28
-
29
- - [How to invite and remove members](/how-to/invite-and-remove-members)
@@ -1,30 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- import { Screenshot } from '../../../../components/Screenshot'
7
-
8
- # Workspace versioning
9
-
10
- When you publish, Picked makes an immutable snapshot of your workspace. A project
11
- always serves exactly one version, the *live* version. A roll-back moves the live
12
- pointer of the project to an earlier snapshot. It changes no data.
13
-
14
- <Screenshot
15
- route="/{orgSlug}/{projectId}/publish-history"
16
- alt="The Publish history page with published workspace versions and the Live and Restore actions"
17
- hide={['[data-testid="version-row-relative-time"]']}
18
- />
19
-
20
- ## Publish history
21
-
22
- The **Publish history** page lists each published version of every workspace in the
23
- project, the newest first. The version that Picked serves now carries a **Live**
24
- badge.
25
-
26
- ## Related
27
-
28
- - [About workspaces and versions](/explanation/workspaces-and-versions) — why a roll-back
29
- changes no data.
30
- - [How to roll back a published version](/how-to/roll-back-a-published-version)
@@ -1,76 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- import { Screenshot } from '../../../../components/Screenshot'
7
-
8
- # Workspaces
9
-
10
- A workspace is one version of the configuration of your project. Use a workspace to hold
11
- a change, to see a preview of it, and to publish it when it is ready.
12
-
13
- <Screenshot
14
- route="/{orgSlug}/{projectId}/workspaces"
15
- alt="The workspaces list inside a project on the Picked dashboard"
16
- hide={['[data-testid="workspace-row-relative-time"]']}
17
- />
18
-
19
- ## How workspaces work
20
-
21
- Each project has a workspace that holds your experiences, feature flags, steps, fields,
22
- actions, and conditions. When you make a change in the dashboard, that change stays in
23
- the workspace until you publish it. A change to a flow, to a feature flag, or to a step
24
- all behave the same way.
25
-
26
- A workspace is in one of three states:
27
-
28
- - **Live** — the workspace that the SDK serves to your visitors. Each project has
29
- exactly one live workspace.
30
- - **Draft** — a workspace that no visitor sees. You can edit a draft, see a preview
31
- of it, and publish it to make it live.
32
- - **Archived** — a draft that you put to one side. An archived workspace is still
33
- editable, but it does not appear in the default workspaces list.
34
-
35
- ## Change previews
36
-
37
- The publish modal shows a side-by-side change preview. It compares the current
38
- workspace against the last published snapshot. Use it to see exactly what your
39
- visitors get after you publish.
40
-
41
- <Screenshot
42
- route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/experiences?action=publish"
43
- alt="The publish modal with a change preview of added experiences, steps, and conditions"
44
- selector='[role="dialog"]'
45
- wait='[role="dialog"]'
46
- hide={['[data-testid="publish-diff-replaces-version"]']}
47
- renderWidth={720}
48
- renderHeight={579}
49
- />
50
-
51
- The preview puts the changes into groups: experiences, feature flags, steps, fields,
52
- actions, and conditions. Each row shows whether the record was **added**, **removed**,
53
- or **modified**. For a modified record, expand the row to see which properties changed.
54
-
55
- Some changes break other records. An example is a field that you remove while other
56
- steps still point at it. The change preview shows a banner above the diff for these
57
- entries, so that you can look at them again before you publish.
58
-
59
- The first publish of a workspace has no earlier snapshot to compare against. The
60
- publish modal shows the contents of the workspace as the first publish, with no diff.
61
-
62
- ## Unpublished changes
63
-
64
- The workspace records whether anything changed since the last publish. The toolbar then
65
- shows a warning badge. It counts a change to any of these:
66
-
67
- - An experience or a feature flag.
68
- - A step, a field, an action, or a condition.
69
-
70
- ## Related
71
-
72
- - [About workspaces and versions](/explanation/workspaces-and-versions) — why a draft and
73
- a version are separate.
74
- - [How to see a preview of a workspace](/how-to/preview-a-workspace)
75
- - [How to publish a workspace](/how-to/publish-a-workspace)
76
- - [How to archive or delete a workspace](/how-to/archive-or-delete-a-workspace)
@@ -1,152 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- # Experience Content Endpoint
7
-
8
- Fetch the content entries that back the steps of a single experience.
9
-
10
- ## Request
11
-
12
- ```
13
- GET /api/v1/projects/:projectId/experiences/:id/content
14
- ```
15
-
16
- | Parameter | In | Description |
17
- | --- | --- | --- |
18
- | `projectId` | path | The project the experience belongs to. |
19
- | `id` | path | The experience to fetch content for. |
20
- | `preview_token` | query | Optional. With it, the endpoint returns preview content, which is unpublished. |
21
-
22
- ## Response
23
-
24
- ```json
25
- {
26
- "experienceId": "exp_123",
27
- "versionId": "ver_456",
28
- "content": [
29
- {
30
- "id": "entry_789",
31
- "contentModelKey": "page-hero",
32
- "data": {
33
- "title": "Spring sale",
34
- "category": { "contentEntryId": "entry_42", "contentModelKey": "category" }
35
- }
36
- }
37
- ],
38
- "references": [
39
- {
40
- "id": "entry_42",
41
- "contentModelKey": "category",
42
- "data": { "name": "Outerwear" }
43
- }
44
- ]
45
- }
46
- ```
47
-
48
- | Field | Type | Description |
49
- | --- | --- | --- |
50
- | `experienceId` | `string` | The experience the content belongs to. |
51
- | `versionId` | `string \| null` | The published version id, or `null` on preview. |
52
- | `content[]` | `array` | The entries that the steps of the experience point at. |
53
- | `content[].id` | `string` | The content entry id. |
54
- | `content[].contentModelKey` | `string \| null` | The Key of the Model, or `null` when it cannot be resolved. |
55
- | `content[].data` | `object` | The entry data. It matches the schema of the Model. |
56
- | `references[]` | `array` | Every entry that a `reference` field reaches, in the same blob shape as `content[]`. |
57
-
58
- The published response and the preview response hold the same fields, and the same
59
- values, for the same content.
60
-
61
- ## A reference field points at a separate blob
62
-
63
- A [Reference field](/reference/dashboard/content/models#reference-fields) arrives as a
64
- pointer, and not as the entry:
65
-
66
- ```json
67
- { "contentEntryId": "entry_42", "contentModelKey": "category" }
68
- ```
69
-
70
- A repeatable Reference field arrives as an array of such pointers.
71
-
72
- The entry itself arrives in `references[]` under its own `id`. Look the pointer up
73
- there. The SDK does this for you, through
74
- [`useReference` and `getReference`](/reference/sdk/content).
75
-
76
- `references[]` holds each entry one time, for any number of fields that point at it. It
77
- omits the entries that are in `content[]` already.
78
-
79
- ### What `references[]` omits
80
-
81
- Picked resolves a chain of references to a maximum depth of 5. It counts the depth from
82
- the entries in `content[]`. An entry is absent from `references[]` when Picked cannot
83
- resolve it:
84
-
85
- | Cause | Result |
86
- | --- | --- |
87
- | The target was deleted | The pointer stays. The entry is absent. |
88
- | The target is in another workspace | The pointer stays. The entry is absent. |
89
- | The chain makes a cycle | The pointer stays. The entry is absent. |
90
- | The chain is deeper than 5 | The pointer stays, with its `contentModelKey`. The entry is absent. |
91
-
92
- A pointer with no entry in `references[]` means that there is no such entry. Picked sends
93
- no empty blob for it.
94
-
95
- :::warning
96
- A reference pointer also carries a `data` field with the content of the target inlined.
97
- This is for the SDK versions that came before `references[]`. Read `references[]`
98
- instead. A later release removes the inline copy.
99
- :::
100
-
101
- ## An HTML asset comes back in the response
102
-
103
- A Model can have an [HTML asset](/reference/dashboard/content/asset-library) field. The
104
- value of that field arrives inside the response. The endpoint changes the reference to
105
- `{ id, content }`. There, `content` holds the HTML that you uploaded, as a string. It
106
- is `null` when the endpoint cannot resolve it:
107
-
108
- ```json
109
- {
110
- "id": "entry_789",
111
- "contentModelKey": "page-hero",
112
- "data": {
113
- "markup": { "id": "asset_42", "content": "<section>...</section>" }
114
- }
115
- }
116
- ```
117
-
118
- The SDK renders the inlined HTML directly, with no extra storage fetch.
119
-
120
- ## Status codes
121
-
122
- | Code | Meaning |
123
- | --- | --- |
124
- | `200` | Success. |
125
- | `401` | Invalid `preview_token`. |
126
- | `404` | The experience has no published content. |
127
-
128
- ## Example
129
-
130
- ```bash
131
- curl https://api.picked.app/api/v1/projects/proj_123/experiences/exp_123/content
132
- ```
133
-
134
- ```json
135
- {
136
- "experienceId": "exp_123",
137
- "versionId": "ver_456",
138
- "content": [
139
- { "id": "entry_789", "contentModelKey": "page-hero", "data": { "title": "Spring sale" } }
140
- ],
141
- "references": []
142
- }
143
- ```
144
-
145
- ## Related
146
-
147
- - [About the two APIs](/explanation/the-two-apis)
148
- - [About content references](/explanation/content-references) — why a reference is a pointer.
149
- - [Content](/reference/sdk/content) — how the SDK resolves a pointer.
150
- - [Project config](/reference/delivery-api/project-config) — the endpoint that links a step to an entry.
151
- - [Server Snapshot](/reference/sdk/ssr/serialize) — how the SDK reads this content.
152
- - [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling)
@@ -1,45 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- # Delivery API
7
-
8
- The Delivery API is a public REST API. It is read-only, and it serves the published
9
- configuration of your project together with your page content. It is separate from the
10
- GraphQL management API.
11
-
12
- ## Base URL and versioning
13
-
14
- All Delivery API routes are versioned under `/api/v1`:
15
-
16
- ```
17
- https://api.picked.app/api/v1
18
- ```
19
-
20
- ## Published content and preview content
21
-
22
- Each endpoint serves two surfaces:
23
-
24
- - **Published** content is anonymous. Anybody can read your published configuration and
25
- your published content.
26
- - **Preview** content needs a `preview_token` query parameter. With it you can render
27
- an unpublished draft before you make it live.
28
-
29
- The management API holds the preview token of a workspace in the `previewToken`
30
- field. The preview action in the dashboard also makes one for you.
31
-
32
- ## Endpoints
33
-
34
- | Endpoint | Description |
35
- | --- | --- |
36
- | [Project Config](/reference/delivery-api/project-config) | `GET /api/v1/projects/:projectId` returns the published configuration of the project, with the content link of each step. |
37
- | [Experience Content](/reference/delivery-api/experience-content) | `GET /api/v1/projects/:projectId/experiences/:id/content` returns the Content Entries of an experience. |
38
-
39
- Both endpoints share some behaviour. See
40
- [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling).
41
-
42
- ## Related
43
-
44
- - [About the two APIs](/explanation/the-two-apis) — which one to use, and why they are
45
- separate.
@@ -1,79 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- # Preview, cache, and crawlers
7
-
8
- Both Delivery API endpoints share this behaviour: the preview token, the cache, CORS,
9
- and what a crawler can read.
10
-
11
- ## Preview tokens
12
-
13
- Pass `?preview_token=<token>` to read unpublished content. Both endpoints take it,
14
- and both return `versionId: null` for a preview. An invalid token returns `401`.
15
-
16
- ```bash
17
- curl "https://api.picked.app/api/v1/projects/proj_123?preview_token=<token>"
18
- ```
19
-
20
- The [management API](/tutorials/first-api-call) holds the preview token of a workspace in the
21
- `previewToken` field. The preview action in the dashboard also makes one for you.
22
-
23
- Use the same token for the project configuration request and for the experience content
24
- request. Both then come from the same preview.
25
-
26
- ## Cache
27
-
28
- The cache rules depend on the surface and on the client that makes the request. The
29
- SDK sends a `Picked-Client: sdk` request header:
30
-
31
- | Request | `Cache-Control` |
32
- | --- | --- |
33
- | Published, `Picked-Client: sdk` | `public, s-maxage=10` |
34
- | Published, other clients | `private, no-store` |
35
- | Preview | `no-store` |
36
-
37
- A published response that a cache can hold also sends `Vary: Picked-Client`. A shared
38
- cache therefore keys on the client header. It never gives a body that it cached for
39
- the SDK to a request from another client.
40
-
41
- ## CORS
42
-
43
- Both endpoints can be read from another origin. An `OPTIONS` preflight returns `204`
44
- with the CORS headers:
45
-
46
- | Header | Value |
47
- | --- | --- |
48
- | `Access-Control-Allow-Origin` | `*` |
49
- | `Access-Control-Allow-Methods` | `GET, OPTIONS` |
50
- | `Access-Control-Allow-Headers` | `Content-Type, Picked-Client, Picked-Version, traceparent, tracestate` |
51
-
52
- ## Crawlers and search rank
53
-
54
- A crawler can read both endpoints, so a search engine can read your published
55
- content. A preview URL is disallowed, so a draft never reaches the index. These are
56
- the `robots.txt` rules:
57
-
58
- ```
59
- User-agent: *
60
-
61
- # Let a crawler read the public project configuration and experience content.
62
- Allow: /api/v1/projects
63
- Allow: /api/v1/projects/*/experiences/*/content
64
-
65
- # Keep a preview response, which is a draft, away from a crawler.
66
- Disallow: /api/v1/projects/*preview_token=
67
-
68
- # Everything else stays disallowed: GraphQL, MCP, internal routes, and the ping.
69
- Disallow: /
70
- ```
71
-
72
- See [Project Config](/reference/delivery-api/project-config) and
73
- [Experience Content](/reference/delivery-api/experience-content) for the endpoints.
74
-
75
- ## Related
76
-
77
- - [About the two APIs](/explanation/the-two-apis) — how a preview stays out of the search
78
- index.
79
- - [How to render an unpublished preview](/how-to/render-an-unpublished-preview)
@@ -1,65 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- # Project Config Endpoint
7
-
8
- Fetch a project's published configuration: its experiences, steps, and the link from each step to the Content Entry that backs it.
9
-
10
- ## Request
11
-
12
- ```
13
- GET /api/v1/projects/:projectId
14
- ```
15
-
16
- | Parameter | In | Description |
17
- | --- | --- | --- |
18
- | `projectId` | path | The project to fetch config for. |
19
- | `preview_token` | query | Optional. With it, the endpoint returns the preview configuration, which are unpublished. |
20
-
21
- ## Response
22
-
23
- The response carries the project's experiences and steps. Each step includes `layoutContentId`, the reference to the Content Entry that backs that step's layout. Use it to know which experiences have content to fetch from the [Experience Content](/reference/delivery-api/experience-content) endpoint.
24
-
25
- | Field | Type | Description |
26
- | --- | --- | --- |
27
- | `id` | `string` | The project id. |
28
- | `versionId` | `string \| null` | The published version id, or `null` on preview. |
29
- | `steps[].layoutContentId` | `string \| null` | The Content Entry of this step, or `null` when the step has no content. |
30
-
31
- ## Published content and preview content
32
-
33
- For published content, `versionId` holds the ID of the published version. For preview
34
- content, which you read with `?preview_token=...`, `versionId` is `null`, because
35
- there is no published version. See [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling).
36
-
37
- ## Example
38
-
39
- ```bash
40
- curl https://api.picked.app/api/v1/projects/proj_123
41
- ```
42
-
43
- ```json
44
- {
45
- "id": "proj_123",
46
- "versionId": "ver_456",
47
- "steps": [
48
- {
49
- "id": "step_1",
50
- "key": "hero",
51
- "name": "Hero",
52
- "layoutName": "HeroLayout",
53
- "layoutContentId": "entry_789"
54
- }
55
- ]
56
- }
57
- ```
58
-
59
- Pass the config to `serialize()` on your server to produce an SSR snapshot. See [Server Snapshot](/reference/sdk/ssr/serialize).
60
-
61
- ## Related
62
-
63
- - [About the two APIs](/explanation/the-two-apis)
64
- - [Experience content](/reference/delivery-api/experience-content)
65
- - [How to server-render a page](/how-to/server-render-a-page)
@@ -1,85 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- # Workspace Schema Endpoint
7
-
8
- A JSON Schema document for the structure of your project: content models, fields, feature keys, experience keys, and step keys. Tooling reads this endpoint to generate TypeScript types for your application.
9
-
10
- ## Request
11
-
12
- ```
13
- GET /api/v1/projects/:projectId/schema
14
- ```
15
-
16
- | Parameter | In | Description |
17
- | --- | --- | --- |
18
- | `projectId` | path | The project whose schema to fetch. |
19
- | `preview_token` | query | Optional. Returns the preview (unpublished) schema when you send it. |
20
-
21
- ## Response
22
-
23
- The response is a [JSON Schema draft 2020-12](https://json-schema.org/draft/2020-12/schema) document with Picked-specific extension fields:
24
-
25
- | Field | Description |
26
- | --- | --- |
27
- | `x-picked-schema-version` | Schema document version (currently `1`). |
28
- | `x-picked-source` | `"published"` or `"preview"` — mirrors the surface you requested. |
29
- | `x-picked-version-id` | Published workspace version id, or `null` on preview. |
30
- | `x-picked-step-content-models` | Map of step key → content model key, which gives each layout its type. |
31
- | `x-picked-feature-values` | Map of feature key → the values that the feature can serve. Picked adds this field only when the workspace has a Text feature flag. |
32
- | `$defs.contentModels` | JSON Schema definitions for each content model. |
33
- | `$defs.contentBlocks` | JSON Schema definitions for reusable content blocks. |
34
- | `$defs.fields` | Object schema for project field values. |
35
- | `$defs.featureKeys` | String enum of feature keys. |
36
- | `$defs.experienceKeys` | String enum of experience keys. |
37
- | `$defs.stepKeys` | String enum of step keys. |
38
-
39
- ## Published and preview
40
-
41
- On the published surface, the schema reflects your last published workspace. On the preview surface (`?preview_token=...`), the schema reflects the current draft workspace. See [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling).
42
-
43
- When no published schema exists, the published endpoint returns `404` and tells you to publish the workspace.
44
-
45
- A Boolean feature flag serves `true` or `false`, and it contributes no entry to
46
- `x-picked-feature-values`. A workspace of Boolean feature flags therefore omits the field.
47
- A schema that Picked published before Text feature flags existed also omits it.
48
-
49
- Picked sorts the values of each Text feature flag by the key of the variant. The document
50
- therefore does not change when you rename a variant or move a row.
51
-
52
- ## Example
53
-
54
- ```bash
55
- curl https://api.picked.app/api/v1/projects/proj_123/schema
56
- ```
57
-
58
- ```json
59
- {
60
- "$schema": "https://json-schema.org/draft/2020-12/schema",
61
- "$id": "picked:project/proj_123/schema",
62
- "x-picked-schema-version": 1,
63
- "x-picked-source": "published",
64
- "x-picked-version-id": "ver_456",
65
- "x-picked-step-content-models": {
66
- "intro": "welcome-page"
67
- },
68
- "x-picked-feature-values": {
69
- "hero": [false, "hero-a", "hero-b"]
70
- },
71
- "$defs": {
72
- "contentModels": {},
73
- "contentBlocks": {},
74
- "fields": { "type": "object", "additionalProperties": false, "properties": {} },
75
- "featureKeys": { "type": "string", "enum": ["default", "hero"] },
76
- "experienceKeys": { "type": "string", "enum": ["welcome-survey"] },
77
- "stepKeys": { "type": "string", "enum": ["intro"] }
78
- }
79
- }
80
- ```
81
-
82
- ## Related
83
-
84
- - [Type generation](/reference/sdk/type-generation) — Generate TypeScript types from this schema in your app.
85
- - [Project Config](/reference/delivery-api/project-config) — Runtime project configuration for the SDK.