@lvlz/sdk 0.1.0 → 0.1.2

package/README.md

@@ -126,5 +126,27 @@ Add `data-slug="my-post-slug"` to render one specific post.
 | `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.
+## Caching
+
+The feed is edge-cached (`s-maxage=300, stale-while-revalidate=86400`), so reads are fast and
+won't hammer your quota. Two things to know:
+
+- **Empty responses are never cached** — as soon as your first post is published it shows up
+  (no stale empty feed).
+- `getPosts()` always sends `limit`/`offset`, so every call hits one canonical, cacheable URL.
+
+Control the **framework-level** cache via `fetchOptions`:
+
+```ts
+// Next.js — ISR: re-fetch at most every 10 minutes (pairs with `export const revalidate`)
+const lvlz = createClient({
+  apiKey: process.env.LVLZ_KEY!,
+  fetchOptions: { next: { revalidate: 600 } },
+});
+
+// Always fresh (e.g. a preview/dev environment)
+const lvlz = createClient({ apiKey: '…', fetchOptions: { cache: 'no-store' } });
+```
+
+New posts appear within the `s-maxage` window (≤5 min) of your `revalidate` interval.
+

package/dist/index.cjs

@@ -0,0 +1,62 @@
+'use strict';
+
+// src/index.ts
+var DEFAULT_BASE = "https://app.lvlz.ai";
+var LvlzError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = "LvlzError";
+    this.status = status;
+  }
+};
+function createClient(options) {
+  const base = (options.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "");
+  const key = options.apiKey.trim();
+  async function request(path, params, init) {
+    const url = new URL(`${base}/api/sdk/v1${path}`);
+    url.searchParams.set("key", key);
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== void 0) url.searchParams.set(k, String(v));
+    }
+    const res = await fetch(url.toString(), {
+      credentials: "omit",
+      ...options.fetchOptions,
+      ...init
+    });
+    if (!res.ok) {
+      let message = `Request failed (${res.status})`;
+      try {
+        const body = await res.json();
+        if (body?.error) message = body.error;
+      } catch {
+      }
+      throw new LvlzError(message, res.status);
+    }
+    return res.json();
+  }
+  return {
+    getPosts(opts = {}, init) {
+      return request(
+        "/posts",
+        { limit: opts.limit ?? 20, offset: opts.offset ?? 0 },
+        init
+      );
+    },
+    async getPost(slug, init) {
+      try {
+        const { post } = await request(
+          `/posts/${encodeURIComponent(slug)}`,
+          {},
+          init
+        );
+        return post;
+      } catch (e) {
+        if (e instanceof LvlzError && e.status === 404) return null;
+        throw e;
+      }
+    }
+  };
+}
+
+exports.LvlzError = LvlzError;
+exports.createClient = createClient;

package/dist/index.d.cts

@@ -0,0 +1,49 @@
+interface PublicPost {
+    id: string;
+    slug: string;
+    title: string;
+    excerpt: string | null;
+    description: string | null;
+    /** Clean semantic HTML, ready to render. */
+    html: string;
+    keywords: string[];
+    wordCount: number;
+    publishedAt: string | null;
+    updatedAt: string;
+    canonicalUrl?: string | null;
+    coverImage?: string | null;
+    /** BlogPosting JSON-LD string — inject in a <script type="application/ld+json">. */
+    jsonLd: string;
+}
+interface PublicPostList {
+    posts: PublicPost[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface LvlzClientOptions {
+    /** Your publishable key (lvlz_pub_…). Safe to ship in client code. */
+    apiKey: string;
+    /** Defaults to https://app.lvlz.ai */
+    baseUrl?: string;
+    /**
+     * Extra fetch options merged into every request — e.g. Next.js caching:
+     * `{ next: { revalidate: 600 } }`.
+     */
+    fetchOptions?: RequestInit;
+}
+interface GetPostsOptions {
+    limit?: number;
+    offset?: number;
+}
+declare class LvlzError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+interface LvlzClient {
+    getPosts(options?: GetPostsOptions, init?: RequestInit): Promise<PublicPostList>;
+    getPost(slug: string, init?: RequestInit): Promise<PublicPost | null>;
+}
+declare function createClient(options: LvlzClientOptions): LvlzClient;
+
+export { type GetPostsOptions, type LvlzClient, type LvlzClientOptions, LvlzError, type PublicPost, type PublicPostList, createClient };

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+interface PublicPost {
+    id: string;
+    slug: string;
+    title: string;
+    excerpt: string | null;
+    description: string | null;
+    /** Clean semantic HTML, ready to render. */
+    html: string;
+    keywords: string[];
+    wordCount: number;
+    publishedAt: string | null;
+    updatedAt: string;
+    canonicalUrl?: string | null;
+    coverImage?: string | null;
+    /** BlogPosting JSON-LD string — inject in a <script type="application/ld+json">. */
+    jsonLd: string;
+}
+interface PublicPostList {
+    posts: PublicPost[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface LvlzClientOptions {
+    /** Your publishable key (lvlz_pub_…). Safe to ship in client code. */
+    apiKey: string;
+    /** Defaults to https://app.lvlz.ai */
+    baseUrl?: string;
+    /**
+     * Extra fetch options merged into every request — e.g. Next.js caching:
+     * `{ next: { revalidate: 600 } }`.
+     */
+    fetchOptions?: RequestInit;
+}
+interface GetPostsOptions {
+    limit?: number;
+    offset?: number;
+}
+declare class LvlzError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+interface LvlzClient {
+    getPosts(options?: GetPostsOptions, init?: RequestInit): Promise<PublicPostList>;
+    getPost(slug: string, init?: RequestInit): Promise<PublicPost | null>;
+}
+declare function createClient(options: LvlzClientOptions): LvlzClient;
+
+export { type GetPostsOptions, type LvlzClient, type LvlzClientOptions, LvlzError, type PublicPost, type PublicPostList, createClient };

package/dist/index.js

@@ -0,0 +1,59 @@
+// src/index.ts
+var DEFAULT_BASE = "https://app.lvlz.ai";
+var LvlzError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = "LvlzError";
+    this.status = status;
+  }
+};
+function createClient(options) {
+  const base = (options.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "");
+  const key = options.apiKey.trim();
+  async function request(path, params, init) {
+    const url = new URL(`${base}/api/sdk/v1${path}`);
+    url.searchParams.set("key", key);
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== void 0) url.searchParams.set(k, String(v));
+    }
+    const res = await fetch(url.toString(), {
+      credentials: "omit",
+      ...options.fetchOptions,
+      ...init
+    });
+    if (!res.ok) {
+      let message = `Request failed (${res.status})`;
+      try {
+        const body = await res.json();
+        if (body?.error) message = body.error;
+      } catch {
+      }
+      throw new LvlzError(message, res.status);
+    }
+    return res.json();
+  }
+  return {
+    getPosts(opts = {}, init) {
+      return request(
+        "/posts",
+        { limit: opts.limit ?? 20, offset: opts.offset ?? 0 },
+        init
+      );
+    },
+    async getPost(slug, init) {
+      try {
+        const { post } = await request(
+          `/posts/${encodeURIComponent(slug)}`,
+          {},
+          init
+        );
+        return post;
+      } catch (e) {
+        if (e instanceof LvlzError && e.status === 404) return null;
+        throw e;
+      }
+    }
+  };
+}
+
+export { LvlzError, createClient };

package/dist/react.cjs

@@ -0,0 +1,78 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/react.tsx
+var STYLE_TAG_ID = "lvlz-sdk-styles";
+var CSS = `
+.lvlz-article{max-width:768px;margin:0 auto;color:inherit}
+.lvlz-cover{width:100%;aspect-ratio:16/9;border-radius:16px;overflow:hidden;margin:0 0 2rem;background:#f3f3f5}
+.lvlz-cover img{width:100%;height:100%;object-fit:cover;display:block}
+.lvlz-title{font-size:2.25rem;font-weight:780;line-height:1.15;margin:0 0 1.25rem;letter-spacing:-.02em}
+.lvlz-prose{line-height:1.75;font-size:1.05rem}
+.lvlz-prose h2{font-size:1.6rem;font-weight:720;margin:2.2rem 0 .8rem;line-height:1.25;letter-spacing:-.01em}
+.lvlz-prose h3{font-size:1.25rem;font-weight:680;margin:1.6rem 0 .6rem}
+.lvlz-prose p{margin:0 0 1.1rem}
+.lvlz-prose a{color:#7c3aed;text-decoration:underline;text-underline-offset:2px}
+.lvlz-prose ul,.lvlz-prose ol{margin:0 0 1.1rem 1.25rem}
+.lvlz-prose li{margin:.35rem 0}
+.lvlz-prose blockquote{border-left:3px solid #7c3aed;padding-left:1rem;margin:1.4rem 0;color:#555;font-style:italic}
+.lvlz-prose img{width:100%;height:auto;border-radius:12px;margin:1.6rem 0;display:block}
+.lvlz-list{display:grid;gap:1.5rem;grid-template-columns:repeat(auto-fill,minmax(280px,1fr));list-style:none;padding:0;margin:0}
+.lvlz-card{overflow:hidden;border-radius:14px;border:1px solid rgba(0,0,0,.08);background:#fff;transition:transform .15s ease,box-shadow .15s ease}
+.lvlz-card:hover{transform:translateY(-2px);box-shadow:0 10px 30px rgba(0,0,0,.08)}
+.lvlz-card a{text-decoration:none;color:inherit;display:flex;flex-direction:column;height:100%}
+.lvlz-card-thumb{aspect-ratio:16/9;overflow:hidden;background:#f3f3f5}
+.lvlz-card-thumb img{width:100%;height:100%;object-fit:cover;display:block;transition:transform .3s ease}
+.lvlz-card:hover .lvlz-card-thumb img{transform:scale(1.04)}
+.lvlz-card-body{padding:1rem 1.1rem 1.2rem}
+.lvlz-card-title{font-size:1.05rem;font-weight:680;margin:0 0 .4rem;line-height:1.3}
+.lvlz-card-excerpt{font-size:.9rem;color:#666;margin:0;line-height:1.5}
+@media (prefers-color-scheme:dark){
+.lvlz-card{background:#15151a;border-color:rgba(255,255,255,.1)}
+.lvlz-card-excerpt{color:#a1a1aa}
+.lvlz-prose blockquote{color:#a1a1aa}
+}
+`;
+function LvlzStyles() {
+  return /* @__PURE__ */ jsxRuntime.jsx("style", { id: STYLE_TAG_ID, dangerouslySetInnerHTML: { __html: CSS } });
+}
+function LvlzArticle({
+  post,
+  className,
+  includeJsonLd = true,
+  showCover = true,
+  showTitle = true,
+  styled = true
+}) {
+  return /* @__PURE__ */ jsxRuntime.jsxs("article", { className: ["lvlz-article", className].filter(Boolean).join(" "), children: [
+    styled ? /* @__PURE__ */ jsxRuntime.jsx(LvlzStyles, {}) : null,
+    includeJsonLd && post.jsonLd ? /* @__PURE__ */ jsxRuntime.jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: post.jsonLd } }) : null,
+    showCover && post.coverImage ? /* @__PURE__ */ jsxRuntime.jsx("figure", { className: "lvlz-cover", children: /* @__PURE__ */ jsxRuntime.jsx("img", { src: post.coverImage, alt: post.title, loading: "eager" }) }) : null,
+    showTitle ? /* @__PURE__ */ jsxRuntime.jsx("h1", { className: "lvlz-title", children: post.title }) : null,
+    /* @__PURE__ */ jsxRuntime.jsx("div", { className: "lvlz-prose", dangerouslySetInnerHTML: { __html: post.html } })
+  ] });
+}
+function LvlzPostList({
+  posts,
+  className,
+  hrefFor,
+  renderItem,
+  styled = true
+}) {
+  const href = hrefFor ?? ((p) => `/blog/${p.slug}`);
+  return /* @__PURE__ */ jsxRuntime.jsxs("ul", { className: ["lvlz-list", className].filter(Boolean).join(" "), children: [
+    styled ? /* @__PURE__ */ jsxRuntime.jsx(LvlzStyles, {}) : null,
+    posts.map((post) => /* @__PURE__ */ jsxRuntime.jsx("li", { className: "lvlz-card", children: renderItem ? renderItem(post) : /* @__PURE__ */ jsxRuntime.jsxs("a", { href: href(post), children: [
+      post.coverImage ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: "lvlz-card-thumb", children: /* @__PURE__ */ jsxRuntime.jsx("img", { src: post.coverImage, alt: post.title, loading: "lazy" }) }) : null,
+      /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "lvlz-card-body", children: [
+        /* @__PURE__ */ jsxRuntime.jsx("h3", { className: "lvlz-card-title", children: post.title }),
+        post.excerpt ? /* @__PURE__ */ jsxRuntime.jsx("p", { className: "lvlz-card-excerpt", children: post.excerpt }) : null
+      ] })
+    ] }) }, post.id))
+  ] });
+}
+
+exports.LvlzArticle = LvlzArticle;
+exports.LvlzPostList = LvlzPostList;
+exports.LvlzStyles = LvlzStyles;

package/dist/react.d.cts

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import { PublicPost } from './index.cjs';
+
+/** Inject the default LVLZ styles once. Safe to render multiple times. */
+declare function LvlzStyles(): React.JSX.Element;
+interface LvlzArticleProps {
+    post: PublicPost;
+    className?: string;
+    /** Render the BlogPosting JSON-LD <script>. Default true. */
+    includeJsonLd?: boolean;
+    /** Render the cover image hero. Default true. */
+    showCover?: boolean;
+    /** Render the post title as an <h1>. Default true. */
+    showTitle?: boolean;
+    /** Inject default styling. Set false to bring your own CSS. Default true. */
+    styled?: boolean;
+}
+/** A full, polished article: cover hero + title + HTML body (inline images included). */
+declare function LvlzArticle({ post, className, includeJsonLd, showCover, showTitle, styled, }: LvlzArticleProps): React.JSX.Element;
+interface LvlzPostListProps {
+    posts: PublicPost[];
+    className?: string;
+    /** Build the href for a post. Default: `/blog/{slug}`. */
+    hrefFor?: (post: PublicPost) => string;
+    /** Custom item renderer; overrides the default card. */
+    renderItem?: (post: PublicPost) => React.ReactNode;
+    /** Inject default styling. Default true. */
+    styled?: boolean;
+}
+/** A responsive grid of post cards with cover thumbnails. */
+declare function LvlzPostList({ posts, className, hrefFor, renderItem, styled, }: LvlzPostListProps): React.JSX.Element;
+
+export { LvlzArticle, type LvlzArticleProps, LvlzPostList, type LvlzPostListProps, LvlzStyles };

package/dist/react.d.ts

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import { PublicPost } from './index.js';
+
+/** Inject the default LVLZ styles once. Safe to render multiple times. */
+declare function LvlzStyles(): React.JSX.Element;
+interface LvlzArticleProps {
+    post: PublicPost;
+    className?: string;
+    /** Render the BlogPosting JSON-LD <script>. Default true. */
+    includeJsonLd?: boolean;
+    /** Render the cover image hero. Default true. */
+    showCover?: boolean;
+    /** Render the post title as an <h1>. Default true. */
+    showTitle?: boolean;
+    /** Inject default styling. Set false to bring your own CSS. Default true. */
+    styled?: boolean;
+}
+/** A full, polished article: cover hero + title + HTML body (inline images included). */
+declare function LvlzArticle({ post, className, includeJsonLd, showCover, showTitle, styled, }: LvlzArticleProps): React.JSX.Element;
+interface LvlzPostListProps {
+    posts: PublicPost[];
+    className?: string;
+    /** Build the href for a post. Default: `/blog/{slug}`. */
+    hrefFor?: (post: PublicPost) => string;
+    /** Custom item renderer; overrides the default card. */
+    renderItem?: (post: PublicPost) => React.ReactNode;
+    /** Inject default styling. Default true. */
+    styled?: boolean;
+}
+/** A responsive grid of post cards with cover thumbnails. */
+declare function LvlzPostList({ posts, className, hrefFor, renderItem, styled, }: LvlzPostListProps): React.JSX.Element;
+
+export { LvlzArticle, type LvlzArticleProps, LvlzPostList, type LvlzPostListProps, LvlzStyles };

package/dist/react.js

@@ -0,0 +1,74 @@
+import { jsx, jsxs } from 'react/jsx-runtime';
+
+// src/react.tsx
+var STYLE_TAG_ID = "lvlz-sdk-styles";
+var CSS = `
+.lvlz-article{max-width:768px;margin:0 auto;color:inherit}
+.lvlz-cover{width:100%;aspect-ratio:16/9;border-radius:16px;overflow:hidden;margin:0 0 2rem;background:#f3f3f5}
+.lvlz-cover img{width:100%;height:100%;object-fit:cover;display:block}
+.lvlz-title{font-size:2.25rem;font-weight:780;line-height:1.15;margin:0 0 1.25rem;letter-spacing:-.02em}
+.lvlz-prose{line-height:1.75;font-size:1.05rem}
+.lvlz-prose h2{font-size:1.6rem;font-weight:720;margin:2.2rem 0 .8rem;line-height:1.25;letter-spacing:-.01em}
+.lvlz-prose h3{font-size:1.25rem;font-weight:680;margin:1.6rem 0 .6rem}
+.lvlz-prose p{margin:0 0 1.1rem}
+.lvlz-prose a{color:#7c3aed;text-decoration:underline;text-underline-offset:2px}
+.lvlz-prose ul,.lvlz-prose ol{margin:0 0 1.1rem 1.25rem}
+.lvlz-prose li{margin:.35rem 0}
+.lvlz-prose blockquote{border-left:3px solid #7c3aed;padding-left:1rem;margin:1.4rem 0;color:#555;font-style:italic}
+.lvlz-prose img{width:100%;height:auto;border-radius:12px;margin:1.6rem 0;display:block}
+.lvlz-list{display:grid;gap:1.5rem;grid-template-columns:repeat(auto-fill,minmax(280px,1fr));list-style:none;padding:0;margin:0}
+.lvlz-card{overflow:hidden;border-radius:14px;border:1px solid rgba(0,0,0,.08);background:#fff;transition:transform .15s ease,box-shadow .15s ease}
+.lvlz-card:hover{transform:translateY(-2px);box-shadow:0 10px 30px rgba(0,0,0,.08)}
+.lvlz-card a{text-decoration:none;color:inherit;display:flex;flex-direction:column;height:100%}
+.lvlz-card-thumb{aspect-ratio:16/9;overflow:hidden;background:#f3f3f5}
+.lvlz-card-thumb img{width:100%;height:100%;object-fit:cover;display:block;transition:transform .3s ease}
+.lvlz-card:hover .lvlz-card-thumb img{transform:scale(1.04)}
+.lvlz-card-body{padding:1rem 1.1rem 1.2rem}
+.lvlz-card-title{font-size:1.05rem;font-weight:680;margin:0 0 .4rem;line-height:1.3}
+.lvlz-card-excerpt{font-size:.9rem;color:#666;margin:0;line-height:1.5}
+@media (prefers-color-scheme:dark){
+.lvlz-card{background:#15151a;border-color:rgba(255,255,255,.1)}
+.lvlz-card-excerpt{color:#a1a1aa}
+.lvlz-prose blockquote{color:#a1a1aa}
+}
+`;
+function LvlzStyles() {
+  return /* @__PURE__ */ jsx("style", { id: STYLE_TAG_ID, dangerouslySetInnerHTML: { __html: CSS } });
+}
+function LvlzArticle({
+  post,
+  className,
+  includeJsonLd = true,
+  showCover = true,
+  showTitle = true,
+  styled = true
+}) {
+  return /* @__PURE__ */ jsxs("article", { className: ["lvlz-article", className].filter(Boolean).join(" "), children: [
+    styled ? /* @__PURE__ */ jsx(LvlzStyles, {}) : null,
+    includeJsonLd && post.jsonLd ? /* @__PURE__ */ jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: post.jsonLd } }) : null,
+    showCover && post.coverImage ? /* @__PURE__ */ jsx("figure", { className: "lvlz-cover", children: /* @__PURE__ */ jsx("img", { src: post.coverImage, alt: post.title, loading: "eager" }) }) : null,
+    showTitle ? /* @__PURE__ */ jsx("h1", { className: "lvlz-title", children: post.title }) : null,
+    /* @__PURE__ */ jsx("div", { className: "lvlz-prose", dangerouslySetInnerHTML: { __html: post.html } })
+  ] });
+}
+function LvlzPostList({
+  posts,
+  className,
+  hrefFor,
+  renderItem,
+  styled = true
+}) {
+  const href = hrefFor ?? ((p) => `/blog/${p.slug}`);
+  return /* @__PURE__ */ jsxs("ul", { className: ["lvlz-list", className].filter(Boolean).join(" "), children: [
+    styled ? /* @__PURE__ */ jsx(LvlzStyles, {}) : null,
+    posts.map((post) => /* @__PURE__ */ jsx("li", { className: "lvlz-card", children: renderItem ? renderItem(post) : /* @__PURE__ */ jsxs("a", { href: href(post), children: [
+      post.coverImage ? /* @__PURE__ */ jsx("div", { className: "lvlz-card-thumb", children: /* @__PURE__ */ jsx("img", { src: post.coverImage, alt: post.title, loading: "lazy" }) }) : null,
+      /* @__PURE__ */ jsxs("div", { className: "lvlz-card-body", children: [
+        /* @__PURE__ */ jsx("h3", { className: "lvlz-card-title", children: post.title }),
+        post.excerpt ? /* @__PURE__ */ jsx("p", { className: "lvlz-card-excerpt", children: post.excerpt }) : null
+      ] })
+    ] }) }, post.id))
+  ] });
+}
+
+export { LvlzArticle, LvlzPostList, LvlzStyles };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lvlz/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Fetch and render your LVLZ.ai published posts on any site (Next.js, React, Vite, plain HTML).",
   "license": "MIT",
   "type": "module",
@@ -23,7 +23,10 @@
   "sideEffects": false,
   "scripts": {
     "build": "tsup",
-    "dev": "tsup --watch"
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build",
+    "prepack": "npm run build",
+    "verify-pack": "npm pack --dry-run 2>&1 | grep -q 'dist/index.js' || (echo 'ERROR: dist/index.js missing from package — run npm run build' && exit 1)"
   },
   "keywords": ["seo", "geo", "blog", "headless", "cms", "lvlz"],
   "peerDependencies": {