zephyr-agent
Version:
Zephyr plugin agent
508 lines (466 loc) • 19.7 kB
text/typescript
/** Categories for all error codes. */
export declare const ZeErrorCategories: {
/** Error we have yet catched and known */
readonly unknown: '00';
/** Stage 0 build error */
readonly build: '10';
/** Stage 1 Deployment error */
readonly deploy: '20';
/** Browser error */
readonly browser: '30';
/** Module Federation/Config related error */
readonly config: '40';
};
/**
* A collection of error types and the error code during local/build stage
*
* If you are searching for an error globally, if it is a build related error, it starts
* with `ZE10`, if it's a deployment related error, search for `ZE20` and then followed
* with their ID.
*
* - `ZE` at the front is a constant
* - Two digits at the middle PP (`10` for build error or `20` for deployment error) is
* their categories,
* - Last three digits is their ID.
*
* For example, if you have a `SNAPSHOT_NOT_FOUND` error, search for `ZE20023`, if you see
* an error showing up on terminal or application, the last three numbers are their IDs.
* We might extend to have more errors in the future.
*/
export declare const ZeErrors: {
readonly ERR_UNKNOWN: {
readonly id: '000';
readonly message: `
Unknown error: {{ message }}
`;
readonly kind: 'unknown';
};
/** Package.json not found error */
readonly ERR_PACKAGE_JSON_NOT_FOUND: {
readonly id: '010';
readonly message: 'package.json not found';
readonly kind: 'build';
};
/** Package.json is not in a valid json format */
readonly ERR_PACKAGE_JSON_NOT_VALID: {
readonly id: '011';
readonly message: 'Package.json is not in a valid json format.';
readonly kind: 'build';
};
/** Webpack config error */
readonly ERR_WEBPACK_CONFIG: {
readonly id: '012';
readonly message: 'Webpack config error.';
readonly kind: 'build';
};
readonly ERR_PACKAGE_JSON_MUST_HAVE_NAME: {
readonly id: '013';
readonly message: 'Zephyr needs package.json at {{ path }} to have a name field to map your application configuration in deployment.';
readonly kind: 'build';
};
readonly ERR_PACKAGE_JSON_MISSING_VERSION: {
readonly id: '025';
readonly message: 'package.json at {{ path }} is missing a version field. Zephyr defaulted the version to {{ defaultVersion }}.';
readonly kind: 'build';
};
readonly ERR_GIT_REMOTE_ORIGIN: {
readonly id: '014';
readonly message: `
Could not detect a git remote called 'origin'. This is required for Zephyr to work properly.
Please set the git remote origin by running the following command:
\`\`\`sh
git init
git remote add origin <url>
\`\`\`
`;
readonly kind: 'build';
};
/** Git username or email is not configured. */
readonly ERR_NO_GIT_USERNAME_EMAIL: {
readonly id: '015';
readonly message: `
Git username or email is not configured:
- please set valid 'git config user.name' and 'git config user.email'
- or provide ZE_USER_TOKEN as environment variable
`;
readonly kind: 'build';
};
/** Could not get git info */
readonly ERR_NO_GIT_INFO: {
readonly id: '016';
readonly message: `
Failed to load git information:
{{ message }}
`;
readonly kind: 'build';
};
/** Build error application_uid missing. */
readonly ERR_MISSING_APPLICATION_UID: {
readonly id: '017';
readonly message: '`application_uid` missing.';
readonly kind: 'build';
};
/** Auth error */
readonly ERR_AUTH_ERROR: {
readonly id: '018';
readonly message: `
Zephyr authentication is missing, invalid, or expired.
Run the deployment in an interactive terminal to complete normal browser login, or provide a valid authentication token in non-interactive environments.
{{ message }}
`;
readonly kind: 'build';
};
readonly ERR_GET_BUILD_ID: {
readonly id: '019';
readonly message: `
Could not create a Build ID for {{ application_uid }} as {{ username }}.
Review the reported reason below. Authentication, target access, and service availability require different recovery actions.
`;
readonly kind: 'build';
};
/** Could not initialize Zephyr Agent. */
readonly ERR_INITIALIZE_ZEPHYR_AGENT: {
readonly id: '020';
readonly message: 'Could not initialize Zephyr Agent.';
readonly kind: 'build';
};
/** Cloudflare specific error */
readonly ERR_UNABLE_CREATE_DIST_FOLDER: {
readonly id: '021';
readonly message: 'Error creating dist folder.';
readonly kind: 'build';
};
/** Auth forbidden error */
readonly ERR_AUTH_FORBIDDEN_ERROR: {
readonly id: '022';
readonly message: `
The authenticated Zephyr account is not allowed to access the requested target.
Verify the application target and account, or ask an organization administrator for access. Reconfiguring Git will not grant target access.
{{ message }}
`;
readonly kind: 'build';
};
/**
* Module federation configuraiton error, throw full stop if configuration is invalid -
* specifically for React Native.
*
* Reference:
* https://github.com/web-infra-dev/rspack/blob/5848d8bbb0434409aab33a4c677eb2afb52c5564/crates/rspack_plugin_library/src/assign_library_plugin.rs#L222
*/
readonly ERR_INVALID_MF_CONFIG: {
readonly id: '023';
readonly message: `Library name {{library_name}} must be a valid identifier when using "var" as library type in Module Federation configuration. Either use a valid identifier (e. g. {base_identifier}) or use a different library type (e. g. type: 'global', which assign a property on the global scope instead of declaring a variable). To see a list of valid identifiers, please refer to:
- Mozilla's documentation on identifiers: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#identifiers
- The list of Module Federation's available library type: https://github.com/module-federation/core/blob/ae5ee1eedad4565774ea82e30b3d0df7c9921c58/webpack/declarations/WebpackOptions.d.ts#L112
You can change the library name to CamelCase to avoid this error.`;
readonly kind: 'build';
};
readonly ERR_INVALID_APP_ID: {
readonly id: '024';
readonly message: `Invalid application_uid: {{application_uid}}. Your application_uid is a combination of:
- git organization name
- git user name
- name in package.json (They should be the same in your Module Federation configuration if there is any).
Please make sure you have set them correctly in your package.json and git repository. The application_uid will be used to assign subdomain for your application. Read more about the standard of what characters are allowed in domain names in IETF: https://datatracker.ietf.org/doc/html/rfc1035#:~:text=The%20labels%20must%20follow%20the%20rules%20for%20ARPANET%20host%20names.%20%20They%20must%0Astart%20with%20a%20letter%2C%20end%20with%20a%20letter%20or%20digit%2C%20and%20have%20as%20interior%0Acharacters%20only%20letters%2C%20digits%2C%20and%20hyphen.%20%20There%20are%20also%20some%0Arestrictions%20on%20the%20length.%20%20Labels%20must%20be%2063%20characters%20or%20less.`;
readonly kind: 'build';
};
/** Deployment error, assets not found */
readonly ERR_ASSETS_NOT_FOUND: {
readonly id: '010';
readonly message: 'Assets not found.';
readonly kind: 'deploy';
};
/** Assets not found in snapshot */
readonly ERR_ASSETS_NOT_FOUND_IN_SNAPSHOT: {
readonly id: '011';
readonly message: 'Assets not found in snapshot.';
readonly kind: 'deploy';
};
/** Application_uid missing */
readonly ERR_DEPLOY_MISSING_APPLICATION_UID: {
readonly id: '012';
readonly message: '`application_uid` is required.';
readonly kind: 'deploy';
};
readonly ERR_MISSING_FILE_HASH: {
readonly id: '013';
readonly message: 'Missing file hash.';
readonly kind: 'deploy';
};
/** Failed to load application configuration. */
readonly ERR_LOAD_APP_CONFIG: {
readonly id: '014';
readonly message: `
Failed to load Application Configuration for {{ application_uid }}.
Review the reported reason below before retrying. Do not print, export, or share credential-file contents.
`;
readonly kind: 'deploy';
};
/** SSR entrypoint could not be detected from output assets. */
readonly ERR_SSR_ENTRYPOINT_NOT_FOUND: {
readonly id: '015';
readonly message: `
Could not detect SSR entrypoint in {{ outputDir }}.
Expected one of: {{ candidates }}.
`;
readonly kind: 'deploy';
};
/** Did not receive envs from build stats upload */
readonly ERR_NOT_RECEIVE_ENVS_FROM_BUILD_STATS: {
readonly id: '016';
readonly message: 'Did not receive envs from build stats upload.';
readonly kind: 'deploy';
};
/** Failed to upload assets. */
readonly ERR_FAILED_UPLOAD: {
readonly id: '017';
readonly message: `
Could not upload {{ type }} to your Edge Provider. This error will affect your tags and environments and it might fail deployments to custom domains.
Please check your network connection and try again.
`;
readonly kind: 'deploy';
};
/** Snapshot uploads gave no results. */
readonly ERR_SNAPSHOT_UPLOADS_NO_RESULTS: {
readonly id: '019';
readonly message: 'Snapshot uploads gave no results.';
readonly kind: 'deploy';
};
/** Failed to get application hash list */
readonly ERR_GET_APPLICATION_HASH_LIST: {
readonly id: '020';
readonly message: 'Failed to get application hash list.';
readonly kind: 'deploy';
};
readonly ERR_SNAPSHOT_ID_NOT_FOUND: {
readonly id: '022';
readonly message: '`snapshot_id` not found.';
readonly kind: 'deploy';
};
readonly ERR_SNAPSHOT_NOT_FOUND: {
readonly id: '023';
readonly message: 'Snapshot not found.';
readonly kind: 'deploy';
};
readonly ERR_DEPLOY_LOCAL_BUILD: {
readonly id: '024';
readonly message: `
Failed to deploy local build.
{{ message }}
`;
readonly kind: 'deploy';
};
/** Cloudflare specific error */
readonly ERR_WRANGLER_DEPENDENCY: {
readonly id: '025';
readonly message: 'Wrangler dependency is needed for Cloudflare deployment. Please install dependencies without --no-optional flag.';
readonly kind: 'deploy';
};
readonly ERR_CONVERT_GRAPH_TO_DASHBOARD: {
readonly id: '026';
readonly message: `
Failed to convert federation configuration to needed information. We are reading your Module Federation configuration to understand your shared dependencies:
- host application's name
- remote application's name
- shared dependencies.
Please refer to the official Module Federation guide https://module-federation.io/configure/index.html to make sure your have required inputs.
`;
readonly kind: 'browser';
};
readonly ERR_UPLOAD_TO_CLOUDFLARE_PAGES: {
readonly id: '027';
readonly message: 'Error upload to Cloudflare pages.';
readonly kind: 'deploy';
};
readonly ERR_USER_IDENTITY: {
readonly id: '036';
readonly message: `
Git username or email is not configured
- please set valid 'git config user.name' and 'git config user.email'
- or provide ZE_USER_TOKEN as environment variable
`;
readonly kind: 'deploy';
};
readonly ERR_TLS_CERT_ALTNAME_INVALID: {
readonly id: '034';
readonly message: "You domain's TLS Certificate is invalid. Have you updated your domain settings with your Registrar?";
readonly kind: 'deploy';
};
readonly ERR_HTTP_ERROR: {
readonly id: '035';
readonly message: `
HTTP request for {{ method }} {{ url }} failed with status code {{ status }}.
Please check your network connection and try again.
{{ content }}
`;
readonly kind: 'config';
};
readonly ERR_NO_WRANGLER: {
readonly id: '028';
readonly message: `Wrangler is not installed. It's needed for Cloudflare deployment. Please install dependencies without --no-optional flag.`;
readonly kind: 'build';
};
readonly ERR_CREATE_DIST_FOLDER: {
readonly id: '029';
readonly message: `Error on creating dist folder. Zephyr is unable to create dist folder for your application's configuration.`;
readonly kind: 'build';
};
/**
* This case needs to be specific without a message as the server respond with 40*, so
* we will need to prioritize the server status code and prints out the status
*
* @example
* {
* "statusCode": 401,
* "timestamp": "2024-08-23T02:21:48.873Z",
* "path": "/v2/builder-packages-api/application-config?application-uid=home-spa.federated_apps.zmzlois"
* }
*/
readonly ERR_NO_RESPONSE_FOR_APP_CONFIG: {
readonly id: '030';
readonly message: 'Failed to load application configuration.';
readonly kind: 'build';
};
readonly ERR_NO_JWT: {
readonly id: '031';
readonly message: `You don't have valid JWT token. Try to log out from the dashboard and log in again. https://app.zephyr-cloud.io`;
readonly kind: 'build';
};
readonly ERR_JWT_INVALID: {
readonly id: '032';
readonly message: 'Your JWT token is invalid. Try to log out from the dashboard and log in again. https://app.zephyr-cloud.io';
readonly kind: 'build';
};
readonly ERR_WEBSOCKET_CONNECTION: {
readonly id: '034';
readonly message: 'Websocket connection error during login.';
readonly kind: 'build';
};
readonly ERR_GET_APP_CONFIG: {
readonly id: '035';
readonly message: 'Error when getting application configuration from API. Could not find application configuration. Please try again after removing ~/.zephyr folder.';
readonly kind: 'build';
};
readonly ERR_GIT_COMMIT_HASH: {
readonly id: '036';
readonly message: 'Failed to get git commit hash. Can you make sure this git repository has commit history?';
readonly kind: 'build';
};
readonly ERR_CI_TOKEN_AUTH: {
readonly id: '037';
readonly message: `
ZE_CI_TOKEN could not be exchanged for a Zephyr access token.
Zephyr detected this CI actor:
- provider: {{ provider }}
- username: {{ username }}
- actor type: {{ actorType }}
- identity source: {{ source }}
- issuer: {{ issuer }}
{{ resolution }}
Also check:
- ZE_CI_TOKEN is the repository or organization secret created for this Zephyr workspace.
- The workflow checks out the Git repository with origin and commit history.
{{ details }}
`;
readonly kind: 'build';
};
readonly ERR_RESOLVE_REMOTES: {
readonly id: '001';
readonly message: `
Failed to resolve remote dependency: {{ appUid }} version {{ version }}
This could be due to one of the following reasons:
- The remote application '{{ appName }}' has not been built with Zephyr yet
- The specified version '{{ version }}' does not exist
- You don't have access to this application
- The application exists but no environment has been created
Steps to resolve:
1. Ensure the remote application is built with Zephyr first
2. For newly created applications, create an environment:
- Go to https://app.zephyr-cloud.io
- Navigate to your application
- Create a new environment (e.g., "development" or "production")
3. Check that the version exists by visiting the dashboard
4. Verify you have access to {{ orgName }}/{{ projectName }}/{{ appName }}
5. If you need any version, use "*" as the version in zephyr:dependencies
Expected behavior:
- Remote applications must be built and deployed before they can be consumed
- Applications must have at least one environment created
- Version must match an existing build (use "*" for latest)
- When using "*", at least one version must exist in the application
- You must have read access to the remote application
Application UID format: [app_name].[project_name].[org_name]
Example: "my-remote.my-project.my-org"
`;
readonly kind: 'config';
};
readonly ERR_ZEPHYR_CONFIG_NOT_VALID: {
readonly id: '002';
readonly message: `
Invalid Zephyr config: {{ message }}
`;
readonly kind: 'config';
};
readonly ERR_CANNOT_RESOLVE_APP_NAME_WITH_VERSION: {
readonly id: '003';
readonly message: `
Failed to resolve remote application with version {{ version }}
This could be due to one of the following reasons:
- Network error while trying to resolve the dependency
- Zephyr API is temporarily unavailable
- Application naming mismatch in configuration
Steps to resolve:
1. Check your network connection
2. If using "*" version, ensure at least one version exists
3. Ensure the application has an environment created in the dashboard
Expected behavior:
- Remote application must have at least one deployed version
- Application must have at least one environment
Application naming is based on:
- git organization/username
- git repository name
- name in package.json
For debugging, check:
- Your ~/.zephyr folder for cached tokens
- Network proxy settings if behind corporate firewall
- API status at https://status.zephyr-cloud.io
Documentation: https://docs.zephyr-cloud.io/tutorials/mf-guide
`;
readonly kind: 'config';
};
readonly ERR_SHARED_PACKAGE: {
readonly id: '004';
readonly message: `
Were the required packages in Module federation plugin installed and included in package.json? We had error while trying to compute your shared dependencies.`;
readonly kind: 'config';
};
readonly ERR_MF_CONFIG_MISSING_FILENAME: {
readonly id: '005';
readonly message: 'Missing filename in Module Federation configuration. Since the filename in React Native is the actual JS bundle, input of filename in Module Federation configuration is required.';
readonly kind: 'config';
};
readonly ERR_MISSING_PLATFORM: {
readonly id: '006';
readonly message: 'Missing platform target (ios, android or others) from compiler options. Please open an issue on https://github.com/ZephyrCloudIO/zephyr-packages/issues';
readonly kind: 'config';
};
readonly ERR_MAX_PAYLOAD_SIZE_EXCEEDED: {
readonly id: '037';
readonly message: `The "{{entity_name}}" is too large. It is {{entity_size}} bytes, but the maximum allowed size is {{max_allowed_size}} bytes.`;
readonly kind: 'deploy';
};
};
/** Error object for Zephyr errors. */
export type ZeErrors = typeof ZeErrors;
/** `"ERR_UNKNOWN"`, `"ERR_PACKAGE_JSON_NOT_FOUND"` ... */
export type ZeErrorKeys = keyof ZeErrors;
/** `ZeErrors.ERR_UNKNOWN`, `ZeErrors.ERR_PACKAGE_JSON_NOT_FOUND` ... */
export type ZeErrorType = ZeErrors[ZeErrorKeys];
/** Builds a Zephyr error code from a given error type. */
export type ZeErrorCode<K extends ZeErrorKeys> = `ZE${(typeof ZeErrorCategories)[ZeErrors[K]['kind']]}${ZeErrors[K]['id']}`;
/** `"ZE00000"`, `"ZE10010"` ... */
export type ZeErrorCodes = {
[K in ZeErrorKeys]: ZeErrorCode<K>;
}[ZeErrorKeys];
/** Ensures `a` and `b` are the same error type. */
export declare function isZeErrorEqual(a: ZeErrorType, b: ZeErrorType): boolean;
//# sourceMappingURL=codes.d.mts.map