Guides
Learn More about Newline

SDK Quickstart Guide

This guide shows how to install the Newline TypeScript SDK, configure authentication, and make a first successful API call. It is intended for developers getting started with the SDK for the first time.

Prerequisites

Before you begin, ensure you have:

  • A Newline program with API access enabled
  • A Program UID and HMAC key
  • A supported JavaScript runtime (see RUNTIMES.md in the SDK repository)
  • Node.js or another modern JavaScript runtime that supports ES Modules (ESM)

Install the SDK

The Newline TypeScript SDK is published to the npm registry.
Choose one of the package managers below and run the corresponding command from the root of your project (the directory containing your package.json file).

You only need to use one of these commands.

Using npm

If your project uses npm, run:

npm add @newline53/newline-ts-sdk

Using pnpm

If your project uses pnpm, run

pnpm add @newline53/newline-ts-sdk

Using Bun bun

If your project uses Bun, run:

bun add @newline53/newline-ts-sdk

Using Yarn yarn

If your project uses Yarn, run:

yarn add @newline53/newline-ts-sdk
📘

Note: The SDK is published as ES Module (ESM) only.
If your application uses CommonJS, you must import the SDK using await import().

After installation, the SDK will be added to your project’s dependencies and can be imported into your application code.

Set Environment Variables

The Newline SDK authenticates using program‑level credentials.
Store your Program UID and HMAC key as environment variables so they are not hard‑coded into your application.

You can obtain these credentials from the Newline dashboard or provisioning process.

macOS / Linux (bash, zsh)

export NEWLINE_PROGRAM_UID="your_program_uid"
export NEWLINE_HMAC_KEY="your_hmac_key"

Store your credentials securely using environment variables.

export NEWLINE_PROGRAM_UID="your_program_uid"
export NEWLINE_HMAC_KEY="your_hmac_key"

For Windows (PowerShell):

setx NEWLINE_PROGRAM_UID "your_program_uid"
setx NEWLINE_HMAC_KEY "your_hmac_key"

After setting the variables, restart your terminal or development environment to ensure they are available to your application.

Initialize the SDK

Create an SDK client instance to begin making requests to the Newline API.
The client is responsible for managing authentication, request configuration, and communication with the selected Newline environment.

Initialization requires:

  • Selecting the target environment
  • Providing program‑level credentials for authentication
import { NewlineSDK } from "newline-ts-sdk";

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

Create an SDK client instance and select the appropriate environment.

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

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

The SDK reads credentials from environment variables so sensitive values are not embedded directly in application code. The same client instance can be reused for all API calls within your application. Server Options Use the server option to control which Newline environment the SDK communicates with:

  • sandbox: Non‑production environment for development and testing
  • prod: Production environment for live transactions

Always start in the sandbox environment during development. Switch to prod only after your integration has been validated and approved for production use. Environment selection affects:

  • API endpoints
  • Transaction behavior
  • Available test data vs. live data

Make Your First API Call

After initializing the SDK, make a simple API call to verify that authentication, environment selection, and network access are all configured correctly.

The recommended first call is token generation, because it:

  • Requires valid program‑level credentials
  • Does not create or modify any data
  • Confirms that request signing and authentication are working as expected
import { NewlineSDK } from "newline-ts-sdk";

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

async function run() {
  const result = await newlineSDK.auth.generateToken();
  console.log(result);
}

run();

What This Call Does

The auth.generateToken() method requests a short‑lived authentication token from the Newline API using your program credentials. This token is used internally by the platform to authorize subsequent requests. This call does not initiate transactions, move funds, or persist data.

Expected Result

If the SDK is configured correctly, the response will include:

  • An authentication token
  • Token expiration metadata
  • Related authorization details

Logging the result confirms:

  • Environment variables are being read correctly
  • Credentials are valid
  • The SDK can successfully communicate with the selected Newline environment

If the Call Fails

Common failure scenarios include:

  • Invalid or missing environment variables
  • Incorrect program credentials
  • Using the wrong environment (sandbox vs prod)
  • Network connectivity issues

Errors returned by the SDK include structured information such as HTTP status codes and error messages, which can be used for troubleshooting. Once this call succeeds, the SDK is ready to be used for additional operations such as listing transactions, initiating transfers, or retrieving account data.

Common Issues

  • Missing credentials: Ensure NEWLINE_PROGRAM_UID and NEWLINE_HMAC_KEY are set.
  • ESM errors: Confirm your runtime supports ES Modules or use dynamic imports.
  • 403 or 401 responses: Verify your program is enabled for API access.

Next Step

You have now installed the SDK and confirmed that it can successfully authenticate and communicate with the Newline platform.

Next, review Authentication & Environment Setup for a deeper explanation of:

  • Program‑level credentials and request authentication
  • Environment separation between sandbox and production
  • Best practices for managing credentials and configuration across deployments

This will ensure your application is securely and correctly configured before building additional functionality with the SDK.

Updated 8 days ago