Installing the SDK

Install and set up the Portal SDK in your project.

Installation

JavaScript

Using npm

npm install portal-sdk

Using yarn

yarn add portal-sdk

Using pnpm

pnpm add portal-sdk

Requirements

Node.js: 18.x or higher
TypeScript (optional): 4.5 or higher
Portal endpoint and auth token: From a hosted Portal or from running Portal yourself (e.g. Docker)

Verify Installation

Create a test file to verify the installation:

import { PortalSDK } from 'portal-sdk';

console.log('Portal SDK imported successfully!');

Run it:

node test.js

Java

Using Gradle

Add the Jitpack repository to your build.gradle:

repositories {
    maven { url 'https://jitpack.io' }
}

Add the dependency:

dependencies {
    implementation 'com.github.PortalTechnologiesInc:java-sdk:0.1.0'
}

Using Maven

Add the repository to your pom.xml:

<repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
</repository>

Add the dependency:

<dependency>
    <groupId>com.github.PortalTechnologiesInc</groupId>
    <artifactId>java-sdk</artifactId>
    <version>0.1.0</version>
</dependency>

Requirements

Java: 17 or higher
Portal endpoint and auth token: From a hosted Portal or from running Portal yourself (e.g. Docker)

Import and setup

JavaScript

TypeScript Support

The SDK includes full TypeScript definitions. No additional @types packages are needed.

tsconfig.json Setup

Recommended TypeScript configuration:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "resolveJsonModule": true
  }
}

Import Options

ES Modules

import { PortalSDK, Currency, Timestamp } from 'portal-sdk';

CommonJS

const { PortalSDK, Currency, Timestamp } = require('portal-sdk');

Import Individual Types

import { 
  PortalSDK, 
  Currency, 
  Timestamp,
  Profile,
  AuthResponseData,
  InvoiceStatus,
  RecurringPaymentRequestContent,
  SinglePaymentRequestContent
} from 'portal-sdk';

Java

Create a PortalSDK with your health and WebSocket endpoints, then connect with your auth token:

var portalSDK = new PortalSDK(healthEndpoint, wsEndpoint);
portalSDK.connect(authToken);

Use sendCommand(request, callback) to send commands; request and response types are in the SDK package.

Browser Support

JavaScript

The SDK works in both Node.js and browser environments.

Browser Setup

<!DOCTYPE html>
<html>
<head>
  <title>Portal SDK Example</title>
</head>
<body>
  <script type="module">
    import { PortalSDK } from './node_modules/portal-sdk/dist/index.js';
    
    const client = new PortalSDK({
      serverUrl: 'ws://localhost:3000/ws'
    });
    
    // Your code here
  </script>
</body>
</html>

Webpack Configuration

If using Webpack, you may need to configure WebSocket:

// webpack.config.js
module.exports = {
  resolve: {
    fallback: {
      "ws": false
    }
  }
};

Browser Bundlers

The SDK uses isomorphic-ws which automatically handles WebSocket in both Node.js and browser environments. Most modern bundlers (Vite, Rollup, esbuild) will handle this automatically.

Java

The Java SDK targets the JVM (Java 17+). For Kotlin examples, see portal-demo.

Framework Integration

JavaScript

React

import React, { useEffect, useState } from 'react';
import { PortalSDK } from 'portal-sdk';

function App() {
  const [client, setClient] = useState<PortalSDK | null>(null);

  useEffect(() => {
    const portalClient = new PortalSDK({
      serverUrl: 'ws://localhost:3000/ws'
    });

    portalClient.connect().then(() => {
      portalClient.authenticate('your-auth-token').then(() => {
        setClient(portalClient);
      });
    });

    return () => {
      portalClient.disconnect();
    };
  }, []);

  return (
    <div>
      {client ? 'Connected to Portal' : 'Connecting...'}
    </div>
  );
}

Next.js

// lib/portal.ts
import { PortalSDK } from 'portal-sdk';

let client: PortalSDK | null = null;

export function getPortalClient() {
  if (!client) {
    client = new PortalSDK({
      serverUrl: process.env.NEXT_PUBLIC_PORTAL_WS_URL || 'ws://localhost:3000/ws'
    });
  }
  return client;
}

Use in API route:

// pages/api/auth.ts
import { getPortalClient } from '@/lib/portal';

export default async function handler(req, res) {
  const client = getPortalClient();
  await client.connect();
  await client.authenticate(process.env.PORTAL_AUTH_TOKEN);
  
  // Use client...
  
  res.status(200).json({ success: true });
}

Vue.js

// plugins/portal.ts
import { PortalSDK } from 'portal-sdk';

export default defineNuxtPlugin(() => {
  const client = new PortalSDK({
    serverUrl: 'ws://localhost:3000/ws'
  });

  return {
    provide: {
      portal: client
    }
  };
});

Express.js

import express from 'express';
import { PortalSDK } from 'portal-sdk';

const app = express();

// Initialize Portal client
const portalClient = new PortalSDK({
  serverUrl: 'ws://localhost:3000/ws'
});

// Connect on server start
portalClient.connect().then(() => {
  return portalClient.authenticate(process.env.PORTAL_AUTH_TOKEN);
}).then(() => {
  console.log('Portal SDK connected');
});

// Use in routes
app.post('/api/authenticate', async (req, res) => {
  const url = await portalClient.newKeyHandshakeUrl((mainKey) => {
    console.log('User authenticated:', mainKey);
    // Create user session...
  });
  
  res.json({ authUrl: url });
});

app.listen(3001, () => {
  console.log('Server running on port 3001');
});

Java

Wire PortalSDK as a bean (e.g. in Spring) and pass health URL, WebSocket URL, and auth token from configuration or environment variables.

Environment Variables

JavaScript

Store your Portal configuration in environment variables:

# .env
PORTAL_WS_URL=ws://localhost:3000/ws
PORTAL_AUTH_TOKEN=your-secret-auth-token

Access in your code:

import { PortalSDK } from 'portal-sdk';

const client = new PortalSDK({
  serverUrl: process.env.PORTAL_WS_URL || 'ws://localhost:3000/ws'
});

await client.connect();
await client.authenticate(process.env.PORTAL_AUTH_TOKEN || '');

Java

Read health URL, WebSocket URL, and auth token from environment or config and pass them to PortalSDK and connect().

Package Information

Exports

The package exports the following:

PortalSDK - Main client class
Currency - Currency enum
Timestamp - Timestamp utility class
All type definitions (TypeScript)

Bundle Size

Minified: ~50KB
Minified + Gzipped: ~15KB

Dependencies

The SDK has minimal dependencies:

ws - WebSocket client for Node.js
isomorphic-ws - Universal WebSocket wrapper

Troubleshooting

JavaScript

“Cannot find module ‘portal-sdk’”

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

TypeScript / module errors

# Ensure TypeScript is installed
npm install --save-dev typescript

# Check your tsconfig.json includes the right settings

Connection Issues

# Verify Portal is running (if self-hosting)
curl http://localhost:3000/health

# Check endpoint URL (ws:// for local, wss:// for hosted)

Module Resolution Errors

If using ES modules, ensure your package.json has:

{
  "type": "module"
}

Or use .mjs file extension:

mv app.js app.mjs

Java

Ensure Jitpack is in repositories and the dependency version is correct.
Verify health and WebSocket URLs and auth token; use curl on the health endpoint.
For issues, see the Java SDK repository.

Next Steps

Basic Usage - Learn how to use the SDK
Configuration - Configure the SDK
Authentication Guide - Implement authentication

Ready to start coding? Head to Basic Usage

Keyboard shortcuts

Portal SDK Documentation