epicenter-libs 3.34.2 → 3.35.0

package/src/adapters/task.ts

@@ -1,17 +1,35 @@
-import type { RoutingOptions } from '../utils/router';
-import type { GenericScope, Address } from '../utils/constants';
+import type { Address, GenericScope, GenericSearchOptions } from '../utils/constants';
+import type { Page, RoutingOptions } from '../utils/router';
 
+import { parseFilterInput } from '../utils/filter-parser';
 import Router from '../utils/router';
 
 export enum RETRY_POLICY {
     DO_NOTHING = 'DO_NOTHING', // If the task fails, do nothing (this is the default)
-    RESCHEDULE = 'RESCHEDULE', // If the task fails retry at the next scheduled time point
-    FIRE_ON_FAIL_SAFE = 'FIRE_ON_FAIL_SAFE', // Will re-execute the task after it fails; how long until this occurs is equal to ttlSeconds
+    FIRE_ON_FAIL_SAFE = 'FIRE_ON_FAIL_SAFE', // Retry within the task's fail-safe execution window
 }
 
 // Generic type aliases for task adapter
 export type TaskPayloadBody = Record<string, unknown>;
 export type TaskPayloadHeaders = Record<string, string>;
+export type TaskHttpMethod =
+    | 'GET'
+    | 'POST'
+    | 'PUT'
+    | 'DELETE';
+export type TaskRetryPolicyReadOutView = 'do_nothing' | 'fire_on_fail_safe';
+export type TaskStatusReadOutView =
+    | 'initialized'
+    | 'triggered'
+    | 'succeeded'
+    | 'failed'
+    | 'cancelled'
+    | 'terminated';
+export type TaskAddressReadOutView = Partial<Address>;
+
+export interface TaskScopeReadOutView extends GenericScope {
+    userKey?: string;
+}
 
 // Status type for group status tasks
 export interface StatusReadOutView {
@@ -53,10 +71,12 @@ export interface HttpTaskPayloadCreateInView<
     H extends object = TaskPayloadHeaders,
 > {
     objectType: 'http';
-    method: string;
+    method: TaskHttpMethod;
     url: string;
+    target?: 'APPLICATION' | 'PROXY';
     body: B;
     headers?: H;
+    timeoutSeconds?: number;
 }
 
 export interface GroupStatusTaskPayloadCreateInView {
@@ -72,16 +92,30 @@ export type TaskPayloadCreateInView<
     | HttpTaskPayloadCreateInView<B, H>
     | GroupStatusTaskPayloadCreateInView;
 
+export type HttpTaskPayloadCreateInput<
+    B extends object = TaskPayloadBody,
+    H extends object = TaskPayloadHeaders,
+> = Omit<HttpTaskPayloadCreateInView<B, H>, 'objectType'> & {
+    objectType?: 'http';
+};
+
+export type TaskPayloadCreateInput<
+    B extends object = TaskPayloadBody,
+    H extends object = TaskPayloadHeaders,
+> = HttpTaskPayloadCreateInput<B, H> | GroupStatusTaskPayloadCreateInView;
+
 // Payload type definitions for reading tasks
 export interface HttpTaskPayloadReadOutView<
     B extends object = TaskPayloadBody,
     H extends object = TaskPayloadHeaders,
 > {
     objectType: 'http';
-    method?: string;
+    method?: TaskHttpMethod;
     url?: string;
+    target?: 'application' | 'proxy';
     body?: B;
     headers?: H;
+    timeoutSeconds?: number;
 }
 
 export interface GroupStatusTaskPayloadReadOutView {
@@ -104,22 +138,38 @@ export interface TaskReadOutView<
 > {
     taskKey?: string;
     name?: string;
-    status?: string;
+    status?: TaskStatusReadOutView;
     cron?: string;
     mutationKey?: string;
     failures?: number;
     successes?: number;
-    address?: Address;
+    address?: TaskAddressReadOutView;
     payload?: TaskPayloadReadOutView<B, H>;
-    scope?: GenericScope;
-    retryPolicy?: string;
+    scope?: TaskScopeReadOutView;
+    retryPolicy?: TaskRetryPolicyReadOutView;
     failSafeTermination?: string;
     ttlSeconds?: number;
 }
 
+export interface TaskHistoryReadOutView {
+    result?: string;
+    execution?: number;
+    response?: number;
+    success?: boolean;
+    taskId?: number;
+}
+
+export interface TaskPageOptions {
+    first?: number;
+    max?: number;
+}
+
+export interface TaskScopePageOptions extends TaskPageOptions {
+    sort?: string[];
+}
 
 /**
- * Creates a task; requires support level authentication
+ * Creates a task; requires facilitator (or higher) privileges
  * Base URL: POST `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/task`
  *
  * @example
@@ -131,7 +181,9 @@ export interface TaskReadOutView<
  * const name = 'task-1-send-emails';
  * const payload = {
  *     method: 'POST',
- *     url: 'https://forio.com/app/forio-dev/test-project/send-out-emails',
+ *     url: '/send-out-emails',
+ *     target: 'PROXY', // fire at the project's proxy server; omit to fire at the app
+ *     body: {},
  * };
  * const trigger = {
  *     value: '0 7 15 * * ?', // triggers on day 15 7am of each month
@@ -144,11 +196,13 @@ export interface TaskReadOutView<
  * @param scope.scopeKey                        Scope key, a unique identifier tied to the scope. E.g., if your `scopeBoundary` is `GROUP`, your `scopeKey` will be your `groupKey`; for `EPISODE`, `episodeKey`, etc.
  * @param [scope.userKey]                       Key associated with the user
  * @param name                                  Name of the task
- * @param payload                               An HTTP task object that will be executed when the task is triggered
- * @param payload.method                        Type of method to use with the HTTP request (e.g., 'GET', 'POST', 'PATCH')
- * @param payload.url                           The URL the HTTP request will be sent to
- * @param [payload.body]                        The body of the HTTP request
- * @param [payload.headers]                     Headers to send along with the HTTP request
+ * @param payload                               An HTTP request or group-status change to execute when the task is triggered
+ * @param payload.method                        Type of method to use with the HTTP request (e.g., 'GET', 'POST')
+ * @param payload.url                           Relative URL the HTTP request will be sent to; the task runner builds the full URL as `{host}{targetPath}/{account}/{project}{url}`
+ * @param [payload.target]                      Where the task fires: 'APPLICATION' (the project app, `/app`, the default) or 'PROXY' (the project's proxy server, `/proxy`)
+ * @param payload.body                          The JSON body of the HTTP request
+ * @param [payload.headers]                     Headers to send along with the HTTP request; must be non-empty when provided — omit rather than pass an empty object
+ * @param [payload.timeoutSeconds]               Request timeout in seconds (1–30)
  * @param trigger                               Object that determines when to run the task (cron, offset, or date)
  * @param [trigger.value]                       For cron: cron expression (e.g., '0 7 * * * ?'). For date: ISO-8601 date-time string
  * @param [trigger.objectType]                  Type of trigger: 'cron', 'offset', or 'date'
@@ -159,8 +213,8 @@ export interface TaskReadOutView<
  * @param [optionals.accountShortName]          Name of account (by default will be the account associated with the session)
  * @param [optionals.projectShortName]          Name of project (by default will be the project associated with the session)
  * @param [optionals.retryPolicy]               Specifies what to do should the task fail; see RETRY_POLICY
- * @param [optionals.failSafeTermination]       The ISO-8601 date-time when the task will be deleted regardless of any triggers; defaults to null
- * @param [optionals.ttlSeconds]                Max life expectancy of the task; used to determine if retrying the task is necessary
+ * @param [optionals.failSafeTermination]       ISO-8601 deadline after which the task terminates; the server defaults and caps this at one year from creation
+ * @param [optionals.ttlSeconds]                Execution fail-safe window in seconds; the server applies its configured minimum
  * @returns promise that resolves to the task object including the taskKey
  */
 export async function create<
@@ -169,16 +223,11 @@ export async function create<
 >(
     scope: { userKey?: string } & GenericScope,
     name: string,
-    payload: {
-        method: string;
-        url: string;
-        body?: B;
-        headers?: H;
-    },
+    payload: TaskPayloadCreateInput<B, H>,
     trigger: TaskTriggerCreateInView,
     optionals: {
         retryPolicy?: keyof typeof RETRY_POLICY;
-        failSafeTermination?: number;
+        failSafeTermination?: string;
         ttlSeconds?: number;
     } & RoutingOptions = {},
 ): Promise<TaskReadOutView<B, H>> {
@@ -188,12 +237,16 @@ export async function create<
         ttlSeconds,
         ...routingOptions
     } = optionals;
+    const normalizedPayload: TaskPayloadCreateInView<B, H> =
+        payload.objectType === 'groupStatus' ?
+            payload :
+            { ...payload, objectType: 'http' };
     return await new Router()
         .post(
             '/task',
             {
                 body: {
-                    payload: { objectType: 'http' as const, ...payload },
+                    payload: normalizedPayload,
                     trigger,
                     retryPolicy,
                     failSafeTermination,
@@ -209,7 +262,7 @@ export async function create<
 
 
 /**
- * Deletes a task (changes status to cancelled); requires support level authentication
+ * Deletes a task (changes status to cancelled); requires facilitator (or higher) privileges
  * Base URL: DELETE `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/task/{TASK_KEY}`
  *
  * @example
@@ -218,7 +271,7 @@ export async function create<
  * await taskAdapter.destroy(taskKey);
  *
  * @param taskKey                               Unique key associated with a task
- * @param [optionals]                           Optional arguments; pass network call options overrides here. Special arguments specific to this method are listed below if they exist.
+ * @param [optionals]                           Optional arguments; pass network call options overrides here.
  * @param [optionals.accountShortName]          Name of account (by default will be the account associated with the session)
  * @param [optionals.projectShortName]          Name of project (by default will be the project associated with the session)
  * @returns promise that resolves to undefined when successful
@@ -234,7 +287,7 @@ export async function destroy(
 
 
 /**
- * Gets a task by taskKey; requires support level authentication
+ * Gets a task by taskKey; requires facilitator (or higher) privileges
  * Base URL: GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/task/{TASK_KEY}`
  *
  * @example
@@ -243,7 +296,7 @@ export async function destroy(
  * const task = await taskAdapter.get(taskKey);
  *
  * @param taskKey                               Unique key associated with a task
- * @param [optionals]                           Optional arguments; pass network call options overrides here. Special arguments specific to this method are listed below if they exist.
+ * @param [optionals]                           Optional arguments; pass network call options overrides here.
  * @param [optionals.accountShortName]          Name of account (by default will be the account associated with the session)
  * @param [optionals.projectShortName]          Name of project (by default will be the project associated with the session)
  * @returns promise that resolves to the task object
@@ -259,7 +312,7 @@ export async function get<
 
 
 /**
- * Gets the history (100 most recent times it has triggered) of a task by taskKey; requires support level authentication
+ * Gets the history (100 most recent times it has triggered) of a task by taskKey; requires facilitator (or higher) privileges
  * Base URL: GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/task/history/{TASK_KEY}`
  *
  * @example
@@ -268,26 +321,30 @@ export async function get<
  * const history = await taskAdapter.getHistory(taskKey);
  *
  * @param taskKey                               Unique key associated with a task
- * @param [optionals]                           Optional arguments; pass network call options overrides here. Special arguments specific to this method are listed below if they exist.
+ * @param [optionals]                           Pagination and network options
+ * @param [optionals.first]                     Zero-based index of the first history record; defaults to 0
+ * @param [optionals.max]                       Maximum history records to return; defaults to 100 and cannot exceed 100
  * @param [optionals.accountShortName]          Name of account (by default will be the account associated with the session)
  * @param [optionals.projectShortName]          Name of project (by default will be the project associated with the session)
- * @returns promise that resolves to an array of task history objects
+ * @returns promise that resolves to a page of task history objects
  */
-export async function getHistory<
-    B extends object = TaskPayloadBody,
-    H extends object = TaskPayloadHeaders,
->(
+export async function getHistory(
     taskKey: string,
-    optionals: RoutingOptions = {},
-): Promise<TaskReadOutView<B, H>[]> {
+    optionals: TaskPageOptions & RoutingOptions = {},
+): Promise<Page<TaskHistoryReadOutView>> {
+    const { first, max, ...routingOptions } = optionals;
     return await new Router()
-        .get(`/task/history/${taskKey}`, optionals)
+        .withSearchParams({ first, max })
+        .get(`/task/history/${taskKey}`, {
+            paginated: true,
+            ...routingOptions,
+        })
         .then(({ body }) => body);
 }
 
 
 /**
- * Gets most recent 100 tasks related to the selected scope; requires support level authentication
+ * Gets most recent 100 tasks related to the selected scope; requires facilitator (or higher) privileges
  * Base URL: GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/task/in/{SCOPE_BOUNDARY}/{SCOPE_KEY}` or GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/task/in/{SCOPE_BOUNDARY}/{SCOPE_KEY}/{USER_KEY}`
  *
  * Note: Will retrieve all tasks that were CREATED in the specified scope. If something was created with episode scope, it will not be retrievable through group scoping.
@@ -304,25 +361,91 @@ export async function getHistory<
  * @param scope.scopeBoundary                   Scope boundary, defines the type of scope; See [scope boundary](#SCOPE_BOUNDARY) for all types
  * @param scope.scopeKey                        Scope key, a unique identifier tied to the scope. E.g., if your `scopeBoundary` is `GROUP`, your `scopeKey` will be your `groupKey`; for `EPISODE`, `episodeKey`, etc.
  * @param [scope.userKey]                       Key associated with the user; will retrieve tasks in the scope that were made by the specified user
- * @param [optionals]                           Optional arguments; pass network call options overrides here. Special arguments specific to this method are listed below if they exist.
+ * @param [optionals]                           Pagination, sorting, and network options
+ * @param [optionals.sort]                      Task fields to sort by
+ * @param [optionals.first]                     Zero-based index of the first task; defaults to 0
+ * @param [optionals.max]                       Maximum tasks to return; defaults to 100 and cannot exceed 100
  * @param [optionals.accountShortName]          Name of account (by default will be the account associated with the session)
  * @param [optionals.projectShortName]          Name of project (by default will be the project associated with the session)
- * @returns promise that resolves to an array of task objects
+ * @returns promise that resolves to a page of task objects
  */
 export async function getTaskIn<
     B extends object = TaskPayloadBody,
     H extends object = TaskPayloadHeaders,
 >(
     scope: { userKey?: string } & GenericScope,
-    optionals: RoutingOptions = {},
-): Promise<TaskReadOutView<B, H>[]> {
+    optionals: TaskScopePageOptions & RoutingOptions = {},
+): Promise<Page<TaskReadOutView<B, H>>> {
     const { scopeBoundary, scopeKey, userKey } = scope;
+    const { sort = [], first, max, ...routingOptions } = optionals;
     return await new Router()
+        .withSearchParams({
+            sort: sort.join(';') || undefined,
+            first,
+            max,
+        })
         .get(
             `/task/in/${scopeBoundary}/${scopeKey}${
                 userKey ? `/${userKey}` : ''
             }`,
-            optionals,
+            {
+                paginated: true,
+                ...routingOptions,
+            },
         )
         .then(({ body }) => body);
 }
+
+
+/**
+ * Queries for tasks
+ * Base URL: GET `https://forio.com/api/v3/{ACCOUNT}/{PROJECT}/task/search`
+ *
+ * No authentication is required; results use facilitator-level row visibility.
+ * Filterable/sortable fields include
+ * `task.taskKey`, `task.name`, `task.status`, `task.scopeBoundary`, `task.scopeKey`,
+ * `task.userKey`, `task.groupName`, `task.episodeName`, `task.nextExecution`,
+ * `task.failSafeExecution`, and `task.created`.
+ *
+ * @example
+ * import { taskAdapter } from 'epicenter-libs';
+ * const page = await taskAdapter.query({
+ *     filter: [
+ *         'task.scopeKey=0000017dd3bf540e5ada5b1e058f08f20461',    // tasks scoped to this group
+ *         'task.status=INITIALIZED',                               // that have not yet fired
+ *     ],
+ *     sort: ['-task.created'],    // newest first
+ *     max: 10,                    // page should only include the first 10 items
+ * });
+ *
+ * @param searchOptions                         Search options for the query
+ * @param [searchOptions.filter]                Filters for searching
+ * @param [searchOptions.sort]                  Sorting criteria
+ * @param [searchOptions.first]                 The starting index of the page returned
+ * @param [searchOptions.max]                   The number of entries per page
+ * @param [optionals]                           Optional arguments; pass network call options overrides here.
+ * @returns promise that resolves to a page of tasks
+ */
+export async function query<
+    B extends object = TaskPayloadBody,
+    H extends object = TaskPayloadHeaders,
+>(
+    searchOptions: GenericSearchOptions,
+    optionals: RoutingOptions = {},
+): Promise<Page<TaskReadOutView<B, H>>> {
+    const { filter, sort = [], first, max } = searchOptions;
+
+    const searchParams = {
+        filter: parseFilterInput(filter),
+        sort: sort.join(';') || undefined,
+        first, max,
+    };
+
+    return await new Router()
+        .withSearchParams(searchParams)
+        .get('/task/search', {
+            paginated: true,
+            ...optionals,
+        })
+        .then(({ body }) => body);
+}

package/src/epicenter.ts

@@ -1,8 +1,8 @@
 import 'regenerator-runtime/runtime';
 
-/* yes, this string template literal is weird;
- * it's cause rollup does not recogize __VERSION__ as an individual token otherwise */
-const version = `Epicenter (v${'__VERSION__'}) for __BUILD__ | Build Date: __DATE__`;
+/* __VERSION__, __BUILD__ and __DATE__ are injected at build time — by
+ * @rollup/plugin-replace for the shipped bundles and by Vite's `define` for tests */
+const version = `Epicenter (v${__VERSION__}) for ${__BUILD__} | Build Date: ${__DATE__}`;
 
 import type { RetryFunction } from './utils/router';
 import { authAdapter, cometdAdapter } from './adapters';
@@ -123,8 +123,15 @@ export {
     dailyAdapter,
     matchmakerAdapter,
     walletAdapter,
+    pipelineAdapter,
+    encyclopediaAdapter,
+    fileAdapter,
+    registrationAdapter,
+    docketAdapter,
     Channel,
     cometdAdapter,
+    gitAdapter,
+    powerpointAdapter,
 } from './adapters';
 
 /* APIs */

package/src/globals.d.ts

@@ -14,3 +14,9 @@ interface JSONObject {
 }
 
 type JSONArray = Array<JSONValue>;
+
+/* Build-time constants injected by @rollup/plugin-replace (shipped bundles)
+ * and Vite's `define` (tests). See src/epicenter.ts. */
+declare const __VERSION__: string;
+declare const __BUILD__: string;
+declare const __DATE__: string;

package/src/types.ts

@@ -234,6 +234,11 @@ export type {
     RETRY_POLICY,
     TaskPayloadBody,
     TaskPayloadHeaders,
+    TaskHttpMethod,
+    TaskRetryPolicyReadOutView,
+    TaskStatusReadOutView,
+    TaskAddressReadOutView,
+    TaskScopeReadOutView,
     StatusReadOutView,
     StatusCreateInView,
     CronTaskTriggerCreateInView,
@@ -243,10 +248,15 @@ export type {
     HttpTaskPayloadCreateInView,
     GroupStatusTaskPayloadCreateInView,
     TaskPayloadCreateInView,
+    HttpTaskPayloadCreateInput,
+    TaskPayloadCreateInput,
     HttpTaskPayloadReadOutView,
     GroupStatusTaskPayloadReadOutView,
     TaskPayloadReadOutView,
     TaskReadOutView,
+    TaskHistoryReadOutView,
+    TaskPageOptions,
+    TaskScopePageOptions,
 } from './adapters/task';
 
 // User Adapter
@@ -306,6 +316,57 @@ export type {
     OrbitType,
 } from './adapters/world';
 
+// File Adapter
+export type {
+    FileEntry,
+    DirectoryEntry,
+    FileSystemEntry,
+} from './adapters/file';
+
+// Registration Adapter
+export type {
+    RegistrationInfo,
+    TeamRegistrationInfo,
+    RegistrationResult,
+    WhoAmI,
+    WhoAmIObjectType,
+    TeamRole,
+    SsoProtocol,
+} from './adapters/registration';
+
+// Docket Adapter
+export type {
+    OperatingSystem,
+    WorkerShape,
+    ScaleFlavor,
+    ScaleCreateInView,
+    ScaleReadOutView,
+    ScaleDocketPayloadCreateInView,
+    ScaleDocketPayloadReadOutView,
+    DocketPayloadCreateInView,
+    DocketPayloadReadOutView,
+    DocketReadOutView,
+} from './adapters/docket';
+
+// Encyclopedia Adapter
+export type {
+    EncyclopediaTranslator,
+    DocumentedEndpointMethod,
+    DocumentedEndpointAuthorization,
+    DocumentedEndpointNotation,
+    DocumentedParameterSource,
+    DocumentedParameter,
+    DocumentedEndpoint,
+    DocumentedResource,
+    KnownServiceReadOutView,
+} from './adapters/encyclopedia';
+
+// Pipeline Adapter
+export type {
+    PipelineExecutionStatus,
+    PipelineAuditReadOutView,
+} from './adapters/pipeline';
+
 // Somebody Adapter
 export type {
     Somebody,

package/src/utils/router.ts

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