From bbfc257b7a08db714fa39339b70e93d0beb9f6ca Mon Sep 17 00:00:00 2001 From: itsbrandond Date: Thu, 20 Mar 2025 17:28:41 -0400 Subject: [PATCH 1/2] update sdk installation page --- docs/hgraph-sdk/installation.md | 125 +++++++++++++++++++++++++++----- 1 file changed, 108 insertions(+), 17 deletions(-) diff --git a/docs/hgraph-sdk/installation.md b/docs/hgraph-sdk/installation.md index 2dbe1da..ea056e1 100644 --- a/docs/hgraph-sdk/installation.md +++ b/docs/hgraph-sdk/installation.md @@ -2,26 +2,70 @@ sidebar_position: 1 --- -# Installation & Usage +# Installation & Setup -To install the `@hgraph.io/sdk`, run the following command: +This guide explains how to install and set up the Hgraph SDK, providing streamlined access to Hgraph's API and tools for the Hedera network. +## Requirements & Compatibility + +Before installation, ensure you have: + +- **Node.js** (v18.x or higher recommended) +- **npm** package manager + +Check your versions: +```bash +node -v +npm -v +``` + +## Installing the SDK + +### Using npm (Recommended) + +Install the latest stable version: ```bash npm install --save-exact @hgraph.io/sdk@latest ``` -This command will add the latest version of the SDK to your project's dependencies, ensuring consistent behavior across environments. +Using `--save-exact` ensures consistent behavior across environments by pinning dependencies to specific versions, aligning with [semantic versioning](https://semver.org). + +### Install a Specific Version (Optional) + +To install a specific SDK version: +```bash +npm install --save-exact @hgraph.io/sdk@x.y.z +``` +Replace `x.y.z` with the desired version number. + +### Local Development Installation (Advanced) + +Clone and build the SDK locally for development or testing: + +```bash +gh repo clone hgraph-io/sdk +cd sdk +npm install +npm run watch +``` + +Use your local SDK in another project: +```bash +npm install ../sdk +``` ## Authenticating -To interact with Hgraph's services, you'll need to authenticate your requests. There are currently two methods for authentication: +To interact with Hgraph's services, you'll need to authenticate your requests. The SDK supports two primary authentication methods: ### Using an API key -To authenticate using an API key, include your API key in the `x-api-key header` of each request. Here's how you can set it up: +Include your API key in the `x-api-key` header: ```javascript -const hgraph = new HGraphSDK({ +import HgraphSDK from '@hgraph.io/sdk'; + +const hgraph = new HgraphSDK({ headers: { 'x-api-key': 'your-api-key-here', }, @@ -30,24 +74,71 @@ const hgraph = new HGraphSDK({ ### Using a JSON Web Token (JWT) -For enhanced security, especially in front-end applications, we are rolling out authentication using JSON Web Tokens (JWT). JWTs allow for secure transmission of authentication details without exposing sensitive information. +JWT authentication provides enhanced security, particularly for front-end applications. This feature is in early access. [Contact support](https://docs.hgraph.com/support) to enable this method. + +Example usage: + +```javascript +import HgraphSDK from '@hgraph.io/sdk'; + +const hgraph = new HgraphSDK({ + headers: { + Authorization: `Bearer your-jwt-token-here`, + }, +}); +``` Learn more about JWTs at [jwt.io](https://jwt.io/). -:::note Early access -JWT authentication is in the early access phase. If you're interested in implementing this method, please [reach out to support](/support) for assistance. -::: +## Quick-Start Examples & Templates + +Quickly integrate Hgraph into your project with pre-configured templates: + +- [Node.js Template](https://github.com/hgraph-io/nodejs-template): Ideal for backend Node.js applications. +- [Browser Template](https://github.com/hgraph-io/browser-template): Web apps running directly in the browser. +- [Next.js Template](https://github.com/hgraph-io/nextjs-template): Server-rendered Next.js apps. +- [React Template](https://github.com/hgraph-io/react-template): Single-page React applications. +- [React Native Template](https://github.com/hgraph-io/react-native-template): Cross-platform mobile development. -#### Example usage +Refer to each template's README for detailed instructions. -Once you have your JWT, you can authenticate your requests as follows: +## Basic SDK Usage + +Perform a basic request: ```javascript -import HGraphSDK from '@hgraph.io/sdk'; +import HgraphSDK from '@hgraph.io/sdk'; -const hgraph = new HGraphSDK({ - headers: { - Authorization: `Bearer your-jwt-token-here`, - }, +const hgraph = new HgraphSDK({ + headers: { 'x-api-key': 'your-api-key-here' } }); + +// Example request +hgraph.query({ /* your query here */ }) + .then(response => console.log(response)) + .catch(error => console.error(error)); ``` + +## Troubleshooting & Debugging + +### Testing WebSocket Connection + +Verify your connection with `wscat`: + +```bash +wscat -s 'graphql-ws' -H 'x-api-key: ' -c wss://testnet.hedera.api.hgraph.dev/v1/graphql +``` + +Install `wscat` globally if needed: +```bash +npm install -g wscat +``` + +### Common Issues + +- **Authentication Errors**: Verify API key or JWT. +- **Version Mismatch**: Ensure SDK version compatibility. + +## Versioning & Updates + +The SDK follows [Semantic Versioning](https://semver.org). Before version 1.0, updates may introduce breaking changes. Pin dependencies to exact versions for stability. \ No newline at end of file From c8979502674b94a6a1eec9eeebd7d20c49dfffab Mon Sep 17 00:00:00 2001 From: itsbrandond Date: Mon, 24 Mar 2025 17:46:02 -0400 Subject: [PATCH 2/2] updates to installation page --- docs/hgraph-sdk/installation.md | 100 +++++++++++++++++++++++--------- 1 file changed, 74 insertions(+), 26 deletions(-) diff --git a/docs/hgraph-sdk/installation.md b/docs/hgraph-sdk/installation.md index ea056e1..d0a50f3 100644 --- a/docs/hgraph-sdk/installation.md +++ b/docs/hgraph-sdk/installation.md @@ -4,16 +4,17 @@ sidebar_position: 1 # Installation & Setup -This guide explains how to install and set up the Hgraph SDK, providing streamlined access to Hgraph's API and tools for the Hedera network. +Hgraph provides custom solutions and blazing fast API access. You can [get your free API key](https://hgraph.com/pricing) and upgrade later. åThis guide explains how to install and set up the Hgraph SDK, providing streamlined access to Hgraph's API and tools for the Hedera network. ## Requirements & Compatibility Before installation, ensure you have: -- **Node.js** (v18.x or higher recommended) -- **npm** package manager +- **Node.js** ([install](https://nodejs.org/en)) +- **npm package manager** Check your versions: + ```bash node -v npm -v @@ -21,9 +22,16 @@ npm -v ## Installing the SDK +First, ensure you initialize your project with: + +```bash +npm init -y +``` + ### Using npm (Recommended) Install the latest stable version: + ```bash npm install --save-exact @hgraph.io/sdk@latest ``` @@ -33,14 +41,16 @@ Using `--save-exact` ensures consistent behavior across environments by pinning ### Install a Specific Version (Optional) To install a specific SDK version: + ```bash npm install --save-exact @hgraph.io/sdk@x.y.z ``` + Replace `x.y.z` with the desired version number. ### Local Development Installation (Advanced) -Clone and build the SDK locally for development or testing: +For contributors and advanced users interested in local development, clone and build the SDK locally: ```bash gh repo clone hgraph-io/sdk @@ -49,16 +59,17 @@ npm install npm run watch ``` -Use your local SDK in another project: +To use your local SDK in another project: + ```bash npm install ../sdk ``` -## Authenticating +# Authenticating -To interact with Hgraph's services, you'll need to authenticate your requests. The SDK supports two primary authentication methods: +To interact with Hgraph's services, you'll need to authenticate your requests. The SDK supports two primary authentication methods **[(see all available authentication methods)](/hgraph-sdk/endpoints-authorization)**: -### Using an API key +## Using an API key Include your API key in the `x-api-key` header: @@ -72,9 +83,9 @@ const hgraph = new HgraphSDK({ }); ``` -### Using a JSON Web Token (JWT) +## Using a JSON Web Token (JWT) -JWT authentication provides enhanced security, particularly for front-end applications. This feature is in early access. [Contact support](https://docs.hgraph.com/support) to enable this method. +JWT authentication provides enhanced security, particularly for front-end applications. This feature is currently in early access. [Contact support](https://docs.hgraph.com/support) to enable this method. Example usage: @@ -88,21 +99,23 @@ const hgraph = new HgraphSDK({ }); ``` -Learn more about JWTs at [jwt.io](https://jwt.io/). +**[See all available authentication methods.](/hgraph-sdk/endpoints-authorization)** -## Quick-Start Examples & Templates +# Quick-Start Examples & Templates -Quickly integrate Hgraph into your project with pre-configured templates: +Quickly integrate Hgraph into your project with our pre-configured templates: - [Node.js Template](https://github.com/hgraph-io/nodejs-template): Ideal for backend Node.js applications. -- [Browser Template](https://github.com/hgraph-io/browser-template): Web apps running directly in the browser. +- [Browser Template](https://github.com/hgraph-io/browser-template): For web apps running directly in the browser. - [Next.js Template](https://github.com/hgraph-io/nextjs-template): Server-rendered Next.js apps. - [React Template](https://github.com/hgraph-io/react-template): Single-page React applications. - [React Native Template](https://github.com/hgraph-io/react-native-template): Cross-platform mobile development. Refer to each template's README for detailed instructions. -## Basic SDK Usage +--- + +# Basic SDK Usage Perform a basic request: @@ -119,9 +132,15 @@ hgraph.query({ /* your query here */ }) .catch(error => console.error(error)); ``` -## Troubleshooting & Debugging +# Subscriptions + +The Hgraph SDK supports GraphQL subscriptions for real-time data updates. Our [GraphQL Subscriptions documentation](https://docs.hgraph.com/graphql-api/subscriptions) provides guidance on setting up and managing these connections, allowing you to track data changes and efficiently handle subscription lifecycles. + +**[GraphQL Subscriptions (docs) →](https://docs.hgraph.com/graphql-api/subscriptions)** + +# Troubleshooting & Debugging -### Testing WebSocket Connection +## Testing WebSocket Connection Verify your connection with `wscat`: @@ -129,16 +148,45 @@ Verify your connection with `wscat`: wscat -s 'graphql-ws' -H 'x-api-key: ' -c wss://testnet.hedera.api.hgraph.dev/v1/graphql ``` -Install `wscat` globally if needed: +If you don't have `wscat` installed, install it globally: + ```bash npm install -g wscat ``` -### Common Issues - -- **Authentication Errors**: Verify API key or JWT. -- **Version Mismatch**: Ensure SDK version compatibility. - -## Versioning & Updates - -The SDK follows [Semantic Versioning](https://semver.org). Before version 1.0, updates may introduce breaking changes. Pin dependencies to exact versions for stability. \ No newline at end of file +## Common Issues + +- **Authentication Errors**: Verify that your API key or JWT is correct. +- **Version Mismatch**: Ensure that the SDK version is compatible with your project setup. + +# Contributing + +If you're interested in contributing to the Hgraph SDK or exploring the codebase further, please follow these steps to set up your local development environment: + +1. **Clone the Repository** + ```bash + gh repo clone hgraph-io/sdk + ``` +2. **Install Dependencies** + Navigate to the cloned repository and install the necessary npm packages: + ```bash + npm install + ``` +3. **Build and Watch for Changes** + Automatically rebuild the project when file changes are detected: + ```bash + npm run watch + ``` +4. **Use the Local SDK in Another Project** + For testing or development purposes, you can use your local SDK: + ```bash + npm install ../sdk + ``` +5. **Debugging with WebSocket** + Use the WebSocket connection test (as described above) to ensure that everything is configured correctly. + +Your contributions and feedback are essential to improving the SDK for the entire Hgraph community. + +# Versioning & Updates + +The SDK adheres to [Semantic Versioning](https://semver.org). Until version 1.0 is officially released, updates may introduce breaking changes. To maintain stability in production environments, we recommend pinning dependencies to exact versions using the `--save-exact` flag during installation. \ No newline at end of file