@cms-lab/contentful 1.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Afaq Rashid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @cms-lab/contentful
+
+Contentful adapter for cms-lab.
+
+```ts
+cms: {
+  provider: "contentful",
+  spaceId: "my-space",
+  environment: "master",
+  accessToken: process.env.CONTENTFUL_DELIVERY_TOKEN!,
+  contentTypes: [
+    {
+      type: "page",
+      contentType: "page",
+      uidField: "routing.slug",
+      urlField: "routing.url",
+    },
+  ],
+}
+```
+
+The adapter reads Contentful Content Delivery API entries, paginates with
+`limit` and `skip`, and normalizes them into cms-lab `CMSDocument` objects.
+Top-level localized fields are flattened to the default locale when possible so
+route mappings can use common fields such as `doc.uid` or `doc.data.slug`.
+
+Use `uidField` or `urlField` when your project stores route values in custom
+fields. Both options read dotted paths from normalized `document.data`.

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { FetchLike, ContentfulCmsProviderConfig, CMSDocument, ContentfulContentTypeConfig } from '@cms-lab/core';
+
+type FetchContentfulDocumentsOptions = {
+    fetch?: FetchLike;
+};
+declare function fetchContentfulDocuments(config: ContentfulCmsProviderConfig, options?: FetchContentfulDocumentsOptions): Promise<CMSDocument[]>;
+declare function normalizeContentfulEntry(contentType: string | ContentfulContentTypeConfig, entry: unknown): CMSDocument;
+
+export { type FetchContentfulDocumentsOptions, fetchContentfulDocuments, normalizeContentfulEntry };

package/dist/index.js

@@ -0,0 +1,132 @@
+// src/index.ts
+import {
+  CmsFetchError,
+  readCmsDataPath
+} from "@cms-lab/core";
+var defaultApiUrl = "https://cdn.contentful.com";
+var defaultEnvironment = "master";
+var pageSize = 100;
+async function fetchContentfulDocuments(config, options = {}) {
+  const fetchImpl = options.fetch ?? fetch;
+  const documents = [];
+  for (const contentType of config.contentTypes) {
+    let skip = 0;
+    while (true) {
+      const url = new URL(
+        `/spaces/${encodeURIComponent(config.spaceId)}/environments/${encodeURIComponent(config.environment ?? defaultEnvironment)}/entries`,
+        config.apiUrl ?? defaultApiUrl
+      );
+      url.searchParams.set("content_type", contentType.contentType);
+      url.searchParams.set("limit", String(pageSize));
+      url.searchParams.set("skip", String(skip));
+      const response = await fetchJson(
+        fetchImpl,
+        url,
+        authHeaders(config.accessToken)
+      );
+      const rows = response.items ?? [];
+      documents.push(
+        ...rows.map((entry) => normalizeContentfulEntry(contentType, entry))
+      );
+      skip += rows.length;
+      const total = response.total ?? skip;
+      if (rows.length === 0 || skip >= total) {
+        break;
+      }
+    }
+  }
+  return documents;
+}
+function normalizeContentfulEntry(contentType, entry) {
+  const config = contentTypeConfig(contentType);
+  const record = asContentfulEntry(entry);
+  const data = normalizeFields(record.fields ?? {});
+  return {
+    id: stringFrom(record.sys?.id, "Contentful entry is missing id"),
+    type: config.type,
+    uid: optionalString(
+      mappedValue(data, config.uidField) ?? data.uid ?? data.slug
+    ),
+    url: optionalString(mappedValue(data, config.urlField)),
+    status: normalizeStatus(record.sys),
+    data
+  };
+}
+async function fetchJson(fetchImpl, url, headers) {
+  let response;
+  try {
+    response = await fetchImpl(url, { headers });
+  } catch (error) {
+    throw new CmsFetchError(
+      error instanceof Error ? error.message : `Failed to reach ${url}`
+    );
+  }
+  if (!response.ok) {
+    throw new CmsFetchError(
+      `Contentful request failed with HTTP ${response.status}`
+    );
+  }
+  return await response.json();
+}
+function authHeaders(token) {
+  return {
+    Accept: "application/json",
+    Authorization: `Bearer ${token}`
+  };
+}
+function asContentfulEntry(value) {
+  return value && typeof value === "object" ? value : {};
+}
+function normalizeFields(fields) {
+  return Object.fromEntries(
+    Object.entries(fields).map(([key, value]) => [key, selectLocalized(value)])
+  );
+}
+function selectLocalized(value) {
+  const record = asRecord(value);
+  if (!record || !isLocalizedRecord(record)) {
+    return value;
+  }
+  return record["en-US"] ?? record.en ?? Object.values(record)[0];
+}
+function isLocalizedRecord(record) {
+  const keys = Object.keys(record);
+  return keys.length > 0 && keys.every((key) => /^[a-z]{2}(?:-[A-Z]{2})?$/.test(key));
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function stringFrom(value, message) {
+  if (typeof value === "string" && value.length > 0) {
+    return value;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(value);
+  }
+  throw new CmsFetchError(message);
+}
+function optionalString(value) {
+  if (typeof value === "string" && value.length > 0) {
+    return value;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(value);
+  }
+  return void 0;
+}
+function contentTypeConfig(contentType) {
+  return typeof contentType === "string" ? { type: contentType, contentType } : contentType;
+}
+function mappedValue(data, path) {
+  return path ? readCmsDataPath(data, path) : void 0;
+}
+function normalizeStatus(sys) {
+  if (sys?.publishedVersion || sys?.publishedAt || sys?.updatedAt) {
+    return "published";
+  }
+  return "draft";
+}
+export {
+  fetchContentfulDocuments,
+  normalizeContentfulEntry
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@cms-lab/contentful",
+  "version": "1.0.5",
+  "type": "module",
+  "description": "Contentful document adapter for cms-lab.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/i-afaqrashid/cms-lab.git",
+    "directory": "packages/contentful"
+  },
+  "homepage": "https://cmslab.afaqrashid.com",
+  "bugs": {
+    "url": "https://github.com/i-afaqrashid/cms-lab/issues"
+  },
+  "keywords": [
+    "cms",
+    "contentful",
+    "testing"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cms-lab/core": "1.0.5"
+  },
+  "author": "Afaq Rashid",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --tsconfig ../../tsconfig.base.json"
+  }
+}