SapanCalDeveloper Docs

SDKs overview

The official BentoCal SDKs for Node.js and Python: what they do, where they run, and how their methods map to the API.

The official SDKs wrap every API endpoint in a typed method. They take the region from your API key, retry rate limits and provider hiccups for you, turn errors into exceptions with a stable code, and check webhook signatures in one call.

Node.js SDKPython SDK
Packagebentocal on npmbentocal on PyPI
Runs onNode.js 20+, Bun, Deno, Cloudflare Workers, Vercel EdgePython 3.11+, sync or asyncio
DependenciesNonehttpx
TypesGenerated from the API's OpenAPI documentTypedDicts generated from the same document
Verify before publishing: the packages aren't on npm or PyPI yet. Remove this callout once npm install bentocal and pip install bentocal work.
The SDKs are for your server. Your API key is a secret, so never use them in a browser or a mobile app. The Node.js SDK refuses to run in a browser page.

A first call

Both clients read BENTOCAL_API_KEY from the environment. The key already says which region your application lives in, so there's no base URL to set. See Authentication and API keys.

TypeScript
import { BentoCal } from 'bentocal';

const bentocal = new BentoCal();
const session = await bentocal.connectSessions.create({
  user_id: 'user_123',
  redirect_uri: 'https://app.example.com/calendar/connected',
});
Python
from bentocal import BentoCal

client = BentoCal()
session = client.connect_sessions.create(
    user_id="user_123",
    redirect_uri="https://app.example.com/calendar/connected",
)

Fields use the API's own names (user_id, slot_duration_minutes) in both SDKs, so the API reference applies as written. The language pages walk through connecting a calendar, finding a time, writing events, verifying webhooks, errors, retries and configuration.

What both SDKs share

  • Retries: network errors, 429 and 502–504 are retried twice with exponential backoff, honouring Retry-After up to 60 seconds. Each attempt times out after 30 seconds.
  • Errors: API errors are BentoCalApiError with status, code, details and the request ID; network failures and timeouts are BentoCalConnectionError. See Errors.
  • Webhooks: webhooks.verify checks the BentoCal-Signature header against the raw body, rejects signatures more than five minutes old, and accepts both secrets during a rotation. See Webhooks.
  • Environment variables: BENTOCAL_API_KEY, BENTOCAL_WEBHOOK_SECRET and BENTOCAL_BASE_URL.

Methods

Node.jsPythonEndpoint
connectSessions.createconnect_sessions.createPOST /connect_sessions
connectSessions.getconnect_sessions.getGET /connect_sessions/{id}
users.getusers.getGET /users/{user_id}
users.updateusers.updatePATCH /users/{user_id}
users.deleteusers.deleteDELETE /users/{user_id}
connections.getconnections.getGET /connections/{id}
connections.deleteconnections.deleteDELETE /connections/{id}
connections.listCalendarsconnections.list_calendarsGET /connections/{id}/calendars
freeBusy.queryfree_busy.queryPOST /free_busy
availability.queryavailability.queryPOST /availability
events.upsertevents.upsertPUT /users/{user_id}/events/{event_id}
events.deleteevents.deleteDELETE /users/{user_id}/events/{event_id}
webhooks.verifywebhooks.verifyChecks a webhook locally

Not using Node.js or Python? Every SDK call is one HTTPS request; the API reference has them all. Both SDKs are MIT licensed.