@flyo/nitro-next 1.12.1 → 2.0.0

package/dist/server.d.ts

@@ -1,55 +1,21 @@
 import * as react from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { Metadata, MetadataRoute } from 'next';
-import { Entity, Block, ConfigResponse, Page, Configuration, EntitiesApi, PagesApi, SearchApi, SitemapApi } from '@flyo/nitro-typescript';
+import { MetadataRoute, Metadata } from 'next';
+import { Entity, ConfigResponse, PagesApi, EntitiesApi, SitemapApi, SearchApi, Page, Block } from '@flyo/nitro-typescript';
 
 /**
- * Interface for Nitro configuration state
+ * Read-only configuration state
  */
 interface NitroState {
-    configuration: Configuration | null;
-    accessToken: string | null;
-    lang: string | null;
-    baseUrl: string | null;
-    components: Record<string, any>;
-    showMissingComponentAlert: boolean;
-    liveEdit: boolean;
-    serverCacheTtl: number;
-    clientCacheTtl: number;
+    readonly accessToken: string;
+    readonly lang: string | null;
+    readonly baseUrl: string | null;
+    readonly components: Record<string, any>;
+    readonly showMissingComponentAlert: boolean;
+    readonly liveEdit: boolean;
+    readonly serverCacheTtl: number;
+    readonly clientCacheTtl: number;
 }
-/**
- * Global Nitro state - shared across server and middleware
- */
-declare const globalNitroState: NitroState;
-/**
- * Access the Nitro configuration state
- * Can be used anywhere: server components, middlewares, API routes, etc.
- * Must be called after initNitro() has been initialized.
- *
- * @throws {Error} If Nitro has not been initialized with initNitro()
- *
- * @example
- * ```ts
- * const state = getNitro();
- * const { configuration, lang, components } = state;
- * ```
- */
-declare function getNitro(): NitroState;
-declare const initNitro: ({ accessToken, lang, baseUrl, components, showMissingComponentAlert, liveEdit, serverCacheTtl, clientCacheTtl, }: {
-    accessToken: string;
-    lang?: string;
-    baseUrl?: string;
-    components?: object;
-    showMissingComponentAlert?: boolean;
-    liveEdit?: boolean;
-    serverCacheTtl?: number;
-    clientCacheTtl?: number;
-}) => (() => NitroState);
-declare const getNitroConfig: () => Promise<ConfigResponse>;
-declare function getNitroPages(): PagesApi;
-declare function getNitroEntities(): EntitiesApi;
-declare function getNitroSitemap(): SitemapApi;
-declare function getNitroSearch(): SearchApi;
 /**
  * Route params type for Next.js catch-all routes
  */
@@ -60,229 +26,210 @@ type RouteParams = {
 };
 /**
  * Generic route params type for entity routes
- * Allows any param structure from Next.js app router
  */
 type EntityRouteParams<T = any> = {
     params: Promise<T>;
 };
-/**
- * Resolve a Nitro page from route params
- * Uses React cache to avoid duplicate fetching.
- * Use this when you need access to the page data for custom rendering logic.
- *
- * @example
- * ```tsx
- * // app/[[...slug]]/page.tsx
- * import { nitroPageResolveRoute, NitroPage } from '@flyo/nitro-next/server';
- *
- * export default async function Page(props: { params: Promise<{ slug?: string[] }> }) {
- *   const { page, cfg } = await nitroPageResolveRoute(props);
- *   return <NitroPage page={page} />;
- * }
- * ```
- */
-declare const nitroPageResolveRoute: ({ params }: RouteParams) => Promise<{
-    page: Page;
-    path: string;
-    cfg: ConfigResponse;
-}>;
 /**
  * Entity resolver function type
  * Users provide this to resolve entities from their route params
  */
 type EntityResolver<T = any> = (params: Promise<T>) => Promise<Entity>;
 /**
- * NitroDebugInfo Component
+ * The Flyo instance returned by initNitro().
+ * Carries all API access methods and configuration state.
+ */
+interface FlyoInstance {
+    /** Read-only configuration state */
+    readonly state: NitroState;
+    /** Fetch and cache the Nitro CMS configuration (React-cached per request) */
+    getNitroConfig(): Promise<ConfigResponse>;
+    /** Create a PagesApi client */
+    getNitroPages(): PagesApi;
+    /** Create an EntitiesApi client */
+    getNitroEntities(): EntitiesApi;
+    /** Create a SitemapApi client */
+    getNitroSitemap(): SitemapApi;
+    /** Create a SearchApi client */
+    getNitroSearch(): SearchApi;
+    /** Resolve a page from catch-all route params (React-cached per request) */
+    pageResolveRoute(props: RouteParams): Promise<{
+        page: Page;
+        path: string;
+        cfg: ConfigResponse;
+    }>;
+    /** Generate a Next.js sitemap from Flyo Nitro content */
+    sitemap(): Promise<MetadataRoute.Sitemap>;
+}
+/**
+ * Initialize and return a FlyoInstance.
+ *
+ * Call once in your flyo.config.tsx and export the result.
+ * The returned object carries all methods bound to the configuration,
+ * eliminating the need for global state.
  *
- * Outputs debug information about the current Nitro/Flyo setup as an HTML comment.
- * This includes environment info, API version, token type, deployment details, etc.
+ * @example
+ * ```tsx
+ * // flyo.config.tsx
+ * import { initNitro } from '@flyo/nitro-next/server';
  *
- * Usage: Add <NitroDebugInfo config={config} /> to your layout to include debug info in the HTML output.
+ * export const flyo = initNitro({
+ *   accessToken: process.env.FLYO_ACCESS_TOKEN || '',
+ *   lang: 'en',
+ *   baseUrl: process.env.SITE_URL || 'http://localhost:3000',
+ *   liveEdit: process.env.FLYO_LIVE_EDIT === 'true',
+ *   components: { HeroBanner, Text },
+ * });
+ * ```
  */
-declare function NitroDebugInfo({ config }: {
-    config: ConfigResponse;
-}): react_jsx_runtime.JSX.Element;
+declare function initNitro({ accessToken, lang, baseUrl, components, showMissingComponentAlert, liveEdit, serverCacheTtl, clientCacheTtl, }: {
+    accessToken: string;
+    lang?: string;
+    baseUrl?: string;
+    components?: Record<string, any>;
+    showMissingComponentAlert?: boolean;
+    liveEdit?: boolean;
+    serverCacheTtl?: number;
+    clientCacheTtl?: number;
+}): FlyoInstance;
 /**
- * Renders a JSON-LD structured data script tag from an Entity's jsonld field.
- * Safely escapes HTML entities to prevent XSS attacks.
- * Returns null if the entity has no jsonld data.
+ * NitroDebugInfo Component
+ *
+ * Async server component that outputs debug information as an HTML comment.
+ * Resolves config internally from the flyo instance.
  *
  * @example
  * ```tsx
- * import { NitroEntityJsonLd } from '@flyo/nitro-next/server';
- *
- * export default function BlogPost({ entity }: { entity: Entity }) {
- *   return (
- *     <>
- *       <NitroEntityJsonLd entity={entity} />
- *       <h1>{entity.entity?.entity_title}</h1>
- *     </>
- *   );
- * }
+ * <NitroDebugInfo flyo={flyo} />
  * ```
  */
+declare function NitroDebugInfo({ flyo }: {
+    flyo: FlyoInstance;
+}): Promise<react_jsx_runtime.JSX.Element>;
+/**
+ * Renders a JSON-LD structured data script tag from an Entity's jsonld field.
+ * Safely escapes HTML to prevent XSS.
+ */
 declare function NitroEntityJsonLd({ entity }: {
     entity: Entity;
 }): react_jsx_runtime.JSX.Element | null;
 /**
- * NitroPage component renders all blocks from a Flyo page
+ * NitroPage renders all blocks from a Flyo page.
  */
-declare function NitroPage({ page, }: {
+declare function NitroPage({ page, flyo, }: {
     page: Page;
+    flyo: FlyoInstance;
 }): react_jsx_runtime.JSX.Element | null;
-declare function NitroBlock({ block, }: {
+/**
+ * NitroBlock renders a single block using the registered component.
+ */
+declare function NitroBlock({ block, flyo, }: {
     block: Block;
+    flyo: FlyoInstance;
 }): react_jsx_runtime.JSX.Element | null;
 /**
- * NitroSlot component renders nested blocks from a slot
- * Used for recursive block rendering when blocks contain slots
+ * NitroSlot renders nested blocks from a slot.
+ * Used for recursive block rendering when blocks contain slots.
  *
  * @example
  * ```tsx
+ * import { flyo } from '@/flyo.config';
  * import { NitroSlot } from '@flyo/nitro-next/server';
  *
- * export default function MyComponent({ block }) {
+ * export function MyComponent({ block }) {
  *   return (
  *     <div>
- *       <NitroSlot slot={block.slots.mysuperslotname} />
+ *       <NitroSlot slot={block.slots?.content} flyo={flyo} />
  *     </div>
  *   );
  * }
  * ```
  */
-declare function NitroSlot({ slot, }: {
+declare function NitroSlot({ slot, flyo, }: {
     slot?: {
         content?: Block[];
     };
+    flyo: FlyoInstance;
 }): react_jsx_runtime.JSX.Element | null;
 /**
- * Default page route handler for Nitro pages
- * Can be re-exported directly from Next.js app routes
+ * Create a page route handler for Nitro pages.
+ * Returns a Next.js page component function.
  *
  * @example
- * ```ts
- * // app/[[...slug]]/page.tsx
- * export { nitroPageRoute as default } from '@flyo/nitro-next/server';
+ * ```tsx
+ * import { flyo } from '@/flyo.config';
+ * import { nitroPageRoute } from '@flyo/nitro-next/server';
+ *
+ * export default nitroPageRoute(flyo);
  * ```
  */
-declare function nitroPageRoute(props: RouteParams): Promise<react_jsx_runtime.JSX.Element>;
+declare function nitroPageRoute(flyo: FlyoInstance): (props: RouteParams) => Promise<react_jsx_runtime.JSX.Element>;
 /**
- * Generate metadata for Nitro pages
- * Provides basic meta tags based on Flyo page data
- * Can be re-exported directly from Next.js app routes
+ * Create a metadata generator for Nitro pages.
+ * Returns a Next.js generateMetadata function.
  *
  * @example
- * ```ts
- * // app/[[...slug]]/page.tsx
- * export { nitroPageGenerateMetadata as generateMetadata } from '@flyo/nitro-next/server';
+ * ```tsx
+ * import { flyo } from '@/flyo.config';
+ * import { nitroPageGenerateMetadata } from '@flyo/nitro-next/server';
+ *
+ * export const generateMetadata = nitroPageGenerateMetadata(flyo);
  * ```
  */
-declare function nitroPageGenerateMetadata(props: RouteParams): Promise<Metadata>;
+declare function nitroPageGenerateMetadata(flyo: FlyoInstance): (props: RouteParams) => Promise<Metadata>;
 /**
- * Generate static params for all Nitro pages
- * Enables static site generation (SSG) for all pages
- * Can be re-exported directly from Next.js app routes
+ * Create a static params generator for Nitro pages.
+ * Returns a Next.js generateStaticParams function.
  *
  * @example
- * ```ts
- * // app/[[...slug]]/page.tsx
- * export { nitroPageGenerateStaticParams as generateStaticParams } from '@flyo/nitro-next/server';
+ * ```tsx
+ * import { flyo } from '@/flyo.config';
+ * import { nitroPageGenerateStaticParams } from '@flyo/nitro-next/server';
+ *
+ * export const generateStaticParams = nitroPageGenerateStaticParams(flyo);
  * ```
  */
-declare function nitroPageGenerateStaticParams(): Promise<{
+declare function nitroPageGenerateStaticParams(flyo: FlyoInstance): () => Promise<{
     slug: string[] | undefined;
 }[]>;
 /**
- * Default entity route handler with custom resolver
- * Flexible solution that works with any route param structure
+ * Create an entity route handler with a custom resolver.
+ * Returns a Next.js page component function.
  *
  * @example
- * ```ts
- * // app/blog/[slug]/page.tsx
- * const resolver = async (params: Promise<{ slug: string }>) => {
+ * ```tsx
+ * import { flyo } from '@/flyo.config';
+ * import { nitroEntityRoute } from '@flyo/nitro-next/server';
+ *
+ * const resolver = async (params) => {
  *   const { slug } = await params;
- *   return getNitroEntities().entityBySlug({ slug, typeId: 123 });
+ *   return flyo.getNitroEntities().entityBySlug({ slug, typeId: 123 });
  * };
  *
- * export default (props) => nitroEntityRoute(props, {
+ * export default nitroEntityRoute(flyo, {
  *   resolver,
- *   render: (entity) => <h1>{entity.entity?.entity_title}</h1>
+ *   render: (entity) => <h1>{entity.entity?.entity_title}</h1>,
  * });
  * ```
- *
- * @example
- * ```ts
- * // app/items/[uniqueid]/page.tsx
- * const resolver = async (params: Promise<{ uniqueid: string }>) => {
- *   const { uniqueid } = await params;
- *   return getNitroEntities().entityByUniqueid({ uniqueid });
- * };
- *
- * export default (props) => nitroEntityRoute(props, { resolver });
- * ```
- *
- * @example
- * ```ts
- * // app/custom/[whatever]/page.tsx
- * const resolver = async (params: Promise<{ whatever: string }>) => {
- *   const { whatever } = await params;
- *   return getNitroEntities().entityBySlug({ slug: whatever });
- * };
- *
- * export default (props) => nitroEntityRoute(props, { resolver });
- * ```
  */
-declare function nitroEntityRoute<T = any>(props: EntityRouteParams<T>, options: {
+declare function nitroEntityRoute<T = any>(flyo: FlyoInstance, options: {
     resolver: EntityResolver<T>;
     render?: (entity: Entity) => React.ReactNode;
-}): Promise<string | number | bigint | boolean | react_jsx_runtime.JSX.Element | Iterable<react.ReactNode> | null | undefined>;
+}): (props: EntityRouteParams<T>) => Promise<string | number | bigint | boolean | react_jsx_runtime.JSX.Element | Iterable<react.ReactNode> | null | undefined>;
 /**
- * Generate metadata for Nitro entities with custom resolver
- * Works with any route param structure
+ * Create a metadata generator for entity detail pages.
+ * Returns a Next.js generateMetadata function.
  *
  * @example
- * ```ts
- * // app/blog/[slug]/page.tsx
- * const resolver = async (params: Promise<{ slug: string }>) => {
- *   const { slug } = await params;
- *   return getNitroEntities().entityBySlug({ slug, typeId: 123 });
- * };
+ * ```tsx
+ * import { flyo } from '@/flyo.config';
+ * import { nitroEntityGenerateMetadata } from '@flyo/nitro-next/server';
  *
- * export const generateMetadata = (props) => nitroEntityGenerateMetadata(props, { resolver });
+ * export const generateMetadata = nitroEntityGenerateMetadata(flyo, { resolver });
  * ```
  */
-declare function nitroEntityGenerateMetadata<T = any>(props: EntityRouteParams<T>, options: {
+declare function nitroEntityGenerateMetadata<T = any>(flyo: FlyoInstance, options: {
     resolver: EntityResolver<T>;
-}): Promise<Metadata>;
-/**
- * Generate sitemap for Next.js from Flyo Nitro
- * Fetches all pages and entities from the sitemap endpoint
- * Uses the baseUrl from the Nitro configuration state
- *
- * @param state The Nitro state containing configuration and baseUrl
- * @returns Promise resolving to Next.js MetadataRoute.Sitemap format
- *
- * @example
- * ```ts
- * // app/sitemap.ts
- * import { nitroSitemap } from '@flyo/nitro-next/server';
- * import { flyoConfig } from '../flyo.config';
- *
- * export default async function sitemap() {
- *   return nitroSitemap(flyoConfig());
- * }
- * ```
- *
- * @example
- * ```ts
- * // flyo.config.tsx
- * export const flyoConfig = initNitro({
- *   accessToken: process.env.FLYO_ACCESS_TOKEN!,
- *   baseUrl: process.env.SITE_URL || 'http://localhost:3000',
- *   lang: 'en',
- * });
- * ```
- */
-declare function nitroSitemap(state: NitroState): Promise<MetadataRoute.Sitemap>;
+}): (props: EntityRouteParams<T>) => Promise<Metadata>;
 
-export { type EntityResolver, NitroBlock, NitroDebugInfo, NitroEntityJsonLd, NitroPage, NitroSlot, type NitroState, getNitro, getNitroConfig, getNitroEntities, getNitroPages, getNitroSearch, getNitroSitemap, globalNitroState, initNitro, nitroEntityGenerateMetadata, nitroEntityRoute, nitroPageGenerateMetadata, nitroPageGenerateStaticParams, nitroPageResolveRoute, nitroPageRoute, nitroSitemap };
+export { type EntityResolver, type FlyoInstance, NitroBlock, NitroDebugInfo, NitroEntityJsonLd, NitroPage, NitroSlot, type NitroState, initNitro, nitroEntityGenerateMetadata, nitroEntityRoute, nitroPageGenerateMetadata, nitroPageGenerateStaticParams, nitroPageRoute };