@decaf-ts/integrations 0.1.3 → 0.1.4

package/lib/types/blob/core/BlobTypes.d.cts

@@ -0,0 +1,122 @@
+/**
+ * @module integrations/blob/core/types
+ * @summary Blob core types.
+ * @description Shared payload, metadata, option, and configuration types for blob store service implementations.
+ */
+export type BlobProvider = "s3" | "minio" | "r2" | "azure-blob" | "gcs" | "local" | "ipfs" | "memory";
+export type BlobKey = string;
+export type BlobValue = Uint8Array | Buffer | AsyncIterable<Uint8Array> | ReadableStream;
+export interface BlobMetadata {
+    contentType?: string;
+    contentLength?: number;
+    sha256?: string;
+    etag?: string;
+    versionId?: string;
+    cid?: string;
+    custom?: Record<string, string>;
+}
+export interface BlobPutOptions {
+    contentType?: string;
+    metadata?: Record<string, string>;
+    ifNotExists?: boolean;
+    expectedSha256?: string;
+}
+export interface BlobGetOptions {
+    range?: {
+        start: number;
+        end?: number;
+    };
+    versionId?: string;
+}
+export interface BlobListOptions {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface BlobEntry {
+    key: BlobKey;
+    metadata?: BlobMetadata;
+}
+export interface BlobListResult {
+    items: BlobEntry[];
+    cursor?: string;
+}
+export interface BlobPutResult {
+    key: BlobKey;
+    uri: string;
+    provider: BlobProvider;
+    sourceId: string;
+    metadata: BlobMetadata;
+}
+export interface BlobGetResult {
+    key: BlobKey;
+    value: AsyncIterable<Uint8Array>;
+    uri: string;
+    provider: BlobProvider;
+    sourceId: string;
+    metadata: BlobMetadata;
+}
+export interface BlobUrlOptions {
+    operation?: "get" | "put";
+    expiresInSeconds?: number;
+    contentType?: string;
+    metadata?: Record<string, string>;
+}
+export interface BlobUrlResult {
+    url: string;
+    method: "GET" | "PUT";
+    expiresAt: Date;
+    headers?: Record<string, string>;
+}
+export interface BlobStoreServiceConfig {
+    provider: BlobProvider;
+    sourceId: string;
+    prefix?: string;
+    credentialsRef?: string;
+    endpoint?: string;
+    region?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    [key: string]: unknown;
+}
+export interface S3BlobStoreServiceConfig extends BlobStoreServiceConfig {
+    provider: "s3" | "minio" | "r2";
+    bucket: string;
+    forcePathStyle?: boolean;
+    autoCreateBucket?: boolean;
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+}
+export interface AzureBlobStoreServiceConfig extends BlobStoreServiceConfig {
+    provider: "azure-blob";
+    container: string;
+    accountName?: string;
+    connectionString?: string;
+}
+export interface GcsBlobStoreServiceConfig extends BlobStoreServiceConfig {
+    provider: "gcs";
+    bucket: string;
+    projectId?: string;
+    credentials?: Record<string, unknown>;
+    apiEndpoint?: string;
+}
+export interface LocalBlobStoreServiceConfig extends BlobStoreServiceConfig {
+    provider: "local";
+    rootPath: string;
+}
+export interface IpfsKeyIndexConfig {
+    provider: "memory" | "postgres" | "local-json";
+    connectionRef?: string;
+    path?: string;
+}
+export interface IpfsBlobStoreServiceConfig extends BlobStoreServiceConfig {
+    provider: "ipfs";
+    apiUrl?: string;
+    gatewayUrl?: string;
+    pinByDefault?: boolean;
+    encryptedOnly?: boolean;
+    keyIndex: IpfsKeyIndexConfig;
+}

package/lib/types/blob/core/BlobTypes.d.mts

@@ -0,0 +1,122 @@
+/**
+ * @module integrations/blob/core/types
+ * @summary Blob core types.
+ * @description Shared payload, metadata, option, and configuration types for blob store service implementations.
+ */
+export type BlobProvider = "s3" | "minio" | "r2" | "azure-blob" | "gcs" | "local" | "ipfs" | "memory";
+export type BlobKey = string;
+export type BlobValue = Uint8Array | Buffer | AsyncIterable<Uint8Array> | ReadableStream;
+export interface BlobMetadata {
+    contentType?: string;
+    contentLength?: number;
+    sha256?: string;
+    etag?: string;
+    versionId?: string;
+    cid?: string;
+    custom?: Record<string, string>;
+}
+export interface BlobPutOptions {
+    contentType?: string;
+    metadata?: Record<string, string>;
+    ifNotExists?: boolean;
+    expectedSha256?: string;
+}
+export interface BlobGetOptions {
+    range?: {
+        start: number;
+        end?: number;
+    };
+    versionId?: string;
+}
+export interface BlobListOptions {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface BlobEntry {
+    key: BlobKey;
+    metadata?: BlobMetadata;
+}
+export interface BlobListResult {
+    items: BlobEntry[];
+    cursor?: string;
+}
+export interface BlobPutResult {
+    key: BlobKey;
+    uri: string;
+    provider: BlobProvider;
+    sourceId: string;
+    metadata: BlobMetadata;
+}
+export interface BlobGetResult {
+    key: BlobKey;
+    value: AsyncIterable<Uint8Array>;
+    uri: string;
+    provider: BlobProvider;
+    sourceId: string;
+    metadata: BlobMetadata;
+}
+export interface BlobUrlOptions {
+    operation?: "get" | "put";
+    expiresInSeconds?: number;
+    contentType?: string;
+    metadata?: Record<string, string>;
+}
+export interface BlobUrlResult {
+    url: string;
+    method: "GET" | "PUT";
+    expiresAt: Date;
+    headers?: Record<string, string>;
+}
+export interface BlobStoreServiceConfig {
+    provider: BlobProvider;
+    sourceId: string;
+    prefix?: string;
+    credentialsRef?: string;
+    endpoint?: string;
+    region?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    [key: string]: unknown;
+}
+export interface S3BlobStoreServiceConfig extends BlobStoreServiceConfig {
+    provider: "s3" | "minio" | "r2";
+    bucket: string;
+    forcePathStyle?: boolean;
+    autoCreateBucket?: boolean;
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+}
+export interface AzureBlobStoreServiceConfig extends BlobStoreServiceConfig {
+    provider: "azure-blob";
+    container: string;
+    accountName?: string;
+    connectionString?: string;
+}
+export interface GcsBlobStoreServiceConfig extends BlobStoreServiceConfig {
+    provider: "gcs";
+    bucket: string;
+    projectId?: string;
+    credentials?: Record<string, unknown>;
+    apiEndpoint?: string;
+}
+export interface LocalBlobStoreServiceConfig extends BlobStoreServiceConfig {
+    provider: "local";
+    rootPath: string;
+}
+export interface IpfsKeyIndexConfig {
+    provider: "memory" | "postgres" | "local-json";
+    connectionRef?: string;
+    path?: string;
+}
+export interface IpfsBlobStoreServiceConfig extends BlobStoreServiceConfig {
+    provider: "ipfs";
+    apiUrl?: string;
+    gatewayUrl?: string;
+    pinByDefault?: boolean;
+    encryptedOnly?: boolean;
+    keyIndex: IpfsKeyIndexConfig;
+}

package/lib/types/blob/core/BlobValue.d.cts

@@ -0,0 +1,13 @@
+import type { BlobValue } from "./BlobTypes.d.cts";
+/**
+ * Converts any supported BlobValue into an AsyncIterable of Uint8Array chunks.
+ */
+export declare function toAsyncIterable(value: BlobValue): AsyncIterable<Uint8Array>;
+/**
+ * Collects an AsyncIterable of Uint8Array chunks into a single Buffer.
+ */
+export declare function collectToBuffer(value: BlobValue): Promise<Buffer>;
+/**
+ * Computes the sha256 hex digest of a blob value.
+ */
+export declare function computeSha256(value: BlobValue): Promise<string>;

package/lib/types/blob/core/BlobValue.d.mts

@@ -0,0 +1,13 @@
+import type { BlobValue } from "./BlobTypes.d.mts";
+/**
+ * Converts any supported BlobValue into an AsyncIterable of Uint8Array chunks.
+ */
+export declare function toAsyncIterable(value: BlobValue): AsyncIterable<Uint8Array>;
+/**
+ * Collects an AsyncIterable of Uint8Array chunks into a single Buffer.
+ */
+export declare function collectToBuffer(value: BlobValue): Promise<Buffer>;
+/**
+ * Computes the sha256 hex digest of a blob value.
+ */
+export declare function computeSha256(value: BlobValue): Promise<string>;

package/lib/types/blob/core/index.d.cts

@@ -0,0 +1,11 @@
+/**
+ * @module integrations/blob/core
+ * @summary Blob core exports.
+ * @description Re-exports the blob store core types, errors, key/value helpers, service abstraction, and factory.
+ */
+export * from "./BlobTypes.d.cts";
+export * from "./BlobErrors.d.cts";
+export * from "./BlobKey.d.cts";
+export * from "./BlobValue.d.cts";
+export * from "./BlobStoreService.d.cts";
+export * from "./BlobStoreFactory.d.cts";

package/lib/types/blob/core/index.d.mts

@@ -0,0 +1,11 @@
+/**
+ * @module integrations/blob/core
+ * @summary Blob core exports.
+ * @description Re-exports the blob store core types, errors, key/value helpers, service abstraction, and factory.
+ */
+export * from "./BlobTypes.d.mts";
+export * from "./BlobErrors.d.mts";
+export * from "./BlobKey.d.mts";
+export * from "./BlobValue.d.mts";
+export * from "./BlobStoreService.d.mts";
+export * from "./BlobStoreFactory.d.mts";

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

@@ -0,0 +1,25 @@
+/**
+ * @module integrations/blob/gcp/service
+ * @summary Google Cloud Storage blob store service.
+ * @description Blob store backed by Google Cloud Storage via @google-cloud/storage.
+ */
+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";
+export declare class GcsBlobStoreService extends BlobStoreService<Bucket, GcsBlobStoreServiceConfig> {
+    private storage;
+    initialize(...args: ContextualArgs<any>): Promise<{
+        config: GcsBlobStoreServiceConfig;
+        client: Bucket;
+    }>;
+    put(key: BlobKey, value: BlobValue, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
+    get(key: BlobKey, options?: BlobGetOptions, ...args: MaybeContextualArg<any>): Promise<BlobGetResult>;
+    has(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<boolean>;
+    stat(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<BlobMetadata>;
+    delete(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<void>;
+    copy(fromKey: BlobKey, toKey: BlobKey, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
+    list(options?: BlobListOptions, ...args: MaybeContextualArg<any>): Promise<BlobListResult>;
+    url(key: BlobKey, options?: BlobUrlOptions, ...args: MaybeContextualArg<any>): Promise<BlobUrlResult>;
+    protected parseError(error: unknown): Error;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * @module integrations/blob/gcp/service
+ * @summary Google Cloud Storage blob store service.
+ * @description Blob store backed by Google Cloud Storage via @google-cloud/storage.
+ */
+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";
+export declare class GcsBlobStoreService extends BlobStoreService<Bucket, GcsBlobStoreServiceConfig> {
+    private storage;
+    initialize(...args: ContextualArgs<any>): Promise<{
+        config: GcsBlobStoreServiceConfig;
+        client: Bucket;
+    }>;
+    put(key: BlobKey, value: BlobValue, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
+    get(key: BlobKey, options?: BlobGetOptions, ...args: MaybeContextualArg<any>): Promise<BlobGetResult>;
+    has(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<boolean>;
+    stat(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<BlobMetadata>;
+    delete(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<void>;
+    copy(fromKey: BlobKey, toKey: BlobKey, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
+    list(options?: BlobListOptions, ...args: MaybeContextualArg<any>): Promise<BlobListResult>;
+    url(key: BlobKey, options?: BlobUrlOptions, ...args: MaybeContextualArg<any>): Promise<BlobUrlResult>;
+    protected parseError(error: unknown): Error;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/blob/gcp
+ * @summary Google Cloud Storage blob store exports.
+ * @description Re-exports the GCS blob store service.
+ */
+export * from "./GcsBlobStoreService.d.cts";

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

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/blob/gcp
+ * @summary Google Cloud Storage blob store exports.
+ * @description Re-exports the GCS blob store service.
+ */
+export * from "./GcsBlobStoreService.d.mts";

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

@@ -0,0 +1,7 @@
+/**
+ * @module integrations/blob
+ * @summary Blob store management helpers for the integrations package.
+ * @description Re-exports the blob store core abstractions only. Provider implementations are exported
+ * through their own subpaths so the core entry does not eagerly load optional provider SDKs.
+ */
+export * from "./core/index.d.cts";

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

@@ -0,0 +1,7 @@
+/**
+ * @module integrations/blob
+ * @summary Blob store management helpers for the integrations package.
+ * @description Re-exports the blob store core abstractions only. Provider implementations are exported
+ * through their own subpaths so the core entry does not eagerly load optional provider SDKs.
+ */
+export * from "./core/index.d.mts";

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

@@ -0,0 +1,26 @@
+/**
+ * @module integrations/blob/ipfs/service
+ * @summary IPFS blob store service.
+ * @description Blob store backed by an IPFS (Kubo) node. Because the blob API is key/value CRUD-like
+ * and IPFS is content-addressed, an IpfsKeyIndex maps logical keys to CIDs.
+ */
+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";
+export declare class IpfsBlobStoreService extends BlobStoreService<KuboRPCClient, IpfsBlobStoreServiceConfig> {
+    private index;
+    initialize(...args: ContextualArgs<any>): Promise<{
+        config: IpfsBlobStoreServiceConfig;
+        client: KuboRPCClient;
+    }>;
+    put(key: BlobKey, value: BlobValue, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
+    get(key: BlobKey, options?: BlobGetOptions, ...args: MaybeContextualArg<any>): Promise<BlobGetResult>;
+    has(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<boolean>;
+    stat(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<BlobMetadata>;
+    delete(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<void>;
+    copy(fromKey: BlobKey, toKey: BlobKey, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
+    list(options?: BlobListOptions, ...args: MaybeContextualArg<any>): Promise<BlobListResult>;
+    url(key: BlobKey, options?: BlobUrlOptions, ...args: MaybeContextualArg<any>): Promise<BlobUrlResult>;
+    protected parseError(error: unknown): Error;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * @module integrations/blob/ipfs/service
+ * @summary IPFS blob store service.
+ * @description Blob store backed by an IPFS (Kubo) node. Because the blob API is key/value CRUD-like
+ * and IPFS is content-addressed, an IpfsKeyIndex maps logical keys to CIDs.
+ */
+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";
+export declare class IpfsBlobStoreService extends BlobStoreService<KuboRPCClient, IpfsBlobStoreServiceConfig> {
+    private index;
+    initialize(...args: ContextualArgs<any>): Promise<{
+        config: IpfsBlobStoreServiceConfig;
+        client: KuboRPCClient;
+    }>;
+    put(key: BlobKey, value: BlobValue, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
+    get(key: BlobKey, options?: BlobGetOptions, ...args: MaybeContextualArg<any>): Promise<BlobGetResult>;
+    has(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<boolean>;
+    stat(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<BlobMetadata>;
+    delete(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<void>;
+    copy(fromKey: BlobKey, toKey: BlobKey, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
+    list(options?: BlobListOptions, ...args: MaybeContextualArg<any>): Promise<BlobListResult>;
+    url(key: BlobKey, options?: BlobUrlOptions, ...args: MaybeContextualArg<any>): Promise<BlobUrlResult>;
+    protected parseError(error: unknown): Error;
+}

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

@@ -0,0 +1,9 @@
+import type { BlobListResult, BlobMetadata, IpfsKeyIndexConfig } from "../core/BlobTypes.d.cts";
+export interface IpfsKeyIndex {
+    get(key: string): Promise<string | undefined>;
+    set(key: string, cid: string, metadata?: BlobMetadata): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string, limit?: number, cursor?: string): Promise<BlobListResult>;
+    stat(key: string): Promise<BlobMetadata>;
+}
+export declare function createIpfsKeyIndex(config: IpfsKeyIndexConfig): IpfsKeyIndex;

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

@@ -0,0 +1,9 @@
+import type { BlobListResult, BlobMetadata, IpfsKeyIndexConfig } from "../core/BlobTypes.d.mts";
+export interface IpfsKeyIndex {
+    get(key: string): Promise<string | undefined>;
+    set(key: string, cid: string, metadata?: BlobMetadata): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string, limit?: number, cursor?: string): Promise<BlobListResult>;
+    stat(key: string): Promise<BlobMetadata>;
+}
+export declare function createIpfsKeyIndex(config: IpfsKeyIndexConfig): IpfsKeyIndex;

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

@@ -0,0 +1,11 @@
+import type { BlobListResult, BlobMetadata } from "../core/BlobTypes.d.cts";
+import type { IpfsKeyIndex } from "./IpfsKeyIndex.d.cts";
+export declare class LocalJsonIpfsKeyIndex implements IpfsKeyIndex {
+    private readonly path;
+    constructor(path: string);
+    get(key: string): Promise<string | undefined>;
+    set(key: string, cid: string, metadata?: BlobMetadata): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string, limit?: number, cursor?: string): Promise<BlobListResult>;
+    stat(key: string): Promise<BlobMetadata>;
+}

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

@@ -0,0 +1,11 @@
+import type { BlobListResult, BlobMetadata } from "../core/BlobTypes.d.mts";
+import type { IpfsKeyIndex } from "./IpfsKeyIndex.d.mts";
+export declare class LocalJsonIpfsKeyIndex implements IpfsKeyIndex {
+    private readonly path;
+    constructor(path: string);
+    get(key: string): Promise<string | undefined>;
+    set(key: string, cid: string, metadata?: BlobMetadata): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string, limit?: number, cursor?: string): Promise<BlobListResult>;
+    stat(key: string): Promise<BlobMetadata>;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * @module integrations/blob/ipfs/memory-index
+ * @summary In-memory IPFS key index.
+ * @description Process-local Map-backed key index for tests and examples.
+ */
+import type { BlobListResult, BlobMetadata } from "../core/BlobTypes.d.cts";
+import type { IpfsKeyIndex } from "./IpfsKeyIndex.d.cts";
+export declare class MemoryIpfsKeyIndex implements IpfsKeyIndex {
+    private readonly values;
+    get(key: string): Promise<string | undefined>;
+    set(key: string, cid: string, metadata?: BlobMetadata): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string, limit?: number, cursor?: string): Promise<BlobListResult>;
+    stat(key: string): Promise<BlobMetadata>;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * @module integrations/blob/ipfs/memory-index
+ * @summary In-memory IPFS key index.
+ * @description Process-local Map-backed key index for tests and examples.
+ */
+import type { BlobListResult, BlobMetadata } from "../core/BlobTypes.d.mts";
+import type { IpfsKeyIndex } from "./IpfsKeyIndex.d.mts";
+export declare class MemoryIpfsKeyIndex implements IpfsKeyIndex {
+    private readonly values;
+    get(key: string): Promise<string | undefined>;
+    set(key: string, cid: string, metadata?: BlobMetadata): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string, limit?: number, cursor?: string): Promise<BlobListResult>;
+    stat(key: string): Promise<BlobMetadata>;
+}

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

@@ -0,0 +1,11 @@
+import type { BlobListResult, BlobMetadata } from "../core/BlobTypes.d.cts";
+import type { IpfsKeyIndex } from "./IpfsKeyIndex.d.cts";
+export declare class PostgresIpfsKeyIndex implements IpfsKeyIndex {
+    private readonly connectionRef;
+    constructor(connectionRef: string);
+    get(key: string): Promise<string | undefined>;
+    set(key: string, cid: string, metadata?: BlobMetadata): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string, limit?: number, cursor?: string): Promise<BlobListResult>;
+    stat(key: string): Promise<BlobMetadata>;
+}

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

@@ -0,0 +1,11 @@
+import type { BlobListResult, BlobMetadata } from "../core/BlobTypes.d.mts";
+import type { IpfsKeyIndex } from "./IpfsKeyIndex.d.mts";
+export declare class PostgresIpfsKeyIndex implements IpfsKeyIndex {
+    private readonly connectionRef;
+    constructor(connectionRef: string);
+    get(key: string): Promise<string | undefined>;
+    set(key: string, cid: string, metadata?: BlobMetadata): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string, limit?: number, cursor?: string): Promise<BlobListResult>;
+    stat(key: string): Promise<BlobMetadata>;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * @module integrations/blob/ipfs
+ * @summary IPFS blob store exports.
+ * @description Re-exports the IPFS blob store service and key-index abstraction.
+ */
+export * from "./IpfsBlobStoreService.d.cts";
+export * from "./IpfsKeyIndex.d.cts";
+export * from "./MemoryIpfsKeyIndex.d.cts";
+export * from "./PostgresIpfsKeyIndex.d.cts";
+export * from "./LocalJsonIpfsKeyIndex.d.cts";

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

@@ -0,0 +1,10 @@
+/**
+ * @module integrations/blob/ipfs
+ * @summary IPFS blob store exports.
+ * @description Re-exports the IPFS blob store service and key-index abstraction.
+ */
+export * from "./IpfsBlobStoreService.d.mts";
+export * from "./IpfsKeyIndex.d.mts";
+export * from "./MemoryIpfsKeyIndex.d.mts";
+export * from "./PostgresIpfsKeyIndex.d.mts";
+export * from "./LocalJsonIpfsKeyIndex.d.mts";

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

@@ -0,0 +1,30 @@
+/**
+ * @module integrations/blob/local/service
+ * @summary Local filesystem blob store service.
+ * @description Filesystem-backed blob store wrapping node:fs with atomic writes and path-traversal protection.
+ */
+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, LocalBlobStoreServiceConfig } from "../core/BlobTypes.d.cts";
+interface LocalFsClient {
+    root: string;
+}
+export declare class LocalBlobStoreService extends BlobStoreService<LocalFsClient, LocalBlobStoreServiceConfig> {
+    initialize(...args: ContextualArgs<any>): Promise<{
+        config: LocalBlobStoreServiceConfig;
+        client: LocalFsClient;
+    }>;
+    put(key: BlobKey, value: BlobValue, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
+    get(key: BlobKey, options?: BlobGetOptions, ...args: MaybeContextualArg<any>): Promise<BlobGetResult>;
+    has(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<boolean>;
+    stat(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<BlobMetadata>;
+    delete(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<void>;
+    copy(fromKey: BlobKey, toKey: BlobKey, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
+    list(options?: BlobListOptions, ...args: MaybeContextualArg<any>): Promise<BlobListResult>;
+    url(key: BlobKey, options?: BlobUrlOptions, ...args: MaybeContextualArg<any>): Promise<BlobUrlResult>;
+    protected parseError(error: unknown): Error;
+    private safePath;
+    private safeStat;
+    private atomicWrite;
+}
+export {};

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

@@ -0,0 +1,30 @@
+/**
+ * @module integrations/blob/local/service
+ * @summary Local filesystem blob store service.
+ * @description Filesystem-backed blob store wrapping node:fs with atomic writes and path-traversal protection.
+ */
+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, LocalBlobStoreServiceConfig } from "../core/BlobTypes.d.mts";
+interface LocalFsClient {
+    root: string;
+}
+export declare class LocalBlobStoreService extends BlobStoreService<LocalFsClient, LocalBlobStoreServiceConfig> {
+    initialize(...args: ContextualArgs<any>): Promise<{
+        config: LocalBlobStoreServiceConfig;
+        client: LocalFsClient;
+    }>;
+    put(key: BlobKey, value: BlobValue, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
+    get(key: BlobKey, options?: BlobGetOptions, ...args: MaybeContextualArg<any>): Promise<BlobGetResult>;
+    has(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<boolean>;
+    stat(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<BlobMetadata>;
+    delete(key: BlobKey, ...args: MaybeContextualArg<any>): Promise<void>;
+    copy(fromKey: BlobKey, toKey: BlobKey, options?: BlobPutOptions, ...args: MaybeContextualArg<any>): Promise<BlobPutResult>;
+    list(options?: BlobListOptions, ...args: MaybeContextualArg<any>): Promise<BlobListResult>;
+    url(key: BlobKey, options?: BlobUrlOptions, ...args: MaybeContextualArg<any>): Promise<BlobUrlResult>;
+    protected parseError(error: unknown): Error;
+    private safePath;
+    private safeStat;
+    private atomicWrite;
+}
+export {};

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

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/blob/local
+ * @summary Local filesystem blob store exports.
+ * @description Re-exports the local filesystem blob store service.
+ */
+export * from "./LocalBlobStoreService.d.cts";

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

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/blob/local
+ * @summary Local filesystem blob store exports.
+ * @description Re-exports the local filesystem blob store service.
+ */
+export * from "./LocalBlobStoreService.d.mts";