@farm.js/strapi 0.1.1-beta.4

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,173 @@
+# @farm.js/strapi
+
+Strapi 5 CMS integration for Farm.js applications. It configures the official Strapi client,
+unwraps typed collection reads, builds responsive image props from generated upload variants, and
+receives authenticated webhooks so cached content can be refreshed after an editor publishes.
+
+See [Stability and Support](https://farmjs.dev/docs/stability) for what this package guarantees.
+
+## Install
+
+```bash
+pnpm add @farm.js/strapi @strapi/client
+```
+
+`@strapi/client` is a peer dependency so the application and integration use one client version.
+
+## Configure
+
+```ts
+import { defineConfig } from "@farm.js/core";
+import { strapi } from "@farm.js/strapi";
+
+export default defineConfig({
+  integrations: {
+    cms: strapi(),
+  },
+});
+```
+
+With no options, values come from the environment:
+
+| Variable                | Purpose                                                         |
+| ----------------------- | --------------------------------------------------------------- |
+| `STRAPI_API_URL`        | Strapi Content API base URL, including `/api`.                  |
+| `STRAPI_MEDIA_URL`      | Optional public media origin. Defaults to the API URL's origin. |
+| `STRAPI_API_TOKEN`      | Optional server-only API token for non-public content.          |
+| `STRAPI_WEBHOOK_SECRET` | Required once webhook invalidation is configured.               |
+
+A missing API URL fails while configuration loads instead of on the first content request.
+
+## Read content
+
+Build the client once and reuse it in the integration and application server code.
+
+```ts
+// src/lib/cms.server.ts
+import {
+  createStrapiClient,
+  createStrapiCollection,
+  resolveStrapiConfig,
+  type StrapiDocument,
+} from "@farm.js/strapi";
+
+interface Article extends StrapiDocument {
+  title: string;
+  slug: string;
+}
+
+export const cms = createStrapiClient(resolveStrapiConfig({}));
+export const articles = createStrapiCollection<Article>(cms, "articles");
+```
+
+```ts
+// farm.config.ts
+integrations: {
+  cms: strapi({ instance: cms }),
+}
+```
+
+Wrap collection reads in `createServerQuery` to validate and cache the result. The helper accepts
+the official client's `populate`, `fields`, `filters`, `sort`, `pagination`, `locale`, and `status`
+query options and unwraps the REST `data` envelope.
+
+```ts
+import { createServerQuery } from "@farm.js/core";
+import { articles } from "./cms.server";
+
+export const postsQuery = createServerQuery({
+  key: () => ["strapi", "articles"],
+  staleTime: "5m",
+  handler: () =>
+    articles.find({
+      fields: ["title", "slug"],
+      populate: ["cover"],
+      sort: ["publishedAt:desc"],
+      status: "published",
+    }),
+});
+```
+
+The generic describes the fields your application expects. Keep runtime validation on the server
+query boundary because Strapi's returned fields still depend on permissions and `populate`.
+
+## Invalidate on publish
+
+Strapi can send a fixed header with every webhook. Farm verifies that shared secret before parsing
+the body and asks the application which cache entries the event affects.
+
+```ts
+strapi({
+  instance: cms,
+  webhook: {
+    onChange(payload) {
+      if (payload.model !== "article") return;
+      const entry = payload.entry as { documentId?: string; slug?: string };
+      return {
+        keys: [
+          ["strapi", "articles"],
+          ...(entry.documentId ? [["strapi", "article", entry.documentId] as const] : []),
+        ],
+        paths: ["/articles", ...(entry.slug ? [`/articles/${entry.slug}`] : [])],
+      };
+    },
+  },
+});
+```
+
+In Strapi, create a webhook under **Settings > Webhooks**:
+
+- URL: `https://your-app.example/api/strapi/webhook`
+- Events: the entry and media events your mapping handles
+- Header name: `x-farm-webhook-secret`
+- Header value: the value of `STRAPI_WEBHOOK_SECRET`
+
+You can change both `webhook.path` and `webhook.secretHeader`. Strapi does not sign or retry webhook
+deliveries, so use `staleTime` as the freshness fallback rather than relying on the webhook alone.
+
+## Serve images
+
+`getStrapiImageProps` selects the smallest generated variant at least as wide as requested and
+builds a `srcset` from the real variants on that asset. It never invents a transformation URL.
+
+```tsx
+import { getStrapiImageProps, type StrapiMediaAsset } from "@farm.js/strapi";
+
+export function Cover({ asset }: { asset: StrapiMediaAsset }) {
+  return (
+    <img
+      {...getStrapiImageProps(asset, {
+        mediaUrl: process.env.STRAPI_MEDIA_URL ?? process.env.STRAPI_API_URL,
+        width: 800,
+        sizes: "100vw",
+      })}
+    />
+  );
+}
+```
+
+Absolute upload-provider URLs are preserved. Relative URLs are resolved against `mediaUrl`, which
+can differ from the Content API host.
+
+## Production notes
+
+- Keep `STRAPI_API_TOKEN` and the official client in server-only modules. Do not import them from a
+  browser entry.
+- Farm's default data cache is in memory per process. Configure a distributed cache adapter when a
+  webhook must invalidate every server instance.
+- Strapi 5's draft status requires an API token that can read the content type. Do not make draft
+  selection depend on an untrusted query parameter; gate it behind application-owned preview auth.
+
+## Options
+
+| Option                 | Default                 | Notes                                              |
+| ---------------------- | ----------------------- | -------------------------------------------------- |
+| `apiUrl`               | `STRAPI_API_URL`        | Content API base URL, including `/api`.            |
+| `mediaUrl`             | API origin              | Public origin for relative upload URLs.            |
+| `token`                | `STRAPI_API_TOKEN`      | Server only.                                       |
+| `instance`             |                         | Existing `StrapiClient`; skips API URL validation. |
+| `webhook.secret`       | `STRAPI_WEBHOOK_SECRET` |                                                    |
+| `webhook.path`         | `/api/strapi/webhook`   |                                                    |
+| `webhook.secretHeader` | `x-farm-webhook-secret` | Configure the same custom header in Strapi.        |
+| `webhook.onChange`     |                         | Maps a payload to `{ keys?, paths? }`.             |
+| `log`                  |                         | Integration lifecycle logger.                      |

package/dist/client.d.ts

@@ -0,0 +1,4 @@
+import { type StrapiClient } from "@strapi/client";
+import type { ResolvedStrapiConfig } from "./config.js";
+export declare function createStrapiClient(config: ResolvedStrapiConfig, instance?: StrapiClient): StrapiClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,oBAAoB,EAC5B,QAAQ,CAAC,EAAE,YAAY,GACtB,YAAY,CAcd"}

package/dist/client.js

@@ -0,0 +1,14 @@
+import { strapi as createClient } from "@strapi/client";
+export function createStrapiClient(config, instance) {
+    if (instance)
+        return instance;
+    if (!config.apiUrl) {
+        throw new TypeError("Cannot create a Strapi client without an API URL. Set STRAPI_API_URL or pass apiUrl.");
+    }
+    // Map only client fields so the public media URL and webhook secret can
+    // never reach the provider SDK or one of its request interceptors.
+    return createClient({
+        baseURL: config.apiUrl,
+        ...(config.token ? { auth: config.token } : {}),
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,41 @@
+import type { FarmIntegrationLogger, RouteDataCacheKey } from "@farm.js/core";
+import type { StrapiClient } from "@strapi/client";
+export declare const DEFAULT_STRAPI_WEBHOOK_PATH = "/api/strapi/webhook";
+export declare const DEFAULT_STRAPI_WEBHOOK_SECRET_HEADER = "x-farm-webhook-secret";
+export interface StrapiWebhookChange {
+    /** Server query keys to invalidate, as passed to `createServerQuery`. */
+    keys?: readonly RouteDataCacheKey[];
+    /** Route paths whose rendered output should be revalidated. */
+    paths?: readonly string[];
+}
+export interface StrapiWebhookOptions {
+    /** Defaults to `STRAPI_WEBHOOK_SECRET`. */
+    secret?: string;
+    /** Defaults to `/api/strapi/webhook`. */
+    path?: string;
+    /** Defaults to `x-farm-webhook-secret`. */
+    secretHeader?: string;
+    /** Maps a Strapi webhook payload to the cache entries it affects. */
+    onChange(payload: Record<string, unknown>): StrapiWebhookChange | void | Promise<StrapiWebhookChange | void>;
+}
+export interface StrapiIntegrationInput {
+    /** Strapi Content API base URL, for example `http://localhost:1337/api`. */
+    apiUrl?: string;
+    /** Public origin for relative media URLs. Defaults to the API URL's origin. */
+    mediaUrl?: string;
+    /** Server-only API token. Defaults to `STRAPI_API_TOKEN`. */
+    token?: string;
+    /** Existing official Strapi client. When provided, Farm does not construct its own. */
+    instance?: StrapiClient;
+    webhook?: StrapiWebhookOptions;
+    log?: FarmIntegrationLogger;
+}
+export interface ResolvedStrapiConfig {
+    apiUrl: string;
+    mediaUrl: string;
+    token?: string;
+    webhookSecret?: string;
+}
+export declare function resolveStrapiConfig(input: StrapiIntegrationInput): ResolvedStrapiConfig;
+export declare function strapiIntegrationConfig(resolved: ResolvedStrapiConfig, input: StrapiIntegrationInput): import("@farm.js/core").FarmIntegrationConfigDefinition<ResolvedStrapiConfig, import("@farm.js/core").FarmSchema | undefined>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE9E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,eAAO,MAAM,2BAA2B,wBAAwB,CAAC;AACjE,eAAO,MAAM,oCAAoC,0BAA0B,CAAC;AAE5E,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,IAAI,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACpC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,QAAQ,CACN,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,mBAAmB,GAAG,IAAI,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;CACrE;AAED,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uFAAuF;IACvF,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,GAAG,CAAC,EAAE,qBAAqB,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAsBD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,sBAAsB,GAAG,oBAAoB,CAgBvF;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,oBAAoB,EAC9B,KAAK,EAAE,sBAAsB,iIAU9B"}

package/dist/config.js

@@ -0,0 +1,46 @@
+import { integrationConfig } from "@farm.js/integration-utils";
+export const DEFAULT_STRAPI_WEBHOOK_PATH = "/api/strapi/webhook";
+export const DEFAULT_STRAPI_WEBHOOK_SECRET_HEADER = "x-farm-webhook-secret";
+function normalizeUrl(value, label) {
+    if (!value)
+        return "";
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new TypeError(`${label} must be an absolute HTTP or HTTPS URL`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new TypeError(`${label} must use HTTP or HTTPS`);
+    }
+    return url.toString().replace(/\/$/, "");
+}
+function readEnv(name) {
+    return process.env[name] || undefined;
+}
+export function resolveStrapiConfig(input) {
+    const configuredMediaUrl = input.mediaUrl ?? readEnv("STRAPI_MEDIA_URL");
+    const mediaUrl = normalizeUrl(configuredMediaUrl, "Strapi media URL");
+    // A supplied client owns its Content API configuration. Only inspect the
+    // API URL when Farm needs it to build a client or derive the media origin.
+    const apiUrl = !input.instance || !mediaUrl
+        ? normalizeUrl(input.apiUrl ?? readEnv("STRAPI_API_URL"), "Strapi API URL")
+        : "";
+    return {
+        apiUrl,
+        mediaUrl: mediaUrl || (apiUrl ? new URL(apiUrl).origin : ""),
+        token: input.token ?? readEnv("STRAPI_API_TOKEN"),
+        webhookSecret: input.webhook?.secret ?? readEnv("STRAPI_WEBHOOK_SECRET"),
+    };
+}
+export function strapiIntegrationConfig(resolved, input) {
+    const required = input.instance ? [] : ["apiUrl"];
+    if (input.webhook)
+        required.push("webhookSecret");
+    return integrationConfig({
+        label: "Strapi integration",
+        input: resolved,
+        required,
+    });
+}

package/dist/image.d.ts

@@ -0,0 +1,35 @@
+export interface StrapiMediaFormat {
+    url: string;
+    width: number;
+    height: number;
+}
+export interface StrapiMediaAsset extends StrapiMediaFormat {
+    alternativeText?: string | null;
+    formats?: Record<string, StrapiMediaFormat | null | undefined> | null;
+}
+export interface StrapiImageOptions {
+    /** Public media origin used to resolve relative upload URLs. */
+    mediaUrl?: string;
+    /** Requested rendered width. Defaults to the original asset width. */
+    width?: number;
+    alt?: string;
+    sizes?: string;
+    loading?: "eager" | "lazy";
+}
+export interface StrapiImageProps {
+    src: string;
+    srcSet: string;
+    alt: string;
+    width: number;
+    height: number;
+    sizes?: string;
+    loading: "eager" | "lazy";
+    decoding: "async";
+}
+/**
+ * Builds native image props from the fixed variants Strapi generated at
+ * upload time. The selected `src` is the smallest available image at least as
+ * wide as requested; `srcSet` advertises the variants at their real widths.
+ */
+export declare function getStrapiImageProps(asset: StrapiMediaAsset, options?: StrapiImageOptions): StrapiImageProps;
+//# sourceMappingURL=image.d.ts.map

package/dist/image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../src/image.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC;CACvE;AAED,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;CACnB;AAqCD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,kBAAuB,GAC/B,gBAAgB,CAiClB"}

package/dist/image.js

@@ -0,0 +1,64 @@
+function resolveAssetUrl(url, mediaUrl) {
+    if (!mediaUrl && !/^https?:\/\//i.test(url)) {
+        throw new TypeError("A Strapi media URL is required for relative asset URLs");
+    }
+    let resolved;
+    try {
+        resolved = new URL(url, mediaUrl ? `${mediaUrl.replace(/\/$/, "")}/` : undefined);
+    }
+    catch {
+        throw new TypeError("Strapi image asset URL must be a valid HTTP or HTTPS URL");
+    }
+    if (resolved.protocol !== "http:" && resolved.protocol !== "https:") {
+        throw new TypeError("Strapi image asset URL must use HTTP or HTTPS");
+    }
+    return resolved.toString();
+}
+function imageCandidates(asset, mediaUrl) {
+    const candidates = [asset, ...Object.values(asset.formats ?? {}).filter(Boolean)]
+        .filter((candidate) => !!candidate &&
+        Number.isFinite(candidate.width) &&
+        candidate.width > 0 &&
+        Number.isFinite(candidate.height) &&
+        candidate.height > 0)
+        .map((candidate) => ({
+        ...candidate,
+        url: resolveAssetUrl(candidate.url, mediaUrl),
+    }))
+        .sort((left, right) => left.width - right.width);
+    return [...new Map(candidates.map((candidate) => [candidate.width, candidate])).values()];
+}
+/**
+ * Builds native image props from the fixed variants Strapi generated at
+ * upload time. The selected `src` is the smallest available image at least as
+ * wide as requested; `srcSet` advertises the variants at their real widths.
+ */
+export function getStrapiImageProps(asset, options = {}) {
+    if (!Number.isFinite(asset.width) ||
+        asset.width <= 0 ||
+        !Number.isFinite(asset.height) ||
+        asset.height <= 0) {
+        throw new TypeError("Strapi image asset dimensions must be positive finite numbers");
+    }
+    const candidates = imageCandidates(asset, options.mediaUrl);
+    if (candidates.length === 0) {
+        throw new TypeError("Strapi image asset has no usable image variants");
+    }
+    const requestedWidth = options.width ?? asset.width;
+    if (!Number.isFinite(requestedWidth) || requestedWidth <= 0) {
+        throw new TypeError("Strapi image width must be a positive finite number");
+    }
+    const selected = candidates.find((candidate) => candidate.width >= requestedWidth) ?? candidates.at(-1);
+    const renderedWidth = Math.round(Math.min(requestedWidth, selected.width));
+    const renderedHeight = Math.round((selected.height / selected.width) * renderedWidth);
+    return {
+        src: selected.url,
+        srcSet: candidates.map((candidate) => `${candidate.url} ${candidate.width}w`).join(", "),
+        alt: options.alt ?? asset.alternativeText ?? "",
+        width: renderedWidth,
+        height: renderedHeight,
+        ...(options.sizes ? { sizes: options.sizes } : {}),
+        loading: options.loading ?? "lazy",
+        decoding: "async",
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { type StrapiIntegrationInput } from "./config.js";
+export declare function strapi(input?: StrapiIntegrationInput): import("@farm.js/core").DefinedIntegration<{
+    category: "cms";
+    type: string;
+    instance: import("@strapi/client").StrapiClient;
+    config: import("@farm.js/core").FarmIntegrationConfigDefinition<import("./config.js").ResolvedStrapiConfig, import("@farm.js/core").FarmSchema | undefined>;
+    log: import("@farm.js/core").FarmIntegrationLogger | undefined;
+    routes: import("@farm.js/core").FarmIntegrationRoute<unknown, unknown, import("@farm.js/core").FarmSchema | undefined>[];
+}, import("@farm.js/core").FarmSchema | undefined>;
+export { createStrapiClient } from "./client.js";
+export { DEFAULT_STRAPI_WEBHOOK_PATH, DEFAULT_STRAPI_WEBHOOK_SECRET_HEADER, resolveStrapiConfig, } from "./config.js";
+export type { ResolvedStrapiConfig, StrapiIntegrationInput, StrapiWebhookChange, StrapiWebhookOptions, } from "./config.js";
+export { getStrapiImageProps } from "./image.js";
+export type { StrapiImageOptions, StrapiImageProps, StrapiMediaAsset, StrapiMediaFormat, } from "./image.js";
+export { createStrapiCollection } from "./query.js";
+export type { StrapiDocument, StrapiQueryParams, TypedStrapiCollection } from "./query.js";
+export { applyStrapiWebhookChange, createStrapiWebhookRoute } from "./webhook.js";
+export type { StrapiWebhookInvalidation, StrapiWebhookRouteOptions } from "./webhook.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":"AAEA,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,aAAa,CAAC;AAGrB,wBAAgB,MAAM,CAAC,KAAK,GAAE,sBAA2B;;;;;;;mDAuBxD;AAED,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EACL,2BAA2B,EAC3B,oCAAoC,EACpC,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAC3F,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAClF,YAAY,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,27 @@
+import { defineIntegration } from "@farm.js/core";
+import { createStrapiClient } from "./client.js";
+import { resolveStrapiConfig, strapiIntegrationConfig, } from "./config.js";
+import { createStrapiWebhookRoute } from "./webhook.js";
+export function strapi(input = {}) {
+    const config = resolveStrapiConfig(input);
+    if (!input.instance && !config.apiUrl) {
+        throw new Error("Strapi integration requires a Content API URL. Set STRAPI_API_URL, pass apiUrl to " +
+            "strapi(), or supply an existing @strapi/client instance.");
+    }
+    const routes = input.webhook && config.webhookSecret
+        ? [createStrapiWebhookRoute({ ...input.webhook, secret: config.webhookSecret })]
+        : [];
+    return defineIntegration({
+        category: "cms",
+        type: "strapi",
+        instance: createStrapiClient(config, input.instance),
+        config: strapiIntegrationConfig(config, input),
+        log: input.log,
+        routes,
+    });
+}
+export { createStrapiClient } from "./client.js";
+export { DEFAULT_STRAPI_WEBHOOK_PATH, DEFAULT_STRAPI_WEBHOOK_SECRET_HEADER, resolveStrapiConfig, } from "./config.js";
+export { getStrapiImageProps } from "./image.js";
+export { createStrapiCollection } from "./query.js";
+export { applyStrapiWebhookChange, createStrapiWebhookRoute } from "./webhook.js";

package/dist/query.d.ts

@@ -0,0 +1,14 @@
+import type { API, StrapiClient } from "@strapi/client";
+export type StrapiQueryParams = API.BaseQueryParams;
+export type StrapiDocument = API.Document;
+export interface TypedStrapiCollection<TDocument extends StrapiDocument> {
+    find(query?: StrapiQueryParams): Promise<TDocument[]>;
+    findOne(documentId: string, query?: StrapiQueryParams): Promise<TDocument>;
+}
+/**
+ * Adds an application-owned document type to the official Strapi manager and
+ * unwraps the REST `data` envelope. Use the returned methods inside
+ * `createServerQuery` so provider credentials remain on the server.
+ */
+export declare function createStrapiCollection<TDocument extends StrapiDocument = StrapiDocument>(client: StrapiClient, resource: string): TypedStrapiCollection<TDocument>;
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAExD,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,eAAe,CAAC;AACpD,MAAM,MAAM,cAAc,GAAG,GAAG,CAAC,QAAQ,CAAC;AAE1C,MAAM,WAAW,qBAAqB,CAAC,SAAS,SAAS,cAAc;IACrE,IAAI,CAAC,KAAK,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IACtD,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CAC5E;AA4BD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,SAAS,cAAc,GAAG,cAAc,EACtF,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,MAAM,GACf,qBAAqB,CAAC,SAAS,CAAC,CAsBlC"}

package/dist/query.js

@@ -0,0 +1,44 @@
+function assertResourceName(resource) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(resource)) {
+        throw new TypeError(`Strapi resource ${JSON.stringify(resource)} must be a collection API id, not a path`);
+    }
+}
+function assertDocumentId(documentId) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(documentId)) {
+        throw new TypeError(`Strapi document id ${JSON.stringify(documentId)} must be an id, not a path`);
+    }
+}
+function assertDocument(value, operation) {
+    if (!value ||
+        typeof value !== "object" ||
+        typeof value.documentId !== "string") {
+        throw new TypeError(`${operation} received a response without a Strapi document`);
+    }
+}
+/**
+ * Adds an application-owned document type to the official Strapi manager and
+ * unwraps the REST `data` envelope. Use the returned methods inside
+ * `createServerQuery` so provider credentials remain on the server.
+ */
+export function createStrapiCollection(client, resource) {
+    assertResourceName(resource);
+    const manager = client.collection(resource);
+    return {
+        async find(query) {
+            const response = await manager.find(query);
+            if (!response || !Array.isArray(response.data)) {
+                throw new TypeError(`Strapi collection ${JSON.stringify(resource)} returned no data array`);
+            }
+            for (const document of response.data) {
+                assertDocument(document, `Strapi collection ${JSON.stringify(resource)}`);
+            }
+            return response.data;
+        },
+        async findOne(documentId, query) {
+            assertDocumentId(documentId);
+            const response = await manager.findOne(documentId, query);
+            assertDocument(response?.data, `Strapi collection ${JSON.stringify(resource)}`);
+            return response.data;
+        },
+    };
+}

package/dist/webhook.d.ts

@@ -0,0 +1,12 @@
+import { type FarmIntegrationRoute, type RouteDataCacheKey } from "@farm.js/core";
+import { type StrapiWebhookChange, type StrapiWebhookOptions } from "./config.js";
+export interface StrapiWebhookInvalidation {
+    invalidate(key: RouteDataCacheKey): void | Promise<void>;
+    revalidatePath(path: string): void | Promise<void>;
+}
+export interface StrapiWebhookRouteOptions extends Omit<StrapiWebhookOptions, "secret"> {
+    secret: string;
+}
+export declare function applyStrapiWebhookChange(change: StrapiWebhookChange | void, invalidation?: StrapiWebhookInvalidation): Promise<number>;
+export declare function createStrapiWebhookRoute(options: StrapiWebhookRouteOptions, invalidation?: StrapiWebhookInvalidation): FarmIntegrationRoute;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../src/webhook.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EAC1B,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,yBAAyB;IACxC,UAAU,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAID,MAAM,WAAW,yBAA0B,SAAQ,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC;IACrF,MAAM,EAAE,MAAM,CAAC;CAChB;AAsBD,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,mBAAmB,GAAG,IAAI,EAClC,YAAY,GAAE,yBAA4C,GACzD,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,yBAAyB,EAClC,YAAY,GAAE,yBAA4C,GACzD,oBAAoB,CAyCtB"}

package/dist/webhook.js

@@ -0,0 +1,76 @@
+import { integrationRoute, invalidate, revalidatePath, } from "@farm.js/core";
+import { DEFAULT_STRAPI_WEBHOOK_PATH, DEFAULT_STRAPI_WEBHOOK_SECRET_HEADER, } from "./config.js";
+const farmInvalidation = { invalidate, revalidatePath };
+function json(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json" },
+    });
+}
+async function secretsEqual(expected, received) {
+    const encoded = new TextEncoder();
+    const [expectedDigest, receivedDigest] = await Promise.all([
+        crypto.subtle.digest("SHA-256", encoded.encode(expected)),
+        crypto.subtle.digest("SHA-256", encoded.encode(received)),
+    ]);
+    const left = new Uint8Array(expectedDigest);
+    const right = new Uint8Array(receivedDigest);
+    let difference = 0;
+    for (let index = 0; index < left.length; index += 1)
+        difference |= left[index] ^ right[index];
+    return difference === 0;
+}
+export async function applyStrapiWebhookChange(change, invalidation = farmInvalidation) {
+    if (!change)
+        return 0;
+    const keys = [...new Map((change.keys ?? []).map((key) => [JSON.stringify(key), key])).values()];
+    const paths = [...new Set(change.paths ?? [])];
+    await Promise.all([
+        ...keys.map((key) => invalidation.invalidate(key)),
+        ...paths.map((path) => invalidation.revalidatePath(path)),
+    ]);
+    return keys.length + paths.length;
+}
+export function createStrapiWebhookRoute(options, invalidation = farmInvalidation) {
+    if (!options.secret)
+        throw new TypeError("Strapi webhook requires a non-empty secret");
+    const secretHeader = options.secretHeader ?? DEFAULT_STRAPI_WEBHOOK_SECRET_HEADER;
+    try {
+        new Headers({ [secretHeader]: "validate" });
+    }
+    catch {
+        throw new TypeError("Strapi webhook secretHeader must be a valid HTTP header name");
+    }
+    return integrationRoute.post(options.path ?? DEFAULT_STRAPI_WEBHOOK_PATH, {
+        // Authentication happens before the integration runtime performs its
+        // ordinary JSON validation. The handler parses the authenticated body.
+        bodyFormat: "none",
+        async handler(request) {
+            const presentedSecret = request.headers.get(secretHeader);
+            if (!presentedSecret || !(await secretsEqual(options.secret, presentedSecret))) {
+                return json(401, { error: "Invalid webhook secret" });
+            }
+            let payload;
+            try {
+                const value = await request.json();
+                if (!value || typeof value !== "object" || Array.isArray(value)) {
+                    return json(400, { error: "Body must be a JSON object" });
+                }
+                payload = value;
+            }
+            catch {
+                return json(400, { error: "Body is not JSON" });
+            }
+            try {
+                const change = await options.onChange(payload);
+                const targets = await applyStrapiWebhookChange(change, invalidation);
+                return json(200, { targets });
+            }
+            catch {
+                // A mapping or cache failure should be visible to the webhook sender,
+                // without reflecting application errors or credentials in the body.
+                return json(500, { error: "Failed to apply change" });
+            }
+        },
+    });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@farm.js/strapi",
+  "version": "0.1.1-beta.4",
+  "description": "Strapi CMS integration for Farm.js",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farming-labs/farm.js",
+    "directory": "packages/farm-strapi"
+  },
+  "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"
+  },
+  "dependencies": {
+    "@farm.js/core": "0.1.1-beta.4",
+    "@farm.js/integration-utils": "0.1.1-beta.4"
+  },
+  "devDependencies": {
+    "@strapi/client": "^1.6.2",
+    "typescript": "^5.3.3",
+    "vitest": "^3.2.7"
+  },
+  "peerDependencies": {
+    "@strapi/client": "^1.6.2"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit -p tsconfig.test.json",
+    "test": "vitest run"
+  }
+}