market-app-web-sdk

@cregis/market-app-web-sdk is the reusable frontend integration layer for App Market third-party web applications.

It extracts the non-business browser-side logic that used to live inside the demo app, including:

1. SSO bridge flow
2. Local auth state storage
3. Axios auth interception and re-auth trigger
4. Route guard and visible-menu navigation
5. App shell layout and menu refresh
6. App-scoped permission helpers

Environment

1. Node.js 18+
2. npm 9+
3. Vue 3 application

Install

Use a local file dependency during local development:

npm install @cregis/market-app-web-sdk

Or declare it in package.json:

{
  "dependencies": {
    "@cregis/market-app-web-sdk": "1.0.0"
  }
}

Peer dependencies expected by the SDK:

1. vue
2. vue-router
3. axios
4. element-plus

Build

npm install
npm run build

Core Exports

Root exports:

1. createMarketAppHttp
2. installMarketAppRouteGuard
3. useMarketAppPermission
4. useMarketAppAnyPermission
5. useMarketAppShell
6. useMarketAppSsoBridge
7. MarketAppShell
8. MarketAppSsoBridge

Auth APIs:

1. bootstrapLogin
2. getCurrentMenuAccess
3. getCurrentDataPermission
4. getCurrentMenus
5. getPlatformUsers
6. getPlatformRoles

Minimal Integration

1. HTTP client

import { createMarketAppHttp } from '@cregis/market-app-web-sdk'

const http = createMarketAppHttp()

The SDK reads VITE_MARKET_APP_SERVER_URL as the backend base URL.

2. Route guard

import { createRouter, createWebHistory } from 'vue-router'
import { installMarketAppRouteGuard } from '@cregis/market-app-web-sdk'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/', redirect: '/sso-bridge' },
    { path: '/sso-bridge', component: SsoBridge },
    { path: '/classes', component: ClassManager, meta: { menuAccess: ['class:query'] } },
  ],
})

installMarketAppRouteGuard(router)

Business pages only declare the permission suffix such as class:query.
The SDK automatically resolves and matches the current appId: prefix.

3. SSO bridge page

<template>
  <MarketAppSsoBridge
    :bootstrap-login="bootstrapLogin"
    :fetch-menu-access="getCurrentMenuAccess"
    :fetch-data-permission="getCurrentDataPermission"
    :fetch-menus="getCurrentMenus"
  />
</template>

4. App shell

<template>
  <MarketAppShell
    app-title="Demo App"
    :fetch-menu-access="getCurrentMenuAccess"
    :fetch-menus="getCurrentMenus"
  >
    <router-view />
  </MarketAppShell>
</template>

5. Button permission

import { useMarketAppPermission } from '@cregis/market-app-web-sdk'

const canCreateClass = useMarketAppPermission('class:create')

Runtime Contract

The SDK expects the backend to provide these endpoints:

1. POST /api/auth/bootstrap
2. GET /api/auth/menu-access
3. GET /api/auth/data-permission
4. GET /api/auth/menus
5. GET /api/auth/users
6. GET /api/auth/roles

The default auth flow is:

1. Parent admin page loads the app iframe with ticket and appCode
2. SSO bridge calls backend /api/auth/bootstrap
3. Backend exchanges ticket with marketing and returns local demoToken
4. SDK fetches menu access, data permission, and visible menus
5. Route guard and shell render the visible pages

Re-Auth Behavior

When backend returns an auth-expired code, the SDK will:

1. Clear local auth state
2. Notify parent page by postMessage
3. Ask the parent admin page to refresh ticket
4. Redirect current iframe page to /sso-bridge

Default message types:

1. APP_MARKET_REFRESH_TICKET
2. APP_MARKET_AUTH_STATE

Configuration

Default configuration is defined in src/config.ts:

1. demoServerUrl
2. refreshTicketMessageType
3. authStateMessageType
4. reAuthThrottleMs

Default backend URL:

VITE_MARKET_APP_SERVER_URL || http://192.168.2.231:8088

For local development, set:

VITE_MARKET_APP_SERVER_URL=http://127.0.0.1:8088

Related Documents

1. Chinese integration guide
2. English integration guide