Jarvis Catalyst Custom App SDK

Table of Contents

1. Install
2. Quick Start
3. API Reference
   • Constants
   • Utilities
   • Permissions
   • Channel
   • Types
4. Examples
5. Development

1. Install

npm install @jarvis-catalyst/custom-app-sdk

2. Quick Start

import { permissions, utils, channel, DEV } from '@jarvis-catalyst/custom-app-sdk'

// check a “read” scope on “tenant”
const allowed = permissions.utils.hasPermissionAndHasSomeScopes(
	userPermissions, // from your Redux store
	'tenant', // scope
	'assets.mgmt', // permission key
	['read'], // required scopes
)

// resolve base URL for apis
const apiBase = utils.getBaseUrl(process.env)

// dispatch an application context change
dispatch(channel.store.actions.setApplicationContextAction({ localeChange: { locale: 'en' } }))

// detect dev mode
if (process.env.NODE_ENV === DEV) {
	/* … */
}

3. API Reference

Constants

• DEV: the string 'dev' for environment checks.

Utilities

import { utils } from '@jarvis-catalyst/custom-app-sdk'

• utils.getBaseUrl(env: any): string
  Build your app’s base URL from environment.

• utils.getEnv(): string
  Read the current runtime environment.

Permissions

import { permissions } from '@jarvis-catalyst/custom-app-sdk'

• permissions.utils.hasPermission(userPermissions, scope, permission): boolean
• permissions.utils.hasPermissionAndHasScopes(userPermissions, scope, permission, values[]): boolean
• permissions.utils.hasPermissionAndHasSomeScopes(userPermissions, scope, permission, values[]): boolean

Channel

import { channel, eventTypes, commandTypes } from '@jarvis-catalyst/custom-app-sdk'

• channel.Channel — the main communication class.
• eventTypes — { APPLICATION_LOADED, TENANT_CHANGE, … }
• commandTypes — { PUSH_NAVIGATION_HISTORY, DISPLAY_NOTIFICATION, … }
• channel.store.reducer — your app’s context reducer.
• channel.store.actions.setApplicationContextAction(payload) — dispatch context updates.
• channel.ui.sendNotification({...}) — trigger in-app banners.
• channel.ui.setSidebar(…), channel.ui.setModalOverlay(…) — open UI overlays.

Types

import type { ContextApplication, SendNotification, UserPermissionsChanged } from '@jarvis-catalyst/custom-app-sdk'

• ContextApplication — full shape of your Redux context.
• SendNotification — payload for notifications.
• UserPermissionsChanged — structure of permission payloads.

4. Examples

Simple Permission Check

import { permissions } from '@jarvis-catalyst/custom-app-sdk'

if (
	permissions.utils.hasPermissionAndHasScopes(userPermissions, 'tenant', 'up.test.permission', ['cat2020', 'cat2021'])
) {
	console.log('user may proceed')
}

Sending a Notification

import { channel } from '@jarvis-catalyst/custom-app-sdk'

channel.ui.sendNotification({
	level: 'success',
	timeout: 5000,
	message: { title: 'Saved!', text: 'Your changes were stored.' },
})

5. Development

git clone [email protected]:catalyst/core/pat/development/jarvis-catalyst-custom-app-sdk.git
cd custom-app-sdk
npm ci
npm run lint
npm run test
npm run build

• npm run lint — ESLint
• npm run test — Vitest
• npm run build — tsup → dist/