@use-handled/ipaas-react-sdk 0.1.0

package/README.md

@@ -0,0 +1,218 @@
+# @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
+
+```bash
+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
+
+```tsx
+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
+
+```tsx
+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
+
+```tsx
+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.
+
+```tsx
+<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.
+
+```tsx
+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.
+
+```tsx
+<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:
+
+```tsx
+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 |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,284 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1 from 'react';
+
+interface HandledConfig {
+    /** Developer's iPaaS client ID from the Handled dashboard */
+    clientId: string;
+    /** The brand's account ID in Handled (child account) */
+    accountId: string;
+    /** Custom API base URL (defaults to https://api.usehandled.io) */
+    apiBaseUrl?: string;
+}
+interface IntegrationInputField {
+    label?: string;
+    type?: 'text' | 'password' | 'email' | 'select' | 'date';
+    required?: boolean;
+    placeholder?: string;
+    description?: string;
+    default?: string;
+    sort_order?: number;
+    options?: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+interface Integration {
+    id: number;
+    name: string;
+    displayName?: string;
+    type: string;
+    description?: string;
+    logoUrl?: string;
+    category: 'ecommerce' | 'marketplace' | 'shipping' | 'accounting' | 'other';
+    authType: 'oauth' | 'oauth2' | 'oauth1' | 'api_key' | 'basic_auth' | 'bearer_token' | 'credentials';
+    status: 'available' | 'coming_soon' | 'beta';
+    inputFields?: Record<string, IntegrationInputField>;
+}
+interface Connection {
+    id: number;
+    integrationId: number;
+    integration: Integration;
+    accountId: number;
+    storeName?: string;
+    storeUrl?: string;
+    status: 'active' | 'inactive' | 'error' | 'pending';
+    connectedAt: string;
+    lastSyncAt?: string;
+    error?: string;
+}
+interface ConnectOptions {
+    /** Integration ID or type to connect */
+    integrationId: number | string;
+    /** Custom redirect after OAuth (optional) */
+    redirectUrl?: string;
+    /** Credentials for non-OAuth integrations */
+    credentials?: Record<string, string>;
+    /** Name for the account integration */
+    accountIntegrationName?: string;
+}
+interface ConnectResult {
+    success: boolean;
+    connection?: Connection;
+    error?: string;
+}
+interface HandledContextValue {
+    /** Whether the SDK is initialized and ready */
+    isReady: boolean;
+    /** Whether operations are in progress */
+    isLoading: boolean;
+    /** Available integrations from Handled */
+    integrations: Integration[];
+    /** Brand's connected integrations */
+    connections: Connection[];
+    /** Connect a new integration (opens OAuth popup or submits credentials) */
+    connect: (integrationId: number | string, options?: {
+        credentials?: Record<string, string>;
+        accountIntegrationName?: string;
+    }) => Promise<ConnectResult>;
+    /** Disconnect an integration */
+    disconnect: (connectionId: number) => Promise<void>;
+    /** Refresh connections list */
+    refreshConnections: () => Promise<void>;
+    /** Any error that occurred */
+    error: Error | null;
+    /** The account ID being used */
+    accountId: string;
+}
+interface IntegrationsResponse {
+    integrations: Integration[];
+}
+interface ConnectionsResponse {
+    connections: Connection[];
+}
+interface ConnectResponse {
+    /** OAuth auth URL (only for OAuth integrations) */
+    authUrl?: string;
+    /** Redirect URL for OAuth (alias for authUrl) */
+    redirect_url?: string;
+    /** Connection ID for status checking */
+    connectionId?: number;
+    /** Whether the connection was successful (for non-OAuth) */
+    success?: boolean;
+    /** The created connection (for non-OAuth) */
+    connection?: Connection;
+    /** The created account integration */
+    account_integration?: Connection;
+    /** Error message if failed */
+    message?: string;
+}
+interface HandledEventMap {
+    'connection:created': Connection;
+    'connection:deleted': {
+        connectionId: number;
+    };
+    'connection:error': {
+        connectionId: number;
+        error: string;
+    };
+    'integration:connected': Connection;
+    'integration:disconnected': {
+        connectionId: number;
+    };
+}
+type HandledEventType = keyof HandledEventMap;
+interface IntegrationHubProps {
+    /** Called when an integration is connected */
+    onConnect?: (connection: Connection) => void;
+    /** Called when an integration is disconnected */
+    onDisconnect?: (connectionId: number) => void;
+    /** Called when an error occurs */
+    onError?: (error: Error) => void;
+    /** Custom class name for the container */
+    className?: string;
+    /** Custom styles */
+    style?: React.CSSProperties;
+    /** Filter integrations by category */
+    categories?: Integration['category'][];
+    /** Show only specific integrations by ID */
+    integrationIds?: number[];
+    /** Hide the connected integrations section */
+    hideConnected?: boolean;
+    /** Custom title */
+    title?: string;
+    /** Custom description */
+    description?: string;
+}
+interface IntegrationCardProps {
+    integration: Integration;
+    connection?: Connection;
+    onConnect: () => void;
+    onDisconnect: () => void;
+    isLoading?: boolean;
+}
+interface ConnectionCardProps {
+    connection: Connection;
+    onDisconnect: () => void;
+    isLoading?: boolean;
+}
+interface ConnectionModalProps {
+    /** Whether the modal is open */
+    isOpen: boolean;
+    /** Function to close the modal */
+    onClose: () => void;
+    /** The integration to connect */
+    integration: Integration;
+    /** Called when connection succeeds */
+    onSuccess: (connection: Connection) => void;
+    /** Called when connection fails */
+    onError: (error: string) => void;
+}
+
+interface HandledProviderProps {
+    /** Developer's iPaaS client ID */
+    clientId: string;
+    /** Brand's account ID in Handled */
+    accountId: string;
+    /** Custom API base URL (defaults to https://api.usehandled.io) */
+    apiBaseUrl?: string;
+    /** Called when an integration is connected */
+    onConnect?: (connection: Connection) => void;
+    /** Called when an integration is disconnected */
+    onDisconnect?: (connectionId: number) => void;
+    /** Called when an error occurs */
+    onError?: (error: Error) => void;
+    /** React children */
+    children: React$1.ReactNode;
+}
+declare function HandledProvider({ clientId, accountId, apiBaseUrl, onConnect, onDisconnect, onError, children, }: HandledProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pre-built UI component for managing integrations.
+ * Displays available integrations and connected accounts.
+ *
+ * @example
+ * ```tsx
+ * <HandledProvider clientId="xxx" accountId="123">
+ *   <IntegrationHub
+ *     onConnect={(conn) => console.log('Connected:', conn)}
+ *     onDisconnect={(id) => console.log('Disconnected:', id)}
+ *   />
+ * </HandledProvider>
+ * ```
+ */
+declare function IntegrationHub({ onConnect, onDisconnect, onError, className, style, categories, integrationIds, hideConnected, title, description, }: IntegrationHubProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Modal component for connecting to an integration.
+ * Handles OAuth and credential-based authentication flows.
+ */
+declare function ConnectionModal({ isOpen, onClose, integration, onSuccess, onError, }: ConnectionModalProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Hook to access the Handled SDK context.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { integrations, connections, connect, disconnect } = useHandled()
+ *
+ *   return (
+ *     <div>
+ *       <h2>Available Integrations</h2>
+ *       {integrations.map(integration => (
+ *         <button
+ *           key={integration.id}
+ *           onClick={() => connect(integration.id)}
+ *         >
+ *           Connect {integration.name}
+ *         </button>
+ *       ))}
+ *
+ *       <h2>Connected</h2>
+ *       {connections.map(connection => (
+ *         <div key={connection.id}>
+ *           {connection.integration.name}
+ *           <button onClick={() => disconnect(connection.id)}>
+ *             Disconnect
+ *           </button>
+ *         </div>
+ *       ))}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useHandled(): HandledContextValue;
+
+declare class HandledApiClient {
+    private config;
+    constructor(config: HandledConfig);
+    private get baseUrl();
+    private get headers();
+    private request;
+    /**
+     * Get list of available integrations
+     */
+    getIntegrations(): Promise<Integration[]>;
+    /**
+     * Get list of connections for the current account
+     */
+    getConnections(): Promise<Connection[]>;
+    /**
+     * Initiate connection to an integration
+     * Returns an auth URL to open in a popup for OAuth, or creates connection directly for other auth types
+     */
+    connect(integrationId: number | string, options?: {
+        credentials?: Record<string, string>;
+        accountIntegrationName?: string;
+        redirectUrl?: string;
+    }): Promise<ConnectResponse>;
+    /**
+     * Disconnect an integration
+     */
+    disconnect(connectionId: number): Promise<void>;
+    /**
+     * Get a specific connection
+     */
+    getConnection(connectionId: number): Promise<Connection>;
+    /**
+     * Check connection status (used after OAuth popup closes)
+     */
+    checkConnectionStatus(connectionId: number): Promise<Connection>;
+}
+
+export { type ConnectOptions, type ConnectResponse, type ConnectResult, type Connection, type ConnectionCardProps, ConnectionModal, type ConnectionModalProps, type ConnectionsResponse, HandledApiClient, type HandledConfig, type HandledContextValue, type HandledEventMap, type HandledEventType, HandledProvider, type HandledProviderProps, type Integration, type IntegrationCardProps, IntegrationHub, type IntegrationHubProps, type IntegrationInputField, type IntegrationsResponse, useHandled };