npm package: @postpal/cli
Description: PostPal is an AI-powered social media content creation, scheduling, and publishing platform built with Next.js 16, React 19, and Supabase.
Latest version: 0.1.1

PostPal is an AI-powered social media content creation, scheduling, and publishing platform built with Next.js 16, React 19, and Supabase.

## Agent Platform

PostPal includes a production-oriented external integration layer for Codex, Claude, and other AI agents:

- Versioned HTTP API at `/api/v1`
- API-key auth for external integrations
- Official Node CLI: `postpal`
- MCP stdio bridge via `postpal mcp serve`
- Webhook callbacks for run and publish events

### Quickstart

1. Start PostPal locally:

```bash
npm install
npm run dev
```

2. Create an API key from an authenticated PostPal session:

```bash
curl -X POST http://localhost:3000/api/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-postpal-session-bearer-token>" \
  -d '{"name":"Local agent key"}'
```

3. Save the key for the CLI in the current workspace:

```bash
node scripts/postpal-cli.mjs auth login-key \
  --api-key ppk_live_your_postpal_api_key \
  --api-base-url http://localhost:3000
```

4. Verify access:

```bash
node scripts/postpal-cli.mjs brands list --json
node scripts/postpal-cli.mjs accounts list --json
```

### CLI

```bash
node scripts/postpal-cli.mjs auth login-key --api-key <key> --api-base-url http://localhost:3000
node scripts/postpal-cli.mjs brands list --json
node scripts/postpal-cli.mjs pals list --json
node scripts/postpal-cli.mjs accounts list --platform twitter --json
node scripts/postpal-cli.mjs content generate --file payload.json --json
node scripts/postpal-cli.mjs drafts create --file payload.json --json
node scripts/postpal-cli.mjs drafts list --json
node scripts/postpal-cli.mjs drafts get --id <draft-id> --json
node scripts/postpal-cli.mjs schedules create --file payload.json --json
node scripts/postpal-cli.mjs publishes create --file payload.json --json
node scripts/postpal-cli.mjs runs get --id <run-id> --json
node scripts/postpal-cli.mjs webhook endpoints list --json
node scripts/postpal-cli.mjs webhook endpoints create --file payload.json --json
node scripts/postpal-cli.mjs mcp serve
```

### API Endpoints

- `GET /api/v1/health`
- `GET /api/v1/brands`
- `GET /api/v1/pals`
- `GET /api/v1/accounts`
- `POST /api/v1/content/generate`
- `GET /api/v1/drafts`
- `GET /api/v1/drafts/:id`
- `POST /api/v1/drafts`
- `POST /api/v1/schedules`
- `POST /api/v1/publishes`
- `GET /api/v1/runs/:id`
- `GET /api/v1/webhooks`
- `POST /api/v1/webhooks`
- `GET /api/v1/openapi`

All `/api/v1` endpoints expect:

- `Authorization: Bearer ppk_live_...`
- JSON bodies for write requests
- Optional `Idempotency-Key` for safe retries

Success responses use `{ data, meta? }`. Errors use `{ error: { code, message, details?, request_id } }`.

### Example: Generate Drafts

```bash
curl -X POST http://localhost:3000/api/v1/content/generate \
  -H "Authorization: Bearer ppk_live_your_postpal_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-001" \
  -d '{
    "topic": "Launch our new analytics dashboard",
    "brand_id": "your-brand-id",
    "platforms": ["twitter", "linkedin", "facebook"],
    "platform_settings": {
      "twitter": "short",
      "linkedin": "medium",
      "facebook": "medium"
    },
    "persist_drafts": true
  }'
```

### Example: MCP

For Claude or Codex, register a stdio MCP server that runs:

```json
{
  "mcpServers": {
    "postpal": {
      "command": "node",
      "args": ["scripts/postpal-cli.mjs", "mcp", "serve"]
    }
  }
}
```

### Webhooks

Create webhook endpoints with `POST /api/v1/webhooks`. Deliveries are signed with:

- `X-PostPal-Event`
- `X-PostPal-Timestamp`
- `X-PostPal-Signature`

The signature is an HMAC SHA-256 over `timestamp + "." + rawBody` using the endpoint signing secret.

Full web docs: `/docs/ai-agent-integrations`

## Getting Started

First, run the development server:

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.

You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.

This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.

## Learn More

To learn more about Next.js, take a look at the following resources:

- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.

You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!

## Deploy on Vercel

The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.

Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

## Utility Scripts

### Clean Up User Usage

Reset usage counters for a specific user. Useful for debugging, customer support, or testing.

```bash
# Reset by email
npm run cleanup-usage -- --email user@example.com

# Reset by user ID
npm run cleanup-usage -- --user-id abc-123

# Preview changes without applying them
npm run cleanup-usage -- --email user@example.com --dry-run

# Also reset the billing period to a fresh 30-day window
npm run cleanup-usage -- --email user@example.com --reset-period
```

Requires `NEXT_PUBLIC_SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` in your `.env` file.

## TikTok Integration

PostPal now supports TikTok integration for video publishing. To enable TikTok functionality:

### Environment Variables

Add the following environment variables to your `.env.local` file:

```bash
# TikTok API Configuration
TIKTOK_CLIENT_KEY=your_tiktok_client_key_here
TIKTOK_CLIENT_SECRET=your_tiktok_client_secret_here
TIKTOK_REDIRECT_URI=http://localhost:3000/api/tiktok/callback
```

### Setup Instructions

1. **Create a TikTok App**: Visit the [TikTok for Developers](https://developers.tiktok.com/) portal
2. **Register your app** and get your Client ID and Client Secret
3. **Configure OAuth Redirect URI** to match your `TIKTOK_REDIRECT_URI`
4. **Request necessary permissions** for video upload and publishing
5. **Add environment variables** to your project

### Features

- **Video Upload**: Upload and publish videos directly to TikTok
- **Content Management**: Schedule and manage TikTok content
- **Multi-Platform Publishing**: Publish the same content across multiple platforms
- **Analytics Integration**: Track performance across all connected platforms

### API Endpoints

- `GET /api/tiktok/auth` - Initiate TikTok OAuth flow
- `GET /api/tiktok/callback` - Handle OAuth callback
- `POST /api/tiktok/post` - Upload and publish videos

### Usage

1. Connect your TikTok account in the Connections page
2. Create content using the Content Creator
3. Select TikTok as a platform
4. Upload your video and add description
5. Publish directly to TikTok

### Limitations

- TikTok API requires special approval for video publishing
- Video files must be in MP4 format
- Maximum video duration and file size limits apply
- Some features may require additional permissions