Node.js SDK changelog

Synced from packages/easy-node/CHANGELOG.md on the latest publish. This is the canonical release history for @easylabs/node.

0.1.0

Minor Changes

0.1.0 — full SDK refresh aligning with the current Easy Labs API

This is the first published release that reflects the API as it stands at 2026-04-26. It is a coordinated bump across all four packages and contains a substantial number of breaking changes alongside a much larger additive surface. Pre-1.0 semver convention: minor bumps may carry breaking changes.

Publishing foundation
- @easylabs/common is now published as a standalone package. The other three packages depend on it directly instead of inlining its code at build time. A patch in common ripples to consumers via semver range rather than requiring three coordinated republishes.
- All four packages now ship dual ESM + CJS, declaration files, source maps, and a modern nested-conditions exports map. arethetypeswrong is clean across node10, node16-cjs, node16-esm, and bundler resolvers.
- MIT license, full repository / homepage / bugs metadata, sideEffects: false, engines.node: ">=22", and publishConfig.access: "public" are set on every package.
- @basis-theory/node-sdk has been removed from @easylabs/node — it was declared but never imported.
- @basis-theory/react-elements, @basis-theory/web-elements, and @basis-theory/react-native-elements are bumped to current minors; @easylabs/react-native's react-native peer is tightened to >=0.79.0 to match the card-vault SDK's floor.
Breaking API alignment

Subscriptions

The legacy Finix-shaped subscription engine is replaced with the new Stripe-style engine.
- SubscriptionData is rewritten with items[], current_period_start/end, billing_cycle_anchor, cancel_at_period_end, pause_collection, latest_invoice_id, proration_behavior, credit_balance, pending_update. The old flat fields (subscription_plan_id, linked_to, buyer_details, subscription_phase, etc.) are gone.
- SubscriptionStatus replaces SubscriptionState (lowercase Stripe-style: incomplete | incomplete_expired | trialing | active | past_due | unpaid | canceled | paused).
- createSubscription(data) — body shape is now { identity_id, items: [{ price_id, quantity? }], instrument_id?, proration_behavior?, billing_cycle_anchor?, trial_period_days?, trial_end?, description?, metadata? }.
- cancelSubscription(id, options?) — now DELETE /subscriptions/:id?at_period_end=..., defaulting to immediate cancel. Pass { at_period_end: true } to schedule for the period boundary.
- getCustomerSubscriptions(id, params?) — returns the new paginated wrapper Paginated<SubscriptionData> ({ data, total, limit, offset }) and accepts an optional status filter.
- The four legacy subscription-plan methods (getSubscriptionPlans, getSubscriptionPlan, createSubscriptionPlan, updateSubscriptionPlan) are removed. SubscriptionPlanData is kept as a @deprecated read-back type only.
Orders
- updateOrderTags(orderId, tags) now hits PATCH /orders/:id (the old /orders/:id/tags route returns 404 on the new API).
- OrderData gains the documented tags: Record<string, unknown> field.
Product prices
- CreatePrice recurring branch now requires { currency, unit_amount, interval, interval_count } and accepts optional pricing_model, trial_period_days. The vestigial finix_subscription_plan_id is gone.
- PriceData replaces finix_subscription_plan_id with interval, interval_count, pricing_model, trial_period_days.
- New Interval and PricingModel enums.
Wallet checkout
- The wallet-checkout flow is not currently served by the Easy API. The three wallet-checkout methods (createCheckoutWithWallet, createWalletCheckout, createWalletCheckoutLegacy) are removed. The CreateWalletCheckout and WalletCheckoutResponseData types are kept in @easylabs/common as internal reference.
Sessions
- EasyApiClient.createBasisTheorySession(body) is narrowed to accept only { nonce: string }. The shared createBasisTheorySession utility forwards only { nonce } regardless of what callers pass, matching the API schema. The util's exposed parameter type is unchanged so EasyProvider callers compile without changes.
Disputes
- EasyApiClient.updateDisputeTags renamed to updateDispute. Wire shape unchanged.
Balance transfers
- Balance transfer operations are removed from the SDK surface. Migration: treasury operations are managed internally by Easy Labs.
Additive expansion

Subscription lifecycle

13 new methods on EasyApiClient covering pause/resume, item management, discounts, one-time charges, metered usage, and proration preview:
- updateSubscription, pauseSubscription, resumeSubscription, getSubscriptionProrationPreview
- addSubscriptionItem, updateSubscriptionItem, removeSubscriptionItem
- applySubscriptionDiscount, listSubscriptionDiscounts, removeSubscriptionDiscount
- createOneTimeCharge
- reportSubscriptionUsage, getSubscriptionUsageSummary, getSubscriptionUsageReconciliation
Refunds
- createRefund(transferId, { refund_amount, tags? }) → POST /transfer/:id/reversals.
Payment links
- CreatePaymentLinkPayload gains payment_limit and branding_overrides.
- PaymentLinkData gains payment_count, payment_limit, branding_overrides, and the documented state enum.
Embedded checkout
- validateEmbeddedCheckoutSession, confirmEmbeddedCheckoutSession, getEmbeddedCheckoutConfig, updateEmbeddedCheckoutConfig.
- validate and confirm authenticate via the session's client_secret rather than the API key — the SDK skips the x-easy-api-key header on those routes via a new internal skipAuth flag in makeRequest.
- CryptoPaymentInfo expanded with optional status and tx_signature.
Webhooks
- Six management methods: registerWebhookEndpoint, listWebhookEndpoints, updateWebhookEndpoint, deleteWebhookEndpoint, listWebhookDeliveries, listEndpointDeliveries.
- New verifier in @easylabs/node: EasyWebhooks.constructEvent(rawBody, signatureHeader, secret). Verifies HMAC-SHA256 via node:crypto.timingSafeEqual, parses the payload, and returns a typed WebhookEvent<TData>. Throws EasyApiError with a specific WEBHOOK_* code on signature problems.
- Full event-type catalog: EASY_EVENT_TYPES (40 values) + EasyEventType union.
New domains
- Invoices — full lifecycle (createInvoice, listInvoices, getInvoice, updateInvoice, sendInvoice, payInvoice, remindInvoice, voidInvoice, getInvoicePdfData).
- Coupons — CRUD (createCoupon, listCoupons, getCoupon, updateCoupon, deleteCoupon).
- Promotion codes — CRUD + validatePromotionCode.
- Authorizations — listAuthorizations, getAuthorization, captureAuthorization, voidAuthorization.
- Analytics — five aggregator getters (getTransactionAnalytics, getDisputeAnalytics, getSettlementAnalytics, getRevenueAnalytics, getRevenueRecoveryAnalytics).
- Compliance forms — listComplianceForms, getComplianceForm, signComplianceForm.
- Dunning / revenue-recovery config — createOrReplaceDunningConfig, getDunningConfig, updateDunningConfig.
- Revenue-recovery automations — list, create, update, delete, plus listRevenueRecoveryAutomationRuns.
Error surface
- New EasyApiError class (exported from @easylabs/common). All non-2xx responses throw an EasyApiError carrying status, code (from the API error envelope), message (preserves the legacy "API request failed: ..." prefix), details, retryAfterSeconds (parsed from the Retry-After header), and raw. Existing callers matching against the message keep working; new callers can instanceof branch and read typed fields.
Out of scope (intentionally deferred)
- Customer Portal end-user flows are cookie/JWT-session based and outside the SDK's API-key-only auth model.
- Tax — feature deferred at the product level.
- Treasury — most routes gate on JWT + 2FA; revisit post-1.0.
- Custom Domains — JWT-only, dashboard-only.

Patch Changes

Updated dependencies
- @easylabs/common@0.1.0

0.0.10

Patch Changes

7134a80: Update ProductData for new api contract returning price ids array

0.0.9

Patch Changes

Added comprehensive subscription management capabilities including subscription plans and customer subscriptions:

Subscription Plans:
- getSubscriptionPlans(params?) - List all subscription plans with optional filtering
- getSubscriptionPlan(planId) - Get a specific subscription plan
- createSubscriptionPlan(data) - Create a new subscription plan with:
  - Billing intervals (DAILY, WEEKLY, MONTHLY, QUARTERLY, YEARLY)
  - Trial periods with configurable duration
  - Discount phases for promotional pricing
  - Billing defaults (invoice/receipt settings)
- updateSubscriptionPlan(planId, data) - Update an existing plan
Customer Subscriptions:
- getSubscriptions(params?) - List all subscriptions (admin context)
- getCustomerSubscriptions(params?) - Get subscriptions for authenticated customer
- getSubscription(subscriptionId) - Get a specific subscription
- createSubscription(data) - Create a subscription with:
  - Buyer details (name, email, phone)
  - Subscription details (trial overrides, discount overrides)
  - Payment instrument configuration
- cancelSubscription(subscriptionId) - Cancel an active subscription
Integration:
- Recurring prices now automatically create subscriptions during checkout
- Mixed cart support (one-time purchases + subscriptions in single transaction)
- Subscription data included in order line items for tracking
All list/collection endpoints now support filtering by specific IDs using the ids query parameter:

Affected Methods:
- getCustomers({ ids: ['cus_123', 'cus_456'] })
- getProducts({ ids: ['prod_123', 'prod_456'] })
- getPrices({ ids: ['price_123', 'price_456'] })
- getOrders({ ids: ['ord_123', 'ord_456'] })
- getTransfers({ ids: ['tfr_123', 'tfr_456'] })
- getSettlements({ ids: ['set_123', 'set_456'] })
- getDisputes({ ids: ['dis_123', 'dis_456'] })
- getSubscriptions({ ids: ['sub_123', 'sub_456'] })
- getSubscriptionPlans({ ids: ['plan_123', 'plan_456'] })
This enables efficient batch fetching of specific resources without retrieving entire collections.

Updated Return Value: The checkout() and related checkout methods now return enhanced data:
```
{
  order: OrderData;              // The created order
  customer: CustomerData;         // Customer information
  subscriptions?: SubscriptionData[]; // Auto-created subscriptions (if cart contains recurring items)
}
```
Benefits:
- Immediate access to created subscription IDs
- No need for separate API calls to fetch subscription details
- Simplified post-checkout subscription management
- Better support for mixed carts (one-time + recurring)
- Added comprehensive subscription examples to Node.js and React SDK docs
- Updated DEVELOPER_DOCS.md for both packages
- Enhanced Docusaurus site with subscription management guides
- Added batch query parameter documentation across all endpoints
Checkout Return Value: The checkout methods now return an object with { order, customer, subscriptions? } instead of just the order. Update your code:
```
// Before
const order = await checkout(data);

// After
const { order, customer, subscriptions } = await checkout(data);
```
- Fixed price display for subscription products (now uses subscription_plan.amount)
- Improved type safety for discriminated union types (CreatePrice, CreateSubscription)
- Fixed controlled input warnings in form components

Patch Changes

- Add handlers for getting a customers payment instruments and orders
- Add handler for updating payment instrument
- Add handlers for getting order(s) and updating order tags
- Add handlers for getProductWithPrice(s). This is used for either getting all the prices for a product or a specifc one. Different from returning the default_price_id

0.0.8

Patch Changes

Create EasyApiClient class to handle all the interactions with easy-api, this reduced a lot of repetitive code that was happening between the node and react packages
Add product and price management APIs

Node.js SDK changelog

On this page