@decaf-ts/integrations 0.11.0 → 0.14.0

package/lib/types/blob/s3/S3CompatibleBlobStoreService.d.cts

@@ -3,10 +3,9 @@
  * @summary S3-compatible blob store base implementation.
  * @description Shared CRUD implementation backed by the AWS SDK v3 S3Client, used by
  * the S3, MinIO, and Cloudflare R2 provider services. Deliberately left undecorated:
- * `@service(...)` on a class whose parent is itself `@service(...)`-decorated breaks
- * that subclass's inherited field initializers (e.g. `Context` ends up `undefined`).
- * Each concrete provider below extends this class directly and carries its own
- * `@service("blob-<provider>")` decorator instead of stacking on top of one another.
+ * concrete providers are plain classes that consumers construct and boot
+ * explicitly (no injectable registration, no `Service.boot` auto-boot), and
+ * each extends this base directly instead of stacking on top of one another.
  */
 import { S3Client } from "@aws-sdk/client-s3";
 import { type ContextualArgs, type MaybeContextualArg } from "@decaf-ts/core";
@@ -16,12 +15,9 @@ import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListR
  * @description Base implementation for S3-compatible blob stores
  * @summary Implements the full blob CRUD API on top of the AWS SDK v3
  * `S3Client` and is shared by the S3, MinIO, and Cloudflare R2 provider
- * services. Deliberately left undecorated: `@service(...)` on a class whose
- * parent is itself `@service(...)`-decorated breaks that subclass's inherited
- * field initializers (e.g. `Context` ends up `undefined`). Each concrete
- * provider extends this class directly and carries its own
- * `@service("blob-<provider>")` decorator instead of stacking on top of one
- * another.
+ * services. Deliberately left undecorated: concrete providers are plain
+ * classes that consumers construct and boot explicitly, so no injectable
+ * registration or `Service.boot` auto-boot applies here.
  * @class S3CompatibleBlobStoreService
  * @memberOf module:integrations/blob/s3/base-service
  */
@@ -29,11 +25,11 @@ export declare abstract class S3CompatibleBlobStoreService extends BlobStoreServ
     /**
      * @description Initializes the S3 client from config or environment
      * @summary Resolves the config via `getConfigFromArgs` (explicit config,
-     * then the provider's environment slice). When no config resolves during a
-     * context-bearing auto-boot of an unconfigured provider (e.g. an optional
-     * `blob-minio`/`blob-r2` registered alongside `blob-s3`), returns
-     * `skipInitialization()` so `Service.boot` does not throw; an explicit
-     * `initialize()` with no resolvable config still throws a
+     * then the provider's environment slice). When no config resolves and the
+     * arguments carry a decaf `Context` (e.g. an unconfigured optional
+     * `blob-minio`/`blob-r2` provider next to `blob-s3`), returns
+     * `skipInitialization()` so the context-bearing boot does not throw; an
+     * explicit `initialize()` with no resolvable config still throws a
      * `ValidationError`. Requires a `bucket`, builds the `S3Client` (with
      * optional static credentials), stores config and client, and optionally
      * creates the bucket when `autoCreateBucket` is set.

package/lib/types/blob/s3/S3CompatibleBlobStoreService.d.mts

@@ -3,10 +3,9 @@
  * @summary S3-compatible blob store base implementation.
  * @description Shared CRUD implementation backed by the AWS SDK v3 S3Client, used by
  * the S3, MinIO, and Cloudflare R2 provider services. Deliberately left undecorated:
- * `@service(...)` on a class whose parent is itself `@service(...)`-decorated breaks
- * that subclass's inherited field initializers (e.g. `Context` ends up `undefined`).
- * Each concrete provider below extends this class directly and carries its own
- * `@service("blob-<provider>")` decorator instead of stacking on top of one another.
+ * concrete providers are plain classes that consumers construct and boot
+ * explicitly (no injectable registration, no `Service.boot` auto-boot), and
+ * each extends this base directly instead of stacking on top of one another.
  */
 import { S3Client } from "@aws-sdk/client-s3";
 import { type ContextualArgs, type MaybeContextualArg } from "@decaf-ts/core";
@@ -16,12 +15,9 @@ import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListR
  * @description Base implementation for S3-compatible blob stores
  * @summary Implements the full blob CRUD API on top of the AWS SDK v3
  * `S3Client` and is shared by the S3, MinIO, and Cloudflare R2 provider
- * services. Deliberately left undecorated: `@service(...)` on a class whose
- * parent is itself `@service(...)`-decorated breaks that subclass's inherited
- * field initializers (e.g. `Context` ends up `undefined`). Each concrete
- * provider extends this class directly and carries its own
- * `@service("blob-<provider>")` decorator instead of stacking on top of one
- * another.
+ * services. Deliberately left undecorated: concrete providers are plain
+ * classes that consumers construct and boot explicitly, so no injectable
+ * registration or `Service.boot` auto-boot applies here.
  * @class S3CompatibleBlobStoreService
  * @memberOf module:integrations/blob/s3/base-service
  */
@@ -29,11 +25,11 @@ export declare abstract class S3CompatibleBlobStoreService extends BlobStoreServ
     /**
      * @description Initializes the S3 client from config or environment
      * @summary Resolves the config via `getConfigFromArgs` (explicit config,
-     * then the provider's environment slice). When no config resolves during a
-     * context-bearing auto-boot of an unconfigured provider (e.g. an optional
-     * `blob-minio`/`blob-r2` registered alongside `blob-s3`), returns
-     * `skipInitialization()` so `Service.boot` does not throw; an explicit
-     * `initialize()` with no resolvable config still throws a
+     * then the provider's environment slice). When no config resolves and the
+     * arguments carry a decaf `Context` (e.g. an unconfigured optional
+     * `blob-minio`/`blob-r2` provider next to `blob-s3`), returns
+     * `skipInitialization()` so the context-bearing boot does not throw; an
+     * explicit `initialize()` with no resolvable config still throws a
      * `ValidationError`. Requires a `bucket`, builds the `S3Client` (with
      * optional static credentials), stores config and client, and optionally
      * creates the bucket when `autoCreateBucket` is set.

package/lib/types/calendar/environment.d.cts

@@ -0,0 +1,48 @@
+/**
+ * @description Environment shape for the calendar integration services
+ * @summary Defines the `calendar` root with the `googleCalendar` slice. The
+ * slice carries the OAuth `token` and/or `apiKey`, the default `calendarId`,
+ * and an optional `baseUrl` override and `timeout`. Fields are typed as
+ * required here so `LoggedEnvironment.accumulate` registers them; absent values
+ * resolve to proxy placeholders at runtime and must pass through
+ * `envString`/`envNumber`. Values are credential references supplied by the
+ * environment, never literals embedded in source.
+ * @memberOf module:integrations/calendar/environment
+ */
+export interface CalendarEnvironmentShape {
+    calendar: {
+        /** Google Calendar OAuth token/API key and default calendar (`calendar/google-calendar`). */
+        googleCalendar: {
+            token: string;
+            apiKey: string;
+            calendarId: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+    };
+}
+/**
+ * @description Accumulated calendar environment singleton
+ * @summary The `LoggedEnvironment.accumulate`-registered instance backing the
+ * `CalendarEnvironmentShape` contract. The Google Calendar service reads
+ * `CalendarEnvironment.calendar.googleCalendar` inside
+ * `configFromEnvironment()` and translates it into its
+ * `HttpApiServiceConfig`-derived config. Credentials come from environment
+ * variables; for as-graph node usage those are provided as
+ * `GRAPH_CREDENTIAL_*` values (placeholders in this example).
+ * @example
+ * ```ts
+ * import { GoogleCalendarService } from "@decaf-ts/integrations/calendar/google-calendar";
+ *
+ * // with calendar.googleCalendar.token / calendarId configured in the environment
+ * const calendar = new GoogleCalendarService();
+ * await calendar.initialize();
+ * ```
+ * @constant {LoggedEnvironment} CalendarEnvironment
+ * @memberOf module:integrations/calendar/environment
+ */
+export declare const CalendarEnvironment: import("@decaf-ts/logging").AccumulatedEnvironment<{
+    app: string | undefined;
+} & import("@decaf-ts/logging").LoggingConfig<object> & {
+    env: any;
+} & CalendarEnvironmentShape>;

package/lib/types/calendar/environment.d.mts

@@ -0,0 +1,48 @@
+/**
+ * @description Environment shape for the calendar integration services
+ * @summary Defines the `calendar` root with the `googleCalendar` slice. The
+ * slice carries the OAuth `token` and/or `apiKey`, the default `calendarId`,
+ * and an optional `baseUrl` override and `timeout`. Fields are typed as
+ * required here so `LoggedEnvironment.accumulate` registers them; absent values
+ * resolve to proxy placeholders at runtime and must pass through
+ * `envString`/`envNumber`. Values are credential references supplied by the
+ * environment, never literals embedded in source.
+ * @memberOf module:integrations/calendar/environment
+ */
+export interface CalendarEnvironmentShape {
+    calendar: {
+        /** Google Calendar OAuth token/API key and default calendar (`calendar/google-calendar`). */
+        googleCalendar: {
+            token: string;
+            apiKey: string;
+            calendarId: string;
+            baseUrl: string;
+            timeout?: number;
+        };
+    };
+}
+/**
+ * @description Accumulated calendar environment singleton
+ * @summary The `LoggedEnvironment.accumulate`-registered instance backing the
+ * `CalendarEnvironmentShape` contract. The Google Calendar service reads
+ * `CalendarEnvironment.calendar.googleCalendar` inside
+ * `configFromEnvironment()` and translates it into its
+ * `HttpApiServiceConfig`-derived config. Credentials come from environment
+ * variables; for as-graph node usage those are provided as
+ * `GRAPH_CREDENTIAL_*` values (placeholders in this example).
+ * @example
+ * ```ts
+ * import { GoogleCalendarService } from "@decaf-ts/integrations/calendar/google-calendar";
+ *
+ * // with calendar.googleCalendar.token / calendarId configured in the environment
+ * const calendar = new GoogleCalendarService();
+ * await calendar.initialize();
+ * ```
+ * @constant {LoggedEnvironment} CalendarEnvironment
+ * @memberOf module:integrations/calendar/environment
+ */
+export declare const CalendarEnvironment: import("@decaf-ts/logging").AccumulatedEnvironment<{
+    app: string | undefined;
+} & import("@decaf-ts/logging").LoggingConfig<object> & {
+    env: any;
+} & CalendarEnvironmentShape>;

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

@@ -0,0 +1,316 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.cts";
+/**
+ * @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>;
+}