@decaf-ts/integrations 0.9.0 → 0.10.0

package/lib/types/blob/gcp/GcsBlobStoreService.d.cts

@@ -7,9 +7,44 @@ import { type Bucket } from "@google-cloud/storage";
 import { type ContextualArgs, type MaybeContextualArg } from "@decaf-ts/core";
 import { BlobStoreService } from "../core/BlobStoreService.d.cts";
 import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListResult, BlobMetadata, BlobPutOptions, BlobPutResult, BlobUrlOptions, BlobUrlResult, BlobValue, GcsBlobStoreServiceConfig } from "../core/BlobTypes.d.cts";
+/**
+ * @description Google Cloud Storage blob store service registered as `blob-gcs`
+ * @summary Stores blobs in a GCS bucket via `@google-cloud/storage`,
+ * authenticating with optional explicit credentials or the environment's
+ * application default credentials.
+ * @class GcsBlobStoreService
+ * @memberOf module:integrations/blob/gcp/service
+ */
 export declare class GcsBlobStoreService extends BlobStoreService<Bucket, GcsBlobStoreServiceConfig> {
+    /**
+     * @description The `Storage` client used to resolve the bucket
+     * @summary Built in `initialize()` from the resolved config.
+     * @type {Storage}
+     * @private
+     */
     private storage;
+    /**
+     * @description Builds the GCS blob config from the environment
+     * @summary Reads the `blobs.gcs` environment slice; considered
+     * unconfigured when no `bucket` is set, which keeps the auto-boot
+     * fallback (see `getConfigFromArgs`) resolving to `undefined`.
+     * @return {GcsBlobStoreServiceConfig | undefined} The environment-derived config, or `undefined` when unconfigured
+     */
     protected configFromEnvironment(): GcsBlobStoreServiceConfig | undefined;
+    /**
+     * @description Initializes the GCS bucket client
+     * @summary Resolves the config via `getConfigFromArgs` (explicit config,
+     * then the `blobs.gcs` environment slice). When no config resolves during a
+     * context-bearing auto-boot of an unconfigured provider, returns
+     * `skipInitialization()` so `Service.boot` does not throw; an explicit
+     * `initialize()` with no resolvable config still throws a
+     * `ValidationError`. Requires a `bucket`, builds the `Storage` client with
+     * the configured project ID, credentials, and API endpoint, and stores the
+     * bucket client.
+     * @param {...ContextualArgs<any>} args - An optional `GcsBlobStoreServiceConfig`, optionally followed by a decaf `Context`
+     * @return {Promise<{config: GcsBlobStoreServiceConfig, client: Bucket}>} The resolved config and the bucket client
+     * @throws {InternalError} When a resolved config has no `bucket`
+     */
     initialize(...args: ContextualArgs<any>): Promise<{
         config: GcsBlobStoreServiceConfig;
         client: Bucket;

package/lib/types/blob/gcp/GcsBlobStoreService.d.mts

@@ -7,9 +7,44 @@ import { type Bucket } from "@google-cloud/storage";
 import { type ContextualArgs, type MaybeContextualArg } from "@decaf-ts/core";
 import { BlobStoreService } from "../core/BlobStoreService.d.mts";
 import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListResult, BlobMetadata, BlobPutOptions, BlobPutResult, BlobUrlOptions, BlobUrlResult, BlobValue, GcsBlobStoreServiceConfig } from "../core/BlobTypes.d.mts";
+/**
+ * @description Google Cloud Storage blob store service registered as `blob-gcs`
+ * @summary Stores blobs in a GCS bucket via `@google-cloud/storage`,
+ * authenticating with optional explicit credentials or the environment's
+ * application default credentials.
+ * @class GcsBlobStoreService
+ * @memberOf module:integrations/blob/gcp/service
+ */
 export declare class GcsBlobStoreService extends BlobStoreService<Bucket, GcsBlobStoreServiceConfig> {
+    /**
+     * @description The `Storage` client used to resolve the bucket
+     * @summary Built in `initialize()` from the resolved config.
+     * @type {Storage}
+     * @private
+     */
     private storage;
+    /**
+     * @description Builds the GCS blob config from the environment
+     * @summary Reads the `blobs.gcs` environment slice; considered
+     * unconfigured when no `bucket` is set, which keeps the auto-boot
+     * fallback (see `getConfigFromArgs`) resolving to `undefined`.
+     * @return {GcsBlobStoreServiceConfig | undefined} The environment-derived config, or `undefined` when unconfigured
+     */
     protected configFromEnvironment(): GcsBlobStoreServiceConfig | undefined;
+    /**
+     * @description Initializes the GCS bucket client
+     * @summary Resolves the config via `getConfigFromArgs` (explicit config,
+     * then the `blobs.gcs` environment slice). When no config resolves during a
+     * context-bearing auto-boot of an unconfigured provider, returns
+     * `skipInitialization()` so `Service.boot` does not throw; an explicit
+     * `initialize()` with no resolvable config still throws a
+     * `ValidationError`. Requires a `bucket`, builds the `Storage` client with
+     * the configured project ID, credentials, and API endpoint, and stores the
+     * bucket client.
+     * @param {...ContextualArgs<any>} args - An optional `GcsBlobStoreServiceConfig`, optionally followed by a decaf `Context`
+     * @return {Promise<{config: GcsBlobStoreServiceConfig, client: Bucket}>} The resolved config and the bucket client
+     * @throws {InternalError} When a resolved config has no `bucket`
+     */
     initialize(...args: ContextualArgs<any>): Promise<{
         config: GcsBlobStoreServiceConfig;
         client: Bucket;

package/lib/types/blob/ipfs/IpfsBlobStoreService.d.cts

@@ -8,9 +8,43 @@ import { type KuboRPCClient } from "kubo-rpc-client";
 import { type ContextualArgs, type MaybeContextualArg } from "@decaf-ts/core";
 import { BlobStoreService } from "../core/BlobStoreService.d.cts";
 import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListResult, BlobMetadata, BlobPutOptions, BlobPutResult, BlobUrlOptions, BlobUrlResult, BlobValue, IpfsBlobStoreServiceConfig } from "../core/BlobTypes.d.cts";
+/**
+ * @description IPFS blob store service registered as `blob-ipfs`
+ * @summary Stores blobs on an IPFS (Kubo) node via `kubo-rpc-client`. Because
+ * the blob API is key/value CRUD-like and IPFS is content-addressed, an
+ * `IpfsKeyIndex` maps logical keys to CIDs; when `encryptedOnly` is set only
+ * encrypted payloads are accepted.
+ * @class IpfsBlobStoreService
+ * @memberOf module:integrations/blob/ipfs/service
+ */
 export declare class IpfsBlobStoreService extends BlobStoreService<KuboRPCClient, IpfsBlobStoreServiceConfig> {
+    /**
+     * @description The key index mapping logical keys to IPFS CIDs
+     * @summary Created in `initialize()` from the configured `keyIndex` provider.
+     * @type {IpfsKeyIndex}
+     * @private
+     */
     private index;
+    /**
+     * @description Builds the IPFS blob config from the environment
+     * @summary Reads the `blobs.ipfs` environment slice; considered
+     * unconfigured when no `sourceId` is set, which keeps the auto-boot
+     * fallback (see `getConfigFromArgs`) resolving to `undefined`.
+     * @return {IpfsBlobStoreServiceConfig | undefined} The environment-derived config, or `undefined` when unconfigured
+     */
     protected configFromEnvironment(): IpfsBlobStoreServiceConfig | undefined;
+    /**
+     * @description Initializes the IPFS Kubo RPC client and key index
+     * @summary Resolves the config via `getConfigFromArgs` (explicit config,
+     * then the `blobs.ipfs` environment slice). When no config resolves during
+     * a context-bearing auto-boot of an unconfigured provider, returns
+     * `skipInitialization()` so `Service.boot` does not throw; an explicit
+     * `initialize()` with no resolvable config still throws a
+     * `ValidationError`. Connects to the Kubo node at the configured `apiUrl`
+     * (default `http://localhost:5001`) and creates the `IpfsKeyIndex`.
+     * @param {...ContextualArgs<any>} args - An optional `IpfsBlobStoreServiceConfig`, optionally followed by a decaf `Context`
+     * @return {Promise<{config: IpfsBlobStoreServiceConfig, client: KuboRPCClient}>} The resolved config and the Kubo RPC client
+     */
     initialize(...args: ContextualArgs<any>): Promise<{
         config: IpfsBlobStoreServiceConfig;
         client: KuboRPCClient;

package/lib/types/blob/ipfs/IpfsBlobStoreService.d.mts

@@ -8,9 +8,43 @@ import { type KuboRPCClient } from "kubo-rpc-client";
 import { type ContextualArgs, type MaybeContextualArg } from "@decaf-ts/core";
 import { BlobStoreService } from "../core/BlobStoreService.d.mts";
 import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListResult, BlobMetadata, BlobPutOptions, BlobPutResult, BlobUrlOptions, BlobUrlResult, BlobValue, IpfsBlobStoreServiceConfig } from "../core/BlobTypes.d.mts";
+/**
+ * @description IPFS blob store service registered as `blob-ipfs`
+ * @summary Stores blobs on an IPFS (Kubo) node via `kubo-rpc-client`. Because
+ * the blob API is key/value CRUD-like and IPFS is content-addressed, an
+ * `IpfsKeyIndex` maps logical keys to CIDs; when `encryptedOnly` is set only
+ * encrypted payloads are accepted.
+ * @class IpfsBlobStoreService
+ * @memberOf module:integrations/blob/ipfs/service
+ */
 export declare class IpfsBlobStoreService extends BlobStoreService<KuboRPCClient, IpfsBlobStoreServiceConfig> {
+    /**
+     * @description The key index mapping logical keys to IPFS CIDs
+     * @summary Created in `initialize()` from the configured `keyIndex` provider.
+     * @type {IpfsKeyIndex}
+     * @private
+     */
     private index;
+    /**
+     * @description Builds the IPFS blob config from the environment
+     * @summary Reads the `blobs.ipfs` environment slice; considered
+     * unconfigured when no `sourceId` is set, which keeps the auto-boot
+     * fallback (see `getConfigFromArgs`) resolving to `undefined`.
+     * @return {IpfsBlobStoreServiceConfig | undefined} The environment-derived config, or `undefined` when unconfigured
+     */
     protected configFromEnvironment(): IpfsBlobStoreServiceConfig | undefined;
+    /**
+     * @description Initializes the IPFS Kubo RPC client and key index
+     * @summary Resolves the config via `getConfigFromArgs` (explicit config,
+     * then the `blobs.ipfs` environment slice). When no config resolves during
+     * a context-bearing auto-boot of an unconfigured provider, returns
+     * `skipInitialization()` so `Service.boot` does not throw; an explicit
+     * `initialize()` with no resolvable config still throws a
+     * `ValidationError`. Connects to the Kubo node at the configured `apiUrl`
+     * (default `http://localhost:5001`) and creates the `IpfsKeyIndex`.
+     * @param {...ContextualArgs<any>} args - An optional `IpfsBlobStoreServiceConfig`, optionally followed by a decaf `Context`
+     * @return {Promise<{config: IpfsBlobStoreServiceConfig, client: KuboRPCClient}>} The resolved config and the Kubo RPC client
+     */
     initialize(...args: ContextualArgs<any>): Promise<{
         config: IpfsBlobStoreServiceConfig;
         client: KuboRPCClient;

package/lib/types/blob/local/LocalBlobStoreService.d.cts

@@ -9,8 +9,35 @@ import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListR
 interface LocalFsClient {
     root: string;
 }
+/**
+ * @description Local filesystem blob store service registered as `blob-local`
+ * @summary Stores blobs under a configurable root path using `node:fs` with
+ * atomic writes (temp file + rename) and path-traversal protection.
+ * @class LocalBlobStoreService
+ * @memberOf module:integrations/blob/local/service
+ */
 export declare class LocalBlobStoreService extends BlobStoreService<LocalFsClient, LocalBlobStoreServiceConfig> {
+    /**
+     * @description Builds the local blob config from the environment
+     * @summary Reads the `blobs.local` environment slice; considered
+     * unconfigured when no `rootPath` is set, which keeps the auto-boot
+     * fallback (see `getConfigFromArgs`) resolving to `undefined`.
+     * @return {LocalBlobStoreServiceConfig | undefined} The environment-derived config, or `undefined` when unconfigured
+     */
     protected configFromEnvironment(): LocalBlobStoreServiceConfig | undefined;
+    /**
+     * @description Initializes the local filesystem blob store client
+     * @summary Resolves the config via `getConfigFromArgs` (explicit config,
+     * then the `blobs.local` environment slice). When no config resolves during
+     * a context-bearing auto-boot of an unconfigured provider, returns
+     * `skipInitialization()` so `Service.boot` does not throw; an explicit
+     * `initialize()` with no resolvable config still throws a
+     * `ValidationError`. Requires a `rootPath`, creates it recursively, and
+     * stores the resolved absolute root as the client.
+     * @param {...ContextualArgs<any>} args - An optional `LocalBlobStoreServiceConfig`, optionally followed by a decaf `Context`
+     * @return {Promise<{config: LocalBlobStoreServiceConfig, client: LocalFsClient}>} The resolved config and the filesystem client
+     * @throws {InternalError} When a resolved config has no `rootPath`
+     */
     initialize(...args: ContextualArgs<any>): Promise<{
         config: LocalBlobStoreServiceConfig;
         client: LocalFsClient;

package/lib/types/blob/local/LocalBlobStoreService.d.mts

@@ -9,8 +9,35 @@ import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListR
 interface LocalFsClient {
     root: string;
 }
+/**
+ * @description Local filesystem blob store service registered as `blob-local`
+ * @summary Stores blobs under a configurable root path using `node:fs` with
+ * atomic writes (temp file + rename) and path-traversal protection.
+ * @class LocalBlobStoreService
+ * @memberOf module:integrations/blob/local/service
+ */
 export declare class LocalBlobStoreService extends BlobStoreService<LocalFsClient, LocalBlobStoreServiceConfig> {
+    /**
+     * @description Builds the local blob config from the environment
+     * @summary Reads the `blobs.local` environment slice; considered
+     * unconfigured when no `rootPath` is set, which keeps the auto-boot
+     * fallback (see `getConfigFromArgs`) resolving to `undefined`.
+     * @return {LocalBlobStoreServiceConfig | undefined} The environment-derived config, or `undefined` when unconfigured
+     */
     protected configFromEnvironment(): LocalBlobStoreServiceConfig | undefined;
+    /**
+     * @description Initializes the local filesystem blob store client
+     * @summary Resolves the config via `getConfigFromArgs` (explicit config,
+     * then the `blobs.local` environment slice). When no config resolves during
+     * a context-bearing auto-boot of an unconfigured provider, returns
+     * `skipInitialization()` so `Service.boot` does not throw; an explicit
+     * `initialize()` with no resolvable config still throws a
+     * `ValidationError`. Requires a `rootPath`, creates it recursively, and
+     * stores the resolved absolute root as the client.
+     * @param {...ContextualArgs<any>} args - An optional `LocalBlobStoreServiceConfig`, optionally followed by a decaf `Context`
+     * @return {Promise<{config: LocalBlobStoreServiceConfig, client: LocalFsClient}>} The resolved config and the filesystem client
+     * @throws {InternalError} When a resolved config has no `rootPath`
+     */
     initialize(...args: ContextualArgs<any>): Promise<{
         config: LocalBlobStoreServiceConfig;
         client: LocalFsClient;

package/lib/types/blob/memory/MemoryBlobStoreService.d.cts

@@ -10,8 +10,35 @@ interface MemoryEntry {
     value: Buffer;
     metadata: BlobMetadata;
 }
+/**
+ * @description In-memory blob store service registered as `blob-memory`
+ * @summary Stores blobs in a process-local `Map`, so data does not survive
+ * restarts. Intended for tests and examples; supports the full blob CRUD API
+ * without any SDK dependency.
+ * @class MemoryBlobStoreService
+ * @memberOf module:integrations/blob/memory/service
+ */
 export declare class MemoryBlobStoreService extends BlobStoreService<Map<string, MemoryEntry>, BlobStoreServiceConfig> {
+    /**
+     * @description Builds the memory blob config from the environment
+     * @summary Reads the `blobs.memory` environment slice; considered
+     * unconfigured when no `sourceId` is set, which keeps the auto-boot
+     * fallback (see `getConfigFromArgs`) resolving to `undefined`.
+     * @return {BlobStoreServiceConfig | undefined} The environment-derived config, or `undefined` when unconfigured
+     */
     protected configFromEnvironment(): BlobStoreServiceConfig | undefined;
+    /**
+     * @description Initializes the in-memory blob store client
+     * @summary Resolves the config via `getConfigFromArgs` (explicit config,
+     * then the `blobs.memory` environment slice). When no config resolves during
+     * a context-bearing auto-boot of an unconfigured provider, returns
+     * `skipInitialization()` so `Service.boot` does not throw; an explicit
+     * `initialize()` with no resolvable config still throws a
+     * `ValidationError`. On success, stores the config and creates the backing
+     * `Map` client.
+     * @param {...ContextualArgs<any>} args - An optional `BlobStoreServiceConfig`, optionally followed by a decaf `Context`
+     * @return {Promise<{config: BlobStoreServiceConfig, client: Map<string, MemoryEntry>}>} The resolved config and the in-memory client
+     */
     initialize(...args: ContextualArgs<any>): Promise<{
         config: BlobStoreServiceConfig;
         client: Map<string, MemoryEntry>;

package/lib/types/blob/memory/MemoryBlobStoreService.d.mts

@@ -10,8 +10,35 @@ interface MemoryEntry {
     value: Buffer;
     metadata: BlobMetadata;
 }
+/**
+ * @description In-memory blob store service registered as `blob-memory`
+ * @summary Stores blobs in a process-local `Map`, so data does not survive
+ * restarts. Intended for tests and examples; supports the full blob CRUD API
+ * without any SDK dependency.
+ * @class MemoryBlobStoreService
+ * @memberOf module:integrations/blob/memory/service
+ */
 export declare class MemoryBlobStoreService extends BlobStoreService<Map<string, MemoryEntry>, BlobStoreServiceConfig> {
+    /**
+     * @description Builds the memory blob config from the environment
+     * @summary Reads the `blobs.memory` environment slice; considered
+     * unconfigured when no `sourceId` is set, which keeps the auto-boot
+     * fallback (see `getConfigFromArgs`) resolving to `undefined`.
+     * @return {BlobStoreServiceConfig | undefined} The environment-derived config, or `undefined` when unconfigured
+     */
     protected configFromEnvironment(): BlobStoreServiceConfig | undefined;
+    /**
+     * @description Initializes the in-memory blob store client
+     * @summary Resolves the config via `getConfigFromArgs` (explicit config,
+     * then the `blobs.memory` environment slice). When no config resolves during
+     * a context-bearing auto-boot of an unconfigured provider, returns
+     * `skipInitialization()` so `Service.boot` does not throw; an explicit
+     * `initialize()` with no resolvable config still throws a
+     * `ValidationError`. On success, stores the config and creates the backing
+     * `Map` client.
+     * @param {...ContextualArgs<any>} args - An optional `BlobStoreServiceConfig`, optionally followed by a decaf `Context`
+     * @return {Promise<{config: BlobStoreServiceConfig, client: Map<string, MemoryEntry>}>} The resolved config and the in-memory client
+     */
     initialize(...args: ContextualArgs<any>): Promise<{
         config: BlobStoreServiceConfig;
         client: Map<string, MemoryEntry>;

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

@@ -12,7 +12,35 @@ import { S3Client } from "@aws-sdk/client-s3";
 import { type ContextualArgs, type MaybeContextualArg } from "@decaf-ts/core";
 import { BlobStoreService } from "../core/BlobStoreService.d.cts";
 import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListResult, BlobMetadata, BlobPutOptions, BlobPutResult, BlobUrlOptions, BlobUrlResult, BlobValue, S3BlobStoreServiceConfig } from "../core/BlobTypes.d.cts";
+/**
+ * @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.
+ * @class S3CompatibleBlobStoreService
+ * @memberOf module:integrations/blob/s3/base-service
+ */
 export declare abstract class S3CompatibleBlobStoreService extends BlobStoreService<S3Client, S3BlobStoreServiceConfig> {
+    /**
+     * @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
+     * `ValidationError`. Requires a `bucket`, builds the `S3Client` (with
+     * optional static credentials), stores config and client, and optionally
+     * creates the bucket when `autoCreateBucket` is set.
+     * @param {...ContextualArgs<any>} args - An optional `S3BlobStoreServiceConfig`, optionally followed by a decaf `Context`
+     * @return {Promise<{config: S3BlobStoreServiceConfig, client: S3Client}>} The resolved config and the constructed `S3Client`
+     * @throws {InternalError} When a resolved config has no `bucket`
+     */
     initialize(...args: ContextualArgs<any>): Promise<{
         config: S3BlobStoreServiceConfig;
         client: S3Client;

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

@@ -12,7 +12,35 @@ import { S3Client } from "@aws-sdk/client-s3";
 import { type ContextualArgs, type MaybeContextualArg } from "@decaf-ts/core";
 import { BlobStoreService } from "../core/BlobStoreService.d.mts";
 import type { BlobGetOptions, BlobGetResult, BlobKey, BlobListOptions, BlobListResult, BlobMetadata, BlobPutOptions, BlobPutResult, BlobUrlOptions, BlobUrlResult, BlobValue, S3BlobStoreServiceConfig } from "../core/BlobTypes.d.mts";
+/**
+ * @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.
+ * @class S3CompatibleBlobStoreService
+ * @memberOf module:integrations/blob/s3/base-service
+ */
 export declare abstract class S3CompatibleBlobStoreService extends BlobStoreService<S3Client, S3BlobStoreServiceConfig> {
+    /**
+     * @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
+     * `ValidationError`. Requires a `bucket`, builds the `S3Client` (with
+     * optional static credentials), stores config and client, and optionally
+     * creates the bucket when `autoCreateBucket` is set.
+     * @param {...ContextualArgs<any>} args - An optional `S3BlobStoreServiceConfig`, optionally followed by a decaf `Context`
+     * @return {Promise<{config: S3BlobStoreServiceConfig, client: S3Client}>} The resolved config and the constructed `S3Client`
+     * @throws {InternalError} When a resolved config has no `bucket`
+     */
     initialize(...args: ContextualArgs<any>): Promise<{
         config: S3BlobStoreServiceConfig;
         client: S3Client;

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

@@ -0,0 +1,40 @@
+import { MaybeContextualArg, Service } from "@decaf-ts/core";
+import { CalendarFile, CalendarReminderOptions } from "./types.d.cts";
+import { type ICalendarWriter } from "./writers/ICalendarWriter.d.cts";
+/**
+ * Creates interoperable iCalendar medication reminders.
+ *
+ * The service has no static Node imports, so the same module can be bundled
+ * for browsers. Node-only filesystem behavior is loaded dynamically.
+ */
+export declare class CalendarService extends Service {
+    protected writer: ICalendarWriter;
+    createMedicationReminder(options: CalendarReminderOptions, ...args: MaybeContextualArg<any>): Promise<CalendarFile>;
+    createAndStoreReminder(options: CalendarReminderOptions, ...args: MaybeContextualArg<any>): Promise<void>;
+    private createRecurrence;
+    /**
+     * Converts the commonly needed medication schedules.
+     *
+     * Unsupported cron shapes fall back to explicit RDATE occurrences.
+     */
+    private convertSimpleCronToRRule;
+    private parseSimpleCron;
+    private parseCronField;
+    private expandCronDates;
+    private getFirstOccurrence;
+    private createFoldedRDateLines;
+    private formatUtcDate;
+    private formatLocalDate;
+    private foldLines;
+    /**
+     * RFC 5545 content lines should be folded at 75 octets.
+     */
+    private foldLine;
+    private escapeText;
+    private escapeProperty;
+    private escapeParameter;
+    private weekdayToIcs;
+    private createUid;
+    private createFilename;
+    private validateOptions;
+}

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

@@ -0,0 +1,40 @@
+import { MaybeContextualArg, Service } from "@decaf-ts/core";
+import { CalendarFile, CalendarReminderOptions } from "./types.d.mts";
+import { type ICalendarWriter } from "./writers/ICalendarWriter.d.mts";
+/**
+ * Creates interoperable iCalendar medication reminders.
+ *
+ * The service has no static Node imports, so the same module can be bundled
+ * for browsers. Node-only filesystem behavior is loaded dynamically.
+ */
+export declare class CalendarService extends Service {
+    protected writer: ICalendarWriter;
+    createMedicationReminder(options: CalendarReminderOptions, ...args: MaybeContextualArg<any>): Promise<CalendarFile>;
+    createAndStoreReminder(options: CalendarReminderOptions, ...args: MaybeContextualArg<any>): Promise<void>;
+    private createRecurrence;
+    /**
+     * Converts the commonly needed medication schedules.
+     *
+     * Unsupported cron shapes fall back to explicit RDATE occurrences.
+     */
+    private convertSimpleCronToRRule;
+    private parseSimpleCron;
+    private parseCronField;
+    private expandCronDates;
+    private getFirstOccurrence;
+    private createFoldedRDateLines;
+    private formatUtcDate;
+    private formatLocalDate;
+    private foldLines;
+    /**
+     * RFC 5545 content lines should be folded at 75 octets.
+     */
+    private foldLine;
+    private escapeText;
+    private escapeProperty;
+    private escapeParameter;
+    private weekdayToIcs;
+    private createUid;
+    private createFilename;
+    private validateOptions;
+}

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

@@ -0,0 +1,3 @@
+export * from "./validators/cron.d.cts";
+export * from "./types.d.cts";
+export * from "./CalendarService.d.cts";

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

@@ -0,0 +1,3 @@
+export * from "./validators/cron.d.mts";
+export * from "./types.d.mts";
+export * from "./CalendarService.d.mts";

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

@@ -0,0 +1,64 @@
+export interface CalendarReminderOptions {
+    /**
+     * Standard 5-field cron:
+     * minute hour day-of-month month day-of-week
+     *
+     * Examples:
+     * "0 9 * * *"       Every day at 09:00
+     * "0 9,21 * * *"    Every day at 09:00 and 21:00
+     * "0 9 * * 1-5"     Weekdays at 09:00
+     */
+    cron: string;
+    title: string;
+    description?: string;
+    location?: string;
+    /**
+     * First date from which occurrences should be calculated.
+     * Defaults to now.
+     */
+    start?: Date;
+    /**
+     * IANA timezone, for example:
+     * "Europe/Lisbon"
+     */
+    timezone?: string;
+    /**
+     * Length of each calendar event.
+     * Defaults to 15 minutes.
+     */
+    durationMinutes?: number;
+    /**
+     * Calendar notification before every occurrence.
+     * Defaults to 10 minutes.
+     */
+    alarmMinutesBefore?: number;
+    /**
+     * Maximum number of generated RDATE occurrences when the cron
+     * expression cannot be converted into a single RRULE.
+     */
+    maxOccurrences?: number;
+    /**
+     * Do not generate occurrences after this date.
+     */
+    until?: Date;
+    uid?: string;
+    organizerEmail?: string;
+    attendeeEmail?: string;
+}
+export interface CalendarFile {
+    filename: string;
+    content: string;
+    mimeType: "text/calendar";
+    bytes: Uint8Array;
+}
+export interface ParsedCron {
+    minute: number[];
+    hour: number[];
+    dayOfMonth: number[] | null;
+    month: number[] | null;
+    dayOfWeek: number[] | null;
+}
+export interface RecurrenceResult {
+    rrule?: string;
+    rdates?: Date[];
+}

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

@@ -0,0 +1,64 @@
+export interface CalendarReminderOptions {
+    /**
+     * Standard 5-field cron:
+     * minute hour day-of-month month day-of-week
+     *
+     * Examples:
+     * "0 9 * * *"       Every day at 09:00
+     * "0 9,21 * * *"    Every day at 09:00 and 21:00
+     * "0 9 * * 1-5"     Weekdays at 09:00
+     */
+    cron: string;
+    title: string;
+    description?: string;
+    location?: string;
+    /**
+     * First date from which occurrences should be calculated.
+     * Defaults to now.
+     */
+    start?: Date;
+    /**
+     * IANA timezone, for example:
+     * "Europe/Lisbon"
+     */
+    timezone?: string;
+    /**
+     * Length of each calendar event.
+     * Defaults to 15 minutes.
+     */
+    durationMinutes?: number;
+    /**
+     * Calendar notification before every occurrence.
+     * Defaults to 10 minutes.
+     */
+    alarmMinutesBefore?: number;
+    /**
+     * Maximum number of generated RDATE occurrences when the cron
+     * expression cannot be converted into a single RRULE.
+     */
+    maxOccurrences?: number;
+    /**
+     * Do not generate occurrences after this date.
+     */
+    until?: Date;
+    uid?: string;
+    organizerEmail?: string;
+    attendeeEmail?: string;
+}
+export interface CalendarFile {
+    filename: string;
+    content: string;
+    mimeType: "text/calendar";
+    bytes: Uint8Array;
+}
+export interface ParsedCron {
+    minute: number[];
+    hour: number[];
+    dayOfMonth: number[] | null;
+    month: number[] | null;
+    dayOfWeek: number[] | null;
+}
+export interface RecurrenceResult {
+    rrule?: string;
+    rdates?: Date[];
+}

package/lib/types/calendar/validators/cron.d.cts

@@ -0,0 +1,7 @@
+import { Validator, ValidatorOptions } from "@decaf-ts/decorator-validation";
+export declare const CRON_VALIDATION_ERROR_MESSAGE = "Not a valid cron expression";
+export declare class CronValidator extends Validator {
+    constructor(message?: string);
+    hasErrors(value: string, options?: ValidatorOptions): string | undefined;
+}
+export declare const cron: (message?: string) => (target: object, propKey?: any) => any;

package/lib/types/calendar/validators/cron.d.mts

@@ -0,0 +1,7 @@
+import { Validator, ValidatorOptions } from "@decaf-ts/decorator-validation";
+export declare const CRON_VALIDATION_ERROR_MESSAGE = "Not a valid cron expression";
+export declare class CronValidator extends Validator {
+    constructor(message?: string);
+    hasErrors(value: string, options?: ValidatorOptions): string | undefined;
+}
+export declare const cron: (message?: string) => (target: object, propKey?: any) => any;

package/lib/types/calendar/writers/CalendarFsWriter.d.cts

@@ -0,0 +1,6 @@
+import { ICalendarWriter } from "./ICalendarWriter.d.cts";
+import { CalendarFile } from "../types.d.cts";
+import { Context } from "@decaf-ts/core";
+export declare class FsCalenderWriter implements ICalendarWriter {
+    write(file: CalendarFile, ctx: Context<any>): Promise<CalendarFile>;
+}

package/lib/types/calendar/writers/CalendarFsWriter.d.mts

@@ -0,0 +1,6 @@
+import { ICalendarWriter } from "./ICalendarWriter.d.mts";
+import { CalendarFile } from "../types.d.mts";
+import { Context } from "@decaf-ts/core";
+export declare class FsCalenderWriter implements ICalendarWriter {
+    write(file: CalendarFile, ctx: Context<any>): Promise<CalendarFile>;
+}