{"id":25856563,"url":"https://github.com/defra/farming-grants-agreements-api","last_synced_at":"2026-01-17T07:04:53.653Z","repository":{"id":279996213,"uuid":"940696978","full_name":"DEFRA/farming-grants-agreements-api","owner":"DEFRA","description":"Git repository for service farming-grants-agreements-api","archived":false,"fork":false,"pushed_at":"2025-02-28T16:23:11.000Z","size":135,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-02-28T21:14:10.794Z","etag":null,"topics":["backend","cdp","node","service"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DEFRA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-28T16:22:55.000Z","updated_at":"2025-02-28T16:23:15.000Z","dependencies_parsed_at":"2025-02-28T21:15:07.231Z","dependency_job_id":"fd92f9bf-8de8-41f3-9961-83e9116f76de","html_url":"https://github.com/DEFRA/farming-grants-agreements-api","commit_stats":null,"previous_names":["defra/farming-grants-agreements-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Ffarming-grants-agreements-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Ffarming-grants-agreements-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Ffarming-grants-agreements-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Ffarming-grants-agreements-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DEFRA","download_url":"https://codeload.github.com/DEFRA/farming-grants-agreements-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241404480,"owners_count":19957662,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend","cdp","node","service"],"created_at":"2025-03-01T18:19:04.295Z","updated_at":"2026-01-17T07:04:53.634Z","avatar_url":"https://github.com/DEFRA.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# farming-grants-agreements-api\n\nCore delivery platform Node.js Backend Template.\n\n- [farming-grants-agreements-api](#farming-grants-agreements-api)\n  - [Requirements](#requirements)\n    - [Node.js](#nodejs)\n  - [Local development](#local-development)\n    - [Setup](#setup)\n    - [Development](#development)\n    - [Testing](#testing)\n  - [Testing the SQS queue](#testing-the-sqs-queue)\n    - [Production](#production)\n    - [Npm scripts](#npm-scripts)\n    - [Update dependencies](#update-dependencies)\n    - [Formatting](#formatting)\n      - [Windows prettier issue](#windows-prettier-issue)\n    - [Running the agreements-api service with JWT authentication enabled](#running-the-agreements-api-service-with-jwt-authentication-enabled)\n  - [API endpoints](#api-endpoints)\n    - [Generating a JWT for API calls (scripts/gen-auth-header.js)](#generating-a-jwt-for-api-calls-scriptsgen-auth-headerjs)\n    - [Proxy](#proxy)\n  - [Docker](#docker)\n    - [Development image](#development-image)\n    - [Production image](#production-image)\n    - [Docker Compose](#docker-compose)\n    - [Viewing messages in LocalStack SQS](#viewing-messages-in-localstack-sqs)\n    - [The Google Analytics trackingId secret configuration GA_TRACKING_ID(googleAnalytics.trackingId)](#the-google-analytics-trackingid-secret-configuration-ga_tracking_idgoogleanalyticstrackingid)\n    - [Dependabot](#dependabot)\n    - [SonarCloud](#sonarcloud)\n  - [Licence](#licence)\n    - [About the licence](#about-the-licence)\n\n## Requirements\n\n### Node.js\n\nPlease install [Node.js](http://nodejs.org/) `\u003e= v18` and [npm](https://nodejs.org/) `\u003e= v9`. You will find it\neasier to use the Node Version Manager [nvm](https://github.com/creationix/nvm)\n\nTo use the correct version of Node.js for this application, via nvm:\n\n```bash\ncd farming-grants-agreements-api\nnvm use\n```\n\n## Local development\n\n### Setup\n\nInstall application dependencies:\n\n```bash\nnpm install\n```\n\n### Development\n\nTo run the application in `development` mode run:\n\n```bash\nnpm run dev\n```\n\nIf you'd like to seed the database with a mock agreement (which you can view by using the agreementId `SFI123456789`) you must set the environment variable `SEED_DB` to `true`.\nTo run the service without `grants-ui` disable the Jwt authentication by setting the environment variable `JWT_ENABLED=false`\n\n```bash\nJWT_ENABLED=false SEED_DB=true npm run dev\n```\n\nIf you want to be able to run the app without dependencies on external service like land grants you can generate the mock data by running `npm run test:contracts:consumer` and then set the environment variable `LAND_GRANTS_BASE_URL=\"http://mock-server:8081\"` (or `LAND_GRANTS_BASE_URL=\"http://localhost:8081\"` if you are running the farming-grants-agreements-api outside of Docker) and start Docker compose with the mock profile:\n\n```bash\ndocker compose --profile mock up\n```\n\n### Testing\n\nTo test the application run:\n\n```bash\nnpm run test\n```\n\n## Testing the SQS queue\n\nTo manually test the listener, run the following to build the required Docker containers:\n\n```bash\ndocker compose -f compose.yml up -d --build\n```\n\nIt might be helpful to use localstack's dashboard to view the SQS queue and any messages: [https://app.localstack.cloud/inst/default/resources/sqs](https://app.localstack.cloud/inst/default/resources/sqs)\n\nYou can send a test `grant_application_approved` event by running:\n\n```bash\nnpm run publish:accept\n```\n\nThe Agreement should be automatically created and viewable on the front-end, and the event should be consumed and deleted from the queue.\n\n### Production\n\nTo mimic the application running in `production` mode locally run:\n\n```bash\nnpm start\n```\n\n### Npm scripts\n\nAll available Npm scripts can be seen in [package.json](./package.json).\nTo view them in your command line run:\n\n```bash\nnpm run\n```\n\n### Update dependencies\n\nTo update dependencies use [npm-check-updates](https://github.com/raineorshine/npm-check-updates):\n\n\u003e The following script is a good start. Check out all the options on\n\u003e the [npm-check-updates](https://github.com/raineorshine/npm-check-updates)\n\n```bash\nncu --interactive --format group\n```\n\n### Formatting\n\n#### Windows prettier issue\n\nIf you are having issues with formatting of line breaks on Windows update your global git config by running:\n\n```bash\ngit config --global core.autocrlf false\n```\n\n### Running the agreements-api service with JWT authentication enabled\n\n1. Ensure JWT is enabled in your .env file:\n   - `JWT_ENABLED=true`\n2. Start the stack (MongoDB, LocalStack and this service):\n\n   ```bash\n   docker compose up -d --build\n   ```\n\n3. Verify containers are healthy (example output):\n\n   ```\n   NAME                                                           COMMAND                  STATE     PORTS\n   farming-grants-agreements-api-farming-grants-agreements-api-1  \"/sbin/tini -- node .\"  running   0.0.0.0:3555-\u003e3555/tcp, [::]:3555-\u003e3555/tcp\n   farming-grants-agreements-api-localstack-1                     \"docker-entrypoint.sh\"  running   0.0.0.0:4510-4559-\u003e4510-4559/tcp, [::]:4510-4559-\u003e4510-4559/tcp, 0.0.0.0:4566-\u003e4566/tcp, [::]:4566-\u003e4566/tcp\n   farming-grants-agreements-api-mongodb-1                        \"docker-entrypoint.s…\"  running   0.0.0.0:27017-\u003e27017/tcp, [::]:27017-\u003e27017/tcp\n   ```\n\n## API endpoints\n\n| Endpoint              | Description                                                   |\n| :-------------------- | :------------------------------------------------------------ |\n| `GET: /health`        | Health                                                        |\n| `GET: /{agreementId}` | Get an agreement in json format based on agreementId          |\n| `GET: /`              | Get an agreement in json format based on the sbi in the token |\n\nPass the JWT token in the header as `x-encrypted-auth`.\n\n### Generating a JWT for API calls (scripts/gen-auth-header.js)\n\nUse the helper script to generate a valid token that this API will accept.\n\nRequirements:\n\n- Use the same JWT secret as the service (AGREEMENTS_JWT_SECRET). When running with Docker Compose, it defaults to `a-string-secret-at-least-256-bits-long` unless you override it in your environment.\n- The `source` claim must be one of `defra` (farmer) or `entra` (case worker).\n- When `source=defra`, you can include an `sbi` claim to test farmer-scoped endpoints.\n\nRun examples:\n\n- With the secret provided as an argument:\n\n  ```bash\n  node ./scripts/gen-auth-header.js --source defra --sbi 106284777 \\\n    --secret \"a-string-secret-at-least-256-bits-long\"\n  ```\n\n- Or using an environment variable for the secret (recommended):\n\n  ```bash\n  AGREEMENTS_JWT_SECRET=\"a-string-secret-at-least-256-bits-long\" \\\n  node ./scripts/gen-auth-header.js --source entra\n  ```\n\nExpected output (example):\n\n```\nUI/API header { 'x-encrypted-auth': 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....' }\n```\n\nCopy the token value and use it in your requests. For example:\n\n```bash\ncurl -sS http://localhost:3555/ \\\n  -H \"x-encrypted-auth: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....\"\n```\n\nNotes:\n\n- On Windows PowerShell, use double quotes around arguments and escape as needed, for example:\n  ```powershell\n  $env:AGREEMENTS_JWT_SECRET=\"a-string-secret-at-least-256-bits-long\"; `\n  node ./scripts/gen-auth-header.js --source defra --sbi 106284777\n  ```\n- The script validates `--source` and will exit with an error if the value is not `defra` or `entra` or if the secret is missing.\n\nSample token for farmer's (`source=defra`) data:\n\n`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMiwic2JpIjoxMDYyODQ3NzcsInNvdXJjZSI6ImRlZnJhIn0.6QYSh1udNQcOF53kBST-4koc8Dp7jQ2hkMEKvCfmO9U`\n\nExample decoded payload:\n\n```json\n{\n  \"sub\": \"1234567890\",\n  \"name\": \"John Doe\",\n  \"admin\": true,\n  \"iat\": 1516239022,\n  \"sbi\": 106284777,\n  \"source\": \"defra\"\n}\n```\n\nSample token for case worker's (`source=entra`) data:\n\n`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gQm9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMiwic291cmNlIjoiZW50cmEifQ.aKtZl5K7iTQ-XI0V1Uga4eR_zjPxX41MTJmzR9lBV7I`\n\nExample decoded payload:\n\n```json\n{\n  \"sub\": \"1234567890\",\n  \"name\": \"John Boe\",\n  \"admin\": true,\n  \"iat\": 1516239022,\n  \"source\": \"entra\"\n}\n```\n\n### Proxy\n\nWe are using forward-proxy which is set up by default. To make use of this: `import { fetch } from 'undici'` then because of the `setGlobalDispatcher(new ProxyAgent(proxyUrl))` calls will use the ProxyAgent Dispatcher\n\nIf you are not using Wreck, Axios or Undici or a similar http that uses `Request`. Then you may have to provide the proxy dispatcher:\n\nTo add the dispatcher to your own client:\n\n```javascript\nimport { ProxyAgent } from 'undici'\n\nreturn await fetch(url, {\n  dispatcher: new ProxyAgent({\n    uri: proxyUrl,\n    keepAliveTimeout: 10,\n    keepAliveMaxTimeout: 10\n  })\n})\n```\n\n## Docker\n\n### Development image\n\nBuild:\n\n```bash\ndocker build --no-cache -t defradigital/farming-grants-agreements-api:latest .\n```\n\nRun:\n\n```bash\ndocker run -e PORT=3555 -p 3555:3555 defradigital/farming-grants-agreements-api:latest\n```\n\n### Production image\n\nBuild:\n\n```bash\ndocker build --no-cache --tag defradigital/farming-grants-agreements-api:latest .\n```\n\nRun:\n\n```bash\ndocker run -e PORT=3555 -p 3555:3555 defradigital/farming-grants-agreements-api:latest\n```\n\n### Docker Compose\n\nA local environment with:\n\n- Localstack for AWS services (S3, SQS)\n- MongoDB\n- This service.\n\n```bash\ndocker compose up --build -d\n```\n\n### Viewing messages in LocalStack SQS\n\nBy default, our LocalStack monitor only shows **message counts** (`ApproximateNumberOfMessages`, `ApproximateNumberOfMessagesNotVisible`) for each queue.\nThis is intentional, so we don’t interfere with the application’s consumers — pulling messages removes them from visibility until they are deleted or the visibility timeout expires.\n\nIf you want to **peek at the actual messages** (for debugging or development only), you can run:\n\n```bash\ndocker compose exec localstack sh -lc '\n  QURL=$(awslocal sqs get-queue-url \\\n    --queue-name record_agreement_status_update \\\n    --query QueueUrl --output text)\n\n  awslocal sqs receive-message \\\n    --queue-url \"$QURL\" \\\n    --max-number-of-messages 10 \\\n    --wait-time-seconds 1 \\\n    --message-attribute-names All \\\n    --attribute-names All\n'\n```\n\n### The Google Analytics trackingId secret configuration GA_TRACKING_ID(googleAnalytics.trackingId)\n\n- Development (Dev): GTM-WJ5C78H\n- Production (Prod): GTM-KRJXHHT\n\n### Dependabot\n\nWe have added an example dependabot configuration file to the repository. You can enable it by renaming\nthe [.github/example.dependabot.yml](.github/example.dependabot.yml) to `.github/dependabot.yml`\n\n### SonarCloud\n\nInstructions for setting up SonarCloud can be found in [sonar-project.properties](./sonar-project.properties)\n\n## Licence\n\nTHIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:\n\n\u003chttp://www.nationalarchives.gov.uk/doc/open-government-licence/version/3\u003e\n\nThe following attribution statement MUST be cited in your products and applications when using this information.\n\n\u003e Contains public sector information licensed under the Open Government license v3\n\n### About the licence\n\nThe Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable\ninformation providers in the public sector to license the use and re-use of their information under a common open\nlicence.\n\nIt is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefra%2Ffarming-grants-agreements-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdefra%2Ffarming-grants-agreements-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefra%2Ffarming-grants-agreements-api/lists"}