Skip to main content

Getting Started with the SDK

Install the rickydata SDK, connect your wallet, and make your first query.

Prerequisites​

  • Node.js 18+
  • An Ethereum wallet (e.g., MetaMask, or a private key for server-side use)

Installation​

npm install @nickydata/sdk

Connect and Authenticate​

Browser (with wallet extension)​

import { AuthManager } from '@nickydata/sdk';

const auth = new AuthManager('https://api.knowledgedataflow.org');

// Use the browser wallet's sign function
const session = await auth.authenticateAuto({
  signFn: (message) => window.ethereum.request({
    method: 'personal_sign',
    params: [message, walletAddress],
  }),
  walletAddress: walletAddress,
});

console.log(`Authenticated as ${session.address}`);

Server-side (with private key)​

import { AuthManager } from '@nickydata/sdk';
import { Wallet } from 'ethers';

const wallet = new Wallet(process.env.PRIVATE_KEY);
const auth = new AuthManager('https://api.knowledgedataflow.org');

const session = await auth.authenticateAuto({
  signFn: (message) => wallet.signMessage(message),
  walletAddress: wallet.address,
});

CI/CD (GitHub Actions)​

import { AuthManager } from '@nickydata/sdk';

const auth = new AuthManager('https://api.knowledgedataflow.org');
const session = await auth.authenticateWithGitHubOIDC('owner/repo');

Make Your First Query​

// Query using KQL
const response = await auth.fetchWithAuth(
  'https://api.knowledgedataflow.org/api/v1/query',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      query: 'MATCH (n) RETURN labels(n) AS label, count(n) AS total ORDER BY total DESC'
    }),
  }
);

const result = await response.json();
console.log(result.data);

Write Data​

const writeResponse = await auth.fetchWithAuth(
  'https://api.knowledgedataflow.org/api/v1/write',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      operations: [{
        operation: 'create_node',
        label: 'Document',
        properties: {
          title: { String: 'My First Document' },
          created: { Integer: Date.now() },
          public: { Boolean: true },
        },
      }],
    }),
  }
);

const writeResult = await writeResponse.json();
console.log(`Created node: ${writeResult.affected_ids[0]}`);

Property Type Wrappers​

All property values in write operations must use type wrappers:

TypeWrapperExample
String{"String": "value"}{"name": {"String": "Alice"}}
Integer{"Integer": 42}{"age": {"Integer": 30}}
Float{"Float": 3.14}{"score": {"Float": 0.95}}
Boolean{"Boolean": true}{"active": {"Boolean": true}}
Vector{"Vector": [0.1, ...]}{"embedding": {"Vector": [0.1, 0.2, 0.3]}}

Next Steps​