@modyo/mcp 0.1.0

package/docs/channels/templates/status-operations.md

@@ -0,0 +1,403 @@
+## State Transitions
+
+### Transition Rules
+
+**Allowed Transitions**:
+
+| From State | To State | Method |
+|------------|----------|--------|
+| Draft | Published | `release-create` |
+| Draft | Scheduled | `release-create` with `publish_at` |
+| Published | Draft (new version) | Edit operation |
+| Published | Unpublished | `*-unpublish` tool |
+| Published | Scheduled (unpublish) | `*-unpublish` with `unpublish_at` |
+| Scheduled | Published | Automatic (at `publish_at`) |
+| Scheduled | Unpublished | Automatic (at `unpublish_at`) |
+| Unpublished | Published | `release-create` |
+| Unpublished | Archived | `*-archive` tool |
+| Archived | Draft | Restore operation |
+
+**Forbidden Transitions**:
+
+| From State | To State | Why |
+|------------|----------|-----|
+| Draft | Unpublished | Can't unpublish what was never published |
+| Published | Archived | Must unpublish first |
+| Archived | Published | Must restore to draft first |
+
+### Transition Examples
+
+**Draft → Published**:
+```typescript
+// 1. Create resource (draft)
+const widget = await widget-definitions-create({ widgetName: "Card" });
+
+// 2. Get publishable elements
+const elements = await release-get-elements-to-publish({ siteId: 4612 });
+
+// 3. Publish
+await release-create({
+  data: { widgetDefinition: [{ id: widget.id, selected: true }] }
+});
+
+// Transition: draft → published
+```
+
+**Published → Draft (New Version)**:
+```typescript
+// Widget is published
+const published = await widget-get-custom-widgets({ siteId: 4612 });
+
+// Edit creates new draft version
+const definitions = await widget-definitions-list({ siteId: 4612 });
+const widget = definitions.widget_definitions[0];
+await widget-definition-update({ widgetId: widget.id, html: "Updated" });
+
+// State: published (live) + draft (pending)
+// Transition: published → published + draft
+```
+
+**Published → Unpublished**:
+```typescript
+// Page is published
+await page-unpublish({ pageId: 456 });
+
+// Transition: published → unpublished
+```
+
+**Unpublished → Published (Re-publish)**:
+```typescript
+// Page is unpublished
+const elements = await release-get-elements-to-publish({ siteId: 4612 });
+await release-create({
+  data: { page: [{ id: 456, selected: true }] }
+});
+
+// Transition: unpublished → published
+```
+
+**Published → Archived (Pages Only)**:
+```typescript
+// Must unpublish first
+await page-unpublish({ pageId: 456 });
+
+// Then archive workflow
+await page-archive({ pageId: 456 });
+
+// Transition: published → unpublished → archived
+```
+
+---
+
+## Querying Resource States
+
+### Templates
+
+```typescript
+// Get single template with state
+const template = await template-get({
+  platformSlug: "fed-team",
+  siteId: 4612,
+  templateId: 123
+});
+
+console.log({
+  published: template.published,    // boolean
+  status: template.status,          // "draft" | "published"
+  deletable: template.deletable     // Can it be deleted?
+});
+
+// List templates with state filter
+const templates = await template-list({
+  platformSlug: "fed-team",
+  siteId: 4612,
+  type: "custom_snippet"  // Filter by type
+});
+
+// Check if publishable
+const publishable = await release-get-elements-to-publish({ siteId: 4612 });
+const isPublishable = publishable.template.some(t => t.id === 123);
+```
+
+### Widget Definitions
+
+```typescript
+// Get widget with state
+const widget = await widget-definition-get({
+  platformSlug: "fed-team",
+  siteId: 4612,
+  widgetId: 123
+});
+
+console.log({
+  published: widget.published,      // boolean
+  read_only: widget.read_only,      // CLI widget?
+  version_id: widget.version_id     // Current version
+});
+
+// Check if published (in custom widgets)
+const customWidgets = await widget-get-custom-widgets({ siteId: 4612 });
+const isPublished = customWidgets.custom_widgets.some(w => w.uuid === widget.uuid);
+
+// Check if publishable
+const publishable = await release-get-elements-to-publish({ siteId: 4612 });
+const isPublishable = publishable.widgetDefinition.some(w => w.oid === widget.uuid);
+```
+
+### Pages
+
+```typescript
+// Get page with state
+const page = await page-get({
+  platformSlug: "fed-team",
+  siteId: 4612,
+  pageId: 456
+});
+
+console.log({
+  published: page.published,        // boolean
+  status: page.status,              // "draft" | "published" | "scheduled" | "unpublished"
+  publish_at: page.publish_at,      // Scheduled publish
+  unpublish_at: page.unpublish_at,  // Scheduled unpublish
+  workflow_id: page.workflow_id     // For archiving
+});
+
+// List pages with state filter
+const pages = await page-list({
+  platformSlug: "fed-team",
+  siteId: 4612,
+  states: ["published"]  // Filter by state
+});
+
+// Check if publishable
+const publishable = await release-get-elements-to-publish({ siteId: 4612 });
+const isPublishable = publishable.page.some(p => p.id === 456);
+```
+
+### Menus
+
+```typescript
+// Get menu with state
+const menu = await navigation-menu-get({
+  platformSlug: "fed-team",
+  siteId: 4612,
+  menuId: 101
+});
+
+console.log({
+  published: menu.published,  // boolean
+  items: menu.items          // Menu items
+});
+
+// Check if publishable
+const publishable = await release-get-elements-to-publish({ siteId: 4612 });
+const isPublishable = publishable.menu.some(m => m.id === 101);
+```
+
+---
+
+## Common State Issues
+
+### Issue 1: "Resource not appearing in publishable elements"
+
+**Symptoms**: Created/edited resource not in `release-get-elements-to-publish` results.
+
+**Causes**:
+1. Resource unchanged since last publish
+2. Team review enabled, not approved yet
+3. Resource already published (no pending changes)
+
+**Solutions**:
+```typescript
+// Check if resource has pending changes
+const template = await template-get({ templateId: 123 });
+console.log(template.published);  // If true, no pending changes
+
+// Make a change
+await template-save({ templateId: 123, body: "Updated" });
+
+// Now appears in publishable
+const elements = await release-get-elements-to-publish({ siteId: 4612 });
+// template with ID 123 now in elements.template
+```
+
+### Issue 2: "Widget ID not found after publishing"
+
+**Symptoms**: Widget exists but can't be retrieved by ID after publishing.
+
+**Cause**: Widget ID changes during publish cycle.
+
+**Solution**: Use UUID for identification.
+```typescript
+// Before publish - save UUID
+const widget = await widget-definition-get({ widgetId: 123 });
+const uuid = widget.uuid;
+
+// Publish
+await release-create({ ... });
+
+// After publish - find by UUID
+const customWidgets = await widget-get-custom-widgets({ siteId: 4612 });
+const published = customWidgets.custom_widgets.find(w => w.uuid === uuid);
+console.log(published.id);  // New ID, likely different from 123
+```
+
+### Issue 3: "Page shows old widget version"
+
+**Symptoms**: Updated widget not appearing on page.
+
+**Cause**: Widget published but page wasn't re-published.
+
+**Solution**: Publish page after widget changes.
+```typescript
+// 1. Update widget
+await widget-definition-update({ widgetId: 123, html: "Updated" });
+
+// 2. Publish widget
+await release-create({ data: { widgetDefinition: [...] } });
+
+// 3. MUST publish page
+const elements = await release-get-elements-to-publish({ siteId: 4612 });
+await release-create({ data: { page: [...] } });
+```
+
+### Issue 4: "Can't delete published page"
+
+**Symptoms**: `page-delete` fails with error.
+
+**Cause**: Published pages can't be deleted directly.
+
+**Solution**: Unpublish → Archive → Delete workflow.
+```typescript
+// Step 1: Unpublish
+await page-unpublish({ pageId: 456 });
+
+// Step 2: Archive
+await page-archive({ pageId: 456 });
+
+// Step 3: Delete
+await page-delete({ pageId: 456 });
+```
+
+### Issue 5: "Scheduled publish didn't execute"
+
+**Symptoms**: Resource didn't publish at scheduled time.
+
+**Causes**:
+1. Date in past
+2. Incorrect timezone
+3. Platform maintenance
+
+**Solutions**:
+```typescript
+// Verify date is future
+const publishDate = new Date("2025-02-01T09:00:00Z");
+const now = new Date();
+console.log(publishDate > now);  // Must be true
+
+// Use UTC timezone (recommended)
+publish_at: "2025-02-01T09:00:00Z"  // Z = UTC
+
+// Check scheduled releases
+const publishable = await release-get-elements-to-publish({ siteId: 4612 });
+// Check if scheduled in elements
+```
+
+---
+
+## Best Practices
+
+### 1. Always Check State Before Operations
+
+```typescript
+// ❌ Assume resource is draft
+await release-create({ data: { widgetDefinition: [{ id: 123, selected: true }] } });
+
+// ✅ Check state first
+const publishable = await release-get-elements-to-publish({ siteId: 4612 });
+const widget = publishable.widgetDefinition.find(w => w.id === 123);
+if (!widget) {
+  console.log("Widget not publishable (already published or no changes)");
+} else {
+  await release-create({ data: { widgetDefinition: [{ id: 123, selected: true }] } });
+}
+```
+
+### 2. Use UUIDs for Widgets
+
+```typescript
+// ❌ Track by ID (changes after publish)
+const widgetId = 123;
+
+// ✅ Track by UUID (stable)
+const widget = await widget-definition-get({ widgetId: 123 });
+const widgetUUID = widget.uuid;  // Stable across publishes
+```
+
+### 3. Re-fetch After State Changes
+
+```typescript
+// Publish widget
+await release-create({ ... });
+
+// ❌ Use stale data
+const widget = await widget-definition-get({ widgetId: 123 });  // May 404
+
+// ✅ Re-fetch to get current state
+const customWidgets = await widget-get-custom-widgets({ siteId: 4612 });
+const widget = customWidgets.custom_widgets.find(w => w.name === "My Widget");
+```
+
+### 4. Follow Required Workflows
+
+```typescript
+// ❌ Skip steps
+await page-delete({ pageId: 456 });  // Fails if published
+
+// ✅ Complete workflow
+await page-unpublish({ pageId: 456 });  // Step 1
+await page-archive({ pageId: 456 });    // Step 2
+await page-delete({ pageId: 456 });     // Step 3
+```
+
+### 5. Bundle Related Changes
+
+```typescript
+// ✅ Publish widget + page together
+await release-create({
+  data: {
+    widgetDefinition: [{ id: 123, selected: true }],
+    page: [{ id: 456, selected: true }]
+  }
+});
+// Atomic state transition - both publish together
+```
+
+---
+
+## Summary
+
+**Key Takeaways**:
+
+1. **All resources follow state machine**: Draft → Published → Unpublished → Archived
+2. **Always query state** before operations
+3. **Widget IDs change** during publish - use UUIDs
+4. **Pages require 3-step delete**: Unpublish → Archive → Delete
+5. **State transitions have rules** - some require intermediate steps
+6. **Scheduled states** transition automatically at specified times
+7. **Team review** adds Pending state between Draft and Published
+
+**Quick State Reference**:
+
+| Resource | States | Critical Tools |
+|----------|--------|----------------|
+| Templates | draft, published | `release-get-elements-to-publish`, `release-create`, `template-unpublish` |
+| Widgets | draft, published, draft+published | `widget-definitions-list`, `widget-get-custom-widgets`, `release-create` |
+| Pages | draft, published, scheduled, unpublished, archived | `page-get`, `page-unpublish`, `page-archive`, `page-delete` |
+| Menus | draft, published | `navigation-menu-get`, `release-create` |
+
+---
+
+**Document Version**: 1.0.0
+**Last Updated**: 2025-01-20
+**Related Docs**: [PUBLISHING_WORKFLOW.md](PUBLISHING_WORKFLOW.md), [WIDGET_WORKFLOWS.md](WIDGET_WORKFLOWS.md)