Hgraph SDK

Hgraph is a Web3 data infrastructure company focused on tooling for the Hedera network and beyond. You can sign up for an account and access our account dashboard console. This SDK intends to make developing with our API easy, flexible, and fast.

Hgraph Docs 📖

• Hgraph SDK documentation →
• About the GraphQL API →
• About GraphQL subscriptions →
• Full Hgraph docs →

Installation & usage

To install the @hgraph.io/sdk, run the following command:

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.

Authenticating

To interact with Hgraph's services, you'll need to authenticate your requests. There are currently two methods for authentication:

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:

import HgraphSDK from '@hgraph.io/sdk';

const hgraph = new HgraphSDK({
  headers: {
    'x-api-key': 'your-api-key-here',
  },
});

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.

Learn more about JWTs at 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 for assistance. :::

Example usage

Once you have your JWT, you can authenticate your requests as follows:

import HgraphSDK from '@hgraph.io/sdk';

const hgraph = new HgraphSDK({
  headers: {
    Authorization: `Bearer your-jwt-token-here`,
  },
});

Examples

Overview

To help you get started quickly, we offer a collection of quick-start template repositories tailored for various development environments. These templates come pre-configured with essential settings and dependencies, allowing you to set up your project with minimal effort. By leveraging these templates, you can quickly integrate Hgraph into your project and begin building right away.

Available Templates

Choose the template that best fits your development environment:

Node →
Ideal for backend and server-side applications using Node.js.

Browser →
Tailored for web applications running directly in the browser, enabling quick integration with Hgraph APIs.

Next.js →
Optimized for full-stack and server-rendered applications using Next.js.

React →
For frontend projects using React, providing an easy setup for single-page applications.

React Native →
Suitable for mobile app development with React Native, allowing cross-platform development with Hgraph.

Subscriptions

Our documentation introduces the subscription capabilities in the Hgraph SDK, enabling developers to easily set up and manage real-time data streams with GraphQL. It provides guidance on using built-in methods to track data changes and efficiently handle subscription lifecycles.

GraphQL Subscriptions (docs) →

Contributing

If you're interested in contributing to this repository or experimenting with the codebase, follow the steps below to set up your local development environment.

Getting Started

1. Clone the Repository

First, clone the repository to your local machine using GitHub CLI:

gh repo clone hgraph-io/sdk

2. Install Dependencies

Navigate to the cloned repository and install all necessary npm packages:

npm install

3. Build and Watch for Changes

To automatically rebuild the project whenever you make changes, run:

npm run watch

This command watches for file changes and rebuilds the project accordingly.

4. Use the Local SDK in Another Project

If you want to use your local version of the SDK in another project for testing or development purposes, you can set it as a local dependency:

npm install ../sdk

This command tells npm to use the SDK from your local file system instead of fetching it from the npm registry.

Debugging

To test the WebSocket connection and ensure that everything is set up correctly, you can use wscat, a WebSocket client for the command line.

Test WebSocket Connection

Replace <YOUR_API_KEY> with your actual API key and run:

wscat -s 'graphql-ws' -H 'x-api-key: <YOUR_API_KEY>' -c wss://testnet.hedera.api.hgraph.dev/v1/graphql

This command initiates a WebSocket connection to the GraphQL endpoint at wss://testnet.hedera.api.hgraph.dev/v1/graphql using your API key for authentication.

Note: If you don't have wscat installed, you can install it globally using:

npm install -g wscat

Versioning

This Software Development Kit (SDK) is actively being developed in conjunction with the Hgraph API to ensure seamless integration and compatibility between the two. We are committed to adopting Semantic Versioning standards, which will provide clear and predictable updates, making it easier for developers to manage dependencies and stay informed about changes.

Before we release version 1.0, updates may introduce breaking changes as we refine the software. To maintain stability in production, we recommend pinning dependencies to an exact version using --save-exact when installing the package.