@botlr/next 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# @botlr/next
+
+## 0.2.0
+
+### Minor Changes
+
+- Page helpers extracted from the satellite apps.
+
+  `@botlr/sdk`: `PageResponse` gains optional `full_slug`, `breadcrumbs` and `alternate_translations` (new `AlternateTranslation` type, also used by `ResolveResponse`). New asset helpers `getAssetUrl`, `createAssetUrl`, `getAssetId`, `getAssetFilename` and `isAssetData` take the media server URL explicitly instead of reading `NEXT_PUBLIC_MEDIA_URL`.
+
+  `@botlr/next`: `resolvePage` and `createPageResolver`, `buildPageMetadata`, `renderCmsPage` with `themeSettingsToCss`, `serveStaticTextFile` and `defaultRobotsContent`, `createLocalePage` and `createLocaleAliasPage`, `rateLimit` and `getClientIp`, plus `scopeFromEnv` and `environmentFromEnv`. Every helper takes its client and component registry as arguments. `html-react-parser` is a new dependency.
+
+### Patch Changes
+
+- Updated dependencies
+  - @botlr/sdk@0.2.0
+  - @botlr/react@0.1.1
+
+## 0.1.0
+
+- First release. `getBotlrForRoute` moves here from the publisher's
+  `lib/botlr-sdk/server.ts`, typed against `@botlr/sdk`, plus
+  `getCachedBotlr`, `createBotlrFromEnv`, `configFromEnv` and
+  `localeFromAcceptLanguage`.
+- Re-exports `@botlr/react` and the `@botlr/sdk` types.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Botlr
+
+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,84 @@
-# Temporary Holding Version
+# @botlr/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.
+Next.js helpers on top of `@botlr/sdk` and `@botlr/react`. Everything from
+both packages is re-exported, so a server file can import from `@botlr/next`
+alone. The package imports `next/headers` and `next/navigation`, so client
+components should import runtime values from `@botlr/sdk` or `@botlr/react`
+instead; type imports from `@botlr/next` are fine anywhere.
+
+## Clients
+
+- `getBotlrForRoute(params)` builds a client for the current request. The
+  locale comes from `Accept-Language` unless given; `baseUrl`, `apiKey` and
+  `appId` fall back to `BOTLR_API_URL`, `BOTLR_API_KEY` and `BOTLR_APP_ID`.
+  All of them are server-side variables: the API URL is never exposed to the
+  browser through a `NEXT_PUBLIC_` name.
+- `getCachedBotlr` is the same, memoised per request with React `cache`.
+- `createBotlrFromEnv(overrides)` needs no request context (scripts,
+  `generateStaticParams`, the page helpers below).
+- `configFromEnv`, `scopeFromEnv({ locale })` (from `BOTLR_ORG_SLUG`,
+  `BOTLR_PROJECT_SLUG`, `BOTLR_APP_INSTANCE_SLUG`, `BOTLR_APP_ID`),
+  `environmentFromEnv()` (`BOTLR_ENVIRONMENT`, `ENVIRONMENT`, `NODE_ENV`) and
+  `localeFromAcceptLanguage` are the building blocks.
+
+## A static locale route in one call
+
+```ts
+// lib/botlr.ts
+import { createBotlrFromEnv } from "@botlr/next";
+export const botlr = createBotlrFromEnv();
+
+// app/(root)/[[...slug]]/page.tsx
+import { createLocalePage } from "@botlr/next";
+import { botlr } from "@/lib/botlr";
+import { publisherSectionRegistry } from "@/components/sections/publisher-section-registry";
+
+// Segment config must stay as literals here so Next can read it statically.
+export const revalidate = false;
+export const dynamicParams = false;
+
+const page = createLocalePage({
+  locale: "da",
+  folder: "",
+  client: botlr,
+  componentRegistry: publisherSectionRegistry,
+  siteUrl: process.env.NEXT_PUBLIC_APP_URL,
+});
+
+export const generateStaticParams = page.generateStaticParams;
+export const generateMetadata = page.generateMetadata;
+export default page.Page;
+```
+
+`createLocalePage` lists slugs with `getPageSlugList`, resolves each request
+once for metadata and page through `createPageResolver`, calls `notFound()`
+for missing and unpublished pages, follows CMS redirects with
+`permanentRedirect` (or `redirect` with `redirect: "temporary"`) prefixed by
+`folder`, and renders with `renderCmsPage`. `createLocaleAliasPage("/sv")`
+makes a folder that only redirects to another one.
+
+## The pieces
+
+- `resolvePage(client, slug, locale, options)` folds `/api/resolve` into
+  `{ kind: "page" | "redirect" | "404" | "error" }` and prepends non-page
+  content (articles by default; see `contentSections`) to the `main` region as
+  an inline section. `createPageResolver(client, options)` binds the client
+  and memoises per request.
+- `buildPageMetadata(pageData, { siteUrl, folder })` turns `seo_meta` into
+  Next `Metadata`: title, description, keywords, Open Graph, Twitter, robots,
+  canonical and hreflang alternates. Without `siteUrl` only an explicit
+  `seo_meta.canonical` is emitted.
+- `renderCmsPage({ pageData, scope, componentRegistry, client })` picks the
+  page template, then the theme's, then a built-in one; merges template and
+  page layouts; applies visibility rules for `environment`; fetches shared
+  sections through `client` or `fetchSharedSection`; and mounts a
+  `SectionRenderer` at every `{{{REGION}}}` marker. `themeSettingsToCss`
+  emits the theme's custom properties.
+- `serveStaticTextFile(client, slug, defaultContent)` serves a CMS page's
+  text sections as `text/plain`, for `robots.txt`, `humans.txt` and
+  `llms.txt` routes. `defaultRobotsContent()` allows everything in production
+  and disallows elsewhere.
+- `rateLimit(key, { limit, window })` and `getClientIp(request)` for form and
+  forum route handlers. In-memory, per server instance.
+
+`next` and `react` are peer dependencies; `html-react-parser` is a dependency.