@decaf-ts/integrations 0.10.8 → 0.12.0

package/lib/types/secrets/model/ModelSecretService.d.mts

@@ -1,22 +1,211 @@
+/**
+ * @module integrations/secrets/model/service
+ * @summary Model-backed encrypted secret service.
+ * @description Implements the `{@link ModelSecretService}`, an undecorated
+ * `ClientBasedSecretService` that
+ * persists AES-encrypted payloads as `{@link Secret}` rows through a
+ * decaf `Repository` (tenant/org-unit/owner scoping included). Encryption
+ * keys derive from a master `keySecret` via `CryptoService`; configuration
+ * comes from the `secrets.model` Environment slice or an explicit boot
+ * config (see `ModelSecretServiceConfig`).
+ */
 import { ClientBasedSecretService, SecretError, SecretProvider } from "../core/index.d.mts";
 import { SecretName, SecretPayload, SecretReference, SecretMetadata } from "../core/index.d.mts";
-import { StoreSecretOptions, RetrieveSecretOptions, DeleteSecretOptions, ExistsSecretOptions, ListSecretsOptions, SecretMetadataOptions } from "../core/index.d.mts";
+import { StoreSecretOptions, RetrieveSecretOptions, DeleteSecretOptions, ExistsSecretOptions, ListSecretsOptions, SecretMetadataOptions, RotateSecretOptions } from "../core/index.d.mts";
 import { Secret } from "./Secret.d.mts";
 import { ContextualArgs, MaybeContextualArg, Repository } from "@decaf-ts/core";
 import { ModelSecretServiceConfig } from "./ModelSecretServiceConfig.d.mts";
+/**
+ * @description Model-backed encrypted secret service
+ * @summary Stores each secret as a `{@link Secret}` row (encrypted payload,
+ * key id/iv/salt metadata, version, enablement flag, and optional
+ * tenant/org-unit/owner scope) through the repository booted as the service
+ * client. Names are validated and normalized before persistence;
+ * `(name, version)` is unique (enforced by a `SECRET_ALREADY_EXISTS`
+ * conflict in `store`/`rotate` and backed by the `uq_secrets_name_version`
+ * database index); retrieval only considers enabled rows, supports version
+ * pinning, and resolves multiple matches deterministically by `updatedAt
+ * DESC`. Delete is soft by default (sets `enabled: false`) unless
+ * `options.force` is set. Errors from the repository are translated into
+ * typed {@link SecretError}s by `parseError`.
+ *
+ * Undecorated and Environment-configurable
+ * through the `secrets.model` slice; the credential service
+ * (`CredentialService`) delegates user/runtime credential storage to this
+ * service.
+ * @class ModelSecretService
+ * @category Secrets
+ * @example
+ * ```ts
+ * import { ModelSecretService } from "@decaf-ts/integrations/secrets";
+ *
+ * const modelSecrets = await new ModelSecretService().boot({
+ *   keySecret: "model-master-key",
+ * });
+ * await modelSecrets.store("my-secret", { value: "s3cr3t" });
+ * const payload = await modelSecrets.retrieve<{ value: string }>("my-secret");
+ * ```
+ */
 export declare class ModelSecretService extends ClientBasedSecretService<Repository<Secret, any>, ModelSecretServiceConfig> {
     readonly provider: SecretProvider;
     private cryptoService;
+    constructor();
+    /**
+     * @description Builds the model secret configuration from the Environment
+     * @summary Reads the `secrets.model` Environment slice and returns a
+     * `ModelSecretServiceConfig` when a `keySecret` is configured; returns
+     * `undefined` otherwise, letting boot fall back to explicit arguments.
+     * @returns {ModelSecretServiceConfig | undefined} The Environment-derived configuration, or `undefined`.
+     * @override
+     */
     protected configFromEnvironment(): ModelSecretServiceConfig | undefined;
+    /**
+     * @description Boots the crypto service and resolves the backing repository
+     * @summary Accepts the configuration (explicit args, merged with the
+     * Environment slice by the base) and an optional `Repository<Secret>` as the
+     * second argument; when absent, creates one via `Repository.forModel(Secret)`.
+     * Returns the config and repository as the service client.
+     * @param {ContextualArgs} args - Configuration and optional `Repository`/`Context` arguments.
+     * @returns {Promise<{config: ModelSecretServiceConfig, client: Repository<Secret, any>}>} The resolved config and repository client.
+     */
     initialize(...args: ContextualArgs<any>): Promise<{
         config: ModelSecretServiceConfig;
         client: Repository<Secret, any>;
     }>;
+    /**
+     * @description Encrypts and persists a secret row
+     * @summary Validates and normalizes the name, serializes the payload, and
+     * encrypts it with a key derived from the master `keySecret`, embedding the
+     * key id/iv/salt in the row's `encryption` metadata. The row carries the
+     * optional tenant/org-unit/owner scoping and version. `(name, version)` is
+     * unique: an application-level pre-check rejects a duplicate combination
+     * with a `SECRET_ALREADY_EXISTS` {@link SecretError} before the insert, and
+     * the `uq_secrets_name_version` database index (which treats `NULL`
+     * versions as `''`) backstops the same rule against concurrent writers.
+     * @template T - The secret payload type.
+     * @param {SecretName} name - The secret name (validated and normalized).
+     * @param {T} value - The payload to encrypt and store.
+     * @param {StoreSecretOptions} [options] - Optional content type, tags, version, and tenant/org/owner scoping.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<SecretReference>} A reference to the persisted secret.
+     * @throws {SecretError} `SECRET_ALREADY_EXISTS` when a row with the same normalized name and version already exists, or `SECRET_NOT_FOUND`/`SECRET_PROVIDER_CONFLICT` when the name is invalid or the repository insert fails.
+     */
     store<T extends SecretPayload = SecretPayload>(name: SecretName, value: T, options?: StoreSecretOptions, ...args: MaybeContextualArg<any>): Promise<SecretReference>;
+    /**
+     * @description Reads, decrypts, and deserializes an enabled secret row
+     * @summary Queries the newest matching enabled row (by normalized name and,
+     * optionally, version), re-derives the key using the row's salt, and decrypts
+     * the payload. Rows are ordered by `updatedAt DESC`, so when several rows
+     * share a name the most recently updated enabled row is resolved
+     * deterministically. The repository SELECT runs inside a principal-bound
+     * transaction (see {@link ModelSecretService.withinPrincipalTransaction}):
+     * it joins an in-flight `transactionLock` on the context or begins one,
+     * binding the context's principal to `app.principal_id` on TypeORM adapters
+     * so namespace RLS applies to the read. Missing rows throw
+     * {@link NotFoundError}; decryption and JSON parse failures throw
+     * `InternalError`.
+     * @template T - The secret payload type.
+     * @param {SecretName | SecretReference} nameOrRef - The secret name or reference.
+     * @param {RetrieveSecretOptions} [options] - Optional version filter.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<T>} The decrypted payload.
+     * @throws {NotFoundError} When no enabled secret matches the name/version.
+     */
     retrieve<T extends SecretPayload = SecretPayload>(nameOrRef: SecretName | SecretReference, options?: RetrieveSecretOptions, ...args: MaybeContextualArg<any>): Promise<T>;
+    /**
+     * @description Runs a repository operation inside a principal-bound transaction
+     * @summary Mirrors core's `@transactional()` proxy for single reads: reuses
+     * the `transactionLock` already cached on the context (nested call), or
+     * resolves a fresh lock for the service client via `resolveTransactionLock`
+     * and calls `begin(context)` - which, on a TypeORM adapter, binds the
+     * context's principal to `app.principal_id` for the new transaction.
+     * Increments the lock depth for the duration of the operation; on failure,
+     * rolls back and zeroes the depth (skipping a redundant rollback when an
+     * inner frame already ended the transaction) and rethrows the original
+     * error; on success, commits when the outermost frame completes.
+     * @template R - The operation result type.
+     * @param {Context} context - The request context, carrying any in-flight transaction lock.
+     * @param {function(ContextLock): Promise<R>} operation - The repository operation to run, receiving the active lock.
+     * @returns {Promise<R>} The operation result.
+     * @throws {InternalError} When the final commit fails; operation errors are rethrown after rollback.
+     */
+    private withinPrincipalTransaction;
+    /**
+     * @description Deletes (or disables) a secret row
+     * @summary Soft-deletes by default: the row is disabled and stamped with a
+     * new `updatedAt`. With `options.force`, the row is hard-deleted from the
+     * repository. Rows are ordered by `updatedAt DESC`, so the most recently
+     * updated matching row is resolved deterministically. A missing secret
+     * resolves silently.
+     * @param {SecretName | SecretReference} nameOrRef - The secret name or reference.
+     * @param {DeleteSecretOptions} [options] - Optional version filter and `force` hard-delete flag.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<void>} Resolves once the row is deleted or disabled.
+     */
     delete(nameOrRef: SecretName | SecretReference, options?: DeleteSecretOptions, ...args: MaybeContextualArg<any>): Promise<void>;
+    /**
+     * @description Checks whether an enabled secret exists (optionally at a version)
+     * @summary Counts enabled rows matching the normalized name (plus any
+     * requested version) and returns whether the count is positive.
+     * @param {SecretName | SecretReference} nameOrRef - The secret name or reference.
+     * @param {ExistsSecretOptions} [options] - Optional version filter.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<boolean>} `true` when at least one enabled row matches.
+     */
     exists(nameOrRef: SecretName | SecretReference, options?: ExistsSecretOptions, ...args: MaybeContextualArg<any>): Promise<boolean>;
+    /**
+     * @description Lists secret metadata across stored rows
+     * @summary Selects rows filtered by the `enabled` flag (when supplied) and
+     * maps them to `SecretMetadata` records (no payloads).
+     * @param {ListSecretsOptions} [options] - Optional `enabled` filter.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<SecretMetadata[]>} Metadata for every matching secret.
+     */
     list(options?: ListSecretsOptions, ...args: MaybeContextualArg<any>): Promise<SecretMetadata[]>;
+    /**
+     * @description Reads one secret's metadata without its payload
+     * @summary Selects the row matching the normalized name (and optional
+     * version) and maps it to `SecretMetadata`; tags are included only when
+     * `options.includeTags` is set. Rows are ordered by `updatedAt DESC`, so
+     * the most recently updated matching row is resolved deterministically.
+     * Returns `undefined` when no row matches.
+     * @param {SecretName | SecretReference} nameOrRef - The secret name or reference.
+     * @param {SecretMetadataOptions} [options] - Optional version filter and `includeTags` flag.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<SecretMetadata | undefined>} The metadata, or `undefined` when absent.
+     */
     metadata(nameOrRef: SecretName | SecretReference, options?: SecretMetadataOptions, ...args: MaybeContextualArg<any>): Promise<SecretMetadata | undefined>;
+    /**
+     * @description Re-encrypts an enabled secret row with a new payload
+     * @summary Locates the enabled row (optionally pinned to
+     * `options.oldVersion`), encrypts the new payload with a freshly derived
+     * key (optionally tagged with `options.keyId`), and updates the row's
+     * payload, encryption metadata, version (`options.newVersion`), and
+     * `updatedAt`. When `options.newVersion` differs from the row's current
+     * version, a `(name, version)` duplicate check rejects the rotation with a
+     * `SECRET_ALREADY_EXISTS` {@link SecretError}; otherwise the target version
+     * is reused and the row is updated in place. Matching rows are ordered by
+     * `updatedAt DESC`, so the most recently updated enabled row is resolved
+     * deterministically.
+     * @template T - The secret payload type.
+     * @param {SecretName | SecretReference} nameOrRef - The secret name or reference.
+     * @param {T} value - The new payload.
+     * @param {RotateSecretOptions} [options] - Optional `newVersion`, `oldVersion`, and `keyId`.
+     * @param {MaybeContextualArg} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<SecretReference>} A reference reflecting the updated row.
+     * @throws {NotFoundError} When no enabled secret matches the name/version.
+     * @throws {SecretError} `SECRET_ALREADY_EXISTS` when the target `newVersion` is already held by another row with the same normalized name, or `SECRET_PROVIDER_CONFLICT` when the repository update fails.
+     */
+    rotate<T extends SecretPayload = SecretPayload>(nameOrRef: SecretName | SecretReference, value: T, options?: RotateSecretOptions, ...args: MaybeContextualArg<any>): Promise<SecretReference>;
+    /**
+     * @description Translates repository errors into typed secret errors
+     * @summary Inspects the error message for "not found"/404, "already
+     * exists"/conflict/409, and decryption-related markers and maps them to
+     * `SECRET_NOT_FOUND`, `SECRET_ALREADY_EXISTS`,
+     * `SECRET_DECRYPTION_FAILED`, or a generic `SECRET_PROVIDER_CONFLICT`
+     * {@link SecretError}.
+     * @param {unknown} error - The raw error thrown by the repository.
+     * @returns {SecretError} The typed secret error.
+     */
     protected parseError(error: unknown): SecretError;
 }

package/lib/types/secrets/model/Secret.d.cts

@@ -1,24 +1,65 @@
 /**
- * @module integrations/secrets/model/secret
- * @summary Encrypted secret model types.
- * @description Model payload and metadata types used by the encrypted-at-rest secret service.
+ * @module integrations/secrets/model/model
+ * @summary Encrypted-at-rest secret persistence model.
+ * @description Defines the `{@link Secret}` model (`secrets` table) persisted
+ * by the `{@link ModelSecretService}`: one row per secret, holding the
+ * encrypted payload, `keyId`/`iv`/`salt` encryption metadata, versioning and
+ * enablement fields, and optional tenant/org-unit/owner scoping columns.
  */
 import { BaseModel } from "@decaf-ts/core";
+/**
+ * @description Encryption metadata embedded in a secret row
+ * @summary `keyId` identifies the key used to encrypt the payload; `iv` and
+ * the optional `aad`/`salt` carry the cipher parameters needed to re-derive
+ * the key and decrypt the payload.
+ */
 export interface SecretEncryptionMetadata {
+    /** @description Identifier of the encryption key used for the payload. */
     keyId: string;
+    /** @description Initialization vector used for the payload encryption. */
     iv: string;
+    /** @description Optional additional authenticated data bound to the cipher. */
     aad?: string;
+    /** @description Optional salt used when deriving the key from the master secret. */
+    salt?: string;
 }
+/**
+ * @description Encrypted secret record stored through the model-backed secret service
+ * @summary Persisted in the `secrets` table. The `encryptedPayload` column is
+ * written only by `{@link ModelSecretService}` (which also fills
+ * `encryption`, `version`, and the optional `tenantId`/`orgUnitId`/
+ * `ownerPrincipalId` scoping columns); `enabled: false` marks soft-deleted
+ * secrets that retrieval filters out.
+ * @category Secrets
+ */
 export declare class Secret extends BaseModel {
+    /** @description Primary key (UUID). */
+    id: string;
+    /** @description Normalized secret name. */
     name: string;
+    /** @description Secret provider discriminator that wrote the row. */
     provider: string;
+    /** @description Encrypted, serialized payload. */
     encryptedPayload: string;
+    /** @description Cipher parameters required to decrypt the payload. */
     encryption: SecretEncryptionMetadata;
+    /** @description Optional content type describing the payload. */
     contentType?: string;
+    /** @description Optional free-form tags. */
     tags?: Record<string, string>;
+    /** @description When `false`, the secret is soft-deleted and filtered from retrieval. */
     enabled: boolean;
+    /** @description Optional version label. */
     version?: string;
+    /** @description Optional external identifier linking the secret to a provider record. */
     externalId?: string;
+    /** @description Optional provider URI for externally stored secrets. */
     uri?: string;
+    /** @description Optional tenant scope id. */
+    tenantId?: string;
+    /** @description Optional organizational unit scope id. */
+    orgUnitId?: string;
+    /** @description Optional owning principal id. */
+    ownerPrincipalId?: string;
     constructor(data?: Partial<Secret>);
 }

package/lib/types/secrets/model/Secret.d.mts

@@ -1,24 +1,65 @@
 /**
- * @module integrations/secrets/model/secret
- * @summary Encrypted secret model types.
- * @description Model payload and metadata types used by the encrypted-at-rest secret service.
+ * @module integrations/secrets/model/model
+ * @summary Encrypted-at-rest secret persistence model.
+ * @description Defines the `{@link Secret}` model (`secrets` table) persisted
+ * by the `{@link ModelSecretService}`: one row per secret, holding the
+ * encrypted payload, `keyId`/`iv`/`salt` encryption metadata, versioning and
+ * enablement fields, and optional tenant/org-unit/owner scoping columns.
  */
 import { BaseModel } from "@decaf-ts/core";
+/**
+ * @description Encryption metadata embedded in a secret row
+ * @summary `keyId` identifies the key used to encrypt the payload; `iv` and
+ * the optional `aad`/`salt` carry the cipher parameters needed to re-derive
+ * the key and decrypt the payload.
+ */
 export interface SecretEncryptionMetadata {
+    /** @description Identifier of the encryption key used for the payload. */
     keyId: string;
+    /** @description Initialization vector used for the payload encryption. */
     iv: string;
+    /** @description Optional additional authenticated data bound to the cipher. */
     aad?: string;
+    /** @description Optional salt used when deriving the key from the master secret. */
+    salt?: string;
 }
+/**
+ * @description Encrypted secret record stored through the model-backed secret service
+ * @summary Persisted in the `secrets` table. The `encryptedPayload` column is
+ * written only by `{@link ModelSecretService}` (which also fills
+ * `encryption`, `version`, and the optional `tenantId`/`orgUnitId`/
+ * `ownerPrincipalId` scoping columns); `enabled: false` marks soft-deleted
+ * secrets that retrieval filters out.
+ * @category Secrets
+ */
 export declare class Secret extends BaseModel {
+    /** @description Primary key (UUID). */
+    id: string;
+    /** @description Normalized secret name. */
     name: string;
+    /** @description Secret provider discriminator that wrote the row. */
     provider: string;
+    /** @description Encrypted, serialized payload. */
     encryptedPayload: string;
+    /** @description Cipher parameters required to decrypt the payload. */
     encryption: SecretEncryptionMetadata;
+    /** @description Optional content type describing the payload. */
     contentType?: string;
+    /** @description Optional free-form tags. */
     tags?: Record<string, string>;
+    /** @description When `false`, the secret is soft-deleted and filtered from retrieval. */
     enabled: boolean;
+    /** @description Optional version label. */
     version?: string;
+    /** @description Optional external identifier linking the secret to a provider record. */
     externalId?: string;
+    /** @description Optional provider URI for externally stored secrets. */
     uri?: string;
+    /** @description Optional tenant scope id. */
+    tenantId?: string;
+    /** @description Optional organizational unit scope id. */
+    orgUnitId?: string;
+    /** @description Optional owning principal id. */
+    ownerPrincipalId?: string;
     constructor(data?: Partial<Secret>);
 }

package/lib/types/shared/environmentValue.d.cts

@@ -11,6 +11,30 @@
  * must use these helpers instead of a raw truthiness check, both to decide whether a
  * field was really configured and to build the config object it returns.
  */
+/**
+ * @description Returns a non-empty string when the value is a usable string
+ * @summary Guards against `LoggedEnvironment` unset-leaf proxies: a value is
+ * accepted only when it is actually a `string` with positive length, so proxy
+ * placeholders and empty strings yield `undefined` instead of leaking into
+ * config objects.
+ * @param {unknown} value - The raw environment value to test.
+ * @returns {string | undefined} The string value, or `undefined` when the value is not a non-empty string.
+ */
 export declare function envString(value: unknown): string | undefined;
+/**
+ * @description Returns a finite number when the value is a usable number
+ * @summary Accepts only real finite numbers, rejecting proxy placeholders,
+ * `NaN`, and `Infinity` so numeric environment leaves produce `undefined`
+ * rather than invalid config values.
+ * @param {unknown} value - The raw environment value to test.
+ * @returns {number | undefined} The numeric value, or `undefined` when the value is not a finite number.
+ */
 export declare function envNumber(value: unknown): number | undefined;
+/**
+ * @description Returns a boolean when the value is actually a boolean
+ * @summary Accepts only `true`/`false`; any other value (including proxy
+ * placeholders and string-encoded flags) yields `undefined`.
+ * @param {unknown} value - The raw environment value to test.
+ * @returns {boolean | undefined} The boolean value, or `undefined` when the value is not a boolean.
+ */
 export declare function envBoolean(value: unknown): boolean | undefined;

package/lib/types/shared/environmentValue.d.mts

@@ -11,6 +11,30 @@
  * must use these helpers instead of a raw truthiness check, both to decide whether a
  * field was really configured and to build the config object it returns.
  */
+/**
+ * @description Returns a non-empty string when the value is a usable string
+ * @summary Guards against `LoggedEnvironment` unset-leaf proxies: a value is
+ * accepted only when it is actually a `string` with positive length, so proxy
+ * placeholders and empty strings yield `undefined` instead of leaking into
+ * config objects.
+ * @param {unknown} value - The raw environment value to test.
+ * @returns {string | undefined} The string value, or `undefined` when the value is not a non-empty string.
+ */
 export declare function envString(value: unknown): string | undefined;
+/**
+ * @description Returns a finite number when the value is a usable number
+ * @summary Accepts only real finite numbers, rejecting proxy placeholders,
+ * `NaN`, and `Infinity` so numeric environment leaves produce `undefined`
+ * rather than invalid config values.
+ * @param {unknown} value - The raw environment value to test.
+ * @returns {number | undefined} The numeric value, or `undefined` when the value is not a finite number.
+ */
 export declare function envNumber(value: unknown): number | undefined;
+/**
+ * @description Returns a boolean when the value is actually a boolean
+ * @summary Accepts only `true`/`false`; any other value (including proxy
+ * placeholders and string-encoded flags) yields `undefined`.
+ * @param {unknown} value - The raw environment value to test.
+ * @returns {boolean | undefined} The boolean value, or `undefined` when the value is not a boolean.
+ */
 export declare function envBoolean(value: unknown): boolean | undefined;

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;
+}