@picked/client 0.0.1-dev.1786405786333 → 0.0.1-dev.1786601464574
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.
- package/dist/.tsbuildinfo +1 -1
- package/dist/api-C8B96Kwv.js +22 -0
- package/dist/api-DS7fA9kj.cjs +1 -0
- package/dist/cjs/index.js +2 -2
- package/dist/cjs/plugins/dynamic-experiences/index.js +1 -1
- package/dist/cjs/server/index.js +1 -1
- package/dist/docs/how-to/authenticate-the-cli.md +95 -0
- package/dist/docs/how-to/install-the-sdk.md +7 -0
- package/dist/docs/how-to/switch-workspaces.md +123 -0
- package/dist/docs/reference/delivery-api/workspace-schema.md +74 -0
- package/dist/docs/reference/sdk/type-generation.md +130 -0
- package/dist/docs/reference/tools/cli.md +141 -0
- package/dist/esm/index.js +23 -14
- package/dist/esm/plugins/dynamic-experiences/index.js +5 -4
- package/dist/esm/server/index.js +1 -1
- package/dist/{plugin-DviILBha.js → plugin-C8hWW3ed.js} +24 -20
- package/dist/plugin-Dtg2sOad.cjs +1 -0
- package/dist/{provider-DnRTKPsK.js → provider-BEpRDCyr.js} +2 -1
- package/dist/provider-ixdOyYTA.cjs +1 -0
- package/dist/registry-C1t8l3t9.cjs +1 -0
- package/dist/registry-CXZv0uLg.js +18 -0
- package/dist/types/data-source/api.d.ts +1 -1
- package/dist/types/data-source/api.d.ts.map +1 -1
- package/dist/types/entities/response/response.d.ts +22 -6
- package/dist/types/entities/response/response.d.ts.map +1 -1
- package/dist/types/form/create-submit-pipeline.d.ts +32 -3
- package/dist/types/form/create-submit-pipeline.d.ts.map +1 -1
- package/dist/types/index.d.ts +2 -0
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/picked.d.ts +3 -3
- package/dist/types/ping.d.ts +4 -3
- package/dist/types/ping.d.ts.map +1 -1
- package/dist/types/plugins/dynamic-experiences/index.d.ts +1 -1
- package/dist/types/plugins/dynamic-experiences/index.d.ts.map +1 -1
- package/dist/types/plugins/dynamic-experiences/plugin.d.ts.map +1 -1
- package/dist/types/plugins/dynamic-experiences/types.d.ts +7 -116
- package/dist/types/plugins/dynamic-experiences/types.d.ts.map +1 -1
- package/dist/types/schema-registry.d.ts +190 -0
- package/dist/types/schema-registry.d.ts.map +1 -0
- package/dist/types/server/index.d.ts +1 -1
- package/dist/types/server/index.d.ts.map +1 -1
- package/dist/types/server/serialize.d.ts +11 -1
- package/dist/types/server/serialize.d.ts.map +1 -1
- package/dist/types/typed-content.d.ts +17 -0
- package/dist/types/typed-content.d.ts.map +1 -0
- package/dist/types/utils/picked-config.d.ts +19 -1
- package/dist/types/utils/picked-config.d.ts.map +1 -1
- package/dist/version-BLzNWQ-j.cjs +1 -0
- package/dist/version-IAAIvoH9.js +4 -0
- package/package.json +3 -1
- package/dist/api-CJXSNevv.js +0 -38
- package/dist/api-CP8La6ax.cjs +0 -1
- package/dist/plugin-DkSWIASL.cjs +0 -1
- package/dist/provider-DIV6y0Wi.cjs +0 -1
- package/dist/registry-D9oWMcgF.js +0 -74
- package/dist/registry-a4Uk2Ivo.cjs +0 -1
- package/dist/types/utils/api.d.ts +0 -25
- package/dist/types/utils/api.d.ts.map +0 -1
- package/dist/types/utils/client-headers.d.ts +0 -2
- package/dist/types/utils/client-headers.d.ts.map +0 -1
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: how-to
|
|
3
|
+
layout: docs
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# How to switch workspaces
|
|
7
|
+
|
|
8
|
+
This guide shows you how to point your local tooling at a different project or workspace.
|
|
9
|
+
Your application then renders that workspace's content and types on your machine. It expects
|
|
10
|
+
a `picked.config.ts` and the [CLI](/reference/tools/cli).
|
|
11
|
+
|
|
12
|
+
Your tooling reads the project and surface named in the committed `picked.config.ts`. The
|
|
13
|
+
CLI writes your choice to `.picked/settings.json` instead. That file is per-developer and
|
|
14
|
+
Git ignores it, so the committed default stays as it is and one command puts it back.
|
|
15
|
+
|
|
16
|
+
See [Workspaces](/reference/dashboard/workspaces) for what Live, Draft, and Archived mean.
|
|
17
|
+
|
|
18
|
+
## 1. Sign in
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
picked login
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
This opens your browser for a one-time OAuth sign-in and stores a session under
|
|
25
|
+
`~/.picked/`. Confirm it with `picked whoami`. For CI, set `PICKED_TOKEN` instead — see
|
|
26
|
+
[CLI authentication](/how-to/authenticate-the-cli).
|
|
27
|
+
|
|
28
|
+
## 2. Find a workspace
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
picked workspace list
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
Acme Corp. (acme-corporation)
|
|
36
|
+
Storefront [proj_a1b2]
|
|
37
|
+
Default Storefront [LIVE] (live)
|
|
38
|
+
Checkout rework [DRAFT]
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Note the **project id** (`proj_a1b2`) and the name or the id of the workspace you want.
|
|
42
|
+
|
|
43
|
+
## 3. Switch to the draft
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
picked workspace use --project proj_a1b2 --workspace ws_draft
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
Active workspace: Checkout rework [DRAFT] in project proj_a1b2 (source: preview)
|
|
51
|
+
Generated types at /app/src/picked-env.d.ts
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
A command that names **one specific workspace** (draft, live, or archived):
|
|
55
|
+
|
|
56
|
+
- writes the selection (and its [preview token](/reference/delivery-api/preview-caching-crawling)) to
|
|
57
|
+
`.picked/settings.json`,
|
|
58
|
+
- switches the resolved `source` to `preview` for that project, and
|
|
59
|
+
- regenerates `picked-env.d.ts` from that workspace's schema (skip with `--no-generate`).
|
|
60
|
+
|
|
61
|
+
To browse instead, run `picked workspace use` with no flags. The interactive picker lists
|
|
62
|
+
every project, with **Published (live version)** and each of its workspaces.
|
|
63
|
+
|
|
64
|
+
## 4. See the draft in your app
|
|
65
|
+
|
|
66
|
+
Both readers of the selection use `.picked/settings.json` with no change to your
|
|
67
|
+
configuration:
|
|
68
|
+
|
|
69
|
+
- **Type generation** now reads the draft schema. Rerun `picked generate types` after more
|
|
70
|
+
edits.
|
|
71
|
+
- The **[Vite plugin](/reference/tools/vite-plugin)** reads the draft's configuration and
|
|
72
|
+
content in development and in a build. It sends the preview token to the
|
|
73
|
+
[Delivery API](/reference/delivery-api). Restart the dev server to apply a switch.
|
|
74
|
+
|
|
75
|
+
Your application renders the unpublished draft on your machine, with types.
|
|
76
|
+
|
|
77
|
+
## 5. Switch back to live
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
picked workspace use --project proj_a1b2
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
A command that names a project with no `--workspace`, or **Published (live version)** in the
|
|
84
|
+
picker, discards the preview token and returns `source` to `published`. To confirm what is
|
|
85
|
+
active:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
picked status
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
Config default: project proj_a1b2 (source: published)
|
|
93
|
+
Active selection: none (using the config default).
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## CI and headless runs
|
|
97
|
+
|
|
98
|
+
`.picked/settings.json` is a local, per-developer file. Do not commit it. To choose one
|
|
99
|
+
workspace in CI with no selection file, set the environment directly:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
PICKED_TOKEN="$TOKEN" \
|
|
103
|
+
PICKED_PROJECT_ID=proj_a1b2 \
|
|
104
|
+
PICKED_PREVIEW_TOKEN="$DRAFT_TOKEN" \
|
|
105
|
+
picked generate types --check
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`PICKED_PREVIEW_TOKEN` applies only when the resolved `source` is `preview`. See the
|
|
109
|
+
[CLI environment variables](/reference/tools/cli#environment-variables) for the full
|
|
110
|
+
precedence order.
|
|
111
|
+
|
|
112
|
+
:::note
|
|
113
|
+
A preview token is a long-lived credential for one workspace. Keep it out of the version
|
|
114
|
+
control system, as you do with each other credential. Git ignores `.picked/settings.json`
|
|
115
|
+
for this reason, because `picked workspace use` writes a token there.
|
|
116
|
+
:::
|
|
117
|
+
|
|
118
|
+
## Related
|
|
119
|
+
|
|
120
|
+
- [CLI](/reference/tools/cli) — every command and flag.
|
|
121
|
+
- [Workspaces](/reference/dashboard/workspaces) — Live, Draft, and Archived states.
|
|
122
|
+
- [Type generation](/reference/sdk/type-generation) — how the schema becomes types.
|
|
123
|
+
- [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling) — preview tokens on the Delivery API.
|
|
@@ -0,0 +1,74 @@
|
|
|
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
|
+
| `$defs.contentModels` | JSON Schema definitions for each content model. |
|
|
32
|
+
| `$defs.contentBlocks` | JSON Schema definitions for reusable content blocks. |
|
|
33
|
+
| `$defs.fields` | Object schema for project field values. |
|
|
34
|
+
| `$defs.featureKeys` | String enum of feature keys. |
|
|
35
|
+
| `$defs.experienceKeys` | String enum of experience keys. |
|
|
36
|
+
| `$defs.stepKeys` | String enum of step keys. |
|
|
37
|
+
|
|
38
|
+
## Published and preview
|
|
39
|
+
|
|
40
|
+
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).
|
|
41
|
+
|
|
42
|
+
When no published schema exists, the published endpoint returns `404` and tells you to publish the workspace.
|
|
43
|
+
|
|
44
|
+
## Example
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
curl https://api.picked.app/api/v1/projects/proj_123/schema
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
53
|
+
"$id": "picked:project/proj_123/schema",
|
|
54
|
+
"x-picked-schema-version": 1,
|
|
55
|
+
"x-picked-source": "published",
|
|
56
|
+
"x-picked-version-id": "ver_456",
|
|
57
|
+
"x-picked-step-content-models": {
|
|
58
|
+
"intro": "welcome-page"
|
|
59
|
+
},
|
|
60
|
+
"$defs": {
|
|
61
|
+
"contentModels": {},
|
|
62
|
+
"contentBlocks": {},
|
|
63
|
+
"fields": { "type": "object", "additionalProperties": false, "properties": {} },
|
|
64
|
+
"featureKeys": { "type": "string", "enum": ["default"] },
|
|
65
|
+
"experienceKeys": { "type": "string", "enum": ["welcome-survey"] },
|
|
66
|
+
"stepKeys": { "type": "string", "enum": ["intro"] }
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Related
|
|
72
|
+
|
|
73
|
+
- [Type generation](/reference/sdk/type-generation) — Generate TypeScript types from this schema in your app.
|
|
74
|
+
- [Project Config](/reference/delivery-api/project-config) — Runtime project configuration for the SDK.
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: reference
|
|
3
|
+
layout: docs
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Type Generation
|
|
7
|
+
|
|
8
|
+
Picked can generate TypeScript types from your workspace schema so field values, feature keys, content models, and step layouts are typed in your app.
|
|
9
|
+
|
|
10
|
+
The generated file augments the `PickedSchemaRegistry` interface of `@picked/client`. Your IDE reads the types as soon as the declaration file is part of your TypeScript project.
|
|
11
|
+
|
|
12
|
+
## Quick start
|
|
13
|
+
|
|
14
|
+
### 1. Add `picked.config.ts`
|
|
15
|
+
|
|
16
|
+
Create a `picked.config.ts` in your project root:
|
|
17
|
+
|
|
18
|
+
```typescript
|
|
19
|
+
import { defineConfig } from '@picked/config'
|
|
20
|
+
|
|
21
|
+
export default defineConfig({
|
|
22
|
+
projectId: 'your-project-id',
|
|
23
|
+
apiUrl: 'https://api.picked.app',
|
|
24
|
+
typesOutput: './src/picked-env.d.ts',
|
|
25
|
+
source: 'published',
|
|
26
|
+
})
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
| Option | Description |
|
|
30
|
+
| --- | --- |
|
|
31
|
+
| `projectId` | **Required.** Your Picked project id. |
|
|
32
|
+
| `apiUrl` | API origin (defaults to `https://api.picked.app`). |
|
|
33
|
+
| `typesOutput` | Path for generated types (defaults to `./src/picked-env.d.ts`). |
|
|
34
|
+
| `source` | Schema surface to type against: `'published'` (default) or `'preview'`. Preview requires `PICKED_PREVIEW_TOKEN` in the environment. |
|
|
35
|
+
|
|
36
|
+
The `source` value matches the `x-picked-source` field on the [workspace schema](/reference/delivery-api/workspace-schema) document — it controls whether tooling fetches the published or preview workspace shape.
|
|
37
|
+
|
|
38
|
+
### 2. Enable the Vite plugin (recommended)
|
|
39
|
+
|
|
40
|
+
If you use Vite, add `@picked/vite-plugin-picked`. Type generation runs automatically on `dev` and `build` when `generateTypes` is enabled (the default):
|
|
41
|
+
|
|
42
|
+
```typescript
|
|
43
|
+
import { picked } from '@picked/vite-plugin-picked'
|
|
44
|
+
|
|
45
|
+
export default defineConfig({
|
|
46
|
+
plugins: [
|
|
47
|
+
picked({ disableLauncher: true }),
|
|
48
|
+
],
|
|
49
|
+
})
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Project identity (`projectId`, `apiUrl`) comes from `picked.config.ts` — the plugin only accepts Vite-specific options:
|
|
53
|
+
|
|
54
|
+
| Option | Default | Description |
|
|
55
|
+
| --- | --- | --- |
|
|
56
|
+
| `generateTypes` | `true` | Read the workspace schema and write types, in development and in a build. |
|
|
57
|
+
| `disableLauncher` | `false` | Turn off the HTML page of the dev launcher. |
|
|
58
|
+
|
|
59
|
+
Set `generateTypes: false` in a nested Vite build that must not regenerate types, such as a build for one more entry point.
|
|
60
|
+
|
|
61
|
+
### 3. Or use the CLI
|
|
62
|
+
|
|
63
|
+
Install `@picked/cli` and run:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
picked generate types
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
In CI, `--check` writes no file and fails when the types are stale. See the [CLI reference](/reference/tools/cli) for each command.
|
|
70
|
+
|
|
71
|
+
## Workspace selection
|
|
72
|
+
|
|
73
|
+
Tooling reads `projectId` and `source` from your committed `picked.config.ts`. The Picked [CLI](/reference/tools/cli) points that tooling at a different project or a draft workspace, and leaves the file as it is. It writes the selection to `.picked/settings.json`, which is per-developer and which Git ignores. That selection supersedes the committed default.
|
|
74
|
+
|
|
75
|
+
See [How to switch workspaces](/how-to/switch-workspaces) for the full set of steps.
|
|
76
|
+
|
|
77
|
+
## Generated output
|
|
78
|
+
|
|
79
|
+
The generated `picked-env.d.ts` file looks like:
|
|
80
|
+
|
|
81
|
+
```typescript
|
|
82
|
+
// GENERATED by `@picked/typegen` — do not edit by hand.
|
|
83
|
+
// source: published `x-picked-version-id`: `ver_456`
|
|
84
|
+
// Reference: `https://docs.picked.app/reference/sdk/type-generation`
|
|
85
|
+
|
|
86
|
+
export interface WelcomePage { /* ... */ }
|
|
87
|
+
export interface FieldValues { /* ... */ }
|
|
88
|
+
export type FeatureKey = 'default' | 'winter-sale'
|
|
89
|
+
|
|
90
|
+
declare module '@picked/client' {
|
|
91
|
+
interface PickedSchemaRegistry {
|
|
92
|
+
contentModels: { 'welcome-page': WelcomePage }
|
|
93
|
+
stepContentModels: { intro: 'welcome-page' }
|
|
94
|
+
fieldValues: FieldValues
|
|
95
|
+
featureKeys: FeatureKey
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Commit this file to the version control system, or regenerate it in CI after you publish a workspace change.
|
|
101
|
+
|
|
102
|
+
## Keys the application defines
|
|
103
|
+
|
|
104
|
+
An application can define a feature, an action, a field, a step, or an experience of its
|
|
105
|
+
own. It does this through `createClient` options or through a `register` method. The
|
|
106
|
+
workspace has no record of such a key, so the generated types have none either.
|
|
107
|
+
|
|
108
|
+
A hook still accepts one. Each key type holds the keys of the workspace and any other
|
|
109
|
+
string. Your editor shows the workspace keys, and no local key is an error:
|
|
110
|
+
|
|
111
|
+
```typescript
|
|
112
|
+
useFeature('winter-sale') // from the workspace, and suggested
|
|
113
|
+
useFeature('summer-sales-experiment') // from createClient, and accepted
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Each key type has a `Known` form that holds the workspace keys alone —
|
|
117
|
+
`KnownFeatureKeys`, `KnownActionKeys`, `KnownFieldKeys`, `KnownStepKeys`, and
|
|
118
|
+
`KnownExperienceKeys`. Use one where you want the workspace set and nothing else.
|
|
119
|
+
|
|
120
|
+
## Cache
|
|
121
|
+
|
|
122
|
+
Type generation writes its artefacts under `.picked/`: the schema JSON and a manifest. The first run adds this directory to `.gitignore` for you.
|
|
123
|
+
|
|
124
|
+
## Related
|
|
125
|
+
|
|
126
|
+
- [CLI](/reference/tools/cli) — commands, authentication, and environment variables.
|
|
127
|
+
- [How to switch workspaces](/how-to/switch-workspaces) — read a draft workspace on your machine.
|
|
128
|
+
- [Vite plugin](/reference/tools/vite-plugin) — the build-time prefetch and the dev launcher.
|
|
129
|
+
- [Workspace schema](/reference/delivery-api/workspace-schema) — the schema endpoint.
|
|
130
|
+
- [Delivery API](/reference/delivery-api) — the published surface and the preview surface.
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: reference
|
|
3
|
+
layout: docs
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# CLI
|
|
7
|
+
|
|
8
|
+
`@picked/cli` is the command-line tool for local Picked development. It generates
|
|
9
|
+
TypeScript types from your workspace schema and lets you switch which project or workspace
|
|
10
|
+
your local tooling loads — without hand-editing `picked.config.ts`.
|
|
11
|
+
|
|
12
|
+
## Installation
|
|
13
|
+
|
|
14
|
+
`@picked/cli` installs as a dev dependency and gives you the binary `picked`. It reads
|
|
15
|
+
`picked.config.ts` from the current directory, so it runs from your project root. See
|
|
16
|
+
[How to authenticate the CLI](/how-to/authenticate-the-cli) to install it and sign in.
|
|
17
|
+
|
|
18
|
+
The `picked` package holds this command too, so a project that installs `picked` has it
|
|
19
|
+
already.
|
|
20
|
+
|
|
21
|
+
## Commands
|
|
22
|
+
|
|
23
|
+
| Command | Description |
|
|
24
|
+
| --- | --- |
|
|
25
|
+
| `picked login` | Sign in with your browser (OAuth) to the API origin of the current directory. Stores a session under `~/.picked/auth/`. |
|
|
26
|
+
| `picked logout` | Clear the stored session for the current directory's API origin. |
|
|
27
|
+
| `picked whoami` | Print the identity signed in to the API origin of the current directory, or report that `PICKED_TOKEN` is in use. |
|
|
28
|
+
| `picked status` | Print the resolved selection and the committed `picked.config` default. |
|
|
29
|
+
| `picked workspace list` | List each org, project, and workspace that you can read. Alias `ls`. `--json` gives machine output. |
|
|
30
|
+
| `picked workspace use` | Set the active project or workspace. Alias `picked use`. Interactive, or `--project` and `--workspace`. |
|
|
31
|
+
| `picked generate types` | Read the workspace schema and write `picked-env.d.ts`. `--check` verifies and writes nothing. |
|
|
32
|
+
|
|
33
|
+
### `picked generate types`
|
|
34
|
+
|
|
35
|
+
Writes the typed schema declaration. See [Type generation](/reference/sdk/type-generation)
|
|
36
|
+
for the `picked.config.ts` reference and the generated output.
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
picked generate types
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
In CI, `--check` writes nothing and fails when the committed types are stale:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
picked generate types --check
|
|
46
|
+
# → "Types are up to date (`…/src/picked-env.d.ts`)." (status 0)
|
|
47
|
+
# → "Types are out of date: `…/src/picked-env.d.ts`" (status 1)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### `picked workspace list`
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
picked workspace list
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
Acme Corp. (acme-corporation)
|
|
58
|
+
Storefront [proj_a1b2]
|
|
59
|
+
Default Storefront [LIVE] (live)
|
|
60
|
+
Checkout rework [DRAFT]
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`--json` gives a machine-readable tree. Each prompt and heading goes to `stderr`, so the
|
|
64
|
+
`stdout` of `--json` stays clean when you send it to another command.
|
|
65
|
+
|
|
66
|
+
### `picked workspace use`
|
|
67
|
+
|
|
68
|
+
Sets the active selection, then regenerates types. See
|
|
69
|
+
[How to switch workspaces](/how-to/switch-workspaces) for the full set of steps.
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
picked workspace use # interactive picker
|
|
73
|
+
picked workspace use --project proj_a1b2 # the project's published (live) version
|
|
74
|
+
picked workspace use --project proj_a1b2 --workspace ws_id # preview a specific workspace via its token
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
Active workspace: Checkout rework [DRAFT] in project proj_a1b2 (source: preview)
|
|
79
|
+
Generated types at /app/src/picked-env.d.ts
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`--no-generate` sets the selection and leaves the types as they are.
|
|
83
|
+
|
|
84
|
+
:::warning
|
|
85
|
+
`picked workspace use` regenerates types by default. Types that no longer match the
|
|
86
|
+
workspace give no error, and a developer can fail to see the problem for a long time. Use
|
|
87
|
+
`--no-generate` only when you regenerate the types yourself.
|
|
88
|
+
:::
|
|
89
|
+
|
|
90
|
+
## Authentication
|
|
91
|
+
|
|
92
|
+
`picked login` signs in through the browser. It uses an authorization-code flow with PKCE
|
|
93
|
+
against the Picked OAuth server. `picked whoami` prints the identity for the current origin.
|
|
94
|
+
`picked logout` clears it.
|
|
95
|
+
|
|
96
|
+
The CLI holds one auth config file for each API origin, outside each repository. Every
|
|
97
|
+
command reads and writes only the origin that the current directory resolves to, and never
|
|
98
|
+
a session for another API.
|
|
99
|
+
|
|
100
|
+
| File | Contents |
|
|
101
|
+
| --- | --- |
|
|
102
|
+
| `~/.picked/auth/<origin>.json` | The OAuth session for one API origin — access token, refresh token, expiry — with the CLI's registered client id for that origin. File mode `600`. Refreshed as it nears expiry. |
|
|
103
|
+
|
|
104
|
+
`PICKED_TOKEN` supersedes each stored session and needs no browser, which is what a CI run
|
|
105
|
+
uses. An API deployment with no OAuth client registration rejects `picked login`, and has
|
|
106
|
+
no other flow.
|
|
107
|
+
|
|
108
|
+
A CLI session is a developer credential. It is not an
|
|
109
|
+
[API key](/reference/dashboard/api-keys), which authenticates server-to-server calls, and
|
|
110
|
+
not [dashboard sign-in](/reference/management-api/authentication).
|
|
111
|
+
|
|
112
|
+
## Environment variables
|
|
113
|
+
|
|
114
|
+
| Variable | Effect |
|
|
115
|
+
| --- | --- |
|
|
116
|
+
| `PICKED_API_URL` | The API origin that the CLI reads. Supersedes `picked.config` `apiUrl` and the `https://api.picked.app` default. |
|
|
117
|
+
| `PICKED_TOKEN` | An access token in place of the stored session, for a CI or headless run. `picked login` is then not needed. |
|
|
118
|
+
| `PICKED_PROJECT_ID` | Supersedes the resolved project id, above the active selection and the committed configuration. |
|
|
119
|
+
| `PICKED_PREVIEW_TOKEN` | Supersedes the preview token. Applies only when the resolved source is `preview`. |
|
|
120
|
+
|
|
121
|
+
### How the selection resolves
|
|
122
|
+
|
|
123
|
+
Tooling — `picked generate types` and the
|
|
124
|
+
[Vite plugin](/reference/tools/vite-plugin) — resolves the configuration in this order. Each
|
|
125
|
+
layer supersedes the layer before it:
|
|
126
|
+
|
|
127
|
+
1. **`picked.config.ts`** — the committed default, `projectId` and `source`.
|
|
128
|
+
2. **`.picked/settings.json`** — the per-developer active selection that
|
|
129
|
+
`picked workspace use` writes. It supersedes `projectId` and `source`, and Git ignores it.
|
|
130
|
+
3. **Environment variables** — `PICKED_PROJECT_ID` and `PICKED_PREVIEW_TOKEN` supersede
|
|
131
|
+
both, for a CI or headless run.
|
|
132
|
+
|
|
133
|
+
`picked status` prints the resolved result.
|
|
134
|
+
|
|
135
|
+
## Related
|
|
136
|
+
|
|
137
|
+
- [How to authenticate the CLI](/how-to/authenticate-the-cli) — install and sign in.
|
|
138
|
+
- [How to switch workspaces](/how-to/switch-workspaces) — the draft-preview workflow.
|
|
139
|
+
- [Type generation](/reference/sdk/type-generation) — `picked.config.ts` and the generated types.
|
|
140
|
+
- [Vite plugin](/reference/tools/vite-plugin) — reads the same selection in development and in a build.
|
|
141
|
+
- [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling) — how a preview token behaves.
|
package/dist/esm/index.js
CHANGED
|
@@ -5,11 +5,12 @@ import { a as i, c as a, d as o, f as s, i as c, l, m as u, n as d, o as f, r as
|
|
|
5
5
|
import { a as _, i as v, r as ee, s as y, t as b } from "../dom-BqcToNL0.js";
|
|
6
6
|
import { l as x, n as S, r as C, u as w } from "../experience-instance-DGk11d8a.js";
|
|
7
7
|
import { i as T, n as E, r as D, t as O } from "../storage-1MW3-_As.js";
|
|
8
|
-
import {
|
|
9
|
-
import { t as
|
|
10
|
-
import { n as
|
|
11
|
-
import { attach as k, combine as A, createApi as j, createDomain as M, createEffect as N, createEvent as P, createStore as F, is as
|
|
8
|
+
import { t as te } from "../id-Bo4RBeOs.js";
|
|
9
|
+
import { t as ne } from "../version-IAAIvoH9.js";
|
|
10
|
+
import { n as re, r as ie, t as ae } from "../inert-script-report-B_bMPRzp.js";
|
|
11
|
+
import { attach as k, combine as A, createApi as j, createDomain as M, createEffect as N, createEvent as P, createStore as F, is as oe, sample as I } from "effector";
|
|
12
12
|
import { createFactory as L, invoke as R } from "@withease/factories";
|
|
13
|
+
import { sendPing as se } from "@picked/delivery-api-client";
|
|
13
14
|
//#region src/entities/experience/experience.ts
|
|
14
15
|
var z = M("experience"), ce = L(({ client: e, experience: r }) => {
|
|
15
16
|
let i = z.store(r), a = j(i, { merge(e, t) {
|
|
@@ -572,13 +573,13 @@ var Fe = 6e3, Ie = O("last_ping", "global"), Le = async (e) => {
|
|
|
572
573
|
try {
|
|
573
574
|
let t = Date.now(), n = E.get(Ie), r = 0;
|
|
574
575
|
if (n.isSet() && (r = n.json() ?? 0), r && t - r < Fe) return !0;
|
|
575
|
-
let i = {
|
|
576
|
+
let i = {}, a = document.getElementById("picked_script")?.dataset.verceltoken;
|
|
577
|
+
a && (i["x-vercel-protection-bypass"] = a);
|
|
578
|
+
let o = await se(e.apiUrl, {
|
|
576
579
|
projectId: e.projectId,
|
|
577
580
|
path: window.location.pathname
|
|
578
|
-
},
|
|
579
|
-
o && (
|
|
580
|
-
let s = (await te(e.apiUrl, "ping", i, a)).ok;
|
|
581
|
-
return s && n.set(t), s;
|
|
581
|
+
}, { headers: i });
|
|
582
|
+
return o && n.set(t), o;
|
|
582
583
|
} catch {
|
|
583
584
|
return !1;
|
|
584
585
|
}
|
|
@@ -1041,7 +1042,7 @@ var Je = (e, t, n) => {
|
|
|
1041
1042
|
}, J = M("history");
|
|
1042
1043
|
function Ye(e, t) {
|
|
1043
1044
|
return {
|
|
1044
|
-
id:
|
|
1045
|
+
id: te(`history-entry-${Date.now()}-${Math.random()}}`),
|
|
1045
1046
|
node: t,
|
|
1046
1047
|
at: Date.now(),
|
|
1047
1048
|
experienceId: e
|
|
@@ -1773,7 +1774,7 @@ var Kt = class {
|
|
|
1773
1774
|
dataProviderFor(e) {
|
|
1774
1775
|
let t = e ?? "", n = this.dataProviders.get(t);
|
|
1775
1776
|
if (n) return n;
|
|
1776
|
-
let r = import("../provider-
|
|
1777
|
+
let r = import("../provider-BEpRDCyr.js").then((t) => t.createPickedDataProvider({
|
|
1777
1778
|
apiUrl: this.apiUrl,
|
|
1778
1779
|
projectId: this.projectId,
|
|
1779
1780
|
...e !== void 0 && { previewToken: e }
|
|
@@ -1983,12 +1984,12 @@ function rn(e, t) {
|
|
|
1983
1984
|
return n;
|
|
1984
1985
|
}
|
|
1985
1986
|
function an(e, t) {
|
|
1986
|
-
if (
|
|
1987
|
+
if (oe.store(t)) return A(t, e.indexStore, (e, t) => nn(t, $(e)));
|
|
1987
1988
|
let n = $(t);
|
|
1988
1989
|
return e.indexStore.map((e) => nn(e, n), { skipVoid: !1 });
|
|
1989
1990
|
}
|
|
1990
1991
|
function on(e, t) {
|
|
1991
|
-
if (
|
|
1992
|
+
if (oe.store(t)) return A(t, e.indexStore, (e, t) => rn(t, tn(e)));
|
|
1992
1993
|
let n = tn(t);
|
|
1993
1994
|
return e.indexStore.map((e) => rn(e, n), { skipVoid: !1 });
|
|
1994
1995
|
}
|
|
@@ -1999,4 +2000,12 @@ var sn = (e) => {
|
|
|
1999
2000
|
return u(t), t;
|
|
2000
2001
|
};
|
|
2001
2002
|
//#endregion
|
|
2002
|
-
|
|
2003
|
+
//#region src/typed-content.ts
|
|
2004
|
+
function cn(e) {
|
|
2005
|
+
return typeof e.data == "object";
|
|
2006
|
+
}
|
|
2007
|
+
function ln(e) {
|
|
2008
|
+
return e.map((e) => !e || !cn(e) ? null : e, { skipVoid: !1 });
|
|
2009
|
+
}
|
|
2010
|
+
//#endregion
|
|
2011
|
+
export { Yt as PICKED_HYDRATED_ATTR, Jt as PICKED_MODULE_SCRIPT_TYPE, qt as PICKED_SCRIPT_TYPE, Wt as PREVIEW_TOKEN_PARAM, Kt as Picked, Zt as buildRehydrateBootstrap, sn as createClient, pe as createPluginEffect, O as createStorageKey, an as deriveReference, on as deriveReferences, n as evaluateRuleLogic, Ft as getPickedConfig, Q as isContentReference, Qt as isHtmlAssetValue, h as isInsideIframe, en as isLazyLoader, _ as isPickedRoot, Gt as isPreviewSession, $t as lazyComponent, E as localStore, ae as onInertScriptSubtrees, $ as readReferenceId, tn as readReferenceIds, Xt as rehydrateScripts, re as reportInertScriptSubtrees, ie as resetInertScriptReport, D as sessionStore, T as subscribe, d as supportsCookies, p as supportsCryptoRandomUUID, c as supportsDocument, i as supportsHistory, f as supportsIntersectionObserver, m as supportsLocalStorage, a as supportsLocation, l as supportsSessionStorage, g as supportsShadowRoot, o as supportsWebComponents, s as supportsWindow, ln as toTypedContentStore };
|
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { t } from "../../../
|
|
3
|
-
import {
|
|
4
|
-
|
|
1
|
+
import { t as e } from "../../../plugin-C8hWW3ed.js";
|
|
2
|
+
import { n as t, t as n } from "../../../api-C8B96Kwv.js";
|
|
3
|
+
import { n as r } from "../../../registry-CXZv0uLg.js";
|
|
4
|
+
import { createClientHeaders as i, fetchSchema as a } from "@picked/delivery-api-client";
|
|
5
|
+
export { i as createClientHeaders, e as dynamicExperiencesPlugin, n as fetchExperienceContent, t as fetchProject, a as fetchSchema, r as registerPickedBundle };
|
package/dist/esm/server/index.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { a as e, c as t, i as n, o as r, s as i, t as a, u as o } from "../../experience-instance-DGk11d8a.js";
|
|
2
|
-
import { n as s } from "../../plugin-
|
|
2
|
+
import { n as s } from "../../plugin-C8hWW3ed.js";
|
|
3
3
|
import { attach as c, createEffect as l, createEvent as u, createStore as d, sample as f } from "effector";
|
|
4
4
|
//#region src/server/serialize.ts
|
|
5
5
|
var p = 1e4;
|