@use-handled/ipaas-react-sdk 0.1.0

package/dist/index.d.ts

@@ -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 };