npm package: @planoly/planogram-config
Description: Centralized configuration for Planoly post experience across all platforms
Author: Planoly
Latest version: 1.1.2

# @planoly/planogram-config

Centralized configuration for the Planoly post experience across all platforms.

## Overview

This package provides a single source of truth for platform configurations, validation rules, and UI settings used across all Planoly clients (iOS, Android, Web, Backend).

## Installation

```bash
npm install @planoly/planogram-config
```

## Usage

### TypeScript / JavaScript

```typescript
import { postExperienceConfig, Platform, PostType, Validation } from '@planoly/planogram-config';

// Get enabled platforms
const enabledPlatforms = postExperienceConfig.platforms.filter(p => p.enabled);

// Find Instagram config
const instagram = postExperienceConfig.platforms.find(p => p.name === 'instagram');

// Get Grid Post validations
const gridPost = instagram?.postTypes.find(pt => pt.name === 'Grid Post');
const captionRule = gridPost?.validations.find(v => v.type === 'autoPostCaptionLength');
console.log(`Max caption: ${captionRule?.parameters?.max} characters`);
```

### Default Import

```typescript
import postExperienceConfig from '@planoly/planogram-config';
```

### Raw JSON Access

If you need the raw JSON file directly:

```typescript
import config from '@planoly/planogram-config/json';
```

## Exported Types

| Type | Description |
|------|-------------|
| `PostExperienceConfig` | Root configuration object |
| `Platform` | Single platform configuration (Instagram, TikTok, etc.) |
| `PostType` | Post type within a platform (Grid Post, Reel, Story, etc.) |
| `Validation` | Validation rule for a post type |
| `VisibilityOption` | Visibility option (for YouTube: public, unlisted, private) |
| `Information` | Tooltip/informational message for a post type |
| `PlatformName` | Union type of all platform names |
| `PlatformId` | Union type of all platform IDs |
| `ValidationType` | Union type of all validation types |

## iOS / Swift

iOS clients should continue using the git submodule approach and read `postExperienceConfig.json` directly

## Configuration Structure

```
postExperienceConfig
├── version: string
└── platforms: Platform[]
    ├── name: string (e.g., "instagram", "tiktok")
    ├── id: number
    ├── enabled: boolean
    ├── order: number
    ├── isBeta: boolean
    └── postTypes: PostType[]
        ├── name: string (e.g., "Grid Post", "Reel", "Story")
        ├── allowAutoPost: boolean
        ├── allowFirstComment: boolean
        ├── allowedMediaTypes: string[]
        ├── allowCanva: boolean
        ├── canvaDesignType: string
        ├── validations: Validation[]
        │   ├── type: string
        │   ├── userErrorMessage: string
        │   ├── errorHelpLink?: string
        │   └── parameters?: object
        └── information?: Information[]
```

## Making Changes

### For Config Updates

1. Edit `postExperienceConfig.json`
2. Create a PR and get review
3. Merge to main
4. Create a release (see below)

### Creating a Release

Use `npm version` to bump versions - it automatically keeps `package.json` and `postExperienceConfig.json` in sync:

```bash
# Bump version (choose one)
npm version patch   # 1.0.0 → 1.0.1 (bug fixes, typos)
npm version minor   # 1.0.0 → 1.1.0 (new platforms, features)
npm version major   # 1.0.0 → 2.0.0 (breaking changes)

# Or set explicit version
npm version 1.2.3

# Push changes and tag
git push origin main --tags
```

This will:
1. Update `package.json` version
2. Run `scripts/sync-version.cjs` → syncs `postExperienceConfig.json`
3. Commit both files
4. Create git tag (e.g., `v1.2.3`)

The Bitbucket pipeline then auto-publishes to npm when it sees the tag.

### Versioning Guidelines

Follow [semver](https://semver.org/):
- **Patch** (`1.0.x`): Bug fixes, typo corrections in messages
- **Minor** (`1.x.0`): New platforms, new post types, new validation rules
- **Major** (`x.0.0`): Breaking changes to config structure

## Development

### Building Locally

```bash
npm install
npm run build
```

### Testing the Package

```bash
# Create a tarball
npm pack

# In another project, install the tarball
npm install /path/to/planoly-planogram-config-1.0.0.tgz
```

## Repository Variables Required

For CI/CD to work, add these to Bitbucket repository settings:

| Variable | Description |
|----------|-------------|
| `NPM_TOKEN` | npm access token with publish permissions |

### ⚠️ NPM Token Expiration

**Important:** npm tokens with write access now expire after **90 days**. 

Set a calendar reminder to rotate the token before expiration:
1. Generate a new token at https://www.npmjs.com → Account → Access Tokens
2. Update the `NPM_TOKEN` repository variable in Bitbucket
3. Delete the old token from npm

@planoly organization created on npm by David H - eventually need to transfer org to more official account

## License

MIT