Class StreamrClient

The main API used to interact with Streamr.

Hierarchy

StreamrClient

Important

createStream

createStream(propsOrStreamIdOrPath: string | Partial<StreamMetadata> & {
id: string;
}): Promise<Stream>
Creates a new stream.
Parameters
- propsOrStreamIdOrPath: string | Partial<StreamMetadata> & {
  id: string;
  }
  
  the stream id to be used for the new stream, and optionally, any associated metadata
Returns Promise<Stream>

getOrCreateStream

getOrCreateStream(props: {
id: string;
partitions?: number;
}): Promise<Stream>
Gets a stream, creating one if it does not exist.
Parameters
- props: {
  id: string;
  partitions?: number;
  }
  
  the stream id to get or create. Field partitions is only used if creating the stream.
  - id: string
  - Optional partitions?: number
Returns Promise<Stream>

getStream

getStream(streamIdOrPath: string): Promise<Stream>
Gets a stream.

Returns
rejects if the stream is not found
Parameters
- streamIdOrPath: string
Returns Promise<Stream>

getSubscriptions

getSubscriptions(streamDefinition?: StreamDefinition): Promise<Subscription[]>
Returns a list of subscriptions matching the given criteria.
Parameters
- Optional streamDefinition: StreamDefinition
  
  leave as undefined to get all subscriptions
Returns Promise<Subscription[]>

publish

publish(streamDefinition: StreamDefinition, content: unknown, metadata?: PublishMetadata): Promise<Message>
Publishes a message to a stream partition in the network.

Returns
the published message (note: the field content is encrypted if the stream is private)
Parameters
- streamDefinition: StreamDefinition
  
  the stream or stream partition to publish the message to
- content: unknown
  
  the content (the payload) of the message (must be JSON serializable)
- Optional metadata: PublishMetadata
  
  provide additional metadata to be included in the message or to control the publishing process
Returns Promise<Message>

resend

resend(streamDefinition: StreamDefinition, options: ResendOptions, onMessage?: MessageListener): Promise<MessageStream>
Performs a resend of stored historical data.

Returns
a MessageStream that provides an alternative way of iterating messages. Rejects if the stream is not stored (i.e. is not assigned to a storage node).
Parameters
- streamDefinition: StreamDefinition
  
  the stream partition for which data should be resent
- options: ResendOptions
  
  defines the kind of resend that should be performed
- Optional onMessage: MessageListener
  
  callback will be invoked for each message retrieved
Returns Promise<MessageStream>

subscribe(options: Object, onMessage?: MessageListener): Promise<Subscription>
Subscribes to a stream partition in the network.

Returns
a Subscription that can be used to manage the subscription etc.
Parameters
- options: Object
  
  the stream or stream partition to subscribe to, additionally a resend can be performed by providing resend options
- Optional onMessage: MessageListener
  
  callback will be invoked for each message received in subscription
Returns Promise<Subscription>

unsubscribe

unsubscribe(streamDefinitionOrSubscription?: StreamDefinition | Subscription): Promise<unknown>
Unsubscribes from streams or stream partitions in the network.

Remarks
no-op if subscription does not exist
Parameters
- Optional streamDefinitionOrSubscription: StreamDefinition | Subscription
  
  leave as undefined to unsubscribe from all existing subscriptions.
Returns Promise<unknown>

Other

constructor

new StreamrClient(config?: StreamrClientConfig): StreamrClient
Parameters
- config: StreamrClientConfig = {}
Returns StreamrClient

`Readonly` id

id: string

`Static` `Readonly` generateEthereumAccount

generateEthereumAccount: (() => {
address: string;
privateKey: string;
}) = _generateEthereumAccount

Type declaration

- (): {
  address: string;
  privateKey: string;
  }
- Returns {
  address: string;
  privateKey: string;
  }
  - address: string
  - privateKey: string

addEncryptionKey

addEncryptionKey(key: EncryptionKey, streamIdOrPath: string): Promise<void>
Adds an encryption key for a given stream to the key store.

Remarks
Keys will be added to the store automatically by the client as encountered. This method can be used to manually add some known keys into the store.
Parameters
- key: EncryptionKey
- streamIdOrPath: string
Returns Promise<void>

addStreamToStorageNode

addStreamToStorageNode(streamIdOrPath: string, storageNodeAddress: string): Promise<void>
Assigns a stream to a storage node.
Parameters
- streamIdOrPath: string
- storageNodeAddress: string
Returns Promise<void>

closeProxyConnections

closeProxyConnections(streamDefinition: StreamDefinition, nodeIds: string[], direction: ProxyDirection): Promise<void>
Parameters
- streamDefinition: StreamDefinition
- nodeIds: string[]
- direction: ProxyDirection
Returns Promise<void>

connect

connect(): Promise<void>
Used to manually initialize the network stack and connect to the network.

Remarks
Connecting is handled automatically by the client. Generally this method need not be called by the user.

Returns Promise<void>

deleteStream

deleteStream(streamIdOrPath: string): Promise<void>
Deletes a stream.
Parameters
- streamIdOrPath: string
Returns Promise<void>

destroy

destroy(): Promise<void>
Destroys an instance of a StreamrClient by disconnecting from peers, clearing any pending tasks, and freeing up resources. This should be called once a user is done with the instance.

Remarks
As the name implies, the client instance (or any streams or subscriptions returned by it) should not be used after calling this method.

Returns Promise<void>

getAddress

getAddress(): Promise<EthereumAddress>
Gets the Ethereum address of the wallet associated with the current StreamrClient instance.

Returns Promise<EthereumAddress>

getNode

getNode(): Promise<NetworkNodeStub>
Deprecated
This in an internal method

Returns Promise<NetworkNodeStub>

getPermissions

getPermissions(streamIdOrPath: string): Promise<PermissionAssignment[]>
Returns the list of all permissions in effect for a given stream.
Parameters
- streamIdOrPath: string
Returns Promise<PermissionAssignment[]>

getStorageNodeMetadata

getStorageNodeMetadata(nodeAddress: string): Promise<StorageNodeMetadata>
Gets the metadata of a storage node from the storage node registry.

Returns
rejects if the storage node is not found
Parameters
- nodeAddress: string
Returns Promise<StorageNodeMetadata>

getStorageNodes

getStorageNodes(streamIdOrPath?: string): Promise<EthereumAddress[]>
Gets a list of storage nodes.
Parameters
- Optional streamIdOrPath: string
  
  if a stream is given, returns the list of storage nodes the stream has been assigned to; leave as undefined to return all storage nodes
Returns Promise<EthereumAddress[]>

getStoredStreams

getStoredStreams(storageNodeAddress: string): Promise<{
blockNumber: number;
streams: Stream[];
}>
Gets all streams assigned to a storage node.

Returns
a list of Stream as well as blockNumber of result (i.e. blockchain state)
Parameters
- storageNodeAddress: string
Returns Promise<{
blockNumber: number;
streams: Stream[];
}>

getStreamPublishers

getStreamPublishers(streamIdOrPath: string): AsyncIterable<EthereumAddress>
Gets all ethereum addresses that have PUBLISH permission to the stream.
Parameters
- streamIdOrPath: string
Returns AsyncIterable<EthereumAddress>

getStreamSubscribers

getStreamSubscribers(streamIdOrPath: string): AsyncIterable<EthereumAddress>
Gets all ethereum addresses that have SUBSCRIBE permission to the stream.
Parameters
- streamIdOrPath: string
Returns AsyncIterable<EthereumAddress>

grantPermissions

grantPermissions(streamIdOrPath: string, ...assignments: PermissionAssignment[]): Promise<void>
Grants permissions on a given stream.
Parameters
- streamIdOrPath: string
- Rest ...assignments: PermissionAssignment[]
Returns Promise<void>

hasPermission

hasPermission(query: PermissionQuery): Promise<boolean>
Checks whether the given permission is in effect.
Parameters
- query: PermissionQuery
Returns Promise<boolean>

isStoredStream

isStoredStream(streamIdOrPath: string, storageNodeAddress: string): Promise<boolean>
Checks whether a stream is assigned to a storage node.
Parameters
- streamIdOrPath: string
- storageNodeAddress: string
Returns Promise<boolean>

isStreamPublisher

isStreamPublisher(streamIdOrPath: string, userAddress: string): Promise<boolean>
Checks whether a given ethereum address has PUBLISH permission to a stream.
Parameters
- streamIdOrPath: string
- userAddress: string
Returns Promise<boolean>

isStreamSubscriber

isStreamSubscriber(streamIdOrPath: string, userAddress: string): Promise<boolean>
Checks whether a given ethereum address has SUBSCRIBE permission to a stream.
Parameters
- streamIdOrPath: string
- userAddress: string
Returns Promise<boolean>

off

off<T>(eventName: T, listener: StreamrClientEvents[T]): void
Removes an event listener from the client.
Type Parameters
- T extends keyof StreamrClientEvents
Parameters
- eventName: T
  
  event name, see StreamrClientEvents for options
- listener: StreamrClientEvents[T]
  
  the callback function to remove
Returns void

on

on<T>(eventName: T, listener: StreamrClientEvents[T]): void
Adds an event listener to the client.
Type Parameters
- T extends keyof StreamrClientEvents
Parameters
- eventName: T
  
  event name, see StreamrClientEvents for options
- listener: StreamrClientEvents[T]
  
  the callback function
Returns void

once

once<T>(eventName: T, listener: StreamrClientEvents[T]): void
Adds an event listener to the client that is invoked only once.
Type Parameters
- T extends keyof StreamrClientEvents
Parameters
- eventName: T
  
  event name, see StreamrClientEvents for options
- listener: StreamrClientEvents[T]
  
  the callback function
Returns void

openProxyConnections

openProxyConnections(streamDefinition: StreamDefinition, nodeIds: string[], direction: ProxyDirection): Promise<void>
Parameters
- streamDefinition: StreamDefinition
- nodeIds: string[]
- direction: ProxyDirection
Returns Promise<void>

removeStreamFromStorageNode

removeStreamFromStorageNode(streamIdOrPath: string, storageNodeAddress: string): Promise<void>
Unassigns a stream from a storage node.
Parameters
- streamIdOrPath: string
- storageNodeAddress: string
Returns Promise<void>

revokePermissions

revokePermissions(streamIdOrPath: string, ...assignments: PermissionAssignment[]): Promise<void>
Revokes permissions on a given stream.
Parameters
- streamIdOrPath: string
- Rest ...assignments: PermissionAssignment[]
Returns Promise<void>

searchStreams

searchStreams(term: undefined | string, permissionFilter: undefined | SearchStreamsPermissionFilter): AsyncIterable<Stream>
Searches for streams based on given criteria.
Parameters
- term: undefined | string
  
  a search term that should be part of the stream id of a result
- permissionFilter: undefined | SearchStreamsPermissionFilter
  
  permissions that should be in effect for a result
Returns AsyncIterable<Stream>

setPermissions

setPermissions(...items: {
assignments: PermissionAssignment[];
streamId: string;
}[]): Promise<void>
Sets a list of permissions to be in effect.

Remarks
Can be used to set the permissions of multiple streams in one transaction. Great for doing bulk operations and saving gas costs. Notice that the behaviour is overwriting, therefore any existing permissions not defined will be removed (per stream).
Parameters
- Rest ...items: {
  assignments: PermissionAssignment[];
  streamId: string;
  }[]
Returns Promise<void>

setStorageNodeMetadata

setStorageNodeMetadata(metadata: undefined | StorageNodeMetadata): Promise<void>
Sets the metadata of a storage node in the storage node registry.

Remarks
Acts on behalf of the wallet associated with the current StreamrClient instance.
Parameters
- metadata: undefined | StorageNodeMetadata
  
  if undefined, removes the storage node from the registry
Returns Promise<void>

updateEncryptionKey

updateEncryptionKey(opts: UpdateEncryptionKeyOptions): Promise<void>
Manually updates the encryption key used when publishing messages to a given stream.
Parameters
- opts: UpdateEncryptionKeyOptions
Returns Promise<void>

updateStream

updateStream(props: Partial<StreamMetadata> & {
id: string;
}): Promise<Stream>
Updates the metadata of a stream.
Parameters
- props: Partial<StreamMetadata> & {
  id: string;
  }
  
  the stream id and the metadata fields to be updated
Returns Promise<Stream>

waitForStorage

waitForStorage(message: Message, options?: {
    count?: number;
    interval?: number;
    messageMatchFn?: ((msgTarget: Message, msgGot: Message) => boolean);
    timeout?: number;
}): Promise<void>
Waits for a message to be stored by a storage node.

Returns
rejects if message was found in storage before timeout
Parameters
- message: Message
  
  the message to be awaited for
- Optional options: {
      count?: number;
      interval?: number;
      messageMatchFn?: ((msgTarget: Message, msgGot: Message) => boolean);
      timeout?: number;
  }
  
  additional options for controlling waiting and message matching
  - Optional count?: number
    
    Controls size of internal resend used in polling.
  - Optional interval?: number
    
    Determines how often should storage node be polled.
  - Optional messageMatchFn?: ((msgTarget: Message, msgGot: Message) => boolean)
    - (msgTarget: Message, msgGot: Message): boolean
      
      Used to set a custom message equality operator.
      
      Deprecated
      
      Parameters
      
      msgTarget: Message
      
      message being waited for (i.e. message)
      
      msgGot: Message
      
      candidate message polled from storage node
      
      Returns boolean
  - Optional timeout?: number
    
    Timeout after which to give up if message was not seen.
Returns Promise<void>

Class StreamrClient

Hierarchy

Index

Important

Other

Important

createStream

Parameters

propsOrStreamIdOrPath: string | Partial<StreamMetadata> & { id: string; }

Returns Promise<Stream>

getOrCreateStream

Parameters

props: { id: string; partitions?: number; }

id: string

Optional partitions?: number

Returns Promise<Stream>

getStream

Returns

Parameters

streamIdOrPath: string

Returns Promise<Stream>

getSubscriptions

Parameters

Optional streamDefinition: StreamDefinition

Returns Promise<Subscription[]>

publish

Returns

Parameters

streamDefinition: StreamDefinition

content: unknown

Optional metadata: PublishMetadata

Returns Promise<Message>

resend

Returns

Parameters

streamDefinition: StreamDefinition

options: ResendOptions

Optional onMessage: MessageListener

Returns Promise<MessageStream>

subscribe

Returns

Parameters

options: Object

Optional onMessage: MessageListener

Returns Promise<Subscription>

unsubscribe

Remarks

Parameters

Optional streamDefinitionOrSubscription: StreamDefinition | Subscription

Returns Promise<unknown>

Other

constructor

Parameters

config: StreamrClientConfig = {}

Returns StreamrClient

Readonly id

Static Readonly generateEthereumAccount

Type declaration

Returns { address: string; privateKey: string; }

address: string

privateKey: string

addEncryptionKey

Remarks

Parameters

key: EncryptionKey

streamIdOrPath: string

Returns Promise<void>

addStreamToStorageNode

Parameters

streamIdOrPath: string

storageNodeAddress: string

Returns Promise<void>

closeProxyConnections

Parameters

streamDefinition: StreamDefinition

nodeIds: string[]

direction: ProxyDirection

Returns Promise<void>

connect

Remarks

propsOrStreamIdOrPath: string | Partial<StreamMetadata> & {
id: string;
}

props: {
id: string;
partitions?: number;
}

`Optional` partitions?: number

`Optional` streamDefinition: StreamDefinition

`Optional` metadata: PublishMetadata

`Optional` onMessage: MessageListener

`Optional` onMessage: MessageListener

`Optional` streamDefinitionOrSubscription: StreamDefinition | Subscription

`Readonly` id

`Static` `Readonly` generateEthereumAccount

Returns {
address: string;
privateKey: string;
}

`Optional` streamIdOrPath: string

Returns Promise<{
blockNumber: number;
streams: Stream[];
}>

`Rest` ...assignments: PermissionAssignment[]