@squidcloud/cli 1.0.446 → 1.0.447

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

@@ -0,0 +1,242 @@
+# Admin & Management
+
+This document covers programmatic management of Squid organizations, applications, integrations, and secrets.
+
+## Contents
+- ManagementClient
+- Admin Integrations
+- Admin Secrets
+
+## ManagementClient
+
+The ManagementClient provides programmatic management of Squid organizations and applications using management API keys.
+
+### Creating Management API Keys
+
+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>`
+
+### Usage
+
+```typescript
+import { ManagementClient } from '@squidcloud/client';
+
+// Initialize with management API key
+const client = new ManagementClient({
+  apiKey: 'squid_mgmt_xxx...',  // From Console Profile Settings
+  consoleRegion: 'us-east-1.aws'  // Your Squid region
+});
+
+// Create an organization
+const { organizationId } = await client.createOrganization({
+  name: 'My Organization'  // 2-50 characters
+});
+console.log('Created org:', organizationId);
+
+// Create an application in the organization
+const { appId, devApiKey, prodApiKey } = await client.createApplication({
+  organizationId,
+  name: 'My Application',
+  region: 'us-east-1.aws'  // SquidRegion (e.g., 'us-east-1.aws', 'us-central1.gcp')
+});
+console.log('Created app:', appId);
+
+// Delete an application
+await client.deleteApplication(appId);
+```
+
+### Available Methods
+
+| Method | Description |
+|--------|-------------|
+| `createOrganization({ name })` | Creates a new organization. User becomes admin. |
+| `createApplication({ organizationId, name, region })` | Creates an application in an organization. Returns `{ appId, devApiKey, prodApiKey }`. |
+| `deleteApplication(appId)` | Deletes an application. Requires admin role. |
+
+### TypeScript Types
+
+```typescript
+import {
+  ManagementClient,
+  ManagementClientOptions,
+  ManagementCreateOrganizationRequest,
+  ManagementCreateOrganizationResponse,
+  ManagementCreateApplicationRequest,
+  ManagementCreateApplicationResponse,
+} from '@squidcloud/client';
+```
+
+### Key Points
+
+- Management API keys are tied to a user account
+- The user associated with the key becomes the organization admin
+- Keys can be suspended/reactivated/deleted in Console Profile Settings
+- Different from app API keys (which bypass security rules)
+- Use for CI/CD pipelines, automation scripts, and programmatic management
+
+### Use Cases
+
+- Automated tenant provisioning (multi-tenant SaaS)
+- CI/CD pipeline integration
+- Infrastructure-as-code workflows
+- Programmatic organization management
+- Automated testing environments
+
+## Admin - Integrations
+
+**Important:** Admin methods require initialization with an API key. They cannot be used with user authentication.
+
+```typescript
+// Squid must be initialized with apiKey
+const squid = new Squid({ appId: 'app-id', region: 'us-east-1.aws', apiKey: 'your-api-key' });
+
+const integrations = squid.admin().integrations();
+
+// List all or by type
+const all = await integrations.list();
+const databases = await integrations.list('database');
+
+// Get one
+const integration = await integrations.get('postgres-db');
+
+// Create/update
+await integrations.upsertIntegration({
+  id: 'my-postgres',
+  type: 'postgres',
+  connectionString: 'postgresql://...'
+});
+
+// Delete
+await integrations.delete('old-integration');
+await integrations.deleteMany(['int-1', 'int-2']);
+
+// Get integration schema
+const schema = await integrations.getIntegrationSchema<MySchemaType>('postgres-db');
+console.log(schema);
+
+// Set integration schema
+await integrations.setIntegrationSchema('postgres-db', {
+  collections: [
+    {
+      name: 'users',
+      fields: [
+        { name: 'id', type: 'string', primaryKey: true },
+        { name: 'email', type: 'string' },
+        { name: 'name', type: 'string' }
+      ]
+    }
+  ]
+});
+
+// Generate AI descriptions for data schema (collections and fields)
+const schemaResult = await integrations.generateAiDescriptionsForDataSchema('postgres-db', {
+  schema: currentSchema,                    // The current schema of the integration
+  collections: ['users', 'orders'],         // Optional: specific collections to generate for
+  instructions: 'Use business terminology'  // Optional: guide the AI
+});
+console.log(schemaResult.schema); // Schema with AI-generated descriptions
+
+// Generate AI descriptions for associations (relationships between entities)
+const assocResult = await integrations.generateAiDescriptionsForAssociations('postgres-db', {
+  schema: currentSchema,
+  associations: ['User_Order'],             // Optional: specific associations to generate for
+  instructions: 'Explain the business relationship'
+});
+
+// Generate AI descriptions for stored procedures
+const spResult = await integrations.generateAiDescriptionsForStoredProcedures('postgres-db', {
+  schema: currentSchema,
+  storedProcedures: ['calculate_totals'],   // Optional: specific procedures to generate for
+  instructions: 'Describe what the procedure does'
+});
+
+// Generate AI descriptions for API endpoints
+const apiResult = await integrations.generateAiDescriptionsForEndpoints('my-api', {
+  schema: apiSchema,
+  endpoints: ['GET /users', 'POST /orders'], // Optional: specific endpoints to generate for
+  instructions: 'Use REST API terminology'
+});
+
+// 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
+
+// Test a database connection to verify it is working (before or after saving)
+const testResult = await integrations.testDataConnection({
+  id: 'my-postgres',
+  type: 'postgres',
+  configuration: {
+    connectionOptions: {
+      host: 'localhost',
+      port: 5432,
+      database: 'mydb',
+      user: 'user',
+      secrets: { password: 'pass' }
+    }
+  }
+});
+if (testResult.success) {
+  console.log('Connection successful!');
+} else {
+  console.log('Connection failed:', testResult.errorMessage);
+}
+
+// Discover schema from a GraphQL endpoint
+const graphqlSchema = await integrations.discoverGraphQLConnectionSchema('my-graphql', {
+  connectionOptions: {
+    url: 'https://api.example.com/graphql',
+    headers: { 'Authorization': 'Bearer token' }
+  }
+});
+
+// Discover schema from an OpenAPI spec URL
+const openApiSchema = await integrations.discoverOpenApiSchema('my-api', {
+  discoveryOptions: {
+    openApiSpecUrl: 'https://api.example.com/openapi.json',
+    headers: { 'Authorization': 'Bearer token' }
+  }
+});
+
+// Discover schema from an uploaded OpenAPI spec file
+const fileSchema = await integrations.discoverOpenApiSchemaFromFile('my-api');
+```
+
+### Admin - Secrets
+
+```typescript
+const secrets = squid.admin().secrets();
+
+// Get secret (returns SecretEntry | undefined, not just the value)
+const secret = await secrets.get('STRIPE_KEY');
+const value = secret?.value;
+
+// Get all
+const all = await secrets.getAll();
+
+// Create/update
+await secrets.upsert('API_KEY', 'secret-value');
+await secrets.upsertMany([
+  { key: 'KEY1', value: 'val1' },
+  { key: 'KEY2', value: 'val2' }
+]);
+
+// Delete
+await secrets.delete('OLD_KEY');
+await secrets.deleteMany(['KEY1', 'KEY2']);
+
+// API Keys
+const apiKeys = secrets.apiKeys;
+await apiKeys.upsert('my-key');
+const key = await apiKeys.get('my-key');
+const allApiKeys = await apiKeys.getAll(); // Get all API keys
+await apiKeys.delete('my-key');
+```
+
+## Best Practices
+
+1. **Copy management API key immediately** - Key value is shown only once when created
+2. **Admin methods require API key** - Cannot use user authentication, must initialize Squid with `apiKey`
+3. **Management keys ≠ App keys** - Management keys are for Console operations, app keys bypass security rules