smartsell-sdk

smartsell-sdk is the public runtime contract for building SmartSell modules outside the main SmartSell repository.

It provides:

• createSmartSellSDK(...) to bootstrap the shared runtime with SMARTSELL_API
• SmartSellProvider and useSmartSellAuth() for provider-based auth/runtime access in React
• public TypeScript types for sdk, pages, extensions, and hooks
• helpers such as defineExtensionManifest and defineHooksManifest
• shared i18n helpers for runtime-loaded modules
• smartsell-build-module, a CLI that builds a module into the single CommonJS bundle expected by the SmartSell Sales runtime

Visual primitives are intentionally out of scope for this package. Import smartsell-theme and smartsell-ui-kit directly from the module code when you need theme tokens, CSS variables, or shared UI components.

The default import path smartsell-sdk is browser-safe and only exposes runtime APIs. If you need the Node build API programmatically, import it from smartsell-sdk/build-tools.

Installation

npm install react smartsell-sdk
npm install smartsell-theme smartsell-ui-kit

Install smartsell-theme and smartsell-ui-kit only when the module renders UI with those public packages. They are shared by the host runtime, but they are not wrapped by smartsell-sdk.

Provider-based runtime

import { SmartSellProvider, createSmartSellSDK } from 'smartsell-sdk';

const sdk = createSmartSellSDK({
  config: {
    SMARTSELL_API: 'https://api.example.com',
  },
});

export function App() {
  return <SmartSellProvider sdk={sdk}>{/* app */}</SmartSellProvider>;
}

Page example

import type { ModulePageProps } from 'smartsell-sdk';
import { useThemeName, useThemeValue } from 'smartsell-theme';

export default function MyPage({ sdk }: ModulePageProps) {
  const user = sdk.auth.getUser();
  const theme = useThemeValue();
  const themeName = useThemeName();
  const isDark = themeName.toLowerCase() === 'dark';

  return (
    <div
      style={{
        minHeight: '100vh',
        padding: 24,
        backgroundColor: theme.colors.background,
        color: theme.colors.onBackground,
      }}
    >
      <h1>Hello, {user?.name}</h1>
      <p>Current theme: {isDark ? 'dark' : 'light'}</p>
      <button
        type="button"
        onClick={() => sdk.navigation.goBack()}
        style={{
          backgroundColor: theme.colors.primary,
          color: theme.colors.onPrimary,
        }}
      >
        Back
      </button>
    </div>
  );
}

Extension example

import type { ExtensionManifest } from 'smartsell-sdk';
import { defineExtensionManifest } from 'smartsell-sdk';
import { useThemeValue, withAlpha } from 'smartsell-theme';

function RevenueCard({ sdk }: { sdk: import('smartsell-sdk').SmartSellSDK }) {
  const theme = useThemeValue();

  return (
    <div
      style={{
        backgroundColor: withAlpha(theme.colors.surface, 0.72),
        border: `1px solid ${withAlpha(theme.colors.positive, 0.3)}`,
        color: theme.colors.onSurface,
      }}
    >
      Custom revenue card
    </div>
  );
}

const manifest: ExtensionManifest = defineExtensionManifest({
  slots: {
    'dashboard:extra-charts': {
      action: 'append',
      component: RevenueCard,
    },
  },
});

export default manifest;

Hook example

import type { HooksManifest } from 'smartsell-sdk';
import { defineHooksManifest } from 'smartsell-sdk';

const manifest: HooksManifest = defineHooksManifest({
  hooks: {
    'order:validate': (order) => {
      const errors: string[] = [];

      if (!order.customerChannel) {
        errors.push('Customer channel is required');
      }

      return errors;
    },
  },
});

export default manifest;

module.json

Create a module.json file in the module folder:

type is required in every module manifest.

{
  "id": "my-custom-page",
  "name": "My Custom Page",
  "version": "1.0.0",
  "type": "page",
  "entryComponent": "MyPage.tsx",
  "routes": [
    {
      "path": "/my-page",
      "label": "My Page",
      "icon": "FileText"
    }
  ]
}

For extension modules use extensionEntry, and for hooks modules use hooksEntry.

Build a module bundle

npx smartsell-build-module --module-dir ./src/my-custom-page --out-dir ./dist/modules

The command:

• reads module.json
• builds the module into a single CommonJS bundle
• injects __moduleConfig metadata required by the SmartSell Sales runtime
• rejects private imports such as @/core/...

Output example:

dist/modules/my-custom-page.js

Theme helpers

Use smartsell-theme directly inside module components. The SmartSell Sales host shares a single ThemeProvider instance with runtime-loaded modules, so hooks such as useThemeValue() and useThemeName() work across host and custom bundles.

import { useThemeName, useThemeValue, withAlpha } from 'smartsell-theme';

const theme = useThemeValue();
const themeName = useThemeName();
const isDark = themeName.toLowerCase() === 'dark';

const border = withAlpha(theme.colors.backgroundLight, 0.5);

This avoids importing private app files such as @/core/theme/useAppTheme and keeps the SDK focused on runtime services, i18n, hooks, and module contracts.

Use smartsell-ui-kit directly for shared components and modal composition. The host runtime resolves that package from the parent app just like it does for smartsell-theme.

I18n helpers

Custom modules should not import the host app's private i18n files. Instead, use the public i18n runtime exposed by smartsell-sdk.

Host apps create the shared service with createI18nService(...). Custom modules consume that same locale state through sdk.i18n and can layer their own translation catalogs on top with useModuleI18n(sdk, resources).

Fallback order:

• module catalog

• host/core catalog from sdk.i18n

• raw key when nothing is registered

• sdk.i18n.getLocale() returns the active host locale such as pt-BR or en

• sdk.i18n.t(key) lets the module reuse shared host translation keys when they exist

• sdk.i18n.subscribe(listener) notifies the module when the host locale changes

• sdk.i18n.setPreference(preference) updates the host language preference globally

• useModuleI18n(sdk, resources) binds React components to the shared locale while checking the module catalog first

import {
  useModuleI18n,
  type ModulePageProps,
  type TranslationCatalog,
} from 'smartsell-sdk';

const moduleMessages: TranslationCatalog = {
  'pt-BR': {
    module: {
      title: 'Resumo do módulo',
      description: 'Este texto segue o idioma atual do core.',
    },
  },
  en: {
    module: {
      title: 'Module summary',
      description: 'This text follows the current host language.',
    },
  },
};

export default function MyLocalizedPage({ sdk }: ModulePageProps) {
  const { t } = useModuleI18n(sdk, moduleMessages);

  return (
    <section>
      <h1>{t('module.title')}</h1>
      <p>{t('module.description')}</p>
      <button type="button">{t('common.backToHome')}</button>
    </section>
  );
}

This keeps the module self-contained while still reacting to host language changes automatically. The button above demonstrates fallback to the host/core catalog when common.backToHome is not defined by the module.

Publish

npm run typecheck
npm run build
npm publish