payments-manager

TypeScript SDK for the Billing Rail integration API. Provides programmatic access to teams, members, licenses, credits, plans, and feature checks.

Installation

npm install payments-manager

Quick Start

import { payments_manager } from "payments-manager";

const pm = payments_manager({ api_key: "your_api_key" });

// Classic API — throws on error
const teams = await pm.getTeams();
const license = await pm.getLicense("license_id");
await pm.deductCredits("license_id", "emails", 10);

// FP API — returns Either<PaymentsManagerError, T>
import { isLeft } from "payments-manager";

const result = await pm.fp.getTeams();
if (isLeft(result)) {
    console.error(result.left.code, result.left.message);
} else {
    console.log(result.right); // Team[]
}

API Reference

Teams

| Method | Parameters | Returns | |--------|-----------|---------| | getTeams() | — | Team[] | | getTeamDetail(team_id) | team_id: string | { team: Team, members: TeamMember[] } | | getTeamMembers(team_id) | team_id: string | TeamMember[] |

Licenses

| Method | Parameters | Returns | |--------|-----------|---------| | getTeamLicenses(team_id) | team_id: string | License[] | | getLicense(license_id) | license_id: string | License | | getLicenseAssignments(license_id) | license_id: string | MemberLicense[] | | getUserLicenses(email) | email: string | MemberLicense[] | | getMemberLicenses(team_id, email) | team_id: string, email: string | MemberLicense[] |

Credits

| Method | Parameters | Returns | |--------|-----------|---------| | getLicenseCredits(license_id) | license_id: string | { creditsLeft: Credit[], planCredits: Credit[] } | | deductCredits(license_id, credit_id, amount) | license_id: string, credit_id: string, amount: number | { creditsLeft: Credit[] } |

Plans & Features

| Method | Parameters | Returns | |--------|-----------|---------| | getPlans() | — | Plan[] | | checkFeature(team_id, email, feature_id) | team_id: string, email: string, feature_id: string | { available: boolean } |

Two API Styles

Every method is available in two forms:

Classic API (default)

Methods are called directly on the payments_manager instance. They return the result value and throw PaymentsManagerException on errors.

import { payments_manager, PaymentsManagerException } from "payments-manager";

const pm = payments_manager({ api_key: "your_key" });

try {
    const teams = await pm.getTeams();
    const credits = await pm.getLicenseCredits("license_123");
    const result = await pm.deductCredits("license_123", "emails", 5);
    console.log("Remaining:", result.creditsLeft);
} catch (e) {
    if (e instanceof PaymentsManagerException) {
        console.error(e.code, e.message);
        // e.code: "insufficient_credits", "not_authorized", etc.
    }
}

FP API (via .fp)

All methods are accessible through the .fp property and return Promise<Either<PaymentsManagerError, T>> from fp-ts. No exceptions are thrown.

import { payments_manager, isLeft, isRight } from "payments-manager";

const pm = payments_manager({ api_key: "your_key" });

const result = await pm.fp.deductCredits("license_123", "emails", 5);
if (isLeft(result)) {
    // result.left: { code: string, message: string }
    console.error("Failed:", result.left.code);
} else {
    // result.right: { creditsLeft: Credit[] }
    console.log("Remaining:", result.right.creditsLeft);
}

Error Codes

| Code | Description | |------|-------------| | invalid_input | Missing or invalid parameters (e.g. amount <= 0) | | not_authorized | Resource does not belong to the API key's account | | no_record | Requested resource not found | | credit_not_found | The credit_id does not exist on the license | | insufficient_credits | Not enough credits to deduct the requested amount | | network_error | Failed to reach the server |

Types

All types are exported from the package:

import type {
    Team, TeamMember, MemberLicense, License, Plan,
    Credit, Feature, BillingInfo, MemberRole,
    ChargingType, PlanType, PlanGroup,
    TeamDetailResult, LicenseCreditsResult,
    DeductCreditsResult, CheckFeatureResult,
    PaymentsManagerError,
} from "payments-manager";

Key Types

type Credit = {
    id: string;        // e.g. "emails"
    name: string;      // e.g. "Emails"
    amount: number;    // remaining balance
    description?: string;
    rollover: boolean; // carries over to next billing cycle
};

type License = {
    _id: string;
    team_id: string;
    planId: string;
    planTitle: string;
    expiresOn: string;
    chargingType: "monthly" | "yearly" | "onetime";
    planType: "paid" | "trial" | "free";
    creditsLeft: Credit[];
    planCredits: Credit[];    // the plan's original credit amounts
    active: boolean;
    payment_status: "success" | "cancelled" | "failed";
};

type Plan = {
    _id: string;
    planId: string;
    title: string;
    credits: Credit[];
    planType: "paid" | "trial" | "free";
    chargingType: "monthly" | "yearly" | "onetime";
    group: { groupId: string; level: number };
    features?: Array<{ id: string; description?: string }>;
    available_for_purchase: boolean;
    purchase_behavior: "refill-only" | "refill-standalone" | "renew";
};

Authentication

All requests are authenticated using an API key passed via the x-api-key HTTP header. The API key is set once when creating the client and sent with every request automatically.

API keys are assigned per top-level customer and can be found in the Billing Rail admin panel.

Development

# Build the package
npm run build

# Output goes to dist/ with TypeScript declarations