Node.js

Installation and Setup

  1. Install the TypeScript library using your package manager of choice:
$npm install @schematichq/schematic-typescript-node
># or
>yarn add @schematichq/schematic-typescript-node
># or
>pnpm add @schematichq/schematic-typescript-node

  1. Issue an API key for the appropriate environment using the Schematic app. Be sure to capture the secret key when you issue the API key; you’ll only see this key once, and this is what you’ll use with schematic-typescript-node.

  2. Using this secret key, initialize a client in your application:

1import { SchematicClient } from "@schematichq/schematic-typescript-node";
2
3const apiKey = process.env.SCHEMATIC_API_KEY;
4const client = new SchematicClient({ apiKey });
5
6// interactions with the client
7
8client.close();

By default, the client will do some local caching for flag checks. If you would like to change this behavior, you can do so using an initialization option to specify the max size of the cache (in terms of number of records) and the max age of the cache (in milliseconds):

1import { LocalCache, SchematicClient } from "@schematichq/schematic-typescript-node";
2
3const apiKey = process.env.SCHEMATIC_API_KEY;
4const cacheSize = 100;
5const cacheTTL = 1000; // in milliseconds
6const client = new SchematicClient({
7    apiKey,
8    cacheProviders: {
9        flagChecks: [new LocalCache<boolean>({ size: cacheSize, ttl: cacheTTL })],
10    },
11});
12
13// interactions with the client
14
15client.close();

You can also disable local caching entirely with an initialization option; bear in mind that, in this case, every flag check will result in a network request:

1import { SchematicClient } from "@schematichq/schematic-typescript-node";
2
3const apiKey = process.env.SCHEMATIC_API_KEY;
4const client = new SchematicClient({
5    apiKey,
6    cacheProviders: {
7        flagChecks: [],
8    },
9});
10
11// interactions with the client
12
13client.close();

You may want to specify default flag values for your application, which will be used if there is a service interruption or if the client is running in offline mode (see below). You can do this using an initialization option:

1import { SchematicClient } from "@schematichq/schematic-typescript-node";
2
3const apiKey = process.env.SCHEMATIC_API_KEY;
4const client = new SchematicClient({
5    apiKey,
6    flagDefaults: {
7        "some-flag-key": true,
8    },
9});
10
11// interactions with the client
12
13client.close();

Usage examples

Sending identify events

Create or update users and companies using identify events.

1import { SchematicClient } from "@schematichq/schematic-typescript-node";
2
3const apiKey = process.env.SCHEMATIC_API_KEY;
4const client = new SchematicClient({ apiKey });
5
6client.identify({
7    company: {
8        id: "your-company-id",
9    },
10    keys: {
11        email: "wcoyote@acme.net",
12        userId: "your-user-id",
13    },
14    name: "Wile E. Coyote",
15    traits: {
16        city: "Atlanta",
17        loginCount: 24,
18        isStaff: false,
19    },
20});
21
22client.close();

This call is non-blocking and there is no response to check.

Sending track events

Track activity in your application using track events; these events can later be used to produce metrics for targeting.

1import { SchematicClient } from "@schematichq/schematic-typescript-node";
2
3const apiKey = process.env.SCHEMATIC_API_KEY;
4const client = new SchematicClient({ apiKey });
5
6client.track({
7    event: "some-action",
8    company: {
9        id: "your-company-id",
10    },
11    user: {
12        email: "wcoyote@acme.net",
13        userId: "your-user-id",
14    },
15});
16
17client.close();

This call is non-blocking and there is no response to check.

Creating and updating companies

Although it is faster to create companies and users via identify events, if you need to handle a response, you can use the companies API to upsert companies. Because you use your own identifiers to identify companies, rather than a Schematic company ID, creating and updating companies are both done via the same upsert operation:

1import { SchematicClient } from "@schematichq/schematic-typescript-node";
2
3const apiKey = process.env.SCHEMATIC_API_KEY;
4const client = new SchematicClient({ apiKey });
5
6const body = {
7    keys: {
8        id: "your-company-id",
9    },
10    name: "Acme Widgets, Inc.",
11    traits: {
12        city: "Atlanta",
13        highScore: 25,
14        isActive: true,
15    },
16};
17
18client.companies
19    .upsertCompany(body)
20    .then((response) => {
21        console.log(response.data);
22    })
23    .catch(console.error);
24
25client.close();

You can define any number of company keys; these are used to address the company in the future, for example by updating the company’s traits or checking a flag for the company.

You can also define any number of company traits; these can then be used as targeting parameters.

Creating and updating users

Similarly, you can upsert users using the Schematic API, as an alternative to using identify events. Because you use your own identifiers to identify users, rather than a Schematic user ID, creating and updating users are both done via the same upsert operation:

1import { SchematicClient } from "@schematichq/schematic-typescript-node";
2
3const apiKey = process.env.SCHEMATIC_API_KEY;
4const client = new SchematicClient({ apiKey });
5
6const body = {
7    keys: {
8        email: "wcoyote@acme.net",
9        userId: "your-user-id",
10    },
11    company: { id: "your-company-id" },
12    name: "Wile E. Coyote",
13    traits: {
14        city: "Atlanta",
15        loginCount: 24,
16        isStaff: false,
17    },
18};
19
20client.companies
21    .upsertUser(body)
22    .then((response) => {
23        console.log(response.data);
24    })
25    .catch(console.error);
26
27client.close();

You can define any number of user keys; these are used to address the user in the future, for example by updating the user’s traits or checking a flag for the user.

You can also define any number of user traits; these can then be used as targeting parameters.

Checking flags

When checking a flag, you’ll provide keys for a company and/or keys for a user. You can also provide no keys at all, in which case you’ll get the default value for the flag.

1import { SchematicClient } from "@schematichq/schematic-typescript-node";
2
3const apiKey = process.env.SCHEMATIC_API_KEY;
4const client = new SchematicClient({ apiKey });
5
6const evaluationCtx = {
7    company: { id: "your-company-id" },
8    user: {
9        email: "wcoyote@acme.net",
10        userId: "your-user-id",
11    },
12};
13
14client
15    .checkFlag(evaluationCtx, "some-flag-key")
16    .then((isFlagOn) => {
17        if (isFlagOn) {
18            // Flag is on
19        } else {
20            // Flag is off
21        }
22    })
23    .catch(console.error);
24
25client.close();

Other API operations

The Schematic API supports many operations beyond these, accessible via the API modules on the client, Accounts, Billing, Companies, Entitlements, Events, Features, and Plans.

Testing

Offline mode

In development or testing environments, you may want to avoid making network requests to the Schematic API. You can run Schematic in offline mode by specifying the offline option; in this case, it does not matter what API key you specify:

1import { SchematicClient } from "@schematichq/schematic-typescript-node";
2
3const client = new SchematicClient({ offline: true });
4
5client.close();

Offline mode works well with flag defaults:

1import { SchematicClient } from "@schematichq/schematic-typescript-node";
2
3const client = new SchematicClient({
4    flagDefaults: { "some-flag-key": true },
5    offline: true,
6});
7
8// interactions with the client
9
10client.close();