@flexacms/next 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Mercedes
+
+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

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# @flexacms/next
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Flexa](https://github.com/flexacms) for the Next.js App Router: server-side fetching through Next's data cache, tagged per entity and entry for precise revalidation.
+
+```bash
+npm install @flexacms/next
+```
+
+```env
+FLEXA_URL=https://cms.example.com
+FLEXA_API_KEY=flx_...
+```
+
+```ts
+// lib/flexa.ts
+import { createFlexaClient } from '@flexacms/next';
+import type { FlexaSchema } from './flexa'; // optional: npx @flexacms/cli generate
+
+export const flexa = createFlexaClient<FlexaSchema>({ revalidate: 300 });
+```
+
+```tsx
+// app/blog/[slug]/page.tsx (Server Component)
+import { notFound } from 'next/navigation';
+import { flexa } from '@/lib/flexa';
+
+export default async function Post({
+    params,
+}: {
+    params: Promise<{ slug: string }>;
+}) {
+    const post = await flexa.entity('posts').find((await params).slug);
+
+    if (!post) notFound();
+
+    return <h1>{post.title}</h1>;
+}
+```
+
+Reads are cached and tagged `flexa`, `flexa:<entity>` and `flexa:<entity>:<id or slug>`; writes are never cached. `revalidate` sets how long cached responses live (default 60 seconds, `false` to keep them until revalidated).
+
+## Revalidation
+
+```ts
+import { revalidateFlexa } from '@flexacms/next';
+
+revalidateFlexa(); // everything
+revalidateFlexa('posts'); // one entity
+revalidateFlexa('posts', 'hello'); // one entry
+```
+
+Or expose a route for webhooks and deploy hooks:
+
+```ts
+// app/api/flexa/revalidate/route.ts
+import { createRevalidateHandler } from '@flexacms/next';
+
+export const POST = createRevalidateHandler({
+    secret: process.env.FLEXA_REVALIDATE_SECRET,
+});
+```
+
+```bash
+curl -X POST https://site.example.com/api/flexa/revalidate \
+  -H "Authorization: Bearer $FLEXA_REVALIDATE_SECRET" \
+  -d '{"entity":"posts","entry":"hello"}'
+```
+
+> Import `createFlexaClient` only from server code: the API key must not reach the browser. For client components, use [`@flexacms/react`](../react) with a Read-only key.

package/dist/index.cjs

@@ -0,0 +1,120 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FLEXA_TAG: () => FLEXA_TAG,
+  createFlexaClient: () => createFlexaClient,
+  createRevalidateHandler: () => createRevalidateHandler,
+  flexaTags: () => flexaTags,
+  revalidateFlexa: () => revalidateFlexa
+});
+module.exports = __toCommonJS(index_exports);
+var import_client = require("@flexacms/client");
+var import_cache = require("next/cache");
+__reExport(index_exports, require("@flexacms/client"), module.exports);
+var FLEXA_TAG = "flexa";
+function requestUrl(input) {
+  if (typeof input === "string") {
+    return input;
+  }
+  return input instanceof URL ? input.href : input.url;
+}
+function flexaTags(path) {
+  const [entity, entry] = path.split("?")[0].split("/").filter(Boolean).map(decodeURIComponent);
+  const tags = [FLEXA_TAG];
+  if (entity) {
+    tags.push(`${FLEXA_TAG}:${entity}`);
+  }
+  if (entity && entry && entry !== "schema") {
+    tags.push(`${FLEXA_TAG}:${entity}:${entry}`);
+  }
+  return tags;
+}
+function createFlexaClient(options = {}) {
+  const { revalidate = 60, ...clientOptions } = options;
+  const url = clientOptions.url ?? process.env.FLEXA_URL;
+  const apiKey = clientOptions.apiKey ?? process.env.FLEXA_API_KEY;
+  if (!url || !apiKey) {
+    throw new Error(
+      'Flexa: set the FLEXA_URL and FLEXA_API_KEY environment variables, or pass "url" and "apiKey".'
+    );
+  }
+  const baseFetch = clientOptions.fetch ?? globalThis.fetch;
+  let client;
+  const cachedFetch = ((input, init = {}) => {
+    if ((init.method ?? "GET").toUpperCase() !== "GET") {
+      return baseFetch(input, { ...init, cache: "no-store" });
+    }
+    const path = new URL(requestUrl(input)).pathname.slice(
+      new URL(client.baseUrl).pathname.length
+    );
+    return baseFetch(input, {
+      ...init,
+      next: {
+        revalidate,
+        ...init.next,
+        tags: [...flexaTags(path), ...init.next?.tags ?? []]
+      }
+    });
+  });
+  client = (0, import_client.createClient)({
+    ...clientOptions,
+    url,
+    apiKey,
+    fetch: cachedFetch
+  });
+  return client;
+}
+function revalidateFlexa(entity, idOrSlug) {
+  const tag = entity === void 0 ? FLEXA_TAG : idOrSlug === void 0 ? `${FLEXA_TAG}:${entity}` : `${FLEXA_TAG}:${entity}:${idOrSlug}`;
+  (0, import_cache.revalidateTag)(tag, "max");
+}
+function createRevalidateHandler(options) {
+  return async function POST(request) {
+    if (!options.secret || request.headers.get("authorization") !== `Bearer ${options.secret}`) {
+      return Response.json({ message: "Unauthorized." }, { status: 401 });
+    }
+    let body = {};
+    try {
+      body = await request.json();
+    } catch {
+    }
+    const entity = typeof body.entity === "string" && body.entity !== "" ? body.entity : void 0;
+    const entry = typeof body.entry === "string" || typeof body.entry === "number" ? body.entry : void 0;
+    revalidateFlexa(entity, entity === void 0 ? void 0 : entry);
+    return Response.json({
+      revalidated: true,
+      entity: entity ?? null,
+      entry: entity === void 0 ? null : entry ?? null
+    });
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FLEXA_TAG,
+  createFlexaClient,
+  createRevalidateHandler,
+  flexaTags,
+  revalidateFlexa,
+  ...require("@flexacms/client")
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { createClient } from '@flexacms/client';\nimport type {\n    ContentSchema,\n    FlexaClient,\n    FlexaClientOptions,\n} from '@flexacms/client';\nimport { revalidateTag } from 'next/cache';\n\nexport * from '@flexacms/client';\n\n/** Tag on every cached Flexa response. */\nexport const FLEXA_TAG = 'flexa';\n\nexport interface FlexaNextOptions extends Partial<FlexaClientOptions> {\n    /**\n     * Seconds before a cached response is refreshed in the background, or\n     * `false` to keep it until it is revalidated by tag. Defaults to 60.\n     */\n    revalidate?: number | false;\n}\n\ntype NextFetchInit = RequestInit & {\n    next?: { revalidate?: number | false; tags?: string[] };\n};\n\n/** The URL of any `fetch` input (string, URL or Request). */\nfunction requestUrl(input: string | URL | Request): string {\n    if (typeof input === 'string') {\n        return input;\n    }\n\n    return input instanceof URL ? input.href : input.url;\n}\n\n/**\n * Cache tags for an API path: `flexa`, `flexa:<entity>` and, for one entry,\n * `flexa:<entity>:<id or slug>`.\n */\nexport function flexaTags(path: string): string[] {\n    const [entity, entry] = path\n        .split('?')[0]!\n        .split('/')\n        .filter(Boolean)\n        .map(decodeURIComponent);\n    const tags = [FLEXA_TAG];\n\n    if (entity) {\n        tags.push(`${FLEXA_TAG}:${entity}`);\n    }\n\n    if (entity && entry && entry !== 'schema') {\n        tags.push(`${FLEXA_TAG}:${entity}:${entry}`);\n    }\n\n    return tags;\n}\n\n/**\n * A Flexa client for Server Components, Route Handlers and Server Actions.\n *\n * Reads go through Next's data cache, tagged per entity and entry so they can\n * be refreshed with `revalidateFlexa()`; writes are never cached. The URL and\n * API key default to the `FLEXA_URL` and `FLEXA_API_KEY` environment variables.\n * Only use it on the server: the API key must not reach the browser.\n */\nexport function createFlexaClient<TSchema extends object = ContentSchema>(\n    options: FlexaNextOptions = {},\n): FlexaClient<TSchema> {\n    const { revalidate = 60, ...clientOptions } = options;\n    const url = clientOptions.url ?? process.env.FLEXA_URL;\n    const apiKey = clientOptions.apiKey ?? process.env.FLEXA_API_KEY;\n\n    if (!url || !apiKey) {\n        throw new Error(\n            'Flexa: set the FLEXA_URL and FLEXA_API_KEY environment variables, or pass \"url\" and \"apiKey\".',\n        );\n    }\n\n    const baseFetch = clientOptions.fetch ?? globalThis.fetch;\n    let client: FlexaClient<TSchema>;\n\n    const cachedFetch = ((\n        input: string | URL | Request,\n        init: NextFetchInit = {},\n    ) => {\n        if ((init.method ?? 'GET').toUpperCase() !== 'GET') {\n            return baseFetch(input, { ...init, cache: 'no-store' });\n        }\n\n        const path = new URL(requestUrl(input)).pathname.slice(\n            new URL(client.baseUrl).pathname.length,\n        );\n\n        return baseFetch(input, {\n            ...init,\n            next: {\n                revalidate,\n                ...init.next,\n                tags: [...flexaTags(path), ...(init.next?.tags ?? [])],\n            },\n        } as RequestInit);\n    }) as typeof fetch;\n\n    client = createClient<TSchema>({\n        ...clientOptions,\n        url,\n        apiKey,\n        fetch: cachedFetch,\n    });\n\n    return client;\n}\n\n/**\n * Refresh cached Flexa content: everything, one entity, or one entry. Call it\n * from a Server Action or Route Handler after content changes.\n */\nexport function revalidateFlexa(\n    entity?: string,\n    idOrSlug?: number | string,\n): void {\n    const tag =\n        entity === undefined\n            ? FLEXA_TAG\n            : idOrSlug === undefined\n              ? `${FLEXA_TAG}:${entity}`\n              : `${FLEXA_TAG}:${entity}:${idOrSlug}`;\n\n    revalidateTag(tag, 'max');\n}\n\n/**\n * A `POST` Route Handler that revalidates Flexa content, for webhooks or\n * deploy hooks. Send `{ \"entity\": \"posts\", \"entry\": \"hello-world\" }` (both\n * optional) with the header `Authorization: Bearer <secret>`.\n *\n *     // app/api/flexa/revalidate/route.ts\n *     export const POST = createRevalidateHandler({ secret: process.env.FLEXA_REVALIDATE_SECRET });\n */\nexport function createRevalidateHandler(options: {\n    secret: string | undefined;\n}) {\n    return async function POST(request: Request): Promise<Response> {\n        if (\n            !options.secret ||\n            request.headers.get('authorization') !== `Bearer ${options.secret}`\n        ) {\n            return Response.json({ message: 'Unauthorized.' }, { status: 401 });\n        }\n\n        let body: { entity?: unknown; entry?: unknown } = {};\n\n        try {\n            body = (await request.json()) as typeof body;\n        } catch {\n            // An empty body revalidates everything.\n        }\n\n        const entity =\n            typeof body.entity === 'string' && body.entity !== ''\n                ? body.entity\n                : undefined;\n        const entry =\n            typeof body.entry === 'string' || typeof body.entry === 'number'\n                ? body.entry\n                : undefined;\n\n        revalidateFlexa(entity, entity === undefined ? undefined : entry);\n\n        return Response.json({\n            revalidated: true,\n            entity: entity ?? null,\n            entry: entity === undefined ? null : (entry ?? null),\n        });\n    };\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,44 @@
+import { FlexaClientOptions, ContentSchema, FlexaClient } from '@flexacms/client';
+export * from '@flexacms/client';
+
+/** Tag on every cached Flexa response. */
+declare const FLEXA_TAG = "flexa";
+interface FlexaNextOptions extends Partial<FlexaClientOptions> {
+    /**
+     * Seconds before a cached response is refreshed in the background, or
+     * `false` to keep it until it is revalidated by tag. Defaults to 60.
+     */
+    revalidate?: number | false;
+}
+/**
+ * Cache tags for an API path: `flexa`, `flexa:<entity>` and, for one entry,
+ * `flexa:<entity>:<id or slug>`.
+ */
+declare function flexaTags(path: string): string[];
+/**
+ * A Flexa client for Server Components, Route Handlers and Server Actions.
+ *
+ * Reads go through Next's data cache, tagged per entity and entry so they can
+ * be refreshed with `revalidateFlexa()`; writes are never cached. The URL and
+ * API key default to the `FLEXA_URL` and `FLEXA_API_KEY` environment variables.
+ * Only use it on the server: the API key must not reach the browser.
+ */
+declare function createFlexaClient<TSchema extends object = ContentSchema>(options?: FlexaNextOptions): FlexaClient<TSchema>;
+/**
+ * Refresh cached Flexa content: everything, one entity, or one entry. Call it
+ * from a Server Action or Route Handler after content changes.
+ */
+declare function revalidateFlexa(entity?: string, idOrSlug?: number | string): void;
+/**
+ * A `POST` Route Handler that revalidates Flexa content, for webhooks or
+ * deploy hooks. Send `{ "entity": "posts", "entry": "hello-world" }` (both
+ * optional) with the header `Authorization: Bearer <secret>`.
+ *
+ *     // app/api/flexa/revalidate/route.ts
+ *     export const POST = createRevalidateHandler({ secret: process.env.FLEXA_REVALIDATE_SECRET });
+ */
+declare function createRevalidateHandler(options: {
+    secret: string | undefined;
+}): (request: Request) => Promise<Response>;
+
+export { FLEXA_TAG, type FlexaNextOptions, createFlexaClient, createRevalidateHandler, flexaTags, revalidateFlexa };

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { FlexaClientOptions, ContentSchema, FlexaClient } from '@flexacms/client';
+export * from '@flexacms/client';
+
+/** Tag on every cached Flexa response. */
+declare const FLEXA_TAG = "flexa";
+interface FlexaNextOptions extends Partial<FlexaClientOptions> {
+    /**
+     * Seconds before a cached response is refreshed in the background, or
+     * `false` to keep it until it is revalidated by tag. Defaults to 60.
+     */
+    revalidate?: number | false;
+}
+/**
+ * Cache tags for an API path: `flexa`, `flexa:<entity>` and, for one entry,
+ * `flexa:<entity>:<id or slug>`.
+ */
+declare function flexaTags(path: string): string[];
+/**
+ * A Flexa client for Server Components, Route Handlers and Server Actions.
+ *
+ * Reads go through Next's data cache, tagged per entity and entry so they can
+ * be refreshed with `revalidateFlexa()`; writes are never cached. The URL and
+ * API key default to the `FLEXA_URL` and `FLEXA_API_KEY` environment variables.
+ * Only use it on the server: the API key must not reach the browser.
+ */
+declare function createFlexaClient<TSchema extends object = ContentSchema>(options?: FlexaNextOptions): FlexaClient<TSchema>;
+/**
+ * Refresh cached Flexa content: everything, one entity, or one entry. Call it
+ * from a Server Action or Route Handler after content changes.
+ */
+declare function revalidateFlexa(entity?: string, idOrSlug?: number | string): void;
+/**
+ * A `POST` Route Handler that revalidates Flexa content, for webhooks or
+ * deploy hooks. Send `{ "entity": "posts", "entry": "hello-world" }` (both
+ * optional) with the header `Authorization: Bearer <secret>`.
+ *
+ *     // app/api/flexa/revalidate/route.ts
+ *     export const POST = createRevalidateHandler({ secret: process.env.FLEXA_REVALIDATE_SECRET });
+ */
+declare function createRevalidateHandler(options: {
+    secret: string | undefined;
+}): (request: Request) => Promise<Response>;
+
+export { FLEXA_TAG, type FlexaNextOptions, createFlexaClient, createRevalidateHandler, flexaTags, revalidateFlexa };

package/dist/index.js

@@ -0,0 +1,89 @@
+// src/index.ts
+import { createClient } from "@flexacms/client";
+import { revalidateTag } from "next/cache";
+export * from "@flexacms/client";
+var FLEXA_TAG = "flexa";
+function requestUrl(input) {
+  if (typeof input === "string") {
+    return input;
+  }
+  return input instanceof URL ? input.href : input.url;
+}
+function flexaTags(path) {
+  const [entity, entry] = path.split("?")[0].split("/").filter(Boolean).map(decodeURIComponent);
+  const tags = [FLEXA_TAG];
+  if (entity) {
+    tags.push(`${FLEXA_TAG}:${entity}`);
+  }
+  if (entity && entry && entry !== "schema") {
+    tags.push(`${FLEXA_TAG}:${entity}:${entry}`);
+  }
+  return tags;
+}
+function createFlexaClient(options = {}) {
+  const { revalidate = 60, ...clientOptions } = options;
+  const url = clientOptions.url ?? process.env.FLEXA_URL;
+  const apiKey = clientOptions.apiKey ?? process.env.FLEXA_API_KEY;
+  if (!url || !apiKey) {
+    throw new Error(
+      'Flexa: set the FLEXA_URL and FLEXA_API_KEY environment variables, or pass "url" and "apiKey".'
+    );
+  }
+  const baseFetch = clientOptions.fetch ?? globalThis.fetch;
+  let client;
+  const cachedFetch = ((input, init = {}) => {
+    if ((init.method ?? "GET").toUpperCase() !== "GET") {
+      return baseFetch(input, { ...init, cache: "no-store" });
+    }
+    const path = new URL(requestUrl(input)).pathname.slice(
+      new URL(client.baseUrl).pathname.length
+    );
+    return baseFetch(input, {
+      ...init,
+      next: {
+        revalidate,
+        ...init.next,
+        tags: [...flexaTags(path), ...init.next?.tags ?? []]
+      }
+    });
+  });
+  client = createClient({
+    ...clientOptions,
+    url,
+    apiKey,
+    fetch: cachedFetch
+  });
+  return client;
+}
+function revalidateFlexa(entity, idOrSlug) {
+  const tag = entity === void 0 ? FLEXA_TAG : idOrSlug === void 0 ? `${FLEXA_TAG}:${entity}` : `${FLEXA_TAG}:${entity}:${idOrSlug}`;
+  revalidateTag(tag, "max");
+}
+function createRevalidateHandler(options) {
+  return async function POST(request) {
+    if (!options.secret || request.headers.get("authorization") !== `Bearer ${options.secret}`) {
+      return Response.json({ message: "Unauthorized." }, { status: 401 });
+    }
+    let body = {};
+    try {
+      body = await request.json();
+    } catch {
+    }
+    const entity = typeof body.entity === "string" && body.entity !== "" ? body.entity : void 0;
+    const entry = typeof body.entry === "string" || typeof body.entry === "number" ? body.entry : void 0;
+    revalidateFlexa(entity, entity === void 0 ? void 0 : entry);
+    return Response.json({
+      revalidated: true,
+      entity: entity ?? null,
+      entry: entity === void 0 ? null : entry ?? null
+    });
+  };
+}
+export {
+  FLEXA_TAG,
+  createFlexaClient,
+  createRevalidateHandler,
+  flexaTags,
+  revalidateFlexa
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { createClient } from '@flexacms/client';\nimport type {\n    ContentSchema,\n    FlexaClient,\n    FlexaClientOptions,\n} from '@flexacms/client';\nimport { revalidateTag } from 'next/cache';\n\nexport * from '@flexacms/client';\n\n/** Tag on every cached Flexa response. */\nexport const FLEXA_TAG = 'flexa';\n\nexport interface FlexaNextOptions extends Partial<FlexaClientOptions> {\n    /**\n     * Seconds before a cached response is refreshed in the background, or\n     * `false` to keep it until it is revalidated by tag. Defaults to 60.\n     */\n    revalidate?: number | false;\n}\n\ntype NextFetchInit = RequestInit & {\n    next?: { revalidate?: number | false; tags?: string[] };\n};\n\n/** The URL of any `fetch` input (string, URL or Request). */\nfunction requestUrl(input: string | URL | Request): string {\n    if (typeof input === 'string') {\n        return input;\n    }\n\n    return input instanceof URL ? input.href : input.url;\n}\n\n/**\n * Cache tags for an API path: `flexa`, `flexa:<entity>` and, for one entry,\n * `flexa:<entity>:<id or slug>`.\n */\nexport function flexaTags(path: string): string[] {\n    const [entity, entry] = path\n        .split('?')[0]!\n        .split('/')\n        .filter(Boolean)\n        .map(decodeURIComponent);\n    const tags = [FLEXA_TAG];\n\n    if (entity) {\n        tags.push(`${FLEXA_TAG}:${entity}`);\n    }\n\n    if (entity && entry && entry !== 'schema') {\n        tags.push(`${FLEXA_TAG}:${entity}:${entry}`);\n    }\n\n    return tags;\n}\n\n/**\n * A Flexa client for Server Components, Route Handlers and Server Actions.\n *\n * Reads go through Next's data cache, tagged per entity and entry so they can\n * be refreshed with `revalidateFlexa()`; writes are never cached. The URL and\n * API key default to the `FLEXA_URL` and `FLEXA_API_KEY` environment variables.\n * Only use it on the server: the API key must not reach the browser.\n */\nexport function createFlexaClient<TSchema extends object = ContentSchema>(\n    options: FlexaNextOptions = {},\n): FlexaClient<TSchema> {\n    const { revalidate = 60, ...clientOptions } = options;\n    const url = clientOptions.url ?? process.env.FLEXA_URL;\n    const apiKey = clientOptions.apiKey ?? process.env.FLEXA_API_KEY;\n\n    if (!url || !apiKey) {\n        throw new Error(\n            'Flexa: set the FLEXA_URL and FLEXA_API_KEY environment variables, or pass \"url\" and \"apiKey\".',\n        );\n    }\n\n    const baseFetch = clientOptions.fetch ?? globalThis.fetch;\n    let client: FlexaClient<TSchema>;\n\n    const cachedFetch = ((\n        input: string | URL | Request,\n        init: NextFetchInit = {},\n    ) => {\n        if ((init.method ?? 'GET').toUpperCase() !== 'GET') {\n            return baseFetch(input, { ...init, cache: 'no-store' });\n        }\n\n        const path = new URL(requestUrl(input)).pathname.slice(\n            new URL(client.baseUrl).pathname.length,\n        );\n\n        return baseFetch(input, {\n            ...init,\n            next: {\n                revalidate,\n                ...init.next,\n                tags: [...flexaTags(path), ...(init.next?.tags ?? [])],\n            },\n        } as RequestInit);\n    }) as typeof fetch;\n\n    client = createClient<TSchema>({\n        ...clientOptions,\n        url,\n        apiKey,\n        fetch: cachedFetch,\n    });\n\n    return client;\n}\n\n/**\n * Refresh cached Flexa content: everything, one entity, or one entry. Call it\n * from a Server Action or Route Handler after content changes.\n */\nexport function revalidateFlexa(\n    entity?: string,\n    idOrSlug?: number | string,\n): void {\n    const tag =\n        entity === undefined\n            ? FLEXA_TAG\n            : idOrSlug === undefined\n              ? `${FLEXA_TAG}:${entity}`\n              : `${FLEXA_TAG}:${entity}:${idOrSlug}`;\n\n    revalidateTag(tag, 'max');\n}\n\n/**\n * A `POST` Route Handler that revalidates Flexa content, for webhooks or\n * deploy hooks. Send `{ \"entity\": \"posts\", \"entry\": \"hello-world\" }` (both\n * optional) with the header `Authorization: Bearer <secret>`.\n *\n *     // app/api/flexa/revalidate/route.ts\n *     export const POST = createRevalidateHandler({ secret: process.env.FLEXA_REVALIDATE_SECRET });\n */\nexport function createRevalidateHandler(options: {\n    secret: string | undefined;\n}) {\n    return async function POST(request: Request): Promise<Response> {\n        if (\n            !options.secret ||\n            request.headers.get('authorization') !== `Bearer ${options.secret}`\n        ) {\n            return Response.json({ message: 'Unauthorized.' }, { status: 401 });\n        }\n\n        let body: { entity?: unknown; entry?: unknown } = {};\n\n        try {\n            body = (await request.json()) as typeof body;\n        } catch {\n            // An empty body revalidates everything.\n        }\n\n        const entity =\n            typeof body.entity === 'string' && body.entity !== ''\n                ? body.entity\n                : undefined;\n        const entry =\n            typeof body.entry === 'string' || typeof body.entry === 'number'\n                ? body.entry\n                : undefined;\n\n        revalidateFlexa(entity, entity === undefined ? undefined : entry);\n\n        return Response.json({\n            revalidated: true,\n            entity: entity ?? null,\n            entry: entity === undefined ? null : (entry ?? null),\n        });\n    };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,62 @@
 {
-  "name": "@flexacms/next",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@flexacms/next",
+    "version": "0.2.0",
+    "description": "Next.js integration for the Flexa headless CMS: cached server-side fetching with tag revalidation.",
+    "keywords": [
+        "cms",
+        "flexa",
+        "headless",
+        "nextjs",
+        "react-server-components"
+    ],
+    "homepage": "https://github.com/flexacms/sdk/tree/main/packages/next#readme",
+    "bugs": {
+        "url": "https://github.com/flexacms/sdk/issues"
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/flexacms/sdk.git",
+        "directory": "packages/next"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "type": "module",
+    "sideEffects": false,
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/index.js"
+            },
+            "require": {
+                "types": "./dist/index.d.cts",
+                "default": "./dist/index.cjs"
+            }
+        }
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "build": "tsup",
+        "typecheck": "tsc -p tsconfig.json"
+    },
+    "dependencies": {
+        "@flexacms/client": "^0.2.0"
+    },
+    "devDependencies": {
+        "next": "^16.4.0",
+        "react": "^19.3.0",
+        "react-dom": "^19.3.0"
+    },
+    "peerDependencies": {
+        "next": ">=15.0.0"
+    }
+}