@decaf-ts/integrations 0.11.0 → 0.14.0

package/lib/types/shared/http/HttpApiService.d.cts

@@ -0,0 +1,193 @@
+import { type AxiosInstance } from "axios";
+import { ClientBasedService, MaybeContextualArg } from "@decaf-ts/core";
+/**
+ * @module integrations/shared/http/base-service
+ * @summary Shared HTTP base service, config contract, and error mapping for the HTTP-backed integration services.
+ * @description Provides the `HttpApiServiceConfig` shape consumed by every Stage 3b HTTP-backed
+ * integration service (Slack, Telegram, Teams, Gmail, GitHub, GitLab, Google Sheets, Airtable, and
+ * GraphQL), the abstract `HttpApiService` client-based service that turns a config into a
+ * configured Axios instance, and the `httpError` mapper that converts transport failures into
+ * decaf `BadRequestError`/`ConflictError`/`NotFoundError`/`InternalError` errors. Concrete
+ * services extend `HttpApiService` and only supply their base URL, auth headers, and environment
+ * slice, inheriting initialization and error mapping.
+ */
+/**
+ * @description Base configuration shared by every HTTP-backed integration service
+ * @summary Carries the optional `baseUrl` override (falling back to the service's
+ * `defaultBaseUrl()`), credentials (`token`, or `username`/`password` for basic-auth
+ * style APIs), an Axios `timeout` in milliseconds (defaults to `30000`), and any
+ * extra default `headers` merged after the service's own `authHeaders`. Concrete
+ * services extend this interface with their provider-specific fields.
+ * @category Shared
+ * @memberOf module:integrations/shared/http/base-service
+ */
+export interface HttpApiServiceConfig {
+    /**
+     * @description Base URL override for the service client
+     * @summary When omitted, the concrete service's `defaultBaseUrl()` is used.
+     */
+    baseUrl?: string;
+    /**
+     * @description Bearer or provider token used for authentication
+     * @summary How the token is sent (header name, scheme, or query parameter) is
+     * decided by each concrete service's `authHeaders()` implementation.
+     */
+    token?: string;
+    /**
+     * @description Optional username for basic-auth style APIs
+     * @summary Used together with {@link HttpApiServiceConfig.password} by services
+     * that authenticate with HTTP basic credentials.
+     */
+    username?: string;
+    /**
+     * @description Optional password for basic-auth style APIs
+     * @summary Used together with {@link HttpApiServiceConfig.username}.
+     */
+    password?: string;
+    /**
+     * @description Request timeout in milliseconds
+     * @summary Applied to the Axios instance created by
+     * {@link HttpApiService.initialize}; defaults to `30000` when omitted.
+     */
+    timeout?: number;
+    /**
+     * @description Extra default headers merged into every request
+     * @summary Merged after the service's own `authHeaders()`, so explicit
+     * `headers` entries take precedence over generated auth headers.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * @description Maps a transport or provider failure to a decaf error
+ * @summary Normalizes `unknown` caught errors into the decaf error hierarchy.
+ * Already-mapped decaf errors are returned unchanged; errors carrying an HTTP
+ * response are mapped by status (`404` to `NotFoundError`, `409` to
+ * `ConflictError`, everything else to `BadRequestError` with the response body
+ * as detail); any other failure becomes an `InternalError` carrying the
+ * original message. Concrete services wrap their API calls with this mapper so
+ * callers only ever observe decaf errors.
+ * @param {string} serviceName - Human-readable provider name used to prefix the error message (e.g. `"Slack"`).
+ * @param {string} action - Short description of the failing operation (e.g. `"API chat.postMessage"`).
+ * @param {unknown} error - The caught error: a decaf error, an Axios-style error with an HTTP `response`, or anything else.
+ * @returns {Error} The corresponding decaf error: the input unchanged when already a decaf error, a status-mapped `NotFoundError`/`ConflictError`/`BadRequestError` when an HTTP response is present, or an `InternalError` otherwise.
+ * @category Shared
+ * @memberOf module:integrations/shared/http/base-service
+ */
+export declare function httpError(serviceName: string, action: string, error: unknown): Error;
+/**
+ * @description Abstract base service for HTTP-backed provider integrations
+ * @summary Implements the shared `ClientBasedService` lifecycle for REST-style
+ * providers: `initialize()` merges an explicitly provided config with the
+ * concrete service's environment slice, resolves the effective base URL
+ * (explicit `baseUrl`, then `defaultBaseUrl()`), and builds an `AxiosInstance`
+ * with the JSON content type, the service's `authHeaders()`, and any extra
+ * config `headers`. Subclasses declare their `serviceName`, supply a
+ * `defaultBaseUrl()`, optionally override `authHeaders()` and
+ * `configFromEnvironment()`, and use `requireToken()` in operations that
+ * mandate a token. Callers always pass a concrete config object (or rely on
+ * the environment slice) and receive typed decaf errors through
+ * {@link httpError}.
+ * @class HttpApiService
+ * @category Shared
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Service as HttpApiService
+ *   participant Env as Environment slice
+ *   participant Axios as Axios
+ *   Caller->>Service: initialize(providedConfig?)
+ *   activate Service
+ *   Service->>Env: configFromEnvironment()
+ *   activate Env
+ *   Env-->>Service: partial config (or undefined)
+ *   deactivate Env
+ *   Service->>Service: merge { ...environment, ...provided }
+ *   alt baseUrl configured
+ *     Service->>Service: baseUrl = config.baseUrl
+ *   else baseUrl missing
+ *     Service->>Service: baseUrl = defaultBaseUrl()
+ *     alt still missing
+ *       Service--xCaller: InternalError (requires a base URL)
+ *     end
+ *   end
+ *   Service->>Axios: create({ baseURL, timeout, headers })
+ *   activate Axios
+ *   Axios-->>Service: AxiosInstance
+ *   deactivate Axios
+ *   Service-->>Caller: { config, client }
+ *   deactivate Service
+ * @example
+ * ```ts
+ * import { SlackService } from "@decaf-ts/integrations/comms/slack";
+ *
+ * const slack = new SlackService();
+ * // explicit config; when omitted, initialize() falls back to the
+ * // service's environment slice (e.g. GRAPH_CREDENTIAL_SLACK_TOKEN)
+ * await slack.initialize({ token: process.env.GRAPH_CREDENTIAL_SLACK_TOKEN });
+ * ```
+ * @memberOf module:integrations/shared/http/base-service
+ */
+export declare abstract class HttpApiService<CONF extends HttpApiServiceConfig> extends ClientBasedService<AxiosInstance, CONF> {
+    constructor();
+    /**
+     * @description Human-readable provider name used in error messages
+     * @summary Subclasses must declare this (e.g. `"Slack"`, `"GitHub"`); it
+     * prefixes messages thrown for missing base URLs, tokens, and mapped errors.
+     */
+    protected abstract readonly serviceName: string;
+    /**
+     * @description The provider's default API base URL
+     * @summary Used by {@link HttpApiService.initialize} when the resolved
+     * config carries no `baseUrl`.
+     * @returns {string} The provider's default base URL (e.g. `"https://api.github.com"`).
+     */
+    protected abstract defaultBaseUrl(): string;
+    /**
+     * @description Builds the default authentication headers for a config
+     * @summary Invoked by {@link HttpApiService.initialize} when creating the
+     * Axios instance. The base implementation returns no headers; subclasses
+     * override it to translate `config.token`/`username`/`password` into
+     * provider-specific headers (e.g. `Authorization: Bearer ...`).
+     * @param {CONF} config - The resolved service configuration.
+     * @returns {Record<string, string>} The headers to send with every request; empty when the config carries no credentials.
+     */
+    protected authHeaders(_config: CONF): Record<string, string>;
+    /**
+     * @description Reads the service's credentials and defaults from the environment
+     * @summary Invoked by {@link HttpApiService.initialize} and merged under the
+     * explicitly provided config (explicit values win). Subclasses override this
+     * to read their `LoggedEnvironment` slice with the
+     * `envString`/`envNumber`/`envBoolean` helpers and return `undefined` when
+     * the slice is not configured at all.
+     * @returns {Partial<CONF> | undefined} A partial config from the environment, or `undefined` when the environment carries no usable credentials.
+     */
+    protected configFromEnvironment(): Partial<CONF> | undefined;
+    /**
+     * @description Resolves the config and builds the Axios client
+     * @summary Merges the explicitly provided config (first argument, when
+     * present) over the environment slice from `configFromEnvironment()`,
+     * resolves the effective base URL (explicit `baseUrl`, then
+     * `defaultBaseUrl()`), and creates an Axios instance with the resolved
+     * `timeout` (default `30000`), JSON content type, `authHeaders(config)`,
+     * and any extra config `headers`. The resolved config and client are also
+     * stored on the service for subsequent operations.
+     * @param {...MaybeContextualArg<any>} args - An optional `Partial<CONF>`, optionally followed by a decaf `Context`.
+     * @returns {Promise<{config: CONF, client: AxiosInstance}>} The merged configuration and the configured Axios instance.
+     * @throws {InternalError} When neither the config nor `defaultBaseUrl()` yields a base URL.
+     */
+    initialize(...args: MaybeContextualArg<any>): Promise<{
+        config: CONF;
+        client: AxiosInstance;
+    }>;
+    /**
+     * @description Asserts that the service was configured with a token
+     * @summary Reads the resolved config and throws when no `token` is present;
+     * operations that require authenticated access call this before issuing
+     * requests.
+     * @param {CONF} [config] - The config to validate; defaults to the service's resolved config.
+     * @returns {string} The configured token.
+     * @throws {InternalError} When the config carries no `token`.
+     */
+    protected requireToken(config?: CONF): string;
+}

package/lib/types/shared/http/HttpApiService.d.mts

@@ -0,0 +1,193 @@
+import { type AxiosInstance } from "axios";
+import { ClientBasedService, MaybeContextualArg } from "@decaf-ts/core";
+/**
+ * @module integrations/shared/http/base-service
+ * @summary Shared HTTP base service, config contract, and error mapping for the HTTP-backed integration services.
+ * @description Provides the `HttpApiServiceConfig` shape consumed by every Stage 3b HTTP-backed
+ * integration service (Slack, Telegram, Teams, Gmail, GitHub, GitLab, Google Sheets, Airtable, and
+ * GraphQL), the abstract `HttpApiService` client-based service that turns a config into a
+ * configured Axios instance, and the `httpError` mapper that converts transport failures into
+ * decaf `BadRequestError`/`ConflictError`/`NotFoundError`/`InternalError` errors. Concrete
+ * services extend `HttpApiService` and only supply their base URL, auth headers, and environment
+ * slice, inheriting initialization and error mapping.
+ */
+/**
+ * @description Base configuration shared by every HTTP-backed integration service
+ * @summary Carries the optional `baseUrl` override (falling back to the service's
+ * `defaultBaseUrl()`), credentials (`token`, or `username`/`password` for basic-auth
+ * style APIs), an Axios `timeout` in milliseconds (defaults to `30000`), and any
+ * extra default `headers` merged after the service's own `authHeaders`. Concrete
+ * services extend this interface with their provider-specific fields.
+ * @category Shared
+ * @memberOf module:integrations/shared/http/base-service
+ */
+export interface HttpApiServiceConfig {
+    /**
+     * @description Base URL override for the service client
+     * @summary When omitted, the concrete service's `defaultBaseUrl()` is used.
+     */
+    baseUrl?: string;
+    /**
+     * @description Bearer or provider token used for authentication
+     * @summary How the token is sent (header name, scheme, or query parameter) is
+     * decided by each concrete service's `authHeaders()` implementation.
+     */
+    token?: string;
+    /**
+     * @description Optional username for basic-auth style APIs
+     * @summary Used together with {@link HttpApiServiceConfig.password} by services
+     * that authenticate with HTTP basic credentials.
+     */
+    username?: string;
+    /**
+     * @description Optional password for basic-auth style APIs
+     * @summary Used together with {@link HttpApiServiceConfig.username}.
+     */
+    password?: string;
+    /**
+     * @description Request timeout in milliseconds
+     * @summary Applied to the Axios instance created by
+     * {@link HttpApiService.initialize}; defaults to `30000` when omitted.
+     */
+    timeout?: number;
+    /**
+     * @description Extra default headers merged into every request
+     * @summary Merged after the service's own `authHeaders()`, so explicit
+     * `headers` entries take precedence over generated auth headers.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * @description Maps a transport or provider failure to a decaf error
+ * @summary Normalizes `unknown` caught errors into the decaf error hierarchy.
+ * Already-mapped decaf errors are returned unchanged; errors carrying an HTTP
+ * response are mapped by status (`404` to `NotFoundError`, `409` to
+ * `ConflictError`, everything else to `BadRequestError` with the response body
+ * as detail); any other failure becomes an `InternalError` carrying the
+ * original message. Concrete services wrap their API calls with this mapper so
+ * callers only ever observe decaf errors.
+ * @param {string} serviceName - Human-readable provider name used to prefix the error message (e.g. `"Slack"`).
+ * @param {string} action - Short description of the failing operation (e.g. `"API chat.postMessage"`).
+ * @param {unknown} error - The caught error: a decaf error, an Axios-style error with an HTTP `response`, or anything else.
+ * @returns {Error} The corresponding decaf error: the input unchanged when already a decaf error, a status-mapped `NotFoundError`/`ConflictError`/`BadRequestError` when an HTTP response is present, or an `InternalError` otherwise.
+ * @category Shared
+ * @memberOf module:integrations/shared/http/base-service
+ */
+export declare function httpError(serviceName: string, action: string, error: unknown): Error;
+/**
+ * @description Abstract base service for HTTP-backed provider integrations
+ * @summary Implements the shared `ClientBasedService` lifecycle for REST-style
+ * providers: `initialize()` merges an explicitly provided config with the
+ * concrete service's environment slice, resolves the effective base URL
+ * (explicit `baseUrl`, then `defaultBaseUrl()`), and builds an `AxiosInstance`
+ * with the JSON content type, the service's `authHeaders()`, and any extra
+ * config `headers`. Subclasses declare their `serviceName`, supply a
+ * `defaultBaseUrl()`, optionally override `authHeaders()` and
+ * `configFromEnvironment()`, and use `requireToken()` in operations that
+ * mandate a token. Callers always pass a concrete config object (or rely on
+ * the environment slice) and receive typed decaf errors through
+ * {@link httpError}.
+ * @class HttpApiService
+ * @category Shared
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Service as HttpApiService
+ *   participant Env as Environment slice
+ *   participant Axios as Axios
+ *   Caller->>Service: initialize(providedConfig?)
+ *   activate Service
+ *   Service->>Env: configFromEnvironment()
+ *   activate Env
+ *   Env-->>Service: partial config (or undefined)
+ *   deactivate Env
+ *   Service->>Service: merge { ...environment, ...provided }
+ *   alt baseUrl configured
+ *     Service->>Service: baseUrl = config.baseUrl
+ *   else baseUrl missing
+ *     Service->>Service: baseUrl = defaultBaseUrl()
+ *     alt still missing
+ *       Service--xCaller: InternalError (requires a base URL)
+ *     end
+ *   end
+ *   Service->>Axios: create({ baseURL, timeout, headers })
+ *   activate Axios
+ *   Axios-->>Service: AxiosInstance
+ *   deactivate Axios
+ *   Service-->>Caller: { config, client }
+ *   deactivate Service
+ * @example
+ * ```ts
+ * import { SlackService } from "@decaf-ts/integrations/comms/slack";
+ *
+ * const slack = new SlackService();
+ * // explicit config; when omitted, initialize() falls back to the
+ * // service's environment slice (e.g. GRAPH_CREDENTIAL_SLACK_TOKEN)
+ * await slack.initialize({ token: process.env.GRAPH_CREDENTIAL_SLACK_TOKEN });
+ * ```
+ * @memberOf module:integrations/shared/http/base-service
+ */
+export declare abstract class HttpApiService<CONF extends HttpApiServiceConfig> extends ClientBasedService<AxiosInstance, CONF> {
+    constructor();
+    /**
+     * @description Human-readable provider name used in error messages
+     * @summary Subclasses must declare this (e.g. `"Slack"`, `"GitHub"`); it
+     * prefixes messages thrown for missing base URLs, tokens, and mapped errors.
+     */
+    protected abstract readonly serviceName: string;
+    /**
+     * @description The provider's default API base URL
+     * @summary Used by {@link HttpApiService.initialize} when the resolved
+     * config carries no `baseUrl`.
+     * @returns {string} The provider's default base URL (e.g. `"https://api.github.com"`).
+     */
+    protected abstract defaultBaseUrl(): string;
+    /**
+     * @description Builds the default authentication headers for a config
+     * @summary Invoked by {@link HttpApiService.initialize} when creating the
+     * Axios instance. The base implementation returns no headers; subclasses
+     * override it to translate `config.token`/`username`/`password` into
+     * provider-specific headers (e.g. `Authorization: Bearer ...`).
+     * @param {CONF} config - The resolved service configuration.
+     * @returns {Record<string, string>} The headers to send with every request; empty when the config carries no credentials.
+     */
+    protected authHeaders(_config: CONF): Record<string, string>;
+    /**
+     * @description Reads the service's credentials and defaults from the environment
+     * @summary Invoked by {@link HttpApiService.initialize} and merged under the
+     * explicitly provided config (explicit values win). Subclasses override this
+     * to read their `LoggedEnvironment` slice with the
+     * `envString`/`envNumber`/`envBoolean` helpers and return `undefined` when
+     * the slice is not configured at all.
+     * @returns {Partial<CONF> | undefined} A partial config from the environment, or `undefined` when the environment carries no usable credentials.
+     */
+    protected configFromEnvironment(): Partial<CONF> | undefined;
+    /**
+     * @description Resolves the config and builds the Axios client
+     * @summary Merges the explicitly provided config (first argument, when
+     * present) over the environment slice from `configFromEnvironment()`,
+     * resolves the effective base URL (explicit `baseUrl`, then
+     * `defaultBaseUrl()`), and creates an Axios instance with the resolved
+     * `timeout` (default `30000`), JSON content type, `authHeaders(config)`,
+     * and any extra config `headers`. The resolved config and client are also
+     * stored on the service for subsequent operations.
+     * @param {...MaybeContextualArg<any>} args - An optional `Partial<CONF>`, optionally followed by a decaf `Context`.
+     * @returns {Promise<{config: CONF, client: AxiosInstance}>} The merged configuration and the configured Axios instance.
+     * @throws {InternalError} When neither the config nor `defaultBaseUrl()` yields a base URL.
+     */
+    initialize(...args: MaybeContextualArg<any>): Promise<{
+        config: CONF;
+        client: AxiosInstance;
+    }>;
+    /**
+     * @description Asserts that the service was configured with a token
+     * @summary Reads the resolved config and throws when no `token` is present;
+     * operations that require authenticated access call this before issuing
+     * requests.
+     * @param {CONF} [config] - The config to validate; defaults to the service's resolved config.
+     * @returns {string} The configured token.
+     * @throws {InternalError} When the config carries no `token`.
+     */
+    protected requireToken(config?: CONF): string;
+}

package/lib/types/shared/http/hermeticBoot.d.cts

@@ -0,0 +1,84 @@
+/**
+ * @description Minimal boot contract required by the hermetic boot helper
+ * @summary Any client-based service exposing the core `boot(...)` shape; kept
+ * structural so the helper does not depend on the core service types.
+ */
+interface HermeticBootableService {
+    boot(...args: unknown[]): Promise<unknown>;
+}
+/**
+ * @description Boots a service with Environment-derived configuration disabled
+ * @summary Node-side replacement for the removed `nonEnvironmentService`
+ * wrappers (SAA-1293): the service's own `configFromEnvironment()` property
+ * descriptor is shadowed with `() => undefined` for the duration of the
+ * `boot()` call and restored (or removed, when the service had no own
+ * descriptor) in `finally`, so configuration keys absent from
+ * the explicit config cannot inherit the service's Environment slice. The
+ * shadowing is per-instance (the prototype is never touched): a module-level
+ * `WeakMap` (`shadowScopes`) tracks each service's original
+ * `configFromEnvironment` descriptor together with a call depth, so
+ * overlapping or nested `bootWithoutEnvironment` calls on the same instance
+ * share a single shadow; a nested call only increments that depth and never
+ * restores the descriptor early, and the original descriptor is restored (or
+ * deleted) only when the outermost call completes. The helper fails closed:
+ * an explicit config object is mandatory, so a node boot can never silently
+ * fall back to Environment configuration. The SAA-1293 undecorated-service
+ * contract stands — no decoration, no wrapper classes, no `Injectables`
+ * registration.
+ * @template CONF The explicit configuration object type passed to `boot()`.
+ * @template S The undecorated service type being booted.
+ * @param {S} service - The undecorated service instance to boot.
+ * @param {CONF} config - Explicit configuration object for the boot; Environment-derived config is disabled for this call.
+ * @param {...unknown} rest - Remaining `boot()` arguments (e.g. a decaf `Context`), forwarded unchanged.
+ * @returns {Promise<S>} The same service instance, booted with only the explicit configuration.
+ * @throws {ValidationError} When `config` is missing or not an object.
+ * @example
+ * ```ts
+ * import { EmailService } from "@decaf-ts/integrations/comms/email";
+ * import { bootWithoutEnvironment } from "@decaf-ts/integrations/shared/http";
+ *
+ * const service = new EmailService();
+ * // The comms.email environment slice is ignored even when configured:
+ * // allowPlaintextAuth stays false unless the explicit config sets it.
+ * await bootWithoutEnvironment(service, {
+ *   provider: "smtp",
+ *   host: "smtp.example",
+ *   port: 587,
+ *   username: "user@example.com",
+ *   password: "secret",
+ * });
+ * ```
+ * @category Shared
+ * @memberOf module:integrations/shared/http/hermetic-boot
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Helper as bootWithoutEnvironment
+ *   participant Service as service
+ *   Caller->>Helper: bootWithoutEnvironment(service, config, ...rest)
+ *   activate Helper
+ *   alt config missing or not an object
+ *     Helper-->>Caller: ValidationError
+ *   else explicit config present
+ *     alt instance not yet shadowed
+ *       Helper->>Service: capture own configFromEnvironment descriptor
+ *       Helper->>Service: shadow own configFromEnvironment with () => undefined
+ *     else re-entrant call on the same instance
+ *       Helper->>Helper: increment shared scope depth
+ *     end
+ *     Helper->>Service: boot(config, ...rest)
+ *     activate Service
+ *     Service-->>Helper: boot completes
+ *     deactivate Service
+ *     alt outermost call (depth reaches 0)
+ *       Helper->>Service: restore or remove own configFromEnvironment descriptor
+ *     else nested call
+ *       Note over Helper,Service: shared shadow stays in place
+ *     end
+ *     Helper-->>Caller: service
+ *   end
+ *   deactivate Helper
+ */
+export declare function bootWithoutEnvironment<CONF extends object, S extends HermeticBootableService>(service: S, config: CONF, ...rest: unknown[]): Promise<S>;
+export {};

package/lib/types/shared/http/hermeticBoot.d.mts

@@ -0,0 +1,84 @@
+/**
+ * @description Minimal boot contract required by the hermetic boot helper
+ * @summary Any client-based service exposing the core `boot(...)` shape; kept
+ * structural so the helper does not depend on the core service types.
+ */
+interface HermeticBootableService {
+    boot(...args: unknown[]): Promise<unknown>;
+}
+/**
+ * @description Boots a service with Environment-derived configuration disabled
+ * @summary Node-side replacement for the removed `nonEnvironmentService`
+ * wrappers (SAA-1293): the service's own `configFromEnvironment()` property
+ * descriptor is shadowed with `() => undefined` for the duration of the
+ * `boot()` call and restored (or removed, when the service had no own
+ * descriptor) in `finally`, so configuration keys absent from
+ * the explicit config cannot inherit the service's Environment slice. The
+ * shadowing is per-instance (the prototype is never touched): a module-level
+ * `WeakMap` (`shadowScopes`) tracks each service's original
+ * `configFromEnvironment` descriptor together with a call depth, so
+ * overlapping or nested `bootWithoutEnvironment` calls on the same instance
+ * share a single shadow; a nested call only increments that depth and never
+ * restores the descriptor early, and the original descriptor is restored (or
+ * deleted) only when the outermost call completes. The helper fails closed:
+ * an explicit config object is mandatory, so a node boot can never silently
+ * fall back to Environment configuration. The SAA-1293 undecorated-service
+ * contract stands — no decoration, no wrapper classes, no `Injectables`
+ * registration.
+ * @template CONF The explicit configuration object type passed to `boot()`.
+ * @template S The undecorated service type being booted.
+ * @param {S} service - The undecorated service instance to boot.
+ * @param {CONF} config - Explicit configuration object for the boot; Environment-derived config is disabled for this call.
+ * @param {...unknown} rest - Remaining `boot()` arguments (e.g. a decaf `Context`), forwarded unchanged.
+ * @returns {Promise<S>} The same service instance, booted with only the explicit configuration.
+ * @throws {ValidationError} When `config` is missing or not an object.
+ * @example
+ * ```ts
+ * import { EmailService } from "@decaf-ts/integrations/comms/email";
+ * import { bootWithoutEnvironment } from "@decaf-ts/integrations/shared/http";
+ *
+ * const service = new EmailService();
+ * // The comms.email environment slice is ignored even when configured:
+ * // allowPlaintextAuth stays false unless the explicit config sets it.
+ * await bootWithoutEnvironment(service, {
+ *   provider: "smtp",
+ *   host: "smtp.example",
+ *   port: 587,
+ *   username: "user@example.com",
+ *   password: "secret",
+ * });
+ * ```
+ * @category Shared
+ * @memberOf module:integrations/shared/http/hermetic-boot
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Helper as bootWithoutEnvironment
+ *   participant Service as service
+ *   Caller->>Helper: bootWithoutEnvironment(service, config, ...rest)
+ *   activate Helper
+ *   alt config missing or not an object
+ *     Helper-->>Caller: ValidationError
+ *   else explicit config present
+ *     alt instance not yet shadowed
+ *       Helper->>Service: capture own configFromEnvironment descriptor
+ *       Helper->>Service: shadow own configFromEnvironment with () => undefined
+ *     else re-entrant call on the same instance
+ *       Helper->>Helper: increment shared scope depth
+ *     end
+ *     Helper->>Service: boot(config, ...rest)
+ *     activate Service
+ *     Service-->>Helper: boot completes
+ *     deactivate Service
+ *     alt outermost call (depth reaches 0)
+ *       Helper->>Service: restore or remove own configFromEnvironment descriptor
+ *     else nested call
+ *       Note over Helper,Service: shared shadow stays in place
+ *     end
+ *     Helper-->>Caller: service
+ *   end
+ *   deactivate Helper
+ */
+export declare function bootWithoutEnvironment<CONF extends object, S extends HermeticBootableService>(service: S, config: CONF, ...rest: unknown[]): Promise<S>;
+export {};

package/lib/types/shared/http/index.d.cts

@@ -0,0 +1,10 @@
+/**
+ * @module integrations/shared/http
+ * @summary Shared HTTP plumbing for client-based API services.
+ * @description Re-exports {@link HttpApiService} (Axios-backed base class with
+ * environment-driven config), {@link httpError} (the failure-to-decaf-error
+ * mapper used by every API service), and {@link bootWithoutEnvironment} (the
+ * Environment-hermetic boot path used by as-graph node consumers).
+ */
+export * from "./HttpApiService.d.cts";
+export * from "./hermeticBoot.d.cts";

package/lib/types/shared/http/index.d.mts

@@ -0,0 +1,10 @@
+/**
+ * @module integrations/shared/http
+ * @summary Shared HTTP plumbing for client-based API services.
+ * @description Re-exports {@link HttpApiService} (Axios-backed base class with
+ * environment-driven config), {@link httpError} (the failure-to-decaf-error
+ * mapper used by every API service), and {@link bootWithoutEnvironment} (the
+ * Environment-hermetic boot path used by as-graph node consumers).
+ */
+export * from "./HttpApiService.d.mts";
+export * from "./hermeticBoot.d.mts";