AI-Powered Connector Integration: Wiring Up External APIs Faster

Every Stripe integration starts the same way — auth headers, request builders, error mappers, retry logic. Let the AI handle the boilerplate so you can focus on the business logic that makes your integration unique.

The Premise

Logic Bee's connector architecture separates external API communication into reusable connector classes in libs/connectors/. When a hook needs to talk to Stripe, QuickBooks, or UPS, it calls a connector — never the raw HTTP client. This pattern is perfect for AI generation because connectors follow a rigid contract.

The developer's role shifts from writing HTTP calls to validating auth flows, error mapping, and retry behavior.

The Story

The team needs a new ShipStation integration for the shipping-management library. A developer prompts:

"Add a ShipStation connector that creates shipment labels and tracks packages. Wire it into a new hook called create-shipment-label in shipping-management. Use the connectors, creating-hooks, and bob-request-api skills."

The AI generates two things: the connector class and the hook that uses it.

What the AI Generates

The Connector

export class ShipStationConnector {
  private baseUrl = 'https://ssapi.shipstation.com'
  
  constructor(private apiKey: string, private apiSecret: string) {}

  async createLabel(shipmentData: CreateLabelPayload): Promise<ShipStationLabel> {
    const response = await fetch(`${this.baseUrl}/shipments/createlabel`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Basic ${Buffer.from(`${this.apiKey}:${this.apiSecret}`).toString('base64')}`
      },
      body: JSON.stringify(shipmentData)
    })
    
    if (!response.ok) {
      throw naoFormatErrorById('bad_request', {
        reason: `ShipStation API error: ${response.status}`
      })
    }
    
    return response.json()
  }
}

The Hook

@LogicHook({
  name: 'ShippingManagementCreateShipmentLabel',
  path: 'shipping-management/create-shipment-label',
  library: 'shipping-management',
  method: 'create-shipment-label',
  legacy: 'app/app.shippingManagementHooks.createShipmentLabel'
})
export class ShippingManagementCreateShipmentLabel {
  public static execute() {
    return async (bob: BobRequest<{ data: { data: any; naoQueryOptions: NaoQueryOptions } }>) => {
      let ok = true, error: any = null, data
      try {
        const eventOptions = {
          shipmentQuery: { docName: 'shipment', cfpPath: 'shipping/shipments' }
        }

        // -->Get: shipment document
        const shipment = await bob.flowGlobal
          .getFlowCollection(eventOptions.shipmentQuery)
          .docs.flowQuery()
          .user(bob.flowUser)
          .flowOptions(eventOptions.shipmentQuery)
          .docId(bob.dataPayload.docId)
          .getOne()

        if (!shipment) {
          throw naoFormatErrorById('not_found', { reason: 'Shipment not found' })
        }

        // -->Create: shipping label via connector
        const connector = new ShipStationConnector(
          process.env.SHIPSTATION_API_KEY,
          process.env.SHIPSTATION_API_SECRET
        )
        const label = await connector.createLabel({
          orderId: shipment.data.orderId,
          weight: shipment.data.totalWeight,
          dimensions: shipment.data.dimensions,
          shipTo: shipment.data.shippingAddress
        })

        // -->Update: shipment with tracking info
        await bob.flowGlobal
          .getFlowCollection(eventOptions.shipmentQuery)
          .docs.flowQuery()
          .user(bob.flowUser)
          .flowOptions(eventOptions.shipmentQuery)
          .docId(shipment.docId)
          .updateOne({
            'data.trackingNumber': label.trackingNumber,
            'data.labelUrl': label.labelUrl,
            'data.status': 'label-created'
          }, bob.dbSession())

        ok = true
        data = { docIds: [shipment.docId], trackingNumber: label.trackingNumber }
      } catch (err) { error = err; ok = false }
      return returnEventResult(bob, { ok, error, data })
    }
  }
}

What You Need to Verify

1. Credential Management

AI often hardcodes process.env.VARIABLE_NAME directly. In Logic Bee, credentials should flow through the configuration layer:

// ❌ AI default
const connector = new ShipStationConnector(
  process.env.SHIPSTATION_API_KEY,
  process.env.SHIPSTATION_API_SECRET
)

// ✅ Better: use workspace-scoped config
const config = bob.flowUser.getWorkspaceConfig('shipstation')
const connector = new ShipStationConnector(config.apiKey, config.apiSecret)

2. Error Response Mapping

The AI generates a generic error handler. Real APIs return structured errors — map them:

// ✅ Map API-specific errors to Logic Bee error format
if (!response.ok) {
  const errorBody = await response.json()
  throw naoFormatErrorById('bad_request', {
    reason: `ShipStation: ${errorBody.ExceptionMessage || response.statusText}`,
    details: errorBody
  })
}

3. Rate Limiting and Retries

External APIs have rate limits. The AI rarely adds retry logic unless prompted.

4. Payload Validation

Verify the connector validates outbound payloads before sending — missing required fields should fail fast, not at the API level.

The Takeaway

The connector integration checklist:

• Credentials loaded from workspace config, not process.env
• API errors mapped to naoFormatErrorById with descriptive reasons
• Rate limiting and retry logic included
• Outbound payload validated before API call
• Response types match TypeScript interfaces
• API-specific edge cases documented in connector class

Let AI wire the plumbing. You verify the valves.