@thredfi/accounting

v0.6.1

Published

8 days ago

Embeddable accounting widget for integrating Thredfi accounting features into your application

0High
0Medium
0Low

manoj-thredfi

dorogonov

accounting widget embeddable thredfi finance bookkeeping

Embeddable accounting widget by Thredfi

📦 Installation

npm install @thredfi/accounting

🚀 Quick Start

ES Module (npm/bundler)

import {
  mountThredfi,
  unmountThredfi,
  setThredfiLanguage,
  type TokenFetcher,
  type TokenResponse,
} from "@thredfi/accounting";

mountThredfi({
  // CSS selector for the container element
  thredfiSelector: "#thredfi-widget",
  // Function to fetch authentication token from your backend
  getToken: async () => {
    const response = await fetch("https://your-api.com/thredfi-token", {
      headers: {
        Authorization: "Bearer your-auth-token",
      },
    });
    return await response.json();
  },
  // Your business UUID in the Thredfi system
  businessId: "964f4325-3efb-400d-a1bd-8b1f29e828cf",
  lang: "en",
  environment: "production", // "sandbox" | "production"
  // Theme customization (optional)
  theme: {
    navigationBackgroundColor: "#f9f9f9",
    cardsBackgroundColor: "#ffffff",
    textColor: "#111827",
    textSecondaryColor: "#6b7280",
    activeColor: "#871f91",
    borderColor: "#dcdcdc",
    borderSecondaryColor: "#e5e7eb",
  },
  // Base path for routing within the widget
  basePath: "/accounting",
  // Hide the header navigation menu (optional)
  hideMenu: false,
});

CDN Usage (UMD)

Use directly in the browser without a bundler:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>My App with Thredfi</title>
  </head>
  <body>
    <!-- Container for the widget -->
    <div id="thredfi-widget"></div>

    <!-- Load from CDN -->
    <script src="https://unpkg.com/@thredfi/accounting@latest/dist/index.umd.js"></script>
    <script>
      // Access via global ThredfiAccounting object
      ThredfiAccounting.mountThredfi({
        thredfiSelector: "#thredfi-widget",
        getToken: async () => {
          const response = await fetch("https://your-api.com/thredfi-token", {
            headers: {
              Authorization: "Bearer your-auth-token",
            },
          });
          return await response.json();
        },
        businessId: "964f4325-3efb-400d-a1bd-8b1f29e828cf",
        environment: "production",
      });
    </script>
  </body>
</html>

📖 API Reference

`mountThredfi(options)`

Mounts the Thredfi accounting widget in the specified container.

Options

interface ThredfiMountOptions {
  thredfiSelector: string; // Required: CSS selector for container
  getToken: () => Promise<{
    // Required: Token fetcher function
    access_token: string;
    expires_in: number;
  }>;
  businessId: string; // Required: Business UUID
  lang?: string; // Optional: Language code (default: "en")
  environment?: string; // Optional: "sandbox" | "production" (default: "sandbox")
  basePath?: string; // Optional: Base path for routing (default: "")
  theme?: ThemeConfig; // Optional: Color overrides for theming
  hideMenu?: boolean; // Optional: Hide header navigation (default: false)
}

interface ThemeConfig {
  navigationBackgroundColor?: string; // Background color for header/navigation
  cardsBackgroundColor?: string; // Background color for cards and panels
  textColor?: string; // Main text color
  textSecondaryColor?: string; // Secondary/muted text color
  activeColor?: string; // Active/highlight/profit color
  borderColor?: string; // Border color for elements
  borderSecondaryColor?: string; // Light/secondary border color
}

`unmountThredfi()`

Unmounts the currently mounted widget and cleans up resources.

unmountThredfi();

When to use:

Cleaning up before remounting with different options
Component unmount in React/Vue/Angular
Page navigation cleanup

`setThredfiLanguage(lang)`

Changes the language of the mounted widget at runtime.

setThredfiLanguage("de"); // Switch to German
setThredfiLanguage("en-GB"); // Switch to English (UK)

Note: The widget must be mounted before calling this function.

🌍 Supported Languages

| Code | Language | | ------- | ---------------- | | en | English (US) | | en-GB | English (UK) | | de | German | | es | Spanish | | fr | French | | it | Italian | | nl | Dutch | | nb | Norwegian Bokmål |

🌐 Environment Configuration

The environment option controls which backend API the widget connects to:

| Environment | Backend URL | Use Case | | ------------ | ----------------------------------- | --------------- | | sandbox | https://sandbox-backend.thredfi.com | Testing/Sandbox | | production | https://backend.thredfi.com | Production |

mountThredfi({
  // ... other options
  environment: "production", // Default is "sandbox"
});

🎛️ Hide Header Menu

You can hide the header navigation menu to show only the content:

mountThredfi({
  // ... other options
  hideMenu: true, // Hide the header menu
});

This is useful when embedding specific views or when you want to provide your own navigation. Thredfi also has menu config that can manage which tabs are shown. The Thredfi widget can see route changes and render the needed tab based on that.

🎨 Theming

Customize the widget appearance with simple color overrides:

mountThredfi({
  // ... other options
  theme: {
    navigationBackgroundColor: "#f9f9f9", // Background color for header/navigation
    cardsBackgroundColor: "#ffffff", // Background color for cards and panels
    textColor: "#111827", // Main text color
    textSecondaryColor: "#6b7280", // Secondary/muted text color
    activeColor: "#871f91", // Active/highlight/profit color
    borderColor: "#dcdcdc", // Border color for elements
    borderSecondaryColor: "#e5e7eb", // Light/secondary border color
  },
});

Available theme properties:

| Property | Description | Default | | --------------------------- | -------------------------------------- | --------- | | navigationBackgroundColor | Background color for header/navigation | #f9f9f9 | | cardsBackgroundColor | Background color for cards and panels | #ffffff | | textColor | Main text color throughout the widget | #111827 | | textSecondaryColor | Secondary/muted text color | #6b7280 | | activeColor | Active/highlight/profit color | #871f91 | | borderColor | Border color for elements | #dcdcdc | | borderSecondaryColor | Light/secondary border color | #e5e7eb |

🔐 Authentication

The widget requires a getToken function to fetch authentication tokens. This gives you full control over how tokens are fetched, including adding custom headers and authentication. Use Thredfi's API key to create short-lived tokens that can be used in the frontend.

Example of a Token Fetcher Function:

import { mountThredfi, type TokenFetcher } from "@thredfi/accounting";

const getToken: TokenFetcher = async () => {
  const response = await fetch("https://your-api.com/thredfi-token", {
    headers: {
      Authorization: "Bearer your-auth-token", // Add your own auth
      "X-Custom-Header": "custom-value", // any custom headers
    },
  });

  const data = await response.json();

  return {
    access_token: data.access_token,
    expires_in: data.expires_in,
  };
};

mountThredfi({
  // ... other options
  getToken, // Your custom token fetcher
});

Token Response Format

Your getToken function must return an object with:

access_token (string) - The JWT access token
expires_in (number) - Token expiration time in seconds

Example response:

{
  access_token: "eyJhbGciOiJIUzI1NiIs...",
  expires_in: 3600
}

Automatic Token Management

The widget automatically:

Calls getToken before making API requests
Refreshes expired tokens (60 seconds before expiration)
Calls getToken when a 401 error is received
Retries failed requests with new tokens

📘 TypeScript Support

The package includes full TypeScript definitions. Import types for better development experience:

import {
  type ThredfiMountOptions,
  type TokenFetcher,
  type TokenResponse,
  type ThredfiLanguage,
} from "@thredfi/accounting";

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme