@agentforge-io/connectors-calendly 3.0.0

package/dist/connector.d.ts

@@ -0,0 +1,26 @@
+import type { ConnectorDefinition } from '@agentforge-io/core';
+export interface CalendlyConnectorOptions {
+    clientId: string;
+    clientSecret: string;
+    /** Optional override of the logo asset URL shown in the Directory. */
+    iconUrl?: string;
+}
+/**
+ * Build the Calendly `ConnectorDefinition` to feed into
+ * `ConnectorRegistryService.register(...)`. The host owns the
+ * `clientId` / `clientSecret` pair — typically resolved from the platform
+ * vault under `CALENDLY_OAUTH_CLIENT_ID` / `CALENDLY_OAUTH_CLIENT_SECRET`,
+ * with an optional per-tenant override (mirrors HubSpot / Slack pattern).
+ *
+ * OAuth notes:
+ *  - Calendly does NOT use granular scopes. The grant is all-or-nothing on
+ *    the connected account, so we leave `scopes: []` and the registry will
+ *    omit the param from the authorize URL.
+ *  - Access tokens TTL is 7200s (2h). Refresh tokens ROTATE on every
+ *    refresh — the core registry already persists the new refresh_token
+ *    when one comes back (see `buildAuthFields`), so no extra wiring
+ *    needed here.
+ *  - PKCE is supported and recommended by Calendly. The registry defaults
+ *    `usePkce` to true; we keep that.
+ */
+export declare function calendlyConnector(opts: CalendlyConnectorOptions): ConnectorDefinition;

package/dist/connector.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calendlyConnector = calendlyConnector;
+const get_user_1 = require("./tools/get-user");
+const list_event_types_1 = require("./tools/list-event-types");
+const list_scheduled_events_1 = require("./tools/list-scheduled-events");
+const get_event_1 = require("./tools/get-event");
+const list_invitees_1 = require("./tools/list-invitees");
+const cancel_event_1 = require("./tools/cancel-event");
+/**
+ * Build the Calendly `ConnectorDefinition` to feed into
+ * `ConnectorRegistryService.register(...)`. The host owns the
+ * `clientId` / `clientSecret` pair — typically resolved from the platform
+ * vault under `CALENDLY_OAUTH_CLIENT_ID` / `CALENDLY_OAUTH_CLIENT_SECRET`,
+ * with an optional per-tenant override (mirrors HubSpot / Slack pattern).
+ *
+ * OAuth notes:
+ *  - Calendly does NOT use granular scopes. The grant is all-or-nothing on
+ *    the connected account, so we leave `scopes: []` and the registry will
+ *    omit the param from the authorize URL.
+ *  - Access tokens TTL is 7200s (2h). Refresh tokens ROTATE on every
+ *    refresh — the core registry already persists the new refresh_token
+ *    when one comes back (see `buildAuthFields`), so no extra wiring
+ *    needed here.
+ *  - PKCE is supported and recommended by Calendly. The registry defaults
+ *    `usePkce` to true; we keep that.
+ */
+function calendlyConnector(opts) {
+    return {
+        id: 'calendly',
+        name: 'Calendly',
+        description: 'Read Calendly event types, list scheduled meetings, fetch invitee ' +
+            'details, and cancel events from agent conversations.',
+        category: 'Scheduling',
+        iconUrl: opts.iconUrl,
+        oauth: {
+            authorizeUrl: 'https://auth.calendly.com/oauth/authorize',
+            tokenUrl: 'https://auth.calendly.com/oauth/token',
+            clientId: opts.clientId,
+            clientSecret: opts.clientSecret,
+            scopes: [],
+            usePkce: true,
+        },
+        tools: [
+            get_user_1.calendlyGetUserTool,
+            list_event_types_1.calendlyListEventTypesTool,
+            list_scheduled_events_1.calendlyListScheduledEventsTool,
+            get_event_1.calendlyGetEventTool,
+            list_invitees_1.calendlyListInviteesTool,
+            cancel_event_1.calendlyCancelEventTool,
+        ],
+    };
+}

package/dist/http.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Thin wrapper around `fetch` for calling Calendly v2 APIs with the
+ * tenant's access token. Kept dep-free on purpose — the official
+ * `@calendly/api-client` is geared at the booking widget, not server
+ * automation, and carries an auth layer we already own.
+ *
+ * Three transparent retries on top of `fetch`:
+ *   - 429: honors `Retry-After` (seconds), up to 2 retries. Calendly's
+ *     default rate limit is generous (1k req/min per token) but bursts
+ *     during agent runs can blow past it.
+ *   - 5xx: one retry with ~500ms jitter.
+ *   - 401: NOT retried here — the registry catches it, refreshes the
+ *     token, and the agent runner re-dispatches the tool call. Retrying
+ *     here with the same expired token would just burn another HTTP.
+ */
+export declare class CalendlyApiError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: string;
+    constructor(status: number, statusText: string, body: string);
+}
+export interface CalendlyGetOptions {
+    accessToken: string;
+    url: string;
+    query?: Record<string, string | number | boolean | undefined>;
+}
+export declare function calendlyGet<T>(opts: CalendlyGetOptions): Promise<T>;
+export interface CalendlyPostOptions {
+    accessToken: string;
+    url: string;
+    body: unknown;
+}
+export declare function calendlyPost<T>(opts: CalendlyPostOptions): Promise<T>;

package/dist/http.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Thin wrapper around `fetch` for calling Calendly v2 APIs with the
+ * tenant's access token. Kept dep-free on purpose — the official
+ * `@calendly/api-client` is geared at the booking widget, not server
+ * automation, and carries an auth layer we already own.
+ *
+ * Three transparent retries on top of `fetch`:
+ *   - 429: honors `Retry-After` (seconds), up to 2 retries. Calendly's
+ *     default rate limit is generous (1k req/min per token) but bursts
+ *     during agent runs can blow past it.
+ *   - 5xx: one retry with ~500ms jitter.
+ *   - 401: NOT retried here — the registry catches it, refreshes the
+ *     token, and the agent runner re-dispatches the tool call. Retrying
+ *     here with the same expired token would just burn another HTTP.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CalendlyApiError = void 0;
+exports.calendlyGet = calendlyGet;
+exports.calendlyPost = calendlyPost;
+class CalendlyApiError extends Error {
+    constructor(status, statusText, body) {
+        super(`Calendly API ${status} ${statusText}: ${body.slice(0, 500)}`);
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+    }
+}
+exports.CalendlyApiError = CalendlyApiError;
+const MAX_429_RETRIES = 2;
+const MAX_5XX_RETRIES = 1;
+async function send(method, opts) {
+    const headers = {
+        authorization: `Bearer ${opts.accessToken}`,
+        accept: 'application/json',
+    };
+    let body;
+    if (opts.body !== undefined && method !== 'GET') {
+        headers['content-type'] = 'application/json';
+        body = JSON.stringify(opts.body);
+    }
+    let attempt429 = 0;
+    let attempt5xx = 0;
+    while (true) {
+        const res = await fetch(opts.url, { method, headers, body });
+        if (res.status === 429 && attempt429 < MAX_429_RETRIES) {
+            const retryAfter = Number(res.headers.get('retry-after') ?? '1');
+            const delayMs = (Number.isFinite(retryAfter) ? retryAfter : 1) * 1000;
+            await sleep(delayMs);
+            attempt429++;
+            continue;
+        }
+        if (res.status >= 500 && res.status < 600 && attempt5xx < MAX_5XX_RETRIES) {
+            await sleep(400 + Math.floor(Math.random() * 200));
+            attempt5xx++;
+            continue;
+        }
+        return res;
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+async function calendlyGet(opts) {
+    const url = new URL(opts.url);
+    for (const [k, v] of Object.entries(opts.query ?? {})) {
+        if (v === undefined || v === null)
+            continue;
+        url.searchParams.set(k, String(v));
+    }
+    const res = await send('GET', { accessToken: opts.accessToken, url: url.toString() });
+    if (!res.ok) {
+        throw new CalendlyApiError(res.status, res.statusText, await res.text().catch(() => ''));
+    }
+    return (await res.json());
+}
+async function calendlyPost(opts) {
+    const res = await send('POST', opts);
+    if (!res.ok) {
+        throw new CalendlyApiError(res.status, res.statusText, await res.text().catch(() => ''));
+    }
+    // Calendly's cancellation endpoint returns 201 with the cancelled
+    // event payload; the meeting-create endpoints return 201. We never
+    // see a 204 from this API in practice, but guard against it anyway
+    // so we don't surface a confusing "Unexpected end of JSON input" if
+    // they ever add one.
+    if (res.status === 204)
+        return undefined;
+    return (await res.json());
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { calendlyConnector, type CalendlyConnectorOptions } from './connector';
+export { calendlyGetUserTool } from './tools/get-user';
+export { calendlyListEventTypesTool } from './tools/list-event-types';
+export { calendlyListScheduledEventsTool } from './tools/list-scheduled-events';
+export { calendlyGetEventTool } from './tools/get-event';
+export { calendlyListInviteesTool } from './tools/list-invitees';
+export { calendlyCancelEventTool } from './tools/cancel-event';
+export { CalendlyApiError } from './http';

package/dist/index.js

@@ -0,0 +1,35 @@
+"use strict";
+// Public API of @agentforge-io/connectors-calendly.
+//
+// Usage in a host's bootstrap:
+//
+//   import { calendlyConnector } from '@agentforge-io/connectors-calendly';
+//   connectorRegistry.register(calendlyConnector({
+//     clientId: env.CALENDLY_OAUTH_CLIENT_ID,
+//     clientSecret: env.CALENDLY_OAUTH_CLIENT_SECRET,
+//   }));
+//
+// Tools registered (per-tenant, after a workspace admin has OAuth'd):
+//   calendly_get_user, calendly_list_event_types,
+//   calendly_list_scheduled_events, calendly_get_event,
+//   calendly_list_invitees, calendly_cancel_event
+//
+// See `CALENDLY_CONNECTOR_SDD.md` at the repo root for the full design.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CalendlyApiError = exports.calendlyCancelEventTool = exports.calendlyListInviteesTool = exports.calendlyGetEventTool = exports.calendlyListScheduledEventsTool = exports.calendlyListEventTypesTool = exports.calendlyGetUserTool = exports.calendlyConnector = void 0;
+var connector_1 = require("./connector");
+Object.defineProperty(exports, "calendlyConnector", { enumerable: true, get: function () { return connector_1.calendlyConnector; } });
+var get_user_1 = require("./tools/get-user");
+Object.defineProperty(exports, "calendlyGetUserTool", { enumerable: true, get: function () { return get_user_1.calendlyGetUserTool; } });
+var list_event_types_1 = require("./tools/list-event-types");
+Object.defineProperty(exports, "calendlyListEventTypesTool", { enumerable: true, get: function () { return list_event_types_1.calendlyListEventTypesTool; } });
+var list_scheduled_events_1 = require("./tools/list-scheduled-events");
+Object.defineProperty(exports, "calendlyListScheduledEventsTool", { enumerable: true, get: function () { return list_scheduled_events_1.calendlyListScheduledEventsTool; } });
+var get_event_1 = require("./tools/get-event");
+Object.defineProperty(exports, "calendlyGetEventTool", { enumerable: true, get: function () { return get_event_1.calendlyGetEventTool; } });
+var list_invitees_1 = require("./tools/list-invitees");
+Object.defineProperty(exports, "calendlyListInviteesTool", { enumerable: true, get: function () { return list_invitees_1.calendlyListInviteesTool; } });
+var cancel_event_1 = require("./tools/cancel-event");
+Object.defineProperty(exports, "calendlyCancelEventTool", { enumerable: true, get: function () { return cancel_event_1.calendlyCancelEventTool; } });
+var http_1 = require("./http");
+Object.defineProperty(exports, "CalendlyApiError", { enumerable: true, get: function () { return http_1.CalendlyApiError; } });

package/dist/tools/cancel-event.d.ts

@@ -0,0 +1,12 @@
+import type { ConnectorToolFactory } from '@agentforge-io/core';
+/**
+ * Cancel a Calendly meeting. The `reason` field is required by the
+ * Calendly API — passing an empty string is rejected with 400, so we
+ * default it server-side to a generic message. The invitee receives
+ * Calendly's standard cancellation email automatically.
+ *
+ * **Approval recommended.** This is a side-effectful write that's
+ * visible to the invitee — wire it as `approval` mode on the agent's
+ * tool whitelist so the human confirms before the email goes out.
+ */
+export declare const calendlyCancelEventTool: ConnectorToolFactory;

package/dist/tools/cancel-event.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calendlyCancelEventTool = void 0;
+const http_1 = require("../http");
+/**
+ * Cancel a Calendly meeting. The `reason` field is required by the
+ * Calendly API — passing an empty string is rejected with 400, so we
+ * default it server-side to a generic message. The invitee receives
+ * Calendly's standard cancellation email automatically.
+ *
+ * **Approval recommended.** This is a side-effectful write that's
+ * visible to the invitee — wire it as `approval` mode on the agent's
+ * tool whitelist so the human confirms before the email goes out.
+ */
+exports.calendlyCancelEventTool = {
+    definition: {
+        name: 'calendly_cancel_event',
+        description: 'Cancel a scheduled Calendly meeting. Calendly emails the invitee ' +
+            'the cancellation automatically. **This is a destructive action ' +
+            'visible to the invitee** — consider asking the human to confirm ' +
+            'before invoking. Returns the cancellation record on success.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                eventUri: {
+                    type: 'string',
+                    description: 'Calendly event URI (e.g. ' +
+                        '`https://api.calendly.com/scheduled_events/ABCD`).',
+                },
+                reason: {
+                    type: 'string',
+                    description: 'Reason shown to the invitee in the cancellation email. ' +
+                        'Defaults to "Cancelled by host" if omitted. Keep it short ' +
+                        '— Calendly renders it inline.',
+                },
+            },
+            required: ['eventUri'],
+        },
+    },
+    build: (ctx) => async (input) => {
+        const eventUri = String(input.eventUri ?? '').trim();
+        if (!eventUri)
+            throw new Error('eventUri is required');
+        if (!eventUri.startsWith('https://api.calendly.com/scheduled_events/')) {
+            throw new Error('eventUri must be a Calendly scheduled event URI (starts with ' +
+                'https://api.calendly.com/scheduled_events/)');
+        }
+        const reason = typeof input.reason === 'string' && input.reason.trim()
+            ? input.reason.trim()
+            : 'Cancelled by host';
+        const accessToken = await ctx.getAccessToken();
+        const url = `${eventUri}/cancellation`;
+        const result = await (0, http_1.calendlyPost)({
+            accessToken,
+            url,
+            body: { reason },
+        });
+        return JSON.stringify({
+            cancelled: result.resource.canceled,
+            reason: result.resource.reason,
+            cancelerType: result.resource.canceler_type,
+            cancelledAt: result.resource.created_at,
+        });
+    },
+};

package/dist/tools/get-event.d.ts

@@ -0,0 +1,7 @@
+import type { ConnectorToolFactory } from '@agentforge-io/core';
+/**
+ * Fetch a single scheduled event's full payload by URI. Use this after
+ * `calendly_list_scheduled_events` returns an event you want to inspect
+ * in detail — meeting notes, host members, join URL, etc.
+ */
+export declare const calendlyGetEventTool: ConnectorToolFactory;

package/dist/tools/get-event.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calendlyGetEventTool = void 0;
+const http_1 = require("../http");
+/**
+ * Fetch a single scheduled event's full payload by URI. Use this after
+ * `calendly_list_scheduled_events` returns an event you want to inspect
+ * in detail — meeting notes, host members, join URL, etc.
+ */
+exports.calendlyGetEventTool = {
+    definition: {
+        name: 'calendly_get_event',
+        description: 'Fetch a single Calendly scheduled event by its URI. Returns full ' +
+            'detail including meeting notes, location, host members, and ' +
+            'invitee count. Use after `calendly_list_scheduled_events` when ' +
+            'you need fields the list view omits.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                eventUri: {
+                    type: 'string',
+                    description: 'Calendly event URI (e.g. ' +
+                        '`https://api.calendly.com/scheduled_events/ABCD`) returned ' +
+                        'by `calendly_list_scheduled_events`.',
+                },
+            },
+            required: ['eventUri'],
+        },
+    },
+    build: (ctx) => async (input) => {
+        const eventUri = String(input.eventUri ?? '').trim();
+        if (!eventUri)
+            throw new Error('eventUri is required');
+        if (!eventUri.startsWith('https://api.calendly.com/scheduled_events/')) {
+            throw new Error('eventUri must be a Calendly scheduled event URI (starts with ' +
+                'https://api.calendly.com/scheduled_events/)');
+        }
+        const accessToken = await ctx.getAccessToken();
+        const json = await (0, http_1.calendlyGet)({
+            accessToken,
+            url: eventUri,
+        });
+        const e = json.resource;
+        return JSON.stringify({
+            uri: e.uri,
+            name: e.name,
+            status: e.status,
+            startTime: e.start_time,
+            endTime: e.end_time,
+            eventTypeUri: e.event_type,
+            location: e.location
+                ? {
+                    type: e.location.type,
+                    location: e.location.location,
+                    joinUrl: e.location.join_url,
+                }
+                : undefined,
+            invitees: e.invitees_counter,
+            meetingNotes: e.meeting_notes_plain ?? undefined,
+            hosts: e.event_memberships?.map((m) => ({
+                userUri: m.user,
+                email: m.user_email,
+            })),
+        });
+    },
+};

package/dist/tools/get-user.d.ts

@@ -0,0 +1,9 @@
+import type { ConnectorToolFactory } from '@agentforge-io/core';
+/**
+ * Returns the connected Calendly user's identity + organization URI. The
+ * `uri` and `current_organization` fields are needed by almost every
+ * other Calendly endpoint (event types are scoped to a user, scheduled
+ * events to an organization). Cheap call — agents should hit this once
+ * at the top of a session and reuse the result.
+ */
+export declare const calendlyGetUserTool: ConnectorToolFactory;

package/dist/tools/get-user.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calendlyGetUserTool = void 0;
+const http_1 = require("../http");
+const USERS_ME = 'https://api.calendly.com/users/me';
+/**
+ * Returns the connected Calendly user's identity + organization URI. The
+ * `uri` and `current_organization` fields are needed by almost every
+ * other Calendly endpoint (event types are scoped to a user, scheduled
+ * events to an organization). Cheap call — agents should hit this once
+ * at the top of a session and reuse the result.
+ */
+exports.calendlyGetUserTool = {
+    definition: {
+        name: 'calendly_get_user',
+        description: 'Fetch the connected Calendly account: name, email, scheduling URL, ' +
+            'timezone, user URI, and organization URI. Call this once at the ' +
+            'start of any Calendly workflow — most other Calendly tools need ' +
+            'the `userUri` or `organizationUri` returned here.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    build: (ctx) => async () => {
+        const accessToken = await ctx.getAccessToken();
+        const json = await (0, http_1.calendlyGet)({
+            accessToken,
+            url: USERS_ME,
+        });
+        const r = json.resource;
+        return JSON.stringify({
+            uri: r.uri,
+            name: r.name,
+            email: r.email,
+            schedulingUrl: r.scheduling_url,
+            timezone: r.timezone,
+            organizationUri: r.current_organization,
+        });
+    },
+};

package/dist/tools/list-event-types.d.ts

@@ -0,0 +1,11 @@
+import type { ConnectorToolFactory } from '@agentforge-io/core';
+/**
+ * List the user's Calendly event types — the bookable meeting templates
+ * the operator has configured on calendly.com (e.g. "30-min intro",
+ * "Strategy call"). Agents need this when an invitee asks "how do I book
+ * a meeting with you?" so the agent can return the right `scheduling_url`.
+ *
+ * Calendly doesn't expose a way to CREATE event types via API; templates
+ * are managed in the Calendly UI. This tool only reads.
+ */
+export declare const calendlyListEventTypesTool: ConnectorToolFactory;

package/dist/tools/list-event-types.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calendlyListEventTypesTool = void 0;
+const http_1 = require("../http");
+const EVENT_TYPES = 'https://api.calendly.com/event_types';
+/**
+ * List the user's Calendly event types — the bookable meeting templates
+ * the operator has configured on calendly.com (e.g. "30-min intro",
+ * "Strategy call"). Agents need this when an invitee asks "how do I book
+ * a meeting with you?" so the agent can return the right `scheduling_url`.
+ *
+ * Calendly doesn't expose a way to CREATE event types via API; templates
+ * are managed in the Calendly UI. This tool only reads.
+ */
+exports.calendlyListEventTypesTool = {
+    definition: {
+        name: 'calendly_list_event_types',
+        description: "List the Calendly user's bookable event types (meeting templates). " +
+            'Returns each event type with its name, duration, scheduling URL, ' +
+            'and active status. **Call `calendly_get_user` first** to obtain ' +
+            'the `userUri` required by this endpoint.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                userUri: {
+                    type: 'string',
+                    description: 'Calendly user URI (e.g. `https://api.calendly.com/users/ABCD`) ' +
+                        'returned by `calendly_get_user`.',
+                },
+                activeOnly: {
+                    type: 'boolean',
+                    default: true,
+                    description: 'When true (default), only return event types currently ' +
+                        'accepting bookings. Set to false to also include disabled ones.',
+                },
+            },
+            required: ['userUri'],
+        },
+    },
+    build: (ctx) => async (input) => {
+        const userUri = String(input.userUri ?? '').trim();
+        if (!userUri)
+            throw new Error('userUri is required');
+        const activeOnly = input.activeOnly !== false;
+        const accessToken = await ctx.getAccessToken();
+        const result = await (0, http_1.calendlyGet)({
+            accessToken,
+            url: EVENT_TYPES,
+            query: {
+                user: userUri,
+                active: activeOnly ? true : undefined,
+            },
+        });
+        return JSON.stringify({
+            total: result.pagination.count,
+            eventTypes: result.collection.map((e) => ({
+                uri: e.uri,
+                name: e.name,
+                slug: e.slug,
+                durationMinutes: e.duration,
+                schedulingUrl: e.scheduling_url,
+                active: e.active,
+                kind: e.kind,
+                description: e.description_plain ?? undefined,
+            })),
+        });
+    },
+};

package/dist/tools/list-invitees.d.ts

@@ -0,0 +1,9 @@
+import type { ConnectorToolFactory } from '@agentforge-io/core';
+/**
+ * List the people who booked into a specific scheduled event. The
+ * `questions_and_answers` field exposes whatever custom intake form
+ * the operator configured on the event type — that's usually where the
+ * "How can I help?" context lives, which is gold for an agent
+ * preparing a meeting briefing.
+ */
+export declare const calendlyListInviteesTool: ConnectorToolFactory;

package/dist/tools/list-invitees.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calendlyListInviteesTool = void 0;
+const http_1 = require("../http");
+/**
+ * List the people who booked into a specific scheduled event. The
+ * `questions_and_answers` field exposes whatever custom intake form
+ * the operator configured on the event type — that's usually where the
+ * "How can I help?" context lives, which is gold for an agent
+ * preparing a meeting briefing.
+ */
+exports.calendlyListInviteesTool = {
+    definition: {
+        name: 'calendly_list_invitees',
+        description: "List the invitees (bookers) on a specific Calendly scheduled " +
+            'event. Returns each invitee with name, email, status, timezone, ' +
+            'and any intake-form answers. Use this to brief an agent before a ' +
+            'meeting or to find the cancel/reschedule URLs for an invitee.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                eventUri: {
+                    type: 'string',
+                    description: 'Calendly event URI (e.g. ' +
+                        '`https://api.calendly.com/scheduled_events/ABCD`).',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['active', 'canceled'],
+                    description: 'Optional filter — only return invitees in this status.',
+                },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 100,
+                    default: 20,
+                },
+            },
+            required: ['eventUri'],
+        },
+    },
+    build: (ctx) => async (input) => {
+        const eventUri = String(input.eventUri ?? '').trim();
+        if (!eventUri)
+            throw new Error('eventUri is required');
+        if (!eventUri.startsWith('https://api.calendly.com/scheduled_events/')) {
+            throw new Error('eventUri must be a Calendly scheduled event URI (starts with ' +
+                'https://api.calendly.com/scheduled_events/)');
+        }
+        const limit = Math.min(100, Math.max(1, Number(input.limit ?? 20)));
+        const accessToken = await ctx.getAccessToken();
+        const url = `${eventUri}/invitees`;
+        const result = await (0, http_1.calendlyGet)({
+            accessToken,
+            url,
+            query: {
+                status: input.status === 'active' || input.status === 'canceled'
+                    ? input.status
+                    : undefined,
+                count: limit,
+            },
+        });
+        return JSON.stringify({
+            total: result.pagination.count,
+            invitees: result.collection.map((i) => ({
+                uri: i.uri,
+                name: i.name,
+                email: i.email,
+                status: i.status,
+                timezone: i.timezone,
+                rescheduled: i.rescheduled,
+                cancelUrl: i.cancel_url,
+                rescheduleUrl: i.reschedule_url,
+                intake: i.questions_and_answers
+                    .filter((q) => q.answer && q.answer.trim().length > 0)
+                    .map((q) => ({ question: q.question, answer: q.answer })),
+            })),
+        });
+    },
+};

package/dist/tools/list-scheduled-events.d.ts

@@ -0,0 +1,8 @@
+import type { ConnectorToolFactory } from '@agentforge-io/core';
+/**
+ * List scheduled meetings on the connected Calendly account. Returns
+ * recent + upcoming meetings filtered by date range, status, or invitee
+ * email. Hard-capped at 100 results — the model rarely needs more, and
+ * Calendly's `count` query param tops out at 100 anyway.
+ */
+export declare const calendlyListScheduledEventsTool: ConnectorToolFactory;

package/dist/tools/list-scheduled-events.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calendlyListScheduledEventsTool = void 0;
+const http_1 = require("../http");
+const SCHEDULED_EVENTS = 'https://api.calendly.com/scheduled_events';
+/**
+ * List scheduled meetings on the connected Calendly account. Returns
+ * recent + upcoming meetings filtered by date range, status, or invitee
+ * email. Hard-capped at 100 results — the model rarely needs more, and
+ * Calendly's `count` query param tops out at 100 anyway.
+ */
+exports.calendlyListScheduledEventsTool = {
+    definition: {
+        name: 'calendly_list_scheduled_events',
+        description: 'List scheduled Calendly meetings filtered by date range, status, ' +
+            'or invitee email. Returns each meeting with its URI, name, ' +
+            'start/end time, status, location, and invitee count. **Call ' +
+            '`calendly_get_user` first** to obtain `userUri` or ' +
+            '`organizationUri`. Use `organizationUri` to see all meetings in ' +
+            'the workspace; use `userUri` to see only this user\'s meetings.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                userUri: {
+                    type: 'string',
+                    description: 'Calendly user URI. Pass either this OR `organizationUri` ' +
+                        '(not both).',
+                },
+                organizationUri: {
+                    type: 'string',
+                    description: 'Calendly organization URI. Pass either this OR `userUri` ' +
+                        '(not both).',
+                },
+                minStartTime: {
+                    type: 'string',
+                    description: 'ISO 8601 timestamp — only return meetings starting at or ' +
+                        'after this time (e.g. `2026-06-07T00:00:00Z`).',
+                },
+                maxStartTime: {
+                    type: 'string',
+                    description: 'ISO 8601 timestamp — only return meetings starting at or ' +
+                        'before this time.',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['active', 'canceled'],
+                    description: 'Filter by status. Omit to return both active and canceled.',
+                },
+                inviteeEmail: {
+                    type: 'string',
+                    description: "Optional — only return meetings where this email is an " +
+                        'invitee. Useful for "what meetings do I have with X?" queries.',
+                },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 100,
+                    default: 20,
+                },
+            },
+        },
+    },
+    build: (ctx) => async (input) => {
+        const userUri = typeof input.userUri === 'string' ? input.userUri.trim() : '';
+        const organizationUri = typeof input.organizationUri === 'string'
+            ? input.organizationUri.trim()
+            : '';
+        if (!userUri && !organizationUri) {
+            throw new Error('userUri or organizationUri is required');
+        }
+        const limit = Math.min(100, Math.max(1, Number(input.limit ?? 20)));
+        const accessToken = await ctx.getAccessToken();
+        const result = await (0, http_1.calendlyGet)({
+            accessToken,
+            url: SCHEDULED_EVENTS,
+            query: {
+                user: userUri || undefined,
+                organization: organizationUri || undefined,
+                min_start_time: typeof input.minStartTime === 'string' ? input.minStartTime : undefined,
+                max_start_time: typeof input.maxStartTime === 'string' ? input.maxStartTime : undefined,
+                status: input.status === 'active' || input.status === 'canceled'
+                    ? input.status
+                    : undefined,
+                invitee_email: typeof input.inviteeEmail === 'string' && input.inviteeEmail
+                    ? input.inviteeEmail
+                    : undefined,
+                count: limit,
+            },
+        });
+        return JSON.stringify({
+            total: result.pagination.count,
+            events: result.collection.map((e) => ({
+                uri: e.uri,
+                name: e.name,
+                status: e.status,
+                startTime: e.start_time,
+                endTime: e.end_time,
+                eventTypeUri: e.event_type,
+                location: e.location
+                    ? {
+                        type: e.location.type,
+                        location: e.location.location,
+                        joinUrl: e.location.join_url,
+                    }
+                    : undefined,
+                invitees: e.invitees_counter,
+            })),
+        });
+    },
+};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@agentforge-io/connectors-calendly",
+  "version": "3.0.0",
+  "description": "Calendly connector for AgentForge \u2014 event types, scheduled events, invitees, and cancellation tools wired to per-tenant OAuth2 credentials managed by the core ConnectorRegistryService.",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist *.tgz"
+  },
+  "peerDependencies": {
+    "@agentforge-io/core": "^3.0.0"
+  },
+  "devDependencies": {
+    "@agentforge-io/core": "*",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}