lynkow 1.0.0

package/README.md

@@ -0,0 +1,314 @@
+# Lynkow SDK
+
+Official TypeScript SDK for [Lynkow](https://lynkow.com) Headless CMS.
+
+## Features
+
+- **Zero dependencies** - Uses native `fetch()` API
+- **Type-safe** - Full TypeScript support with comprehensive types
+- **Framework-agnostic** - Works with Next.js, Nuxt, Astro, SvelteKit, etc.
+- **Tree-shakeable** - Only import what you need
+- **Spam protection** - Built-in honeypot fields for form submissions
+
+## Installation
+
+```bash
+npm install lynkow
+# or
+yarn add lynkow
+# or
+pnpm add lynkow
+```
+
+## Quick Start
+
+```typescript
+import { createLynkowClient } from 'lynkow'
+
+const lynkow = createLynkowClient({
+  siteId: 'your-site-uuid',
+  locale: 'fr', // optional default locale
+})
+
+// Fetch blog posts
+const { data: posts, meta } = await lynkow.contents.list({
+  page: 1,
+  perPage: 10,
+  category: 'tech',
+})
+
+// Fetch a single post
+const post = await lynkow.contents.getBySlug('my-article')
+```
+
+## Configuration
+
+```typescript
+interface LynkowConfig {
+  // Required: Your site UUID
+  siteId: string
+
+  // Optional: API base URL (default: https://api.lynkow.com)
+  baseUrl?: string
+
+  // Optional: Default locale for all requests
+  locale?: string
+
+  // Optional: Custom fetch options (for Next.js cache, etc.)
+  fetchOptions?: RequestInit
+}
+```
+
+### Next.js App Router Example
+
+```typescript
+const lynkow = createLynkowClient({
+  siteId: process.env.LYNKOW_SITE_ID!,
+  locale: 'fr',
+  fetchOptions: {
+    next: { revalidate: 60 }, // ISR: revalidate every 60 seconds
+  },
+})
+```
+
+## Services
+
+### Contents (Blog Posts)
+
+```typescript
+// List contents with filters
+const { data, meta } = await lynkow.contents.list({
+  page: 1,
+  perPage: 10,
+  category: 'tech',
+  tag: 'javascript',
+  search: 'tutorial',
+  sort: 'published_at',
+  order: 'desc',
+})
+
+// Get by slug
+const content = await lynkow.contents.getBySlug('my-article')
+```
+
+### Categories
+
+```typescript
+// List all categories
+const { data } = await lynkow.categories.list()
+
+// Get category tree (nested)
+const { data: tree } = await lynkow.categories.tree()
+
+// Get category with its contents
+const { category, contents } = await lynkow.categories.getBySlug('tech', {
+  page: 1,
+  perPage: 10,
+})
+```
+
+### Tags
+
+```typescript
+const { data: tags } = await lynkow.tags.list()
+```
+
+### Pages (Site Blocks)
+
+```typescript
+// List all pages
+const { data } = await lynkow.pages.list()
+
+// Get page by slug
+const page = await lynkow.pages.getBySlug('about')
+
+// Get page by path
+const page = await lynkow.pages.getByPath('/services/consulting')
+
+// Get JSON-LD data
+const jsonLd = await lynkow.pages.getJsonLd('about')
+```
+
+### Global Blocks (Header, Footer)
+
+```typescript
+// Get site config with all global blocks
+const { data } = await lynkow.blocks.siteConfig()
+const header = data.globals['header']
+const footer = data.globals['footer']
+
+// Get a specific global block
+const { data: header } = await lynkow.blocks.global('header')
+```
+
+### Forms
+
+```typescript
+// Get form schema
+const form = await lynkow.forms.getBySlug('contact')
+
+// Submit form (spam protection is automatic)
+const result = await lynkow.forms.submit('contact', {
+  name: 'John Doe',
+  email: 'john@example.com',
+  message: 'Hello!',
+})
+
+// With reCAPTCHA token
+const result = await lynkow.forms.submit(
+  'contact',
+  { name: 'John', email: 'john@example.com' },
+  { recaptchaToken: 'token-from-recaptcha' }
+)
+```
+
+### Reviews
+
+```typescript
+// List approved reviews
+const { data, meta } = await lynkow.reviews.list({
+  minRating: 4,
+  perPage: 10,
+})
+
+// Get review settings
+const settings = await lynkow.reviews.settings()
+
+// Submit a review
+const result = await lynkow.reviews.submit({
+  authorName: 'Alice',
+  rating: 5,
+  content: 'Excellent service!',
+})
+```
+
+### Site Configuration
+
+```typescript
+const config = await lynkow.site.getConfig()
+console.log(config.enabledLocales) // ['fr', 'en']
+console.log(config.defaultLocale) // 'fr'
+```
+
+### Legal Documents
+
+```typescript
+// List all legal documents
+const { data } = await lynkow.legal.list()
+
+// Get specific document
+const privacy = await lynkow.legal.getByType('privacy')
+const terms = await lynkow.legal.getByType('terms')
+```
+
+### Cookie Consent
+
+```typescript
+// Get cookie banner config
+const config = await lynkow.cookies.getConfig()
+
+// Log user consent
+await lynkow.cookies.logConsent({
+  necessary: true,
+  analytics: true,
+  marketing: false,
+})
+```
+
+### SEO (Sitemap, Robots)
+
+```typescript
+// Get sitemap XML
+const xml = await lynkow.seo.sitemap()
+
+// Get robots.txt
+const txt = await lynkow.seo.robots()
+```
+
+### Paths (SSG)
+
+```typescript
+// Get all paths for static generation
+const { paths } = await lynkow.paths.list()
+
+// Resolve a path to content or category
+const result = await lynkow.paths.resolve('/blog/tech/my-article')
+if (result.type === 'content') {
+  // Render article
+} else {
+  // Render category listing
+}
+
+// Check for redirects
+const redirect = await lynkow.paths.matchRedirect('/old-page')
+if (redirect) {
+  // Redirect to redirect.target with redirect.statusCode
+}
+```
+
+## Error Handling
+
+```typescript
+import { LynkowError, isLynkowError } from 'lynkow'
+
+try {
+  const post = await lynkow.contents.getBySlug('not-found')
+} catch (error) {
+  if (isLynkowError(error)) {
+    console.log(error.status) // 404
+    console.log(error.code) // 'NOT_FOUND'
+    console.log(error.message) // 'Content not found'
+    console.log(error.errors) // [{ message: '...' }]
+  }
+}
+```
+
+### Error Codes
+
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| `BAD_REQUEST` | 400 | Invalid request |
+| `UNAUTHORIZED` | 401 | Authentication required |
+| `FORBIDDEN` | 403 | Access denied |
+| `NOT_FOUND` | 404 | Resource not found |
+| `VALIDATION_ERROR` | 422 | Validation failed |
+| `TOO_MANY_REQUESTS` | 429 | Rate limited |
+| `INTERNAL_ERROR` | 500 | Server error |
+| `SERVICE_UNAVAILABLE` | 503 | Service unavailable |
+| `NETWORK_ERROR` | 0 | Network error |
+
+## Type Guards
+
+```typescript
+import { isContentResolve, isCategoryResolve } from 'lynkow'
+
+const result = await lynkow.paths.resolve('/blog/tech')
+
+if (isContentResolve(result)) {
+  // result.content is available
+} else if (isCategoryResolve(result)) {
+  // result.category and result.contents are available
+}
+```
+
+## TypeScript
+
+All types are exported for your convenience:
+
+```typescript
+import type {
+  Content,
+  ContentSummary,
+  Category,
+  Page,
+  Form,
+  Review,
+  LynkowConfig,
+  ContentsFilters,
+  // ... and many more
+} from 'lynkow'
+```
+
+## License
+
+MIT