aigroup-workflow 2.1.2 → 2.2.0

package/skills/backend/code-documenter/references/typescript-jsdoc.md

@@ -0,0 +1,145 @@
+# TypeScript JSDoc
+
+## Function Documentation
+
+```typescript
+/**
+ * Calculate total cost including tax.
+ *
+ * @param items - List of items to calculate total for
+ * @param taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
+ * @returns Total cost including tax
+ * @throws {Error} If taxRate is negative or items is empty
+ *
+ * @example
+ * ```typescript
+ * const total = calculateTotal(items, 0.08);
+ * console.log(total); // 108.00
+ * ```
+ */
+function calculateTotal(items: Item[], taxRate = 0): number {
+```
+
+## Class Documentation
+
+```typescript
+/**
+ * Service for managing user operations.
+ *
+ * Handles CRUD operations and integrates with authentication system.
+ *
+ * @example
+ * ```typescript
+ * const service = new UserService(db, cache);
+ * const user = await service.create(userData);
+ * ```
+ */
+class UserService {
+  /**
+   * Create a new UserService instance.
+   *
+   * @param db - Database connection
+   * @param cache - Redis cache client
+   */
+  constructor(
+    private readonly db: Database,
+    private readonly cache: Cache,
+  ) {}
+}
+```
+
+## Interface Documentation
+
+```typescript
+/**
+ * User data transfer object.
+ *
+ * @interface UserDto
+ */
+interface UserDto {
+  /** Unique user identifier */
+  id: string;
+
+  /** User's email address (unique) */
+  email: string;
+
+  /** User's display name */
+  name: string;
+
+  /** Account creation timestamp */
+  createdAt: Date;
+}
+```
+
+## Generic Types
+
+```typescript
+/**
+ * Paginated response wrapper.
+ *
+ * @template T - Type of items in the data array
+ */
+interface PaginatedResponse<T> {
+  /** Array of items for current page */
+  data: T[];
+
+  /** Total number of items across all pages */
+  total: number;
+
+  /** Current page number (1-indexed) */
+  page: number;
+
+  /** Number of items per page */
+  limit: number;
+}
+```
+
+## Async Functions
+
+```typescript
+/**
+ * Fetch user by ID from database.
+ *
+ * @param id - User's unique identifier
+ * @returns Promise resolving to user data or null if not found
+ * @throws {DatabaseError} If connection fails
+ *
+ * @async
+ */
+async function findUserById(id: string): Promise<User | null> {
+```
+
+## Quick Reference
+
+| Tag | Purpose | Example |
+|-----|---------|---------|
+| `@param` | Parameter description | `@param name - User's name` |
+| `@returns` | Return value | `@returns User object` |
+| `@throws` | Exception thrown | `@throws {Error} If invalid` |
+| `@example` | Usage example | Code block |
+| `@see` | Reference link | `@see UserService` |
+| `@deprecated` | Mark deprecated | `@deprecated Use v2 instead` |
+| `@template` | Generic type param | `@template T - Item type` |
+| `@async` | Async function | Mark async |
+| `@private` | Private member | Internal use |
+| `@readonly` | Read-only property | Cannot modify |
+
+## Common Patterns
+
+```typescript
+// Optional parameters
+/** @param [options] - Optional configuration */
+
+// Default values
+/** @param [limit=10] - Items per page (default: 10) */
+
+// Multiple types
+/** @param input - Input value (string or number) */
+
+// Callback parameters
+/**
+ * @callback FilterFn
+ * @param item - Item to filter
+ * @returns Whether item passes filter
+ */
+```

package/skills/backend/code-documenter/references/user-guides-tutorials.md

@@ -0,0 +1,530 @@
+# User Guides & Tutorials
+
+## Tutorial Structure
+
+### Progressive Learning Path
+
+```markdown
+# Getting Started with API
+
+## Prerequisites
+Before you begin, ensure you have:
+- [ ] Node.js 18+ installed
+- [ ] An API key from your dashboard
+- [ ] Basic knowledge of REST APIs
+
+## Quick Start (5 minutes)
+
+### 1. Install the SDK
+```bash
+npm install @myapi/sdk
+```
+
+### 2. Create Your First Request
+```typescript
+import { Client } from '@myapi/sdk';
+
+const client = new Client({ apiKey: 'your_key' });
+const users = await client.users.list();
+console.log(users);
+```
+
+### 3. Verify It Works
+Run the code and you should see a list of users.
+
+**Expected output:**
+```json
+{
+  "data": [
+    { "id": "1", "name": "Alice" },
+    { "id": "2", "name": "Bob" }
+  ],
+  "total": 2
+}
+```
+
+## Next Steps
+- [Authentication Guide](/docs/auth) - Learn about OAuth and API keys
+- [Advanced Queries](/docs/queries) - Filtering, sorting, pagination
+- [Error Handling](/docs/errors) - Handle errors gracefully
+```
+
+### Step-by-Step Tutorial
+
+```markdown
+# Tutorial: Building a User Dashboard
+
+**What you'll learn:**
+- Fetching user data from the API
+- Handling pagination
+- Displaying data in a table
+- Adding real-time updates
+
+**Time:** 30 minutes
+**Level:** Intermediate
+
+## Step 1: Set Up the Project
+
+Create a new project:
+```bash
+mkdir user-dashboard
+cd user-dashboard
+npm init -y
+npm install @myapi/sdk react
+```
+
+## Step 2: Fetch Users
+
+Create `src/api/users.ts`:
+```typescript
+import { Client } from '@myapi/sdk';
+
+const client = new Client({ apiKey: process.env.API_KEY });
+
+export async function getUsers(page = 1, limit = 20) {
+  const response = await client.users.list({ page, limit });
+  return response;
+}
+```
+
+**What's happening:**
+1. We import the SDK client
+2. Initialize it with our API key from environment
+3. Create a helper function that fetches paginated users
+
+## Step 3: Create the Component
+
+Create `src/components/UserTable.tsx`:
+```typescript
+import { useState, useEffect } from 'react';
+import { getUsers } from '../api/users';
+
+export function UserTable() {
+  const [users, setUsers] = useState([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    async function fetchData() {
+      const data = await getUsers();
+      setUsers(data.data);
+      setLoading(false);
+    }
+    fetchData();
+  }, []);
+
+  if (loading) return <div>Loading...</div>;
+
+  return (
+    <table>
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Email</th>
+        </tr>
+      </thead>
+      <tbody>
+        {users.map(user => (
+          <tr key={user.id}>
+            <td>{user.name}</td>
+            <td>{user.email}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+```
+
+## Step 4: Test It
+
+Run your app:
+```bash
+npm run dev
+```
+
+You should see a table with user data.
+
+## Checkpoint
+At this point, you have:
+- [x] Set up the SDK
+- [x] Created an API helper
+- [x] Built a user table component
+- [ ] Added pagination
+- [ ] Added real-time updates
+
+## Next: Adding Pagination
+
+[Continue to Step 5 →](/docs/tutorial/step-5)
+```
+
+## Information Architecture
+
+### Content Hierarchy
+
+```markdown
+Documentation/
+├── Getting Started/
+│   ├── Quick Start (5 min)
+│   ├── Installation
+│   ├── Authentication
+│   └── First Request
+│
+├── Guides/
+│   ├── User Management
+│   ├── File Uploads
+│   ├── Webhooks
+│   └── Rate Limiting
+│
+├── API Reference/
+│   ├── Users API
+│   ├── Files API
+│   └── Webhooks API
+│
+├── SDK Documentation/
+│   ├── Python SDK
+│   ├── TypeScript SDK
+│   └── Go SDK
+│
+├── Tutorials/
+│   ├── Build a Dashboard (30 min)
+│   ├── Integrate Authentication (45 min)
+│   └── Real-time Sync (60 min)
+│
+└── Resources/
+    ├── Troubleshooting
+    ├── FAQ
+    ├── Best Practices
+    └── Migration Guides
+```
+
+## Writing Techniques
+
+### Task-Based Writing
+
+```markdown
+# How to Upload a File
+
+**Goal:** Upload an image file to your account storage
+
+**Time:** 5 minutes
+
+## Steps
+
+### 1. Prepare the file
+Get the file from user input or file system:
+```typescript
+const file = document.querySelector('input[type="file"]').files[0];
+```
+
+### 2. Create form data
+```typescript
+const formData = new FormData();
+formData.append('file', file);
+formData.append('folder', 'avatars');
+```
+
+### 3. Upload with the SDK
+```typescript
+const result = await client.files.upload(formData);
+console.log('File URL:', result.url);
+```
+
+## Common Issues
+
+**"File too large" error:**
+Maximum file size is 10MB. Compress images before uploading.
+
+**"Invalid file type" error:**
+Only .jpg, .png, .gif are allowed. Check the file extension.
+
+## Related
+- [File API Reference](/api/files)
+- [Handling Upload Progress](/guides/upload-progress)
+```
+
+### Progressive Disclosure
+
+```markdown
+# Authentication
+
+## Basic: API Keys (Recommended for Getting Started)
+
+API keys are the simplest way to authenticate.
+
+```typescript
+const client = new Client({ apiKey: 'your_key' });
+```
+
+**When to use:** Scripts, internal tools, testing
+
+[Generate an API key →](/dashboard/api-keys)
+
+<details>
+<summary>Advanced: OAuth 2.0</summary>
+
+For user-facing applications, use OAuth 2.0.
+
+### Authorization Code Flow
+
+1. Redirect user to authorization URL:
+```typescript
+const authUrl = client.oauth.getAuthUrl({
+  redirectUri: 'https://yourapp.com/callback',
+  scopes: ['read:users', 'write:users'],
+});
+window.location.href = authUrl;
+```
+
+2. Handle the callback:
+```typescript
+const code = new URLSearchParams(window.location.search).get('code');
+const tokens = await client.oauth.exchangeCode(code);
+```
+
+3. Use the access token:
+```typescript
+const client = new Client({ accessToken: tokens.access_token });
+```
+
+[Full OAuth guide →](/guides/oauth)
+</details>
+
+<details>
+<summary>Enterprise: JWT Tokens</summary>
+
+For service-to-service authentication, use JWTs.
+
+```typescript
+const jwt = createJWT({
+  issuer: 'your-service',
+  subject: 'service-account-id',
+  privateKey: process.env.PRIVATE_KEY,
+});
+
+const client = new Client({ jwt });
+```
+
+[JWT setup guide →](/guides/jwt)
+</details>
+```
+
+## Visual Communication
+
+### Diagram Integration
+
+```markdown
+# System Architecture
+
+## Request Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant API
+    participant Database
+    participant Cache
+
+    Client->>API: POST /users
+    API->>Cache: Check cache
+    Cache-->>API: Cache miss
+    API->>Database: Insert user
+    Database-->>API: User created
+    API->>Cache: Store user
+    API-->>Client: 201 Created
+```
+
+## Data Model
+
+```mermaid
+erDiagram
+    USER ||--o{ POST : creates
+    USER ||--o{ COMMENT : writes
+    POST ||--o{ COMMENT : has
+
+    USER {
+        string id PK
+        string email UK
+        string name
+        datetime created_at
+    }
+
+    POST {
+        string id PK
+        string user_id FK
+        string title
+        text content
+    }
+```
+```
+
+### Screenshot Annotations
+
+```markdown
+# Dashboard Overview
+
+![Dashboard with numbered annotations](./images/dashboard-annotated.png)
+
+**Key features:**
+
+1. **Navigation** - Switch between sections
+2. **API Key** - Copy your key (click to reveal)
+3. **Usage Stats** - Current month's API calls
+4. **Quick Actions** - Generate new key, view docs
+5. **Recent Activity** - Last 10 API requests
+
+## Creating Your First API Key
+
+1. Click "Generate New Key" (highlighted in green)
+2. Enter a description like "Production API"
+3. Select permissions (default: all)
+4. Click "Create"
+5. **Important:** Copy the key immediately - it won't be shown again
+
+![Create API key dialog](./images/create-key.png)
+```
+
+## Troubleshooting Guides
+
+### Problem-Solution Format
+
+```markdown
+# Troubleshooting
+
+## Authentication Errors
+
+### "Invalid API key"
+
+**Symptoms:**
+- 401 Unauthorized error
+- Error message: "Invalid API key"
+
+**Causes:**
+1. API key was copied incorrectly (extra spaces)
+2. API key was revoked
+3. Using test key in production environment
+
+**Solutions:**
+
+**1. Verify the key:**
+```bash
+# Check for extra spaces
+echo -n "$API_KEY" | wc -c  # Should be exactly 32 characters
+```
+
+**2. Regenerate the key:**
+- Go to [dashboard](/dashboard)
+- Click "Revoke & Regenerate"
+- Update your environment variables
+
+**3. Check environment:**
+```typescript
+console.log('Environment:', process.env.NODE_ENV);
+console.log('API URL:', client.baseUrl);
+```
+
+**Still not working?**
+[Contact support](/support) with your request ID from the error response.
+
+---
+
+### "Rate limit exceeded"
+
+**Symptoms:**
+- 429 Too Many Requests error
+- Requests failing intermittently
+
+**Immediate fix:**
+Wait 60 seconds and retry.
+
+**Long-term solutions:**
+
+**1. Implement exponential backoff:**
+```typescript
+async function retryWithBackoff(fn, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (error.status === 429 && i < maxRetries - 1) {
+        await sleep(Math.pow(2, i) * 1000);
+        continue;
+      }
+      throw error;
+    }
+  }
+}
+```
+
+**2. Batch requests:**
+Instead of 100 individual requests, use batch endpoints.
+
+**3. Upgrade your plan:**
+[View plans](/pricing) - Higher tiers have increased limits.
+```
+
+## FAQ Section
+
+```markdown
+# Frequently Asked Questions
+
+## General
+
+### What's included in the free tier?
+- 1,000 API requests/month
+- 1GB storage
+- Community support
+- All core features
+
+### How do I upgrade?
+Click "Upgrade" in your [dashboard](/dashboard) and select a plan.
+
+## Technical
+
+### Can I use this in production?
+Yes, the API is production-ready with 99.9% SLA on paid plans.
+
+### What's the rate limit?
+- Free: 10 requests/minute
+- Pro: 100 requests/minute
+- Enterprise: Custom limits
+
+### Do you support webhooks?
+Yes! See [Webhooks Guide](/guides/webhooks) for setup.
+
+### Which regions are available?
+Currently: US East, US West, EU Central, Asia Pacific.
+
+## Billing
+
+### How does billing work?
+- Monthly subscription
+- Pay-as-you-go for overages
+- Cancel anytime
+
+### What payment methods do you accept?
+Credit card, PayPal, wire transfer (annual plans only).
+
+---
+
+**Can't find your answer?**
+- [Browse all docs](/docs)
+- [Ask the community](https://community.example.com)
+- [Contact support](/support)
+```
+
+## Quick Reference
+
+| Content Type | Best For | Key Elements |
+|-------------|----------|-------------|
+| Quick Start | New users (5 min) | Prerequisites, minimal code, verify |
+| Tutorial | Learning by doing | Steps, checkpoints, working code |
+| How-To Guide | Specific tasks | Goal, steps, troubleshooting |
+| Reference | Looking up details | Comprehensive, searchable |
+| Explanation | Understanding concepts | Why, not how |
+
+| Writing Principle | Technique |
+|------------------|-----------|
+| Clarity | Active voice, short sentences |
+| Scannability | Headings, lists, code blocks |
+| Completeness | Prerequisites, next steps, related links |
+| Accuracy | Test all code, version specifics |