@squidcloud/cli 1.0.460 → 1.0.462

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

@@ -0,0 +1,616 @@
+# Connector Client SDKs & Executable Methods
+
+Squid ships 13 connector client SDKs that developers can import and call directly from frontend or backend code. These provide typed methods for interacting with SaaS services without needing the raw APIs.
+
+## How Connector Functions Work
+
+There are **three ways** to use connector functionality:
+
+1. **Client SDK** (`@squidcloud/<connector>-client`) - Import and call typed methods directly from frontend or backend code
+2. **AI Functions** (`@aiFunction`) - Automatically available to AI agents when the integration is connected (see [connector-functions.md](connector-functions.md))
+3. **Executables** (`@executable`) - Backend methods callable via `squid.executeFunction()` from the client
+
+All three call the same underlying connector logic. Use Client SDKs for the best developer experience.
+
+---
+
+## Slack - `@squidcloud/slack-client`
+
+```typescript
+import { SquidSlackClient } from '@squidcloud/slack-client';
+
+const slackClient = new SquidSlackClient(squid, 'my-slack-integration-id');
+
+// Send a message to a channel
+await slackClient.sendMessage({ channel: '#general', text: 'Hello from Squid!' });
+
+// Search indexed messages (semantic search)
+const results = await slackClient.searchMessages({ prompt: 'deployment issues', limit: 10 });
+```
+
+### Methods
+| Method | Parameters | Description |
+|--------|-----------|-------------|
+| `sendMessage` | `{ channel, text }` | Send a message to a Slack channel |
+| `searchMessages` | `{ prompt, limit? }` | Semantic search across indexed Slack messages |
+
+---
+
+## Jira - `@squidcloud/jira-client`
+
+```typescript
+import { SquidJiraClient } from '@squidcloud/jira-client';
+
+const jiraClient = new SquidJiraClient(squid, 'my-jira-integration-id');
+
+// Search issues
+const issues = await jiraClient.searchIssues({ query: 'login bug', projectKey: 'BACKEND' });
+
+// Search by JQL
+const jqlResults = await jiraClient.searchByJql({ jql: 'project = BACKEND AND status = Open' });
+
+// Get issue details
+const issue = await jiraClient.getIssue({ issueKey: 'BACKEND-123' });
+
+// Create an issue
+const newIssue = await jiraClient.createIssue({
+  projectKey: 'BACKEND',
+  summary: 'Fix login button',
+  issueType: 'Bug',
+  description: 'The login button is not responding on mobile'
+});
+
+// Update an issue
+await jiraClient.updateIssue({ issueKey: 'BACKEND-123', fields: { priority: 'High' } });
+
+// Add a comment
+await jiraClient.addComment({ issueKey: 'BACKEND-123', comment: 'Working on this now' });
+
+// Transition issue status
+await jiraClient.transitionIssue({ issueKey: 'BACKEND-123', transitionId: '31' });
+
+// Add labels
+await jiraClient.addLabels({ issueKey: 'BACKEND-123', labels: ['urgent', 'mobile'] });
+
+// List projects
+const projects = await jiraClient.listProjects();
+```
+
+### Methods
+| Method | Description |
+|--------|-------------|
+| `searchIssues` | Text search with optional project/status filters |
+| `searchByJql` | Search using Jira Query Language |
+| `getIssue` | Get full issue details by key |
+| `createIssue` | Create a new issue |
+| `updateIssue` | Update issue fields |
+| `addComment` | Add a comment to an issue |
+| `transitionIssue` | Move issue to a new status |
+| `addLabels` | Add labels to an issue |
+| `listProjects` | List available projects |
+
+---
+
+## Jira Service Management - `@squidcloud/jira-jsm-client`
+
+```typescript
+import { SquidJiraJsmClient } from '@squidcloud/jira-jsm-client';
+
+const jsmClient = new SquidJiraJsmClient(squid, 'my-jsm-integration-id');
+
+// List service desks
+const desks = await jsmClient.listServiceDesks();
+
+// List request types for a desk
+const types = await jsmClient.listRequestTypes({ serviceDeskId: '1' });
+
+// Create a request
+const request = await jsmClient.createRequest({
+  serviceDeskId: '1',
+  requestTypeId: '10',
+  summary: 'Laptop replacement needed',
+  description: 'Screen is cracked'
+});
+
+// Search requests
+const results = await jsmClient.searchRequests({ query: 'laptop' });
+
+// Get request details
+const details = await jsmClient.getRequest({ requestId: 'IT-42' });
+
+// Update a request
+await jsmClient.updateRequest({ requestId: 'IT-42', fields: { priority: 'High' } });
+
+// Add a comment
+await jsmClient.addComment({ requestId: 'IT-42', comment: 'Ordered replacement', isPublic: true });
+
+// Transition request status
+await jsmClient.transitionRequest({ requestId: 'IT-42', transitionId: '5' });
+
+// List customers
+const customers = await jsmClient.listCustomers({ serviceDeskId: '1' });
+```
+
+### Methods
+| Method | Description |
+|--------|-------------|
+| `listServiceDesks` | List all service desks |
+| `listRequestTypes` | List request types for a service desk |
+| `searchRequests` | Search requests by text |
+| `getRequest` | Get request details |
+| `createRequest` | Create a new service request |
+| `updateRequest` | Update request fields |
+| `addComment` | Add a comment (public or internal) |
+| `transitionRequest` | Transition request status |
+| `listCustomers` | List customers in a service desk |
+
+---
+
+## Zendesk
+
+Zendesk does NOT have a separate client SDK package. Use `squid.executeFunction()` to call the backend executables:
+
+```typescript
+// Search tickets (semantic)
+const results = await squid.executeFunction('searchInZendesk', prompt, integrationId);
+
+// List tickets
+const tickets = await squid.executeFunction('listZendeskTickets', integrationId, limit, sortBy, ascending, status);
+
+// Get ticket details
+const details = await squid.executeFunction('getZendeskTicketDetails', ticketId, integrationId, relatedTicketsMode);
+
+// Reply to a ticket
+await squid.executeFunction('replyToZendeskTicket', ticketId, integrationId, replyText, isReplyToCustomer, reassignToEmail, status);
+```
+
+### Executable Methods
+| Method | Description |
+|--------|-------------|
+| `searchInZendesk` | Semantic search across tickets and KB |
+| `listZendeskTickets` | List tickets with sorting/filtering |
+| `getZendeskTicketDetails` | Get full ticket details with comments |
+| `replyToZendeskTicket` | Reply to a ticket (customer or internal) |
+
+---
+
+## GitHub - `@squidcloud/github-client`
+
+```typescript
+import { SquidGitHubClient } from '@squidcloud/github-client';
+
+const ghClient = new SquidGitHubClient(squid, 'my-github-integration-id');
+
+// Search PRs
+const prs = await ghClient.searchPullRequests({ query: 'fix', state: 'open' });
+
+// Get PR details
+const pr = await ghClient.getPullRequest({ prNumber: 42 });
+
+// List open PRs
+const openPrs = await ghClient.listPullRequests();
+
+// Search code
+const code = await ghClient.searchCode({ query: 'handleAuth', path: 'src/' });
+
+// Get file content
+const file = await ghClient.getFileContent({ path: 'src/index.ts', ref: 'main' });
+
+// Create a PR
+const newPr = await ghClient.createPullRequest({
+  title: 'Fix auth bug',
+  body: 'Fixes the login issue',
+  head: 'fix/auth-bug',
+  base: 'main'
+});
+
+// Add a PR comment
+await ghClient.addPRComment({ prNumber: 42, body: 'Looks good!' });
+
+// Submit a review
+await ghClient.addPRReview({ prNumber: 42, body: 'LGTM', event: 'APPROVE' });
+
+// Close a PR
+await ghClient.closePullRequest({ prNumber: 42 });
+
+// Merge a PR
+await ghClient.mergePullRequest({ prNumber: 42, mergeMethod: 'squash' });
+
+// Extract webhook data
+const payload = await ghClient.extractWebhookData(webhookRequest);
+```
+
+### Methods
+| Method | Description |
+|--------|-------------|
+| `searchPullRequests` | Search PRs by query, state, author, label |
+| `getPullRequest` | Get PR details with files and reviews |
+| `listPullRequests` | List open pull requests |
+| `searchCode` | Search code across repository |
+| `getFileContent` | Get file content by path and ref |
+| `createPullRequest` | Create a new PR |
+| `addPRComment` | Add a comment to a PR |
+| `addPRReview` | Submit a review (APPROVE/REQUEST_CHANGES/COMMENT) |
+| `closePullRequest` | Close a PR |
+| `mergePullRequest` | Merge a PR (merge/squash/rebase) |
+| `extractWebhookData` | Parse GitHub webhook payload |
+
+---
+
+## Salesforce - `@squidcloud/salesforce-client`
+
+```typescript
+import { SquidSalesforceClient } from '@squidcloud/salesforce-client';
+
+const sfClient = new SquidSalesforceClient(squid, 'my-salesforce-integration-id');
+
+// Opportunities
+const opp = await sfClient.getOpportunity({ opportunityId: '006...' });
+const newOpp = await sfClient.createOpportunity({ name: 'Acme Deal', stageName: 'Prospecting', closeDate: '2025-06-01', amount: 50000 });
+await sfClient.updateOpportunity({ opportunityId: '006...', fields: { stageName: 'Closed Won' } });
+await sfClient.deleteOpportunity({ opportunityId: '006...' });
+const oppFields = await sfClient.describeOpportunity();
+
+// Cases
+const case_ = await sfClient.getCase({ caseId: '500...' });
+const newCase = await sfClient.createCase({ subject: 'Login issue', description: 'Cannot log in', priority: 'High' });
+await sfClient.updateCase({ caseId: '500...', fields: { status: 'Closed' } });
+await sfClient.deleteCase({ caseId: '500...' });
+
+// Accounts
+const account = await sfClient.getAccount({ accountId: '001...' });
+const newAccount = await sfClient.createAccount({ name: 'Acme Corp', industry: 'Technology' });
+await sfClient.updateAccount({ accountId: '001...', fields: { phone: '555-0100' } });
+await sfClient.deleteAccount({ accountId: '001...' });
+
+// Incidents
+const incident = await sfClient.getIncident({ incidentId: '...' });
+const newIncident = await sfClient.createIncident({ subject: 'Outage', description: 'Service down' });
+await sfClient.updateIncident({ incidentId: '...', fields: { status: 'Resolved' } });
+await sfClient.deleteIncident({ incidentId: '...' });
+
+// Knowledge Base search
+const kbResults = await sfClient.searchKnowledgeBase({ prompt: 'password reset policy' });
+```
+
+### Methods (per object type: Opportunity, Case, Account, Incident)
+| Method | Description |
+|--------|-------------|
+| `get{Type}` | Get record by ID |
+| `create{Type}` | Create a new record |
+| `update{Type}` | Update record fields |
+| `delete{Type}` | Delete a record |
+| `describe{Type}` | Get field metadata |
+| `searchKnowledgeBase` | Semantic search across knowledge articles |
+
+---
+
+## Freshdesk - `@squidcloud/freshdesk-client`
+
+```typescript
+import { FreshdeskClient } from '@squidcloud/freshdesk-client';
+
+const fdClient = new FreshdeskClient(squid, 'my-freshdesk-integration-id');
+
+// Search tickets
+const tickets = await fdClient.searchTickets({ query: 'billing issue' });
+
+// Get ticket details
+const ticket = await fdClient.getTicketDetails({ ticketId: '12345' });
+
+// Create a ticket
+const newTicket = await fdClient.createTicket({
+  subject: 'Cannot access account',
+  description: 'Getting 403 error',
+  email: 'customer@example.com',
+  priority: 3  // 1=Low, 2=Medium, 3=High, 4=Urgent
+});
+
+// Update a ticket
+await fdClient.updateTicket({ ticketId: '12345', fields: { priority: 4 } });
+
+// Reply to a ticket (visible to requester)
+await fdClient.replyToTicket({ ticketId: '12345', body: 'We are looking into this.' });
+
+// Add internal note (not visible to requester)
+await fdClient.addNote({ ticketId: '12345', body: 'Escalated to engineering' });
+
+// Change status/priority
+await fdClient.changeStatus({ ticketId: '12345', status: 4 });  // 2=Open, 3=Pending, 4=Resolved, 5=Closed
+await fdClient.changePriority({ ticketId: '12345', priority: 2 });
+
+// Quick actions
+await fdClient.resolveTicket({ ticketId: '12345' });
+await fdClient.closeTicket({ ticketId: '12345' });
+await fdClient.reopenTicket({ ticketId: '12345' });
+```
+
+### Methods
+| Method | Description |
+|--------|-------------|
+| `searchTickets` | Text search for tickets |
+| `getTicketDetails` | Get full ticket details |
+| `createTicket` | Create a new ticket |
+| `updateTicket` | Update ticket fields |
+| `replyToTicket` | Public reply (visible to requester) |
+| `addNote` | Internal note (not visible to requester) |
+| `changeStatus` | Change ticket status |
+| `changePriority` | Change ticket priority |
+| `resolveTicket` | Set ticket to Resolved |
+| `closeTicket` | Set ticket to Closed |
+| `reopenTicket` | Reopen a closed ticket |
+
+---
+
+## HubSpot
+
+HubSpot does NOT have a separate client SDK package. Use `squid.executeFunction()`:
+
+```typescript
+// Get contact details
+const contact = await squid.executeFunction('getHubSpotContactDetails', contactId, integrationId);
+
+// Get company details
+const company = await squid.executeFunction('getHubSpotCompanyDetails', companyId, integrationId);
+
+// Search contacts
+const contacts = await squid.executeFunction('searchHubSpotContacts', query, limit, integrationId);
+
+// Search companies
+const companies = await squid.executeFunction('searchHubSpotCompanies', query, limit, integrationId);
+```
+
+---
+
+## Linear - `@squidcloud/linear-client`
+
+```typescript
+import { SquidLinearClient } from '@squidcloud/linear-client';
+
+const linearClient = new SquidLinearClient(squid, 'my-linear-integration-id');
+
+// Search issues
+const issues = await linearClient.searchIssues({ query: 'login bug', teamId: 'team-1' });
+
+// Get issue details
+const issue = await linearClient.getIssue({ issueId: 'LIN-42' });
+
+// Create an issue
+const newIssue = await linearClient.createIssue({
+  title: 'Fix mobile login',
+  description: 'Button not responding on iOS',
+  teamId: 'team-1',
+  priority: 1
+});
+
+// Update an issue
+await linearClient.updateIssue({ issueId: 'LIN-42', fields: { status: 'In Progress' } });
+
+// Add a comment
+await linearClient.addComment({ issueId: 'LIN-42', body: 'Reproduced on iOS 17' });
+
+// List teams
+const teams = await linearClient.listTeams();
+
+// Extract webhook data
+const payload = await linearClient.extractWebhookData(webhookRequest);
+```
+
+### Methods
+| Method | Description |
+|--------|-------------|
+| `searchIssues` | Search issues by text with team/status filters |
+| `getIssue` | Get issue details |
+| `createIssue` | Create a new issue |
+| `updateIssue` | Update issue fields |
+| `addComment` | Add a comment |
+| `listTeams` | List available teams |
+| `extractWebhookData` | Parse Linear webhook payload |
+
+---
+
+## Mail - `@squidcloud/mail-client`
+
+```typescript
+import { SquidMailClient } from '@squidcloud/mail-client';
+
+const mailClient = new SquidMailClient(squid, 'my-mail-integration-id');
+
+// Send an email
+await mailClient.sendMail({
+  to: 'user@example.com',
+  from: 'noreply@company.com',  // optional, uses configured default
+  subject: 'Welcome!',
+  body: '<h1>Welcome to our platform</h1>',
+  html: true
+});
+```
+
+### Methods
+| Method | Description |
+|--------|-------------|
+| `sendMail` | Send an email via SMTP (supports HTML) |
+
+---
+
+## Google Calendar - `@squidcloud/google-calendar-client`
+
+```typescript
+import { SquidGoogleCalendarClient, SCOPES } from '@squidcloud/google-calendar-client';
+
+const calClient = new SquidGoogleCalendarClient(squid, 'my-gcal-integration-id');
+
+// Save OAuth auth code (first-time setup)
+await calClient.saveAuthCode({ authCode: 'code-from-oauth-flow' });
+
+// Get calendar events
+const events = await calClient.getCalendarEvents({
+  startDate: '2025-01-01',
+  endDate: '2025-01-31',
+  maxResults: 50,
+  calendarId: 'primary'
+});
+
+// Create/update a calendar event
+await calClient.upsertCalendarEvent({
+  summary: 'Team Meeting',
+  start: '2025-01-15T10:00:00',
+  end: '2025-01-15T11:00:00',
+  calendarId: 'primary'
+});
+```
+
+### Methods
+| Method | Description |
+|--------|-------------|
+| `saveAuthCode` | Save OAuth authorization code |
+| `getCalendarEvents` | List events in a date range |
+| `upsertCalendarEvent` | Create or update a calendar event |
+
+---
+
+## Google Drive - `@squidcloud/google-drive-client`
+
+```typescript
+import { GoogleDriveClient, GOOGLE_DRIVE_SCOPES } from '@squidcloud/google-drive-client';
+
+const driveClient = new GoogleDriveClient(squid, 'my-gdrive-integration-id');
+
+// Save OAuth auth code (first-time setup)
+await driveClient.saveAuthCode({ authCode: 'code-from-oauth-flow' });
+
+// List indexed documents
+const docs = await driveClient.listIndexedDocuments({ type: 'document' });
+
+// Index a document or folder for semantic search
+await driveClient.indexDocumentOrFolder({ documentId: 'doc-id-123' });
+
+// Unindex a document
+await driveClient.unindexDocumentOrFolder({ documentId: 'doc-id-123' });
+
+// Extract structured data from a document
+const data = await driveClient.extractDataFromDocument({ documentId: 'doc-id-123', schema: extractionSchema });
+```
+
+### Methods
+| Method | Description |
+|--------|-------------|
+| `saveAuthCode` | Save OAuth authorization code |
+| `listIndexedDocuments` | List indexed documents with type filter |
+| `indexDocumentOrFolder` | Index a document/folder for search |
+| `unindexDocumentOrFolder` | Remove from search index |
+| `extractDataFromDocument` | Extract structured data from a document |
+
+---
+
+## ServiceNow CSM - `@squidcloud/servicenow_csm-client`
+
+```typescript
+import { SquidServiceNowCSMClient } from '@squidcloud/servicenow_csm-client';
+
+const snowClient = new SquidServiceNowCSMClient(squid, 'my-servicenow-integration-id');
+
+// Get case details
+const case_ = await snowClient.getCase({ caseId: 'CS001234' });
+
+// Create a case
+const newCase = await snowClient.createCase({
+  short_description: 'Network connectivity issue',
+  description: 'Cannot access internal services from office'
+});
+
+// Reply to a case
+await snowClient.replyToCase({ caseId: 'CS001234', body: 'Investigating now' });
+
+// Search knowledge base
+const articles = await snowClient.searchKnowledgeBase({ prompt: 'VPN setup instructions' });
+
+// Search cases
+const cases = await snowClient.searchCases({ query: 'network', state: 'open' });
+```
+
+### Methods
+| Method | Description |
+|--------|-------------|
+| `getCase` | Get case details |
+| `createCase` | Create a new case |
+| `replyToCase` | Reply to an existing case |
+| `searchKnowledgeBase` | Semantic search in ServiceNow KB |
+| `searchCases` | Search cases by text |
+
+---
+
+## Teams - `@squidcloud/teams-client`
+
+```typescript
+import { SquidTeamsClient } from '@squidcloud/teams-client';
+
+const teamsClient = new SquidTeamsClient(squid, 'my-teams-integration-id');
+
+// Search indexed messages
+const results = await teamsClient.searchMessages({
+  prompt: 'product launch discussion',
+  teamNames: 'Engineering',
+  channelNames: 'general'
+});
+```
+
+### Methods
+| Method | Description |
+|--------|-------------|
+| `searchMessages` | Semantic search across indexed Teams messages |
+
+---
+
+## SharePoint - `@squidcloud/sharepoint-client`
+
+```typescript
+import { SharePointClient } from '@squidcloud/sharepoint-client';
+
+const spClient = new SharePointClient(squid, 'my-sharepoint-integration-id');
+
+// List indexed documents
+const docs = await spClient.listIndexedDocuments({ type: 'document' });
+
+// Index a document or folder
+await spClient.indexDocumentOrFolder({ documentId: 'doc-id' });
+
+// Unindex a document
+await spClient.unindexDocumentOrFolder({ documentId: 'doc-id' });
+
+// Extract structured data from a document
+const data = await spClient.extractDataFromDocument({ documentId: 'doc-id', schema: extractionSchema });
+```
+
+### Methods
+| Method | Description |
+|--------|-------------|
+| `listIndexedDocuments` | List indexed SharePoint documents |
+| `indexDocumentOrFolder` | Index a document/folder for search |
+| `unindexDocumentOrFolder` | Remove from search index |
+| `extractDataFromDocument` | Extract structured data from a document |
+
+---
+
+## Summary: Which Connectors Have Client SDKs
+
+| Connector | Client SDK Package | Has Client SDK |
+|-----------|-------------------|----------------|
+| Slack | `@squidcloud/slack-client` | Yes |
+| Jira | `@squidcloud/jira-client` | Yes |
+| Jira JSM | `@squidcloud/jira-jsm-client` | Yes |
+| Zendesk | - | No (use executeFunction) |
+| GitHub | `@squidcloud/github-client` | Yes |
+| Salesforce | `@squidcloud/salesforce-client` | Yes |
+| Freshdesk | `@squidcloud/freshdesk-client` | Yes |
+| HubSpot | - | No (use executeFunction) |
+| Linear | `@squidcloud/linear-client` | Yes |
+| Mail | `@squidcloud/mail-client` | Yes |
+| Google Calendar | `@squidcloud/google-calendar-client` | Yes |
+| Google Drive | `@squidcloud/google-drive-client` | Yes |
+| ServiceNow CSM | `@squidcloud/servicenow_csm-client` | Yes |
+| Teams | `@squidcloud/teams-client` | Yes |
+| SharePoint | `@squidcloud/sharepoint-client` | Yes |
+| Confluence | - | No (AI functions only) |
+
+For connectors without a client SDK, use `squid.executeFunction('methodName', ...args)` to call the backend executable methods directly.