@squidcloud/cli 1.0.445 → 1.0.447

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

@@ -0,0 +1,472 @@
+# Database & Data Management
+
+Squid provides database functionality similar to Firestore but more powerful, with collections, document references, and real-time capabilities. Squid supports multiple database types including NoSQL databases (like MongoDB) and relational databases (like PostgreSQL, MySQL).
+
+## Contents
+- Collection Access
+- Document References
+- CRUD Operations
+- Real-time Subscriptions
+- Query Operators
+- OR Queries
+- Join Queries
+- Dereference
+- Pagination
+- Watch Changes
+- Transactions
+- Numeric Operations
+- Native Queries
+- Backend Decorator: @trigger
+- Schema Discovery
+
+## Collection Access
+
+A collection represents a set of documents (similar to a table in relational databases or a collection in NoSQL databases).
+
+```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');
+```
+
+**Type parameter**: The generic type `<T>` defines the structure of documents in the collection.
+
+## Document References
+
+The `doc()` method has different behaviors:
+
+### No parameters - `doc()`
+Generates a new document ID (useful for creating new documents):
+```typescript
+// For built_in_db without schema - generates a random ID
+const newDocRef = collection.doc();
+await newDocRef.insert({ name: 'John', age: 30 });
+
+// For other integrations - creates a placeholder that gets resolved on insert
+const newDocRef = collection.doc();
+```
+
+### String parameter - `doc(stringId)`
+**Only supported for `built_in_db` integration without a defined schema:**
+```typescript
+// Valid only for built_in_db collections without schema
+const docRef = collection.doc('my-doc-id');
+const docRef = collection.doc('user-12345');
+```
+**Important**: For collections with defined schemas or non-built_in_db integrations, you must use object format.
+
+### Object parameter - `doc({id: value})`
+Used for collections with defined primary keys. The object maps primary key field names to their values:
+```typescript
+// Single primary key field "id"
+const docRef = collection.doc({ id: 'user-123' });
+
+// Single primary key field "userId"
+const docRef = collection.doc({ userId: 42 });
+
+// Composite primary key (id1, id2)
+const docRef = collection.doc({ id1: 'part1', id2: 'part2' });
+
+// Partial primary key - missing fields generated on server if supported
+const docRef = collection.doc({ id1: 'part1' }); // id2 generated on insert
+```
+
+**Key points about document IDs:**
+- For `built_in_db` without schema: can use string IDs or object format
+- For `built_in_db` with schema: must use object format matching primary key fields
+- For other integrations: must use object format matching primary key fields
+- Partial primary keys: missing fields may be auto-generated on insert (if integration supports it)
+- Empty `doc()`: generates a placeholder ID that gets resolved when document is created
+
+## CRUD Operations
+
+```typescript
+// Insert
+await userDoc.insert({ name: 'John', email: 'john@example.com' });
+
+// Update (partial)
+await userDoc.update({ name: 'Jane' });
+
+// Update specific path
+await userDoc.setInPath('address.street', 'Main St');
+
+// Delete specific path
+await userDoc.deleteInPath('tempData');
+
+// Delete document
+await userDoc.delete();
+
+// Get data (promise)
+const userData = await userDoc.snapshot();
+console.log(userData);
+
+// Get data (observable - realtime)
+userDoc.snapshots().subscribe(data => {
+  console.log(data);
+});
+
+// Get cached data (no server fetch)
+const cached = userDoc.peek();
+
+// Check if document has data populated
+if (userDoc.hasData) {
+  console.log('Document is loaded');
+  // Access data directly (with defensive copy)
+  console.log(userDoc.data);
+}
+
+// Bulk operations
+await users.insertMany([
+  { id: 'user-1', data: { name: 'Alice' } },
+  { id: 'user-2', data: { name: 'Bob' } }
+]);
+
+await users.deleteMany(['user-1', 'user-2']);
+```
+
+## Real-time Subscriptions
+
+Squid provides real-time data synchronization. Subscribe to document or query changes and receive updates automatically.
+
+### Document Subscriptions
+```typescript
+// Subscribe to document changes
+const subscription = docRef.snapshots().subscribe((userData) => {
+  if (userData) {
+    console.log('Document updated:', userData);
+  } else {
+    console.log('Document deleted or does not exist');
+  }
+});
+
+// Unsubscribe when done
+subscription.unsubscribe();
+```
+
+### Query Subscriptions
+```typescript
+// Subscribe to query results - ALWAYS use dereference()
+const subscription = collection
+  .query()
+  .eq('status', 'active')
+  .gte('age', 18)
+  .dereference()  // Important: Converts DocumentReferences to actual data
+  .snapshots()
+  .subscribe((users) => {
+    console.log('Active users updated:', users);
+    // users is Array<User> with actual data
+  });
+
+// Unsubscribe when done
+subscription.unsubscribe();
+```
+
+### Real-time Updates
+When data changes on the server (from any client or backend operation):
+- Document subscriptions receive the updated document data
+- Query subscriptions receive the updated query results
+- Updates are pushed to clients via WebSocket connections
+- Changes are automatically reflected in the local data
+
+**Important**: Always unsubscribe from subscriptions when they're no longer needed to prevent memory leaks.
+
+## Query Operators
+
+**ALL Available Operators:**
+- Comparison: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`
+- Arrays: `in`, `nin`, `arrayIncludesSome`, `arrayIncludesAll`, `arrayNotIncludes`
+- Patterns: `like`, `notLike` (% = any chars, _ = one char)
+
+```typescript
+// Basic query
+const activeUsers = await users.query()
+  .eq('status', 'active')
+  .gt('age', 18)
+  .sortBy('name', true) // true = ascending
+  .limit(100) // max 20000, default 1000
+  .snapshot();
+
+activeUsers.data.forEach(doc => {
+  console.log(doc.data); // Document data
+});
+
+// Realtime query
+users.query()
+  .eq('status', 'active')
+  .snapshots().subscribe(snapshot => {
+    snapshot.data.forEach(doc => console.log(doc.data));
+  });
+
+// Pattern matching (CASE-INSENSITIVE by default)
+const results = await users.query()
+  .like('email', '%.com') // case-insensitive by default
+  .snapshot();
+
+// Case-sensitive pattern matching
+const caseSensitive = await users.query()
+  .like('name', 'John%', true) // third parameter: caseSensitive = true
+  .snapshot();
+
+// Array operators
+const tagged = await posts.query()
+  .in('category', ['tech', 'news'])
+  .arrayIncludesSome('tags', ['urgent', 'important'])
+  .snapshot();
+
+// Using where() method (all operators above are shortcuts for where)
+const results1 = await users.query().eq('status', 'active').snapshot();
+const results2 = await users.query().where('status', '==', 'active').snapshot();
+// These are equivalent
+
+// Multiple sort
+const sorted = await users.query()
+  .sortBy('lastName', true)
+  .sortBy('firstName', true)
+  .limit(50)
+  .snapshot();
+```
+
+**Note:** `offset()` does NOT exist - use `paginate()` for pagination.
+
+## OR Queries
+
+Combine multiple queries with OR logic:
+
+```typescript
+const query1 = users.query().eq('status', 'active');
+const query2 = users.query().eq('status', 'pending');
+const orResults = await users.or(query1, query2)
+  .dereference()
+  .snapshot();
+// Returns documents matching either query
+// Note: Results are merged and deduplicated
+```
+
+## Join Queries
+
+Combine data from multiple collections:
+
+```typescript
+// Start with joinQuery() and alias
+const results = await teachers
+  .joinQuery('teacher')  // Alias for teachers collection
+  .join(
+    students.query(),
+    'students',           // Alias for students collection
+    { left: 'id', right: 'teacherId' }  // Join condition
+  )
+  .dereference()  // Important: converts refs to actual data
+  .snapshot();
+// Results: Array<{ teacher: Teacher, students?: Student }>
+
+// Inner join (only matching records)
+const innerResults = await teachers
+  .joinQuery('teacher')
+  .join(
+    students.query(),
+    'students',
+    { left: 'id', right: 'teacherId' },
+    { isInner: true }  // Inner join option
+  )
+  .dereference()
+  .snapshot();
+
+// Multi-level joins
+const threeWay = await collection1
+  .joinQuery('a')
+  .join(collection2.query(), 'b', { left: 'id', right: 'parentId' })
+  .join(collection3.query(), 'c', { left: 'id', right: 'grandParentId' })
+  .dereference()
+  .snapshot();
+
+// Grouped joins (nests one-to-many as arrays)
+const grouped = await teachers
+  .joinQuery('teacher')
+  .join(students.query(), 'students', { left: 'id', right: 'teacherId' })
+  .grouped()
+  .dereference()
+  .snapshot();
+// Results: Array<{ teacher: Teacher, students: Student[] }>
+```
+
+## Dereference
+
+Converts DocumentReferences to actual data:
+
+```typescript
+// WITHOUT dereference: returns Array<DocumentReference<User>>
+const refs = await users.query().eq('active', true).snapshot();
+// refs.data[0].data to access actual data
+
+// WITH dereference: returns Array<User> directly
+const userData = await users.query()
+  .eq('active', true)
+  .dereference()
+  .snapshot();
+// userData[0] is the actual user object
+
+// ALWAYS use dereference() for:
+// - Real-time subscriptions (makes working with data easier)
+// - When you need document data directly
+// DON'T use dereference() if:
+// - You need DocumentReference methods like .update() or .delete()
+```
+
+## Pagination
+
+```typescript
+const pagination = users.query()
+  .sortBy('createdAt', false)
+  .dereference()
+  .paginate({
+    pageSize: 50,       // Number of items per page (default: 100)
+    subscribe: true     // Subscribe to real-time updates (default: true)
+  });
+
+const firstPage = await pagination.first();  // Jump to first page
+const nextPage = await pagination.next();    // Go to next page
+const prevPage = await pagination.prev();    // Go to previous page
+
+// Check pagination state
+console.log(firstPage.hasNext);  // boolean
+console.log(firstPage.hasPrev);  // boolean
+```
+
+## Watch Changes
+
+```typescript
+users.query()
+  .eq('status', 'active')
+  .changes()
+  .subscribe(changes => {
+    console.log('Inserts:', changes.inserts);
+    console.log('Updates:', changes.updates);
+    console.log('Deletes:', changes.deletes);
+  });
+```
+
+## Transactions
+
+```typescript
+await squid.runInTransaction(async (txId) => {
+  const userRef = squid.collection('users').doc('user-1');
+  const accountRef = squid.collection('accounts').doc('acc-1');
+
+  // Pass txId as last parameter to each operation
+  // Use incrementInPath/decrementInPath for numeric operations
+  await userRef.decrementInPath('balance', 100, txId);
+  await accountRef.incrementInPath('balance', 100, txId);
+
+  // Both commit together or rollback together
+});
+```
+
+## Numeric Operations
+
+```typescript
+// Increment/decrement
+await userDoc.incrementInPath('loginCount', 1);
+await userDoc.decrementInPath('credits', 50);
+
+// For arrays/objects, use update() with full new value
+const currentData = await userDoc.snapshot();
+await userDoc.update({
+  tags: [...currentData.tags, 'newTag'],
+  notifications: [...currentData.notifications, { msg: 'Hi' }]
+});
+```
+
+## Native Queries
+
+For advanced queries that require database-specific syntax:
+
+### SQL (PostgreSQL, MySQL, etc.)
+Uses `${param}` syntax for parameters:
+```typescript
+const users = await squid.executeNativeRelationalQuery<User[]>(
+  'postgres-db',
+  'SELECT * FROM users WHERE age > ${minAge}',
+  { minAge: 18 }
+);
+```
+
+### MongoDB Aggregation
+```typescript
+const orders = await squid.executeNativeMongoQuery<Order[]>(
+  'mongo-db',
+  'orders',
+  [
+    { $match: { status: 'completed' } },
+    { $group: { _id: '$userId', total: { $sum: '$amount' } } }
+  ]
+);
+```
+
+### Elasticsearch
+```typescript
+const products = await squid.executeNativeElasticQuery(
+  'elastic-db',
+  'products',
+  { query: { match: { name: 'laptop' } } },
+  '_search', // endpoint (optional)
+  'GET' // method (optional)
+);
+```
+
+### Pure (Finos Legend Pure Language)
+Uses `${param}` syntax:
+```typescript
+const items = await squid.executeNativePureQuery(
+  'my-db',
+  'from products->filter(p | $p.price < ${maxPrice})',
+  { maxPrice: 1000 }
+);
+```
+
+## Backend Decorator: @trigger
+
+Responds to database collection changes:
+
+```typescript
+import { SquidService, trigger, TriggerRequest } from '@squidcloud/backend';
+
+export class MyService extends SquidService {
+  @trigger({ id: 'user-created', collection: 'users', mutationTypes: ['insert'] })
+  async onUserCreated(request: TriggerRequest<User>): Promise<void> {
+    console.log(request.mutationType); // 'insert' | 'update' | 'delete'
+    console.log(request.docBefore);
+    console.log(request.docAfter);
+  }
+}
+```
+
+## Schema Discovery
+
+AI-powered schema analysis for database integrations:
+
+```typescript
+const integrations = squid.admin().integrations();
+
+// Discover schema from a database connection
+const discovered = await integrations.discoverDataConnectionSchema('postgres-db');
+console.log(discovered.schema);              // Discovered tables, columns, relationships
+console.log(discovered.collectionReadiness); // Permission and replication status
+
+// Generate AI descriptions for data schema
+const schemaResult = await integrations.generateAiDescriptionsForDataSchema('postgres-db', {
+  schema: currentSchema,
+  collections: ['users', 'orders'],
+  instructions: 'Use business terminology'
+});
+```
+
+For security rules on databases, see [security.md](security.md).
+
+## Best Practices
+
+1. **Use transactions for multi-doc updates** - Atomic operations prevent partial updates
+2. **Limit query results** - Default 1000, max 20000
+3. **Use snapshots for one-time data** - Use subscriptions only for real-time needs
+4. **Batch operations when possible** - Use insertMany, deleteMany for efficiency

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

@@ -0,0 +1,98 @@
+# OpenAI Provider Features
+
+OpenAI-specific features in Squid. For general AI usage, see [ai.md](ai.md).
+
+## Model Constants
+
+```typescript
+import {
+  OPENAI_CHAT_MODEL_NAMES,                  // Chat models
+  OPENAI_IMAGE_MODEL_NAMES,                 // DALL-E
+  OPENAI_AUDIO_TRANSCRIPTION_MODEL_NAMES,   // Whisper
+  OPENAI_AUDIO_CREATE_SPEECH_MODEL_NAMES,   // TTS
+  OPENAI_EMBEDDINGS_MODEL_NAMES,            // Embeddings
+} from '@squidcloud/client';
+```
+
+**Source of truth:** `node_modules/@squidcloud/client/dist/internal-common/src/public-types/ai-common.public-types.d.ts`
+
+## OpenAI-Specific Parameters
+
+### Verbosity Control
+
+Controls response length. OpenAI plain text responses only (ignored for other providers).
+
+```typescript
+const response = await agent.ask('Explain quantum computing', {
+  verbosity: 'low'  // 'low' | 'medium' | 'high'
+});
+```
+
+### Reasoning Models
+
+o-series and gpt-5 series models support `reasoningEffort` (no temperature support):
+
+```typescript
+const response = await agent.ask('Complex problem...', {
+  reasoningEffort: 'high'  // 'minimal' | 'low' | 'medium' | 'high'
+});
+```
+
+## Code Interpreter
+
+Execute Python code with file access. Supported by **OpenAI, Gemini, and Claude** models.
+
+```typescript
+const response = await agent.ask('Analyze this data', {
+  useCodeInterpreter: 'llm',
+  fileIds: [fileId]  // from squid.ai().files('openai').uploadFile()
+});
+```
+
+### Squid's Built-in Code Interpreter
+
+Squid also provides its own code interpreter via the `executePythonCode` AI function, which executes prepared Python code independently of the LLM provider.
+
+## File Upload
+
+```typescript
+const aiFiles = squid.ai().files('openai');
+const fileId = await aiFiles.uploadFile({ file: myFile, purpose: 'assistants' });
+await aiFiles.deleteFile(fileId);
+```
+
+## Voice (TTS)
+
+```typescript
+const voiceResult = await agent.askWithVoiceResponse('Hello', {
+  voiceOptions: {
+    modelName: 'tts-1',  // see OPENAI_AUDIO_CREATE_SPEECH_MODEL_NAMES
+    voice: 'alloy',      // alloy, ash, ballad, coral, echo, fable, onyx, nova, sage, shimmer, verse
+    speed: 1.0           // 0.25 to 4.0
+  }
+});
+```
+
+## Image Generation (DALL-E)
+
+```typescript
+const imageUrl = await squid.ai().image().generate('A futuristic city', {
+  modelName: 'dall-e-3',
+  quality: 'hd',        // 'hd' | 'standard'
+  size: '1024x1024'     // '1024x1024' | '1792x1024' | '1024x1792'
+});
+```
+
+## Audio Transcription (Whisper)
+
+```typescript
+const text = await squid.ai().audio().transcribe(audioFile, {
+  modelName: 'whisper-1',
+  language: 'en',
+  responseFormat: 'text'  // 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'
+});
+```
+
+## OpenAI-Compatible Providers
+
+Squid supports any OpenAI-compatible API via `openai_compatible` integration type. Configure with custom `baseUrl`, API key, and model list. Supports chat and function calling (not code interpreter).