diff --git a/README.md b/README.md index 421ce7ce..c16c2eb2 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,14 @@ ## Usage -Please refer our [Getting Started Guide](https://docs.neynar.com/reference/getting-started-with-sdk) +Please refer to our [Getting Started Guide](https://docs.neynar.com/reference/getting-started-with-sdk) Checkout [examples](https://github.com/neynarxyz/farcaster-examples) using this SDK +## Contribution Guidelines + +see [CONTRIBUTING.md](./docs/CONTRIBUTING.md). + ## License -This project is licensed under the MIT License - see the [LICENSE](https://github.com/neynarxyz/nodejs-sdk/blob/main/LICENSE) file for details. +This project is licensed under the MIT License. This license permits free use, modification, and distribution of the software, with the requirement that the original copyright and license notice are included in any substantial portion of the work. - see the [LICENSE](https://github.com/neynarxyz/nodejs-sdk/blob/main/LICENSE) file for details. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 00000000..1d7fbf91 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,101 @@ +# Contributing to Neynar Node.js SDK + +We welcome contributions to the Neynar Node.js SDK. This document provides guidelines and instructions for contributing. + +## Prerequisites + +Before you begin, ensure you have the following installed: + +- [Node.js](https://nodejs.org/en/download/) +- [Yarn](https://classic.yarnpkg.com/lang/en/docs/install) + +## Setting Up for Development + +1. Fork the SDK repository from [@neynar/nodejs-sdk](https://github.com/neynarxyz/nodejs-sdk) to your GitHub account. +2. Clone your forked repository to your local machine. +3. Inside your local clone, initialize and update submodules, and install dependencies. + +```bash +git submodule update --init --recursive +yarn install +``` + +## Contributing Guidelines + +### Updating Auto-Generated Code + +Auto-generated code is located in the following directories: + +- `src/neynar-api/v1/openapi` +- `src/neynar-api/v2/openapi-farcaster` +- `src/neynar-api/v2/openapi-recommendation` + +These are generated using [openapi-generator-cli](https://github.com/OpenAPITools/openapi-generator-cli). To make changes, update the OpenAPI Specification (OAS) in the [OAS Repository](https://github.com/neynarxyz/oas). After updating the OAS, synchronize the OAS in your local clone of the SDK repository. + +```bash +git submodule update --remote src/oas +``` + +### Writing Wrapper Code + +#### New Tag in OAS + +When a new tag is added in the OAS, follow these steps: + +1. A new API is generated under `src/neynar-api/v{version}/openapi/apis`. +2. In the internal wrappers (`src/neynar-api/v{version}/client`), add the new tag to the `public readonly apis` property. +3. Instantiate the new API in the constructor. +4. Write wrapper code for the new methods. +5. Add corresponding wrapper code in the external wrapper (`src/neynar-api/neynar-api-client`). + +#### Method Naming Guidelines + +- Be descriptive with method names. +- Prepend `lookup` for GET APIs returning a single entity (e.g., `lookupUserByFid`). +- Use `fetch` for GET APIs returning multiple entities (e.g., `fetchRecentUsers`). +- Use `publish` for POST APIs (e.g., `publishCast`). +- Use `delete` for DELETE APIs (e.g., `deleteReactionFromCast`). +- Use `update` for PUT/PATCH APIs (e.g., `updateUser`). +- For bulk operations, use `fetchBulkX`, `updateBulkX`, etc. + +#### Parameters Guidelines + +- In methods on the wrapper client, all required parameters must be added first, followed by optional parameters, which should be encapsulated within an options object. For example, use `fetchUser(reqParam1, reqParam2, {optionalParam1, optionalParam2})`. + +#### Adding a JS Docstring + +When writing JS docstrings, adhere to the following guidelines: + +1. **Instance Name**: Use **`client`** as the instance name in examples. +2. **Parameter Inclusion**: Include most parameters in examples, where applicable. +3. **Parameter Descriptions**: + - Consistently describe **`viewerFid`** as "The FID of the user viewing this information, used for providing contextual data specific to the viewer." + - For the **`limit`** parameter, include its default and maximum values. + - For the **`cursor`** parameter, consistently describe it as "Pagination cursor for the next set of results, Omit this parameter for the initial request." In the example, add the cursor as **`// cursor: "nextPageCursor", // Pagination cursor for the next set of results, Omit this parameter for the initial request.`** +4. **[options] Description**: Describe **`[options]`** as "Optional parameters to tailor the request." +5. **Usage Examples**: + - Provide only one example that demonstrates a practical application of the method with multiple parameters. + - Include explanatory comments within the example code to clarify the purpose and usage of each line or significant code section. +6. **Neynar Documentation Reference**: Include a link to the Neynar documentation for additional information. + +### Coding Standards + +- Ensure code readability and maintainability. +- Comment your code where necessary, especially for complex logic. + + +### Submitting a Pull Request + +- After completing your changes, commit them to your forked repository. +- Push your changes to your GitHub fork. +- Create a pull request from your fork to the main SDK repository. +- Make sure your code adheres to the project's coding standards. +- Provide a clear and detailed description of your changes in the pull request. +- Link any relevant issues in your pull request description. + +### Community Guidelines + +- Follow the project's code of conduct. +- Report any issues or concerns to the maintainers. + +Thank you for contributing to the Neynar Node.js SDK! diff --git a/package.json b/package.json index cebe2e5f..606f5f44 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@neynar/nodejs-sdk", - "version": "1.0.0", + "version": "1.1.0", "description": "SDK to interact with Neynar APIs (https://docs.neynar.com/)", "main": "./build/index.js", "types": "./build/index.d.ts", @@ -27,4 +27,4 @@ "axios": "^1.6.2", "viem": "^1.19.9" } -} +} \ No newline at end of file diff --git a/src/neynar-api/index.ts b/src/neynar-api/index.ts index c4f9d1c4..43aae58e 100644 --- a/src/neynar-api/index.ts +++ b/src/neynar-api/index.ts @@ -1,3 +1,3 @@ export * from "./neynar-api-client"; export * from "./utils"; -export { FeedType, FilterType, ReactionsType, CastParamType } from "./v2"; +export { FeedType, FilterType, ReactionsType, CastParamType, ReactionType } from "./v2"; diff --git a/src/neynar-api/neynar-api-client.ts b/src/neynar-api/neynar-api-client.ts index 536cd963..f18f7411 100644 --- a/src/neynar-api/neynar-api-client.ts +++ b/src/neynar-api/neynar-api-client.ts @@ -1004,7 +1004,7 @@ export class NeynarAPIClient { * containing information about the specified cast. * * @example - * import { CastParamType } from "@neynar/nodejs-sdk/build/neynar-api/v2"; + * import { CastParamType } from "@neynar/nodejs-sdk"; * * // Example: Retrieve information for a cast using its hash * client.lookUpCastByHashOrWarpcastUrl('0xfe90f9de682273e05b201629ad2338bdcd89b6be', CastParamType.Hash).then(response => { @@ -1172,7 +1172,7 @@ export class NeynarAPIClient { * * @example * - * import { ReactionType } from "@neynar/nodejs-sdk/build/neynar-api/v2"; + * import { ReactionType } from "@neynar/nodejs-sdk"; * * // Example: Post a 'like' reaction to a cast * client.publishReactionToCast('19d0c5fd-9b33-4a48-a0e2-bc7b0555baec', ReactionType.Like, '0x1ea99cbed57e4020314ba3fadd7c692d2de34d5f').then(response => { @@ -1206,7 +1206,7 @@ export class NeynarAPIClient { * * @example * - * import { ReactionType } from "@neynar/nodejs-sdk/build/neynar-api/v2"; + * import { ReactionType } from "@neynar/nodejs-sdk"; * * // Example: Remove a 'like' reaction from a cast * client.deleteReactionFromCast('19d0c5fd-9b33-4a48-a0e2-bc7b0555baec', ReactionType.Like, '0x1ea99cbed57e4020314ba3fadd7c692d2de34d5f').then(response => { @@ -1244,7 +1244,7 @@ export class NeynarAPIClient { * * @example * - * import { ReactionsType } from "@neynar/nodejs-sdk/build/neynar-api/v2"; + * import { ReactionsType } from "@neynar/nodejs-sdk"; * * // Example: Fetch a user's reactions * client.fetchUserReactions(3, ReactionsType.All, { diff --git a/src/neynar-api/v1/v1-client.ts b/src/neynar-api/v1/client.ts similarity index 100% rename from src/neynar-api/v1/v1-client.ts rename to src/neynar-api/v1/client.ts diff --git a/src/neynar-api/v1/index.ts b/src/neynar-api/v1/index.ts index 7726b59b..08aeef1f 100644 --- a/src/neynar-api/v1/index.ts +++ b/src/neynar-api/v1/index.ts @@ -1,2 +1,2 @@ export * from './openapi' -export * from './v1-client' \ No newline at end of file +export * from './client' \ No newline at end of file diff --git a/src/neynar-api/v2/v2-client.ts b/src/neynar-api/v2/client.ts similarity index 100% rename from src/neynar-api/v2/v2-client.ts rename to src/neynar-api/v2/client.ts diff --git a/src/neynar-api/v2/index.ts b/src/neynar-api/v2/index.ts index a2a9880d..4046e277 100644 --- a/src/neynar-api/v2/index.ts +++ b/src/neynar-api/v2/index.ts @@ -1,2 +1,2 @@ export * from "./openapi-farcaster"; -export * from "./v2-client"; +export * from "./client"; diff --git a/test-sdk.ts b/test-sdk.ts new file mode 100644 index 00000000..e69de29b