@bagdock/worker-sdk

  ----++                                ----++                    ---+++     
  ---+++                                ---++                     ---++      
 ----+---     -----     ---------  --------++ ------     -----   ----++----- 
 ---------+ --------++----------++--------+++--------+ --------++---++---++++
 ---+++---++ ++++---++---+++---++---+++---++---+++---++---++---++------++++  
----++ ---++--------++---++----++---+++---++---++ ---+---++     -------++    
----+----+---+++---++---++----++---++----++---++---+++--++ --------+---++   
---------++--------+++--------+++--------++ -------+++ -------++---++----++  
 +++++++++   +++++++++- +++---++   ++++++++    ++++++    ++++++  ++++  ++++  
                     --------+++                                             
                       +++++++                                               

@bagdock/worker-sdk

Platform SDK for building Bagdock adapter workers on Cloudflare Workers — lifecycle hooks, typed comms contract, webhook verification primitives, and error boundaries.

Install

npm install @bagdock/worker-sdk

yarn add @bagdock/worker-sdk

pnpm add @bagdock/worker-sdk

bun add @bagdock/worker-sdk

Requires @cloudflare/workers-types as a peer dependency.

Quick start

import { createCommsWorker } from '@bagdock/worker-sdk'
import type { HandlerContext } from '@bagdock/worker-sdk'

interface Env {
  TELNYX_API_KEY: string
  OPERATOR_CONFIG?: KVNamespace
}

async function handleSmsSend(ctx: HandlerContext<Env>): Promise<Response> {
  const { to, body } = await ctx.request.json() as { to: string; body: string }
  // Call your vendor's SMS API using ctx.env for secrets
  return Response.json({ id: crypto.randomUUID(), status: 'queued' })
}

export default createCommsWorker<Env>({
  capabilities: ['sms'],

  async onInstall(ctx) {
    // Provision vendor resources, store per-installation state
    await ctx.store.put('api_key', 'vendor-key-from-provisioning')
    return { installation_state: { provisioned: true } }
  },

  async onUninstall(ctx) {
    // Clean up vendor resources
  },

  routes: {
    'sms/send': handleSmsSend,
  },
})

What the SDK handles

Concern	You write	SDK handles
Lifecycle	onInstall / onUninstall hooks	Idempotency flags, retry safety, dual-write to platform state
Routing	Route handlers as functions	__platform/setup, __platform/teardown, health, dispatch routing, 404s
Comms contract	Declare capabilities	Compile-time route enforcement per capability (SMS, voice, numbers)
Health	Optional vendor reachability check	Auto-generated health response, 15s TTL cache, in-flight dedup
Webhooks	Adapter-local VerifyFunction	Clone-based body handoff, structured 401/500 error responses
Errors	Nothing	Structured JSON errors with timing headers, global error boundary

Webhook verification

The SDK is vendor-agnostic — it knows nothing about Telnyx, Stripe, Shopify, or any other vendor. Webhook verification follows the same pattern every major platform uses: the vendor who signs the webhook publishes the SDK that verifies it.

Default path: vendor SDK (recommended)

// src/verify.ts — adapter-local, wraps the vendor's own SDK
import Telnyx from 'telnyx'
import type { VerifyFunction } from '@bagdock/worker-sdk'
import type { Env } from './types'

const client = new Telnyx()

export const telnyxWebhookVerify: VerifyFunction<Env> = async (request, env, body) => {
  try {
    await client.webhooks.unwrap(body, {
      headers: {
        'telnyx-signature-ed25519': request.headers.get('telnyx-signature-ed25519') ?? '',
        'telnyx-timestamp': request.headers.get('telnyx-timestamp') ?? '',
      },
      key: env.TELNYX_WEBHOOK_PUBLIC_KEY,
    })
    return true
  } catch {
    return Response.json({ error: 'Invalid webhook signature' }, { status: 401 })
  }
}

Fallback path: SDK primitives

For vendors without a Workers-compatible SDK, wrap the SDK's crypto primitives:

import { ed25519Verify } from '@bagdock/worker-sdk'
import type { VerifyFunction } from '@bagdock/worker-sdk'
import type { Env } from './types'

export const vendorVerify: VerifyFunction<Env> = (req, env, body) =>
  ed25519Verify({
    signature: req.headers.get('x-sig-ed25519'),
    publicKey: env.VENDOR_PUBLIC_KEY,
    signingString: `${req.headers.get('x-timestamp')}|${body}`,
    timestamp: req.headers.get('x-timestamp'),
  })

Both hmacSha256Verify and ed25519Verify handle null signatures, timestamp skew, and constant-time comparison — callers can safely pass headers.get(...) without pre-checking.

API reference

Factories

Export	Description
createBagdockWorker(config)	Base factory — lifecycle hooks, health, routing, error boundaries
createCommsWorker(config)	Comms factory — extends base with capabilities-driven typed route enforcement

Verification primitives

Export	Description
hmacSha256Verify(opts)	HMAC-SHA256 verification with constant-time comparison
ed25519Verify(opts)	Ed25519 verification via Web Crypto

Types

Type	Description
HandlerContext<E>	Unified context for all handlers — operator ID, installation ID, env, store, logger
VerifyFunction<E>	Webhook verification contract — (request, env, rawBody) => Promise<true | Response>
CommsCapability	'sms' | 'voice' | 'numbers'
InstallStore	Per-installation encrypted state bag (KV-backed)
RouteHandler<E>	(ctx: HandlerContext<E>) => Promise<Response>
SendSMSParams / SendSMSResult	SMS contract types
CreateCallParams / CallResult	Voice contract types
NumberSearchParams / AvailableNumber	Numbers contract types

Documentation

• Full documentation
• Worker SDK guide
• API reference

License

MIT — see LICENSE