Skip to content

Latest commit

 

History

History
120 lines (80 loc) · 4.96 KB

README.grpcweb.md

File metadata and controls

120 lines (80 loc) · 4.96 KB
Raw

@farcaster/hub-web

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.

Features

  • 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.

Installation

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

Documentation

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.

Getting start: fetching casts

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)));
})();

Instantiating a client

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.

Usage

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);
})();

Returns

Type Description
HubRpcClient A new gRPC-Web Client instance.

Parameters

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

Streaming hub events

gRPC-Web hub event streams are instances of the Observable class in @farcaster/hub-web.

Usage

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);
      },
    });
  });
};

Returns

Type Description
HubResult<Observable<HubEvent>> An Observable stream wrapped in a Result

Parameters

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.

Contributing

Please see our contributing guidelines before making a pull request.

License

MIT License