@contentful/experiences-client 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+## 0.1.1 (2026-07-17)
+
+### 🧱 Updated Dependencies
+
+- Updated core to 0.5.1
+
+## 0.1.0 (2026-07-17)
+
+### 🚀 Features
+
+- add packages/client with fetchExperience and delivery client [AIS-147] ([#30](https://github.com/contentful/experiences/pull/30), [#27](https://github.com/contentful/experiences/issues/27))
+
+### 🧱 Updated Dependencies
+
+- Updated core to 0.5.0

package/README.md

@@ -0,0 +1,117 @@
+# @contentful/experiences-client
+
+> **Internal package.** Published to npm so framework adapters can resolve it at install time, but not intended for direct customer import. Consumed transitively via the framework adapter (`@contentful/experiences-react`, `@contentful/experiences-svelte`, etc.).
+
+Isolates `@contentful/experience-delivery` — the generated experience delivery client — so that `@contentful/experiences-core` stays zero-dep and framework adapters that don't need network access don't pull it in transitively.
+
+---
+
+## What's in here
+
+### `fetchExperience(experienceOptions, clientOptions, resolveOptions)`
+
+The primary fetch + resolve entry point. Fetches an Experience payload from the Experience Delivery API and resolves it into a `PortableRenderPlan` in one call.
+
+Three positional args group by concern:
+
+| Arg                 | Type                                                | Purpose                                           |
+| ------------------- | --------------------------------------------------- | ------------------------------------------------- |
+| `experienceOptions` | `{ spaceId, environmentId, experienceId, locale? }` | Which Experience to fetch.                        |
+| `clientOptions`     | `{ accessToken, host? }` **or** `{ client }`        | How to fetch — inline creds or a pre-made client. |
+| `resolveOptions`    | `{ config, context? }`                              | How to resolve — component registry + context.    |
+
+```ts
+import { fetchExperience } from '@contentful/experiences-react'; // or experiences-svelte
+
+// Inline credentials — client created internally
+const plan = await fetchExperience(
+  { spaceId: '...', environmentId: 'master', experienceId: slug, locale: 'en-US' },
+  {
+    accessToken: process.env.CDA_TOKEN!,
+    host: 'https://preview.xdn.contentful.com', // optional — omit for default endpoint
+  },
+  {
+    config: experienceConfig,
+    context: { isPreview: false, metadata: { slug } }, // flows into resolveData hooks
+  }
+);
+
+// Pre-created client — useful when you manage the client lifecycle yourself
+import { createClient } from '@contentful/experiences-react';
+const client = createClient({ accessToken: process.env.CDA_TOKEN! });
+const plan = await fetchExperience(
+  { spaceId, environmentId, experienceId },
+  { client },
+  { config: experienceConfig }
+);
+```
+
+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).
+
+### `createClient(options)`
+
+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-creds path.
+
+```ts
+import { createClient } from '@contentful/experiences-react';
+
+const client = createClient({
+  accessToken: process.env.CDA_TOKEN!,
+  host: 'https://preview.xdn.contentful.com', // optional
+  // headers, timeoutInSeconds, maxRetries, fetch, logging pass through
+});
+```
+
+### `NotFoundError`
+
+Re-exported from `@contentful/experience-delivery` as a value + type. Thrown by the underlying delivery client on 404 responses. Route it to your framework's 404 idiom:
+
+```ts
+import { fetchExperience, NotFoundError } from '@contentful/experiences-react';
+
+try {
+  const experience = await fetchExperience(/* … */);
+  // …
+} catch (err) {
+  if (err instanceof NotFoundError) notFound(); // Next.js
+  throw err;
+}
+```
+
+The full delivery-client error namespace is also re-exported as `ContentfulViewDelivery` (`UnauthorizedError`, `ForbiddenError`, `ConflictError`, `UnprocessableEntityError`, `InternalServerError`, `ContentfulViewDeliveryError`, `ContentfulViewDeliveryTimeoutError`).
+
+### `ContentfulViewDeliveryClient`
+
+Re-exported directly from `@contentful/experience-delivery`. Exposed for advanced use cases where you want full control over the client (custom base URL, request options, reuse across calls). Most consumers should prefer `createClient` (above).
+
+```ts
+import { ContentfulViewDeliveryClient } from '@contentful/experiences-react';
+
+const client = new ContentfulViewDeliveryClient({
+  token: process.env.CDA_TOKEN!,
+  baseUrl: 'https://xdn.contentful.com', // default delivery endpoint
+});
+```
+
+---
+
+## Why a separate package?
+
+`@contentful/experiences-core` is intentionally zero-dep and runtime-neutral — it must stay importable without pulling in any network or platform code. The experience delivery client is large (~3,000 generated files) and only needed when doing server-side fetching. Isolating it here means:
+
+- Core stays lean and usable in any environment (edge, SSR, test fixtures).
+- Future adapters that render from local fixtures or a custom fetch path don't pay the delivery client's weight.
+- The delivery client version can be bumped in one place.
+
+---
+
+## Package conventions
+
+- Do not import `@contentful/experience-delivery` from anywhere except this package.
+- Re-export only what framework adapters need to surface to customers.
+- Keep `fetchExperience` thin — fetch + cast + resolve. Business logic belongs in `packages/core`.
+- Name mappings between SDK options and delivery-client options live in `create-client.ts` — one place to change.
+
+## License
+
+MIT. See the repository [`LICENSE`](../../LICENSE) and [`NOTICE`](../../NOTICE) for full attribution.

package/dist/create-client.d.ts

@@ -0,0 +1,9 @@
+import { ContentfulViewDeliveryClient } from '@contentful/experience-delivery';
+
+type CreateClientOptions = {
+    accessToken: string;
+    host?: string;
+} & Omit<ContentfulViewDeliveryClient.Options, 'token' | 'baseUrl'>;
+declare function createClient(options: CreateClientOptions): ContentfulViewDeliveryClient;
+
+export { type CreateClientOptions, createClient };

package/dist/create-client.js

@@ -0,0 +1,13 @@
+import { ContentfulViewDeliveryClient } from "@contentful/experience-delivery";
+function createClient(options) {
+  const { accessToken, host, ...rest } = options;
+  return new ContentfulViewDeliveryClient({
+    ...rest,
+    token: accessToken,
+    baseUrl: host
+  });
+}
+export {
+  createClient
+};
+//# sourceMappingURL=create-client.js.map

package/dist/create-client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/create-client.ts"],"sourcesContent":["import { ContentfulViewDeliveryClient } from '@contentful/experience-delivery';\n\nexport type CreateClientOptions = {\n  accessToken: string;\n  host?: string;\n} & Omit<ContentfulViewDeliveryClient.Options, 'token' | 'baseUrl'>;\n\nexport function createClient(options: CreateClientOptions): ContentfulViewDeliveryClient {\n  const { accessToken, host, ...rest } = options;\n  return new ContentfulViewDeliveryClient({\n    ...rest,\n    token: accessToken,\n    baseUrl: host,\n  });\n}\n"],"mappings":"AAAA,SAAS,oCAAoC;AAOtC,SAAS,aAAa,SAA4D;AACvF,QAAM,EAAE,aAAa,MAAM,GAAG,KAAK,IAAI;AACvC,SAAO,IAAI,6BAA6B;AAAA,IACtC,GAAG;AAAA,IACH,OAAO;AAAA,IACP,SAAS;AAAA,EACX,CAAC;AACH;","names":[]}

package/dist/fetch-experience.d.ts

@@ -0,0 +1,22 @@
+import { ContentfulViewDeliveryClient } from '@contentful/experience-delivery';
+import { ResolverConfig, ResolveExperienceOptions, PortableRenderPlan } from '@contentful/experiences-core';
+
+type ExperienceOptions = {
+    spaceId: string;
+    environmentId: string;
+    experienceId: string;
+    locale?: string;
+};
+type ClientOptions = {
+    accessToken: string;
+    host?: string;
+} | {
+    client: ContentfulViewDeliveryClient;
+};
+type ResolveOptions = {
+    config: ResolverConfig;
+    context?: ResolveExperienceOptions['experience'];
+};
+declare function fetchExperience(experienceOptions: ExperienceOptions, clientOptions: ClientOptions, resolveOptions: ResolveOptions): Promise<PortableRenderPlan>;
+
+export { type ClientOptions, type ExperienceOptions, type ResolveOptions, fetchExperience };

package/dist/fetch-experience.js

@@ -0,0 +1,15 @@
+import { resolveExperience } from "@contentful/experiences-core";
+import { createClient } from "./create-client.js";
+async function fetchExperience(experienceOptions, clientOptions, resolveOptions) {
+  const { spaceId, environmentId, experienceId, locale } = experienceOptions;
+  const { config, context } = resolveOptions;
+  const client = "client" in clientOptions ? clientOptions.client : createClient({ accessToken: clientOptions.accessToken, host: clientOptions.host });
+  const payload = await client.view.getExperience(spaceId, environmentId, experienceId, {
+    locale
+  });
+  return resolveExperience(payload, config, { experience: context });
+}
+export {
+  fetchExperience
+};
+//# sourceMappingURL=fetch-experience.js.map

package/dist/fetch-experience.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/fetch-experience.ts"],"sourcesContent":["import type { ContentfulViewDeliveryClient } from '@contentful/experience-delivery';\nimport { resolveExperience } from '@contentful/experiences-core';\nimport type {\n  ExperiencePayload,\n  PortableRenderPlan,\n  ResolveExperienceOptions,\n  ResolverConfig,\n} from '@contentful/experiences-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  | { accessToken: string; host?: string }\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  const client =\n    'client' in clientOptions\n      ? clientOptions.client\n      : createClient({ accessToken: clientOptions.accessToken, host: clientOptions.host });\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;AAkB7B,eAAsB,gBACpB,mBACA,eACA,gBAC6B;AAC7B,QAAM,EAAE,SAAS,eAAe,cAAc,OAAO,IAAI;AACzD,QAAM,EAAE,QAAQ,QAAQ,IAAI;AAE5B,QAAM,SACJ,YAAY,gBACR,cAAc,SACd,aAAa,EAAE,aAAa,cAAc,aAAa,MAAM,cAAc,KAAK,CAAC;AAGvF,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":[]}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { ContentfulViewDelivery } from '@contentful/experience-delivery';
+export { ContentfulViewDelivery, ContentfulViewDeliveryClient } from '@contentful/experience-delivery';
+export { CreateClientOptions, createClient } from './create-client.js';
+export { ClientOptions, ExperienceOptions, ResolveOptions, fetchExperience } from './fetch-experience.js';
+import '@contentful/experiences-core';
+
+declare const NotFoundError: typeof ContentfulViewDelivery.NotFoundError;
+type NotFoundError = InstanceType<typeof ContentfulViewDelivery.NotFoundError>;
+
+export { NotFoundError };

package/dist/index.js

@@ -0,0 +1,16 @@
+import { ContentfulViewDelivery } from "@contentful/experience-delivery";
+import {
+  ContentfulViewDelivery as ContentfulViewDelivery2,
+  ContentfulViewDeliveryClient
+} from "@contentful/experience-delivery";
+const NotFoundError = ContentfulViewDelivery.NotFoundError;
+import { createClient } from "./create-client.js";
+import { fetchExperience } from "./fetch-experience.js";
+export {
+  ContentfulViewDelivery2 as ContentfulViewDelivery,
+  ContentfulViewDeliveryClient,
+  NotFoundError,
+  createClient,
+  fetchExperience
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { ContentfulViewDelivery } from '@contentful/experience-delivery';\n\nexport {\n  ContentfulViewDelivery,\n  ContentfulViewDeliveryClient,\n} from '@contentful/experience-delivery';\nexport const NotFoundError = ContentfulViewDelivery.NotFoundError;\nexport type NotFoundError = InstanceType<typeof ContentfulViewDelivery.NotFoundError>;\nexport { createClient } from './create-client.js';\nexport type { CreateClientOptions } from './create-client.js';\nexport { fetchExperience } from './fetch-experience.js';\nexport type { ExperienceOptions, ClientOptions, ResolveOptions } from './fetch-experience.js';\n"],"mappings":"AAAA,SAAS,8BAA8B;AAEvC;AAAA,EACE,0BAAAA;AAAA,EACA;AAAA,OACK;AACA,MAAM,gBAAgB,uBAAuB;AAEpD,SAAS,oBAAoB;AAE7B,SAAS,uBAAuB;","names":["ContentfulViewDelivery"]}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@contentful/experiences-client",
+  "version": "0.1.1",
+  "description": "Delivery client + fetchExperience for Contentful Experiences",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/contentful/experiences.git",
+    "directory": "packages/client"
+  },
+  "dependencies": {
+    "@contentful/experience-delivery": "1.0.0-dev.3",
+    "@contentful/experiences-core": "0.5.1"
+  }
+}