@bcts/hubert 1.0.0-alpha.17

package/dist/index-CY3TCzIm.d.cts

@@ -0,0 +1,217 @@
+import { r as HubertError, t as KvStore } from "./kv-store-ww-AUyLd.cjs";
+import { ARID } from "@bcts/components";
+import { Envelope } from "@bcts/envelope";
+
+//#region src/hybrid/error.d.ts
+/**
+ * Base class for Hybrid-specific errors.
+ *
+ * @category Hybrid
+ */
+declare class HybridError extends HubertError {
+  constructor(message: string);
+}
+/**
+ * Referenced IPFS content not found.
+ *
+ * Port of `Error::ContentNotFound` from hybrid/error.rs line 4-5.
+ *
+ * @category Hybrid
+ */
+declare class ContentNotFoundError extends HybridError {
+  constructor();
+}
+/**
+ * Not a reference envelope.
+ *
+ * Port of `Error::NotReferenceEnvelope` from hybrid/error.rs line 7-8.
+ *
+ * @category Hybrid
+ */
+declare class NotReferenceEnvelopeError extends HybridError {
+  constructor();
+}
+/**
+ * Invalid ARID in reference envelope.
+ *
+ * Port of `Error::InvalidReferenceArid` from hybrid/error.rs line 10-11.
+ *
+ * @category Hybrid
+ */
+declare class InvalidReferenceAridError extends HybridError {
+  constructor();
+}
+/**
+ * No id assertion found in reference envelope.
+ *
+ * Port of `Error::NoIdAssertion` from hybrid/error.rs line 13-14.
+ *
+ * @category Hybrid
+ */
+declare class NoIdAssertionError extends HybridError {
+  constructor();
+}
+//#endregion
+//#region src/hybrid/reference.d.ts
+/**
+ * Creates a reference envelope that points to content stored in IPFS.
+ *
+ * Reference envelopes are small envelopes stored in the DHT that contain
+ * a pointer to the actual envelope stored in IPFS. This allows the hybrid
+ * storage layer to transparently handle large envelopes that exceed the
+ * DHT size limit.
+ *
+ * Port of `create_reference_envelope()` from hybrid/reference.rs lines 31-39.
+ *
+ * # Format
+ *
+ * ```text
+ * '' [
+ *     'dereferenceVia': "ipfs",
+ *     'id': <ARID>,
+ *     "size": <number>
+ * ]
+ * ```
+ *
+ * @param referenceArid - The ARID used to look up the actual envelope in IPFS
+ * @param actualSize - Size of the actual envelope in bytes (for diagnostics)
+ * @returns A reference envelope that can be stored in the DHT
+ *
+ * @category Hybrid
+ */
+declare function createReferenceEnvelope(referenceArid: ARID, actualSize: number): Envelope;
+/**
+ * Checks if an envelope is a reference envelope.
+ *
+ * A reference envelope contains `dereferenceVia: "ipfs"` and an `id` assertion.
+ *
+ * Port of `is_reference_envelope()` from hybrid/reference.rs lines 53-91.
+ *
+ * @param envelope - The envelope to check
+ * @returns `true` if this is a reference envelope, `false` otherwise
+ *
+ * @category Hybrid
+ */
+declare function isReferenceEnvelope(envelope: Envelope): boolean;
+/**
+ * Extracts the reference ARID from a reference envelope.
+ *
+ * Port of `extract_reference_arid()` from hybrid/reference.rs lines 104-129.
+ *
+ * @param envelope - The reference envelope
+ * @returns The reference ARID
+ * @throws {NotReferenceEnvelopeError} If the envelope is not a reference envelope
+ * @throws {InvalidReferenceAridError} If the ARID cannot be extracted
+ * @throws {NoIdAssertionError} If no id assertion is found
+ *
+ * @category Hybrid
+ */
+declare function extractReferenceArid(envelope: Envelope): ARID;
+//#endregion
+//#region src/hybrid/kv.d.ts
+/**
+ * Hybrid storage layer combining Mainline DHT and IPFS.
+ *
+ * Automatically optimizes storage based on envelope size:
+ * - **Small envelopes (≤1000 bytes)**: Stored directly in DHT
+ * - **Large envelopes (>1000 bytes)**: Reference in DHT → actual envelope in IPFS
+ *
+ * This provides the best of both worlds:
+ * - Fast lookups for small messages via DHT
+ * - Large capacity for big messages via IPFS
+ * - Transparent indirection handled automatically
+ *
+ * Port of `struct HybridKv` from hybrid/kv.rs lines 59-63.
+ *
+ * # Requirements
+ *
+ * - No external daemon for DHT (embedded client)
+ * - Requires Kubo daemon for IPFS (http://127.0.0.1:5001)
+ *
+ * @category Hybrid Backend
+ *
+ * @example
+ * ```typescript
+ * const store = await HybridKv.create("http://127.0.0.1:5001");
+ *
+ * // Small envelope → DHT only
+ * const arid1 = ARID.new();
+ * const small = Envelope.new("Small message");
+ * await store.put(arid1, small);
+ *
+ * // Large envelope → DHT reference + IPFS
+ * const arid2 = ARID.new();
+ * const large = Envelope.new("x".repeat(2000));
+ * await store.put(arid2, large);
+ *
+ * // Get works the same for both
+ * const retrieved1 = await store.get(arid1);
+ * const retrieved2 = await store.get(arid2);
+ * ```
+ */
+declare class HybridKv implements KvStore {
+  private readonly dht;
+  private ipfs;
+  private dhtSizeLimit;
+  /**
+   * Private constructor - use `create()` factory method.
+   */
+  private constructor();
+  /**
+   * Create a new Hybrid KV store with default settings.
+   *
+   * Port of `HybridKv::new()` from hybrid/kv.rs lines 75-84.
+   *
+   * @param ipfsRpcUrl - IPFS RPC endpoint (e.g., "http://127.0.0.1:5001")
+   */
+  static create(ipfsRpcUrl: string): Promise<HybridKv>;
+  /**
+   * Set custom DHT size limit (default: 1000 bytes).
+   *
+   * Envelopes larger than this will use IPFS indirection.
+   *
+   * Port of `HybridKv::with_dht_size_limit()` from hybrid/kv.rs lines 89-92.
+   */
+  withDhtSizeLimit(limit: number): this;
+  /**
+   * Set whether to pin content in IPFS (default: false).
+   *
+   * Only affects envelopes stored in IPFS (when larger than DHT limit).
+   *
+   * Port of `HybridKv::with_pin_content()` from hybrid/kv.rs lines 97-100.
+   */
+  withPinContent(pin: boolean): this;
+  /**
+   * Check if an envelope fits in the DHT.
+   *
+   * Port of `HybridKv::fits_in_dht()` from hybrid/kv.rs lines 103-106.
+   *
+   * @internal
+   */
+  private fitsInDht;
+  /**
+   * Store an envelope at the given ARID.
+   *
+   * Port of `KvStore::put()` implementation from hybrid/kv.rs lines 109-168.
+   */
+  put(arid: ARID, envelope: Envelope, ttlSeconds?: number, verbose?: boolean): Promise<string>;
+  /**
+   * Retrieve an envelope for the given ARID.
+   *
+   * Port of `KvStore::get()` implementation from hybrid/kv.rs lines 171-230.
+   */
+  get(arid: ARID, timeoutSeconds?: number, verbose?: boolean): Promise<Envelope | null>;
+  /**
+   * Check if an envelope exists at the given ARID.
+   *
+   * Port of `KvStore::exists()` implementation from hybrid/kv.rs lines 254-257.
+   */
+  exists(arid: ARID): Promise<boolean>;
+  /**
+   * Destroy the hybrid store and release resources.
+   */
+  destroy(): Promise<void>;
+}
+//#endregion
+export { ContentNotFoundError as a, NoIdAssertionError as c, isReferenceEnvelope as i, NotReferenceEnvelopeError as l, createReferenceEnvelope as n, HybridError as o, extractReferenceArid as r, InvalidReferenceAridError as s, HybridKv as t };
+//# sourceMappingURL=index-CY3TCzIm.d.cts.map

package/dist/index-CY3TCzIm.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-CY3TCzIm.d.cts","names":[],"sources":["../src/hybrid/error.ts","../src/hybrid/reference.ts","../src/hybrid/kv.ts"],"mappings":";;;;;;;;;;cAea,WAAA,SAAoB,WAAA;cACnB,OAAA;AAAA;;;;AA2Bd;;;;cAda,oBAAA,SAA6B,WAAA;EAAA,WAAA,CAAA;AAAA;;;;AA0C1C;;;;cA5Ba,yBAAA,SAAkC,WAAA;EAAA,WAAA,CAAA;AAAA;;ACa/C;;;;;;cDCa,yBAAA,SAAkC,WAAA;EAAA,WAAA,CAAA;AAAA;;ACkB/C;;;;;AAyDA;cD7Da,kBAAA,SAA2B,WAAA;EAAA,WAAA,CAAA;AAAA;;;;;;;;AA1CxC;;;;;AAcA;;;;;AAcA;;;;;AAcA;;;;;;iBCfgB,uBAAA,CAAwB,aAAA,EAAe,IAAA,EAAM,UAAA,WAAqB,QAAA;;AAAlF;;;;;;;;;;AAmBA;iBAAgB,mBAAA,CAAoB,QAAA,EAAU,QAAA;;;;AAyD9C;;;;;;;;;;iBAAgB,oBAAA,CAAqB,QAAA,EAAU,QAAA,GAAW,IAAA;;;;;;;ADvG1D;;;;;AAcA;;;;;AAcA;;;;;AAcA;;;;;;;;ACfA;;;;;;;;;;AAmBA;;;cCjBa,QAAA,YAAoB,OAAA;EAAA,iBACd,GAAA;EAAA,QACT,IAAA;EAAA,QACA,YAAA;;;;UAKD,WAAA,CAAA;EDkEiD;;;;;;AC1E1D;ED0E0D,OCrD3C,MAAA,CAAO,UAAA,WAAqB,OAAA,CAAQ,QAAA;;;;;;;;EAcjD,gBAAA,CAAiB,KAAA;EAoFkD;;;;;;;EAxEnE,cAAA,CAAe,GAAA;EA9CE;;;;;;;EAAA,QA0DT,SAAA;EAxBR;;;;;EAkCM,GAAA,CACJ,IAAA,EAAM,IAAA,EACN,QAAA,EAAU,QAAA,EACV,UAAA,WACA,OAAA,aACC,OAAA;EAJK;;;;;EAiDF,GAAA,CAAI,IAAA,EAAM,IAAA,EAAM,cAAA,WAAyB,OAAA,aAAoB,OAAA,CAAQ,QAAA;EA7CxE;;;;;EA4FG,MAAA,CAAO,IAAA,EAAM,IAAA,GAAO,OAAA;EA/CyC;;;EAuD7D,OAAA,CAAA,GAAW,OAAA;AAAA"}

package/dist/index-DEr4SR1J.d.cts

@@ -0,0 +1,215 @@
+import { r as HubertError, t as KvStore } from "./kv-store-ww-AUyLd.cjs";
+import { ARID } from "@bcts/components";
+import { Envelope } from "@bcts/envelope";
+import { KuboRPCClient } from "kubo-rpc-client";
+
+//#region src/ipfs/error.d.ts
+/**
+ * Base class for IPFS-specific errors.
+ *
+ * @category IPFS
+ */
+declare class IpfsError extends HubertError {
+  constructor(message: string);
+}
+/**
+ * Envelope size exceeds practical limit.
+ *
+ * Port of `Error::EnvelopeTooLarge { size }` from ipfs/error.rs line 5.
+ *
+ * @category IPFS
+ */
+declare class EnvelopeTooLargeError extends IpfsError {
+  readonly size: number;
+  constructor(size: number);
+}
+/**
+ * IPFS daemon error.
+ *
+ * Port of `Error::DaemonError` from ipfs/error.rs line 8.
+ *
+ * @category IPFS
+ */
+declare class IpfsDaemonError extends IpfsError {
+  constructor(message: string);
+}
+/**
+ * Operation timed out.
+ *
+ * Port of `Error::Timeout` from ipfs/error.rs line 11.
+ *
+ * @category IPFS
+ */
+declare class IpfsTimeoutError extends IpfsError {
+  constructor();
+}
+/**
+ * Unexpected IPNS path format.
+ *
+ * Port of `Error::UnexpectedIpnsPathFormat` from ipfs/error.rs line 14.
+ *
+ * @category IPFS
+ */
+declare class UnexpectedIpnsPathFormatError extends IpfsError {
+  readonly path: string;
+  constructor(path: string);
+}
+//#endregion
+//#region src/ipfs/value.d.ts
+/**
+ * Add (upload) bytes to IPFS and return the CID.
+ *
+ * Port of `add_bytes()` from ipfs/value.rs lines 9-15.
+ *
+ * @param client - Kubo RPC client
+ * @param bytes - Data to add
+ * @returns CID of the added content
+ *
+ * @category IPFS
+ */
+declare function addBytes(client: KuboRPCClient, bytes: Uint8Array): Promise<string>;
+/**
+ * Cat (download) bytes from IPFS by CID.
+ *
+ * Port of `cat_bytes()` from ipfs/value.rs lines 18-28.
+ *
+ * @param client - Kubo RPC client
+ * @param cid - Content identifier
+ * @returns Content bytes
+ *
+ * @category IPFS
+ */
+declare function catBytes(client: KuboRPCClient, cid: string): Promise<Uint8Array>;
+/**
+ * Pin a CID to ensure it persists in local IPFS storage.
+ *
+ * Port of `pin_cid()` from ipfs/value.rs lines 31-38.
+ *
+ * @param client - Kubo RPC client
+ * @param cid - Content identifier to pin
+ * @param recursive - Whether to recursively pin linked content
+ *
+ * @category IPFS
+ */
+declare function pinCid(client: KuboRPCClient, cid: string, recursive: boolean): Promise<void>;
+//#endregion
+//#region src/ipfs/kv.d.ts
+/**
+ * IPFS-backed key-value store using IPNS for ARID-based addressing.
+ *
+ * This implementation uses:
+ * - ARID → IPNS key name derivation (deterministic)
+ * - IPFS content addressing (CID) for immutable storage
+ * - IPNS for publish-once mutable names
+ * - Write-once semantics (publish fails if name already exists)
+ *
+ * Port of `struct IpfsKv` from ipfs/kv.rs lines 54-60.
+ *
+ * # Requirements
+ *
+ * Requires a running Kubo daemon (or compatible IPFS node) with RPC API
+ * available at the configured endpoint (default: http://127.0.0.1:5001).
+ *
+ * @category IPFS Backend
+ *
+ * @example
+ * ```typescript
+ * const store = new IpfsKv("http://127.0.0.1:5001");
+ * const arid = ARID.new();
+ * const envelope = Envelope.new("Hello, IPFS!");
+ *
+ * // Put envelope (write-once)
+ * await store.put(arid, envelope);
+ *
+ * // Get envelope with verbose logging
+ * const retrieved = await store.get(arid, undefined, true);
+ * ```
+ */
+declare class IpfsKv implements KvStore {
+  private readonly client;
+  private readonly keyCache;
+  private maxEnvelopeSize;
+  private resolveTimeoutMs;
+  private pinContent;
+  /**
+   * Create a new IPFS KV store with default settings.
+   *
+   * Port of `IpfsKv::new()` from ipfs/kv.rs lines 73-81.
+   *
+   * @param rpcUrl - IPFS RPC endpoint (e.g., "http://127.0.0.1:5001")
+   */
+  constructor(rpcUrl: string);
+  /**
+   * Set the maximum envelope size (default: 10 MB).
+   *
+   * Port of `IpfsKv::with_max_size()` from ipfs/kv.rs lines 84-87.
+   */
+  withMaxSize(size: number): this;
+  /**
+   * Set the IPNS resolve timeout (default: 30 seconds).
+   *
+   * Port of `IpfsKv::with_resolve_timeout()` from ipfs/kv.rs lines 90-93.
+   *
+   * @param timeoutMs - Timeout in milliseconds
+   */
+  withResolveTimeout(timeoutMs: number): this;
+  /**
+   * Set whether to pin content (default: false).
+   *
+   * Port of `IpfsKv::with_pin_content()` from ipfs/kv.rs lines 96-99.
+   */
+  withPinContent(pin: boolean): this;
+  /**
+   * Get or create an IPNS key for the given ARID.
+   *
+   * Port of `IpfsKv::get_or_create_key()` from ipfs/kv.rs lines 102-142.
+   *
+   * @internal
+   */
+  private getOrCreateKey;
+  /**
+   * Check if an IPNS name is already published.
+   *
+   * Port of `IpfsKv::is_published()` from ipfs/kv.rs lines 145-161.
+   *
+   * @internal
+   */
+  private isPublished;
+  /**
+   * Publish a CID to an IPNS name (write-once).
+   *
+   * Port of `IpfsKv::publish_once()` from ipfs/kv.rs lines 164-204.
+   *
+   * @internal
+   */
+  private publishOnce;
+  /**
+   * Resolve an IPNS name to a CID with polling and custom timeout.
+   *
+   * Port of `IpfsKv::resolve_with_retry_timeout()` from ipfs/kv.rs lines 207-258.
+   *
+   * @internal
+   */
+  private resolveWithRetryTimeout;
+  /**
+   * Store an envelope at the given ARID.
+   *
+   * Port of `KvStore::put()` implementation from ipfs/kv.rs lines 289-367.
+   */
+  put(arid: ARID, envelope: Envelope, ttlSeconds?: number, verbose?: boolean): Promise<string>;
+  /**
+   * Retrieve an envelope for the given ARID.
+   *
+   * Port of `KvStore::get()` implementation from ipfs/kv.rs lines 370-450.
+   */
+  get(arid: ARID, timeoutSeconds?: number, verbose?: boolean): Promise<Envelope | null>;
+  /**
+   * Check if an envelope exists at the given ARID.
+   *
+   * Port of `KvStore::exists()` implementation from ipfs/kv.rs lines 453-481.
+   */
+  exists(arid: ARID): Promise<boolean>;
+}
+//#endregion
+export { EnvelopeTooLargeError as a, IpfsTimeoutError as c, pinCid as i, UnexpectedIpnsPathFormatError as l, addBytes as n, IpfsDaemonError as o, catBytes as r, IpfsError as s, IpfsKv as t };
+//# sourceMappingURL=index-DEr4SR1J.d.cts.map

package/dist/index-DEr4SR1J.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-DEr4SR1J.d.cts","names":[],"sources":["../src/ipfs/error.ts","../src/ipfs/value.ts","../src/ipfs/kv.ts"],"mappings":";;;;;;;;;;;cAea,SAAA,SAAkB,WAAA;cACjB,OAAA;AAAA;;;;;;;;cAaD,qBAAA,SAA8B,SAAA;EAAA,SAChC,IAAA;cAEG,IAAA;AAAA;;;;;;;;cAcD,eAAA,SAAwB,SAAA;cACvB,OAAA;AAAA;;;AA2Bd;;;;;cAda,gBAAA,SAAyB,SAAA;EAAA,WAAA,CAAA;AAAA;;;;;;ACrCtC;;cDmDa,6BAAA,SAAsC,SAAA;EAAA,SACxC,IAAA;cAEG,IAAA;AAAA;;;;;;;;;;AAhDd;;;;iBCNsB,QAAA,CAAS,MAAA,EAAQ,aAAA,EAAe,KAAA,EAAO,UAAA,GAAa,OAAA;;;;;;ADuB1E;;;;;;iBCHsB,QAAA,CAAS,MAAA,EAAQ,aAAA,EAAe,GAAA,WAAc,OAAA,CAAQ,UAAA;;;ADiB5E;;;;;AAcA;;;;iBCAsB,MAAA,CACpB,MAAA,EAAQ,aAAA,EACR,GAAA,UACA,SAAA,YACC,OAAA;;;;;;;;ADjDH;;;;;;;;;;AAiBA;;;;;;;;;AAcA;;;;;AAcA;;cEVa,MAAA,YAAkB,OAAA;EAAA,iBACZ,MAAA;EAAA,iBACA,QAAA;EAAA,QACT,eAAA;EAAA,QACA,gBAAA;EAAA,QACA,UAAA;EFQgB;;;;;ACtD1B;;cCuDc,MAAA;EDvDyB;;;;;ECoErC,WAAA,CAAY,IAAA;EDpEiB;;;;;;AAoB/B;EC4DE,kBAAA,CAAmB,SAAA;;;;;;EAUnB,cAAA,CAAe,GAAA;EDtEsB;;;;;;;EAAA,QCkFvB,cAAA;EDnDY;;;;;;;EAAA,QCwFZ,WAAA;EDpFN;;;;;ACdV;;EDcU,QCiHM,WAAA;EAqGN;;;;;;;EAAA,QAvDM,uBAAA;EA7Ke;;;;;EAmOvB,GAAA,CACJ,IAAA,EAAM,IAAA,EACN,QAAA,EAAU,QAAA,EACV,UAAA,WACA,OAAA,aACC,OAAA;EArOK;;;;;EAySF,GAAA,CAAI,IAAA,EAAM,IAAA,EAAM,cAAA,WAAyB,OAAA,aAAoB,OAAA,CAAQ,QAAA;EAjR/D;;;;;EAyWN,MAAA,CAAO,IAAA,EAAM,IAAA,GAAO,OAAA;AAAA"}

package/dist/index-T1LHanIb.d.mts

@@ -0,0 +1,217 @@
+import { r as HubertError, t as KvStore } from "./kv-store-DmngWWuw.mjs";
+import { ARID } from "@bcts/components";
+import { Envelope } from "@bcts/envelope";
+
+//#region src/hybrid/error.d.ts
+/**
+ * Base class for Hybrid-specific errors.
+ *
+ * @category Hybrid
+ */
+declare class HybridError extends HubertError {
+  constructor(message: string);
+}
+/**
+ * Referenced IPFS content not found.
+ *
+ * Port of `Error::ContentNotFound` from hybrid/error.rs line 4-5.
+ *
+ * @category Hybrid
+ */
+declare class ContentNotFoundError extends HybridError {
+  constructor();
+}
+/**
+ * Not a reference envelope.
+ *
+ * Port of `Error::NotReferenceEnvelope` from hybrid/error.rs line 7-8.
+ *
+ * @category Hybrid
+ */
+declare class NotReferenceEnvelopeError extends HybridError {
+  constructor();
+}
+/**
+ * Invalid ARID in reference envelope.
+ *
+ * Port of `Error::InvalidReferenceArid` from hybrid/error.rs line 10-11.
+ *
+ * @category Hybrid
+ */
+declare class InvalidReferenceAridError extends HybridError {
+  constructor();
+}
+/**
+ * No id assertion found in reference envelope.
+ *
+ * Port of `Error::NoIdAssertion` from hybrid/error.rs line 13-14.
+ *
+ * @category Hybrid
+ */
+declare class NoIdAssertionError extends HybridError {
+  constructor();
+}
+//#endregion
+//#region src/hybrid/reference.d.ts
+/**
+ * Creates a reference envelope that points to content stored in IPFS.
+ *
+ * Reference envelopes are small envelopes stored in the DHT that contain
+ * a pointer to the actual envelope stored in IPFS. This allows the hybrid
+ * storage layer to transparently handle large envelopes that exceed the
+ * DHT size limit.
+ *
+ * Port of `create_reference_envelope()` from hybrid/reference.rs lines 31-39.
+ *
+ * # Format
+ *
+ * ```text
+ * '' [
+ *     'dereferenceVia': "ipfs",
+ *     'id': <ARID>,
+ *     "size": <number>
+ * ]
+ * ```
+ *
+ * @param referenceArid - The ARID used to look up the actual envelope in IPFS
+ * @param actualSize - Size of the actual envelope in bytes (for diagnostics)
+ * @returns A reference envelope that can be stored in the DHT
+ *
+ * @category Hybrid
+ */
+declare function createReferenceEnvelope(referenceArid: ARID, actualSize: number): Envelope;
+/**
+ * Checks if an envelope is a reference envelope.
+ *
+ * A reference envelope contains `dereferenceVia: "ipfs"` and an `id` assertion.
+ *
+ * Port of `is_reference_envelope()` from hybrid/reference.rs lines 53-91.
+ *
+ * @param envelope - The envelope to check
+ * @returns `true` if this is a reference envelope, `false` otherwise
+ *
+ * @category Hybrid
+ */
+declare function isReferenceEnvelope(envelope: Envelope): boolean;
+/**
+ * Extracts the reference ARID from a reference envelope.
+ *
+ * Port of `extract_reference_arid()` from hybrid/reference.rs lines 104-129.
+ *
+ * @param envelope - The reference envelope
+ * @returns The reference ARID
+ * @throws {NotReferenceEnvelopeError} If the envelope is not a reference envelope
+ * @throws {InvalidReferenceAridError} If the ARID cannot be extracted
+ * @throws {NoIdAssertionError} If no id assertion is found
+ *
+ * @category Hybrid
+ */
+declare function extractReferenceArid(envelope: Envelope): ARID;
+//#endregion
+//#region src/hybrid/kv.d.ts
+/**
+ * Hybrid storage layer combining Mainline DHT and IPFS.
+ *
+ * Automatically optimizes storage based on envelope size:
+ * - **Small envelopes (≤1000 bytes)**: Stored directly in DHT
+ * - **Large envelopes (>1000 bytes)**: Reference in DHT → actual envelope in IPFS
+ *
+ * This provides the best of both worlds:
+ * - Fast lookups for small messages via DHT
+ * - Large capacity for big messages via IPFS
+ * - Transparent indirection handled automatically
+ *
+ * Port of `struct HybridKv` from hybrid/kv.rs lines 59-63.
+ *
+ * # Requirements
+ *
+ * - No external daemon for DHT (embedded client)
+ * - Requires Kubo daemon for IPFS (http://127.0.0.1:5001)
+ *
+ * @category Hybrid Backend
+ *
+ * @example
+ * ```typescript
+ * const store = await HybridKv.create("http://127.0.0.1:5001");
+ *
+ * // Small envelope → DHT only
+ * const arid1 = ARID.new();
+ * const small = Envelope.new("Small message");
+ * await store.put(arid1, small);
+ *
+ * // Large envelope → DHT reference + IPFS
+ * const arid2 = ARID.new();
+ * const large = Envelope.new("x".repeat(2000));
+ * await store.put(arid2, large);
+ *
+ * // Get works the same for both
+ * const retrieved1 = await store.get(arid1);
+ * const retrieved2 = await store.get(arid2);
+ * ```
+ */
+declare class HybridKv implements KvStore {
+  private readonly dht;
+  private ipfs;
+  private dhtSizeLimit;
+  /**
+   * Private constructor - use `create()` factory method.
+   */
+  private constructor();
+  /**
+   * Create a new Hybrid KV store with default settings.
+   *
+   * Port of `HybridKv::new()` from hybrid/kv.rs lines 75-84.
+   *
+   * @param ipfsRpcUrl - IPFS RPC endpoint (e.g., "http://127.0.0.1:5001")
+   */
+  static create(ipfsRpcUrl: string): Promise<HybridKv>;
+  /**
+   * Set custom DHT size limit (default: 1000 bytes).
+   *
+   * Envelopes larger than this will use IPFS indirection.
+   *
+   * Port of `HybridKv::with_dht_size_limit()` from hybrid/kv.rs lines 89-92.
+   */
+  withDhtSizeLimit(limit: number): this;
+  /**
+   * Set whether to pin content in IPFS (default: false).
+   *
+   * Only affects envelopes stored in IPFS (when larger than DHT limit).
+   *
+   * Port of `HybridKv::with_pin_content()` from hybrid/kv.rs lines 97-100.
+   */
+  withPinContent(pin: boolean): this;
+  /**
+   * Check if an envelope fits in the DHT.
+   *
+   * Port of `HybridKv::fits_in_dht()` from hybrid/kv.rs lines 103-106.
+   *
+   * @internal
+   */
+  private fitsInDht;
+  /**
+   * Store an envelope at the given ARID.
+   *
+   * Port of `KvStore::put()` implementation from hybrid/kv.rs lines 109-168.
+   */
+  put(arid: ARID, envelope: Envelope, ttlSeconds?: number, verbose?: boolean): Promise<string>;
+  /**
+   * Retrieve an envelope for the given ARID.
+   *
+   * Port of `KvStore::get()` implementation from hybrid/kv.rs lines 171-230.
+   */
+  get(arid: ARID, timeoutSeconds?: number, verbose?: boolean): Promise<Envelope | null>;
+  /**
+   * Check if an envelope exists at the given ARID.
+   *
+   * Port of `KvStore::exists()` implementation from hybrid/kv.rs lines 254-257.
+   */
+  exists(arid: ARID): Promise<boolean>;
+  /**
+   * Destroy the hybrid store and release resources.
+   */
+  destroy(): Promise<void>;
+}
+//#endregion
+export { ContentNotFoundError as a, NoIdAssertionError as c, isReferenceEnvelope as i, NotReferenceEnvelopeError as l, createReferenceEnvelope as n, HybridError as o, extractReferenceArid as r, InvalidReferenceAridError as s, HybridKv as t };
+//# sourceMappingURL=index-T1LHanIb.d.mts.map

package/dist/index-T1LHanIb.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-T1LHanIb.d.mts","names":[],"sources":["../src/hybrid/error.ts","../src/hybrid/reference.ts","../src/hybrid/kv.ts"],"mappings":";;;;;;;;;;cAea,WAAA,SAAoB,WAAA;cACnB,OAAA;AAAA;;;;AA2Bd;;;;cAda,oBAAA,SAA6B,WAAA;EAAA,WAAA,CAAA;AAAA;;;;AA0C1C;;;;cA5Ba,yBAAA,SAAkC,WAAA;EAAA,WAAA,CAAA;AAAA;;ACa/C;;;;;;cDCa,yBAAA,SAAkC,WAAA;EAAA,WAAA,CAAA;AAAA;;ACkB/C;;;;;AAyDA;cD7Da,kBAAA,SAA2B,WAAA;EAAA,WAAA,CAAA;AAAA;;;;;;;;AA1CxC;;;;;AAcA;;;;;AAcA;;;;;AAcA;;;;;;iBCfgB,uBAAA,CAAwB,aAAA,EAAe,IAAA,EAAM,UAAA,WAAqB,QAAA;;AAAlF;;;;;;;;;;AAmBA;iBAAgB,mBAAA,CAAoB,QAAA,EAAU,QAAA;;;;AAyD9C;;;;;;;;;;iBAAgB,oBAAA,CAAqB,QAAA,EAAU,QAAA,GAAW,IAAA;;;;;;;ADvG1D;;;;;AAcA;;;;;AAcA;;;;;AAcA;;;;;;;;ACfA;;;;;;;;;;AAmBA;;;cCjBa,QAAA,YAAoB,OAAA;EAAA,iBACd,GAAA;EAAA,QACT,IAAA;EAAA,QACA,YAAA;;;;UAKD,WAAA,CAAA;EDkEiD;;;;;;AC1E1D;ED0E0D,OCrD3C,MAAA,CAAO,UAAA,WAAqB,OAAA,CAAQ,QAAA;;;;;;;;EAcjD,gBAAA,CAAiB,KAAA;EAoFkD;;;;;;;EAxEnE,cAAA,CAAe,GAAA;EA9CE;;;;;;;EAAA,QA0DT,SAAA;EAxBR;;;;;EAkCM,GAAA,CACJ,IAAA,EAAM,IAAA,EACN,QAAA,EAAU,QAAA,EACV,UAAA,WACA,OAAA,aACC,OAAA;EAJK;;;;;EAiDF,GAAA,CAAI,IAAA,EAAM,IAAA,EAAM,cAAA,WAAyB,OAAA,aAAoB,OAAA,CAAQ,QAAA;EA7CxE;;;;;EA4FG,MAAA,CAAO,IAAA,EAAM,IAAA,GAAO,OAAA;EA/CyC;;;EAuD7D,OAAA,CAAA,GAAW,OAAA;AAAA"}