claudeinone-cli 1.0.1 → 1.0.3

package/kit/.claude/skills/api-webhooks.md

@@ -0,0 +1,226 @@
+# Webhooks & Events
+
+Push-based communication for real-time integrations.
+
+## Webhook Implementation
+
+```typescript
+// Endpoint to receive webhooks
+app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), async (req, res) => {
+  const sig = req.headers['stripe-signature'];
+  
+  let event;
+  try {
+    event = stripe.webhooks.constructEvent(
+      req.body,
+      sig,
+      process.env.STRIPE_WEBHOOK_SECRET
+    );
+  } catch (err) {
+    return res.status(400).send(`Webhook Error: ${err.message}`);
+  }
+
+  // Handle event
+  switch (event.type) {
+    case 'payment_intent.succeeded':
+      await handlePaymentSuccess(event.data.object);
+      break;
+    case 'payment_intent.failed':
+      await handlePaymentFailure(event.data.object);
+      break;
+    default:
+      console.log(`Unhandled event type ${event.type}`);
+  }
+
+  res.json({ received: true });
+});
+
+async function handlePaymentSuccess(paymentIntent: any) {
+  const order = await db.orders.findById(paymentIntent.metadata.orderId);
+  await db.orders.update(order.id, { status: 'paid' });
+  
+  // Send confirmation email
+  await emailService.sendOrderConfirmation(order);
+}
+```
+
+## Retry Logic
+
+```typescript
+interface WebhookDelivery {
+  id: string;
+  url: string;
+  payload: any;
+  status: 'pending' | 'delivered' | 'failed';
+  attempts: number;
+  nextRetry?: Date;
+}
+
+async function deliverWebhook(delivery: WebhookDelivery) {
+  try {
+    const response = await fetch(delivery.url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Webhook-ID': delivery.id,
+        'X-Webhook-Signature': signPayload(delivery.payload)
+      },
+      body: JSON.stringify(delivery.payload),
+      timeout: 30000
+    });
+
+    if (response.ok) {
+      await db.webhookDeliveries.update(delivery.id, {
+        status: 'delivered'
+      });
+    } else {
+      throw new Error(`HTTP ${response.status}`);
+    }
+  } catch (error) {
+    delivery.attempts += 1;
+
+    if (delivery.attempts < 5) {
+      // Exponential backoff: 60s, 5m, 30m, 2h
+      const delays = [60, 300, 1800, 7200];
+      const delaySeconds = delays[delivery.attempts - 1];
+
+      await db.webhookDeliveries.update(delivery.id, {
+        attempts: delivery.attempts,
+        nextRetry: new Date(Date.now() + delaySeconds * 1000)
+      });
+    } else {
+      await db.webhookDeliveries.update(delivery.id, {
+        status: 'failed'
+      });
+    }
+  }
+}
+
+// Retry worker
+setInterval(async () => {
+  const pending = await db.webhookDeliveries.find({
+    status: 'pending',
+    nextRetry: { $lte: new Date() }
+  });
+
+  for (const delivery of pending) {
+    await deliverWebhook(delivery);
+  }
+}, 60000); // Check every minute
+```
+
+## Webhook Security
+
+```typescript
+import crypto from 'crypto';
+
+function signPayload(payload: any): string {
+  const timestamp = Math.floor(Date.now() / 1000);
+  const message = `${timestamp}.${JSON.stringify(payload)}`;
+
+  const signature = crypto
+    .createHmac('sha256', process.env.WEBHOOK_SECRET!)
+    .update(message)
+    .digest('hex');
+
+  return `t=${timestamp},v1=${signature}`;
+}
+
+function verifySignature(payload: string, signature: string): boolean {
+  const [timestamp, ...parts] = signature.split(',');
+  const ts = parseInt(timestamp.split('=')[1]);
+  const sig = parts[0].split('=')[1];
+
+  // Prevent replay attacks
+  if (Math.abs(Date.now() / 1000 - ts) > 300) {
+    return false;
+  }
+
+  const message = `${ts}.${payload}`;
+  const expectedSig = crypto
+    .createHmac('sha256', process.env.WEBHOOK_SECRET!)
+    .update(message)
+    .digest('hex');
+
+  return crypto.timingSafeEqual(sig, expectedSig);
+}
+```
+
+## Publishing Events
+
+```typescript
+async function publishWebhookEvent(event: {
+  type: string;
+  data: any;
+}) {
+  // Find all webhook endpoints subscribed to this event type
+  const subscriptions = await db.webhookSubscriptions.find({
+    events: event.type
+  });
+
+  for (const subscription of subscriptions) {
+    // Create delivery record
+    await db.webhookDeliveries.insert({
+      id: crypto.randomUUID(),
+      url: subscription.url,
+      payload: event.data,
+      status: 'pending',
+      attempts: 0
+    });
+
+    // Attempt immediate delivery
+    const delivery = await db.webhookDeliveries.findById(id);
+    await deliverWebhook(delivery);
+  }
+}
+
+// Usage
+app.post('/api/orders', async (req, res) => {
+  const order = await db.orders.create(req.body);
+
+  // Publish event
+  await publishWebhookEvent({
+    type: 'order.created',
+    data: { orderId: order.id, amount: order.total }
+  });
+
+  res.status(201).json(order);
+});
+```
+
+## Client-Side Webhook Handling
+
+```typescript
+async function handleStripeWebhook(event: any) {
+  console.log('Received webhook:', event.type);
+
+  // Verify signature
+  const signature = request.headers['stripe-signature'];
+  if (!verifyStripeSignature(request.body, signature)) {
+    return res.status(401).send('Unauthorized');
+  }
+
+  // Process asynchronously
+  await queue.enqueue({
+    type: 'webhook',
+    eventType: event.type,
+    data: event.data
+  });
+
+  // Return 200 immediately
+  res.json({ received: true });
+}
+```
+
+## Best Practices
+
+✅ **Verify signatures** - Ensure webhook authenticity
+✅ **Retry logic** - Use exponential backoff
+✅ **Idempotency** - Handle duplicate deliveries
+✅ **Async processing** - Don't block on webhook delivery
+✅ **Logging** - Track all webhook events
+
+## Resources
+
+- [Webhook Best Practices](https://docs.svix.com/webhooks/best-practices)
+- [Stripe Webhooks](https://stripe.com/docs/webhooks)

package/kit/.claude/skills/arch-clean-code.md

@@ -0,0 +1,226 @@
+# Clean Code Architecture
+
+Principles for writing maintainable, testable code.
+
+## SOLID Principles
+
+```typescript
+// Single Responsibility Principle
+// Bad: UserService does too much
+class UserService {
+  async createUser(userData) { /*...*/ }
+  async sendEmail(to, subject, body) { /*...*/ }
+  async logActivity(userId, action) { /*...*/ }
+}
+
+// Good: Separate concerns
+class UserService {
+  async createUser(userData) { /*...*/ }
+}
+
+class EmailService {
+  async sendEmail(to, subject, body) { /*...*/ }
+}
+
+class LogService {
+  async logActivity(userId, action) { /*...*/ }
+}
+
+// Open/Closed Principle
+// Bad: Hard to extend without modification
+class PaymentProcessor {
+  process(payment, method) {
+    if (method === 'stripe') {
+      // Stripe logic
+    } else if (method === 'paypal') {
+      // PayPal logic
+    }
+  }
+}
+
+// Good: Extensible via inheritance
+abstract class PaymentProvider {
+  abstract process(payment: Payment): Promise<void>;
+}
+
+class StripeProvider extends PaymentProvider {
+  async process(payment: Payment) { /*...*/ }
+}
+
+class PayPalProvider extends PaymentProvider {
+  async process(payment: Payment) { /*...*/ }
+}
+
+class PaymentProcessor {
+  constructor(private provider: PaymentProvider) {}
+  
+  async process(payment: Payment) {
+    await this.provider.process(payment);
+  }
+}
+```
+
+## Dependency Injection
+
+```typescript
+// Bad: Tightly coupled
+class UserRepository {
+  private db = new Database();
+  
+  async findById(id: string) {
+    return this.db.query('...');
+  }
+}
+
+// Good: Injected dependencies
+class UserRepository {
+  constructor(private db: Database) {}
+  
+  async findById(id: string) {
+    return this.db.query('...');
+  }
+}
+
+// Container pattern
+class Container {
+  private services = new Map();
+  
+  register(name: string, factory: () => any) {
+    this.services.set(name, factory);
+  }
+  
+  get(name: string) {
+    const factory = this.services.get(name);
+    return factory();
+  }
+}
+
+const container = new Container();
+container.register('db', () => new Database());
+container.register('userRepository', () => 
+  new UserRepository(container.get('db'))
+);
+```
+
+## Design Patterns
+
+```typescript
+// Factory Pattern
+interface UserFactory {
+  createAdmin(data: any): User;
+  createMember(data: any): User;
+}
+
+class StandardUserFactory implements UserFactory {
+  createAdmin(data) {
+    return new User({ ...data, role: 'admin' });
+  }
+  
+  createMember(data) {
+    return new User({ ...data, role: 'member' });
+  }
+}
+
+// Strategy Pattern
+interface PaymentStrategy {
+  pay(amount: number): Promise<void>;
+}
+
+class CreditCardPayment implements PaymentStrategy {
+  async pay(amount: number) { /*...*/ }
+}
+
+class PayPalPayment implements PaymentStrategy {
+  async pay(amount: number) { /*...*/ }
+}
+
+class OrderProcessor {
+  constructor(private paymentStrategy: PaymentStrategy) {}
+  
+  async checkout(amount: number) {
+    await this.paymentStrategy.pay(amount);
+  }
+}
+
+// Observer Pattern
+class EventBus {
+  private listeners = new Map<string, Function[]>();
+  
+  on(event: string, callback: Function) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, []);
+    }
+    this.listeners.get(event)!.push(callback);
+  }
+  
+  emit(event: string, data: any) {
+    this.listeners.get(event)?.forEach(cb => cb(data));
+  }
+}
+```
+
+## Error Handling
+
+```typescript
+// Custom error classes
+class ApplicationError extends Error {
+  constructor(
+    public statusCode: number,
+    message: string,
+    public code: string
+  ) {
+    super(message);
+  }
+}
+
+class ValidationError extends ApplicationError {
+  constructor(message: string) {
+    super(400, message, 'VALIDATION_ERROR');
+  }
+}
+
+class NotFoundError extends ApplicationError {
+  constructor(resource: string) {
+    super(404, `${resource} not found`, 'NOT_FOUND');
+  }
+}
+
+// Usage
+async function getUser(id: string) {
+  if (!id) {
+    throw new ValidationError('User ID is required');
+  }
+  
+  const user = await db.users.findById(id);
+  if (!user) {
+    throw new NotFoundError('User');
+  }
+  
+  return user;
+}
+
+// Error handler middleware
+app.use((err: Error, req, res, next) => {
+  if (err instanceof ApplicationError) {
+    return res.status(err.statusCode).json({
+      code: err.code,
+      message: err.message
+    });
+  }
+  
+  res.status(500).json({ code: 'INTERNAL_ERROR' });
+});
+```
+
+## Best Practices
+
+✅ **DRY** - Don't Repeat Yourself
+✅ **KISS** - Keep It Simple, Stupid
+✅ **YAGNI** - You Aren't Gonna Need It
+✅ **Meaningful names** - Self-documenting code
+✅ **Small functions** - Single responsibility
+
+## Resources
+
+- [Clean Code by Robert C. Martin](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882)
+- [Design Patterns](https://refactoring.guru/design-patterns)

package/kit/.claude/skills/arch-clean.md

@@ -0,0 +1,91 @@
+# Clean Architecture
+
+## Overview
+Organize code in layers: Domain (core logic) → Application (use cases) → Infrastructure (DB/HTTP) → Interface (controllers).
+
+## Project Structure
+
+```
+src/
+├── domain/          # No external deps — pure business logic
+│   └── user/
+│       ├── User.ts           # Entity
+│       └── UserRepository.ts # Interface (Port)
+├── application/     # Orchestrates domain
+│   └── user/
+│       └── CreateUserUseCase.ts
+├── infrastructure/  # Implements ports
+│   └── user/
+│       └── PrismaUserRepository.ts
+└── interfaces/      # HTTP, GraphQL — thin layer
+    └── UserController.ts
+```
+
+## Domain Entity
+
+```typescript
+export class User {
+  private constructor(
+    public readonly id: string,
+    public readonly email: string,
+    public readonly name: string,
+  ) {}
+
+  static create(props: { email: string; name: string }): User {
+    if (!props.email.includes('@')) throw new Error('Invalid email');
+    return new User(crypto.randomUUID(), props.email, props.name);
+  }
+}
+
+export interface UserRepository {
+  findById(id: string): Promise<User | null>;
+  findByEmail(email: string): Promise<User | null>;
+  save(user: User): Promise<void>;
+}
+```
+
+## Application Use Case
+
+```typescript
+export class CreateUserUseCase {
+  constructor(private readonly userRepo: UserRepository) {}
+
+  async execute(input: { email: string; name: string }) {
+    const existing = await this.userRepo.findByEmail(input.email);
+    if (existing) throw new Error('Email already in use');
+    const user = User.create(input);
+    await this.userRepo.save(user);
+    return { id: user.id, email: user.email, name: user.name };
+  }
+}
+```
+
+## Infrastructure Adapter
+
+```typescript
+export class PrismaUserRepository implements UserRepository {
+  constructor(private readonly prisma: PrismaClient) {}
+
+  async findById(id: string): Promise<User | null> {
+    const row = await this.prisma.user.findUnique({ where: { id } });
+    return row ? User.create({ email: row.email, name: row.name }) : null;
+  }
+
+  async save(user: User): Promise<void> {
+    await this.prisma.user.upsert({
+      where: { id: user.id },
+      create: { id: user.id, email: user.email, name: user.name },
+      update: { name: user.name },
+    });
+  }
+}
+```
+
+## Best Practices
+- Domain layer must have zero external dependencies
+- Use interfaces (ports) at every layer boundary
+- Inject all dependencies — never instantiate in use cases
+- Entities validate their own invariants
+
+## Resources
+- [Clean Architecture (Robert C. Martin)](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)