@snaha/swarm-id 0.0.1

package/dist/proxy/feed-manifest.d.ts

@@ -0,0 +1,62 @@
+import type { Bee, Stamper, UploadOptions, BeeRequestOptions } from "@ethersphere/bee-js";
+/**
+ * Options for creating a feed manifest
+ */
+export interface CreateFeedManifestOptions {
+    /**
+     * Whether to encrypt the manifest.
+     * Default: true (encrypted)
+     */
+    encrypt?: boolean;
+    /**
+     * Feed type: "Sequence" for sequential feeds, "Epoch" for epoch feeds.
+     * Default: "Sequence"
+     */
+    feedType?: "Sequence" | "Epoch";
+}
+/**
+ * Result of creating a feed manifest
+ */
+export interface CreateFeedManifestResult {
+    /**
+     * Reference to the feed manifest.
+     * - Encrypted: 128 hex chars (64 bytes = address + encryption key)
+     * - Unencrypted: 64 hex chars (32 bytes = address)
+     */
+    reference: string;
+    /**
+     * Tag UID if a tag was created during upload
+     */
+    tagUid?: number;
+}
+/**
+ * Create a feed manifest directly using chunk upload
+ *
+ * Instead of using bee.createFeedManifest() which calls the /feeds endpoint,
+ * this function builds the manifest locally as a MantarayNode and uploads it
+ * via the encrypted chunk endpoint (or plain chunk endpoint if encrypt=false).
+ *
+ * Feed manifests have a single "/" path with metadata:
+ * - swarm-feed-owner: Owner's ethereum address (40 hex chars, no 0x)
+ * - swarm-feed-topic: Topic hash (64 hex chars)
+ * - swarm-feed-type: "Sequence" for sequential feeds
+ *
+ * IMPORTANT: This function implements client-side "saveRecursively" logic:
+ * 1. Upload the "/" child node first and get its address
+ * 2. Set the child's selfAddress to the uploaded address
+ * 3. Then upload the root node (which references the child's address)
+ *
+ * Without this, Bee's /bzz/ endpoint returns 404 because the "/" child chunk
+ * doesn't exist (only its calculated hash was stored in the root manifest).
+ *
+ * @param bee - Bee client instance
+ * @param stamper - Stamper for client-side signing
+ * @param topic - Topic hex string (64 chars)
+ * @param owner - Owner hex string (40 chars, no 0x prefix)
+ * @param options - Options for creating the manifest (encrypt, etc.)
+ * @param uploadOptions - Upload options (tag, deferred, etc.)
+ * @param requestOptions - Bee request options
+ * @returns Reference to the feed manifest
+ */
+export declare function createFeedManifestDirect(bee: Bee, stamper: Stamper, topic: string, owner: string, options?: CreateFeedManifestOptions, uploadOptions?: UploadOptions, requestOptions?: BeeRequestOptions): Promise<CreateFeedManifestResult>;
+//# sourceMappingURL=feed-manifest.d.ts.map

package/dist/proxy/feed-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feed-manifest.d.ts","sourceRoot":"","sources":["../../src/proxy/feed-manifest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,GAAG,EACH,OAAO,EACP,aAAa,EACb,iBAAiB,EAClB,MAAM,qBAAqB,CAAA;AAS5B;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,UAAU,GAAG,OAAO,CAAA;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,yBAAyB,EACnC,aAAa,CAAC,EAAE,aAAa,EAC7B,cAAc,CAAC,EAAE,iBAAiB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAyFnC"}

package/dist/proxy/feeds/epochs/async-finder.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Async Epoch Feed Finder (Concurrent)
+ *
+ * Concurrent implementation for finding feed updates at specific timestamps
+ * using epoch-based indexing with parallel chunk fetching.
+ */
+import type { Bee } from "@ethersphere/bee-js";
+import { EthAddress, Topic } from "@ethersphere/bee-js";
+import type { EpochFinder, EpochLookupResult } from "./types";
+/**
+ * Async concurrent finder for epoch-based feeds
+ *
+ * Launches parallel chunk fetches along the epoch tree path
+ * to find the feed update valid at a specific timestamp.
+ *
+ * Implements the EpochFinder interface.
+ */
+export declare class AsyncEpochFinder implements EpochFinder {
+    private readonly bee;
+    private readonly topic;
+    private readonly owner;
+    private readonly encryptionKey?;
+    constructor(bee: Bee, topic: Topic, owner: EthAddress, encryptionKey?: Uint8Array | undefined);
+    /**
+     * Find the feed update valid at time `at`
+     * @param at - Target unix timestamp (seconds)
+     * @param after - Hint of latest known update timestamp (0 if unknown)
+     * @returns 32-byte Swarm reference, or undefined if no update found
+     */
+    findAt(at: bigint, after?: bigint): Promise<Uint8Array | undefined>;
+    /**
+     * Recursively find update at epoch, with parallel fetching
+     *
+     * @param at - Target timestamp
+     * @param epoch - Current epoch to check
+     * @param currentBest - Best result found so far
+     * @returns Reference if found, undefined otherwise
+     */
+    private findAtEpoch;
+    /**
+     * Fetch chunk for a specific epoch
+     *
+     * @param at - Target timestamp for validation
+     * @param epoch - Epoch to fetch
+     * @returns Chunk payload
+     * @throws Error if chunk not found
+     */
+    private getEpochChunk;
+    /**
+     * Find the feed update valid at time `at` with full metadata
+     * Used by updater to calculate next epoch when no hints provided
+     *
+     * @param at - Target unix timestamp (seconds)
+     * @returns EpochLookupResult with reference, epoch, and timestamp, or undefined if no update found
+     */
+    findAtWithMetadata(at: bigint): Promise<EpochLookupResult | undefined>;
+    /**
+     * Recursively find update at epoch with full metadata tracking
+     *
+     * @param at - Target timestamp
+     * @param epoch - Current epoch to check
+     * @param currentBest - Best result found so far
+     * @returns EpochLookupResult if found, undefined otherwise
+     */
+    private findAtEpochWithMetadata;
+    /**
+     * Fetch chunk for a specific epoch and return full metadata
+     *
+     * @param at - Target timestamp for validation
+     * @param epoch - Epoch to fetch
+     * @returns Object with reference and timestamp, or undefined if timestamp > at
+     * @throws Error if chunk not found
+     */
+    private getEpochChunkWithMetadata;
+    private findPreviousLeaf;
+}
+//# sourceMappingURL=async-finder.d.ts.map

package/dist/proxy/feeds/epochs/async-finder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-finder.d.ts","sourceRoot":"","sources":["../../../../src/proxy/feeds/epochs/async-finder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,GAAG,EAAqB,MAAM,qBAAqB,CAAA;AACjE,OAAO,EAAE,UAAU,EAAa,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAElE,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAM7D;;;;;;;GAOG;AACH,qBAAa,gBAAiB,YAAW,WAAW;IAEhD,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;gBAHd,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,UAAU,EACjB,aAAa,CAAC,EAAE,UAAU,YAAA;IAG7C;;;;;OAKG;IACG,MAAM,CACV,EAAE,EAAE,MAAM,EACV,KAAK,GAAE,MAAW,GACjB,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAwClC;;;;;;;OAOG;YACW,WAAW;IAgDzB;;;;;;;OAOG;YACW,aAAa;IAQ3B;;;;;;OAMG;IACG,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IAwB5E;;;;;;;OAOG;YACW,uBAAuB;IA+DrC;;;;;;;OAOG;YACW,yBAAyB;IAmGvC,OAAO,CAAC,gBAAgB;CAQzB"}

package/dist/proxy/feeds/epochs/epoch.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Epoch-based Feed Indexing
+ *
+ * Implements time-based indexing using a binary tree structure where each epoch
+ * represents a time range with start time and level (0-32).
+ *
+ * Based on the Swarm Book of Feeds and Bee's epochs implementation.
+ */
+/** Maximum epoch level (2^32 seconds ≈ 136 years) */
+export declare const MAX_LEVEL = 32;
+/**
+ * Epoch interface - represents a time slot in the epoch tree
+ */
+export interface Epoch {
+    start: bigint;
+    level: number;
+}
+/**
+ * EpochIndex class - implements epoch-based feed indexing
+ *
+ * Each epoch represents a time range:
+ * - start: beginning timestamp of the epoch
+ * - level: determines the epoch's time span (2^level seconds)
+ *
+ * Epochs form a binary tree structure for efficient sparse updates.
+ */
+export declare class EpochIndex implements Epoch {
+    readonly start: bigint;
+    readonly level: number;
+    constructor(start: bigint, level: number);
+    /**
+     * Marshal epoch to binary format for hashing
+     * Returns Keccak256 hash of start (8 bytes big-endian) + level (1 byte)
+     */
+    marshalBinary(): Promise<Uint8Array>;
+    /**
+     * Calculate the next epoch for a new update
+     * @param last - Timestamp of last update
+     * @param at - Timestamp of new update
+     */
+    next(last: bigint, at: bigint): EpochIndex;
+    /**
+     * Calculate epoch length in seconds (2^level)
+     */
+    length(): bigint;
+    /**
+     * Get parent epoch
+     * UNSAFE: Do not call on top-level epoch (level 32)
+     */
+    parent(): EpochIndex;
+    /**
+     * Get left sibling epoch
+     * UNSAFE: Do not call on left sibling (when start is aligned to 2*length)
+     */
+    left(): EpochIndex;
+    /**
+     * Get child epoch containing timestamp `at`
+     * UNSAFE: Do not call with `at` outside this epoch's range
+     */
+    childAt(at: bigint): EpochIndex;
+    /**
+     * Check if this epoch is a left child of its parent
+     */
+    isLeft(): boolean;
+    /**
+     * String representation: "start/level"
+     */
+    toString(): string;
+}
+/**
+ * Calculate Lowest Common Ancestor epoch for two timestamps
+ *
+ * The LCA is the smallest epoch that contains both `at` and `after`.
+ * This is used to find the optimal starting point for feed lookups.
+ *
+ * @param at - Target timestamp
+ * @param after - Reference timestamp (0 if no previous update)
+ * @returns LCA epoch
+ */
+export declare function lca(at: bigint, after: bigint): EpochIndex;
+/**
+ * Helper function to get next epoch for update, handling null previous epoch
+ * @param prevEpoch - Previous epoch (null if first update)
+ * @param last - Timestamp of last update
+ * @param at - Timestamp of new update
+ */
+export declare function next(prevEpoch: EpochIndex | undefined, last: bigint, at: bigint): EpochIndex;
+//# sourceMappingURL=epoch.d.ts.map

package/dist/proxy/feeds/epochs/epoch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"epoch.d.ts","sourceRoot":"","sources":["../../../../src/proxy/feeds/epochs/epoch.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,qDAAqD;AACrD,eAAO,MAAM,SAAS,KAAK,CAAA;AAE3B;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;GAQG;AACH,qBAAa,UAAW,YAAW,KAAK;aAEpB,KAAK,EAAE,MAAM;aACb,KAAK,EAAE,MAAM;gBADb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM;IAS/B;;;OAGG;IACG,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC;IAa1C;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU;IAO1C;;OAEG;IACH,MAAM,IAAI,MAAM;IAIhB;;;OAGG;IACH,MAAM,IAAI,UAAU;IAMpB;;;OAGG;IACH,IAAI,IAAI,UAAU;IAIlB;;;OAGG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU;IAa/B;;OAEG;IACH,MAAM,IAAI,OAAO;IAIjB;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAwBzD;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAClB,SAAS,EAAE,UAAU,GAAG,SAAS,EACjC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,UAAU,CAKZ"}

package/dist/proxy/feeds/epochs/finder.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Synchronous Epoch Feed Finder
+ *
+ * Recursive implementation for finding feed updates at specific timestamps
+ * using epoch-based indexing.
+ */
+import type { Bee } from "@ethersphere/bee-js";
+import { EthAddress, Topic } from "@ethersphere/bee-js";
+import type { EpochFinder } from "./types";
+/**
+ * Synchronous recursive finder for epoch-based feeds
+ *
+ * Traverses the epoch tree recursively to find the feed update
+ * valid at a specific timestamp.
+ *
+ * Implements the EpochFinder interface.
+ */
+export declare class SyncEpochFinder implements EpochFinder {
+    private readonly bee;
+    private readonly topic;
+    private readonly owner;
+    constructor(bee: Bee, topic: Topic, owner: EthAddress);
+    /**
+     * Find the feed update valid at time `at`
+     * @param at - Target unix timestamp (seconds)
+     * @param after - Hint of latest known update timestamp (0 if unknown)
+     * @returns 32-byte Swarm reference, or undefined if no update found
+     */
+    findAt(at: bigint, after?: bigint): Promise<Uint8Array | undefined>;
+    /**
+     * Find the lowest common ancestor epoch with an existing chunk
+     *
+     * Traverses UP the epoch tree from the LCA until finding a chunk,
+     * or reaching the top level.
+     *
+     * @param at - Target timestamp
+     * @param after - Reference timestamp
+     * @returns Epoch and chunk found at that epoch (if any)
+     */
+    private common;
+    /**
+     * Recursive descent to find exact update at timestamp
+     *
+     * Traverses DOWN the epoch tree, handling left/right branches
+     * to find the most recent update not later than `at`.
+     *
+     * @param at - Target timestamp
+     * @param epoch - Current epoch being examined
+     * @param currentChunk - Best chunk found so far
+     * @returns Final chunk reference, or undefined
+     */
+    private atEpoch;
+    /**
+     * Fetch chunk for a specific epoch
+     *
+     * Calculates the chunk address from topic, epoch, and owner,
+     * then downloads it from the Bee node.
+     *
+     * @param at - Target timestamp for validation
+     * @param epoch - Epoch to fetch
+     * @returns Chunk reference (32 or 64 bytes), or undefined if timestamp invalid
+     * @throws Error if chunk not found or network error
+     */
+    private getEpochChunk;
+    private findPreviousLeaf;
+}
+//# sourceMappingURL=finder.d.ts.map

package/dist/proxy/feeds/epochs/finder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finder.d.ts","sourceRoot":"","sources":["../../../../src/proxy/feeds/epochs/finder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,GAAG,EAAqB,MAAM,qBAAqB,CAAA;AACjE,OAAO,EAAE,UAAU,EAAa,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAElE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAK1C;;;;;;;GAOG;AACH,qBAAa,eAAgB,YAAW,WAAW;IAE/C,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAFL,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,UAAU;IAGpC;;;;;OAKG;IACG,MAAM,CACV,EAAE,EAAE,MAAM,EACV,KAAK,GAAE,MAAW,GACjB,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IA0ClC;;;;;;;;;OASG;YACW,MAAM;IA+BpB;;;;;;;;;;OAUG;YACW,OAAO;IA+CrB;;;;;;;;;;OAUG;YACW,aAAa;IAiF3B,OAAO,CAAC,gBAAgB;CAQzB"}

package/dist/proxy/feeds/epochs/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Epoch-Based Feeds
+ *
+ * Time-based feed indexing using a binary tree structure for efficient
+ * sparse updates across long time periods.
+ */
+export { EpochIndex, lca, next, MAX_LEVEL, type Epoch } from "./epoch";
+export type { EpochFinder, EpochUpdater, EpochFeedOptions, EpochFeedWriterOptions, EpochLookupResult, } from "./types";
+export { SyncEpochFinder } from "./finder";
+export { AsyncEpochFinder } from "./async-finder";
+export { BasicEpochUpdater } from "./updater";
+import type { EpochFinder, EpochUpdater, EpochFeedOptions, EpochFeedWriterOptions } from "./types";
+/**
+ * Create a synchronous epoch feed finder (non-concurrent)
+ *
+ * @returns EpochFinder implementation
+ */
+export declare function createSyncEpochFinder(options: EpochFeedOptions): EpochFinder;
+/**
+ * Create an async epoch feed finder (concurrent)
+ *
+ * @returns EpochFinder implementation
+ */
+export declare function createAsyncEpochFinder(options: EpochFeedOptions): EpochFinder;
+/**
+ * Create an epoch feed updater
+ *
+ * @returns EpochUpdater implementation
+ */
+export declare function createEpochUpdater(options: EpochFeedWriterOptions): EpochUpdater;
+/**
+ * @deprecated Use createSyncEpochFinder instead
+ */
+export declare const createEpochFinder: typeof createSyncEpochFinder;
+//# sourceMappingURL=index.d.ts.map

package/dist/proxy/feeds/epochs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/proxy/feeds/epochs/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAA;AAGtE,YAAY,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAM7C,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACvB,MAAM,SAAS,CAAA;AAEhB;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,GAAG,WAAW,CAE5E;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,WAAW,CAO7E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,sBAAsB,GAC9B,YAAY,CAEd;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,8BAAwB,CAAA"}

package/dist/proxy/feeds/epochs/test-utils.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Test utilities for epoch feeds
+ *
+ * Provides mock storage and helpers for testing epoch feed operations
+ */
+import { PrivateKey, Topic, EthAddress } from "@ethersphere/bee-js";
+/**
+ * In-memory chunk storage for testing
+ */
+export declare class MockChunkStore {
+    private chunks;
+    put(address: string, data: Uint8Array): Promise<void>;
+    get(address: string): Promise<Uint8Array>;
+    has(address: string): boolean;
+    clear(): void;
+    size(): number;
+}
+/**
+ * Mock Bee instance for testing
+ */
+export declare class MockBee {
+    readonly url = "http://localhost:1633";
+    private store;
+    private tagCounter;
+    constructor(store?: MockChunkStore);
+    createTag(): Promise<{
+        uid: number;
+        split: number;
+        seen: number;
+        stored: number;
+        sent: number;
+        synced: number;
+        address: string;
+        startedAt: string;
+    }>;
+    downloadChunk(reference: string): Promise<Uint8Array>;
+    uploadChunk(data: Uint8Array, _postageBatchId: string): Promise<{
+        reference: string;
+    }>;
+    getStore(): MockChunkStore;
+}
+/**
+ * Create test signer with a deterministic private key
+ */
+export declare function createTestSigner(): PrivateKey;
+/**
+ * Create test topic
+ */
+export declare function createTestTopic(name?: string): Topic;
+/**
+ * Create test owner address
+ */
+export declare function createTestOwner(): EthAddress;
+/**
+ * Create test reference (32 bytes)
+ */
+export declare function createTestReference(value: number | bigint): Uint8Array;
+/**
+ * Create test payload with timestamp
+ */
+export declare function createTestPayload(at: bigint): Uint8Array;
+/**
+ * Create a mock Stamper for testing
+ *
+ * Returns an object with a stamp() method that produces a valid-looking
+ * EnvelopeWithBatchId without performing real cryptographic operations.
+ */
+export declare function createMockStamper(): {
+    stamp(_chunk: any): {
+        batchId: {
+            toUint8Array: () => Uint8Array<ArrayBuffer>;
+        };
+        index: Uint8Array<ArrayBuffer>;
+        timestamp: Uint8Array<ArrayBuffer>;
+        signature: Uint8Array<ArrayBuffer>;
+        issuer: Uint8Array<ArrayBuffer>;
+    };
+};
+/**
+ * Mock fetch for SOC and chunk uploads
+ *
+ * Intercepts fetch calls to /soc/ and /chunks endpoints, storing data
+ * in the provided MockChunkStore.
+ *
+ * @param store - Mock chunk store for persisting uploaded data
+ * @param owner - Owner address for computing SOC addresses on /chunks uploads
+ */
+export declare function mockFetch(store?: MockChunkStore, owner?: EthAddress): void;
+/**
+ * Restore original fetch
+ */
+export declare function restoreFetch(): void;
+//# sourceMappingURL=test-utils.d.ts.map

package/dist/proxy/feeds/epochs/test-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-utils.d.ts","sourceRoot":"","sources":["../../../../src/proxy/feeds/epochs/test-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAEnE;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAgC;IAExC,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAQ/C,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI7B,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,MAAM;CAGf;AAED;;GAEG;AACH,qBAAa,OAAO;IAClB,SAAgB,GAAG,2BAA0B;IAC7C,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,UAAU,CAAI;gBAEV,KAAK,CAAC,EAAE,cAAc;IAI5B,SAAS,IAAI,OAAO,CAAC;QACzB,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,MAAM,CAAA;QACb,IAAI,EAAE,MAAM,CAAA;QACZ,MAAM,EAAE,MAAM,CAAA;QACd,IAAI,EAAE,MAAM,CAAA;QACZ,MAAM,EAAE,MAAM,CAAA;QACd,OAAO,EAAE,MAAM,CAAA;QACf,SAAS,EAAE,MAAM,CAAA;KAClB,CAAC;IAcI,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAIrD,WAAW,CACf,IAAI,EAAE,UAAU,EAChB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAOjC,QAAQ,IAAI,cAAc;CAG3B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CAK7C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,MAAoB,GAAG,KAAK,CAIjE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,UAAU,CAE5C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAKtE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,CAKxD;AASD;;;;;GAKG;AACH,wBAAgB,iBAAiB;kBAEf,GAAG;;;;;;;;;EAYpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,KAAK,CAAC,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,IAAI,CAuF1E;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAGnC"}

package/dist/proxy/feeds/epochs/types.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Types for Epoch-Based Feeds
+ */
+import type { Bee, EthAddress, Topic, PrivateKey, Stamper } from "@ethersphere/bee-js";
+import type { EpochIndex } from "./epoch";
+/**
+ * Options for creating an epoch feed reader
+ */
+export interface EpochFeedOptions {
+    /** Bee instance for chunk operations */
+    bee: Bee;
+    /** Feed topic (32 bytes) */
+    topic: Topic;
+    /** Feed owner address */
+    owner: EthAddress;
+    /** Optional encryption key for encrypted feed updates */
+    encryptionKey?: Uint8Array;
+}
+/**
+ * Options for creating an epoch feed writer
+ */
+export interface EpochFeedWriterOptions extends EpochFeedOptions {
+    /** Private key for signing chunks */
+    signer: PrivateKey;
+}
+/**
+ * Result from an epoch feed lookup
+ */
+export interface EpochLookupResult {
+    /** Swarm reference (32 bytes) */
+    reference: Uint8Array;
+    /** Epoch where the update was found */
+    epoch: EpochIndex;
+    /** Timestamp of the update */
+    timestamp: bigint;
+}
+/**
+ * Hints for calculating the next epoch in a stateless manner.
+ * Callers should store these after each update and pass them to subsequent updates.
+ */
+export interface EpochUpdateHints {
+    /** Previous epoch (for calculating next) */
+    lastEpoch?: {
+        start: bigint;
+        level: number;
+    };
+    /** Timestamp of last update */
+    lastTimestamp?: bigint;
+}
+/**
+ * Result from an epoch feed update, including epoch info for subsequent updates.
+ */
+export interface EpochUpdateResult {
+    /** SOC address of the uploaded chunk */
+    socAddress: Uint8Array;
+    /** Epoch used for this update (for caller to store as hint) */
+    epoch: {
+        start: bigint;
+        level: number;
+    };
+    /** Timestamp used (for caller to store as hint) */
+    timestamp: bigint;
+}
+/**
+ * Interface for epoch feed finders (readers)
+ *
+ * Implementations: SyncEpochFinder, AsyncEpochFinder
+ */
+export interface EpochFinder {
+    /**
+     * Find the feed update valid at time `at`
+     *
+     * @param at - Target unix timestamp (seconds)
+     * @param after - Hint of latest known update timestamp (0 if unknown)
+     * @returns 32 or 64-byte Swarm reference, or undefined if no update found
+     */
+    findAt(at: bigint, after?: bigint): Promise<Uint8Array | undefined>;
+}
+/**
+ * Interface for epoch feed updaters (writers)
+ *
+ * Implementation: BasicEpochUpdater
+ *
+ * Implements Bee-compatible stateless epoch calculation.
+ * Each update uses hints from the previous update to calculate the next epoch,
+ * creating a proper epoch tree that Bee's finder can traverse.
+ */
+export interface EpochUpdater {
+    /**
+     * Update feed with a reference at given timestamp
+     *
+     * Calculates the appropriate epoch based on hints:
+     * - First update (no hints): uses root epoch (level 32, start 0)
+     * - Subsequent updates: calculates next epoch using LCA-based algorithm
+     *
+     * @param at - Unix timestamp for this update (seconds)
+     * @param reference - 32 or 64-byte Swarm reference to store
+     * @param stamper - Stamper object for stamping
+     * @param encryptionKey - Optional encryption key for the update
+     * @param hints - Optional hints from previous update for calculating epoch
+     * @returns Update result with SOC address and epoch info for next update
+     */
+    update(at: bigint, reference: Uint8Array, stamper: Stamper, encryptionKey?: Uint8Array, hints?: EpochUpdateHints): Promise<EpochUpdateResult>;
+    /**
+     * Get the owner address (derived from signer)
+     */
+    getOwner(): EthAddress;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/proxy/feeds/epochs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/proxy/feeds/epochs/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,GAAG,EACH,UAAU,EACV,KAAK,EACL,UAAU,EACV,OAAO,EACR,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEzC;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,GAAG,EAAE,GAAG,CAAA;IAER,4BAA4B;IAC5B,KAAK,EAAE,KAAK,CAAA;IAEZ,yBAAyB;IACzB,KAAK,EAAE,UAAU,CAAA;IAEjB,yDAAyD;IACzD,aAAa,CAAC,EAAE,UAAU,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB;IAC9D,qCAAqC;IACrC,MAAM,EAAE,UAAU,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,SAAS,EAAE,UAAU,CAAA;IAErB,uCAAuC;IACvC,KAAK,EAAE,UAAU,CAAA;IAEjB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,SAAS,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5C,+BAA+B;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,UAAU,EAAE,UAAU,CAAA;IACtB,+DAA+D;IAC/D,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IACvC,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAA;CACpE;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;;;;OAaG;IACH,MAAM,CACJ,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,OAAO,EAChB,aAAa,CAAC,EAAE,UAAU,EAC1B,KAAK,CAAC,EAAE,gBAAgB,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAE7B;;OAEG;IACH,QAAQ,IAAI,UAAU,CAAA;CACvB"}

package/dist/proxy/feeds/epochs/updater.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Basic Epoch Feed Updater
+ *
+ * Handles writing updates to epoch-based feeds by calculating the next
+ * epoch and uploading chunks.
+ */
+import type { Bee, Stamper } from "@ethersphere/bee-js";
+import { EthAddress, Topic, PrivateKey } from "@ethersphere/bee-js";
+import type { EpochUpdater, EpochUpdateHints, EpochUpdateResult } from "./types";
+/**
+ * Basic updater for epoch-based feeds
+ *
+ * Implements Bee-compatible stateless epoch calculation.
+ * Each update uses hints from the previous update to calculate the next epoch,
+ * creating a proper epoch tree that Bee's finder can traverse.
+ *
+ * - First update (no hints): uses root epoch (level 32, start 0)
+ * - Subsequent updates: calculates next epoch using the standard algorithm:
+ *   - If new timestamp within previous epoch's range: dive to child
+ *   - Else: jump to LCA(newTimestamp, prevTimestamp) and dive to child
+ *
+ * Implements the EpochUpdater interface.
+ */
+export declare class BasicEpochUpdater implements EpochUpdater {
+    private readonly bee;
+    private readonly topic;
+    private readonly signer;
+    constructor(bee: Bee, topic: Topic, signer: PrivateKey);
+    /**
+     * Update feed with a reference at given timestamp
+     *
+     * @param at - Unix timestamp for this update (seconds)
+     * @param reference - 32 or 64-byte Swarm reference to store
+     * @param stamper - Stamper object for stamping
+     * @param encryptionKey - Optional encryption key for the update
+     * @param hints - Optional hints from previous update for calculating epoch
+     * @returns Update result with SOC address and epoch info for next update
+     */
+    update(at: bigint, reference: Uint8Array, stamper: Stamper, encryptionKey?: Uint8Array, hints?: EpochUpdateHints): Promise<EpochUpdateResult>;
+    /**
+     * Calculate the epoch for this update based on hints or auto-lookup
+     *
+     * When hints are provided, uses them for fast epoch calculation.
+     * When no hints are provided, looks up the current feed state to calculate
+     * the next epoch, preventing overwrites of previous updates.
+     *
+     * @param at - Timestamp for this update
+     * @param hints - Optional hints from previous update
+     * @param encryptionKey - Optional encryption key for looking up encrypted feeds
+     * @returns Epoch to use for this update
+     */
+    private calculateEpoch;
+    /**
+     * Get the owner address (derived from signer)
+     */
+    getOwner(): EthAddress;
+    /**
+     * Upload a chunk for a specific epoch
+     *
+     * @param epoch - Epoch to upload to
+     * @param at - Timestamp of this update
+     * @param reference - 32 or 64-byte reference to store
+     * @param stamper - Stamper object for stamping
+     * @returns SOC chunk address for utilization tracking
+     */
+    private uploadEpochChunk;
+}
+//# sourceMappingURL=updater.d.ts.map

package/dist/proxy/feeds/epochs/updater.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updater.d.ts","sourceRoot":"","sources":["../../../../src/proxy/feeds/epochs/updater.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAc,MAAM,qBAAqB,CAAA;AAM/E,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAGhF;;;;;;;;;;;;;GAaG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IAElD,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAFN,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,UAAU;IAGrC;;;;;;;;;OASG;IACG,MAAM,CACV,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,OAAO,EAChB,aAAa,CAAC,EAAE,UAAU,EAC1B,KAAK,CAAC,EAAE,gBAAgB,GACvB,OAAO,CAAC,iBAAiB,CAAC;IA2B7B;;;;;;;;;;;OAWG;YACW,cAAc;IAmC5B;;OAEG;IACH,QAAQ,IAAI,UAAU;IAItB;;;;;;;;OAQG;YACW,gBAAgB;CA8C/B"}

package/dist/proxy/feeds/epochs/utils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared utilities for epoch feed finders
+ */
+import { EpochIndex } from "./epoch";
+/**
+ * Type for the chunk fetcher callback used by findPreviousLeaf.
+ * This allows both sync and async finders to share the same logic.
+ */
+export type EpochChunkFetcher = (at: bigint, epoch: EpochIndex) => Promise<Uint8Array | undefined>;
+/**
+ * Find a previous leaf chunk by scanning backwards from the target timestamp.
+ *
+ * This is a recovery fallback for poisoned-ancestor histories where the tree
+ * traversal fails but valid leaf nodes exist.
+ *
+ * @param at - Target unix timestamp (seconds)
+ * @param after - Hint of latest known update timestamp (0 if unknown)
+ * @param getEpochChunk - Callback function to fetch epoch chunks
+ * @returns 32-byte Swarm reference, or undefined if no update found
+ */
+export declare function findPreviousLeaf(at: bigint, after: bigint, getEpochChunk: EpochChunkFetcher): Promise<Uint8Array | undefined>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/proxy/feeds/epochs/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../src/proxy/feeds/epochs/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAIpC;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,UAAU,KACd,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAA;AAEpC;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,iBAAiB,GAC/B,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CA6BjC"}