Skip to main content

Advanced SDK Features

The Scaffald SDK includes several advanced features for optimizing API usage, customizing requests, and improving performance.

Table of Contents​

Request/Response Interceptors​

Interceptors allow you to transform requests before they're sent, modify responses before they're returned, or handle errors in a custom way.

Request Interceptors​

Add custom headers, log requests, or modify URLs before they're sent:

import Scaffald from '@scaffald/sdk'

const client = new Scaffald({ apiKey: 'sk_live_...' })

// Add a request interceptor
const id = client.getInterceptors().addRequestInterceptor(async (url, init) => {
  // Add custom header
  init.headers = {
    ...init.headers,
    'X-Request-ID': crypto.randomUUID(),
  }

  // Log request
  console.log('Request:', init.method, url)

  return { url, init }
})

// Remove interceptor later
client.getInterceptors().removeRequestInterceptor(id)

Response Interceptors​

Transform or log responses:

// Add a response interceptor
client.getInterceptors().addResponseInterceptor(async (response) => {
  // Log response
  console.log('Response:', response.status, response.url)

  // You can clone and modify the response if needed
  return response
})

Error Interceptors​

Handle errors globally:

// Add an error interceptor
client.getInterceptors().addErrorInterceptor(async (error) => {
  // Log error to external service
  console.error('API Error:', error.message)

  // You can return a custom Response to recover from errors
  // Or re-throw the error to propagate it
  return error
})

Use Cases​

Authentication Refresh:

client.getInterceptors().addErrorInterceptor(async (error) => {
  if (error.message.includes('401')) {
    // Refresh token
    const newToken = await refreshAccessToken()

    // Update client
    // Note: You'll need to create a new client with the new token

    // Or return a new response after retry
  }

  return error
})

Request Logging:

client.getInterceptors().addRequestInterceptor(async (url, init) => {
  await analytics.track('api_request', {
    url,
    method: init.method,
    timestamp: Date.now(),
  })

  return { url, init }
})

Response Caching​

The SDK includes an intelligent response cache that can dramatically reduce API calls and improve performance.

Enable Caching​

const client = new Scaffald({
  apiKey: 'sk_live_...',
  cache: {
    enabled: true,
    defaultTtl: 5 * 60 * 1000, // 5 minutes (default)
    maxSize: 100, // Maximum 100 cached responses (default)
  },
})

Cache Control​

// Enable cache after initialization
client.getCache().enable()

// Disable cache
client.getCache().disable()

// Clear all cache
client.getCache().clear()

// Invalidate specific cache entries
client.getCache().invalidate(/jobs/) // Clear all job-related cache

// Get cache statistics
const stats = client.getCache().getStats()
console.log(`Cache: ${stats.size}/${stats.maxSize} (${stats.enabled ? 'enabled' : 'disabled'})`)

How It Works​

  • Only GET requests are cached by default
  • Cache keys include URL and query parameters
  • Cached responses respect TTL (time-to-live)
  • LRU eviction when cache is full
  • Separate cache per client instance

Example: Smart Caching Strategy​

const client = new Scaffald({
  apiKey: 'sk_live_...',
  cache: {
    enabled: true,
    defaultTtl: 5 * 60 * 1000, // 5 minutes for most endpoints
  },
})

// Fetch jobs (will be cached)
const jobs = await client.jobs.list({ limit: 20 })

// Same request within 5 minutes will use cache
const cachedJobs = await client.jobs.list({ limit: 20 }) // Instant!

// Invalidate cache after creating a new application
await client.applications.createQuick({ /* ... */ })
client.getCache().invalidate(/applications/)

Request Deduplication​

Request deduplication prevents multiple identical concurrent requests from being sent to the API.

How It Works​

When multiple parts of your application request the same data simultaneously, only one HTTP request is made. All callers receive a clone of the same response.

const client = new Scaffald({
  apiKey: 'sk_live_...',
  enableDeduplication: true, // Enabled by default
})

// These three calls happen simultaneously
const [job1, job2, job3] = await Promise.all([
  client.jobs.retrieve('job_123'),
  client.jobs.retrieve('job_123'),
  client.jobs.retrieve('job_123'),
])

// Only ONE HTTP request was made!
// All three calls receive the same data

Disable Deduplication​

const client = new Scaffald({
  apiKey: 'sk_live_...',
  enableDeduplication: false,
})

When It Helps​

  • React components: Multiple components fetching the same data during render
  • Parallel operations: Making multiple API calls at once
  • Real-time updates: Polling the same endpoint from different parts of your app

Limitations​

  • Only deduplicates GET requests
  • Only prevents concurrent duplicate requests
  • Does not deduplicate sequential requests (use caching for that)

Rate Limit Tracking​

Monitor and react to API rate limits in real-time.

Get Rate Limit Info​

const info = client.getRateLimitInfo()

if (info) {
  console.log(`Rate limit: ${info.remaining}/${info.limit}`)
  console.log(`Resets in ${client.getSecondsUntilRateLimitReset()} seconds`)
}

Subscribe to Updates​

const unsubscribe = client.onRateLimitUpdate((info) => {
  console.log(`Rate limit updated: ${info.remaining}/${info.limit}`)

  if (client.isRateLimitApproaching()) {
    console.warn('⚠️  Rate limit approaching!')
  }

  if (client.isRateLimitExceeded()) {
    console.error('❌ Rate limit exceeded!')
  }
})

// Later: clean up
unsubscribe()

React Hook Example​

import { useEffect, useState } from 'react'
import { client } from './client'

function useRateLimit() {
  const [rateLimit, setRateLimit] = useState(client.getRateLimitInfo())

  useEffect(() => {
    const unsubscribe = client.onRateLimitUpdate(setRateLimit)
    return unsubscribe
  }, [])

  return {
    rateLimit,
    isApproaching: client.isRateLimitApproaching(),
    isExceeded: client.isRateLimitExceeded(),
    secondsUntilReset: client.getSecondsUntilRateLimitReset(),
  }
}

function RateLimitBadge() {
  const { rateLimit, isApproaching } = useRateLimit()

  if (!rateLimit) return null

  return (
    <div className={isApproaching ? 'warning' : 'normal'}>
      {rateLimit.remaining}/{rateLimit.limit} requests remaining
    </div>
  )
}

Bundle Optimization​

The SDK is built with aggressive optimization to keep bundle sizes small.

Bundle Sizes​

The SDK is split into multiple bundles for optimal tree-shaking:

  • Core SDK (@scaffald/sdk): Main client with all resources
  • React Hooks (@scaffald/sdk/react): React-specific hooks
  • OAuth (@scaffald/sdk/oauth): OAuth client only
  • Webhooks (@scaffald/sdk/webhooks): Webhook verification only

Import What You Need​

// Full SDK (includes everything)
import Scaffald from '@scaffald/sdk'

// OAuth only (smaller bundle)
import { OAuthClient } from '@scaffald/sdk/oauth'

// Webhooks only (smaller bundle)
import { verifyWebhookSignature } from '@scaffald/sdk/webhooks'

Analyze Bundle Size​

# Build and analyze bundle sizes
pnpm build:analyze

# Output:
# ┌─────────────────────────────────────────┬────────────┬──────────────┐
# │ Bundle                                  │ Size       │ Gzipped      │
# ├─────────────────────────────────────────┼────────────┼──────────────┤
# │ index.mjs                               │ 45.2 KB    │ 12.8 KB      │
# │ react/index.mjs                         │ 8.5 KB     │ 2.1 KB       │
# │ oauth/oauth.mjs                         │ 6.2 KB     │ 1.8 KB       │
# │ webhooks/verify.mjs                     │ 2.1 KB     │ 0.7 KB       │
# └─────────────────────────────────────────┴────────────┴──────────────┘

Build Optimizations​

The SDK uses several build optimizations:

  1. Code Splitting: Separate bundles for optional features
  2. Tree Shaking: Aggressive unused code removal
  3. Minification: Property mangling and comment removal
  4. Modern Target: ES2020+ for smaller output
  5. Dual Format: ESM (smaller) and CJS (compatibility)

Tree Shaking Example​

// ❌ Imports everything
import Scaffald from '@scaffald/sdk'

// ✅ Only imports OAuth (tree-shakes the rest)
import { OAuthClient } from '@scaffald/sdk'

// ✅ Even better: use the standalone OAuth bundle
import { OAuthClient } from '@scaffald/sdk/oauth'

Configuration Reference​

Complete configuration example with all advanced features:

const client = new Scaffald({
  // Authentication
  apiKey: 'sk_live_...',
  // OR
  accessToken: 'oauth_token',

  // Network
  baseUrl: 'https://api.scaffald.com',
  maxRetries: 3,
  timeout: 60000, // 60 seconds

  // Custom headers
  headers: {
    'X-Custom-Header': 'value',
  },

  // Caching
  cache: {
    enabled: true,
    defaultTtl: 5 * 60 * 1000, // 5 minutes
    maxSize: 100,
  },

  // Deduplication
  enableDeduplication: true,
})

// Add interceptors
client.getInterceptors().addRequestInterceptor(async (url, init) => {
  // Custom request logic
  return { url, init }
})

client.getInterceptors().addResponseInterceptor(async (response) => {
  // Custom response logic
  return response
})

client.getInterceptors().addErrorInterceptor(async (error) => {
  // Custom error handling
  return error
})

// Subscribe to rate limits
const unsubscribe = client.onRateLimitUpdate((info) => {
  console.log('Rate limit:', info)
})

Best Practices​

1. Enable Caching for Read-Heavy Apps​

const client = new Scaffald({
  apiKey: 'sk_live_...',
  cache: {
    enabled: true,
    defaultTtl: 5 * 60 * 1000, // 5 minutes
  },
})

2. Use Request Deduplication​

// Default behavior - keep it enabled!
const client = new Scaffald({
  apiKey: 'sk_live_...',
  enableDeduplication: true,
})

3. Monitor Rate Limits Proactively​

client.onRateLimitUpdate((info) => {
  if (info.remaining < 10) {
    // Throttle requests
    console.warn('Approaching rate limit!')
  }
})

4. Use Interceptors for Cross-Cutting Concerns​

// Logging
client.getInterceptors().addRequestInterceptor(async (url, init) => {
  logger.info('API Request', { url, method: init.method })
  return { url, init }
})

// Error tracking
client.getInterceptors().addErrorInterceptor(async (error) => {
  errorTracker.captureException(error)
  return error
})

5. Invalidate Cache After Mutations​

// Create new job
await client.jobs.create(/* ... */)

// Clear job cache so next list() call fetches fresh data
client.getCache().invalidate(/jobs/)

Next Steps​