@picked/client 0.0.1-dev.1789541668638 → 0.0.1-dev.1793756239746

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 (213) hide show
  1. package/LICENSE +1 -0
  2. package/README.md +34 -158
  3. package/dist/.tsbuildinfo +1 -1
  4. package/dist/{api-C7q_7vxn.js → api-B5i4XuCs.js} +1 -1
  5. package/dist/api-DMYLC1At.cjs +1 -0
  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 +465 -505
  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 +40 -36
  28. package/dist/esm/storage.js +1 -0
  29. package/dist/{experience-instance-B9S6Yf0N.js → experience-instance-4D6Yk-h0.js} +323 -260
  30. package/dist/experience-instance-D2FAkiPx.cjs +1 -0
  31. package/dist/plugin-CVLK5ZLV.cjs +1 -0
  32. package/dist/plugin-C_cLCzXK.js +256 -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/preview-unavailable-BAhTGDAp.cjs +1 -0
  36. package/dist/{version-CPKulHMH.js → preview-unavailable-OHRfSIId.js} +100 -61
  37. package/dist/provider-BFZgizAt.cjs +1 -0
  38. package/dist/provider-dD92LNPP.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-instance/experience-instance.d.ts +14 -1
  50. package/dist/types/entities/experience-instance/experience-instance.d.ts.map +1 -1
  51. package/dist/types/exports.d.ts +1 -0
  52. package/dist/types/exports.d.ts.map +1 -1
  53. package/dist/types/index.d.ts +2 -2
  54. package/dist/types/index.d.ts.map +1 -1
  55. package/dist/types/lifecycle/rules-logic.d.ts.map +1 -1
  56. package/dist/types/logic-engine.d.ts +9 -0
  57. package/dist/types/logic-engine.d.ts.map +1 -1
  58. package/dist/types/picked.d.ts +38 -8
  59. package/dist/types/picked.d.ts.map +1 -1
  60. package/dist/types/plugins/dynamic-experiences/index.d.ts +1 -0
  61. package/dist/types/plugins/dynamic-experiences/index.d.ts.map +1 -1
  62. package/dist/types/plugins/dynamic-experiences/plugin.d.ts.map +1 -1
  63. package/dist/types/plugins/dynamic-experiences/types.d.ts +5 -2
  64. package/dist/types/plugins/dynamic-experiences/types.d.ts.map +1 -1
  65. package/dist/types/plugins/experience-browser-storage/plugin.d.ts.map +1 -1
  66. package/dist/types/plugins/telemetry/plugin.d.ts +2 -0
  67. package/dist/types/plugins/telemetry/plugin.d.ts.map +1 -1
  68. package/dist/types/schema-registry.d.ts +34 -0
  69. package/dist/types/schema-registry.d.ts.map +1 -1
  70. package/dist/types/server/serialize.d.ts +1 -0
  71. package/dist/types/server/serialize.d.ts.map +1 -1
  72. package/dist/types/storage.d.ts +6 -0
  73. package/dist/types/storage.d.ts.map +1 -0
  74. package/dist/types/typed-content.d.ts +14 -1
  75. package/dist/types/typed-content.d.ts.map +1 -1
  76. package/dist/types/utils/events.d.ts +4 -0
  77. package/dist/types/utils/events.d.ts.map +1 -1
  78. package/dist/types/utils/rules-logic.d.ts +3 -2
  79. package/dist/types/utils/rules-logic.d.ts.map +1 -1
  80. package/dist/types/utils/search-params.d.ts +20 -0
  81. package/dist/types/utils/search-params.d.ts.map +1 -1
  82. package/package.json +39 -13
  83. package/dist/api-Ctvh1qkk.cjs +0 -1
  84. package/dist/docs/_root.css +0 -101
  85. package/dist/docs/explanation/conditions-and-the-logic-engine.md +0 -94
  86. package/dist/docs/explanation/content-references.md +0 -99
  87. package/dist/docs/explanation/feature-flag-allocation.md +0 -218
  88. package/dist/docs/explanation/how-picked-works.md +0 -124
  89. package/dist/docs/explanation/how-pickedql-works.md +0 -76
  90. package/dist/docs/explanation/pages-and-flows.md +0 -64
  91. package/dist/docs/explanation/the-content-model.md +0 -87
  92. package/dist/docs/explanation/the-two-apis.md +0 -68
  93. package/dist/docs/explanation/why-server-side-rendering.md +0 -76
  94. package/dist/docs/explanation/workspaces-and-versions.md +0 -71
  95. package/dist/docs/how-to/add-a-step-field-or-action.md +0 -43
  96. package/dist/docs/how-to/analytics/index.md +0 -316
  97. package/dist/docs/how-to/archive-or-delete-a-workspace.md +0 -46
  98. package/dist/docs/how-to/authenticate-the-cli.md +0 -97
  99. package/dist/docs/how-to/authenticate-with-a-magic-link.md +0 -40
  100. package/dist/docs/how-to/authenticate-with-a-password.md +0 -51
  101. package/dist/docs/how-to/authenticate-with-an-api-key.md +0 -51
  102. package/dist/docs/how-to/authenticate-with-oauth.md +0 -40
  103. package/dist/docs/how-to/build-a-flow.md +0 -83
  104. package/dist/docs/how-to/connect-the-mcp-server.md +0 -38
  105. package/dist/docs/how-to/create-a-content-entry.md +0 -48
  106. package/dist/docs/how-to/create-a-project.md +0 -29
  107. package/dist/docs/how-to/create-an-experience.md +0 -42
  108. package/dist/docs/how-to/create-and-revoke-an-api-key.md +0 -42
  109. package/dist/docs/how-to/debug-with-the-chrome-extension.md +0 -57
  110. package/dist/docs/how-to/define-a-page-layout.md +0 -46
  111. package/dist/docs/how-to/fill-and-publish-a-page.md +0 -66
  112. package/dist/docs/how-to/install-the-gtm-template.md +0 -84
  113. package/dist/docs/how-to/install-the-sdk.md +0 -93
  114. package/dist/docs/how-to/install-the-vite-plugin.md +0 -69
  115. package/dist/docs/how-to/invite-and-remove-members.md +0 -35
  116. package/dist/docs/how-to/point-one-entry-at-another.md +0 -61
  117. package/dist/docs/how-to/preview-a-workspace.md +0 -28
  118. package/dist/docs/how-to/publish-a-workspace.md +0 -30
  119. package/dist/docs/how-to/read-a-feature-flag.md +0 -113
  120. package/dist/docs/how-to/read-a-referenced-entry.md +0 -109
  121. package/dist/docs/how-to/register-a-component.md +0 -55
  122. package/dist/docs/how-to/register-an-action-handler.md +0 -67
  123. package/dist/docs/how-to/render-a-step-form.md +0 -131
  124. package/dist/docs/how-to/render-an-unpublished-preview.md +0 -41
  125. package/dist/docs/how-to/reuse-a-section.md +0 -53
  126. package/dist/docs/how-to/reuse-a-step-field-or-action.md +0 -28
  127. package/dist/docs/how-to/roll-back-a-published-version.md +0 -26
  128. package/dist/docs/how-to/run-an-ab-test.md +0 -49
  129. package/dist/docs/how-to/run-code-on-a-form-submission.md +0 -125
  130. package/dist/docs/how-to/server-render-a-page.md +0 -81
  131. package/dist/docs/how-to/set-a-content-security-policy.md +0 -32
  132. package/dist/docs/how-to/set-up-mfa.md +0 -69
  133. package/dist/docs/how-to/switch-workspaces.md +0 -122
  134. package/dist/docs/how-to/upload-and-use-an-asset.mdx +0 -73
  135. package/dist/docs/how-to/validate-a-field.md +0 -52
  136. package/dist/docs/how-to/write-a-condition.md +0 -45
  137. package/dist/docs/how-to/write-a-predicate.md +0 -60
  138. package/dist/docs/index.md +0 -59
  139. package/dist/docs/reference/dashboard/actions.mdx +0 -53
  140. package/dist/docs/reference/dashboard/api-keys.mdx +0 -38
  141. package/dist/docs/reference/dashboard/conditions.mdx +0 -42
  142. package/dist/docs/reference/dashboard/content/asset-library.mdx +0 -63
  143. package/dist/docs/reference/dashboard/content/blocks.mdx +0 -57
  144. package/dist/docs/reference/dashboard/content/content-entries.mdx +0 -95
  145. package/dist/docs/reference/dashboard/content/models.mdx +0 -108
  146. package/dist/docs/reference/dashboard/content/pages.mdx +0 -61
  147. package/dist/docs/reference/dashboard/experiences.mdx +0 -51
  148. package/dist/docs/reference/dashboard/features.mdx +0 -154
  149. package/dist/docs/reference/dashboard/fields.mdx +0 -106
  150. package/dist/docs/reference/dashboard/flow-builder/canvas.mdx +0 -58
  151. package/dist/docs/reference/dashboard/flow-builder/condition-builder.md +0 -57
  152. package/dist/docs/reference/dashboard/flow-builder/keyboard-shortcuts.md +0 -72
  153. package/dist/docs/reference/dashboard/flow-builder/nodes.md +0 -63
  154. package/dist/docs/reference/dashboard/projects.mdx +0 -44
  155. package/dist/docs/reference/dashboard/reports.mdx +0 -43
  156. package/dist/docs/reference/dashboard/steps.mdx +0 -37
  157. package/dist/docs/reference/dashboard/team-management.md +0 -29
  158. package/dist/docs/reference/dashboard/workspace-versioning.mdx +0 -30
  159. package/dist/docs/reference/dashboard/workspaces.mdx +0 -76
  160. package/dist/docs/reference/delivery-api/experience-content.md +0 -152
  161. package/dist/docs/reference/delivery-api/index.md +0 -45
  162. package/dist/docs/reference/delivery-api/preview-caching-crawling.md +0 -79
  163. package/dist/docs/reference/delivery-api/project-config.md +0 -65
  164. package/dist/docs/reference/delivery-api/workspace-schema.md +0 -85
  165. package/dist/docs/reference/glossary.md +0 -181
  166. package/dist/docs/reference/management-api/authentication.md +0 -74
  167. package/dist/docs/reference/management-api/authorization-and-scopes.md +0 -285
  168. package/dist/docs/reference/management-api/error-handling.md +0 -233
  169. package/dist/docs/reference/management-api/pagination.md +0 -192
  170. package/dist/docs/reference/pickedql/data-sources.md +0 -174
  171. package/dist/docs/reference/pickedql/dimensions.md +0 -103
  172. package/dist/docs/reference/pickedql/filtering.md +0 -64
  173. package/dist/docs/reference/pickedql/index.md +0 -18
  174. package/dist/docs/reference/pickedql/schema.md +0 -172
  175. package/dist/docs/reference/pickedql/virtual-functions.md +0 -248
  176. package/dist/docs/reference/sdk/actions.md +0 -30
  177. package/dist/docs/reference/sdk/analytics-events.md +0 -445
  178. package/dist/docs/reference/sdk/conditions.md +0 -147
  179. package/dist/docs/reference/sdk/content-security-policy.md +0 -21
  180. package/dist/docs/reference/sdk/content.md +0 -213
  181. package/dist/docs/reference/sdk/experiences.md +0 -51
  182. package/dist/docs/reference/sdk/features.md +0 -256
  183. package/dist/docs/reference/sdk/fields.md +0 -255
  184. package/dist/docs/reference/sdk/index.md +0 -68
  185. package/dist/docs/reference/sdk/plugins/create-experience.md +0 -123
  186. package/dist/docs/reference/sdk/plugins/dynamic-experiences.md +0 -74
  187. package/dist/docs/reference/sdk/plugins/index.md +0 -29
  188. package/dist/docs/reference/sdk/plugins/window-object.md +0 -25
  189. package/dist/docs/reference/sdk/predicates.md +0 -43
  190. package/dist/docs/reference/sdk/ssr/index.md +0 -33
  191. package/dist/docs/reference/sdk/ssr/rendering-and-hydration.md +0 -103
  192. package/dist/docs/reference/sdk/ssr/serialize.md +0 -80
  193. package/dist/docs/reference/sdk/ssr/slots-and-placements.md +0 -59
  194. package/dist/docs/reference/sdk/steps.md +0 -86
  195. package/dist/docs/reference/sdk/type-generation.md +0 -196
  196. package/dist/docs/reference/tools/chrome-extension.md +0 -16
  197. package/dist/docs/reference/tools/cli.md +0 -146
  198. package/dist/docs/reference/tools/image-optimisation-service.md +0 -104
  199. package/dist/docs/reference/tools/mcp.md +0 -90
  200. package/dist/docs/reference/tools/vite-plugin.md +0 -163
  201. package/dist/docs/tutorials/first-api-call.md +0 -228
  202. package/dist/docs/tutorials/first-experience-in-the-dashboard.mdx +0 -143
  203. package/dist/docs/tutorials/first-experience.mdx +0 -254
  204. package/dist/docs/tutorials/first-server-rendered-page.mdx +0 -186
  205. package/dist/dom-DlLH3FxV.cjs +0 -1
  206. package/dist/experience-instance-D8rOg6We.cjs +0 -1
  207. package/dist/plugin-ChafFq6S.js +0 -194
  208. package/dist/plugin-Dn25Gffy.cjs +0 -1
  209. package/dist/preview-channel-Cx0e6fye.cjs +0 -1
  210. package/dist/provider-B8wvmeC8.js +0 -98
  211. package/dist/provider-BBLlQOjV.cjs +0 -1
  212. package/dist/rules-logic-CGZIYgAI.cjs +0 -1
  213. package/dist/version-CLjPfmxk.cjs +0 -1
@@ -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.
@@ -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)