@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: "[email protected]",
    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