@streamr/cli-tools 4.1.0 → 6.0.0-alpha.0

package/.eslintignore

@@ -0,0 +1,3 @@
+node_modules/**
+dist/**
+

package/.eslintrc

@@ -0,0 +1,6 @@
+{
+  "extends": "eslint-config-streamr-ts",
+  "rules": {
+    "no-console": "off"
+  }
+}

package/CHANGELOG.md

@@ -5,7 +5,38 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
-## Changed
+- Add permission commands: `stream grant-permission` and `stream revoke-permission`
+- Remove `typescript` and `ts-node` as run-time dependencies
+- Remove `--msg-chain-id` parameter from `stream resend from`
+- (Breaking) `streamr stream create` argument is a stream ID, not a name
+- Support path notation when defining a stream ID
+
+## [5.0.0] - 2021-05-05
+### Added
+- Add storage node commands under `streamr storage-node`
+
+### Changed
+- (Breaking) Commands are divided to subcommands: most of the existing command are under `streamr stream`, and `generate` command under `streamr mock-data`
+  - `streamr subscribe` is now `streamr stream subscribe`
+  - `streamr publish` is now `streamr stream publish`
+  - `streamr list` is now `streamr stream list`
+  - `streamr show` is now `streamr stream show`
+  - `streamr create` is now `streamr stream create`
+  - `streamr resend` is now `streamr stream resend`
+  - `streamr generate` is now `streamr mock-data generate`
+- Fixed examples of --private-key in README
+- Internal implementation was converted to TypeScript
+- Bump dependency streamr-client to 5.2.1
+- Bump dependency commander to 7.2.0
+
+## [4.1.1] - 2021-02-11
+### Changed
+- Bump dependency streamr-client to 5.0.0-beta.6
+- Bump dependency commander to ^6.1.0
+
+## [4.1.0] - 2020-10-12
+### Changed
+- Bump dependency streamr-client to ^4.1.1.
 - Turn option `--privateKey` into `--private-key` for consistency.
 - Turn `--apiKey` into `--api-key` for consistency.
 
@@ -14,7 +45,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Ethereum authentication with `--privateKey <key>`. This also enables message signing when publishing messages.
 
 ### Changed
--  (Breaking) Rename command `listen` to `subscribe`.
+- (Breaking) Rename command `listen` to `subscribe`.
 - (Breaking) API key is now given with `--apiKey <key>`. API keys are deprecated. Option `--privateKey` should be preferred.
 
 ## [3.1.1] - 2020-04-16
@@ -40,7 +71,10 @@ ordering and gap filling.
 - Bump dependency commander to ^4.0.1.
 - Re-organize README.md and a few touches to Developing section paragraphs.
 
-[Unreleased]: https://github.com/streamr-dev/cli-tools/compare/v4.0.0...HEAD
+[Unreleased]: https://github.com/streamr-dev/cli-tools/compare/v5.0.0...HEAD
+[5.0.0]: https://github.com/streamr-dev/cli-tools/compare/v4.1.1...v5.0.0
+[4.1.1]: https://github.com/streamr-dev/cli-tools/compare/v4.1.0...v4.1.1
+[4.1.0]: https://github.com/streamr-dev/cli-tools/compare/v4.0.0...v4.1.0
 [4.0.0]: https://github.com/streamr-dev/cli-tools/compare/v3.1.1...v4.0.0
 [3.1.1]: https://github.com/streamr-dev/cli-tools/compare/v3.1.0...v3.1.1
 [3.1.0]: https://github.com/streamr-dev/cli-tools/compare/v3.0.1...v3.1.0

package/README.md

@@ -1,35 +1,53 @@
-# Streamr Command Line Tools
+<p align="center">
+  <a href="https://streamr.network">
+    <img alt="Streamr" src="https://raw.githubusercontent.com/streamr-dev/network-monorepo/main/packages/client/readme-header-img.png" width="1320" />
+  </a>
+</p>
+
+# @streamr/cli-tools
 
 Command line tool for interacting with [Streamr](https://streamr.network).
 
 See [Changelog](CHANGELOG.md) for version information and changes.
 
-## Installation
+## Table of Contents
+- [Install](#install)
+- [Use](#use)
+- [Develop](#develop)
+- [Release](#release)
+- [Contribute](#contribute)
+
+## Install
 
 ```
 npm install -g @streamr/cli-tools
 ```
 
-## Usage
-To get a list of all (sub)commands simply run `streamr`.
+## Use
+All commands follow pattern `streamr <command> <subcommand>`, e.g.
+```
+streamr stream subscribe
+streamr mock-data generate
+```
+
+To get a list of all commands simply run `streamr`. To list subcommands run e.g. `streamr stream`
 
-All (sub)commands follow pattern `streamr <command>`.
+Run `streamr <command> <subcommand> --help` to get more information about a a command, its options, and so forth.
 
-Run `streamr help <command>` or `streamr <command> --help` to get more information about a a command, its options, and
-so forth.
+If there is a stream parameter in a command, it can be defined as a full id (e.g. `0x1234567890123456789012345678901234567890/foo/bar`) or a path (e.g. `/foo/bar`). If path notation is used, the stream ID is made by prefixing the authenticated Ethereum address (`--private-key <key>`) to the path.
 
 ### subscribe
 Used to subscribe to a stream and output real-time JSON objects to stdout line-by-line.
 
 For example, to subscribe to a public stream such as the tram demo do
 ```
-streamr subscribe 7wa7APtlTq6EC5iTCBy6dw
+streamr stream subscribe streamr.eth/demos/helsinki-trams
 ```
 
 To subscribe to a private stream and authenticate with an Ethereum private key:
 
 ```
-streamr subscribe streamId --privateKey <key>
+streamr stream subscribe streamId --private-key <key>
 ```
 
 Flag `--dev` or `--stg` can be enabled for the command to operate on pre-defined development or staging environment. Alternatively, you can give `--ws-url <url>` and `--http-url <url>` to connect to any custom network.
@@ -40,7 +58,7 @@ Used to publish events to a stream from stdin line-by-line. Each line should be
 
 Example of use:
 ```
-streamr publish <streamId> --privateKey <key>
+streamr stream publish <streamId> --private-key <key>
 ```
 
 Flag `--dev` or `--stg` can be enabled for the command to operate on pre-defined development or staging environment.
@@ -51,44 +69,51 @@ Generate random JSON objects to stdout line-by-line.
 
 Useful for generating test data to be published to a stream with `publish`, e.g.:
 ```
-streamr generate | streamr publish <streamId> --privateKey <key>
+streamr mock-data generate | streamr stream publish <streamId> --private-key <key>
 ```
 
 ### list
 Fetch a list of streams that are accessible to the user authenticated by the private key
 ```
-streamr list --privateKey <key>
+streamr stream list --private-key <key>
 ```
 
 ### show
 Show detailed information about a specific stream
 ```
-streamr show <streamId> --privateKey <key>
+streamr stream show <streamId> --private-key <key>
 ```
 
 ### create
 Create a new stream
 ```
-streamr create <name> --privateKey <key>
+streamr stream create <streamId> --private-key <key>
+```
+E.g.
 ```
+streamr stream create /foo/bar
+streamr stream create 0x1234567890123456789012345678901234567890/foobar
+streamr stream create yourdomain.ens/foobar
+```
+
 
 ### resend
 Request a resend of historical data printed as JSON objects to stdout line-by-line.
 
 For example, to fetch the 10 latest messages of a public stream such as the tram demo do
 ```
-streamr resend last 10 7wa7APtlTq6EC5iTCBy6dw
+streamr stream resend last 10 streamr.eth/demos/helsinki-trams
 ```
 
 
 To fetch data starting from a particular date-time
 ```
-streamr resend from 2019-05-10T17:00:00 <streamId> --privateKey <key>
+streamr stream resend from 2019-05-10T17:00:00 <streamId> --private-key <key>
 ```
 
 To fetch data between two date-times
 ```
-streamr resend range 2019-05-10T17:00:00 2019-05-11T21:00:00 <streamId> --privateKey <key>
+streamr stream resend range 2019-05-10T17:00:00 2019-05-11T21:00:00 <streamId> --private-key <key>
 ```
 
 Flag `--dev` or `--stg` can be enabled for the command to operate on pre-defined development or staging environment.
@@ -104,21 +129,21 @@ You can pipe the line-by-line JSON objects output by `subscribe` to
 your program written in any language. Just make the program read JSON objects
 from stdin.
 ```
-streamr subscribe 7wa7APtlTq6EC5iTCBy6dw | ruby calculate-average-speed.rb
+streamr stream subscribe streamr.eth/demos/helsinki-trams | ruby calculate-average-speed.rb
 ```
 
 #### Publishing to a stream from any programming language
 If your program produces JSON objects to stdout (line-by-line), you can
 redirect it to command `publish` to publish the JSON objects to a stream.
 ```
-python printSensorReadingsAsJson.py | streamr publish <streamId> --privateKey <key>
+python printSensorReadingsAsJson.py | streamr stream publish <streamId> --private-key <key>
 ```
 
 #### Transforming streams
 You can also subscribe to a stream, apply a transformation, and then pipe the
 transformed output into another stream.
 ```
-streamr subscribe <sourceStream> | ./calculateMovingAverages | streamr publish <destinationStream> --privateKey <key>
+streamr stream subscribe <sourceStream> | ./calculateMovingAverages | streamr stream publish <destinationStream> --private-key <key>
 ```
 
 Same rules apply here as before. Your program should accept line-by-line JSON
@@ -129,23 +154,23 @@ If you have a working stream in production that you'd also like to use in your
 development environment, you can combine the `subscribe` and `publish` commands to effectively copy
 the real-time events.
 ```
-streamr subscribe 7wa7APtlTq6EC5iTCBy6dw | streamr publish --dev <streamId> --privateKey <key>
+streamr stream subscribe streamr.eth/demos/helsinki-trams | streamr stream publish --dev <streamId> --private-key <key>
 ```
 
 And the same for staging environment:
 ```
-streamr subscribe 7wa7APtlTq6EC5iTCBy6dw | streamr publish --stg <streamId> --privateKey <key>
+streamr stream subscribe streamr.eth/demos/helsinki-trams | streamr stream publish --stg <streamId> --private-key <key>
 ```
 
-## Contributing
-See issues, especially those tagged with "help wanted". We welcome pull requests and issues.
-
-## Developing
+## Develop
 This project is a thin wrapper around [streamr-client-javascript](https://github.com/streamr-dev/streamr-client-javascript),
 which does the heavy lifting, while this project concentrates on CLI concerns: parsing and
 passing arguments, stdin/stdout, errors, and so forth.
 
-### Releasing to NPM
+### Release
 ```
 npm publish --access=public
 ```
+
+## Contribute
+See issues, especially those tagged with "help wanted". We welcome pull requests and issues.

package/bin/common.ts

@@ -0,0 +1,94 @@
+import * as commander from 'commander'
+import { Wallet } from 'ethers'
+import { StreamrClientOptions } from 'streamr-client'
+
+export interface EnvironmentOptions {
+    dev?: boolean
+    stg?: boolean
+    httpUrl?: string
+}
+
+export interface AuthenticationOptions {
+    privateKey?: string
+}
+
+export function envOptions(program: commander.Command): commander.Command {
+    return program
+        .option('--dev', 'use pre-defined development environment')
+        .option('--stg', 'use pre-defined staging environment')
+        .option('--ws-url <url>', 'alternative websocket url to use')
+        .option('--http-url <url>', 'alternative http url to use')
+}
+
+export function authOptions(program: commander.Command): commander.Command {
+    return program
+        .option('--private-key <key>', 'use an Ethereum private key to authenticate')
+}
+
+export function exitWithHelpIfArgsNotBetween(program: commander.Command, min: number, max: number): void {
+    if (program.args.length < min || program.args.length > max) {
+        program.help()
+    }
+}
+
+export function formStreamrOptionsWithEnv(
+    { dev, stg, httpUrl, privateKey }: EnvironmentOptions & AuthenticationOptions
+): StreamrClientOptions {
+    const options: StreamrClientOptions = {}
+
+    if (dev && stg) {
+        console.error('flags --dev and --stg cannot be enabled at the same time')
+        process.exit(1)
+    }
+
+    if (dev) {
+        options.restUrl = 'http://localhost/api/v1'
+        options.storageNodeRegistry = [{
+            // "broker-node-storage-1" on Docker environment
+            address: '0xde1112f631486CfC759A50196853011528bC5FA0',
+            url: 'http://10.200.10.1:8891'
+        }]
+    } else if (stg) {
+        options.restUrl = 'https://staging.streamr.com/api/v1/'
+    }
+
+    if (httpUrl) {
+        options.restUrl = httpUrl
+    }
+
+    if (privateKey) {
+        options.auth = {
+            privateKey
+        }
+    }
+
+    return options
+}
+
+export function createFnParseInt(name: string): (s: string) => number {
+    return (str: string) => {
+        const n = parseInt(str, 10)
+        if (isNaN(n)) {
+            console.error(`${name} must be an integer (was "${str}")`)
+            process.exit(1)
+        }
+        return n
+    }
+}
+
+// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+export const getStreamId = (streamIdOrPath: string|undefined, options: any): string|undefined => {
+    if (streamIdOrPath === undefined) {
+        return undefined
+    }
+    const PATH_PREFIX = '/'
+    if (!streamIdOrPath.startsWith(PATH_PREFIX)) {
+        return streamIdOrPath
+    }
+    const privateKey = options.privateKey
+    if (privateKey === undefined) {
+        console.error(`relative stream id ${streamIdOrPath} requires authentication`)
+        process.exit(1)
+    }
+    return new Wallet(privateKey).address.toLowerCase() + streamIdOrPath
+}

package/bin/streamr-misc-get-session-token.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { Command } from 'commander'
+import { StreamrClient } from 'streamr-client'
+import {
+    envOptions,
+    authOptions,
+    exitWithHelpIfArgsNotBetween,
+    formStreamrOptionsWithEnv,
+} from './common'
+import pkg from '../package.json'
+
+const program = new Command()
+program
+    .description('get a session token for the current user')
+authOptions(program)
+envOptions(program)
+    .version(pkg.version)
+    .action(async (options: any) => {
+        const client = new StreamrClient(formStreamrOptionsWithEnv(options))
+        try {
+            console.info(await client.session.getSessionToken())
+        } catch (err) {
+            console.error(err)
+            process.exit(1)
+        }
+    })
+    .parseAsync(process.argv)
+    .catch((e) => {
+        console.error(e)
+        process.exit(1)
+    })
+
+exitWithHelpIfArgsNotBetween(program, 0, 0)

package/bin/streamr-misc.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { program } from 'commander'
+import pkg from '../package.json'
+
+program
+    .version(pkg.version)
+    .usage('<command> [<args>]')
+    .description('miscellaneous subcommands')
+    .command('get-session-token', 'get a session token for the current user')
+    .parse(process.argv)

package/bin/streamr-mock-data-generate.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { Command } from 'commander'
+import { generate } from '../src/generate'
+import { exitWithHelpIfArgsNotBetween, createFnParseInt } from './common'
+import pkg from '../package.json'
+
+const program = new Command()
+program
+    .description('generate and print semi-random JSON data to stdout')
+    .option('-r, --rate <n>', 'rate in milliseconds', createFnParseInt('--rate'), 500)
+    .version(pkg.version)
+    .action((options: any) => {
+        generate(options.rate)
+    })
+    .parse(process.argv)
+
+exitWithHelpIfArgsNotBetween(program, 0, 0)

package/bin/streamr-mock-data.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { program } from 'commander'
+import pkg from '../package.json'
+
+program
+    .version(pkg.version)
+    .usage('<command> [<args>]')
+    .description('mock-data subcommands')
+    .command('generate', 'generate JSON data')
+    .parse(process.argv)

package/bin/streamr-storage-node-add-stream.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { Command } from 'commander'
+import { StreamrClient, Stream } from 'streamr-client'
+import {
+    envOptions,
+    authOptions,
+    exitWithHelpIfArgsNotBetween,
+    formStreamrOptionsWithEnv,
+    getStreamId,
+} from './common'
+import pkg from '../package.json'
+
+const program = new Command()
+program
+    .arguments('<storageNodeAddress> <streamId>')
+    .description('add stream to a storage node')
+authOptions(program)
+envOptions(program)
+    .version(pkg.version)
+    .action((storageNodeAddress: string, streamIdOrPath: string, options: any) => {
+        const client = new StreamrClient(formStreamrOptionsWithEnv(options))
+        const streamId = getStreamId(streamIdOrPath, options)!
+        client.getStream(streamId)
+            .then((stream: Stream) => stream.addToStorageNode(storageNodeAddress))
+            .catch((err) => {
+                console.error(err)
+                process.exit(1)
+            })
+    })
+    .parse(process.argv)
+
+exitWithHelpIfArgsNotBetween(program, 2, 2)

package/bin/streamr-storage-node-list-stream-parts.ts

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { Command } from 'commander'
+import { StreamrClient } from 'streamr-client'
+import {
+    envOptions,
+    authOptions,
+    exitWithHelpIfArgsNotBetween,
+    formStreamrOptionsWithEnv,
+} from './common'
+import pkg from '../package.json'
+import EasyTable from 'easy-table'
+
+const program = new Command()
+program
+    .arguments('<storageNodeAddress>')
+    .description('list streams parts in a storage node')
+authOptions(program)
+envOptions(program)
+    .version(pkg.version)
+    .action((storageNodeAddress: string, options: any) => {
+        const client = new StreamrClient(formStreamrOptionsWithEnv(options))
+        client.getStreamPartsByStorageNode(storageNodeAddress)
+            .then((streamParts) => {
+                if (streamParts.length > 0) {
+                    console.info(EasyTable.print(streamParts.map(({ streamId, streamPartition }) => ({
+                        streamId,
+                        streamPartition,
+                    }))))
+                }
+                return true
+            }).catch((err) => {
+                console.error(err)
+                process.exit(1)
+            })
+    })
+    .parse(process.argv)
+
+exitWithHelpIfArgsNotBetween(program, 1, 1)

package/bin/streamr-storage-node-list.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { Command } from 'commander'
+import { StreamrClient } from 'streamr-client'
+import {
+    envOptions,
+    authOptions,
+    exitWithHelpIfArgsNotBetween,
+    formStreamrOptionsWithEnv,
+    getStreamId,
+} from './common'
+import pkg from '../package.json'
+import EasyTable from 'easy-table'
+
+const getStorageNodes = async (streamId: string | undefined, client: StreamrClient): Promise<string[]> => {
+    if (streamId !== undefined) {
+        const stream = await client.getStream(streamId)
+        const storageNodes = await stream.getStorageNodes()
+        return storageNodes.map((storageNode) => storageNode.address)
+    } else {
+        // all storage nodes (currently there is only one)
+        const nodes = await client.getNodes()
+        return nodes.map((n) => n.address)
+    }
+}
+
+const program = new Command()
+program
+    .description('fetch a list of storage nodes')
+    .option('-s, --stream <streamId>', 'only storage nodes which store the given stream (needs authentication)')
+
+authOptions(program)
+
+envOptions(program)
+    .version(pkg.version)
+    .action((options: any) => {
+        const client = new StreamrClient(formStreamrOptionsWithEnv(options))
+        const streamId = getStreamId(options.stream, options)
+        getStorageNodes(streamId, client).then((addresses: string[]) => {
+            if (addresses.length > 0) {
+                console.info(EasyTable.print(addresses.map((address: string) => ({
+                    address
+                }))))
+            }
+            return true
+        }).catch((err) => {
+            console.error(err)
+            process.exit(1)
+        })
+    })
+    .parse(process.argv)
+
+exitWithHelpIfArgsNotBetween(program, 0, 0)

package/bin/streamr-storage-node-remove-stream.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { Command } from 'commander'
+import { StreamrClient, Stream } from 'streamr-client'
+import {
+    envOptions,
+    authOptions,
+    exitWithHelpIfArgsNotBetween,
+    formStreamrOptionsWithEnv,
+    getStreamId,
+} from './common'
+import pkg from '../package.json'
+
+const program = new Command()
+program
+    .arguments('<storageNodeAddress> <streamId>')
+    .description('remove stream from a storage node')
+authOptions(program)
+envOptions(program)
+    .version(pkg.version)
+    .action((storageNodeAddress: string, streamIdOrPath: string, options: any) => {
+        const client = new StreamrClient(formStreamrOptionsWithEnv(options))
+        const streamId = getStreamId(streamIdOrPath, options)!
+        client.getStream(streamId)
+            .then((stream: Stream) => stream.removeFromStorageNode(storageNodeAddress))
+            .catch((err) => {
+                console.error(err)
+                process.exit(1)
+            })
+    })
+    .parse(process.argv)
+
+exitWithHelpIfArgsNotBetween(program, 2, 2)

package/bin/streamr-storage-node.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { program } from 'commander'
+import pkg from '../package.json'
+
+program
+    .version(pkg.version)
+    .usage('<command> [<args>]')
+    .description('storage node subcommands')
+    .command('list', 'list storage nodes')
+    .command('add-stream', 'add stream')
+    .command('remove-stream', 'remove stream')
+    .command('list-stream-parts', 'list stream parts in a storage node')
+    .parse(process.argv)

package/bin/streamr-stream-create.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { Command } from 'commander'
+import { create } from '../src/create'
+import {
+    envOptions,
+    authOptions,
+    exitWithHelpIfArgsNotBetween,
+    formStreamrOptionsWithEnv,
+    createFnParseInt
+} from './common'
+import pkg from '../package.json'
+
+const program = new Command()
+program
+    .arguments('<streamId>')
+    .description('create a new stream')
+    .option('-d, --description <description>', 'define a description')
+    .option('-c, --config <config>', 'define a configuration as JSON', (s: string) => JSON.parse(s))
+    .option('-p, --partitions <count>', 'define a partition count',
+        createFnParseInt('--partitions'))
+authOptions(program)
+envOptions(program)
+    .version(pkg.version)
+    .action((streamIdOrPath: string, options: any) => {
+        const body: any = {
+            id: streamIdOrPath,
+            description: options.description,
+            config: options.config,
+            partitions: options.partitions
+        }
+        create(body, formStreamrOptionsWithEnv(options))
+    })
+    .parse(process.argv)
+
+exitWithHelpIfArgsNotBetween(program, 1, 1)