Skip to main content

SyncHive Apps

A SyncHive App is an application that uses the SyncHive Unified Data Store (UDS) as its data store.

Apps are registered to a specific SyncHive instance. Once registered, an app can write data to and read data from SyncHive through the Unified Data Store.

Data exchange between SyncHive Apps and SyncHive occurs via APIs, using SyncHive shapes as the data contract.

Registering a New App​

  1. Open SyncHive Apps
  2. Click Register App
  3. Enter the app details:
    • Name
    • Shapes it integrates with
    • Status: enabled or disabled
    • App URLs: the URL(s) where your app is hosted. SyncHive will only allow sign-in and API access from these URL(s).
  4. Confirm registration

Once saved, SyncHive will generate a publishable key for the app and display it in the connection details. You’ll use this key in your app to initialize the SyncHive Javascript SDK.

Viewing and Editing Registered Apps​

The SyncHive Apps main page displays a list of all apps registered within your SyncHive instance.

For each app, you can see:

  • App name
  • Shapes it connects to
  • Current status

From this page, you can:

  • View the app’s connection details
  • Edit the app’s registration information
  • Change the app’s status
  • Delete the app’s connection

Building Your App​

SyncHive Apps are built using the official SyncHive JavaScript SDK, which handles sign-in and secure access automatically.

View the SDK on GitHub: https://github.com/synchivehq/synchive-js.

Most apps install it via npm:

npm install synchive-js-sdk

Once installed, your app can connect to SyncHive. In the snippet below, replace the placeholder value for publishableKey with the publishable key from the app’s connection details.

import { SyncHiveClient } from "synchive-js-sdk";

const synchive = new SyncHiveClient({
  publishableKey: "sh_publishable_...",
});

try {
  await synchive.init();
} catch (error) {
  console.error("Auth failed:", error);
}

const user = await synchive.getUser();
const isLoggedIn = !!user && !user.expired;

if (isLoggedIn) {
  // Render logged-in UI
  // Example:
  // onSignOutClick -> await synchive.signOutRedirect();
} else {
  // Render logged-out UI with a Sign In action
  // Example:
  // onSignInClick -> await synchive.signInRedirect();
}

Requesting Data from SyncHive​

After signing in, you can access SyncHive data using simple helper methods.

List Records​

Use list() to fetch records from a shape:

const products = await synchive.list("Product", {
  top: 20,
});

Get a Specific Record​

Use get() to retrieve a single record by its hiveId:

const product = await synchive.get("Product", "D6BFA0AB71A1");

Create a Record​

Use create() to create a new record in a shape:

const createdProduct = await synchive.create("Product", {
  name: "Two-Slice Toaster",
  sku: "TOASTER-2S-BLK",
});

create() returns the full created shape record.

Update a Record​

Use update() to update an existing record by hiveId. You can pass either a partial shape or a full shape:

const updatedProduct = await synchive.update("Product", "D6BFA0AB71A1", {
  status: "discontinued",
});

update() returns the full updated shape record.

Filtering and Paging​

You can pass query options such as:

  • top controls how many records are returned (maximum 500 per request)
  • skip controls how many records are skipped before returning results
  • filter lets you request only records that match specific conditions
  • orderby sorts records by one or more fields (use asc or desc)

Additional details:

  • If top is greater than 500, SyncHive uses 500 instead.
  • For orderby, use a comma-separated list such as createdOn desc,name asc.

Example:

const salesOrders = await synchive.list("SalesOrder", {
  filter:
    "transactionNumber eq 'TOASTER-1001' and salesOrderItem/any(i: i/name eq '4-Slice Toaster')",
  orderby: "createdOn desc,transactionNumber asc",
  skip: 0,
  top: 25,
});

Supported filters​

SyncHive supports only this subset of the OData filter syntax:

  • Comparison operators: eq, ne, gt, lt, ge, le
  • Logical operators: and, or, not
  • Collection operators: any, all
  • One text function: contains(field,'value')

Examples of supported filters:

  • status eq 'Active'
  • status ne 'Inactive'
  • amount gt 100 and amount lt 500
  • total ge 1000 or discount le 25
  • not (status eq 'Archived')
  • salesOrderItem/any(i: i/name eq '4-Slice Toaster')
  • salesOrderItem/all(i: i/quantity ge 1)
  • contains(customerName,'Acme')

Unsupported filters​

SyncHive does not currently support:

  • Other OData functions such as startswith(), endswith(), length(), or tolower()
  • Lambda expressions beyond any and all
  • Full OData query features such as expand or advanced nested function combinations

Examples of unsupported filters:

  • startswith(customerName,'A')
  • endswith(customerName,'Inc')
  • length(customerName) gt 10
  • tolower(customerName) eq 'acme'
  • salesOrderItem/filter(i: i/qty gt 1)
  • contains(tolower(customerName),'acme')
  • expand=salesOrderItem

If a filter uses syntax not listed in Supported filters, treat it as unsupported.

Troubleshooting​

App URLs​

If your sign-in does not work, the most common cause is an App URL mismatch.

When this happens, you will usually see:

  • "Authentication Failed"
  • "We couldn't sign you in because the URL of your app isn't allowed to communicate with SyncHive..."

This means the app URL you entered in SyncHive does not exactly match the URL your app is using during sign-in.

Common issues​

  • A missing or extra slash
    • Entered in SyncHive: https://my-app.com/sign-in
    • App is using: https://my-app.com/sign-in/
  • http vs https
    • Entered in SyncHive: https://my-app.com/sign-in
    • App is using: http://my-app.com/sign-in
  • Different web address
    • Entered in SyncHive: https://portal.my-app.com/sign-in
    • App is using: https://my-app.com/sign-in
  • Different path or capitalization
    • Entered in SyncHive: https://my-app.com/Sign-In/
    • App is using: https://my-app.com/sign-in/

How to fix​

  1. Open Apps in SyncHive and select your app.
  2. Go to App URLs.
  3. Compare what you entered in App URLs against the URL of your app before you start sign-in.
  4. Make sure they match exactly, including:
    • http or https
    • full web address
    • full path
    • trailing slash (/)
  5. Save your changes.
  6. Try signing in again.