REST Client for Warpcast's private APIs

.vscode/project.code-workspace

@@ -16,6 +16,10 @@
             "name": "packages/farcaster-js-neynar",
             "path": "../packages/farcaster-js-neynar"
         },
+        {
+            "name": "packages/farcaster-js-warpcast",
+            "path": "../packages/farcaster-js-warpcast"
+        }
     ],
     "settings": {
         "files.exclude": {

packages/farcaster-js-warpcast/.mocharc.yaml

@@ -0,0 +1,6 @@
+require:
+  - ts-node/register
+  - dotenv/config
+extensions: ['ts']
+spec: ['tests/**/*.ts']
+loader: ts-node/esm

packages/farcaster-js-warpcast/docs/.nojekyll

@@ -0,0 +1 @@
+TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.

packages/farcaster-js-warpcast/docs/README.md

@@ -0,0 +1,154 @@
+@standard-crypto/farcaster-js-warpcast / [Exports](modules.md)
+
+# Farcaster.js
+
+A collection of tools for interacting with the Farcaster social network.
+
+![NPM](https://img.shields.io/npm/l/@standard-crypto/farcaster-js?no-cache)
+![NPM](https://img.shields.io/npm/v/@standard-crypto/farcaster-js?no-cache)
+![GitHub Workflow Status](https://github.com/standard-crypto/farcaster-js/actions/workflows/farcaster-js.yml/badge.svg?branch=main)
+
+<!-- AUTO-GENERATED-CONTENT:START (TOC) -->
+- [Farcaster Hub REST API](#farcaster-hub-rest-api)
+- [Neynar REST APIs](#neynar-rest-apis)
+- [Signers](#signers)
+  - [Privy](#privy)
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+## Farcaster Hub REST API
+
+Farcaster hubs expose a public REST API which can be used for simple queries.
+
+***Setup:***
+
+```sh
+# Install all farcaster-js tools
+npm install axios @standard-crypto/farcaster-js
+
+# ...or install only the Hub REST API client
+npm install axios @standard-crypto/farcaster-js-hub-rest
+```
+
+***Example:***
+
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/hubRest.ts) -->
+<!-- The below code snippet is automatically added from ./examples/hubRest.ts -->
+```ts
+import { HubRestAPIClient, ExternalEd25519Signer } from '@standard-crypto/farcaster-js';
+
+import { NobleEd25519Signer } from '@farcaster/core';
+
+const client = new HubRestAPIClient();
+console.log(await client.getHubInfo());
+
+// Use a private key
+const signerPrivateKey = '0x...';
+const fid = 111;
+const writeClient = new HubRestAPIClient({ hubUrl: 'https://hub.farcaster.standardcrypto.vc:2281' });
+
+const publishCastResponse = await writeClient.submitCast({ text: 'This is a test cast submitted from farcaster-js' }, fid, signerPrivateKey);
+console.log(`new cast hash: ${publishCastResponse.hash}`);
+
+// Use an external signer
+const nobleSigner = new NobleEd25519Signer(new Uint8Array([]));
+const _signMessage = async(messageHash: Uint8Array): Promise<Uint8Array> => {
+  const res = await nobleSigner.signMessageHash(messageHash);
+  if (res.isErr()) {
+    throw res.error;
+  }
+  return res._unsafeUnwrap();
+};
+const _getPublicKey = async(): Promise<Uint8Array> => {
+  const res = await nobleSigner.getSignerKey();
+  if (res.isErr()) {
+    throw res.error;
+  }
+  return res._unsafeUnwrap();
+};
+const externalSigner = new ExternalEd25519Signer(_signMessage, _getPublicKey);
+
+const publishCastExternalSignerResponse = await writeClient.submitCast({ text: 'This is a test cast submitted from farcaster-js using an external signer' }, fid, externalSigner);
+console.log(`new cast hash with external signer: ${publishCastExternalSignerResponse.hash}`);
+```
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+See the [@standard-crypto/farcaster-js-hub-rest](./packages/farcaster-js-hub-rest/README.md)
+package for more info.
+
+## Neynar REST APIs
+
+***Setup:***
+
+```sh
+# Install all farcaster-js tools
+npm install axios @standard-crypto/farcaster-js
+
+# ...or install only the Neynar API client
+npm install axios @standard-crypto/farcaster-js-neynar
+```
+
+***Example:***
+
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/neynar.ts) -->
+<!-- The below code snippet is automatically added from ./examples/neynar.ts -->
+```ts
+import { NeynarAPIClient, NeynarV2 } from '@standard-crypto/farcaster-js';
+
+const signerUuid = 'approvedSignerUUID';
+const client = new NeynarAPIClient('apiKey');
+
+// Publish cast
+const cast = await client.v2.publishCast(signerUuid, 'This is a test cast.');
+
+// React to cast
+await client.v2.reactToCast(signerUuid, NeynarV2.ReactionType.Like, cast.hash);
+```
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+## Signers
+
+Signers are required to write data to Farcaster. You can learn more about signers from these resources ([Farcaster](https://docs.farcaster.xyz/developers/guides/accounts/create-account-key), [Neynar](https://docs.neynar.com/docs/write-to-farcaster-with-neynar-managed-signers), [Privy](https://docs.privy.io/guide/react/recipes/misc/farcaster-writes#_2-create-an-embedded-farcaster-signer)).
+
+This package includes a CLI for creating signers. You can run the code below to generate a signer:
+```
+farcaster-js create-signer
+```
+
+Read more about the CLI in [farcaster-js-cli](./packages/farcaster-js-cli/README.md).
+
+Additionally, signers may be created programmatically without use of the CLI. See the examples in [farcaster-js-neynar](./packages/farcaster-js-neynar/README.md#create-a-signer) or follow [this guide](https://docs.privy.io/guide/react/recipes/misc/farcaster-writes#_1-login-with-farcaster) from Privy for logging users in with Farcaster and authorizing a signer.
+
+### Privy
+
+[Privy](https://privy.io) enables users to easily log in to your app using their Farcaster account. Follow [this guide](https://docs.privy.io/guide/react/recipes/misc/farcaster-writes) to enable Farcaster login and begin writing messages. See the example below for usage once logging in with Farcaster is integrated.
+
+```
+import { HubRestAPIClient, ExternalEd25519Signer } from '@standard-crypto/farcaster-js';
+import { useExperimentalFarcasterSigner, usePrivy } from '@privy-io/react-auth';
+
+const client = new HubRestAPIClient();
+console.log(await client.getHubInfo());
+
+const { user } = usePrivy();
+const { getFarcasterSignerPublicKey, signFarcasterMessage } = useExperimentalFarcasterSigner();
+
+// Use a Privy embedded signer
+const privySigner = new ExternalEd25519Signer(signFarcasterMessage, getFarcasterSignerPublicKey);
+const fid = user.farcaster.fid!;
+
+const publishCastExternalSignerResponse = await client.submitCast({ text: 'This is a test cast submitted from farcaster-js using an external signer' }, fid, privySigner);
+console.log(`new cast hash with privy embedded signer signer: ${publishCastExternalSignerResponse.hash}`);
+```
+
+***Usage Versus Hub APIs:***
+
+The REST APIs exposed by a Farcaster hub are designed to provide protocol entities optimized for the transport and indexing layer. Neynar APIs are designed for building at the application-layer.
+
+Neynar v1 APIs are designed to replicate the deprecated Warpcast APIs to ensure that the ecosystem of products built on those APIs can continue thriving with minimal switching costs. The Neynar v1 APIs should act serve a drop-in replacement for applications using `farcaster-js` pre-version 6.0.
+
+Neynar v2 APIs bring in additional support for new Farcaster protocol primitives like channels and signer management with much more support for storage, sign in with farcaster and new features delivered regularly.
+
+See <https://neynar.com/> for API access and more details.
+
+See the [@standard-crypto/farcaster-js-neynar](./packages/farcaster-js-neynar/README.md)
+package for more on the Neynar API client.

packages/farcaster-js-warpcast/docs/modules.md

@@ -0,0 +1,3 @@
+[@standard-crypto/farcaster-js-warpcast](README.md) / Exports
+
+# @standard-crypto/farcaster-js-warpcast

packages/farcaster-js-warpcast/openapi-generator-config.json

@@ -0,0 +1,9 @@
+{
+    "withSeparateModelsAndApi": true,
+    "apiPackage": "apis",
+    "modelPackage": "models",
+    "stringEnums": true,
+    "useSingleRequestParameter": true,
+    "supportsES6": true,
+    "enablePostProcessFile": true
+}

packages/farcaster-js-warpcast/openapitools.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/@openapitools/openapi-generator-cli/config.schema.json",
+  "spaces": 2,
+  "generator-cli": {
+    "version": "6.6.0"
+  }
+}

packages/farcaster-js-warpcast/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@standard-crypto/farcaster-js-warpcast",
+  "version": "1.0.0-rc.2",
+  "description": "A tool for interacting with the private APIs of the Warpcast client.",
+  "type": "module",
+  "repository": {
+    "url": "https://github.com/standard-crypto/farcaster-js",
+    "type": "git"
+  },
+  "homepage": "https://github.com/standard-crypto/farcaster-js",
+  "bugs": "https://github.com/standard-crypto/farcaster-js/issues",
+  "author": "Gavi Galloway",
+  "license": "MIT",
+  "peerDependencies": {
+    "axios": "~1.6.0"
+  },
+  "devDependencies": {
+    "@openapitools/openapi-generator-cli": "^2.7.0",
+    "@types/chai": "^4.3.9",
+    "@types/chai-as-promised": "^7.1.5",
+    "@types/prompts": "^2.4.7",
+    "axios": "~1.6.0",
+    "chai": "^4.3.4",
+    "chai-as-promised": "^7.1.1",
+    "dotenv": "^16.3.1",
+    "markdown-magic": "^2.6.1",
+    "mocha": "^10.2.0",
+    "openapi-response-validator": "^12.1.3",
+    "openapi-types": "^12.1.3",
+    "openapi-typescript": "^6.7.0",
+    "ts-mocha": "^10.0.0",
+    "type-fest": "^4.8.3",
+    "typedoc": "^0.25.4",
+    "typedoc-plugin-markdown": "^3.15.2",
+    "yaml": "^2.3.2"
+  },
+  "files": [
+    "package.json",
+    "README.md",
+    "dist/**"
+  ],
+  "scripts": {
+    "build": "yarn run -T tshy",
+    "clean": "yarn clean:dist && yarn clean:generated",
+    "clean:dist": "rm -rf dist",
+    "clean:generated": "rm -rf src/openapi/generated",
+    "cz": "yarn run -T cz",
+    "fixup-imports": "yarn run -T fix-esm-import-path src && sed -i.bak 's|models\"|models/index.js\"|' src/openapi/generated/**/*.ts && sed -i.bak 's|models|models/index.js|' src/openapi/generated/apis/**/*.ts && rm src/openapi/generated/**/*.ts.bak",
+    "generate": "yarn run generate:openapi && yarn run generate:docs",
+    "generate:docs": "md-magic --path './README.md' && typedoc --plugin typedoc-plugin-markdown",
+    "generate:openapi": "yarn run generate:openapi-axios && yarn run generate:openapi-typescript && yarn run fixup-imports",
+    "generate:openapi-axios": "TS_POST_PROCESS_FILE=./src/openapi/post-process.sh openapi-generator-cli generate --global-property apis,models,supportingFiles=index.ts:api.ts:configuration.ts:base.ts:common.ts -i src/openapi/spec.yaml -g typescript-axios -o src/openapi/generated --config openapi-generator-config.json",
+    "generate:openapi-typescript": "openapi-typescript src/openapi/spec.yaml -o src/openapi/generated/schema.d.ts",
+    "test": "yarn test:integration",
+    "test:integration": "mocha",
+    "publish": "yarn npm publish"
+  },
+  "keywords": [
+    "farcaster",
+    "warpcast"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/index.d.ts",
+        "default": "./dist/commonjs/index.js"
+      }
+    }
+  },
+  "tshy": {
+    "exports": {
+      "./package.json": "./package.json",
+      ".": "./src/index.ts"
+    }
+  },
+  "main": "./dist/commonjs/index.js",
+  "types": "./dist/commonjs/index.d.ts"
+}

packages/farcaster-js-warpcast/src/index.ts

@@ -0,0 +1,2 @@
+export * from './openapi/index.js';
+export * from './warpcastApiClient.js';

packages/farcaster-js-warpcast/src/logger.ts

@@ -0,0 +1,24 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-empty-function */
+
+export interface Logger {
+  trace: (message?: any, ...optionalParams: any[]) => void
+  debug: (message?: any, ...optionalParams: any[]) => void
+  info: (message?: any, ...optionalParams: any[]) => void
+  warn: (message?: any, ...optionalParams: any[]) => void
+  error: (message?: any, ...optionalParams: any[]) => void
+  [x: string]: any
+}
+
+export const silentLogger: Logger = {
+  trace: (_message?: any, ..._optionalParams: any[]) => {},
+  debug: (_message?: any, ..._optionalParams: any[]) => {},
+  info: (_message?: any, ..._optionalParams: any[]) => {},
+  warn: (_message?: any, ..._optionalParams: any[]) => {},
+  error: (_message?: any, ..._optionalParams: any[]) => {},
+};
+
+/* eslint-enable @typescript-eslint/no-unused-vars */
+/* eslint-enable @typescript-eslint/no-explicit-any */
+/* eslint-enable @typescript-eslint/no-empty-function */

packages/farcaster-js-warpcast/src/openapi/generated/.openapi-generator/FILES

@@ -0,0 +1,30 @@
+api.ts
+apis/direct-casts-api.ts
+apis/users-api.ts
+base.ts
+common.ts
+configuration.ts
+index.ts
+models/conversation-details.ts
+models/conversation-message.ts
+models/conversation-viewer-context.ts
+models/conversation.ts
+models/index.ts
+models/onboarding-state.ts
+models/pagination.ts
+models/user-pfp.ts
+models/user-profile-bio.ts
+models/user-profile-location.ts
+models/user-profile.ts
+models/user-viewer-context.ts
+models/user.ts
+models/v2-direct-cast-conversation-details-get200-response.ts
+models/v2-direct-cast-conversation-get200-response-result.ts
+models/v2-direct-cast-conversation-get200-response.ts
+models/v2-direct-cast-conversation-list-get200-response-result.ts
+models/v2-direct-cast-conversation-list-get200-response.ts
+models/v2-onboarding-state-get200-response-result.ts
+models/v2-onboarding-state-get200-response.ts
+models/v2-user-get200-response-result-extras.ts
+models/v2-user-get200-response-result.ts
+models/v2-user-get200-response.ts

packages/farcaster-js-warpcast/src/openapi/generated/.openapi-generator/VERSION

@@ -0,0 +1 @@
+6.6.0

packages/farcaster-js-warpcast/src/openapi/generated/api.ts

@@ -0,0 +1,19 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Warpcast API
+ * Private API used by the Warpcast client
+ *
+ * The version of the OpenAPI document: 1.0
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+
+
+export * from './apis/direct-casts-api.js';
+export * from './apis/users-api.js';
+