@ethersphere/bee-js 3.2.0 → 3.3.0

package/dist/mjs/modules/debug/transactions.js

@@ -0,0 +1,57 @@
+import { http } from '../../utils/http';
+const transactionsEndpoint = 'transactions';
+/**
+ * Get list of all pending transactions
+ *
+ * @param ky   Debug Ky instance
+ */
+export async function getAllTransactions(ky) {
+    const response = await http(ky, {
+        path: transactionsEndpoint,
+        responseType: 'json',
+    });
+    return response.data.pendingTransactions;
+}
+/**
+ * Get information for specific pending transactions
+ *
+ * @param ky   Debug Ky instance
+ * @param transactionHash Hash of the transaction
+ */
+export async function getTransaction(ky, transactionHash) {
+    const response = await http(ky, {
+        path: `${transactionsEndpoint}/${transactionHash}`,
+        responseType: 'json',
+    });
+    return response.data;
+}
+/**
+ * Rebroadcast existing transaction
+ *
+ * @param ky   Debug Ky instance
+ * @param transactionHash Hash of the transaction
+ */
+export async function rebroadcastTransaction(ky, transactionHash) {
+    const response = await http(ky, {
+        method: 'post',
+        path: `${transactionsEndpoint}/${transactionHash}`,
+        responseType: 'json',
+    });
+    return response.data.transactionHash;
+}
+/**
+ * Cancel existing transaction
+ *
+ * @param ky   Debug Ky instance
+ * @param transactionHash Hash of the transaction
+ * @param gasPrice Optional gas price
+ */
+export async function cancelTransaction(ky, transactionHash, gasPrice) {
+    const response = await http(ky, {
+        method: 'delete',
+        headers: { 'gas-price': gasPrice },
+        path: `${transactionsEndpoint}/${transactionHash}`,
+        responseType: 'json',
+    });
+    return response.data.transactionHash;
+}

package/dist/mjs/modules/feed.js

@@ -0,0 +1,61 @@
+import { filterHeaders, http } from '../utils/http';
+import { extractUploadHeaders } from '../utils/headers';
+import { BeeError } from '../utils/error';
+const feedEndpoint = 'feeds';
+/**
+ * Create an initial feed root manifest
+ *
+ * @param ky Ky instance
+ * @param owner           Owner's ethereum address in hex
+ * @param topic           Topic in hex
+ * @param postageBatchId  Postage BatchId to be used to create the Feed Manifest
+ * @param options         Additional options, like type (default: 'sequence')
+ */
+export async function createFeedManifest(ky, owner, topic, postageBatchId, options) {
+    const response = await http(ky, {
+        method: 'post',
+        responseType: 'json',
+        path: `${feedEndpoint}/${owner}/${topic}`,
+        searchParams: filterHeaders(options),
+        headers: extractUploadHeaders(postageBatchId),
+    });
+    return response.data.reference;
+}
+function readFeedUpdateHeaders(headers) {
+    const feedIndex = headers.get('swarm-feed-index');
+    const feedIndexNext = headers.get('swarm-feed-index-next');
+    if (!feedIndex) {
+        throw new BeeError('Response did not contain expected swarm-feed-index!');
+    }
+    if (!feedIndexNext) {
+        throw new BeeError('Response did not contain expected swarm-feed-index-next!');
+    }
+    return {
+        feedIndex,
+        feedIndexNext,
+    };
+}
+/**
+ * Find and retrieve feed update
+ *
+ * The feed consists of updates. This endpoint looks up an
+ * update that matches the provided parameters and returns
+ * the reference it contains along with its index and the
+ * index of the subsequent update.
+ *
+ * @param ky Ky instance
+ * @param owner       Owner's ethereum address in hex
+ * @param topic       Topic in hex
+ * @param options     Additional options, like index, at, type
+ */
+export async function fetchFeedUpdate(ky, owner, topic, options) {
+    const response = await http(ky, {
+        responseType: 'json',
+        path: `${feedEndpoint}/${owner}/${topic}`,
+        searchParams: filterHeaders(options),
+    });
+    return {
+        ...response.data,
+        ...readFeedUpdateHeaders(response.headers),
+    };
+}

package/dist/mjs/modules/pinning.js

@@ -0,0 +1,60 @@
+import { http } from '../utils/http';
+const PINNING_ENDPOINT = 'pins';
+/**
+ * Pin data with given reference
+ *
+ * @param ky Ky instance for given Bee class instance
+ * @param reference Bee data reference
+ */
+export async function pin(ky, reference) {
+    await http(ky, {
+        method: 'post',
+        responseType: 'json',
+        path: `${PINNING_ENDPOINT}/${reference}`,
+    });
+}
+/**
+ * Unpin data with given reference
+ *
+ * @param ky Ky instance for given Bee class instance
+ * @param reference Bee data reference
+ */
+export async function unpin(ky, reference) {
+    await http(ky, {
+        method: 'delete',
+        responseType: 'json',
+        path: `${PINNING_ENDPOINT}/${reference}`,
+    });
+}
+/**
+ * Get pin status for specific address.
+ *
+ * @param ky Ky instance
+ * @param reference
+ * @throws Error if given address is not pinned
+ */
+export async function getPin(ky, reference) {
+    const response = await http(ky, {
+        method: 'get',
+        responseType: 'json',
+        path: `${PINNING_ENDPOINT}/${reference}`,
+    });
+    return response.data;
+}
+/**
+ * Get list of all pins
+ *
+ * @param ky Ky instance
+ */
+export async function getAllPins(ky) {
+    const response = await http(ky, {
+        method: 'get',
+        responseType: 'json',
+        path: `${PINNING_ENDPOINT}`,
+    });
+    const result = response.data.references;
+    if (result === null) {
+        return [];
+    }
+    return result;
+}

package/dist/mjs/modules/pss.js

@@ -0,0 +1,36 @@
+import WebSocket from 'isomorphic-ws';
+import { prepareData } from '../utils/data';
+import { http } from '../utils/http';
+import { extractUploadHeaders } from '../utils/headers';
+const endpoint = 'pss';
+/**
+ * Send to recipient or target with Postal Service for Swarm
+ *
+ * @param ky Ky instance for given Bee class instance
+ * @param topic Topic name
+ * @param target Target message address prefix
+ * @param data
+ * @param postageBatchId Postage BatchId that will be assigned to sent message
+ * @param recipient Recipient public key
+ *
+ */
+export async function send(ky, topic, target, data, postageBatchId, recipient) {
+    await http(ky, {
+        method: 'post',
+        path: `${endpoint}/send/${topic}/${target}`,
+        body: await prepareData(data),
+        responseType: 'json',
+        searchParams: { recipient },
+        headers: extractUploadHeaders(postageBatchId),
+    });
+}
+/**
+ * Subscribe for messages on the given topic
+ *
+ * @param url Bee node URL
+ * @param topic Topic name
+ */
+export function subscribe(url, topic) {
+    const wsUrl = url.replace(/^http/i, 'ws');
+    return new WebSocket(`${wsUrl}/${endpoint}/subscribe/${topic}`);
+}

package/dist/mjs/modules/soc.js

@@ -0,0 +1,28 @@
+import { extractUploadHeaders } from '../utils/headers';
+import { http } from '../utils/http';
+const socEndpoint = 'soc';
+/**
+ * Upload single owner chunk (SOC) to a Bee node
+ *
+ * @param ky Ky instance
+ * @param owner           Owner's ethereum address in hex
+ * @param identifier      Arbitrary identifier in hex
+ * @param signature       Signature in hex
+ * @param data            Content addressed chunk data to be uploaded
+ * @param postageBatchId  Postage BatchId that will be assigned to uploaded data
+ * @param options         Additional options like tag, encryption, pinning
+ */
+export async function upload(ky, owner, identifier, signature, data, postageBatchId, options) {
+    const response = await http(ky, {
+        method: 'post',
+        path: `${socEndpoint}/${owner}/${identifier}`,
+        body: data,
+        headers: {
+            'content-type': 'application/octet-stream',
+            ...extractUploadHeaders(postageBatchId, options),
+        },
+        responseType: 'json',
+        searchParams: { sig: signature },
+    });
+    return response.data.reference;
+}

package/dist/mjs/modules/status.js

@@ -0,0 +1,11 @@
+import { http } from '../utils/http';
+/**
+ * Ping the base bee URL. If connection was not successful throw error
+ *
+ * @param ky Ky instance for given Bee class instance
+ */
+export async function checkConnection(ky) {
+    await http(ky, {
+        path: '',
+    });
+}

package/dist/mjs/modules/stewardship.js

@@ -0,0 +1,23 @@
+import { http } from '../utils/http';
+const stewardshipEndpoint = 'stewardship';
+/**
+ * Reupload locally pinned data
+ * @param ky Ky instance
+ * @param reference
+ * @param options
+ * @throws BeeResponseError if not locally pinned or invalid data
+ */
+export async function reupload(ky, reference) {
+    await http(ky, {
+        method: 'put',
+        path: `${stewardshipEndpoint}/${reference}`,
+    });
+}
+export async function isRetrievable(ky, reference) {
+    const response = await http(ky, {
+        method: 'get',
+        responseType: 'json',
+        path: `${stewardshipEndpoint}/${reference}`,
+    });
+    return response.data.isRetrievable;
+}

package/dist/mjs/modules/tag.js

@@ -0,0 +1,69 @@
+import { http } from '../utils/http';
+const endpoint = 'tags';
+/**
+ * Create new tag on the Bee node
+ *
+ * @param url Bee tag URL
+ */
+export async function createTag(ky) {
+    const response = await http(ky, {
+        method: 'post',
+        path: endpoint,
+        responseType: 'json',
+    });
+    return response.data;
+}
+/**
+ * Retrieve tag information from Bee node
+ *
+ * @param url Bee tag URL
+ * @param uid UID of tag to be retrieved
+ */
+export async function retrieveTag(ky, uid) {
+    const response = await http(ky, {
+        path: `${endpoint}/${uid}`,
+        responseType: 'json',
+    });
+    return response.data;
+}
+/**
+ * Get limited listing of all tags.
+ *
+ * @param url
+ * @param offset
+ * @param limit
+ */
+export async function getAllTags(ky, offset, limit) {
+    const response = await http(ky, {
+        path: `${endpoint}`,
+        searchParams: { offset, limit },
+        responseType: 'json',
+    });
+    return response.data.tags;
+}
+/**
+ * Removes tag from the Bee node.
+ * @param url
+ * @param uid
+ */
+export async function deleteTag(ky, uid) {
+    await http(ky, {
+        method: 'delete',
+        path: `${endpoint}/${uid}`,
+    });
+}
+/**
+ * Updates tag
+ * @param url
+ * @param uid
+ * @param reference
+ */
+export async function updateTag(ky, uid, reference) {
+    await http(ky, {
+        method: 'patch',
+        path: `${endpoint}/${uid}`,
+        json: {
+            reference,
+        },
+    });
+}

package/dist/mjs/package.json

@@ -0,0 +1,7 @@
+{
+    "type": "module",
+    "browser": {
+      "./utils/data.js": "./utils/data.browser.js",
+      "./utils/collection.node.js": "./utils/collection.browser.js"
+    }
+}

package/dist/mjs/types/debug.js

@@ -0,0 +1,6 @@
+export var BeeModes;
+(function (BeeModes) {
+    BeeModes["FULL"] = "full";
+    BeeModes["LIGHT"] = "light";
+    BeeModes["DEV"] = "dev";
+})(BeeModes || (BeeModes = {}));

package/dist/mjs/types/index.js

@@ -0,0 +1,33 @@
+export * from './debug';
+export const SPAN_SIZE = 8;
+export const SECTION_SIZE = 32;
+export const BRANCHES = 128;
+export const CHUNK_SIZE = SECTION_SIZE * BRANCHES;
+export const ADDRESS_HEX_LENGTH = 64;
+export const PSS_TARGET_HEX_LENGTH_MAX = 6;
+export const PUBKEY_HEX_LENGTH = 66;
+export const BATCH_ID_HEX_LENGTH = 64;
+export const REFERENCE_HEX_LENGTH = 64;
+export const ENCRYPTED_REFERENCE_HEX_LENGTH = 128;
+export const REFERENCE_BYTES_LENGTH = 32;
+export const ENCRYPTED_REFERENCE_BYTES_LENGTH = 64;
+/**
+ * Minimal depth that can be used for creation of postage batch
+ */
+export const STAMPS_DEPTH_MIN = 17;
+/**
+ * Maximal depth that can be used for creation of postage batch
+ */
+export const STAMPS_DEPTH_MAX = 255;
+export const TAGS_LIMIT_MIN = 1;
+export const TAGS_LIMIT_MAX = 1000;
+/*********************************************************
+ * Writers and Readers interfaces
+ */
+export const TOPIC_BYTES_LENGTH = 32;
+export const TOPIC_HEX_LENGTH = 64;
+/*********************************************************
+ * Ethereum compatible signing interfaces and definitions
+ */
+export const SIGNATURE_HEX_LENGTH = 130;
+export const SIGNATURE_BYTES_LENGTH = 65;

package/dist/mjs/utils/bytes.js

@@ -0,0 +1,95 @@
+import { bytesToHex } from './hex';
+/**
+ * Type guard for `Bytes<T>` type
+ *
+ * @param b       The byte array
+ * @param length  The length of the byte array
+ */
+export function isBytes(b, length) {
+    return b instanceof Uint8Array && b.length === length;
+}
+/**
+ * Verifies if a byte array has a certain length
+ *
+ * @param b       The byte array
+ * @param length  The specified length
+ */
+export function assertBytes(b, length) {
+    if (!isBytes(b, length)) {
+        throw new TypeError(`Parameter is not valid Bytes of length: ${length} !== ${b.length}`);
+    }
+}
+/**
+ * Type guard for FlexBytes<Min,Max> type
+ *
+ * @param b       The byte array
+ * @param min     Minimum size of the array
+ * @param max     Maximum size of the array
+ */
+export function isFlexBytes(b, min, max) {
+    return b instanceof Uint8Array && b.length >= min && b.length <= max;
+}
+/**
+ * Verifies if a byte array has a certain length between min and max
+ *
+ * @param b       The byte array
+ * @param min     Minimum size of the array
+ * @param max     Maximum size of the array
+ */
+export function assertFlexBytes(b, min, max) {
+    if (!isFlexBytes(b, min, max)) {
+        throw new TypeError(`Parameter is not valid FlexBytes of  min: ${min}, max: ${max}, length: ${b.length}`);
+    }
+}
+/**
+ * Return `length` bytes starting from `offset`
+ *
+ * @param data   The original data
+ * @param offset The offset to start from
+ * @param length The length of data to be returned
+ */
+export function bytesAtOffset(data, offset, length) {
+    const offsetBytes = data.slice(offset, offset + length);
+    // We are returning strongly typed Bytes so we have to verify that length is really what we claim
+    assertBytes(offsetBytes, length);
+    return offsetBytes;
+}
+/**
+ * Return flex bytes starting from `offset`
+ *
+ * @param data   The original data
+ * @param offset The offset to start from
+ * @param _min   The minimum size of the data
+ * @param _max   The maximum size of the data
+ */
+export function flexBytesAtOffset(data, offset, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_min, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_max) {
+    return data.slice(offset);
+}
+/**
+ * Returns true if two byte arrays are equal
+ *
+ * @param a Byte array to compare
+ * @param b Byte array to compare
+ */
+export function bytesEqual(a, b) {
+    return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+/**
+ * Returns a new byte array filled with zeroes with the specified length
+ *
+ * @param length The length of data to be returned
+ */
+export function makeBytes(length) {
+    return new Uint8Array(length);
+}
+export function wrapBytesWithHelpers(data) {
+    return Object.assign(data, {
+        text: () => new TextDecoder('utf-8').decode(data),
+        json: () => JSON.parse(new TextDecoder('utf-8').decode(data)),
+        hex: () => bytesToHex(data),
+    });
+}

package/dist/mjs/utils/collection.browser.js

@@ -0,0 +1,18 @@
+/**
+ * Creates array in the format of Collection with data loaded from directory on filesystem.
+ * The function loads all the data into memory!
+ *
+ * @param dir path to the directory
+ */
+export async function makeCollectionFromFS(dir) {
+    throw new Error('Creating Collection from File System is not supported in browsers!');
+}
+/**
+ * Calculate folder size recursively
+ *
+ * @param dir the path to the folder to check
+ * @returns size in bytes
+ */
+export async function getFolderSize(dir) {
+    throw new Error('Creating Collection from File System is not supported in browsers!');
+}

package/dist/mjs/utils/collection.js

@@ -0,0 +1,52 @@
+import { BeeArgumentError } from './error';
+import { fileArrayBuffer } from './file';
+import { isUint8Array } from './type';
+export function isCollection(data) {
+    if (!Array.isArray(data)) {
+        return false;
+    }
+    return data.every(entry => typeof entry === 'object' && entry.data && entry.path && isUint8Array(entry.data));
+}
+export function assertCollection(data) {
+    if (!isCollection(data)) {
+        throw new BeeArgumentError('invalid collection', data);
+    }
+}
+function makeFilePath(file) {
+    if (file.webkitRelativePath && file.webkitRelativePath !== '') {
+        return file.webkitRelativePath.replace(/.*?\//i, '');
+    }
+    if (file.name) {
+        return file.name;
+    }
+    throw new TypeError('file is not valid File object');
+}
+export async function makeCollectionFromFileList(fileList) {
+    const collection = [];
+    for (let i = 0; i < fileList.length; i++) {
+        const file = fileList[i];
+        if (file) {
+            collection.push({
+                path: makeFilePath(file),
+                data: new Uint8Array(await fileArrayBuffer(file)),
+            });
+        }
+    }
+    return collection;
+}
+/**
+ * Calculate cumulative size of files
+ *
+ * @param fileList list of files to check
+ * @returns size in bytes
+ */
+export function getCollectionSize(fileList) {
+    let sum = 0;
+    for (let i = 0; i < fileList.length; i++) {
+        const file = fileList[i];
+        if (file) {
+            sum += file.size;
+        }
+    }
+    return sum;
+}

package/dist/mjs/utils/collection.node.js

@@ -0,0 +1,63 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Creates array in the format of Collection with data loaded from directory on filesystem.
+ * The function loads all the data into memory!
+ *
+ * @param dir path to the directory
+ */
+export async function makeCollectionFromFS(dir) {
+    if (typeof dir !== 'string') {
+        throw new TypeError('dir has to be string!');
+    }
+    if (dir === '') {
+        throw new TypeError('dir must not be empty string!');
+    }
+    return buildCollectionRelative(dir, '');
+}
+async function buildCollectionRelative(dir, relativePath) {
+    // Handles case when the dir is not existing or it is a file ==> throws an error
+    const dirname = path.join(dir, relativePath);
+    const entries = await fs.promises.opendir(dirname);
+    let collection = [];
+    for await (const entry of entries) {
+        const fullPath = path.join(dir, relativePath, entry.name);
+        const entryPath = path.join(relativePath, entry.name);
+        if (entry.isFile()) {
+            collection.push({
+                path: entryPath,
+                data: new Uint8Array(await fs.promises.readFile(fullPath)),
+            });
+        }
+        else if (entry.isDirectory()) {
+            collection = [...(await buildCollectionRelative(dir, entryPath)), ...collection];
+        }
+    }
+    return collection;
+}
+/**
+ * Calculate folder size recursively
+ *
+ * @param dir the path to the folder to check
+ * @returns size in bytes
+ */
+export async function getFolderSize(dir) {
+    if (typeof dir !== 'string') {
+        throw new TypeError('dir has to be string!');
+    }
+    if (dir === '') {
+        throw new TypeError('dir must not be empty string!');
+    }
+    const entries = await fs.promises.opendir(dir);
+    let size = 0;
+    for await (const entry of entries) {
+        if (entry.isFile()) {
+            const stats = await fs.promises.stat(path.join(dir, entry.name));
+            size += stats.size;
+        }
+        else if (entry.isDirectory()) {
+            size += await getFolderSize(path.join(dir, entry.name));
+        }
+    }
+    return size;
+}

package/dist/mjs/utils/data.browser.js

@@ -0,0 +1,57 @@
+import { isNodeReadable, isReadableStream } from './stream';
+import Blob from 'cross-blob';
+/**
+ * Validates input and converts to Uint8Array
+ *
+ * @param data any string, ArrayBuffer or Uint8Array
+ */
+export async function prepareData(data) {
+    if (typeof data === 'string')
+        return new Blob([data], { type: 'text/plain' });
+    if (data instanceof Uint8Array || data instanceof ArrayBuffer) {
+        return new Blob([data], { type: 'application/octet-stream' });
+    }
+    if (data instanceof Blob) {
+        return data;
+    }
+    // Currently it is not possible to stream requests from browsers
+    // there are already first experiments on this field (Chromium)
+    // but till it is fully implemented across browsers-land we have to
+    // buffer the data before sending the requests.
+    if (isNodeReadable(data)) {
+        return new Promise(resolve => {
+            const buffers = [];
+            data.on('data', d => {
+                buffers.push(d);
+            });
+            data.on('end', () => {
+                resolve(new Blob(buffers, { type: 'application/octet-stream' }));
+            });
+        });
+    }
+    if (isReadableStream(data)) {
+        return new Promise(async (resolve) => {
+            const reader = data.getReader();
+            const buffers = [];
+            let done, value;
+            do {
+                ;
+                ({ done, value } = await reader.read());
+                if (!done) {
+                    buffers.push(value);
+                }
+            } while (!done);
+            resolve(new Blob(buffers, { type: 'application/octet-stream' }));
+        });
+    }
+    throw new TypeError('unknown data type');
+}
+export async function prepareWebsocketData(data) {
+    if (typeof data === 'string')
+        return new TextEncoder().encode(data);
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (data instanceof Blob)
+        return new Uint8Array(await new Response(data).arrayBuffer());
+    throw new TypeError('unknown websocket data type');
+}