TypeScript Code for Workers

The minimal expected code is a function exported as default that should return the result of the worker’s script execution.

For example:

export default async function MyFunction() {

   // Do what you want

   return {
       status: 'DOWNLOAD_PROCEED',
       message: 'proceed',
   }
}

To enhance the developer experience we have chosen to use TypeScript. The worker function takes two inputs, which are injected.

export default async function (context: PlatformContext, data: T) Promise<U> {

   // Do what you want

   return {
       status: 'DOWNLOAD_PROCEED',
       message: 'proceed',
   }
}

Where T and U types stand for the data type (for example, BeforeDownloadRequest) and the expected returned response (like BeforeDownloadResponse for BeforeDownloadRequest).

Event payloads include a userContext object for the user or token that triggered the event. The object contains id (user ID or token ID), isToken, and realm. For more information, see Configure Workers for Custom Flows.

You can give a name to your function for convenience. You can also use anonymous functions instead.

The code editor also supports arrow functions. The samples provided in the documentation use arrow functions.

TypeScript APIs

You can use the following common interface types in your Worker code.

• PlatformContext
• PlatformClients
• PlatformHttpClient
• IPlatformHttpResponse
• PlatformHttpClientError
• StateManager

PlatformContext

interface PlatformContext {
   baseUrl: string; // platform base URL
   clients: PlatformClients; // clients to communicate with the platform or external resources
   platformToken: string; // platform access token
   wait: (delayMs: number) => Promise<void> // creates a promise that resolves after "duration" expressed in millisecondes
   state: StateManager; // State manager to store and retrieve state for this Worker between executions
   getRemainingExecutionTime: () => number // remaining milliseconds before the Worker execution times out
}

PlatformClients

Axios

The object axios is available inside the script. You can use this object to perform external calls. For more information, refer to the Axios Documentation.

interface PlatformClients {
   platformHttp: PlatformHttpClient // generic HTTP client to communicate with the platform. Hostname and token are set automatically.
   axios: AxiosInstance // generic HTTP client to communicate with external web resources.
}

PlatformHttpClient

PlatformHttpClient relies on Axios to perform HTTP requests. It is a ready to use client to call any JFrog Platform REST API. The endpoint input must be a relative URL with the pattern <serviceName>/api/<endpoint>. For example, the methods of the PlatformHttpClient, /artifactory/api/system/ping, return an object of type IPlatformHttpResponse or throw an object of type PlatformHttpClientError as error.

Use request(method, body, headers) when you need to send a request body with DELETE, or to specify a custom method, body, and headers. The get, post, put, patch, and delete methods are unchanged. The delete method does not accept a request body.

interface PlatformHttpClient {
   /**
    * Perform HTTP GET request to the JFrog Platform
    * @param {string} endpoint - API endpoint. For example, /artifactory/api/repositories
    * @param {Record<string, string>} headers - additional headers used in the request
    */
   get(endpoint: string, headers?: Record<string, string>): Promise<IPlatformHttpResponse>


   /**
    * Perform HTTP POST request to JFrog platform
    * @param {string} endpoint - API endpoint. For example, /artifactory/api/repositories
    * @param {any} requestData - data sent in request body
    * @param {Record<string, string>} headers - additional headers used in the request
    */
   post(endpoint: string, requestData?: any, headers?: Record<string, string>): Promise<IPlatformHttpResponse>


   /**
    * Perform HTTP PUT request to JFrog platform
    * @param {string} endpoint - API endpoint. For example, /artifactory/api/repositories
    * @param {any} requestData - data sent in request body
    * @param {Record<string, string>} headers - additional headers used in the request
    */
   put(endpoint: string, requestData?: any, headers?: Record<string, string>): Promise<IPlatformHttpResponse>


   /**
    * Perform HTTP PATCH request to JFrog platform
    * @param {string} endpoint - API endpoint. For example, /artifactory/api/repositories
    * @param {any} requestData - data sent in request body
    * @param {Record<string, string>} headers - additional headers used in the request
    */
   patch(endpoint: string, requestData?: any, headers?: Record<string, string>): Promise<IPlatformHttpResponse>


   /**
    * Perform HTTP DELETE request to JFrog platform
    * @param {string} endpoint - API endpoint. For example, /artifactory/api/repositories
    * @param {Record<string, string>} headers - additional headers used in the request
    */
   delete(endpoint: string, headers?: Record<string, string>): Promise<IPlatformHttpResponse>


   /**
    * Perform an HTTP request to the JFrog Platform. Use this method when you need to send a body with DELETE, or to specify the HTTP method, body, and headers without changing get, post, put, patch, or delete.
    * @param {string} method - HTTP method. For example, GET, POST, PUT, PATCH, or DELETE
    * @param {any} body - data sent in the request body, including for DELETE
    * @param {Record<string, string>} headers - additional headers used in the request
    */
   request(method: string, body?: any, headers?: Record<string, string>): Promise<IPlatformHttpResponse>
}

IPlatformHttpResponse

interface IPlatformHttpResponse {
   /**
    * HTTP status
    */
   status: number;
   /**
    * Response headers
    */
   headers: Record<string, string>;
   /**
    * Parsed response body
    */
   data: any;
}

PlatformHttpClientError

interface PlatformHttpClientError {
    /**
     * The reason of the error
     */
    message: string;

    /**
     * Http status
     */
    status: number;
}

StateManager

This interface allows you to set or modify a Worker state at runtime, which persists between Worker runs. For example:

export default async (context: PlatformContext): Promise<any> => {
  context.state.has('foo'); // false
  context.state.set('foo', 'bar');
  context.state.has('foo'); // true

  return context.state.getAll(); // { "foo": "bar" }
};

The state is stored as a string: to safely retrieve a number, use the following syntax:

const numberStr = context.state.get('number');
const number = Number.parseInt(numberStr) || 0;

This code will try to get the property ‘number’ from the state and convert it to a number. If it doesn't exist or cannot be parsed, the code returns 0.

interface StateManager {
    /**
     * Retrieves a value from the state by its key
     * @param {string} key - The key of the value to retrieve
     */
    get(key: string): string;
    /**
     * Sets a value in the state by its key
     * @param {string} key - The key of the value to set
     * @param {any} value - The value to set. If the value is not a string, it will be converted to a JSON string.
     */
    set(key: string, value: any): void;
    /**
     * Checks if a value exists in the state by its key
     * @param {string} key - The key of the value to check
     * @returns {boolean} - True if the value exists, false otherwise
     */
    has(key: string): boolean;
    /**
     * Deletes a value from the state by its key.
     * If it does not exist, it does nothing.
     * @param {string} key - The key of the value to delete
     */
    delete(key: string): void;
    /**
     * Clears the entire state
     */
    clear(): void;
    /**
     * Returns a copy of the entire state
     */
    getAll(): Record<string, string>;
}