Third-Party Integrations

Third-Party Integrations

Skill Purpose: External service integration patterns, API client management, and third-party service orchestration

---

Core Skill Pattern

Objective: Establish comprehensive third-party integration patterns with client management, error handling, and service orchestration.

Universal Pattern:

1. Define integration architecture and client patterns
2. Create service client management and configuration
3. Set up error handling and retry logic
4. Establish authentication and security patterns
5. Create integration testing and monitoring procedures

Key Decisions (Project-Specific):

• Integration architecture and client approach
• Error handling strategy and retry policies
• Authentication methods and security requirements
• Service orchestration and dependency management
• Monitoring and observability requirements

---

Project-Specific Implementation Notes

Customize per project:

• Integration depth based on service requirements
• Error handling based on service criticality and reliability
• Authentication based on security requirements and service capabilities
• Orchestration complexity based on service dependencies
• Monitoring depth based on business impact and SLA requirements

---

Example Implementation (Third-Party Integration Pattern)

Note: This is an example pattern for third-party integrations. Adapt integration methods and services based on your specific project requirements and service ecosystem.

Prerequisites (Example)

• External services identified and documented
• API credentials and authentication configured
• Integration requirements and error handling defined

---

Example: Third-Party Integrations Implementation

Framework-Specific Example: This demonstrates integration patterns using Stripe and Google services. Adapt for your specific services and integration requirements.

Primary Integrations (Example)

Note: Additional integrations are added as identified by Company Head in project specifications.

---

Integration Patterns

1. Service Client Pattern

// lib/​integrations/​stripe.ts
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2023-10-16',
});

export { stripe };

2. Error Handling

// lib/​integrations/​errors.ts
export class IntegrationError extends Error {
  constructor(
    public service: string,
    public code: string,
    message: string,
    public retryable: boolean = false
  ) {
    super(`[${service}] ${code}: ${message}`);
  }
}

// Usage
try {
  await stripe.customers.create({ email });
} catch (error) {
  if (error instanceof Stripe.errors.StripeError) {
    throw new IntegrationError(
      'stripe',
      error.code || 'unknown',
      error.message,
      error.type === 'StripeConnectionError'
    );
  }
  throw error;
}

3. Retry Logic

// lib/​integrations/​retry.ts
export async function withRetry<T>(
  fn: () => Promise<T>,
  options: { maxRetries?: number; delay?: number } = {}
): Promise<T> {
  const { maxRetries = 3, delay = 1000 } = options;
  
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries) throw error;
      if (error instanceof IntegrationError && !error.retryable) throw error;
      await new Promise(r => setTimeout(r, delay * attempt));
    }
  }
  throw new Error('Unreachable');
}

---

File Structure

/​lib/​integrations/
├── index.ts           # Re-exports
├── errors.ts          # Error types
├── retry.ts           # Retry utilities
├── stripe/
│   ├── client.ts      # Stripe client
│   ├── customers.ts   # Customer operations
│   └── payments.ts    # Payment operations
└── google/
    ├── client.ts      # Google client
    └── email.ts       # Email operations

---

Environment Variables

# Stripe
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=

# Google
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

---

Webhook Handling

// app/​api/​webhooks/​stripe/​route.ts
import { stripe } from '@/​lib/​integrations/​stripe';
import { headers } from 'next/​headers';

export async function POST(request: Request) {
  const body = await request.text();
  const signature = headers().get('stripe-signature')!;
  
  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (error) {
    return Response.json({ error: 'Invalid signature' }, { status: 400 });
  }
  
  // Handle event
  switch (event.type) {
    case 'payment_intent.succeeded':
      // Handle successful payment
      break;
  }
  
  return Response.json({ received: true });
}

---

Adding New Integrations

When Company Head identifies a new integration:

1. Create folder in /​lib/​integrations/​{service}/
2. Add client configuration
3. Add error handling specific to service
4. Add to environment variables
5. Document in INTERFACE_CONTRACT.md
6. Update this skill file

---

Stop Conditions

STOP and escalate if:

• API credentials not available
• Service documentation unclear
• Rate limits or quotas undefined
• Webhook requirements not specified

---

Skill Version: 1.0.0