Deprecation Notice: grpc-web has been deprecated and is no longer supported. Please use the HTTP API instead. This original document has been kept only for historical reference.
A lightweight, fast Typescript interface for Farcaster Hubs. Designed to work with Hubble and any other Hub that implements the Farcaster protocol.
- Call any Hub endpoint from a browser environment using gRPC-Web.
- Serializes and deserializes Farcaster protobufs into Javascript objects.
- Has helpers to create and sign Farcaster messages.
- Written entirely in TypeScript, with strict types for safety.
Install @farcaster/hub-web with the package manager of your choice
npm install @farcaster/hub-web
yarn add @farcaster/hub-web
pnpm install @farcaster/hub-web
The @farcaster/hub-web APIs are largely the same as @farcaster/hub-nodejs. Read the @farcaster/hub-nodejs documentation and browse code examples. We're also including sample @farcaster/hub-web code below as well as a list of differences with the other package.
import { getHubRpcClient } from '@farcaster/hub-web';
(async () => {
const client = getHubRpcClient('https://testnet1.farcaster.xyz:2285');
const castsResult = await client.getCastsByFid({ fid: 15 });
castsResult.map((casts) => casts.messages.map((cast) => console.log(cast.data?.castAddBody?.text)));
})();
The method to construct a Hub gRPC client differs from @farcaster/hub-nodejs. Use getHubRpcClient
, which returns a Hub gRPC-Web client. Make sure that the gRPC server you're connecting to implements a gRPC-Web proxy. The standard is to expose the gRPC-Web proxy at port 2285.
import { getHubRpcClient } from '@farcaster/hub-web';
(async () => {
const client = getHubRpcClient('https://testnet1.farcaster.xyz:2285');
// If you're using gRPC-Web from a Nodejs environment, add a second false parameter
// const nodeClient = getHubRpcClient('https://testnet1.farcaster.xyz:2285', false);
})();
Type | Description |
---|---|
HubRpcClient |
A new gRPC-Web Client instance. |
Name | Type | Description |
---|---|---|
url |
string |
Address and RPC port string (e.g. https://testnet1.farcaster.xyz:2285 ) |
isBrowser |
boolean |
Optional parameter indicating whether to use the gRPC-Web Nodejs transport |
gRPC-Web hub event streams are instances of the Observable class in @farcaster/hub-web.
import { getHubRpcClient } from '@farcaster/hub-web';
async () => {
const client = getHubRpcClient('https://testnet1.farcaster.xyz:2285');
const result = client.subscribe({ eventTypes: [HubEventType.PRUNE_MESSAGE], fromId: 0 });
result.map((observable) => {
observable.subscribe({
next(event: HubEvent) {
console.log('received event', event);
},
error(err) {
console.error(err);
},
});
});
};
Type | Description |
---|---|
HubResult<Observable<HubEvent>> |
An Observable stream wrapped in a Result |
Name | Type | Description |
---|---|---|
fromId |
number |
(Optional) ID of the hub event to start streaming from. A fromId of 0 will stream all events from the hub, and passing no fromId will start the stream from the present moment. |
eventTypes |
HubEventType[] |
Array of hub event types to return. If eventTypes is [] , all event types will be returned. |
Please see our contributing guidelines before making a pull request.
MIT License