feat: surface approval URL when calling unapproved Actor (#1111)

tldr; the run Actor API returns an `approvalUrl` when an Actor needs
full account access — we were swallowing it and only printing the bare
error message.

  ## Before
  Run: Calling Actor apify/puppeteer-scraper (YJCnS9qogi9XxDgLB)

Error: This Actor requires full access to your account. You must approve
its permissions before running it.

  ## After
<img width="912" height="113" alt="image"
src="https://github.com/user-attachments/assets/c9d4376f-a0dd-4746-8842-7f72eabcb2ae"
/>


Handled in the same `catch` block as `record-not-found` in
`run-on-cloud.ts`. Affects `apify call`, `apify actors call`, `apify
actors start`, `apify task run` and `apify tasks run`.

  ## Test plan
- [x] Manually triggered against `apify/puppeteer-scraper`, approval URL
surfaces correctly
- [ ] Add a vitest case for the `full-permission-actor-not-approved`
branch

Author: raethlo

src/lib/commands/run-on-cloud.ts

@@ -88,6 +88,17 @@ export async function* runActorOrTaskOnCloud(apifyClient: ApifyClient, options:
 			throw new Error(`${type} ${actorOrTaskData.userFriendlyId} (${actorOrTaskData.id}) not found!`);
 		}
 
+		if (err.type === 'full-permission-actor-not-approved') {
+			const approvalUrl: string | undefined = err.data?.approvalUrl;
+			const lines = [
+				`${type} ${actorOrTaskData.userFriendlyId} requires full access to your Apify account and has not been approved yet.`,
+			];
+			if (approvalUrl) {
+				lines.push('', `Approve here: ${chalk.blue(approvalUrl)}`);
+			}
+			throw new Error(lines.join('\n'));
+		}
+
 		throw err;
 	}
 

test/local/lib/run-on-cloud.test.ts

@@ -0,0 +1,57 @@
+import type { ApifyClient } from 'apify-client';
+
+import { runActorOrTaskOnCloud } from '../../../src/lib/commands/run-on-cloud.js';
+
+const fakeClientThatThrows = (error: unknown) =>
+	({
+		actor: () => ({
+			start: async () => {
+				throw error;
+			},
+		}),
+	}) as unknown as ApifyClient;
+
+const callAndCatch = async (apiError: unknown) => {
+	const iterator = runActorOrTaskOnCloud(fakeClientThatThrows(apiError), {
+		actorOrTaskData: { id: 'abc', userFriendlyId: 'apify/test-actor' },
+		runOptions: {},
+		type: 'Actor',
+		silent: true,
+	});
+
+	try {
+		for await (const _ of iterator) {
+			// drain
+		}
+	} catch (err) {
+		return err as Error;
+	}
+
+	throw new Error('Expected runActorOrTaskOnCloud to throw');
+};
+
+describe('runActorOrTaskOnCloud', () => {
+	it('surfaces approval URL when Actor requires full account access', async () => {
+		const approvalUrl = 'https://console.apify.com/actors/abc?approvePermissions=true';
+		const apiError = Object.assign(new Error('This Actor requires full access to your account.'), {
+			type: 'full-permission-actor-not-approved',
+			data: { approvalUrl },
+		});
+
+		const err = await callAndCatch(apiError);
+
+		expect(err.message).toMatch(/has not been approved yet/);
+		expect(err.message).toContain(approvalUrl);
+	});
+
+	it('falls back to bare message when API response has no approvalUrl', async () => {
+		const apiError = Object.assign(new Error('This Actor requires full access to your account.'), {
+			type: 'full-permission-actor-not-approved',
+		});
+
+		const err = await callAndCatch(apiError);
+
+		expect(err.message).toMatch(/has not been approved yet/);
+		expect(err.message).not.toMatch(/Approve here/);
+	});
+});