# @brixon/presentation-sdk v0.0.1

SDK for building B2B presentations that deploy to the Brixon platform.
Primary user: Claude Code. Secondary user: Human developers.

## Install

```bash
npm install @brixon/presentation-sdk
```

Peer deps: react@^18 || ^19, react-dom@^18 || ^19

## CLI

```bash
brixon init [name]        # Create presentation project
  -f, --force             # Overwrite existing directory

brixon build              # Build for deployment
  -o, --outDir <dir>      # Output directory (default: dist)
  -c, --config <path>     # Config file path

brixon dev                # Show dev workflow guidance
  -p, --port <port>       # Port number (default: 3000)

brixon deploy             # Deploy to Brixon platform
  -k, --api-key <key>     # API key (or BRIXON_API_KEY env)
  -e, --endpoint <url>    # Upload endpoint
  --dry-run               # Preview without uploading
```

## Exports

```typescript
// Main exports
import {
  PresentationWrapper,
  Hero,
  Content,
  CTA,
  Section,
  cn,
  useTracking,
  defineConfig,
} from '@brixon/presentation-sdk'

// Subpath exports
import { PresentationWrapper } from '@brixon/presentation-sdk/components'
import { useTracking } from '@brixon/presentation-sdk/hooks'
import { defineConfig } from '@brixon/presentation-sdk/config'
```

## Types

```typescript
interface SectionConfig {
  id: string           // Unique section ID
  label: string        // Display label for analytics
  order: number        // Order in presentation
  type: 'hero' | 'content' | 'cta' | 'feature' | 'testimonial' | 'pricing'
}

interface BrixonConfig {
  presentation: {
    slug: string       // URL slug
    title: string      // Display title
    subtitle?: string
    clientName?: string
  }
  build?: {
    outDir?: string    // Default: 'dist'
    minify?: boolean   // Default: true
  }
  dev?: {
    port?: number      // Default: 3000
  }
}
```

## Components

### PresentationWrapper
Root layout. Required.

```tsx
<PresentationWrapper
  title: string           // Required. Page title
  sections: SectionConfig[] // Required. For navigation
  children: ReactNode     // Required. Presentation content
/>
```

### Hero
Full-screen title section.

```tsx
<Hero
  title: string           // Required. Main headline
  subtitle?: string       // Tagline
  clientName?: string     // Client company name
  year?: string           // Year display
/>
```

### Content
General content section.

```tsx
<Content
  id: string              // Required. Section ID
  label: string           // Required. Analytics label
  headline: string        // Required. Section heading
  description?: string    // Body text
  children?: ReactNode    // Additional content
/>
```

### CTA
Call-to-action section.

```tsx
<CTA
  headline: string        // Required. CTA heading
  subline?: string        // Supporting text
  buttonText: string      // Required. Button label
  buttonHref: string      // Required. Button link
/>
```

### Section
Generic trackable section wrapper.

```tsx
<Section
  id: string              // Required. Section ID
  label: string           // Required. Analytics label
  type?: SectionConfig['type'] // Default: 'content'
  children: ReactNode     // Required. Section content
/>
```

## Hooks

### useTracking
Analytics tracking hook.

```tsx
const { trackEngagement } = useTracking({
  presentationId: string,    // Required. Presentation ID
  sections: SectionConfig[], // Required. Section list
  endpoint?: string,         // API endpoint (default: /api/analytics/track)
})

// Manual tracking
trackEngagement(eventName: string, data?: Record<string, unknown>)
```

## Config File

brixon.config.ts:

```typescript
import { defineConfig } from '@brixon/presentation-sdk'

export default defineConfig({
  presentation: {
    slug: 'my-presentation',
    title: 'My Presentation',
  },
})
```

## Project Structure

```
my-presentation/
├── src/
│   └── presentation.tsx   # Main component
├── public/                # Static assets
├── brixon.config.ts       # Configuration
├── package.json
├── tsconfig.json
└── CLAUDE.md              # AI context
```

## Patterns

### Add new section
1. Add to sections array with unique id, label, order, type
2. Add component in PresentationWrapper children
3. Use matching id in component's id prop

### Change content
Edit props on Hero, Content, CTA components directly.

### Add custom section
Use Section wrapper with id and label:
```tsx
<Section id="custom" label="Custom">
  <div>Custom content</div>
</Section>
```

### Build and deploy
```bash
npm run build    # Creates dist/
npm run dev      # Shows Next.js workflow
npm run deploy   # Deploy to platform
```

## CI/CD

GitHub Actions workflow auto-deploys on push to main.

Setup:
1. Add BRIXON_API_KEY to repo secrets
2. Push to main branch
3. Presentation deploys automatically

Workflow location: `.github/workflows/deploy.yml`

## Claude Code Integration

The Brixon platform integrates with Claude Code via slash commands for automated workflows.

### Available Commands

| Command | Description |
|---------|-------------|
| `/brixon:list` | List all presentations for your tenant |
| `/brixon:register <slug>` | Register a new presentation |
| `/brixon:deploy [slug]` | Build and deploy presentation |
| `/brixon:status [slug]` | Check deployment status |
| `/brixon:analytics [slug]` | View presentation analytics |

### Setup

1. Get your API key from the Brixon dashboard (Settings > API Keys)
2. Set the environment variable:
   ```bash
   export BRIXON_API_KEY=bri_your_key_here
   ```
3. Use slash commands in Claude Code

### Example Workflow

```bash
# Start new presentation project
npx @brixon/presentation-sdk init acme-proposal

# Register in platform
/brixon:register acme-proposal

# Build and deploy
/brixon:deploy

# Check status
/brixon:status

# View analytics after sharing
/brixon:analytics --days=7
```

### V1 REST API

For programmatic access, use the V1 REST API:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/presentations` | GET | List presentations |
| `/api/v1/presentations` | POST | Register presentation |
| `/api/v1/presentations/{slug}` | GET | Get presentation |
| `/api/v1/presentations/{slug}` | PATCH | Update presentation |
| `/api/v1/presentations/{slug}/deploy` | POST | Deploy presentation |
| `/api/v1/presentations/{slug}/analytics` | GET | Get analytics |

All endpoints require `x-api-key` header with a valid API key.

### API Key Scopes

| Scope | Allows |
|-------|--------|
| `read` | List, get, analytics endpoints |
| `write` | Register, update endpoints |
| `upload` | Deploy endpoint |
| `*` | All operations |