@solarpunkltd/swarm-id 0.0.0-stage → 0.8.0

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

@@ -0,0 +1,60 @@
+import type { UploadOptions } from "@ethersphere/bee-js";
+import { type UploadTarget } from "./upload";
+/**
+ * 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 target - Upload target (stamper or subsidised mode)
+ * @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.)
+ * @returns Reference to the feed manifest
+ */
+export declare function createFeedManifestDirect(target: UploadTarget, topic: string, owner: string, options?: CreateFeedManifestOptions, uploadOptions?: UploadOptions): Promise<CreateFeedManifestResult>;

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

@@ -0,0 +1,70 @@
+import { EthAddress, Topic } from "@ethersphere/bee-js";
+import type { ChunkDownloader } from "../../download-data";
+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: ChunkDownloader, 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;
+}

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

@@ -0,0 +1,79 @@
+/** 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;

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

@@ -0,0 +1,60 @@
+import { EthAddress, Topic } from "@ethersphere/bee-js";
+import type { ChunkDownloader } from "../../download-data";
+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: ChunkDownloader, 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;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * 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, epochSocAddress, makeEpochIdentifier, } 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;

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

@@ -0,0 +1,110 @@
+/**
+ * Types for Epoch-Based Feeds
+ */
+import type { EthAddress, Topic, PrivateKey } from "@ethersphere/bee-js";
+import type { ChunkDownloader } from "../../download-data";
+import type { UploadTarget } from "../../upload";
+import type { EpochIndex } from "./epoch";
+/**
+ * Options for creating an epoch feed reader
+ */
+export interface EpochFeedOptions {
+    /** Chunk reader — a `Bee`, or anything else that can `downloadChunk` */
+    bee: ChunkDownloader;
+    /** 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 target - Upload target (stamper or subsidised gateway)
+     * @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, target: UploadTarget, encryptionKey?: Uint8Array, hints?: EpochUpdateHints): Promise<EpochUpdateResult>;
+    /**
+     * Get the owner address (derived from signer)
+     */
+    getOwner(): EthAddress;
+}

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

@@ -0,0 +1,76 @@
+import { EthAddress, Topic, PrivateKey, Identifier } from "@ethersphere/bee-js";
+import { EpochIndex } from "./epoch";
+import { type UploadTarget } from "../../upload";
+import type { EpochUpdater, EpochUpdateHints, EpochUpdateResult } from "./types";
+/**
+ * Build the SOC identifier for one epoch of a topic's epoch feed:
+ * `keccak256(topic ‖ epoch.marshalBinary())`. Exported so readers can
+ * reconstruct the SOC address of a feed entry they found (e.g. the
+ * partition-state reader compensates for the slot the entry's own SOC
+ * consumed).
+ */
+export declare function makeEpochIdentifier(topic: Topic, epoch: EpochIndex): Promise<Identifier>;
+/**
+ * 32-byte SOC chunk address of one epoch-feed entry:
+ * `keccak256(identifier ‖ owner)` — same formula as every SOC address.
+ */
+export declare function epochSocAddress(topic: Topic, epoch: EpochIndex, owner: EthAddress): Promise<Uint8Array>;
+/**
+ * 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 topic;
+    private readonly signer;
+    constructor(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 target - Upload target (stamper or subsidised gateway)
+     * @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, target: UploadTarget, 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 and using stamper mode, looks up the current
+     * feed state to calculate the next epoch, preventing overwrites.
+     * In subsidised mode without hints, uses root epoch (first update).
+     *
+     * @param at - Timestamp for this update
+     * @param hints - Optional hints from previous update
+     * @param encryptionKey - Optional encryption key for looking up encrypted feeds
+     * @param target - Upload target for determining if auto-lookup is possible
+     * @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 target - Upload target (stamper or subsidised gateway)
+     * @returns SOC chunk address for utilization tracking
+     */
+    private uploadEpochChunk;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * 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>;

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

@@ -0,0 +1,4 @@
+/**
+ * Feed utilities and implementations
+ */
+export * from "./epochs";

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

@@ -0,0 +1,14 @@
+/**
+ * Async Sequential Feed Finder
+ *
+ * Currently delegates to the sync finder to match Go behavior
+ * while keeping an async interface.
+ */
+import type { EthAddress, Topic, BeeRequestOptions } from "@ethersphere/bee-js";
+import type { ChunkDownloader } from "../../download-data";
+import type { SequentialFinder, SequentialLookupResult } from "./types";
+export declare class AsyncSequentialFinder implements SequentialFinder {
+    private readonly syncFinder;
+    constructor(bee: ChunkDownloader, topic: Topic, owner: EthAddress);
+    findAt(at: bigint, after?: bigint, requestOptions?: BeeRequestOptions): Promise<SequentialLookupResult>;
+}

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

@@ -0,0 +1,11 @@
+import type { EthAddress, Topic, BeeRequestOptions } from "@ethersphere/bee-js";
+import type { ChunkDownloader } from "../../download-data";
+import type { SequentialFinder, SequentialLookupResult } from "./types";
+export declare class SyncSequentialFinder implements SequentialFinder {
+    private readonly bee;
+    private readonly topic;
+    private readonly owner;
+    constructor(bee: ChunkDownloader, topic: Topic, owner: EthAddress);
+    findAt(_at: bigint, _after?: bigint, requestOptions?: BeeRequestOptions): Promise<SequentialLookupResult>;
+    private indexExists;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Sequential Feeds
+ *
+ * Sequential feed indexing for versioned updates.
+ */
+export type { SequentialFeedOptions, SequentialFeedWriterOptions, SequentialLookupResult, SequentialFinder, SequentialUpdater, } from "./types";
+export { SyncSequentialFinder } from "./finder";
+export { AsyncSequentialFinder } from "./async-finder";
+export { BasicSequentialUpdater } from "./updater";
+import type { SequentialFeedOptions, SequentialFeedWriterOptions, SequentialFinder, SequentialUpdater } from "./types";
+/**
+ * Create a synchronous sequential feed finder
+ */
+export declare function createSyncSequentialFinder(options: SequentialFeedOptions): SequentialFinder;
+/**
+ * Create an async sequential feed finder
+ */
+export declare function createAsyncSequentialFinder(options: SequentialFeedOptions): SequentialFinder;
+/**
+ * Create a sequential feed updater
+ */
+export declare function createSequentialUpdater(options: SequentialFeedWriterOptions): SequentialUpdater;

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

@@ -0,0 +1,82 @@
+/**
+ * Types for Sequential Feeds
+ */
+import type { Bee, EthAddress, Topic, PrivateKey, Stamper, BeeRequestOptions } from "@ethersphere/bee-js";
+import type { ChunkDownloader } from "../../download-data";
+/**
+ * Options for creating a sequential feed reader
+ */
+export interface SequentialFeedOptions {
+    /** Chunk reader — a `Bee`, or anything else that can `downloadChunk` */
+    bee: ChunkDownloader;
+    /** Feed topic (32 bytes) */
+    topic: Topic;
+    /** Feed owner address */
+    owner: EthAddress;
+}
+/**
+ * Options for creating a sequential feed writer
+ */
+export interface SequentialFeedWriterOptions extends SequentialFeedOptions {
+    /** The writer uploads as well as reads, so it needs the whole client */
+    bee: Bee;
+    /** Private key for signing chunks */
+    signer: PrivateKey;
+}
+/**
+ * Result from sequential feed lookup
+ */
+export interface SequentialLookupResult {
+    /** Current (latest) index if found */
+    current?: bigint;
+    /** Next index to use */
+    next: bigint;
+}
+/**
+ * Interface for sequential feed finders (readers)
+ *
+ * Implementations: SyncSequentialFinder, AsyncSequentialFinder
+ */
+export interface SequentialFinder {
+    /**
+     * Find the latest feed update index
+     *
+     * @param at - Ignored for sequential feeds (for compatibility with Go API)
+     * @param after - Hint of latest known index (0 if unknown)
+     * @returns Lookup result with current and next index
+     */
+    findAt(at: bigint, after?: bigint, requestOptions?: BeeRequestOptions): Promise<SequentialLookupResult>;
+}
+/**
+ * Interface for sequential feed updaters (writers)
+ */
+export interface SequentialUpdater {
+    /**
+     * Update feed with payload data
+     *
+     * @param payload - Payload to store
+     * @param stamper - Stamper object for stamping
+     * @returns SOC chunk address for utilization tracking
+     */
+    update(payload: Uint8Array, stamper: Stamper, encryptionKey?: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Get the owner address (derived from signer)
+     */
+    getOwner(): EthAddress;
+    /**
+     * Get current state (for persistence/debugging)
+     */
+    getState(): {
+        nextIndex: bigint;
+    };
+    /**
+     * Restore state (from persistence)
+     */
+    setState(state: {
+        nextIndex: bigint;
+    }): void;
+    /**
+     * Reset updater state (useful for testing or reinitialization)
+     */
+    reset(): void;
+}

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

@@ -0,0 +1,20 @@
+import type { Bee, Stamper } from "@ethersphere/bee-js";
+import { EthAddress, Topic, PrivateKey } from "@ethersphere/bee-js";
+import type { SequentialUpdater } from "./types";
+export declare class BasicSequentialUpdater implements SequentialUpdater {
+    private readonly bee;
+    private readonly topic;
+    private readonly signer;
+    private nextIndex;
+    constructor(bee: Bee, topic: Topic, signer: PrivateKey);
+    update(payload: Uint8Array, stamper: Stamper, encryptionKey?: Uint8Array): Promise<Uint8Array>;
+    getOwner(): EthAddress;
+    getState(): {
+        nextIndex: bigint;
+    };
+    setState(state: {
+        nextIndex: bigint;
+    }): void;
+    reset(): void;
+    private makeIdentifier;
+}

package/dist/proxy/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./chunking";
+export { uploadData, uploadSOC, uploadChunk, isStamperTarget, isSubsidisedTarget, type UploadTarget, type UploadDataOptions, type UploadDataResult, type UploadSOCOptions, type UploadSOCResult, type UploadChunkOptions, type UploadChunkResult, } from "./upload";
+export * from "./feeds";
+export * from "./act";