Helixdevelopment Helixagent Windsurf Sdk Patterns

Windsurf SDK Patterns

Overview

Production-ready patterns for Windsurf SDK usage in TypeScript and Python.

Prerequisites

• Completed windsurf-install-auth setup
• Familiarity with async/await patterns
• Understanding of error handling best practices

Instructions

Step 1: Implement Singleton Pattern (Recommended)

// src/windsurf/client.ts
import { WindsurfClient } from '@windsurf/sdk';

let instance: WindsurfClient | null = null;

export function getWindsurfClient(): WindsurfClient {
  if (!instance) {
    instance = new WindsurfClient({
      apiKey: process.env.WINDSURF_API_KEY!,
      // Additional options
    });
  }
  return instance;
}

Step 2: Add Error Handling Wrapper

import { WindsurfError } from '@windsurf/sdk';

async function safeWindsurfCall<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 WindsurfError) {
      console.error({
        code: err.code,
        message: err.message,
      });
    }
    return { data: null, error: err as Error };
  }
}

Step 3: Implement Retry Logic

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');
}

Output

• Type-safe client singleton
• Robust error handling with structured logging
• Automatic retry with exponential backoff
• Runtime validation for API responses

Error Handling

Examples

Factory Pattern (Multi-tenant)

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

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

Python Context Manager

from contextlib import asynccontextmanager
from windsurf import WindsurfClient

@asynccontextmanager
async def get_windsurf_client():
    client = WindsurfClient()
    try:
        yield client
    finally:
        await client.close()

Zod Validation

import { z } from 'zod';

const windsurfResponseSchema = z.object({
  id: z.string(),
  status: z.enum(['active', 'inactive']),
  createdAt: z.string().datetime(),
});

Resources

• Windsurf SDK Reference
• Windsurf API Types
• Zod Documentation

Next Steps

Apply patterns in windsurf-core-workflow-a for real-world usage.

Source: HelixDevelopment/HelixAgent — distributed by TomeVault.