contentstack-cli.mdc

---
description: 'Contentstack CLI specific patterns and API integration'
globs: ['**/import/**/*.ts', '**/export/**/*.ts', '**/modules/**/*.ts', '**/services/**/*.ts', '**/utils/**/*.ts']
alwaysApply: false
---

# Contentstack CLI Standards

## API Integration

- Use `@contentstack/cli-utilities` for SDK factory: `managementSDKClient(config)`
- Stack-scoped API access: `stackAPIClient.asset()`, `stackAPIClient.extension()`
- Fluent SDK chaining: `stack.contentType().entry().query().find()`
- Custom HTTP for variants: `apiClient.put/get` with path strings

## Authentication

- Use `@contentstack/cli-utilities` for token management
- Management token alias: `configHandler.get('tokens.<alias>')`
- OAuth context: `configHandler.get('userUid'|'email'|'oauthOrgUid')`
- Authentication check: `isAuthenticated()` before operations
- Never log API keys or tokens in console or files

## Rate Limiting - Multiple Mechanisms

### Batch Spacing (Import/Export)
```typescript
// ✅ GOOD - Ensure minimum 1 second between batches
async logMsgAndWaitIfRequired(processName: string, start: number): Promise<void> {
  const end = Date.now();
  const exeTime = end - start;
  if (exeTime < 1000) await this.delay(1000 - exeTime);
}
```

### 429 Retry (Branches)
```typescript
// ✅ GOOD - Handle 429 with retry
export async function handleErrorMsg(err, retryCallback?: () => Promise<any>) {
  if (err?.status === 429 || err?.response?.status === 429) {
    await new Promise((resolve) => setTimeout(resolve, 1000)); // 1 sec delay
    if (retryCallback) {
      return retryCallback(); // Retry the request
    }
  }
}
```

### Variant Pagination Throttle
```typescript
// ✅ GOOD - Throttle variant API requests
if (requestTime < 1000) {
  await delay(1000 - requestTime);
}
```

## Error Handling

### Standard Pattern
```typescript
// ✅ GOOD - Use handleAndLogError from utilities
try {
  const result = await this.stack.contentType().entry().fetch();
} catch (error) {
  handleAndLogError(error);
  this.logAndPrintErrorDetails(error, config);
}
```

### User-Friendly Errors
```typescript
// ✅ GOOD - User-facing error display
cliux.print(errorMessage, { color: 'red' });
// For critical failures
process.exit(1);
```

## Module Architecture (Import/Export)

### BaseClass Pattern
```typescript
// ✅ GOOD - Extend BaseClass for entity modules
export class ContentTypes extends BaseClass {
  constructor(params: ModuleClassParams) {
    super(params);
    // Entity-specific initialization
  }

  async import(): Promise<void> {
    // Use this.makeConcurrentCall for batching
    // Use this.logMsgAndWaitIfRequired for rate limiting
  }
}
```

### Batch Processing
```typescript
// ✅ GOOD - Concurrent batch processing
const batches = chunk(apiContent, batchSize);
for (const batch of batches) {
  const start = Date.now();
  await this.makeConcurrentCall(batch, this.processItem.bind(this));
  await this.logMsgAndWaitIfRequired('Processing', start, batches.length, batchIndex);
}
```

## Configuration Patterns

### Import/Export Config
```typescript
// ✅ GOOD - Use configHandler for management tokens
const config = {
  host: configHandler.get('region.cma'),
  managementTokenAlias: flags.alias,
  stackApiKey: flags['stack-api-key'],
  rateLimit: 5, // Default rate limit
};
```

### Regional Configuration
```typescript
// ✅ GOOD - Handle regional endpoints
const defaultConfig = {
  host: 'https://api.contentstack.io',
  cdn: 'https://cdn.contentstack.io',
  // Regional developer hub URLs
};
```

## Testing Patterns

### SDK Mocking
```typescript
// ✅ GOOD - Mock stack client methods
const mockStackClient = {
  fetch: sinon.stub().resolves({ name: 'Test Stack', uid: 'stack-uid' }),
  locale: sinon.stub().returns({
    query: sinon.stub().returns({
      find: sinon.stub().resolves({ items: [], count: 0 }),
    }),
  }),
};
```

### Error Simulation
```typescript
// ✅ GOOD - Test error handling
it('should handle 429 rate limit', async () => {
  const error = { status: 429 };
  mockClient.fetch.rejects(error);
  // Test retry logic
});
```

## Package-Specific Patterns

### Plugin vs Library
- **Plugin packages**: Have `oclif.commands` in package.json
- **Library packages** (e.g., variants): No OCLIF commands, consumed by other packages

### Monorepo Structure
- Commands: `packages/*/src/commands/cm/**/*.ts`
- Modules: `packages/*/src/{import,export,modules}/**/*.ts`
- Utilities: `packages/*/src/utils/**/*.ts`
- Built artifacts: `packages/*/lib/**` (not source)