Using the SDK

This guide explains how to use the Newline TypeScript SDK in application code after completing setup and authentication. It focuses on common usage patterns, recommended workflows, and important considerations when interacting with Newline APIs through the SDK.

This guide assumes you have already:

• Installed the SDK
• Configured authentication and environment settings
• Successfully made an initial SDK call

Reusing the SDK Client

Create a single SDK client instance and reuse it throughout your application. The client manages authentication, configuration, and request handling internally.

import { NewlineSDK } from "newline-ts-sdk";

export const newlineSDK = new NewlineSDK({
  server: "sandbox",
  security: {
    programUid: process.env.NEWLINE_PROGRAM_UID ?? "",
    hmacKey: process.env.NEWLINE_HMAC_KEY ?? "",
  },
});

Reusing the same instance:

• Avoids repeated configuration
• Ensures consistent behavior
• Simplifies testing and dependency management

Making API Calls

All API interactions are performed through resource‑grouped methods on the SDK client.

Examples of common read operations:

const transactions = await newlineSDK.transactions.list();

const account = await newlineSDK.custodialAccounts.getById({
  custodialAccountUid: "account_uid",
});

Write operations follow the same pattern and map directly to API endpoints.

Working with Transactions

The SDK provides access to transaction data, events, and related records, but it does not alter transaction lifecycle behavior.

When working with transactions:

• Use SDK methods to retrieve transaction details and events
• Rely on reporting documentation to understand lifecycle timing
• Do not infer posting or reconciliation state from settlement alone

Example: retrieving a transaction and its events

const transaction = await newlineSDK.transactions.get({
  transactionUid: "transaction_uid",
});

const events = await newlineSDK.transactions.listEvents({
  transactionUid: "transaction_uid",
});

Initiating Transfers

Transfers are created using dedicated transfer methods. These calls initiate operational workflows and may result in lifecycle events over time.

await newlineSDK.transfers.initiate({
  amount: 1000,
  currency: "USD",
  sourceAccountUid: "source_uid",
  destinationAccountUid: "destination_uid",
});

Transfer results should be monitored through transaction records and reporting, not assumed to be final immediately after initiation.

Using Standalone Functions

In addition to the SDK client, all operations are available as standalone functions. These are useful for:

• Browser or serverless environments
• Bundle‑size‑sensitive applications
• Situations where only a small subset of functionality is needed

Standalone functions behave identically to client methods and follow the same authentication and error‑handling rules.

Refer to the standalone functions documentation for usage details.

Handling Errors

All SDK errors extend from a common NewlineError base class and preserve API error details.

Recommended practices:

• Catch errors explicitly
• Log status codes and messages
• Avoid retrying non‑idempotent operations

Example:

try {
  await newlineSDK.products.list();
} catch (error) {
  if (error instanceof NewlineError) {
    console.error(error.statusCode, error.message);
  }
}

Error behavior is identical whether using the SDK or direct API calls.

Retries and Idempotency

Some SDK operations support retries. Defaults are inherited from the API but can be overridden per call or globally.

Only retry:

• Read operations
• Idempotent writes where explicitly supported

Avoid retrying operations that could result in duplicate financial actions unless documented as safe.

Reporting and Reconciliation Considerations

While the SDK can retrieve reporting‑related data programmatically, it does not replace CSV‑based reporting.

Important guidelines:

• Use CSV reports for reconciliation and posting alignment
• Do not rely on SDK transaction data alone for bank statement matching
• Treat settlement, posting, and reconciliation as separate phases

Refer to reporting guides for authoritative reconciliation workflows.

Sandbox vs Production Usage

During development:

• Use the sandbox environment
• Leverage simulation and test data
• Validate all workflows before production use

In production:

• Switch to prod
• Use production credentials
• Implement logging and error handling appropriate for live systems

Best Practices

• Centralize SDK initialization
• Separate business logic from SDK calls
• Avoid hard‑coding credentials or environment values
• Read API and reporting documentation alongside SDK usage
• Pin SDK versions in production environments

Next Step

After becoming familiar with common SDK usage patterns, refer to the SDK Reference for complete method documentation and detailed parameter definitions.