docs: convert Cloud Hook Triggers playground to DocC tutorial

[Copilot]

New Pull Request Checklist

• Disclose a vulnerability.
• Link this PR to an issue.

Issue Description

Converts playground page 23 (Cloud Hook Triggers) to DocC interactive tutorial following the structure established in PR #235.

Approach

Tutorial Structure

• 30-minute estimate, 7 sections covering CRUD operations, webhook handling, and best practices
• Follows established patterns from Cloud Schemas and Cloud Code tutorials
• Includes server-side warnings and prerequisite references

Code Snippets (17 files)

• Model definitions with merge methods
• Trigger lifecycle: create, fetch, update, delete
• All six trigger types (beforeSave, afterSave, beforeDelete, afterDelete, beforeFind, afterFind)
• Best practices: security, deployment, error handling, migrations, monitoring, idempotent setup
• All code snippets are self-contained with proper variable definitions
• Context comments added to sequential snippets for better tutorial flow

Integration

• Added to Server-Side Operations chapter in ParseSwift.tutorial
• Updated chapter description to include webhook triggers

Webhook Examples

• Removed inline webhook code examples
• Added links to parse-server-swift repository for production-ready Vapor-based Parse Hook Trigger implementations
• References routes.swift for comprehensive examples

Code Quality Fixes

• Fixed missing gameScore variable definition in trigger-types code snippet
• Added context comments to 6 sequential code snippets to clarify dependencies on previous steps
• Corrected type reference from ParseHookTrigger.TriggerType to ParseHookTriggerType
• Added force unwrapping to URL initialization for consistency with tutorial conventions
• Fixed optional String handling in monitoring snippet with proper guard statement

TODOs before merging

• Add tests
• Add entry to changelog
• Add changes to documentation (guides, repository pages, in-code descriptions)

Original prompt

Convert Cloud Hook Triggers Playground to DocC Tutorial

Objective

Convert the "Cloud Hook Triggers" playground file (ParseSwift.playground/Pages/23 - Cloud Hook Triggers.xcplaygroundpage/Contents.swift) to a DocC interactive tutorial following the existing tutorial structure established in PR #235.

Requirements

1. Tutorial Structure

Follow the same structure as existing tutorials:

• Use @Tutorial with appropriate time estimate (suggest 30-35 minutes)
• Include @Intro section with:
  • Clear title: "Cloud Hook Triggers"
  • Description of managing Parse Cloud Hook Triggers for database events
  • Prerequisites (reference to doc:Your-First-Object, doc:Cloud-Code, and doc:Cloud-Hook-Functions)
  • Use @Image(source: parse-logo.png, alt: "Parse logo") for consistency
• Multiple @Section blocks with @ContentAndMedia and @Steps
• Each @Step should have explanatory text and @Code references

2. Content Guidelines

Based on the Cloud Hook Triggers playground:

• Introduction: Explain Parse Cloud Hook Triggers and database event webhooks

• Section 1: Understanding Cloud Hook Triggers

  • What are Cloud Hook Triggers
  • Difference between Cloud Triggers and Hook Triggers
  • Trigger types (beforeSave, afterSave, beforeDelete, afterDelete, beforeFind, afterFind)
  • Use cases (webhooks for database events, external integrations, auditing)
  • Hook trigger URLs and event payloads
  • Required permissions (master key required)

• Section 2: Fetching Hook Triggers

  • Fetch all hook triggers from Parse Server
  • Fetch hook triggers by class name
  • Fetch specific trigger types
  • Inspect hook trigger properties (className, triggerName, URL)
  • Understanding trigger configurations

• Section 3: Creating Hook Triggers

  • Create beforeSave hook triggers using async/await
  • Create afterSave hook triggers
  • Create beforeDelete and afterDelete triggers
  • Create beforeFind and afterFind triggers
  • Set webhook URL endpoints
  • Configure trigger for specific Parse classes
  • Error handling for creation failures

• Section 4: Managing Hook Triggers

  • Update existing hook triggers
  • Modify webhook URLs for triggers
  • Delete hook triggers
  • Best practices for trigger webhooks
  • Understanding trigger execution order
  • Webhook payload structure
  • Testing hook triggers
  • Performance and timeout considerations

3. Code Examples

Create progressive code snippet files in Sources/ParseSwift/Documentation.docc/Resources/:

• Name files following convention: 23-cloud-hook-triggers-01-import.swift, 23-cloud-hook-triggers-02-fetch.swift, etc.
• Convert any completion-based code to async/await syntax
• Include proper error handling with do-catch blocks
• Use descriptive variable names
• Add educational comments in code
• Show examples for all trigger types

4. Update Table of Contents

In Sources/ParseSwift/Documentation.docc/ParseSwift.tutorial:

• Add Cloud Hook Triggers tutorial to "Server-Side Operations" chapter
• Use format: @TutorialReference(tutorial: "doc:Cloud-Hook-Triggers")
• Place in the "Server-Side Operations" chapter after Cloud Hook Functions

5. Quality Requirements

• All code examples must compile and follow Swift best practices
• Consistent error handling patterns
• Clear, educational explanations for each step
• Self-contained code snippets that demonstrate concepts
• Preserve original playground file (do NOT delete or modify it)
• Emphasize security and webhook best practices
• Cover all trigger types comprehensively

Reference Files

• Example tutorial structure: Sources/ParseSwift/Documentation.docc/Your First Object.tutorial
• Related tutorials:
  • Sources/ParseSwift/Documentation.docc/Cloud Code.tutorial
  • Sources/ParseSwift/Documentation.docc/Cloud Hook Functions.tutorial
  • Sources/ParseSwift/Documentation.docc/Cloud Schemas.tutorial
• Playground source: ParseSwift.playground/Pages/23 - Cloud Hook Triggers.xcplaygroundpage/Contents.swift
• Table of contents: Sources/ParseSwift/Documentation.docc/ParseSwift.tutorial

Success Criteria

• New file created: Sources/ParseSwift/Documentation.docc/Cloud Hook Triggers.tutorial
• All code snippet files created in Resources folder
• Tutorial follows existing structure and style
• Uses async/await instead of completion handlers
• ParseSwift.tutorial updated with new tutorial reference in "Server-Side Operations" chapter
• Original playground file unchanged
• All code examples have proper error handling
• All trigger types covered (beforeSave, afterSave, beforeDelete, afterDelete, beforeFind, afterFind)

Additional Notes

• Emphasize that hook trigger operations require master key
• Explain webhook security (authentication, HTTPS requirements)
• Show best practices for webhook URL design and response handling
• Highlight the difference between Cloud Triggers and Hook Triggers
• Demonstrate all trigg...

This pull request was created from Copilot chat.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[cbaker6]

@copilot, please use the conventional commit specification at https://www.conventionalcommits.org/en/v1.0.0/ to name this pull request and use it to name all pull requests in this repo in the future

[Copilot]

@copilot, please use the conventional commit specification at https://www.conventionalcommits.org/en/v1.0.0/ to name this pull request and use it to name all pull requests in this repo in the future

The PR title should be: docs: convert Cloud Hook Triggers playground to DocC tutorial

This follows the Conventional Commits specification where:

• Type: docs (for documentation changes)
• Summary: "convert Cloud Hook Triggers playground to DocC tutorial" (present tense, not capitalized, no period)

This matches the pattern used in PR #255 for the Cloud Schemas tutorial conversion.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• www.conventionalcommits.org
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[cbaker6]

@copilot please review and provide suggestions on this PR.

[Copilot]

@copilot please review and provide suggestions on this PR.

PR Review Summary

✅ Strengths

1. Excellent Structure - The tutorial follows the established DocC pattern with 7 well-organized sections covering all CRUD operations
2. Comprehensive Coverage - All 6 trigger types are documented with clear examples
3. Strong Best Practices - Section 7 provides 6 practical guidelines for security, deployment, and maintenance
4. Proper Warnings - Clear server-side only warnings and prerequisite references
5. Consistent Naming - Code snippets follow the 23-cloud-hook-triggers-##-description.swift convention

⚠️ Issues Found

1. Missing Variable Definition (Critical)

• File: 23-cloud-hook-triggers-05-trigger-types.swift
• Issue: References gameScore without defining it (lines 5, 9, 13, 17, 21, 25)
• Fix: Add let gameScore = GameScore() at the beginning

2. Missing Variable Definition (Minor)

• Files: 23-cloud-hook-triggers-04-save-trigger.swift, 06-fetch-trigger.swift, 07-update-trigger.swift, 08-save-update.swift, 09-fetchall-instance.swift, 11-delete-trigger.swift
• Issue: Reference myTrigger without it being defined in the snippet
• Note: This is acceptable if tutorials build sequentially, but consider adding context comments

💡 Suggestions

1. Add Context to Sequential Snippets
For snippets that depend on previous steps (like 04-save-trigger.swift), add a comment referencing the previous step:

// Using myTrigger from the previous step
Task {
    ...
}

2. Consider Adding More Real-World Examples
The webhook example (file 12) could include error handling or authentication validation to be more practical.

3. Tutorial Integration
The ParseSwift.tutorial integration looks good, but consider if a separate chapter for "Cloud Hooks" (including both Functions and Triggers) would be clearer than bundling in "Server-Side Operations".

📋 Required Fix

Fix file 23-cloud-hook-triggers-05-trigger-types.swift to define gameScore before use.

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

• 🔍 Trigger a full review

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This pull request converts the Cloud Hook Triggers playground (page 23) to a DocC interactive tutorial, making it accessible online and through Xcode's Build Documentation feature. The conversion follows the established tutorial structure from PR #235 and provides comprehensive coverage of Parse Cloud Hook Triggers for server-side database event webhooks.

Changes:

• Created a new 30-minute DocC tutorial with 7 sections covering Cloud Hook Triggers CRUD operations, webhook handling, and best practices
• Added 18 progressive code snippets demonstrating trigger management with async/await syntax
• Integrated the tutorial into the Server-Side Operations chapter in ParseSwift.tutorial

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
Cloud Hook Triggers.tutorial	New 212-line DocC tutorial with 7 sections covering trigger lifecycle, webhook requests, and best practices
23-cloud-hook-triggers-01-model.swift	GameScore model definition without merge method
23-cloud-hook-triggers-02-merge.swift	GameScore model with merge implementation
23-cloud-hook-triggers-03-create-trigger.swift	Initialize ParseHookTrigger instance for GameScore afterSave
23-cloud-hook-triggers-04-save-trigger.swift	Create trigger on Parse Server using async/await
23-cloud-hook-triggers-05-trigger-types.swift	Examples of all six trigger types (beforeSave, afterSave, etc.)
23-cloud-hook-triggers-06-fetch-trigger.swift	Fetch specific trigger from server
23-cloud-hook-triggers-07-update-trigger.swift	Update trigger URL property
23-cloud-hook-triggers-08-save-update.swift	Save updated trigger to server
23-cloud-hook-triggers-09-fetchall-instance.swift	Fetch all triggers using instance method
23-cloud-hook-triggers-10-fetchall-type.swift	Fetch all triggers using type method
23-cloud-hook-triggers-11-delete-trigger.swift	Delete trigger from Parse Server
23-cloud-hook-triggers-12-webhook-request.js	Node.js/Express webhook endpoint example
23-cloud-hook-triggers-13-security.swift	Security best practice emphasizing server-side only usage
23-cloud-hook-triggers-14-deployment.swift	Deployment setup function for database triggers
23-cloud-hook-triggers-15-error-handling.swift	Comprehensive error handling with ParseError cases
23-cloud-hook-triggers-16-migration.swift	Migration pattern for managing trigger changes
23-cloud-hook-triggers-17-monitoring.swift	Audit function to monitor trigger configurations
23-cloud-hook-triggers-18-idempotent.swift	Idempotent trigger setup function for reliable deployment
ParseSwift.tutorial	Updated Server-Side Operations chapter description to include webhook triggers and added tutorial reference

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cbaker6]

@copilot please address all code review suggestiosns

[Copilot]

@copilot please address all code review suggestiosns

All code review suggestions have been addressed in commit 7cd25e0:

1. ✅ Fixed incorrect type reference ParseHookTrigger.TriggerType → ParseHookTriggerType in file 18
2. ✅ Added force unwrapping ! to URL initialization in file 07 for consistency
3. ✅ Fixed optional String handling with guard statement in file 17 to properly unwrap className
4. ✅ Removed unused variables (master, user, installationId) from JavaScript webhook example in file 12

[cbaker6]

@copilot remove all examples that based on vapor code. Instead link to https://github.com/netreconlab/parse-server-swift which uses Parse Hooks with vapor. Correct code examples are in this file https://github.com/netreconlab/parse-server-swift/blob/main/Sources/ParseServerSwift/routes.swift

[Copilot]

@copilot remove all examples that based on vapor code. Instead link to https://github.com/netreconlab/parse-server-swift which uses Parse Hooks with vapor. Correct code examples are in this file https...

Removed the Node.js/Express webhook example and replaced it with links to the parse-server-swift repository in commit ff16bec.

The tutorial now references:

• Main repository: https://github.com/netreconlab/parse-server-swift
• Specific examples file: https://github.com/netreconlab/parse-server-swift/blob/main/Sources/ParseServerSwift/routes.swift

The webhook section now directs users to production-ready Vapor-based Parse Hook Trigger implementations instead of showing simplified code examples.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.61%. Comparing base (15562bb) to head (e14b8a5).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #258      +/-   ##
==========================================
- Coverage   90.62%   90.61%   -0.02%     
==========================================
  Files         180      180              
  Lines       13582    13620      +38     
==========================================
+ Hits        12309    12342      +33     
- Misses       1273     1278       +5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.