@decaf-ts/integrations 0.11.0 → 0.14.0

package/lib/types/calendar/google-calendar/GoogleCalendarService.d.mts

@@ -0,0 +1,316 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.mts";
+/**
+ * @description Configuration for the Google Calendar service
+ * @summary Extends {@link HttpApiServiceConfig} with an optional OAuth
+ * `token`, an optional `apiKey`, and a default `calendarId`. When omitted, the
+ * `calendar.googleCalendar` environment slice supplies the same values (plus
+ * optional `baseUrl`/`timeout`). At least one credential is required; the token
+ * wins when both are set, and the calendar defaults to `"primary"`.
+ * @category Calendar
+ * @memberOf module:integrations/calendar/google-calendar/service
+ */
+export interface GoogleCalendarServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Google OAuth access token
+     * @summary Sent as `Authorization: Bearer <token>` when present.
+     */
+    token?: string;
+    /**
+     * @description Google API key
+     * @summary Sent as the `key` query parameter only when no OAuth token is configured.
+     */
+    apiKey?: string;
+    /**
+     * @description Default calendar ID used when a call does not override it
+     */
+    calendarId?: string;
+}
+/**
+ * @description Input for creating a Google Calendar event
+ * @summary Carries the optional target `calendarId`, `summary`, optional
+ * description and location, start/end values (date or date-time), an optional
+ * time zone, and attendee email addresses.
+ * @category Calendar
+ * @memberOf module:integrations/calendar/google-calendar/service
+ */
+export interface GoogleCalendarEventInput {
+    /**
+     * @description Calendar ID (defaults to the configured value or `primary`)
+     */
+    calendarId?: string;
+    /**
+     * @description Event summary/title
+     */
+    summary: string;
+    /**
+     * @description Event description
+     */
+    description?: string;
+    /**
+     * @description Event location
+     */
+    location?: string;
+    /**
+     * @description Start date (`YYYY-MM-DD`) or date-time (ISO 8601)
+     */
+    start: string;
+    /**
+     * @description End date (`YYYY-MM-DD`) or date-time (ISO 8601)
+     */
+    end: string;
+    /**
+     * @description IANA time zone applied to date-time values
+     */
+    timeZone?: string;
+    /**
+     * @description Attendee email addresses
+     */
+    attendees?: string[];
+}
+/**
+ * @description Input for listing Google Calendar events
+ * @summary Carries the optional `calendarId` plus the time window, result cap,
+ * free-text query, and single-events expansion flag.
+ * @category Calendar
+ * @memberOf module:integrations/calendar/google-calendar/service
+ */
+export interface GoogleCalendarListEventsInput {
+    /**
+     * @description Calendar ID (defaults to the configured value or `primary`)
+     */
+    calendarId?: string;
+    /**
+     * @description Lower bound for event start time (ISO 8601)
+     */
+    timeMin?: string;
+    /**
+     * @description Upper bound for event start time (ISO 8601)
+     */
+    timeMax?: string;
+    /**
+     * @description Maximum number of events to return
+     */
+    maxResults?: number;
+    /**
+     * @description Free-text search across event fields
+     */
+    q?: string;
+    /**
+     * @description Whether recurring events are expanded into instances
+     */
+    singleEvents?: boolean;
+}
+/**
+ * @description Input for updating a Google Calendar event
+ * @summary Carries the optional `calendarId` and the fields to change; omitted
+ * fields are left untouched by the partial update.
+ * @category Calendar
+ * @memberOf module:integrations/calendar/google-calendar/service
+ */
+export interface GoogleCalendarEventUpdate {
+    /**
+     * @description Calendar ID (defaults to the configured value or `primary`)
+     */
+    calendarId?: string;
+    /**
+     * @description New event summary/title
+     */
+    summary?: string;
+    /**
+     * @description New event description
+     */
+    description?: string;
+    /**
+     * @description New event location
+     */
+    location?: string;
+    /**
+     * @description New start date or date-time
+     */
+    start?: string;
+    /**
+     * @description New end date or date-time
+     */
+    end?: string;
+    /**
+     * @description IANA time zone applied to date-time values
+     */
+    timeZone?: string;
+    /**
+     * @description Replacement attendee email addresses
+     */
+    attendees?: string[];
+}
+/**
+ * @description Google Calendar API integration service
+ * @summary An undecorated HTTP service for listing calendars and events and
+ * for creating, reading, updating, and deleting events. Every operation needs
+ * either an OAuth token or an API key; missing credentials or identifiers raise
+ * `InternalError`, and transport failures are mapped to decaf errors via
+ * {@link httpError}.
+ * @class GoogleCalendarService
+ * @extends HttpApiService
+ * @category Calendar
+ * @example
+ * ```ts
+ * import { GoogleCalendarService } from "@decaf-ts/integrations/calendar/google-calendar";
+ *
+ * const calendar = new GoogleCalendarService();
+ * await calendar.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_GOOGLE_CALENDAR_TOKEN,
+ *   calendarId: "primary",
+ * });
+ * await calendar.listEvents({ timeMin: new Date().toISOString() });
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Service as GoogleCalendarService
+ *   participant API as Google Calendar API
+ *   Caller->>Service: createEvent(input)
+ *   activate Service
+ *   Service->>Service: requireAuth()
+ *   Service->>API: POST /calendars/{id}/events
+ *   activate API
+ *   API-->>Service: created event
+ *   deactivate API
+ *   Service-->>Caller: created event
+ *   deactivate Service
+ * @memberOf module:integrations/calendar/google-calendar/service
+ */
+export declare class GoogleCalendarService extends HttpApiService<GoogleCalendarServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Google Calendar";
+    /**
+     * @description The Google Calendar API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://www.googleapis.com/calendar/v3"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Builds the Google Calendar authorization headers
+     * @summary Returns `Authorization: Bearer <token>` when an OAuth token is
+     * configured, and no headers otherwise (API keys travel as query parameters).
+     * @param {GoogleCalendarServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token).
+     */
+    protected authHeaders(config: GoogleCalendarServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the Google Calendar credentials and defaults from the environment
+     * @summary Reads the `calendar.googleCalendar` slice and returns a partial
+     * config when a token or API key is configured, `undefined` otherwise. Values
+     * pass through `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<GoogleCalendarServiceConfig> | undefined} A partial config, or `undefined` when no credential is configured.
+     */
+    protected configFromEnvironment(): Partial<GoogleCalendarServiceConfig> | undefined;
+    /**
+     * @description Asserts that an OAuth token or API key is configured
+     * @summary Called by every operation before it touches the network.
+     * @returns {void}
+     * @throws {InternalError} When neither a token nor an API key is configured.
+     */
+    protected requireAuth(): void;
+    /**
+     * @description Builds API-key query parameters when no OAuth token is set
+     * @summary Returns `{ key }` for API-key authentication, and an empty object
+     * when an OAuth token is used (or no API key is configured).
+     * @returns {Record<string, string>} The query parameters carrying the API key, if any.
+     */
+    private authParams;
+    /**
+     * @description Builds the encoded events path for a calendar
+     * @summary Resolves the calendar ID from the argument, the configured
+     * default, or `"primary"`, then encodes it into
+     * `/calendars/<id>/events`.
+     * @param {string} [calendarId] - Optional per-call calendar ID.
+     * @returns {string} The calendar events API path.
+     */
+    private calendarPath;
+    /**
+     * @description Builds the Google Calendar start/end object
+     * @summary Emits `{ date }` for all-day values and `{ dateTime, timeZone? }`
+     * for values containing a `T` separator.
+     * @param {string} value - The date or date-time value.
+     * @param {string} [timeZone] - Optional IANA time zone for date-time values.
+     * @returns {Record<string, string>} The Calendar API time object.
+     */
+    private eventTime;
+    /**
+     * @description Lists the calendars visible to the authenticated user
+     * @summary `GET`s `/users/me/calendarList` and returns the calendar list.
+     * @returns {Promise<unknown>} The calendar list payload.
+     * @throws {InternalError} When no credential is configured.
+     * @throws {BadRequestError} When Google rejects the request.
+     */
+    listCalendars(): Promise<unknown>;
+    /**
+     * @description Lists events in a calendar
+     * @summary `GET`s the calendar's events applying the optional time window,
+     * result cap, free-text query, and single-events flag.
+     * @param {GoogleCalendarListEventsInput} [input] - The calendar and event query options.
+     * @returns {Promise<unknown>} The event collection payload.
+     * @throws {InternalError} When no credential is configured.
+     * @throws {NotFoundError} When the calendar does not exist (HTTP 404).
+     * @throws {BadRequestError} When Google rejects the query.
+     */
+    listEvents(input?: GoogleCalendarListEventsInput): Promise<unknown>;
+    /**
+     * @description Creates a Google Calendar event
+     * @summary `POST`s the event to the resolved calendar; start/end values are
+     * normalized to Calendar time objects and attendees are mapped to
+     * `{ email }` entries.
+     * @param {GoogleCalendarEventInput} input - The event definition.
+     * @returns {Promise<unknown>} The created event payload.
+     * @throws {InternalError} When no credential is configured, or the summary, start, or end is missing.
+     * @throws {NotFoundError} When the calendar does not exist (HTTP 404).
+     * @throws {BadRequestError} When Google rejects the event.
+     * @example
+     * ```ts
+     * await calendar.createEvent({
+     *   summary: "Release review",
+     *   start: "2026-11-01T09:00:00Z",
+     *   end: "2026-11-01T10:00:00Z",
+     *   attendees: ["team@example.com"],
+     * });
+     * ```
+     */
+    createEvent(input: GoogleCalendarEventInput): Promise<unknown>;
+    /**
+     * @description Fetches a single Google Calendar event
+     * @summary `GET`s the event from the given calendar.
+     * @param {string} calendarId - The calendar ID (empty falls back to the configured value or `primary`).
+     * @param {string} eventId - The event ID.
+     * @returns {Promise<unknown>} The event payload.
+     * @throws {InternalError} When no credential is configured or the event ID is empty.
+     * @throws {NotFoundError} When the event does not exist (HTTP 404).
+     * @throws {BadRequestError} When Google rejects the request.
+     */
+    getEvent(calendarId: string, eventId: string): Promise<unknown>;
+    /**
+     * @description Partially updates a Google Calendar event
+     * @summary `PATCH`es only the supplied fields on the event, normalizing
+     * start/end and attendee values; omitted fields are left unchanged.
+     * @param {string} eventId - The event ID to update.
+     * @param {GoogleCalendarEventUpdate} input - The fields to change.
+     * @returns {Promise<unknown>} The updated event payload.
+     * @throws {InternalError} When no credential is configured or the event ID is empty.
+     * @throws {NotFoundError} When the event does not exist (HTTP 404).
+     * @throws {BadRequestError} When Google rejects the update.
+     */
+    updateEvent(eventId: string, input: GoogleCalendarEventUpdate): Promise<unknown>;
+    /**
+     * @description Deletes a Google Calendar event
+     * @summary `DELETE`s the event from the given calendar and returns
+     * `{ deleted: true, eventId }`.
+     * @param {string} calendarId - The calendar ID (empty falls back to the configured value or `primary`).
+     * @param {string} eventId - The event ID to delete.
+     * @returns {Promise<unknown>} `{ deleted: true, eventId }` on success.
+     * @throws {InternalError} When no credential is configured or the event ID is empty.
+     * @throws {NotFoundError} When the event does not exist (HTTP 404).
+     * @throws {BadRequestError} When Google rejects the deletion.
+     */
+    deleteEvent(calendarId: string, eventId: string): Promise<unknown>;
+}

package/lib/types/calendar/google-calendar/index.d.cts

@@ -0,0 +1,2 @@
+export * from "../environment.d.cts";
+export * from "./GoogleCalendarService.d.cts";

package/lib/types/calendar/google-calendar/index.d.mts

@@ -0,0 +1,2 @@
+export * from "../environment.d.mts";
+export * from "./GoogleCalendarService.d.mts";

package/lib/types/comms/discord/DiscordService.d.cts

@@ -0,0 +1,285 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.cts";
+/**
+ * @description Configuration for the Discord service
+ * @summary Extends {@link HttpApiServiceConfig} with the Discord bot token
+ * sent as `Authorization: Bot <token>`. When omitted, the `comms.discord`
+ * environment slice supplies `token` (plus optional `baseUrl`/`timeout`).
+ * The token is a credential reference read from configuration, never a value
+ * to hard-code in source.
+ * @category Comms
+ * @memberOf module:integrations/comms/discord/service
+ */
+export interface DiscordServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Discord bot token
+     * @summary Sent as `Authorization: Bot <token>` with every API call.
+     */
+    token?: string;
+}
+/**
+ * @description Input for sending a Discord channel message
+ * @summary Carries the destination `channelId`, the message `content`, the
+ * optional text-to-speech flag, and optional rich `embeds`.
+ * @category Comms
+ * @memberOf module:integrations/comms/discord/service
+ */
+export interface DiscordMessageInput {
+    /**
+     * @description ID of the channel that receives the message
+     */
+    channelId: string;
+    /**
+     * @description Plain-text message body
+     */
+    content: string;
+    /**
+     * @description Whether Discord reads the message with text-to-speech
+     */
+    tts?: boolean;
+    /**
+     * @description Rich embed payloads attached to the message
+     */
+    embeds?: unknown[];
+}
+/**
+ * @description Input for listing a Discord channel's messages
+ * @summary Carries the `channelId` plus optional page size and a `before`
+ * message ID cursor for fetching older messages.
+ * @category Comms
+ * @memberOf module:integrations/comms/discord/service
+ */
+export interface DiscordMessageListInput {
+    /**
+     * @description ID of the channel to list messages from
+     */
+    channelId: string;
+    /**
+     * @description Maximum number of messages to return
+     */
+    limit?: number;
+    /**
+     * @description Message ID cursor; only older messages are returned
+     */
+    before?: string;
+}
+/**
+ * @description Input for creating a Discord guild channel
+ * @summary Carries the target `guildId`, the new channel `name`, and the
+ * optional channel `type` (Discord numeric type, default `0` for text),
+ * `topic`, and `parentId` (category).
+ * @category Comms
+ * @memberOf module:integrations/comms/discord/service
+ */
+export interface DiscordChannelInput {
+    /**
+     * @description ID of the guild that owns the new channel
+     */
+    guildId: string;
+    /**
+     * @description Name of the new channel
+     */
+    name: string;
+    /**
+     * @description Discord numeric channel type (default `0`, text channel)
+     */
+    type?: number;
+    /**
+     * @description Optional channel topic
+     */
+    topic?: string;
+    /**
+     * @description Optional parent category ID
+     */
+    parentId?: string;
+}
+/**
+ * @description Input for adding a reaction to a Discord message
+ * @summary Identifies the `channelId`, the target `messageId`, and the
+ * `emoji` to add as the bot user.
+ * @category Comms
+ * @memberOf module:integrations/comms/discord/service
+ */
+export interface DiscordReactionInput {
+    /**
+     * @description ID of the channel containing the message
+     */
+    channelId: string;
+    /**
+     * @description ID of the message to react to
+     */
+    messageId: string;
+    /**
+     * @description Emoji to add (Unicode character or `name:id` custom emoji)
+     */
+    emoji: string;
+}
+/**
+ * @description Discord Bot API integration service
+ * @summary An undecorated HTTP service for channel messages
+ * (`sendMessage`, `getMessage`, `listMessages`), channels (`getChannel`,
+ * `listChannels`, `createChannel`, `deleteChannel`), and reactions
+ * (`addReaction`). Every operation requires a bot token and throws
+ * `InternalError` when it is missing or a required identifier is empty;
+ * transport failures are mapped to decaf errors via {@link httpError}. This is
+ * the callable comms surface (`core.comms.discord`), not the mastra agent
+ * trigger/response kinds.
+ * @class DiscordService
+ * @extends HttpApiService
+ * @category Comms
+ * @example
+ * ```ts
+ * import { DiscordService } from "@decaf-ts/integrations/comms/discord";
+ *
+ * const discord = new DiscordService();
+ * await discord.initialize({ token: process.env.GRAPH_CREDENTIAL_DISCORD_TOKEN });
+ * await discord.sendMessage({
+ *   channelId: process.env.DISCORD_CHANNEL_ID ?? "",
+ *   content: "Deployment finished",
+ * });
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Service as DiscordService
+ *   participant Discord as Discord Bot API
+ *   Caller->>Service: sendMessage(input)
+ *   activate Service
+ *   Service->>Service: requireBotToken()
+ *   Service->>Discord: POST /channels/{id}/messages
+ *   activate Discord
+ *   Discord-->>Service: message payload
+ *   deactivate Discord
+ *   Service-->>Caller: message payload
+ *   deactivate Service
+ * @memberOf module:integrations/comms/discord/service
+ */
+export declare class DiscordService extends HttpApiService<DiscordServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Discord";
+    /**
+     * @description The Discord Bot API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://discord.com/api/v10"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Builds the Discord bot authorization header
+     * @summary Returns `Authorization: Bot <token>` when the config carries a
+     * token, and no headers otherwise.
+     * @param {DiscordServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token).
+     */
+    protected authHeaders(config: DiscordServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the Discord credentials and defaults from the environment
+     * @summary Reads the `comms.discord` environment slice and returns a partial
+     * config when a bot token is configured, `undefined` otherwise. Values pass
+     * through `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<DiscordServiceConfig> | undefined} A partial config, or `undefined` when no Discord token is configured.
+     */
+    protected configFromEnvironment(): Partial<DiscordServiceConfig> | undefined;
+    /**
+     * @description Asserts that a Discord bot token is configured
+     * @summary Called by every operation before it touches the network.
+     * @returns {void}
+     * @throws {InternalError} When the resolved config has no `token`.
+     */
+    protected requireBotToken(): void;
+    /**
+     * @description Builds the encoded path for a channel resource
+     * @summary Validates the channel ID and URL-encodes it into `/channels/<id>`.
+     * @param {string} channelId - The Discord channel ID.
+     * @returns {string} The channel API path.
+     * @throws {InternalError} When `channelId` is empty.
+     */
+    private channelPath;
+    /**
+     * @description Sends a message to a Discord channel
+     * @summary `POST`s the content (and optional `tts`/`embeds`) to the channel
+     * messages endpoint and returns Discord's message payload.
+     * @param {DiscordMessageInput} input - The destination channel and message content.
+     * @returns {Promise<unknown>} The created message payload.
+     * @throws {InternalError} When no bot token is configured.
+     * @throws {BadRequestError} When Discord rejects the request.
+     * @example
+     * ```ts
+     * await discord.sendMessage({ channelId: "1234567890", content: "Hello" });
+     * ```
+     */
+    sendMessage(input: DiscordMessageInput): Promise<unknown>;
+    /**
+     * @description Fetches a single Discord message
+     * @summary `GET`s the message by channel and message ID and returns the
+     * message payload.
+     * @param {string} channelId - The channel containing the message.
+     * @param {string} messageId - The message ID to fetch.
+     * @returns {Promise<unknown>} The message payload.
+     * @throws {InternalError} When no bot token is configured or the message ID is empty.
+     * @throws {NotFoundError} When the message does not exist (HTTP 404).
+     * @throws {BadRequestError} When Discord rejects the request.
+     */
+    getMessage(channelId: string, messageId: string): Promise<unknown>;
+    /**
+     * @description Lists messages in a Discord channel
+     * @summary `GET`s the channel messages with the optional `limit` and
+     * `before` cursor and returns Discord's message page.
+     * @param {DiscordMessageListInput} input - The channel and paging options.
+     * @returns {Promise<unknown>} The message page payload.
+     * @throws {InternalError} When no bot token is configured.
+     * @throws {BadRequestError} When Discord rejects the request.
+     */
+    listMessages(input: DiscordMessageListInput): Promise<unknown>;
+    /**
+     * @description Fetches a Discord channel
+     * @summary `GET`s the channel by ID and returns its payload.
+     * @param {string} channelId - The channel ID to fetch.
+     * @returns {Promise<unknown>} The channel payload.
+     * @throws {InternalError} When no bot token is configured or the channel ID is empty.
+     * @throws {NotFoundError} When the channel does not exist (HTTP 404).
+     * @throws {BadRequestError} When Discord rejects the request.
+     */
+    getChannel(channelId: string): Promise<unknown>;
+    /**
+     * @description Lists every channel in a Discord guild
+     * @summary `GET`s `/guilds/<id>/channels` and returns the channel list.
+     * @param {string} guildId - The guild whose channels are listed.
+     * @returns {Promise<unknown>} The guild channel list payload.
+     * @throws {InternalError} When no bot token is configured or the guild ID is empty.
+     * @throws {BadRequestError} When Discord rejects the request.
+     */
+    listChannels(guildId: string): Promise<unknown>;
+    /**
+     * @description Creates a channel in a Discord guild
+     * @summary `POST`s the channel `name`, numeric `type` (default text), and
+     * optional `topic`/`parentId` to the guild channels endpoint.
+     * @param {DiscordChannelInput} input - The guild and new channel definition.
+     * @returns {Promise<unknown>} The created channel payload.
+     * @throws {InternalError} When no bot token is configured.
+     * @throws {BadRequestError} When Discord rejects the request.
+     */
+    createChannel(input: DiscordChannelInput): Promise<unknown>;
+    /**
+     * @description Deletes a Discord channel
+     * @summary `DELETE`s the channel and returns the response payload, falling
+     * back to `{ deleted: true, channelId }` when Discord returns no body.
+     * @param {string} channelId - The channel ID to delete.
+     * @returns {Promise<unknown>} The deletion payload.
+     * @throws {InternalError} When no bot token is configured or the channel ID is empty.
+     * @throws {NotFoundError} When the channel does not exist (HTTP 404).
+     * @throws {BadRequestError} When Discord rejects the request.
+     */
+    deleteChannel(channelId: string): Promise<unknown>;
+    /**
+     * @description Adds a reaction to a Discord message as the bot
+     * @summary `PUT`s the emoji to the message's `@me` reaction endpoint and
+     * echoes the channel and message IDs on success.
+     * @param {DiscordReactionInput} input - The channel, message, and emoji.
+     * @returns {Promise<unknown>} `{ channelId, messageId }` on success.
+     * @throws {InternalError} When no bot token is configured, or the message ID or emoji is empty.
+     * @throws {BadRequestError} When Discord rejects the request.
+     */
+    addReaction(input: DiscordReactionInput): Promise<unknown>;
+}