@squidcloud/cli 1.0.445 → 1.0.447

package/dist/resources/claude/skills/squid-development/reference/client.md

@@ -0,0 +1,442 @@
+# Client SDK
+
+The Squid Client SDK (`@squidcloud/client`) provides TypeScript/JavaScript APIs for frontend applications to interact with Squid backends.
+
+Docs: https://docs.getsquid.ai/reference-docs/typescript-client/
+
+## Contents
+- Where Can You Use the SDK?
+- Initialization
+- Built-in Features (Essentials)
+- Authentication
+- Common Client Operations
+- Client vs Backend Permissions
+- Authentication Patterns
+- Storage
+- Queues
+- Distributed Locks
+- Web
+- Extraction
+- Jobs
+- Observability & Metrics
+- Custom Notifications
+
+## Where Can You Use the SDK?
+
+The Squid Client SDK can be instantiated in various environments:
+- **Web applications** (vanilla JavaScript, React, Vue, Angular, etc.)
+- **Node.js servers** (Express, Fastify, etc.)
+- **Mobile applications** (React Native, etc.)
+- **Desktop applications** (Electron, etc.)
+
+**Important:** When writing backend code that runs on Squid's infrastructure, the Squid client is **already initialized and available with API key and full permissions**. You don't need to manually create a new instance.
+
+## Initialization
+
+### Configuration Options
+
+**Required Parameters:**
+- **`appId`** (string): Your Squid application identifier. Can be found in the Squid Console.
+- **`region`** (string): The region where your Squid application is deployed:
+  - AWS regions: `'us-east-1.aws'`, `'ap-south-1.aws'`
+  - GCP regions: `'us-central1.gcp'`
+
+**Optional Parameters:**
+- **`apiKey`** (string): API key that bypasses security rules and provides full administrative access.
+  - **IMPORTANT**: Has **complete control over your application** and bypasses all security rules
+  - Only use in trusted environments (backend servers, admin tools, development)
+  - **Never expose in client-side code** (web browsers, mobile apps)
+- **`authProvider`** (object): Authentication provider that supplies OAuth2.0 tokens for the current user
+  - `integrationId` (string): The ID of your auth integration
+  - `getToken` (function): Returns the user's auth token. Can return `Promise<string | undefined>` or `string | undefined` synchronously
+  - Authentication details are **available in backend functions** via the execution context
+- **`environmentId`** (string): Environment identifier (dev, staging, prod). Defaults to production.
+- **`squidDeveloperId`** (string): Your developer identifier, used for local development and debugging.
+- **`consoleRegion`** (string): Console region (optional)
+
+### Basic Setup
+
+```typescript
+import { Squid } from '@squidcloud/client';
+
+const squid = new Squid({
+  appId: 'your-app-id',
+  region: 'us-east-1.aws',
+  environmentId: 'dev' // optional
+});
+```
+
+## Built-in Features (Essentials)
+
+Every Squid application includes the **Essentials Connector** - a built-in integration that provides core utilities without any additional setup. These features are always available:
+
+| Feature | Access | Description | Docs |
+|---------|--------|-------------|------|
+| **Web Utilities** | `squid.web()` | AI-powered web search, URL content extraction, short URLs | [Web section](#web) |
+| **AI Agents** | `squid.ai().agent()` | Chat with built-in or custom AI agents | [ai.md](ai.md) |
+| **Knowledge Bases** | `squid.ai().knowledgeBase()` | RAG with semantic search and reranking | [ai.md](ai.md) |
+| **Image Generation** | `squid.ai().image()` | Generate images with DALL-E | [ai.md](ai.md) |
+| **Audio** | `squid.ai().audio()` | Transcription and text-to-speech | [ai.md](ai.md) |
+| **PDF/Extraction** | `squid.extraction()` | Create PDFs, extract data from documents | [Extraction section](#extraction) |
+| **Observability** | `squid.observability` | Report and query custom metrics | [Observability section](#observability--metrics) |
+
+**Note:** For additional integrations (databases, auth providers, storage, etc.), see [connectors.md](connectors.md). Configure integrations in the [Squid Console](https://console.getsquid.ai/).
+
+## Authentication
+
+### API Key vs Auth Provider
+
+**Using API Key (Server-Side Only):**
+```typescript
+const squid = new Squid({
+  appId: 'your-app-id',
+  region: 'us-east-1.aws',
+  apiKey: 'your-api-key' // Full admin access
+});
+```
+- **Use cases**: Backend servers, admin tools, scripts, development environments
+- **Security**: Has full control - bypasses all security rules
+- **Warning**: Never use in client-side code
+
+**Using Auth Provider (Client-Side):**
+```typescript
+const squid = new Squid({
+  appId: 'your-app-id',
+  region: 'us-east-1.aws',
+  authProvider: {
+    integrationId: 'auth-integration-id',
+    getToken: async () => {
+      // Return user's OAuth token
+      return await getCurrentUserToken();
+    }
+  }
+});
+```
+- **Use cases**: Web apps, mobile apps, any user-facing application
+- **Security**: Respects security rules based on authenticated user
+- **Backend access**: User authentication details are available in backend functions through the execution context
+
+**Setting Auth Provider After Initialization:**
+```typescript
+const squid = new Squid({
+  appId: 'your-app-id',
+  region: 'us-east-1.aws'
+});
+
+// Later, when user logs in
+squid.setAuthProvider({
+  integrationId: 'auth-integration-id',
+  getToken: async () => userAuthToken
+});
+```
+
+## Common Client Operations
+
+### Accessing Collections
+```typescript
+// Get collection reference in the built-in database
+const users = squid.collection<User>('users');
+
+// Get collection reference in a specific integration
+const orders = squid.collection<Order>('orders', 'postgres-db');
+```
+
+Use `collection.doc()` to get document references for CRUD operations. See [databases.md](databases.md) for full details on `doc()` behavior, queries, and subscriptions.
+
+### Calling Backend Functions
+```typescript
+// Execute @executable() decorated function
+const result = await squid.executeFunction('greetUser', 'John');
+const typedResult = await squid.executeFunction<string>('greetUser', 'John');
+
+// With headers
+const result = await squid.executeFunctionWithHeaders(
+  'processPayment',
+  { 'X-Custom-Header': 'value' },
+  paymentData
+);
+```
+
+See [backend.md](backend.md) for more details on `@executable`. 
+
+### AI Agent Access
+```typescript
+// Get the built-in agent (no ID required)
+const builtInAgent = squid.ai().agent();
+
+// Get a custom agent by ID
+const myAgent = squid.ai().agent('my-agent-id');
+
+// Ask a question
+const response = await myAgent.ask('How do I reset my password?');
+```
+
+See [ai.md](ai.md) for full AI agent capabilities.
+
+### Webhooks
+```typescript
+// Get URL for a specific webhook
+const webhookUrl = squid.getWebhookUrl('github-events');
+// Returns: https://<appId>.<region>.squid.cloud/webhooks/github-events
+
+// Get base webhooks URL (no webhook ID)
+const baseUrl = squid.getWebhookUrl();
+// Returns: https://<appId>.<region>.squid.cloud/webhooks
+```
+
+## Client vs Backend Permissions
+
+| Aspect | Client with Auth Provider | Client with API Key | Backend (`this.squid`) |
+|--------|--------------------------|---------------------|------------------------|
+| Security Rules | Enforced | Bypassed | Bypassed |
+| User Context | Available | N/A | Available via `getUserAuth()` |
+| Use Case | User-facing apps | Admin tools, scripts | Server-side logic |
+| Permissions | Limited by rules | Full access | Full access |
+
+## Authentication Patterns
+
+### OAuth Integration
+```typescript
+// Auth0 example
+const squid = new Squid({
+  appId: 'YOUR_APP_ID',
+  region: 'us-east-1.aws',
+  authProvider: {
+    integrationId: 'auth0',
+    getToken: async () => await auth0.getAccessTokenSilently()
+  }
+});
+```
+
+### External OAuth Integration
+
+Manage OAuth tokens for external integrations. Squid automatically handles token refresh when tokens expire.
+
+```typescript
+const externalAuth = squid.externalAuth('google-oauth-integration');
+
+// Save authorization code (exchange for access token)
+const tokenResponse = await externalAuth.saveAuthCode(
+  'authorization-code-from-oauth-flow',
+  'user-identifier' // Unique identifier for this user
+);
+console.log('Access token:', tokenResponse.accessToken);
+console.log('Expires at:', tokenResponse.expirationTime);
+
+// Get access token (auto-refreshes if expired)
+const token = await externalAuth.getAccessToken('user-identifier');
+console.log('Current access token:', token.accessToken);
+console.log('Expires at:', token.expirationTime);
+```
+
+**Use cases:**
+- Google Drive/Calendar integration
+- GitHub OAuth
+- Slack OAuth
+- Any external service requiring OAuth 2.0
+- Squid handles token refresh automatically
+
+## Storage
+
+Store and retrieve files with built-in storage or external providers like S3.
+
+```typescript
+const storage = squid.storage(); // built_in_storage
+const s3 = squid.storage('aws-s3-integration');
+
+// Upload file
+await storage.uploadFile('/documents', file, 3600); // 1 hour expiration
+
+// Get download URL
+const url = await storage.getDownloadUrl('/documents/report.pdf', 3600);
+
+// Get file metadata
+const metadata = await storage.getFileMetadata('/documents/report.pdf');
+
+// List directory
+const contents = await storage.listDirectoryContents('/documents');
+
+// Delete files
+await storage.deleteFile('/documents/report.pdf');
+await storage.deleteFiles(['/docs/file1.pdf', '/docs/file2.pdf']);
+```
+
+To secure storage operations, see [security.md](security.md) for `@secureStorage`. For S3 and other storage integrations, see [connectors.md](connectors.md).
+
+## Queues
+
+Publish and consume messages from topics. Supports built-in queues and external providers like Kafka.
+
+```typescript
+const queue = squid.queue<Message>('notifications');
+const kafkaQueue = squid.queue<Event>('events', 'kafka-integration');
+
+// Produce messages
+await queue.produce([
+  { type: 'email', to: 'user@example.com' },
+  { type: 'sms', to: '+1234567890' }
+]);
+
+// Consume messages (observable)
+const subscription = queue.consume<Message>().subscribe(message => {
+  console.log('Received:', message);
+});
+
+subscription.unsubscribe();
+```
+
+To secure queue topics, see [security.md](security.md) for `@secureTopic`. For Kafka and other queue integrations, see [connectors.md](connectors.md).
+
+## Distributed Locks
+
+Prevent race conditions when multiple clients or instances access shared resources.
+
+```typescript
+// Acquire and release manually
+const lock = await squid.acquireLock('payment-processing');
+try {
+  await processPayment();
+} finally {
+  lock.release();
+}
+
+// Automatic release with withLock (recommended)
+const result = await squid.withLock('payment-processing', async (lock) => {
+  await processPayment();
+  return 'success';
+});
+```
+
+To secure lock access, see [security.md](security.md) for `@secureDistributedLock`.
+
+## Web
+
+Web utilities for AI-powered search, fetching URL content as markdown, and creating short URLs.
+
+Also available as a REST API: [Web Utilities API](https://docs.getsquid.ai/reference-docs/api/#tag/Web-Utilities)
+
+```typescript
+const web = squid.web();
+
+// AI-powered web search
+const results = await web.aiSearch('latest AI developments');
+
+// Get URL content (as markdown)
+const content = await web.getUrlContent('https://example.com/article');
+
+// URL shortening
+const shortUrl = await web.createShortUrl('https://very-long-url.com', 86400);
+```
+
+## Extraction
+
+Create PDFs from HTML/markdown and extract structured data from documents using AI.
+
+Also available as a REST API: [Extraction Utilities API](https://docs.getsquid.ai/reference-docs/api/#tag/Extraction-Utilities)
+
+```typescript
+const extraction = squid.extraction();
+
+// Create PDF from HTML or markdown
+const pdfResponse = await extraction.createPdf({
+  content: '<h1>Hello</h1><p>This is a PDF</p>',
+  contentType: 'html', // or 'markdown'
+  options: {
+    pageSize: 'A4',
+    margin: { top: '1cm', bottom: '1cm', left: '1cm', right: '1cm' }
+  }
+});
+console.log('PDF created:', pdfResponse.url);
+
+// Extract data from document file
+const extractedData = await extraction.extractDataFromDocumentFile(
+  myPdfFile,
+  {
+    schema: {
+      fields: [
+        { name: 'invoiceNumber', type: 'string', description: 'Invoice number' },
+        { name: 'total', type: 'number', description: 'Total amount' },
+        { name: 'date', type: 'date', description: 'Invoice date' }
+      ]
+    }
+  }
+);
+
+// Extract data from document URL
+const urlData = await extraction.extractDataFromDocumentUrl(
+  'https://example.com/document.pdf',
+  {
+    schema: {
+      fields: [
+        { name: 'title', type: 'string' },
+        { name: 'author', type: 'string' }
+      ]
+    }
+  }
+);
+```
+
+## Jobs
+
+Track long-running asynchronous operations. Poll for completion and retrieve results.
+
+```typescript
+const jobClient = squid.job();
+
+// Get job status
+const job = await jobClient.getJob<Result>('job-123');
+if (job?.status === 'completed') {
+  console.log('Result:', job.result);
+}
+
+// Wait for completion
+const result = await jobClient.awaitJob<Result>('job-123');
+```
+
+## Observability & Metrics
+
+Report and query custom metrics for monitoring application performance.
+
+```typescript
+const obs = squid.observability;
+
+// Report metric
+await obs.reportMetric({
+  name: 'api_request_count',
+  value: 1,
+  tags: { endpoint: '/users', method: 'GET' },
+  timestamp: Date.now()
+});
+
+// Query metrics
+const metrics = await obs.queryMetrics({
+  metricNames: ['api_request_count'],
+  startTime: startTimestamp,
+  endTime: endTimestamp,
+  groupBy: ['endpoint'],
+  aggregation: 'sum'
+});
+```
+
+## Custom Notifications
+
+Send custom messages between clients for real-time coordination.
+
+```typescript
+const notifications = squid.getNotificationClient();
+
+// Observe incoming notifications
+const subscription = notifications.observeNotifications().subscribe(payload => {
+  console.log('Received notification:', payload);
+  // payload can be any serializable data
+});
+
+// Publish notification (requires API key)
+await notifications.publishNotification(
+  { type: 'update', message: 'Data changed' }, // payload
+  ['client-id-1', 'client-id-2'] // target client IDs
+);
+
+// Clean up when done
+subscription.unsubscribe();
+```

package/dist/resources/claude/skills/squid-development/reference/connectors.md

@@ -0,0 +1,33 @@
+# Integrations & Connectors
+
+Squid connects to external services through **integrations** (configured in [Squid Console](console.md), accessed via SDK).
+
+## Integration Types
+
+```typescript
+import { IntegrationType, INTEGRATION_TYPES } from '@squidcloud/client';
+```
+
+- **`IntegrationType`** - Type for a single integration (e.g., `'postgres'`, `'mongo'`, `'auth0'`)
+- **`INTEGRATION_TYPES`** - Complete array of all supported types
+
+**Source of truth:** `node_modules/@squidcloud/client/dist/internal-common/src/public-types/integration.public-types.d.ts`
+
+**Note:** AI providers (OpenAI, Anthropic, Gemini, etc.) are configured separately in Console AI settings, not as `IntegrationType`. See [ai.md](ai.md).
+
+## Essentials Connector
+
+Every app includes the **Essentials Connector** automatically - no setup required. See [client.md](client.md) for details. Provides:
+- `squid.web()` - AI search, URL extraction, short URLs
+- `squid.ai()` - AI queries against configured providers
+- `squid.extraction()` - Structured data extraction from documents/URLs
+
+## Using Integrations
+
+Access integrations by their ID (configured in Console):
+
+```typescript
+squid.collection<Order>('orders', 'my-postgres');  // Database
+squid.storage('my-s3-bucket');                      // Storage
+squid.queue<Event>('events', 'my-kafka');           // Queue
+```

package/dist/resources/claude/skills/squid-development/reference/console.md

@@ -0,0 +1,189 @@
+# Squid Console (Web UI)
+
+The Squid Console is a web-based management interface at https://console.getsquid.ai/ for setting up and managing your Squid applications.
+
+## Contents
+- Overview
+- Organizations & Applications
+- AI Studio
+- Knowledge Bases
+- Integrations Setup
+- Monitoring & Debugging
+- Console vs SDK
+- SDK Equivalents
+- Profile Settings
+
+## Overview
+
+The Console provides visual interfaces for:
+- Organization and application management
+- AI agent configuration and testing
+- Knowledge base management
+- Integration setup and configuration
+- Monitoring and debugging
+
+## Organizations & Applications
+
+### Managing Organizations
+- Create organizations (teams/workspaces)
+- Invite team members and manage roles
+- View organization-wide settings and billing
+
+### Managing Applications
+- Create applications (projects) within organizations
+- Configure application settings
+- Manage API keys and secrets
+- View application logs and metrics
+- Switch between environments (dev, staging, prod)
+
+### API Keys and Secrets
+- Generate API keys for backend access
+- Store secrets securely (database passwords, third-party API keys)
+- Manage secret access and rotation
+
+## AI Studio
+
+The AI Studio provides visual tools for building and testing AI agents:
+
+### Agent Configuration
+- Create and configure AI agents visually
+- Set agent instructions, models, and guardrails
+- Configure agent memory and conversation settings
+- Connect agents to functions, knowledge bases, and integrations
+
+### Testing Agents
+- Interactive chat interface for testing agents
+- View agent reasoning and function calls
+- Debug conversation history
+- Test different scenarios and edge cases
+
+### Connecting Resources
+- Link agents to backend functions (`@aiFunction`)
+- Connect agents to knowledge bases for RAG
+- Configure connected integrations (databases, APIs)
+- Set up agent collaboration (connected agents)
+
+## Knowledge Bases
+
+### Creating Knowledge Bases
+- Create new knowledge bases for RAG (Retrieval Augmented Generation)
+- Configure embedding models and settings
+- Set up metadata schemas
+
+### Managing Content
+- Upload documents (PDF, text, markdown, etc.)
+- View and edit contexts
+- Search and preview indexed content
+- Monitor indexing status
+
+## Integrations Setup
+
+### Database Connections
+- Connect databases (PostgreSQL, MySQL, MongoDB, etc.)
+- Configure connection strings and credentials
+- Set up schema discovery and synchronization
+- Test database connections
+
+### SaaS Integrations
+- Connect SaaS services (Stripe, Slack, HubSpot, etc.)
+- Configure OAuth flows
+- Set up webhooks and callbacks
+- Manage integration credentials
+
+### OAuth Configuration
+- Configure OAuth providers for user authentication
+- Set up OAuth for external service access
+- Manage OAuth secrets and redirect URLs
+
+### Storage Providers
+- Connect storage providers (AWS S3, GCS, etc.)
+- Configure bucket access and permissions
+- Set up file upload/download policies
+
+## Monitoring & Debugging
+
+### Real-time Logs
+- View application logs in real-time
+- Filter logs by type, severity, and source
+- Search log history
+
+### API Usage
+- Monitor API call volumes
+- Track rate limits and quotas
+- View usage analytics and trends
+
+### Agent Debugging
+- Debug agent conversations step-by-step
+- View function calls and their results
+- Analyze agent decision-making process
+- Identify and fix conversation issues
+
+### Performance Metrics
+- Track response times
+- Monitor error rates
+- View resource utilization
+
+## Console vs SDK
+
+| Task | Console | SDK |
+|------|---------|-----|
+| Initial setup | Great for | Possible but harder |
+| Visual agent config | Ideal | N/A |
+| Quick testing | Easy | Requires code |
+| Monitoring | Real-time UI | Custom implementation |
+| CI/CD pipelines | Not suited | Ideal |
+| Programmatic control | N/A | Full control |
+| Dynamic configuration | Manual | Automated |
+| Complex automation | Limited | Unlimited |
+
+**Rule of thumb:**
+- **Console is great for:** Initial setup, visual agent configuration, quick testing, monitoring
+- **SDK is more powerful for:** Programmatic control, CI/CD pipelines, dynamic configuration, complex automation
+
+## SDK Equivalents
+
+Everything in Console can be done via SDK (except creating orgs/apps, which requires ManagementClient):
+
+```typescript
+// Console: Click to create an agent with AI Studio
+// SDK equivalent:
+const agent = squid.ai().agent('my-agent');
+await agent.upsert({
+  description: 'Customer support agent',
+  options: {
+    model: 'gpt-4o',
+    instructions: 'You are a helpful support agent...'
+  }
+});
+
+// Console: Upload document to knowledge base
+// SDK equivalent:
+const kb = squid.ai().knowledgeBase('docs');
+await kb.upsertContext({
+  contextId: 'doc-1',
+  text: 'Product documentation...'
+}, pdfFile);
+
+// Console: Configure database integration
+// SDK equivalent (requires API key):
+const integrations = squid.admin().integrations();
+await integrations.upsertIntegration({
+  id: 'my-db',
+  type: 'postgres',
+  configuration: {
+    connectionString: 'postgresql://...'
+  }
+});
+```
+
+## Profile Settings
+
+### Management API Keys
+For programmatic org/app management, create management API keys in Profile Settings:
+
+1. Go to Squid Console → Profile Settings → API Keys
+2. Click "Create API Key"
+3. Copy the key value (shown only once)
+4. Key format: `squid_mgmt_<uuid>`
+
+See [admin.md](admin.md) for using ManagementClient with these keys.