@squidcloud/cli 1.0.445 → 1.0.447

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

@@ -0,0 +1,87 @@
+# REST API Reference
+
+Most Squid SDK functionality is also available via REST APIs.
+
+## API Documentation
+
+Full API reference: https://docs.getsquid.ai/reference-docs/api/
+
+## Authentication
+
+All API endpoints require an API key. Include it in the request headers:
+```
+Authorization: Bearer YOUR_API_KEY
+```
+
+## API Categories
+
+### [Agent API](https://docs.getsquid.ai/reference-docs/api/#tag/Agent)
+Manage AI agents. SDK: [ai.md](ai.md)
+- `GET /agent/get/{agentId}` - Get agent details
+- `POST /agent/upsert` - Create or update agent
+- `POST /agent/delete` - Delete agent
+- `POST /agent/updateInstructions` - Update agent instructions
+- `POST /agent/updateModel` - Change LLM model
+- `POST /agent/updateConnectedAgents` - Manage connected agents
+- `POST /agent/updateGuardrails` - Configure guardrails
+- `POST /agent/updateCustomGuardrails` - Set custom guardrails
+- `POST /agent/deleteCustomGuardrails` - Remove custom guardrails
+- `POST /agent/ask` - Send prompt, get response
+- `POST /agent/askWithAnnotations` - Get response with annotations
+- `GET /agent/revisions/{agentId}` - List revisions
+- `POST /agent/restoreRevision` - Restore revision
+- `POST /agent/deleteRevision` - Delete revision
+
+### [AI Audio API](https://docs.getsquid.ai/reference-docs/api/#tag/AI-Audio)
+Transcribe audio, text-to-speech. SDK: [ai.md](ai.md)
+- `POST /audio/transcribe` - Transcribe audio to text
+- `POST /audio/createSpeech` - Text to speech
+
+### [AI Image API](https://docs.getsquid.ai/reference-docs/api/#tag/AI-Image)
+Generate images, remove backgrounds. SDK: [ai.md](ai.md)
+- `POST /image/generate` - Generate image from prompt
+- `POST /image/removeBackground` - Remove image background
+
+### [KnowledgeBase API](https://docs.getsquid.ai/reference-docs/api/#tag/KnowledgeBase)
+Manage knowledge bases for RAG. SDK: [ai.md](ai.md)
+- `GET /knowledge-base/get/{knowledgeBaseId}` - Get knowledge base
+- `POST /knowledge-base/upsert` - Create or update knowledge base
+- `POST /knowledge-base/delete` - Delete knowledge base
+- `POST /knowledge-base/upsertContexts` - Add or update contexts
+- `POST /knowledge-base/deleteContexts` - Delete contexts
+- `GET /knowledge-base/getContext/{knowledgeBaseId}/{contextId}` - Get context
+- `GET /knowledge-base/listContexts/{knowledgeBaseId}` - List contexts
+- `POST /knowledge-base/search` - Semantic search
+
+### [Matchmaking API](https://docs.getsquid.ai/reference-docs/api/#tag/Matchmaking) *(deprecated)*
+Use `knowledgeBase().searchContextsWith*()` instead.
+
+### [Web Utilities API](https://docs.getsquid.ai/reference-docs/api/#tag/Web-Utilities)
+Web search, URL content, short URLs. SDK: [client.md](client.md)
+- `POST /web/aiSearch` - AI-powered web search
+- `POST /web/getUrlContent` - Fetch URL as markdown
+- `POST /web/createShortUrl` - Create short URL
+- `POST /web/createShortUrls` - Create multiple short URLs
+- `POST /web/deleteShortUrl` - Delete short URL
+- `POST /web/deleteShortUrls` - Delete multiple short URLs
+
+### [Database API](https://docs.getsquid.ai/reference-docs/api/#tag/Database)
+AI queries against databases. SDK: [ai.md](ai.md)
+- `POST /db/executeAiQuery` - Execute AI query
+
+### [Extraction Utilities API](https://docs.getsquid.ai/reference-docs/api/#tag/Extraction-Utilities)
+Create PDFs, extract data from documents. SDK: [client.md](client.md)
+- `POST /extraction/createPdf` - Create PDF from HTML/markdown
+- `POST /extraction/extractDataFromUrl` - Extract data from URL
+- `POST /extraction/extractDataFromFile` - Extract data from file
+
+## SDK vs REST API
+
+| Feature | SDK | REST API |
+|---------|-----|----------|
+| AI Agents | `squid.ai().agent()` | Agent API |
+| Audio | `squid.ai().audio()` | AI Audio API |
+| Image | `squid.ai().image()` | AI Image API |
+| Knowledge Bases | `squid.ai().knowledgeBase()` | KnowledgeBase API |
+| Web Utilities | `squid.web()` | Web Utilities API |
+| Extraction | `squid.extraction()` | Extraction Utilities API |

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

@@ -0,0 +1,462 @@
+# Backend SDK
+
+The Squid Backend SDK (`@squidcloud/backend`) provides TypeScript decorators and base classes for building server-side logic that runs on Squid's infrastructure.
+
+Docs: https://docs.getsquid.ai/reference-docs/backend/
+
+## Contents
+- CLI Commands
+- Project Structure
+- How Backend Runs
+- SquidService Base Class
+- Backend Functions (@executable)
+- Webhooks (@webhook)
+- Triggers (@trigger)
+- Schedulers (@scheduler)
+- Rate Limiting (@limits)
+- Client Connection State (@clientConnectionStateHandler)
+- Using Squid Client in Backend
+- File Handling
+
+## CLI Commands
+
+Install the CLI globally:
+```bash
+npm install -g @squidcloud/cli
+```
+
+**`squid init <project-name>`** - Creates a new backend project with `.env` and example service. Also populates `.claude/skills/` with Squid development skills for Claude.
+```bash
+squid init backend --appId YOUR_APP_ID --apiKey YOUR_API_KEY --environmentId dev --squidDeveloperId YOUR_DEV_ID --region us-east-1.aws
+```
+
+**`squid start`** - Runs backend locally with hot-reload. Connects to Squid Cloud via reverse proxy.
+```bash
+cd backend && squid start
+```
+
+**`squid deploy`** - Builds and deploys to Squid Cloud.
+```bash
+squid deploy [--apiKey KEY] [--environmentId prod] [--skipBuild]
+```
+
+**`squid build`** - Builds backend project without deploying.
+```bash
+squid build [--dev] [--skip-version-check]
+```
+
+**Extended logging** - Add to `.env`:
+```env
+SQUID_LOG_TYPES=QUERY,MUTATION,AI,API,ERROR
+```
+
+## Project Structure
+
+After running `squid init`, your backend project has this structure:
+
+```
+backend/
+├── .env                    # Environment config: SQUID_APP_ID, SQUID_API_KEY, SQUID_ENVIRONMENT_ID, SQUID_REGION
+├── package.json            # Dependencies: @squidcloud/backend, devDeps: @squidcloud/cli
+├── tsconfig.json           # TypeScript configuration
+├── src/
+│   ├── index.ts            # Entry point - exports SquidProject and all services
+│   ├── service/            # All SquidService classes go here
+│   │   ├── index.ts        # Re-exports all services (e.g., export * from './example-service')
+│   │   └── *.ts            # Your SquidService classes with decorators
+│   └── public/             # Static assets (accessible via this.assetsDirectory)
+└── dist/                   # Build output
+```
+
+**Key files:**
+- `src/index.ts` - Must export a `SquidProject` instance and all services
+- `src/service/index.ts` - Re-exports all service files so they're included in the bundle
+- `.env` - Contains credentials from Squid Console (never commit to git)
+
+## How Backend Runs
+
+**Local development (`squid start`):**
+- Runs your backend code on your machine
+- Hot-reload on file changes
+- Connects to Squid Cloud via reverse proxy
+- Your code can access integrations configured in Console
+
+**Production (`squid deploy`):**
+- Builds and uploads your code to Squid Cloud
+- Squid Cloud runs your backend in a managed environment
+- Multiple backend instances can be configured for scaling
+
+## SquidService Base Class
+
+All backend services extend `SquidService`:
+
+```typescript
+import { SquidService } from '@squidcloud/backend';
+
+export class MyService extends SquidService {
+  // Decorated methods
+}
+```
+
+**Important:** In backend code running on Squid's infrastructure, the Squid client is **already initialized and available** via `this.squid`. You don't need to manually create a new instance or provide configuration parameters.
+
+### Available Properties
+
+```typescript
+this.region          // 'local' during dev, region in production
+this.backendBaseUrl
+this.secrets         // From Squid Console
+this.apiKeys
+this.context         // RunContext (appId, clientId, sourceIp, headers, openApiContext)
+this.squid           // Pre-initialized Squid client (initialized with admin API key, full permissions)
+this.assetsDirectory // Path to public/ folder
+```
+
+### Auth Methods
+
+```typescript
+// Get user authentication (JWT token)
+this.getUserAuth() // AuthWithBearer | undefined
+  // Returns: { type: 'Bearer', userId: string, expiration: number, attributes: Record<string, any>, jwt?: string }
+
+// Get API key authentication
+this.getApiKeyAuth() // AuthWithApiKey | undefined
+  // Returns: { type: 'ApiKey', apiKey: string }
+
+this.isAuthenticated()     // boolean - true if user token OR API key
+this.assertIsAuthenticated() // throws if not authenticated
+this.assertApiKeyCall()    // throws if not API key auth
+```
+
+**Example: Getting User Info**
+```typescript
+@executable()
+async getUserData(): Promise<UserData> {
+  this.assertIsAuthenticated();
+  const userId = this.getUserAuth()?.userId;
+  if (!userId) throw new Error('User not authenticated');
+  return await fetchUserData(userId);
+}
+```
+
+### Helper Methods
+
+```typescript
+// Create webhook response (for @webhook decorated functions)
+this.createWebhookResponse(body?, statusCode?, headers?)
+// Throws webhook response immediately (interrupts execution)
+this.throwWebhookResponse({ body?, statusCode?, headers? })
+
+// Create OpenAPI response (for OpenAPI/tsoa decorated functions)
+this.createOpenApiResponse(body?, statusCode?, headers?)
+// Throws OpenAPI response immediately (interrupts execution)
+this.throwOpenApiResponse({ body?, statusCode?, headers? })
+
+// Convert browser File to SquidFile for OpenAPI file returns
+await this.convertToSquidFile(file: File): Promise<SquidFile>
+
+// Publish AI status update to specific client (used in @aiFunction)
+await this.publishAiStatusUpdate(update: AiStatusMessage, clientId: ClientId)
+```
+
+## Backend Functions (@executable)
+
+Backend functions allow you to write custom server-side logic that can be called from the client.
+
+### Backend Definition
+
+```typescript
+import { SquidService, executable, SquidFile } from '@squidcloud/backend';
+
+export class MyService extends SquidService {
+  @executable()
+  async greetUser(name: string): Promise<string> {
+    return `Hello, ${name}`;
+  }
+
+  @executable()
+  async uploadFile(file: SquidFile): Promise<Result> {
+    console.log(file.originalName, file.size, file.data);
+    return { success: true };
+  }
+}
+```
+
+### Client Invocation
+
+```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
+);
+```
+
+## Webhooks (@webhook)
+
+Webhooks allow you to create publicly accessible HTTP endpoints that can receive data from external services.
+
+### Backend Definition
+
+```typescript
+import { SquidService, webhook, WebhookRequest } from '@squidcloud/backend';
+
+export class MyService extends SquidService {
+  @webhook('github-events')
+  async handleGithub(request: WebhookRequest): Promise<any> {
+    console.log(request.body);
+    console.log(request.headers);
+    console.log(request.queryParams);
+    console.log(request.httpMethod); // 'post' | 'get' | 'put' | 'delete'
+    console.log(request.files);
+
+    return this.createWebhookResponse({ received: true }, 200);
+  }
+}
+```
+
+**Webhook URL:** `https://<appId>.<region>.squid.cloud/webhooks/<webhook-id>`
+
+### Client Usage
+
+```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
+
+// Call webhook programmatically (optional)
+// Usually webhooks are called by external services
+const result = await squid.executeWebhook<Response>('github-events', {
+  headers: { 'X-GitHub-Event': 'push' },
+  queryParams: { ref: 'main' },
+  body: { commits: [...] },
+  files: [file1, file2]
+});
+```
+
+## Triggers (@trigger)
+
+Triggers respond to database document changes (insert, update, delete).
+
+```typescript
+import { SquidService, trigger, TriggerRequest } from '@squidcloud/backend';
+
+export class MyService extends SquidService {
+  // Using options object (recommended)
+  @trigger({ collection: 'users', mutationTypes: ['insert'] })
+  async onUserCreated(request: TriggerRequest<User>): Promise<void> {
+    console.log(request.mutationType);  // 'insert' | 'update' | 'delete'
+    console.log(request.docId);         // Document ID
+    console.log(request.collectionName);
+    console.log(request.integrationId);
+    console.log(request.docBefore);     // undefined for insert
+    console.log(request.docAfter);      // undefined for delete
+  }
+
+  // Custom ID and specific integration
+  @trigger({ id: 'order-update', collection: 'orders', integrationId: 'my-postgres' })
+  async onOrderChange(request: TriggerRequest<Order>): Promise<void> {
+    if (request.mutationType === 'update') {
+      const before = request.docBefore;
+      const after = request.docAfter;
+      // Handle order update
+    }
+  }
+
+  // Positional arguments (legacy)
+  @trigger('user-deleted', 'users')
+  async onUserDeleted(request: TriggerRequest<User>): Promise<void> {
+    // Called for all mutation types on 'users' collection
+  }
+}
+```
+
+**TriggerOptions:**
+- `id?: string` - Trigger ID (defaults to `ClassName.FunctionName`)
+- `collection: string` - Collection name to watch
+- `integrationId?: string` - Database integration (defaults to `built_in_db`)
+- `mutationTypes?: ('insert' | 'update' | 'delete')[]` - Filter by mutation types
+
+**TriggerRequest<T>:**
+- `mutationType` - The type of mutation ('insert' | 'update' | 'delete')
+- `docId` - Document ID
+- `collectionName` - Collection name
+- `integrationId` - Integration ID
+- `docBefore?: T` - Document state before mutation (undefined for insert)
+- `docAfter?: T` - Document state after mutation (undefined for delete)
+
+## Schedulers (@scheduler)
+
+Schedules periodic execution using cron expressions.
+
+```typescript
+import { SquidService, scheduler, CronExpression } from '@squidcloud/backend';
+
+export class MyService extends SquidService {
+  // Using cron string directly
+  @scheduler({ id: 'daily-cleanup', cron: '0 0 * * *' }) // Daily at midnight UTC
+  async cleanup(): Promise<void> {
+    console.log('Running cleanup');
+  }
+
+  // Using predefined CronExpression enum
+  @scheduler({ id: 'hourly-sync', cron: CronExpression.EVERY_HOUR })
+  async hourlySync(): Promise<void> {
+    console.log('Running hourly sync');
+  }
+
+  @scheduler({ id: 'weekday-morning', cron: CronExpression.MONDAY_TO_FRIDAY_AT_9AM })
+  async weekdayTask(): Promise<void> {
+    console.log('Running weekday morning task');
+  }
+
+  @scheduler({ id: 'frequent', cron: CronExpression.EVERY_5_MINUTES, exclusive: false })
+  async frequentTask(): Promise<void> {
+    // exclusive: false allows concurrent runs
+  }
+}
+```
+
+**Common CronExpression values:**
+- `EVERY_SECOND`, `EVERY_5_SECONDS`, `EVERY_10_SECONDS`, `EVERY_30_SECONDS`
+- `EVERY_MINUTE`, `EVERY_5_MINUTES`, `EVERY_10_MINUTES`, `EVERY_30_MINUTES`
+- `EVERY_HOUR`, `EVERY_2_HOURS`, `EVERY_3_HOURS`, etc.
+- `EVERY_DAY_AT_MIDNIGHT`, `EVERY_DAY_AT_NOON`, `EVERY_DAY_AT_1AM`, etc.
+- `EVERY_WEEKDAY`, `EVERY_WEEKEND`, `EVERY_WEEK`
+- `MONDAY_TO_FRIDAY_AT_9AM`, `MONDAY_TO_FRIDAY_AT_5PM`, etc.
+- `EVERY_1ST_DAY_OF_MONTH_AT_MIDNIGHT`, `EVERY_QUARTER`, `EVERY_YEAR`
+
+### Client Management
+
+```typescript
+const schedulers = squid.schedulers;
+
+// List all
+const all = await schedulers.list();
+
+// Enable/disable
+await schedulers.enable('daily-cleanup');
+await schedulers.enable(['scheduler-1', 'scheduler-2']);
+
+await schedulers.disable('hourly-sync');
+await schedulers.disable(['scheduler-1', 'scheduler-2']);
+```
+
+## Rate Limiting (@limits)
+
+Apply rate limits and quotas to functions.
+
+```typescript
+import { SquidService, executable, limits } from '@squidcloud/backend';
+
+export class MyService extends SquidService {
+  // Simple rate limit (5 QPS globally)
+  @limits({ rateLimit: 5 })
+  @executable()
+  async limited(): Promise<void> {}
+
+  // Quota (100 calls/month per user)
+  @limits({ quotaLimit: { value: 100, scope: 'user', renewPeriod: 'monthly' } })
+  @executable()
+  async quotaLimited(): Promise<void> {}
+
+  // Multiple limits
+  @limits({
+    rateLimit: [
+      { value: 100, scope: 'global' },
+      { value: 10, scope: 'user' }
+    ],
+    quotaLimit: [
+      { value: 10000, scope: 'global', renewPeriod: 'monthly' },
+      { value: 500, scope: 'user', renewPeriod: 'weekly' }
+    ]
+  })
+  @executable()
+  async multiLimited(): Promise<void> {}
+}
+```
+
+**Scopes:** `'global'`, `'user'`, `'ip'`
+**Periods:** `'hourly'`, `'daily'`, `'weekly'`, `'monthly'`, `'quarterly'`, `'annually'`
+
+## Client Connection State (@clientConnectionStateHandler)
+
+Handle client connection and disconnection events.
+
+```typescript
+import { SquidService, clientConnectionStateHandler, ClientConnectionState } from '@squidcloud/backend';
+import { ClientId } from '@squidcloud/client';
+
+export class MyService extends SquidService {
+  @clientConnectionStateHandler()
+  async handleConnectionState(
+    clientId: ClientId,
+    state: ClientConnectionState
+  ): Promise<void> {
+    if (state === 'CONNECTED') {
+      console.log('Client connected:', clientId);
+    } else if (state === 'DISCONNECTED') {
+      console.log('Client disconnected:', clientId);
+    } else if (state === 'REMOVED') {
+      console.log('Client removed:', clientId);
+    }
+  }
+}
+```
+
+**ClientConnectionState values:**
+- `'CONNECTED'` - Client just connected
+- `'DISCONNECTED'` - Client disconnected but ID still retained
+- `'REMOVED'` - Client disconnected and ID removed
+
+## Using Squid Client in Backend
+
+The pre-initialized `this.squid` client has full permissions:
+
+```typescript
+export class MyService extends SquidService {
+  @executable()
+  async aggregateStats(userId: string): Promise<Stats> {
+    // this.squid has API key permissions - full access
+    const orders = await this.squid.collection('orders')
+      .query()
+      .eq('userId', userId)
+      .snapshot();
+
+    return { totalOrders: orders.data.length };
+  }
+}
+```
+
+## File Handling
+
+```typescript
+// Receiving files in backend functions
+@executable()
+async processFile(file: SquidFile): Promise<Result> {
+  console.log(file.originalName); // Original filename
+  console.log(file.size);         // File size in bytes
+  console.log(file.mimetype);     // MIME type
+  const content = new TextDecoder().decode(file.data); // Read as text
+  return { processed: true };
+}
+```
+
+For AI-related decorators (`@aiFunction`, `@secureAiAgent`, etc.), see [ai.md](ai.md).
+For security decorators (`@secureDatabase`, `@secureCollection`, etc.), see [security.md](security.md).
+
+## Best Practices
+
+1. **Don't store state in class properties** - Use collections instead (instances may restart or scale)
+2. **Validate input in executables** - Always check auth and validate parameters before processing
+3. **Never commit `.env` to git** - Contains credentials from Squid Console
+4. **Use options object for decorators** - Prefer `@trigger({ collection: 'users' })` over positional args (legacy)