feat: add forcePermissionLevel run option (#743)

We want Actor developers to be able to easily test their full permission
Actors with limited permissions without changing the Actor configuration
for everybody or redeploying the Actor under a different name. For that
reason, we have introduced a new `forcePermissionLevel` run option. This
PR adds the option to the client.

Full context here: apify/apify-core#22681

Author: tobice

package.json

@@ -62,7 +62,7 @@
         "build:browser": "rsbuild build"
     },
     "dependencies": {
-        "@apify/consts": "^2.25.0",
+        "@apify/consts": "^2.42.0",
         "@apify/log": "^2.2.6",
         "@apify/utilities": "^2.18.0",
         "@crawlee/types": "^3.3.0",

src/resource_clients/actor.ts

@@ -2,7 +2,7 @@ import type { AxiosRequestConfig } from 'axios';
 import ow from 'ow';
 
 import type { RUN_GENERAL_ACCESS } from '@apify/consts';
-import { ACT_JOB_STATUSES, META_ORIGINS } from '@apify/consts';
+import { ACT_JOB_STATUSES, ACTOR_PERMISSION_LEVEL, META_ORIGINS } from '@apify/consts';
 
 import type { ApiClientSubResourceOptions } from '../base/api_client';
 import { ResourceClient } from '../base/resource_client';
@@ -70,10 +70,11 @@ export class ActorClient extends ResourceClient {
                 webhooks: ow.optional.array.ofType(ow.object),
                 maxItems: ow.optional.number.not.negative,
                 maxTotalChargeUsd: ow.optional.number.not.negative,
+                forcePermissionLevel: ow.optional.string.oneOf(Object.values(ACTOR_PERMISSION_LEVEL)),
             }),
         );
 
-        const { waitForFinish, timeout, memory, build, maxItems, maxTotalChargeUsd } = options;
+        const { waitForFinish, timeout, memory, build, maxItems, maxTotalChargeUsd, forcePermissionLevel } = options;
 
         const params = {
             waitForFinish,
@@ -83,6 +84,7 @@ export class ActorClient extends ResourceClient {
             webhooks: stringifyWebhooksToBase64(options.webhooks),
             maxItems,
             maxTotalChargeUsd,
+            forcePermissionLevel,
         };
 
         const request: AxiosRequestConfig = {
@@ -126,6 +128,7 @@ export class ActorClient extends ResourceClient {
                 webhooks: ow.optional.array.ofType(ow.object),
                 maxItems: ow.optional.number.not.negative,
                 maxTotalChargeUsd: ow.optional.number.not.negative,
+                forcePermissionLevel: ow.optional.string.oneOf(Object.values(ACTOR_PERMISSION_LEVEL)),
             }),
         );
 
@@ -394,6 +397,12 @@ export interface ActorStartOptions {
     maxItems?: number;
 
     // TODO(PPE): add maxTotalChargeUsd after finished
+
+    /**
+     * Override the Actor's permissions for this run. If not set, the Actor will run with permissions configured in the
+     * Actor settings.
+     */
+    forcePermissionLevel?: ACTOR_PERMISSION_LEVEL;
 }
 
 export interface ActorCallOptions extends Omit<ActorStartOptions, 'waitForFinish'> {

src/resource_clients/task.ts

@@ -232,7 +232,7 @@ export interface TaskLastRunOptions {
     status?: keyof typeof ACT_JOB_STATUSES;
 }
 
-export type TaskStartOptions = Omit<ActorStartOptions, 'contentType'>;
+export type TaskStartOptions = Omit<ActorStartOptions, 'contentType' | 'forcePermissionLevel'>;
 
 export interface TaskCallOptions extends Omit<TaskStartOptions, 'waitForFinish'> {
     waitSecs?: number;