@highnoteplatform/highnote-nodejs-sdk

@highnoteplatform/highnote-nodejs-sdk

TypeScript server SDK for the Highnote GraphQL API. Resource-oriented — no GraphQL knowledge required.

Status: Alpha — available via GitHub Packages for internal testing.

Installation

# Configure GitHub Packages registry (one-time setup — see .npmrc.template)
npm install @highnoteplatform/highnote-nodejs-sdk

Quick Start

import {
  Highnote,
  PaymentCardClientTokenPermission,
  PhoneLabel,
} from "@highnoteplatform/highnote-nodejs-sdk";

const client = new Highnote({
  apiKey: "sk_test_...",
  environment: "test", // "test" | "live"
});

// Create an account holder
const holder = await client.accountHolders.createUSPerson({
  personAccountHolder: {
    name: { givenName: "Jane", familyName: "Doe" },
    dateOfBirth: "1990-01-15",
    email: "[e-mail]",
    billingAddress: {
      streetAddress: "123 Main St",
      locality: "San Francisco",
      region: "CA",
      postalCode: "94105",
      countryCodeAlpha3: "USA",
    },
    phoneNumber: {
      countryCode: "1",
      number: "5551234567",
      label: PhoneLabel.MOBILE,
    },
  },
});

// Issue a card
const card = await client.cards.issue({
  financialAccountId: "fa_...",
  options: { activateOnCreate: true, expirationDate: "2028-12-31T00:00:00Z" },
});

// Generate a client token for the frontend card viewer
const token = await client.clientTokens.createForPaymentCard({
  paymentCardId: card.id,
  permissions: [PaymentCardClientTokenPermission.READ_RESTRICTED_DETAILS],
});

// List card products (auto-paginated)
for await (const product of client.cardProducts.list()) {
  console.log(product.name);
}

Resources

Resource	Methods	Status
cardProducts	list(), get(id)	Available
cards	issue(), activate(), suspend(), close(), reissue(), orderPhysical(), cancelPhysicalOrder(), findATMLocations(), get(id)	Available
accountHolders	createUSPerson(), get(id), listPersons(), listBusinesses(), searchPersons(), searchBusinesses()	Available
applications	create(), get(id)	Available
clientTokens	createForPaymentCard(), createForTokenization()	Available
financialAccounts	issue(), get(id), suspend(), unsuspend()	Available
transactions	list() with pagination and filtering	Available
transfers	initiateBetweenAccounts()	Available
spendRules	createMerchantCategory(), createAmountLimit(), attachToCard(), detachFromCard()	Available
webhooks	add(), deactivate()	Available
documents	startSession(), createUploadLink(), endSession()	Available
digitalWallets	addToApplePay(), addToGooglePay()	Available
collaborativeAuth	addEndpoint(), deactivateEndpoint()	Available
disputes	initiate(), get(id)	Available
externalAccounts	addVerifiedThroughPlaid(), addVerifiedThroughFinicity(), addNonVerified()	Available
ach	initiateTransfer(), createOneTimeTransfer(), createRecurringTransfer(), cancelTransfer()	Available

Configuration

Option	Type	Default	Description
apiKey	string	required	Highnote API key (sk_test_... or sk_live_...)
environment	"test" | "live"	"test"	API environment
baseUrl	string	—	Override API URL (for proxies/mocking)
defaultPageSize	number	20	Items per page for paginated queries

Exported Enums

The SDK exports enums for properly typing inputs — no as any needed:

Enum	Used For
PhoneLabel	Account holder phone numbers (MOBILE, HOME, WORK, SUPPORT)
PaymentCardClientTokenPermission	Client token permissions (READ_RESTRICTED_DETAILS, SET_PAYMENT_CARD_PIN, etc.)
GeneratePaymentMethodTokenizationClientTokenPermission	Tokenization permissions
PaymentCardStatus	Card status (ACTIVE, SUSPENDED, CLOSED, ACTIVATION_REQUIRED)
PaymentCardOrderStatus	Physical card order status (NEW, APPROVED, SHIPPED, CANCELED, etc.)
CardFormFactor	Card form factor (PHYSICAL, VIRTUAL)
FinancialAccountStatus	Account status (ACTIVE, SUSPENDED, CLOSED, PENDING_CLOSURE)
FinancialAccountSuspensionReasonInput	Suspension reason (ACCOUNT_HOLDER_REQUEST, SUSPECTED_FRAUD, etc.)
AccountHolderApplicationStatusCode	Application status (APPROVED, DENIED, IN_REVIEW, PENDING, CLOSED)
PaymentTransactionStatus	Transaction status (AUTHORIZED, CAPTURED, etc.)
TransferPurpose	Transfer purpose (GENERAL, LOAN_ADVANCE, REFUND_OR_REVERSAL, etc.)
InterFinancialAccountTransferStatus	Transfer status
NotificationEventName	Webhook event subscriptions (50+ events)
NotificationTargetStatus	Webhook target status (ACTIVE, PENDING_VERIFICATION, DEACTIVATED)
DocumentType	Document upload type (DRIVERS_LICENSE, BANK_STATEMENT, etc.)
DocumentUploadSessionStatusCode	Upload session status (CREATED, INITIATED, SUBMITTED, etc.)
PaymentCardDigitalWalletDeviceType	Device type for wallet provisioning (MOBILE, TABLET, WATCH)
CollaborativeAuthorizationEndpointStatus	Auth endpoint status (ACTIVE, PENDING_VERIFICATION, DEACTIVATED)
PaymentCardDisputeStatus	Dispute status (INITIATED, IN_PROGRESS, WON, LOST, etc.)
PaymentCardDisputeCategoryType	Dispute category (FRAUD, CUSTOMER_DISPUTE, AUTHORIZATION, PROCESSING_ERROR)
PaymentCardDisputeCustomerClaimType	Customer claim type (VERBAL, WRITTEN)
PaymentCardChargebackStatus	Chargeback status (SUBMITTED, RECEIVED, WON, LOST, etc.)
BankAccountType	External bank account type (CHECKING, SAVINGS)
AchTransferPurpose	ACH transfer purpose (DEPOSIT, WITHDRAWAL, PAYROLL, etc.)

Error Handling

The SDK throws typed exceptions when the API returns error union members:

import {
  HighnoteUserError,
  HighnoteAccessDeniedError,
} from "@highnoteplatform/highnote-nodejs-sdk";

try {
  await client.cardProducts.get("invalid_id");
} catch (err) {
  if (err instanceof HighnoteUserError) {
    // fieldErrors: Array<{ code?: string, description?: string }>
    console.error("Validation errors:", err.fieldErrors);
  } else if (err instanceof HighnoteAccessDeniedError) {
    console.error("Permission denied:", err.message);
  }
}

Pagination

All .list() methods return async iterables with lazy page fetching:

// Iterate all items (fetches pages on demand)
for await (const product of client.cardProducts.list()) {
  console.log(product.name);
}

// Custom page size
for await (const product of client.cardProducts.list({ pageSize: 10 })) {
  // ...
}

// Break early — no extra pages fetched
for await (const product of client.cardProducts.list()) {
  if (product.name === "Target") break;
}

Development

npm install                # Install dependencies
cp .env.template .env      # Fill in HIGHNOTE_API_KEY
npm run codegen            # Generate types from Highnote schema
npm run typecheck          # Type-check without emitting
npm run build              # Build CJS + ESM + .d.ts via tsup
npm run test:unit          # Run unit tests (no network needed)
npm run test:integration   # Run integration tests (requires API key in .env)
npm run lint               # Lint with eslint
npm run format             # Format with prettier

CI/CD

• Pull requests and pushes to main — GitHub Actions runs unit tests (Node 18/20/22), typecheck, and build.
• Publishing — a v* tag triggers the publish workflow (dormant until NPM_TOKEN secret is configured).

Contributing

See CONTRIBUTING.md for setup, development workflow, and how to add new resources.

Architecture

See .claude/PLAN.md for the full architecture spec, technical decisions, and implementation roadmap.

License

MIT