@punkbit/test24jan/README.md

A standalone package for Fleek Agents AI user-interface

# ⚡️Fleek Platform Agents UI

[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-blue.svg)](https://conventionalcommits.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

The Agents UI provides standalone functionality for the Eliza Agents. Originally it is implemented in the [fleek-platform/website](https://github.com/fleek-platform/website) repository but the team took a decision to extract it into a separate, standalone package for maintainability purposes, separating concerns and easier management of requirements. 

There was a transition period when code lived in both repositories and had to be encapsulated and synced to prevent diversion and maintenance overhead. 

## Overview

- [🤖 Install](#install)
- [👷‍♀️Development](#development)
  - [Environment Variables](#environment-variables)
  - [Changeset](#changeset)
- [🧸 Basic Usage](#basic-usage)
  - [Interface](#interface)
  - [Example usage](#example-usage)
- [⏳ Transition period](#transition-period)
- [⚠️ Known issues](#known-issues)
- [🙏 Contributing](#contributing)
  - [Branching strategy](#branching-strategy)
  - [Contributing](#conventional-commits)
- [⏱️ Changelog](./CHANGELOG.md)

## Install

Install the package by executing:

```sh
npm i @fleek-platform/agents-ui
```

⚠️ If you're planning to contribute as a developer, you must install [pnpm](https://pnpm.io), otherwise most commands will fail.

For a quick start, learn the [basic usage](#basic-usage).

## Development

For developers looking to contribute to the `@fleek-platform/agents-ui`, [clone](https://github.com/fleekxyz/agents-ui) the repository and follow the [contribution guide](#contributing).

For runtime we utilize [Nodejs](https://nodejs.org/en/download) and [PNPM](https://pnpm.io/installation) as the package manager.

Next, install the project dependencies:

```sh
pnpm i
```

### Environment variables

If you'll be interacting with services, you'll need to set up the environment variables.

Create a local file named `.env` and declare the following environment variables for the environment you're interested (below we're using the public~production settings):

```sh
PUBLIC_FLEEK_REST_API_URL="https://api.fleek.xyz"
PUBLIC_UI_APP_URL="https://app.fleek.xyz"
PUBLIC_BEEHIIV_PROXY_SERVER_URL="https://faas-lon1-917a94a7.doserverless.co/api/v1/web/fn-5aaf2a72-1b5b-4ac6-8c42-a2e735a32d8b/main/create-subscription"
```

The application uses the [getDefined](./src/Eliza/defined.ts) to lookup for environment variables.

### Changeset

Manage the versioning of changelog entries.

Declare an intent to release by executing the command and answering the wizard's questions:

```sh
pnpm changeset:add
```

## Basic usage

Package is distributed as ESM module that exports source code, transpiling and processing is left to the host application. To use it, you need to do the following:

1. Make sure that it is included as a dependency.

```ts
// package.json

"dependencies": {
  "@fleek-platform/agents-ui": "*", // specify the correct version
  // ...
}
```
2. Import `ElizaIntegrationLayer` component and pass the required props.


### Interface

Package defines the expected interface inside the [ElizaIntegrationLayer.tsx](src/components/Eliza/ElizaIntegrationLayer.tsx) component. The host app is expected to pass the following props:

```tsx
// package
// src/components/Eliza/ElizaIntegrationLayer.tsx

export interface ElizaIntegrationLayerProps {
  // auth props
  isLoggedIn: boolean;
  isLoggingIn: boolean;
  login: () => Promise<void>;
  fetchFleekToken: (projectId?: string) => Promise<string | undefined>;
  getSubscriptions: getSubscriptionsType;
  getPlans: getPlansType;
  // active project props
  activeProjectId: string;
}

// callback types, please see the source for the exact response shape 
type getSubscriptionsType = (projectId?: string,  token?: string) => Promise<{ ... }>;
type getPlansType = (token?: string) => Promise<{ ... }>;
```

Not all data is passed via props, additional data is passed via the `src/settings.json` common configuration file. Components inside the `src/components/Eliza` import this file. These are the required fields by the package (host app may define other, additional fields):

```ts
// src/settings.json

{
  "elizaPage": {
    "endpoints": {
      "aiAgents": "ai-agents endpoint url"
    },
    "agentsDashboardPage": "dashboard url"
  }
}
```

💡 Note: You must use relative import for this file.

```ts
import settings from '../../../settings.json'; // ✅ will work

import settings from '@base/settings.json'; // ❌ will fail
```

### Example usage

Example usage inside the host app:

```tsx
// host app (e.g. fleek-platform/website)
// src/components/AgentsUI/index.tsx

// host auth methods
import {
  createSubscription,
  getPlans,
  getSubscriptions,
} from '@components/Eliza/api';

// import implementation from the package
import { ElizaIntegrationLayer } from '@fleek-platform/agents-ui';

export const AgentsUIIntegration: React.FC = () => {
  const { triggerLoginModal, accessToken, isLoggingIn, isLoggedIn, projectId } =
    useAuthStore();
  const login = () =>
    typeof triggerLoginModal === 'function' && triggerLoginModal(true);

  return (
    <ElizaIntegrationLayer
      accessToken={accessToken}
      activeProjectId={projectId}
      isLoggedIn={isLoggedIn}
      isLoggingIn={isLoggingIn}
      login={login}
      getSubscriptions={getSubscriptions}
      getPlans={getPlans}
      createSubscription={createSubscription}
    />
  );
};

const AgentsUI: React.FC = () => <AgentsUIIntegration />;

// to be used in Astro
export default AgentsUI;
```

## Transition period

The original implementation is located in [src/components/Eliza](https://github.com/fleek-platform/website/tree/develop/src/components/Eliza). The main goal is encapsulation, allowing it to be synced with a simple copy/paste of the `src/components/Eliza` directory. There are only a few external files; those are `src/settings.json`
and the files inside `src/utils` directory. If they are changed they need to be updated too.

```bash
# package file structure

├── src
│   ├── components
│   │   └── Eliza
│   │       ├── api
│   │       ├── components
│   │       ├── hooks
│   │       └── utils
│   ├── settings.json
│   └── utils
│       ├── cn.ts
│       └── common.ts
```

## Known issues

1. The package currently does not export fonts used by Tailwind theme. The host application needs to have them installed.

```bash
AtypDisplay, IBM Plex Sans, IBM Plex Mono
```

2. Import path alias for the `src/settings.json` breaks. Components must use relative imports for this file only. Other files can use absolute imports using path aliases defined in the `tsconfig.json`.

```ts
import settings from '@base/settings.json'; // ❌ will fail
```

3. Local testing with a local file-based dependency will fail and produce false negative. You need to publish a private test package to the Github registry and include it as a dependency in the host project.

Incorrect:

```bash
# package.json
"@fleek-platform/agents-ui": "file:../agents-ui", # ❌ will fail, React dependency is doubled

npm i --install-links 
```

Correct:

```bash
# in the agents-ui 
# package.json
"version": "0.0.0-test-1",
"private": true,

# point to the Github registry and provide the token
# ~/.npmrc
//npm.pkg.github.com/:_authToken=my-github-token
@fleek-platform:registry=https://npm.pkg.github.com

# publish private test version
npm publish

# in the host app
# package.json
"@fleek-platform/agents-ui": "@fleek-platform/agents-ui@0.0.0-test-1", # ✅ will work, React dependency is deduped

npm i 
```

## Contributing

This section guides you through the process of contributing to our open-source project. From creating a feature branch to submitting a pull request, get started by:

1. Fork the project [here](https://github.com/fleekxyz/cli)
2. Create your feature branch using our [branching strategy](#branching-strategy), e.g. `git checkout -b feat/my-new-feature`
3. Run the tests: `pnpm test`
4. Commit your changes by following our [commit conventions](#conventional-commits), e.g. `git commit -m 'chore: 🤖 my contribution description'`
5. Push to the branch, e.g. `git push origin feat/my-new-feature`
6. Create new Pull Request following the corresponding template guidelines

### Branching strategy

The develop branch serves as the main integration branch for features, enhancements, and fixes. It is always in a deployable state and represents the latest development version of the application.

Feature branches are created from the develop branch and are used to develop new features or enhancements. They should be named according to the type of work being done and the scope of the feature and in accordance with conventional commits [here](#conventional-commits).

### Conventional commits

We prefer to commit our work following [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0) conventions. Conventional Commits are a simple way to write commit messages that both people and computers can understand. It help us keep track fo changes in a consistent manner, making it easier to see what was added, changed, or fixed in each commit or update.

The commit messages are formatted as **[type]/[scope]**
The **type** is a short descriptor indicating the nature of the work (e.g., feat, fix, docs, style, refactor, test, chore). This follows the conventional commit types.

The **scope** is a more detailed description of the feature or fix. This could be the component or part of the codebase affected by the change.

Here's an example of different conventional commits messages that you should follow:

```txt
test: 💍 Adding missing tests
feat: 🎸 A new feature
fix: 🐛 A bug fix
chore: 🤖 Build process or auxiliary tool changes
docs: 📝 Documentation only changes
refactor: 💡 A code change that neither fixes a bug or adds a feature
style: 💄 Markup, white-space, formatting, missing semi-colons...
```