npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@cardstack/hub

v0.28.7

Published

Stock API server for the Cardstack tech stack.

Downloads

1,187

Readme

@cardstack/hub

The Cardstack Hub is the API server for the Cardstack project. For more information, see the project-wide README.

Architecture

The Hub consists of API endpoints and a postgres database.

The app uses a Postgresql-based background task queue built on graphile/worker

Configuration

Below is a list of the most common environment variables that the Hub accepts:

  • SERVER_SECRET (required) - to generate one for your machine, run node --eval="console.log(crypto.randomBytes(32).toString('base64'))"
  • FIXER_API_KEY (required for /api/exchange-rates) - API key for currency exchange rates, we use https://fixer.io/
  • EXCHANGE_RATES_ALLOWED_DOMAINS - domains from which a request to /api/exchange-rates is allowed
  • HUB_AWS_ACCESS_KEY_ID
  • HUB_AWS_SECRET_ACCESS_KEY
  • HUB_AWS_REGION
  • AWS_PROFILE - if none of the HUBAWS* variables are defined, no credentials or region will be passed to the aws-sdk. This will make the aws-sdk's default behavior take effect, which includes using an AWS_PROFILE env var if it is set
  • DATABASE_URL - defaults in development to postgres://postgres:postgres@localhost:5432/hub_development
  • LOG_LEVELS - defaults to *=info

Search the mono-repo for process.env and check the config directory to see these variables referenced.

To use the variables, create a file named .env in the hub's folder, and put in the variables you want to use.

For example:

SERVER_SECRET=7TmgY1xFo/WrYTnAFSvAemZtFB8wQVMd8IkoeQKBboE=
AWS_PROFILE=cardstack

Setting up Discord

Some of the packages in this mono repo support the operation of a discord bot that uses the hub's DI system. We leverage CordeJS for our unit tests. CordeJS uses a discord bot running in discord to test the bot functionality by emulating a discord user and sending commands to the bot under test. In order to run the cordejs tests, you'll need to setup a discord server and install the cordebot with full permissions as well as the cardbot into the discord server.

The instructions for setting up the cordebot (and cardbot) are here: https://cordejs.org/docs/creatingdiscordbot. In these instructions you need to setup 2 bots (the instructions outline how to setup a single bot). One bot that you setup will be the cardbot, the other bot that you setup will be the cordebot (used to test the cardbot).

At the time of this writing the cardbot requires the following OAuth scopes:

Once the cardbot and cordebot bots are setup, you can then configure environment variables for running the bot tests. Specifically:

  • CORDE_BOT_ID: The bot ID for the cordebot
  • CORDE_BOT_TOKEN: The bot token for the cordebot
  • CARDBOT_ID: The bot ID for the cardbot
  • CARDBOT_TOKEN: The bot token for the cardbot
  • CARDBOT_ALLOWED_GUILDS: A comma separated list of the discord server IDs that the cardbot is allowed to communicate on. This should be the server(s) that you added the cardbot to.
  • CARDBOT_ALLOWED_CHANNELS: A comma separated list of channel IDs the cardbot is allowed to communicate in.

(Note: to easily obtain server and channel ID's enable User Settings -> Advanced -> Enable Developer Mode in Discord. This will reveal a "Copy ID" item in the settings panel for servers and channels to retrieve these ID's.)

Getting Started

You need to build the hub via yarn build, or start watching for live rebuilds with yarn rebuild.

The following command will create a hub_development database on your locally running postgres server

    createdb hub_development
    yarn db:migrate up
    dist/hub.js db seed
    dist/hub.js db dump
    NODE_ENV=test dist/hub.js db init

Running the hub

# Starts the server on port 3000
dist/hub.js server

# Starts the worker process
dist/hub.js worker

# Starts the discord bot
dist/hub.js bot

# If you want to run both in the same terminal you can run
yarn start

Database migrations

# Run available migrations
yarn db:migrate up

#To reverse the last migration:
yarn db:migrate down

#To redo the last migration (i.e. down + up):
yarn db:migrate redo

## Creating database migrations
yarn db:migrate create <migration-name>`

Documentation on how to create migration scripts is available at https://salsita.github.io/node-pg-migrate/#/migrations

After you have completed running your new DB migration script create a pg_dump of the DB in the config/structure.sql file using:

dist/hub.js db dump

Application console

To test, debug and call isolated parts of the application within its context.

yarn console starts the application console.

Examples:

Make a DB query (call installed modules)

Hub > const { Client } = require('pg');
Hub > const config = require('config');
Hub > const client = new Client(config.db.url);
Hub > await client.connect();
Hub > await client.query('SELECT * FROM merchant_infos');

Call a service (call application modules)

Hub > const workerClient = await container.lookup('worker-client');
Hub > await workerClient.addJob('persist-off-chain-merchant-info', { id: 1 });

Connecting to the database staging|production database on AWS

Setup AWS Session Manager ssh config

Add the following to your ~/.ssh/config file:

# SSH over Session Manager
host i-* mi-*
    ProxyCommand sh -c "aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'"

Lookup the tunneling command and database password:

cd [PROJECTS]/cardstack/infra/configs/hub/[staging|production]
AWS_PROFILE=cardstack terraform output | grep tunnel_to_database
AWS_PROFILE=cardstack terraform output | grep postgres_password

Run the command, open a postgres client, and connect to localhost, port 55432 with username cardstack, password as looked up in previous step.

Provided APIs

APIs conform to the JSON API specification.

GET /api/exchange-rates

GET /api/prepaid-card-patterns

GET /api/prepaid-card-color-schemes

POST /api/prepaid-card-customizations

POST /api/merchant-infos

GET /api/merchant-infos/validate-slug/:slug

The Hub CLI

The hub CLI can be invoked from within the hub package

dist/hub.js

💡 Tip: Add export PATH="./bin:$PATH" to your .zshenv or .bash_profile to be to invoke hub directly (without the bin/)

The files that support the CLI are in the cli/ directory. You can add your own by following these instructions. The full yargs api can be found here.

The Card Compiler

All compiler functionality is currently hidden behind the COMPILER feature flag. So to start the server with card compiling and related routes, use that flag.

COMPILER=true dist/hub.js server

Contributing

Note that this package is written in TypeScript, so be sure to run a TypesScript compiler as you work. See the project-wide README for information about running the Hub and its tests locally.