@squidcloud/cli 1.0.460 → 1.0.461

package/dist/resources/claude/skills/squid-integrations/reference/connector-functions.md

@@ -0,0 +1,541 @@
+# Connector AI Functions Reference
+
+Each Squid SaaS connector provides built-in AI functions that AI agents can call automatically when connected to the integration. These functions are available out-of-the-box - no custom code needed.
+
+## How to Use Connector AI Functions
+
+1. **Add the integration** in Squid Console (e.g., add a Slack integration with bot token)
+2. **Connect it to an AI Agent** either in Console AI Studio or via code:
+
+```typescript
+// Via agent upsert
+await squid.ai().agent('my-agent').upsert({
+  description: 'Support agent',
+  options: {
+    model: 'gpt-5-mini',
+    instructions: 'You are a support agent that can search tickets and send messages.'
+  }
+});
+
+// Via ask/chat options
+const response = await squid.ai().agent('my-agent').ask('Find open tickets about login issues', {
+  connectedIntegrations: [
+    {
+      integrationId: 'zendesk-prod',
+      integrationType: 'zendesk',
+      description: 'Zendesk support system with customer tickets'
+    }
+  ]
+});
+
+// Restrict to specific functions
+const response = await squid.ai().agent('my-agent').ask('Search for login issues', {
+  connectedIntegrations: [
+    {
+      integrationId: 'zendesk-prod',
+      integrationType: 'zendesk',
+      functionsToUse: ['searchInZendeskAiFunction', 'getZendeskTicketDetailsAiFunction']
+    }
+  ]
+});
+```
+
+3. The agent automatically discovers and calls the connector's AI functions based on the user's prompt.
+
+---
+
+## Mail Connector
+
+Integration type: `mail`. Requires SMTP configuration (host, port, user, encryption).
+
+### sendMailWithAi
+Send emails via SMTP.
+- **to** (string, required): Recipient email address
+- **from** (string, optional): Sender email address
+- **subject** (string, required): Email subject line
+- **body** (string, required): Email body content
+- **html** (boolean, required): Whether body is HTML
+
+**Example prompt:** "Send an email to john@example.com about the meeting tomorrow"
+
+---
+
+## Slack Connector
+
+Integration type: `slack`. Requires app ID, bot token, signing secret.
+
+### searchInSlack
+Semantic search across indexed Slack messages.
+- **prompt** (string, required): Search query
+- **limit** (number, optional): Max results
+
+**Example prompt:** "Search Slack for messages about the production outage last week"
+
+---
+
+## Jira Connector
+
+Integration type: `jira`. Requires API key, domain, email. Supports issue indexing for semantic search.
+
+### AI Functions
+The Jira connector provides issue management functions with knowledge base integration for semantic search across indexed issues:
+- Search issues by text and filters
+- Get issue details
+- Create new issues
+- Update existing issues
+- Add comments
+- Transition issue status
+
+**Example prompt:** "Find all open bugs in the BACKEND project assigned to me"
+
+---
+
+## Jira Service Management (JSM) Connector
+
+Integration type: `jira_jsm`. Extends Jira for service desk workflows.
+
+### searchJsmRequests
+Search service desk requests by text.
+- **query** (string, required): Search text
+- **serviceDeskId** (string, optional): Filter by service desk
+
+### getJsmRequestDetails
+Get detailed request information.
+- **requestId** (string, required): The request ID/key
+
+### searchJsmKnowledgeBase
+Semantic search across JSM knowledge base using embeddings.
+- **prompt** (string, required): Search query
+
+### createJsmRequest
+Create new service desk requests.
+- **serviceDeskId** (string, required): Target service desk
+- **requestTypeId** (string, required): Type of request
+- **summary** (string, required): Request summary
+- **description** (string, optional): Request description
+
+### updateJsmRequest
+Update existing requests.
+- **requestId** (string, required): The request ID/key
+- **fields** (string, optional): Fields to update (JSON)
+
+### addJsmComment
+Add comments to requests.
+- **requestId** (string, required): The request ID/key
+- **comment** (string, required): Comment text
+- **isPublic** (boolean, optional): Whether comment is public
+
+### transitionJsmRequest
+Transition request status.
+- **requestId** (string, required): The request ID/key
+- **transitionId** (string, required): Target transition
+
+### listJsmServiceDesks
+List available service desks. No parameters.
+
+### listJsmRequestTypes
+List request types for a service desk.
+- **serviceDeskId** (string, required): Service desk ID
+
+**Example prompt:** "Create a new IT support request for laptop replacement in the IT Help Desk"
+
+---
+
+## Zendesk Connector
+
+Integration type: `zendesk`. Requires subdomain, email, API token.
+
+### searchInZendeskAiFunction
+Semantic search across Zendesk tickets and knowledge base.
+- **prompt** (string, required): Search query
+
+### listZendeskTicketsAiFunction
+List tickets with sorting and filtering.
+- **sortBy** (string, optional): Sort field
+- **sortOrder** (string, optional): asc or desc
+
+### getZendeskTicketDetailsAiFunction
+Get detailed ticket information including comments and metadata.
+- **ticketId** (string, required): Zendesk ticket ID
+
+**Example prompt:** "Show me the details of ticket #12345 and find similar tickets about password reset"
+
+---
+
+## Freshdesk Connector
+
+Integration type: `freshdesk`. Requires subdomain, API key. Supports ticket indexing.
+
+### searchFreshdeskTickets
+Text-based ticket search.
+- **query** (string, required): Search text
+
+### findSimilarFreshdeskTickets
+Semantic similarity search using embeddings.
+- **prompt** (string, required): Description to find similar tickets for
+
+### getFreshdeskTicketDetails
+Get ticket details with related tickets.
+- **ticketId** (string, required): Freshdesk ticket ID
+
+### searchFreshdeskKnowledgeBase
+Semantic search across Freshdesk knowledge base articles.
+- **prompt** (string, required): Search query
+
+### createFreshdeskTicket
+Create new support tickets.
+- **subject** (string, required): Ticket subject
+- **description** (string, required): Ticket description
+- **email** (string, required): Requester email
+- **priority** (number, optional): 1=Low, 2=Medium, 3=High, 4=Urgent
+- **status** (number, optional): 2=Open, 3=Pending, 4=Resolved, 5=Closed
+
+### updateFreshdeskTicket
+Update ticket properties.
+- **ticketId** (string, required): Ticket ID
+- **fields** (string, required): JSON of fields to update
+
+### replyToFreshdeskTicket
+Add a reply to a ticket (visible to requester).
+- **ticketId** (string, required): Ticket ID
+- **body** (string, required): Reply content
+
+### addFreshdeskNote
+Add an internal note to a ticket (not visible to requester).
+- **ticketId** (string, required): Ticket ID
+- **body** (string, required): Note content
+
+### listFreshdeskTickets
+List tickets with pagination.
+- **page** (number, optional): Page number
+- **perPage** (number, optional): Results per page
+
+**Example prompt:** "Create a high-priority ticket for the billing system being down and find similar past tickets"
+
+---
+
+## GitHub Connector
+
+Integration type: `github`. Requires app ID, installation ID, private key, webhook secret.
+
+### searchPullRequests
+Search PRs with multiple filters.
+- **query** (string, required): Search text
+- **state** (string, optional): open, closed, all
+- **author** (string, optional): PR author
+- **label** (string, optional): PR label
+
+### getPRDetails
+Get PR details including files changed and reviews.
+- **prNumber** (number, required): Pull request number
+
+### searchCode
+Search code across repository.
+- **query** (string, required): Code search query
+- **path** (string, optional): File path filter
+
+### getFileContent
+Get specific file contents.
+- **path** (string, required): File path
+- **ref** (string, optional): Branch or commit ref
+
+### createPullRequest
+Create a new pull request.
+- **title** (string, required): PR title
+- **body** (string, required): PR description
+- **head** (string, required): Source branch
+- **base** (string, required): Target branch
+
+### addPRComment
+Add a comment to a PR.
+- **prNumber** (number, required): PR number
+- **body** (string, required): Comment text
+
+### submitPRReview
+Submit a PR review.
+- **prNumber** (number, required): PR number
+- **body** (string, required): Review body
+- **event** (string, required): APPROVE, REQUEST_CHANGES, or COMMENT
+
+### closePullRequest
+Close a pull request.
+- **prNumber** (number, required): PR number
+
+### mergePullRequest
+Merge a pull request.
+- **prNumber** (number, required): PR number
+- **mergeMethod** (string, optional): merge, squash, or rebase
+
+### listOpenPRs
+List open pull requests. No required parameters.
+
+**Example prompt:** "Show me all open PRs by john-doe and review PR #42"
+
+---
+
+## Salesforce Connector
+
+Integration type: `salesforce`. Requires instance domain, OAuth consumer key/secret.
+
+### Opportunity Management
+- **getOpportunity** (opportunityId) - Get opportunity details
+- **createOpportunity** (name, stageName, closeDate, amount, ...) - Create opportunity
+- **updateOpportunity** (opportunityId, fields) - Update opportunity
+- **deleteOpportunity** (opportunityId) - Delete opportunity
+- **describeOpportunity** - Get opportunity field metadata
+
+### Case Management
+- **getCase** (caseId) - Get case details
+- **createCase** (subject, description, priority, ...) - Create case
+- **updateCase** (caseId, fields) - Update case
+- **deleteCase** (caseId) - Delete case
+- **describeCase** - Get case field metadata
+
+### Account Management
+- **getAccount** (accountId) - Get account details
+- **createAccount** (name, industry, ...) - Create account
+- **updateAccount** (accountId, fields) - Update account
+- **deleteAccount** (accountId) - Delete account
+- **describeAccount** - Get account field metadata
+
+### Incident Management
+- **getIncident** (incidentId) - Get incident details
+- **createIncident** (subject, description, ...) - Create incident
+- **updateIncident** (incidentId, fields) - Update incident
+- **deleteIncident** (incidentId) - Delete incident
+- **describeIncident** - Get incident field metadata
+
+### searchSalesforceKnowledgeBase
+Semantic search across Salesforce knowledge articles.
+- **prompt** (string, required): Search query
+
+**Example prompt:** "Create a new opportunity for Acme Corp worth $50k closing next month"
+
+---
+
+## HubSpot Connector
+
+Integration type: `hubspot`. Requires access token.
+
+### getHubSpotContactDetailsAiFunction
+Get contact information by ID.
+- **contactId** (string, required): HubSpot contact ID
+
+### getHubSpotCompanyDetailsAiFunction
+Get company information by ID.
+- **companyId** (string, required): HubSpot company ID
+
+### searchHubSpotContactsAiFunction
+Search contacts by query.
+- **query** (string, required): Search query
+
+### searchHubSpotCompaniesAiFunction
+Search companies by query.
+- **query** (string, required): Search query
+
+**Example prompt:** "Find all contacts at Acme Corp and show me their details"
+
+---
+
+## Confluence Connector
+
+Integration type: `confluence`. Requires API key, domain, space filters.
+
+### searchInConfluence
+Semantic search across indexed Confluence pages.
+- **prompt** (string, required): Search query
+
+**Example prompt:** "Find documentation about the deployment process"
+
+---
+
+## Google Calendar Connector
+
+Integration type: `google_calendar`. Requires OAuth configuration.
+
+### listCalendarEvents
+List calendar events in a date range.
+- **startDate** (string, required): Start date
+- **endDate** (string, required): End date
+- **maxResults** (number, optional): Maximum events to return
+- **calendarId** (string, optional): Specific calendar ID
+
+**Example prompt:** "Show me my meetings for next week"
+
+---
+
+## Google Drive Connector
+
+Integration type: `google_drive`. Requires OAuth configuration.
+
+### listIndexedDocuments
+List indexed documents with type filtering.
+- **type** (string, optional): Filter by document type
+
+### searchInGoogleDrive
+Semantic search across indexed Google Drive documents.
+- **prompt** (string, required): Search query
+
+**Example prompt:** "Find the Q4 financial report in Google Drive"
+
+---
+
+## Linear Connector
+
+Integration type: `linear`. Requires API key. Supports issue indexing.
+
+### searchLinearIssues
+Search issues with team and status filtering.
+- **query** (string, required): Search text
+- **teamId** (string, optional): Filter by team
+- **status** (string, optional): Filter by status
+
+### findSimilarIssues
+Semantic similarity search for issues.
+- **prompt** (string, required): Description to find similar issues for
+
+### getLinearIssueDetails
+Get detailed issue information.
+- **issueId** (string, required): Linear issue ID
+
+### searchLinearKnowledgeBase
+Semantic search with embeddings across indexed issues.
+- **prompt** (string, required): Search query
+
+### createLinearIssue
+Create new issues.
+- **title** (string, required): Issue title
+- **description** (string, optional): Issue description
+- **teamId** (string, required): Team ID
+- **priority** (number, optional): Priority level
+- **assigneeId** (string, optional): Assignee ID
+
+### updateLinearIssue
+Update issue properties.
+- **issueId** (string, required): Issue ID
+- **fields** (string, required): JSON of fields to update
+
+### addLinearComment
+Add comments to issues.
+- **issueId** (string, required): Issue ID
+- **body** (string, required): Comment text
+
+### listLinearTeams
+List available teams. No parameters.
+
+**Example prompt:** "Create a high-priority bug in the Frontend team: login button not working on mobile"
+
+---
+
+## ServiceNow CSM Connector
+
+Integration type: `servicenow_csm`. Requires instance domain, API token.
+
+### searchInServiceNowKnowledgeBaseAiFunction
+Semantic search across ServiceNow knowledge base.
+- **prompt** (string, required): Search query
+
+### searchServiceNowCasesAiFunction
+Text-based case search.
+- **query** (string, required): Search query
+
+### getServiceNowCaseDetailsAiFunction
+Get detailed case information.
+- **caseId** (string, required): Case ID
+
+### createServiceNowCaseAiFunction
+Create new cases.
+- **short_description** (string, required): Case summary
+- **description** (string, optional): Detailed description
+
+### replyToServiceNowCaseAiFunction
+Reply to existing cases.
+- **caseId** (string, required): Case ID
+- **body** (string, required): Reply content
+
+**Example prompt:** "Create a new case for network connectivity issues in the office"
+
+---
+
+## Microsoft Teams Connector
+
+Integration type: `teams`. Requires Microsoft tenant, client secret.
+
+### searchInTeams
+Semantic search across indexed Teams messages.
+- **prompt** (string, required): Search query
+- **teamNames** (string, optional): Filter by team names
+- **channelNames** (string, optional): Filter by channel names
+
+**Example prompt:** "Search Teams for discussions about the product launch"
+
+---
+
+## SharePoint Connector
+
+Integration type: `sharepoint`. Requires Microsoft tenant, client secret.
+
+### listIndexedDocuments
+List indexed SharePoint documents.
+- **type** (string, optional): Filter by document type
+
+### searchInSharePoint
+Semantic search across indexed SharePoint documents.
+- **prompt** (string, required): Search query
+
+**Example prompt:** "Find the employee handbook in SharePoint"
+
+---
+
+## OneDrive Integration
+
+Integration type: `onedrive`. Requires Microsoft OAuth configuration.
+
+Access OneDrive files through the SharePoint connector or via storage APIs.
+
+---
+
+## Google Docs Integration
+
+Integration type: `google_docs`. Requires OAuth configuration.
+
+Access Google Docs content through the Google Drive connector's indexing and search capabilities.
+
+---
+
+## Common Patterns
+
+### Multi-Connector Agent
+```typescript
+const response = await squid.ai().agent('ops-agent').ask('Summarize open issues and recent messages', {
+  connectedIntegrations: [
+    { integrationId: 'jira-prod', integrationType: 'jira', description: 'Issue tracker' },
+    { integrationId: 'slack-eng', integrationType: 'slack', description: 'Engineering Slack' },
+    { integrationId: 'confluence-docs', integrationType: 'confluence', description: 'Documentation' }
+  ]
+});
+```
+
+### Agent with Knowledge Base + Connector
+```typescript
+const response = await squid.ai().agent('support-agent').ask(customerQuestion, {
+  connectedIntegrations: [
+    { integrationId: 'zendesk-prod', integrationType: 'zendesk' }
+  ],
+  connectedKnowledgeBases: [
+    { knowledgeBaseId: 'product-docs', description: 'Product documentation and FAQs' }
+  ]
+});
+```
+
+### Restricting Functions
+```typescript
+// Only allow search, not create/update/delete
+const response = await squid.ai().agent('readonly-agent').ask('Find related tickets', {
+  connectedIntegrations: [{
+    integrationId: 'jira-prod',
+    integrationType: 'jira',
+    functionsToUse: ['searchJiraIssues', 'getJiraIssueDetails']
+  }]
+});
+```