{"_id":"@bajerm/cactus-api-client","name":"@bajerm/cactus-api-client","dist-tags":{"latest":"1.1.3-u1"},"versions":{"1.1.3-u1":{"name":"@bajerm/cactus-api-client","version":"1.1.3-u1","description":"Universal library used by both front end and back end components of Cactus. Aims to be a developer swiss army knife.","keywords":["Hyperledger","Cactus","Integration","Blockchain","Distributed Ledger Technology"],"homepage":"https://github.com/hyperledger/cactus#readme","bugs":{"url":"https://github.com/hyperledger/cactus/issues"},"repository":{"type":"git","url":"git+https://github.com/hyperledger/cactus.git"},"license":"Apache-2.0","author":{"name":"Hyperledger Cactus Contributors","email":"cactus@lists.hyperledger.org","url":"https://www.hyperledger.org/use/cactus"},"contributors":[{"name":"Please add yourself to the list of contributors","email":"your.name@example.com","url":"https://example.com"},{"name":"Peter Somogyvari","email":"peter.somogyvari@accenture.com","url":"https://accenture.com"}],"main":"dist/lib/main/typescript/index.js","module":"dist/lib/main/typescript/index.js","browser":"dist/cactus-api-client.web.umd.js","types":"dist/lib/main/typescript/index.d.ts","scripts":{"watch":"npm-watch","webpack":"npm-run-all webpack:dev","webpack:dev":"npm-run-all webpack:dev:node webpack:dev:web","webpack:dev:node":"webpack --env=dev --target=node --config ../../webpack.config.js","webpack:dev:web":"webpack --env=dev --target=web --config ../../webpack.config.js"},"dependencies":{"@hyperledger/cactus-common":"1.1.3","@bajerm/cactus-core":"1.1.3-u2","@hyperledger/cactus-core-api":"1.1.3","@bajerm/cactus-plugin-consortium-manual":"1.1.3-u2","rxjs":"7.3.0"},"devDependencies":{"@hyperledger/cactus-test-tooling":"1.1.3"},"engines":{"node":">=10","npm":">=6"},"publishConfig":{"access":"public"},"browserMinified":"dist/cactus-api-client.web.umd.min.js","mainMinified":"dist/cactus-api-client.node.umd.min.js","watch":{},"gitHead":"ec53718ee00de2bc333ab455b8256475248a6bb7","_id":"@bajerm/cactus-api-client@1.1.3-u1","_nodeVersion":"16.19.0","_npmVersion":"8.19.3","dist":{"integrity":"sha512-ma7ix+yFslzASvNFiO+nayN30bvHDTwuMyzfifvKIQ2Hqezg4hg6+n8y9zP2Hr/qexTqjw5S+Lhgex7ipJegdA==","shasum":"d0f82a4cef8d7b8265f154028aae30808d5bcce9","tarball":"https://registry.npmjs.org/@bajerm/cactus-api-client/-/cactus-api-client-1.1.3-u1.tgz","fileCount":22,"unpackedSize":119249,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDI2uLYECbfTsQuTbrPdyJ2DoWsr92dUCX8jsDdaQl1bAIgAk+uVlQW0z9uz7CQ2IKvwArHaYMw+0TDjBbahKdheRg="}]},"_npmUser":{"name":"bajerm","email":"michal.bajer@fujitsu.com"},"directories":{},"maintainers":[{"name":"bajerm","email":"michal.bajer@fujitsu.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/cactus-api-client_1.1.3-u1_1687771681320_0.9988139951537995"},"_hasShrinkwrap":false}},"time":{"created":"2023-06-26T09:28:01.263Z","1.1.3-u1":"2023-06-26T09:28:01.489Z","modified":"2023-06-26T09:28:01.667Z"},"maintainers":[{"name":"bajerm","email":"michal.bajer@fujitsu.com"}],"description":"Universal library used by both front end and back end components of Cactus. Aims to be a developer swiss army knife.","homepage":"https://github.com/hyperledger/cactus#readme","keywords":["Hyperledger","Cactus","Integration","Blockchain","Distributed Ledger Technology"],"repository":{"type":"git","url":"git+https://github.com/hyperledger/cactus.git"},"contributors":[{"name":"Please add yourself to the list of contributors","email":"your.name@example.com","url":"https://example.com"},{"name":"Peter Somogyvari","email":"peter.somogyvari@accenture.com","url":"https://accenture.com"}],"author":{"name":"Hyperledger Cactus Contributors","email":"cactus@lists.hyperledger.org","url":"https://www.hyperledger.org/use/cactus"},"bugs":{"url":"https://github.com/hyperledger/cactus/issues"},"license":"Apache-2.0","readme":"# `@hyperledger/cactus-api-client` <!-- omit in toc -->\n\n- [Summary](#summary)\n- [Usage](#usage)\n  - [Routing to Cactus Node with connector to specific ledger](#routing-to-cactus-node-with-connector-to-specific-ledger)\n    - [Leverage the `ConsortiumDatabase` for discovery](#leverage-the-consortiumdatabase-for-discovery)\n    - [Use a provided `mainApiHost` and `ledgerId`](#use-a-provided-mainapihost-and-ledgerid)\n    - [Use the API host of a node directly](#use-the-api-host-of-a-node-directly)\n- [Public API Surface](#public-api-surface)\n  - [`DefaultConsortiumProvider`](#defaultconsortiumprovider)\n  - [`ApiClient`](#apiclient)\n\n## Summary\n\nThe Hyperledger Cactus API Client package is designed to be a generic extension with convenience features wrapped around the\n[**typescript-axios** flavored API clients][(https://github.com/OpenAPITools/openapi-generator/blob/v5.2.1/docs/generators/typescript-axios.md](https://github.com/OpenAPITools/openapi-generator/blob/v5.2.1/docs/generators/typescript-axios.md)) that we auto-generate and ship with each web service-enabled\nplugin such as the API clients of the\n* [**Manual Consortium Plugin** Typescript Axios API Client](https://github.com/hyperledger/cactus/tree/main/packages/cactus-plugin-consortium-manual/src/main/typescript/generated/openapi/typescript-axios)\n* [**Besu Connector** Typescript Axios API Client](https://github.com/hyperledger/cactus/tree/main/packages/cactus-plugin-ledger-connector-besu/src/main/typescript/generated/openapi/typescript-axios)\n* [**Corda Connector** Typescript Axios API Client](https://github.com/hyperledger/cactus/tree/main/packages/cactus-plugin-ledger-connector-corda/src/main/typescript/generated/openapi/typescript-axios)\n* [**Fabric Connector** Typescript Axios API Client](https://github.com/hyperledger/cactus/tree/main/packages/cactus-plugin-ledger-connector-fabric/src/main/typescript/generated/openapi/typescript-axios)\n* [**Quorum Connector** Typescript Axios API Client](https://github.com/hyperledger/cactus/tree/main/packages/cactus-plugin-ledger-connector-quorum/src/main/typescript/generated/openapi/typescript-axios)\n* [**API Server** Typescript Axios API Client](https://github.com/hyperledger/cactus/tree/main/packages/cactus-cmd-api-server/src/main/typescript/generated/openapi/typescript-axios)\n* [**Vault Keychain Plugin** Typescript Axios API Client](https://github.com/hyperledger/cactus/tree/main/packages/cactus-plugin-keychain-vault/src/main/typescript/generated/openapi/typescript-axios)\n\nThe code generation for the listed code folders above is done by the [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) tool that can convert OpenAPI V3 json specifications of ours straight into the program code of the API clients.\n\nThe above means that the `ApiClient` class is not the one containing the implementation\nresponsible for executing all the supported API calls by a Cactus node (which would make\nit a monolith, something that we try to avoid as it is the opposite of a flexible plugin\narchitecture)\n\nFor example you can use the `@hyperledger/cactus-api-client` node package to perform\nCactus node discovery based on ledger IDs (that can be obtained from the `ConsortiumDatabase` as defined by the [generated models](https://github.com/hyperledger/cactus/blob/main/packages/cactus-core-api/src/main/typescript/generated/openapi/typescript-axios/api.ts) of the `@hyperledger/cactus-core-api` package.\n\n> While you can generate API Clients for the Cactus API specifications in any supported langauge of the [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) the features provided by this package will have to be developed separately (if not already done by the Cactus maintainers).\n> Currently the only implementation of the abstract API Client and its features (node discovery) is in Typescript (e.g. the `@hyperledger/cactus-api-client` package).\n## Usage\n\n### Routing to Cactus Node with connector to specific ledger\n\nLet's say you have a consortium with several members who all have their own ledgers deployed as well.\nThe `ConsortiumDatabase` will therefore contain the entities pertaining to these entities\n(such as the ledgers or the members themselves) meaning that if you are developing an\napplication that needs to perform operations on one of the ledgers in the consortium then\nyou have a couple of different ways of obtaining an API client to do just that:\n\n#### Leverage the `ConsortiumDatabase` for discovery\n\n```typescript\nimport { ApiClient } from \"@hyperledger/cactus-api-client\";\n\nimport { ConsortiumDatabase, Ledger, LedgerType } from \"@hyperledger/cactus-core-api\";\n\nimport { PluginRegistry } from \"@hyperledger/cactus-core\";\n\nimport { DefaultApi as QuorumApi } from \"@hyperledger/cactus-plugin-ledger-connector-quorum\";\n\nconst mainFn = async () => {\n  const ledgerId = \"theIdOfYourLedgerInTheConsortiumDatabase\";\n\n  // How you obtain a consortium provider is dependent on which consortium\n  // plugin you use and your exact deployment scenario\n  const consortiumProvider: IAsyncProvider<ConsortiumDatabase> = ...;\n  const consortiumDatabase: ConsortiumDatabase = await consortiumProvider.get();\n  const consortium = consortiumDatabase.consortium[0];\n\n  const mainApiClient = new ApiClient({ basePath: consortium.mainApiHost });\n\n  // This client is now configured to point to a node that has a connector to\n  // the ledger referenced by `ledgerId`\n  const apiClient = await mainApiClient.ofLedger(ledgerId, QuorumApi);\n\n  // Use the client to perform any supported operation on the ledger\n};\n\nmainFn();\n```\n\n#### Use a provided `mainApiHost` and `ledgerId`\n\n```typescript\nimport { ApiClient } from \"@hyperledger/cactus-api-client\";\n\nimport { ConsortiumDatabase, Ledger, LedgerType } from \"@hyperledger/cactus-core-api\";\n\nimport { PluginRegistry } from \"@hyperledger/cactus-core\";\n\nimport { DefaultApi as QuorumApi } from \"@hyperledger/cactus-plugin-ledger-connector-quorum\";\n\nconst mainFn = async () => {\n  const ledgerId = \"theIdOfYourLedgerInTheConsortiumDatabase\";\n  const consortiumMainApiHost = \"https://cactus.example.com\";\n\n  const mainApiClient = new ApiClient({ basePath: consortiumMainApiHost });\n\n  // This client is now configured to point to a node that has a connector to\n  // the ledger referenced by `ledgerId`\n  const apiClient = await mainApiClient.ofLedger(ledgerId, QuorumApi);\n}\n\nmainFn();\n```\n\n#### Use the API host of a node directly\n\n```typescript\nimport { ApiClient } from \"@hyperledger/cactus-api-client\";\n\nimport { ConsortiumDatabase, Ledger, LedgerType } from \"@hyperledger/cactus-core-api\";\n\nimport { PluginRegistry } from \"@hyperledger/cactus-core\";\n\nimport { DefaultApi as QuorumApi } from \"@hyperledger/cactus-plugin-ledger-connector-quorum\";\n\nconst mainFn = async () => {\n  const nodeApiHost = \"https://my-node.cactus.example.com\";\n\n  const mainApiClient = new ApiClient({ basePath: nodeApiHost });\n\n  // This client is now configured to point to a node that has a connector to the ledger of your choice\n  const apiClient = await mainApiClient.extendWith(QuorumApi);\n}\n\nmainFn();\n```\n\n## Public API Surface\n\n### `DefaultConsortiumProvider`\n\nBuilds the default Consortium provider that can be used by this object to retrieve the Cactus Consortium metadata object when necessary (one such case is when we need information about the consortium nodes to perform routing requests to a specific ledger via a connector plugin, but later other uses could be added as well).\n\nThe DefaultConsortiumProvider class leverages the simplest consortium plugin that we have at the time of this writing: @hyperledger/cactus-plugin-consortium-manual which holds the consortium metadata as pre-configured by the consortium operators.\n\nThe pattern we use in the ApiClient class is that you can inject your own `IAsyncProvider<Consortium>` implementation which then will be used for routing information and in theory you can implement completely arbitrary consortium management in your own consortium plugins which then Cactus can use and leverage for the routing. This allows us to support any exotic consortium management algorithms that people may come up with such as storing the consortium definition in a multi-sig smart contract or have the list of consortium nodes be powered by some sort of automatic service discovery or anything else that people might think of.\n\n### `ApiClient`\n\nClass responsible for providing additional functionality to the DefaultApi classes of the generated clients (OpenAPI generator / typescript-axios).\n\nEach package (plugin) can define it's own OpenAPI spec which means that they all can ship with their own `DefaultApi` class that is generated directly from the respective OpenAPI spec of the package/plugin.\n\nThe functionality provided by this class is meant to be common traints that can be useful for all of those different `DefaultApi` implementations.\n\nOne such common trait is the client side component of the routing that decides which Cactus node to point the `ApiClient` towards (which is in itself ends up being the act of routing).\n\n@see — https ://github.com/OpenAPITools/openapi-generator/blob/v5.0.0-beta2/modules/openapi-generator/src/main/resources/typescript-axios/apiInner.mustache#L337\n\n@see — https ://github.com/OpenAPITools/openapi-generator/blob/v5.0.0/docs/generators/typescript-axios.md\n","readmeFilename":"README.md"}