neonctl 2.24.0 → 2.24.1

package/commands/dev.js

@@ -51,7 +51,7 @@ const runSingleSource = async (props) => {
         throw new Error(`Source file not found: ${source}`);
     }
     const branchId = await resolveBranchId(props);
-    const neonEnv = await resolveDevEnv({
+    const { vars: neonEnv, skipped } = await resolveDevEnv({
         cwd: process.cwd(),
         ...(props.projectId ? { projectId: props.projectId } : {}),
         ...(branchId ? { branchId } : {}),
@@ -63,10 +63,13 @@ const runSingleSource = async (props) => {
         bundleDir: join(process.cwd(), 'node_modules', '.neon-dev'),
         childEnv: buildChildEnv(neonEnv, portFromProps(props.port)),
         label: null,
+        envSummary: { neon: Object.keys(neonEnv), fn: [] },
     };
     // No config reload in single-source mode: there's exactly one file to serve, and
     // nothing to add or remove. neon.ts hot-reload is config-mode only.
-    await runSupervisor([unit]);
+    await runSupervisor([unit], {
+        ...(skipped ? { envNote: skipped.reason } : {}),
+    });
 };
 /**
  * Multi-function mode: serve every function declared in neon.ts. Requires a neon.ts
@@ -85,7 +88,7 @@ const runFromConfig = async (props) => {
         throw new Error('neon.ts has no functions to serve. Add at least one under ' +
             '`preview.functions`, or pass --source <path>.');
     }
-    const neonEnv = await resolveDevEnv({
+    const { vars: neonEnv, skipped } = await resolveDevEnv({
         cwd: process.cwd(),
         ...(props.projectId ? { projectId: props.projectId } : {}),
         ...(branchId ? { branchId } : {}),
@@ -102,7 +105,10 @@ const runFromConfig = async (props) => {
             return null;
         return planFunctionsToUnits(re.functions, neonEnv, searchBase);
     };
-    await runSupervisor(units, { configPath, replan });
+    await runSupervisor(units, {
+        reload: { configPath, replan },
+        ...(skipped ? { envNote: skipped.reason } : {}),
+    });
 };
 /**
  * Map a list of {@link PlannedFunction}s to {@link ServedUnit}s, coordinating the search
@@ -174,6 +180,7 @@ const plannedToUnit = (fn, branchEnv, searchBase) => {
         bundleDir: join(process.cwd(), 'node_modules', '.neon-dev', fn.slug),
         childEnv,
         label: fn.slug,
+        envSummary: { neon: Object.keys(branchEnv), fn: Object.keys(fn.env) },
         // Signature of the function's *own* neon.ts config (NOT the dynamically-chosen search
         // base) so reconcile can tell a real change from a no-op save. A search-mode function
         // re-planned with a different base must hash identically, or it would be needlessly
@@ -221,7 +228,8 @@ const READY_PATTERN = /neon-dev:ready (\d+)/;
  * stayed the same. A function whose config (env/port/portless/source) changed is restarted
  * in place; siblings are untouched.
  */
-const runSupervisor = async (units, reload) => {
+const runSupervisor = async (units, options = {}) => {
+    const { reload, envNote } = options;
     if (hasPortlessUnit(units)) {
         assertPortlessAvailable();
     }
@@ -310,7 +318,7 @@ const runSupervisor = async (units, reload) => {
         await Promise.all(running.map((r) => stopUnit(r)));
         throw new Error('No function started. See the output above for details.');
     }
-    printBanner(running);
+    printBanner(running, envNote);
     // Config mode only: watch neon.ts and reconcile the live unit set when it changes.
     // Reconciles are serialized: a burst of saves (editor write-then-format) must not run
     // overlapping diffs against the mutating `running` array. A trailing run coalesces the
@@ -448,7 +456,10 @@ const reconcileOnce = async (running, replan, ops) => {
         await Promise.all(added.map((r) => ops.startUnit(r)));
         for (const r of added) {
             if (r.status === 'ready') {
-                logUnit(r.unit, chalk.green('ready') + ` ${urlFor(r.boundPort)}`);
+                const env = formatEnvSummary(r.unit.envSummary);
+                logUnit(r.unit, chalk.green('ready') +
+                    ` ${urlFor(r.boundPort)}` +
+                    (env ? chalk.dim(`  ${env}`) : ''));
             }
         }
     }
@@ -513,15 +524,13 @@ const spawnSyncCheck = (bin) => {
 const writeBundle = async (source, bundleDir) => {
     const files = await bundleEntry(source);
     mkdirSync(bundleDir, { recursive: true });
-    // The bundle is ESM (`format: 'esm'`), but it's written into a `.js` file under the
-    // user's node_modules — where Node, finding no `"type"`, would treat `.js` as CommonJS
-    // and throw `Unexpected token 'export'`. Drop a `package.json` marker so Node runs it as
-    // ESM. (A bare `out.mjs` would also work but breaks the `out.js.map` sourcemap link.)
-    writeFileSync(join(bundleDir, 'package.json'), '{"type":"module"}\n');
+    // bundleEntry emits `index.mjs` (+ `index.mjs.map`). The `.mjs` extension makes Node load
+    // it as ESM directly, so no `package.json` `"type": "module"` marker is needed, and esbuild
+    // points the sourcemap link at `index.mjs.map` for us.
     for (const [name, contents] of Object.entries(files)) {
         writeFileSync(join(bundleDir, name), contents);
     }
-    return join(bundleDir, 'out.js');
+    return join(bundleDir, 'index.mjs');
 };
 const urlFor = (port) => port === null ? chalk.red('not running') : `http://localhost:${port}`;
 const waitForReady = (child) => new Promise((resolveReady) => {
@@ -567,7 +576,7 @@ const pipeChildOutput = (child, label) => {
     forward('stdout');
     forward('stderr');
 };
-const printBanner = (running) => {
+const printBanner = (running, envNote) => {
     log.info('');
     log.info(chalk.green.bold('  Neon Functions dev server'));
     log.info('');
@@ -575,9 +584,34 @@ const printBanner = (running) => {
         const name = r.unit.label ?? 'function';
         const url = urlFor(r.boundPort);
         log.info(`  ${chalk.dim(name.padEnd(20))} ${url}`);
+        const env = formatEnvSummary(r.unit.envSummary);
+        if (env)
+            log.info(`  ${' '.repeat(20)} ${chalk.dim(env)}`);
+    }
+    if (envNote) {
+        log.info('');
+        log.info(`  ${chalk.yellow('!')} ${chalk.dim(`Neon env: ${envNote}`)}`);
     }
     log.info('');
 };
+/**
+ * Render a unit's injected env into one transparent line for the banner, e.g.
+ * `env: DATABASE_URL, DATABASE_URL_UNPOOLED · neon.ts: RESEND_API_KEY`. Var **names** only
+ * (never values — they're secrets). Returns `''` when nothing is injected, so the caller can
+ * skip the line. Exported for unit testing.
+ */
+export const formatEnvSummary = (summary) => {
+    if (!summary)
+        return '';
+    const parts = [];
+    if (summary.neon.length > 0) {
+        parts.push(`env: ${[...summary.neon].sort().join(', ')}`);
+    }
+    if (summary.fn.length > 0) {
+        parts.push(`neon.ts: ${[...summary.fn].sort().join(', ')}`);
+    }
+    return parts.join(' · ');
+};
 const logUnit = (unit, message) => {
     const prefix = unit.label ? chalk.dim(`[${unit.label}] `) : '';
     log.info(`${prefix}${message}`);

package/commands/env.js

@@ -1,3 +1,4 @@
+import chalk from 'chalk';
 import { NEON_ENV_VAR_KEYS } from '@neondatabase/env';
 import { log } from '../log.js';
 import { resolveNeonEnvVars } from '../dev/env.js';
@@ -5,6 +6,13 @@ import { mergeEnvFile, resolveEnvFilePath } from '../env_file.js';
 import { branchIdFromProps, fillSingleProject } from '../utils/enrichers.js';
 export const command = 'env';
 export const describe = "Manage a branch's Neon env variables locally";
+/**
+ * Shown (to stderr) when `link` / `checkout` skip the bundled env pull because the user passed
+ * `--no-env-pull`. Names the two ways to get the branch's vars without an on-disk file written
+ * eagerly: an explicit `neonctl env pull`, or runtime injection via `neon-env run`.
+ */
+export const ENV_PULL_SKIPPED_HINT = 'Skipped env pull (--no-env-pull). Run `neonctl env pull` to write this branch’s env vars ' +
+    '(DATABASE_URL, …) into a local .env, or inject them at runtime with `neon-env run -- <your dev command>`.';
 export const builder = (argv) => argv
     .usage('$0 env <sub-command> [options]')
     .options({
@@ -23,7 +31,9 @@ export const builder = (argv) => argv
     },
 })
     .example('$0 env pull', "Write the linked branch's Neon vars into .env.local (or .env if present)")
-    .example('$0 env pull --branch preview --file .env.preview', 'Pull a specific branch into a specific file'), (args) => pull(args))
+    .example('$0 env pull --branch preview --file .env.preview', 'Pull a specific branch into a specific file'), async (args) => {
+    await pull(args);
+})
     .demandCommand(1);
 export const handler = (args) => args;
 /** Every OS-level env var name `@neondatabase/env` can emit, used only for reporting. */
@@ -45,11 +55,55 @@ export const pull = async (props) => {
     if (Object.keys(neonVars).length === 0) {
         log.info('No Neon env variables to pull for this branch (no DATABASE_URL or ' +
             'enabled Auth / Data API).');
-        return;
+        return { status: 'empty' };
     }
     const targetPath = resolveEnvFilePath(cwd, props.file);
     const { written } = mergeEnvFile(targetPath, neonVars);
     log.info('Pulled %d Neon variable%s into %s: %s', written.length, written.length === 1 ? '' : 's', targetPath, written.join(', '));
+    return { status: 'written', written, file: targetPath };
+};
+/**
+ * Pull a freshly-pinned branch's Neon env vars into a local `.env`, bundled into `link` and
+ * `checkout` so the branch-first loop is just *link + checkout* — `env pull` runs for you.
+ *
+ * On by default; `--no-env-pull` opts out (e.g. when env is injected at runtime via
+ * `neon-env run` / `neon dev`, or to keep secrets out of the working tree). The pin is the
+ * command's primary effect and has already succeeded by the time this runs, so a pull failure
+ * degrades to a warning rather than failing the command. Returns what happened so
+ * `link --agent` can fold an accurate note into its JSON message.
+ */
+export const autoPullEnvAfterPin = async (props) => {
+    if (!props.envPull) {
+        log.info(chalk.dim(ENV_PULL_SKIPPED_HINT));
+        return { status: 'skipped' };
+    }
+    try {
+        return await pull(props);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log.warning('Branch pinned, but pulling its Neon env vars failed: %s\n' +
+            'Run `neonctl env pull` once resolved (e.g. `neonctl deploy` if a declared service ' +
+            'is missing), or inject them at runtime with `neon-env run -- <your dev command>`.', message);
+        return { status: 'failed', message };
+    }
+};
+/**
+ * Render the one-line env-pull note appended to `link --agent`'s JSON `message`, so an agent
+ * reading the structured output knows whether its branch env is already on disk.
+ */
+export const renderAgentPullNote = (result) => {
+    switch (result.status) {
+        case 'written':
+            return ` Pulled ${result.written.length} Neon env var${result.written.length === 1 ? '' : 's'} into ${result.file}.`;
+        case 'empty':
+            return ' No Neon env vars to pull for this branch yet.';
+        case 'skipped':
+            return (' Skipped env pull (--no-env-pull); run `neonctl env pull` later, ' +
+                'or inject env at runtime with `neon-env run -- <your dev command>`.');
+        case 'failed':
+            return ` Could not pull env vars (${result.message}); run \`neonctl env pull\` once resolved.`;
+    }
 };
 /**
  * Keep only the recognized Neon variables from the resolved set, so a stray inherited

package/commands/index.js

@@ -21,6 +21,7 @@ import * as dev from './dev.js';
 import * as config from './config.js';
 import * as deploy from './deploy.js';
 import * as env from './env.js';
+import * as bucket from './bucket.js';
 export default [
     auth,
     users,
@@ -45,4 +46,5 @@ export default [
     config,
     deploy,
     env,
+    bucket,
 ];

package/commands/link.js

@@ -3,6 +3,8 @@ import prompts from 'prompts';
 import { applyContext, readContextFile } from '../context.js';
 import { isCi } from '../env.js';
 import { log } from '../log.js';
+import { createBranch, pickBranchInteractively, } from '../utils/branch_picker.js';
+import { autoPullEnvAfterPin, renderAgentPullNote } from './env.js';
 import { REGIONS } from './projects.js';
 const PROJECTS_LIST_LIMIT = 100;
 const CREATE_NEW_SENTINEL = '__create_new__';
@@ -40,6 +42,13 @@ export const builder = (argv) => argv.usage('$0 link [options]').options({
         type: 'boolean',
         default: false,
     },
+    'env-pull': {
+        describe: "Pull the linked branch's Neon env vars (DATABASE_URL, …) into a local .env after " +
+            'linking. On by default; use --no-env-pull to skip (e.g. when injecting env at ' +
+            'runtime with `neon-env run` / `neon dev`).',
+        type: 'boolean',
+        default: true,
+    },
 });
 export const handler = async (props) => {
     if (props.agent) {
@@ -134,7 +143,7 @@ const runNonInteractive = async (props, inputs) => {
             projectId: inputs.projectId,
             branchId,
         });
-        printHumanSummary(props, {
+        await finalizeHumanLink(props, {
             contextFile: props.contextFile,
             orgId,
             projectId: inputs.projectId,
@@ -153,7 +162,7 @@ const runNonInteractive = async (props, inputs) => {
         projectId: created.project.id,
         branchId: created.branchId,
     });
-    printHumanSummary(props, {
+    await finalizeHumanLink(props, {
         contextFile: props.contextFile,
         orgId,
         projectId: created.project.id,
@@ -187,13 +196,13 @@ const runInteractive = async (props, inputs) => {
         orgId = await promptOrgFromList(orgResolution.orgs);
     }
     if (inputs.projectId) {
-        const branchId = await resolveDefaultBranchId(props, inputs.projectId);
+        const branchId = await resolveInteractiveBranchId(props, inputs.projectId);
         applyContext(props.contextFile, {
             orgId,
             projectId: inputs.projectId,
             branchId,
         });
-        printHumanSummary(props, {
+        await finalizeHumanLink(props, {
             contextFile: props.contextFile,
             orgId,
             projectId: inputs.projectId,
@@ -213,7 +222,7 @@ const runInteractive = async (props, inputs) => {
             projectId: created.project.id,
             branchId: created.branchId,
         });
-        printHumanSummary(props, {
+        await finalizeHumanLink(props, {
             contextFile: props.contextFile,
             orgId,
             projectId: created.project.id,
@@ -228,13 +237,13 @@ const runInteractive = async (props, inputs) => {
     const projects = await listAllProjects(props, orgId);
     const action = await promptProjectChoice(projects, inputs.projectName);
     if (action.type === 'existing') {
-        const branchId = await resolveDefaultBranchId(props, action.projectId);
+        const branchId = await resolveInteractiveBranchId(props, action.projectId);
         applyContext(props.contextFile, {
             orgId,
             projectId: action.projectId,
             branchId,
         });
-        printHumanSummary(props, {
+        await finalizeHumanLink(props, {
             contextFile: props.contextFile,
             orgId,
             projectId: action.projectId,
@@ -257,7 +266,7 @@ const runInteractive = async (props, inputs) => {
         projectId: created.project.id,
         branchId: created.branchId,
     });
-    printHumanSummary(props, {
+    await finalizeHumanLink(props, {
         contextFile: props.contextFile,
         orgId,
         projectId: created.project.id,
@@ -382,12 +391,18 @@ const runAgent = async (props, inputs) => {
     if (projectId) {
         const branchId = await resolveDefaultBranchId(props, projectId);
         applyContext(props.contextFile, { orgId, projectId, branchId });
+        const pullNote = renderAgentPullNote(await autoPullEnvAfterPin({
+            ...props,
+            projectId,
+            branch: branchId,
+            envPull: props.envPull,
+        }));
         emitAgent({
             status: 'linked',
             context_file: props.contextFile,
             context: { orgId, projectId, branchId },
             project: { id: projectId },
-            message: `Linked ${props.contextFile} to project ${projectId} (org ${orgId}) on branch ${branchId}.`,
+            message: `Linked ${props.contextFile} to project ${projectId} (org ${orgId}) on branch ${branchId}.${pullNote}`,
         });
         return;
     }
@@ -416,6 +431,12 @@ const runAgent = async (props, inputs) => {
             projectId: created.project.id,
             branchId: created.branchId,
         });
+        const pullNote = renderAgentPullNote(await autoPullEnvAfterPin({
+            ...props,
+            projectId: created.project.id,
+            branch: created.branchId,
+            envPull: props.envPull,
+        }));
         emitAgent({
             status: 'linked',
             context_file: props.contextFile,
@@ -429,7 +450,7 @@ const runAgent = async (props, inputs) => {
                 name: created.project.name,
                 region_id: created.project.region_id,
             },
-            message: `Created project ${created.project.id} ("${created.project.name ?? projectName}") in ${created.project.region_id ?? regionId} and linked ${props.contextFile}.`,
+            message: `Created project ${created.project.id} ("${created.project.name ?? projectName}") in ${created.project.region_id ?? regionId} and linked ${props.contextFile}.${pullNote}`,
         });
         return;
     }
@@ -591,6 +612,33 @@ const resolveDefaultBranchId = async (props, projectId) => {
     }
     return branch.id;
 };
+/**
+ * Resolve which branch to pin for an interactively-chosen project. When the project has a
+ * single branch there is nothing to choose, so we pin it silently. Otherwise we offer the
+ * shared branch picker (the same "＋ Create a new branch…" + list as `neonctl checkout`),
+ * creating the branch when the user opts to. This makes `link` a full org → project →
+ * branch flow instead of always pinning the default branch.
+ */
+const resolveInteractiveBranchId = async (props, projectId) => {
+    const { data } = await props.apiClient.listProjectBranches({ projectId });
+    const branches = data.branches;
+    if (branches.length <= 1) {
+        const only = branches.find((b) => b.default) ?? branches[0];
+        if (!only) {
+            throw new Error(`Could not find a default branch for project ${projectId}.`);
+        }
+        return only.id;
+    }
+    const picked = await pickBranchInteractively(branches, {
+        message: 'Which branch would you like to link?',
+        nonInteractiveMessage: 'No branch could be selected without an interactive terminal. ' +
+            'Re-run `neonctl link` interactively, or `neonctl checkout <branch>` to pin one.',
+    });
+    if (picked.kind === 'existing') {
+        return picked.branchId;
+    }
+    return createBranch(props.apiClient, projectId, picked.name, branches);
+};
 const fetchRegions = async (props) => {
     try {
         const { data } = await props.apiClient.getActiveRegions();
@@ -648,6 +696,20 @@ const printHumanSummary = (_props, summary) => {
     lines.push('');
     process.stdout.write(`${lines.join('\n')}\n`);
 };
+/**
+ * Print the link summary, then run the bundled `env pull` so a human `link` ends with the
+ * branch's connection string already on disk — the branch-first loop is just link + checkout.
+ * `--no-env-pull` opts out (env pull's own status / skip hint is logged to stderr).
+ */
+const finalizeHumanLink = async (props, summary) => {
+    printHumanSummary(props, summary);
+    await autoPullEnvAfterPin({
+        ...props,
+        projectId: summary.projectId,
+        branch: summary.branchId,
+        envPull: props.envPull,
+    });
+};
 const onPromptState = (state) => {
     if (state.aborted) {
         process.stdout.write('\x1B[?25h');

package/dev/env.js

@@ -82,24 +82,40 @@ export const resolveNeonEnvVars = async (ctx) => {
 };
 /**
  * `neon dev`'s env resolver: {@link resolveNeonEnvVars} with graceful degradation.
- * A missing branch context or any failure (no Neon account, no `.neon`, no network)
- * logs a warning and returns `{}` so the function still runs locally; only a
- * {@link DevEnvMismatchError} (policy declares a resource the branch lacks) is
- * re-thrown for the caller to surface.
+ *
+ * - Success → `{ vars }` (possibly just the always-present Postgres URLs).
+ * - No linked branch / project → `{ vars: {}, skipped }` with a "link a branch" hint; the
+ *   function still runs locally, just without Neon env.
+ * - Any other failure (offline, transient API error) → `{ vars: {}, skipped }` naming the
+ *   cause; again non-fatal.
+ * - {@link DevEnvMismatchError} (policy declares a secret-bearing service the branch lacks)
+ *   is the one hard stop and is re-thrown for the caller to surface.
  */
 export const resolveDevEnv = async (ctx) => {
     try {
-        return await resolveNeonEnvVars(ctx);
+        return { vars: await resolveNeonEnvVars(ctx) };
     }
     catch (err) {
         if (err instanceof DevEnvMismatchError)
             throw err;
         if (err instanceof MissingBranchContextError) {
             log.debug('dev: %s; skipping env injection', err.message);
-            return {};
+            return {
+                vars: {},
+                skipped: {
+                    reason: 'no linked Neon branch — run `neonctl link`, then ' +
+                        '`neonctl checkout <branch>`, to inject DATABASE_URL and friends',
+                },
+            };
         }
-        log.warning('Could not inject Neon env vars; the function will run without them: %s', err instanceof Error ? err.message : String(err));
-        return {};
+        const detail = err instanceof Error ? err.message : String(err);
+        log.debug('dev: env resolution failed: %s', detail);
+        return {
+            vars: {},
+            skipped: {
+                reason: `could not reach Neon (${detail}); running without Neon env`,
+            },
+        };
     }
 };
 /**

package/package.json

@@ -5,7 +5,7 @@
     "url": "git+ssh://git@github.com/neondatabase/neonctl.git"
   },
   "type": "module",
-  "version": "2.24.0",
+  "version": "2.24.1",
   "description": "CLI tool for NeonDB Cloud management",
   "main": "index.js",
   "author": "NeonDB",

package/pkg.js

@@ -1,3 +1,25 @@
 import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-export default JSON.parse(readFileSync(fileURLToPath(new URL('./package.json', import.meta.url)), 'utf-8'));
+/**
+ * Load the CLI's package.json for version metadata. In the built CLI it sits right next to
+ * this module (the build copies it into `dist`); when running from source (tests, `tsx`) it
+ * does not, so we walk up to the nearest `package.json`. Both layouts resolve to the same
+ * file, keeping `pkg.version` correct everywhere without a test-only shim.
+ */
+const loadPkg = () => {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        try {
+            return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf-8'));
+        }
+        catch {
+            const parent = dirname(dir);
+            if (parent === dir) {
+                throw new Error('Could not locate package.json for version detection.');
+            }
+            dir = parent;
+        }
+    }
+};
+export default loadPkg();

package/storage_api.js

@@ -0,0 +1,114 @@
+// Typed client helpers for the branch object-storage (bucket/object) API.
+//
+// These endpoints are part of the Neon object-storage surface (the "Buckets"
+// tag in the public API). They are not yet exposed as typed methods on the
+// published `@neondatabase/api-client` package, so the request/response types
+// and the thin call helpers live here. They are implemented on top of the
+// api-client's public `request()` method, which means they reuse the exact
+// same authentication, base URL, headers and retry behaviour as every other
+// neonctl command. When the generated client gains these methods, the call
+// sites in `src/commands/bucket.ts` can switch over with no behavioural
+// change.
+const bucketsPath = (projectId, branchId) => `/projects/${encodeURIComponent(projectId)}/branches/${encodeURIComponent(branchId)}/buckets`;
+const bucketPath = (projectId, branchId, bucketName) => `${bucketsPath(projectId, branchId)}/${encodeURIComponent(bucketName)}`;
+/**
+ * Create a bucket on a branch.
+ *
+ * @request POST /projects/{project_id}/branches/{branch_id}/buckets
+ */
+export const createProjectBranchBucket = (apiClient, { projectId, branchId, name, accessLevel, }) => {
+    const body = { name };
+    // Omit access_level entirely so the server default (`private`) applies.
+    if (accessLevel !== undefined) {
+        body.access_level = accessLevel;
+    }
+    return apiClient.request({
+        path: bucketsPath(projectId, branchId),
+        method: 'POST',
+        body,
+        format: 'json',
+        secure: true,
+    });
+};
+/**
+ * List the buckets on a branch.
+ *
+ * @request GET /projects/{project_id}/branches/{branch_id}/buckets
+ */
+export const listProjectBranchBuckets = (apiClient, { projectId, branchId }) => apiClient.request({
+    path: bucketsPath(projectId, branchId),
+    method: 'GET',
+    format: 'json',
+    secure: true,
+});
+/**
+ * Delete a bucket from a branch.
+ *
+ * @request DELETE /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}
+ */
+export const deleteProjectBranchBucket = (apiClient, { projectId, branchId, bucketName, }) => apiClient.request({
+    path: bucketPath(projectId, branchId, bucketName),
+    method: 'DELETE',
+    secure: true,
+});
+/**
+ * List objects (and collapsed folders) in a bucket on a branch.
+ *
+ * @request GET /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects
+ */
+export const listProjectBranchBucketObjects = (apiClient, { projectId, branchId, bucketName, ...query }) => apiClient.request({
+    path: `${bucketPath(projectId, branchId, bucketName)}/objects`,
+    method: 'GET',
+    query,
+    format: 'json',
+    secure: true,
+});
+/**
+ * Download an object's raw bytes from a bucket on a branch.
+ *
+ * The server returns the body as `application/octet-stream` with a
+ * `Content-Disposition: attachment` header; the helper requests the body as a
+ * stream (`responseType: 'stream'`), so `.data` is a Node `Readable` the caller
+ * can pipe straight to disk without buffering the whole object in memory. The
+ * response headers are returned alongside so the caller can derive a filename
+ * from `Content-Disposition`.
+ *
+ * The object key may contain `/`; it is percent-encoded into a single path
+ * segment so nested keys are routed to the `{object_key}` parameter.
+ *
+ * @request GET /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects/{object_key}/download
+ */
+export const getProjectBranchBucketObject = (apiClient, { projectId, branchId, bucketName, objectKey, }) => apiClient.request({
+    path: `${bucketPath(projectId, branchId, bucketName)}/objects/${encodeURIComponent(objectKey)}/download`,
+    method: 'GET',
+    format: 'stream',
+    secure: true,
+});
+/**
+ * Delete an object from a bucket on a branch.
+ *
+ * The object key may contain `/`; it is percent-encoded into a single path
+ * segment so nested keys are routed to the `{object_key}` parameter.
+ *
+ * @request DELETE /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects/{object_key}
+ */
+export const deleteProjectBranchBucketObject = (apiClient, { projectId, branchId, bucketName, objectKey, }) => apiClient.request({
+    path: `${bucketPath(projectId, branchId, bucketName)}/objects/${encodeURIComponent(objectKey)}`,
+    method: 'DELETE',
+    secure: true,
+});
+/**
+ * Delete every object under a key prefix (folder) in a bucket on a branch.
+ *
+ * `prefix` must be non-empty and end with `/`; every object on this branch
+ * whose key starts with the prefix is soft-deleted in a single call.
+ *
+ * @request DELETE /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects-by-prefix
+ */
+export const deleteProjectBranchBucketObjectsByPrefix = (apiClient, { projectId, branchId, bucketName, prefix, }) => apiClient.request({
+    path: `${bucketPath(projectId, branchId, bucketName)}/objects-by-prefix`,
+    method: 'DELETE',
+    query: { prefix },
+    format: 'json',
+    secure: true,
+});