@lvlz/sdk 0.1.0

package/README.md

@@ -0,0 +1,130 @@
+# @lvlz/sdk
+
+Fetch and render your [LVLZ.ai](https://lvlz.ai) published posts on **any** site —
+Next.js, React, Vite, or plain HTML. LVLZ generates SEO/GEO-optimized blog posts; this
+SDK puts them on your domain so they boost _your_ search and AI-answer visibility.
+
+> **For SEO/GEO, render on the server.** AI crawlers (GPTBot, ClaudeBot, PerplexityBot)
+> usually don't run JavaScript, and Google's JS rendering is unreliable. The Next.js
+> recipe below server-renders your posts — that's what actually moves the needle. The
+> `<script>` embed is a convenience for sites without a build step.
+
+## Install
+
+```bash
+npm install @lvlz/sdk
+```
+
+Get a **publishable key** (`lvlz_pub_…`) from LVLZ → Settings → Integrations → Website SDK.
+It's read-only and brand-scoped, so it's safe to ship in client code.
+
+## Core client
+
+```ts
+import { createClient } from '@lvlz/sdk';
+
+const lvlz = createClient({ apiKey: 'lvlz_pub_…' });
+
+const { posts } = await lvlz.getPosts({ limit: 20 });
+const post = await lvlz.getPost('my-post-slug'); // null if not found
+```
+
+## Next.js (recommended — SSR + ISR + metadata)
+
+`app/blog/page.tsx`
+
+```tsx
+import { createClient } from '@lvlz/sdk';
+import { LvlzPostList } from '@lvlz/sdk/react';
+
+const lvlz = createClient({ apiKey: process.env.LVLZ_KEY! });
+export const revalidate = 600; // re-check for new posts every 10 minutes
+
+export default async function Blog() {
+  const { posts } = await lvlz.getPosts();
+  return <LvlzPostList posts={posts} />;
+}
+```
+
+`app/blog/[slug]/page.tsx`
+
+```tsx
+import { notFound } from 'next/navigation';
+import type { Metadata } from 'next';
+import { createClient } from '@lvlz/sdk';
+import { LvlzArticle } from '@lvlz/sdk/react';
+
+const lvlz = createClient({ apiKey: process.env.LVLZ_KEY! });
+export const revalidate = 600;
+
+export async function generateStaticParams() {
+  const { posts } = await lvlz.getPosts({ limit: 100 });
+  return posts.map((p) => ({ slug: p.slug }));
+}
+
+export async function generateMetadata(
+  { params }: { params: Promise<{ slug: string }> },
+): Promise<Metadata> {
+  const { slug } = await params;
+  const post = await lvlz.getPost(slug);
+  if (!post) return {};
+  return {
+    title: post.title,
+    description: post.description ?? post.excerpt ?? undefined,
+    keywords: post.keywords,
+    openGraph: { title: post.title, description: post.excerpt ?? undefined, type: 'article' },
+  };
+}
+
+export default async function PostPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const post = await lvlz.getPost(slug);
+  if (!post) notFound();
+  return <LvlzArticle post={post} className="prose mx-auto" />;
+}
+```
+
+`LvlzArticle` also injects a `BlogPosting` JSON-LD `<script>` for richer SEO/GEO.
+
+## React / Vite (client-side)
+
+```tsx
+import { useEffect, useState } from 'react';
+import { createClient, type PublicPost } from '@lvlz/sdk';
+import { LvlzPostList } from '@lvlz/sdk/react';
+
+const lvlz = createClient({ apiKey: import.meta.env.VITE_LVLZ_KEY });
+
+export function Blog() {
+  const [posts, setPosts] = useState<PublicPost[]>([]);
+  useEffect(() => {
+    lvlz.getPosts().then((r) => setPosts(r.posts));
+  }, []);
+  return <LvlzPostList posts={posts} />;
+}
+```
+
+## Plain HTML (no build step)
+
+```html
+<div id="lvlz-blog"></div>
+<script
+  src="https://app.lvlz.ai/sdk.js"
+  data-key="lvlz_pub_…"
+  data-target="#lvlz-blog"
+></script>
+```
+
+The embed lists your posts and renders a single post when the URL has `?lvlz_slug=…`.
+Add `data-slug="my-post-slug"` to render one specific post.
+
+## API
+
+| Method | Returns |
+| --- | --- |
+| `createClient({ apiKey, baseUrl?, fetchOptions? })` | `LvlzClient` |
+| `client.getPosts({ limit?, offset? })` | `{ posts, total, limit, offset }` |
+| `client.getPost(slug)` | `PublicPost \| null` |
+
+Feed responses are edge-cached (`s-maxage` + `stale-while-revalidate`), so reads are fast
+and won't hammer your quota.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@lvlz/sdk",
+  "version": "0.1.0",
+  "description": "Fetch and render your LVLZ.ai published posts on any site (Next.js, React, Vite, plain HTML).",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "require": "./dist/react.cjs"
+    }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "keywords": ["seo", "geo", "blog", "headless", "cms", "lvlz"],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "react": "^19",
+    "tsup": "^8.0.0",
+    "typescript": "^5"
+  }
+}