Events

Action Types

Type	Description	Data
page_loaded	Page finished loading	{ path }
document_created	Document was created	{ id, documentType }
document_updated	Document was updated	{ id, documentType }
document_deleted	Document was deleted	{ id, documentType }
customer_created	Customer was created	{ id }
customer_updated	Customer was updated	{ id }
customer_deleted	Customer was deleted	{ id }
navigation	User navigated	{ path }
close_requested	User wants to close	—

Handling Actions

Action Handlertypescript

Copy

const _si = new SpaceInvoices({
  apiKey: "ek_live_...",
  entityId: "ent_123",
  onAction: (action) => {
    switch(action.type) {
      case "document_created":
        // Handle document creation
        break;
      case "document_updated":
        // Handle document update
        break;
      case "navigation":
        // Handle navigation
        break;
      case "close_requested":
        // Handle close request
        break;
    }
  },
});

Document Events

Document Eventstypescript

Copy

onAction: (action) => {
  if (action.type === "document_created") {
    const { id, documentType } = action.data;

    // Refresh your invoice list
    refreshInvoices();

    // Show success notification
    toast.success("Invoice created!");
  }

  if (action.type === "document_updated") {
    const { id, documentType } = action.data;

    // Refresh specific document
    refreshDocument(id);
  }

  if (action.type === "document_deleted") {
    const { id } = action.data;

    // Remove from your local state
    removeFromList(id);
  }
};

Customer Events

Customer Eventstypescript

Copy

onAction: (action) => {
  if (action.type === "customer_created") {
    const { id } = action.data;

    // Refresh your customer list
    refreshCustomers();
  }

  if (action.type === "customer_updated") {
    const { id } = action.data;
  }

  if (action.type === "customer_deleted") {
    const { id } = action.data;
  }
};

Navigation Events

Navigation Eventstypescript

Copy

onAction: (action) => {
  if (action.type === "page_loaded") {
  }

  if (action.type === "navigation") {
    const { path } = action.data;

    // Update your app's URL or breadcrumbs
    updateBreadcrumbs(path);
  }
};

Close Requests

Handle when users click a close button:

Close Requesttypescript

Copy

const si = new SpaceInvoices({
  apiKey: "ek_live_...",
  entityId: "ent_123",
  onAction: (action) => {
    if (action.type === "close_requested") {
      // User clicked a close button in the embed
      // Close the embed and show your own UI
      si.close();

      // Or hide the modal/sidebar containing the embed
      setShowEmbed(false);
    }
  },
});

Error Handling

Error Handlingtypescript

Copy

const _si = new SpaceInvoices({
  apiKey: "ek_live_...",
  entityId: "ent_123",
  onError: (error) => {
    console.error("Embed error:", error.code, error.message);

    switch(error.code) {
      case "auth_failed":
      case "invalid_api_key":
        // Re-authenticate or show error
        showAuthError();
        break;
      case "entity_not_found":
        // Entity was deleted or doesn__PROTECTED_8__t have permission
        showPermissionError();
        break;
      case "network_error":
        // Network issue - maybe retry
        showNetworkError();
        break;
      default:
        showGenericError(error.message);
    }
  },
});

Error Codes

Code	Description
auth_failed	Authentication failed
invalid_api_key	API key is invalid
entity_not_found	Entity doesn’t exist
permission_denied	No permission for action
network_error	Network request failed
unknown_error	Unknown error occurred

Next Steps

• Framework Examples — React, Vue, vanilla JS