@riverbankcms/sdk 0.7.0 → 0.7.3

package/dist/cli/init-docs/content/getting-started.md

@@ -0,0 +1,130 @@
+# Getting Started with RiverbankCMS SDK
+
+This site uses RiverbankCMS as a headless CMS. Content is managed through the SDK CLI.
+
+## Quick Setup
+
+### 1. Verify Environment Configuration
+
+Check `.env.local` has these variables:
+
+```bash
+# Local development
+RIVERBANK_LOCAL_SITE_ID=your-site-id
+RIVERBANK_LOCAL_DASHBOARD_URL=http://localhost:4000
+RIVERBANK_LOCAL_MGMT_API_KEY=bld_mgmt_sk_...
+
+# Production (optional)
+RIVERBANK_REMOTE_SITE_ID=your-site-id
+RIVERBANK_REMOTE_DASHBOARD_URL=https://your-dashboard.riverbankcms.com
+RIVERBANK_REMOTE_MGMT_API_KEY=bld_mgmt_sk_...
+```
+
+### 2. Pull Content
+
+Download current content from the CMS:
+
+```bash
+riverbankcms pull
+```
+
+This creates a `content/` directory with JSON files:
+
+```
+content/
+├── entries/
+│   └── [content-type].json
+├── pages/
+│   └── [page-identifier].json
+└── navigation.json
+```
+
+### 3. Make Changes
+
+Edit the JSON files directly, or use CLI commands:
+
+```bash
+# Create or update an entry
+riverbankcms entry upsert blog-post my-new-post --data '{"title": "New Post"}'
+
+# Create a page
+riverbankcms page upsert about --title "About Us" --path /about
+
+# Add a block to a page
+riverbankcms block upsert about hero-section --kind block.hero --data '{"heading": "About Us"}'
+```
+
+### 4. Push Changes
+
+Preview what would change:
+
+```bash
+riverbankcms push --dry-run
+```
+
+Apply changes to the CMS:
+
+```bash
+riverbankcms push
+```
+
+## Key Documentation
+
+| Document | Purpose |
+|----------|---------|
+| `cli-reference.md` | All CLI commands and options |
+| `content-management.md` | How content is structured |
+| `schema.md` | This site's content types and blocks (auto-generated) |
+| `block-types.md` | Available block types (auto-generated) |
+| `workflows/` | Step-by-step guides for common tasks |
+
+## Common Tasks
+
+| Task | Command |
+|------|---------|
+| Pull all content | `riverbankcms pull` |
+| Push changes | `riverbankcms push` |
+| Preview changes | `riverbankcms push --dry-run` |
+| Create a page | `riverbankcms page upsert <id> --title "..." --path /...` |
+| Add a block | `riverbankcms block upsert <page> <block-id> --kind ... --data '...'` |
+| Publish an entry | `riverbankcms entry publish <type> <id>` |
+| Publish a page | `riverbankcms page publish <id>` |
+| List entries | `riverbankcms entry list <type>` |
+| Get JSON output | Add `--json` to any command |
+
+## Configuration Files
+
+### riverbank.config.ts
+
+Main SDK configuration defining:
+
+- Site ID
+- Custom blocks
+- Block field extensions
+- Block field options
+- Content type definitions
+- Sync settings
+
+### content.config.ts (if present)
+
+Additional content configuration for scaffolding.
+
+## Working with Remote/Production
+
+Add `--remote` to target production instead of local:
+
+```bash
+# Pull from production
+riverbankcms pull --remote
+
+# Push to production (requires --yes for safety)
+riverbankcms push --remote --yes
+```
+
+**Safety note:** Remote push requires `--yes` flag to prevent accidental production changes.
+
+## Next Steps
+
+1. Read `cli-reference.md` for detailed command documentation
+2. Review `schema.md` to understand this site's content model
+3. Check `workflows/` for step-by-step guides

package/dist/cli/init-docs/content/site-workflows-readme.md

@@ -0,0 +1,96 @@
+# Site-Specific Workflows
+
+This directory is for workflows specific to this site. The core workflows in `../workflows/` cover generic SDK operations, while this folder is for site-specific procedures.
+
+## When to Add Site Workflows
+
+Add workflows here when you have:
+
+- **Site-specific content patterns** - e.g., "How to add a new product to the catalog"
+- **Custom block configurations** - e.g., "Setting up the featured posts carousel"
+- **Multi-step business processes** - e.g., "Publishing a campaign landing page"
+- **Integration procedures** - e.g., "Syncing content with the marketing site"
+
+## Creating a Workflow
+
+Create a markdown file following this structure:
+
+```markdown
+# Workflow: [Name]
+
+## Purpose
+
+What this workflow accomplishes and when to use it.
+
+## Prerequisites
+
+- Required access, tools, or setup
+- Any content that must exist first
+
+## Steps
+
+1. First step with command
+   ```bash
+   riverbankcms ...
+   ```
+
+2. Second step
+   ```bash
+   riverbankcms ...
+   ```
+
+## Verification
+
+How to confirm the workflow completed successfully.
+
+## Rollback (if applicable)
+
+How to undo the changes if needed.
+
+## Notes
+
+Any additional context or edge cases.
+```
+
+## Example Workflows
+
+### Site-specific content creation
+
+`create-product.md`:
+```markdown
+# Workflow: Create a Product
+
+## Purpose
+Add a new product to the catalog with all required fields.
+
+## Steps
+1. Create the product entry
+2. Add product images
+3. Link to category
+4. Publish
+```
+
+### Campaign or seasonal content
+
+`launch-campaign.md`:
+```markdown
+# Workflow: Launch Marketing Campaign
+
+## Purpose
+Create and publish a campaign landing page with all blocks.
+
+## Steps
+1. Create campaign page
+2. Add hero with campaign messaging
+3. Add product grid
+4. Add CTA section
+5. Preview and publish
+```
+
+## Best Practices
+
+- Keep workflows focused on one task
+- Include all commands needed (copy-pasteable)
+- Document site-specific field requirements
+- Reference the CLI reference for command details
+- Update workflows when the site schema changes

package/dist/cli/init-docs/content/workflow-add-block.md

@@ -0,0 +1,228 @@
+# Workflow: Add a Block
+
+This workflow guides you through adding a block to an existing page.
+
+## Prerequisites
+
+- Page already exists in the CMS
+- Latest content pulled: `riverbankcms pull`
+
+## Steps
+
+### 1. Check Available Block Types
+
+View built-in blocks in `block-types.md`. Common block kinds:
+
+| Kind | Description |
+|------|-------------|
+| `block.hero` | Hero sections with heading, subheading, image, CTA |
+| `block.bodyText` | Rich text content |
+| `block.image` | Image with caption |
+| `block.cta` | Call-to-action buttons |
+| `block.embed` | Embedded content (videos, iframes) |
+| `block.gallery` | Image gallery |
+| `block.quote` | Blockquote with attribution |
+
+Check `schema.md` for custom blocks specific to this site.
+
+### 2. List Existing Blocks
+
+See what blocks are already on the page:
+
+```bash
+riverbankcms block list <page-identifier>
+```
+
+**Example:**
+
+```bash
+riverbankcms block list home
+```
+
+### 3. Add the Block
+
+**Basic usage:**
+
+```bash
+riverbankcms block upsert <page-id> <block-id> --kind <block-kind> --data '<json>'
+```
+
+**Examples:**
+
+Add a hero block:
+
+```bash
+riverbankcms block upsert home main-hero \
+  --kind block.hero \
+  --data '{"heading": "Welcome", "subheading": "to our website"}'
+```
+
+Add a body text block:
+
+```bash
+riverbankcms block upsert home intro-content \
+  --kind block.bodyText \
+  --data '{"content": "<p>Welcome to our site. We offer...</p>"}'
+```
+
+Add an image block:
+
+```bash
+riverbankcms block upsert home feature-image \
+  --kind block.image \
+  --data '{"src": "/images/feature.jpg", "alt": "Feature image", "caption": "Our latest product"}'
+```
+
+Add a CTA block:
+
+```bash
+riverbankcms block upsert home main-cta \
+  --kind block.cta \
+  --data '{"text": "Get Started", "url": "/signup", "style": "primary"}'
+```
+
+### 4. Specify Position (Optional)
+
+Add the block at a specific position (0-indexed):
+
+```bash
+riverbankcms block upsert home new-section \
+  --kind block.bodyText \
+  --data '{"content": "<p>...</p>"}' \
+  --position 0
+```
+
+- `--position 0` places it first
+- `--position 1` places it second
+- Omitting position adds it at the end
+
+### 5. Preview the Block
+
+Preview how the block will render:
+
+```bash
+riverbankcms preview block.hero \
+  --data '{"heading": "Welcome", "subheading": "to our website"}' \
+  --open
+```
+
+### 6. Verify the Block
+
+Confirm the block was added:
+
+```bash
+riverbankcms block get home main-hero
+```
+
+List all blocks to see the order:
+
+```bash
+riverbankcms block list home
+```
+
+## Complex Block Content
+
+For blocks with nested or complex content, use a JSON file.
+
+### Example: Hero with Background and CTA
+
+**hero-content.json:**
+
+```json
+{
+  "heading": "Welcome to Our Platform",
+  "subheading": "Build amazing things with us",
+  "backgroundImage": {
+    "src": "/images/hero-bg.jpg",
+    "alt": "Abstract background"
+  },
+  "cta": {
+    "text": "Get Started",
+    "url": "/signup"
+  },
+  "alignment": "center"
+}
+```
+
+```bash
+riverbankcms block upsert home main-hero \
+  --kind block.hero \
+  --file ./hero-content.json
+```
+
+### Example: Gallery Block
+
+**gallery-content.json:**
+
+```json
+{
+  "title": "Our Work",
+  "images": [
+    { "src": "/images/project-1.jpg", "alt": "Project 1", "caption": "E-commerce redesign" },
+    { "src": "/images/project-2.jpg", "alt": "Project 2", "caption": "Mobile app" },
+    { "src": "/images/project-3.jpg", "alt": "Project 3", "caption": "Brand identity" }
+  ],
+  "layout": "grid"
+}
+```
+
+```bash
+riverbankcms block upsert home portfolio-gallery \
+  --kind block.gallery \
+  --file ./gallery-content.json
+```
+
+## Updating Existing Blocks
+
+To update a block, use the same `upsert` command with the same block ID:
+
+```bash
+riverbankcms block upsert home main-hero \
+  --kind block.hero \
+  --data '{"heading": "New Heading", "subheading": "Updated content"}'
+```
+
+The block is replaced with the new content.
+
+## Reordering Blocks
+
+Change the order of blocks on the page:
+
+```bash
+riverbankcms block reorder home main-hero intro-content feature-image main-cta
+```
+
+Blocks appear in the order listed.
+
+## Deleting Blocks
+
+Remove a block:
+
+```bash
+riverbankcms delete block home old-section --yes
+```
+
+## Troubleshooting
+
+### "Invalid block kind"
+
+- Check the kind matches exactly (e.g., `block.hero` not `hero`)
+- See `block-types.md` for valid system blocks
+- See `schema.md` for custom blocks (e.g., `custom.my-block`)
+
+### Block not rendering correctly
+
+- Verify the data structure matches what the block expects
+- Preview the block: `riverbankcms preview <kind> --data '...' --open`
+- Check for required fields in `block-types.md`
+
+### JSON parsing error
+
+- Ensure JSON is properly quoted in the shell
+- Use single quotes around the JSON string
+- For complex content, use `--file` instead of `--data`
+
+### Block at wrong position
+
+- Use `riverbankcms block reorder` to fix the order
+- Or delete and re-add with `--position`

package/dist/cli/init-docs/content/workflow-create-page.md

@@ -0,0 +1,193 @@
+# Workflow: Create a Page
+
+This workflow guides you through creating a new page in the CMS.
+
+## Prerequisites
+
+- SDK CLI installed (`@riverbankcms/sdk`)
+- Environment variables configured in `.env.local`
+- Latest content pulled: `riverbankcms pull`
+
+## Steps
+
+### 1. Create the Page
+
+```bash
+riverbankcms page upsert <identifier> \
+  --title "Page Title" \
+  --path /url-path \
+  --seo-title "SEO Title" \
+  --seo-description "Meta description for search engines"
+```
+
+**Example:**
+
+```bash
+riverbankcms page upsert contact \
+  --title "Contact Us" \
+  --path /contact \
+  --seo-title "Contact Us | Company Name" \
+  --seo-description "Get in touch with our team. We'd love to hear from you."
+```
+
+### 2. Add Blocks to the Page
+
+Add a hero block:
+
+```bash
+riverbankcms block upsert contact hero-section \
+  --kind block.hero \
+  --data '{"heading": "Contact Us", "subheading": "We would love to hear from you"}'
+```
+
+Add a body text block:
+
+```bash
+riverbankcms block upsert contact intro-text \
+  --kind block.bodyText \
+  --data '{"content": "<p>Reach out using the form below or email us directly.</p>"}'
+```
+
+Add more blocks as needed. See `block-types.md` for available block types.
+
+### 3. Preview Blocks (Optional)
+
+Preview individual blocks before publishing:
+
+```bash
+riverbankcms preview block.hero \
+  --data '{"heading": "Contact Us", "subheading": "We would love to hear from you"}' \
+  --open
+```
+
+### 4. Verify the Page
+
+Check the page was created:
+
+```bash
+riverbankcms page get contact
+```
+
+List blocks on the page:
+
+```bash
+riverbankcms block list contact
+```
+
+### 5. Publish the Page
+
+When ready to make the page live:
+
+```bash
+riverbankcms page publish contact
+```
+
+## Additional Operations
+
+### Reordering Blocks
+
+Change the order of blocks on the page:
+
+```bash
+riverbankcms block reorder contact hero-section intro-text form-section
+```
+
+Blocks will appear in the order specified.
+
+### Editing Block Content
+
+Update an existing block by upserting with new data:
+
+```bash
+riverbankcms block upsert contact hero-section \
+  --kind block.hero \
+  --data '{"heading": "New Heading", "subheading": "Updated subheading"}'
+```
+
+### Deleting Blocks
+
+Remove a block from the page:
+
+```bash
+riverbankcms delete block contact hero-section --yes
+```
+
+### Using JSON Files for Complex Content
+
+For blocks with complex nested content, use a JSON file:
+
+**hero-content.json:**
+
+```json
+{
+  "heading": "Contact Our Team",
+  "subheading": "We're here to help",
+  "backgroundImage": {
+    "src": "/images/contact-bg.jpg",
+    "alt": "Office background"
+  },
+  "cta": {
+    "text": "Send Message",
+    "url": "#contact-form"
+  }
+}
+```
+
+```bash
+riverbankcms block upsert contact hero-section \
+  --kind block.hero \
+  --file ./hero-content.json
+```
+
+## Complete Example
+
+Create a full about page with multiple blocks:
+
+```bash
+# 1. Create the page
+riverbankcms page upsert about \
+  --title "About Us" \
+  --path /about \
+  --seo-title "About Us | Company Name" \
+  --seo-description "Learn about our company, mission, and team."
+
+# 2. Add hero block
+riverbankcms block upsert about hero \
+  --kind block.hero \
+  --data '{"heading": "About Us", "subheading": "Our story and mission"}'
+
+# 3. Add introduction text
+riverbankcms block upsert about intro \
+  --kind block.bodyText \
+  --data '{"content": "<p>Founded in 2020, we have been...</p>"}'
+
+# 4. Add team section (if using a team block)
+riverbankcms block upsert about team \
+  --kind block.bodyText \
+  --data '{"content": "<h2>Our Team</h2><p>Meet the people behind the company.</p>"}'
+
+# 5. Verify
+riverbankcms page get about
+riverbankcms block list about
+
+# 6. Publish when ready
+riverbankcms page publish about
+```
+
+## Troubleshooting
+
+### Page already exists
+
+If the page identifier already exists, `upsert` will update it. This is intentional - use unique identifiers for new pages.
+
+### Block not appearing
+
+- Verify the block was created: `riverbankcms block get <page> <block-id>`
+- Check block kind is valid: see `block-types.md`
+- Ensure JSON data is properly formatted
+
+### Page not showing on site
+
+- Check if page is published: `riverbankcms page get <identifier>`
+- Look for `status: "published"` in the output
+- Publish if needed: `riverbankcms page publish <identifier>`