@decaf-ts/integrations 0.11.0 → 0.14.0

package/lib/esm/comms/gmail/GmailService.js

@@ -0,0 +1,230 @@
+/**
+ * @module integrations/comms/gmail/service
+ * @summary Gmail API integration service for sending and listing messages.
+ * @description Exposes the Gmail REST API (`users.messages.send`,
+ * `users.messages.list`, `users.messages.get`, `users.labels.list`) as an
+ * undecorated client-based service built on {@link HttpApiService}.
+ * Message sending reuses the shared MIME builder from the email integration
+ * (`buildEmail`) and posts the raw MIME message as base64url. Configuration
+ * comes from an explicit `GmailServiceConfig` or the `comms.gmail` environment
+ * slice, and failures are mapped to decaf errors via {@link httpError}.
+ */
+import { InternalError } from "@decaf-ts/db-decorators";
+import { CommsEnvironment } from "./../environment.js";
+import { envNumber, envString } from "./../../shared/environmentValue.js";
+import { HttpApiService, httpError, } from "./../../shared/http/index.js";
+import { buildEmail } from "./../email/mime.js";
+/**
+ * @description Gmail API integration service
+ * @summary An undecorated HTTP service for sending MIME-built
+ * emails, listing messages with Gmail query syntax and page tokens, fetching
+ * a single message in a chosen format, and listing labels. All operations
+ * require an OAuth token (`requireToken()`) and operate on the configured
+ * `userId` mailbox (default `"me"`); transport failures are mapped to decaf
+ * errors via {@link httpError}.
+ * @class GmailService
+ * @category Comms
+ * @example
+ * ```ts
+ * import { GmailService } from "@decaf-ts/integrations/comms/gmail";
+ *
+ * const gmail = new GmailService();
+ * await gmail.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_GMAIL_TOKEN,
+ * });
+ * await gmail.send({
+ *   from: "bot@example.com",
+ *   to: "ops@example.com",
+ *   subject: "Deploy",
+ *   text: "Release 1.2.0 is live",
+ * });
+ * ```
+ * @memberOf module:integrations/comms/gmail/service
+ */
+export class GmailService extends HttpApiService {
+    constructor() {
+        super(...arguments);
+        /**
+         * @description The provider name used in error messages
+         */
+        this.serviceName = "Gmail";
+    }
+    /**
+     * @description The Gmail REST API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://gmail.googleapis.com/gmail/v1"`.
+     */
+    defaultBaseUrl() {
+        return "https://gmail.googleapis.com/gmail/v1";
+    }
+    /**
+     * @description Builds the Gmail OAuth bearer authorization headers
+     * @summary Returns the `Authorization: Bearer <token>` header when the
+     * config carries a token, and no headers otherwise.
+     * @param {GmailServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token).
+     */
+    authHeaders(config) {
+        return config.token ? { Authorization: `Bearer ${config.token}` } : {};
+    }
+    /**
+     * @description Reads the Gmail credentials and defaults from the environment
+     * @summary Reads the `comms.gmail` environment slice and returns a partial
+     * config when a token is configured, `undefined` otherwise. Values pass
+     * through `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<GmailServiceConfig> | undefined} A partial config, or `undefined` when no Gmail token is configured.
+     */
+    configFromEnvironment() {
+        const env = CommsEnvironment.comms.gmail;
+        const token = envString(env?.token);
+        if (!token)
+            return undefined;
+        return {
+            token,
+            userId: envString(env.userId),
+            baseUrl: envString(env.baseUrl),
+            timeout: envNumber(env.timeout),
+        };
+    }
+    /**
+     * @description Builds the mailbox-scoped API path
+     * @summary Returns `/users/<userId>` with the configured `userId` (or
+     * `"me"` when unset) URL-encoded; all message and label operations are
+     * relative to this path.
+     * @returns {string} The URL-encoded mailbox path.
+     */
+    userPath() {
+        return `/users/${encodeURIComponent(this.config.userId ?? "me")}`;
+    }
+    /**
+     * @description Sends an email through the Gmail API
+     * @summary Builds a raw MIME message from the input with the shared email
+     * MIME builder (`buildEmail`), base64url-encodes it, and `POST`s it to
+     * `users.messages.send`. Requires a token and a `from` sender address.
+     * @param {EmailMessageInput} input - The message envelope and body (`from`, `to`, `subject`, and optional `cc`/`bcc`/`text`/`html`/`replyTo`/`attachments`).
+     * @returns {Promise<GmailSendResult>} Gmail's identifiers for the sent message.
+     * @throws {InternalError} When no token is configured or the sender address is missing.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When Gmail answers with HTTP 409.
+     * @throws {BadRequestError} When Gmail answers with any other HTTP error status (e.g. invalid recipients).
+     */
+    async send(input) {
+        this.requireToken();
+        if (!input.from) {
+            throw new InternalError("Gmail send requires a sender address");
+        }
+        const built = buildEmail(input);
+        try {
+            const response = await this.client.post(`${this.userPath()}/messages/send`, {
+                raw: Buffer.from(built.raw, "utf8").toString("base64url"),
+            });
+            return {
+                id: String(response.data.id ?? built.messageId),
+                threadId: response.data.threadId,
+                labelIds: response.data.labelIds,
+            };
+        }
+        catch (error) {
+            throw httpError("Gmail", "send message", error);
+        }
+    }
+    /**
+     * @description Lists mailbox messages with Gmail query paging
+     * @summary `GET`s `users.messages.list` with an optional Gmail `query`
+     * (`q` parameter, e.g. `"from:user@example.com is:unread"`), a page size
+     * (default `25`), a `pageToken` from the previous page, and `labelIds`
+     * filtering. Returns the message references and the `nextPageToken` to pass
+     * back as `pageToken` for the next page.
+     * @param {object} [options] - Query and paging options.
+     * @param {string} [options.query] - Gmail search query (`q` parameter).
+     * @param {number} [options.maxResults] - Page size; defaults to `25`.
+     * @param {string} [options.pageToken] - The `nextPageToken` from the previous page.
+     * @param {string[]} [options.labelIds] - Label IDs the messages must carry.
+     * @returns {Promise<GmailListResult>} One page of message references with the next page token when more pages exist.
+     * @throws {InternalError} When no token is configured.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When Gmail answers with HTTP 409.
+     * @throws {BadRequestError} When Gmail answers with any other HTTP error status (e.g. invalid query).
+     * @example
+     * ```ts
+     * let pageToken: string | undefined;
+     * do {
+     *   const page = await gmail.listMessages({
+     *     query: "is:unread",
+     *     maxResults: 100,
+     *     pageToken,
+     *   });
+     *   console.log(page.messages);
+     *   pageToken = page.nextPageToken;
+     * } while (pageToken);
+     * ```
+     */
+    async listMessages(options = {}) {
+        this.requireToken();
+        try {
+            const response = await this.client.get(`${this.userPath()}/messages`, {
+                params: {
+                    q: options.query,
+                    maxResults: options.maxResults ?? 25,
+                    pageToken: options.pageToken,
+                    labelIds: options.labelIds,
+                },
+            });
+            return {
+                messages: response.data.messages ?? [],
+                nextPageToken: response.data.nextPageToken,
+                resultSizeEstimate: response.data.resultSizeEstimate,
+            };
+        }
+        catch (error) {
+            throw httpError("Gmail", "list messages", error);
+        }
+    }
+    /**
+     * @description Fetches a single Gmail message
+     * @summary `GET`s `users.messages.get` for the given message ID with the
+     * requested `format`. With `"full"` (the default) the payload includes the
+     * parsed body parts; `"metadata"` limits it to headers and labels,
+     * `"minimal"` to identifiers only, and `"raw"` returns the raw MIME string.
+     * @param {string} id - The Gmail message ID.
+     * @param {"full" | "metadata" | "minimal" | "raw"} [format] - The message format to request; defaults to `"full"`.
+     * @returns {Promise<Record<string, unknown>>} The raw Gmail message payload in the requested format.
+     * @throws {InternalError} When no token is configured or the message ID is empty.
+     * @throws {NotFoundError} When the message does not exist (HTTP 404).
+     * @throws {ConflictError} When Gmail answers with HTTP 409.
+     * @throws {BadRequestError} When Gmail answers with any other HTTP error status.
+     */
+    async getMessage(id, format = "full") {
+        this.requireToken();
+        if (!id)
+            throw new InternalError("Gmail getMessage requires a message ID");
+        try {
+            const response = await this.client.get(`${this.userPath()}/messages/${encodeURIComponent(id)}`, { params: { format } });
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Gmail", "get message", error);
+        }
+    }
+    /**
+     * @description Lists the mailbox's Gmail labels
+     * @summary `GET`s `users.labels.list` and returns the raw label payloads
+     * (including `id`, `name`, and `type`).
+     * @returns {Promise<Array<Record<string, unknown>>>} The raw Gmail label payloads.
+     * @throws {InternalError} When no token is configured.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When Gmail answers with HTTP 409.
+     * @throws {BadRequestError} When Gmail answers with any other HTTP error status.
+     */
+    async listLabels() {
+        this.requireToken();
+        try {
+            const response = await this.client.get(`${this.userPath()}/labels`);
+            return response.data.labels ?? [];
+        }
+        catch (error) {
+            throw httpError("Gmail", "list labels", error);
+        }
+    }
+}
+//# sourceMappingURL=GmailService.js.map

package/lib/esm/comms/gmail/GmailService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GmailService.js","sourceRoot":"","sources":["../../../../src/comms/gmail/GmailService.ts"],"names":[],"mappings":"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"}

package/lib/esm/comms/gmail/index.js

@@ -0,0 +1,7 @@
+/**
+ * @module integrations/comms/gmail
+ * @summary Gmail service (REST v1 message send/list/get and label listing).
+ * @description Re-exports the Gmail client-based service and its types.
+ */
+export * from "./GmailService.js";
+//# sourceMappingURL=index.js.map

package/lib/esm/comms/gmail/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/comms/gmail/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,kCAA+B"}

package/lib/esm/comms/index.js

@@ -0,0 +1,17 @@
+/**
+ * @module integrations/comms
+ * @summary Comms integration services (Slack, Telegram, Teams, Gmail, Email).
+ * @description Re-exports the messaging/email services, their per-service
+ * modules, and the shared `comms` environment slice. Each sub-module is also
+ * available through its own package subpath export.
+ */
+export * from "./email/index.js";
+export * from "./gmail/index.js";
+export * from "./slack/index.js";
+export * from "./teams/index.js";
+export * from "./telegram/index.js";
+export * from "./discord/index.js";
+export * from "./whatsapp/index.js";
+export * from "./outlook/index.js";
+export * from "./environment.js";
+//# sourceMappingURL=index.js.map

package/lib/esm/comms/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/comms/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,iCAAwB;AACxB,iCAAwB;AACxB,iCAAwB;AACxB,iCAAwB;AACxB,oCAA2B;AAC3B,mCAA0B;AAC1B,oCAA2B;AAC3B,mCAA0B;AAC1B,iCAA8B"}

package/lib/esm/comms/outlook/MicrosoftOutlookService.js

@@ -0,0 +1,320 @@
+/**
+ * @module integrations/comms/outlook/service
+ * @summary Microsoft Outlook mail and calendar integration service (Microsoft Graph).
+ * @description Exposes Outlook mail (`sendMail`, `listMessages`, `getMessage`)
+ * and calendar (`listEvents`, `createEvent`, `deleteEvent`) operations through
+ * Microsoft Graph `v1.0` as an undecorated client-based service built on
+ * {@link HttpApiService}. Configuration comes from an explicit
+ * `OutlookServiceConfig` or the `comms.outlook` environment slice; the access
+ * token is sent as `Authorization: Bearer <token>`. Credentials are referenced
+ * from configuration (and, from as-graph nodes, from the resolved
+ * `microsoft-outlook` credential secret) and are never embedded in source.
+ * Failures are mapped to decaf errors via {@link httpError}.
+ */
+import { InternalError } from "@decaf-ts/db-decorators";
+import { CommsEnvironment } from "./../environment.js";
+import { envNumber, envString } from "./../../shared/environmentValue.js";
+import { HttpApiService, httpError, } from "./../../shared/http/index.js";
+/**
+ * @description Normalizes Outlook recipient addresses into Graph recipients
+ * @summary Accepts a single address, an array, or a comma/semicolon-separated
+ * string, trims entries, drops blanks, and maps each address to the Graph
+ * `{ emailAddress: { address } }` envelope.
+ * @param {string | string[] | undefined} value - The raw recipient value.
+ * @returns {Array<{ emailAddress: { address: string } }>} The Graph recipient envelopes.
+ */
+function recipientList(value) {
+    if (!value)
+        return [];
+    const values = Array.isArray(value)
+        ? value
+        : value.split(/[,;]/).map((entry) => entry.trim());
+    return values
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0)
+        .map((address) => ({ emailAddress: { address } }));
+}
+/**
+ * @description Microsoft Outlook (Graph) mail and calendar integration service
+ * @summary An undecorated HTTP service for sending and reading mail and for
+ * listing, creating, and deleting calendar events on the signed-in user
+ * (`/me`). Every operation requires a Graph access token; missing credentials
+ * or identifiers raise `InternalError`, and transport failures are mapped to
+ * decaf errors via {@link httpError}.
+ * @class MicrosoftOutlookService
+ * @extends HttpApiService
+ * @category Comms
+ * @example
+ * ```ts
+ * import { MicrosoftOutlookService } from "@decaf-ts/integrations/comms/outlook";
+ *
+ * const outlook = new MicrosoftOutlookService();
+ * await outlook.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_MICROSOFT_OUTLOOK_TOKEN,
+ * });
+ * await outlook.sendMail({
+ *   to: "team@example.com",
+ *   subject: "Deployment finished",
+ *   body: "Release 1.2.0 is live",
+ * });
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Service as MicrosoftOutlookService
+ *   participant Graph as Microsoft Graph
+ *   Caller->>Service: sendMail(input)
+ *   activate Service
+ *   Service->>Service: requireAccessToken()
+ *   Service->>Graph: POST /me/sendMail
+ *   activate Graph
+ *   Graph-->>Service: 202 Accepted
+ *   deactivate Graph
+ *   Service-->>Caller: { sent, to, subject }
+ *   deactivate Service
+ * @memberOf module:integrations/comms/outlook/service
+ */
+export class MicrosoftOutlookService extends HttpApiService {
+    constructor() {
+        super(...arguments);
+        /**
+         * @description The provider name used in error messages
+         */
+        this.serviceName = "Microsoft Outlook";
+    }
+    /**
+     * @description The Microsoft Graph base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://graph.microsoft.com/v1.0"`.
+     */
+    defaultBaseUrl() {
+        return "https://graph.microsoft.com/v1.0";
+    }
+    /**
+     * @description Builds the Microsoft Graph bearer authorization headers
+     * @summary Returns `Authorization: Bearer <token>` when configured, and no
+     * headers otherwise.
+     * @param {OutlookServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token).
+     */
+    authHeaders(config) {
+        return config.token ? { Authorization: `Bearer ${config.token}` } : {};
+    }
+    /**
+     * @description Reads the Outlook credentials and defaults from the environment
+     * @summary Reads the `comms.outlook` slice and returns a partial config when
+     * an access token is configured, `undefined` otherwise. Values pass through
+     * `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<OutlookServiceConfig> | undefined} A partial config, or `undefined` when no Outlook token is configured.
+     */
+    configFromEnvironment() {
+        const env = CommsEnvironment.comms.outlook;
+        const token = envString(env?.token);
+        if (!token)
+            return undefined;
+        return {
+            token,
+            baseUrl: envString(env.baseUrl),
+            timeout: envNumber(env.timeout),
+        };
+    }
+    /**
+     * @description Asserts that a Microsoft Graph access token is configured
+     * @summary Delegates to the shared `requireToken()` guard used by every
+     * operation.
+     * @returns {void}
+     * @throws {InternalError} When the resolved config has no `token`.
+     */
+    requireAccessToken() {
+        this.requireToken();
+    }
+    /**
+     * @description Sends a mail message through Outlook
+     * @summary `POST`s the message to `/me/sendMail`; recipients are normalized
+     * to Graph envelopes and `saveToSentItems` defaults to `true`.
+     * @param {OutlookMailInput} input - The recipients, subject, body, and content options.
+     * @returns {Promise<unknown>} `{ sent: true, to, subject }` on success.
+     * @throws {InternalError} When no token is configured, or recipients or subject are missing.
+     * @throws {BadRequestError} When Graph rejects the request.
+     * @example
+     * ```ts
+     * await outlook.sendMail({
+     *   to: ["a@example.com", "b@example.com"],
+     *   subject: "Status",
+     *   body: "All systems operational",
+     *   contentType: "Text",
+     * });
+     * ```
+     */
+    async sendMail(input) {
+        this.requireAccessToken();
+        if (!input.to || !input.subject) {
+            throw new InternalError("Microsoft Outlook sendMail requires recipients and a subject");
+        }
+        try {
+            await this.client.post("/me/sendMail", {
+                message: {
+                    subject: input.subject,
+                    body: {
+                        contentType: input.contentType ?? "Text",
+                        content: input.body ?? "",
+                    },
+                    toRecipients: recipientList(input.to),
+                    ...(input.cc ? { ccRecipients: recipientList(input.cc) } : {}),
+                    ...(input.bcc ? { bccRecipients: recipientList(input.bcc) } : {}),
+                },
+                saveToSentItems: input.saveToSentItems ?? true,
+            });
+            return { sent: true, to: input.to, subject: input.subject };
+        }
+        catch (error) {
+            throw httpError("Microsoft Outlook", "send mail", error);
+        }
+    }
+    /**
+     * @description Lists messages in an Outlook mail folder
+     * @summary `GET`s `/me/mailFolders/<folder>/messages` (default `inbox`)
+     * applying the optional `$top`, `$filter`, and `$search` parameters.
+     * @param {OutlookListInput} [input] - The folder and OData query options.
+     * @returns {Promise<unknown>} The Graph message collection.
+     * @throws {InternalError} When no token is configured.
+     * @throws {NotFoundError} When the folder does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the query.
+     */
+    async listMessages(input = {}) {
+        this.requireAccessToken();
+        const folder = input.folderId ?? "inbox";
+        try {
+            const response = await this.client.get(`/me/mailFolders/${encodeURIComponent(folder)}/messages`, {
+                params: {
+                    ...(input.top !== undefined ? { $top: input.top } : {}),
+                    ...(input.filter ? { $filter: input.filter } : {}),
+                    ...(input.search ? { $search: input.search } : {}),
+                },
+            });
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Microsoft Outlook", "list messages", error);
+        }
+    }
+    /**
+     * @description Fetches a single Outlook message
+     * @summary `GET`s `/me/messages/<id>` and returns the message payload.
+     * @param {string} messageId - The Graph message ID.
+     * @returns {Promise<unknown>} The message payload.
+     * @throws {InternalError} When no token is configured or the message ID is empty.
+     * @throws {NotFoundError} When the message does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    async getMessage(messageId) {
+        this.requireAccessToken();
+        if (!messageId) {
+            throw new InternalError("Microsoft Outlook requires a message id");
+        }
+        try {
+            const response = await this.client.get(`/me/messages/${encodeURIComponent(messageId)}`);
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Microsoft Outlook", "get message", error);
+        }
+    }
+    /**
+     * @description Lists Outlook calendar events
+     * @summary `GET`s `/me/events` applying the optional `$top`, `$filter`, and
+     * `$search` parameters; the mail `folderId` is not used.
+     * @param {OutlookListInput} [input] - The OData query options.
+     * @returns {Promise<unknown>} The Graph event collection.
+     * @throws {InternalError} When no token is configured.
+     * @throws {BadRequestError} When Graph rejects the query.
+     */
+    async listEvents(input = {}) {
+        this.requireAccessToken();
+        try {
+            const response = await this.client.get("/me/events", {
+                params: {
+                    ...(input.top !== undefined ? { $top: input.top } : {}),
+                    ...(input.filter ? { $filter: input.filter } : {}),
+                    ...(input.search ? { $search: input.search } : {}),
+                },
+            });
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Microsoft Outlook", "list events", error);
+        }
+    }
+    /**
+     * @description Creates an Outlook calendar event
+     * @summary `POST`s the event to `/me/events`; `start`/`end` are sent with the
+     * configured or default (`UTC`) time zone and attendees as required.
+     * @param {OutlookEventInput} input - The event definition.
+     * @returns {Promise<unknown>} The created Graph event.
+     * @throws {InternalError} When no token is configured, or subject, start, or end is missing.
+     * @throws {BadRequestError} When Graph rejects the event.
+     * @example
+     * ```ts
+     * await outlook.createEvent({
+     *   subject: "Release review",
+     *   start: "2026-11-01T09:00:00",
+     *   end: "2026-11-01T10:00:00",
+     *   timeZone: "Europe/Lisbon",
+     * });
+     * ```
+     */
+    async createEvent(input) {
+        this.requireAccessToken();
+        if (!input.subject || !input.start || !input.end) {
+            throw new InternalError("Microsoft Outlook createEvent requires subject, start, and end");
+        }
+        const timeZone = input.timeZone ?? "UTC";
+        try {
+            const response = await this.client.post("/me/events", {
+                subject: input.subject,
+                ...(input.body
+                    ? { body: { contentType: "Text", content: input.body } }
+                    : {}),
+                start: { dateTime: input.start, timeZone },
+                end: { dateTime: input.end, timeZone },
+                ...(input.location ? { location: { displayName: input.location } } : {}),
+                ...(input.attendees
+                    ? {
+                        attendees: recipientList(input.attendees).map((entry) => ({
+                            emailAddress: entry.emailAddress,
+                            type: "required",
+                        })),
+                    }
+                    : {}),
+            });
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Microsoft Outlook", "create event", error);
+        }
+    }
+    /**
+     * @description Deletes an Outlook calendar event
+     * @summary `DELETE`s `/me/events/<id>` and returns `{ deleted: true, eventId }`.
+     * @param {string} eventId - The Graph event ID.
+     * @returns {Promise<unknown>} `{ deleted: true, eventId }` on success.
+     * @throws {InternalError} When no token is configured or the event ID is empty.
+     * @throws {NotFoundError} When the event does not exist (HTTP 404).
+     * @throws {BadRequestError} When Graph rejects the request.
+     */
+    async deleteEvent(eventId) {
+        this.requireAccessToken();
+        if (!eventId) {
+            throw new InternalError("Microsoft Outlook requires an event id");
+        }
+        try {
+            await this.client.delete(`/me/events/${encodeURIComponent(eventId)}`);
+            return { deleted: true, eventId };
+        }
+        catch (error) {
+            throw httpError("Microsoft Outlook", "delete event", error);
+        }
+    }
+}
+//# sourceMappingURL=MicrosoftOutlookService.js.map

package/lib/esm/comms/outlook/MicrosoftOutlookService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MicrosoftOutlookService.js","sourceRoot":"","sources":["../../../../src/comms/outlook/MicrosoftOutlookService.ts"],"names":[],"mappings":"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"}

package/lib/esm/comms/outlook/index.js

@@ -0,0 +1,2 @@
+export * from "./MicrosoftOutlookService.js";
+//# sourceMappingURL=index.js.map

package/lib/esm/comms/outlook/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/comms/outlook/index.ts"],"names":[],"mappings":"AAAA,6CAA0C"}