Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,16 @@ If you modified a command's flags, args, description, or added/removed a command
- Do not add docstrings, comments, or type annotations to code you did not change. Keep diffs tight.
- Use contractions in command, flag, and arg descriptions, and in docs text: "doesn't", "can't", "aren't", not "does not", "cannot", "are not". `docs/` is generated from these strings, so fix the source.

## Apify API usage

`apify-client` types are hand-written and lag behind the API. The API is the source of truth, not the client types. Apply this when you write or review code that calls the API.

- Check the endpoint in the OpenAPI spec (`https://docs.apify.com/api/openapi.json`) before you use a client method. If the spec is unclear, check the live response with `apify api <endpoint>`; list and single-item endpoints can return different fields.
- Before you filter, sort, paginate, or poll on the client side, check whether the API has a parameter for it (`sortBy`, `status`, `prefix`, `waitForFinish`, a `HEAD` endpoint).
- Field missing from the client types: add a type to `src/lib/api-overrides.ts` with the spec schema name, and use that type at the call site. Don't use `Reflect.get`, `as never`, or `@ts-expect-error` to read API data.
- Parameter missing from the client: the client rejects unknown options at runtime, so send the request directly, as `src/lib/git-source/gitSource.ts` does.
- On each `apify-client` bump, remove the overrides the client now covers.

## Install size

The CLI is installed globally by many users and in Actors, so keep the npm install footprint lean. Always look for opportunities to shrink it:
Expand Down
8 changes: 4 additions & 4 deletions src/commands/actors/info.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import type { Actor, ActorChargeEvent, ActorTaggedBuild, ApifyApiError, ApifyClient, Build, User } from 'apify-client';
import type { ActorChargeEvent, ActorTaggedBuild, ApifyApiError, ApifyClient, Build, User } from 'apify-client';
import chalk from 'chalk';

import type { ApiActor } from '../../lib/api-overrides.js';
import { ApifyCommand } from '../../lib/command-framework/apify-command.js';
import { Args } from '../../lib/command-framework/args.js';
import { Flags } from '../../lib/command-framework/flags.js';
Expand All @@ -9,7 +10,7 @@ import { CompactMode, ResponsiveTable } from '../../lib/commands/responsive-tabl
import { error, simpleLog } from '../../lib/outputs.js';
import { DurationFormatter, getLoggedClientOrThrow, printJsonToStdout, TimestampFormatter } from '../../lib/utils.js';

interface HydratedActorInfo extends Omit<Actor, 'taggedBuilds'> {
interface HydratedActorInfo extends Omit<ApiActor, 'taggedBuilds'> {
taggedBuilds?: Record<string, ActorTaggedBuild & { build?: Build }>;
actorMaker?: User;
}
Expand Down Expand Up @@ -191,8 +192,7 @@ export class ActorsInfoCommand extends ApifyCommand<typeof ActorsInfoCommand> {
`${chalk.yellow('Made by:')} ${chalk.cyan(actorInfo.actorMaker.profile.name ?? actorInfo.actorMaker.username)}`,
);

// Missing types who?
if (Reflect.get(actorInfo, 'isCritical')) {
if (actorInfo.isCritical) {
message[message.length - 1] += ` ${chalk.bgGray('Maintained by Apify')}`;
}
}
Expand Down
17 changes: 15 additions & 2 deletions src/commands/actors/ls.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
import { Time } from '@sapphire/duration';
import type { Actor, ActorRunListItem, ActorTaggedBuild, PaginatedList } from 'apify-client';
import {
type Actor,
ActorListSortBy,
type ActorRunListItem,
type ActorTaggedBuild,
type PaginatedList,
} from 'apify-client';
import chalk from 'chalk';

import type { ACTOR_JOB_STATUSES } from '@apify/consts';
Expand Down Expand Up @@ -144,7 +150,14 @@ export class ActorsLsCommand extends ApifyCommand<typeof ActorsLsCommand> {

const client = await getLoggedClientOrThrow();

const rawActorList = await client.actors().list({ limit, offset, desc, my });
const rawActorList = await client.actors().list({
limit,
offset,
// Without --my the list is "recently used", so the most recent run always comes first.
desc: my ? desc : true,
my,
sortBy: my ? ActorListSortBy.CREATED_AT : ActorListSortBy.LAST_RUN_STARTED_AT,
});

if (rawActorList.count === 0) {
if (json) {
Expand Down
6 changes: 3 additions & 3 deletions src/commands/actors/pull.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import { downloadTemplate } from 'giget';
import jju from 'jju';
import { gt } from 'semver';

import type { ApiSourceFile } from '../../lib/api-overrides.js';
import { ApifyCommand } from '../../lib/command-framework/apify-command.js';
import { Args } from '../../lib/command-framework/args.js';
import { Flags } from '../../lib/command-framework/flags.js';
Expand Down Expand Up @@ -155,13 +156,12 @@ export class ActorsPullCommand extends ApifyCommand<typeof ActorsPullCommand> {
throwMissingSourceCodeAccessError();
}

const { sourceFiles } = correctVersion;
const sourceFiles: ApiSourceFile[] = correctVersion.sourceFiles;
for (const file of sourceFiles) {
const folderPath = dirname(file.name);
mkdirSync(`${dirpath}/${folderPath}`, { recursive: true });

// @ts-expect-error TODO: is this an actual field?
if (!file.folder) {
if (!('folder' in file)) {
const fileContent =
file.format === 'BASE64' ? Buffer.from(file.content, 'base64').toString() : file.content;

Expand Down
7 changes: 3 additions & 4 deletions src/commands/actors/push.ts
Original file line number Diff line number Diff line change
Expand Up @@ -879,8 +879,6 @@ export class ActorsPushCommand extends ApifyCommand<typeof ActorsPushCommand> {
const filesSize = await sumFilesSizeInBytes(uploadedFiles, uploadRoot);

if ((filesSize < MAX_MULTIFILE_BYTES || actorPath) && !isActorCreatedNow) {
const client = await actorClient.get();

// Check when was files modified last
const mostRecentModifiedFileMs = uploadedFiles.reduce((modifiedMs, filePath) => {
const { mtimeMs, ctimeMs } = statSync(join(uploadRoot, filePath));
Expand All @@ -890,7 +888,7 @@ export class ActorsPushCommand extends ApifyCommand<typeof ActorsPushCommand> {

return modifiedMs > fileModifiedMs ? modifiedMs : fileModifiedMs;
}, 0);
const actorModifiedMs = client?.modifiedAt.valueOf();
const actorModifiedMs = actor.modifiedAt.valueOf();

if (
!this.flags.force &&
Expand Down Expand Up @@ -1069,7 +1067,8 @@ Skipping push. Use --force to override.`,
// branches below see the real outcome.
while (!isTerminalStatus(build.status) && Date.now() < deadline) {
await new Promise((resolve) => setTimeout(resolve, 1000));
build = (await apifyClient.build(build.id).get())!;
const waitForFinish = Math.max(0, Math.min(60, Math.ceil((deadline - Date.now()) / 1000)));
build = (await apifyClient.build(build.id).get({ waitForFinish }))!;
}

// Platform updates `taggedBuilds[buildTag]` asynchronously after the
Expand Down
8 changes: 2 additions & 6 deletions src/commands/builds/add-tag.ts
Original file line number Diff line number Diff line change
Expand Up @@ -81,12 +81,8 @@ export class BuildsAddTagCommand extends ApifyCommand<typeof BuildsAddTagCommand
try {
// Update only the specific tag
await apifyClient.actor(build.actId).update({
taggedBuilds: {
[tag]: {
buildId: build.id,
},
},
} as never);
taggedBuilds: { [tag]: { buildId: build.id } },
});

const previousBuildInfo = existingTagData?.buildNumber
? ` (previously pointed to build ${chalk.gray(existingTagData.buildNumber)})`
Expand Down
9 changes: 4 additions & 5 deletions src/commands/builds/info.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import chalk from 'chalk';

import type { ApiBuild } from '../../lib/api-overrides.js';
import { ApifyCommand } from '../../lib/command-framework/apify-command.js';
import { Args } from '../../lib/command-framework/args.js';
import { consoleBuildUrl } from '../../lib/commands/agent-output.js';
Expand Down Expand Up @@ -38,7 +39,7 @@ export class BuildsInfoCommand extends ApifyCommand<typeof BuildsInfoCommand> {

const apifyClient = await getLoggedClientOrThrow();

const build = await apifyClient.build(buildId).get();
const build: ApiBuild | undefined = await apifyClient.build(buildId).get();

if (!build) {
error({ message: `Build with ID "${buildId}" was not found on your account.`, stdout: true });
Expand All @@ -64,8 +65,7 @@ export class BuildsInfoCommand extends ApifyCommand<typeof BuildsInfoCommand> {
}
}

// TODO: untyped field, https://github.com/apify/apify-client-js/issues/526
const exitCode = Reflect.get(build, 'exitCode') as number | undefined;
const { exitCode } = build;

const fullActorName = actor?.username ? `${actor.username}/${actor.name}` : (actor?.name ?? 'unknown-actor');
const versionTaggedAs = buildTag ? ` (tagged as ${chalk.yellow(buildTag)})` : '';
Expand Down Expand Up @@ -95,8 +95,7 @@ export class BuildsInfoCommand extends ApifyCommand<typeof BuildsInfoCommand> {
message.push(` ${chalk.yellow('Compute Units')}: ${build.stats.computeUnits.toFixed(3)}`);
}

// TODO: untyped field, https://github.com/apify/apify-client-js/issues/526
const dockerImageSize = Reflect.get(build.stats ?? {}, 'imageSizeBytes') as number | undefined;
const dockerImageSize = build.stats?.imageSizeBytes;

if (dockerImageSize) {
message.push(` ${chalk.yellow('Docker Image Size')}: ${prettyPrintBytes({ bytes: dockerImageSize })}`);
Expand Down
20 changes: 8 additions & 12 deletions src/commands/builds/ls.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import type { BuildCollectionClientListItem } from 'apify-client';
import chalk from 'chalk';

import type { ApiBuildListItem } from '../../lib/api-overrides.js';
import { ApifyCommand } from '../../lib/command-framework/apify-command.js';
import { Args } from '../../lib/command-framework/args.js';
import { Flags } from '../../lib/command-framework/flags.js';
Expand Down Expand Up @@ -89,10 +89,10 @@ export class BuildsLsCommand extends ApifyCommand<typeof BuildsLsCommand> {
const allBuilds = await client.actor(ctx.id).builds().list({ desc, limit, offset });
const actorInfo = (await client.actor(ctx.id).get())!;

const buildsByActorVersion = objectGroupBy(allBuilds.items, (item) => {
const versionNumber = Reflect.get(item, 'buildNumber') as string;
const builds = allBuilds.items as ApiBuildListItem[];

const [major, minor] = versionNumber.split('.');
const buildsByActorVersion = objectGroupBy(builds, (item) => {
const [major, minor] = item.buildNumber.split('.');

return `${major}.${minor}`;
});
Expand All @@ -108,11 +108,8 @@ export class BuildsLsCommand extends ApifyCommand<typeof BuildsLsCommand> {

if (json) {
// Hydrate the builds with their tags
for (const build of allBuilds.items) {
// TODO: untyped field, https://github.com/apify/apify-client-js/issues/526
const buildNumber = Reflect.get(build, 'buildNumber') as string;

const hasTag = buildTagToActorVersion[buildNumber];
for (const build of builds) {
const hasTag = buildTagToActorVersion[build.buildNumber];

if (hasTag) {
Reflect.set(build, 'buildTag', hasTag);
Expand Down Expand Up @@ -167,14 +164,13 @@ export class BuildsLsCommand extends ApifyCommand<typeof BuildsLsCommand> {
buildsForVersion,
buildTagToActorVersion,
}: {
buildsForVersion: BuildCollectionClientListItem[];
buildsForVersion: ApiBuildListItem[];
buildTagToActorVersion: Record<string, string>;
}) {
const table = tableFactory();

for (const build of buildsForVersion) {
// TODO: untyped field, https://github.com/apify/apify-client-js/issues/526
const buildNumber = Reflect.get(build, 'buildNumber') as string;
const { buildNumber } = build;

const hasTag = buildTagToActorVersion[buildNumber]
? ` (${chalk.yellow(buildTagToActorVersion[buildNumber])})`
Expand Down
7 changes: 3 additions & 4 deletions src/commands/builds/remove-tag.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import type { ActorTaggedBuild, ApifyApiError } from 'apify-client';
import chalk from 'chalk';

import type { ApiTaggedBuildsUpdate } from '../../lib/api-overrides.js';
import { ApifyCommand } from '../../lib/command-framework/apify-command.js';
import { Flags, YesFlag } from '../../lib/command-framework/flags.js';
import { useYesNoConfirm } from '../../lib/hooks/user-confirmations/useYesNoConfirm.js';
Expand Down Expand Up @@ -98,10 +99,8 @@ export class BuildsRemoveTagCommand extends ApifyCommand<typeof BuildsRemoveTagC
try {
// To remove a tag, set it to null
await apifyClient.actor(build.actId).update({
taggedBuilds: {
[tag]: null,
},
} as never);
taggedBuilds: { [tag]: null } satisfies ApiTaggedBuildsUpdate as never,
});

success({
message: `Tag "${chalk.yellow(tag)}" removed from build ${chalk.gray(build.buildNumber)} (${chalk.gray(buildId)})`,
Expand Down
5 changes: 2 additions & 3 deletions src/commands/datasets/info.ts
Original file line number Diff line number Diff line change
Expand Up @@ -102,11 +102,10 @@ export class DatasetsInfoCommand extends ApifyCommand<typeof DatasetsInfoCommand
const pricing = getUserPlanPricing(user.plan);

if (pricing) {
const storeCostPerHour = pricing.KEY_VALUE_STORE_TIMED_STORAGE_GBYTE_HOURS * (fullSizeInBytes / 1000 ** 3);
const storeCostPerHour = pricing.DATASET_TIMED_STORAGE_GBYTE_HOURS * (fullSizeInBytes / 1000 ** 3);
const storeCostPerMonth = storeCostPerHour * 24 * 30;

const usdAmountString =
storeCostPerMonth > 1 ? `$${storeCostPerMonth.toFixed(2)}` : `$${storeCostPerHour.toFixed(3)}`;
const usdAmountString = `$${storeCostPerMonth.toFixed(storeCostPerMonth > 1 ? 2 : 3)}`;

row3 += `\nStorage size: ${prettyPrintBytes({ bytes: fullSizeInBytes, shortBytes: true, precision: 1 })} / ${chalk.gray(`${usdAmountString} per month`)}`;
}
Expand Down
3 changes: 1 addition & 2 deletions src/commands/datasets/ls.ts
Original file line number Diff line number Diff line change
Expand Up @@ -79,8 +79,7 @@ export class DatasetsLsCommand extends ApifyCommand<typeof DatasetsLsCommand> {
}

for (const dataset of rawDatasetList.items) {
// TODO: update apify-client types
const size = Reflect.get(dataset.stats, 's3StorageBytes') as number | undefined;
const size = dataset.stats?.storageBytes;

table.pushRow({
'Dataset ID': dataset.id,
Expand Down
2 changes: 1 addition & 1 deletion src/commands/datasets/rename.ts
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ export class DatasetsRenameCommand extends ApifyCommand<typeof DatasetsRenameCom
})();

try {
await existingDataset.datasetClient.update({ name: unname ? (null as never) : newName! });
await existingDataset.datasetClient.update({ name: unname ? null : newName! });

success({
message: successMessage,
Expand Down
4 changes: 1 addition & 3 deletions src/commands/key-value-stores/delete-value.ts
Original file line number Diff line number Diff line change
Expand Up @@ -62,9 +62,7 @@ export class KeyValueStoresDeleteValueCommand extends ApifyCommand<typeof KeyVal

const { keyValueStoreClient: client } = maybeStore;

const existing = await client.getRecord(itemKey);

if (!existing) {
if (!(await client.recordExists(itemKey))) {
error({
message: `Item with key "${itemKey}" not found in the key-value store.`,
});
Expand Down
3 changes: 1 addition & 2 deletions src/commands/key-value-stores/info.ts
Original file line number Diff line number Diff line change
Expand Up @@ -107,8 +107,7 @@ export class KeyValueStoresInfoCommand extends ApifyCommand<typeof KeyValueStore
const storeCostPerHour = pricing.KEY_VALUE_STORE_TIMED_STORAGE_GBYTE_HOURS * (fullSizeInBytes / 1000 ** 3);
const storeCostPerMonth = storeCostPerHour * 24 * 30;

const usdAmountString =
storeCostPerMonth > 1 ? `$${storeCostPerMonth.toFixed(2)}` : `$${storeCostPerHour.toFixed(3)}`;
const usdAmountString = `$${storeCostPerMonth.toFixed(storeCostPerMonth > 1 ? 2 : 3)}`;

row3 += `\nStorage size: ${prettyPrintBytes({ bytes: fullSizeInBytes, shortBytes: true, precision: 1 })} / ${chalk.gray(`${usdAmountString} per month`)}`;
}
Expand Down
5 changes: 2 additions & 3 deletions src/commands/key-value-stores/ls.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import chalk from 'chalk';

import type { ApiKeyValueStoreListItem } from '../../lib/api-overrides.js';
import { ApifyCommand } from '../../lib/command-framework/apify-command.js';
import { Flags } from '../../lib/command-framework/flags.js';
import { prettyPrintBytes } from '../../lib/commands/pretty-print-bytes.js';
Expand Down Expand Up @@ -76,9 +77,7 @@ export class KeyValueStoresLsCommand extends ApifyCommand<typeof KeyValueStoresL
}

for (const store of rawKvsList.items) {
// TODO: update apify-client types
const statsObject = Reflect.get(store, 'stats') as { s3StorageBytes?: number };
const size = statsObject.s3StorageBytes;
const size = (store as ApiKeyValueStoreListItem).stats?.s3StorageBytes;

table.pushRow({
'Store ID': store.id,
Expand Down
2 changes: 1 addition & 1 deletion src/commands/key-value-stores/rename.ts
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ export class KeyValueStoresRenameCommand extends ApifyCommand<typeof KeyValueSto
})();

try {
await existingDataset.keyValueStoreClient.update({ name: unname ? (null as never) : newName! });
await existingDataset.keyValueStoreClient.update({ name: unname ? null : newName! });

success({
message: successMessage,
Expand Down
43 changes: 43 additions & 0 deletions src/lib/api-overrides.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
// API fields that the hand-written apify-client types lack. Each type names its schema in
// https://docs.apify.com/api/openapi.json. Remove an entry when apify-client covers it.
import type {
Actor,
ActorVersionSourceFile,
Build,
BuildCollectionClientListItem,
KeyValueStore,
UserPlan,
} from 'apify-client';

// BuildListItem, https://github.com/apify/apify-client-js/issues/526
export type ApiBuildListItem = BuildCollectionClientListItem & { buildNumber: string };

// Build and BuildStats, https://github.com/apify/apify-client-js/issues/526
export type ApiBuild = Omit<Build, 'stats'> & {
exitCode?: number | null;
stats?: Build['stats'] & { imageSizeBytes?: number | null };
};

// KeyValueStoreStats: the list endpoint returns `s3StorageBytes`, the single GET returns `storageBytes`.
export type ApiKeyValueStoreListItem = Omit<KeyValueStore, 'stats'> & {
stats?: KeyValueStore['stats'] & { s3StorageBytes?: number };
};

// SourceCodeFolder: a version's `sourceFiles` also lists folders, which have no content.
export type ApiSourceFile = ActorVersionSourceFile | { name: string; folder: true };

// UserPlan.planPricing is an untyped object in the spec; the shape is from the live `GET /v2/users/me`.
export type ApiUserPlan = UserPlan & {
planPricing?: {
chargeableServiceUnitPricesUsd?: {
DATASET_TIMED_STORAGE_GBYTE_HOURS: number;
KEY_VALUE_STORE_TIMED_STORAGE_GBYTE_HOURS: number;
};
};
};

// ActorResource
export type ApiActor = Actor & { isCritical?: boolean };

// UpdateActorRequest.taggedBuilds: `{ buildId }` moves a tag, `null` removes it.
export type ApiTaggedBuildsUpdate = Record<string, { buildId: string } | null>;
6 changes: 5 additions & 1 deletion src/lib/commands/agent-output.ts
Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,12 @@ export async function waitForTerminalStatus(options: WaitForJobOptions): Promise
const startedAt = Date.now();

while (true) {
const remainingSecs = maxWaitMillis ? Math.floor((maxWaitMillis - (Date.now() - startedAt)) / 1000) : 60;
const waitForFinish = Math.max(0, Math.min(60, remainingSecs));
const job =
kind === ACTOR_JOB_TYPES.BUILD ? await apifyClient.build(jobId).get() : await apifyClient.run(jobId).get();
kind === ACTOR_JOB_TYPES.BUILD
? await apifyClient.build(jobId).get({ waitForFinish })
: await apifyClient.run(jobId).get({ waitForFinish });

if (!job) {
throw new Error(`${kind === ACTOR_JOB_TYPES.BUILD ? 'Build' : 'Run'} with ID "${jobId}" was not found.`);
Expand Down
2 changes: 1 addition & 1 deletion src/lib/commands/run-on-cloud.ts
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ export async function* runActorOrTaskOnCloud(apifyClient: ApifyClient, options:

if (waitForRunToFinish) {
while (!TerminalStatuses.includes(run.status as never)) {
run = (await apifyClient.run(run.id).get())!;
run = (await apifyClient.run(run.id).get({ waitForFinish: 60 }))!;

if (TerminalStatuses.includes(run.status as never)) {
break;
Expand Down
Loading
Loading