matimo-examples 0.1.0-alpha.8 → 0.1.0-alpha.9

package/hubspot/README.md

@@ -0,0 +1,316 @@
+# HubSpot Tools Examples
+
+Example directory contains **3 example patterns** showing different ways to use Matimo's HubSpot tools:
+1. **Factory Pattern** - Direct SDK execution (simplest)
+2. **Decorator Pattern** - Class-based with @tool decorators
+3. **LangChain Pattern** - AI-driven with OpenAI agent
+
+All examples are **fully working** and demonstrate real HubSpot operations (contacts, companies, products, invoices, etc.).
+
+## 🚀 Quick Start
+
+### 1. Create a HubSpot Service Key
+
+1. Go to your HubSpot workspace
+2. Click **Settings** (gear icon) → **Integrations** → **Service Keys**
+3. Click **Create service key**
+4. Enter a name like "Matimo Integration"
+5. Select required scopes
+
+### 2. Configure Required Scopes
+
+Select these scopes for full functionality:
+
+**Required Scopes:**
+```
+crm.objects.contacts.read        - Read contacts
+crm.objects.contacts.write       - Create/update contacts
+crm.objects.companies.read       - Read companies
+crm.objects.companies.write      - Create/update companies
+crm.objects.products.read        - Read products
+crm.objects.products.write       - Create/update products
+crm.objects.invoices.read        - Read invoices
+crm.objects.invoices.write       - Create/update invoices
+crm.objects.deals.read           - Read deals
+crm.objects.deals.write          - Create/update deals
+crm.objects.leads.read           - Read leads
+crm.objects.leads.write          - Create/update leads
+crm.objects.line_items.read      - Read line items
+crm.objects.line_items.write     - Create/update line items
+```
+
+### 3. Copy Your Service Key
+
+Once created, copy the **Service Key** (starts with `pat-na1-` or `pat-eu1-`)
+
+### 4. Set Up Environment
+
+Create a `.env` file in `examples/tools/`:
+
+```env
+MATIMO_HUBSPOT_API_KEY=pat-na1-your-service-key-here
+OPENAI_API_KEY=sk-your-openai-key-here
+```
+
+The `OPENAI_API_KEY` is only required for the LangChain example.
+
+### 5. Run Examples
+
+```bash
+# Factory Pattern (simplest, direct API calls)
+pnpm hubspot:factory
+
+# Decorator Pattern (class-based OOP approach)
+pnpm hubspot:decorator
+
+# LangChain Pattern (AI-driven agent with OpenAI)
+pnpm hubspot:langchain
+```
+
+## 📚 Examples Overview
+
+### 1. Factory Pattern (`hubspot-factory.ts`)
+
+**Best for:** Scripts, quick tests, CLI tools
+
+**What it does:**
+- ✅ Direct tool execution with `matimo.execute()`
+- ✅ Creates contacts, companies, products, invoices
+- ✅ Lists existing resources
+- ✅ Retrieves specific records by ID
+- ✅ Simplest implementation
+
+**Run it:**
+```bash
+pnpm hubspot:factory
+```
+
+**Key Code:**
+```typescript
+const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+// Create a contact
+const contact = await matimo.execute('hubspot-create-contact', {
+  email: 'john@example.com',
+  firstname: 'John',
+  lastname: 'Doe'
+});
+
+// List contacts
+const contacts = await matimo.execute('hubspot-list-contacts', {
+  limit: 10,
+  properties: ['email', 'firstname', 'lastname']
+});
+
+// Create a company
+const company = await matimo.execute('hubspot-create-company', {
+  name: 'Acme Corp',
+  domain: 'acme.com'
+});
+```
+
+**File:** [hubspot-factory.ts](hubspot-factory.ts)
+
+### 2. Decorator Pattern (`hubspot-decorator.ts`)
+
+**Best for:** Object-oriented design, class-based applications
+
+**What it does:**
+- ✅ Class methods decorated with `@tool`
+- ✅ Automatic tool execution via decorators
+- ✅ Multiple operations in organized class
+- ✅ Creates contacts, companies, products, invoices
+- ✅ OOP-friendly approach
+
+**Run it:**
+```bash
+pnpm hubspot:decorator
+```
+
+**Key Code:**
+```typescript
+import { setGlobalMatimoInstance, tool } from '@matimo/core';
+
+const matimo = await MatimoInstance.init({ autoDiscover: true });
+setGlobalMatimoInstance(matimo);
+
+class HubSpotAgent {
+  @tool('hubspot-create-contact')
+  async createContact(email: string, firstname: string, lastname: string) {
+    // Decorator auto-executes the tool
+  }
+
+  @tool('hubspot-create-company')
+  async createCompany(name: string, domain: string) {
+    // Also auto-executed
+  }
+
+  @tool('hubspot-list-contacts')
+  async listContacts(limit: number, properties: string[]) {
+    // Decorator handles execution
+  }
+}
+
+const agent = new HubSpotAgent();
+await agent.createContact('john@example.com', 'John', 'Doe');
+await agent.createCompany('Acme Corp', 'acme.com');
+const contacts = await agent.listContacts(10, ['email', 'firstname', 'lastname']);
+```
+
+**File:** [hubspot-decorator.ts](hubspot-decorator.ts)
+
+### 3. LangChain Pattern (`hubspot-langchain.ts`)
+
+**Best for:** AI-driven workflows, autonomous agents, multi-step reasoning
+
+**What it does:**
+- ✅ Real AI agent using OpenAI (GPT-4o-mini)
+- ✅ LLM decides which tools to use based on natural language
+- ✅ LLM generates parameters from context
+- ✅ Autonomous tool execution and result processing
+- ✅ Natural language conversation with the agent
+- ✅ Multi-step workflows with reasoning
+
+**Prerequisites:**
+- Requires `OPENAI_API_KEY` set in `.env`
+- Requires `@langchain/openai` and `langchain` dependencies
+
+**Run it:**
+```bash
+pnpm hubspot:langchain
+```
+
+**Key Code:**
+```typescript
+import { createAgent } from 'langchain';
+import { ChatOpenAI } from '@langchain/openai';
+import { convertToolsToLangChain } from '@matimo/core';
+
+const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+// Get HubSpot tools
+const hubspotTools = matimo.listTools()
+  .filter(t => t.name.startsWith('hubspot-'));
+
+// Convert to LangChain format
+const langchainTools = await convertToolsToLangChain(
+  hubspotTools,
+  matimo
+);
+
+// Create LLM-powered agent
+const model = new ChatOpenAI({ modelName: 'gpt-4o-mini' });
+const agent = await createAgent({ model, tools: langchainTools });
+
+// Natural language requests - LLM decides which tools to use
+const response = await agent.invoke({
+  messages: [{
+    role: 'user',
+    content: 'Create a new contact named John Smith with email john@example.com'
+  }]
+});
+
+console.log(response.messages[response.messages.length - 1].content);
+```
+
+**Agent Examples:**
+```
+User: "Create a new contact for John Smith with email john@example.com"
+Agent: "I'll create a new contact with that information..." [calls hubspot-create-contact]
+Agent: "Done! Created contact with ID 123456"
+
+User: "Add a new company called TechCorp"
+Agent: "I'll add TechCorp to the system..." [calls hubspot-create-company]
+Agent: "Company TechCorp has been created with ID 789012"
+
+User: "How many contacts do we have?"
+Agent: "Let me check..." [calls hubspot-list-contacts]
+Agent: "You have 47 contacts in the system"
+
+User: "Create a product called Premium Suite for $299.99"
+Agent: "I'll create that product..." [calls hubspot-create-product]
+Agent: "Product Premium Suite created with ID 345678"
+
+User: "Generate an invoice"
+Agent: "I'll create an invoice..." [calls hubspot-create-invoice]
+Agent: "Invoice created with ID 567890"
+```
+
+**File:** [hubspot-langchain.ts](hubspot-langchain.ts)
+
+## 🔧 Supported Operations
+
+All examples work with these HubSpot operations:
+
+| Operation | Tool Name | Example |
+|-----------|-----------|---------|
+| **Create Contact** | `hubspot-create-contact` | Create a new contact |
+| **Get Contact** | `hubspot-get-contact` | Retrieve contact details |
+| **List Contacts** | `hubspot-list-contacts` | List all contacts |
+| **Create Company** | `hubspot-create-company` | Create a new company |
+| **Get Company** | `hubspot-get-company` | Retrieve company details |
+| **Create Product** | `hubspot-create-product` | Create a new product |
+| **Create Invoice** | `hubspot-create-invoice` | Create a new invoice |
+| **List Products** | `hubspot-list-products` | List all products |
+
+See [packages/hubspot/README.md](../../packages/hubspot/README.md) for complete tool list and documentation.
+
+## 📖 Full Documentation
+
+For comprehensive documentation, see:
+
+- **Package Docs:** [packages/hubspot/README.md](../../packages/hubspot/README.md)
+- **HubSpot API Reference:** https://developers.hubspot.com/docs/api-reference/crm-objects
+- **Service Keys Guide:** https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/account-service-keys
+- **Matimo Documentation:** [docs/getting-started/](../../docs/getting-started/)
+
+## 🛠️ Troubleshooting
+
+### "MATIMO_HUBSPOT_API_KEY not set"
+```bash
+# Solution: Set your HubSpot service key
+export MATIMO_HUBSPOT_API_KEY="pat-na1-your-key-here"
+```
+
+### "Property does not exist"
+Your service key might not have the required scopes. Go to HubSpot Settings → Integrations → Service Keys and verify all 14 CRM scopes are enabled.
+
+### "Unauthorized" (401 error)
+- Verify your service key is correct (check for typos)
+- Verify scopes include the required permissions
+- Try rotating the key: Settings → Service Keys → your key → Rotate
+
+### "OpenAI API error" (LangChain example)
+```bash
+# Solution: Ensure OpenAI API key is set
+export OPENAI_API_KEY="sk-your-openai-key-here"
+
+# Get one from: https://platform.openai.com/account/api-keys
+```
+
+### "Module not found: @langchain/openai"
+```bash
+# Solution: Install LangChain dependencies
+pnpm install
+```
+
+## 🚀 Next Steps
+
+1. **Try each example:**
+   - Start with Factory (simplest)
+   - Try Decorator (OOP style)
+   - Explore LangChain (AI-driven)
+
+2. **Build your own:**
+   - Combine patterns as needed
+   - Add more HubSpot tools from [full list](../../packages/hubspot/README.md)
+   - Integrate with your own application
+
+3. **Advanced:**
+   - Use multi-step workflows with LangChain agent
+   - Chain multiple HubSpot operations
+   - Combine HubSpot tools with other Matimo providers (Slack, Gmail, etc.)
+
+---
+
+**Questions?** See [CONTRIBUTING.md](../../CONTRIBUTING.md) or review the Matimo core documentation.

package/hubspot/hubspot-decorator.ts

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * ============================================================================
+ * HUBSPOT TOOLS - DECORATOR PATTERN EXAMPLE
+ * ============================================================================
+ *
+ * PATTERN: Class Decorator Pattern
+ * ─────────────────────────────────────────────────────────────────────────
+ * Tool execution via @tool decorators - class-based approach.
+ *
+ * Use this pattern when:
+ * ✅ Building agents with class-based structure
+ * ✅ Encapsulating tool logic in methods
+ * ✅ Integration with LangChain or CrewAI
+ * ✅ Domain-specific agent classes
+ *
+ * SETUP:
+ * ─────────────────────────────────────────────────────────────────────────
+ * 1. Create .env file:
+ *    MATIMO_HUBSPOT_API_KEY=pat-na1-xxxxxxxxxxxx
+ *
+ * 2. Get a Service Key:
+ *    - Go to: https://app.hubapi.com/settings/integrations/service-keys
+ *    - Click "Create service key"
+ *    - Select required scopes
+ *    - Copy the service key
+ *
+ * USAGE:
+ * ─────────────────────────────────────────────────────────────────────────
+ *   export MATIMO_HUBSPOT_API_KEY=pat-na1-xxxx
+ *   npm run hubspot:decorator
+ *
+ * ============================================================================
+ */
+
+import 'dotenv/config';
+import { MatimoInstance, setGlobalMatimoInstance, tool } from '@matimo/core';
+
+/**
+ * Run decorator pattern examples
+ */
+async function runDecoratorPatternExamples() {
+  console.info('\n╔════════════════════════════════════════════════════════╗');
+  console.info('║     HubSpot Tools - Decorator Pattern                  ║');
+  console.info('║     (Class-based approach with decorators)             ║');
+  console.info('╚════════════════════════════════════════════════════════╝\n');
+
+  const apiKey = process.env.MATIMO_HUBSPOT_API_KEY;
+  if (!apiKey) {
+    console.error('❌ Error: MATIMO_HUBSPOT_API_KEY not set in .env');
+    console.error('\nSetup Instructions:');
+    console.error('1. Create a Service Key in HubSpot');
+    console.error('2. Set environment variable: export MATIMO_HUBSPOT_API_KEY="pat-na1-xxxx"');
+    console.error('3. Or create .env: echo "MATIMO_HUBSPOT_API_KEY=pat-na1-xxxx" > .env');
+    process.exit(1);
+  }
+
+  console.info(`🔑 Service Key is set`);
+  console.info('🚀 Initializing Matimo...\n');
+
+  // Initialize Matimo with auto-discovery
+  const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+  // Set global instance for decorators
+  setGlobalMatimoInstance(matimo);
+
+  const allTools = matimo.listTools();
+  console.info(`✅ Loaded ${allTools.length} total tools\n`);
+
+  const hubspotTools = allTools.filter((t) => t.name.startsWith('hubspot-'));
+  console.info(`🔧 Found ${hubspotTools.length} HubSpot tools\n`);
+
+  class HubSpotAgent {
+    @tool('hubspot-create-contact')
+    async createContact(email: string, firstname?: string, lastname?: string): Promise<unknown> {
+      // Decorator auto-executes via matimo
+      return undefined;
+    }
+
+    @tool('hubspot-get-contact')
+    async getContact(id: string, properties?: string[]): Promise<unknown> {
+      // Decorator auto-executes via matimo
+      return undefined;
+    }
+
+    @tool('hubspot-create-company')
+    async createCompany(name: string, domain?: string): Promise<unknown> {
+      // Decorator auto-executes via matimo
+      return undefined;
+    }
+
+    @tool('hubspot-list-contacts')
+    async listContacts(limit?: number, after?: string, properties?: string[]): Promise<unknown> {
+      // Decorator auto-executes via matimo
+      return undefined;
+    }
+
+    @tool('hubspot-create-product')
+    async createProduct(name: string, description?: string, price?: number): Promise<unknown> {
+      // Decorator auto-executes via matimo
+      return undefined;
+    }
+
+    @tool('hubspot-create-invoice')
+    async createInvoice(hs_currency?: string): Promise<unknown> {
+      // Decorator auto-executes via matimo
+      return undefined;
+    }
+  }
+
+  console.info('════════════════════════════════════════════════════════════\n');
+  console.info('Running Decorator Pattern Examples:');
+  console.info('════════════════════════════════════════════════════════════\n');
+
+  try {
+    const agent = new HubSpotAgent();
+
+    // Example 1: Create contact via decorator
+    console.info('1️⃣  Creating contact via decorator...');
+    const contact = await agent.createContact(
+      `decorator-test-${Date.now()}@example.com`,
+      'Decorator',
+      'Test'
+    );
+    const contactId = (contact as any).data?.id;
+    console.info(`   ✅ Contact created: ${contactId}\n`);
+
+    // Example 2: Get contact via decorator
+    if (contactId) {
+      console.info('2️⃣  Retrieving contact via decorator...');
+      const contactData = await agent.getContact(contactId, ['email', 'firstname', 'lastname']);
+      const props = (contactData as any).data?.properties || {};
+      console.info(`   ✅ Retrieved contact: ${props.email}\n`);
+    }
+
+    // Example 3: Create company via decorator
+    console.info('3️⃣  Creating company via decorator...');
+    const company = await agent.createCompany(`Company ${Date.now()}`, 'example.com');
+    const companyId = (company as any).data?.id;
+    console.info(`   ✅ Company created: ${companyId}\n`);
+
+    // Example 4: List contacts via decorator
+    console.info('4️⃣  Listing contacts via decorator...');
+    const contactsList = await agent.listContacts(5, undefined, ['email', 'firstname', 'lastname']);
+    const count = ((contactsList as any).data?.results || []).length;
+    console.info(`   ✅ Found ${count} contacts\n`);
+
+    // Example 5: Create product via decorator
+    console.info('5️⃣  Creating product via decorator...');
+    const product = await agent.createProduct(
+      `Product ${Date.now()}`,
+      'Created via decorator pattern',
+      19999
+    );
+    const productId = (product as any).data?.id;
+    console.info(`   ✅ Product created: ${productId}\n`);
+
+    // Example 6: Create invoice via decorator
+    console.info('6️⃣  Creating invoice via decorator...');
+    const invoice = await agent.createInvoice('USD');
+    const invoiceId = (invoice as any).data?.id;
+    console.info(`   ✅ Invoice created: ${invoiceId}\n`);
+
+    console.info('════════════════════════════════════════════════════════════');
+    console.info('✨ Decorator Pattern Example Complete!');
+    console.info('════════════════════════════════════════════════════════════\n');
+    console.info('Summary of agent actions:');
+    console.info(`  • Created contact: ${contactId}`);
+    console.info(`  • Retrieved contact: ${contactId}`);
+    console.info(`  • Created company: ${companyId}`);
+    console.info(`  • Found contacts: ${count}`);
+    console.info(`  • Created product: ${productId}`);
+    console.info(`  • Created invoice: ${invoiceId}\n`);
+  } catch (error) {
+    console.error('❌ Error:', error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+runDecoratorPatternExamples().catch(console.error);

package/hubspot/hubspot-factory.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * ============================================================================
+ * HUBSPOT TOOLS - FACTORY PATTERN EXAMPLE
+ * ============================================================================
+ *
+ * PATTERN: SDK Factory Pattern
+ * ─────────────────────────────────────────────────────────────────────────
+ * Direct tool execution via MatimoInstance - the simplest way to use tools.
+ *
+ * Use this pattern when:
+ * ✅ Building simple scripts or CLI tools
+ * ✅ Direct API calls without abstraction
+ * ✅ Quick prototyping
+ * ✅ One-off tool execution
+ *
+ * SETUP:
+ * ─────────────────────────────────────────────────────────────────────────
+ * 1. Create .env file:
+ *    MATIMO_HUBSPOT_API_KEY=pat-na1-xxxxxxxxxxxx
+ *
+ * 2. Get a Service Key:
+ *    - Go to: https://app.hubapi.com/settings/integrations/service-keys
+ *    - Click "Create service key"
+ *    - Select required scopes (contacts, companies, deals, tickets, etc.)
+ *    - Copy the service key
+ *
+ * USAGE:
+ * ─────────────────────────────────────────────────────────────────────────
+ *   export MATIMO_HUBSPOT_API_KEY=pat-na1-xxxx
+ *   npm run hubspot:factory
+ *
+ * AVAILABLE TOOLS (50 TOTAL):
+ * ─────────────────────────────────────────────────────────────────────────
+ * Contacts (5): create, get, update, delete, list
+ * Companies (5): create, get, update, delete, list
+ * Deals (5): create, get, update, delete, list
+ * Tickets (5): create, get, update, delete, list
+ * Leads (5): create, get, update, delete, list
+ * Line Items (5): create, get, update, delete, list
+ * Invoices (5): create, get, update, delete, list
+ * Orders (5): create, get, update, delete, list
+ * Products (5): create, get, update, delete, list
+ * Custom Objects (5): create, get, update, delete, list
+ *
+ * ============================================================================
+ */
+
+import 'dotenv/config';
+import { MatimoInstance } from '@matimo/core';
+
+/**
+ * Run factory pattern examples
+ */
+async function runFactoryPatternExamples() {
+  console.info('\n╔════════════════════════════════════════════════════════╗');
+  console.info('║     HubSpot Tools - Factory Pattern                    ║');
+  console.info('║     (Direct execution - simplest approach)             ║');
+  console.info('╚════════════════════════════════════════════════════════╝\n');
+
+  const apiKey = process.env.MATIMO_HUBSPOT_API_KEY;
+  if (!apiKey) {
+    console.error('❌ Error: MATIMO_HUBSPOT_API_KEY not set in .env');
+    console.error('\nSetup Instructions:');
+    console.error('1. Create a Service Key in HubSpot:');
+    console.error('   Go to: Settings → Integrations → Service Keys');
+    console.error('   Click "Create service key"');
+    console.error('   Select all required scopes (contacts, companies, deals, etc.)');
+    console.error('   Copy the service key\n');
+    console.error('2. Create .env file:');
+    console.error('   echo "MATIMO_HUBSPOT_API_KEY=pat-na1-xxxx" > .env\n');
+    console.error('3. Or set environment variable:');
+    console.error('   export MATIMO_HUBSPOT_API_KEY="pat-na1-xxxx"\n');
+    console.error(
+      '📚 Docs: https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/account-service-keys'
+    );
+    process.exit(1);
+  }
+
+  console.info(`🔑 Service Key is set`);
+  console.info('🚀 Initializing Matimo...\n');
+
+  // Initialize Matimo with auto-discovery to find all @matimo/* packages
+  const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+  const allTools = matimo.listTools();
+  console.info(`✅ Loaded ${allTools.length} total tools\n`);
+
+  // Get HubSpot tools
+  const hubspotTools = allTools.filter((t) => t.name.startsWith('hubspot-'));
+  console.info(`🔧 Found ${hubspotTools.length} HubSpot tools`);
+  console.info(`   - Contacts: 5 tools`);
+  console.info(`   - Companies: 5 tools`);
+  console.info(`   - Deals: 5 tools`);
+  console.info(`   - Tickets: 5 tools`);
+  console.info(`   - Leads: 5 tools`);
+  console.info(`   - Line Items: 5 tools`);
+  console.info(`   - Invoices: 5 tools`);
+  console.info(`   - Orders: 5 tools`);
+  console.info(`   - Products: 5 tools`);
+  console.info(`   - Custom Objects: 5 tools\n`);
+
+  console.info('════════════════════════════════════════════════════════════\n');
+  console.info('Running Examples:');
+  console.info('════════════════════════════════════════════════════════════\n');
+
+  try {
+    // Example 1: Create a contact
+    console.info('1️⃣  Creating contact...');
+    const createContactResult = await matimo.execute('hubspot-create-contact', {
+      email: `factory-test-${Date.now()}@example.com`,
+      firstname: 'Factory',
+      lastname: 'Test',
+    });
+    const contactId = (createContactResult as any).data?.id;
+    console.info(`   ✅ Contact created: ${contactId}\n`);
+
+    // Example 2: Get the contact
+    let contactEmail = '';
+    if (contactId) {
+      console.info('2️⃣  Retrieving contact...');
+      const getContactResult = await matimo.execute('hubspot-get-contact', {
+        id: contactId,
+        properties: ['email', 'firstname', 'lastname', 'createdate'],
+      });
+      const contactData = (getContactResult as any).data?.properties || {};
+      contactEmail = contactData.email || '';
+      console.info(`   ✅ Retrieved contact`);
+      console.info(`      Email: ${contactData.email}`);
+      console.info(`      Name: ${contactData.firstname} ${contactData.lastname}`);
+      console.info(`      Created: ${contactData.createdate}\n`);
+    }
+
+    // Example 3: Create a company
+    console.info('3️⃣  Creating company...');
+    const createCompanyResult = await matimo.execute('hubspot-create-company', {
+      name: `Test Company ${Date.now()}`,
+      domain: 'example.com',
+    });
+    const companyId = (createCompanyResult as any).data?.id;
+    console.info(`   ✅ Company created: ${companyId}\n`);
+
+    // Example 4: List contacts with pagination
+    console.info('4️⃣  Listing contacts (limit 5)...');
+    const listContactsResult = await matimo.execute('hubspot-list-contacts', {
+      limit: 5,
+      properties: ['email', 'firstname', 'lastname'],
+    });
+    const contactsList = (listContactsResult as any).data?.results || [];
+    console.info(`   ✅ Found ${contactsList.length} contacts\n`);
+
+    // Example 5: Create a product
+    console.info('5️⃣  Creating product...');
+    const createProductResult = await matimo.execute('hubspot-create-product', {
+      name: `Test Product ${Date.now()}`,
+      description: 'A sample product for testing',
+      price: 9999,
+    });
+    const productId = (createProductResult as any).data?.id;
+    console.info(`   ✅ Product created: ${productId}\n`);
+
+    // Example 6: Create an invoice
+    console.info('6️⃣  Creating invoice...');
+    const createInvoiceResult = await matimo.execute('hubspot-create-invoice', {
+      hs_currency: 'USD',
+    });
+    const invoiceId = (createInvoiceResult as any).data?.id;
+    console.info(`   ✅ Invoice created: ${invoiceId}\n`);
+
+    console.info('════════════════════════════════════════════════════════════');
+    console.info('✨ Factory Pattern Example Complete!');
+    console.info('════════════════════════════════════════════════════════════\n');
+    console.info('Summary of actions:');
+    console.info(`  • Created contact: ${contactId}`);
+    if (contactEmail) {
+      console.info(`  • Retrieved contact: ${contactEmail}`);
+    }
+    console.info(`  • Created company: ${companyId}`);
+    console.info(`  • Listed contacts: ${contactsList.length} found`);
+    console.info(`  • Created product: ${productId}`);
+    console.info(`  • Created invoice: ${invoiceId}\n`);
+  } catch (error) {
+    console.error('❌ Error:', error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+runFactoryPatternExamples().catch(console.error);

package/hubspot/hubspot-langchain.ts

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/**
+ * ============================================================================
+ * HUBSPOT TOOLS - LANGCHAIN AI AGENT EXAMPLE
+ * ============================================================================
+ *
+ * PATTERN: True AI Agent with OpenAI + LangChain
+ * ─────────────────────────────────────────────────────────────────────────
+ * This is a REAL AI agent that:
+ * 1. Takes natural language user requests
+ * 2. Uses OpenAI LLM (GPT-4o-mini) to decide which HubSpot tools to use
+ * 3. Generates appropriate parameters based on context
+ * 4. Executes tools autonomously
+ * 5. Processes results and responds naturally
+ *
+ * Use this pattern when:
+ * ✅ Building true autonomous AI agents
+ * ✅ LLM should decide which tools to use
+ * ✅ Complex workflows with LLM reasoning
+ * ✅ Multi-step agentic processes
+ * ✅ User gives high-level instructions (not low-level API calls)
+ *
+ * SETUP:
+ * ─────────────────────────────────────────────────────────────────────────
+ * 1. Create .env file:
+ *    MATIMO_HUBSPOT_API_KEY=pat-na1-xxxxxxxxxxxxx
+ *    OPENAI_API_KEY=sk-xxxxxxxxxxxxx
+ *
+ * 2. Install dependencies:
+ *    npm install
+ *
+ * USAGE:
+ * ─────────────────────────────────────────────────────────────────────────
+ *   export MATIMO_HUBSPOT_API_KEY=pat-na1-xxxx
+ *   export OPENAI_API_KEY=sk-xxxx
+ *   npm run hubspot:langchain
+ *
+ * WHAT IT DOES:
+ * ─────────────────────────────────────────────────────────────────────────
+ * This example shows an AI agent that can:
+ * 1. Create contacts in HubSpot
+ * 2. Create companies
+ * 3. List existing contacts
+ * 4. Create products
+ * 5. Create invoices
+ * 6. Respond naturally in conversation style
+ *
+ * Example conversation:
+ *   User: "Create a new contact with email test@example.com"
+ *   AI Agent: "I'll create a new contact with that email..."
+ *   [AI Agent calls hubspot-create-contact tool]
+ *   AI Agent: "Done! Contact created with ID xxxxxx."
+ *
+ * ============================================================================
+ */
+
+import 'dotenv/config';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { createAgent } from 'langchain';
+import { ChatOpenAI } from '@langchain/openai';
+import { MatimoInstance, convertToolsToLangChain, ToolDefinition } from '@matimo/core';
+
+/**
+ * Run AI Agent with HubSpot tools
+ * The agent receives natural language requests and decides which HubSpot tools to use
+ */
+async function runHubSpotAIAgent() {
+  console.info('\n╔════════════════════════════════════════════════════════╗');
+  console.info('║     HubSpot AI Agent - LangChain + OpenAI             ║');
+  console.info('║     True autonomous agent with LLM reasoning          ║');
+  console.info('╚════════════════════════════════════════════════════════╝\n');
+
+  // Check required environment variables
+  const hubspotKey = process.env.MATIMO_HUBSPOT_API_KEY;
+  if (!hubspotKey) {
+    console.error('❌ Error: MATIMO_HUBSPOT_API_KEY not set in .env');
+    console.info('   Go to: https://app.hubapi.com/settings/integrations/service-keys');
+    console.info('   Create a service key and copy it');
+    process.exit(1);
+  }
+
+  const openaiKey = process.env.OPENAI_API_KEY;
+  if (!openaiKey) {
+    console.error('❌ Error: OPENAI_API_KEY not set in .env');
+    console.info('   Set it: export OPENAI_API_KEY="sk-..."');
+    console.info('   Get one from: https://platform.openai.com/account/api-keys');
+    process.exit(1);
+  }
+
+  console.info(`🔑 HubSpot Service Key is set`);
+  console.info(`🔑 OpenAI API Key is set`);
+  console.info(`🤖 Using OpenAI (GPT-4o-mini) as the AI agent\n`);
+
+  try {
+    // Initialize Matimo with auto-discovery
+    console.info('🚀 Initializing Matimo...');
+    const matimo = await MatimoInstance.init({ autoDiscover: true });
+
+    // Get HubSpot tools and convert to LangChain format
+    console.info('💼 Loading HubSpot tools...');
+    const matimoTools = matimo.listTools();
+    const hubspotTools = matimoTools.filter((t) => t.name.startsWith('hubspot-'));
+    console.info(`✅ Loaded ${hubspotTools.length} HubSpot tools\n`);
+
+    // Select key HubSpot tools for the agent
+    const keyHubSpotTools = hubspotTools.filter((t) =>
+      [
+        'hubspot-create-contact',
+        'hubspot-get-contact',
+        'hubspot-list-contacts',
+        'hubspot-create-company',
+        'hubspot-create-product',
+        'hubspot-create-invoice',
+      ].includes(t.name)
+    );
+
+    // ✅ Convert Matimo tools to LangChain format
+    console.info('🔧 Converting tools to LangChain format...');
+    const langchainTools = await convertToolsToLangChain(
+      keyHubSpotTools as ToolDefinition[],
+      matimo,
+      {
+        MATIMO_HUBSPOT_API_KEY: hubspotKey,
+      }
+    );
+
+    console.info(`✅ Converted ${langchainTools.length} tools\n`);
+
+    // Initialize OpenAI LLM
+    console.info('🤖 Initializing OpenAI (GPT-4o-mini) LLM...');
+    const model = new ChatOpenAI({
+      modelName: 'gpt-4o-mini',
+      temperature: 0.7,
+    });
+
+    // Create agent
+    console.info('🔧 Creating agent...\n');
+    const agent = await createAgent({
+      model,
+      tools: langchainTools as any[], // Type casting for LangChain tools
+    });
+
+    // Define agent tasks (natural language requests)
+    const userRequests = [
+      {
+        title: 'Example 1: Create a new contact',
+        request:
+          'Create a new contact for a prospect named John Smith with email john.smith@company.com',
+      },
+      {
+        title: 'Example 2: Create a company',
+        request: 'Add a new company called TechCorp for tracking in HubSpot',
+      },
+      {
+        title: 'Example 3: Create a product',
+        request:
+          'Create a new product called "Premium Analytics Suite" priced at $299.99 with description "Advanced analytics for enterprise use"',
+      },
+      {
+        title: 'Example 4: List contacts',
+        request: 'How many contacts do we have in HubSpot? Show me the first 5 with their emails.',
+      },
+      {
+        title: 'Example 5: Create an invoice',
+        request: 'Generate a new invoice in USD for billing',
+      },
+    ];
+
+    console.info('🧪 Running AI Agent Tasks');
+    console.info('═'.repeat(60));
+
+    // Run each task through the agent
+    for (const task of userRequests) {
+      console.info(`\n${task.title}`);
+      console.info('─'.repeat(60));
+      console.info(`👤 User: "${task.request}"\n`);
+
+      try {
+        const response = await agent.invoke({
+          messages: [
+            {
+              role: 'user',
+              content: task.request,
+            },
+          ],
+        });
+
+        // Get the last message from the agent
+        const lastMessage = response.messages[response.messages.length - 1];
+        if (lastMessage) {
+          if (typeof lastMessage.content === 'string') {
+            console.info(`🤖 Agent: ${lastMessage.content}\n`);
+          } else {
+            console.info(`🤖 Agent:`, lastMessage.content, '\n');
+          }
+        }
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        console.info(`⚠️  Agent error: ${errorMsg}\n`);
+      }
+    }
+
+    console.info('═'.repeat(60));
+    console.info('✨ AI Agent Examples Complete!\n');
+    console.info('Key Features:');
+    console.info('  ✅ Real LLM (OpenAI) decides which tools to use');
+    console.info('  ✅ Natural language requests, not API calls');
+    console.info('  ✅ LLM generates tool parameters based on context');
+    console.info('  ✅ Agentic reasoning and decision-making');
+    console.info('  ✅ Multi-step workflows with tool chaining\n');
+  } catch (error) {
+    console.error('❌ Error:', error instanceof Error ? error.message : String(error));
+    if (error instanceof Error && error.stack) {
+      console.error('Stack:', error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Run the AI agent
+runHubSpotAIAgent().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "matimo-examples",
-  "version": "0.1.0-alpha.8",
+  "version": "0.1.0-alpha.9",
   "description": "Matimo SDK examples - Factory Pattern, Decorator Pattern, and LangChain integration with Slack and Gmail",
   "type": "module",
   "dependencies": {
@@ -9,11 +9,12 @@
     "langchain": "^1.2.16",
     "dotenv": "^17.2.3",
     "zod": "^4.3.6",
-    "matimo": "0.1.0-alpha.8",
-    "@matimo/postgres": "0.1.0-alpha.8",
-    "@matimo/slack": "0.1.0-alpha.8",
-    "@matimo/github": "0.1.0-alpha.8",
-    "@matimo/gmail": "0.1.0-alpha.8"
+    "matimo": "0.1.0-alpha.9",
+    "@matimo/slack": "0.1.0-alpha.9",
+    "@matimo/gmail": "0.1.0-alpha.9",
+    "@matimo/postgres": "0.1.0-alpha.9",
+    "@matimo/hubspot": "0.1.0-alpha.9",
+    "@matimo/github": "0.1.0-alpha.9"
   },
   "devDependencies": {
     "@types/node": "^25.1.0",
@@ -57,6 +58,9 @@
     "github:decorator": "tsx github/github-decorator.ts",
     "github:langchain": "tsx github/github-langchain.ts",
     "github:approval": "tsx github/github-with-approval.ts",
+    "hubspot:factory": "tsx hubspot/hubspot-factory.ts",
+    "hubspot:decorator": "tsx hubspot/hubspot-decorator.ts",
+    "hubspot:langchain": "tsx hubspot/hubspot-langchain.ts",
     "build": "tsc",
     "clean": "rm -rf dist"
   }

package/edit/temp-agent-edit-demo.txt.backup

@@ -1,6 +0,0 @@
-Project TODO List
-================
-- TODO: Implement authentication module
-- TODO: Add database migrations
-- TODO: Write API documentation
-- TODO: Set up CI/CD pipeline