@kowalski21/isp-sdk

A comprehensive TypeScript SDK for the ISP Management System API. Provides type-safe client-side access to customer management, subscriptions, billing, support tickets, and notifications.

Installation

npm install @kowalski21/isp-sdk

Requirements: Node.js 18+

Quick Start

import { IspSdk } from "@kowalski21/isp-sdk";

const sdk = new IspSdk({
  baseUrl: "https://api.example.com",
  auth: { jwtTokenStorageMethod: "local" },
});

// Authenticate
await sdk.auth.login({ email: "user@example.com", password: "password" });

// Access customer portal
const { customer } = await sdk.customerPortal.getProfile();

// Admin operations
const { users } = await sdk.admin.users.list();

Configuration

const sdk = new IspSdk({
  baseUrl: "https://api.example.com",
  auth: {
    jwtTokenStorageMethod: "local", // "local" | "session" | "memory" | "custom" | "nostore"
    customStorage: myCustomStorage, // Required when using "custom"
  },
  debug: false,
  globalHeaders: { "X-App-Version": "1.0.0" },
  customFetch: fetch, // Optional custom fetch implementation
});

Storage Options

Method	Use Case
local	Browser - persists across sessions
session	Browser - cleared when tab closes
memory	Node.js/SSR - in-memory storage
custom	React Native - use AsyncStorage or similar
nostore	Manual token management

Modules

Authentication

// Register
await sdk.auth.register({ email, password, firstName, lastName });

// Login
await sdk.auth.login({ email, password });

// Token management
const token = await sdk.getToken();
await sdk.setToken(token);
await sdk.clearToken();
await sdk.auth.logout();

// Password reset
await sdk.auth.forgotPassword({ email });
await sdk.auth.resetPassword({ token, newPassword });

Customer Portal

// Profile
const { customer } = await sdk.customerPortal.getProfile();
await sdk.customerPortal.updateProfile({ firstName, lastName });

// Subscriptions
const { subscriptions } = await sdk.customerPortal.getSubscriptions();
const { subscription } = await sdk.customerPortal.getSubscription(id);

// Orders
await sdk.customerPortal.createOrder({ packageId, paymentMethod });

// Support tickets
await sdk.customerPortal.createTicket({ subject, message, categoryId });
const { tickets } = await sdk.customerPortal.getTickets();

Admin

The admin namespace provides comprehensive management capabilities:

// Users & Access Control
sdk.admin.users         // User CRUD, role assignment
sdk.admin.roles         // Role management
sdk.admin.permissions   // Permission definitions
sdk.admin.policies      // Policy management

// Business Operations
sdk.admin.customers     // Customer profiles, locations, routers
sdk.admin.packages      // ISP packages/plans
sdk.admin.subscribers   // Subscriber verification
sdk.admin.subscriptions // Subscription lifecycle, queue management
sdk.admin.payments      // Payment management
sdk.admin.storeCredits  // Credit accounts and transactions

// Support
sdk.admin.tickets       // Tickets, teams, categories, priorities

// Analytics
sdk.admin.dashboard     // Stats, usage, registrations, package sales

Notifications

// List events
const { events } = await sdk.notifications.listEvents();

// Manage templates
const { templates } = await sdk.notifications.listTemplates();
await sdk.notifications.createTemplate({
  eventId,
  channel: "sms", // "sms" | "email" | "whatsapp" | "telegram"
  content,
});

Utility

Preview operations (dry-run) for subscription changes:

// Preview topup
const preview = await sdk.utility.previewTopup({ subscriptionId, amount });

// Preview package change
const preview = await sdk.utility.previewPackageChange({ subscriptionId, newPackageId });

// Preview renewal
const preview = await sdk.utility.previewRenewal({ subscriptionId });

Error Handling

import { IspSdkError, TokenRefreshError, ConfigurationError } from "@kowalski21/isp-sdk";

try {
  await sdk.auth.login({ email, password });
} catch (error) {
  if (error instanceof IspSdkError) {
    if (error.isUnauthorized()) {
      // Handle 401
    } else if (error.isForbidden()) {
      // Handle 403
    } else if (error.isNotFound()) {
      // Handle 404
    } else if (error.isValidationError()) {
      // Handle 400
    } else if (error.isRateLimited()) {
      // Handle 429
    } else if (error.isServerError()) {
      // Handle 5xx
    }
  }
}

Features

• Type-Safe - Full TypeScript support with strict mode
• Automatic Token Refresh - Handles 401s with request deduplication
• Flexible Storage - Multiple storage adapters for different environments
• FormData Support - File uploads with automatic Content-Type handling
• Custom Fetch - Support for custom fetch implementations

Documentation

Detailed documentation for each module is available in the sdk-docs/ directory:

• Authentication
• Customer Portal
• Orders
• Notifications
• Utility
• Admin Modules

License

MIT