@contentful/experiences-client 0.1.4 β 0.1.5
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/CHANGELOG.md +6 -0
- package/README.md +32 -8
- package/dist/fetch-experience.d.ts +17 -0
- package/dist/fetch-experience.js +16 -1
- package/dist/fetch-experience.js.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
package/README.md
CHANGED
|
@@ -14,11 +14,11 @@ The primary fetch + resolve entry point. Fetches an Experience payload from the
|
|
|
14
14
|
|
|
15
15
|
Three positional args group by concern:
|
|
16
16
|
|
|
17
|
-
| Arg | Type
|
|
18
|
-
| ------------------- |
|
|
19
|
-
| `experienceOptions` | `{ spaceId, environmentId, experienceId, locale? }`
|
|
20
|
-
| `clientOptions` | `{ accessToken, host? }` **or** `{ client }`
|
|
21
|
-
| `resolveOptions` | `{ config, context? }`
|
|
17
|
+
| Arg | Type | Purpose |
|
|
18
|
+
| ------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
|
19
|
+
| `experienceOptions` | `{ spaceId, environmentId, experienceId, locale? }` | Which Experience to fetch. |
|
|
20
|
+
| `clientOptions` | `{ accessToken, previewToken?, preview?, host? }` **or** `{ client }` | How to fetch β inline credentials (with optional preview toggle) or a pre-made client. |
|
|
21
|
+
| `resolveOptions` | `{ config, context? }` | How to resolve β component registry + context. |
|
|
22
22
|
|
|
23
23
|
```ts
|
|
24
24
|
import { fetchExperience } from '@contentful/experiences-react'; // or experiences-svelte
|
|
@@ -28,7 +28,8 @@ const plan = await fetchExperience(
|
|
|
28
28
|
{ spaceId: '...', environmentId: 'master', experienceId: slug, locale: 'en-US' },
|
|
29
29
|
{
|
|
30
30
|
accessToken: process.env.CDA_TOKEN!,
|
|
31
|
-
|
|
31
|
+
previewToken: process.env.PREVIEW_TOKEN!, // optional β only required when preview: true
|
|
32
|
+
preview: false, // flip to true for preview mode; picks previewToken + preview host
|
|
32
33
|
},
|
|
33
34
|
{
|
|
34
35
|
config: experienceConfig,
|
|
@@ -48,16 +49,39 @@ const plan = await fetchExperience(
|
|
|
48
49
|
|
|
49
50
|
Returns `PortableRenderPlan`. An empty-nodes payload (draft / unpublished / empty locale) resolves to a valid plan with `nodes: []` β it is not a 404. For the missing-experience case, catch `NotFoundError` (re-exported below).
|
|
50
51
|
|
|
52
|
+
#### Preview mode
|
|
53
|
+
|
|
54
|
+
Configure both tokens up front and flip `preview: true` per call to hit the preview API.
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
const experience = await fetchExperience(
|
|
58
|
+
{ spaceId, environmentId, experienceId },
|
|
59
|
+
{
|
|
60
|
+
accessToken: process.env.CDA_TOKEN!,
|
|
61
|
+
previewToken: process.env.PREVIEW_TOKEN!,
|
|
62
|
+
preview: previewMode, // boolean β flip per request
|
|
63
|
+
},
|
|
64
|
+
{ config: experienceConfig }
|
|
65
|
+
);
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
- `preview: false` (or unset) β uses `accessToken` against the delivery host.
|
|
69
|
+
- `preview: true` β uses `previewToken` against the preview host. Throws `fetchExperience() called with preview: true but no previewToken was provided` if `previewToken` is missing.
|
|
70
|
+
- `host` is only for custom base URLs (staging, proxy, per-region). When set, it wins over the `preview`-derived host β so `{ previewToken, preview: true, host: 'https://preview-stagingβ¦' }` uses the preview token against your custom URL.
|
|
71
|
+
- With the `{ client }` option, `preview` is ignored (bring your own client, bring your own token/host choice).
|
|
72
|
+
|
|
51
73
|
### `createClient(options)`
|
|
52
74
|
|
|
53
|
-
Functional constructor over `ContentfulViewDeliveryClient` matching the SDK's option shape. Maps `accessToken β token` and `host β baseUrl`; passes everything else through unchanged. Prefer over `new ContentfulViewDeliveryClient({...})` so field names stay consistent with `fetchExperience`'s inline-
|
|
75
|
+
Functional constructor over `ContentfulViewDeliveryClient` matching the SDK's option shape. Maps `accessToken β token` and `host β baseUrl`; passes everything else through unchanged. Prefer over `new ContentfulViewDeliveryClient({...})` so field names stay consistent with `fetchExperience`'s inline-credentials path.
|
|
76
|
+
|
|
77
|
+
`createClient` is a one-time setup primitive β it builds a single client bound to a single token and does not participate in the per-request `preview` toggle. If you need runtime-dynamic swaps between delivery and preview, use `fetchExperience`'s inline-credentials path (`{ accessToken, previewToken, preview }`) instead of pre-building a client via `createClient` and passing `{ client }`.
|
|
54
78
|
|
|
55
79
|
```ts
|
|
56
80
|
import { createClient } from '@contentful/experiences-react';
|
|
57
81
|
|
|
58
82
|
const client = createClient({
|
|
59
83
|
accessToken: process.env.CDA_TOKEN!,
|
|
60
|
-
host: 'https://preview.
|
|
84
|
+
host: 'https://preview-staging.example.com', // optional custom base URL
|
|
61
85
|
// headers, timeoutInSeconds, maxRetries, fetch, logging pass through
|
|
62
86
|
});
|
|
63
87
|
```
|
|
@@ -9,6 +9,23 @@ type ExperienceOptions = {
|
|
|
9
9
|
};
|
|
10
10
|
type ClientOptions = {
|
|
11
11
|
accessToken: string;
|
|
12
|
+
/**
|
|
13
|
+
* Preview access token. Required when calling with `preview: true`.
|
|
14
|
+
*/
|
|
15
|
+
previewToken?: string;
|
|
16
|
+
/**
|
|
17
|
+
* Flip between delivery (default) and preview at request time. When
|
|
18
|
+
* `true`, `fetchExperience` uses `previewToken` and the preview host;
|
|
19
|
+
* when `false` or unset, it uses `accessToken` and the delivery host.
|
|
20
|
+
* Ignored when a pre-made `client` is passed instead of inline creds.
|
|
21
|
+
*/
|
|
22
|
+
preview?: boolean;
|
|
23
|
+
/**
|
|
24
|
+
* Custom base URL for the delivery client (staging, proxy, per-region).
|
|
25
|
+
* Wins over the `preview`-derived default host β combine `host` with
|
|
26
|
+
* `preview: true` to point preview mode at a non-prod endpoint.
|
|
27
|
+
* Omit for the standard delivery / preview hosts.
|
|
28
|
+
*/
|
|
12
29
|
host?: string;
|
|
13
30
|
} | {
|
|
14
31
|
client: ContentfulViewDeliveryClient;
|
package/dist/fetch-experience.js
CHANGED
|
@@ -1,9 +1,24 @@
|
|
|
1
1
|
import { resolveExperience } from "@contentful/experiences-sdk-core";
|
|
2
2
|
import { createClient } from "./create-client.js";
|
|
3
|
+
const PREVIEW_HOST = "https://preview.xdn.contentful.com";
|
|
3
4
|
async function fetchExperience(experienceOptions, clientOptions, resolveOptions) {
|
|
4
5
|
const { spaceId, environmentId, experienceId, locale } = experienceOptions;
|
|
5
6
|
const { config, context } = resolveOptions;
|
|
6
|
-
|
|
7
|
+
let client;
|
|
8
|
+
if ("client" in clientOptions) {
|
|
9
|
+
client = clientOptions.client;
|
|
10
|
+
} else {
|
|
11
|
+
const { accessToken, previewToken, preview, host } = clientOptions;
|
|
12
|
+
if (preview && !previewToken) {
|
|
13
|
+
throw new Error(
|
|
14
|
+
"fetchExperience() called with preview: true but no previewToken was provided"
|
|
15
|
+
);
|
|
16
|
+
}
|
|
17
|
+
client = createClient({
|
|
18
|
+
accessToken: preview ? previewToken : accessToken,
|
|
19
|
+
host: host ?? (preview ? PREVIEW_HOST : void 0)
|
|
20
|
+
});
|
|
21
|
+
}
|
|
7
22
|
const payload = await client.view.getExperience(spaceId, environmentId, experienceId, {
|
|
8
23
|
locale
|
|
9
24
|
});
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/fetch-experience.ts"],"sourcesContent":["import type { ContentfulViewDeliveryClient } from '@contentful/experience-delivery';\nimport { resolveExperience } from '@contentful/experiences-sdk-core';\nimport type {\n ExperiencePayload,\n PortableRenderPlan,\n ResolveExperienceOptions,\n ResolverConfig,\n} from '@contentful/experiences-sdk-core';\nimport { createClient } from './create-client.js';\n\nexport type ExperienceOptions = {\n spaceId: string;\n environmentId: string;\n experienceId: string;\n locale?: string;\n};\n\nexport type ClientOptions =\n | {
|
|
1
|
+
{"version":3,"sources":["../src/fetch-experience.ts"],"sourcesContent":["import type { ContentfulViewDeliveryClient } from '@contentful/experience-delivery';\nimport { resolveExperience } from '@contentful/experiences-sdk-core';\nimport type {\n ExperiencePayload,\n PortableRenderPlan,\n ResolveExperienceOptions,\n ResolverConfig,\n} from '@contentful/experiences-sdk-core';\nimport { createClient } from './create-client.js';\n\nconst PREVIEW_HOST = 'https://preview.xdn.contentful.com';\n\nexport type ExperienceOptions = {\n spaceId: string;\n environmentId: string;\n experienceId: string;\n locale?: string;\n};\n\nexport type ClientOptions =\n | {\n accessToken: string;\n /**\n * Preview access token. Required when calling with `preview: true`.\n */\n previewToken?: string;\n /**\n * Flip between delivery (default) and preview at request time. When\n * `true`, `fetchExperience` uses `previewToken` and the preview host;\n * when `false` or unset, it uses `accessToken` and the delivery host.\n * Ignored when a pre-made `client` is passed instead of inline creds.\n */\n preview?: boolean;\n /**\n * Custom base URL for the delivery client (staging, proxy, per-region).\n * Wins over the `preview`-derived default host β combine `host` with\n * `preview: true` to point preview mode at a non-prod endpoint.\n * Omit for the standard delivery / preview hosts.\n */\n host?: string;\n }\n | { client: ContentfulViewDeliveryClient };\n\nexport type ResolveOptions = {\n config: ResolverConfig;\n context?: ResolveExperienceOptions['experience'];\n};\n\nexport async function fetchExperience(\n experienceOptions: ExperienceOptions,\n clientOptions: ClientOptions,\n resolveOptions: ResolveOptions\n): Promise<PortableRenderPlan> {\n const { spaceId, environmentId, experienceId, locale } = experienceOptions;\n const { config, context } = resolveOptions;\n\n let client: ContentfulViewDeliveryClient;\n if ('client' in clientOptions) {\n client = clientOptions.client;\n } else {\n const { accessToken, previewToken, preview, host } = clientOptions;\n if (preview && !previewToken) {\n throw new Error(\n 'fetchExperience() called with preview: true but no previewToken was provided'\n );\n }\n client = createClient({\n accessToken: preview ? (previewToken as string) : accessToken,\n host: host ?? (preview ? PREVIEW_HOST : undefined),\n });\n }\n\n // Response from the experience delivery client is structurally compatible with ExperiencePayload (superset)\n const payload = (await client.view.getExperience(spaceId, environmentId, experienceId, {\n locale,\n })) as unknown as ExperiencePayload;\n\n return resolveExperience(payload, config, { experience: context });\n}\n"],"mappings":"AACA,SAAS,yBAAyB;AAOlC,SAAS,oBAAoB;AAE7B,MAAM,eAAe;AAsCrB,eAAsB,gBACpB,mBACA,eACA,gBAC6B;AAC7B,QAAM,EAAE,SAAS,eAAe,cAAc,OAAO,IAAI;AACzD,QAAM,EAAE,QAAQ,QAAQ,IAAI;AAE5B,MAAI;AACJ,MAAI,YAAY,eAAe;AAC7B,aAAS,cAAc;AAAA,EACzB,OAAO;AACL,UAAM,EAAE,aAAa,cAAc,SAAS,KAAK,IAAI;AACrD,QAAI,WAAW,CAAC,cAAc;AAC5B,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,aAAS,aAAa;AAAA,MACpB,aAAa,UAAW,eAA0B;AAAA,MAClD,MAAM,SAAS,UAAU,eAAe;AAAA,IAC1C,CAAC;AAAA,EACH;AAGA,QAAM,UAAW,MAAM,OAAO,KAAK,cAAc,SAAS,eAAe,cAAc;AAAA,IACrF;AAAA,EACF,CAAC;AAED,SAAO,kBAAkB,SAAS,QAAQ,EAAE,YAAY,QAAQ,CAAC;AACnE;","names":[]}
|