@majkapp/plugin-kit 3.7.3 → 3.7.5

package/docs/AUTH.md

@@ -0,0 +1,248 @@
+# Auth API
+
+Authentication API for accessing MAJK Core Cognito credentials and making authenticated requests to AWS/MAJK services.
+
+## Interface
+
+```typescript
+export interface AuthAPI {
+  getAccount(): Promise<SystemAccount | null>;
+  getAccountsOfType(type: AccountType | '*'): Promise<SystemAccount[]>;
+  getCredentials(options?: CredentialOptions): Promise<Credentials>;
+  isAuthenticated(): Promise<boolean>;
+}
+```
+
+## Usage
+
+Access the auth API through the function handler context:
+
+```typescript
+.function('myFunction', {
+  description: 'Example function using auth',
+  input: { type: 'object', properties: {}, additionalProperties: false },
+  output: { type: 'object', properties: { result: { type: 'string' } } },
+  handler: async (input, ctx) => {
+    // Check authentication status
+    const isAuth = await ctx.majk.auth.isAuthenticated();
+
+    if (!isAuth) {
+      throw new Error('Not authenticated');
+    }
+
+    // Get current account
+    const account = await ctx.majk.auth.getAccount();
+
+    // Get credentials for AWS service calls
+    const credentials = await ctx.majk.auth.getCredentials();
+
+    return { result: 'success' };
+  }
+})
+```
+
+## Methods
+
+### isAuthenticated()
+
+Check if the user is currently authenticated with MAJK Core.
+
+```typescript
+const isAuthenticated = await ctx.majk.auth.isAuthenticated();
+if (isAuthenticated) {
+  // User is authenticated with Cognito
+}
+```
+
+**Returns:** `Promise<boolean>` - true if authenticated
+
+### getAccount()
+
+Get the current system account (typically the Cognito account).
+
+```typescript
+const account = await ctx.majk.auth.getAccount();
+if (account) {
+  console.log('Account type:', account.type);
+  console.log('Account name:', account.name);
+  console.log('Expires at:', account.expiresAt);
+}
+```
+
+**Returns:** `Promise<SystemAccount | null>` - Current account or null if not authenticated
+
+### getAccountsOfType(type)
+
+Get all accounts of a specific type.
+
+```typescript
+// Get AWS Cognito accounts
+const cognitoAccounts = await ctx.majk.auth.getAccountsOfType('aws-cognito');
+
+// Get all accounts
+const allAccounts = await ctx.majk.auth.getAccountsOfType('*');
+```
+
+**Parameters:**
+- `type: AccountType | '*'` - Account type filter or '*' for all
+
+**Account Types:**
+- `'aws-cognito'` - AWS Cognito accounts
+- `'azure-entra'` - Azure Entra ID accounts
+- `'api-key'` - API key accounts
+- `'system-default'` - System default accounts
+
+**Returns:** `Promise<SystemAccount[]>` - Array of matching accounts
+
+### getCredentials(options?)
+
+Get credentials for making authenticated requests to AWS/MAJK services.
+
+```typescript
+// Get current credentials
+const creds = await ctx.majk.auth.getCredentials();
+
+// Force refresh credentials
+const freshCreds = await ctx.majk.auth.getCredentials({
+  forceRefresh: true
+});
+
+// Get credentials for specific purpose
+const serviceCreds = await ctx.majk.auth.getCredentials({
+  purpose: 'bedrock-api-call'
+});
+```
+
+**Parameters:**
+- `options?: CredentialOptions`
+  - `forceRefresh?: boolean` - Force credential refresh
+  - `purpose?: string` - Purpose description for logging
+  - `timeout?: number` - Request timeout in milliseconds
+
+**Returns:** `Promise<Credentials>` - Credential object with tokens
+
+## Credential Types
+
+### AWS Cognito Credentials
+
+```typescript
+interface AwsCognitoCredentials {
+  accountType: 'aws-cognito';
+  bearerToken: string;          // For Authorization header
+  aws: {
+    accessKeyId: string;        // For AWS SDK
+    secretAccessKey: string;
+    sessionToken: string;
+    region: string;
+  };
+  cognito: {
+    idToken: string;           // Cognito identity token
+    accessToken: string;       // Cognito access token
+    refreshToken: string;
+  };
+}
+```
+
+## Common Patterns
+
+### Making AWS Service Calls
+
+```typescript
+handler: async (input, ctx) => {
+  const credentials = await ctx.majk.auth.getCredentials();
+
+  if (credentials.accountType === 'aws-cognito') {
+    const awsCreds = credentials.aws;
+
+    // Use with AWS SDK
+    const client = new SomeAWSClient({
+      region: awsCreds.region,
+      credentials: {
+        accessKeyId: awsCreds.accessKeyId,
+        secretAccessKey: awsCreds.secretAccessKey,
+        sessionToken: awsCreds.sessionToken
+      }
+    });
+
+    return await client.someOperation();
+  }
+}
+```
+
+### Making HTTP Requests to MAJK Services
+
+```typescript
+handler: async (input, ctx) => {
+  const credentials = await ctx.majk.auth.getCredentials();
+
+  const response = await fetch('https://api.majkapp.com/some-endpoint', {
+    headers: {
+      'Authorization': `Bearer ${credentials.bearerToken}`,
+      'Content-Type': 'application/json'
+    },
+    method: 'POST',
+    body: JSON.stringify(data)
+  });
+
+  return await response.json();
+}
+```
+
+### Authentication Guard
+
+```typescript
+handler: async (input, ctx) => {
+  // Check auth before proceeding
+  if (!await ctx.majk.auth.isAuthenticated()) {
+    throw new Error('Authentication required');
+  }
+
+  const account = await ctx.majk.auth.getAccount();
+  if (!account || account.isExpired()) {
+    throw new Error('Account expired or invalid');
+  }
+
+  // Proceed with authenticated operation
+  return { success: true };
+}
+```
+
+### Error Handling
+
+```typescript
+handler: async (input, ctx) => {
+  try {
+    const credentials = await ctx.majk.auth.getCredentials();
+    // Use credentials...
+  } catch (error) {
+    ctx.logger.error('Authentication failed', {
+      error: error.message,
+      function: 'myFunction'
+    });
+
+    // Handle unauthenticated state
+    if (error.message.includes('not authenticated')) {
+      throw new Error('Please authenticate with MAJK Core');
+    }
+
+    throw error;
+  }
+}
+```
+
+## Best Practices
+
+1. **Always check authentication** before accessing protected resources
+2. **Cache credentials** within a single function call to avoid multiple requests
+3. **Handle token expiration** gracefully with appropriate error messages
+4. **Use forceRefresh** only when necessary to avoid rate limiting
+5. **Log authentication errors** with context for debugging
+6. **Validate credential types** before using type-specific properties
+
+## Error Scenarios
+
+- **Not authenticated**: `isAuthenticated()` returns false
+- **No account**: `getAccount()` returns null
+- **Expired credentials**: Account `isExpired()` returns true
+- **Network issues**: Credential refresh may fail
+- **Rate limiting**: Too many refresh requests

package/docs/BATCH.md

@@ -0,0 +1,256 @@
+# Batch API
+
+Batch processing for large sets of items with parallelism, retry logic, and progress tracking.
+
+## Quick Start
+
+```typescript
+handler: async (input, ctx) => {
+  // Create a batch job to process files
+  const { job } = await ctx.majk.batch.create_batch_job({
+    name: 'Review TypeScript files',
+    input: {
+      source: { type: 'glob', pattern: 'src/**/*.ts' }
+    },
+    processor: {
+      type: 'teammate',
+      teammateId: 'code-reviewer',
+      taskTemplate: 'Review {{item}} for best practices'
+    },
+    execution: { maxParallelism: 3 },
+    autoStart: true
+  });
+
+  // Wait for completion
+  const result = await ctx.majk.batch.await_batch_job({ jobId: job.id });
+  return { processed: result.finalProgress.completedItems };
+}
+```
+
+## API Reference
+
+### create_batch_job(input)
+
+Create a new batch processing job.
+
+```typescript
+const { job } = await ctx.majk.batch.create_batch_job({
+  name: string,
+  description?: string,
+  input: {
+    source: BatchInputSource,
+    transformTemplate?: string,  // Transform items before processing
+    skipIfTemplate?: string,     // Skip items matching condition
+    limit?: number
+  },
+  processor: BatchProcessorConfig,
+  execution?: BatchExecutionConfig,
+  tags?: string[],
+  metadata?: Record<string, any>,
+  autoStart?: boolean
+});
+```
+
+### Input Sources
+
+```typescript
+// List of items
+{ type: 'list', items: ['item1', 'item2', 'item3'] }
+
+// Directory scan
+{ type: 'directory', path: 'src/', recursive: true, extensions: ['.ts', '.js'] }
+
+// Glob pattern
+{ type: 'glob', pattern: 'src/**/*.ts', basePath: '.', ignore: ['node_modules'] }
+```
+
+### Processor Types
+
+```typescript
+// Delegate to teammate
+{ type: 'teammate', teammateId: 'code-reviewer', taskTemplate: 'Review {{item}}', witness: {...} }
+
+// Call RPC function
+{ type: 'rpc', pluginId: 'my-plugin', serviceName: 'analyzer', functionName: 'analyze', input: { file: '{{item}}' } }
+
+// Run witness check
+{ type: 'witness', witness: { bash: 'eslint {{item}}' } }
+
+// Execute script
+{ type: 'script', code: 'return processItem(item)', timeoutMs: 5000 }
+```
+
+### Execution Config
+
+```typescript
+execution: {
+  maxParallelism: 5,      // Concurrent items
+  itemTimeoutMs: 60000,   // Per-item timeout
+  jobTimeoutMs: 3600000,  // Total job timeout
+  retry: {
+    maxAttempts: 3,
+    backoff: 'exponential',  // 'none' | 'fixed' | 'linear' | 'exponential'
+    initialDelayMs: 1000,
+    maxDelayMs: 30000,
+    jitter: true
+  }
+}
+```
+
+### start_batch_job(input)
+
+Start a pending batch job.
+
+```typescript
+const { job } = await ctx.majk.batch.start_batch_job({ jobId: string });
+```
+
+### pause_batch_job(input)
+
+Pause a running job.
+
+```typescript
+const { job } = await ctx.majk.batch.pause_batch_job({ jobId: string, reason?: string });
+```
+
+### resume_batch_job(input)
+
+Resume a paused job.
+
+```typescript
+const { job } = await ctx.majk.batch.resume_batch_job({ jobId: string });
+```
+
+### cancel_batch_job(input)
+
+Cancel a job.
+
+```typescript
+const { job } = await ctx.majk.batch.cancel_batch_job({ jobId: string });
+```
+
+### check_batch_job(input)
+
+Get current status and progress.
+
+```typescript
+const result = await ctx.majk.batch.check_batch_job({
+  jobId: string,
+  includeFailedItems?: boolean,
+  failedItemsLimit?: number
+});
+// Returns: { job, progress: { totalItems, completedItems, failedItems, ... }, failedItems? }
+```
+
+### await_batch_job(input)
+
+Wait for job completion.
+
+```typescript
+const result = await ctx.majk.batch.await_batch_job({
+  jobId: string,
+  timeoutMs?: number,
+  ignoreBlockers?: boolean
+});
+// Returns: { job, finalProgress, resultSummary?, hasBlockers?, blockedCount? }
+```
+
+### list_batch_jobs(input?)
+
+List jobs with filters.
+
+```typescript
+const { jobs, total, hasMore } = await ctx.majk.batch.list_batch_jobs({
+  status?: BatchJobStatus | BatchJobStatus[],
+  tags?: string[],
+  limit?: number,
+  offset?: number
+});
+```
+
+### get_batch_job_items(input)
+
+Get items from a job.
+
+```typescript
+const { items, total, hasMore } = await ctx.majk.batch.get_batch_job_items({
+  jobId: string,
+  status?: BatchItemStatus | BatchItemStatus[],
+  limit?: number,
+  offset?: number
+});
+```
+
+### replay_failed_batch_items(input)
+
+Create new job to retry failed items.
+
+```typescript
+const { job } = await ctx.majk.batch.replay_failed_batch_items({ jobId: string });
+```
+
+### clone_batch_job(input)
+
+Clone a job configuration.
+
+```typescript
+const { job } = await ctx.majk.batch.clone_batch_job({
+  jobId: string,
+  name?: string,
+  tags?: string[]
+});
+```
+
+## Common Patterns
+
+### Process Files with Progress
+
+```typescript
+const { job } = await ctx.majk.batch.create_batch_job({
+  name: 'Analyze codebase',
+  input: { source: { type: 'glob', pattern: '**/*.ts' } },
+  processor: { type: 'rpc', pluginId: 'analyzer', functionName: 'analyze' },
+  autoStart: true
+});
+
+// Poll for progress
+let status;
+do {
+  await new Promise(r => setTimeout(r, 5000));
+  status = await ctx.majk.batch.check_batch_job({ jobId: job.id });
+  ctx.logger.info(`Progress: ${status.progress.completedItems}/${status.progress.totalItems}`);
+} while (status.job.status === 'running');
+```
+
+### Handle Failures
+
+```typescript
+const result = await ctx.majk.batch.await_batch_job({ jobId: job.id });
+
+if (result.finalProgress.failedItems > 0) {
+  const { items } = await ctx.majk.batch.get_batch_job_items({
+    jobId: job.id,
+    status: 'failed'
+  });
+
+  for (const item of items) {
+    ctx.logger.error(`Failed: ${item.data}`, { error: item.error });
+  }
+
+  // Retry failed items
+  await ctx.majk.batch.replay_failed_batch_items({ jobId: job.id });
+}
+```
+
+## Best Practices
+
+1. **Set appropriate parallelism** - Balance throughput vs resource usage
+2. **Use retry with backoff** - Handle transient failures gracefully
+3. **Monitor progress** - Check status periodically for long jobs
+4. **Handle partial failures** - Use replay for failed items
+5. **Tag jobs** - Organize and filter jobs by purpose
+
+## Next Steps
+
+Run `npx @majkapp/plugin-kit --delegation` - Task delegation API
+Run `npx @majkapp/plugin-kit --scripting` - Script execution API

package/docs/CONFIG_API.md

@@ -0,0 +1,206 @@
+# Config API
+
+Access MAJK configuration using path-based dot notation.
+
+## Quick Start
+
+```typescript
+handler: async (input, ctx) => {
+  // Get config value
+  const region = ctx.majk.config.get('aws.region', 'us-east-1');
+
+  // Check if config exists
+  if (ctx.majk.config.has('bedrock.models.claude')) {
+    const model = ctx.majk.config.get('bedrock.models.claude');
+  }
+
+  // Discover available keys
+  const awsKeys = ctx.majk.config.keys('aws');
+
+  return { region, awsKeys };
+}
+```
+
+## API Reference
+
+### get<T>(path, defaultValue?)
+
+Get a configuration value by path.
+
+```typescript
+// Simple get
+const region = ctx.majk.config.get('aws.region');
+
+// With default value
+const timeout = ctx.majk.config.get('plugins.timeout', 30000);
+
+// Type-safe get
+interface BedrockConfig {
+  models: string[];
+  region: string;
+}
+const bedrock = ctx.majk.config.get<BedrockConfig>('bedrock');
+
+// Get entire section
+const awsConfig = ctx.majk.config.get('aws');
+```
+
+### has(path)
+
+Check if a configuration path exists.
+
+```typescript
+if (ctx.majk.config.has('aws.pluginMarket.apiEndpoint')) {
+  // Plugin market is configured
+}
+
+// Feature detection
+if (ctx.majk.config.has('experimental.newFeature')) {
+  // Enable experimental feature
+}
+```
+
+### keys(path?)
+
+Get all keys under a path.
+
+```typescript
+// Top-level namespaces
+const namespaces = ctx.majk.config.keys();
+// ['aws', 'auth', 'bedrock', 'litellm', 'plugins']
+
+// Keys under aws
+const awsKeys = ctx.majk.config.keys('aws');
+// ['pluginMarket', 'telemetry', 'region', ...]
+
+// Nested keys
+const marketKeys = ctx.majk.config.keys('aws.pluginMarket');
+// ['apiEndpoint', 'region', 'enabled']
+```
+
+### getAll()
+
+Get the entire configuration object.
+
+```typescript
+// For debugging only - prefer specific get() calls
+const allConfig = ctx.majk.config.getAll();
+console.log('Full config:', JSON.stringify(allConfig, null, 2));
+```
+
+## Configuration Namespaces
+
+### aws.*
+
+AWS resources and services.
+
+```typescript
+ctx.majk.config.get('aws.region');
+ctx.majk.config.get('aws.pluginMarket.apiEndpoint');
+ctx.majk.config.get('aws.telemetry.enabled');
+ctx.majk.config.get('aws.tokenUsage.tableName');
+```
+
+### auth.*
+
+Authentication configuration.
+
+```typescript
+ctx.majk.config.get('auth.cognito.userPoolId');
+ctx.majk.config.get('auth.cognito.clientId');
+ctx.majk.config.get('auth.cognito.region');
+```
+
+### bedrock.*
+
+Bedrock AI model settings.
+
+```typescript
+ctx.majk.config.get('bedrock.region');
+ctx.majk.config.get('bedrock.models');
+ctx.majk.config.get('bedrock.defaultModel');
+```
+
+### litellm.*
+
+LiteLLM proxy configuration.
+
+```typescript
+ctx.majk.config.get('litellm.apiBase');
+ctx.majk.config.get('litellm.apiKey');
+ctx.majk.config.get('litellm.models');
+```
+
+### plugins.*
+
+Plugin system configuration.
+
+```typescript
+ctx.majk.config.get('plugins.directory');
+ctx.majk.config.get('plugins.autoStart');
+ctx.majk.config.get('plugins.hotReload');
+```
+
+## Common Patterns
+
+### Safe Config Access
+
+```typescript
+function getAwsConfig() {
+  const region = ctx.majk.config.get('aws.region');
+  if (!region) {
+    throw new Error('AWS region not configured');
+  }
+
+  return {
+    region,
+    endpoint: ctx.majk.config.get('aws.pluginMarket.apiEndpoint'),
+    enabled: ctx.majk.config.get('aws.pluginMarket.enabled', false)
+  };
+}
+```
+
+### Feature Flags
+
+```typescript
+function isFeatureEnabled(feature: string): boolean {
+  return ctx.majk.config.get(`features.${feature}`, false);
+}
+
+if (isFeatureEnabled('newUI')) {
+  // Use new UI
+}
+```
+
+### Dynamic Configuration
+
+```typescript
+// Build config object from keys
+const awsKeys = ctx.majk.config.keys('aws');
+const awsConfig = {};
+
+for (const key of awsKeys) {
+  awsConfig[key] = ctx.majk.config.get(`aws.${key}`);
+}
+```
+
+### Environment-Specific Config
+
+```typescript
+const env = ctx.majk.config.get('environment', 'development');
+const apiUrl = ctx.majk.config.get(`api.${env}.url`);
+const timeout = ctx.majk.config.get(`api.${env}.timeout`, 5000);
+```
+
+## Best Practices
+
+1. **Use defaults** - Always provide sensible defaults
+2. **Check existence** - Use `has()` before optional configs
+3. **Type assertions** - Use generics for type safety
+4. **Avoid getAll()** - Use specific paths for better performance
+5. **Consistent paths** - Follow dot notation conventions
+
+## Next Steps
+
+Run `npx @majkapp/plugin-kit --secrets` - Secrets management
+Run `npx @majkapp/plugin-kit --auth` - Authentication API