npm package: @siteproof/sdk
Description: Core SDK for SiteProof visual editor integration — config, content fetching, editor detection, and PostMessage bridge
Author: Phoenix AI Consulting, LLC
Latest version: 0.1.0

# @siteproof/sdk

Core SDK for [SiteProof](https://siteproof.dev) visual editor integration. Provides configuration, content fetching, editor detection, and the PostMessage bridge for iframe communication.

## Installation

```bash
npm install @siteproof/sdk @siteproof/react
```

## Quick Start

### 1. Create a config file

Create `siteproof.config.ts` in your project root:

```ts
import { defineConfig } from '@siteproof/sdk';

export default defineConfig({
  projectId: 'your-project-id',
  editorOrigin: process.env.NEXT_PUBLIC_SITEPROOF_URL ?? 'https://app.siteproof.dev',
});
```

### 2. Import the config in your root layout

```tsx
// app/layout.tsx
import '../siteproof.config';
import { SiteProofProvider } from '@siteproof/react';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <SiteProofProvider>{children}</SiteProofProvider>
      </body>
    </html>
  );
}
```

### 3. Wrap editable content

```tsx
import { Editable } from '@siteproof/react';

export function Hero() {
  return (
    <section>
      <Editable field="home.hero.title" type="text" label="Hero Title">
        <h1>Welcome to our site</h1>
      </Editable>
      <Editable field="home.hero.subtitle" type="text" label="Subtitle">
        <p>The best platform for modern teams.</p>
      </Editable>
    </section>
  );
}
```

## How It Works

- **Production mode**: The SDK is completely inert. `<SiteProofProvider>` and `<Editable>` render children as-is with zero runtime overhead.
- **Editor mode**: When loaded inside SiteProof's visual editor iframe, the SDK activates automatically. It detects the editor environment, completes a PostMessage handshake, registers all `<Editable>` fields, and enables inline editing.

## API Reference

### `defineConfig(config)`

Initialize the SDK with your project settings.

```ts
defineConfig({
  projectId: string;       // Your SiteProof project ID
  payloadUrl?: string;     // Payload CMS URL (optional)
  payloadApiKey?: string;  // Payload API key (optional)
  editorOrigin?: string;   // SiteProof editor URL (default: https://app.siteproof.dev)
})
```

### `isEditMode()`

Returns `true` when the site is loaded inside SiteProof's visual editor.

### Content Fetching

```ts
import { getContent, getContentById, getCollectionItems } from '@siteproof/sdk';

// Fetch first document from a collection
const page = await getContent<PageData>('pages');

// Fetch by ID
const post = await getContentById<Post>('posts', 'abc123');

// Fetch collection with filtering and pagination
const posts = await getCollectionItems<Post>('posts', {
  where: { status: { equals: 'published' } },
  limit: 10,
  sort: '-createdAt',
});
```

### `PostMessageBridge`

Low-level class for iframe communication. Used internally by `@siteproof/react`.

### `SiteProofClient`

HTTP client for the SiteProof platform API. Used internally.

## Requirements

- Next.js 14+ (App Router or Pages Router)
- React 18+
- TypeScript recommended

## License

MIT - Phoenix AI Consulting, LLC