diff --git a/CLAUDE.md b/CLAUDE.md index c5d2c0c6b..9ec950343 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 `; 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: diff --git a/src/commands/actors/info.ts b/src/commands/actors/info.ts index 2ab6f068a..cab89762e 100644 --- a/src/commands/actors/info.ts +++ b/src/commands/actors/info.ts @@ -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'; @@ -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 { +interface HydratedActorInfo extends Omit { taggedBuilds?: Record; actorMaker?: User; } @@ -191,8 +192,7 @@ export class ActorsInfoCommand extends ApifyCommand { `${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')}`; } } diff --git a/src/commands/actors/ls.ts b/src/commands/actors/ls.ts index 8ecaacaa7..cb30b63f9 100644 --- a/src/commands/actors/ls.ts +++ b/src/commands/actors/ls.ts @@ -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'; @@ -144,7 +150,14 @@ export class ActorsLsCommand extends ApifyCommand { 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) { diff --git a/src/commands/actors/pull.ts b/src/commands/actors/pull.ts index 4ceae4ba2..e6f446d0b 100644 --- a/src/commands/actors/pull.ts +++ b/src/commands/actors/pull.ts @@ -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'; @@ -155,13 +156,12 @@ export class ActorsPullCommand extends ApifyCommand { 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; diff --git a/src/commands/actors/push.ts b/src/commands/actors/push.ts index 68facb989..657ded697 100644 --- a/src/commands/actors/push.ts +++ b/src/commands/actors/push.ts @@ -879,8 +879,6 @@ export class ActorsPushCommand extends ApifyCommand { 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)); @@ -890,7 +888,7 @@ export class ActorsPushCommand extends ApifyCommand { return modifiedMs > fileModifiedMs ? modifiedMs : fileModifiedMs; }, 0); - const actorModifiedMs = client?.modifiedAt.valueOf(); + const actorModifiedMs = actor.modifiedAt.valueOf(); if ( !this.flags.force && @@ -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 diff --git a/src/commands/builds/add-tag.ts b/src/commands/builds/add-tag.ts index 398a89d4e..3ded9e2c2 100644 --- a/src/commands/builds/add-tag.ts +++ b/src/commands/builds/add-tag.ts @@ -81,12 +81,8 @@ export class BuildsAddTagCommand extends ApifyCommand { 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 }); @@ -64,8 +65,7 @@ export class BuildsInfoCommand extends ApifyCommand { } } - // 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)})` : ''; @@ -95,8 +95,7 @@ export class BuildsInfoCommand extends ApifyCommand { 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 })}`); diff --git a/src/commands/builds/ls.ts b/src/commands/builds/ls.ts index 34a40bcdb..6ff7e72a1 100644 --- a/src/commands/builds/ls.ts +++ b/src/commands/builds/ls.ts @@ -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'; @@ -89,10 +89,10 @@ export class BuildsLsCommand extends ApifyCommand { 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}`; }); @@ -108,11 +108,8 @@ export class BuildsLsCommand extends ApifyCommand { 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); @@ -167,14 +164,13 @@ export class BuildsLsCommand extends ApifyCommand { buildsForVersion, buildTagToActorVersion, }: { - buildsForVersion: BuildCollectionClientListItem[]; + buildsForVersion: ApiBuildListItem[]; buildTagToActorVersion: Record; }) { 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])})` diff --git a/src/commands/builds/remove-tag.ts b/src/commands/builds/remove-tag.ts index 4b467df90..c3f1b2c39 100644 --- a/src/commands/builds/remove-tag.ts +++ b/src/commands/builds/remove-tag.ts @@ -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'; @@ -98,10 +99,8 @@ export class BuildsRemoveTagCommand extends ApifyCommand 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`)}`; } diff --git a/src/commands/datasets/ls.ts b/src/commands/datasets/ls.ts index f2aeca97c..c9383e79e 100644 --- a/src/commands/datasets/ls.ts +++ b/src/commands/datasets/ls.ts @@ -79,8 +79,7 @@ export class DatasetsLsCommand extends ApifyCommand { } 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, diff --git a/src/commands/datasets/rename.ts b/src/commands/datasets/rename.ts index 6cc4ac823..3c571b940 100644 --- a/src/commands/datasets/rename.ts +++ b/src/commands/datasets/rename.ts @@ -86,7 +86,7 @@ export class DatasetsRenameCommand extends ApifyCommand 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`)}`; } diff --git a/src/commands/key-value-stores/ls.ts b/src/commands/key-value-stores/ls.ts index 7de4c7f21..3520c2cc3 100644 --- a/src/commands/key-value-stores/ls.ts +++ b/src/commands/key-value-stores/ls.ts @@ -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'; @@ -76,9 +77,7 @@ export class KeyValueStoresLsCommand extends ApifyCommand & { + exitCode?: number | null; + stats?: Build['stats'] & { imageSizeBytes?: number | null }; +}; + +// KeyValueStoreStats: the list endpoint returns `s3StorageBytes`, the single GET returns `storageBytes`. +export type ApiKeyValueStoreListItem = Omit & { + 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; diff --git a/src/lib/commands/agent-output.ts b/src/lib/commands/agent-output.ts index 5d9021b32..5bb3396d2 100644 --- a/src/lib/commands/agent-output.ts +++ b/src/lib/commands/agent-output.ts @@ -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.`); diff --git a/src/lib/commands/run-on-cloud.ts b/src/lib/commands/run-on-cloud.ts index 74ec6164e..d2d2abf5f 100644 --- a/src/lib/commands/run-on-cloud.ts +++ b/src/lib/commands/run-on-cloud.ts @@ -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; diff --git a/src/lib/commands/storage-size.ts b/src/lib/commands/storage-size.ts index 90c9f76f5..0575aa79a 100644 --- a/src/lib/commands/storage-size.ts +++ b/src/lib/commands/storage-size.ts @@ -1,14 +1,5 @@ -import type { UserPlan } from 'apify-client'; +import type { ApiUserPlan } from '../api-overrides.js'; -export function getUserPlanPricing(userPlan: UserPlan) { - const planPricing = Reflect.get(userPlan, 'planPricing'); - - if (!planPricing) { - return null; - } - - return Reflect.get(planPricing, 'chargeableServiceUnitPricesUsd') as { - DATASET_TIMED_STORAGE_GBYTE_HOURS: number; - KEY_VALUE_STORE_TIMED_STORAGE_GBYTE_HOURS: number; - } | null; +export function getUserPlanPricing(userPlan: ApiUserPlan) { + return userPlan.planPricing?.chargeableServiceUnitPricesUsd ?? null; }