@farm.js/contentful 0.1.0-beta.104

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Farm.js Team
+
+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,33 @@
+# @farm.js/contentful
+
+Contentful content source for [Farm.js](https://github.com/farming-labs/farm.js). Feeds Contentful
+entries into `@farm.js/content` collections, where they get the same schema validation, transforms,
+and generated server types as local Markdown.
+
+```ts
+import { collection, content } from "@farm.js/content";
+import { contentfulSource } from "@farm.js/contentful";
+
+content({
+  collections: {
+    posts: collection({
+      source: contentfulSource({
+        contentType: "post",
+        query: { order: ["-sys.createdAt"] },
+        refreshInterval: 30_000, // dev only
+      }),
+      schema: post,
+    }),
+  },
+});
+```
+
+Set `CONTENTFUL_SPACE_ID` and `CONTENTFUL_ACCESS_TOKEN`, or pass an existing client through
+`client`. Entry IDs default to a string `fields.slug`, falling back to `sys.id`. Pagination past
+Contentful's 1000-entry page cap is handled internally. For drafts, set
+`host: "preview.contentful.com"` with `CONTENTFUL_PREVIEW_TOKEN`.
+
+Content is a build-time snapshot: entries are fetched while the configuration loads and bundled
+into production output. Point a Contentful webhook at your platform's deploy hook to rebuild on
+publish. See the [content plugin docs](https://farmjs.dev/docs/plugins/content) for the shared
+pipeline and the live-content alternative.

package/dist/content.d.ts

@@ -0,0 +1,45 @@
+import type { ContentRemoteSource } from "@farm.js/content";
+import { type ContentfulClientApi } from "contentful";
+export interface ContentfulSourceOptions {
+    /** Contentful content type ID to load, e.g. "post". */
+    contentType: string;
+    /**
+     * Extra `getEntries` parameters: `order`, `include`, field filters. `skip`
+     * and `content_type` are owned by the source; `limit` caps the page size.
+     */
+    query?: Record<string, unknown>;
+    /** Existing Contentful client. When provided, Farm does not construct its own. */
+    client?: ContentfulClientApi<undefined>;
+    /** Defaults to `CONTENTFUL_SPACE_ID`. */
+    space?: string;
+    /** Defaults to `CONTENTFUL_ACCESS_TOKEN` (`CONTENTFUL_PREVIEW_TOKEN` for the preview host). */
+    accessToken?: string;
+    /** Defaults to `CONTENTFUL_ENVIRONMENT`, then "master". */
+    environment?: string;
+    /** Set "preview.contentful.com" with a preview token to load drafts. */
+    host?: string;
+    /** Names the source in error messages. Defaults to `contentful:<contentType>`. */
+    name?: string;
+    /**
+     * Entry identifier per document. Defaults to a string `fields.slug` when
+     * present, falling back to `sys.id`.
+     */
+    id?: (entry: {
+        sys: {
+            id: string;
+        };
+        fields: Record<string, unknown>;
+    }) => string;
+    /** Optional Markdown body per document, for `entry.body` and word counts. */
+    body?: (fields: Record<string, unknown>) => string | undefined;
+    /** Development re-fetch cadence in milliseconds. */
+    refreshInterval?: number;
+}
+/**
+ * A `@farm.js/content` source that loads entries from Contentful, so a CMS
+ * collection gets the same schema validation, transforms, and generated
+ * server types as local files. Content is a build-time snapshot; point a
+ * Contentful webhook at a deploy hook to rebuild on publish.
+ */
+export declare function contentfulSource(options: ContentfulSourceOptions): ContentRemoteSource;
+//# sourceMappingURL=content.d.ts.map

package/dist/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAyB,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAapE,MAAM,WAAW,uBAAuB;IACtC,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,kFAAkF;IAClF,MAAM,CAAC,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;IACxC,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE;YAAE,EAAE,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,KAAK,MAAM,CAAC;IACjF,6EAA6E;IAC7E,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;IAC/D,oDAAoD;IACpD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAKD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,mBAAmB,CAmFtF"}

package/dist/content.js

@@ -0,0 +1,85 @@
+import { createClient } from "contentful";
+/** Contentful caps a single page at 1000 entries. */
+const PAGE_SIZE = 1000;
+/**
+ * A `@farm.js/content` source that loads entries from Contentful, so a CMS
+ * collection gets the same schema validation, transforms, and generated
+ * server types as local files. Content is a build-time snapshot; point a
+ * Contentful webhook at a deploy hook to rebuild on publish.
+ */
+export function contentfulSource(options) {
+    if (typeof options?.contentType !== "string" || !options.contentType.trim()) {
+        throw new TypeError("contentfulSource() requires a `contentType`");
+    }
+    const name = options.name ?? `contentful:${options.contentType}`;
+    const resolveId = options.id ?? defaultEntryId;
+    // Resolved lazily so importing farm.config.ts without the env set only
+    // fails when the collection actually loads, with an actionable message.
+    let client = options.client;
+    const resolveClient = () => {
+        if (client)
+            return client;
+        const preview = options.host?.includes("preview") ?? false;
+        const space = options.space ?? process.env.CONTENTFUL_SPACE_ID;
+        const accessToken = options.accessToken ??
+            (preview ? process.env.CONTENTFUL_PREVIEW_TOKEN : undefined) ??
+            process.env.CONTENTFUL_ACCESS_TOKEN;
+        if (!space || !accessToken) {
+            throw new Error(`contentfulSource(${JSON.stringify(name)}) requires a space and access token. Set ` +
+                "CONTENTFUL_SPACE_ID and CONTENTFUL_ACCESS_TOKEN, pass them to contentfulSource(), " +
+                "or supply an existing client through `client`.");
+        }
+        client = createClient({
+            space,
+            accessToken,
+            environment: options.environment ?? process.env.CONTENTFUL_ENVIRONMENT ?? "master",
+            ...(options.host ? { host: options.host } : {}),
+        });
+        return client;
+    };
+    return {
+        kind: "remote",
+        name,
+        ...(options.refreshInterval !== undefined ? { refreshInterval: options.refreshInterval } : {}),
+        async fetch() {
+            const resolved = resolveClient();
+            const pageSize = Math.min(Number(options.query?.limit ?? PAGE_SIZE) || PAGE_SIZE, PAGE_SIZE);
+            const entries = [];
+            // getEntries pages at most 1000 entries; keep fetching until `total`.
+            for (let skip = 0;; skip += pageSize) {
+                const page = (await resolved.getEntries({
+                    ...options.query,
+                    content_type: options.contentType,
+                    limit: pageSize,
+                    skip,
+                }));
+                if (!page || !Array.isArray(page.items)) {
+                    throw new Error(`contentfulSource(${JSON.stringify(name)}) received a response without items`);
+                }
+                entries.push(...page.items);
+                if (entries.length >= page.total || page.items.length === 0)
+                    break;
+            }
+            return entries.map((entry, index) => {
+                if (!entry?.sys?.id || !entry.fields || typeof entry.fields !== "object") {
+                    throw new Error(`contentfulSource(${JSON.stringify(name)}) entry at index ${index} is missing sys.id or fields`);
+                }
+                const id = resolveId(entry);
+                if (typeof id !== "string" || !id) {
+                    throw new Error(`contentfulSource(${JSON.stringify(name)}) could not derive an id for entry ` +
+                        `${JSON.stringify(entry.sys.id)}; give entries a slug field or pass an \`id\` function`);
+                }
+                const body = options.body?.(entry.fields);
+                return {
+                    id,
+                    data: entry.fields,
+                    ...(typeof body === "string" ? { body } : {}),
+                };
+            });
+        },
+    };
+}
+function defaultEntryId(entry) {
+    const slug = entry.fields.slug;
+    return typeof slug === "string" && slug ? slug : entry.sys.id;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { contentfulSource } from "./content.js";
+export type { ContentfulSourceOptions } from "./content.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { contentfulSource } from "./content.js";

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@farm.js/contentful",
+  "version": "0.1.0-beta.104",
+  "description": "Contentful content source for Farm.js",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farming-labs/farm.js",
+    "directory": "packages/farm-contentful"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "contentful": "^11.8.6",
+    "typescript": "^5.3.3",
+    "vitest": "^3.2.7",
+    "@farm.js/content": "0.1.0-beta.0"
+  },
+  "peerDependencies": {
+    "contentful": "^10.0.0 || ^11.0.0",
+    "@farm.js/content": "^0.1.0-beta.0"
+  },
+  "peerDependenciesMeta": {
+    "@farm.js/content": {
+      "optional": false
+    }
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}