@omni-gate/frame-core

The shared core utilities and constants package for the Omni Gate frame-bridge SDK ecosystem.

This package contains shared protocol constants, permission helpers, the REST proxy base class, and internationalization resources used by both @omni-gate/frame-client-sdk and @omni-gate/frame-parent-sdk.

简体中文 | English

Installation

npm install @omni-gate/frame-core

Note: Both @omni-gate/frame-client-sdk and @omni-gate/frame-parent-sdk depend on and re-export this package. Sub-applications and shell applications generally do not need to install @omni-gate/frame-core directly.

Exports Overview

• constants: Protocol message types, window commands, broadcast event names, cache TTLs, and configuration types (OmniFrameOptions, OmniTokenOptions, BRIDGE_MESSAGES, BROADCAST_MESSAGES, STORAGE_KEYS, CACHE_TTL, DEFAULT_OPTIONS).
• Permissions: Helper class for verifying flat and nested dot-notation user permissions.
• BaseRestServiceProxy: Abstract base class for wrapping @ticatec/restful_service_api with automatic JWT token attachment, language headers, and centralized error handling.
• i18nRes: Reactive internationalization resource proxy for frame-bridge error/prompt texts.

API Reference

1. Permissions

A lightweight helper for checking user permissions, typically used to control the visibility or enabled state of UI elements (buttons, menu items, actions) on the frontend.

import { Permissions } from '@omni-gate/frame-core';

// Construct from a permission map (usually from getPermission() / getEntityPermission()),
// or with no argument for an empty permission set.
const permissions = new Permissions({
  'user-management': {
    maintain: true,
    delete: false
  },
  'role-management.view': true
});

// Flat and dot-notation checking
permissions.has('user-management.maintain'); // true
permissions.has('user-management.delete');   // false
permissions.has('user-management.create');   // false (key not present)
permissions.has('role-management.view');     // true

Checking rules

• A permission is granted only when its value is exactly true.
• undefined, null, false, or any other value is treated as not granted.
• has() accepts a dot-notation path (e.g. 'user-management.maintain') and walks nested objects level by level.

Notes

• Permissions only offers a convenient client-side lookup; it does not fetch or manage permission data itself. In the parent/shell app, permission data is typically retrieved from the backend and cached by OmniParentApi (see @omni-gate/frame-parent-sdk).
• Treat this as a UI-level convenience, not a security boundary — always re-validate sensitive operations on the backend, since cached permission data can become stale.

2. BaseRestServiceProxy

An abstract base class for configuring and invoking RESTful services with automatic JWT and language headers.

import { BaseRestServiceProxy, RestServiceBuilder } from '@omni-gate/frame-core';
import RestService from '@ticatec/restful_service_api';

class MyServiceProxy extends BaseRestServiceProxy {
  constructor(builder: RestServiceBuilder) {
    super(builder, {
      jwtStorage: sessionStorage,
      jwtStorageKey: 'omni-token'
    });
  }

  protected errorHandler(ex: Error): boolean {
    console.error('API Error:', ex);
    return true;
  }
}

const proxy = new MyServiceProxy(
  (errorHandler, preInterceptor) => new RestService('https://api.example.com', errorHandler, preInterceptor)
);

const data = await proxy.service.get('/api/users');

BaseRestServiceProxy is abstract — the only thing a subclass must implement is errorHandler(). The constructor and options (jwtStorage/jwtStorageKey) are optional; omit options entirely to use the defaults (sessionStorage / 'omni-token').

3. Constants

import {
  BRIDGE_MESSAGES,
  BROADCAST_MESSAGES,
  STORAGE_KEYS,
  CACHE_TTL,
  DEFAULT_OPTIONS
} from '@omni-gate/frame-core';

• BRIDGE_MESSAGES: OPEN_MODULE, HEARTBEAT, GET_TOKEN, GET_ME, GET_PERMISSION, GET_OPTIONS_DATA, GET_CHILDREN_OPTIONS, GET_ENTITY_PERMISSION, GET_ERROR_MESSAGES, GET_CURRENT_LANGUAGE.
• BROADCAST_MESSAGES: THEME_CHANGED, LOGOFF, TOKEN_CHANGED.
• STORAGE_KEYS: ME, JWT_TOKEN, PERMISSION_PREFIX, DICTIONARY_PREFIX, MESSAGE_PREFIX, LANGUAGE.
• CACHE_TTL: Default TTL values for permission, options, and messages.

License

MIT