/Temzone-API

The Temtem Interactive Map API

Primary LanguageTypeScriptMIT LicenseMIT

Temzone - API

Version Build Quality

Welcome to Temzone API, a RESTful API built with Cloudflare Workers from Temtem Interactive Map.

Getting started

This guide will help you get up and running the application in just a few minutes.

Prerequisites

Before getting started, make sure you have the following tools installed on your development machine:

  • Node.js (version 18.13.0)
  • npm (the Node.js package manager, which should be installed with Node.js)
  • Wrangler (the Cloudflare Workers CLI, which can be installed with npm)

Install dependencies

To install the dependencies for a Cloudflare Workers project, you'll need to use the npm install command. This command reads the dependencies and devDependencies sections of the package.json file and installs the packages listed there.

For example, to install all of the dependencies you can run the following command in the project directory:

npm install

You can also use npm install to install a specific package by providing the package name as an argument. For example:

npm install hono

This will install the hono package and add it to the dependencies section of the package.json file.

Setting up Firebase

To use Firebase, follow these steps:

  1. Create a new project in the Firebase console at https://console.firebase.google.com.
  2. Navigate to the Authentication tab and enable the sign-in method(s) you want to use.
  3. In the .dev.vars file of the project, add the following variable: FIREBASE_PROJECT_ID.
  4. In the .env file of the project, add the following variables: FIREBASE_PROJECT_ID, FIREBASE_PRIVATE_KEY, FIREBASE_CLIENT_EMAIL, FIREBASE_API_KEY, FIREBASE_USER_EMAIL, FIREBASE_USER_PASSWORD, TEMZONE_BASE_URL.
  • FIREBASE_PROJECT_ID: This variable should contain the ID of your Firebase project.
  • FIREBASE_PRIVATE_KEY: Use this variable to store the private key associated with your Firebase project. It's typically a long string that starts with -----BEGIN PRIVATE KEY----- and ends with -----END PRIVATE KEY-----.
  • FIREBASE_CLIENT_EMAIL: Set this variable to the email address of the Firebase service account used for authentication and authorization.
  • FIREBASE_API_KEY: This variable should contain the Firebase API key, which is required for authenticating with Firebase services.
  • FIREBASE_USER_EMAIL: Use this variable to specify the email address of a Firebase user. Please note that the user account associated with this email must have a custom claim with a value of admin:true in order to have write access to the database.
  • FIREBASE_USER_PASSWORD: Set this variable to the password for the above Firebase user. It will be used for authentication purposes when interacting with Firebase services.
  • TEMZONE_BASE_URL: This variable should store the base URL of the Temzone API instance. If you are running the server instance locally, set the variable to http://127.0.0.1:8787, which is the default URL for a local instance of the API.

Note that the Cloudflare Workers project will use the tokens generated by Firebase to authenticate requests. To validate the tokens, the server will need to know the ID of your Firebase project. That's why you need to add the FIREBASE_PROJECT_ID variable in the .dev.vars file. Additionally, the remaining variables mentioned are crucial for test execution and push notifications to function properly.

Scrape Temtem Wiki

To scrape data from the Official Temtem Wiki, run the following command in the project directory:

npm run scraper

This command will start the data scraping process and store the scraped data in a local JSON file. You can modify the scraping logic by editing the files in the scraper folder.

The npm run scraper command accepts additional parameters that you can use to customize the data scraping process. For example, if you only want to run a single scraper instead of all of them, you can specify the name of the scraper as a parameter. The available scrapers are:

  • npm run scraper -- types: This command will scrape the types data.
  • npm run scraper -- temtem: This command will scrape the temtem data.
  • npm run scraper -- spawns: This command will scrape the spawns data.
  • npm run scraper -- saipark: This command will scrape the saipark data.

Prior to running these commands, ensure that you add the following environment variables to the .env file in order to enable push notifications with Firebase:

FIREBASE_PROJECT_ID=
FIREBASE_PRIVATE_KEY=
FIREBASE_CLIENT_EMAIL=

Setting up database

Temzone's RESTful API requires two technologies to store and retrieve data: D1 and KV.

  • D1 is an SQLite database at the edge. It provides a simple SQL interface that allows you to store and retrieve data from anywhere in the world within a few milliseconds.

  • KV is a global, low-latency, key-value data store that is designed for high throughput and low latency use cases. It provides a simple key-value interface that allows you to store and retrieve data from anywhere in the world within a few milliseconds.

To create a D1 database and a KV namespace, we will use the Wrangler command-line tool. If you haven't already, make sure to install Wrangler and configure it with your Cloudflare account.

To create the D1 database, run the following command:

npx wrangler d1 create temzone

This command generates a new database with the name temzone and returns a binding that can be used to access the newly created database. This binding should be added to the wrangler.toml file in the d1_databases section.

To create the KV namespace, run the following command:

npx wrangler kv:namespace create cache

This command creates a new namespace with the name cache and returns a binding that can be used to access the newly created namespace. This binding should be added to the wrangler.toml file in the kv_namespaces section.

For more information on how to use D1 and KV with a Workers application, see the official documentation.

Migrating database

To create or update the necessary tables in the database, you can use the following command:

npm run database:migrate

This command will migrate the D1 database using the schemas defined in the migrations folder. Each migration file in the folder has a version number specified in the filename and is listed in sequential order. Keep in mind that any changes you make to the database schema will require you to create a new migration file and run this command again to keep the tables up-to-date.

Populating database

To populate the database with the data scraped from the Official Temtem Wiki, you can run the following command:

npm run database:populate

However, before running this command, you need to add the following environment variables to the .env file:

FIREBASE_API_KEY=
FIREBASE_USER_EMAIL=
FIREBASE_USER_PASSWORD=
TEMZONE_BASE_URL=

Note that this command should only be run after creating the necessary tables in the database using npm run database:migrate. Also, if you run the command again, any markers that have already been added to the database will be ignored and not added again.

Running development server

To run the Temzone API development server, navigate to the project directory and run the following command:

npm run dev

This command will start the Cloudflare Workers development server, which will automatically reload the Workers as you make changes to the code. You can then access the API via http://127.0.0.1:8787.

Note that the development server is intended for local testing only and is not suitable for production use. To deploy the API in a production environment, you will need to use a Cloudflare Workers script deployment tool such as Wrangler.

Running tests

To run the tests for the application, you can use the following command:

npm run test

The tests use the Vitest testing framework, which is included as a devDependency in the project's package.json file. By default, Vitest will look for files with a .test.js extension in the project directory.

Additionally, it's worth noting that the tests are executed using a Firebase emulator, which allows for local testing of Firebase functions and features. This means that the tests are not actually modifying any data on the Firebase server, but are instead using a locally emulated version of the Firebase services. The configuration for the Firebase emulator can be found in the firebase.json file.

License

This project is licensed under the terms of the MIT license.