@apify/actors-mcp-server 0.18.4 → 0.18.5-beta.1

package/dist/tools/versions/delete_actor_version.js

@@ -0,0 +1,121 @@
+import { ActorSourceType, ApifyApiError } from 'apify-client';
+import dedent from 'dedent';
+import { z } from 'zod';
+import { APIFY_ERROR_TYPE_TOO_FEW_VERSIONS, HELPER_TOOLS } from '../../const.js';
+import { UserInputError } from '../../errors.js';
+import { TOOL_TYPE } from '../../types.js';
+import { compileSchema } from '../../utils/ajv.js';
+import { respondAborted, respondOk, respondUserError } from '../../utils/mcp.js';
+import { deleteActorVersionToolOutputSchema } from '../structured_output_schemas.js';
+import { buildFilesManifest, buildFilesRevision } from './source_files.js';
+import { extractSourceFiles, fetchActor, resolveVersion, respondToSourceToolError } from './source_helpers.js';
+const deleteActorVersionArgs = z.object({
+    actor: z
+        .string()
+        .min(1)
+        .describe('The Actor to delete the version from: its ID, its name (resolved against your own Actors), or its full name as username/name or username~name.'),
+    versionNumber: z.string().min(1).describe('The version to delete, in MAJOR.MINOR form, for example 0.2.'),
+    expectedRevision: z
+        .string()
+        .optional()
+        .describe('The revision of the version when you read it. When given, the delete is refused if any file of the ' +
+        'version changed since. Only a version stored as files has a revision.'),
+});
+/**
+ * Throws `UserInputError` unless the version's revision, computed as get-actor-version and the write tools compute it,
+ * is `expectedRevision`, ignoring case. A version not stored as files has no revision.
+ */
+function validateRevision(version, fullName, expectedRevision) {
+    if (version.sourceType !== ActorSourceType.SourceFiles) {
+        throw new UserInputError(`Nothing was deleted: version ${version.versionNumber} of ${fullName} has source type ${version.sourceType}, ` +
+            'and only a version stored as files has a revision to compare expectedRevision with.');
+    }
+    if (!version.sourceFiles) {
+        throw new UserInputError(`Nothing was deleted: version ${version.versionNumber} of ${fullName} came back without its source, so it ` +
+            'has no revision to compare expectedRevision with.');
+    }
+    const revision = buildFilesRevision(buildFilesManifest(extractSourceFiles(version, `Version ${version.versionNumber} of ${fullName}`)));
+    if (expectedRevision.toLowerCase() === revision)
+        return;
+    throw new UserInputError(`Nothing was deleted: expectedRevision failed with REVISION_MISMATCH. The version's revision is ${revision}, ` +
+        `not ${expectedRevision}.`);
+}
+/**
+ * https://docs.apify.com/api/v2/actor-get
+ *  /v2/actors/{actorId}
+ * https://docs.apify.com/api/v2/actor-version-delete
+ *  /v2/actors/{actorId}/versions/{versionNumber}
+ *
+ * The Actor is read first: apify-client swallows a 404 on delete, so a missing version would otherwise look deleted.
+ * The platform refuses to delete the last version, and leaves the version's builds and tags in place.
+ */
+export const deleteActorVersion = Object.freeze({
+    type: TOOL_TYPE.INTERNAL,
+    name: HELPER_TOOLS.ACTOR_VERSION_DELETE,
+    title: 'Delete Actor version',
+    description: dedent `
+        Delete one version of an Actor, with its source and environment variables; a deleted version cannot be restored. The platform refuses to delete an Actor's last version.
+        The version's builds stay, and so do the tags that point to them: a run with such a tag still uses that build. A build of the version that is still running keeps running, and takes its tag if it succeeds.
+
+        USAGE:
+        - Use only when the user explicitly wants the version removed.
+
+        USAGE EXAMPLES:
+        - user_input: Delete version 0.2 of my Actor john/my-scraper`,
+    inputSchema: z.toJSONSchema(deleteActorVersionArgs),
+    outputSchema: deleteActorVersionToolOutputSchema,
+    ajvValidate: compileSchema(z.toJSONSchema(deleteActorVersionArgs)),
+    annotations: {
+        title: 'Delete Actor version',
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    call: async (toolArgs) => {
+        var _a;
+        const { args, apifyClient: client, signal, loadedToolNames } = toolArgs;
+        const parsed = deleteActorVersionArgs.parse(args);
+        try {
+            const { actor, fullName } = await fetchActor(client, parsed.actor);
+            const version = resolveVersion(actor, parsed.versionNumber, parsed.actor);
+            const { versionNumber } = version;
+            // AJV turns a null expectedRevision into an empty string, which no version has, so it counts as not given.
+            if (parsed.expectedRevision)
+                validateRevision(version, fullName, parsed.expectedRevision);
+            // A cancel before the DELETE deletes nothing; per the MCP spec the cancelled request gets no response.
+            if (signal === null || signal === void 0 ? void 0 : signal.aborted)
+                return respondAborted();
+            try {
+                await client.actor(actor.id).version(versionNumber).delete();
+            }
+            catch (error) {
+                if (error instanceof ApifyApiError && error.type === APIFY_ERROR_TYPE_TOO_FEW_VERSIONS) {
+                    return respondUserError(`Version ${versionNumber} is the only version of ${fullName}, and an Actor keeps at least one version.`, { httpStatus: error.statusCode });
+                }
+                throw error;
+            }
+            const summary = `Deleted version ${versionNumber} of ${fullName}.`;
+            const buildTool = loadedToolNames.includes(HELPER_TOOLS.ACTOR_BUILD)
+                ? `${HELPER_TOOLS.ACTOR_BUILD} and `
+                : '';
+            // A tag points to the build it was last given to, which may be a build of another version than the one with
+            // that buildTag.
+            const tags = Object.entries((_a = actor.taggedBuilds) !== null && _a !== void 0 ? _a : {})
+                .filter(([, { buildNumber }]) => buildNumber === null || buildNumber === void 0 ? void 0 : buildNumber.startsWith(`${versionNumber}.`))
+                .map(([tag]) => tag);
+            const structuredContent = { actorId: actor.id, fullName, versionNumber, deleted: true, tags };
+            // build-actor takes one tag, so the text names one build per tag.
+            const text = tags.length > 0
+                ? `${summary}\nRuns with tag ${tags.join(', ')} still use the deleted version's build until each tag ` +
+                    `points to another build, such as one of another version made with ${buildTool}` +
+                    `tag ${tags.join(', then one with tag ')}.`
+                : summary;
+            return respondOk([JSON.stringify(structuredContent), text], { structuredContent });
+        }
+        catch (error) {
+            return respondToSourceToolError(error);
+        }
+    },
+});
+//# sourceMappingURL=delete_actor_version.js.map

package/dist/tools/versions/delete_actor_version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delete_actor_version.js","sourceRoot":"","sources":["../../../src/tools/versions/delete_actor_version.ts"],"names":[],"mappings":"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"}

package/dist/tools/versions/get_actor_version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get_actor_version.d.ts","sourceRoot":"","sources":["../../../src/tools/versions/get_actor_version.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAoB,SAAS,EAAmB,MAAM,gBAAgB,CAAC;AA4HnF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,SA6EnB,CAAC"}

package/dist/tools/{source → versions}/get_actor_version.js

@@ -1,7 +1,4 @@
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9a02aa21-6712-56af-a634-93a1e782edda")}catch(e){}}();
 import { posix } from 'node:path';
-import { ActorSourceType } from 'apify-client';
 import dedent from 'dedent';
 import { z } from 'zod';
 import { HELPER_TOOLS, MAX_INLINE_BYTES } from '../../const.js';
@@ -9,15 +6,15 @@ import { UserInputError } from '../../errors.js';
 import { TOOL_TYPE } from '../../types.js';
 import { compileSchema } from '../../utils/ajv.js';
 import { respondOk, respondUserError } from '../../utils/mcp.js';
-import { listVersionNumbers } from '../builds/build_helpers.js';
 import { getActorVersionToolOutputSchema } from '../structured_output_schemas.js';
 import { buildFilesManifest, buildFilesRevision } from './source_files.js';
+import { extractSourceFiles, fetchActor, resolveVersion, respondToSourceToolError } from './source_helpers.js';
 const INLINE_LIMIT_KIB = MAX_INLINE_BYTES / 1024;
 const getActorVersionArgs = z.object({
     actor: z
         .string()
         .min(1)
-        .describe('The Actor to read: its ID, or its full name as username/name or username~name. A name without the username is not enough.'),
+        .describe('The Actor to read: its ID, its name (resolved against your own Actors), or its full name as username/name or username~name.'),
     // Format is not enforced by a regex: the lookup against the Actor's versions rejects anything that is not an
     // existing version with a soft fail.
     versionNumber: z
@@ -41,80 +38,6 @@ const getActorVersionArgs = z.object({
         .optional()
         .describe('Number of lines to return from startLine; defaults to the rest of the file. Only with exactly one path in paths.'),
 });
-/** The requested version, or the only one when none is requested; throws `UserInputError` otherwise. */
-function resolveVersion(actor, requestedVersionNumber, actorSelector) {
-    const versionNumbers = listVersionNumbers(actor);
-    if (requestedVersionNumber === undefined && versionNumbers.length !== 1) {
-        // The source type and build tag tell the caller which version holds the code it is after.
-        const versions = actor.versions
-            .filter((version) => version.versionNumber !== undefined)
-            .map(({ versionNumber, sourceType, buildTag }) => {
-            const tag = buildTag ? `, build tag ${buildTag}` : '';
-            return `${versionNumber} (${sourceType}${tag})`;
-        });
-        throw new UserInputError(`Specify versionNumber; this Actor has versions: ${versions.join(', ')}.`);
-    }
-    const versionNumber = requestedVersionNumber !== null && requestedVersionNumber !== void 0 ? requestedVersionNumber : versionNumbers[0];
-    const version = actor.versions.find((candidate) => candidate.versionNumber === versionNumber);
-    if (!version) {
-        throw new UserInputError(`Actor '${actorSelector}' has no version ${versionNumber}; available versions: ${versionNumbers.join(', ')}.`);
-    }
-    return { ...version, versionNumber };
-}
-/**
- * The URL without what can grant access to it: the query string, the password, and, for http and https, the user. An
- * SSH user such as `git@` is not a secret and stays. A URL the parser cannot read, such as
- * `git@github.com:user/repo.git`, loses only its query string.
- */
-function formatUrlWithoutSecrets(url) {
-    if (URL.canParse(url)) {
-        const parsed = new URL(url);
-        parsed.search = '';
-        parsed.password = '';
-        if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
-            parsed.username = '';
-        }
-        return parsed.href;
-    }
-    const queryIndex = url.indexOf('?');
-    if (queryIndex === -1)
-        return url;
-    const hashIndex = url.indexOf('#', queryIndex);
-    return url.slice(0, queryIndex) + (hashIndex === -1 ? '' : url.slice(hashIndex));
-}
-/**
- * Why a version not stored as files is refused, and what to use instead. A version keeps the URL fields of a source
- * type it used before, so only the URL of its current type is named.
- */
-function formatSourceTypeRefusal(version, versionLabel) {
-    if (version.sourceType === ActorSourceType.GitRepo) {
-        const url = version.gitRepoUrl ? ` ${formatUrlWithoutSecrets(version.gitRepoUrl)}` : '';
-        return `${versionLabel} has its files in the Git repository${url}, not stored on Apify, so this tool cannot work on them; use the repository.`;
-    }
-    if (version.sourceType === ActorSourceType.GitHubGist) {
-        const url = version.gitHubGistUrl ? ` ${formatUrlWithoutSecrets(version.gitHubGistUrl)}` : '';
-        return `${versionLabel} has its files in the GitHub gist${url}, not stored on Apify, so this tool cannot work on them; use the gist.`;
-    }
-    // TODO(#1452): Read zip-stored (TARBALL) versions with adm-zip 0.6.1 or later, within the download and unpacking
-    // limits the issue lists.
-    if (version.sourceType === ActorSourceType.Tarball) {
-        return `${versionLabel} is stored as a zip archive (apify push does this for sources over 3 MiB), and this tool cannot work on zip-stored versions yet.`;
-    }
-    // The API's legacy SOURCE_CODE type and any type added later are not in apify-client's enum.
-    const { sourceType } = version;
-    return `${versionLabel} has source type ${sourceType}, which this tool cannot work on; only versions stored as files are supported.`;
-}
-/** Throws `UserInputError` for a version not stored as files and for one whose source the API hides. */
-function extractVersionFiles(version, versionLabel) {
-    if (version.sourceType !== ActorSourceType.SourceFiles) {
-        throw new UserInputError(formatSourceTypeRefusal(version, versionLabel));
-    }
-    // The API returns only the number, type, and build tag of a version whose source it hides from this account.
-    if (!version.sourceFiles) {
-        throw new UserInputError(`${versionLabel} came back without its source: the API hides it from accounts that cannot modify the Actor. Ask the Actor's owner for the source.`);
-    }
-    return buildFilesManifest(version.sourceFiles);
-}
 /** Lines with their line endings kept, so joined back they give the exact text. */
 function splitLines(text) {
     if (text === '')
@@ -224,19 +147,15 @@ export const getActorVersion = Object.freeze({
         }
         try {
             // TODO: The Actor GET returns every file of every version; read only the files asked for once the API can.
-            // apify-client turns username/name into the API's username~name.
-            const actor = await client.actor(parsed.actor).get();
-            // Extra path segments, such as username/name/runs/last, reach a sub-resource that is not an Actor.
-            if (!actor || typeof actor.name !== 'string' || typeof actor.username !== 'string') {
-                return respondUserError(`Actor '${parsed.actor}' not found. Give its ID or its full name, username/name; a name without the username is not enough.`);
-            }
-            const fullName = `${actor.username}/${actor.name}`;
+            const { actor, fullName } = await fetchActor(client, parsed.actor);
             const version = resolveVersion(actor, parsed.versionNumber, parsed.actor);
-            const files = extractVersionFiles(version, `Version ${version.versionNumber} of ${fullName}`);
+            const files = buildFilesManifest(extractSourceFiles(version, `Version ${version.versionNumber} of ${fullName}`));
+            const { buildTag } = version;
             const structuredContent = {
                 actorId: actor.id,
                 fullName,
                 versionNumber: version.versionNumber,
+                ...(buildTag && { buildTag }),
                 revision: buildFilesRevision(files),
                 files: files.map(({ path, sizeBytes, hash }) => ({ path, sizeBytes, hash })),
                 ...selectContents(files, paths, lineRange),
@@ -245,9 +164,10 @@ export const getActorVersion = Object.freeze({
             const omittedHint = lineRange
                 ? 'ask for fewer lines with lineCount'
                 : 'ask for a file alone, or for part of it with startLine and lineCount';
+            const tag = buildTag ? ` (build tag ${buildTag})` : '';
             // Names the requested files that did not come back, for a caller that reads only the text.
             const summary = [
-                `Read version ${version.versionNumber} of ${fullName}.`,
+                `Read version ${version.versionNumber}${tag} of ${fullName}.`,
                 omittedPaths &&
                     `Left out over the ${INLINE_LIMIT_KIB} KiB limit: ${omittedPaths.join(', ')}; ${omittedHint}.`,
                 notFoundPaths &&
@@ -258,11 +178,8 @@ export const getActorVersion = Object.freeze({
             return respondOk([JSON.stringify(structuredContent), summary], { structuredContent });
         }
         catch (error) {
-            if (error instanceof UserInputError)
-                return respondUserError(error.message);
-            throw error;
+            return respondToSourceToolError(error);
         }
     },
 });
-//# sourceMappingURL=get_actor_version.js.map
-//# debugId=9a02aa21-6712-56af-a634-93a1e782edda
+//# sourceMappingURL=get_actor_version.js.map

package/dist/tools/versions/get_actor_version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get_actor_version.js","sourceRoot":"","sources":["../../../src/tools/versions/get_actor_version.ts"],"names":[],"mappings":"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"}

package/dist/tools/{source → versions}/source_files.d.ts

@@ -11,13 +11,17 @@ export type SourceFile = {
     contentBytes: number;
     /** The content as returned: the text for utf8, the base64 for base64. */
     content: string;
+    /** The entry as stored, which a write sends back for a file it leaves alone. */
+    entry: ActorVersionSourceFile;
 };
 export declare function hasBinaryExtension(path: string): boolean;
 /** Paths in JavaScript's default string order, so the manifest and the revision do not depend on the locale. */
 export declare function compareSourcePaths(a: string, b: string): number;
 /**
- * Identifies the file set: one `path\0hash\n` line per regular file, sorted by path. The stored format does not go
- * in, so a file stored as TEXT or as BASE64 gives the same revision.
+ * Identifies the file set: the JSON array of `[path, hash]` pairs of its regular files, sorted by path. JSON quotes
+ * each path and escapes quotes and control characters in it, so two different file sets never give the same text, as
+ * a stored name with NUL and a line break once did. The stored format does not go in, so a file stored as TEXT or as
+ * BASE64 gives the same revision.
  */
 export declare function buildFilesRevision(files: readonly Pick<SourceFile, 'path' | 'hash'>[]): string;
 /**

package/dist/tools/versions/source_files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source_files.d.ts","sourceRoot":"","sources":["../../../src/tools/versions/source_files.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AA4D3D,qCAAqC;AACrC,MAAM,MAAM,UAAU,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,2GAA2G;IAC3G,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,KAAK,EAAE,sBAAsB,CAAC;CACjC,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGxD;AAOD,gHAAgH;AAChH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAG/D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,MAAM,CAG9F;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,sBAAsB,GAAG,UAAU,CAc9E;AAED,4HAA4H;AAC5H,wBAAgB,aAAa,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAEnE;AAED,mHAAmH;AACnH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,GAAG,UAAU,EAAE,CAQ3F"}

package/dist/tools/{source → versions}/source_files.js

@@ -1,5 +1,3 @@
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4abfae6a-7ffb-53f2-a005-41621ac9f11d")}catch(e){}}();
 import { isUtf8 } from 'node:buffer';
 import { createHash } from 'node:crypto';
 import { posix } from 'node:path';
@@ -73,14 +71,14 @@ export function compareSourcePaths(a, b) {
     return a < b ? -1 : 1;
 }
 /**
- * Identifies the file set: one `path\0hash\n` line per regular file, sorted by path. The stored format does not go
- * in, so a file stored as TEXT or as BASE64 gives the same revision.
+ * Identifies the file set: the JSON array of `[path, hash]` pairs of its regular files, sorted by path. JSON quotes
+ * each path and escapes quotes and control characters in it, so two different file sets never give the same text, as
+ * a stored name with NUL and a line break once did. The stored format does not go in, so a file stored as TEXT or as
+ * BASE64 gives the same revision.
  */
 export function buildFilesRevision(files) {
-    const lines = [...files]
-        .sort((a, b) => compareSourcePaths(a.path, b.path))
-        .map(({ path, hash }) => `${path}\0${hash}\n`);
-    return getSha256Prefix(lines.join(''));
+    const pairs = [...files].sort((a, b) => compareSourcePaths(a.path, b.path)).map(({ path, hash }) => [path, hash]);
+    return getSha256Prefix(JSON.stringify(pairs));
 }
 /**
  * A file stored inline in the version, read as the build worker reads it: no `format` is TEXT, no `content` is empty,
@@ -92,7 +90,7 @@ export function buildInlineSourceFile(file) {
     const content = storedContent !== null && storedContent !== void 0 ? storedContent : '';
     const path = posix.normalize(name);
     const bytes = Buffer.from(content, format === 'BASE64' ? 'base64' : 'utf8');
-    const common = { path, sizeBytes: bytes.length, hash: getSha256Prefix(bytes) };
+    const common = { path, sizeBytes: bytes.length, hash: getSha256Prefix(bytes), entry: file };
     if (format !== 'BASE64') {
         return { ...common, encoding: 'utf8', contentBytes: bytes.length, content };
     }
@@ -117,5 +115,4 @@ export function buildFilesManifest(entries) {
     }
     return [...filesByPath.values()].sort((a, b) => compareSourcePaths(a.path, b.path));
 }
-//# sourceMappingURL=source_files.js.map
-//# debugId=4abfae6a-7ffb-53f2-a005-41621ac9f11d
+//# sourceMappingURL=source_files.js.map

package/dist/tools/versions/source_files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source_files.js","sourceRoot":"","sources":["../../../src/tools/versions/source_files.ts"],"names":[],"mappings":"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"}

package/dist/tools/versions/source_helpers.d.ts

@@ -0,0 +1,154 @@
+import type { Actor, ActorVersion, ActorVersionSourceFile } from 'apify-client';
+import { z } from 'zod';
+import type { ApifyClient } from '../../apify_client.js';
+import type { InternalToolArgs } from '../../types.js';
+import type { ToolResponse } from '../../utils/mcp.js';
+/** The input shape of one file sent whole. */
+export declare const sourceFileArgs: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodString;
+    encoding: z.ZodOptional<z.ZodEnum<{
+        base64: "base64";
+        utf8: "utf8";
+    }>>;
+}, z.core.$strip>;
+/**
+ * The logged copy of a source tool's arguments (`redactArgs`), built as an allowlist: `keys`, and each entry of the
+ * list under `listKey` with its `entryKeys`, and with its content and its edits' oldText and newText as `REDACTED`.
+ * File content can hold secrets, such as an API key written into the code.
+ */
+export declare function redactSourceToolArgs(args: Record<string, unknown>, fields: {
+    keys: readonly string[];
+    listKey: string;
+    entryKeys: readonly string[];
+}): Record<string, unknown>;
+/**
+ * The Actor by its ID, its name (resolved against the token's own Actors), or its full name, `username/name` or
+ * `username~name` (apify-client turns username/name into the API's username~name); throws `UserInputError` when there
+ * is none.
+ */
+export declare function fetchActor(client: ApifyClient, actorSelector: string): Promise<{
+    actor: Actor;
+    fullName: string;
+}>;
+/** The requested version, or the only one when none is requested; throws `UserInputError` otherwise. */
+export declare function resolveVersion(actor: Pick<Actor, 'versions'>, requestedVersionNumber: string | undefined, actorSelector: string): ActorVersion & {
+    versionNumber: string;
+};
+/**
+ * The version's stored entries, folders included. Throws `UserInputError` for a version not stored as files and for
+ * one whose source the API hides.
+ */
+export declare function extractSourceFiles(version: ActorVersion, versionLabel: string): ActorVersionSourceFile[];
+/**
+ * The entry to store for a file sent whole: TEXT for utf8, BASE64 for base64, where no encoding means base64 for a
+ * binary extension, the rule get-actor-version reads by. The path is normalized the way get-actor-version lists it.
+ */
+export declare function buildSourceFileEntry({ path, content, encoding, }: z.infer<typeof sourceFileArgs>): ActorVersionSourceFile;
+/**
+ * Throws `UserInputError` for content the stored file would not hold as sent: base64 that does not decode without
+ * loss, and text with a lone UTF-16 surrogate, which UTF-8 stores as U+FFFD.
+ */
+export declare function validateFileContent({ format, content }: ActorVersionSourceFile, label: string): void;
+/**
+ * Throws `UserInputError` for a path with a control character, U+0000 to U+001F or U+007F, or with a lone UTF-16
+ * surrogate. The build writes the files to disk, where a file name cannot hold NUL, and UTF-8 stores a lone surrogate
+ * as U+FFFD.
+ */
+export declare function validatePathCharacters(path: string, label: string): void;
+/**
+ * Throws `UserInputError` for a normalized path no file can be written at. The build worker refuses a version with a
+ * path outside the Actor root, so every build of it would fail; `.` and a path ending in a slash name a folder. A
+ * backslash is refused too: the build takes it as part of the file name, so src\main.js would land in the Actor root.
+ */
+export declare function validateFilePath(path: string, label: string): void;
+/**
+ * The paths of a version's files and folder entries, to check where a new file can go: one path cannot be both a file
+ * and a folder, and the build worker fails to write such a file. Each check and change looks up only the folders of
+ * its path, since comparing each file with every other took 8 s for 20,000 files.
+ */
+export declare class SourcePathIndex {
+    private readonly filePaths;
+    /** The files under each folder, at any depth, in the order they were added. */
+    private readonly filePathsByFolder;
+    private readonly folderPaths;
+    constructor(filePaths: Iterable<string>, folderPaths?: readonly string[]);
+    hasFile(path: string): boolean;
+    /** A file added again keeps its place in the order. */
+    addFile(path: string): void;
+    deleteFile(path: string): void;
+    /**
+     * Throws `UserInputError` when a new file at `path` collides with another file or folder: a file at a folder of
+     * `path`, or else the first file added under `path`, or else the first folder entry at or under `path`. A file at
+     * `path` itself is for the caller to check.
+     */
+    validateNewFilePath(path: string, label: string): void;
+}
+/**
+ * The entries to send, one per file; throws `UserInputError` for a path no file can be written at, for content the
+ * stored file would not hold as sent, and for a path given twice, which leaves the version with two entries where the
+ * build uses the last.
+ */
+export declare function buildSourceFileEntries(files: readonly z.infer<typeof sourceFileArgs>[]): ActorVersionSourceFile[];
+/** The build worker skips a file whose content is empty, so the caller hears of such files. */
+export declare function buildEmptyFilesWarnings(paths: readonly string[]): {
+    warnings?: string[];
+};
+/**
+ * The response to a committed write. With autoBuild, a build of the version starts first; a cancel that arrives before
+ * the start gets the cancelled-call response. When the build starts, `buildStartedWarnings`, if given, replaces the
+ * warnings in `structuredContent`.
+ */
+export declare function respondAfterWrite(params: {
+    toolArgs: Pick<InternalToolArgs, 'apifyClient' | 'apifyToken' | 'loadedToolNames' | 'signal'>;
+    autoBuild: boolean;
+    target: {
+        actorId: string;
+        versionNumber: string;
+    };
+    structuredContent: Record<string, unknown>;
+    buildStartedWarnings?: string[];
+    summary: string;
+}): Promise<ToolResponse>;
+/**
+ * The response to a POST that created a version from `sourceFiles`, as `respondAfterWrite` gives it: their manifest
+ * and revision as get-actor-version gives them, and the warnings about empty files followed by
+ * `extraWarning.withoutBuild`, or by `extraWarning.withBuild` when autoBuild starts a build.
+ */
+export declare function respondAfterCreate(params: {
+    toolArgs: Pick<InternalToolArgs, 'apifyClient' | 'apifyToken' | 'loadedToolNames' | 'signal'>;
+    autoBuild: boolean;
+    created: {
+        actorId: string;
+        fullName: string;
+        versionNumber: string;
+    };
+    sourceFiles: readonly ActorVersionSourceFile[];
+    extraWarning?: {
+        withoutBuild: string;
+        withBuild: string;
+    };
+    summary: string;
+}): Promise<ToolResponse>;
+/**
+ * A `UserInputError`, or the platform's refusal of a taken version number or of a version over the limit on the
+ * number of versions or on their combined size, as a soft failure with the platform's own message; anything else is
+ * rethrown for the tool-call engine to report. The engine would add a token-access hint to these 403s, which
+ * contradicts their reason.
+ */
+export declare function respondToSourceToolError(error: unknown): ToolResponse;
+/**
+ * The response to an error of a create POST. apify-client retries the POST after a network error, a timeout, a 429,
+ * or a 5xx, so when the platform refuses a retry as taken (`takenErrorType`), an attempt it saved but did not answer
+ * may have created what it refused (`refused`, such as `version 0.2`): the response says so, then adds `note` when
+ * given. Any other error goes to `respondToSourceToolError`.
+ */
+export declare function respondToCreateError(error: unknown, params: {
+    takenErrorType: string;
+    loadedToolNames: readonly string[];
+    refused: string;
+    created: string;
+    sentFiles: string;
+    note?: string;
+}): ToolResponse;
+//# sourceMappingURL=source_helpers.d.ts.map

package/dist/tools/versions/source_helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source_helpers.d.ts","sourceRoot":"","sources":["../../../src/tools/versions/source_helpers.ts"],"names":[],"mappings":"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"}