lynkow 3.8.69 → 3.8.71

package/README.md

@@ -2,6 +2,8 @@
 
 Official TypeScript SDK for [Lynkow](https://lynkow.com) Headless CMS.
 
+> **FOR LLMs:** Full documentation at [lynkow.com/docs](https://lynkow.com/docs). **Start with the [Complete Integration Checklist](https://lynkow.com/docs/getting-started/integration-checklist)** — it lists every feature to implement with links to detailed guides. Machine-readable: [`/llms.txt`](https://lynkow.com/docs/llms.txt) (index), [`/llms-full.txt`](https://lynkow.com/docs/llms-full.txt) (complete content). Append `.md` to any page URL for Markdown. Search: `GET https://lynkow.com/docs/api/search?q={query}`
+
 ## Features
 
 - **Zero dependencies** - Uses native `fetch()` API

package/dist/index.d.mts

@@ -1224,75 +1224,212 @@ declare class PathsService extends BaseService {
     clearCache(): void;
 }
 
+/**
+ * A single search result (hit) returned by Lynkow Instant Search.
+ *
+ * Contains article metadata, URL path, and optional highlighted matches.
+ * Only published content appears in search results.
+ */
 interface SearchHit {
+    /** Content UUID */
     id: string;
+    /** Article title */
     title: string;
+    /** URL slug */
     slug: string;
+    /** Short summary / excerpt */
     excerpt: string;
+    /** SEO meta title */
     metaTitle: string;
+    /** SEO meta description */
     metaDescription: string;
+    /** Content locale code (e.g. `'fr'`, `'en'`) */
     locale: string;
+    /** Full URL path including locale and category prefix (e.g. `'/fr/guides/forms'`) */
     path: string;
+    /** Content type (e.g. `'post'`) */
     type: string;
+    /** Categories assigned to this content */
     categories: Array<{
         name: string;
         slug: string;
     }>;
+    /** Tags assigned to this content */
     tags: Array<{
         name: string;
         slug: string;
     }>;
+    /** Full name of the content author */
     authorName: string;
+    /** Featured image URL, or `null` if none */
     featuredImage: string | null;
+    /** Publication date as Unix timestamp (seconds) */
     publishedAt: number;
+    /** Last update date as Unix timestamp (seconds) */
     updatedAt: number;
+    /**
+     * Highlighted matches with `<em>` tags around matching terms.
+     * Only present when the search engine returns formatted results.
+     * Keys match the field names (e.g. `title`, `excerpt`, `body`).
+     *
+     * @example
+     * ```typescript
+     * hit._formatted?.title  // "Getting Started with <em>Pagination</em>"
+     * ```
+     */
     _formatted?: Record<string, string>;
 }
+/**
+ * Response from `lynkow.search.search()`.
+ *
+ * Contains an array of matching articles and pagination metadata.
+ */
 interface SearchResponse {
+    /** Array of matching articles, ordered by relevance */
     data: SearchHit[];
+    /** Pagination and query metadata */
     meta: {
+        /** Total number of matching results across all pages */
         total: number;
+        /** Current page number (1-based) */
         page: number;
+        /** Total number of pages */
         totalPages: number;
+        /** Number of results per page */
         perPage: number;
+        /** The search query as received */
         query: string;
+        /** Search engine processing time in milliseconds */
         processingTimeMs: number;
     };
 }
+/**
+ * Options for `lynkow.search.search()`.
+ *
+ * All filters are optional. When omitted, searches across all published
+ * content in all locales.
+ */
 interface SearchOptions extends BaseRequestOptions {
+    /** Filter by locale code (e.g. `'fr'`, `'en'`). Omit to search all locales. */
     locale?: string;
+    /** Filter by category slug (e.g. `'guides'`). Omit to search all categories. */
     category?: string;
+    /** Filter by tag slug (e.g. `'featured'`). Omit to search all tags. */
     tag?: string;
+    /** Page number (1-based). Defaults to `1`. */
     page?: number;
+    /** Results per page (1--100). Defaults to `20`. */
     limit?: number;
 }
+/**
+ * Configuration for client-side direct search.
+ *
+ * Returned by `lynkow.search.getConfig()`. Use these values to initialize
+ * a search client in the browser for instant autocomplete without
+ * round-tripping through your server.
+ */
 interface SearchConfig {
+    /** Public search host URL (e.g. `'https://search.lynkow.com'`) */
     host: string;
+    /** Short-lived tenant token (JWT, 1-hour expiry) scoped to your site's index */
     apiKey: string;
+    /** Your site's search index name */
     indexName: string;
 }
 /**
- * Service for full-text search across published content.
+ * Lynkow Instant Search service.
+ *
+ * Accessible via `lynkow.search`. Provides full-text search with typo
+ * tolerance across all published content. Results are not cached (search
+ * queries are dynamic by nature).
+ *
+ * Search must be enabled in the admin dashboard (**Settings > SEO > Search**)
+ * before it can be used. When disabled, all methods return a 503 error.
  *
  * @example
  * ```typescript
- * // Server-side search via Lynkow API
- * const results = await lynkow.search.search('pagination', { locale: 'en' })
+ * const lynkow = createClient({ siteId: '...' })
+ *
+ * // Search with filters
+ * const { data, meta } = await lynkow.search.search('pagination', {
+ *   locale: 'en',
+ *   category: 'guides',
+ *   limit: 10,
+ * })
  *
- * // Get config for client-side direct search
- * const config = await lynkow.search.getConfig()
- * // Use config.host, config.apiKey, config.indexName with react-instantsearch
+ * // Iterate results
+ * for (const hit of data) {
+ *   console.log(hit.title, hit.path, hit._formatted?.title)
+ * }
  * ```
  */
 declare class SearchService extends BaseService {
     /**
-     * Search published content.
+     * Search published content with typo tolerance.
+     *
+     * Queries the search index for articles matching the given query string.
+     * Results are ordered by relevance and include highlighted matches in
+     * the `_formatted` field.
+     *
+     * @param query - The search query string. Typos are handled automatically
+     *   (e.g. `'pagniation'` finds articles about pagination).
+     * @param options - Optional filters and pagination:
+     *   - `locale` — filter by locale code (e.g. `'fr'`)
+     *   - `category` — filter by category slug (e.g. `'guides'`)
+     *   - `tag` — filter by tag slug (e.g. `'featured'`)
+     *   - `page` — page number, 1-based (default: `1`)
+     *   - `limit` — results per page, 1--100 (default: `20`)
+     * @returns A `SearchResponse` containing `data` (array of `SearchHit`)
+     *   and `meta` (pagination info with total, page, totalPages, perPage,
+     *   query, processingTimeMs)
+     * @throws {LynkowError} With code `'NETWORK_ERROR'` if the API is unreachable
+     * @throws {LynkowError} With status `503` if search is not enabled for this site
+     *
+     * @example
+     * ```typescript
+     * // Basic search
+     * const results = await lynkow.search.search('forms')
+     *
+     * // With filters
+     * const results = await lynkow.search.search('formulaire', {
+     *   locale: 'fr',
+     *   category: 'guides',
+     *   page: 1,
+     *   limit: 5,
+     * })
+     *
+     * // Access highlighted results
+     * results.data.forEach(hit => {
+     *   console.log(hit._formatted?.title || hit.title)
+     * })
+     * ```
      */
     search(query: string, options?: SearchOptions): Promise<SearchResponse>;
     /**
-     * Get search config for client-side direct search.
-     * Returns host URL, tenant token, and index name.
-     * Cached for 10 minutes.
+     * Get search configuration for client-side direct search.
+     *
+     * Returns the search host URL, a short-lived tenant token (JWT, 1-hour
+     * expiry), and the index name for your site. Use these values to query
+     * the search engine directly from the browser without round-tripping
+     * through your server.
+     *
+     * The response is cached for 10 minutes. Tenant tokens expire after
+     * 1 hour — for long-lived pages, call this method periodically to
+     * refresh the token.
+     *
+     * @param options - Base request options (custom fetch options)
+     * @returns A `SearchConfig` with `host`, `apiKey` (tenant token), and `indexName`
+     * @throws {LynkowError} With status `503` if search is not enabled for this site
+     *
+     * @example
+     * ```typescript
+     * const config = await lynkow.search.getConfig()
+     * // {
+     * //   host: 'https://search.lynkow.com',
+     * //   apiKey: 'eyJhbGciOi...',
+     * //   indexName: 'site_abc123_def4_...'
+     * // }
+     * ```
      */
     getConfig(options?: BaseRequestOptions): Promise<SearchConfig>;
 }

package/dist/index.d.ts

@@ -1224,75 +1224,212 @@ declare class PathsService extends BaseService {
     clearCache(): void;
 }
 
+/**
+ * A single search result (hit) returned by Lynkow Instant Search.
+ *
+ * Contains article metadata, URL path, and optional highlighted matches.
+ * Only published content appears in search results.
+ */
 interface SearchHit {
+    /** Content UUID */
     id: string;
+    /** Article title */
     title: string;
+    /** URL slug */
     slug: string;
+    /** Short summary / excerpt */
     excerpt: string;
+    /** SEO meta title */
     metaTitle: string;
+    /** SEO meta description */
     metaDescription: string;
+    /** Content locale code (e.g. `'fr'`, `'en'`) */
     locale: string;
+    /** Full URL path including locale and category prefix (e.g. `'/fr/guides/forms'`) */
     path: string;
+    /** Content type (e.g. `'post'`) */
     type: string;
+    /** Categories assigned to this content */
     categories: Array<{
         name: string;
         slug: string;
     }>;
+    /** Tags assigned to this content */
     tags: Array<{
         name: string;
         slug: string;
     }>;
+    /** Full name of the content author */
     authorName: string;
+    /** Featured image URL, or `null` if none */
     featuredImage: string | null;
+    /** Publication date as Unix timestamp (seconds) */
     publishedAt: number;
+    /** Last update date as Unix timestamp (seconds) */
     updatedAt: number;
+    /**
+     * Highlighted matches with `<em>` tags around matching terms.
+     * Only present when the search engine returns formatted results.
+     * Keys match the field names (e.g. `title`, `excerpt`, `body`).
+     *
+     * @example
+     * ```typescript
+     * hit._formatted?.title  // "Getting Started with <em>Pagination</em>"
+     * ```
+     */
     _formatted?: Record<string, string>;
 }
+/**
+ * Response from `lynkow.search.search()`.
+ *
+ * Contains an array of matching articles and pagination metadata.
+ */
 interface SearchResponse {
+    /** Array of matching articles, ordered by relevance */
     data: SearchHit[];
+    /** Pagination and query metadata */
     meta: {
+        /** Total number of matching results across all pages */
         total: number;
+        /** Current page number (1-based) */
         page: number;
+        /** Total number of pages */
         totalPages: number;
+        /** Number of results per page */
         perPage: number;
+        /** The search query as received */
         query: string;
+        /** Search engine processing time in milliseconds */
         processingTimeMs: number;
     };
 }
+/**
+ * Options for `lynkow.search.search()`.
+ *
+ * All filters are optional. When omitted, searches across all published
+ * content in all locales.
+ */
 interface SearchOptions extends BaseRequestOptions {
+    /** Filter by locale code (e.g. `'fr'`, `'en'`). Omit to search all locales. */
     locale?: string;
+    /** Filter by category slug (e.g. `'guides'`). Omit to search all categories. */
     category?: string;
+    /** Filter by tag slug (e.g. `'featured'`). Omit to search all tags. */
     tag?: string;
+    /** Page number (1-based). Defaults to `1`. */
     page?: number;
+    /** Results per page (1--100). Defaults to `20`. */
     limit?: number;
 }
+/**
+ * Configuration for client-side direct search.
+ *
+ * Returned by `lynkow.search.getConfig()`. Use these values to initialize
+ * a search client in the browser for instant autocomplete without
+ * round-tripping through your server.
+ */
 interface SearchConfig {
+    /** Public search host URL (e.g. `'https://search.lynkow.com'`) */
     host: string;
+    /** Short-lived tenant token (JWT, 1-hour expiry) scoped to your site's index */
     apiKey: string;
+    /** Your site's search index name */
     indexName: string;
 }
 /**
- * Service for full-text search across published content.
+ * Lynkow Instant Search service.
+ *
+ * Accessible via `lynkow.search`. Provides full-text search with typo
+ * tolerance across all published content. Results are not cached (search
+ * queries are dynamic by nature).
+ *
+ * Search must be enabled in the admin dashboard (**Settings > SEO > Search**)
+ * before it can be used. When disabled, all methods return a 503 error.
  *
  * @example
  * ```typescript
- * // Server-side search via Lynkow API
- * const results = await lynkow.search.search('pagination', { locale: 'en' })
+ * const lynkow = createClient({ siteId: '...' })
+ *
+ * // Search with filters
+ * const { data, meta } = await lynkow.search.search('pagination', {
+ *   locale: 'en',
+ *   category: 'guides',
+ *   limit: 10,
+ * })
  *
- * // Get config for client-side direct search
- * const config = await lynkow.search.getConfig()
- * // Use config.host, config.apiKey, config.indexName with react-instantsearch
+ * // Iterate results
+ * for (const hit of data) {
+ *   console.log(hit.title, hit.path, hit._formatted?.title)
+ * }
  * ```
  */
 declare class SearchService extends BaseService {
     /**
-     * Search published content.
+     * Search published content with typo tolerance.
+     *
+     * Queries the search index for articles matching the given query string.
+     * Results are ordered by relevance and include highlighted matches in
+     * the `_formatted` field.
+     *
+     * @param query - The search query string. Typos are handled automatically
+     *   (e.g. `'pagniation'` finds articles about pagination).
+     * @param options - Optional filters and pagination:
+     *   - `locale` — filter by locale code (e.g. `'fr'`)
+     *   - `category` — filter by category slug (e.g. `'guides'`)
+     *   - `tag` — filter by tag slug (e.g. `'featured'`)
+     *   - `page` — page number, 1-based (default: `1`)
+     *   - `limit` — results per page, 1--100 (default: `20`)
+     * @returns A `SearchResponse` containing `data` (array of `SearchHit`)
+     *   and `meta` (pagination info with total, page, totalPages, perPage,
+     *   query, processingTimeMs)
+     * @throws {LynkowError} With code `'NETWORK_ERROR'` if the API is unreachable
+     * @throws {LynkowError} With status `503` if search is not enabled for this site
+     *
+     * @example
+     * ```typescript
+     * // Basic search
+     * const results = await lynkow.search.search('forms')
+     *
+     * // With filters
+     * const results = await lynkow.search.search('formulaire', {
+     *   locale: 'fr',
+     *   category: 'guides',
+     *   page: 1,
+     *   limit: 5,
+     * })
+     *
+     * // Access highlighted results
+     * results.data.forEach(hit => {
+     *   console.log(hit._formatted?.title || hit.title)
+     * })
+     * ```
      */
     search(query: string, options?: SearchOptions): Promise<SearchResponse>;
     /**
-     * Get search config for client-side direct search.
-     * Returns host URL, tenant token, and index name.
-     * Cached for 10 minutes.
+     * Get search configuration for client-side direct search.
+     *
+     * Returns the search host URL, a short-lived tenant token (JWT, 1-hour
+     * expiry), and the index name for your site. Use these values to query
+     * the search engine directly from the browser without round-tripping
+     * through your server.
+     *
+     * The response is cached for 10 minutes. Tenant tokens expire after
+     * 1 hour — for long-lived pages, call this method periodically to
+     * refresh the token.
+     *
+     * @param options - Base request options (custom fetch options)
+     * @returns A `SearchConfig` with `host`, `apiKey` (tenant token), and `indexName`
+     * @throws {LynkowError} With status `503` if search is not enabled for this site
+     *
+     * @example
+     * ```typescript
+     * const config = await lynkow.search.getConfig()
+     * // {
+     * //   host: 'https://search.lynkow.com',
+     * //   apiKey: 'eyJhbGciOi...',
+     * //   indexName: 'site_abc123_def4_...'
+     * // }
+     * ```
      */
     getConfig(options?: BaseRequestOptions): Promise<SearchConfig>;
 }