epicenter-libs 3.34.2 → 3.35.1

package/dist/types/epicenter.d.ts

@@ -1,11 +1,11 @@
 import 'regenerator-runtime/runtime';
-declare const version = "Epicenter (v__VERSION__) for __BUILD__ | Build Date: __DATE__";
+declare const version: string;
 import { Handler } from './utils/error-manager';
 export declare const DEFAULT_ERROR_HANDLERS: Record<string, Handler>;
 export * from './types';
 export { version };
 export { SCOPE_BOUNDARY, RITUAL, PUSH_CATEGORY, ROLE, } from './utils/constants';
 export { config, errorManager, Router, Fault, } from './utils';
-export { accountAdapter, adminAdapter, assetAdapter, consensusAdapter, emailAdapter, authAdapter, chatAdapter, episodeAdapter, groupAdapter, leaderboardAdapter, presenceAdapter, projectAdapter, recaptchaAdapter, runAdapter, taskAdapter, timeAdapter, userAdapter, vaultAdapter, videoAdapter, vonageAdapter, worldAdapter, somebodyAdapter, dailyAdapter, matchmakerAdapter, walletAdapter, Channel, cometdAdapter, } from './adapters';
+export { accountAdapter, adminAdapter, assetAdapter, consensusAdapter, emailAdapter, authAdapter, chatAdapter, episodeAdapter, groupAdapter, leaderboardAdapter, presenceAdapter, projectAdapter, recaptchaAdapter, runAdapter, taskAdapter, timeAdapter, userAdapter, vaultAdapter, videoAdapter, vonageAdapter, worldAdapter, somebodyAdapter, dailyAdapter, matchmakerAdapter, walletAdapter, pipelineAdapter, encyclopediaAdapter, fileAdapter, registrationAdapter, docketAdapter, Channel, cometdAdapter, gitAdapter, powerpointAdapter, } from './adapters';
 export { videoAPI, vonageAPI, } from './apis';
 export * as utils from './utilities';

package/dist/types/types.d.ts

@@ -24,10 +24,15 @@ export type { Leaderboard, Score, Tag, } from './adapters/leaderboard';
 export type { Presence, } from './adapters/presence';
 export type { ACCESS_TYPE, AccessType, WORKER_PARTITION, WorkerPartition, PHYLOGENY, Phylogeny, FileType, CHANNEL_PROTOCOL, ChannelProtocol, ProjectMember, Deployment, TeamProject, PersonalProject, Project, } from './adapters/project';
 export type { RunReadOutView, RunVariables, RunMetadata, RunCreateOptions, RunStrategy, ExecutionContext, ModelContext, ModelContextDefaults, OperationOptions, VariableOptions, EventOptions, RewindMarker, ReplayOperation, ReplayRestoration, SnapshotRestoration, Restorations, Protections, InputGuard, OverwriteGuard, RelativeGuard, RoleGuard, PrivilegeGuard, V1ExecutionContext, V2ModelContext, ExcelModelControl, JavaModelControl, PowersimModelControl, VensimModelControl, VensimModelTool, StellaModelTool, ProcActionable, GetActionable, SetActionable, Actionable, Route, WireExternalFunction, AptExternalDependency, CranExternalDependency, GitExternalDependency, JuliaExternalDependency, NpmExternalDependency, PypiExternalDependency, ShellExternalDependency, MORPHOLOGY, MetadataFirstPop, MetadataLastPop, MetadataAllPop, MetadataPop, MetadataUpdate, } from './adapters/run';
-export type { RETRY_POLICY, TaskPayloadBody, TaskPayloadHeaders, StatusReadOutView, StatusCreateInView, CronTaskTriggerCreateInView, DateTaskTriggerCreateInView, OffsetTaskTriggerCreateInView, TaskTriggerCreateInView, HttpTaskPayloadCreateInView, GroupStatusTaskPayloadCreateInView, TaskPayloadCreateInView, HttpTaskPayloadReadOutView, GroupStatusTaskPayloadReadOutView, TaskPayloadReadOutView, TaskReadOutView, } from './adapters/task';
+export type { RETRY_POLICY, TaskPayloadBody, TaskPayloadHeaders, TaskHttpMethod, TaskRetryPolicyReadOutView, TaskStatusReadOutView, TaskAddressReadOutView, TaskScopeReadOutView, StatusReadOutView, StatusCreateInView, CronTaskTriggerCreateInView, DateTaskTriggerCreateInView, OffsetTaskTriggerCreateInView, TaskTriggerCreateInView, HttpTaskPayloadCreateInView, GroupStatusTaskPayloadCreateInView, TaskPayloadCreateInView, HttpTaskPayloadCreateInput, TaskPayloadCreateInput, HttpTaskPayloadReadOutView, GroupStatusTaskPayloadReadOutView, TaskPayloadReadOutView, TaskReadOutView, TaskHistoryReadOutView, TaskPageOptions, TaskScopePageOptions, } from './adapters/task';
 export type { UserReadOutView, UserCreateInView, NativeUserCreateInView, ExternalUserCreateInView, ExternalUserReadOutView, NativeUserReadOutView, PseudonymReadOutView, UserReport, DiscardedUser, MFADetailReadOutView, MFADetailCreateInView, GraftReadOutView, GraftCreateInView, SecretCreateInView, GroupRelationshipReadOutView, UploadOptions, Modality, MFAMethodology, Countdown, RealmData, } from './adapters/user';
 export type { Vault, VaultItems, Items, } from './adapters/vault';
 export type { WalletReadOutView, WalletItemReadOutView, WalletItemCreateInView, } from './adapters/wallet';
 export type { WorldReadOutView, WorldRole, AssignmentReadOutView, AssignmentCreateInView, PersonaReadOutView, PersonaCreateInView, AssignmentMap, ColorAnimalWorldNameGenerator, SequentialWorldNameGenerator, WorldNameGenerator, WORLD_NAME_GENERATOR_TYPE, WorldNameGeneratorType, OBJECTIVE, Objective, OrbitType, } from './adapters/world';
+export type { FileEntry, DirectoryEntry, FileSystemEntry, } from './adapters/file';
+export type { RegistrationInfo, TeamRegistrationInfo, RegistrationResult, WhoAmI, WhoAmIObjectType, TeamRole, SsoProtocol, } from './adapters/registration';
+export type { OperatingSystem, WorkerShape, ScaleFlavor, ScaleCreateInView, ScaleReadOutView, ScaleDocketPayloadCreateInView, ScaleDocketPayloadReadOutView, DocketPayloadCreateInView, DocketPayloadReadOutView, DocketReadOutView, } from './adapters/docket';
+export type { EncyclopediaTranslator, DocumentedEndpointMethod, DocumentedEndpointAuthorization, DocumentedEndpointNotation, DocumentedParameterSource, DocumentedParameter, DocumentedEndpoint, DocumentedResource, KnownServiceReadOutView, } from './adapters/encyclopedia';
+export type { PipelineExecutionStatus, PipelineAuditReadOutView, } from './adapters/pipeline';
 export type { Somebody, } from './adapters/somebody';
 export type { VideoReadOutView, VideoDir, AFFILIATE, Affiliate, MEDIA_FORMAT, MediaFormat, LANGUAGE_CODE, LanguageCode, ProcessingType, } from './apis/video';

package/dist/types/utils/router.d.ts

@@ -34,6 +34,7 @@ export interface RetryFunction<Output> {
 export interface Page<Item> {
     firstResult: number;
     maxResults: number;
+    resultSize: number;
     totalResults: number;
     values: Item[];
     prev: () => Promise<Item[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "epicenter-libs",
-  "version": "3.34.2",
+  "version": "3.35.1",
   "main": "dist/cjs/epicenter.js",
   "type": "module",
   "module": "dist/module/epicenter.js",
@@ -13,8 +13,9 @@
   ],
   "scripts": {
     "test": "vitest",
-    "test:run": "vitest run",
-    "test:coverage": "vitest run --coverage",
+    "test:run": "npm run type-check && vitest run",
+    "test:coverage": "npm run type-check && vitest run --coverage",
+    "test:dist": "npm run build && vitest run --config vitest.dist.config.js",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
     "changelog:all": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
     "type-check": "tsc --noEmit",
@@ -23,9 +24,7 @@
     "build:types": "tsc --emitDeclarationOnly",
     "build:js": "rollup -c -m",
     "build": "npm run build:clean && npm run build:types && npm run build:js",
-    "build:test": "rollup -c rollup.config.test.js",
-    "pretest": "npm run type-check && npm run build:test",
-    "pretest:run": "npm run type-check && npm run build:test",
+    "prepublishOnly": "npm run test:run && npm run test:dist",
     "start": "rollup -c -m inline -w",
     "prepare": "node -e \"if (!process.env.CI && !process.env.JENKINS_HOME) require('child_process').execSync('husky', {stdio: 'inherit'})\""
   },
@@ -50,6 +49,11 @@
     "cometd": "^8.0.9",
     "cross-fetch": "^3.0.6"
   },
+  "overrides": {
+    "tar": "^7.5.16",
+    "esbuild": "^0.28.1",
+    "sigstore": "^4.1.1"
+  },
   "devDependencies": {
     "@babel/cli": "^7.26.0",
     "@babel/core": "^7.26.0",
@@ -70,9 +74,10 @@
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^15.3.0",
     "@rollup/plugin-replace": "^6.0.2",
-    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-terser": "^1.0.0",
     "@stylistic/eslint-plugin": "^5.4.0",
     "@types/cometd": "^4.0.8",
+    "@vitest/coverage-v8": "^3.2.6",
     "babel-loader": "^9.2.1",
     "conventional-changelog": "^7.1.1",
     "conventional-changelog-angular": "^8.0.0",

package/src/adapters/authentication.ts

@@ -112,7 +112,8 @@ export function setLocalSession(session: Session): Session {
  */
 export async function removeLocalSession(): Promise<void> {
     identification.session = undefined;
-    await cometdAdapter.disconnect();
+    // CometD disconnect is best-effort cleanup; its failure must not fail session removal
+    await cometdAdapter.disconnect().catch(() => undefined);
 }
 
 

package/src/adapters/cometd.ts

@@ -20,6 +20,7 @@ const CONNECT_META_CHANNEL = '/meta/connect';
 const DISCONNECT_META_CHANNEL = '/meta/disconnect';
 const HANDSHAKE_META_CHANNEL = '/meta/handshake';
 const COMETD_RECONNECTED = 'COMETD_RECONNECTED';
+const CHANNELS_NOT_ENABLED = 'CHANNELS_NOT_ENABLED';
 const DEFAULT_CHANNEL_PROTOCOL = 'cometd';
 
 type HandshakeState = 'idle' | 'handshaking' | 'succeeded' | 'failed';
@@ -85,7 +86,7 @@ class CometdAdapter {
 
     async startup(options: { logLevel: 'info' | 'debug' | 'warn' } = { logLevel: 'warn' }) {
         const project = await getProject();
-        if (!project.channelEnabled) throw new EpicenterError('Push Channels are not enabled on this project');
+        if (!project.channelEnabled) throw new EpicenterError('Push Channels are not enabled on this project', CHANNELS_NOT_ENABLED);
         const channelProtocol = project.channelProtocol?.toLowerCase() || DEFAULT_CHANNEL_PROTOCOL;
         const { CometD } = await import('cometd');
         const { AckExtension } = await import('cometd');
@@ -196,7 +197,11 @@ class CometdAdapter {
 
     async init(options?: { logLevel: 'info' | 'debug' | 'warn' }) {
         if (!this.initialization) {
-            this.initialization = this.startup(options);
+            // A rejected startup must not be cached, or every later init() call re-throws it
+            this.initialization = this.startup(options).catch((error) => {
+                this.initialization = undefined;
+                throw error;
+            });
         }
         return this.initialization;
     }

package/src/adapters/docket.ts

@@ -0,0 +1,109 @@
+import type { RoutingOptions } from '../utils/router';
+import type { TaskTriggerCreateInView } from './task';
+
+import { Router } from '../utils';
+
+export type OperatingSystem = 'LINUX' | 'MAC' | 'WINDOWS';
+
+export type WorkerShape =
+    | 'GS' | 'GM' | 'GL' | 'GXL' | 'G2XL' | 'G4XL'
+    | 'ML' | 'MXL' | 'M2XL' | 'M4XL'
+    | 'CL' | 'CXL' | 'C2XL' | 'C4XL';
+
+export type ScaleFlavor = 'PROCESS' | 'DOCKER' | 'JVM' | 'WSDL';
+
+export interface ScaleCreateInView {
+    active: boolean;
+    initialWorkerCount: number;
+    additionalWorkerLimit: number;
+    flavors?: ScaleFlavor[];
+}
+
+export interface ScaleReadOutView {
+    active?: boolean | null;
+    initialWorkerCount?: number | null;
+    additionalWorkerLimit?: number | null;
+    flavors?: ScaleFlavor[] | null;
+    test?: boolean | null;
+    shape?: WorkerShape | null;
+    operatingSystem?: OperatingSystem | null;
+}
+
+export interface ScaleDocketPayloadCreateInView {
+    objectType: 'scale';
+    scale: ScaleCreateInView;
+    operatingSystem: OperatingSystem;
+    workerShape: WorkerShape;
+    test?: boolean;
+}
+
+export interface ScaleDocketPayloadReadOutView {
+    objectType: 'scale';
+    scale?: ScaleReadOutView | null;
+    operatingSystem?: OperatingSystem | null;
+    workerShape?: WorkerShape | null;
+    test?: boolean | null;
+}
+
+export type DocketPayloadCreateInView = ScaleDocketPayloadCreateInView;
+export type DocketPayloadReadOutView = ScaleDocketPayloadReadOutView;
+
+export interface DocketReadOutView {
+    docketKey?: string | null;
+    date?: string | null;
+    payload?: DocketPayloadReadOutView | null;
+    ttlMinutes?: number | null;
+    complete?: boolean | null;
+    error?: string | null;
+    attempts?: number | null;
+}
+
+
+/**
+ * Creates a new docket entry, scheduling a deferred operation for later execution.
+ * Requires `support` level authorization.
+ * Base URL: POST `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/docket`
+ *
+ * @example
+ * import { docketAdapter } from 'epicenter-libs';
+ * const docket = await docketAdapter.create(
+ *     {
+ *         objectType: 'scale',
+ *         operatingSystem: 'LINUX',
+ *         workerShape: 'GS',
+ *         scale: {
+ *             active: true,
+ *             initialWorkerCount: 1,
+ *             additionalWorkerLimit: 4,
+ *             flavors: ['DOCKER'],
+ *         },
+ *     },
+ *     { objectType: 'date', value: '2026-06-01T00:00:00Z' },
+ *     '2026-05-20T00:00:00Z',
+ *     { ttlMinutes: 60 },
+ * );
+ *
+ * @param payload                   Docket payload describing the operation to schedule
+ * @param trigger                   Trigger describing when the operation should fire
+ *                                  (cron, date, or offset)
+ * @param date                      ISO-8601 date string indicating when the docket is scheduled
+ * @param [optionals]               Optional arguments; pass network call options overrides here. Special arguments specific to this method are listed below if they exist.
+ * @param [optionals.ttlMinutes]    Time-to-live in minutes for the docket entry (minimum 2)
+ * @returns promise that resolves to the newly created docket
+ */
+export async function create(
+    payload: DocketPayloadCreateInView,
+    trigger: TaskTriggerCreateInView,
+    date: string,
+    optionals: {
+        ttlMinutes?: number;
+    } & RoutingOptions = {},
+): Promise<DocketReadOutView> {
+    const { ttlMinutes, ...routingOptions } = optionals;
+    return await new Router()
+        .post('/docket', {
+            body: { payload, trigger, date, ttlMinutes },
+            ...routingOptions,
+        })
+        .then(({ body }) => body);
+}

package/src/adapters/encyclopedia.ts

@@ -0,0 +1,128 @@
+import type { RoutingOptions } from '../utils/router';
+
+import { Router } from '../utils';
+
+
+export type EncyclopediaTranslator = 'ASCIIDOC' | 'ASCIIDOC_TO_HTML' | 'OPENAPI';
+
+export type DocumentedEndpointMethod = 'CONNECT' | 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'PATCH' | 'POST' | 'PUT' | 'TRACE';
+
+export type DocumentedEndpointAuthorization = 'SYSTEM' | 'DASHBOARD' | 'OWNER' | 'AUTHOR' | 'SUPPORT' | 'REVIEWER' | 'FACILITATOR' | 'LEADER' | 'PARTICIPANT' | 'ANONYMOUS';
+
+export type DocumentedEndpointNotation = 'POST_RATHER_THAN_GET' | 'UNSUPPORTED_IGNORED';
+
+export type DocumentedParameterSource = 'PATH' | 'HEADER' | 'QUERY' | 'MATRIX';
+
+export interface DocumentedParameter {
+    name?: string;
+    source?: DocumentedParameterSource;
+    type?: Record<string, unknown>;
+}
+
+export interface DocumentedEndpoint {
+    method?: DocumentedEndpointMethod;
+    path?: string;
+    authorization?: DocumentedEndpointAuthorization;
+    response?: Record<string, unknown>;
+    summary?: string;
+    description?: string;
+    deprecated?: boolean;
+    paged?: boolean;
+    notations?: DocumentedEndpointNotation[];
+    body?: Record<string, unknown>;
+    parameters?: DocumentedParameter[];
+    produces?: unknown[];
+    consumes?: unknown[];
+}
+
+export interface DocumentedResource {
+    silenced?: boolean;
+    endpoints?: DocumentedEndpoint[];
+    definitions?: Record<string, unknown>;
+}
+
+export interface KnownServiceReadOutView {
+    name?: string;
+    development?: boolean;
+    trusted?: boolean;
+    published?: boolean;
+}
+
+
+/**
+ * Lists the known API services available for the given encyclopedia version.
+ * Base URL: GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/encyclopedia/v{version}`
+ *
+ * @example
+ * import { encyclopediaAdapter } from 'epicenter-libs';
+ * const services = await encyclopediaAdapter.listServices(3);
+ *
+ * @param version       Encyclopedia version number
+ * @param [optionals]   Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves to an array of known service descriptors
+ */
+export async function listServices(
+    version: number,
+    optionals: RoutingOptions = {},
+): Promise<KnownServiceReadOutView[]> {
+    return await new Router()
+        .get(`/encyclopedia/v${version}`, optionals)
+        .then(({ body }) => body);
+}
+
+
+/**
+ * Retrieves the documented resource (API documentation) for a specific service and encyclopedia version.
+ * Base URL: GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/encyclopedia/v{version}/{api}`
+ *
+ * @example
+ * import { encyclopediaAdapter } from 'epicenter-libs';
+ * const resource = await encyclopediaAdapter.getResource(3, 'run');
+ *
+ * @param version       Encyclopedia version number
+ * @param api           Name of the API service to retrieve documentation for
+ * @param [optionals]   Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves to the documented resource containing endpoints and definitions
+ */
+export async function getResource(
+    version: number,
+    api: string,
+    optionals: RoutingOptions = {},
+): Promise<DocumentedResource> {
+    return await new Router()
+        .get(`/encyclopedia/v${version}/${api}`, optionals)
+        .then(({ body }) => body);
+}
+
+
+/**
+ * Retrieves a translated representation of the API documentation for a specific service and encyclopedia version.
+ * Supported translators are ASCIIDOC, ASCIIDOC_TO_HTML, and OPENAPI.
+ * Base URL: GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/encyclopedia/as/{translator}/v{version}/{api}`
+ *
+ * NOTE: The backend returns the translated content with a translator-specific content-type
+ * (e.g. `text/asciidoc`, `text/html`, `application/json`). The shared Router throws when the
+ * response content-type is not `application/json`, so only the OPENAPI translator works here.
+ * For ASCIIDOC and ASCIIDOC_TO_HTML, use the underlying fetch API directly against the
+ * constructed URL.
+ *
+ * @example
+ * import { encyclopediaAdapter } from 'epicenter-libs';
+ * const openApiDoc = await encyclopediaAdapter.translate('OPENAPI', 3, 'run');
+ *
+ * @param translator    Output format for the documentation; one of 'ASCIIDOC', 'ASCIIDOC_TO_HTML', or 'OPENAPI'
+ * @param version       Encyclopedia version number
+ * @param api           Name of the API service to translate documentation for
+ * @param [optionals]   Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves to the translated documentation (only when translator is 'OPENAPI')
+ */
+export async function translate(
+    translator: EncyclopediaTranslator,
+    version: number,
+    api: string,
+    optionals: RoutingOptions = {},
+): Promise<unknown> {
+    return await new Router()
+        .get(`/encyclopedia/as/${translator}/v${version}/${api}`, optionals)
+        .then(({ body }) => body);
+}