@aifabrix/builder 2.7.0 → 2.9.0

package/integration/hubspot/README.md

@@ -0,0 +1,136 @@
+# HubSpot CRM Integration
+
+HubSpot CRM external system integration with companies, contacts, and deals datasources.
+
+## Overview
+
+This integration connects to HubSpot CRM API and exposes companies, contacts, and deals data via the AI Fabrix Dataplane. Data is automatically synced and made available for querying via MCP/OpenAPI.
+
+## Files
+
+- `variables.yaml` - Application configuration with externalIntegration block
+- `hubspot-deploy.json` - External system definition with OAuth2 authentication
+- `hubspot-deploy-company.json` - Companies datasource with field mappings
+- `hubspot-deploy-contact.json` - Contacts datasource with field mappings
+- `hubspot-deploy-deal.json` - Deals datasource with field mappings
+- `env.template` - Environment variables template with kv:// references
+
+## Setup
+
+### 1. Configure OAuth2 Credentials
+
+1. Register an OAuth2 app in HubSpot:
+   - Go to HubSpot Settings → Integrations → Private Apps
+   - Create a new private app
+   - Grant scopes:
+     - `crm.objects.companies.read`
+     - `crm.objects.companies.write`
+     - `crm.objects.contacts.read`
+     - `crm.objects.contacts.write`
+     - `crm.objects.deals.read`
+     - `crm.objects.deals.write`
+
+2. Set credentials via Miso Controller or Dataplane portal:
+   - Navigate to the HubSpot external system configuration
+   - Enter OAuth2 Client ID and Client Secret
+   - Values are automatically stored in Key Vault by the platform
+   - No manual Key Vault operations required
+
+**Note:** The platform manages Key Vault storage automatically. You only need to provide values via the interface.
+
+### 2. Validate Configuration
+
+```bash
+aifabrix validate hubspot
+```
+
+### 3. Deploy
+
+```bash
+# Login to controller
+aifabrix login --controller https://controller.aifabrix.ai --method device --environment dev
+
+# Register application
+aifabrix app register hubspot --environment dev
+
+# Deploy entire system
+aifabrix deploy hubspot --controller https://controller.aifabrix.ai --environment dev
+
+# Or deploy individual datasources for testing
+aifabrix datasource deploy hubspot-company --environment dev --file integration/hubspot/hubspot-deploy-company.json
+aifabrix datasource deploy hubspot-contact --environment dev --file integration/hubspot/hubspot-deploy-contact.json
+aifabrix datasource deploy hubspot-deal --environment dev --file integration/hubspot/hubspot-deploy-deal.json
+```
+
+## Field Mappings
+
+HubSpot uses a nested properties structure. Field mappings transform this to flat, normalized fields:
+
+**HubSpot structure:**
+```json
+{
+  "properties": {
+    "name": { "value": "Acme Corp" },
+    "country": { "value": "us" }
+  }
+}
+```
+
+**Normalized structure:**
+```json
+{
+  "name": "Acme Corp",
+  "country": "US"
+}
+```
+
+Transformations applied:
+- `trim` - Remove whitespace
+- `toLower` - Convert to lowercase (for domains, emails)
+- `toUpper` - Convert to uppercase (for country codes)
+
+## Datasources
+
+### Companies (`hubspot-company`)
+- **Resource Type:** `customer`
+- **Access Fields:** `country`, `domain` (for ABAC filtering)
+- **Fields:** `id`, `name`, `domain`, `country`, `city`, `industry`, `website`, `phone`, `createdAt`, `updatedAt`
+
+### Contacts (`hubspot-contact`)
+- **Resource Type:** `contact`
+- **Access Fields:** `email`, `country` (for ABAC filtering)
+- **Fields:** `id`, `firstName`, `lastName`, `email`, `phone`, `company`, `jobTitle`, `address`, `city`, `country`, `createdAt`, `updatedAt`
+
+### Deals (`hubspot-deal`)
+- **Resource Type:** `deal`
+- **Access Fields:** `stage`, `pipeline` (for ABAC filtering)
+- **Fields:** `id`, `dealName`, `amount`, `currency`, `stage`, `pipeline`, `closeDate`, `dealType`, `associatedCompany`, `associatedContacts`, `createdAt`, `updatedAt`
+
+## OpenAPI Operations
+
+All datasources expose full CRUD operations:
+- `list` - GET `/crm/v3/objects/{entity}`
+- `get` - GET `/crm/v3/objects/{entity}/{id}`
+- `create` - POST `/crm/v3/objects/{entity}`
+- `update` - PATCH `/crm/v3/objects/{entity}/{id}`
+- `delete` - DELETE `/crm/v3/objects/{entity}/{id}`
+
+RBAC permissions are auto-generated: `hubspot.company.list`, `hubspot.company.get`, etc.
+
+## Verification
+
+```bash
+# List datasources
+aifabrix datasource list --environment dev
+
+# Validate specific datasource
+aifabrix datasource validate hubspot-company --environment dev
+```
+
+## Documentation
+
+- [External Systems Guide](../../docs/EXTERNAL-SYSTEMS.md) - Complete guide with examples
+- [CLI Reference](../../docs/CLI-REFERENCE.md) - All commands
+- [Configuration Reference](../../docs/CONFIGURATION.md) - Config file details
+
+

package/integration/hubspot/env.template

@@ -0,0 +1,9 @@
+# HubSpot OAuth2 Configuration
+# These values are set via the Miso Controller interface or Dataplane portal
+# Values are stored in Key Vault automatically by the platform
+
+CLIENTID=kv://hubspot-clientidKeyVault
+CLIENTSECRET=kv://hubspot-clientsecretKeyVault
+TOKENURL=https://api.hubapi.com/oauth/v1/token
+REDIRECT_URI=kv://hubspot-redirect-uriKeyVault
+

package/integration/hubspot/hubspot-deploy-company.json

@@ -0,0 +1,200 @@
+{
+  "key": "hubspot-company",
+  "displayName": "HubSpot Company",
+  "description": "HubSpot companies datasource with field mappings for CRM company data",
+  "systemKey": "hubspot",
+  "entityKey": "company",
+  "resourceType": "customer",
+  "enabled": true,
+  "version": "1.0.0",
+  "metadataSchema": {
+    "type": "object",
+    "properties": {
+      "id": {
+        "type": "string"
+      },
+      "properties": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "domain": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "country": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "city": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "industry": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "website": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "phone": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "createdate": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "hs_lastmodifieddate": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "required": ["id", "properties"]
+  },
+  "fieldMappings": {
+    "accessFields": ["country", "domain"],
+    "fields": {
+      "id": {
+        "expression": "{{id}}",
+        "type": "string",
+        "description": "Unique company identifier",
+        "required": true
+      },
+      "name": {
+        "expression": "{{properties.name.value}} | trim",
+        "type": "string",
+        "description": "Company name",
+        "required": false
+      },
+      "domain": {
+        "expression": "{{properties.domain.value}} | toLower | trim",
+        "type": "string",
+        "description": "Company domain for ABAC filtering",
+        "required": false
+      },
+      "country": {
+        "expression": "{{properties.country.value}} | toUpper | trim",
+        "type": "string",
+        "description": "Country code for ABAC filtering",
+        "required": false
+      },
+      "city": {
+        "expression": "{{properties.city.value}} | trim",
+        "type": "string",
+        "description": "City name",
+        "required": false
+      },
+      "industry": {
+        "expression": "{{properties.industry.value}} | trim",
+        "type": "string",
+        "description": "Industry classification",
+        "required": false
+      },
+      "website": {
+        "expression": "{{properties.website.value}} | trim",
+        "type": "string",
+        "description": "Company website URL",
+        "required": false
+      },
+      "phone": {
+        "expression": "{{properties.phone.value}} | trim",
+        "type": "string",
+        "description": "Phone number",
+        "required": false
+      },
+      "createdAt": {
+        "expression": "{{properties.createdate.value}}",
+        "type": "string",
+        "description": "Creation timestamp",
+        "required": false
+      },
+      "updatedAt": {
+        "expression": "{{properties.hs_lastmodifieddate.value}}",
+        "type": "string",
+        "description": "Last modification timestamp",
+        "required": false
+      }
+    }
+  },
+  "exposed": {
+    "fields": ["id", "name", "domain", "country", "city", "industry", "website", "phone", "createdAt", "updatedAt"],
+    "description": "Exposed fields for HubSpot companies"
+  },
+  "openapi": {
+    "enabled": true,
+    "documentKey": "hubspot-v3",
+    "baseUrl": "https://api.hubapi.com",
+    "operations": {
+      "list": {
+        "operationId": "getCompanies",
+        "method": "GET",
+        "path": "/crm/v3/objects/companies"
+      },
+      "get": {
+        "operationId": "getCompany",
+        "method": "GET",
+        "path": "/crm/v3/objects/companies/{companyId}"
+      },
+      "create": {
+        "operationId": "createCompany",
+        "method": "POST",
+        "path": "/crm/v3/objects/companies"
+      },
+      "update": {
+        "operationId": "updateCompany",
+        "method": "PATCH",
+        "path": "/crm/v3/objects/companies/{companyId}"
+      },
+      "delete": {
+        "operationId": "deleteCompany",
+        "method": "DELETE",
+        "path": "/crm/v3/objects/companies/{companyId}"
+      }
+    },
+    "autoRbac": true
+  }
+}
+
+

package/integration/hubspot/hubspot-deploy-contact.json

@@ -0,0 +1,228 @@
+{
+  "key": "hubspot-contact",
+  "displayName": "HubSpot Contact",
+  "description": "HubSpot contacts datasource with field mappings for CRM contact data",
+  "systemKey": "hubspot",
+  "entityKey": "contact",
+  "resourceType": "contact",
+  "enabled": true,
+  "version": "1.0.0",
+  "metadataSchema": {
+    "type": "object",
+    "properties": {
+      "id": {
+        "type": "string"
+      },
+      "properties": {
+        "type": "object",
+        "properties": {
+          "firstname": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "lastname": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "email": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "phone": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "company": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "jobtitle": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "address": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "city": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "country": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "createdate": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          },
+          "hs_lastmodifieddate": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "required": ["id", "properties"]
+  },
+  "fieldMappings": {
+    "accessFields": ["email", "country"],
+    "fields": {
+      "id": {
+        "expression": "{{id}}",
+        "type": "string",
+        "description": "Unique contact identifier",
+        "required": true
+      },
+      "firstName": {
+        "expression": "{{properties.firstname.value}} | trim",
+        "type": "string",
+        "description": "First name",
+        "required": false
+      },
+      "lastName": {
+        "expression": "{{properties.lastname.value}} | trim",
+        "type": "string",
+        "description": "Last name",
+        "required": false
+      },
+      "email": {
+        "expression": "{{properties.email.value}} | toLower | trim",
+        "type": "string",
+        "description": "Email address for ABAC filtering",
+        "required": false
+      },
+      "phone": {
+        "expression": "{{properties.phone.value}} | trim",
+        "type": "string",
+        "description": "Phone number",
+        "required": false
+      },
+      "company": {
+        "expression": "{{properties.company.value}} | trim",
+        "type": "string",
+        "description": "Associated company name",
+        "required": false
+      },
+      "jobTitle": {
+        "expression": "{{properties.jobtitle.value}} | trim",
+        "type": "string",
+        "description": "Job title",
+        "required": false
+      },
+      "address": {
+        "expression": "{{properties.address.value}} | trim",
+        "type": "string",
+        "description": "Street address",
+        "required": false
+      },
+      "city": {
+        "expression": "{{properties.city.value}} | trim",
+        "type": "string",
+        "description": "City name",
+        "required": false
+      },
+      "country": {
+        "expression": "{{properties.country.value}} | toUpper | trim",
+        "type": "string",
+        "description": "Country code for ABAC filtering",
+        "required": false
+      },
+      "createdAt": {
+        "expression": "{{properties.createdate.value}}",
+        "type": "string",
+        "description": "Creation timestamp",
+        "required": false
+      },
+      "updatedAt": {
+        "expression": "{{properties.hs_lastmodifieddate.value}}",
+        "type": "string",
+        "description": "Last modification timestamp",
+        "required": false
+      }
+    }
+  },
+  "exposed": {
+    "fields": ["id", "firstName", "lastName", "email", "phone", "company", "jobTitle", "address", "city", "country", "createdAt", "updatedAt"],
+    "description": "Exposed fields for HubSpot contacts"
+  },
+  "openapi": {
+    "enabled": true,
+    "documentKey": "hubspot-v3",
+    "baseUrl": "https://api.hubapi.com",
+    "operations": {
+      "list": {
+        "operationId": "getContacts",
+        "method": "GET",
+        "path": "/crm/v3/objects/contacts"
+      },
+      "get": {
+        "operationId": "getContact",
+        "method": "GET",
+        "path": "/crm/v3/objects/contacts/{contactId}"
+      },
+      "create": {
+        "operationId": "createContact",
+        "method": "POST",
+        "path": "/crm/v3/objects/contacts"
+      },
+      "update": {
+        "operationId": "updateContact",
+        "method": "PATCH",
+        "path": "/crm/v3/objects/contacts/{contactId}"
+      },
+      "delete": {
+        "operationId": "deleteContact",
+        "method": "DELETE",
+        "path": "/crm/v3/objects/contacts/{contactId}"
+      }
+    },
+    "autoRbac": true
+  }
+}
+
+