@nebulateam/jarvis-sdk 0.0.0-stage → 5.57.9

package/README.md

@@ -1,3 +1,198 @@
-# Temporary Holding Version
+# @nebulateam/jarvis-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+JavaScript/TypeScript SDK for the **Jarvis public API**, distributed as an ES module with full type definitions,
+so editors such as VS Code offer IntelliSense on every client, request and response.
+
+This build targets **Jarvis 5.57.9** (SDK version 5.57.9).
+
+## Installation
+
+```sh
+npm install @nebulateam/jarvis-sdk
+```
+
+The package is ESM only (`import`), it has no runtime dependencies and uses the standard `fetch` API:
+it runs in browsers and in Node.js 18 or later.
+
+## Versions
+
+The SDK version follows the Jarvis release it was generated from: SDK `5.57.10` is built from the public API of Jarvis `5.57.10`.
+
+When the SDK needs a fix without a new Jarvis release, a version such as `5.57.10-fix.1` is published.
+For npm these are pre-release versions, so ranges like `^5.57.10` or `~5.57.10` do **not** pick them up. To get them:
+
+| What you need | Install |
+|---|---|
+| The latest SDK | `npm install @nebulateam/jarvis-sdk` (dist-tag `latest`) |
+| The latest SDK build for a given Jarvis version, fixes included | `npm install @nebulateam/jarvis-sdk@jarvis-5.57.10` |
+| An exact build | `npm install @nebulateam/jarvis-sdk@5.57.10-fix.1` |
+
+Use the SDK built for the Jarvis version you are calling: newer SDKs may contain endpoints your Jarvis does not have yet.
+
+## Quick start
+
+```ts
+import { Jarvis } from '@nebulateam/jarvis-sdk';
+
+const API_VERSION = '2';
+const jarvis = Jarvis.CreateClient('https://my-jarvis.example.com', process.env.JARVIS_TOKEN, { callInfoHeader: 'my-app' });
+
+const result = await jarvis.createWorkTaskClient().searchV2(API_VERSION, 'Workspace_12', {
+    text: 'pump',
+    startIndex: 0,
+    pageSize: 20
+});
+
+if (result.success) {
+    for (const task of result.data ?? []) {
+        console.log(task.id, task.title, task.statusId);
+    }
+} else {
+    console.error(result.error?.message);
+}
+```
+
+### Creating the client
+
+| Method | When to use it |
+|---|---|
+| `Jarvis.CreateClient(url, token?, { callInfoHeader? })` | Scripts, back-ends and applications that call a known Jarvis. |
+| `Jarvis.Autodiscover(devLocation?)` | Components served by Jarvis itself: they call the Jarvis that serves the page. On `localhost` they use `devLocation` (`{ url, token }`). |
+| `Jarvis.ConnectTo(location, token?)` | Like `Autodiscover`, with an explicit `Location`. |
+
+- **Authentication**: the token is sent in the `jarvis-auth-token` header. Omit it when the calls run in a browser page already authenticated on Jarvis.
+- **Call info**: `callInfoHeader` (or the `jarvisInfoHeader` argument of every `create...Client` method) is sent as `X-Jarvis-Call-Info`, to tag the calls made by your application.
+
+### API clients
+
+`JarvisClient` creates one client per area of the public API, for example:
+
+| Method | Area |
+|---|---|
+| `createWorkspaceClient()`, `createWorkspacePlanningClient()`, `createWorkTaskClient()`, `createTaskTypeV2Client()` | Workspaces, planning and work tasks |
+| `createDatasetClient()`, `createFieldsClient()`, `createPropertiesClient()` | Datasets, fields and properties |
+| `createDocumentClient()`, `createDocumentTypeClient()`, `createContainerClient()`, `createDmsSearchClient()`, `createFileUploadClient()` | Documents (DMS) |
+| `createTicketClient()` | Tickets |
+| `createAccountV2Client()`, `createContactV2Client()`, `createUsersClient()`, `createAvatarClient()` | Accounts, contacts and users |
+| `createIdTranslationV1Client()`, `createLongRunningJobClient()`, `createIntegrationClient()` | Utilities |
+
+Every client, method, request and response is documented in the type definitions: hover on a method in your editor to read it.
+All the generated clients and DTOs are also exported, so you can import types such as `OmniSearchPublicSearchRequest` directly.
+
+Each method takes the API version as first argument: use `'2'` for the V2 clients and `'1'` for the V1 ones
+(`ContactV1Client`, `PropertiesV1Client`, `IdTranslationV1Client`).
+
+### Responses and errors
+
+Most methods resolve to a response with:
+
+- `success`: `false` when the request failed validation or a constraint;
+- `data`: the result of the operation;
+- `logs` and `error`: what happened on the server.
+
+When Jarvis answers with an unexpected HTTP status the promise is rejected with an `ApiException`
+(`status`, `response`, `headers`):
+
+```ts
+import { ApiException } from '@nebulateam/jarvis-sdk';
+
+try {
+    const ticket = await jarvis.createTicketClient().detail('2', { ticketId: 'Ticket_1' });
+    if (!ticket.success) console.warn(ticket.error?.message, ticket.logs);
+} catch (e) {
+    if (e instanceof ApiException) console.error(e.status, e.response);
+}
+```
+
+## Examples
+
+### Filter work tasks by field values
+
+`filteringExpression` combines conditions on fields with `PublicFilteringLogic.And` / `Or`; operands can be nested expressions.
+Field values of a work task are returned in `fields`, one entry per field with its `values`.
+
+```ts
+import { PublicFilteringLogic, WorkTaskSearchResult } from '@nebulateam/jarvis-sdk';
+
+const workTasks = jarvis.createWorkTaskClient();
+
+const response = await workTasks.searchV2('2', 'Workspace_12', {
+    startIndex: 0,
+    pageSize: 100,
+    showArchived: false,
+    sortField: 'version',
+    sortDescending: true,
+    filteringExpression: {
+        logic: PublicFilteringLogic.And,
+        operands: [
+            { field: 'modelname', value: 'PUMP-200' },
+            { field: 'taskstatusid', filterType: 'notEqual', value: 'TaskStatus_9' }
+        ]
+    }
+});
+
+const fieldValue = (task: WorkTaskSearchResult, fieldId: string) =>
+    task.fields?.find((f) => f.id?.toLowerCase() === fieldId)?.values?.[0];
+
+for (const task of response.data ?? []) {
+    console.log(task.title, fieldValue(task, 'modelname'), fieldValue(task, 'assettype'));
+}
+```
+
+### Page through all the results
+
+```ts
+const pageSize = 200;
+const all: WorkTaskSearchResult[] = [];
+for (let startIndex = 0; ; startIndex += pageSize) {
+    const page = await workTasks.searchV2('2', 'Workspace_12', { startIndex, pageSize, showArchived: false });
+    if (!page.success) throw new Error(page.error?.message);
+    all.push(...(page.data ?? []));
+    if (!page.data?.length || all.length >= (page.total ?? 0)) break;
+}
+```
+
+### Search the selectable values of a field
+
+Useful to build pickers for selection fields (users, datasets, other work tasks...):
+
+```ts
+const fields = jarvis.createFieldsClient();
+
+const selection = await fields.searchSelection('2', {
+    field: 'customer',
+    term: 'acme',
+    startIndex: 0,
+    numOfRecords: 20
+});
+
+const options = (selection.data?.items ?? []).map((item) => ({ id: item.id, label: item.title }));
+console.log(`${options.length} of ${selection.data?.total ?? 0}`);
+```
+
+## Components embedded in Jarvis
+
+`JarvisShell` lets a page shown inside Jarvis (iframe or web component) interact with the host:
+
+```ts
+import { Jarvis, JarvisShell } from '@nebulateam/jarvis-sdk';
+
+// served by Jarvis: calls go to the same Jarvis with the user session; on localhost to the given dev instance
+const jarvis = Jarvis.Autodiscover({ url: 'https://my-dev-jarvis.example.com/', token: '<dev token>' }, undefined, { callInfoHeader: 'my-component' });
+
+const shell = new JarvisShell();
+shell.init((host, configuration) => {
+    host.showToast('Ready', `Hello ${configuration?.user.fullName}`, 'success');
+    host.on('WorkTask.Updated', (notification) => console.log('updated', notification.modelId));
+    host.on('WorkTask.Created', (notification) => console.log('created', notification.modelId));
+});
+
+// open a work task in Jarvis, in a new tab
+shell.navigateById('WorkTask_42', 'Workspace_12', true);
+```
+
+Available actions: `navigate`, `navigateById`, `openDetail`, `showToast`, `showDialog`, `showContextMenu` and subscriptions to Jarvis events (`on`).
+The actions supported by the host are listed in `configuration.capabilities`.
+
+`AutomationClient` calls the Jarvis Automation workflows (`getWorkflowInstance`, `getWorkflowInstances`, `dispatchSignal`, `triggerWorkflow`)
+from components served by Jarvis.

package/dist/app/automation-client.d.ts

@@ -0,0 +1,33 @@
+import { DispatchSignalResponse, GetWorkflowInstancesRequest, WorkflowInstance, WorkflowResponse } from "./automation-client.models";
+/** Result of {@link AutomationClient.triggerWorkflow}. */
+export declare class ResponseDto {
+    ok: boolean;
+    json: {
+        body?: any;
+        errorMessage?: string;
+    };
+    static create(ok: boolean, body?: string, errorMessage?: string): ResponseDto;
+}
+/**
+ * Client of Jarvis Automation (workflows), for components served by the same Jarvis:
+ * calls are relative to the page origin and use the browser session.
+ */
+export declare class AutomationClient {
+    private baseUrl;
+    private workflowActivationBaseUrl;
+    /** Gets a workflow instance by id. @throws AutomationApiException when the call fails */
+    getWorkflowInstance(id: string): Promise<WorkflowInstance>;
+    /** Searches the instances of a workflow. @throws AutomationApiException when the call fails */
+    getWorkflowInstances(request: GetWorkflowInstancesRequest): Promise<WorkflowResponse>;
+    /** Dispatches a signal to the workflows waiting for it. @throws AutomationApiException when the call fails */
+    dispatchSignal(signalName: string, input: any): Promise<DispatchSignalResponse>;
+    /**
+     * Triggers a workflow exposed through an HTTP endpoint.
+     * @param endpointVerb the verb of the workflow endpoint
+     * @param url the endpoint path, relative to /automation/workflows
+     * @param inputs query parameters (GET) or body (POST, required)
+     */
+    triggerWorkflow(endpointVerb: 'GET' | 'POST', url: string, inputs?: string[][] | Record<string, string | string[]>): Promise<ResponseDto>;
+    private fetchGet;
+    private fetchPost;
+}

package/dist/app/automation-client.models.d.ts

@@ -0,0 +1,77 @@
+/** Error raised by {@link AutomationClient} when Jarvis Automation answers with an error status. */
+export declare class AutomationApiException extends Error {
+    message: string;
+    status: number;
+    constructor(message: string, status: number);
+}
+export interface WorkflowResponse {
+    $id: string;
+    items: WorkflowInstance[];
+    page: number;
+    pageSize: number;
+    totalCount: number;
+}
+export interface WorkflowInstanceFault {
+    $id: string;
+    message: string;
+    exception: {
+        $id: string;
+        type: string;
+        message: string;
+        stackTrace: string;
+    };
+}
+export interface WorkflowInstance {
+    $id: string;
+    id: string;
+    definitionId: string;
+    definitionVersionId: string;
+    version: number;
+    workflowStatus: string;
+    correlationId: string;
+    createdAt: string;
+    lastExecutedAt: string;
+    finishedAt: string;
+    metadata: {
+        $id: string;
+    };
+    variables: {
+        $id: string;
+        data: {
+            [key: string]: any;
+        };
+    };
+    faults: WorkflowInstanceFault[];
+}
+export interface GetWorkflowInstancesRequest {
+    status?: string;
+    orderBy: string;
+    pageSize: number;
+    workflow: string;
+}
+export interface DispatchSignalResponse {
+    startedWorkflows: StartedWorkflow[];
+}
+export interface StartedWorkflow {
+    workflowInstanceId: string;
+    workflowInstance: StartedWorkflowInstance;
+    activityId: string;
+}
+export interface StartedWorkflowInstance {
+    definitionId: string;
+    definitionVersionId: string;
+    version: number;
+    workflowStatus: string;
+    correlationId: string;
+    createdAt: string;
+    variables: {
+        data: any;
+    };
+    activityData: any;
+    metadata: any;
+    blockingActivities: any[];
+    faults: any[];
+    scheduledActivities: any[];
+    scopes: any[];
+    id: string;
+}

package/dist/app/jarvis-client.d.ts

@@ -0,0 +1,201 @@
+import { AccountV2Client, ContactV2Client, ContainerV2Client, DatasetV2Client, DmsSearchV2Client, DocumentTypeV2Client, DocumentV2Client, FileUploadV2Client, JarvisApiBaseClient, JarvisApiConfig, JarvisFieldsV2Client, LongRunningJobPublicV2Client, PropertiesV2Client, TaskTypeV2Client, TicketV2Client, UsersV2Client, WorkTaskV2Client, WorkspaceV2Client, AvatarV2Client, IntegrationV2Client, WorkspacePlanningV2Client } from "./jarvis-public-api-v2.client";
+import { ContactV1Client, IdTranslationV1Client, PropertiesV1Client } from "./jarvis-public-api.client";
+/** Locale aware helpers to format dates for display and for the Jarvis API. */
+export declare class Formatters {
+    private _locale;
+    /**
+     *Creates an instance of Formatters.
+     * @param {string} [_locale="it-IT"]
+     * @memberof Formatters
+     */
+    constructor(_locale?: string);
+    static longDate: Intl.DateTimeFormatOptions;
+    static shortDate: Intl.DateTimeFormatOptions;
+    /** Formats a date with the client locale (short date by default). */
+    dateTime: (date: Date, options?: Intl.DateTimeFormatOptions) => string;
+    /** Formats a date as yyyyMMdd, the date-only format expected by the Jarvis API. */
+    toAPIDateOnly: (date: Date) => string;
+}
+/**
+ * Factory of the clients of the Jarvis public API, all sharing the same Jarvis address and credentials.
+ * Create it with {@link Jarvis.CreateClient} or {@link Jarvis.Autodiscover}.
+ * @example
+ * const jarvis = Jarvis.CreateClient('https://my-jarvis.example.com', '<api token>');
+ * const result = await jarvis.createWorkspaceClient().searchAllWorkspaces('2', { pageSize: 10 });
+ */
+export declare class JarvisClient {
+    private root;
+    private token?;
+    private callInfo?;
+    /** Date formatting helpers. */
+    readonly format: Formatters;
+    /**
+     * @param root the Jarvis address, e.g. https://my-jarvis.example.com
+     * @param token the API token, sent in the jarvis-auth-token header; omit it when the browser session is already authenticated
+     * @param callInfo default value of the X-Jarvis-Call-Info header, which tags the calls made by this client
+     */
+    constructor(root: string, token?: string | undefined, callInfo?: string | undefined);
+    /** True when the client points to a local Jarvis (localhost or 127.0.0.1). */
+    isLocalHost(): boolean;
+    /**
+     * Creates a TicketV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createTicketClient: (jarvisInfoHeader?: string) => TicketV2Client;
+    /**
+     * Creates a WorkspaceV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createWorkspaceClient: (jarvisInfoHeader?: string) => WorkspaceV2Client;
+    /**
+     * Creates a WorkspacePlanningV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createWorkspacePlanningClient: (jarvisInfoHeader?: string) => WorkspacePlanningV2Client;
+    /**
+     * Creates a WorkTaskV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createWorkTaskClient: (jarvisInfoHeader?: string) => WorkTaskV2Client;
+    /**
+     * Creates a DatasetV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createDatasetClient: (jarvisInfoHeader?: string) => DatasetV2Client;
+    /**
+     * Creates a DocumentV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createDocumentClient: (jarvisInfoHeader?: string) => DocumentV2Client;
+    /**
+     * Creates a ContainerV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createContainerClient: (jarvisInfoHeader?: string) => ContainerV2Client;
+    /**
+     * Creates a DocumentTypeV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createDocumentTypeClient: (jarvisInfoHeader?: string) => DocumentTypeV2Client;
+    /**
+     * Creates a DmsSearchV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createDmsSearchClient: (jarvisInfoHeader?: string) => DmsSearchV2Client;
+    /**
+     * Creates a UsersV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createUsersClient: (jarvisInfoHeader?: string) => UsersV2Client;
+    /**
+     * Creates a FileUploadV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createFileUploadClient: (jarvisInfoHeader?: string) => FileUploadV2Client;
+    /**
+     * Creates a ContactV1Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createContactV1Client: (jarvisInfoHeader?: string) => ContactV1Client;
+    /**
+     * Creates a ContactV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createContactV2Client: (jarvisInfoHeader?: string) => ContactV2Client;
+    /**
+     * Creates a AccountV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createAccountV2Client: (jarvisInfoHeader?: string) => AccountV2Client;
+    /**
+     * Creates a PropertiesV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createPropertiesClient: (jarvisInfoHeader?: string) => PropertiesV2Client;
+    /**
+     * Creates a JarvisFieldsV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createFieldsClient: (jarvisInfoHeader?: string) => JarvisFieldsV2Client;
+    /**
+     * Creates a PropertiesV1Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createPropertiesV1Client: (jarvisInfoHeader?: string) => PropertiesV1Client;
+    /**
+     * Creates a IdTranslationV1Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createIdTranslationV1Client: (jarvisInfoHeader?: string) => IdTranslationV1Client;
+    /**
+     * Creates a LongRunningJobPublicV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createLongRunningJobClient: (jarvisInfoHeader?: string) => LongRunningJobPublicV2Client;
+    /**
+     * Creates a TaskTypeV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createTaskTypeV2Client: (jarvisInfoHeader?: string) => TaskTypeV2Client;
+    /**
+     * Creates a AvatarV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createAvatarClient: (jarvisInfoHeader?: string) => AvatarV2Client;
+    /**
+     * Creates a IntegrationV2Client.
+     * @param jarvisInfoHeader overrides the X-Jarvis-Call-Info header for the calls of this client
+     */
+    createIntegrationClient: (jarvisInfoHeader?: string) => IntegrationV2Client;
+}
+/** Creates a generated API client with the configuration of a {@link JarvisClient}. */
+export declare class JarvisTsClient<T extends JarvisApiBaseClient> {
+    private clientType;
+    private baseUrl?;
+    private token?;
+    private jarvisCallInfoHeader?;
+    constructor(clientType: new (config: JarvisApiConfig, baseUrl?: string, http?: {
+        fetch(url: RequestInfo, init?: RequestInit): Promise<Response>;
+    }) => T, baseUrl?: string | undefined, token?: string | undefined, jarvisCallInfoHeader?: string | undefined);
+    createClient(http?: {
+        fetch(url: RequestInfo, init?: RequestInit): Promise<Response>;
+    }): T;
+}
+/** Entry point of the SDK: creates a {@link JarvisClient}. */
+export declare class Jarvis {
+    /**
+     * Creates a client for the given Jarvis address.
+     * @param root the Jarvis address, e.g. https://my-jarvis.example.com
+     * @param token the API token; omit it when the browser session is already authenticated
+     * @param contextInfo optional X-Jarvis-Call-Info header sent with every call
+     */
+    static CreateClient: (root: string, token?: string, contextInfo?: {
+        callInfoHeader?: string;
+    }) => JarvisClient;
+    /**
+     * For components hosted inside Jarvis: connects to the Jarvis that serves the page.
+     * On localhost it uses {@link Jarvis.CreateDevClient} instead.
+     * @param jarvisLocation Jarvis address and token to use during local development
+     * @param location the page location, window.location by default
+     */
+    static Autodiscover: (jarvisLocation?: {
+        url: string;
+        token: string;
+    }, location?: Location, contextInfo?: {
+        callInfoHeader?: string;
+    }) => JarvisClient;
+    /**
+     * Client for local development: uses jarvisLocation or, when missing, the JARVIS_URI and token
+     * globals defined by the development proxy.
+     */
+    static CreateDevClient: (jarvisLocation?: {
+        url: string;
+        token: string;
+    }, contextInfo?: {
+        callInfoHeader?: string;
+    }) => JarvisClient;
+    /** Creates a client for the Jarvis at the given page location (protocol, host and port). */
+    static ConnectTo: (location: Location, token?: string, contextInfo?: {
+        callInfoHeader?: string;
+    }) => JarvisClient;
+}