Skip to content

Commit 887507f

Browse files
horsefactshorsefacts
authored
feat: ConnectKit docs (#123)
1 parent 0fd3f03 commit 887507f

20 files changed

+1166
-54
lines changed

‎.prettierrc.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
semi: true
22
trailingComma: 'es5'
33
singleQuote: true
4-
printWidth: 120
4+
printWidth: 80
55
tabWidth: 2
6-
useTabs: false
6+
useTabs: false

‎docs/.vitepress/config.mts‎

Lines changed: 310 additions & 52 deletions
Large diffs are not rendered by default.

‎docs/connect-kit/client/app/client.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# App Client
2+
3+
If you're building a [connected app](https://docs.farcaster.xyz/learn/what-is-farcaster/apps#connected-apps) and want users to sign in with Farcaster, use an `AppClient`.
4+
5+
You can use an `AppClient` to create a Farcaster Connect relay channel, generate a deep link to request a signature from the user's Farcaster wallet app, and verify the returned signature.
6+
7+
```ts
8+
import { createAppClient, viem } from '@farcaster/connect';
9+
10+
const appClient = createAppClient({
11+
relay: 'https://relay.farcaster.xyz',
12+
ethereum: viem(),
13+
});
14+
```
15+
16+
## Parameters
17+
18+
| Parameter | Type | Description | Required |
19+
| ---------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
20+
| `ethereum` | `Ethereum` | <p>An Ethereum connector, used to query the Farcaster contracts and verify smart contract wallet signatures. `@farcaster/connect` currently provides only the `viem` connector type.</p> <p>To use a custom RPC, pass an RPC URL to the viem connector.</p> | Yes |
21+
| `relay` | `string` | Relay server URL. Defaults to the public relay at `https://relay.farcaster.xyz` | No |
22+
| `version` | `string` | Farcaster Connect version. Defaults to `"v1"` | No |

‎docs/connect-kit/client/app/connect.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# `connect`
2+
3+
Create a Farcaster Connect relay channel.
4+
5+
Returns a secret token identifying the channel, and a URI to display to the end user as a link or QR code.
6+
7+
```ts
8+
const channel = await appClient.connect({
9+
siweUri: 'https://example.com/login',
10+
domain: 'example.com',
11+
});
12+
```
13+
14+
## Parameters
15+
16+
| Parameter | Type | Description | Required | Example |
17+
| ---------------- | -------- | ----------------------------------------------------------------------------- | -------- | -------------------------------------- |
18+
| `siweUri` | `string` | Login URL for your application. | Yes | `https://example.com/login` |
19+
| `domain` | `string` | Domain of your application. | Yes | `example.com` |
20+
| `nonce` | `string` | A custom nonce. Must be at least 8 alphanumeric characters. | No | `ESsxs6MaFio7OvqWb` |
21+
| `notBefore` | `string` | Start time at which the signature becomes valid. ISO 8601 datetime. | No | `2023-12-20T23:21:24.917Z` |
22+
| `expirationTime` | `string` | Expiration time at which the signature is no longer valid. ISO 8601 datetime. | No | `2023-12-20T23:21:24.917Z` |
23+
| `requestId` | `string` | A system specific ID your app can use to refer to the sign in request. | No | `8d0494d9-e0cf-402b-ab0a-394ac7fe07a0` |
24+
25+
## Returns
26+
27+
```ts
28+
{
29+
response: Response;
30+
data: {
31+
channelToken: string;
32+
connectURI: string;
33+
nonce: string;
34+
}
35+
isError: boolean;
36+
error: Error;
37+
}
38+
```
39+
40+
| Parameter | Description |
41+
| ------------------- | ---------------------------------------------------------------------------------- |
42+
| `response` | HTTP response from the Connect relay server. |
43+
| `data.channelToken` | Connect relay channel token UUID. |
44+
| `data.connectURI` | Sign in With Farcaster URL to present to the user. Links to Warpcast client in v1. |
45+
| `data.nonce` | Random nonce included in the Sign in With Farcaster message. |
46+
| `isError` | True when an error has occurred. |
47+
| `error` | `Error` instance. |

‎docs/connect-kit/client/app/status.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# `status`
2+
3+
Get current status of a Farcaster Connect request.
4+
5+
Returns the current state of the request, either `'pending'` if the user's Farcaster wallet app has not yet sent back a signature, or `'completed'` once the wallet app has returned a response.
6+
7+
In `'completed'` state, the response includes the generated Sign in With Farcaster message, a signature from the user's custody address, the user's verified fid, and user profile information.
8+
9+
```ts
10+
const status = await appClient.status({
11+
channelToken: '210f1718-427e-46a4-99e3-2207f21f83ec',
12+
});
13+
```
14+
15+
## Parameters
16+
17+
| Parameter | Type | Description | Required | Example |
18+
| -------------- | -------- | -------------------------------- | -------- | -------------------------------------- |
19+
| `channelToken` | `string` | Farcaster Connect channel token. | Yes | `8d0494d9-e0cf-402b-ab0a-394ac7fe07a0` |
20+
21+
## Returns
22+
23+
```ts
24+
{
25+
response: Response
26+
data: {
27+
state: 'pending' | 'completed'
28+
nonce: string
29+
message?: string
30+
signature?: `0x${string}`
31+
fid?: number
32+
username?: string
33+
bio?: string
34+
displayName?: string
35+
pfpUrl?: string
36+
}
37+
isError: boolean
38+
error: Error
39+
}
40+
```
41+
42+
| Parameter | Description |
43+
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
44+
| `response` | HTTP response from the Connect relay server. |
45+
| `data.state` | Status of the sign in request, either `"pending"` or `"complete"` |
46+
| `data.nonce` | Random nonce used in the SIWE message. If you don't provide a custom nonce as an argument to the hook, you should read this value. |
47+
| `data.message` | The generated SIWE message. |
48+
| `data.signature` | Hex signature produced by the user's Warpcast wallet. |
49+
| `data.fid` | User's Farcaster ID. |
50+
| `data.username` | User's Farcaster username. |
51+
| `data.bio` | User's Farcaster bio. |
52+
| `data.displayName` | User's Farcaster display name. |
53+
| `data.pfpUrl` | User's Farcaster profile picture URL. |
54+
| `isError` | True when an error has occurred. |
55+
| `error` | `Error` instance. |

‎docs/connect-kit/client/app/verify-sign-in-message.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# `verifySignInMessage`
2+
3+
Verify a Sign In With Farcaster message. Your app should call this function and check that it succeeds after reading the message and signature provided by the user's Farcaster wallet over the Connect channel.
4+
5+
Returns the parsed Sign in With Farcaster message, the user's fid, and whether the verification succeeded.
6+
7+
```ts
8+
const { data, success, fid } = await appClient.verifySignInMessage({
9+
nonce: 'abcd1234',
10+
domain: 'example.com',
11+
message: 'example.com wants you to sign in with your Ethereum account…',
12+
signature: '0x9335c3055d47780411a3fdabad293c68c84ea350a11794cd11fd51b…',
13+
});
14+
```
15+
16+
## Parameters
17+
18+
| Parameter | Type | Description | Required |
19+
| ----------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
20+
| `domain` | `string` | Domain of your application. Must match the domain in the provided SIWF message. | Yes |
21+
| `nonce` | `string` | A custom nonce. Must match the nonce in the provided SIWF message. | Yes |
22+
| `message` | `string` or `SiweMessage` | The Sign in With Farcaster message to verify. This may be either a string or a parsed `SiweMessage`. Your app should read this value from the Connect channel once the request is completed. | Yes |
23+
| `signature` | `Hex` | Signature provided by the user's Farcaster wallet. Your app should read this from the Connect channel once the request is completed. | Yes |
24+
25+
## Returns
26+
27+
```ts
28+
{
29+
data: SiweMessage,
30+
success: boolean,
31+
fid: number
32+
isError: boolean
33+
error: Error
34+
}
35+
```
36+
37+
| Parameter | Description |
38+
| --------- | ----------------------------------------------- |
39+
| `data` | Parsed SIWF message, as a `SiweMessage` object. |
40+
| `success` | True if provided signature is valid. |
41+
| `fid` | FID of the user. |
42+
| `isError` | True when an error has occurred. |
43+
| `error` | `Error` instance. |

‎docs/connect-kit/client/app/watch-status.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# `watchStatus`
2+
3+
Poll for the current status of a Farcaster Connect request.
4+
5+
When the status changes to `'complete'` this action resolves with the final channel value, including the Sign In With Farcaster message, signature, and user profile information.
6+
7+
```ts
8+
const status = await appClient.watchStatus({
9+
channelToken: '210f1718-427e-46a4-99e3-2207f21f83ec',
10+
timeout: 60_000,
11+
interval: 1_000,
12+
onResponse: ({ response, data }) => {
13+
console.log('Response code:', response.status);
14+
console.log('Status data:', data);
15+
},
16+
});
17+
```
18+
19+
## Parameters
20+
21+
| Parameter | Type | Description | Required | Example |
22+
| -------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------- |
23+
| `channelToken` | `string` | Farcaster Connect channel token. | Yes | `8d0494d9-e0cf-402b-ab0a-394ac7fe07a0` |
24+
| `timeout` | `number` | Polling timeout, in milliseconds. If the connect request is not completed before the timeout, `watchStatus` returns an error. | No | `300_000` |
25+
| `interval` | `number` | Polling interval, in milliseconds. The client will check for updates at this frequency. | No | `1_000` |
26+
| `onResponse` | `function` | Callback function invoked each time the client polls for an update and receives a response from the relay server. Receives the return value of the latest `status` request. | No | `({ data }) => console.log(data.fid)` |
27+
28+
## Returns
29+
30+
```ts
31+
{
32+
response: Response
33+
data: {
34+
state: 'pending' | 'completed'
35+
nonce: string
36+
message?: string
37+
signature?: `0x${string}`
38+
fid?: number
39+
username?: string
40+
bio?: string
41+
displayName?: string
42+
pfpUrl?: string
43+
}
44+
isError: boolean
45+
error: Error
46+
}
47+
```
48+
49+
| Parameter | Description |
50+
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
51+
| `response` | HTTP response from the Connect relay server. |
52+
| `data.state` | Status of the sign in request, either `"pending"` or `"complete"` |
53+
| `data.nonce` | Random nonce used in the SIWE message. If you don't provide a custom nonce as an argument to the hook, you should read this value. |
54+
| `data.message` | The generated SIWE message. |
55+
| `data.signature` | Hex signature produced by the user's Warpcast wallet. |
56+
| `data.fid` | User's Farcaster ID. |
57+
| `data.username` | User's Farcaster username. |
58+
| `data.bio` | User's Farcaster bio. |
59+
| `data.displayName` | User's Farcaster display name. |
60+
| `data.pfpUrl` | User's Farcaster profile picture URL. |
61+
| `isError` | True when an error has occurred. |
62+
| `error` | `Error` instance. |

‎docs/connect-kit/client/auth/authenticate.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# `authenticate`
2+
3+
Submit a Sign In With Farcaster message, user signature, and profile data to the Connect relay server.
4+
5+
```ts
6+
const params = await authClient.authenticate({
7+
message: 'example.com wants you to sign in with your Ethereum account…',
8+
signature: '0x9335c3055d47780411a3fdabad293c68c84ea350a11794cdc811fd5…',
9+
fid: 1,
10+
username: 'alice',
11+
bio: "I'm a little teapot who didn't fill out my bio",
12+
displayName: 'Alice Teapot',
13+
pfpUrl: 'https://images.example.com/profile.png',
14+
});
15+
```
16+
17+
## Parameters
18+
19+
| Parameter | Type | Description | Required |
20+
| -------------- | -------- | ----------------------------------------------------------------------------------------------- | -------- |
21+
| `authKey` | `string` | Farcaster Connect API key. Farcaster Connect v1 restricts calls to `/authenticate` to Warpcast. | Yes |
22+
| `channelToken` | `string` | Farcaster Connect channel token. | Yes |
23+
| `message` | `string` | The Sign in With Farcaster message produced by your wallet app and signed by the user. | Yes |
24+
| `message` | `string` | The Sign in With Farcaster message produced by your wallet app and signed by the user. | Yes |
25+
| `signature` | `Hex` | SIWE signature created by the wallet user's account. | Yes |
26+
| `fid` | `number` | Wallet user's fid. | Yes |
27+
| `username` | `string` | Wallet user's Farcaster username. | Yes |
28+
| `bio` | `string` | Wallet user's bio. | Yes |
29+
| `displayName` | `string` | Wallet user's display name. | Yes |
30+
| `pfpUrl` | `string` | Wallet user's profile photo URL. | Yes |
31+
32+
## Returns
33+
34+
```ts
35+
{
36+
response: Response
37+
data: {
38+
state: 'completed'
39+
nonce: string
40+
message?: string
41+
signature?: `Hex`
42+
fid?: number
43+
username?: string
44+
bio?: string
45+
displayName?: string
46+
pfpUrl?: string
47+
}
48+
isError: boolean
49+
error: Error
50+
}
51+
```
52+
53+
| Parameter | Description |
54+
| ------------------ | ----------------------------------------------------------------- |
55+
| `response` | HTTP response from the Connect relay server. |
56+
| `data.state` | Status of the sign in request, either `"pending"` or `"complete"` |
57+
| `data.nonce` | Random nonce used in the SIWE message. |
58+
| `data.message` | The generated SIWE message. |
59+
| `data.signature` | Hex signature produced by the user's Warpcast wallet. |
60+
| `data.fid` | User's Farcaster ID. |
61+
| `data.username` | User's Farcaster username. |
62+
| `data.bio` | User's Farcaster bio. |
63+
| `data.displayName` | User's Farcaster display name. |
64+
| `data.pfpUrl` | User's Farcaster profile picture URL. |
65+
| `isError` | True when an error has occurred. |
66+
| `error` | `Error` instance. |

0 commit comments

Comments
 (0)