​
Introduction

Sauron is the GraphQL API your application’s server will call to request the data you seek.

Check out the GraphQL Schema Reference to see details on all Queries, Mutations, Types and their descriptions.

​
eye-of-sauron Node.js SDK

We provide a Node.js SDK that makes it super easy to interact with the Sauron API. eyeofsauron completely abstracts away the complexity of authentication and interacting with the GraphQL APIs.

​
Install eye-of-sauron

npm i -g @gandalf-network/eyeofsauron

eyeofsauron generate

This will generate an eyeofsauron folder in your project root directory.

​
Usage

​
Import the library

// Typescript
import Eye, { Source } from './eyeofsauron';

// ESModules
import Eye, { Source } from './eyeofsauron/index.js';

// CommonJS
const Connect = require("@gandalf-network/connect");
const { Source } = require('./eyeofsauron');

​
Get Activity

const eye = new Eye({privateKey: process.env.PRIVATE_KEY})

const { data } = await eye.getActivity({dataKey: dataKey,  source: Source.Amazon, limit: 100, page: 2})

​
Authentication

eyeofsauron SDK handles all of this authentication stuff automagically! You might want to consider using it instead.

Every request to the Sauron API needs to be authenticated using your privateKey. This is required to validate that the data request is truly coming from your application.

1

Prepare the signature

Start by creating a digital signature of your request’s body. You’ll need to hash the body of your request using SHA-256 and then sign the hash with ECDSA using your privateKey.

2

Encode the signature

After signing, encode the digital signature using Base64.

3

Add signature header

Add the Base64-encoded signature to the request’s headers with the key X-Gandalf-Signature.

Securing your privateKey is extremely important. All requests to Sauron should be made server-side.

See example code snippets:

import os
import json
import hashlib
import base64
from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport
from ecdsa import SigningKey, NIST256p

# Step 1: Prepare the signature
def prepare_signature(request_body):
    sha256_hash = hashlib.sha256(request_body.encode('utf-8')).digest()
    private_key_hex = os.environ.get('PRIVATE_KEY')
    private_key_bytes = bytes.fromhex(private_key_hex)
    private_key = SigningKey.from_string(private_key_bytes, curve=NIST256p)
    signature = private_key.sign(sha256_hash)
    return signature

# Step 2: Encode the signature
def encode_signature(signature):
    return base64.b64encode(signature).decode('utf-8')

# Step 3: Add signature header
def add_signature_header(signature_b64):
    return {'X-Gandalf-Signature': signature_b64}

# Example GraphQL query
query = gql("""
    query getActivity($dataKey: String!, $source: Source!, $limit: Int, $page: Int) {
        getActivity(dataKey: $dataKey, source: $source, limit: $limit, page: $page) {
            # ... specify the fields you want to get back
        }
    }
""")

# GraphQL client setup
transport = RequestsHTTPTransport(
    url='https://sauron.gandalf.network/public/gql',
    use_json=True,
)

client = Client(transport=transport, fetch_schema_from_transport=True)

# Variables for the GraphQL query
variables = {
    "dataKey": "your_data_key",
    "source": "your_source",
    "limit": 10,
    "page": 1
}

# Serialize the query and variables to create a JSON representation
request_body = json.dumps({'query': str(query), 'variables': variables})
signature = prepare_signature(request_body)
signature_b64 = encode_signature(signature)

# Add the signature to the headers
transport.headers = add_signature_header(signature_b64)

# Execute the GraphQL query
result = client.execute(query, variable_values=variables)
print(result)

​
Requesting Data

Calling the getActivity() query is how you pull data on your users.

Every Query or Mutation in the Sauron GraphQL API is accessible in eye-of-sauron as a function. You can read about all Queries, Mutations & Types in the Schema Reference.
ConnectGems