JSPM

@spaceinvoices/embed-sdk

1.0.3
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 33
  • Score
    100M100P100Q59019F
  • License MIT

Embed Space Invoices UI in your application via iframes

Package Exports

  • @spaceinvoices/embed-sdk

Readme

@spaceinvoices/embed-sdk

Embed Space Invoices UI in your application via iframes with customizable themes.

Installation

npm install @spaceinvoices/embed-sdk
# or
yarn add @spaceinvoices/embed-sdk
# or
pnpm add @spaceinvoices/embed-sdk

Quick Start

import { SpaceInvoices } from '@spaceinvoices/embed-sdk';

const si = new SpaceInvoices({
  apiKey: 'ek_live_your_entity_api_key',
  entityId: 'ent_123',
  theme: {
    primary: '#6366f1',
    radius: 8,
  },
  onAction: (action) => {
    console.log('Action:', action);
  },
});

// Open invoice list
si.open('invoices', { container: '#invoice-container' });

Usage via Script Tag

<div id="space-invoices-embed" style="height: 600px;"></div>

<script src="https://unpkg.com/@spaceinvoices/embed-sdk"></script>
<script>
  const si = new SpaceInvoices.SpaceInvoices({
    apiKey: 'ek_live_your_entity_api_key',
    entityId: 'ent_123',
  });

  si.open('invoices');
</script>

Configuration

interface SpaceInvoicesConfig {
  // Required
  apiKey: string;      // Entity API key (ek_live_* or ek_test_*)
  entityId: string;    // Entity ID

  // Optional
  baseUrl?: string;    // Custom base URL (for self-hosted)
  theme?: ThemeConfig; // Theme customization

  // Callbacks
  onAction?: (action: EmbedAction) => void;
  onReady?: () => void;
  onError?: (error: EmbedError) => void;
  onClose?: () => void;
}

Available Views

View Description
invoices Invoice list
invoice/new Create new invoice
invoice View invoice (requires id)
estimates Estimate list
estimate/new Create new estimate
estimate View estimate (requires id)
credit-notes Credit note list
credit-note/new Create new credit note
credit-note View credit note (requires id)
advance-invoices Advance invoice list
advance-invoice/new Create new advance invoice
advance-invoice View advance invoice (requires id)
delivery-notes Delivery note list
delivery-note/new Create new delivery note
delivery-note View delivery note (requires id)
customers Customer list
customer/new Create new customer
customer View customer (requires id)
settings/company Company settings
settings/defaults Default settings
settings/numbering Numbering settings
settings/tax Tax settings
settings/furs FURS fiscalization settings
settings/fina FINA settings
settings/templates Document templates settings
export Document export

Theme Customization

const si = new SpaceInvoices({
  apiKey: 'ek_live_...',
  entityId: 'ent_123',
  theme: {
    primary: '#6366f1',    // Primary brand color
    accent: '#8b5cf6',     // Accent color
    background: '#ffffff', // Background color
    foreground: '#1a1a1a', // Text color
    card: '#ffffff',       // Card background
    border: '#e5e5e5',     // Border color
    radius: 8,             // Border radius (px)
    darkMode: false,       // Enable dark mode
  },
});

You can update the theme dynamically:

si.updateTheme({
  primary: '#10b981',
  darkMode: true,
});

Navigate between views without recreating the embed:

// Open invoice list
si.open('invoices');

// Navigate to create form
si.navigate('invoice/new');

// Navigate to view a specific invoice
si.navigate('invoice', { id: 'inv_123' });

Actions

Listen for user actions within the embed:

const si = new SpaceInvoices({
  // ...config
  onAction: (action) => {
    switch (action.type) {
      case 'document_created':
        console.log('Created document:', action.data?.id);
        break;
      case 'navigation':
        console.log('Navigated to:', action.data?.path);
        break;
      case 'close_requested':
        // User requested to close the embed
        si.close();
        break;
    }
  },
});

Action Types

Type Description
page_loaded Page finished loading
document_created Document was created
document_updated Document was updated
document_deleted Document was deleted
customer_created Customer was created
customer_updated Customer was updated
customer_deleted Customer was deleted
navigation User navigated within embed
close_requested User requested to close
settings_updated Settings were updated
export_started Document export started
export_completed Document export completed

API Reference

SpaceInvoices

Main SDK class.

Methods

  • open(view, options?) - Open a view in a container
  • navigate(view, options?) - Navigate to a different view
  • updateTheme(theme) - Update theme colors dynamically
  • close() - Close and unmount the embed
  • ready() - Returns a promise that resolves when embed is ready
  • getInstance() - Get current embed instance
  • destroy() - Destroy SDK and clean up resources

EmbedInstance

Returned by open().

interface EmbedInstance {
  id: string;
  container: HTMLElement;
  iframe: HTMLIFrameElement;
  view: EmbedView;
  unmount: () => void;
  navigate: (view, options?) => void;
  updateTheme: (theme) => void;
}

Framework Examples

React

import { useEffect, useRef } from 'react';
import { SpaceInvoices } from '@spaceinvoices/embed-sdk';

function InvoiceEmbed() {
  const containerRef = useRef<HTMLDivElement>(null);
  const sdkRef = useRef<SpaceInvoices | null>(null);

  useEffect(() => {
    if (!containerRef.current) return;

    sdkRef.current = new SpaceInvoices({
      apiKey: 'ek_live_...',
      entityId: 'ent_123',
      onAction: (action) => console.log(action),
    });

    sdkRef.current.open('invoices', { container: containerRef.current });

    return () => sdkRef.current?.destroy();
  }, []);

  return <div ref={containerRef} style={{ height: '600px' }} />;
}

Vue

<template>
  <div ref="container" style="height: 600px" />
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import { SpaceInvoices } from '@spaceinvoices/embed-sdk';

const container = ref(null);
let sdk = null;

onMounted(() => {
  sdk = new SpaceInvoices({
    apiKey: 'ek_live_...',
    entityId: 'ent_123',
  });
  sdk.open('invoices', { container: container.value });
});

onUnmounted(() => sdk?.destroy());
</script>

Security

  • The SDK uses entity API keys (ek_*), which are scoped to a single entity
  • All communication happens via postMessage with origin validation
  • Iframes provide complete style isolation and security boundaries
  • API keys should be kept secure and not exposed in client-side code for production use

Browser Support

  • Chrome/Edge 80+
  • Firefox 75+
  • Safari 13.1+

License

MIT