@fund-my-cause/sdk — JavaScript / TypeScript SDK

A typed client for interacting with Fund-My-Cause Soroban contracts from any JavaScript environment (Node.js, browser, Next.js).

Installation

# From the monorepo root (local link)
npm install ./sdks/js

# Once published to npm
npm install @fund-my-cause/sdk

Requirements

Peer dependency	Version
`@stellar/stellar-sdk`	`^14.0.0`

Quick start

import { FmcClient } from "@fund-my-cause/sdk";

const client = new FmcClient({
  contractId:        "C...",
  rpcUrl:            "https://soroban-testnet.stellar.org",
  networkPassphrase: "Test SDF Network ; September 2015",
  horizonUrl:        "https://horizon-testnet.stellar.org",
});

// Read campaign stats (no wallet required)
const stats = await client.getStats();
console.log(`${stats.raisedXlm} / ${stats.goalXlm} XLM (${stats.progressPercent}%)`);

// Contribute (requires wallet signing function)
await client.contribute({
  contributor: "G...",
  amountXlm:  10,
  tokenId:    "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
  signTx,     // (xdr: string) => Promise<string>
});

API reference

Full generated reference: docs/api/sdk-js — every public class, method, interface, and type, with parameters, return values, and the contract errors each call can throw.

The tables below are a quick index; the generated reference is authoritative.

Regenerating the reference

The reference is generated by TypeDoc from the JSDoc in src/, and the output is committed to the repository — it is not built in CI. Regenerate it whenever you change a public signature or its JSDoc:

cd sdks/js
npm install     # first time only
npm run docs    # writes to ../../docs/api/sdk-js

Commit the resulting changes under docs/api/sdk-js/ alongside your source change, so the published reference never lags the code.

To validate the JSDoc without writing any files — useful before opening a PR:

npm run docs:check

Configuration lives in typedoc.json. It sets treatValidationWarningsAsErrors, so any public export missing a comment, @param, or @returns fails the run rather than silently producing an empty entry. If npm run docs exits non-zero, read the warning: it names the exact symbol to document.

Source links are pinned to Fund-My-Cause/Fund-My-Cause at main rather than inferred from your git remote. That keeps regenerated output identical on forks and stops every run from rewriting all files with a new commit SHA.

Constructor

new FmcClient(config: FmcClientConfig)

interface FmcClientConfig {
  contractId:        string;
  rpcUrl:            string;
  networkPassphrase: string;
  horizonUrl:        string;
}

Read methods (no auth)

Method	Returns	Description
`getStats()`	`CampaignStats`	Live funding metrics
`getCampaignInfo()`	`CampaignInfo`	Full metadata snapshot
`getPerformanceMetrics()`	`PerformanceMetrics`	Velocity and trend data
`getContribution(address)`	`number` (XLM)	Contribution for one address
`listContributors(opts)`	`string[]`	Paginated contributor addresses
`getMatchingConfig()`	`MatchingConfig \| null`	Active matching config
`getTotalMatched()`	`number` (XLM)	Total matched so far
`getMatchingPool()`	`number` (XLM)	Remaining unspent pool
`isContributor(address)`	`boolean`	Whether address has contributed
`getContributionHistory(address)`	`ContributionRecord[]`	Per-address history

Write methods (require `signTx`)

Method	Description
`contribute(opts)`	Pledge tokens
`withdraw(opts)`	Creator claims funds
`refundSingle(opts)`	Contributor claims refund
`setupMatching(opts)`	Sponsor sets up matching pool
`refundMatchingSponsor(opts)`	Refund unused matching pool
`cancelCampaign(opts)`	Creator cancels the campaign

Registry methods

import { FmcRegistryClient } from "@fund-my-cause/sdk";

const registry = new FmcRegistryClient({
  contractId: "C...", // registry contract id
  rpcUrl,
  networkPassphrase,
  horizonUrl,
});

const page = await registry.list({ offset: 0, limit: 20 });
const tech  = await registry.getByCampaignCategory({ categoryId: 1, offset: 0, limit: 10 });

Constants and helpers

STROOPS_PER_XLM and the conversion helpers are package-level exports:

import { STROOPS_PER_XLM, xlmToStroops, stroopsToXlm } from "@fund-my-cause/sdk";

There was previously a duplicate FmcClient.STROOPS_PER_XLM static, marked "Unused" in the source. It has been removed — it held the same value as the package-level export above, which is the one to use.

Error handling

import { FmcContractError } from "@fund-my-cause/sdk";

try {
  await client.contribute({ ... });
} catch (e) {
  if (e instanceof FmcContractError) {
    console.error(`Contract error ${e.code}: ${e.message}`);
  }
}

See ../../docs/api/errors.md for all error codes.

Building

cd sdks/js
npm install
npm run build   # outputs to dist/
npm test        # runs Jest tests

FilesExpand file tree

README.md

Latest commit

History