npm package: @highnoteplatform/highnote-nodejs-sdk
Description: Highnote Server SDK for Node.js — resource-oriented wrapper over the Highnote GraphQL API
Latest version: 0.1.0-alpha.5

# @highnoteplatform/highnote-nodejs-sdk

TypeScript server SDK for the [Highnote](https://highnote.com) GraphQL API. Resource-oriented — no GraphQL knowledge required.

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

## Installation

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

## Quick Start

```typescript
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: "jane@example.com",
    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:

```typescript
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:

```typescript
// 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

```bash
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](CONTRIBUTING.md) for setup, development workflow, and how to add new resources.

## Architecture

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

## License

MIT