@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,285 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- # Authorization and scopes
7
-
8
- The Picked API controls access with scopes. Every authenticated caller carries a set
9
- of scopes, and those scopes decide which operations the caller can do. A caller is
10
- either a user with a session or an API key. This guide covers the scopes, the roles,
11
- and how the API resolves a permission.
12
-
13
- ## The format of a scope name
14
-
15
- A scope has the form `resource/action`:
16
-
17
- ```
18
- organization/read
19
- organization_members/create
20
- organization_projects/delete
21
- ```
22
-
23
- - **resource** — a lowercase name. It uses an underscore between words, as in
24
- `organization_members` and `organization_api_keys`.
25
- - **action** — one of `create`, `read`, `update`, or `delete`.
26
-
27
- The GraphQL schema holds the scopes in the `Scope` enum. There they are uppercase
28
- with an underscore between words, as in `ORGANIZATION_READ` and
29
- `ORGANIZATION_MEMBERS_CREATE`. The two forms name the same scope.
30
-
31
- ## Full scope list
32
-
33
- These are the scopes:
34
-
35
- ### Organization
36
-
37
- | Scope | GraphQL Enum | Description |
38
- |-------|-------------|-------------|
39
- | `organization/create` | `ORGANIZATION_CREATE` | Create an organization |
40
- | `organization/read` | `ORGANIZATION_READ` | Read the detail of an organization |
41
- | `organization/update` | `ORGANIZATION_UPDATE` | Update the name, the slug, and the settings of an organization |
42
- | `organization/delete` | `ORGANIZATION_DELETE` | Delete an organization |
43
-
44
- ### Organization members
45
-
46
- | Scope | GraphQL Enum | Description |
47
- |-------|-------------|-------------|
48
- | `organization_members/create` | `ORGANIZATION_MEMBERS_CREATE` | Add a member to an organization |
49
- | `organization_members/read` | `ORGANIZATION_MEMBERS_READ` | Read the member list of an organization |
50
- | `organization_members/update` | `ORGANIZATION_MEMBERS_UPDATE` | Update the role of a member |
51
- | `organization_members/delete` | `ORGANIZATION_MEMBERS_DELETE` | Remove a member from an organization |
52
-
53
- ### Organization invitations
54
-
55
- | Scope | GraphQL Enum | Description |
56
- |-------|-------------|-------------|
57
- | `organization_invitations/create` | `ORGANIZATION_INVITATIONS_CREATE` | Send an invitation to join an organization |
58
- | `organization_invitations/read` | `ORGANIZATION_INVITATIONS_READ` | Read the invitations that wait for an answer |
59
- | `organization_invitations/delete` | `ORGANIZATION_INVITATIONS_DELETE` | Revoke an invitation that waits for an answer |
60
-
61
- ### Organization projects
62
-
63
- | Scope | GraphQL Enum | Description |
64
- |-------|-------------|-------------|
65
- | `organization_projects/create` | `ORGANIZATION_PROJECTS_CREATE` | Create a project |
66
- | `organization_projects/read` | `ORGANIZATION_PROJECTS_READ` | Read the detail of a project |
67
- | `organization_projects/update` | `ORGANIZATION_PROJECTS_UPDATE` | Update the settings of a project |
68
- | `organization_projects/delete` | `ORGANIZATION_PROJECTS_DELETE` | Delete a project |
69
-
70
- ### Organization API keys
71
-
72
- | Scope | GraphQL Enum | Description |
73
- |-------|-------------|-------------|
74
- | `organization_api_keys/create` | `ORGANIZATION_API_KEYS_CREATE` | Create an API key |
75
- | `organization_api_keys/read` | `ORGANIZATION_API_KEYS_READ` | Read the API keys. This gives the prefix only, and not the full key. |
76
- | `organization_api_keys/delete` | `ORGANIZATION_API_KEYS_DELETE` | Revoke an API key |
77
-
78
- ### Organization integrations
79
-
80
- | Scope | GraphQL Enum | Description |
81
- |-------|-------------|-------------|
82
- | `organization_integrations/create` | `ORGANIZATION_INTEGRATIONS_CREATE` | Set up an integration |
83
- | `organization_integrations/read` | `ORGANIZATION_INTEGRATIONS_READ` | Read the options of an integration |
84
- | `organization_integrations/update` | `ORGANIZATION_INTEGRATIONS_UPDATE` | Change the settings of an integration |
85
- | `organization_integrations/delete` | `ORGANIZATION_INTEGRATIONS_DELETE` | Remove an integration |
86
-
87
- ### Organization reports
88
-
89
- | Scope | GraphQL Enum | Description |
90
- |-------|-------------|-------------|
91
- | `organization_reports/create` | `ORGANIZATION_REPORTS_CREATE` | Create a report |
92
- | `organization_reports/read` | `ORGANIZATION_REPORTS_READ` | Read a report |
93
- | `organization_reports/update` | `ORGANIZATION_REPORTS_UPDATE` | Update the settings of a report |
94
- | `organization_reports/delete` | `ORGANIZATION_REPORTS_DELETE` | Delete a report |
95
-
96
- ## Roles
97
-
98
- Each member of an organization holds one of two roles:
99
-
100
- ### Owner
101
-
102
- An owner has full control inside the organization. These are the default scopes of an
103
- owner:
104
-
105
- - All `organization/*` scopes (`read`, `update`, `delete`)
106
- - All `organization_members/*` scopes
107
- - All `organization_invitations/*` scopes
108
- - `organization_projects/read`, `organization_projects/update`, `organization_projects/delete`
109
- - All `organization_api_keys/*` scopes
110
- - All `organization_integrations/*` scopes
111
- - `organization_reports/read`
112
-
113
- ### Member
114
-
115
- A member can reach most things, but cannot delete the organization and cannot control
116
- another member. These are the default scopes of a member:
117
-
118
- - `organization/read`, `organization/update`
119
- - `organization_members/read`
120
- - `organization_invitations/read`
121
- - `organization_projects/read`, `organization_projects/update`, `organization_projects/delete`
122
- - All `organization_api_keys/*` scopes
123
- - All `organization_integrations/*` scopes
124
- - `organization_reports/read`
125
-
126
- These are the differences between an owner and a member:
127
-
128
- | Capability | Owner | Member |
129
- |-----------|-------|--------|
130
- | Delete the organization | Yes | No |
131
- | Invite new members | Yes | No |
132
- | Remove members | Yes | No |
133
- | Update member roles | Yes | No |
134
- | Revoke invitations | Yes | No |
135
- | Control projects and integrations | Yes | Yes |
136
- | Control API keys | Yes | Yes |
137
- | Read reports | Yes | Yes |
138
-
139
- ## How scopes are resolved
140
-
141
- When an authenticated request reaches the API, the API resolves the scopes like this:
142
-
143
- 1. **A user with a session** — the API finds the role of that caller in the target
144
- organization. It then gives the caller the default scopes of that role.
145
- 2. **A request with an API key** — the API uses the scopes that the key received when
146
- somebody created it. Those scopes are always scopes of the user who created the
147
- key.
148
-
149
- Most queries and mutations point at one organization. For those, the caller must hold
150
- the scope inside that organization. For a root-level operation such as
151
- `organizationCreate`, the API resolves the scope at the account level.
152
-
153
- When the caller does not hold the scope that an operation needs, the API returns an
154
- authorization error with the code `FORBIDDEN`. See [Errors](/reference/management-api/error-handling).
155
-
156
- ## Operations and required scopes
157
-
158
- This table gives the scope that each common operation needs:
159
-
160
- ### Queries
161
-
162
- | Query | Required Scope |
163
- |-------|---------------|
164
- | `organization` | `organization/read` |
165
- | `organizations` | `organization/read` |
166
- | `project` | `organization_projects/read` |
167
- | `apiKeys` | `organization_api_keys/read` |
168
- | `shopifyWebhooks` | `organization_integrations/read` |
169
- | `shopifyMetafieldConfigs` | `organization_integrations/read` |
170
- | `shopifyProduct` / `shopifyProducts` | `organization_integrations/read` |
171
- | `report` | `organization_reports/read` |
172
-
173
- ### Mutations
174
-
175
- | Mutation | Required Scope |
176
- |----------|---------------|
177
- | `organizationCreate` | `organization/create` |
178
- | `organizationUpdate` | `organization/update` |
179
- | `organizationDelete` | `organization/delete` |
180
- | `organizationMemberInvite` | `organization_invitations/create` |
181
- | `organizationInvitationRevoke` | `organization_invitations/delete` |
182
- | `organizationMemberRemove` | `organization_members/delete` |
183
- | `organizationMemberRoleUpdate` | `organization_members/update` |
184
- | `projectCreate` | `organization_projects/create` |
185
- | `apiKeyCreate` | `organization_api_keys/create` |
186
- | `apiKeyRevoke` | `organization_api_keys/delete` |
187
- | `shopifyWebhookCreate` | `organization_integrations/create` |
188
- | `shopifyWebhookUpdate` | `organization_integrations/update` |
189
- | `shopifyWebhookDelete` | `organization_integrations/delete` |
190
- | `shopifyMetafieldConfigCreate` | `organization_integrations/create` |
191
- | `shopifyMetafieldConfigUpdate` | `organization_integrations/update` |
192
- | `shopifyMetafieldConfigDelete` | `organization_integrations/delete` |
193
- | `reportCreate` | `organization_reports/create` |
194
- | `reportUpdate` | `organization_reports/update` |
195
- | `reportDelete` | `organization_reports/delete` |
196
-
197
- Some mutations do not require organization-level scopes because they operate on the caller's own data:
198
-
199
- | Mutation | Requirement |
200
- |----------|------------|
201
- | `sessionCreate` / `sessionRefresh` | No authentication required |
202
- | `accountCreate` / `accountVerifyEmail` | No authentication required |
203
- | `oauthAuthorize` / `oauthCallback` | No authentication required |
204
- | `magicLinkSend` / `magicLinkVerify` | No authentication required |
205
- | `passwordResetSend` / `passwordReset` | No authentication required |
206
- | `passwordUpdate` | Authenticated session (no specific scope) |
207
- | `organizationInvitationAccept` / `organizationInvitationDecline` | Authenticated session (no specific scope) |
208
- | `mfaFactorEnroll` / `mfaChallengeSend` / `mfaChallengeVerify` / `mfaFactorUnenroll` | Authenticated session (no specific scope) |
209
-
210
- ## Read your scopes
211
-
212
- ### Root-level scopes
213
-
214
- The `viewerScopes` query returns the root-level scopes for the authenticated caller:
215
-
216
- ```graphql
217
- query {
218
- viewerScopes
219
- }
220
- ```
221
-
222
- Response:
223
-
224
- ```json
225
- {
226
- "data": {
227
- "viewerScopes": [
228
- "ORGANIZATION_CREATE"
229
- ]
230
- }
231
- }
232
- ```
233
-
234
- ### Organization-level scopes
235
-
236
- Each `Organization` object exposes a `viewerScopes` field that returns the scopes the caller has within that specific organization:
237
-
238
- ```graphql
239
- query {
240
- organization(input: { slug: "my-company" }) {
241
- id
242
- name
243
- viewerScopes
244
- }
245
- }
246
- ```
247
-
248
- Response:
249
-
250
- ```json
251
- {
252
- "data": {
253
- "organization": {
254
- "id": "org_abc123",
255
- "name": "My Company",
256
- "viewerScopes": [
257
- "ORGANIZATION_READ",
258
- "ORGANIZATION_UPDATE",
259
- "ORGANIZATION_MEMBERS_READ",
260
- "ORGANIZATION_PROJECTS_READ",
261
- "ORGANIZATION_PROJECTS_UPDATE",
262
- "ORGANIZATION_PROJECTS_DELETE",
263
- "ORGANIZATION_API_KEYS_CREATE",
264
- "ORGANIZATION_API_KEYS_READ",
265
- "ORGANIZATION_API_KEYS_DELETE",
266
- "ORGANIZATION_INTEGRATIONS_CREATE",
267
- "ORGANIZATION_INTEGRATIONS_READ",
268
- "ORGANIZATION_INTEGRATIONS_UPDATE",
269
- "ORGANIZATION_INTEGRATIONS_DELETE",
270
- "ORGANIZATION_REPORTS_READ"
271
- ]
272
- }
273
- }
274
- }
275
- ```
276
-
277
- Use this to build a UI that changes with the permissions of the caller. An example is
278
- a **Delete Organization** button that the UI hides when the caller does not hold
279
- `ORGANIZATION_DELETE`.
280
-
281
- ## Related
282
-
283
- - [Authentication](/reference/management-api/authentication)
284
- - [How to authenticate with an API key](/how-to/authenticate-with-an-api-key)
285
- - [API keys](/reference/dashboard/api-keys) — the dashboard surface.
@@ -1,233 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- # Errors
7
-
8
- The Picked API returns an error in the standard GraphQL format. This guide covers the
9
- shape of an error response, every error code, and what your code must do with each
10
- one.
11
-
12
- ## Error response shape
13
-
14
- When an operation fails, the API returns an `errors` array in the response body. Each
15
- error object holds these fields:
16
-
17
- ```json
18
- {
19
- "data": null,
20
- "errors": [
21
- {
22
- "message": "A human-readable description of the error",
23
- "path": ["mutationName"],
24
- "extensions": {
25
- "code": "ERROR_CODE"
26
- }
27
- }
28
- ]
29
- }
30
- ```
31
-
32
- | Field | Description |
33
- |-------|-------------|
34
- | `message` | A description of the error that a person can read. Put it in your log. Do not write code against it. |
35
- | `path` | The path to the field in the query that made the error. |
36
- | `extensions.code` | An error code that a machine can read. Write your code against this field. |
37
-
38
- One response can hold more than one error. The `data` field is `null` when the whole
39
- operation failed. It holds part of the data when only some fields failed.
40
-
41
- ## Authentication error codes
42
-
43
- These errors come from a session, an account, OAuth, a magic link, a password
44
- operation, or MFA. They match the `AuthErrorCode` enum in the schema.
45
-
46
- | Code | Description |
47
- |------|-------------|
48
- | `INVALID_CREDENTIALS` | The email address and the password do not match. |
49
- | `EMAIL_NOT_CONFIRMED` | The account is there, but nobody verified the email address. See [Authentication](/reference/management-api/authentication#the-mutations). |
50
- | `USER_NOT_FOUND` | There is no account with that email address. |
51
- | `USER_ALREADY_EXISTS` | An account with that email address is there already. The API returns this when you create an account. |
52
- | `WEAK_PASSWORD` | The password is not strong enough. |
53
- | `INVALID_TOKEN` | The token is invalid or malformed. This covers a verification token, a reset token, and a magic link token. |
54
- | `TOKEN_EXPIRED` | The token expired. Ask for a new one. |
55
- | `MFA_CHALLENGE_FAILED` | The MFA verification code is not correct. |
56
- | `MFA_FACTOR_NOT_FOUND` | That MFA factor is not there, or it belongs to another caller. |
57
- | `OAUTH_PROVIDER_ERROR` | The exchange with the OAuth provider, such as Google, failed. |
58
- | `RATE_LIMITED` | Too many requests in a short period. Wait, then try again. |
59
-
60
- ### Example: invalid credentials
61
-
62
- ```json
63
- {
64
- "data": {
65
- "sessionCreate": {
66
- "session": null,
67
- "requiresMfa": false,
68
- "mfaFactors": null
69
- }
70
- },
71
- "errors": [
72
- {
73
- "message": "Invalid credentials",
74
- "path": ["sessionCreate"],
75
- "extensions": {
76
- "code": "INVALID_CREDENTIALS"
77
- }
78
- }
79
- ]
80
- }
81
- ```
82
-
83
- ## Authorization error codes
84
-
85
- An authorization error happens when the caller does not hold the
86
- [scope](/reference/management-api/authorization-and-scopes) that an operation needs.
87
-
88
- | Code | Description |
89
- |------|-------------|
90
- | `UNAUTHORIZED` | The request carries no valid authentication. It has no `Authorization` header and no `x-api-key` header, or the token is invalid. |
91
- | `FORBIDDEN` | The caller is authenticated, but it does not hold the scope that the operation needs. |
92
-
93
- ### Example: the scope is not enough
94
-
95
- A caller that holds `organization/read` only tries to delete an organization. It
96
- receives this:
97
-
98
- ```json
99
- {
100
- "data": {
101
- "organizationDelete": null
102
- },
103
- "errors": [
104
- {
105
- "message": "Insufficient permissions",
106
- "path": ["organizationDelete"],
107
- "extensions": {
108
- "code": "FORBIDDEN"
109
- }
110
- }
111
- ]
112
- }
113
- ```
114
-
115
- ## Organization, member, and invitation error codes
116
-
117
- These errors come from an organization, a member operation, or an invitation. They
118
- match the `ErrorCode` enum in the schema.
119
-
120
- ### Organization errors
121
-
122
- | Code | Description |
123
- |------|-------------|
124
- | `ORGANIZATION_NOT_FOUND` | That organization is not there, or the caller cannot reach it. |
125
- | `ORGANIZATION_ALREADY_EXISTS` | An organization with that name is there already. |
126
- | `SLUG_ALREADY_EXISTS` | Another organization uses that slug already. |
127
- | `INVALID_SLUG` | The slug holds an invalid character. A slug takes lowercase letters, digits, and hyphens only. |
128
-
129
- ### Member errors
130
-
131
- | Code | Description |
132
- |------|-------------|
133
- | `MEMBER_NOT_FOUND` | That user is not a member of the organization. |
134
- | `MEMBER_ALREADY_EXISTS` | The user is a member of the organization already. |
135
- | `CANNOT_REMOVE_PRIMARY_OWNER` | You cannot remove the primary owner of an organization. |
136
- | `CANNOT_CHANGE_OWN_ROLE` | A member cannot change the role of that same member. Another owner must do it. |
137
-
138
- ### Invitation errors
139
-
140
- | Code | Description |
141
- |------|-------------|
142
- | `INVITATION_NOT_FOUND` | That invitation is not there. |
143
- | `INVITATION_EXPIRED` | The invitation expired. Nobody can accept it now. |
144
- | `INVITATION_ALREADY_ACCEPTED` | Somebody accepted the invitation already. |
145
-
146
- ### Project errors
147
-
148
- | Code | Description |
149
- |------|-------------|
150
- | `PROJECT_NOT_FOUND` | That project is not there, or the caller cannot reach it. |
151
-
152
- ### General errors
153
-
154
- | Code | Description |
155
- |------|-------------|
156
- | `VALIDATION_ERROR` | The input failed a validation rule. Read the `message` field to learn which field is invalid. |
157
- | `INTERNAL_ERROR` | The server met an unexpected error. Try the request again. Contact support when the error continues. |
158
-
159
- ## What your code must do
160
-
161
- ### Look for an error first
162
-
163
- Check every response for an `errors` array before you read `data`:
164
-
165
- ```javascript
166
- const response = await fetch('/graphql', {
167
- method: 'POST',
168
- headers: {
169
- 'Content-Type': 'application/json',
170
- 'Authorization': `Bearer ${accessToken}`,
171
- },
172
- body: JSON.stringify({ query, variables }),
173
- });
174
-
175
- const result = await response.json();
176
-
177
- if (result.errors) {
178
- for (const error of result.errors) {
179
- const code = error.extensions?.code;
180
-
181
- switch (code) {
182
- case 'UNAUTHORIZED':
183
- // Send the user to the sign-in page.
184
- break;
185
- case 'FORBIDDEN':
186
- // Show a permissions error.
187
- break;
188
- case 'RATE_LIMITED':
189
- // Wait, then try again.
190
- break;
191
- default:
192
- // Put the message in the log, or show it.
193
- console.error(error.message);
194
- }
195
- }
196
- }
197
- ```
198
-
199
- ### Refresh a token that expired
200
-
201
- A request can return `UNAUTHORIZED` while the caller holds a refresh token. Try a
202
- [session refresh](/reference/management-api/authentication#the-mutations) first. Do not treat it as a
203
- failure to sign in:
204
-
205
- ```javascript
206
- if (code === 'UNAUTHORIZED' && refreshToken) {
207
- const refreshResult = await sessionRefresh(refreshToken);
208
- if (refreshResult.session) {
209
- // Try the first request again with the new access token.
210
- } else {
211
- // Send the user to the sign-in page.
212
- }
213
- }
214
- ```
215
-
216
- ### Read data that is only part complete
217
-
218
- GraphQL can return part of the data together with an error. Take a query that reads
219
- an organization and its members. It can succeed for the organization and fail for the
220
- members, when the caller does not hold `organization_members/read`. The response then
221
- holds `data` with the organization, and `errors` for the members field. Always read
222
- both.
223
-
224
- ### Try again after a transient failure
225
-
226
- `INTERNAL_ERROR` and `RATE_LIMITED` are both transient. For `RATE_LIMITED`, use an
227
- exponential backoff before you try again. For `INTERNAL_ERROR`, one more try is
228
- usually enough.
229
-
230
- ## Related
231
-
232
- - [Authentication](/reference/management-api/authentication)
233
- - [Your first API call](/tutorials/first-api-call)
@@ -1,192 +0,0 @@
1
- ---
2
- type: reference
3
- layout: docs
4
- ---
5
-
6
- # Pagination
7
-
8
- The Picked API paginates every list field that can return a large result. It uses a
9
- cursor, in the Relay-style pattern. This guide covers the connection pattern and
10
- shows how to move through a result.
11
-
12
- ## Connection pattern
13
-
14
- A paginated field returns a **connection** object with this shape:
15
-
16
- ```graphql
17
- type ExampleConnection {
18
- edges: [ExampleEdge!]!
19
- pageInfo: PageInfo!
20
- totalCount: Int!
21
- }
22
-
23
- type ExampleEdge {
24
- cursor: String!
25
- node: Example!
26
- }
27
-
28
- type PageInfo {
29
- hasNextPage: Boolean!
30
- hasPreviousPage: Boolean!
31
- startCursor: String
32
- endCursor: String
33
- }
34
- ```
35
-
36
- | Field | Description |
37
- |-------|-------------|
38
- | `edges` | An ordered list of edges. Each edge holds a `cursor` and a `node`, and the `node` holds the data. |
39
- | `pageInfo.hasNextPage` | `true` when more results come after the last edge |
40
- | `pageInfo.hasPreviousPage` | `true` when results come before the first edge |
41
- | `pageInfo.startCursor` | The cursor of the first edge on the current page |
42
- | `pageInfo.endCursor` | The cursor of the last edge on the current page |
43
- | `totalCount` | The number of items on every page together |
44
-
45
- ## Forward pagination with `first` and `after`
46
-
47
- To move forward through the results, use two arguments. The `first` argument gives
48
- the page size. The `after` argument gives the cursor to start after.
49
-
50
- ### First page
51
-
52
- Leave the `after` argument out to read the first page:
53
-
54
- ```graphql
55
- query {
56
- organizations(input: { first: 10 }) {
57
- edges {
58
- cursor
59
- node {
60
- id
61
- name
62
- }
63
- }
64
- pageInfo {
65
- hasNextPage
66
- endCursor
67
- }
68
- totalCount
69
- }
70
- }
71
- ```
72
-
73
- ### Next page
74
-
75
- Pass the `endCursor` from the previous response as the `after` argument:
76
-
77
- ```graphql
78
- query {
79
- organizations(input: { first: 10, after: "cursor_from_previous_page" }) {
80
- edges {
81
- cursor
82
- node {
83
- id
84
- name
85
- }
86
- }
87
- pageInfo {
88
- hasNextPage
89
- endCursor
90
- }
91
- totalCount
92
- }
93
- }
94
- ```
95
-
96
- ## Check for more pages
97
-
98
- Read the `hasNextPage` field before you ask for the next page:
99
-
100
- - `hasNextPage: true` — more results are available. Pass `endCursor` as the `after`
101
- argument of the next request.
102
- - `hasNextPage: false` — you read every result. Stop here.
103
-
104
- ## Full paginated query example
105
-
106
- This example reads every member of an organization, one page at a time:
107
-
108
- ```graphql
109
- # Page 1
110
- query {
111
- organization(input: { slug: "my-company" }) {
112
- members(first: 20) {
113
- edges {
114
- cursor
115
- node {
116
- id
117
- userEmail
118
- role
119
- joinedAt
120
- }
121
- }
122
- pageInfo {
123
- hasNextPage
124
- endCursor
125
- }
126
- totalCount
127
- }
128
- }
129
- }
130
- ```
131
-
132
- If `pageInfo.hasNextPage` is `true`, fetch the next page:
133
-
134
- ```graphql
135
- # Page 2
136
- query {
137
- organization(input: { slug: "my-company" }) {
138
- members(first: 20, after: "cursor_from_page_1") {
139
- edges {
140
- cursor
141
- node {
142
- id
143
- userEmail
144
- role
145
- joinedAt
146
- }
147
- }
148
- pageInfo {
149
- hasNextPage
150
- endCursor
151
- }
152
- totalCount
153
- }
154
- }
155
- }
156
- ```
157
-
158
- Continue until `hasNextPage` returns `false`.
159
-
160
- ## Paginated fields
161
-
162
- These fields in the schema return a connection type. They all take the `first` and
163
- `after` arguments:
164
-
165
- | Parent Type | Field | Connection Type |
166
- |------------|-------|----------------|
167
- | `Query` | `organizations` | `OrganizationConnection` |
168
- | `User` | `organizations` | `OrganizationConnection` |
169
- | `User` | `invitations` | `ViewerInvitationConnection` |
170
- | `Organization` | `members` | `OrganizationMemberConnection` |
171
- | `Organization` | `invitations` | `OrganizationInvitationConnection` |
172
- | `Organization` | `projects` | `ProjectConnection` |
173
- | `Project` | `reports` | `ProjectReportConnection` |
174
-
175
- All of these fields accept the same `first` and `after` arguments and return the standard `edges`, `pageInfo`, and `totalCount` structure.
176
-
177
- ## Tips
178
-
179
- - **The default page size** — the API applies a default limit when you leave `first`
180
- out. Set `first` yourself to make sure that each page has the size you expect.
181
- - **A cursor is opaque** — treat a cursor string as an opaque token. Do not parse it,
182
- build it, or change it. Pass it back exactly as the API gave it.
183
- - **The order is stable** — a connection returns its results in a stable order. The
184
- same cursor always points at the same position in the result.
185
- - **Use them with other fields** — you can use the pagination arguments together with
186
- other query fields. One request that reads an organization and the first page of
187
- its members is common, and it is efficient.
188
-
189
- ## Related
190
-
191
- - [Your first API call](/tutorials/first-api-call)
192
- - [Authorization and scopes](/reference/management-api/authorization-and-scopes)