@byterm/agc-sdk

A typed Node.js + TypeScript client for the AppGallery Connect (AGC) API, using Service Account authentication. Part of the agc-ts monorepo — see also @byterm/agc-cli for the command-line tool.

Requirements

• Node.js >= 18 (uses the built-in fetch and WebCrypto)

Install

npm i @byterm/agc-sdk

Authentication (Service Account + API Client for PMS)

1. In AGC → Users and permissions → API key → Connect API → Service Account, create a developer-level Service Account and download the *.private.json credential file.
2. Pass that file to AgcClient.fromFile(...).

The SDK signs a PS256 JWT (RSASSA-PSS, SHA-256) from key_id, sub_account and private_key, and sends it directly as Authorization: Bearer <jwt>. Tokens are cached and refreshed automatically (1 h lifetime, refreshed ~5 min early). There is no separate token-exchange step for Service Account auth.

PMS is the exception: it rejects Service Account JWTs (401) and requires an API Client (OAuth2 client_credentials exchange against /api/oauth2/v1/token, ~48 h tokens). The API Client must be team-level (project = N/A) with an administrator role — a project-scoped client gets 403 on every PMS call. Pass it via new AgcClient({ credentials, apiClient }) or AgcClient.fromApiClientFile(path).

Keep the credential file secret — never commit it.

Usage

import { AgcClient } from '@byterm/agc-sdk';

const agc = AgcClient.fromFile('./my-key.private.json', { site: 'CN' });

const res = await agc.publishing.getAppInfo({ appId: '1234567890', lang: 'zh-CN' });
console.log(res.appInfo?.versionNumber);

// Upload a package and bind it
const { objectId } = await agc.upload.uploadFile({ appId: '1234567890', filePath: './app.app' });
await agc.publishing.updatePackageInfo('1234567890', { fileName: 'app.app', objectId });
await agc.publishing.submitPublish({ appId: '1234567890' });

Errors are typed: AgcCredentialsError, AgcHttpError (transport/non-2xx), AgcApiError (2xx with non-zero ret.code). The client automatically checks the ret envelope and throws AgcApiError on business failures.

Resource coverage

agc.publishing, agc.provisioning, agc.testing, agc.reports, agc.upload, agc.domain, agc.pms — covering the Publishing, Provisioning, Testing, Reports, Upload Management, Domain Management and PMS (digital product management) API groups. Method names map 1:1 to AGC endpoints. For anything not yet wrapped, drop to the raw client: agc.http.get(...) / .post(...) etc., which still applies auth and the ret check.

PMS uses the { error: { errorCode, errorMsg } } envelope instead of ret (non-zero errorCode throws AgcApiError) and requires API Client auth (see Authentication above) — every request carries Authorization: Bearer <access_token> plus client_id (the API Client's id) and appId headers.

Region sites

| Site | Domain | | --- | --- | | CN | connect-api.cloud.huawei.com | | DE | connect-api-dre.cloud.huawei.com | | SG | connect-api-dra.cloud.huawei.com | | RU | connect-api-drru.cloud.huawei.com |

The site must match the project's configured data-processing location.

License

MIT © Term