Miro CI Integration

Overview

Set up CI/CD pipelines for Miro integrations with automated testing.

Prerequisites

• GitHub repository with Actions enabled
• Miro test API key
• npm/pnpm project configured

Instructions

Step 1: Create GitHub Actions Workflow

Create .github/workflows/miro-integration.yml:

name: Miro Integration Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  MIRO_API_KEY: ${{ secrets.MIRO_API_KEY }}

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      MIRO_API_KEY: ${{ secrets.MIRO_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test -- --coverage
      - run: npm run test:integration

Step 2: Configure Secrets

gh secret set MIRO_API_KEY --body "sk_test_***"

Step 3: Add Integration Tests

describe('Miro Integration', () => {
  it.skipIf(!process.env.MIRO_API_KEY)('should connect', async () => {
    const client = getMiroClient();
    const result = await client.healthCheck();
    expect(result.status).toBe('ok');
  });
});

Output

• Automated test pipeline
• PR checks configured
• Coverage reports uploaded
• Release workflow ready

Error Handling

Examples

Release Workflow

on:
  push:
    tags: ['v*']

jobs:
  release:
    runs-on: ubuntu-latest
    env:
      MIRO_API_KEY: ${{ secrets.MIRO_API_KEY_PROD }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - name: Verify Miro production readiness
        run: npm run test:integration
      - run: npm run build
      - run: npm publish

Branch Protection

required_status_checks:
  - "test"
  - "miro-integration"

Resources

• GitHub Actions Documentation
• Miro CI Guide

Next Steps

For deployment patterns, see miro-deploy-integration.

Miro Common Errors

Overview

Quick reference for the top 10 most common Miro errors and their solutions.

Prerequisites

• Miro SDK installed
• API credentials configured
• Access to error logs

Instructions

Step 1: Identify the Error

Check error message and code in your logs or console.

Step 2: Find Matching Error Below

Match your error to one of the documented cases.

Step 3: Apply Solution

Follow the solution steps for your specific error.

Output

• Identified error cause
• Applied fix
• Verified resolution

Error Handling

Authentication Failed

Error Message:

Authentication error: Invalid API key

Cause: API key is missing, expired, or invalid.

Solution:

# Verify API key is set
echo $MIRO_API_KEY

Rate Limit Exceeded

Error Message:

Rate limit exceeded. Please retry after X seconds.

Cause: Too many requests in a short period.

Solution:

Implement exponential backoff. See miro-rate-limits skill.

Network Timeout

Error Message:

Request timeout after 30000ms

Cause: Network connectivity or server latency issues.

Solution:

// Increase timeout
const client = new Client({ timeout: 60000 });

Examples

Quick Diagnostic Commands

# Check Miro status
curl -s https://status.miro.com

# Verify API connectivity
curl -I https://api.miro.com

# Check local configuration
env | grep MIRO

Escalation Path

1. Collect evidence with miro-debug-bundle
2. Check Miro status page
3. Contact support with request ID

Resources

• Miro Status Page
• Miro Support
• Miro Error Codes

Next Steps

For comprehensive debugging, see miro-debug-bundle.

Miro Core Workflow A

Overview

Primary money-path workflow for Miro. This is the most common use case.

Prerequisites

• Completed miro-install-auth setup
• Understanding of Miro core concepts
• Valid API credentials configured

Instructions

Step 1: Initialize

// Step 1 implementation

Step 2: Execute

// Step 2 implementation

Step 3: Finalize

// Step 3 implementation

Output

• Completed Core Workflow A execution
• Expected results from Miro API
• Success confirmation or error details

Error Handling

Examples

Complete Workflow

// Complete workflow example

Common Variations

• Variation 1: Description
• Variation 2: Description

Resources

• Miro Documentation
• Miro API Reference

Next Steps

For secondary workflow, see miro-core-workflow-b.

Miro Core Workflow B

Overview

Secondary workflow for Miro. Complements the primary workflow.

Prerequisites

• Completed miro-install-auth setup
• Familiarity with miro-core-workflow-a
• Valid API credentials configured

Instructions

Step 1: Setup

// Step 1 implementation

Step 2: Process

// Step 2 implementation

Step 3: Complete

// Step 3 implementation

Output

• Completed Core Workflow B execution
• Results from Miro API
• Success confirmation or error details

Error Handling

Examples

Complete Workflow

// Complete workflow example

Error Recovery

// Error handling code

Resources

• Miro Documentation
• Miro API Reference

Next Steps

For common errors, see miro-common-errors.

Miro Cost Tuning

Overview

Optimize Miro costs through smart tier selection, sampling, and usage monitoring.

Prerequisites

• Access to Miro billing dashboard
• Understanding of current usage patterns
• Database for usage tracking (optional)
• Alerting system configured (optional)

Pricing Tiers

Cost Estimation

interface UsageEstimate {
  requestsPerMonth: number;
  tier: string;
  estimatedCost: number;
  recommendation?: string;
}

function estimateMiroCost(requestsPerMonth: number): UsageEstimate {
  if (requestsPerMonth <= 1000) {
    return { requestsPerMonth, tier: 'Free', estimatedCost: 0 };
  }

  if (requestsPerMonth <= 100000) {
    return { requestsPerMonth, tier: 'Pro', estimatedCost: 99 };
  }

  const proOverage = (requestsPerMonth - 100000) * 0.001;
  const proCost = 99 + proOverage;

  return {
    requestsPerMonth,
    tier: 'Pro (with overage)',
    estimatedCost: proCost,
    recommendation: proCost > 500
      ? 'Consider Enterprise tier for volume discounts'
      : undefined,
  };
}

Usage Monitoring

class MiroUsageMonitor {
  private requestCount = 0;
  private bytesTransferred = 0;
  private alertThreshold: number;

  constructor(monthlyBudget: number) {
    this.alertThreshold = monthlyBudget * 0.8; // 80% warning
  }

  track(request: { bytes: number }) {
    this.requestCount++;
    this.bytesTransferred += request.bytes;

    if (this.estimatedCost() > this.alertThreshold) {
      this.sendAlert('Approaching Miro budget limit');
    }
  }

  estimatedCost(): number {
    return estimateMiroCost(this.requestCount).estimatedCost;
  }

  private sendAlert(message: string) {
    // Send to Slack, email, PagerDuty, etc.
  }
}

Cost Reduction Strategies

Step 1: Request Sampling

function shouldSample(samplingRate = 0.1): boolean {
  return Math.random() < samplingRate;
}

// Use for non-critical telemetry
if (shouldSample(0.1)) { // 10% sample
  await miroClient.trackEvent(event);
}

Step 2: Batching Requests

// Instead of N individual calls
await Promise.all(ids.map(id => miroClient.get(id)));

// Use batch endpoint (1 call)
await miroClient.batchGet(ids);

Step 3: Caching (from P16)

• Cache frequently accessed data
• Use cache invalidation webhooks
• Set

Miro Data Handling

Overview

Handle sensitive data correctly when integrating with Miro.

Prerequisites

• Understanding of GDPR/CCPA requirements
• Miro SDK with data export capabilities
• Database for audit logging
• Scheduled job infrastructure for cleanup

Data Classification

PII Detection

const PII_PATTERNS = [
  { type: 'email', regex: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g },
  { type: 'phone', regex: /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/g },
  { type: 'ssn', regex: /\b\d{3}-\d{2}-\d{4}\b/g },
  { type: 'credit_card', regex: /\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b/g },
];

function detectPII(text: string): { type: string; match: string }[] {
  const findings: { type: string; match: string }[] = [];

  for (const pattern of PII_PATTERNS) {
    const matches = text.matchAll(pattern.regex);
    for (const match of matches) {
      findings.push({ type: pattern.type, match: match[0] });
    }
  }

  return findings;
}

Data Redaction

function redactPII(data: Record<string, any>): Record<string, any> {
  const sensitiveFields = ['email', 'phone', 'ssn', 'password', 'apiKey'];
  const redacted = { ...data };

  for (const field of sensitiveFields) {
    if (redacted[field]) {
      redacted[field] = '[REDACTED]';
    }
  }

  return redacted;
}

// Use in logging
console.log('Miro request:', redactPII(requestData));

Data Retention Policy

Retention Periods

Automatic Cleanup

async function cleanupMiroData(retentionDays: number): Promise<void> {
  const cutoff = new Date();
  cutoff.setDate(cutoff.getDate() - retentionDays);

  await db.miroLogs.deleteMany({
    createdAt: { $lt: cutoff },
    type: { $nin: ['audit', 'compliance'] },
  });
}

// Schedule daily cleanup
cron.schedule('0 3 * * *', () => cleanupMiroData(30));

GDPR/CC

Miro Debug Bundle

Overview

Collect all necessary diagnostic information for Miro support tickets.

Prerequisites

• Miro SDK installed
• Access to application logs
• Permission to collect environment info

Instructions

Step 1: Create Debug Bundle Script

#!/bin/bash
# miro-debug-bundle.sh

BUNDLE_DIR="miro-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

echo "=== Miro Debug Bundle ===" > "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date)" >> "$BUNDLE_DIR/summary.txt"

Step 2: Collect Environment Info

# Environment info
echo "--- Environment ---" >> "$BUNDLE_DIR/summary.txt"
node --version >> "$BUNDLE_DIR/summary.txt" 2>&1
npm --version >> "$BUNDLE_DIR/summary.txt" 2>&1
echo "MIRO_API_KEY: ${MIRO_API_KEY:+[SET]}" >> "$BUNDLE_DIR/summary.txt"

Step 3: Gather SDK and Logs

# SDK version
npm list @miro/sdk 2>/dev/null >> "$BUNDLE_DIR/summary.txt"

# Recent logs (redacted)
grep -i "miro" ~/.npm/_logs/*.log 2>/dev/null | tail -50 >> "$BUNDLE_DIR/logs.txt"

# Configuration (redacted - secrets masked)
echo "--- Config (redacted) ---" >> "$BUNDLE_DIR/summary.txt"
cat .env 2>/dev/null | sed 's/=.*/=***REDACTED***/' >> "$BUNDLE_DIR/config-redacted.txt"

# Network connectivity test
echo "--- Network Test ---" >> "$BUNDLE_DIR/summary.txt"
echo -n "API Health: " >> "$BUNDLE_DIR/summary.txt"
curl -s -o /dev/null -w "%{http_code}" https://api.miro.com/health >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

Step 4: Package Bundle

tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
echo "Bundle created: $BUNDLE_DIR.tar.gz"

Output

• miro-debug-YYYYMMDD-HHMMSS.tar.gz archive containing:
• summary.txt - Environment and SDK info
• logs.txt - Recent redacted logs
• config-redacted.txt - Configuration (secrets removed)

Error Handling

# Add Miro secrets to Vercel
vercel secrets add miro_api_key sk_live_***
vercel secrets add miro_webhook_secret whsec_***

# Link to project
vercel link

# Deploy preview
vercel

# Deploy production
vercel --prod

{
  "env": {
    "MIRO_API_KEY": "@miro_api_key"
  },
  "functions": {
    "api/**/*.ts": {
      "maxDuration": 30
    }
  }
}

app = "my-miro-app"
primary_region = "iad"

[env]
  NODE_ENV = "production"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true

# Set Miro secrets
fly secrets set MIRO_API_KEY=sk_live_***
fly secrets set MIRO_WEBHOOK_SECRET=whsec_***

# Deploy
fly deploy

FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
CMD ["npm", "start"]

#!/bin/bash
# deploy-cloud-run.sh

PROJECT_ID="${GOOGLE_CLOUD_PROJECT}"
SERVICE_NAME="miro-service"
REGION="us-central1"

# Build and push image
gcloud builds submit --tag gcr.io/$PROJECT_ID/$SERVICE_NAME

# Deploy to Cloud Run
gcloud run deploy $SERVICE_NAME \
  --image gcr.io/$PROJECT_ID/$SERVICE_NAME \
  --region $REGION \
  --platform managed \
  --allow-unauthenticated \
  --set-secrets=MIRO_API_KEY=miro-api-key:latest

// config/miro.ts
interface MiroConfig {
  apiKey: string;
  environment: 'development' | 'staging' | 'production';
  webhookSecret?: string;
}

export function getMiroConfig(): MiroConfig {
  const env = process.env.NODE_ENV || 'development';

  return {
    apiKey: process.env.MIRO_API_KEY!,
    environment: env as MiroConfig['environment'],
    webhookSecret: process.env.MIRO_WEBHOOK_SECRET,
  };
}

// api/health.ts
export async function GET() {
  const miroStatus = await checkMiroConnection();

  return Response.json({
    status: miroStatus ? 'healthy' : 'degraded',
    servic

enum MiroRole {
  Admin = 'admin',
  Developer = 'developer',
  Viewer = 'viewer',
  Service = 'service',
}

interface MiroPermissions {
  read: boolean;
  write: boolean;
  delete: boolean;
  admin: boolean;
}

const ROLE_PERMISSIONS: Record<MiroRole, MiroPermissions> = {
  admin: { read: true, write: true, delete: true, admin: true },
  developer: { read: true, write: true, delete: false, admin: false },
  viewer: { read: true, write: false, delete: false, admin: false },
  service: { read: true, write: true, delete: false, admin: false },
};

function checkPermission(
  role: MiroRole,
  action: keyof MiroPermissions
): boolean {
  return ROLE_PERMISSIONS[role][action];
}

// Miro SAML setup
const samlConfig = {
  entryPoint: 'https://idp.company.com/saml/sso',
  issuer: 'https://miro.com/saml/metadata',
  cert: process.env.SAML_CERT,
  callbackUrl: 'https://app.yourcompany.com/auth/miro/callback',
};

// Map IdP groups to Miro roles
const groupRoleMapping: Record<string, MiroRole> = {
  'Engineering': MiroRole.Developer,
  'Platform-Admins': MiroRole.Admin,
  'Data-Team': MiroRole.Viewer,
};

import { OAuth2Client } from '@miro/sdk';

const oauthClient = new OAuth2Client({
  clientId: process.env.MIRO_OAUTH_CLIENT_ID!,
  clientSecret: process.env.MIRO_OAUTH_CLIENT_SECRET!,
  redirectUri: 'https://app.yourcompany.com/auth/miro/callback',
  scopes: ['read', 'write'],
});

interface MiroOrganization {
  id: string;
  name: string;
  ssoEnabled: boolean;
  enforceSso: boolean;
  allowedDomains: string[];
  defaultRole: MiroRole;
}

async function createOrganization(
  config: MiroOrganization
): Promise<void> {
  await miroClient.organizations.create({
    ...config,
    settings: {
      sso: {
        ena

import { MiroClient } from '@miro/sdk';

const client = new MiroClient({
  apiKey: process.env.MIRO_API_KEY,
});

async function main() {
  // Your first API call here
}

main().catch(console.error);

Success! Your Miro connection is working.

import { MiroClient } from '@miro/sdk';

const client = new MiroClient({
  apiKey: process.env.MIRO_API_KEY,
});

async function main() {
  // Your first API call here
}

main().catch(console.error);

from miro import MiroClient

client = MiroClient()

# Your first API call here

# 1. Check Miro status
curl -s https://status.miro.com | jq

# 2. Check our integration health
curl -s https://api.yourapp.com/health | jq '.services.miro'

# 3. Check error rate (last 5 min)
curl -s localhost:9090/api/v1/query?query=rate(miro_errors_total[5m])

# 4. Recent error logs
kubectl logs -l app=miro-integration --since=5m | grep -i error | tail -20

Miro API returning errors?
├─ YES: Is status.miro.com showing incident?
│   ├─ YES → Wait for Miro to resolve. Enable fallback.
│   └─ NO → Our integration issue. Check credentials, config.
└─ NO: Is our service healthy?
    ├─ YES → Likely resolved or intermittent. Monitor.
    └─ NO → Our infrastructure issue. Check pods, memory, network.

# Verify API key is set
kubectl get secret miro-secrets -o jsonpath='{.data.api-key}' | base64 -d

# Check if key was rotated
# → Verify in Miro dashboard

# Remediation: Update secret and restart pods
kubectl create secret generic miro-secrets --from-literal=api-key=NEW_KEY --dry-run=client -o yaml | kubectl apply -f -
kubectl rollout restart deployment/miro-integration

# Check rate limit headers
curl -v https://api.miro.com 2>&1 | grep -i rate

# Enable request queuing
kubectl set env deployment/miro-integration RATE_LIMIT_MODE=queue

# Long-term: Contact Miro for limit increase

# Enable graceful degradation
kubectl set env deployment/miro-integration MIRO_FALLBACK=true

# Notify users of degraded service
# Update status page

# Monitor Miro status for resolution

🔴 P1 INCIDENT: Miro Integration
Status: INVESTIGATING
Impact: [Describe user impact]
Current action: [What you're doing]
Next update: [Time]
I

# Node.js
npm install @miro/sdk

# Python
pip install miro

# Set environment variable
export MIRO_API_KEY="your-api-key"

# Or create .env file
echo 'MIRO_API_KEY=your-api-key' >> .env

// Test connection code here

import { MiroClient } from '@miro/sdk';

const client = new MiroClient({
  apiKey: process.env.MIRO_API_KEY,
});

from miro import MiroClient

client = MiroClient(
    api_key=os.environ.get('MIRO_API_KEY')
)

my-miro-project/
├── src/
│   ├── miro/
│   │   ├── client.ts       # Miro client wrapper
│   │   ├── config.ts       # Configuration management
│   │   └── utils.ts        # Helper functions
│   └── index.ts
├── tests/
│   └── miro.test.ts
├── .env.local              # Local secrets (git-ignored)
├── .env.example            # Template for team
└── package.json

# Copy environment template
cp .env.example .env.local

# Install dependencies
npm install

# Start development server
npm run dev

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "test": "vitest",
    "test:watch": "vitest --watch"
  }
}

import { describe, it, expect, vi } from 'vitest';
import { MiroClient } from '../src/miro/client';

describe('Miro Client', () => {
  it('should initialize with API key', () => {
    const client = new MiroClient({ apiKey: 'test-key' });
    expect(client).toBeDefined();
  });
});

vi.mock('@miro/sdk', () => ({
  MiroClient: vi.fn().mockImplementation(() => ({
    // Mock methods here
  })),
}));

# Enable verbose logging
DEBUG=MIRO=* npm run dev

# Document current implementation
find . -name "*.ts" -o -name "*.py" | xargs grep -l "miro" > miro-files.txt

# Count integration points
wc -l miro-files.txt

# Identify dependencies
npm list | grep miro
pip freeze | grep miro

interface MigrationInventory {
  dataTypes: string[];
  recordCounts: Record<string, number>;
  dependencies: string[];
  integrationPoints: string[];
  customizations: string[];
}

async function assessMiroMigration(): Promise<MigrationInventory> {
  return {
    dataTypes: await getDataTypes(),
    recordCounts: await getRecordCounts(),
    dependencies: await analyzeDependencies(),
    integrationPoints: await findIntegrationPoints(),
    customizations: await documentCustomizations(),
  };
}

Phase 1: Parallel Run
┌─────────────┐     ┌─────────────┐
│   Old       │     │   New       │
│   System    │ ──▶ │  Miro   │
│   (100%)    │     │   (0%)      │
└─────────────┘     └─────────────┘

Phase 2: Gradual Shift
┌─────────────┐     ┌─────────────┐
│   Old       │     │   New       │
│   (50%)     │ ──▶ │   (50%)     │
└─────────────┘     └─────────────┘

Phase 3: Complete
┌─────────────┐     ┌─────────────┐
│   Old       │     │   New       │
│   (0%)      │ ──▶ │   (100%)    │
└─────────────┘     └─────────────┘

# Install Miro SDK
npm install @miro/sdk

# Configure credentials
cp .env.example .env.miro
# Edit with new credentials

# Verify connectivity
node -e "require('@miro/sdk').ping()"

// src/adapters/miro.ts
interface ServiceAdapter {
  create(data: CreateInput): Promise<Resource>;
  read(id: string): Promise<Resource>;
  update(id: string, data: UpdateInput): Promise<Resource>;
  delete(id: string): Promise<void>;
}

cl

config/
├── miro/
│   ├── base.json           # Shared config
│   ├── development.json    # Dev overrides
│   ├── staging.json        # Staging overrides
│   └── production.json     # Prod overrides

{
  "timeout": 30000,
  "retries": 3,
  "cache": {
    "enabled": true,
    "ttlSeconds": 60
  }
}

{
  "apiKey": "${MIRO_API_KEY}",
  "baseUrl": "https://api-sandbox.miro.com",
  "debug": true,
  "cache": {
    "enabled": false
  }
}

{
  "apiKey": "${MIRO_API_KEY_STAGING}",
  "baseUrl": "https://api-staging.miro.com",
  "debug": false
}

{
  "apiKey": "${MIRO_API_KEY_PROD}",
  "baseUrl": "https://api.miro.com",
  "debug": false,
  "retries": 5
}

// src/miro/config.ts
import baseConfig from '../../config/miro/base.json';

type Environment = 'development' | 'staging' | 'production';

function detectEnvironment(): Environment {
  const env = process.env.NODE_ENV || 'development';
  const validEnvs: Environment[] = ['development', 'staging', 'production'];
  return validEnvs.includes(env as Environment)
    ? (env as Environment)
    : 'development';
}

export function getMiroConfig() {
  const env = detectEnvironment();
  const envConfig = require(`../../config/miro/${env}.json`);

  return {
    ...baseConfig,
    ...envConfig,
    environment: env,
  };
}

# .env.local (git-ignored)
MIRO_API_KEY=sk_test_dev_***

import { Registry, Counter, Histogram, Gauge } from 'prom-client';

const registry = new Registry();

const requestCounter = new Counter({
  name: 'miro_requests_total',
  help: 'Total Miro API requests',
  labelNames: ['method', 'status'],
  registers: [registry],
});

const requestDuration = new Histogram({
  name: 'miro_request_duration_seconds',
  help: 'Miro request duration',
  labelNames: ['method'],
  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
  registers: [registry],
});

const errorCounter = new Counter({
  name: 'miro_errors_total',
  help: 'Miro errors by type',
  labelNames: ['error_type'],
  registers: [registry],
});

async function instrumentedRequest<T>(
  method: string,
  operation: () => Promise<T>
): Promise<T> {
  const timer = requestDuration.startTimer({ method });

  try {
    const result = await operation();
    requestCounter.inc({ method, status: 'success' });
    return result;
  } catch (error: any) {
    requestCounter.inc({ method, status: 'error' });
    errorCounter.inc({ error_type: error.code || 'unknown' });
    throw error;
  } finally {
    timer();
  }
}

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('miro-client');

async function tracedMiroCall<T>(
  operationName: string,
  operation: () => Promise<T>
): Promise<T> {
  return tracer.startActiveSpan(`miro.${operationName}`, async (span) => {
    try {
      const result = await operation();
      span.setStatus({ code: SpanStatusCode.OK });
      return result;
    } catch (error: any) {
      span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
      span.recordException(error);
      throw err

import { LRUCache } from 'lru-cache';

const cache = new LRUCache<string, any>({
  max: 1000,
  ttl: 60000, // 1 minute
  updateAgeOnGet: true,
});

async function cachedMiroRequest<T>(
  key: string,
  fetcher: () => Promise<T>,
  ttl?: number
): Promise<T> {
  const cached = cache.get(key);
  if (cached) return cached as T;

  const result = await fetcher();
  cache.set(key, result, { ttl });
  return result;
}

import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

async function cachedWithRedis<T>(
  key: string,
  fetcher: () => Promise<T>,
  ttlSeconds = 60
): Promise<T> {
  const cached = await redis.get(key);
  if (cached) return JSON.parse(cached);

  const result = await fetcher();
  await redis.setex(key, ttlSeconds, JSON.stringify(result));
  return result;
}

import DataLoader from 'dataloader';

const miroLoader = new DataLoader<string, any>(
  async (ids) => {
    // Batch fetch from Miro
    const results = await miroClient.batchGet(ids);
    return ids.map(id => results.find(r => r.id === id) || null);
  },
  {
    maxBatchSize: 100,
    batchScheduleFn: callback => setTimeout(callback, 10),
  }
);

// Usage - automatically batched
const [item1, item2, item3] = await Promise.all([
  miroLoader.load('id-1'),
  miroLoader.load('id-2'),
  miroLoader.load('id-3'),
]);

import { Agent } from 'https';

// Keep-alive connection pooling
const agent = new Agent({
  keepAlive: true,
  maxSockets: 10,
  maxFreeSockets: 5,
  timeout: 30000,
});

const client = new MiroClient({
  apiKey: process.env.MIRO_API_KEY!,
  httpAgent: agent,
});

async function* paginatedMiroList<T>(
  fetcher: (cursor?: string) => Promise<{ data: T[]; nextCursor?: string }>
): AsyncGenerator<T> {
  let cursor: string | undefined

# Pre-flight checks
curl -f https://staging.example.com/health
curl -s https://status.miro.com

# Gradual rollout - start with canary (10%)
kubectl apply -f k8s/production.yaml
kubectl set image deployment/miro-integration app=image:new --record
kubectl rollout pause deployment/miro-integration

# Monitor canary traffic for 10 minutes
sleep 600
# Check error rates and latency before continuing

# If healthy, continue rollout to 50%
kubectl rollout resume deployment/miro-integration
kubectl rollout pause deployment/miro-integration
sleep 300

# Complete rollout to 100%
kubectl rollout resume deployment/miro-integration
kubectl rollout status deployment/miro-integration

async function healthCheck(): Promise<{ status: string; miro: any }> {
  const start = Date.now();
  try {
    await

async function withExponentialBackoff<T>(
  operation: () => Promise<T>,
  config = { maxRetries: 5, baseDelayMs: 1000, maxDelayMs: 32000, jitterMs: 500 }
): Promise<T> {
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error: any) {
      if (attempt === config.maxRetries) throw error;
      const status = error.status || error.response?.status;
      if (status !== 429 && (status < 500 || status >= 600)) throw error;

      // Exponential delay with jitter to prevent thundering herd
      const exponentialDelay = config.baseDelayMs * Math.pow(2, attempt);
      const jitter = Math.random() * config.jitterMs;
      const delay = Math.min(exponentialDelay + jitter, config.maxDelayMs);

      console.log(`Rate limited. Retrying in ${delay.toFixed(0)}ms...`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

import { v4 as uuidv4 } from 'uuid';
import crypto from 'crypto';

// Generate deterministic key from operation params (for safe retries)
function generateIdempotencyKey(operation: string, params: Record<string, any>): string {
  const data = JSON.stringify({ operation, params });
  return crypto.createHash('sha256').update(data).digest('hex');
}

async function idempotentRequest<T>(
  client: MiroClient,
  params: Record<string, any>,
  idempotencyKey?: string  // Pass existing key for retries
): Promise<T> {
  // Use provided key (for retries) or generate deterministic key from params
  const key = idempotencyKey || generateIdempotencyKey(params.method || 'POST', params);
  return client.request({
    ...params,
    headers: { 'Idempotency-Key': key, ...params.headers },
  });
}

my-miro-project/
├── src/
│   ├── miro/
│   │   ├── client.ts           # Singleton client wrapper
│   │   ├── config.ts           # Environment configuration
│   │   ├── types.ts            # TypeScript types
│   │   ├── errors.ts           # Custom error classes
│   │   └── handlers/
│   │       ├── webhooks.ts     # Webhook handlers
│   │       └── events.ts       # Event processing
│   ├── services/
│   │   └── miro/
│   │       ├── index.ts        # Service facade
│   │       ├── sync.ts         # Data synchronization
│   │       └── cache.ts        # Caching layer
│   ├── api/
│   │   └── miro/
│   │       └── webhook.ts      # Webhook endpoint
│   └── jobs/
│       └── miro/
│           └── sync.ts         # Background sync job
├── tests/
│   ├── unit/
│   │   └── miro/
│   └── integration/
│       └── miro/
├── config/
│   ├── miro.development.json
│   ├── miro.staging.json
│   └── miro.production.json
└── docs/
    └── miro/
        ├── SETUP.md
        └── RUNBOOK.md

┌─────────────────────────────────────────┐
│             API Layer                    │
│   (Controllers, Routes, Webhooks)        │
├─────────────────────────────────────────┤
│           Service Layer                  │
│  (Business Logic, Orchestration)         │
├─────────────────────────────────────────┤
│          Miro Layer        │
│   (Client, Types, Error Handling)        │
├─────────────────────────────────────────┤
│         Infrastructure Layer             │
│    (Cache, Queue, Monitoring)            │
└─────────────────────────────────────────┘

// src/miro/client.ts
export class MiroService {
  private client: MiroClient;
  private cache: Cache;
  private monitor: Monitor;

  constructor(config: MiroConfig) {
    this.client = new MiroClient(config);
    this.cache = new Cache(config.cacheOptions);
    this.monitor = new Monitor('miro');
  }

  async get(id: string): Promise<Resource> {
    return this.cache.getOrFetch(id, () =>
      this.monitor.track('get', () => this.client.get(id))
    );
  }
}

// src/miro/errors.ts
export class MiroServiceError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly retryable: boolean,
    public readonly originalError?: Error
  ) {
    super(message);
    this.name = 'MiroServiceError';
  }
}

export function wrapMiroError(error: unknown): MiroServiceError {
  /

// src/miro/client.ts
import { MiroClient } from '@miro/sdk';

let instance: MiroClient | null = null;

export function getMiroClient(): MiroClient {
  if (!instance) {
    instance = new MiroClient({
      apiKey: process.env.MIRO_API_KEY!,
      // Additional options
    });
  }
  return instance;
}

import { MiroError } from '@miro/sdk';

async function safeMiroCall<T>(
  operation: () => Promise<T>
): Promise<{ data: T | null; error: Error | null }> {
  try {
    const data = await operation();
    return { data, error: null };
  } catch (err) {
    if (err instanceof MiroError) {
      console.error({
        code: err.code,
        message: err.message,
      });
    }
    return { data: null, error: err as Error };
  }
}

async function withRetry<T>(
  operation: () => Promise<T>,
  maxRetries = 3,
  backoffMs = 1000
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (err) {
      if (attempt === maxRetries) throw err;
      const delay = backoffMs * Math.pow(2, attempt - 1);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

const clients = new Map<string, MiroClient>();

export function getClientForTenant(tenantId: string): MiroClient {
  if (!clients.has(tenantId)) {
    const apiKey = getTenantApiKey(tenantId);
    clients.set(tenantId, new MiroClient({ apiKey }));
  }
  return clients.get(tenantId)!;
}

# .env (NEVER commit to git)
MIRO_API_KEY=sk_live_***
MIRO_SECRET=***

# .gitignore
.env
.env.local
.env.*.local

# 1. Generate new key in Miro dashboard
# 2. Update environment variable
export MIRO_API_KEY="new_key_here"

# 3. Verify new key works
curl -H "Authorization: Bearer ${MIRO_API_KEY}" \
  https://api.miro.com/health

# 4. Revoke old key in dashboard

const clients = {
  reader: new MiroClient({
    apiKey: process.env.MIRO_READ_KEY,
  }),
  writer: new MiroClient({
    apiKey: process.env.MIRO_WRITE_KEY,
  }),
};

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string, signature: string, secret: string
): boolean {
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

interface AuditEntry {
  timestamp: Date;
  action: string;
  userId: string;
  resource: string;
  result: 'success' | 'failure';
  metadata?: Record<string, any>;
}

async function

npm list @miro/sdk
npm view @miro/sdk version

open https://github.com/miro/sdk/releases

git checkout -b upgrade/miro-sdk-vX.Y.Z
npm install @miro/sdk@latest
npm test

// Before (v1.x)
import { Client } from '@miro/sdk';

// After (v2.x)
import { MiroClient } from '@miro/sdk';

// Before (v1.x)
const client = new Client({ key: 'xxx' });

// After (v2.x)
const client = new MiroClient({
  apiKey: 'xxx',
});

npm install @miro/sdk@1.x.x --save-exact

// Monitor for deprecation warnings in development
if (process.env.NODE_ENV === 'development') {
  process.on('warning', (warning) => {
    if (warning.name === 'DeprecationWarning') {
      console.warn('[Miro]', warning.message);
      // Log to tracking system for proactive updates
    }
  });
}

// Common deprecation patterns to watch for:
// - Renamed methods: client.oldMethod() -> client.newMethod()
// - Changed parameters: { key: 'x' } -> { apiKey: 'x' }
// - Removed features: Check release notes before upgrading

import express from 'express';
import crypto from 'crypto';

const app = express();

// IMPORTANT: Raw body needed for signature verification
app.post('/webhooks/miro',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-miro-signature'] as string;
    const timestamp = req.headers['x-miro-timestamp'] as string;

    if (!verifyMiroSignature(req.body, signature, timestamp)) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    const event = JSON.parse(req.body.toString());
    await handleMiroEvent(event);

    res.status(200).json({ received: true });
  }
);

function verifyMiroSignature(
  payload: Buffer,
  signature: string,
  timestamp: string
): boolean {
  const secret = process.env.MIRO_WEBHOOK_SECRET!;

  // Reject old timestamps (replay attack protection)
  const timestampAge = Date.now() - parseInt(timestamp) * 1000;
  if (timestampAge > 300000) { // 5 minutes
    console.error('Webhook timestamp too old');
    return false;
  }

  // Compute expected signature
  const signedPayload = `${timestamp}.${payload.toString()}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  // Timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

type MiroEventType = 'resource.created' | 'resource.updated' | 'resource.deleted';

interface MiroEvent {
  id: string;
  type: MiroEventType;
  data: Record<string, any>;
  created: string;
}

const eventHandlers: Record<MiroEventType, (data: any) => Promise<void>> = {
  'resource.created': async (data) => { /* handle */ },
  'resource.updated': async (data) => { /* handle */ },
  'resource.deleted': async (data) => { /* handle */ }
};

async function handleMiroEvent(event: MiroEvent): Promise<void> {
  const handler = eventHandlers[event.type];

  if (!handler) {
    console.log(`Unhandled event type: ${event.type}`);
    return;
  }

  try {
    await handler(event.data);
    console.log(`Processed ${event.type}: ${event.id}`);
  } catch (error) {
    console.error(`Failed to process ${event.type}: ${event.id}`, error);
    thr