The GoodParty.org API built on Node.js.

Description

GoodParty.org API

Project setup

Prerequisites

• Be sure to install Node if you haven't already.
• You will need to be on node 22.12+
• If you have nvm installed, you can run nvm use to get the version from the .nvmrc file.

Setup

$ npm install

(Optional) Use Docker for postgres

Install Docker

$ docker compose up -d

# to stop docker
$ docker compose stop

# docker can also be managed in the docker dashboard of the desktop app

Install Postgres locally (Not docker)

• Create a Postgres database for the project to connect to. There are many ways to do this, below is an example using Homebrew on macOS:

  # install postgres
  brew install postgresql
  
  # start a postgres instance
  brew services start postgresql
  
  # connect to the local db
  psql postgres

  Inside the psql prompt, create a new database:

  -- create a new database for app
  CREATE DATABASE gpdb;
  -- connect to the new database
  \c gpdb;
  -- create user and password
  CREATE USER postgres WITH PASSWORD 'postgres';
  -- grant all privileges to the user
  GRANT ALL PRIVILEGES ON DATABASE gpdb TO postgres;
  -- allow the user to create databases
  ALTER USER postgres CREATEDB;

Database Setup

• Copy .env.example to .env and fill in the necessary environment variables.

• Run the following command to create the database tables:

$ npm run migrate:reset

• This also generates the Prisma Client and Typescript types.
• This should also run seeds to populate your local DB with dummy data.

Database Stop & Cleanup

Enter \q to exit the psql prompt and brew services stop postgresql to stop the postgres instance. To clean up the local database instance, reinstall with brew reinstall postgresql.

Compile and run the project

# development
$ npm run start

# watch mode
$ npm run start:dev

# production mode
$ npm run start:prod

Swagger / API documentation

• Visit http://localhost:3000/api to see swagger documentation
• Visit http://localhost:3000/api-json to get the JSON openApi representation of swagger config

Development

Testing

You can run the tests in the Postman desktop app or you can run them using the Postman CLI in a terminal:

• Install the Postman CLI tool: https://learning.postman.com/docs/postman-cli/postman-cli-installation/#system-requirements
• Generate a Postman API key: https://learning.postman.com/docs/developer/postman-api/authentication/#generate-a-postman-api-key
• Login to Postman CLI: postman login --with-api-key [API_KEY]
• Get the IDs of the collection you want to test, and the environment you want to test with from Postman: https://learning.postman.com/docs/postman-cli/postman-cli-options/#signing-in-and-out:~:text=Then%20select%20the%20information%20icon
• Run a collection: postman run [collection_id] --environment [environment_id]

(This will eventually be automated to run in a npm/npx script to automatically fetch the collection and environment keys for you)

Campaign Event Generation (Local)

To test the campaign event generation Lambda locally, run the local server in gp-ai-projects:

cd /gp-ai-projects
source .venv/bin/activate
python campaign_plan_lambda/local_server.py

Then add to your gp-api .env:

CAMPAIGN_PLAN_LOCAL_URL=http://localhost:8089/generate
CAMPAIGN_PLAN_RESULTS_BUCKET=campaign-plan-results-dev

See gp-ai-projects/campaign_plan_lambda/README.md for full setup instructions including AWS credentials and SQS queue configuration.

AWS Setup

To set up your AWS CLI locally, run the following script:

curl -fsSL https://raw.githubusercontent.com/thegoodparty/gp-api/master/scripts/aws-setup.sh | bash

Contracts Package (@goodparty_org/contracts)

A shared Zod schema and TypeScript types package published to npm as @goodparty_org/contracts. It is consumed by gp-sdk and other projects to keep API request/response types in sync without duplication.

The contracts source lives in the contracts/ directory at the repo root and is managed as an npm workspace.

Local Development

Contracts are built automatically as part of npm run start:dev and npm run build — no extra steps needed. A fresh clone workflow is:

npm install
npm run start:dev

This runs Prisma client generation, contracts codegen + build, then starts the NestJS watcher.

For live rebuilds of contracts source during development (e.g., when editing schemas for gp-sdk consumption):

cd contracts && npm run dev

When You Modify a Contract Schema

Add a changeset file before opening your PR:

cd contracts
npx changeset

Follow the interactive prompt to select a semver bump type and write a summary, then commit the generated changeset file with your PR.

When You Modify a Prisma Enum

Run npm run generate at the repo root first (to regenerate Prisma client), then:

cd contracts && npm run build

This regenerates the enum definitions in contracts/src/generated/enums.ts.

How Publishing Works

Contracts are automatically published to npm when changes are merged to master. The changesets/action in CI opens a "Version Packages" PR to bump the version. Merging that PR triggers the actual npm publish.

On develop and qa branches, contracts receive a snapshot version that is committed but not published.

Testing Against gp-sdk Locally

Build contracts first, then use the path form of npm link from gp-sdk:

cd ~/dev/good-party/gp-api/contracts
npm run build

cd ~/dev/good-party/gp-sdk
npm link ../gp-api/contracts

Run npm run dev in both contracts/ and gp-sdk/ for live rebuild chaining. To revert to the npm-published version:

cd ~/dev/good-party/gp-sdk
npm unlink @goodparty_org/contracts
npm install

Agent Job Contracts

src/generated/agent-job-contracts.ts holds TypeScript types for every agent experiment's Input and Output, used by ExperimentRunsService.dispatchRun() to type-check params per experimentType. The file is generated from per-experiment manifest.json files (with input_schema and output_schema JSON Schemas) in the agent-experiment-metadata-dev S3 bucket.

Regenerate after the agent side adds or changes a manifest:

tsx scripts/generate-agent-job-types.ts

Requires AWS credentials with read access to agent-experiment-metadata-dev. Commit the regenerated file. See src/agentExperiments/CLAUDE.md for the full dispatch flow.

Deployment

This project's deployment is managed via Pulumi within the deploy directory.

There is an in-tree CLI for interacting with the Pulumi stack: npm run infra.

For example, to validate deployment changes, you can run npm run infra diff <dev|qa|prod> -- this will output a summary of changes that will be applied to the specified environment.

Note: You'll need to be authenticated via the AWS CLI locally before running infra commands.

Resources

Check out a few resources that may come in handy when working with NestJS:

• Visit the NestJS Documentation to learn more about the framework.
• For questions and support, please visit our Discord channel.
• To dive deeper and get more hands-on experience, check out our official video courses.
• Deploy your application to AWS with the help of NestJS Mau in just a few clicks.
• Visualize your application graph and interact with the NestJS application in real-time using NestJS Devtools.
• Need help with your project (part-time to full-time)? Check out our official enterprise support.
• To stay in the loop and get updates, follow us on X and LinkedIn.
• Looking for a job, or have a job to offer? Check out our official Jobs board.

AI-Assisted Development

We use Claude Code for AI-assisted development. Project-specific context lives in CLAUDE.md at the repo root. If you find yourself teaching the AI the same thing more than once, add it to CLAUDE.md so all future sessions (for the whole team) benefit.

License

Nest is MIT licensed.