digiqagent 1.2.0

package/skills/postman-collection-generator/collection-patterns.md

@@ -0,0 +1,493 @@
+# Postman Collection Patterns
+
+Reference patterns for structuring Postman collections. Copy and adapt when generating collections.
+
+## Auth Flow — Login, Store Token, Use in Requests
+
+A complete authentication flow with token capture and reuse.
+
+### Login Request
+
+```json
+{
+  "name": "Login",
+  "event": [
+    {
+      "listen": "test",
+      "script": {
+        "type": "text/javascript",
+        "exec": [
+          "if (pm.response.code === 200) {",
+          "    const response = pm.response.json();",
+          "    pm.environment.set('authToken', response.accessToken || response.token);",
+          "    if (response.refreshToken) {",
+          "        pm.environment.set('refreshToken', response.refreshToken);",
+          "    }",
+          "    if (response.user) {",
+          "        pm.environment.set('userId', response.user.id);",
+          "        pm.environment.set('userEmail', response.user.email);",
+          "    }",
+          "    // Store expiry for auto-refresh logic",
+          "    if (response.expiresIn) {",
+          "        pm.environment.set('tokenExpiry', Date.now() + (response.expiresIn * 1000));",
+          "    }",
+          "}"
+        ]
+      }
+    }
+  ],
+  "request": {
+    "method": "POST",
+    "header": [
+      { "key": "Content-Type", "value": "application/json" }
+    ],
+    "url": {
+      "raw": "{{baseUrl}}/api/auth/login",
+      "host": ["{{baseUrl}}"],
+      "path": ["api", "auth", "login"]
+    },
+    "body": {
+      "mode": "raw",
+      "raw": "{\n  \"email\": \"admin@example.com\",\n  \"password\": \"SecureP@ss123\"\n}"
+    }
+  }
+}
+```
+
+### Register Request
+
+```json
+{
+  "name": "Register",
+  "event": [
+    {
+      "listen": "test",
+      "script": {
+        "type": "text/javascript",
+        "exec": [
+          "if (pm.response.code === 201) {",
+          "    const response = pm.response.json();",
+          "    pm.environment.set('newUserId', response.id || response.user?.id);",
+          "}"
+        ]
+      }
+    }
+  ],
+  "request": {
+    "method": "POST",
+    "header": [
+      { "key": "Content-Type", "value": "application/json" }
+    ],
+    "url": {
+      "raw": "{{baseUrl}}/api/auth/register",
+      "host": ["{{baseUrl}}"],
+      "path": ["api", "auth", "register"]
+    },
+    "body": {
+      "mode": "raw",
+      "raw": "{\n  \"name\": \"Jane Smith\",\n  \"email\": \"jane.smith@example.com\",\n  \"password\": \"SecureP@ss123\"\n}"
+    }
+  }
+}
+```
+
+### Refresh Token Request
+
+```json
+{
+  "name": "Refresh Token",
+  "event": [
+    {
+      "listen": "test",
+      "script": {
+        "type": "text/javascript",
+        "exec": [
+          "if (pm.response.code === 200) {",
+          "    const response = pm.response.json();",
+          "    pm.environment.set('authToken', response.accessToken || response.token);",
+          "    if (response.refreshToken) {",
+          "        pm.environment.set('refreshToken', response.refreshToken);",
+          "    }",
+          "}"
+        ]
+      }
+    }
+  ],
+  "request": {
+    "method": "POST",
+    "header": [
+      { "key": "Content-Type", "value": "application/json" }
+    ],
+    "url": {
+      "raw": "{{baseUrl}}/api/auth/refresh",
+      "host": ["{{baseUrl}}"],
+      "path": ["api", "auth", "refresh"]
+    },
+    "body": {
+      "mode": "raw",
+      "raw": "{\n  \"refreshToken\": \"{{refreshToken}}\"\n}"
+    }
+  }
+}
+```
+
+## CRUD Operation Ordering
+
+Follow this sequence within each resource folder for a natural workflow:
+
+```
+1. POST   /api/resources        → Create resource (capture ID)
+2. GET    /api/resources        → List resources (verify created item appears)
+3. GET    /api/resources/:id    → Get by ID (verify details)
+4. PUT    /api/resources/:id    → Update resource
+5. GET    /api/resources/:id    → Get by ID (verify update applied)
+6. DELETE /api/resources/:id    → Delete resource
+7. GET    /api/resources/:id    → Get by ID (verify 404)
+```
+
+### Create Request with ID Capture
+
+```json
+{
+  "name": "Create Product",
+  "event": [
+    {
+      "listen": "test",
+      "script": {
+        "type": "text/javascript",
+        "exec": [
+          "if (pm.response.code === 201) {",
+          "    const response = pm.response.json();",
+          "    const id = response.id || response.data?.id;",
+          "    pm.environment.set('productId', id);",
+          "    console.log('Created product with ID:', id);",
+          "}"
+        ]
+      }
+    }
+  ],
+  "request": {
+    "method": "POST",
+    "header": [
+      { "key": "Content-Type", "value": "application/json" },
+      { "key": "Authorization", "value": "Bearer {{authToken}}" }
+    ],
+    "url": {
+      "raw": "{{baseUrl}}/api/products",
+      "host": ["{{baseUrl}}"],
+      "path": ["api", "products"]
+    },
+    "body": {
+      "mode": "raw",
+      "raw": "{\n  \"name\": \"Wireless Bluetooth Headphones\",\n  \"description\": \"Premium noise-cancelling headphones with 30-hour battery\",\n  \"price\": 149.99,\n  \"category\": \"electronics\",\n  \"sku\": \"WBH-2025-001\"\n}"
+    }
+  }
+}
+```
+
+### Get by ID Using Captured Variable
+
+```json
+{
+  "name": "Get Product by ID",
+  "request": {
+    "method": "GET",
+    "header": [
+      { "key": "Authorization", "value": "Bearer {{authToken}}" }
+    ],
+    "url": {
+      "raw": "{{baseUrl}}/api/products/{{productId}}",
+      "host": ["{{baseUrl}}"],
+      "path": ["api", "products", "{{productId}}"]
+    }
+  }
+}
+```
+
+### Update Request
+
+```json
+{
+  "name": "Update Product",
+  "request": {
+    "method": "PUT",
+    "header": [
+      { "key": "Content-Type", "value": "application/json" },
+      { "key": "Authorization", "value": "Bearer {{authToken}}" }
+    ],
+    "url": {
+      "raw": "{{baseUrl}}/api/products/{{productId}}",
+      "host": ["{{baseUrl}}"],
+      "path": ["api", "products", "{{productId}}"]
+    },
+    "body": {
+      "mode": "raw",
+      "raw": "{\n  \"name\": \"Wireless Bluetooth Headphones Pro\",\n  \"price\": 179.99\n}"
+    }
+  }
+}
+```
+
+### Delete Request
+
+```json
+{
+  "name": "Delete Product",
+  "request": {
+    "method": "DELETE",
+    "header": [
+      { "key": "Authorization", "value": "Bearer {{authToken}}" }
+    ],
+    "url": {
+      "raw": "{{baseUrl}}/api/products/{{productId}}",
+      "host": ["{{baseUrl}}"],
+      "path": ["api", "products", "{{productId}}"]
+    }
+  }
+}
+```
+
+## Chained Request Patterns
+
+When one request depends on another's output, chain them with environment variables.
+
+### Pattern: Create Parent -> Create Child -> List Children
+
+```
+1. POST /api/projects         → capture {{projectId}}
+2. POST /api/projects/:id/tasks → capture {{taskId}}, uses {{projectId}}
+3. GET  /api/projects/:id/tasks → list tasks, uses {{projectId}}
+```
+
+**Create child with parent reference:**
+```json
+{
+  "name": "Create Task for Project",
+  "event": [
+    {
+      "listen": "test",
+      "script": {
+        "type": "text/javascript",
+        "exec": [
+          "if (pm.response.code === 201) {",
+          "    pm.environment.set('taskId', pm.response.json().id);",
+          "}"
+        ]
+      }
+    }
+  ],
+  "request": {
+    "method": "POST",
+    "header": [
+      { "key": "Content-Type", "value": "application/json" },
+      { "key": "Authorization", "value": "Bearer {{authToken}}" }
+    ],
+    "url": {
+      "raw": "{{baseUrl}}/api/projects/{{projectId}}/tasks",
+      "host": ["{{baseUrl}}"],
+      "path": ["api", "projects", "{{projectId}}", "tasks"]
+    },
+    "body": {
+      "mode": "raw",
+      "raw": "{\n  \"title\": \"Implement user authentication\",\n  \"priority\": \"high\",\n  \"assigneeId\": \"{{userId}}\"\n}"
+    }
+  }
+}
+```
+
+### Pattern: Dynamic Pre-Request Data Generation
+
+```json
+{
+  "name": "Create User with Unique Email",
+  "event": [
+    {
+      "listen": "prerequest",
+      "script": {
+        "type": "text/javascript",
+        "exec": [
+          "const timestamp = Date.now();",
+          "pm.environment.set('uniqueEmail', `user_${timestamp}@example.com`);",
+          "pm.environment.set('uniqueName', `TestUser_${timestamp}`);"
+        ]
+      }
+    },
+    {
+      "listen": "test",
+      "script": {
+        "type": "text/javascript",
+        "exec": [
+          "if (pm.response.code === 201) {",
+          "    pm.environment.set('createdUserId', pm.response.json().id);",
+          "}"
+        ]
+      }
+    }
+  ],
+  "request": {
+    "method": "POST",
+    "header": [
+      { "key": "Content-Type", "value": "application/json" }
+    ],
+    "url": {
+      "raw": "{{baseUrl}}/api/users",
+      "host": ["{{baseUrl}}"],
+      "path": ["api", "users"]
+    },
+    "body": {
+      "mode": "raw",
+      "raw": "{\n  \"name\": \"{{uniqueName}}\",\n  \"email\": \"{{uniqueEmail}}\",\n  \"password\": \"SecureP@ss123\"\n}"
+    }
+  }
+}
+```
+
+## File Upload Request
+
+### Single File Upload
+
+```json
+{
+  "name": "Upload Avatar",
+  "request": {
+    "method": "POST",
+    "header": [
+      { "key": "Authorization", "value": "Bearer {{authToken}}" }
+    ],
+    "url": {
+      "raw": "{{baseUrl}}/api/users/{{userId}}/avatar",
+      "host": ["{{baseUrl}}"],
+      "path": ["api", "users", "{{userId}}", "avatar"]
+    },
+    "body": {
+      "mode": "formdata",
+      "formdata": [
+        {
+          "key": "file",
+          "type": "file",
+          "src": "/path/to/avatar.png",
+          "description": "User avatar image (PNG or JPEG, max 5MB)"
+        },
+        {
+          "key": "description",
+          "value": "Profile avatar",
+          "type": "text"
+        }
+      ]
+    }
+  }
+}
+```
+
+### Multiple File Upload
+
+```json
+{
+  "name": "Upload Attachments",
+  "request": {
+    "method": "POST",
+    "header": [
+      { "key": "Authorization", "value": "Bearer {{authToken}}" }
+    ],
+    "url": {
+      "raw": "{{baseUrl}}/api/documents/upload",
+      "host": ["{{baseUrl}}"],
+      "path": ["api", "documents", "upload"]
+    },
+    "body": {
+      "mode": "formdata",
+      "formdata": [
+        {
+          "key": "files",
+          "type": "file",
+          "src": ["/path/to/doc1.pdf", "/path/to/doc2.pdf"]
+        },
+        {
+          "key": "folder",
+          "value": "invoices",
+          "type": "text"
+        }
+      ]
+    }
+  }
+}
+```
+
+## List with Query Parameters
+
+```json
+{
+  "name": "List Users (Filtered & Paginated)",
+  "request": {
+    "method": "GET",
+    "header": [
+      { "key": "Authorization", "value": "Bearer {{authToken}}" }
+    ],
+    "url": {
+      "raw": "{{baseUrl}}/api/users?page=1&limit=20&sortBy=createdAt&sortOrder=desc&status=active",
+      "host": ["{{baseUrl}}"],
+      "path": ["api", "users"],
+      "query": [
+        { "key": "page", "value": "1", "description": "Page number" },
+        { "key": "limit", "value": "20", "description": "Items per page" },
+        { "key": "sortBy", "value": "createdAt", "description": "Sort field" },
+        { "key": "sortOrder", "value": "desc", "description": "Sort direction (asc/desc)" },
+        { "key": "status", "value": "active", "description": "Filter by status" },
+        { "key": "search", "value": "", "description": "Search by name or email", "disabled": true }
+      ]
+    }
+  }
+}
+```
+
+## Collection-Level Pre-Request Script
+
+Apply to the collection root to run before every request:
+
+```javascript
+// Set timestamp for requests that need it
+pm.environment.set("currentTimestamp", new Date().toISOString());
+
+// Generate correlation ID for request tracing
+pm.environment.set("correlationId", pm.variables.replaceIn("{{$guid}}"));
+```
+
+## Folder Structure Template
+
+Standard folder hierarchy for a typical API:
+
+```json
+{
+  "item": [
+    {
+      "name": "Auth",
+      "item": [
+        { "name": "Register" },
+        { "name": "Login" },
+        { "name": "Refresh Token" },
+        { "name": "Logout" },
+        { "name": "Forgot Password" },
+        { "name": "Reset Password" }
+      ]
+    },
+    {
+      "name": "Users",
+      "item": [
+        { "name": "Create User" },
+        { "name": "List Users" },
+        { "name": "Get User by ID" },
+        { "name": "Update User" },
+        { "name": "Delete User" },
+        { "name": "Upload Avatar" }
+      ]
+    },
+    {
+      "name": "System",
+      "item": [
+        { "name": "Health Check" },
+        { "name": "Get API Version" }
+      ]
+    }
+  ]
+}
+```