Fluree Client SDK for TypeScript/JavaScript
This is the official Fluree client SDK for TypeScript/JavaScript. It is a wrapper around the Fluree API, providing a more convenient way to interact with Fluree v3 databases.
Installation
npm install @fluree/fluree-client
Usage
To use the Fluree client SDK, you need to import the FlureeClient
class from the package and create a new instance of it. You can then use the instance to interact with a Fluree database.
import { FlureeClient } from '@fluree/fluree-client';
const client = new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
await client
.query({
select: { freddy: ['*'] },
})
.send();
Client Config
The FlureeClient
constructor takes an optional config
object with the following properties:
{
isFlureeHosted,
apiKey,
ledger,
host,
port,
create,
privateKey,
signMessages,
defaultContext,
}
For example:
const client = new FlureeClient({
ledger: 'fluree-client/client',
host: 'localhost',
port: 58090,
create: true,
privateKey: 'XXX...XXX',
signMessages: true,
defaultContext: {
schema: 'http://schema.org/',
name: 'schema:name',
},
});
You can also update the configuration of an existing client by using the configure()
method:
const client = new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
});
const privateKey = client.generateKeyPair();
client.configure({
privateKey,
signMessages: true,
});
Methods
connect()
In order to use the FlureeClient instance, you must first connect to the Fluree instance. This will test the connection and (if config.create === true
) create the ledger if it does not exist.
It will also throw an error if the connection fails (e.g. invalid host, ledger does not exist, etc.)
const connectedClient = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
create()
The create()
method can be used to create a new ledger on the Fluree instance. This will throw an error if the ledger already exists.
The returned FlureeClient will be configured to use the new ledger.
const client = new FlureeClient({
host: 'localhost',
port: 8080,
ledger: 'fluree-client/client',
});
const createdClient = await client.create('new-ledger');
query()
The query()
method creates a new QueryInstance
for querying the Fluree database. The QueryInstance
can be used & re-used to build, sign, and send queries to the Fluree instance.
See the QueryInstance section for more information.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
const queryInstance = client.query({
select: { freddy: ['*'] },
});
const response = await queryInstance.send();
transact()
The transact()
method creates a new TransactionInstance
for transacting with the Fluree database. The TransactionInstance
can be used & re-used to build, sign, and send transactions to the Fluree instance.
See the TransactionInstance section for more information.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
const transactionInstance = client.transact({
insert: { '@id': 'freddy', name: 'Freddy' },
});
const response = await transactionInstance.send();
history()
The history()
method creates a new HistoryQueryInstance
for querying the history of the Fluree database. The HistoryQueryInstance
can be used & re-used to build, sign, and send history queries to the Fluree instance.
See the HistoryQueryInstance section for more information.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
const historyQuery = client.history({
'commit-details': true,
t: { at: 'latest' },
});
const response = await historyQuery.send();
generateKeyPair()
Automatically generates a new key pair and adds it to the FlureeClient instance. The public key and DID will be derived from the private key and added to the FlureeClient instance.
const client = new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
});
client.generateKeyPair();
const privateKey = client.getPrivateKey();
setKey()
This adds a private key to the FlureeClient instance. This key will be used to sign messages by default when using the sign() method on a query or transaction.
The public key and DID will be derived from the private key and added to the FlureeClient instance.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
const privateKey = 'XXX...XXX';
client.setKey(privateKey);
const publicKey = client.getPublicKey();
const did = client.getDid();
getPrivateKey()
The getPrivateKey()
method returns the private key of the FlureeClient instance (if one has been set).
NOTE: Be careful with this method. It is not recommended to log or expose private keys.
const client = new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
});
client.generateKeyPair();
const privateKey = client.getPrivateKey();
getPublicKey()
The getPublicKey()
method returns the public key of the FlureeClient instance (if one has been set).
const client = new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
});
client.generateKeyPair();
const publicKey = client.getPublicKey();
getDid()
The getDid()
method returns the DID of the FlureeClient instance (if one has been set).
const client = new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
});
client.generateKeyPair();
const did = client.getDid();
setContext()
The setContext()
method sets the default context for the FlureeClient instance. This context will be used for all queries and transactions by default.
Unlike addToContext()
, which merges new context elements into any existing context for the client, this method will replace the existing default context entirely.
const client = new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
defaultContext: { schema: 'http://schema.org/' },
});
client.setContext({ ex: 'http://example.org/' });
addToContext()
The addToContext()
method adds to the default context for the FlureeClient instance. This context will be used for all queries and transactions by default.
If a default context already exists, the new context will be merged with the existing context.
const client = new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
defaultContext: { schema: 'http://schema.org/' },
});
client.addToContext({ ex: 'http://example.org/' });
getContext()
The getContext()
method returns the default context for the FlureeClient instance (if one has been set).
const client = new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
defaultContext: { schema: 'http://schema.org/' },
});
const context = client.getContext();
QueryInstance
The QueryInstance
class is used to build, sign, and send queries to the Fluree instance.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
const queryInstance = client.query({
select: { freddy: ['*'] },
});
const signedQueryInstance = queryInstance.sign('XXX...XXX');
const response = await signedQueryInstance.send();
Additional Methods:
send()
The send()
method sends the query to the Fluree instance and returns the response.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
const queryInstance = client.query({
select: { freddy: ['*'] },
});
const response = await queryInstance.send();
sign()
The sign()
method signs the query with the private key of the FlureeClient instance. If no private key has been set, or if no privateKey parameter is passed to sign()
, it will throw an error.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
let signedQueryInstance = client
.query({
select: { freddy: ['*'] },
})
.sign('XXX...XXX');
client.generateKeyPair();
signedQueryInstance = client
.query({
select: { freddy: ['*'] },
})
.sign();
const response = await signedQueryInstance.send();
getQuery()
The getQuery()
method returns the query object of the QueryInstance.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
defaultContext: { ex: 'http://example.org/' },
}).connect();
const queryInstance = client.query({
select: { 'ex:freddy': ['*'] },
});
const query = queryInstance.getQuery();
console.log(query);
getSignedQuery()
The getSignedQuery()
method returns the signed query of the QueryInstance in the form of a JWS string.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
client.generateKeyPair();
const queryInstance = client.query({
select: { freddy: ['*'] },
});
const signedQueryInstance = queryInstance.sign();
const signedQuery = signedQueryInstance.getSignedQuery();
console.log(signedQuery);
TransactionInstance
The TransactionInstance
class is used to build, sign, and send transactions to the Fluree instance.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
const transaction = client.transact({
insert: { '@id': 'freddy', name: 'Freddy' },
});
const signedTransaction = transaction.sign('XXX...XXX');
const response = await signedTransaction.send();
Additional Methods:
send()
The send()
method sends the transaction to the Fluree instance and returns the response.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
const transaction = client.transact({
insert: { '@id': 'freddy', name: 'Freddy' },
});
const response = await transaction.send();
sign()
The sign()
method signs the transaction with the private key of the FlureeClient instance. If no private key has been set, or if no privateKey parameter is passed to sign()
, it will throw an error.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
let signedTransaction = client
.transact({
insert: { '@id': 'freddy', name: 'Freddy' },
})
.sign('XXX...XXX');
client.generateKeyPair();
signedTransaction = client
.transact({
insert: { '@id': 'freddy', name: 'Freddy' },
})
.sign();
const response = await signedTransaction.send();
getTransaction()
The getTransaction()
method returns the transaction object of the TransactionInstance.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
const transaction = client.transact({
insert: { '@id': 'freddy', name: 'Freddy' },
});
const txn = transaction.getTransaction();
console.log(txn);
getSignedTransaction()
The getSignedTransaction()
method returns the signed transaction of the TransactionInstance in the form of a JWS string.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
client.generateKeyPair();
const transaction = client.transact({
insert: { '@id': 'freddy', name: 'Freddy' },
});
const signedTransaction = transaction.sign();
const signedTxn = signedTransaction.getSignedTransaction();
console.log(signedTxn);
HistoryQueryInstance
The HistoryQueryInstance
class is used to build, sign, and send history queries to the Fluree instance.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
const historyQuery = client.history({
'commit-details': true,
t: { at: 'latest' },
});
const response = await historyQuery.send();
send()
The send()
method sends the history query to the Fluree instance and returns the response.
const client = await new FlureeClient({
isFlureeHosted: true,
apiKey: process.env.FLUREE_API_KEY,
ledger: 'fluree-jld/387028092978173',
}).connect();
const historyQuery = client.history({
'commit-details': true,
t: { at: 'latest' },
});
const response = await historyQuery.send();