@farcaster/hub-web 0.6.5 → 0.6.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.grpcweb.md +120 -0
  2. package/README.md +27 -87
  3. package/dist/index.d.ts +420 -10
  4. package/dist/index.js +49 -6
  5. package/dist/index.mjs +49 -6
  6. package/package.json +3 -4
package/README.grpcweb.md ADDED
@@ -0,0 +1,120 @@
1
+ # @farcaster/hub-web
2
+
3
+ **Deprecation Notice:**
4
+ grpc-web has been deprecated and will be removed in a future release. Please use the [HTTP API](./README.md) instead.
5
+
6
+
7
+ A lightweight, fast Typescript interface for Farcaster Hubs. Designed to work with [Hubble](https://github.com/farcasterxyz/hubble/) and any other Hub that implements the [Farcaster protocol](https://github.com/farcasterxyz/protocol).
8
+
9
+ ## Features
10
+
11
+ - Call any Hub endpoint from a browser environment using gRPC-Web.
12
+ - Serializes and deserializes Farcaster protobufs into Javascript objects.
13
+ - Has helpers to create and sign Farcaster messages.
14
+ - Written entirely in TypeScript, with strict types for safety.
15
+
16
+ ## Installation
17
+
18
+ Install @farcaster/hub-web with the package manager of your choice
19
+
20
+ ```bash
21
+ npm install @farcaster/hub-web
22
+ yarn add @farcaster/hub-web
23
+ pnpm install @farcaster/hub-web
24
+ ```
25
+
26
+ ## Documentation
27
+
28
+ The @farcaster/hub-web APIs are largely the same as @farcaster/hub-nodejs. Read the [@farcaster/hub-nodejs documentation](https://github.com/farcasterxyz/hubble/tree/main/packages/hub-nodejs/docs) and browse code [examples](https://github.com/farcasterxyz/hubble/tree/main/packages/hub-nodejs/examples). We're also including sample @farcaster/hub-web code below as well as a list of differences with the other package.
29
+
30
+ ### Getting start: fetching casts
31
+
32
+ ```typescript
33
+ import { getHubRpcClient } from '@farcaster/hub-web';
34
+
35
+ (async () => {
36
+ const client = getHubRpcClient('https://testnet1.farcaster.xyz:2285');
37
+
38
+ const castsResult = await client.getCastsByFid({ fid: 15 });
39
+
40
+ castsResult.map((casts) => casts.messages.map((cast) => console.log(cast.data?.castAddBody?.text)));
41
+ })();
42
+ ```
43
+
44
+ ### Instantiating a client
45
+
46
+ 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.
47
+
48
+ #### Usage
49
+
50
+ ```typescript
51
+ import { getHubRpcClient } from '@farcaster/hub-web';
52
+
53
+ (async () => {
54
+ const client = getHubRpcClient('https://testnet1.farcaster.xyz:2285');
55
+
56
+ // If you're using gRPC-Web from a Nodejs environment, add a second false parameter
57
+ // const nodeClient = getHubRpcClient('https://testnet1.farcaster.xyz:2285', false);
58
+ })();
59
+ ```
60
+
61
+ #### Returns
62
+
63
+ | Type | Description |
64
+ | :------------- | :------------------------------ |
65
+ | `HubRpcClient` | A new gRPC-Web Client instance. |
66
+
67
+ #### Parameters
68
+
69
+ | Name | Type | Description |
70
+ | :---------- | :-------- | :------------------------------------------------------------------------- |
71
+ | `url` | `string` | Address and RPC port string (e.g. `https://testnet1.farcaster.xyz:2285`) |
72
+ | `isBrowser` | `boolean` | Optional parameter indicating whether to use the gRPC-Web Nodejs transport |
73
+
74
+ ### Streaming hub events
75
+
76
+ gRPC-Web hub event streams are instances of the [Observable class](https://rxjs.dev/guide/observable) in @farcaster/hub-web.
77
+
78
+ #### Usage
79
+
80
+ ```typescript
81
+ import { getHubRpcClient } from '@farcaster/hub-web';
82
+
83
+ async () => {
84
+ const client = getHubRpcClient('https://testnet1.farcaster.xyz:2285');
85
+
86
+ const result = client.subscribe({ eventTypes: [HubEventType.PRUNE_MESSAGE], fromId: 0 });
87
+
88
+ result.map((observable) => {
89
+ observable.subscribe({
90
+ next(event: HubEvent) {
91
+ console.log('received event', event);
92
+ },
93
+ error(err) {
94
+ console.error(err);
95
+ },
96
+ });
97
+ });
98
+ };
99
+ ```
100
+
101
+ #### Returns
102
+
103
+ | Type | Description |
104
+ | :-------------------------------- | :---------------------------------------------------------------------------- |
105
+ | `HubResult<Observable<HubEvent>>` | An [Observable](https://rxjs.dev/guide/observable) stream wrapped in a Result |
106
+
107
+ #### Parameters
108
+
109
+ | Name | Type | Description |
110
+ | :----------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
111
+ | `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. |
112
+ | `eventTypes` | `HubEventType[]` | Array of hub event types to return. If `eventTypes` is `[]`, all event types will be returned. |
113
+
114
+ ## Contributing
115
+
116
+ Please see our [contributing guidelines](https://github.com/farcasterxyz/hubble/blob/main/CONTRIBUTING.md) before making a pull request.
117
+
118
+ ## License
119
+
120
+ MIT License
package/README.md CHANGED
@@ -1,111 +1,51 @@
1
1
  # @farcaster/hub-web
2
2
 
3
- A lightweight, fast Typescript interface for Farcaster Hubs. Designed to work with [Hubble](https://github.com/farcasterxyz/hubble/) and any other Hub that implements the [Farcaster protocol](https://github.com/farcasterxyz/protocol).
3
+ A fast and easy REST-like interface to work with Farcaster Hubs. Designed to work with [Hubble](https://github.com/farcasterxyz/hubble/) and any other Hub that implements the [Farcaster protocol](https://github.com/farcasterxyz/protocol).
4
4
 
5
5
  ## Features
6
-
7
- - Call any Hub endpoint from a browser environment using gRPC-Web.
8
- - Serializes and deserializes Farcaster protobufs into Javascript objects.
9
- - Has helpers to create and sign Farcaster messages.
10
- - Written entirely in TypeScript, with strict types for safety.
6
+ - Call any endpoint using a simple HTTP API, including from a browser environment
7
+ - Responses are plain JSON
8
+ - Written entirely in Typescript, with strict types for safety.
11
9
 
12
10
  ## Installation
13
-
14
- Install @farcaster/hub-web with the package manager of your choice
11
+ The examples in this package use `axios` to make HTTP requests, but you can use any library. It is also useful to install the `@farcaster/core` library which has several helper methods that are useful while working with Farcaster messages.
15
12
 
16
13
  ```bash
17
- npm install @farcaster/hub-web
18
- yarn add @farcaster/hub-web
19
- pnpm install @farcaster/hub-web
14
+ yarn add axios @farcaster/core
15
+ yarn add -D @types/axios
20
16
  ```
21
17
 
22
18
  ## Documentation
19
+ The HTTP API endpoints are [documented here](https://www.thehubble.xyz/docs/httpapi/httpapi.html).
23
20
 
24
- The @farcaster/hub-web APIs are largely the same as @farcaster/hub-nodejs. Read the [@farcaster/hub-nodejs documentation](https://github.com/farcasterxyz/hubble/tree/main/packages/hub-nodejs/docs) and browse code [examples](https://github.com/farcasterxyz/hubble/tree/main/packages/hub-nodejs/examples). We're also including sample @farcaster/hub-web code below as well as a list of differences with the other package.
25
-
26
- ### Getting start: fetching casts
27
-
21
+ ### Getting started: fetching casts
28
22
  ```typescript
29
- import { getHubRpcClient } from '@farcaster/hub-web';
30
-
31
- (async () => {
32
- const client = getHubRpcClient('https://testnet1.farcaster.xyz:2285');
33
-
34
- const castsResult = await client.getCastsByFid({ fid: 15 });
23
+ import axios from "axios";
35
24
 
36
- castsResult.map((casts) => casts.messages.map((cast) => console.log(cast.data?.castAddBody?.text)));
37
- })();
38
- ```
39
-
40
- ### Instantiating a client
41
-
42
- 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.
43
-
44
- #### Usage
45
-
46
- ```typescript
47
- import { getHubRpcClient } from '@farcaster/hub-web';
25
+ const fid = 2;
26
+ const server = "http://nemes.farcaster.xyz:2281";
48
27
 
49
- (async () => {
50
- const client = getHubRpcClient('https://testnet1.farcaster.xyz:2285');
28
+ try {
29
+ const response = await axios.get(`${server}/v1/castsByFid?fid=${fid}`);
51
30
 
52
- // If you're using gRPC-Web from a Nodejs environment, add a second false parameter
53
- // const nodeClient = getHubRpcClient('https://testnet1.farcaster.xyz:2285', false);
54
- })();
31
+ console.log(`API Returned HTTP status ${response.status}`);
32
+ console.log(`First Cast's text is ${response.messages[0].data.castAddBody.text}`);
33
+ } catch (e) {
34
+ // Handle errors
35
+ console.log(response);
36
+ }
55
37
  ```
56
38
 
57
- #### Returns
39
+ ### Running the examples
40
+ There are several examples in the `examples/` folder. To run the examples, please look at the individual README files in the examples directory. Most examples can be run by
58
41
 
59
- | Type | Description |
60
- | :------------- | :------------------------------ |
61
- | `HubRpcClient` | A new gRPC-Web Client instance. |
62
-
63
- #### Parameters
64
-
65
- | Name | Type | Description |
66
- | :---------- | :-------- | :------------------------------------------------------------------------- |
67
- | `url` | `string` | Address and RPC port string (e.g. `https://testnet1.farcaster.xyz:2285`) |
68
- | `isBrowser` | `boolean` | Optional parameter indicating whether to use the gRPC-Web Nodejs transport |
69
-
70
- ### Streaming hub events
71
-
72
- gRPC-Web hub event streams are instances of the [Observable class](https://rxjs.dev/guide/observable) in @farcaster/hub-web.
73
-
74
- #### Usage
75
-
76
- ```typescript
77
- import { getHubRpcClient } from '@farcaster/hub-web';
78
-
79
- async () => {
80
- const client = getHubRpcClient('https://testnet1.farcaster.xyz:2285');
81
-
82
- const result = client.subscribe({ eventTypes: [HubEventType.PRUNE_MESSAGE], fromId: 0 });
83
-
84
- result.map((observable) => {
85
- observable.subscribe({
86
- next(event: HubEvent) {
87
- console.log('received event', event);
88
- },
89
- error(err) {
90
- console.error(err);
91
- },
92
- });
93
- });
94
- };
42
+ ```bash
43
+ yarn install
44
+ yarn start
95
45
  ```
96
46
 
97
- #### Returns
98
-
99
- | Type | Description |
100
- | :-------------------------------- | :---------------------------------------------------------------------------- |
101
- | `HubResult<Observable<HubEvent>>` | An [Observable](https://rxjs.dev/guide/observable) stream wrapped in a Result |
102
-
103
- #### Parameters
104
-
105
- | Name | Type | Description |
106
- | :----------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
107
- | `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. |
108
- | `eventTypes` | `HubEventType[]` | Array of hub event types to return. If `eventTypes` is `[]`, all event types will be returned. |
47
+ ## grpc-Web
48
+ grpc-web was an older way of proxying to the grpc API from web environments. This has been deprecated, and will be removed in a future release. You can read the [grpc-web documentation and examples here](./README.grpcweb.md).
109
49
 
110
50
  ## Contributing
111
51