market-app-web-sdk

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

What it provides

1. SSO bridge flow
2. Local auth state storage
3. HTTP auth interception and re-auth trigger
4. Route guard and visible-menu navigation
5. App shell layout helpers
6. App-scoped permission helpers
7. Third-party-mode route and permission adaptation

Install

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

Quick Start

1. Initialize the SDK

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

initCregisMarketAppConfig({
  sdkServerUrl: import.meta.env.VITE_MARKET_APP_SERVER_URL || 'http://127.0.0.1:48088',
})

Notes:

1. In third-party mode, sdkServerUrl should point to the real third-party backend
2. In internal mode, the SDK automatically resolves the API base to {origin}/app-market-api/{appCode}
3. Frontends must never hold appThirdId/appSecret
4. If the backend wants to push API errors to marketing by default, set app-market.app-api-error-enabled=true in the server SDK config

2. Create an HTTP client

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

export const http = createMarketAppHttp()

The backend is expected to return the standard structure below on success:

{
  "code": 200,
  "msg": "success",
  "data": {}
}

Using MarketAppCommonResult<T> from marketing-app-security-sdk is recommended, but any backend response with the same JSON shape is also supported.

3. Install the route guard

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

installMarketAppRouteGuard(router)

4. Use the SSO bridge

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

Mode Detection

The SDK decides the runtime mode from the current path:

1. /app-market/{appCode}/... -> internal mode
2. Anything else -> third-party mode

In internal mode, the SDK automatically:

1. Resolves the router base to /app-market/{appCode}
2. Resolves the API base to {origin}/app-market-api/{appCode}

In third-party mode, the SDK uses the configured sdkServerUrl.

Permission Convention

Business pages are expected to declare permission suffixes, for example:

meta: { menuAccess: ['class:query'] }

The SDK automatically matches them against the current app-scoped permission set.

Environment Variable

Default env variable:

1. VITE_MARKET_APP_SERVER_URL

Security Rules

1. Do not expose appThirdId/appSecret to the frontend
2. Do not call normal marketing admin APIs from the third-party frontend
3. Keep backend authorization checks even when buttons are hidden in the UI
4. Keep the backend allow-origins list aligned with the real page origins

Docs

Unified documents:

1. docs/三方独立应用接入.md
2. docs/三方独立应用架构设计文档.md