npm - @ivannxbt/ai-config - Versions diffs - 0.1.0 - Mend

@ivannxbt/ai-config 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1428) hide show

package/.agents/skills/analytics-tracking/references/gtm-implementation.md ADDED Viewed

@@ -0,0 +1,390 @@
+# Google Tag Manager Implementation Reference
+Detailed guide for implementing tracking via Google Tag Manager.
+## Contents
+- Container Structure (tags, triggers, variables)
+- Naming Conventions
+- Data Layer Patterns
+- Common Tag Configurations (GA4 configuration tag, GA4 event tag, Facebook pixel)
+- Preview and Debug
+- Workspaces and Versioning
+- Consent Management
+- Advanced Patterns (tag sequencing, exception handling, custom JavaScript variables)
+## Container Structure
+### Tags
+Tags are code snippets that execute when triggered.
+**Common tag types:**
+- GA4 Configuration (base setup)
+- GA4 Event (custom events)
+- Google Ads Conversion
+- Facebook Pixel
+- LinkedIn Insight Tag
+- Custom HTML (for other pixels)
+### Triggers
+Triggers define when tags fire.
+**Built-in triggers:**
+- Page View: All Pages, DOM Ready, Window Loaded
+- Click: All Elements, Just Links
+- Form Submission
+- Scroll Depth
+- Timer
+- Element Visibility
+**Custom triggers:**
+- Custom Event (from dataLayer)
+- Trigger Groups (multiple conditions)
+### Variables
+Variables capture dynamic values.
+**Built-in (enable as needed):**
+- Click Text, Click URL, Click ID, Click Classes
+- Page Path, Page URL, Page Hostname
+- Referrer
+- Form Element, Form ID
+**User-defined:**
+- Data Layer variables
+- JavaScript variables
+- Lookup tables
+- RegEx tables
+- Constants
+---
+## Naming Conventions
+### Recommended Format
+```
+[Type] - [Description] - [Detail]
+Tags:
+GA4 - Event - Signup Completed
+GA4 - Config - Base Configuration
+FB - Pixel - Page View
+HTML - LiveChat Widget
+Triggers:
+Click - CTA Button
+Submit - Contact Form
+View - Pricing Page
+Custom - signup_completed
+Variables:
+DL - user_id
+JS - Current Timestamp
+LT - Campaign Source Map
+```
+---
+## Data Layer Patterns
+### Basic Structure
+```javascript
+// Initialize (in <head> before GTM)
+window.dataLayer = window.dataLayer || [];
+// Push event
+dataLayer.push({
+  'event': 'event_name',
+  'property1': 'value1',
+  'property2': 'value2'
+});
+```
+### Page Load Data
+```javascript
+// Set on page load (before GTM container)
+window.dataLayer = window.dataLayer || [];
+dataLayer.push({
+  'pageType': 'product',
+  'contentGroup': 'products',
+  'user': {
+    'loggedIn': true,
+    'userId': '12345',
+    'userType': 'premium'
+  }
+});
+```
+### Form Submission
+```javascript
+document.querySelector('#contact-form').addEventListener('submit', function() {
+  dataLayer.push({
+    'event': 'form_submitted',
+    'formName': 'contact',
+    'formLocation': 'footer'
+  });
+});
+```
+### Button Click
+```javascript
+document.querySelector('.cta-button').addEventListener('click', function() {
+  dataLayer.push({
+    'event': 'cta_clicked',
+    'ctaText': this.innerText,
+    'ctaLocation': 'hero'
+  });
+});
+```
+### E-commerce Events
+```javascript
+// Product view
+dataLayer.push({ ecommerce: null }); // Clear previous
+dataLayer.push({
+  'event': 'view_item',
+  'ecommerce': {
+    'items': [{
+      'item_id': 'SKU123',
+      'item_name': 'Product Name',
+      'price': 99.99,
+      'item_category': 'Category',
+      'quantity': 1
+    }]
+  }
+});
+// Add to cart
+dataLayer.push({ ecommerce: null });
+dataLayer.push({
+  'event': 'add_to_cart',
+  'ecommerce': {
+    'items': [{
+      'item_id': 'SKU123',
+      'item_name': 'Product Name',
+      'price': 99.99,
+      'quantity': 1
+    }]
+  }
+});
+// Purchase
+dataLayer.push({ ecommerce: null });
+dataLayer.push({
+  'event': 'purchase',
+  'ecommerce': {
+    'transaction_id': 'T12345',
+    'value': 99.99,
+    'currency': 'USD',
+    'tax': 5.00,
+    'shipping': 10.00,
+    'items': [{
+      'item_id': 'SKU123',
+      'item_name': 'Product Name',
+      'price': 99.99,
+      'quantity': 1
+    }]
+  }
+});
+```
+---
+## Common Tag Configurations
+### GA4 Configuration Tag
+**Tag Type:** Google Analytics: GA4 Configuration
+**Settings:**
+- Measurement ID: G-XXXXXXXX
+- Send page view: Checked (for pageviews)
+- User Properties: Add any user-level dimensions
+**Trigger:** All Pages
+### GA4 Event Tag
+**Tag Type:** Google Analytics: GA4 Event
+**Settings:**
+- Configuration Tag: Select your config tag
+- Event Name: {{DL - event_name}} or hardcode
+- Event Parameters: Add parameters from dataLayer
+**Trigger:** Custom Event with event name match
+### Facebook Pixel - Base
+**Tag Type:** Custom HTML
+```html
+<script>
+  !function(f,b,e,v,n,t,s)
+  {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
+  n.callMethod.apply(n,arguments):n.queue.push(arguments)};
+  if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
+  n.queue=[];t=b.createElement(e);t.async=!0;
+  t.src=v;s=b.getElementsByTagName(e)[0];
+  s.parentNode.insertBefore(t,s)}(window, document,'script',
+  'https://connect.facebook.net/en_US/fbevents.js');
+  fbq('init', 'YOUR_PIXEL_ID');
+  fbq('track', 'PageView');
+</script>
+```
+**Trigger:** All Pages
+### Facebook Pixel - Event
+**Tag Type:** Custom HTML
+```html
+<script>
+  fbq('track', 'Lead', {
+    content_name: '{{DL - form_name}}'
+  });
+</script>
+```
+**Trigger:** Custom Event - form_submitted
+---
+## Preview and Debug
+### Preview Mode
+1. Click "Preview" in GTM
+2. Enter site URL
+3. GTM debug panel opens at bottom
+**What to check:**
+- Tags fired on this event
+- Tags not fired (and why)
+- Variables and their values
+- Data layer contents
+### Debug Tips
+**Tag not firing:**
+- Check trigger conditions
+- Verify data layer push
+- Check tag sequencing
+**Wrong variable value:**
+- Check data layer structure
+- Verify variable path (nested objects)
+- Check timing (data may not exist yet)
+**Multiple firings:**
+- Check trigger uniqueness
+- Look for duplicate tags
+- Check tag firing options
+---
+## Workspaces and Versioning
+### Workspaces
+Use workspaces for team collaboration:
+- Default workspace for production
+- Separate workspaces for large changes
+- Merge when ready
+### Version Management
+**Best practices:**
+- Name every version descriptively
+- Add notes explaining changes
+- Review changes before publish
+- Keep production version noted
+**Version notes example:**
+```
+v15: Added purchase conversion tracking
+- New tag: GA4 - Event - Purchase
+- New trigger: Custom Event - purchase
+- New variables: DL - transaction_id, DL - value
+- Tested: Chrome, Safari, Mobile
+```
+---
+## Consent Management
+### Consent Mode Integration
+```javascript
+// Default state (before consent)
+gtag('consent', 'default', {
+  'analytics_storage': 'denied',
+  'ad_storage': 'denied'
+});
+// Update on consent
+function grantConsent() {
+  gtag('consent', 'update', {
+    'analytics_storage': 'granted',
+    'ad_storage': 'granted'
+  });
+}
+```
+### GTM Consent Overview
+1. Enable Consent Overview in Admin
+2. Configure consent for each tag
+3. Tags respect consent state automatically
+---
+## Advanced Patterns
+### Tag Sequencing
+**Setup tags to fire in order:**
+Tag Configuration > Advanced Settings > Tag Sequencing
+**Use cases:**
+- Config tag before event tags
+- Pixel initialization before tracking
+- Cleanup after conversion
+### Exception Handling
+**Trigger exceptions** - Prevent tag from firing:
+- Exclude certain pages
+- Exclude internal traffic
+- Exclude during testing
+### Custom JavaScript Variables
+```javascript
+// Get URL parameter
+function() {
+  var params = new URLSearchParams(window.location.search);
+  return params.get('campaign') || '(not set)';
+}
+// Get cookie value
+function() {
+  var match = document.cookie.match('(^|;) ?user_id=([^;]*)(;|$)');
+  return match ? match[2] : null;
+}
+// Get data from page
+function() {
+  var el = document.querySelector('.product-price');
+  return el ? parseFloat(el.textContent.replace('$', '')) : 0;
+}
+```

package/.agents/skills/appinsights-instrumentation/LICENSE.txt ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright 2025 (c) Microsoft Corporation.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE

package/.agents/skills/appinsights-instrumentation/SKILL.md ADDED Viewed

@@ -0,0 +1,72 @@
+---
+name: appinsights-instrumentation
+description: "Guidance for instrumenting webapps with Azure Application Insights. Provides telemetry patterns, SDK setup, and configuration references. USE FOR: how to instrument app, App Insights SDK, telemetry patterns, what is App Insights, Application Insights guidance, instrumentation examples, APM best practices. DO NOT USE FOR: adding App Insights to my app (use azure-prepare), add telemetry to my project (use azure-prepare), add monitoring (use azure-prepare). This skill provides guidance—azure-prepare orchestrates component changes."
+license: MIT
+metadata:
+  author: Microsoft
+  version: "1.0.0"
+---
+# AppInsights Instrumentation Guide
+This skill provides **guidance and reference material** for instrumenting webapps with Azure Application Insights.
+> **⛔ ADDING COMPONENTS?**
+>
+> If the user wants to **add App Insights to their app**, invoke **azure-prepare** instead.
+> This skill provides reference material—azure-prepare orchestrates the actual changes.
+## When to Use This Skill
+- User asks **how** to instrument (guidance, patterns, examples)
+- User needs SDK setup instructions
+- azure-prepare invokes this skill during research phase
+- User wants to understand App Insights concepts
+## When to Use azure-prepare Instead
+- User says "add telemetry to my app"
+- User says "add App Insights"
+- User wants to modify their project
+- Any request to change/add components
+## Prerequisites
+The app in the workspace must be one of these kinds
+- An ASP.NET Core app hosted in Azure
+- A Node.js app hosted in Azure
+## Guidelines
+### Collect context information
+Find out the (programming language, application framework, hosting) tuple of the application the user is trying to add telemetry support in. This determines how the application can be instrumented. Read the source code to make an educated guess. Confirm with the user on anything you don't know. You must always ask the user where the application is hosted (e.g. on a personal computer, in an Azure App Service as code, in an Azure App Service as container, in an Azure Container App, etc.).
+### Prefer auto-instrument if possible
+If the app is a C# ASP.NET Core app hosted in Azure App Service, use [AUTO guide](references/auto.md) to help user auto-instrument the app.
+### Manually instrument
+Manually instrument the app by creating the AppInsights resource and update the app's code.
+#### Create AppInsights resource
+Use one of the following options that fits the environment.
+- Add AppInsights to existing Bicep template. See [examples/appinsights.bicep](examples/appinsights.bicep) for what to add. This is the best option if there are existing Bicep template files in the workspace.
+- Use Azure CLI. See [scripts/appinsights.ps1](scripts/appinsights.ps1) for what Azure CLI command to execute to create the App Insights resource.
+No matter which option you choose, recommend the user to create the App Insights resource in a meaningful resource group that makes managing resources easier. A good candidate will be the same resource group that contains the resources for the hosted app in Azure.
+#### Modify application code
+- If the app is an ASP.NET Core app, see [ASPNETCORE guide](references/aspnetcore.md) for how to modify the C# code.
+- If the app is a Node.js app, see [NODEJS guide](references/nodejs.md) for how to modify the JavaScript/TypeScript code.
+- If the app is a Python app, see [PYTHON guide](references/python.md) for how to modify the Python code.
+## SDK Quick References
+- **OpenTelemetry Distro**: [Python](references/sdk/azure-monitor-opentelemetry-py.md) | [TypeScript](references/sdk/azure-monitor-opentelemetry-ts.md)
+- **OpenTelemetry Exporter**: [Python](references/sdk/azure-monitor-opentelemetry-exporter-py.md) | [Java](references/sdk/azure-monitor-opentelemetry-exporter-java.md)

package/.agents/skills/appinsights-instrumentation/examples/appinsights.bicep ADDED Viewed

@@ -0,0 +1,30 @@
+@description('Location for all resources')
+param location string = resourceGroup().location
+@description('Name for new Application Insights')
+param name string
+// Create Log Analytics Workspace
+resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2022-10-01' = {
+  name: '${name}-workspace'
+  location: location
+  properties: {
+    sku: {
+      name: 'PerGB2018'
+    }
+    retentionInDays: 30
+  }
+}
+// Create Application Insights
+resource applicationInsights 'Microsoft.Insights/components@2020-02-02' = {
+  name: name
+  location: location
+  kind: 'web'
+  properties: {
+    Application_Type: 'web'
+    WorkspaceResourceId: logAnalyticsWorkspace.id
+  }
+}
+output connectionString string = applicationInsights.properties.ConnectionString

package/.agents/skills/appinsights-instrumentation/references/aspnetcore.md ADDED Viewed

@@ -0,0 +1,29 @@
+## Modify code
+Make these necessary changes to the app.
+- Install client library
+```
+dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
+```
+- Configure the app to use Azure Monitor
+An ASP.NET Core app typically has a Program.cs file that "builds" the app. Find this file and apply these changes.
+  - Add `using Azure.Monitor.OpenTelemetry.AspNetCore;` at the top
+  - Before calling `builder.Build()`, add this line `builder.Services.AddOpenTelemetry().UseAzureMonitor();`.
+> Note: since we modified the code of the app, the app needs to be deployed to take effect.
+## Configure App Insights connection string
+The App Insights resource has a connection string. Add the connection string as an environment variable of the running app. You can use Azure CLI to query the connection string of the App Insights resource. See [scripts/appinsights.ps1](../scripts/appinsights.ps1) for what Azure CLI command to execute for querying the connection string.
+After getting the connection string, set this environment variable with its value.
+```
+"APPLICATIONINSIGHTS_CONNECTION_STRING={your_application_insights_connection_string}"
+```
+If the app has IaC template such as Bicep or terraform files representing its cloud instance, this environment variable should be added to the IaC template to be applied in each deployment. Otherwise, use Azure CLI to manually apply the environment variable to the cloud instance of the app. See [scripts/appinsights.ps1](../scripts/appinsights.ps1) for what Azure CLI command to execute for setting this environment variable.
+> Important: Don't modify appsettings.json. It was a deprecated way to configure App Insights. The environment variable is the new recommended way.

package/.agents/skills/appinsights-instrumentation/references/auto.md ADDED Viewed

@@ -0,0 +1,13 @@
+# Auto-instrument app
+Use Azure Portal to auto-instrument a webapp hosted in Azure App Service for App Insights without making any code changes. Only the following types of app can be auto-instrumented. See [supported environments and resource providers](https://learn.microsoft.com/azure/azure-monitor/app/codeless-overview#supported-environments-languages-and-resource-providers).
+- ASP.NET Core app hosted in Azure App Service
+- Node.js app hosted in Azure App Service
+Construct a url to bring the user to the Application Insights blade in Azure Portal for the App Service App.
+```
+https://portal.azure.com/#resource/subscriptions/{subscription_id}/resourceGroups/{resource_group_name}/providers/Microsoft.Web/sites/{app_service_name}/monitoringSettings
+```
+Use the context or ask the user to get the subscription_id, resource_group_name, and the app_service_name hosting the webapp.

package/.agents/skills/appinsights-instrumentation/references/nodejs.md ADDED Viewed

@@ -0,0 +1,28 @@
+## Modify code
+Make these necessary changes to the app.
+- Install client library
+```
+npm install @azure/monitor-opentelemetry
+```
+- Configure the app to use Azure Monitor
+A Node.js app typically has an entry file that is listed as the "main" property in package.json. Find this file and apply these changes in it.
+  - Require the client library at the top. `const { useAzureMonitor } = require("@azure/monitor-opentelemetry");`
+  - Call the setup method. `useAzureMonitor();`
+> Note: The setup method should be called as early as possible but it must be after the environment variables are configured since it needs the App Insights connection string from the environment variable. For example, if the app uses dotenv to load environment variables, the setup method should be called after it but before anything else.
+> Note: since we modified the code of the app, it needs to be deployed to take effect.
+## Configure App Insights connection string
+The App Insights resource has a connection string. Add the connection string as an environment variable of the running app. You can use Azure CLI to query the connection string of the App Insights resource. See [scripts/appinsights.ps1] for what Azure CLI command to execute for querying the connection string.
+After getting the connection string, set this environment variable with its value.
+```
+"APPLICATIONINSIGHTS_CONNECTION_STRING={your_application_insights_connection_string}"
+```
+If the app has IaC template such as Bicep or terraform files representing its cloud instance, this environment variable should be added to the IaC template to be applied in each deployment. Otherwise, use Azure CLI to manually apply the environment variable to the cloud instance of the app. See what Azure CLI command to execute for setting this environment variable.

package/.agents/skills/appinsights-instrumentation/references/python.md ADDED Viewed

@@ -0,0 +1,48 @@
+## Modify code
+Make these necessary changes to the app.
+- Install client library
+```
+pip install azure-monitor-opentelemetry
+```
+- Configure the app to use Azure Monitor
+Python applications send telemetry via the logger class in Python standard library. Create a module that configures and creates a logger that can send telemetry.
+```python
+import logging
+from azure.monitor.opentelemetry import configure_azure_monitor
+configure_azure_monitor(
+    logger_name="<your_logger_namespace>"
+)
+logger = logging.getLogger("<your_logger_namespace>")
+```
+> Note: since we modified the code of the app, it needs to be deployed to take effect.
+## Configure App Insights connection string
+The App Insights resource has a connection string. Add the connection string as an environment variable of the running app. You can use Azure CLI to query the connection string of the App Insights resource. See [scripts/appinsights.ps1] for what Azure CLI command to execute for querying the connection string.
+After getting the connection string, set this environment variable with its value.
+```
+"APPLICATIONINSIGHTS_CONNECTION_STRING={your_application_insights_connection_string}"
+```
+If the app has IaC template such as Bicep or terraform files representing its cloud instance, this environment variable should be added to the IaC template to be applied in each deployment. Otherwise, use Azure CLI to manually apply the environment variable to the cloud instance of the app. See what Azure CLI command to execute for setting this environment variable.
+## Send data
+Create a logger that is configured to send telemetry.
+```python
+logger = logging.getLogger("<your_logger_namespace>")
+logger.setLevel(logging.INFO)
+```
+Then send telemetry events by calling its logging methods.
+```python
+logger.info("info log")
+```

package/.agents/skills/appinsights-instrumentation/references/sdk/azure-monitor-opentelemetry-exporter-java.md ADDED Viewed

@@ -0,0 +1,31 @@
+# Azure Monitor OpenTelemetry Exporter — Java SDK Quick Reference
+> Condensed from **azure-monitor-opentelemetry-exporter-java**. Full patterns
+> (trace/metric/log export, spans, semantic conventions)
+> in the **azure-monitor-opentelemetry-exporter-java** plugin skill if installed.
+## Install
+```xml
+<dependency>
+    <groupId>com.azure</groupId>
+    <artifactId>azure-monitor-opentelemetry-exporter</artifactId>
+    <version>1.0.0-beta.x</version>
+</dependency>
+```
+> **DEPRECATED**: Migrate to `azure-monitor-opentelemetry-autoconfigure`.
+## Quick Start
+```java
+// Prefer autoconfigure instead:
+// <artifactId>azure-monitor-opentelemetry-autoconfigure</artifactId>
+```
+## Best Practices
+- Use autoconfigure — migrate to `azure-monitor-opentelemetry-autoconfigure`
+- Set meaningful span names — use descriptive operation names
+- Add relevant attributes — include contextual data for debugging
+- Handle exceptions — always record exceptions on spans
+- Use semantic conventions — follow OpenTelemetry semantic conventions
+- End spans in finally — ensure spans are always ended
+- Use try-with-resources — scope management with try-with-resources pattern

package/.agents/skills/appinsights-instrumentation/references/sdk/azure-monitor-opentelemetry-exporter-py.md ADDED Viewed

@@ -0,0 +1,22 @@
+# Azure Monitor OpenTelemetry Exporter — Python SDK Quick Reference
+> Condensed from **azure-monitor-opentelemetry-exporter-py**. Full patterns
+> (metric exporter, log exporter, offline storage, sovereign clouds)
+> in the **azure-monitor-opentelemetry-exporter-py** plugin skill if installed.
+## Install
+pip install azure-monitor-opentelemetry-exporter
+## Quick Start
+```python
+from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
+exporter = AzureMonitorTraceExporter()  # reads APPLICATIONINSIGHTS_CONNECTION_STRING
+```
+## Best Practices
+- Use BatchSpanProcessor for production (not SimpleSpanProcessor)
+- Use ApplicationInsightsSampler for consistent sampling across services
+- Enable offline storage for reliability in production
+- Use AAD authentication instead of instrumentation keys
+- Set export intervals appropriate for your workload
+- Use the distro (azure-monitor-opentelemetry) unless you need custom pipelines