# @pengraph/node

> Official Node.js SDK for PenGraph — pull AI-generated SEO blog posts into Next.js and Node apps via the Site API

Latest version **0.1.1** (published 2026-09-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install @pengraph/node
pnpm add @pengraph/node
yarn add @pengraph/node
bun add @pengraph/node
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2026-09-24 |
| First published | 2026-09-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 0 |
| Unpacked size | 13.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | PenGraph |
| Maintainers | bazzscript |
| Keywords | pengraph, seo, blog, cms, headless-cms, content-api, nextjs, nodejs, typescript, api-client, ai-content |

## Links

- npm: https://www.npmjs.com/package/@pengraph/node
- Repository: https://github.com/bonaventureugome-maker/Seoautomation
- Homepage: https://www.npmjs.com/package/@pengraph/node
- Issues: https://github.com/bonaventureugome-maker/Seoautomation/issues
- npm.io page: https://npm.io/package/@pengraph/node

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 0.1.1 (latest) — 2026-09-24
- 0.1.0 — 2026-09-24

## README

# @pengraph/node

[![npm version](https://img.shields.io/npm/v/@pengraph/node.svg)](https://www.npmjs.com/package/@pengraph/node)
[![license](https://img.shields.io/npm/l/@pengraph/node.svg)](https://www.npmjs.com/package/@pengraph/node)
[![node](https://img.shields.io/node/v/@pengraph/node.svg)](https://www.npmjs.com/package/@pengraph/node)

**Official Node.js / Next.js SDK** for the [PenGraph](https://github.com/bonaventureugome-maker/Seoautomation) Site API.

Pull **published** blog posts from PenGraph into your own website, storefront, or CMS — with typed helpers and zero runtime dependencies.

---

## What is PenGraph?

**PenGraph** is an AI-powered SEO blog platform. You generate, review, and publish posts in PenGraph; your live site **pulls** them over a secure API (no webhook required for the default flow).

Typical stack:

1. Write / generate content in the PenGraph dashboard  
2. Publish when ready  
3. Your Next.js (or any Node) app fetches posts with `@pengraph/node`  
4. You render them on your domain for SEO and branding  

WordPress and Shopify plugins are planned; they will use the **same** Site API.

---

## What this package does

| Method | Purpose |
|--------|---------|
| `getPosts()` | List published posts (paginated) |
| `getPostBySlug(slug)` | Fetch one published post by URL slug |

Returns title, slug, markdown, **`content_html`**, SEO/Open Graph fields, tags, and timestamps — ready for Server Components or API routes.

**Not included:** browser / client-side usage with a secret key. Always call from the **server**.

---

## Documentation

| Resource | Link |
|----------|------|
| **npm** | https://www.npmjs.com/package/@pengraph/node |
| **Node.js guide** | On your PenGraph host: `/docs/nodejs` |
| **HTTP API** | `/docs/api` |
| **OpenAPI 3.1** | `GET /api/v1/openapi` on your PenGraph host |
| **Source** | [packages/pengraph-node](https://github.com/bonaventureugome-maker/Seoautomation/tree/staging/packages/pengraph-node) |
| **Site API (markdown)** | [docs/SITE-API.md](https://github.com/bonaventureugome-maker/Seoautomation/blob/staging/docs/SITE-API.md) |

Create API keys in PenGraph: **Settings → Integrations → Site API**.

---

## Install

```bash
npm install @pengraph/node
```

```bash
yarn add @pengraph/node
pnpm add @pengraph/node
```

---

## Requirements & dependencies

### Runtime

| Requirement | Notes |
|-------------|--------|
| **Node.js ≥ 18** | Uses global `fetch` (no polyfill shipped) |
| **HTTPS / HTTP** | Your PenGraph `baseUrl` |

### npm dependencies

| Kind | Packages |
|------|----------|
| **Runtime (`dependencies`)** | **None** — zero production deps |
| **Dev (`devDependencies`)** | `typescript` (build only; not installed by consumers) |
| **Peer dependencies** | **None** — works with Next.js, Nuxt, Express, plain Node, etc. |

You do **not** need to install Anthropic, Supabase, or other PenGraph server packages in your blog app — only this client + your env vars.

---

## Quick start

```ts
import { createPenGraphClient } from "@pengraph/node";

const client = createPenGraphClient({
  baseUrl: process.env.PENGRAPH_BASE_URL!, // e.g. https://your-pengraph.app
  siteId: process.env.PENGRAPH_SITE_ID!,   // site UUID
  apiKey: process.env.PENGRAPH_API_KEY!,   // pg_live_…
});

const { posts, pagination } = await client.getPosts({ limit: 20 });
const post = await client.getPostBySlug("how-to-get-started-with-seo");

// Prefer HTML for display
// post?.content_html
```

### Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PENGRAPH_BASE_URL` | Yes | Origin of your PenGraph deployment |
| `PENGRAPH_SITE_ID` | Yes | Site UUID from the dashboard |
| `PENGRAPH_API_KEY` | Yes | Site API key (`pg_live_…`) |

Never expose `PENGRAPH_API_KEY` as `NEXT_PUBLIC_*` or ship it to the browser.

### Next.js App Router

```tsx
import { createPenGraphClient } from "@pengraph/node";

export const dynamic = "force-dynamic";

export default async function BlogPage() {
  const client = createPenGraphClient({
    baseUrl: process.env.PENGRAPH_BASE_URL!,
    siteId: process.env.PENGRAPH_SITE_ID!,
    apiKey: process.env.PENGRAPH_API_KEY!,
  });
  const { posts } = await client.getPosts();

  return (
    <ul>
      {posts.map((p) => (
        <li key={p.id}>
          <a href={`/blog/${p.slug}`}>{p.title}</a>
        </li>
      ))}
    </ul>
  );
}
```

```tsx
// app/blog/[slug]/page.tsx
import { notFound } from "next/navigation";
import { createPenGraphClient } from "@pengraph/node";

export default async function PostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const client = createPenGraphClient({
    baseUrl: process.env.PENGRAPH_BASE_URL!,
    siteId: process.env.PENGRAPH_SITE_ID!,
    apiKey: process.env.PENGRAPH_API_KEY!,
  });
  const post = await client.getPostBySlug(slug);
  if (!post) notFound();

  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content_html || "" }} />
    </article>
  );
}
```

---

## API surface

### `createPenGraphClient(options)` / `new PenGraphClient(options)`

```ts
type PenGraphClientOptions = {
  baseUrl: string;
  siteId: string;
  apiKey: string;
  fetch?: typeof fetch; // optional override
};
```

### `client.getPosts(options?)`

```ts
{ limit?: number; offset?: number; since?: string }
// → { posts: PenGraphPost[]; pagination: { limit; offset; total } }
```

### `client.getPostBySlug(slug)`

Returns `PenGraphPost | null` (`null` on 404).

### Errors

Failed responses throw `PenGraphError` with `status` and `body`.

---

## Security

- Use **server-side only** (Route Handlers, Server Components, workers).  
- Keys are scoped to one site; rotate/revoke in PenGraph Settings.  
- Prefer `content_html` for rendering; sanitize if you have a strict CSP policy.

---

## Changelog

See [CHANGELOG.md](./CHANGELOG.md).

---

## License

MIT © PenGraph

---
_Source: https://npm.io/package/@pengraph/node · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._