Musora Content Services

Welcome to the musora-content-services repository. This package provides a collection of utility functions designed to fetch and manage content from our Sanity Studio. These functions are tailored to interact with our Sanity backend, allowing you to easily retrieve, filter, and manipulate content for use in various applications.

Setup

To set up the Musora Content Services project for local development, follow these steps:

• In the railenvironment directory, start up the container with the ./rrr.sh command
• Run r setup musora-content-services
• Run npm install --save-dev jest
• Create a new .env file in the root of the project and copy the contents from 1Password "musora-content-services .env"

You're now set for doing basic development and running tests through npm. To set up an even better developer experience, you can also do the following:

• Find the location of node within the container by running which node in your terminal (inside the rrr shell)
  • This should be something along the lines of /home/.nvm/versions/node/v20.14.0/bin/node
• Add the Node interpreter to your IDE. The following steps are for PHPStorm:
  • Go to File > Settings
  • Under Languages & Frameworks, click on Node.js
  • Under the Node interpreter dropdown, click "Add..." and select "Add Remote..."
  • In the next window, choose the Docker option
    • Set the Server to Docker
    • For the Image name, use the dropdown to select railenvironment_docker-manager:latest (this is the docker image that we're in when running the rrr shell)
    • For the Node.js interpreter path, paste in the path from step 1 (e.g. /home/.nvm/versions/node/v20.14.0/bin/node)
  • Apply the changes and click OK
• You now have a Node interpreter set up that will assist in linting, tests, etc.

Features

• Fetch Content by ID: Retrieve specific content items using their unique Railcontent ID.
• Fetch All Songs: Get a list of all songs for a brand with pagination and search capabilities.
• Filter Options: Generate filtering options based on difficulty, genre, and more.
• Fetch Related Content: Easily fetch related lessons, songs, and content items.
• Sanity Integration: Simplified interaction with the Sanity API using customizable configurations.

Installation

To install the package, use npm:

npm install musora-content-services

Generating index.js and index.d.ts

The index.js and index.d.ts files provide all exported functions from this package, and are generated automatically. Simply run npm run build-index to build these files. It works by running the tools/generate-index.js file, which simply parses the files under the src/services directory and builds up the index files with any functions tagged with export.

If you want to exclude any of your exported functions from the generated index files, be sure to add the function name to the excludeFromGeneratedIndex array inside the service file.

Publishing Package Updates

To publish a new version to NPM run,

./publish.sh

NPM reauthentication

If you see this error displayed when publishing, you need to reauthenticate:

npm notice Publishing to https://registry.npmjs.org/ with tag latest and default access
npm notice Access token expired or revoked. Please try logging in again.
npm ERR! code E404
npm ERR! 404 Not Found - PUT https://registry.npmjs.org/musora-content-services - Not found
npm ERR! 404
npm ERR! 404  '[email protected]' is not in this registry.
npm ERR! 404
npm ERR! 404 Note that you can also install from a
npm ERR! 404 tarball, folder, http url, or git url.

Use the shared musora_dev account in 1password ("NPM Access Token For musora_dev") and update this value as npmAccessToken in the railenvironment credentials file.

Alternatively, request your own account or renew your own token. Update railenvironment credentials file with your new account details

npmUserName=
npmPassword=
npmAccessToken=

Either restart the manager container (docker restart railenvironmentdocker_manager) or run ./usr/local/bin/setup-npm.sh inside the container to update the ~/.npmrc file.

Symlinking

To link this package to the MWP repo for local development run,

./link_mcs.sh

If either of these commands fail due to permissions,

chmod +x <command>

Publish Documentation

This repo uses JSDoc to generate API documentation. To update the docs, run:

npm run doc

GitHub Page Documentation

https://railroadmedia.github.io/musora-content-services/

Run tests

Ensure that the setup process has been completed, including copying .env file from 1Password "musora-content-services .env" and having jest installed (npm install --save-dev jest). To run the full test suite, simply run the following:

npm test

You can also filter down to specific tests with the -- -t="..." option. e.g. you can run the userContext test suite with npm test -- -t="userContext" or just the contentLiked test with npm test -- -t="contentLiked"