@use-handled/ipaas-react-sdk

Embedded iPaaS SDK for React. Let your users connect their e-commerce platforms (Shopify, Amazon, WooCommerce, etc.) directly from your application.

Installation

npm install @use-handled/ipaas-react-sdk
# or
yarn add @use-handled/ipaas-react-sdk
# or
pnpm add @use-handled/ipaas-react-sdk

Quick Start

1. Wrap your app with the provider

import { HandledProvider } from '@use-handled/ipaas-react-sdk'

function App() {
  // Your app knows which brand/merchant is logged in
  const currentBrand = getCurrentBrand() // { handledAccountId: "123" }

  return (
    <HandledProvider
      clientId="your-client-id"           // Your iPaaS client ID
      accountId={currentBrand.handledAccountId}  // Brand's Handled account ID
    >
      <YourApp />
    </HandledProvider>
  )
}

2. Use the pre-built IntegrationHub

import { IntegrationHub } from '@use-handled/ipaas-react-sdk'

function SettingsPage() {
  return (
    <IntegrationHub
      title="Connect Your Stores"
      description="Link your e-commerce platforms to sync orders and inventory."
      onConnect={(connection) => {
        console.log('Connected:', connection.integration.name)
      }}
      onDisconnect={(connectionId) => {
        console.log('Disconnected:', connectionId)
      }}
    />
  )
}

3. Or build a custom UI

import { useHandled } from '@use-handled/ipaas-react-sdk'

function CustomIntegrations() {
  const { integrations, connections, connect, disconnect, isLoading } = useHandled()

  return (
    <div>
      <h2>Available Integrations</h2>
      <div className="grid">
        {integrations.map((integration) => {
          const isConnected = connections.some(c => c.integrationId === integration.id)

          return (
            <div key={integration.id} className="card">
              <img src={integration.logoUrl} alt={integration.name} />
              <h3>{integration.name}</h3>

              {isConnected ? (
                <button onClick={() => {
                  const conn = connections.find(c => c.integrationId === integration.id)
                  if (conn) disconnect(conn.id)
                }}>
                  Disconnect
                </button>
              ) : (
                <button onClick={() => connect(integration.id)}>
                  Connect
                </button>
              )}
            </div>
          )
        })}
      </div>
    </div>
  )
}

API Reference

HandledProvider

The provider component that initializes the SDK.

<HandledProvider
  clientId="your-client-id"        // Required: Your iPaaS client ID
  accountId="brand-account-id"      // Required: Brand's Handled account ID
  apiBaseUrl="https://api.usehandled.io"  // Optional: Custom API URL
  onConnect={(connection) => {}}    // Optional: Called when integration connected
  onDisconnect={(connectionId) => {}} // Optional: Called when disconnected
  onError={(error) => {}}           // Optional: Called on errors
>
  {children}
</HandledProvider>

useHandled Hook

Access the SDK context from any component.

const {
  isReady,          // SDK is initialized
  isLoading,        // Operation in progress
  integrations,     // Available integrations (Shopify, Amazon, etc.)
  connections,      // Brand's connected integrations
  connect,          // Connect an integration (opens OAuth popup)
  disconnect,       // Disconnect an integration
  refreshConnections, // Refresh the connections list
  error,            // Any error that occurred
  accountId,        // Current account ID
} = useHandled()

IntegrationHub

Pre-built UI component for managing integrations.

<IntegrationHub
  title="Integrations"                    // Optional: Custom title
  description="Connect your platforms"    // Optional: Custom description
  categories={['ecommerce', 'marketplace']} // Optional: Filter by category
  integrationIds={[1, 2, 3]}             // Optional: Show specific integrations
  hideConnected={false}                   // Optional: Hide connected section
  onConnect={(connection) => {}}          // Optional: Connection callback
  onDisconnect={(connectionId) => {}}     // Optional: Disconnect callback
  onError={(error) => {}}                 // Optional: Error callback
  className="custom-class"                // Optional: CSS class
  style={{ maxWidth: '600px' }}          // Optional: Inline styles
/>

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                     Your Application                             │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  <HandledProvider clientId="xxx" accountId="brand_123">   │  │
│  │                                                            │  │
│  │    ┌─────────────────────────────────────────────────┐    │  │
│  │    │         IntegrationHub Component                 │    │  │
│  │    │  ┌─────────┐ ┌─────────┐ ┌─────────┐           │    │  │
│  │    │  │ Shopify │ │ Amazon  │ │   Woo   │           │    │  │
│  │    │  │ Connect │ │ Connect │ │ Connect │           │    │  │
│  │    │  └─────────┘ └─────────┘ └─────────┘           │    │  │
│  │    └─────────────────────────────────────────────────┘    │  │
│  │                                                            │  │
│  └───────────────────────────────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
                    ┌──────────────────────┐
                    │   Handled API        │
                    │ api.usehandled.io    │
                    └──────────┬───────────┘
                               │
          ┌────────────────────┼────────────────────┐
          ▼                    ▼                    ▼
    ┌──────────┐        ┌──────────┐        ┌──────────┐
    │ Shopify  │        │  Amazon  │        │   Woo    │
    └──────────┘        └──────────┘        └──────────┘

1. Developer signs up for Handled iPaaS and gets clientId
2. Developer creates child accounts for their brands/merchants
3. Developer embeds SDK with brand's accountId
4. Brand user clicks "Connect Shopify" → OAuth popup opens
5. Handled creates account_integration for that brand
6. Developer can now access brand's data via Handled's unified API

TypeScript

This package is fully typed. Import types as needed:

import type {
  Integration,
  Connection,
  ConnectResult,
  IntegrationHubProps,
} from '@use-handled/ipaas-react-sdk'

Integration Categories

| Category | Examples | |----------|----------| | ecommerce | Shopify, WooCommerce, BigCommerce, Magento | | marketplace | Amazon, eBay, Walmart, Etsy | | shipping | ShipStation, EasyPost, Shippo | | accounting | QuickBooks, Xero, NetSuite |

Publishing

To publish this package to npm:

# Set your npm auth token
npm config set //registry.npmjs.org/:_authToken YOUR_NPM_TOKEN

# Bump version and publish
npm version patch && npm publish --access public

Version bump options:

• npm version patch - 0.1.0 -> 0.1.1 (bug fixes)
• npm version minor - 0.1.0 -> 0.2.0 (new features)
• npm version major - 0.1.0 -> 1.0.0 (breaking changes)

License

MIT