epicenter-libs 3.34.2 → 3.35.0

package/src/adapters/git.ts

@@ -0,0 +1,278 @@
+import type { RoutingOptions } from '../utils/router';
+
+import { Router } from '../utils';
+
+// ──────────────────────────────────────────────
+// Types
+// ──────────────────────────────────────────────
+
+export type GitAlgorithm = 'rsa' | 'ed25519';
+export type GitKeySpec = 'openssh' | 'pkcs8' | 'x509';
+
+export interface GitStatusReadOutView {
+    currentBranch?: string | null;
+}
+
+export interface GitIntegrationReadOutView {
+    privateKeySpec?: GitKeySpec | null;
+    publicKey?: string | null;
+    uri?: string | null;
+    publicKeySpec?: GitKeySpec | null;
+    algorithm?: GitAlgorithm | null;
+}
+
+export interface GitIntegrationCreateInView {
+    privateKey: string;
+    privateKeySpec: GitKeySpec;
+    publicKey: string;
+    uri: string;
+    publicKeySpec: GitKeySpec;
+    algorithm: GitAlgorithm;
+}
+
+export interface GitIntegrationUpdateInView {
+    privateKey?: string | null;
+    privateKeySpec: GitKeySpec;
+    publicKey?: string | null;
+    uri?: string | null;
+    publicKeySpec: GitKeySpec;
+    algorithm: GitAlgorithm;
+}
+
+
+// ──────────────────────────────────────────────
+// Functions
+// ──────────────────────────────────────────────
+
+/**
+ * Retrieves the git integration configuration for the project.
+ * Base URL: GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/git`
+ *
+ * @example
+ * import { gitAdapter } from 'epicenter-libs';
+ * const integration = await gitAdapter.get();
+ *
+ * @param [optionals]   Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves to the git integration configuration
+ */
+export async function get(
+    optionals: RoutingOptions = {},
+): Promise<GitIntegrationReadOutView> {
+    return new Router()
+        .get('/git', optionals)
+        .then(({ body }) => body);
+}
+
+
+/**
+ * Retrieves the current git status for the project.
+ * Base URL: GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/git/status`
+ *
+ * @example
+ * import { gitAdapter } from 'epicenter-libs';
+ * const status = await gitAdapter.getStatus();
+ * console.log(status.currentBranch);
+ *
+ * @param [optionals]   Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves to the git status, including the current branch
+ */
+export async function getStatus(
+    optionals: RoutingOptions = {},
+): Promise<GitStatusReadOutView> {
+    return new Router()
+        .get('/git/status', optionals)
+        .then(({ body }) => body);
+}
+
+
+/**
+ * Checks out a branch in the project's git repository.
+ * Base URL: GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/git/checkout/{branch}`
+ *
+ * @example
+ * import { gitAdapter } from 'epicenter-libs';
+ * await gitAdapter.checkout('main');
+ *
+ * @param branch        Name of the branch to check out
+ * @param [optionals]   Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves when the checkout is complete
+ */
+export async function checkout(
+    branch: string,
+    optionals: RoutingOptions = {},
+): Promise<void> {
+    return new Router()
+        .get(`/git/checkout/${branch}`, optionals)
+        .then(({ body }) => body);
+}
+
+
+/**
+ * Resets the project's git repository, optionally to a specific branch.
+ * Base URL: DELETE `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/git/reset[/{branch}]`
+ *
+ * @example
+ * import { gitAdapter } from 'epicenter-libs';
+ * await gitAdapter.reset();                        // reset current branch
+ * await gitAdapter.reset({ branch: 'main' });      // reset to 'main'
+ *
+ * @param [optionals]           Optional arguments; pass network call options overrides here. Special arguments specific to this method are listed below if they exist.
+ * @param [optionals.branch]    Branch to reset to; if omitted, resets the current branch
+ * @returns promise that resolves when the reset is complete
+ */
+export async function reset(
+    optionals: { branch?: string } & RoutingOptions = {},
+): Promise<void> {
+    const { branch, ...routingOptions } = optionals;
+    return new Router()
+        .delete(`/git/reset${branch ? `/${branch}` : ''}`, routingOptions)
+        .then(({ body }) => body);
+}
+
+
+/**
+ * Creates a git integration for the project.
+ * Base URL: POST `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/git/integration`
+ *
+ * @example
+ * import { gitAdapter } from 'epicenter-libs';
+ * const integration = await gitAdapter.createIntegration({
+ *     uri: 'git@github.com:myorg/myrepo.git',
+ *     publicKey: '...',
+ *     privateKey: '...',
+ *     publicKeySpec: 'openssh',
+ *     privateKeySpec: 'pkcs8',
+ *     algorithm: 'ed25519',
+ * });
+ *
+ * @param integration   Git integration configuration to create
+ * @param [optionals]   Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves to the created git integration
+ */
+export async function createIntegration(
+    integration: GitIntegrationCreateInView,
+    optionals: RoutingOptions = {},
+): Promise<GitIntegrationReadOutView> {
+    return new Router()
+        .post('/git/integration', {
+            body: integration,
+            ...optionals,
+        }).then(({ body }) => body);
+}
+
+
+/**
+ * Updates the git integration for the project.
+ * Base URL: PATCH `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/git/integration`
+ *
+ * @example
+ * import { gitAdapter } from 'epicenter-libs';
+ * const integration = await gitAdapter.updateIntegration({
+ *     uri: 'git@github.com:myorg/newrepo.git',
+ *     publicKeySpec: 'openssh',
+ *     privateKeySpec: 'pkcs8',
+ *     algorithm: 'ed25519',
+ * });
+ *
+ * @param integration   Fields to update on the git integration
+ * @param [optionals]   Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves to the updated git integration
+ */
+export async function updateIntegration(
+    integration: GitIntegrationUpdateInView,
+    optionals: RoutingOptions = {},
+): Promise<GitIntegrationReadOutView> {
+    return new Router()
+        .patch('/git/integration', {
+            body: integration,
+            ...optionals,
+        }).then(({ body }) => body);
+}
+
+
+/**
+ * Removes the git integration for the project.
+ * Base URL: DELETE `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/git/integration`
+ *
+ * @example
+ * import { gitAdapter } from 'epicenter-libs';
+ * await gitAdapter.removeIntegration();
+ *
+ * @param [optionals]   Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves when the integration is removed
+ */
+export async function removeIntegration(
+    optionals: RoutingOptions = {},
+): Promise<void> {
+    return new Router()
+        .delete('/git/integration', optionals)
+        .then(({ body }) => body);
+}
+
+
+/**
+ * Pushes local commits to the remote git repository.
+ * Base URL: POST `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/git/push`
+ *
+ * @example
+ * import { gitAdapter } from 'epicenter-libs';
+ * await gitAdapter.push({ message: 'Update simulation data' });
+ *
+ * @param optionals             Arguments object; also accepts network call option overrides.
+ * @param optionals.message     Commit message (required)
+ * @param [optionals.password]  Password for authentication
+ * @param [optionals.force]     Force-push, bypassing non-fast-forward checks
+ * @returns promise that resolves when the push is complete
+ */
+export async function push(
+    optionals: {
+        message: string;
+        password?: string | null;
+        force?: boolean | null;
+    } & RoutingOptions,
+): Promise<void> {
+    const { message, password, force, ...routingOptions } = optionals;
+    return new Router()
+        .withSearchParams({ force })
+        .post('/git/push', {
+            body: { message, password },
+            ...routingOptions,
+        }).then(({ body }) => body);
+}
+
+
+/**
+ * Pulls changes from the remote git repository into the project.
+ * Base URL: POST `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/git/pull`
+ *
+ * @example
+ * import { gitAdapter } from 'epicenter-libs';
+ * await gitAdapter.pull({ force: true, confirm: true });
+ *
+ * @param [optionals]           Optional arguments; pass network call options overrides here. Special arguments specific to this method are listed below if they exist.
+ * @param [optionals.password]  Password for authentication
+ * @param [optionals.force]     Force the pull, overwriting local changes
+ * @param [optionals.confirm]   Set the `X-Forio-Confirmation` header to confirm an overwrite
+ * @returns promise that resolves when the pull is complete
+ */
+export async function pull(
+    optionals: {
+        password?: string | null;
+        force?: boolean | null;
+        confirm?: boolean | null;
+    } & RoutingOptions = {},
+): Promise<void> {
+    const { password, force, confirm, headers: headersOverride, ...routingOptions } = optionals;
+    const headers = Object.assign(
+        {},
+        headersOverride,
+        confirm ? { 'X-Forio-Confirmation': true } : {},
+    );
+    return new Router()
+        .withSearchParams({ force })
+        .post('/git/pull', {
+            body: { password },
+            headers,
+            ...routingOptions,
+        }).then(({ body }) => body);
+}

package/src/adapters/index.ts

@@ -23,8 +23,15 @@ import * as somebodyAdapter from './somebody';
 import * as matchmakerAdapter from './matchmaker';
 import * as dailyAdapter from './daily';
 import * as walletAdapter from './wallet';
+import * as pipelineAdapter from './pipeline';
+import * as encyclopediaAdapter from './encyclopedia';
+import * as fileAdapter from './file';
+import * as registrationAdapter from './registration';
+import * as docketAdapter from './docket';
 import { default as cometdAdapter } from './cometd';
 import { default as Channel } from './channel';
+import * as gitAdapter from './git';
+import * as powerpointAdapter from './powerpoint';
 
 export {
     accountAdapter,
@@ -53,5 +60,12 @@ export {
     matchmakerAdapter,
     dailyAdapter,
     walletAdapter,
+    pipelineAdapter,
+    encyclopediaAdapter,
+    fileAdapter,
+    registrationAdapter,
+    docketAdapter,
     Channel,
+    gitAdapter,
+    powerpointAdapter,
 };

package/src/adapters/pipeline.ts

@@ -0,0 +1,145 @@
+import type { Page, RoutingOptions } from '../utils/router';
+
+import { Router } from '../utils';
+
+
+export type PipelineExecutionStatus = 'RUNNING' | 'SUCCEEDED' | 'FAILED';
+
+export interface PipelineAuditReadOutView {
+    status?: PipelineExecutionStatus | null;
+    started?: string | null;
+    finished?: string | null;
+    executionKey?: string | null;
+    accountShortName?: string | null;
+    projectShortName?: string | null;
+    configName?: string | null;
+    /* Virtual field: display name of the admin who triggered the execution. */
+    creator?: string | null;
+}
+
+
+/**
+ * Builds the NPM Docker images used by pipeline NPM operations.
+ * Requires `system` (admin) authorization.
+ * Base URL: GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/pipeline/npm/images`
+ *
+ * @example
+ * import { pipelineAdapter } from 'epicenter-libs';
+ * const built = await pipelineAdapter.buildImages();
+ *
+ * @param [optionals]   Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves to `true` when the images were built successfully
+ */
+export async function buildImages(
+    optionals: RoutingOptions = {},
+): Promise<boolean> {
+    return await new Router()
+        .get('/pipeline/npm/images', optionals)
+        .then(({ body }) => body);
+}
+
+
+/**
+ * Executes a stored pipeline configuration. The operations to run are read server-side from the
+ * named config file; only step inputs (such as credentials) are supplied here via `attributes`.
+ * The execution runs asynchronously — the returned audit record starts in its `RUNNING` state and
+ * is updated by the worker on completion (poll `getExecution` to observe progress).
+ * Base URL: POST `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/pipeline/{configName}`
+ *
+ * @example
+ * import { pipelineAdapter } from 'epicenter-libs';
+ * // Pass the git credential the config's git step will consume, keyed by operation type
+ * const audit = await pipelineAdapter.execute('deploy', { git: 'my-git-token' });
+ *
+ * @param configName        Name of the stored pipeline config to execute
+ * @param [attributes]      Step inputs keyed by operation type (e.g. `{ git: '<token>' }`)
+ * @param [optionals]       Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves to the newly created audit record in its initial RUNNING state
+ */
+export async function execute(
+    configName: string,
+    attributes: Record<string, unknown> = {},
+    optionals: RoutingOptions = {},
+): Promise<PipelineAuditReadOutView> {
+    return await new Router()
+        .post(`/pipeline/${encodeURIComponent(configName)}`, {
+            body: { attributes },
+            ...optionals,
+        }).then(({ body }) => body);
+}
+
+
+/**
+ * Retrieves a single pipeline audit record by its execution key.
+ * Base URL: GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/pipeline/{executionKey}`
+ *
+ * @example
+ * import { pipelineAdapter } from 'epicenter-libs';
+ * const audit = await pipelineAdapter.getExecution('<executionKey>');
+ *
+ * @param executionKey  Execution key of the audit record to retrieve
+ * @param [optionals]   Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves to the audit record
+ */
+export async function getExecution(
+    executionKey: string,
+    optionals: RoutingOptions = {},
+): Promise<PipelineAuditReadOutView> {
+    return await new Router()
+        .get(`/pipeline/${encodeURIComponent(executionKey)}`, optionals)
+        .then(({ body }) => body);
+}
+
+
+/**
+ * Lists the audit history for a stored pipeline config.
+ * Base URL: GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/pipeline/with/{configName}`
+ *
+ * @example
+ * import { pipelineAdapter } from 'epicenter-libs';
+ * const page = await pipelineAdapter.listAudits('deploy', { first: 0, max: 20 });
+ *
+ * @param configName        Name of the stored pipeline config
+ * @param [optionals]       Optional arguments; pass network call options overrides here. Special arguments specific to this method are listed below if they exist.
+ * @param [optionals.first] Index of the first record to return (for pagination)
+ * @param [optionals.max]   Maximum number of records to return (for pagination)
+ * @returns promise that resolves to a page of audit records
+ */
+export async function listAudits(
+    configName: string,
+    optionals: {
+        first?: number;
+        max?: number;
+    } & RoutingOptions = {},
+): Promise<Page<PipelineAuditReadOutView>> {
+    const { first = 0, max, ...routingOptions } = optionals;
+    return await new Router()
+        .withSearchParams({ first, max })
+        .get(`/pipeline/with/${encodeURIComponent(configName)}`, {
+            paginated: true,
+            ...routingOptions,
+        }).then(({ body }) => body);
+}
+
+
+/**
+ * Deletes a pipeline audit record by its execution key.
+ * Requires `system` (admin) authorization.
+ * Base URL: DELETE `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/pipeline/{executionKey}`
+ *
+ * @example
+ * import { pipelineAdapter } from 'epicenter-libs';
+ * await pipelineAdapter.deleteAudit('<executionKey>');
+ *
+ * @param executionKey  Execution key of the audit record to delete
+ * @param [optionals]   Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves to `true` when the audit record was deleted
+ */
+export async function deleteAudit(
+    executionKey: string,
+    optionals: RoutingOptions = {},
+): Promise<boolean> {
+    return await new Router()
+        .delete(`/pipeline/${encodeURIComponent(executionKey)}`, optionals)
+        .then(({ body }) => body);
+}

package/src/adapters/powerpoint.ts

@@ -0,0 +1,238 @@
+import fetch from 'cross-fetch';
+
+import type { RoutingOptions } from '../utils/router';
+import { Router, identification, config } from '../utils';
+
+export type TemplateDirectory = 'DATA' | 'MODEL';
+
+// ──────────────────────────────────────────────
+// Data Points
+// ──────────────────────────────────────────────
+
+export interface NDataPoint {
+    n?: number | null;
+}
+
+export interface XYDataPoint {
+    x?: number | null;
+    y?: number | null;
+}
+
+// ──────────────────────────────────────────────
+// Chart Series
+// ──────────────────────────────────────────────
+
+export interface BarSeriesShadow {
+    objectType: 'bar';
+    name?: string;
+    data?: NDataPoint[] | null;
+}
+
+export interface AreaSeriesShadow {
+    objectType: 'area';
+    name?: string;
+    data?: NDataPoint[] | null;
+}
+
+export interface LineSeriesShadow {
+    objectType: 'line';
+    name?: string;
+    data?: NDataPoint[] | null;
+}
+
+export interface PieSeriesShadow {
+    objectType: 'pie';
+    name?: string;
+    data?: NDataPoint[] | null;
+}
+
+export interface ScatterSeriesShadow {
+    objectType: 'scatter';
+    name?: string;
+    data?: XYDataPoint[] | null;
+}
+
+export interface YSeriesShadow {
+    objectType: 'y';
+    name?: string;
+    data?: number[] | null;
+}
+
+export interface XYSeriesShadow {
+    objectType: 'xy';
+    name?: string;
+    data?: XYDataPoint[] | null;
+}
+
+export type SeriesShadow =
+    | BarSeriesShadow
+    | AreaSeriesShadow
+    | LineSeriesShadow
+    | PieSeriesShadow
+    | ScatterSeriesShadow
+    | YSeriesShadow
+    | XYSeriesShadow;
+
+// ──────────────────────────────────────────────
+// Chart, Table, Picture
+// ──────────────────────────────────────────────
+
+export interface ChartShadow {
+    name?: string;
+    categories?: unknown[] | null;
+    series?: SeriesShadow[] | null;
+}
+
+export interface TableShadow {
+    name?: string;
+    header?: unknown;
+    data?: unknown[] | null;
+}
+
+export interface PictureShadow {
+    name?: string;
+    data?: BinaryData;
+}
+
+// ──────────────────────────────────────────────
+// Binary Data
+// ──────────────────────────────────────────────
+
+export interface BinaryData {
+    encoding: 'HEX' | 'BASE_64';
+    data: unknown;
+    encryption?: 'AES' | null;
+    name?: string | null;
+    content_type?: string | null;
+    contentType?: unknown;
+}
+
+// ──────────────────────────────────────────────
+// Environment, Slide, Document
+// ──────────────────────────────────────────────
+
+export interface EnvironmentShadow {
+    parameters?: Record<string, unknown> | null;
+    charts?: ChartShadow[] | null;
+    tables?: TableShadow[] | null;
+    pictures?: PictureShadow[] | null;
+}
+
+export interface SlideShadow {
+    /** Slide number (1-based) */
+    number?: number;
+    environment?: EnvironmentShadow;
+}
+
+export interface DocumentShadow {
+    output?: string;
+    environment?: EnvironmentShadow;
+    slides?: SlideShadow[] | null;
+}
+
+
+/**
+ * Generates a PowerPoint file from a template and returns it as binary data (JSON-encoded)
+ * Base URL: PUT `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/powerpoint/{TEMPLATE_DIRECTORY}/{TEMPLATE_PATH}`
+ *
+ * @example
+ * import { powerpointAdapter } from 'epicenter-libs';
+ * const binaryData = await powerpointAdapter.generate('MODEL', 'en-US-debrief-template.pptx', {
+ *     output: 'debrief-slides.pptx',
+ *     environment: {},
+ *     slides: [
+ *         {
+ *             number: 1,
+ *             environment: {
+ *                 tables: [{ name: 'Leaderboard', data: [['Rank', 'Name', 'Score']] }],
+ *             },
+ *         },
+ *     ],
+ * });
+ *
+ * @param templateDirectory     Directory where the template is stored: 'DATA' or 'MODEL'
+ * @param templatePath          Path to the template file within the directory
+ * @param document              Document shadow defining the output filename, environment, and slides
+ * @param [optionals]           Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves to the generated PowerPoint as BinaryData
+ */
+export async function generate(
+    templateDirectory: TemplateDirectory,
+    templatePath: string,
+    document: DocumentShadow,
+    optionals: RoutingOptions = {},
+): Promise<BinaryData> {
+    return new Router()
+        .put(`/powerpoint/${templateDirectory}/${templatePath}`, {
+            body: document,
+            ...optionals,
+        }).then(({ body }) => body);
+}
+
+
+/**
+ * Generates a PowerPoint file from a template and returns it as a streaming response.
+ * Useful for downloading the generated file directly.
+ * Base URL: POST `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/powerpoint/{TEMPLATE_DIRECTORY}/{TEMPLATE_PATH}`
+ *
+ * @example
+ * import { powerpointAdapter } from 'epicenter-libs';
+ * const response = await powerpointAdapter.stream('MODEL', 'en-US-debrief-template.pptx', {
+ *     output: 'debrief-slides.pptx',
+ *     environment: {},
+ *     slides: [],
+ * });
+ * const blob = await response.blob();
+ *
+ * @param templateDirectory     Directory where the template is stored: 'DATA' or 'MODEL'
+ * @param templatePath          Path to the template file within the directory
+ * @param document              Document shadow defining the output filename, environment, and slides
+ * @param [optionals]           Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves to the raw Response for streaming/blob handling
+ */
+export async function stream(
+    templateDirectory: TemplateDirectory,
+    templatePath: string,
+    document: DocumentShadow,
+    optionals: RoutingOptions = {},
+): Promise<Response> {
+    const {
+        server,
+        accountShortName,
+        projectShortName,
+        useProjectProxy,
+        query,
+        headers: headersOverride,
+        authorization,
+        includeAuthorization,
+    } = optionals;
+    const url = new Router().getURL(`/powerpoint/${templateDirectory}/${templatePath}`, {
+        server,
+        accountShortName,
+        projectShortName,
+        useProjectProxy,
+        query,
+    });
+
+    const headers: Record<string, string> = {
+        'Content-type': 'application/json; charset=UTF-8',
+        ...headersOverride,
+    };
+
+    if (includeAuthorization !== false) {
+        const { session } = identification;
+        if (!headers.Authorization) {
+            if (session) headers.Authorization = `Bearer ${session.token}`;
+            if (authorization) headers.Authorization = authorization;
+            if (config.authOverride) headers.Authorization = config.authOverride;
+        }
+    }
+
+    return fetch(url.toString(), {
+        method: 'POST',
+        cache: 'no-cache',
+        redirect: 'follow',
+        headers,
+        body: JSON.stringify(document),
+    });
+}