@picked/client 0.0.101-next.2 → 0.0.101-next.3

package/dist/docs/explanation/how-pickedql-works.md

@@ -1,76 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About PickedQL
-
-PickedQL is SQL over your Picked analytics data, but it is not only SQL. It expands what
-you write before it runs. Why add a layer at all, and not give you the tables?
-
-## The problem it answers
-
-An A/B test question is short to ask, and the SQL behind it is not. Take one question:
-"How many users are in the control group?" It needs four things. It needs a filter on the
-variant, a count of distinct users, a join to each dimension in the group, and a tenant
-filter.
-
-Write that by hand for every question, and most of each query is the same text again.
-
-PickedQL lets you write the short version:
-
-```sql
-SELECT control_users(), variant_users()
-FROM metrics
-WHERE project_id = 'your-project-id'
-```
-
-## What it expands
-
-**Virtual tables.** A name such as `metrics` maps to the real tables below it. You name
-the thing that you ask about, and not the storage.
-
-**Virtual functions.** `control_users()` expands to a full aggregate expression. The
-definition lives in one place, so every report that counts control users counts them the
-same way.
-
-**Automatic joins.** Point at a dimension column such as `device_category` or
-`country_code` and PickedQL adds the `LEFT JOIN` for you. This gives you the most: a
-dimension that you did not join is the most common reason for a wrong answer that looks
-correct.
-
-**SQL passthrough.** Standard SQL still works next to a virtual function, and that
-includes `CASE WHEN`, window functions, and subqueries. The layer adds; it does not
-restrict.
-
-## Why every query must carry a tenant filter
-
-Every query must carry a tenant filter in its `WHERE` clause. That filter is `project_id`
-for most tables. The `projects` table uses `id` instead, because there the row ID *is* the
-project ID.
-
-PickedQL reads that filter and checks your permission for that project. The filter is
-therefore not a convention that you can forget. Without one, the query does not run.
-The isolation is a property of the language, and not of each author.
-
-## Which table to reach for
-
-| Table | Use it for |
-| --- | --- |
-| `metrics` | A dashboard. The data is aggregated first, so it is much faster than raw events. |
-| `events` | Anything deeper. Raw events let you build any breakdown or funnel. |
-| `experience_journey` | A sankey or a funnel chart. One line of SQL returns `source, target, users`. |
-
-Note what `experience_journey` does for you. It builds the eight common table expressions
-that a path analysis needs. Those remove the duplicates, rank the top paths, and call
-`lagInFrame`. You pass your parameters in the `WHERE` clause.
-
-Some reference columns are free on `events`. `step_title`, `experience_title`, and
-`project_name` come from reference tables that PickedQL joins for you.
-
-## Related
-
-- [PickedQL](/reference/pickedql) — the language surface.
-- [Data sources](/reference/pickedql/data-sources) — every table.
-- [Virtual functions](/reference/pickedql/virtual-functions) — every function.
-- [How to run an analytics query](/how-to/analytics) — worked examples.

package/dist/docs/explanation/pages-and-flows.md

@@ -1,64 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About pages and flows
-
-An experience has two kinds, and the dashboard makes you choose
-between them when you create one. Why two, and how do you know which one a piece of work needs?
-
-## The two kinds
-
-| | Page | Flow |
-| --- | --- | --- |
-| What it is | A standalone experience that your server renders from a content entry. | An interactive experience of more than one step, which the browser renders. |
-| Use it for | A landing page or a campaign page where the search rank matters. | A quiz, a survey, a product finder, onboarding of more than one step. |
-
-The split is not about how complex the content is. It is about **who has to read it**.
-
-## Why the split exists
-
-A crawler and a social preview read the HTML your server returns. Neither waits for
-JavaScript in the browser. Content that a search engine must find is therefore
-content that must be in the first response. Only a server render puts it there.
-
-A flow has the reverse constraint. Its value is in the interaction: a visitor answers,
-the flow branches, the next screen depends on what came before. None of that can be in the
-first response, because none of it exists until the visitor acts.
-
-Choose a Page when the content must reach a search engine. Choose a Flow when the value is
-in the interaction and a browser render is acceptable.
-
-## What backs a page
-
-Four pieces sit behind every Page, and they are separate on purpose:
-
-1. A **page layout** sets the shape: which fields the page can hold.
-2. A **content entry** fills that shape with real data.
-3. A **Page** binds one entry, so the SDK can render it.
-4. The **SDK** reads the entry and renders it on your server.
-
-Layout and entry are separate because one layout backs many entries. Describe a campaign
-page one time, then make many pages from it. Change the layout and you must check every
-entry again. That is why the dashboard reports an invalid entry and does not serve it.
-
-A step layout does the same thing for one step inside a flow. The parts behave the same
-way. Only the thing that they give shape to is different.
-
-## They meet at the same publish
-
-Both kinds are experiences. Both live in a workspace, both go into the same immutable
-version, and both come out of the same Delivery API. The SDK decides where to render each
-one, and every step before that treats them the same way.
-
-This matters, because it means a project mixes them freely. A server-rendered
-landing page can carry a browser-rendered quiz inside it.
-
-## Related
-
-- [About how Picked works](/explanation/how-picked-works) — the path that both kinds take.
-- [About server-side rendering](/explanation/why-server-side-rendering) — how a Page
-  reaches the browser.
-- [Pages](/reference/dashboard/content/pages) — the page editor.
-- [Experiences](/reference/dashboard/experiences) — the flow options.

package/dist/docs/explanation/the-content-model.md

@@ -1,87 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About the content model
-
-Picked splits your content into three pieces: a Model, a Block, and a content entry.
-Why three, when a page editor needs only one?
-
-## Schema and data are separate
-
-A **Model** is a schema. It sets which fields a piece of content can hold, and it holds
-no data itself. A **content entry** is one instance of that schema, filled with real
-values.
-
-One Model backs many entries. Describe a campaign page one time, then make many pages
-from it. Each entry carries its own title, its own body, and its own image, but they all
-share the shape.
-
-That split is also what lets your code depend on content that it never saw. Your component
-reads `content.title` because the Model promises a `title`. It works for every entry that
-comes from that Model.
-
-## A category gives a Model a role
-
-A Model can carry a **category**, and the category decides what the Model gives its shape
-to. A **page layout** backs a standalone Page. A **step layout** backs one Step inside a
-Flow.
-
-The category is fixed because it decides where the SDK renders the entry. That is not a
-property that you can change under an entry that exists already.
-
-A Model can also carry no category. Such a Model has no layout role, and nothing renders
-its entries directly. It holds the content that other content points at, such as a
-product or a category of your own. See
-[About content references](/explanation/content-references).
-
-The three roles are one machine. A layout is a Model with a job in the render path. A
-Model with no category is the same machine with no such job.
-
-## A Block is a schema fragment
-
-A Model gives shape to a whole page or a whole step. A **Block** is a part that you put
-inside one or more Models.
-
-Define a hero one time as a Block, then point at it from every Model that needs one.
-Change the Block and every Model that holds it changes with it.
-
-This is the reason Blocks exist at all. Without them you must describe a common
-structure again in each Model, and the copies then become different. It is the same
-argument for one fact in one place that runs through the rest of this documentation.
-
-A Block sits **inside** the entry that embeds it. It has no entry of its own, and no id
-that you can point at.
-
-That is the difference between a Block and a reference. A Block is a shape that many
-entries hold. A reference is a pointer at one entry that many entries share.
-
-## Why a schema change does not migrate your data
-
-Change a Model or a Block, and Picked does not rewrite the entries behind it. An entry
-that no longer matches its schema becomes invalid, and the dashboard shows an error on
-each field that does not fit.
-
-That is deliberate. An automatic change must decide what a new required field holds for
-every entry that came before it. Any value that it chooses is content that nobody wrote.
-Picked reports the error instead, and you correct it.
-
-The cost is real. After a schema change, check every entry that uses that Model and fix
-each error before you publish. Picked serves valid content only, so an entry with an error
-does not reach a visitor.
-
-## An error points at the exact field
-
-A validation error carries a path in JSON style, such as `sections[0].data.title`. The
-path holds through nested groups, repeated fields, and Blocks. An error inside a
-repeated group therefore tells you which item in that group holds it.
-
-## Related
-
-- [Models](/reference/dashboard/content/models) — every field type.
-- [Blocks](/reference/dashboard/content/blocks) — the reusable fragments.
-- [Content entries](/reference/dashboard/content/content-entries) — the editor and the
-  validation.
-- [About content references](/explanation/content-references) — how one entry points at another.
-- [About pages and flows](/explanation/pages-and-flows) — which category you need.

package/dist/docs/explanation/the-two-apis.md

@@ -1,68 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About the two APIs
-
-Picked has two HTTP APIs, and a new reader often reaches for the wrong one. This page
-covers which is which and why they are separate.
-
-## The split
-
-| | Delivery API | Management API |
-| --- | --- | --- |
-| Style | REST | GraphQL |
-| Access | Public, anonymous | Authenticated |
-| Operations | Read-only | Read and write |
-| Base | `https://api.picked.app/api/v1` | `POST https://api.picked.app/api/graphql` |
-| Use it to | Serve published configuration and content to your application | Control your projects, experiences, and content |
-
-The short rule is this: **the Delivery API serves your visitors, and the management API
-serves you.**
-
-## Why they are not one API
-
-Three properties of the delivery path make it a different kind of API.
-
-**It is anonymous.** A crawler must read your published page content with no credential at
-all. An API that requires a token cannot serve a search engine, and an API that serves a
-search engine cannot require one.
-
-**It is cacheable.** A published response is the same for every reader, so a shared cache
-can hold it. The Delivery API sends `s-maxage` for an SDK request, and it sends
-`Vary: Picked-Client`. A GraphQL endpoint that takes any query over a `POST` has none of
-those properties.
-
-**It is read-only.** Nothing that a reader reaches without a credential can change your
-data. Every write stays on a separate authenticated surface, so that property holds by
-design.
-
-## What the Delivery API serves
-
-Two endpoints, and the SDK calls both:
-
-- **Project config** returns the published configuration of a project: its experiences and
-  steps, and the content link on each step.
-- **Experience content** returns the content entries behind an experience.
-
-Your server usually calls the first and lets `serialize()` call the second. See
-[About server-side rendering](/explanation/why-server-side-rendering).
-
-## How a preview stays out of the search index
-
-A preview needs unpublished content, and by the definition of it that content is not
-public. The Delivery API takes a `preview_token` query parameter for exactly that. It then
-treats the result differently. `versionId` comes back `null`, the response is `no-store`,
-and `robots.txt` does not allow the preview path.
-
-That last part matters more than it looks. A draft that anybody can read over an anonymous
-URL is a draft that a search engine can find. A campaign page that is only part complete
-can then appear in the search results of a customer.
-
-## Related
-
-- [Delivery API](/reference/delivery-api) — the endpoints and their responses.
-- [Management API](/reference/management-api/authentication) — authentication and scopes.
-- [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling) — the
-  exact cache rules and `robots.txt` rules.

package/dist/docs/explanation/why-server-side-rendering.md

@@ -1,76 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About server-side rendering
-
-Why does a Page need a snapshot, when the SDK can fetch its content in the browser?
-Because the reader that matters most does not run JavaScript.
-
-## The constraint
-
-A crawler and a social preview read the HTML your server returns, and they do not wait for
-the browser to fetch anything. If the content of a Page arrives after the first response,
-those readers never see it.
-
-So the content has to be in the HTML. That means your server has to know, before it
-answers, which experiences match this URL and what their content is.
-
-## What the snapshot is for
-
-`serialize()` answers that question on the server. It registers your project configuration and
-evaluates each experience condition against the URL. It then reads the content for each
-experience that matches, and returns a `PickedSnapshot` as plain JSON.
-
-```
-projectConfig (Delivery API)
-  -> serialize(client, params) on the server -> PickedSnapshot
-  -> embed snapshot in HTML
-  -> client seeds from snapshot -> renders the same markup -> hydrates
-```
-
-The snapshot carries the exact options the server chose with, and the condition results it
-reached. The first render in the browser therefore reuses the decisions of the server. It
-does not evaluate them a second time.
-
-That last point is the whole reason the snapshot holds condition results and not only
-content. A browser that evaluates the conditions itself can reach a different answer. A different URL shape, a
-different time, or a different flag value each give a different result. The markup then does not
-match what the server sent, and hydration discards the server HTML. That failure is the
-one server-side rendering exists to prevent.
-
-## Why a slot instead of a selector
-
-A browser-rendered flow points at a DOM selector, and the SDK inserts the component next
-to the element that it finds. That cannot work on a server, because a server has no DOM
-to search.
-
-A slot reverses that. `<ExperienceSlot name="page" />` is a mount point that you place in
-your own markup. An experience joins it when its target selector is `.picked-slot-<name>`.
-Your component tree decides where the content goes, so the server renders it in one pass.
-
-## Why placements have an order
-
-More than one experience can point at the same slot, so the slot needs a rule. The order
-is:
-
-```
-replace -> before -> prepend -> append -> after
-```
-
-`replace` wins: an active experience with that placement renders alone. Every other active
-experience renders in the order above.
-
-The rule exists so the outcome does not depend on which experience came first. Two editors
-can add an experience to the same slot on the same day. The result then follows from the
-placements, and not from the database.
-
-## Related
-
-- [Your first server-rendered page](/tutorials/first-server-rendered-page) — the whole
-  path, in practice.
-- [Server snapshot](/reference/sdk/ssr/serialize) — every `serialize()` parameter.
-- [Slots and placements](/reference/sdk/ssr/slots-and-placements) — the exact rules for
-  the order.
-- [About pages and flows](/explanation/pages-and-flows) — which kind you need.

package/dist/docs/explanation/workspaces-and-versions.md

@@ -1,71 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About workspaces and versions
-
-Why can you not edit what your visitors see? Because Picked keeps two things separate on
-purpose: the work in progress, and the thing that it serves.
-
-## The two states
-
-A **workspace** holds your changes. Edit a flow, a feature flag, a step, a field, an
-action, or a condition, and the change stays in the workspace. No visitor sees it.
-
-A **version** is what your visitors get. When you publish, Picked takes the current
-workspace and makes an immutable snapshot of it. A project serves exactly one version at a
-time, the live one.
-
-Everything else follows from that split.
-
-## Why the snapshot is immutable
-
-A published version cannot change. That is what makes a roll-back safe. When you restore
-an earlier version, Picked moves the live pointer of the project and changes no data. The
-version that you restore is the exact version that was live before, and not a copy that
-Picked builds again.
-
-It is also what lets your draft continue. When you publish, your workspace stays
-editable, and a roll-back discards no draft. The two move at their own speed.
-
-## The three workspace states
-
-- **Live** — the workspace whose snapshot the SDK serves. Each project has exactly one.
-- **Draft** — a workspace that no visitor sees. Edit it, see a preview of it, publish it.
-- **Archived** — a draft that you put to one side. It is still editable, but it is out of
-  the default list.
-
-Picked keeps these two operations separate on purpose. Archive a draft when you are not
-certain about it. You cannot reverse a delete, but you can always unarchive.
-
-## Why the publish modal shows a diff
-
-It is the one step in the dashboard that you cannot take back. It is therefore the one
-place that shows you exactly what changes. The modal compares the current workspace
-against the last published snapshot. It puts the changes into groups, and marks each row
-added, removed, or modified.
-
-The diff also carries a warning that a plain list of changes cannot give you. Some changes
-break other records. Remove a field while steps still point at it, and those steps
-now have an error. The preview shows that above the diff, before you publish and not after.
-
-The first publish of a workspace has no earlier snapshot to compare against, so the modal
-shows the contents instead of a diff.
-
-## A preview does not reach production
-
-A preview sends the workspace state to the SDK in the query parameters. Your unpublished
-workspace therefore applies to your browser and to nothing else. The visitors on your live
-site see no change.
-
-One result of this matters. In a preview the SDK stores a feature flag decision in session
-storage and not in local storage. A preview allocation is therefore disposable, and it can
-differ from a production one. See
-[About feature flag allocation](/explanation/feature-flag-allocation).
-
-## Related
-
-- [About how Picked works](/explanation/how-picked-works) — what a publish feeds.
-- [Workspaces](/reference/dashboard/workspaces) — the states and the settings.
-- [Publish history](/reference/dashboard/workspace-versioning) — the version list.

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

@@ -1,43 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to add a step, a field, an action, or a condition
-
-This guide shows you how to create the parts that a flow is built from. All four follow
-the same shape, and all four belong to the project: you can use one in more than one flow.
-
-## Steps
-
-1. Open a flow. The library is on the left of the flow builder.
-2. Find the **Steps**, **Fields**, **Actions**, or **Conditions** section in it.
-3. Click the **+** next to that section.
-4. Enter a name. The dashboard makes the key from it.
-5. Click the **Create** button for that kind: **Create step**, **Create field**,
-   **Create action**, **Create condition**.
-
-The flow builder opens again, and the new one is in the library.
-
-**Fields** also has its own sidebar entry, so you can make a field without a flow. A step,
-an action, and a condition belong to a flow, and the library is the only way to reach
-them.
-
-The key is the identifier that your application uses. You set it one time, and you cannot
-change it later. Your visitors never see a name or a key.
-
-## What each one needs after that
-
-| Kind | Set this next |
-| --- | --- |
-| Step | A **Layout**, such as `card`, `modal`, or `fullscreen`. |
-| Field | A **Label**, a type, and any validation rule. |
-| Action | Nothing in the dashboard. Register the handler in your code. |
-| Condition | The rule, in the **Logic** section of the inspector. |
-
-## Related
-
-- [How to build a flow](/how-to/build-a-flow) — put it on the canvas.
-- [How to write a condition](/how-to/write-a-condition)
-- [How to register an action handler](/how-to/register-an-action-handler)
-- [How to reuse a step, a field, or an action](/how-to/reuse-a-step-field-or-action)