Update types to match the latest API and add docs

Author: Pijukatel

docs/guides/log_redirection.mdx

@@ -0,0 +1,64 @@
+---
+id: log-redirection
+title: Log redirection
+description: Redirect logs from another Actor run
+---
+
+import ApiLink from '@site/src/components/ApiLink';
+
+In some situations, one Actor is going to start one or more other Actors and wait for them to finish and produce some results. In such cases, you might want to redirect the logs of the started Actors' runs back to the parent Actor run, so that you can see the progress of the started Actors' runs in the parent Actor's logs. This guide will show possibilities on how to do it.
+
+### Redirecting logs from Actor.call
+
+Typical use case for log redirection is to call another Actor using the [`Actor.call()`](/reference/class/Actor#call) method. This method has an optional logger argument, which is by default set to the `default` literal. This means that the logs of the called Actor will be automatically redirected to the parent Actor's logs with default formatting and filtering. If you set the logger argument to `null`, then no log redirection happens. The third option is to pass your own `Log` instance with the possibility to define your specific logging. Below you can see those three possible ways of log redirection when starting another Actor run through Actor.call.
+
+```javascript
+import { Actor } from 'apify';
+import {LoggerActorRedirect} from 'apify-client';
+import { LEVELS, Log } from '@apify/log';
+
+const input = {}; // Some Actor input
+const actorId= 'someActorId'; // ID of actor you want to call
+
+await Actor.init();
+
+// Default log redirection - implicitly
+await Actor.call(actorId, input);
+
+// Default log redirection - explicitly
+await Actor.call(actorId, input, {log:'default'});
+
+// No log redirection
+await Actor.call(actorId, input, {log:null});
+
+// Custom log redirection
+await Actor.call(actorId, input, {log: new Log({ level: LEVELS.DEBUG, prefix: 'customPrefix', logger: new LoggerActorRedirect()});
+
+await Actor.exit();
+```
+
+Each default redirect log entry will have a specific format. After the timestamp, it will contain cyan colored text that will contain the redirect information - the other Actor's name and the run ID. The rest of the log message will be printed in the same manner as the parent Actor's log is configured.
+
+The log redirection can be deep, meaning that if the other Actor also starts another actor and is redirecting logs from it, then in the top-level Actor, you can see it as well. See the following example screenshot of the Apify log console when one Actor recursively starts itself (there are 2 levels of recursion in the example).
+
+### Redirecting logs from already running Actor run
+
+In some cases, you might want to connect to an already running Actor run and redirect its logs to your current Actor run. This can be done using the <ApiLink to="class/ApifyClient">`ApifyClient`</ApiLink> and getting the streamed log from a specific Actor run. You can then control the log redirection manually by explicitly calling start and stop methods.
+
+You can further decide whether you want to redirect just new logs of the ongoing Actor run, or if you also want to redirect historical logs from that Actor's run, so all logs it has produced since it was started. This can be controlled by the `fromStart` option of the `getStreamedLog()` method. If you set it to `true`, all historical logs will be redirected first, and then new logs will be redirected as they are produced. If you set it to `false`, only new logs will be redirected.
+
+```javascript
+import { Actor } from 'apify';
+
+const actorRunId = 'someRunId'; // ID of actor you want to call
+
+await Actor.init();
+
+// Redirect only new logs from the other Actor run, due to `fromStart: false`
+await Actor.newClient().run(actorRunId).getStreamedLog({ fromStart: false });
+streamedLog.start();
+// Do some stuff while also redirecting logs from another Actor
+await streamedLog.stop();
+
+await Actor.exit();
+```

package-lock.json

@@ -77,7 +77,7 @@
         "@types/semver": "^7.5.8",
         "@types/tough-cookie": "^4.0.5",
         "@types/ws": "^8.5.12",
-        "apify-client": "^2.17.0",
+        "apify-client": "^2.20.0",
         "commitlint": "^20.0.0",
         "crawlee": "^3.13.5",
         "eslint": "^9.23.0",

package.json

@@ -26,6 +26,7 @@ import type {
 import { sleep, snakeCaseToCamelCase } from '@crawlee/utils';
 import type {
     ActorCallOptions,
+    ActorStartOptions,
     ApifyClientOptions,
     RunAbortOptions,
     TaskCallOptions,
@@ -227,40 +228,37 @@ export interface ApifyEnv {
 
 export type UserFunc<T = unknown> = () => Awaitable<T>;
 
-export interface CallOptions extends Omit<ActorCallOptions, 'timeout'> {
+export interface Token {
     /**
-     * User API token that is used to run the Actor. By default, it is taken from the `APIFY_TOKEN` environment variable.
+     * User Apify API token that is used for API calls. By default, it is taken from the `APIFY_TOKEN` environment variable.
      */
     token?: string;
-    /**
-     * Timeout for the Actor run in seconds, or `'inherit'`.
-     *
-     * Using `inherit` will set timeout of the newly started Actor run to the time
-     * remaining until this Actor run times out so that the new run does not outlive this one.
-     */
-    timeout?: number | 'inherit';
 }
 
-export interface CallTaskOptions extends Omit<TaskCallOptions, 'timeout'> {
+export interface Timeout {
     /**
-     * User API token that is used to run the Actor. By default, it is taken from the `APIFY_TOKEN` environment variable.
-     */
-    token?: string;
-    /**
-     * Timeout for the Actor task in seconds, or `'inherit'`.
+     * Timeout for the Actor run in seconds, or `'inherit'`.
      *
-     * Using `inherit` will set timeout of the newly started Actor task to the time
+     * Using `inherit` will set timeout of the newly started Actor run to the time
      * remaining until this Actor run times out so that the new run does not outlive this one.
      */
     timeout?: number | 'inherit';
 }
 
-export interface AbortOptions extends RunAbortOptions {
-    /**
-     * User API token that is used to run the Actor. By default, it is taken from the `APIFY_TOKEN` environment variable.
-     */
-    token?: string;
-
+export interface CallOptions
+    extends Omit<ActorCallOptions, 'timeout'>,
+        Token,
+        Timeout {}
+export interface StartOptions
+    extends Omit<ActorStartOptions, 'waitForFinish' | 'timeout'>,
+        Token,
+        Timeout {}
+export interface CallTaskOptions
+    extends Omit<TaskCallOptions, 'timeout'>,
+        Token,
+        Timeout {}
+
+export interface AbortOptions extends RunAbortOptions, Token {
     /** Exit with given status message */
     statusMessage?: string;
 }
@@ -718,7 +716,7 @@ export class Actor<Data extends Dictionary = Dictionary> {
     async start(
         actorId: string,
         input?: unknown,
-        options: CallOptions = {},
+        options: StartOptions = {},
     ): Promise<ClientActorRun> {
         const timeout =
             options.timeout === 'inherit'

packages/apify/src/actor.ts

@@ -24,6 +24,7 @@ module.exports = {
                 'guides/pay-per-event',
                 'guides/type-script-actor',
                 'guides/docker-images',
+                'guides/log-redirection',
             ],
         },
         {