rim-xmg-lib

Note: Coveralls will post a comment on pull requests with a link to the coverage report.

Coveralls setup

To enable Coveralls reporting on PRs and see the coverage badge in this README, add a repository secret named COVERALLS_REPO_TOKEN in GitHub (only required for private repositories). Steps:

1. Go to your repo Settings -> Secrets -> Actions -> New repository secret
2. Name it COVERALLS_REPO_TOKEN and paste the token from Coveralls
3. Push a commit or open a PR and the CI will upload coverage and post a link in the PR comments

If you want CI to fail when coverage drops below the configured threshold, we enforce this via vitest settings in vitest.config.ts which defines 80% thresholds for statements, branches, functions and lines.

A small TypeScript utility library for parsing Coin Magi (XMG) blocks and transactions.

Quick start

Install and build:

npm install
npm run build

Install from GitHub Packages (published as a scoped package):

npm install @rimblehelm/rim-xmg-lib

If you need to publish to npmjs.org instead of GitHub Packages, set an NPM_TOKEN secret and update the publish step in .github/workflows/publish.yml to use the npm registry URL (https://registry.npmjs.org/) and NODE_AUTH_TOKEN set to ${{ secrets.NPM_TOKEN }}. Local token validation scripts

To validate an NPM_TOKEN locally (recommended before pushing), use the included scripts (Bash and PowerShell):

• Linux/macOS / Git Bash / WSL:

export NPM_TOKEN=your-token-here
./scripts/test-npm-token.sh

• Windows PowerShell:

$env:NPM_TOKEN = 'your-token-here'
.\scripts\test-npm-token.ps1

These scripts perform two checks:

• npm whoami --registry https://registry.npmjs.org/ — ensures the token can authenticate.
• npm publish --dry-run --registry https://registry.npmjs.org/ — validates that the token can publish (dry-run).

Additionally, you can verify locally that the token is an Automation token by running:

npm token list --json --registry https://registry.npmjs.org/ | node -e "const fs=require('fs'); const s=fs.readFileSync(0,'utf8'); const tokens=(s?JSON.parse(s):[]); console.log(tokens.some(t=>t.type==='automation'))"

This prints true if the token is an Automation token (suitable for CI). If it prints false or fails, create an Automation token on npmjs.

If the account requires 2FA for publishing, the dry-run will show an EOTP error. In that case create a new npm Automation token via the npm website and place the token in the NPM_TOKEN secret in GitHub.

To publish from the Publish workflow to npmjs.org via manual dispatch, use the workflow_dispatch input use_npm=true and ensure your NPM_TOKEN secret is set. The workflow will fail early if NPM_TOKEN is missing. Example (from Actions UI):

• Open the Publish workflow in the Actions tab and click Run workflow
• Select use_npm: true then click Run workflow

This will switch the registry to https://registry.npmjs.org/ and use NPM_TOKEN to authenticate.

Publishing details & troubleshooting

• npm Automation token: If your npm account requires 2FA for publishing, you must create an "Automation" token on npmjs (Profile → Access Tokens → Create New Token → Automation) and add it as NPM_TOKEN in your repository secrets. Personal 2FA codes or interactive tokens will not work in CI and will cause an EOTP error.
• Quick GH CLI dispatch (npm):

gh workflow run "Publish" --ref master --repo rimblehelm/rim-xmg-lib --field use_npm=true

• How the workflow helps debug:

  • The Check NPM token (whoami) step authenticates to the configured registry and prints the npm username — this confirms your token is valid.
  • The new Debug npm config and whoami step prints the npm global registry and the resolved scoped registry for your package scope so you can confirm the publish target.
  • The Publish to npm registry (EOTP aware) step captures npm logs and prints a helpful remediation message if EOTP (2FA) or 401/Unauthorized errors occur.

  Trusted publishing (OIDC)

  This repo supports Trusted publishing (OIDC) for publishing to npmjs.org so you shouldn't need long-lived tokens in CI.

  Steps to use Trusted Publishing:

  • Create a Trusted Publisher for your package on npmjs.com and point it to your repo and the workflow filename publish.yml.
  • Ensure your Publish workflow includes the id-token: write permission (the workflow in this repo sets it by default).
  • When manually dispatching the Publish workflow, select use_npm: true and use_oidc: true — this will attempt to use OIDC to publish (no NPM_TOKEN required).

  How to add Trusted Publisher on npmjs.com (high level):

  1. Sign in to npmjs.com and go to your package page.
  2. Open Settings → Trusted Publisher (section).
  3. Choose GitHub Actions as the provider.
  4. Fill in Organization/User and Repository. For the workflow filename enter publish.yml (this must match exactly — case-sensitive).
  5. Save and try running the Publish job again with use_oidc: true.

  Troubleshooting: If the publish step fails with ENEEDAUTH or need auth, then the repository isn't set up as a trusted publisher or the workflow filename doesn't match. If you prefer not to use Trusted Publishing, set use_oidc: false and create an automation token on npm (or a proper granular token) and configure NPM_TOKEN in GitHub secrets.

  If OIDC-based trusted publishing isn't configured for your repo, the workflow will fall back to the token-based path if you supply an NPM_TOKEN. The workflow contains helpful diagnostics and instructions to create an Automation (or granular) token if necessary.

  New in CI: we also added a step that checks your NPM token's type and fails early if the token is not an "Automation" token. This reduces confusion caused by 2FA (EOTP) tokens which cannot be used in CI.

If you need help creating an npm Automation token I can add a short visual guide or a script to validate the token locally.

Re-run Publish from the CLI

After you set NPM_TOKEN to an Automation token, you can trigger the Publish workflow from the command line (GH CLI) as follows:

gh workflow run "Publish" --ref master --repo rimblehelm/rim-xmg-lib --field use_npm=true

You can also validate your token locally with the included npm script:

npm run test:npm-token

Generate API docs locally:

npm run docs
# docs will be generated to ./docs

The GitHub Actions workflow will also build and publish docs to GitHub Pages on push to main (or master) and on pull requests.

GitHub Pages badge

Add the following badge to the top of your README to point to published docs (replace USERNAME/REPO):

[![Docs](https://img.shields.io/website?down_color=red&down_message=offline&up_color=green&up_message=online&url=https://USERNAME.github.io/REPO/)](https://USERNAME.github.io/REPO/)

Example usage

Basic example in TypeScript:

import { XMGTransaction } from 'rim-xmg-lib';
import { XMGWallet } from 'rim-xmg-lib';

const txJson = `{"txid":"abc123","version":1,"time":1600000000,"locktime":0,"vin":[],"vout":[]}`;
const tx = XMGTransaction.fromJSON(txJson);
console.log(tx.ID); // 'abc123'

const wallet = new XMGWallet({ address: 'Xx...', createdAt: new Date(), transactions: [] });
console.log(wallet.balance); // 0 (no transactions)

Default-import example (backwards compatible):

import rim from 'rim-xmg-lib';

const txJson = `{"txid":"def456","version":1,"time":1600000000,"locktime":0,"vin":[],"vout":[]}`;
const tx = rim.XMGTransaction.fromJSON(txJson);
console.log(tx.ID);

Examples

Examples are located under examples/. TypeDoc is configured to include the examples entry point so they will be rendered in the generated docs. See examples/transaction-example.ts for a small demo script.

Contributing

• Run npm run lint and npm run typecheck before committing.
• Docs are automatically generated by GitHub Actions and published to the gh-pages branch.

Labels & Release Categories

Pull requests will be auto-labeled by file changes (using actions/labeler). The following labels are recognized and will be used to add items to releases via Release Drafter:

- `feature`, `enhancement`, `feat` — Features and new functionality
- `bug`, `fix` — Bug fixes
- `docs` — Documentation changes
- `chore` — Maintenance tasks
- `tests` — Tests or CI-related changes
- `ci`, `build` — Build system / CI changes
- `refactor` — Code refactors (no functionality change)
- `security` — Security fixes
- `dependencies` — Dependency upgrades (lockfile, package.json)
- `example` — Example code and demos

If your PR touches src/ files it will be labeled feature by default; if it touches tests/, docs/ or examples/ it will be labeled accordingly. You can also apply labels manually when opening a PR to be more specific (for example bug or breaking), and those will take precedence in Release Drafter's release notes.

Release & Changelog

We use release-drafter to create draft releases and auto-changelog to maintain CHANGELOG.md on releases/tags. When you merge a PR into main, release-drafter will update the draft; when a release is published (or a tag v* is pushed), a workflow will publish the package and auto-generate CHANGELOG.md and commit it back.

If you'd like me to add a GitHub Pages badge to the README or to generate a docs index with some examples, I can do that next.