Revise codelabs

AGENTS.md

@@ -0,0 +1,78 @@
+# 🤖 AGENTS.md
+
+## Purpose
+This file defines the operating model for AI agents and human contributors working on this repository. It establishes **goals, scope, and guardrails** so that automation produces consistent, high-quality outputs without scope creep or errors.
+
+---
+
+## 🎯 Core Objectives
+- Maintain **accuracy and consistency** across all documentation in this repo.  
+- Ensure **Codelabs**, **Cookbooks**, and **CLI docs** follow standardized workflows and DevRev guidelines.  
+- Automate repetitive editing tasks while respecting repo boundaries.  
+
+---
+
+## 📂 Scope of Work
+
+### ✅ Allowed Directories
+- `codelabs/` → 15 Codelabs, must follow standardized **Setup → Code → Run → Verify** structure.   
+
+### ❌ Out of Scope
+- Do not generate or modify **source code** in `code/` directories.  
+- Do not change **infrastructure configs** (`package.json`, `.github/`, `vercel.json`, etc.) unless explicitly instructed.  
+- Do not use **external knowledge** about DevRev or Snap-ins. Documentation must derive from repo content.  
+
+---
+
+## 🧭 Operating Guidelines
+
+### Documentation Rules
+- Always include **frontmatter** (title, description).  
+- Start visible content at **H2**.  
+- Use **Setup, Code, Run, Verify** in all Codelabs.  
+- Provide **full, untruncated code snippets**.  
+- Add **expected output** in Verify sections.  
+
+### Writing Standards
+- **Voice**: Developer-first, active, concise.  
+- **Terminology**: Use correct DevRev capitalization (`DevRev`, `snap-in`, `manifest.yaml`).  
+- **Formatting**:  
+  - Backticks for commands, file paths, code.  
+  - Lists for sequential actions.  
+  - Callouts for tips, warnings, errors.  
+
+---
+
+## 📋 Validation Protocol
+Before finalizing changes, agents must confirm:
+- [ ] All Codelabs have Setup → Code → Run → Verify flow.  
+- [ ] Code snippets and manifests are complete.  
+- [ ] Init, validate-manifest, and fixture creation covered in Setup.  
+- [ ] Terminology is consistent with DevRev style.  
+- [ ] Internal/external links are valid.  
+- [ ] No speculative or external content added.  
+
+---
+
+## 🛡️ Guardrails
+- **Ground Truth**: All factual claims must be based on files in this repo.  
+- **No Speculation**: If information is missing, leave a placeholder or flag for human review.  
+- **Consistency First**: Enforce standard formats across all docs.  
+- **Evidence Required**: Cite file paths and line numbers when referencing code.  
+
+---
+
+## 🚀 Execution Flow
+1. Identify target directory (`codelabs/`).  
+2. Apply **scope + writing guidelines**.  
+3. Revise or create documentation using repo content.  
+4. Run through **Validation Protocol**.  
+5. Commit with a descriptive message (e.g., `docs: revise codelab 03 with standardized structure`).  
+
+---
+
+## 📌 Success Definition
+- 100% of Codelabs revised to standardized format.  
+- Cookbook entries are short, targeted, and runnable.  
+- CLI docs map directly to actual code in repo.  
+- All docs are actionable, accurate, and consistent.

codelabs/1-starter.mdx

@@ -0,0 +1,273 @@
+---
+title: 'Starter Snap-in'
+description: 'A basic template for creating your own DevRev snap-ins, demonstrating fundamental structure and function registration.'
+---
+
+## Setup
+
+This section guides you on setting up a new snap-in project and explains the structure of this example.
+
+### Prerequisites
+
+- Node.js and `npm` installed.
+- A DevRev account with the CLI installed and configured.
+
+### 1. Initialize Your Project
+
+To create a new snap-in, run the following command in your terminal, replacing `<project_name>` with your desired project name:
+
+```bash
+devrev snap_in_version init <project_name>
+```
+
+This creates a new directory with a template structure for your snap-in.
+
+### 2. Validate the Manifest
+
+Before writing any code, it's a good practice to validate the template's `manifest.yaml` file. Run the following command from your project's root directory:
+
+```bash
+devrev snap_in_version validate-manifest manifest.yaml
+```
+
+### 3. Prepare Test Data
+
+For local testing, you need a sample event payload. This example includes a fixture file at `code/src/fixtures/function_1_event.json`. You can create similar files for your own functions.
+
+## Code
+
+The core logic of your snap-in resides in its functions. This starter example includes a basic function that logs the event payload it receives. The code is located in `1-starter/code/src/functions/function_1/index.ts`.
+
+```typescript
+/*
+ * Copyright (c) 2023 DevRev, Inc. All rights reserved.
+ */
+
+export const run = async (events: any[]) => {
+  /*
+  Put your code here and remove the log below
+  */
+
+  console.info('events', events);
+};
+
+export default run;
+```
+
+This example uses a function factory pattern (`src/function-factory.ts`) to dynamically load and execute functions. This allows you to add new functions without modifying the core logic of the snap-in.
+
+## Run
+
+To run the function locally, navigate to the `1-starter/code` directory and execute the following commands.
+
+1.  **Install dependencies:**
+    ```bash
+    npm install
+    ```
+
+2.  **Run the local test runner:**
+    ```bash
+    npm run start:watch -- --functionName=function_1 --fixturePath=function_1_event.json
+    ```
+
+## Verify
+
+After running the commands, you should see the following output in your console, confirming that the function executed successfully. The output contains the full event payload from the `function_1_event.json` fixture.
+
+```json
+info: events [
+  {
+    "context": {
+      "dev_oid": "don:identity:dvrv-us-1:devo/0",
+      "automation_id": "don:integration:dvrv-us-1:devo/0:automation/00000001-0001-0001-0001-00000001",
+      "snap_in_id": "don:integration:dvrv-us-1:devo/0:snap_in/00000001-0001-0001-0001-00000001",
+      "snap_in_version_id": "don:integration:dvrv-us-1:devo/0:snap_in_package/00000001-0001-0001-0001-00000001:snap_in_version/00000001-0001-0001-0001-00000001"
+    },
+    "execution_metadata": {
+      "request_id": "4QtCBSKJcKKqwQhoJKZvRQ",
+      "function_name": "foobar"
+    },
+    "input_data": {
+      "global_values": {
+        "message": "tokens",
+        "ticket_id": "don:core:dvrv-us-1:devo/0:product/1"
+      },
+      "event_sources": {},
+      "keyrings": {
+        "devrev" : ""
+      }
+    },
+    "payload": {
+      "id": "don:integration:dvrv-us-1:devo/0:webhook/WRVqEXT7:webhook_event/31WPF0QWh8M",
+      "timestamp": "2023-02-07T10:08:42.591611Z",
+      "type": "work_updated",
+      "unique_key": "ZG9uOmludGVncmF0aW9uOmR2cnYtdXMtMTpkZXZvLzhtNDZjcDdSOmV2ZW50X3NvdXJjZS8zMjAxMDIzOS00MjA5LTRjOGEtYjcyMy1hYmZkYjAyMzkxOGE=",
+      "webhook_id": "don:integration:dvrv-us-1:devo/0:webhook/WRVqEXT7",
+      "work_updated": {
+        "old_work": {
+          "applies_to_part": {
+            "display_id": "FEAT-5",
+            "id": "don:core:dvrv-us-1:devo/0:feature/5",
+            "id_v1": "don:DEV-0:feature:5",
+            "name": "Default Feature 5",
+            "type": "feature"
+          },
+          "body": "Install the PLuG widget into your application with just a few lines of code and immediately bring the voice of your customer to your entire team. \n\nYou can also test the PLuG widget by clicking DevRev Org settings (top left DevRev icon) -> Support -> Try out PLuG.\n\nFollow step by step guide and copy and paste code from the link here -> https://devrev.ai/docs/plug/installation",
+          "created_by": {
+            "display_handle": "devrev-bot",
+            "display_id": "SYSU-1",
+            "display_name": "devrev-bot",
+            "full_name": "DevRev Bot",
+            "id": "don:identity:dvrv-us-1:devo/0:sysu/1",
+            "id_v1": "don:DEV-0:sys_user:SYSU-1",
+            "type": "sys_user"
+          },
+          "created_date": "2023-01-31T12:04:25.946Z",
+          "custom_fields": null,
+          "display_id": "ISS-12",
+          "id": "don:core:dvrv-us-1:devo/0:issue/12",
+          "id_v1": "don:DEV-0:issue:12",
+          "links": [
+            {
+              "link_id": "don:core:dvrv-us-1:devo/0:link/11",
+              "link_id_v1": "don:DEV-0:link:11",
+              "link_type": "is_dependency_of",
+              "target": "don:core:dvrv-us-1:devo/0:ticket/4",
+              "target_object_type": "ticket",
+              "target_v1": "don:DEV-0:ticket:4"
+            }
+          ],
+          "modified_by": {
+            "display_handle": "devrev-bot",
+            "display_id": "SYSU-1",
+            "display_name": "devrev-bot",
+            "full_name": "DevRev Bot",
+            "id": "don:identity:dvrv-us-1:devo/0:sysu/1",
+            "id_v1": "don:DEV-0:sys_user:SYSU-1",
+            "type": "sys_user"
+          },
+          "modified_date": "2023-01-31T12:04:49.215Z",
+          "owned_by": [
+            {
+              "display_handle": "devrev-bot",
+              "display_id": "SYSU-1",
+              "display_name": "devrev-bot",
+              "full_name": "DevRev Bot",
+              "id": "don:identity:dvrv-us-1:devo/0:sysu/1",
+              "id_v1": "don:DEV-0:sys_user:SYSU-1",
+              "type": "sys_user"
+            }
+          ],
+          "priority": "p1",
+          "stage": {
+            "name": "next",
+            "ordinal": 3000
+          },
+          "state": "open",
+          "stock_schema_fragment": "don:core:dvrv-us-1:stock_sf/292711",
+          "tags": [
+            {
+              "id": {
+                "display_id": "TAG-1",
+                "id": "don:core:dvrv-us-1:devo/0:tag/1",
+                "id_v1": "don:DEV-0:tag:1",
+                "name": ""
+              },
+              "tag": {
+                "display_id": "TAG-1",
+                "id": "don:core:dvrv-us-1:devo/0:tag/1",
+                "id_v1": "don:DEV-0:tag:1",
+                "name": ""
+              }
+            }
+          ],
+          "title": "'Install PLuG Today!' - Needs Dev Attention",
+          "type": "issue"
+        },
+        "work": {
+          "applies_to_part": {
+            "display_id": "FEAT-5",
+            "id": "don:core:dvrv-us-1:devo/0:feature/5",
+            "id_v1": "don:DEV-0:feature:5",
+            "name": "Default Feature 5",
+            "type": "feature"
+          },
+          "body": "Install the PLuG widget into your application with just a few lines of code and immediately bring the voice of your customer to your entire team. \n\nYou can also test the PLuG widget by clicking DevRev Org settings (top left DevRev icon) -> Support -> Try out PLuG.\n\nFollow step by step guide and copy and paste code from the link here -> https://devrev.ai/docs/plug/installation",
+          "created_by": {
+            "display_handle": "devrev-bot",
+            "display_id": "SYSU-1",
+            "display_name": "devrev-bot",
+            "full_name": "DevRev Bot",
+            "id": "don:identity:dvrv-us-1:devo/0:sysu/1",
+            "id_v1": "don:DEV-0:sys_user:SYSU-1",
+            "type": "sys_user"
+          },
+          "created_date": "2023-01-31T12:04:25.946Z",
+          "custom_fields": null,
+          "display_id": "ISS-12",
+          "id": "don:core:dvrv-us-1:devo/0:issue/12",
+          "id_v1": "don:DEV-0:issue:12",
+          "links": [
+            {
+              "link_id": "don:core:dvrv-us-1:devo/0:link/11",
+              "link_id_v1": "don:DEV-0:link:11",
+              "link_type": "is_dependency_of",
+              "target": "don:core:dvrv-us-1:devo/0:ticket/4",
+              "target_object_type": "ticket",
+              "target_v1": "don:DEV-0:ticket:4"
+            }
+          ],
+          "modified_by": {
+            "display_handle": "i-dev-user",
+            "display_id": "DEVU-2",
+            "display_name": "i-dev-user",
+            "email": "i-dev-user@devrev.ai",
+            "full_name": "Dev User",
+            "id": "don:identity:dvrv-us-1:devo/0:devu/2",
+            "id_v1": "don:DEV-0:dev_user:DEVU-2",
+            "state": "active",
+            "type": "dev_user"
+          },
+          "modified_date": "2023-02-07T10:08:09.59Z",
+          "owned_by": [
+            {
+              "display_handle": "devrev-bot",
+              "display_id": "SYSU-1",
+              "display_name": "devrev-bot",
+              "full_name": "DevRev Bot",
+              "id": "don:identity:dvrv-us-1:devo/0:sysu/1",
+              "id_v1": "don:DEV-0:sys_user:SYSU-1",
+              "type": "sys_user"
+            }
+          ],
+          "priority": "p1",
+          "stage": {
+            "name": "next",
+            "ordinal": 3000
+          },
+          "state": "open",
+          "stock_schema_fragment": "don:core:dvrv-us-1:stock_sf/292711",
+          "tags": [
+            {
+              "id": {
+                "display_id": "TAG-1",
+                "id": "don:core:dvrv-us-1:devo/0:tag/1",
+                "id_v1": "don:DEV-0:tag:1",
+                "name": ""
+              },
+              "tag": {
+                "display_id": "TAG-1",
+                "id": "don:core:dvrv-us-1:devo/0:tag/1",
+                "id_v1": "don:DEV-0:tag:1",
+                "name": ""
+              }
+            }
+          ],
+          "title": "'Install PLuG Today!' - Needs Dev Attention",
+          "type": "issue"
+        }
+      }
+    }
+  }
+]
+```