@picked/client 0.0.101-next.2 → 0.0.101

package/dist/docs/how-to/register-an-api-that-uses-oauth2.md

@@ -1,107 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to register an API that uses OAuth2
-
-This guide shows you how to let a workflow call an API whose access tokens expire, such as
-Zoho CRM. You need a client ID and a client secret from the provider. For the refresh token
-grant, you also need a refresh token.
-
-Picked keeps the credential, gets an access token from the provider, and sends the token
-with each request. Picked gets a new token before the old token expires.
-
-## 1. Make a refresh token in Zoho
-
-Do this step for Zoho CRM only. For another provider, get the credential from the
-provider's documentation.
-
-1. Open the Zoho API console for the region of your Zoho account.
-2. Add a client of the type `Self Client`.
-3. Make a grant code with the scopes that the workflow needs, such as
-   `ZohoCRM.modules.leads.CREATE`.
-4. Send a `POST` request to the token URL of your region, such as
-   `https://accounts.zoho.com.au/oauth/v2/token`. Put the parameters in the form body, not
-   in the URL. The parameters are `grant_type=authorization_code`, `client_id`,
-   `client_secret`, and `code` with the grant code. The grant code expires soon, so do this
-   step immediately.
-5. Keep the `refresh_token` from the answer.
-
-:::warning
-Make the refresh token as a Zoho user that only Picked uses. Zoho keeps 20 refresh tokens
-for each user and client. When you make one more, Zoho stops the oldest refresh token. That
-token can be the token that Picked uses.
-:::
-
-## 2. Register the external API
-
-1. Open **Integrations**.
-2. Choose **Configure external APIs**.
-3. Choose **New external API**.
-4. For Zoho CRM, set **Preset** to the region of your Zoho account. The preset sets the
-   **Display name**, the **Origin**, the **Credential** and the settings of the OAuth2
-   credential. Then go to step 10. If **Preset** does not show your region, do steps 5 to 9.
-5. Enter a **Display name**.
-6. Enter the **Origin**, such as `https://www.zohoapis.com.au`.
-7. Set **Credential** to **OAuth2 credential**.
-8. Enter the **Token URL** from the provider's documentation. Do not put a secret in the
-   token URL.
-9. Set the **Grant**, the **Client authentication** and the **Header scheme** from the
-   provider's documentation.
-10. Enter the **Client ID**.
-11. Enter the **Client secret**.
-12. For the refresh token grant, enter the **Refresh token**.
-13. Choose **Register external API**.
-
-The client secret and the refresh token are write-only. After you save them, Picked shows
-only that they are stored.
-
-## 3. Add a credential to an external API that you registered
-
-1. Open the external API.
-2. Choose **Use an OAuth2 credential**.
-3. For Zoho CRM, set **Preset** to the region of your Zoho account. For another provider,
-   do steps 8 and 9 of section 2.
-4. Do steps 10 to 12 of section 2.
-5. Choose **Save credential**.
-
-The credential replaces the authorization header of the external API.
-
-## 4. Refresh only for an expired token
-
-Some APIs answer 401 for an error that a new token does not correct. To get a new token only
-for an expired token:
-
-1. Open the external API.
-2. Choose **Edit OAuth2 credential**.
-3. In **401 rule: response body path**, enter the path of the error code in the 401 answer,
-   such as `code`. Put a dot between the parts of the path, for example `data.0.code`.
-4. In **401 rule: values**, enter the error codes that show an expired token, such as
-   `INVALID_TOKEN`.
-5. Choose **Save credential**.
-
-The Zoho CRM preset sets this rule for you.
-
-## 5. Replace a refresh token that the provider rejected
-
-When the provider rejects the credential, the external API page shows the reason in **Last
-refresh failure**. Each call fails with `credential_rejected` until you correct the
-credential.
-
-1. Make a new refresh token.
-2. Open the external API.
-3. Choose **Edit OAuth2 credential**.
-4. Enter the new **Refresh token**.
-5. Choose **Save credential**.
-
-Leave the **Client secret** empty to keep the stored client secret. If you change the
-**Token URL**, the **Client ID** or the **Client authentication**, enter the client secret
-and the refresh token again.
-
-## Related
-
-- [External APIs](/reference/dashboard/external-apis#oauth2-credential) — every setting of
-  an OAuth2 credential, and when Picked gets a new token.
-- [How to call an external API from a workflow](/how-to/call-an-external-api-from-a-workflow)
-  — the node that sends the request.

package/dist/docs/how-to/render-a-step-form.md

@@ -1,131 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to render a step form
-
-This guide shows you how to render the fields of the active step and let a visitor submit
-them.
-
-## 1. Put the steps in a router
-
-`StepRouter` watches the step state and activates the `Step` whose `id` matches.
-
-:::code-group
-
-```tsx [React]
-import { StepRouter, Step } from '@picked/react/router'
-
-function MyExperience() {
-  return (
-    <StepRouter>
-      <Step id="welcome">
-        <WelcomeScreen />
-      </Step>
-      <Step id="contact">
-        <ContactForm />
-      </Step>
-    </StepRouter>
-  )
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { StepRouter, Step } from '@picked/svelte/router'
-</script>
-
-<StepRouter>
-  <Step id="welcome">
-    <WelcomeScreen />
-  </Step>
-  <Step id="contact">
-    <ContactForm />
-  </Step>
-</StepRouter>
-```
-
-:::
-
-:::note
-A router must hold every Step, even when there is only one Step.
-:::
-
-## 2. Render the fields
-
-Bind `form.props` to your `<form>` element and map over the fields.
-
-:::code-group
-
-```tsx [React]
-import { useStep, useStoreGlobal } from '@picked/react/hooks'
-
-function StepForm() {
-  const { fields, form } = useStep()
-  const currentFields = useStoreGlobal(fields)
-  const isSubmitting = useStoreGlobal(form.submitting)
-
-  return (
-    <form {...form.props}>
-      {currentFields.map((field) => (
-        <div key={field.id}>
-          <label htmlFor={field.id}>{field.label}</label>
-          <input
-            id={field.id}
-            name={field.id}
-            value={field.value ?? ''}
-            onChange={field.onChange}
-            onBlur={field.onBlur}
-          />
-          {field.error && field.touched && <p className="error">{field.error.userMessage}</p>}
-        </div>
-      ))}
-      <button type="submit" disabled={isSubmitting}>Continue</button>
-    </form>
-  )
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getStep } from '@picked/svelte/hooks'
-
-  const { fields, form } = getStep()
-  const isSubmitting = form.submitting
-</script>
-
-<form {...form.props}>
-  {#each $fields as field}
-    <div>
-      <label for={field.id}>{field.label}</label>
-      <input
-        id={field.id}
-        name={field.id}
-        value={field.value ?? ''}
-        onchange={field.onChange}
-        onblur={field.onBlur}
-      />
-      {#if field.error && field.touched}
-        <p class="error">{field.error.userMessage}</p>
-      {/if}
-    </div>
-  {/each}
-  <button type="submit" disabled={$isSubmitting}>Continue</button>
-</form>
-```
-
-:::
-
-The SDK checks a field on blur, and not while the visitor types.
-
-## 3. Load a large step lazily
-
-Pass a dynamic import to the `component` prop of `<Step>`. The SDK does not load the
-content until that step becomes active.
-
-## Related
-
-- [How to run code on a form submission](/how-to/run-code-on-a-form-submission) — the
-  callbacks.
-- [SDK steps](/reference/sdk/steps) — the `StepContext` shape.

package/dist/docs/how-to/render-an-unpublished-preview.md

@@ -1,41 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to render an unpublished preview
-
-This guide shows you how to render draft content on your server. Your server cannot read
-the query string of the browser, so you must pass the token yourself.
-
-## 1. Get the token
-
-The management API holds the preview token of a workspace in the `previewToken` field. The
-preview action in the dashboard also makes one for you.
-
-## 2. Read the config with the token
-
-```bash
-curl "https://api.picked.app/api/v1/projects/proj_123?preview_token=<token>"
-```
-
-A preview response returns `versionId: null`. An invalid token returns `401`.
-
-## 3. Pass the same token to `serialize()`
-
-```ts
-const snapshot = await serialize(client, {
-  projectConfig,
-  attributes: { location: { pathname: '/promo' } },
-  previewToken,
-})
-```
-
-Use the same token for both requests. The configuration and the content then come from the same
-preview.
-
-## Related
-
-- [About the two APIs](/explanation/the-two-apis) — how a preview stays out of the search
-  index.
-- [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling).

package/dist/docs/how-to/retry-a-failed-call-with-a-loop.md

@@ -1,81 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to retry a failed call with a loop
-
-This guide shows you how to make a workflow send a request again after the request fails.
-The workflow waits before each new try. It stops after a number of tries that you set.
-
-You need a workflow with an **External API** node first. Refer to
-[How to call an external API from a workflow](/how-to/call-an-external-api-from-a-workflow).
-
-## The loop
-
-A loop is a path of edges that goes back to a node that the run reached before. This loop
-has three nodes:
-
-| Node                | Function                                         |
-| ------------------- | ------------------------------------------------ |
-| External API `send` | Sends the request.                               |
-| Condition `check`   | Decides if the workflow sends the request again. |
-| Sleep `pause`       | Waits before the next try.                       |
-
-When you save a workflow, Picked refuses a loop that does not have a sleep node and a
-condition node on it. Picked also refuses an edge from a node to the same node.
-
-## 1. Connect the error exit to a condition
-
-1. Open the workflow.
-2. Choose **Add condition** on the error exit of `send`.
-3. In the rule of `check`, test `{{ nodes.send.error.retryable }}`.
-4. Connect the `false` exit of `check` to the nodes that record the failure.
-
-`check` runs only when the call fails. The rule can then read the error of the last try.
-
-## 2. Add the sleep node
-
-1. Choose **Add sleep** on the `true` exit of `check`.
-2. Set **Wait for** to the time between two tries.
-3. Connect the exit of `pause` to the input of `send`.
-
-The editor shows a loop as an edge that goes back to `send`.
-
-## 3. Set the number of tries
-
-Each node in the loop runs one time for each try. A run can visit one node a maximum
-number of times. This number is the visit cap of the workflow.
-
-1. Open the workflow settings.
-2. Set **Visit cap** to a number from 1 to 100. If you do not set it, the visit cap is 10.
-
-A node can get to the visit cap. If the run then gets to the node again, the run stops.
-The run shows `Failed` with the code `loop_limit_reached`.
-
-To stop the loop before the visit cap, test `current.visit` in the rule of `check`.
-Its value is the number of the visit to `check`. This is also the number of failed tries.
-This rule tries a maximum of 3 times:
-
-```json
-{
-  "and": [{ "var": "nodes.send.error.retryable" }, { "<": ["{{ current.visit }}", 3] }]
-}
-```
-
-With this rule, the run continues on the `false` exit of `check` after 3 failures.
-
-## 4. Read the result
-
-A node reads the last visit of another node. After the loop, `{{ nodes.send.status }}`
-gives the status of the last try.
-
-The **Tasks** card of the run shows each visit as a task. Refer to the
-[Workflow runs reference](/reference/dashboard/workflow-runs#tasks).
-
-## Related
-
-- [Workflow runs](/reference/dashboard/workflow-runs) — the tasks of each visit, and the
-  visit cap.
-- [Workflow templates](/reference/dashboard/workflow-templates) — the data that a node
-  reads in a loop.

package/dist/docs/how-to/reuse-a-section.md

@@ -1,53 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to reuse a section
-
-This guide shows you how to define a common structure one time and use it in more than
-one Model.
-
-## 1. Create the section
-
-1. Click **Pages** in the sidebar.
-2. Click **Page Sections**.
-3. Click **New block**.
-4. Enter a **Name** and a **Key**.
-5. Add your fields.
-6. Click **Create block**.
-
-The **Category** is **Section** already, because you opened the list from **Page
-Sections**.
-
-## 2. Accept the section in a Model
-
-1. Open a page layout or a step layout.
-2. Add a **Page Sections** field to the schema.
-3. Click **Save**.
-
-The field now accepts any Block of the Section category. Make the field repeatable to
-build a page from a list of sections.
-
-If you want one section at a fixed place instead of a list, add a **Content block** field.
-Set its **Block category** to the **Section** category.
-
-## 3. Choose the section in an entry
-
-1. Open a content entry that uses the Model.
-2. Find the field that you added.
-3. Choose your Block.
-4. Fill in the fields of the Block.
-5. Click **Save**.
-
-:::warning
-An edit to a Block does not migrate the entries that use it. Check each affected content
-entry again, and correct every field error before you publish.
-:::
-
-## Related
-
-- [About the content model](/explanation/the-content-model) — why a schema change does not
-  migrate your data.
-- [Blocks](/reference/dashboard/content/blocks) — the reference.
-- [Models](/reference/dashboard/content/models) — every field type.

package/dist/docs/how-to/reuse-a-step-field-or-action.md

@@ -1,28 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to reuse a step, a field, or an action
-
-This guide shows you how to use one step, field, action, or condition in more than one
-flow. All four belong to the project, and not to the experience that you made them in.
-
-## Steps
-
-1. Open the flow builder for the second experience.
-2. Find the step, the action, or the condition in the library on the left.
-3. Drag it onto the canvas, or onto a step node for a field.
-
-The same one now appears in both flows.
-
-:::warning
-A change to the options applies at every place that uses it. Check the other flows before
-you change a shared step, field, action, or condition.
-:::
-
-## Related
-
-- [Steps](/reference/dashboard/steps) — the step options.
-- [Fields](/reference/dashboard/fields) — the field options.
-- [Actions](/reference/dashboard/actions) — the action options.

package/dist/docs/how-to/roll-back-a-published-version.md

@@ -1,26 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to roll back a published version
-
-This guide shows you how to make an earlier published version live again. Your current
-draft does not change.
-
-## Steps
-
-1. Open **Publish history** from the project sidebar.
-2. Find the version that you want to restore.
-3. Click **Restore**.
-4. Read the diff preview. It compares the current live version against the one that you
-   chose.
-5. Click **Restore this version** to confirm.
-
-The restored version is live immediately.
-
-## Related
-
-- [About workspaces and versions](/explanation/workspaces-and-versions) — why a roll-back
-  changes no data.
-- [Publish history](/reference/dashboard/workspace-versioning) — the version list.

package/dist/docs/how-to/run-an-ab-test.md

@@ -1,49 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to run an A/B test
-
-This guide shows you how to split your traffic with a feature flag and read the result in
-your application.
-
-Read [About feature flag allocation](/explanation/feature-flag-allocation) first. The
-point at which you read the feature flag decides when a visitor enters the test.
-
-## 1. Create the feature flag
-
-1. Open your project.
-2. Click **Feature flags** in the sidebar.
-3. Click **New feature flag**.
-4. Enter a name.
-5. Click **Create feature flag**.
-
-You cannot change the key after you create the feature flag.
-
-## 2. Set the allocation
-
-Open the detail page of the feature flag and set these controls:
-
-1. Turn **Enabled** on. A feature flag that is off allocates nobody.
-2. Set **Weight** to the percentage of visitors that you want in the test.
-3. Enter a **Description** that says what the feature flag tests.
-
-## 3. Read the feature flag in your application
-
-See [How to read a feature flag](/how-to/read-a-feature-flag). Read it at the point where
-the decision matters, and not at startup.
-
-## 4. Change the weight later
-
-1. Change **Weight** on the detail page.
-2. Increment the version.
-
-The new weight then applies to a visitor with a cached decision. Leave the version as it
-is to apply the new weight only to a visitor who is not allocated yet.
-
-## Related
-
-- [About feature flag allocation](/explanation/feature-flag-allocation) — why two feature
-  flags at the same weight give four groups, not two.
-- [Feature flags](/reference/dashboard/features) — the controls.

package/dist/docs/how-to/run-code-on-a-form-submission.md

@@ -1,125 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to run code on a form submission
-
-This guide shows you how to act on a step submission. Pass your callbacks to `useStep()`
-in React, or to `getStep()` in Svelte.
-
-## What the SDK does on submit
-
-1. It collects the field values from the HTML form.
-2. It runs each `onBeforeSubmit` callback, one after another.
-3. It checks each required field and each validation rule.
-4. It commits the responses to the experience state.
-5. It fires `form_submit_success` or `form_submit_error` on the event bus.
-6. It runs your `onSuccess` or `onError` callback.
-7. It moves to the next step.
-
-## Change the data before it is stored
-
-:::code-group
-
-```tsx [React]
-const { form } = useStep({
-  onBeforeSubmit: async (data) => ({
-    ...data,
-    'email-address': String(data['email-address']).toLowerCase(),
-  }),
-})
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  const { form } = getStep({
-    onBeforeSubmit: async (data) => ({
-      ...data,
-      'email-address': String(data['email-address']).toLowerCase(),
-    }),
-  })
-</script>
-```
-
-:::
-
-:::warning
-An `onBeforeSubmit` callback that throws aborts the submit before the SDK commits
-anything, and the step does not advance. Use it for a transform and for a check. Put a
-side effect, such as an analytics call, in `onSuccess`.
-:::
-
-## Act on the outcome
-
-:::code-group
-
-```tsx [React]
-const { form } = useStep({
-  onSuccess: ({ data }) => analytics.track('lead_captured', data),
-  onError: (errors) => console.error('Validation errors:', errors),
-})
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  const { form } = getStep({
-    onSuccess: ({ data }) => analytics.track('lead_captured', data),
-    onError: (errors) => console.error('Validation errors:', errors),
-  })
-</script>
-```
-
-:::
-
-A callback belongs to the component that passes it, and the SDK releases it when that
-component unmounts. An `onSuccess` callback that throws cannot stop the flow. The SDK
-reports the failure as `form_submit_callback_error`.
-
-## Choose the next step yourself
-
-Call `stopNavigation()` inside `onSuccess`, then move where you want:
-
-:::code-group
-
-```tsx [React]
-const experience = useExperience()
-
-const { form } = useStep({
-  onSuccess: ({ data, stopNavigation }) => {
-    stopNavigation()
-    if (data['plan-type'] === 'enterprise') {
-      experience.goToStepById('enterprise-contact')
-    } else {
-      experience.goToNextStep()
-    }
-  },
-})
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  const experience = getExperience()
-
-  const { form } = getStep({
-    onSuccess: ({ data, stopNavigation }) => {
-      stopNavigation()
-      if (data['plan-type'] === 'enterprise') {
-        experience.goToStepById('enterprise-contact')
-      } else {
-        experience.goToNextStep()
-      }
-    },
-  })
-</script>
-```
-
-:::
-
-`goToStepById()` takes a step `id`. `goToStepByKey()` takes the key of the step. When no
-step matches, the call does nothing.
-
-## Related
-
-- [How to render a step form](/how-to/render-a-step-form).
-- [SDK steps](/reference/sdk/steps) — the `form` object.