@schematichq/schematic-js

schematic-js

schematic-js is a client-side JavaScript SDK for tracking event-based usage, identifying users, and checking flags using Schematic.

Install

npm install @schematichq/schematic-js
# or
yarn add @schematichq/schematic-js
# or
pnpm add @schematichq/schematic-js

Usage

You can use Schematic to identify users; after this, your subsequent track events and flag checks will be associated with this user.

A number of these examples use keys to identify companies and users. Learn more about keys here.

import { Schematic } from "@schematichq/schematic-js";

const schematic = new Schematic("your-api-key");

// Send an identify event
schematic.identify({
    keys: {
        id: "my-user-id",
    },
    traits: {
        anykey: "anyval",
    },
    company: {
        name: "My Company",
        keys: {
            id: "my-company-id",
        },
        traits: {
            location: "Atlanta, GA",
        },
    },
});

// Send a track event to record usage
schematic.track({ event: "query" });
// OR, Send a track event with a quantity to record multiple units of usage
schematic.track({ event: "query", quantity: 10 });

// Check a flag
await schematic.checkFlag({ key: "some-flag-key" });

By default, checkFlag will perform a network request to get the flag value for this user. If you'd like to check all flags at once in order to minimize network requests, you can use checkFlags:

import { Schematic } from "@schematichq/schematic-js";

const schematic = new Schematic("your-api-key");

schematic.identify({
    keys: { id: "my-user-id" },
    company: {
        keys: { id: "my-company-id" },
    },
});

await schematic.checkFlags();

Alternatively, you can run in websocket mode, which will keep a persistent connection open to the Schematic service and receive flag updates in real time:

import { Schematic } from "@schematichq/schematic-js";

const schematic = new Schematic("your-api-key", { useWebSocket: true });

schematic.identify({
    keys: { id: "my-user-id" },
    company: { keys: { id: "my-company-id" } },
});

await schematic.checkFlag("some-flag-key");

// Close the connection when you're done with the Schematic client
schematic.cleanup();

Credit balances

In websocket mode, the client also tracks the company's credit balances, keyed by credit ID, updating in real time as balances change:

// Read the balance for a single credit, or all balances for the current context
const balance = schematic.getCreditBalance("credit-id");
const balances = schematic.getCreditBalances();

// Subscribe to balance changes
const unsubscribe = schematic.addCreditBalanceListener((balances) => {
    console.log(balances["credit-id"]?.settled);
});

settled is the spendable balance and the number to display to end users.

A feature's entitlement carries the same numbers. getFlagCheck returns creditId, creditSettled, creditRemaining, and creditReserved for features metered by credit burndown, and undefined for each when the feature is not credit-based:

const check = schematic.getFlagCheck("some-flag-key");

if (check?.creditId) {
    console.log(`${check.creditSettled} credits remaining`);
}

The entitlement refreshes with each flag check. getCreditBalance also updates on the credit partials that arrive between checks, so prefer it for a balance you render.

Usage warnings

If a usage warning is configured on the entitlement, getFlagCheck returns it as warningTiers, so you can warn a customer before they hit the limit rather than after. Each tier is a { key, value } pair in the entitlement's usage units, and the dashboard writes a single tier under the key default. The field is undefined when no warning is configured.

const check = schematic.getFlagCheck("some-flag-key");
const warning = check?.warningTiers?.find((tier) => tier.key === "default");

if (
    typeof check?.featureUsage === "number" &&
    typeof warning?.value === "number" &&
    check.featureUsage >= warning.value
) {
    console.log(`Approaching your limit of ${warning.value}`);
}

getFlagCheck also returns softLimit, the soft limit for overage charges or the next tier boundary under usage-based pricing.

Fallback Behavior

The SDK includes built-in fallback behavior you can use to ensure your application continues to function even when unable to reach Schematic (e.g., during service disruptions or network issues).

Flag Check Fallbacks

When checkFlag cannot reach Schematic, it uses fallback values in the following priority order:

• Callsite fallback - fallback values can be provided directly in the checkFlag call
• Initialization defaults - fallback values configured via flagCheckDefaults or flagValueDefaults options when initializing the SDK
• Default value - Returns false if no fallback is configured

// Provide a fallback value at the callsite
const value = await schematic.checkFlag({ 
    key: "feature-flag", 
    fallback: true  // Used if API request fails
});

// Or configure defaults at initialization
const schematic = new Schematic("your-api-key", {
    flagValueDefaults: {
        "feature-flag": true,  // Used if API request fails and no callsite fallback
    },
    flagCheckDefaults: {
        "another-flag": {
            flag: "another-flag",
            value: true,
            reason: "Default value",
        },
    },
});

Event Queueing and Retry

When events (track, identify) cannot be sent due to network issues, they are automatically queued and retried:

• Events are queued in memory (up to 100 events by default, configurable via maxEventQueueSize)
• Failed events are retried with exponential backoff (up to 5 attempts by default, configurable via maxEventRetries)
• Events are automatically flushed when the network connection is restored
• Events queued when the page is hidden are sent when the page becomes visible

WebSocket Fallback

In WebSocket mode, if the WebSocket connection fails, the SDK will provide the last known value or the configured fallback values as outlined above. The WebSocket will also automatically attempt to re-establish its connection with Schematic using an exponential backoff.

Troubleshooting

For debugging and development, Schematic supports two special modes:

Debug Mode

Enables console logging of all Schematic operations:

// Enable at initialization
const schematic = new Schematic("your-api-key", { debug: true });

// Or via URL parameter
// https://yoursite.com/?schematic_debug=true

Offline Mode

Prevents network requests and returns fallback values for all flag checks:

// Enable at initialization
const schematic = new Schematic("your-api-key", { offline: true });

// Or via URL parameter
// https://yoursite.com/?schematic_offline=true

Offline mode automatically enables debug mode to help with troubleshooting.

License

MIT

Support

Need help? Please open a GitHub issue or reach out to [e-mail] and we'll be happy to assist.