Skip to content

Commit 0afde97

Browse files
suleigoldenwtfsayo
suleigolden
and
wtfsayo
authored
feat: Plugin football (elizaOS#2461)
* feat: inital football plugin setup from using bootstrap plugin * feat: get match action * feat: fetch standings action * fix: type script error * feat: enhance fetchMatchAction and fetchStandingsAction with reliability and validation updates - Added 5-second timeout using AbortController for fetchMatchAction. - Implemented response validation to ensure data structure matches expected types. - Improved error handling with detailed logs for better debugging. - Removed .ts extensions from imports in index.ts to prevent production build issues. - Cleaned up tsup.config.ts by removing unused externals (@reflink/reflink and @node-llama-cpp). - Guarded against invalid API responses to enhance type safety. * Update pnpm-lock.yaml * feat: football.character * feat: display standing result with callback * Update pnpm-lock.yaml * Update .env.example --------- Co-authored-by: Sayo <hi@sayo.wtf>
1 parent b776877 commit 0afde97

17 files changed

+1101
-15
lines changed

‎.env.example

+4-1
Original file line numberDiff line numberDiff line change
@@ -817,4 +817,7 @@ HYPERBOLIC_ENV=production
817817
HYPERBOLIC_API_KEY=
818818
HYPERBOLIC_GRANULAR_LOG=true
819819
HYPERBOLIC_SPASH=true
820-
HYPERBOLIC_LOG_LEVEL=debug
820+
HYPERBOLIC_LOG_LEVEL=debug
821+
822+
# Football Plugin Configuration
823+
FOOTBALL_API_KEY= # API key from Football-Data.org (https://www.football-data.org/)

‎agent/package.json

+3-1
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,8 @@
123123
"@elizaos/plugin-suno": "workspace:*",
124124
"@elizaos/plugin-udio": "workspace:*",
125125
"@elizaos/plugin-hyperbolic": "workspace:*",
126-
"readline": "1.3.0",
126+
"@elizaos/plugin-football": "workspace:*",
127+
"readline": "1.3.0",
127128
"ws": "8.18.0",
128129
"yargs": "17.7.2"
129130
},
@@ -135,3 +136,4 @@
135136
"tsup": "8.3.5"
136137
}
137138
}
139+

‎agent/src/index.ts

+4-2
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ import {
4444
validateCharacterConfig,
4545
} from "@elizaos/core";
4646
import { zgPlugin } from "@elizaos/plugin-0g";
47+
import { footballPlugin } from "@elizaos/plugin-football";
4748

4849
import { bootstrapPlugin } from "@elizaos/plugin-bootstrap";
4950
import { normalizeCharacter } from "@elizaos/plugin-di";
@@ -947,6 +948,7 @@ export async function createAgent(
947948
getSecret(character, "DEXSCREENER_API_KEY")
948949
? dexScreenerPlugin
949950
: null,
951+
getSecret(character, "FOOTBALL_API_KEY") ? footballPlugin : null,
950952
getSecret(character, "CONFLUX_CORE_PRIVATE_KEY")
951953
? confluxPlugin
952954
: null,
@@ -1397,12 +1399,12 @@ if (
13971399
parseBooleanFromText(process.env.PREVENT_UNHANDLED_EXIT)
13981400
) {
13991401
// Handle uncaught exceptions to prevent the process from crashing
1400-
process.on("uncaughtException", (err) => {
1402+
process.on('uncaughtException', function(err) {
14011403
console.error("uncaughtException", err);
14021404
});
14031405

14041406
// Handle unhandled rejections to prevent the process from crashing
1405-
process.on("unhandledRejection", (err) => {
1407+
process.on('unhandledRejection', function(err) {
14061408
console.error("unhandledRejection", err);
14071409
});
14081410
}

‎packages/core/src/defaultCharacter.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { type Character, ModelProviderName } from "./types.ts";
1+
import { Character, ModelProviderName } from "./types.ts";
22

33
export const defaultCharacter: Character = {
44
name: "Eliza",

‎packages/plugin-football/.npmignore

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
*
2+
3+
!dist/**
4+
!package.json
5+
!readme.md
6+
!tsup.config.ts

‎packages/plugin-football/README.md

+216
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
# @elizaos/plugin-football
2+
3+
A plugin providing live football match data and league standings integration for ElizaOS agents.
4+
5+
## Description
6+
7+
The Football plugin integrates with the [Football-Data.org API](https://www.football-data.org/) to enable ElizaOS agents to fetch live football match information and league standings. It includes actions and utilities to provide real-time football data in conversations.
8+
9+
## Installation
10+
11+
To install the plugin, use the following command:
12+
13+
```bash
14+
pnpm install @elizaos/plugin-football
15+
```
16+
17+
## Features
18+
19+
### 1. Live Match Data
20+
21+
- **Action**: `fetchMatchAction`
22+
- Retrieves live football match data, including:
23+
- Teams
24+
- Scores
25+
- Game events
26+
- Provides real-time updates for ongoing matches.
27+
28+
### 2. League Standings
29+
30+
- **Action**: `fetchStandingsAction`
31+
- Fetches league standings for a specified competition, including:
32+
- Team rankings
33+
- Points
34+
- Goals scored
35+
- Other league statistics.
36+
37+
### 3. Flexible Integration
38+
39+
- Extendable for additional football data, such as:
40+
- Player statistics
41+
- Match schedules
42+
- Historical match data.
43+
44+
## API Key Configuration
45+
46+
To use this plugin, you need an API key from [Football-Data.org](https://www.football-data.org/).
47+
48+
1. Register and obtain your API key from Football-Data.org.
49+
2. Add the API key to your `.env` file:
50+
51+
```env
52+
FOOTBALL_API_KEY=your_api_key_here
53+
```
54+
55+
The plugin will use this key to authenticate requests.
56+
57+
## Usage Examples
58+
59+
### `fetchMatchAction`
60+
61+
**Description**: Retrieves live match data.
62+
63+
**Code Example**:
64+
65+
```javascript
66+
import { fetchMatchAction } from "@elizaos/plugin-football";
67+
68+
const result = await fetchMatchAction.handler(runtime, message, state);
69+
console.log(result);
70+
```
71+
72+
**Sample Output**:
73+
74+
```json
75+
{
76+
"matches": [
77+
{
78+
"homeTeam": { "name": "Chelsea" },
79+
"awayTeam": { "name": "Arsenal" },
80+
"score": {
81+
"fullTime": { "homeTeam": 1, "awayTeam": 2 }
82+
}
83+
}
84+
]
85+
}
86+
```
87+
88+
### `fetchStandingsAction`
89+
90+
**Description**: Fetches league standings for a specific competition.
91+
92+
**Code Example**:
93+
94+
```javascript
95+
import { fetchStandingsAction } from "@elizaos/plugin-football";
96+
97+
const result = await fetchStandingsAction.handler(runtime, message, state);
98+
console.log(result);
99+
```
100+
101+
**Sample Output**:
102+
103+
```json
104+
{
105+
"standings": [
106+
{
107+
"table": [
108+
{
109+
"position": 1,
110+
"team": { "name": "Manchester City" },
111+
"points": 45
112+
},
113+
{ "position": 2, "team": { "name": "Arsenal" }, "points": 42 }
114+
]
115+
}
116+
]
117+
}
118+
```
119+
120+
## Development
121+
122+
### Steps to Build and Test
123+
124+
1. Clone the repository:
125+
126+
```bash
127+
git clone https://github.com/elizaOS/eliza.git
128+
```
129+
130+
2. Navigate to the `plugin-football` directory and install dependencies:
131+
132+
```bash
133+
cd packages/plugin-football
134+
pnpm install
135+
```
136+
137+
3. Build the plugin:
138+
139+
```bash
140+
pnpm run build
141+
```
142+
143+
4. Run linting:
144+
145+
```bash
146+
pnpm run lint
147+
```
148+
149+
5. Test the plugin:
150+
151+
```bash
152+
pnpm vitest src/tests/match-action.test.ts
153+
pnpm vitest src/tests/fetch-standings-action.test.ts
154+
```
155+
156+
## Dependencies
157+
158+
This plugin relies on the following dependency:
159+
160+
- `@elizaos/core: workspace:*`
161+
162+
## Future Enhancements
163+
164+
### Expanded Football Data Features
165+
166+
- Player statistics
167+
- Match schedules and fixtures
168+
- Team information and histories
169+
- Historical match data
170+
171+
### Advanced League Tracking
172+
173+
- Real-time updates for all supported leagues
174+
- Integration with more competitions (e.g., Champions League, World Cup)
175+
176+
### Customizable Output
177+
178+
- Improved data formatting for conversational outputs
179+
- Support for additional localization options
180+
181+
### Integration Improvements
182+
183+
- Enhanced API error handling
184+
- Caching for frequently accessed data
185+
- Increased rate-limit compliance for the Football-Data.org API
186+
187+
### Developer Tools
188+
189+
- Sample applications for plugin usage
190+
- Test suites for advanced football scenarios
191+
- Examples for extending plugin functionality
192+
193+
## Contributing
194+
195+
Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information.
196+
197+
## Credits
198+
199+
This plugin integrates with and builds upon several key technologies:
200+
201+
- [Football-Data.org](https://www.football-data.org/documentation/quickstart/) Official Football-Data platform API
202+
203+
Special thanks to:
204+
205+
- Special thanks to [Football-Data.org](https://www.football-data.org/) for providing the API that powers this plugin.
206+
- The Eliza Core development team.
207+
- The Eliza community for their contributions and feedback
208+
209+
For more information about Football-Data integration capabilities:
210+
211+
- [Football-Data API Documentation](https://www.football-data.org/documentation/quickstart)
212+
- [Football-Data Developer Portal](https://www.football-data.org/documentation/api)
213+
214+
## License
215+
216+
This plugin is part of the Eliza project. See the main project repository for license information.

‎packages/plugin-football/eslint.config.mjs

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
import eslintGlobalConfig from "../../eslint.config.mjs";
2+
3+
export default [...eslintGlobalConfig];

‎packages/plugin-football/package.json

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
{
2+
"name": "@elizaos/plugin-football",
3+
"version": "0.1.8+build.1",
4+
"type": "module",
5+
"main": "dist/index.js",
6+
"module": "dist/index.js",
7+
"types": "dist/index.d.ts",
8+
"exports": {
9+
"./package.json": "./package.json",
10+
".": {
11+
"import": {
12+
"@elizaos/source": "./src/index.ts",
13+
"types": "./dist/index.d.ts",
14+
"default": "./dist/index.js"
15+
}
16+
}
17+
},
18+
"files": [
19+
"dist"
20+
],
21+
"dependencies": {
22+
"@elizaos/core": "workspace:*",
23+
"tsup": "8.3.5"
24+
},
25+
"scripts": {
26+
"build": "tsup --format esm --dts",
27+
"dev": "tsup --format esm --dts --watch",
28+
"lint": "eslint --fix --cache ."
29+
},
30+
"peerDependencies": {
31+
"whatwg-url": "7.1.0"
32+
}
33+
}

0 commit comments

Comments
 (0)