[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]
## About Notifi
Notifi is a cross-blockchain notification service that allows dapps to send notifications to their users.
Application owners (Developers) can push notifications to their users in various ways by leveraging Notifi protocol.
- **Community messages**: broadcast messages to the on-chain community by using [Community Manager of Notifi Admin Portal](https://admin.notifi.network/community).
- **On-chain events**: By using Notifi [on-chain parser](https://github.com/notifi-network/notifi-parser-sdk), Dapps can send notifications to their users based on on-chain events.
Register a new account on [Notifi Admin Portal](https://admin.notifi.network) and start sending notifications to your users.
> For more detailed info to get started with Notifi, please check the [official documentation](https://docs.notifi.network/docs/getting-started).
## About Notifi SDK TS
This monorepo contains the following packages which are used to interact with Notifi services.
- [@notifi-network/notifi-frontend-client](#notifi-frontend-client)
- [@notifi-network/notifi-react](#notifi-react)
- [@notifi-network/notifi-node](#notifi-node)
- [@notifi-network/notifi-graphql](#notifi-graphql)
- [@notifi-network/notifi-web-push-service-worker](#notifi-web-push-service-worker)
#### Notifi Frontend Client
[@notifi-network/notifi-frontend-client](https://github.com/notifi-network/notifi-sdk-ts/tree/main/packages/notifi-frontend-client) package is designed for frontend (application) use. It enables interaction with Notifi services by instantiating a `NotifiFrontendClient` object, which provides essential client methods.
> - Framework-agnostic: This package can be integrated into any frontend application, regardless of the framework.
> - Implementation reference: See [@notifi-network/notifi-react](#notifi-react) for an example implementation.
> - Type documentation: [Notifi Frontend Client](https://docs.notifi.network/notifi-sdk-ts/notifi-frontend-client/modules.html)
#### Notifi React
[@notifi-network/notifi-react](https://github.com/notifi-network/notifi-sdk-ts/tree/main/packages/notifi-react) package is a React library that provides:
- Prebuilt UI Component: An out-of-the-box UI card modal component, `NotifiCardModal` enabling developers to seamlessly integrate Notifi services without managing underlying implementation details.
- Custom UI Flexibility: A set of context methods that allow developers to build custom UI components to interact with Notifi services.
> - Framework-specific: Designed exclusively for [React based applications](https://www.robinwieruch.de/react-starter/) .
> - Example implementation: Refer to the [@notifi-network/notifi-react-example-v2](https://github.com/notifi-network/notifi-sdk-ts/tree/main/packages/notifi-react-example-v2) package for a practical example.
> - Built on: This package implements the [@notifi-network/notifi-frontend-client](#notifi-frontend-client) package.
> - Type documentation: [Notifi React](https://docs.notifi.network/notifi-sdk-ts/notifi-react/modules.html)
#### Notifi Node
[@notifi-network/notifi-node](https://github.com/notifi-network/notifi-sdk-ts/tree/main/packages/notifi-node) package is designed for Node.js server-side use. It allows DApp owners to implement off-chain log parsing logic and send notifications to their users.
> Example implementation: Refer to the [@notifi-network/notifi-node-sample](https://github.com/notifi-network/notifi-sdk-ts/tree/main/packages/notifi-node-sample) package for a practical example.
> Type documentation: [Notifi Node](https://docs.notifi.network/notifi-sdk-ts/notifi-node/modules.html)
#### Notifi GraphQL
[@notifi-network/notifi-graphql](https://github.com/notifi-network/notifi-sdk-ts/tree/main/packages/notifi-graphql), powered by [graphql-codegen](https://the-guild.dev/graphql/codegen/docs/getting-started), provides a GraphQL client with the necessary types and queries to interact with Notifi services. It is especially useful for developers looking to build custom services (SDKs) on top of Notifi's infrastructure.
> Implementation reference: See [@notifi-network/notifi-frontend-client](#notifi-frontend-client) for an example implementation.
> Type documentation: [Notifi GraphQL](https://docs.notifi.network/notifi-sdk-ts/notifi-graphql/modules.html)
#### Notifi Web Push Service Worker (Coming soon)
[@notifi-network/notifi-web-push-service-worker](https://github.com/notifi-network/notifi-sdk-ts/tree/main/packages/notifi-web-push-service-worker) package introduces a [Service Worker](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) that handles the browser push notification subscription.
This is useful for the cross platform applications which adopt the Progressive Web App (PWA) architecture.
> Respective example packages: [@notifi-network/notifi-pwa-example](https://github.com/notifi-network/notifi-sdk-ts/tree/main/packages/notifi-pwa-example)
## Build with Notifi (for repository maintainers or contributors)
### Prerequisites
- Node.js (v18.x or higher with corresponding npm version)
- [NVM (Node Version Manager)](https://www.freecodecamp.org/news/node-version-manager-nvm-install-guide/) is recommended to manage the node versions. Run `nvm use` to adopt supported node version (defined in `.nvmrc`).
- prettier configured in your IDE: in your **vscode** `settings.json`, add the following configuration. If you are using other IDEs, please make sure the `.prettierrc` file is adopted by the IDE.
```json
// ... other settings
"prettier.configPath": "./.prettierrc"
// ... other settings
```
### Contribute to the repository (for contributors)
Before contributing, please make sure the following steps are followed.
> [!TIP]
> This repository uses [Husky](https://typicode.github.io/husky/) to manage Git hooks for maintaining code quality and consistency.
>
> - Pre-commit: Checks code formatting
> - Pre-push: Verifies syntax correctness and ensures a successful build.
>
> ⚠️ Commits or pushes that fail these checks will be rejected until the issues are resolved.
#### Code formatting & linting
Before pushing changes, make sure your code is properly formatted and passes lint checks by running:
```bash
# on the root directory
npm run format && npm run lint
```
> [!WARNING]
> If your IDE does not automatically use `"prettier.configPath": "./.prettierrc"` , please manually run `npm run format` and commit the formatted changes before pushing.
#### Build packages
After making changes, build all packages to ensure updates are reflected in the compiled files:
```bash
# on the root directory
npm run build
```
#### Unit tests (Jest) & Component tests (Cypress)
You can run tests for **all packages** in the monorepo using:
```bash
npm run test
```
However, if you’ve only made changes to specific packages, it’s more efficient to run tests for just those. Here are the details:
1. Component Tests for `@notifi-network/notifi-react` (Cypress)
If you’ve modified the `@notifi-network/notifi-react` package, please run Cypress tests to validate UI component behavior.
These tests should be executed locally via the `@notifi-network/notifi-react-example-v2` package:
```bash
# Open the Cypress test runner for the example project
npx lerna --scope=@notifi-network/notifi-react-example-v2 run cypress:open
# or run headless tests
npx lerna --scope=@notifi-network/notifi-react-example-v2 run test
```
You can find detailed test scenarios in the [Cypress test script](https://github.com/notifi-network/notifi-sdk-ts/blob/main/packages/notifi-react-example-v2/cypress/component/NotifiCardModal.cy.tsx).
> ⚠️ **IMPORTANT:**
> If you modify any test scripts, please run them repeatedly (at least 5–10 times) to ensure stability:
>
> ```bash
> for i in {1..10}; do npm npx lerna --scope=@notifi-network/notifi-react-example-v2 run test; done
> ```
2. Unit Tests for Other Packages (Jest)
For non-UI packages, we use Jest for testing.
Before running these tests, make sure to configure your environment:
- Navigate to `packages/notifi-node/`
- Copy `.env.example` to `.env`
- Fill in the required environment variables
Then run:
```bash
npm run test:node && npm run test:frontend-client
```
### Tips & Code Style Conventions
Use `lerna` commands to run scripts for a specific package:
```bash
npx lerna --scope=@notifi-network/ run
```
**Common examples:**
- Start the development server for `notifi-react-example-v2`:
```bash
npx lerna --scope=@notifi-network/notifi-react-example-v2 run dev
```
- Open the Cypress test runner for `notifi-react-example-v2`:
```bash
npx lerna --scope=@notifi-network/notifi-react-example-v2 run cypress:open
```
- **Avoid leaving commented-out code** in the codebase.
If comments are necessary, follow these conventions:
- For actionable tasks:
```ts
// TODO: clarify this logic
```
- For descriptive or contextual comments:
```ts
/* Explains the reason for this conditional block */
```
### Publish packages to npm (for internal maintainers)
1. Publish canary version to npm
The following command will publish the all packages with canary version to npm. It will prompt you to select the version with suffix `-alpha.x`.
**IMPORTANT**: Run `npm run build` before running the following command.
```bash
# on the root directory
npx lerna publish --canary --force-publish
```
2. Publish official version to npm
The following command will publish the updated packages to npm. It will prompt you to select the version for each package.
**IMPORTANT**: Run `npm run build` before running the following command.
```bash
# on the root directory
npx lerna publish
```
### Type documentation
`notifi-sdk-ts` utilizes [typedoc](https://typedoc.org/) to generate the type documentation. We want to ensure that the documentation is always up-to-date by regenerating the documentation when the codebase is updated.
1. Run the command below to generate the updated typedoc.
```bash
# on the root directory
npm run docs
```
2. To preview the generated documentation locally, run the following command.
```bash
# on the root directory
npm run serve-docs
```
This will establish a local server by `light-server` to host the Type documentation page on `http://localhost:4000`.
### Bundle size analysis
To analyze the bundle size of the Notifi packages, please run the following command:
```bash
# on the root directory
npx lerna --scope=@notifi-network/notifi-react-example-v2 run build:analyze
```
## Advanced
We understand that not all scenarios can be solved with the current state of the SDK. When adding SDK features, we'd like to ensure we're building exactly what developers want. If you need to break out of the SDK features for more advanced interaction with Notifi, please see our Notifi [GraphQL API](https://api.notifi.network/gql/) that you can consume alongside the SDK.
### Built With ❤️ and ...
- [Lerna.js](https://lerna.js.org/)
- [Cypress](https://www.cypress.io/)
- [Nx](https://nx.dev/)
- [React.js](https://reactjs.org/)
- [Next.js](https://nextjs.org/)
- [GraphQL-Codegen](https://the-guild.dev/graphql/codegen/docs/getting-started)
- [TypeDoc](https://typedoc.org/)
- [husky](https://typicode.github.io/husky/)
(back to top)
[contributors-shield]: https://img.shields.io/github/contributors/notifi-network/notifi-sdk-ts.svg?style=for-the-badge
[contributors-url]: https://github.com/notifi-network/notifi-sdk-ts/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/notifi-network/notifi-sdk-ts.svg?style=for-the-badge
[forks-url]: https://github.com/notifi-network/notifi-sdk-ts/network/members
[stars-shield]: https://img.shields.io/github/stars/notifi-network/notifi-sdk-ts.svg?style=for-the-badge
[stars-url]: https://github.com/notifi-network/notifi-sdk-ts/stargazers
[issues-shield]: https://img.shields.io/github/issues/notifi-network/notifi-sdk-ts.svg?style=for-the-badge
[issues-url]: https://github.com/notifi-network/notifi-sdk-ts/issues
[license-shield]: https://img.shields.io/github/license/notifi-network/notifi-sdk-ts.svg?style=for-the-badge
[license-url]: https://github.com/notifi-network/notifi-sdk-ts/blob/main/LICENSE.txt