SaaS API with Webhooks

A TypeScript SDK for a SaaS product with a rich feature set: OAuth2 authorization code flow, webhook signature verification, SSE streaming responses, cursor pagination with async iterators, and a mock client for testing.

opensdk: "1.0.0"

openapi:
  $ref: "./openapi.yaml"

sdk:
  name: "saas-platform"
  version: "3.0.0"
  license: "MIT"

languages:
  - language: typescript
    package:
      name: "@saas/platform-sdk"
      registry: npm
    style:
      naming: camelCase
      enumStyle: string-union
      optionalStyle: question-mark
      dateStyle: string           # ISO-8601 strings avoid Date serialization quirks
      fileNaming: kebab-case
    features:
      auth:
        - oauth2-authorization-code
        - api-key                 # fallback for server-to-server
      retries:
        enabled: true
        maxAttempts: 3
        backoff: exponential
        retryOn: [429, 500, 503]
      pagination:
        strategy: cursor
        iteratorHelper: true      # asyncIterator<Page<T>> helpers
        defaultPageSize: 50
      streaming: true             # ReadableStream / SSE helpers
      webhooks: true              # payload types + HMAC-SHA256 verification
      mocking: true               # vitest-compatible mock client
      examples: true
      telemetry:
        enabled: true
        traces: true
        metrics: true
    additionalProperties:
      usePromises: true
      treeshakable: true
      generateFetchWrapper: true  # thin fetch wrapper, no axios dependency

codegenRules:
  validation:
    - rule: no-unnamed-operations
      severity: error
    - rule: required-tags
      severity: error
    - rule: required-descriptions
      severity: warn
    - rule: no-deprecated-without-successor
      severity: warn
  breakingChangePolicy: deprecate-first   # keep old symbols for one release cycle
  sdkVersioning: semver-manual
  outputStructure: by-tag

The webhooks: true flag generates:

• Typed payload interfaces for each webhook event schema
• An verifyWebhookSignature(payload, secret, headers) helper using HMAC-SHA256
• A webhook router utility for matching event types to handlers

The mocking: true flag generates a mock client that implements the same interface as the real client, making it drop-in compatible with vitest, jest, and other test runners.