Javascript Client Library

@appteum-js

This reference documents every object and method available in Appteum's JavaScript library, appteum-js. You can use appteum-js to interact with your workspace data, and build login and user management functionality.

Installing

Install as package

You can install @appteun/appteum-js via the terminal.

npm install @appteum/appteum-js

Initializing

You can initialize a new Appteum client using the AppteumWorkspaceClient() class.

The Appteum client is your entrypoint to the rest of the Appteum functionality and is the easiest way to interact with everything we offer within the Appteum platform.

import { AppteumWorkspaceClient } from "@appteum/appteum-js";

WorkspaceClient Parameters

API Key

Use API Key scoped clients to call Auth and Object services.

⚠️ API Key scoped clients use the Anonymous User by default: You should treat the Anonymous User with caution, limiting access to data you are willing to expose publicly.

import { AppteumWorkspaceClient } from "@appteum/appteum-js";

const apiKeyScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
});

API Key & ID Token

Use API Key and Token scoped clients to call object services.

import { AppteumWorkspaceClient } from "@appteum/appteum-js";

const apiKeyIdAccessTokenScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
  idToken: "<JWT_ID_TOKEN>",
});

API Key & ID / ACCESS Token

Use API Key, id Token and access Token scoped clients to change workspace users password.

import { AppteumWorkspaceClient } from "@appteum/appteum-js";

const apiKeyIdAccessTokenScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
  idToken: "<JWT_ID_TOKEN>",
  accessToken: "<JWT_ACCESS_TOKEN>",
});

Auth

Sign-Up

To create a user, you need to provide the profileId of one of the profiles that exists in your workspace.

import { AppteumWorkspaceClient } from "@appteum/appteum-js";
import { ServiceResponse } from "@appteum/appteum-js/api";

const apiKeyScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
});

const signUp: ServiceResponse = await apiKeyScopedClient.auth.signUp({
  email: "",
  password: "",
  profileId: "", // -> can be retrieved from appteum administration panel
});

Confirm Sign-Up

Once you sign-up a user they will receive an email with a confirmation code in order to verify their email address before logging in.

import { AppteumWorkspaceClient } from "@appteum/appteum-js";
import { ActionResponse } from "@appteum/appteum-js/api";

const apiKeyScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
});

const confirmSignUp: ActionResponse =
  await apiKeyScopedClient.auth.confirmSignUp({
    email: "",
    confirmationCode: "", //-> sent to workspace users email on sign up
  });

Resend Confirmation Code

import { AppteumWorkspaceClient } from "@appteum/appteum-js";
import { ActionResponse } from "@appteum/appteum-js/api";

const apiKeyScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
});

const resendCode: ActionResponse =
  await apiKeyScopedClient.auth.resendConfirmationCode({
    email: "",
  });

Sign-In

Log in an existing user with an email and password.

import { AppteumWorkspaceClient } from "@appteum/appteum-js";
import { SignInResponse } from "@appteum/appteum-js/api";

const apiKeyScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
});

const signIn: SignInResponse = await apiKeyScopedClient.auth.signIn({
  email: "",
  password: "",
});

Temporary Password Sign-In

info

Valid only for workspace users invited from the appteum admin panel and have received temporary password in their emails.

import { AppteumWorkspaceClient } from "@appteum/appteum-js";
import { SignInResponse } from "@appteum/appteum-js/api";

const apiKeyScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
});

const signIn: SignInResponse =
  await apiKeyScopedClient.auth.temporaryPasswordSignIn({
    email: "",
    temporaryPassword: "", // ->  sent to workspace users email on workspace user invitation from appteums admin panel
    password: "",
  });

Forgot Password Request

import { AppteumWorkspaceClient } from "@appteum/appteum-js";
import { ActionResponse } from "@appteum/appteum-js/api";

const apiKeyScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
});

const forgotPassword: ActionResponse =
  await apiKeyScopedClient.auth.forgotPassword({
    email: "",
  });

Confirm Forgot Password Request

import { AppteumWorkspaceClient } from "@appteum/appteum-js";
import { ActionResponse } from "@appteum/appteum-js/api";

const apiKeyScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
});

const confirmForgotPassword: ActionResponse =
  await apiKeyScopedClient.auth.confirmForgotPassword({
    password: "",
    confirmationCode: "", // ->  sent to workspace users email on Forgot Password Request
    email: "",
  });

Refresh JWT Token

import { AppteumWorkspaceClient } from "@appteum/appteum-js";
import { RefreshTokenResponse } from "@appteum/appteum-js/api";

const apiKeyScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
});

const refreshJWtToken: RefreshTokenResponse =
  await apiKeyScopedClient.auth.refreshToken({
    refreshToken: signIn.auth.refreshToken,
  });

Change User Password

import { AppteumWorkspaceClient } from "@appteum/appteum-js";
import { ActionResponse } from "@appteum/appteum-js/api";

const apiKeyTokenScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
  idToken: `Bearer <JWT_ID_TOKEN>`,
  accessToken: "<JWT_ACCESS_TOKEN>",
});
const changeUserPassword: ActionResponse =
  await apiKeyTokenScopedClient.auth.changePassword({
    previousPassword: "",
    newPassword: "",
  });

Objects

👉 Object services can be used with API Key scoped or API Key and Token scoped clients.

Query Data

Perform a query on the object or relations.

• By default, Appteum returns a maximum of 100 rows. You can use the DataCursor method to paginate through your data.
• For the query syntax check the API Query Syntax Docs

import { AppteumWorkspaceClient } from "@appteum/appteum-js";
import { CursorResponse } from "@appteum/appteum-js/api";

const apiKeyTokenScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
  idToken: `Bearer <JWT_ID_TOKEN>`, // -> remove to use with anonymous user
});

const dataQueryResult: CursorResponse =
  await apiKeyTokenScopedClient.objects.data({
    q: "select first_name, last_name from users",
  });

Query Data Cursor

Use the DataCursor to paginate through your object data.

import { AppteumWorkspaceClient } from "@appteum/appteum-js";
import { CursorResponse } from "@appteum/appteum-js/api";

const apiKeyTokenScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
  idToken: `Bearer <JWT_ID_TOKEN>`, // -> remove to use with anonymous user
});
const dataQueryResult: CursorResponse =
  await apiKeyTokenScopedClient.objects.data({
    q: "select first_name, last_name from users",
  });

const objectBatchData: CursorResponse =
  await apiKeyTokenScopedClient.objects.dataCursor(
    dataQuery.cursor.nextDataCursor,
    { xQueryBatchSize: "100" }
  );

Create Data

👉 Can be used to create single or multiple records. Max number of records per request is 200.

info

name is a mandatory field for all objects.

import { AppteumWorkspaceClient } from "@appteum/appteum-js";
import { ServiceResponse } from "@appteum/appteum-js/api";
const apiKeyTokenScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
  idToken: `Bearer <JWT_ID_TOKEN>`, // -> remove to use with anonymous user
});

const createObjectDataRecord: ServiceResponse =
  await apiKeyTokenScopedClient.objects.create("users", {
    dataRecords: [
      // -> max array size 200
      {
        name: "John Doe", // -> mandatory field for all objects
        first_name: "John",
        last_name: "Doe",
      },
      {
        name: "John Smith", // -> mandatory field for all objects
        first_name: "John",
        last_name: "Smith",
      },
    ],
  });

Delete Data

import { AppteumWorkspaceClient } from "@appteum/appteum-js";
import { ServiceResponse } from "@appteum/appteum-js/api";

const apiKeyTokenScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
  idToken: `Bearer <JWT_ID_TOKEN>`, // -> remove to use with anonymous user
});

const deleteObjectDataRecord: ServiceResponse =
  await apiKeyTokenScopedClient.objects.delete(
    "<OBJECT_NAME>",
    "<OBJECT_DATA_RECORD_ID>"
  );

Update Data

import { AppteumWorkspaceClient } from "@appteum/appteum-js";
import { ServiceResponse } from "@appteum/appteum-js/api";

const apiKeyTokenScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
  idToken: `Bearer <JWT_ID_TOKEN>`, // -> remove to use with anonymous user
});

const updateRecordRequest: UpdateRecordRequest = {
  rowVersion: "<RECORD_ROW_VERSION>",
  dataRecord: {
    first_name: "", //-> record property to update
  },
};

const updateObjectDataRecord: ServiceResponse =
  await apiKeyTokenScopedClient.objects.update(
    "<OBJECT_NAME>",
    "<RECORD_ID>",
    updateRecordRequest
  );

Describe Object

import { AppteumWorkspaceClient } from "@appteum/appteum-js";
import { ObjectDescribeResponse } from "@appteum/appteum-js/api";

const apiKeyIdAccessTokenScopedClient = new AppteumWorkspaceClient({
  apiKey: "<API_KEY>",
  idToken: `Bearer <JWT_ID_TOKEN>`, // -> remove to use with anonymous user
});

const objectDescribeResponse: ObjectDescribeResponse =
  await apiKeyTokenScopedClient.objects.describe("<OBJECT_NAME>");