@qikdev/mcp 6.6.6 → 6.6.9

package/build/src/documentation.js

@@ -0,0 +1,1200 @@
+/**
+ * Qik API Documentation Integration
+ *
+ * This module provides comprehensive documentation understanding capabilities
+ * for the Qik MCP server, integrating the full API documentation to provide
+ * context-aware help, examples, and troubleshooting assistance.
+ */
+/**
+ * Comprehensive Qik API Documentation
+ * Based on the full API documentation PDF
+ */
+export const QIK_DOCUMENTATION = {
+    authentication: {
+        tokenTypes: {
+            user: {
+                description: "User access tokens are granted when users log in to the platform admin console at https://app.qik.dev. Typically reserved for administration staff, developers or team members.",
+                prefix: "ey",
+                useCase: "Administrative access, platform management, content creation by staff",
+                example: "eyJhbGciOiJIUzI1NiIsIn..."
+            },
+            persona: {
+                description: "Persona access tokens are generated when customers log in to your applications. Branded with your custom domain and business name.",
+                prefix: "pa-",
+                useCase: "Customer-facing applications, branded experiences, user-specific content",
+                example: "pa-123524316234735478345843584358"
+            },
+            application: {
+                description: "Application access tokens are static tokens for every application you create. Useful for public websites or backend integrations.",
+                prefix: "at-",
+                useCase: "Public websites, search engine indexing, backend integrations, static content",
+                example: "at-9x7OK8sT5..."
+            }
+        },
+        methods: {
+            bearer: {
+                description: "Include the token in the Authorization header using Bearer authentication",
+                example: "Authorization: Bearer eyJsadh432kndsfgi45..."
+            },
+            queryString: {
+                description: "Include the token as a URL query parameter",
+                example: "https://api.qik.dev/user?access_token=eyJsadh432kndsfgi45..."
+            }
+        },
+        errorCodes: {
+            "401": {
+                description: "Unauthorized - The request was made without an access token or with an expired/invalid access token",
+                commonCauses: [
+                    "Missing access token",
+                    "Expired access token",
+                    "Invalid token format",
+                    "Token not properly formatted in header"
+                ],
+                solutions: [
+                    "Check that QIK_ACCESS_TOKEN environment variable is set",
+                    "Verify token is not expired",
+                    "Ensure Bearer prefix is included in Authorization header",
+                    "Refresh token if using user/persona tokens"
+                ]
+            },
+            "403": {
+                description: "Access Denied - The user does not have permission to make the request",
+                commonCauses: [
+                    "Insufficient permissions for the operation",
+                    "Trying to access content outside permitted scopes",
+                    "Application token lacks required permissions"
+                ],
+                solutions: [
+                    "Check user/application permissions",
+                    "Verify scope access rights",
+                    "Contact administrator to grant required permissions",
+                    "Use a token with appropriate access level"
+                ]
+            },
+            "429": {
+                description: "Too many requests - You have exceeded the allowed rate limit",
+                commonCauses: [
+                    "Making requests too quickly",
+                    "Bulk operations without rate limiting",
+                    "Multiple concurrent requests"
+                ],
+                solutions: [
+                    "Implement exponential backoff",
+                    "Add delays between requests",
+                    "Use batch operations where available",
+                    "Monitor request frequency"
+                ]
+            }
+        }
+    },
+    endpoints: {
+        "/content/:type/create": {
+            method: "POST",
+            description: "Create new content items of a specified type. Supports file uploads for media content types.",
+            parameters: {
+                "type": {
+                    type: "string",
+                    required: true,
+                    description: "The key of the content type to create (e.g., 'car', 'blogPost', 'article')",
+                    example: "article"
+                },
+                "title": {
+                    type: "string",
+                    required: true,
+                    description: "The title of the content item",
+                    example: "My New Article"
+                },
+                "meta": {
+                    type: "object",
+                    required: true,
+                    description: "Meta information including scopes (required)",
+                    example: { scopes: ["62b59cb573fb4772e7b5fa93"] }
+                },
+                "data": {
+                    type: "object",
+                    required: false,
+                    description: "Custom field data based on content type definition",
+                    example: { make: "Toyota", model: "Camry" }
+                }
+            },
+            examples: [
+                {
+                    request: {
+                        title: "Pathfinder",
+                        meta: { scopes: ["62b59cb573fb4772e7b5fa93"] },
+                        data: { make: "Nissan", style: "Ti" }
+                    },
+                    response: {
+                        _id: "62cf66e161ad86b0095ca407",
+                        title: "Pathfinder",
+                        meta: {
+                            created: "2023-07-14T00:44:17.764Z",
+                            type: "article",
+                            slug: "pathfinder",
+                            status: "active"
+                        },
+                        data: { make: "Nissan", style: "Ti" }
+                    },
+                    description: "Creating a basic content item with custom fields"
+                },
+                {
+                    request: {
+                        title: "Awesome Photo",
+                        meta: { scopes: ["62b59cb573fb4772e7b5fa93"] },
+                        mediaIntegrationType: "upload",
+                        file: {
+                            url: "https://publicimages.com/landscape.jpg",
+                            name: "Landscape.jpg"
+                        },
+                        data: { caption: "What a lovely landscape" }
+                    },
+                    response: {
+                        _id: "62cf66e161ad86b0095ca408",
+                        title: "Awesome Photo",
+                        mediaIntegrationType: "upload",
+                        fileName: "Landscape.jpg"
+                    },
+                    description: "Creating an image by providing external URL for upload"
+                }
+            ],
+            commonErrors: [
+                "Missing required 'scopes' in meta object",
+                "Invalid content type key",
+                "Field placement errors (root vs data object)",
+                "Insufficient permissions for the specified scopes"
+            ],
+            relatedEndpoints: [
+                "/content/:type/list",
+                "/content/:id",
+                "/content/:type/definition"
+            ]
+        },
+        "/content/:type/list": {
+            method: "POST",
+            description: "Retrieve multiple content items with advanced filtering, sorting, and pagination",
+            parameters: {
+                "type": {
+                    type: "string",
+                    required: true,
+                    description: "Content type to list",
+                    example: "profile"
+                },
+                "search": {
+                    type: "string",
+                    required: false,
+                    description: "Keywords to search within title, tags, and text areas",
+                    example: "john smith"
+                },
+                "filter": {
+                    type: "object",
+                    required: false,
+                    description: "Advanced filter criteria with 40+ comparators",
+                    example: {
+                        operator: "and",
+                        filters: [
+                            { key: "firstName", comparator: "startswith", value: "John" }
+                        ]
+                    }
+                },
+                "sort": {
+                    type: "object",
+                    required: false,
+                    description: "Sorting configuration",
+                    example: { key: "meta.created", direction: "desc", type: "date" }
+                },
+                "page": {
+                    type: "object",
+                    required: false,
+                    description: "Pagination settings",
+                    example: { size: 20, index: 1 }
+                }
+            },
+            examples: [
+                {
+                    request: {
+                        sort: { direction: "asc", type: "string", key: "title" },
+                        search: "",
+                        select: ["title", "data.make"],
+                        page: { size: 50, index: 1 },
+                        filter: {
+                            operator: "and",
+                            filters: [{
+                                    operator: "and",
+                                    filters: [
+                                        { key: "data.make", comparator: "in", values: ["Toyota", "Nissan"] },
+                                        { key: "title", comparator: "contains", value: "ra" }
+                                    ]
+                                }]
+                        }
+                    },
+                    response: {
+                        items: [
+                            { _id: "62b5a0316143c2335f858ea8", title: "Prado", data: { make: "Toyota" } },
+                            { _id: "62b5a0af6143c2335f85905f", title: "Navara", data: { make: "Nissan" } }
+                        ],
+                        total: 2,
+                        page: { index: 1, total: 1 }
+                    },
+                    description: "Complex filtering with multiple conditions and field selection"
+                }
+            ],
+            commonErrors: [
+                "Invalid filter syntax",
+                "Unknown comparator in filter",
+                "Invalid content type",
+                "Page size exceeds maximum (100)"
+            ],
+            relatedEndpoints: [
+                "/content/:type/create",
+                "/content/:id",
+                "/glossary"
+            ]
+        }
+    },
+    contentTypes: {
+        "profile": {
+            description: "Represents a human person's details including contact information, demographics, and custom fields",
+            useCase: "Managing people in your organization - customers, employees, students, members, etc.",
+            fieldStructure: {
+                rootLevel: ["firstName", "lastName", "emails", "phoneNumbers", "gender", "dob*", "addresses", "meta"],
+                dataObject: ["customField1", "customField2", "additionalInfo"]
+            },
+            examples: {
+                creation: {
+                    firstName: "John",
+                    lastName: "Smith",
+                    emails: ["john@example.com"],
+                    phoneNumbers: [{ label: "Mobile", countryCode: "AU", number: "0412345678" }],
+                    meta: { scopes: ["scope-id-here"] },
+                    data: { department: "Engineering", startDate: "2024-01-15" }
+                },
+                update: {
+                    emails: ["john.smith@newcompany.com"],
+                    data: { department: "Product", role: "Senior Engineer" }
+                },
+                query: {
+                    filter: {
+                        operator: "and",
+                        filters: [
+                            { key: "firstName", comparator: "startswith", value: "John" },
+                            { key: "data.department", comparator: "equal", value: "Engineering" }
+                        ]
+                    }
+                }
+            },
+            commonPatterns: [
+                "Use anniversarynext/anniversarypast for birthday queries",
+                "Search by name using 'contains' or 'startswith' comparators",
+                "Filter by custom fields using 'data.fieldName' notation",
+                "Use 'in' comparator for multiple email addresses"
+            ],
+            troubleshooting: [
+                "If profile creation fails, check that firstName and lastName are provided",
+                "Email validation errors - ensure valid email format",
+                "Phone number format - use separate countryCode and number fields",
+                "Custom fields must go in 'data' object, not at root level"
+            ]
+        },
+        "article": {
+            description: "Text-based content for blogs, knowledge bases, and other content-driven applications",
+            useCase: "Creating blog posts, documentation, news articles, knowledge base entries",
+            fieldStructure: {
+                rootLevel: ["title", "body", "meta"],
+                dataObject: ["category", "author", "tags", "customFields"]
+            },
+            examples: {
+                creation: {
+                    title: "Getting Started with Qik",
+                    body: "<p>Welcome to Qik platform...</p>",
+                    meta: { scopes: ["public-scope"], security: "public" },
+                    data: { category: "Tutorial", estimatedReadTime: 5 }
+                },
+                update: {
+                    body: "<p>Updated content...</p>",
+                    data: { category: "Advanced Tutorial", lastReviewed: "2024-01-15" }
+                },
+                query: {
+                    search: "getting started",
+                    filter: {
+                        operator: "and",
+                        filters: [
+                            { key: "data.category", comparator: "equal", value: "Tutorial" },
+                            { key: "meta.created", comparator: "datepast", value: 30, value2: "days" }
+                        ]
+                    }
+                }
+            },
+            commonPatterns: [
+                "Use 'body' field for main content (HTML supported)",
+                "Search across title and body content with search parameter",
+                "Filter by publication date using date comparators",
+                "Use security levels: public, secure, private"
+            ],
+            troubleshooting: [
+                "Body content should be at root level, not in data object",
+                "HTML content should be properly escaped",
+                "Large content may hit size limits - consider file attachments",
+                "Search indexing may take time for new articles"
+            ]
+        },
+        "event": {
+            description: "Represents events, meetings, or periods of time with start/end dates and attendee management",
+            useCase: "Managing calendar events, meetings, conferences, classes, appointments",
+            fieldStructure: {
+                rootLevel: ["title", "startDate", "endDate", "allDay", "timezone", "body", "meta"],
+                dataObject: ["location", "capacity", "registrationRequired", "customEventFields"]
+            },
+            examples: {
+                creation: {
+                    title: "Team Meeting",
+                    startDate: "2024-03-15T14:00:00Z",
+                    endDate: "2024-03-15T15:00:00Z",
+                    timezone: "Australia/Sydney",
+                    body: "Weekly team sync meeting",
+                    meta: { scopes: ["team-scope"] },
+                    data: { location: "Conference Room A", capacity: 10 }
+                },
+                update: {
+                    startDate: "2024-03-15T14:30:00Z",
+                    data: { location: "Conference Room B", capacity: 15 }
+                },
+                query: {
+                    filter: {
+                        operator: "and",
+                        filters: [
+                            { key: "startDate", comparator: "datenext", value: 7, value2: "days" },
+                            { key: "data.location", comparator: "contains", value: "Conference" }
+                        ]
+                    }
+                }
+            },
+            commonPatterns: [
+                "Use ISO 8601 format for dates",
+                "Filter upcoming events with 'datenext' comparator",
+                "Use 'datebetween' for date range queries",
+                "Set timezone for proper date handling"
+            ],
+            troubleshooting: [
+                "Date format must be ISO 8601 (YYYY-MM-DDTHH:mm:ssZ)",
+                "Timezone handling - ensure consistent timezone usage",
+                "All-day events should set allDay: true and omit times",
+                "End date must be after start date"
+            ]
+        }
+    },
+    filterSyntax: {
+        operators: {
+            "and": {
+                description: "All filters must match (logical AND)",
+                examples: [
+                    {
+                        operator: "and",
+                        filters: [
+                            { key: "firstName", comparator: "equal", value: "John" },
+                            { key: "lastName", comparator: "equal", value: "Smith" }
+                        ]
+                    }
+                ],
+                commonUse: "Combining multiple conditions that all must be true"
+            },
+            "or": {
+                description: "Any filter can match (logical OR)",
+                examples: [
+                    {
+                        operator: "or",
+                        filters: [
+                            { key: "firstName", comparator: "equal", value: "John" },
+                            { key: "firstName", comparator: "equal", value: "Jane" }
+                        ]
+                    }
+                ],
+                commonUse: "Finding items that match any of several conditions"
+            },
+            "nor": {
+                description: "None of the filters can match (logical NOR)",
+                examples: [
+                    {
+                        operator: "nor",
+                        filters: [
+                            { key: "status", comparator: "equal", value: "deleted" },
+                            { key: "status", comparator: "equal", value: "archived" }
+                        ]
+                    }
+                ],
+                commonUse: "Excluding items that match certain conditions"
+            }
+        },
+        comparators: {
+            "equal": {
+                description: "Field value equals the specified value (case insensitive for strings)",
+                valueTypes: ["string", "number", "boolean"],
+                examples: [
+                    { key: "firstName", comparator: "equal", value: "John" },
+                    { key: "age", comparator: "equal", value: 25 },
+                    { key: "active", comparator: "equal", value: true }
+                ],
+                relatedComparators: ["notequal", "in", "notin"]
+            },
+            "contains": {
+                description: "String field contains the specified substring (case insensitive)",
+                valueTypes: ["string"],
+                examples: [
+                    { key: "title", comparator: "contains", value: "meeting" },
+                    { key: "description", comparator: "contains", value: "urgent" }
+                ],
+                relatedComparators: ["excludes", "startswith", "endswith"]
+            },
+            "anniversarynext": {
+                description: "Find dates that have their anniversary in the next specified duration",
+                valueTypes: ["number", "string"],
+                examples: [
+                    { key: "dob", comparator: "anniversarynext", value: 10, value2: "days" },
+                    { key: "startDate", comparator: "anniversarynext", value: 1, value2: "months" }
+                ],
+                relatedComparators: ["anniversarypast", "anniversarybetween", "dateanniversary"]
+            },
+            "datepast": {
+                description: "Find dates that are in the last specified duration from now",
+                valueTypes: ["number", "string"],
+                examples: [
+                    { key: "meta.created", comparator: "datepast", value: 30, value2: "days" },
+                    { key: "lastLogin", comparator: "datepast", value: 1, value2: "weeks" }
+                ],
+                relatedComparators: ["datenext", "datebetween", "datebeforenow"]
+            },
+            "in": {
+                description: "Field value is in the specified array of values",
+                valueTypes: ["array"],
+                examples: [
+                    { key: "status", comparator: "in", values: ["active", "pending", "approved"] },
+                    { key: "department", comparator: "in", values: ["Engineering", "Product"] }
+                ],
+                relatedComparators: ["notin", "equal", "notequal"]
+            }
+        },
+        patterns: {
+            "birthday_queries": {
+                description: "Find people with birthdays in a specific timeframe",
+                example: {
+                    operator: "and",
+                    filters: [{
+                            key: "dob",
+                            comparator: "anniversarynext",
+                            value: 7,
+                            value2: "days"
+                        }]
+                },
+                useCase: "Birthday reminders, celebration planning"
+            },
+            "recent_content": {
+                description: "Find content created or updated recently",
+                example: {
+                    operator: "and",
+                    filters: [{
+                            key: "meta.updated",
+                            comparator: "datepast",
+                            value: 30,
+                            value2: "days"
+                        }]
+                },
+                useCase: "Activity feeds, recent changes reports"
+            },
+            "complex_profile_search": {
+                description: "Multi-criteria profile search with OR logic",
+                example: {
+                    operator: "or",
+                    filters: [
+                        { key: "firstName", comparator: "startswith", value: "John" },
+                        { key: "lastName", comparator: "contains", value: "Smith" },
+                        { key: "emails", comparator: "contains", value: "john" }
+                    ]
+                },
+                useCase: "Flexible people search across multiple fields"
+            }
+        }
+    },
+    widgetTypes: {
+        "dateobject": {
+            description: "A complex date/time widget that stores date and time components as separate fields in an object structure. Used for precise date/time input where individual components need to be accessible.",
+            expectedInput: {
+                hour: "number (0-23)",
+                minute: "number (0-59)",
+                day: "number (1-31)",
+                month: "number (1-12)",
+                year: "number (full year, e.g., 2025)"
+            },
+            examples: [
+                {
+                    description: "Event start time - January 15, 2025 at 1:30 PM",
+                    value: { hour: 13, minute: 30, day: 15, month: 1, year: 2025 }
+                },
+                {
+                    description: "Meeting end time - March 22, 2024 at 9:45 AM",
+                    value: { hour: 9, minute: 45, day: 22, month: 3, year: 2024 }
+                },
+                {
+                    description: "All-day event (midnight start)",
+                    value: { hour: 0, minute: 0, day: 10, month: 6, year: 2024 }
+                },
+                {
+                    description: "Late evening event - 11:59 PM",
+                    value: { hour: 23, minute: 59, day: 31, month: 12, year: 2024 }
+                }
+            ],
+            validation: [
+                "hour must be integer between 0-23 (24-hour format)",
+                "minute must be integer between 0-59",
+                "day must be integer between 1-31 (validated against month/year)",
+                "month must be integer between 1-12 (January=1, December=12)",
+                "year must be a 4-digit integer (e.g., 2024, 2025)",
+                "Date combination must be valid (e.g., no February 30th)",
+                "All fields are required - partial dates not supported"
+            ],
+            commonErrors: [
+                "Using 12-hour format instead of 24-hour (use 13 for 1 PM, not 1)",
+                "Using 0-based months instead of 1-based (January is 1, not 0)",
+                "Providing string values instead of numbers",
+                "Missing required fields (all 5 fields must be present)",
+                "Invalid date combinations (e.g., February 30, April 31)",
+                "Using minute values > 59 or hour values > 23",
+                "Providing ISO date strings instead of object structure"
+            ],
+            relatedWidgets: [
+                "date",
+                "time",
+                "datetime",
+                "timestamp"
+            ]
+        },
+        "date": {
+            description: "Simple date widget for date-only input without time components",
+            expectedInput: "ISO 8601 date string (YYYY-MM-DD)",
+            examples: [
+                { description: "Birthday", value: "1990-05-15" },
+                { description: "Event date", value: "2024-12-25" }
+            ],
+            validation: [
+                "Must be valid ISO 8601 date format (YYYY-MM-DD)",
+                "Date must be valid calendar date"
+            ],
+            commonErrors: [
+                "Using MM/DD/YYYY or DD/MM/YYYY format instead of ISO",
+                "Including time components in date-only field"
+            ],
+            relatedWidgets: ["dateobject", "datetime", "timestamp"]
+        },
+        "time": {
+            description: "Time-only widget for time input without date components",
+            expectedInput: "Time string in HH:MM format (24-hour)",
+            examples: [
+                { description: "Morning meeting", value: "09:30" },
+                { description: "Afternoon deadline", value: "15:45" }
+            ],
+            validation: [
+                "Must be in HH:MM format using 24-hour time",
+                "Hours must be 00-23, minutes must be 00-59"
+            ],
+            commonErrors: [
+                "Using 12-hour format with AM/PM",
+                "Single digit hours/minutes without leading zero"
+            ],
+            relatedWidgets: ["dateobject", "datetime"]
+        },
+        "datetime": {
+            description: "Combined date and time widget using ISO 8601 datetime format",
+            expectedInput: "ISO 8601 datetime string (YYYY-MM-DDTHH:MM:SSZ)",
+            examples: [
+                { description: "Event start", value: "2024-03-15T14:30:00Z" },
+                { description: "Deadline", value: "2024-12-31T23:59:59Z" }
+            ],
+            validation: [
+                "Must be valid ISO 8601 datetime format",
+                "Should include timezone (Z for UTC or offset like +10:00)"
+            ],
+            commonErrors: [
+                "Missing T separator between date and time",
+                "Missing timezone information",
+                "Using local time format instead of ISO 8601"
+            ],
+            relatedWidgets: ["dateobject", "date", "time", "timestamp"]
+        }
+    },
+    concepts: {
+        "field_placement": {
+            title: "Field Placement Rules",
+            description: "Understanding where fields go in the JSON payload - root level vs data object",
+            keyPoints: [
+                "Fields defined in glossary 'fields' array go at ROOT LEVEL",
+                "Fields defined in glossary 'definedFields' array go in DATA OBJECT",
+                "Standard fields (title, meta, reference, body) always go at root level",
+                "Custom content-specific fields typically go in data object"
+            ],
+            examples: [
+                {
+                    description: "Correct field placement for a custom car content type",
+                    correct: {
+                        type: "car",
+                        title: "My Car",
+                        meta: { scopes: ["scope-id"] },
+                        data: { make: "Toyota", model: "Camry" }
+                    },
+                    incorrect: {
+                        type: "car",
+                        data: {
+                            title: "My Car",
+                            make: "Toyota",
+                            model: "Camry"
+                        }
+                    }
+                }
+            ],
+            relatedConcepts: ["content_types", "glossary_structure", "api_validation"],
+            commonMisunderstandings: [
+                "Putting title in data object instead of root level",
+                "Putting custom fields at root level instead of data object",
+                "Confusing 'fields' vs 'definedFields' in glossary"
+            ]
+        },
+        "widget_types": {
+            title: "Understanding Widget Types in Field Definitions",
+            description: "Widget types define how fields should be input and validated, with specific expected formats and structures",
+            keyPoints: [
+                "Widget type determines the expected input format for a field",
+                "dateobject widget requires object structure with hour, minute, day, month, year",
+                "Different widgets have different validation rules and formats",
+                "Widget type is specified in the glossary field definition"
+            ],
+            examples: [
+                {
+                    description: "Event with dateobject start/end times",
+                    correct: {
+                        title: "Team Meeting",
+                        meta: { scopes: ["team-scope"] },
+                        data: {
+                            start: { hour: 14, minute: 0, day: 15, month: 3, year: 2024 },
+                            end: { hour: 15, minute: 30, day: 15, month: 3, year: 2024 }
+                        }
+                    },
+                    incorrect: {
+                        title: "Team Meeting",
+                        meta: { scopes: ["team-scope"] },
+                        data: {
+                            start: "2024-03-15T14:00:00Z",
+                            end: "2024-03-15T15:30:00Z"
+                        }
+                    }
+                }
+            ],
+            relatedConcepts: ["field_placement", "content_types", "validation"],
+            commonMisunderstandings: [
+                "Using ISO date strings for dateobject widgets",
+                "Not understanding widget-specific input requirements",
+                "Assuming all date fields use the same format"
+            ]
+        },
+        "scopes_and_permissions": {
+            title: "Scopes and Permissions System",
+            description: "Hierarchical permission structure that controls access to content and operations",
+            keyPoints: [
+                "Every content item must belong to at least one scope",
+                "Scopes are hierarchical like folders - permissions can inherit",
+                "Users need appropriate permissions within scopes to perform actions",
+                "Different token types have different permission models"
+            ],
+            examples: [
+                {
+                    description: "Scope hierarchy example",
+                    structure: {
+                        "Organization": {
+                            "HR Department": ["Employee Records", "Policies"],
+                            "Engineering": ["Projects", "Documentation"],
+                            "Public": ["Blog Posts", "Marketing"]
+                        }
+                    }
+                }
+            ],
+            relatedConcepts: ["authentication", "content_security", "user_roles"],
+            commonMisunderstandings: [
+                "Forgetting to include scopes in meta object",
+                "Using scope names instead of scope IDs",
+                "Not understanding permission inheritance"
+            ]
+        },
+        "workflow_system": {
+            title: "Workflow Definitions vs Workflow Cards",
+            description: "Understanding the difference between workflow templates and workflow instances",
+            keyPoints: [
+                "Workflow Definition = Template with columns, steps, automation rules",
+                "Workflow Card = Individual item that moves through the workflow",
+                "Definitions define the structure, Cards are the instances",
+                "One definition can have many cards moving through it"
+            ],
+            examples: [
+                {
+                    description: "Student onboarding workflow",
+                    definition: {
+                        title: "Student Onboarding",
+                        columns: ["Application", "Review", "Approved", "Enrolled"],
+                        automation: "Entry/exit functions for each step"
+                    },
+                    cards: [
+                        { title: "John Smith - Application", currentStep: "Review" },
+                        { title: "Jane Doe - Application", currentStep: "Approved" }
+                    ]
+                }
+            ],
+            relatedConcepts: ["content_types", "definitions_vs_instances", "automation"],
+            commonMisunderstandings: [
+                "Confusing when to create definition vs card",
+                "Not understanding the template/instance relationship",
+                "Trying to add people directly to definitions instead of creating cards"
+            ]
+        }
+    },
+    examples: {
+        "authentication": {
+            "bearer_token": {
+                title: "Using Bearer Token Authentication",
+                description: "How to properly authenticate API requests using Bearer tokens",
+                code: {
+                    headers: {
+                        "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsIn...",
+                        "Content-Type": "application/json"
+                    }
+                },
+                explanation: "Include the access token in the Authorization header with 'Bearer ' prefix",
+                variations: [
+                    {
+                        description: "Query string authentication",
+                        code: "https://api.qik.dev/user?access_token=eyJhbGciOiJIUzI1NiIsIn..."
+                    }
+                ]
+            }
+        },
+        "content_creation": {
+            "basic_article": {
+                title: "Creating a Basic Article",
+                description: "Simple article creation with title, body, and scopes",
+                code: {
+                    type: "article",
+                    title: "Getting Started Guide",
+                    body: "<p>Welcome to our platform...</p>",
+                    meta: {
+                        scopes: ["public-content"],
+                        security: "public"
+                    }
+                },
+                explanation: "Articles require title and body at root level, with scopes in meta object",
+                variations: [
+                    {
+                        description: "Article with custom fields",
+                        code: {
+                            type: "article",
+                            title: "Advanced Guide",
+                            body: "<p>Advanced content...</p>",
+                            meta: { scopes: ["public-content"] },
+                            data: { category: "Tutorial", difficulty: "Advanced" }
+                        }
+                    }
+                ]
+            },
+            "profile_with_contacts": {
+                title: "Creating Profile with Contact Information",
+                description: "Complete profile creation including phone numbers and addresses",
+                code: {
+                    firstName: "John",
+                    lastName: "Smith",
+                    emails: ["john@example.com", "j.smith@work.com"],
+                    phoneNumbers: [
+                        { label: "Mobile", countryCode: "AU", number: "0412345678" },
+                        { label: "Work", countryCode: "AU", number: "0287654321" }
+                    ],
+                    addresses: [{
+                            title: "Home",
+                            addressLine1: "123 Main St",
+                            suburb: "Sydney",
+                            state: "NSW",
+                            postalCode: "2000",
+                            country: "Australia"
+                        }],
+                    meta: { scopes: ["employee-records"] }
+                },
+                explanation: "Profiles support multiple emails, phone numbers, and addresses with structured data",
+                variations: [
+                    {
+                        description: "Profile with custom fields",
+                        code: {
+                            firstName: "Jane",
+                            lastName: "Doe",
+                            emails: ["jane@example.com"],
+                            meta: { scopes: ["employee-records"] },
+                            data: { department: "Engineering", startDate: "2024-01-15", employeeId: "EMP001" }
+                        }
+                    }
+                ]
+            }
+        },
+        "filtering": {
+            "birthday_search": {
+                title: "Finding Upcoming Birthdays",
+                description: "Search for people with birthdays in the next 10 days",
+                code: {
+                    type: "profile",
+                    filter: {
+                        operator: "and",
+                        filters: [{
+                                key: "dob",
+                                comparator: "anniversarynext",
+                                value: 10,
+                                value2: "days"
+                            }]
+                    },
+                    sort: { key: "dob", direction: "asc", type: "date" }
+                },
+                explanation: "Use 'anniversarynext' comparator to find anniversary dates in the future",
+                variations: [
+                    {
+                        description: "Birthdays this month",
+                        code: {
+                            filter: {
+                                operator: "and",
+                                filters: [{ key: "dobMonth", comparator: "equal", value: 3 }]
+                            }
+                        }
+                    }
+                ]
+            },
+            "complex_content_search": {
+                title: "Multi-Criteria Content Search",
+                description: "Search articles by category, date range, and author",
+                code: {
+                    type: "article",
+                    search: "tutorial",
+                    filter: {
+                        operator: "and",
+                        filters: [
+                            { key: "data.category", comparator: "in", values: ["Tutorial", "Guide"] },
+                            { key: "meta.created", comparator: "datepast", value: 90, value2: "days" },
+                            { key: "data.author", comparator: "startswith", value: "John" }
+                        ]
+                    },
+                    sort: { key: "meta.created", direction: "desc", type: "date" }
+                },
+                explanation: "Combine search terms with complex filters for precise content discovery",
+                variations: [
+                    {
+                        description: "OR logic for flexible matching",
+                        code: {
+                            filter: {
+                                operator: "or",
+                                filters: [
+                                    { key: "data.category", comparator: "equal", value: "Tutorial" },
+                                    { key: "title", comparator: "contains", value: "guide" }
+                                ]
+                            }
+                        }
+                    }
+                ]
+            }
+        }
+    },
+    troubleshooting: {
+        "field_placement_errors": {
+            symptoms: [
+                "Error: Field 'X' is defined in glossary 'fields' array and must be at ROOT LEVEL",
+                "Error: Field 'Y' is defined in glossary 'definedFields' array and must be in DATA OBJECT",
+                "Validation failed: incorrect field placement",
+                "Content creation rejected due to field structure"
+            ],
+            causes: [
+                "Putting glossary 'fields' in data object instead of root level",
+                "Putting glossary 'definedFields' at root level instead of data object",
+                "Misunderstanding the difference between fields and definedFields",
+                "Not checking content type definition before creating content"
+            ],
+            solutions: [
+                "Check content type definition using qik_get_content_definition",
+                "Move 'fields' array items to root level of payload",
+                "Move 'definedFields' array items to data object",
+                "Use qik_create_content_intelligent for automatic field placement"
+            ],
+            prevention: [
+                "Always review content type definition before creating content",
+                "Use the intelligent creation tool when unsure about field placement",
+                "Create documentation for custom content types",
+                "Test with simple examples before complex implementations"
+            ],
+            relatedIssues: ["validation_errors", "content_creation_failures", "api_rejection"]
+        },
+        "authentication_failures": {
+            symptoms: [
+                "401 Unauthorized responses",
+                "403 Access Denied errors",
+                "Token validation failed messages",
+                "Unable to access content or perform operations"
+            ],
+            causes: [
+                "Missing or expired access token",
+                "Incorrect token format in Authorization header",
+                "Using wrong token type for the operation",
+                "Insufficient permissions for the requested scope"
+            ],
+            solutions: [
+                "Verify QIK_ACCESS_TOKEN environment variable is set",
+                "Check token expiration and refresh if needed",
+                "Ensure Bearer prefix in Authorization header",
+                "Use appropriate token type (user/persona/application)",
+                "Contact administrator for permission grants"
+            ],
+            prevention: [
+                "Implement token refresh logic for user/persona tokens",
+                "Monitor token expiration times",
+                "Use application tokens for static/public content",
+                "Regularly audit user permissions"
+            ],
+            relatedIssues: ["permission_errors", "scope_access_denied", "token_expiration"]
+        },
+        "filter_syntax_errors": {
+            symptoms: [
+                "Invalid filter syntax error messages",
+                "Unknown comparator errors",
+                "Filter validation failed",
+                "Unexpected query results or empty results"
+            ],
+            causes: [
+                "Using unsupported comparator names",
+                "Incorrect value types for comparators",
+                "Missing required value2 parameter for range comparators",
+                "Malformed nested filter structure"
+            ],
+            solutions: [
+                "Check comparator spelling and supported list",
+                "Verify value types match comparator requirements",
+                "Add value2 for range comparators (between, anniversarynext, etc.)",
+                "Validate nested filter structure with proper operators",
+                "Test filters with simple examples first"
+            ],
+            prevention: [
+                "Use filter builder tools or templates",
+                "Reference documentation for comparator requirements",
+                "Start with simple filters and build complexity gradually",
+                "Test filters in isolation before combining"
+            ],
+            relatedIssues: ["query_performance", "unexpected_results", "data_type_mismatches"]
+        },
+        "scope_permission_issues": {
+            symptoms: [
+                "403 Access Denied when creating content",
+                "Empty results when listing content",
+                "Unable to access specific content items",
+                "Permission denied for scope operations"
+            ],
+            causes: [
+                "User lacks permissions for specified scopes",
+                "Using scope names instead of scope IDs",
+                "Scopes not properly assigned to content",
+                "Token type doesn't have required scope access"
+            ],
+            solutions: [
+                "Use qik_get_scopes to find available scopes and permissions",
+                "Verify scope IDs are correct (not names)",
+                "Check user permissions within the scope hierarchy",
+                "Use appropriate token type for scope access level"
+            ],
+            prevention: [
+                "Implement scope validation before content operations",
+                "Maintain clear scope hierarchy documentation",
+                "Regular permission audits and cleanup",
+                "Use descriptive scope names for easier management"
+            ],
+            relatedIssues: ["authentication_failures", "content_access_denied", "hierarchy_confusion"]
+        },
+        "workflow_confusion": {
+            symptoms: [
+                "Confusion about when to create workflow definitions vs cards",
+                "Unable to add people to workflows",
+                "Workflow structure not working as expected",
+                "Cards not moving through workflow properly"
+            ],
+            causes: [
+                "Not understanding definition vs card concept",
+                "Trying to add people directly to definitions",
+                "Incorrect workflow structure setup",
+                "Missing automation or step configuration"
+            ],
+            solutions: [
+                "Create workflow DEFINITION first (template)",
+                "Create workflow CARDS for individual instances",
+                "Reference profiles in workflow cards, not definitions",
+                "Set up proper column and step structure in definitions"
+            ],
+            prevention: [
+                "Study workflow examples and patterns",
+                "Start with simple workflows before complex automation",
+                "Document workflow processes clearly",
+                "Test workflow flow with sample data"
+            ],
+            relatedIssues: ["content_type_confusion", "automation_failures", "process_design"]
+        },
+        "date_handling_issues": {
+            symptoms: [
+                "Date filter queries returning unexpected results",
+                "Timezone-related date mismatches",
+                "Anniversary queries not working correctly",
+                "Date format validation errors"
+            ],
+            causes: [
+                "Incorrect date format (not ISO 8601)",
+                "Timezone confusion or missing timezone info",
+                "Using wrong date comparators",
+                "Date field not properly indexed or formatted"
+            ],
+            solutions: [
+                "Use ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ)",
+                "Specify timezone consistently",
+                "Use appropriate date comparators (datepast, datenext, anniversarynext)",
+                "Validate date formats before API calls"
+            ],
+            prevention: [
+                "Standardize on UTC for storage, convert for display",
+                "Use date validation libraries",
+                "Document date format requirements clearly",
+                "Test date queries across timezone boundaries"
+            ],
+            relatedIssues: ["filter_syntax_errors", "data_validation", "timezone_confusion"]
+        },
+        "performance_issues": {
+            symptoms: [
+                "Slow query responses",
+                "Timeout errors on large datasets",
+                "Rate limiting (429 errors)",
+                "Memory issues with large result sets"
+            ],
+            causes: [
+                "Inefficient filter queries",
+                "Large page sizes without proper pagination",
+                "Too many concurrent requests",
+                "Complex nested filters without optimization"
+            ],
+            solutions: [
+                "Optimize filter queries with indexed fields",
+                "Use appropriate page sizes (20-50 items)",
+                "Implement request throttling and retry logic",
+                "Use select parameter to limit returned fields",
+                "Cache frequently accessed data"
+            ],
+            prevention: [
+                "Design queries with performance in mind",
+                "Monitor query performance and optimize regularly",
+                "Implement proper pagination strategies",
+                "Use background processing for bulk operations"
+            ],
+            relatedIssues: ["rate_limiting", "memory_usage", "query_optimization"]
+        }
+    }
+};
+/**
+ * Helper functions for documentation integration
+ */
+export class QikDocumentationHelper {
+    /**
+     * Get documentation for a specific topic
+     */
+    static getTopicDocumentation(topic) {
+        const parts = topic.split('.');
+        let current = QIK_DOCUMENTATION;
+        for (const part of parts) {
+            if (current && typeof current === 'object' && part in current) {
+                current = current[part];
+            }
+            else {
+                return null;
+            }
+        }
+        return current;
+    }
+    /**
+     * Search documentation for relevant information
+     */
+    static searchDocumentation(query) {
+        const results = [];
+        const searchTerm = query.toLowerCase();
+        // Search through all documentation sections
+        this.searchInObject(QIK_DOCUMENTATION, searchTerm, '', results);
+        return results.slice(0, 10); // Limit to top 10 results
+    }
+    static searchInObject(obj, searchTerm, path, results) {
+        if (typeof obj === 'string' && obj.toLowerCase().includes(searchTerm)) {
+            results.push({ path, content: obj, type: 'text' });
+        }
+        else if (Array.isArray(obj)) {
+            obj.forEach((item, index) => {
+                this.searchInObject(item, searchTerm, `${path}[${index}]`, results);
+            });
+        }
+        else if (typeof obj === 'object' && obj !== null) {
+            Object.keys(obj).forEach(key => {
+                if (key.toLowerCase().includes(searchTerm)) {
+                    results.push({ path: `${path}.${key}`, content: obj[key], type: 'key' });
+                }
+                this.searchInObject(obj[key], searchTerm, `${path}.${key}`, results);
+            });
+        }
+    }
+    /**
+     * Get troubleshooting information for a specific error
+     */
+    static getTroubleshootingInfo(errorMessage) {
+        const troubleshooting = QIK_DOCUMENTATION.troubleshooting;
+        // Try to match error message to known issues
+        for (const [issueKey, issue] of Object.entries(troubleshooting)) {
+            if (issue.symptoms.some((symptom) => errorMessage.toLowerCase().includes(symptom.toLowerCase()) ||
+                symptom.toLowerCase().includes(errorMessage.toLowerCase()))) {
+                return { issue: issueKey, ...issue };
+            }
+        }
+        return null;
+    }
+    /**
+     * Get examples for a specific use case
+     */
+    static getExamples(category, example) {
+        const examples = QIK_DOCUMENTATION.examples[category];
+        if (!examples)
+            return null;
+        if (example && examples[example]) {
+            return examples[example];
+        }
+        return examples;
+    }
+    /**
+     * Validate field placement based on content type
+     */
+    static validateFieldPlacement(contentType, payload) {
+        const errors = [];
+        // This would need to be enhanced with actual glossary data
+        // For now, provide basic validation rules
+        const rootLevelFields = ['title', 'meta', 'reference', 'referenceType', 'body', 'organisation'];
+        const dataObjectFields = ['customField1', 'customField2']; // This would come from glossary
+        // Check for common mistakes
+        if (payload.data) {
+            rootLevelFields.forEach(field => {
+                if (payload.data[field]) {
+                    errors.push(`Field '${field}' should be at root level, not in data object`);
+                }
+            });
+        }
+        // Check for missing required fields
+        if (!payload.title) {
+            errors.push('Missing required field: title');
+        }
+        if (!payload.meta || !payload.meta.scopes) {
+            errors.push('Missing required field: meta.scopes');
+        }
+        return {
+            valid: errors.length === 0,
+            errors
+        };
+    }
+}
+//# sourceMappingURL=documentation.js.map