Cookbook SDK

A lightweight postMessage SDK that makes it trivial to connect iframe “client” experiences with a parent “host” web app. Ship tools from untrusted HTML into the Cookbook host without rewriting postMessage plumbing.

• ✅ Automatic client <-> host handshake
• ✅ Simple tool() helper for iframe modules
• ✅ Promise-based complete() IPC from client to host
• ✅ Host-side registry with timeout-aware callTool
• ✅ Works as ESM/CommonJS module or as a global bundle for <script> tags

Installation

npm install cookbook-sdk

Or, when loading from a CDN or local build, include the global bundle:

<script src="https://cdn.example.com/cookbook-sdk.global.js"></script>

Client (iframe) usage

import { createCookbookClient, tool, complete } from 'cookbook-sdk/client';

createCookbookClient({ debug: true });

tool({
  name: 'get-weather',
  description: 'Returns a fake weather report for the requested location.',
  inputSchema: {
    type: 'object',
    properties: {
      location: { type: 'string' }
    },
    required: ['location']
  },
  async execute({ location }) {
    const temperature = 65 + Math.floor(Math.random() * 15);
    return { location, temperature };
  }
});

const completion = await complete('Suggest a dinner idea that uses chicken.');

The client helper automatically forwards tool registrations, handles invocation responses, and times out completion calls after 30 seconds (configurable via completionTimeoutMs).

Host (parent) usage

import { CookbookHost } from 'cookbook-sdk/host';

const host = new CookbookHost({ debug: true });

host.setCompletionHandler(async ({ prompt }) => {
  return {
    message: `Host received: ${prompt}`,
    suggestion: 'Consider pasta with seasonal vegetables.'
  };
});

host.on('toolRegistered', ({ clientId, tool }) => {
  console.log('Tool registered:', clientId, tool.name);
});

async function callFirstTool(args: Record<string, unknown>) {
  const [tool] = host.listTools();
  if (!tool) throw new Error('No tools registered yet');
  return host.callTool(tool.clientId, tool.name, args);
}

Host events

• clientConnected
• clientDisconnected
• toolRegistered
• toolUnregistered

Each call returns a disposer to unsubscribe.

Global bundle usage

When using the generated IIFE bundle, access the API through window.CookbookSDK:

<script src="/dist/cookbook-sdk.global.js"></script>
<script>
  const { CookbookHost, tool, createCookbookClient } = window.CookbookSDK;
</script>

Examples

Run npm run build and open the example parent page:

npm run build
open examples/parent.html

The parent page loads examples/child.html in an iframe, registers a mock weather tool, demonstrates host-driven tool calls, and handles completions initiated by the iframe.

Development

• npm run build – generate ESM, CJS, and global bundles in dist/
• npm run clean – remove build output

The project uses tsup with TypeScript. Update SDK_VERSION in src/utils.ts when publishing new releases.