{"id":15427743,"url":"https://github.com/complexlity/uni-farcaster-sdk","last_synced_at":"2026-03-16T12:05:06.158Z","repository":{"id":252204510,"uuid":"839735424","full_name":"Complexlity/uni-farcaster-sdk","owner":"Complexlity","description":"An SDK that combines different farcaster infra with additional features and consistent api","archived":false,"fork":false,"pushed_at":"2024-09-12T06:42:54.000Z","size":286,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-20T22:53:39.957Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://uni-farcaster-sdk.vercel.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Complexlity.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-08T08:16:06.000Z","updated_at":"2024-09-12T06:42:57.000Z","dependencies_parsed_at":"2024-08-23T13:42:29.132Z","dependency_job_id":"55bd1515-2595-4f3a-8ea5-fa9f1c62c4a4","html_url":"https://github.com/Complexlity/uni-farcaster-sdk","commit_stats":{"total_commits":148,"total_committers":2,"mean_commits":74.0,"dds":"0.16216216216216217","last_synced_commit":"729c387612387cebb754faf272fd8112659e5826"},"previous_names":["complexlity/uni-farcaster-sdk"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Complexlity%2Funi-farcaster-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Complexlity%2Funi-farcaster-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Complexlity%2Funi-farcaster-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Complexlity%2Funi-farcaster-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Complexlity","download_url":"https://codeload.github.com/Complexlity/uni-farcaster-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235519884,"owners_count":19003201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-01T18:01:20.782Z","updated_at":"2025-10-06T10:32:00.175Z","avatar_url":"https://github.com/Complexlity.png","language":"TypeScript","readme":"For more comprehensive documentation, please visit the full docs - [https://uni-farcaster-sdk.vercel.app/](https://uni-farcaster-sdk.vercel.app/)\n\n# UniFarcaster SDK\n\nThis is an SDK that combines neynar, airstack to provide a single API without needing to know the underlying apis of both.\n\n## Installation\n\n```bash\nnpm install uni-farcaster-sdk\n```\n\n## Usage\n\n```js\nimport uniFarcasterSdk from 'uni-farcaster-sdk'\n//Initialization\n\n//with no configuration\nconst sdkInstance = new uniFarcasterSdk();\n\n//with custom Neynar api key\nconst sdkInstance = new uniFarcasterSdk({\n\tneynarApiKey: 'your-neynar-api-key',\n\tactiveService: 'neynar'//Optional. It's implied from the api key you provide\n})\n\n// with custom Airstack api key\nconst sdkInstance = new uniFarcasterSdk({\n\tairstackApiKey: 'your-airstack-api-key',\n\tactiveService: 'airstack' //Optional. It's implied from the api key you provide\n})\n\n// Invalid active service is ignored\nconst sdkInstance = new uniFarcasterSdk({\n\tairstackApiKey: 'your-airstack-api-key',\n\tactiveService: 'neynar' //Automatically set to airstack since only airstack api key is provided\n})\n\n//Both services. Useful for retries and custom queries\nconst sdkInstance = new uniFarcasterSdk({\n  neynarApiKey: 'your-neynar-api-key',\n  airstackApiKey: 'your-airstack-api-key',\n  //You should specify if you prefer neynar or airstack else it randomly choses one of them\n  activeService: 'airstack',\n})\n\n//Debug Mode\nconst sdkInstance = new uniFarcasterSdk({\n\t...otherConfigOptions\n  debug: true, //Logs every query on the console with the active service used for it,\n  logLevel: \"info\"| \"warn\"| \"error\"| \"success\"\n  //Optional and only used when debug is true.\n  // By default, all query is logged but setting the log level will only log queries with the specified level\n})\n\n//Retries\nconst sdkInstance = new uniFarcasterSdk({\n  ...otherConfigOptions\n  retries: 3, //Number of retries to do before returning the error\n  retryStrategy: \"normal\" | \"switch\" | \"switchTemp\" //Optional.\n)}\n// See https://uni-farcaster-sdk.vercel.app/configuration#retries for more information about retries and retryStrategy\n\n//Get Active Service\nsdkInstance.getActiveService() //airstack\n\n//Set Active Service\nsdkInstance.setActiveService('neynar')\nsdkInstance.getActiveService() //neynar\n\n//Get User By Fid\nconst userFid = [3]\nconst viewerFid = 4\nawait sdkInstance.getUsersByFid(userFid, viewerFid)\n//Viewer Fid is optional and defaults to 213144\n\n//Get User By Username\nconst userName = 'ds8'\nawait sdkInstance.getUserByUsername(userName)\n//Viewer Fid is optional and defaults to 213144\n\n//Get Cast By Url\nawait sdkInstance.getCastByUrl(castUrl, viewerFid)\n\n//Get Cast By Hash\nawait sdkInstance.getCastByHash(castHash, viewerFid)\n\n//Custom Queries\nawait sdkInstance.neynar(endpoint, params)\nawait sdkInstance.airstack(graphQlQuery, variables)\n```\n\n\u003e [!IMPORTANT]\n\u003e Getting by username doesn't return viewer context when using airstack instance so use getUserByFid when you always need viewerContext.\n\n## Return Types\n\n```ts\ntype User = {\n  fid: number;\n  ethAddresses: string[];\n  solAddresses: string[];\n  username: string;\n  displayName: string;\n  bio: string;\n  pfpUrl: string;\n  followerCount: number;\n  followingCount: number;\n  powerBadge?: boolean;\n  viewerContext: {\n    following: boolean;\n    followedBy: boolean;\n  };\n};\n\ntype Cast = {\n  author: UserWithOptionalViewerContext;\n  userReactions: {\n    likes: number;\n    recasts: number;\n  };\n  viewerContext: {\n    liked: boolean;\n    recasted: boolean;\n  };\n  text: string;\n  embeds: unknown[];\n  channel: string | null;\n};\n```\n\n## Error Handling\n\nBy default, invalid configurations will throw an error.\nAll queries don't throw errors but return an object\n\n```ts\n//Not Errors\n{data: PossibleReturnedValue , error: null}\nor\n//With Error\n{ data: null, error: {message: string}}\n```\n\nCheck if error is not null to knowif there was an error and handle it accordingly.\n\n## TODO\n\n- Add debug mode to log all queries ✅\n- Add query caching to avoid hitting the service for the same query ✅\n- Add airstack custom support. Where you can pass in custom airstack graphql queries if you need more than the sdk offers ✅\n- Add neynar custom support where you can pass custom neynar rest endpoints if you need more than the sdk offers ✅\n- Add an optional `retry` config to all queries and the option to switch service if there's an error\n  i.e If the current active service is airstack and the query fails, it will try to use neynar`\n  ✅\n- Fetch multiple users in a single query ✅\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcomplexlity%2Funi-farcaster-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcomplexlity%2Funi-farcaster-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcomplexlity%2Funi-farcaster-sdk/lists"}