Neon Postgres Agent Platforms

#!/usr/bin/env bash
# Reference-only curls for sample product REST routes (see CURL_REFERENCE.md: not Neon Management API).
# Safe defaults: localhost, no destructive verbs. Expect 401 without STACK_SESSION_COOKIE.

APP_BASE_URL="${APP_BASE_URL:-http://localhost:3000}"
APP_PROJECT_ID="${APP_PROJECT_ID:-YOUR_PROJECT_ID}"
APP_VERSION_ID="${APP_VERSION_ID:-YOUR_VERSION_ID}"

COOKIE_HEADER=()
if [[ -n "${STACK_SESSION_COOKIE:-}" ]]; then
  COOKIE_HEADER=(-H "Cookie: ${STACK_SESSION_COOKIE}")
fi

echo "# GET /api/v1/models (requires auth)"
curl -sS "${COOKIE_HEADER[@]}" "${APP_BASE_URL}/api/v1/models" | head -c 800
echo -e "\n"

echo "# POST /api/v1/projects, body: {\"name\": \"dev-placeholder\"}"
curl -sS -X POST "${COOKIE_HEADER[@]}" \
  -H "Content-Type: application/json" \
  -d '{"name":"dev-placeholder"}' \
  "${APP_BASE_URL}/api/v1/projects" | head -c 800
echo -e "\n"

echo "# GET /api/v1/projects/{projectId}/versions"
curl -sS "${COOKIE_HEADER[@]}" \
  "${APP_BASE_URL}/api/v1/projects/${APP_PROJECT_ID}/versions" | head -c 1200
echo -e "\n"

echo "# POST /api/v1/projects/{projectId}/checkpoint, optional assistantMessageId"
curl -sS -X POST "${COOKIE_HEADER[@]}" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "${APP_BASE_URL}/api/v1/projects/${APP_PROJECT_ID}/checkpoint" | head -c 800
echo -e "\n"

echo "# POST /api/v1/projects/{projectId}/versions, body: {\"versionId\": \"...\"}"
curl -sS -X POST "${COOKIE_HEADER[@]}" \
  -H "Content-Type: application/json" \
  -d "{\"versionId\":\"${APP_VERSION_ID}\"}" \
  "${APP_BASE_URL}/api/v1/projects/${APP_PROJECT_ID}/versions" | head -c 1200
echo -e "\n"

/**
 * Neon Auth: application users (REST) and how they show up in Postgres.
 *
 * Subcommands:
 *   meta     print [meta] map: REST vs Postgres, doc links
 *   create   POST .../auth/users (needs USER_EMAIL, optional USER_NAME)
 *   delete   DELETE .../auth/users/{id} (needs AUTH_USER_ID)
 */
import "dotenv/config";
import { createApiClient } from "@neondatabase/api-client";

const apiKey = process.env.NEON_API_KEY?.trim();
const projectId = process.env.NEON_PROJECT_ID;
const branchId = process.env.NEON_BRANCH_ID;
const [, , cmd] = process.argv;

function printMeta(): void {
  console.log(
    JSON.stringify(
      {
        title:
          "[meta] Application users (Neon Auth) vs Postgres database roles",
        rest: {
          createUser:
            "POST /api/v2/projects/{project_id}/branches/{branch_id}/auth/users",
          deleteUser:
            "DELETE /api/v2/projects/{project_id}/branches/{branch_id}/auth/users/{auth_user_id}",
          updateRole:
            "PUT /api/v2/projects/{project_id}/branches/{branch_id}/auth/users/{auth_user_id}/role",
          enableAuth:
            "POST /api/v2/projects/{project_id}/branches/{branch_id}/auth",
        },
        postgres: {
          note: "Neon Auth syncs user data into the branch database (default schema `neon_auth`, e.g. table `users_sync`).",
          listUsersExampleSql: "SELECT * FROM neon_auth.users_sync LIMIT 50;",
          rolesNote:
            "Database roles (connection users, privileges) are separate; use SQL or Console (Manage roles), not this REST API.",
        },
        docs: [
          "https://neon.com/docs/neon-auth/api",
          "https://neon.com/docs/auth/guides/user-management",
          "https://neon.com/docs/manage/users",
          "https://api-docs.neon.tech/reference/createbranchneonauthnewuser",
        ],
        envForThisScript: {
          create: [
            "NEON_API_KEY",
            "NEON_PROJECT_ID",
            "NEON_BRANCH_ID",
            "USER_EMAIL",
            "USER_NAME (optional)",
          ],
          delete: [
            "NEON_API_KEY",
            "NEON_PROJECT_ID",
            "NEON_BRANCH_ID",
            "AUTH_USER_ID",
          ],
        },
      },
      null,
      2,
    ),
  );
}

if (cmd === "meta") {
  printMeta();
  process.exit(0);
}

if (!["create", "delete"].includes(cmd ?? "")) {
  console.error(
    "Usage: npm run auth-users -- meta | create | delete\n" +
      "  meta   [meta] REST vs Postgres, links\n" +
      "  create requires USER_EMAIL (and project/branch)\n" +
      "  delete requires AUTH_USER_ID",
  );
  process.exit(1);
}

if (!apiKey) {
  console.error("NEON_API_KEY is required.");
  process.exit(1);
}

if (!projectId || !branchId) {
  console.error("Set NEON_PROJECT_ID and NEON_BRANCH_ID.");
  process.exit(1);
}

const api = createApiClient({ apiKey });

if (cmd === "create") {
  const email = process.env.USER_EMAIL;
  const name = process.env.USER_NAME;
  if (!email) {
    console.error("Set USER_EMAIL for create.");
    process.exit(1);
  }
  const { data } = await api.createBranchNeonAuthNewUser(projectId, branchId, {
    email,
    ...(name ? { name } : {}),
  });
  console.log(JSON.stringify(data, null, 2));
  process.exit(0);
}

if (cmd === "delete") {
  const authUserId = process.env.AUTH_USER_ID;
  if (!authUserId) {
    console.error("Set AUTH_USER_ID for delete.");
    process.exit(1);
  }
  await api.deleteBranchNeonAuthUser(projectId, branchId, authUserId);
  console.log(JSON.stringify({ ok: true, deleted: authUserId }, null, 2));
  process.exit(0);
}

/**
 * List branches or create a dev branch from production (main / production).
 *
 * Usage (from `scripts/` after `npm run build`):
 *   NEON_API_KEY=... NEON_PROJECT_ID=... node dist/scripts/branch.js list
 *   NEON_API_KEY=... NEON_PROJECT_ID=... node dist/scripts/branch.js create <branch-name>
 * Or: npm run branch -- list | create <branch-name>
 */
import "dotenv/config";
import { createApiClient } from "@neondatabase/api-client";

import { createBranchWithOperations, getProductionBranchId } from "./utils.js";

const apiKey = process.env.NEON_API_KEY?.trim();
const projectId = process.env.NEON_PROJECT_ID;
const [, , cmd, branchName] = process.argv;

if (!apiKey) {
  console.error("NEON_API_KEY is required.");
  process.exit(1);
}

if (!projectId) {
  console.error("Set NEON_PROJECT_ID.");
  process.exit(1);
}

const api = createApiClient({ apiKey });

if (cmd === "list") {
  const { data } = await api.listProjectBranches({ projectId });
  const branches = (data.branches ?? []).map((b) => ({
    id: b.id,
    name: b.name,
    created_at: b.created_at,
    parent_id: b.parent_id,
  }));
  console.log(JSON.stringify(branches, null, 2));
  process.exit(0);
}

if (cmd === "create") {
  if (!branchName) {
    console.error("Usage: npm run branch -- create <branch-name>");
    process.exit(1);
  }
  const prodId =
    process.env.NEON_PARENT_BRANCH_ID?.trim() ||
    (await getProductionBranchId(api, projectId));
  if (!prodId) {
    console.error("Could not resolve production branch (main or production).");
    process.exit(1);
  }
  const { id } = await createBranchWithOperations(api, projectId, {
    name: branchName,
    parentId: prodId,
  });
  console.log(
    JSON.stringify({ branchId: id, parentBranchId: prodId }, null, 2),
  );
  process.exit(0);
}

console.error("Usage: npm run branch -- list | create <branch-name>");
process.exit(1);

/**
 * GET /consumption_history/v2/projects: usage-based metrics aligned with billing.
 *
 * `metrics` query parameter: comma-separated or repeated; each value must be one of:
 * `compute_unit_seconds`, `root_branch_bytes_month`, `child_branch_bytes_month`,
 * `instant_restore_bytes_month`, `snapshot_storage_bytes_month`,
 * `public_network_transfer_bytes`, `private_network_transfer_bytes`, `extra_branches_month`.
 *
 * Do not use legacy `GET /consumption_history/account` for new work; it is deprecated with a planned
 * sunset of **2026-06-01** — use this v2 project endpoint (or legacy per-project metrics only if you
 * still need legacy fields). See Neon’s consumption docs.
 * @see https://neon.com/docs/guides/consumption-metrics
 * @see https://neon.com/docs/guides/consumption-metrics-legacy
 */
import "dotenv/config";
import {
  ConsumptionHistoryGranularity,
  createApiClient,
} from "@neondatabase/api-client";

const apiKey = process.env.NEON_API_KEY?.trim();
const orgId = process.env.NEON_ORG_ID;
const from = process.env.CONSUMPTION_FROM;
const to = process.env.CONSUMPTION_TO;
const granularityRaw = process.env.CONSUMPTION_GRANULARITY || "daily";

const DEFAULT_METRICS = [
  "compute_unit_seconds",
  "root_branch_bytes_month",
  "child_branch_bytes_month",
  "instant_restore_bytes_month",
  "snapshot_storage_bytes_month",
  "public_network_transfer_bytes",
  "private_network_transfer_bytes",
  "extra_branches_month",
];

const metricsRaw = process.env.CONSUMPTION_METRICS;
const metrics = metricsRaw
  ? metricsRaw
      .split(",")
      .map((s: string) => s.trim())
      .filter(Boolean)
  : DEFAULT_METRICS;

const projectIdsRaw = process.env.CONSUMPTION_PROJECT_IDS;
const projectIds = projectIdsRaw
  ? projectIdsRaw
      .split(",")
      .map((s: string) => s.trim())
      .filter(Boolean)
  : undefined;

const GRANULARITY_BY_ENV: Record<string, ConsumptionHistoryGranularity> = {
  hourly: ConsumptionHistoryGranularity.Hourly,
  daily: ConsumptionHistoryGranularity.Daily,
  monthly: ConsumptionHistoryGranularity.Monthly,
};

if (!apiKey || !orgId || !from || !to) {
  console.error(
    "Set NEON_API_KEY, NEON_ORG_ID, CONSUMPTION_FROM, CONSUMPTION_TO (RFC 3339). Optional: CONSUMPTION_GRANULARITY, CONSUMPTION_METRICS (comma list), CONSUMPTION_PROJECT_IDS.",
  );
  process.exit(1);
}

const granularity = GRANULARITY_BY_ENV[granularityRaw];
if (granularity === undefined) {
  console.error("CONSUMPTION_GRANULARITY must be hourly, daily, or monthly.");
  process.exit(1);
}

const api = createApiClient({ apiKey });
const { data } = await api.getConsumptionHistoryPerProjectV2({
  org_id: orgId,
  from,
  to,
  granularity,
  metrics,
  project_ids: projectIds,
  limit: process.env.CONSUMPTION_LIMIT
    ? Number(process.env.CONSUMPTION_LIMIT)
    : undefined,
  cursor: process.env.CONSUMPTION_CURSOR || undefined,
});

console.log(JSON.stringify(data, null, 2));

/**
 * Create a Neon project, then enable Neon Auth on the default branch (Better Auth).
 *
 * Prints Neon Auth keys once; store pub_client_key / secret_server_key securely.
 */
import "dotenv/config";
import {
  createApiClient,
  NeonAuthSupportedAuthProvider,
} from "@neondatabase/api-client";

import { createProjectWithOperations, getProductionBranchId } from "./utils.js";

const apiKey = process.env.NEON_API_KEY?.trim();
const orgId = process.env.NEON_ORG_ID;
const name =
  process.env.NEON_PROJECT_NAME?.trim() || `tenant-auth-${Date.now()}`;
const authDb = process.env.NEON_AUTH_DATABASE_NAME?.trim();

if (!apiKey) {
  console.error("NEON_API_KEY is required.");
  process.exit(1);
}

const api = createApiClient({ apiKey });

const { projectId, databaseUrl } = await createProjectWithOperations(api, {
  name,
  orgId: orgId || undefined,
  endpointSettings: {
    autoscaling_limit_min_cu: 0.25,
    autoscaling_limit_max_cu: 2,
    suspend_timeout_seconds: 300,
  },
});

const prodBranchId = await getProductionBranchId(api, projectId);
if (!prodBranchId) {
  console.error(
    JSON.stringify(
      { error: "No production branch after create", projectId },
      null,
      2,
    ),
  );
  process.exit(1);
}

const { data: neonAuth } = await api.createNeonAuth(projectId, prodBranchId, {
  auth_provider: NeonAuthSupportedAuthProvider.BetterAuth,
  ...(authDb ? { database_name: authDb } : {}),
});

console.error(
  "[neon-auth] Keys below are shown once by Neon; save pub_client_key and secret_server_key.",
);

console.log(
  JSON.stringify(
    {
      projectId,
      branchId: prodBranchId,
      databaseUrl,
      name,
      neonAuth,
    },
    null,
    2,
  ),
);

/**
 * Create a Neon project (REST API). Optional org + autoscaling match multi-tenant / Agent Program flows.
 */
import "dotenv/config";
import { createApiClient } from "@neondatabase/api-client";

import { createProjectWithOperations } from "./utils.js";

const apiKey = process.env.NEON_API_KEY?.trim();
const orgId = process.env.NEON_ORG_ID;
const name = process.env.NEON_PROJECT_NAME?.trim() || `tenant-${Date.now()}`;

if (!apiKey) {
  console.error("NEON_API_KEY is required.");
  process.exit(1);
}

const api = createApiClient({ apiKey });

const { projectId, databaseUrl } = await createProjectWithOperations(api, {
  name,
  orgId: orgId || undefined,
  endpointSettings: {
    autoscaling_limit_min_cu: 0.25,
    autoscaling_limit_max_cu: 2,
    suspend_timeout_seconds: 300,
  },
});

console.log(JSON.stringify({ projectId, databaseUrl, name }, null, 2));

/**
 * Delete a branch by id (e.g. orphaned `main (old)` after a finalized restore).
 * Destructive; Neon may reject protected/root branches.
 *
 * @see https://neon.com/docs/ai/ai-database-versioning#cleanup-strategy
 */
import "dotenv/config";
import { createApiClient } from "@neondatabase/api-client";

import { deleteBranchWithWait } from "./utils.js";

const apiKey = process.env.NEON_API_KEY?.trim();
const projectId = process.env.NEON_PROJECT_ID;
const branchId = process.env.NEON_BRANCH_ID;

if (!apiKey || !projectId || !branchId) {
  console.error("Set NEON_API_KEY, NEON_PROJECT_ID, and NEON_BRANCH_ID.");
  process.exit(1);
}

console.error(
  "[delete-branch] Deleting branch; irreversible for that branch environment.",
);

const api = createApiClient({ apiKey });
await deleteBranchWithWait(api, projectId, branchId);
console.log(JSON.stringify({ ok: true, projectId, branchId }, null, 2));

import "dotenv/config";
import { createApiClient } from "@neondatabase/api-client";

const apiKey = process.env.NEON_API_KEY?.trim();
const projectId = process.env.NEON_PROJECT_ID;

if (!apiKey) {
  console.error("NEON_API_KEY is required.");
  process.exit(1);
}

if (!projectId) {
  console.error("Set NEON_PROJECT_ID to the project to delete.");
  process.exit(1);
}

const api = createApiClient({ apiKey });
await api.deleteProject(projectId);
console.log(`Deleted project ${projectId}`);

/**
 * Delete one snapshot by id (async operations are polled to completion).
 * @see https://neon.com/docs/ai/ai-database-versioning#delete-snapshot
 */
import "dotenv/config";
import { createApiClient } from "@neondatabase/api-client";

import { deleteSnapshotWithWait } from "./utils.js";

const apiKey = process.env.NEON_API_KEY?.trim();
const projectId = process.env.NEON_PROJECT_ID;
const snapshotId = process.env.NEON_SNAPSHOT_ID;

if (!apiKey || !projectId || !snapshotId) {
  console.error("Set NEON_API_KEY, NEON_PROJECT_ID, and NEON_SNAPSHOT_ID.");
  process.exit(1);
}

const api = createApiClient({ apiKey });
await deleteSnapshotWithWait(api, projectId, snapshotId);
console.log(JSON.stringify({ ok: true, projectId, snapshotId }, null, 2));

import "dotenv/config";
import { createApiClient } from "@neondatabase/api-client";

const apiKey = process.env.NEON_API_KEY?.trim();
if (!apiKey) {
  throw new Error(
    "NEON_API_KEY is required. Add it to .env (see .env.example) or export it in your shell.",
  );
}

const api = createApiClient({ apiKey });

const { data } = await api.listProjects({ limit: 400 });
const projects = data.projects ?? [];

for (const p of projects) {
  const id = p.id;
  const name = p.name ?? "";
  if (!id) continue;
  console.log(`${id}\t${name}`);
}

/**
 * List all logical snapshots for a project (IDs, names, timestamps; see Neon API).
 * @see https://neon.com/docs/ai/ai-database-versioning#list-available-snapshots
 */
import "dotenv/config";
import { createApiClient } from "@neondatabase/api-client";

const apiKey = process.env.NEON_API_KEY?.trim();
const projectId = process.env.NEON_PROJECT_ID;

if (!apiKey || !projectId) {
  console.error("Set NEON_API_KEY and NEON_PROJECT_ID.");
  process.exit(1);
}

const api = createApiClient({ apiKey });
const { data } = await api.listSnapshots(projectId);
const snapshots = data.snapshots ?? [];
console.log(JSON.stringify({ projectId, snapshots }, null, 2));

{
  "name": "neon-for-agent-platforms",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "neon-for-agent-platforms",
      "version": "1.0.0",
      "license": "Apache-2.0",
      "dependencies": {
        "@neondatabase/api-client": "^2.7.1",
        "dotenv": "^16.5.0"
      },
      "devDependencies": {
        "@types/node": "^25.6.0",
        "prettier": "^3.4.2",
        "typescript": "^6.0.3"
      }
    },
    "node_modules/@neondatabase/api-client": {
      "version": "2.7.1",
      "resolved": "https://registry.npmjs.org/@neondatabase/api-client/-/api-client-2.7.1.tgz",
      "integrity": "sha512-hEYOJ89xIa2eEXBu9HRKYTJc9lrmszhNc0SIxzJvNE/3Av4xK7vkXWQ3LWy0DTTFY4Kn6wfM2wAjRIjf/jOu6w==",
      "license": "MIT",
      "dependencies": {
        "axios": "^1.13.5"
      }
    },
    "node_modules/@types/node": {
      "version": "25.6.0",
      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.6.0.tgz",
      "integrity": "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
        "undici-types": "~7.19.0"
      }
    },
    "node_modules/asynckit": {
      "version": "0.4.0",
      "resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz",
      "integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==",
      "license": "MIT"
    },
    "node_modules/axios": {
      "version": "1.15.2",
      "resolved": "https://registry.npmjs.org/axios/-/axios-1.15.2.tgz",
      "integrity": "sha512-wLrXxPtcrPTsNlJmKjkPnNPK2Ihe0hn0wGSaTEiHRPxwjvJwT3hKmXF4dpqxmPO9SoNb2FsYXj/xEo0gHN+D5A==",
      "license": "MIT",
      "dependencies": {
        "follow-redirects": "^1.15.11",
        "form-data": "^4.0.5",
        "proxy-from-env": "^2.1.0"
      }
    },
    "node_modules/call-bind-apply-helpers": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz",
      "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==",
      "license": "MIT",
      "dependencies": {
        "es-errors": "^1.3.0",
        "function-bind": "^1.1.2"
      },
      "engines": {
        "node": ">= 0.4"
      }
    },
    "node_modules/combined-stream": {
      "version": "1.0.8",
      "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz",
      "integrity": "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==",
      "license": "MIT",
      "dependencies": {
        "delayed-stream": "~1.0.0"
      },
      "engines": {
        "node": ">= 0.8"
      }
    },
    "node_modules/delayed-stream": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz",
      "integrity": "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==",
      "license": "MIT",
      "engines": {
        "node": ">=0.4.0"
      }
    },
    "node_modules/dotenv": {
      "version": "16.6.1",
      "resolved": "https://npm-proxy.dev.databricks.com/dotenv/-/dotenv-16.6.1.tgz",
      "integrity": "sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==",
      "license": "BSD-2-Clause",
      "engines": {
        "node": ">=12"
      },
      "funding": {
        "url": "https://dotenvx.com"
      }
    },
    "node_modules/dunder-proto": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
      "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==",
      "license": "MIT",
      "dependencies": {
        "call-bind-apply-helpers": "^1.0.1",
        "es-errors": "^1.3.0",
        "gopd": "^1.2.0"
      },
      "engines": {
        "node": ">= 0.4"
      }
    },
    "node_modules/es-define-property": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
      "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==",
      "license": "MIT",
      "engines": {
        "node": ">= 0.4"
      }
    },
    "node_modules/es-errors": {
      "version": "1.3.0",
      "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz",
      "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==",
      "license": "MIT",
      "engines": {
        "node": ">= 0.4"
      }
    },
    "node_modules/es-object-atoms": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz",
      "integrity": "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==",
      "license": "MIT",
      "dependencies": {
        "es-errors": "^1.3.0"
      },
      "engines": {
        "node": ">= 0.4"
      }
    },
    "node_modules/es-set-tostringtag": {
      "version": "2.1.0",
      "resolved": "https://registry.npmjs.org/es-set-tostringtag/-/es-set-tostringtag-2.1.0.tgz",
      "integrity": "sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==",
      "license": "MIT",
      "dependencies": {
        "es-errors": "^1.3.0",
        "get-intrinsic": "^1.2.6",
        "has-tostringtag": "^1.0.2",
        "hasown": "^2.0.2"
      },
      "engines": {
        "node": ">= 0.4"
      }
    },
    "node_modules/follow-redirects": {
      "version": "1.16.0",
      "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.16.0.tgz",
      "integrity": "sha512-y5rN/uOsadFT/JfYwhxRS5R7Qce+g3zG97+JrtFZlC9klX/W5hD7iiLzScI4nZqUS7DNUdhPgw4xI8W2LuXlUw==",
      "funding": [
        {
          "type": "individual",
          "url": "https://github.com/sponsors/RubenVerborgh"
        }
      ],
      "license": "MIT",
      "engines": {
        "node": ">=4.0"
      },
      "peerDependenciesMeta": {
        "debug": {
          "optional": true
        }
      }
    },
    "node_modules/form-data": {
      "version": "4.0.5",
      "resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.5.tgz",
      "integrity": "sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==",
      "license": "MIT",
      "dependencies": {
        "asynckit": "^0.4.0",
        "combined-stream": "^1.0.8",
        "es-set-tostringtag": "^2.1.0",
        "hasown": "^2.0.2",
        "mime-types": "^2.1.12"
      },
      "engines": {
        "node": ">= 6"
      }
    },
    "node_modules/function-bind": {
      "version": "1.1.2",
      "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
      "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==",
      "license": "MIT",
      "funding": {
        "url": "https://github.com/sponsors/ljharb"
      }
    },
    "node_modules/get-intrinsic": {
      "version": "1.3.0",
      "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
      "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==",
      "license": "MIT",
      "dependencies": {
        "call-bind-apply-helpers": "^1.0.2",
        "es-define-property": "^1.0.1",
        "es-errors": "^1.3.0",
        "es-object-atoms": "^1.1.1",
        "function-bind": "^1.1.2",
        "get-proto": "^1.0.1",
        "gopd": "^1.2.0",
        "has-symbols": "^1.1.0",
        "hasown": "^2.0.2",
        "math-intrinsics": "^1.1.0"
      },
      "engines": {
        "node": ">= 0.4"
      },
      "funding": {
        "url": "https://github.com/sponsors/ljharb"
      }
    },
    "node_modules/get-proto": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz",
      "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==",
      "license": "MIT",
      "dependencies": {
        "dunder-proto": "^1.0.1",
        "es-object-atoms": "^1.0.0"
      },
      "engines": {
        "node": ">= 0.4"
      }
    },
    "node_modules/gopd": {
      "version": "1.2.0",
      "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
      "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==",
      "license": "MIT",
      "engines": {
        "node": ">= 0.4"
      },
      "funding": {
        "url": "https://github.com/sponsors/ljharb"
      }
    },
    "node_modules/has-symbols": {
      "version": "1.1.0",
      "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz",
      "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==",
      "license": "MIT",
      "engines": {
        "node": ">= 0.4"
      },
      "funding": {
        "url": "https://github.com/sponsors/ljharb"
      }
    },
    "node_modules/has-tostringtag": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/has-tostringtag/-/has-tostringtag-1.0.2.tgz",
      "integrity": "sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==",
      "license": "MIT",
      "dependencies": {
        "has-symbols": "^1.0.3"
      },
      "engines": {
        "node": ">= 0.4"
      },
      "funding": {
        "url": "https://github.com/sponsors/ljharb"
      }
    },
    "node_modules/hasown": {
      "version": "2.0.3",
      "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.3.tgz",
      "integrity": "sha512-ej4AhfhfL2Q2zpMmLo7U1Uv9+PyhIZpgQLGT1F9miIGmiCJIoCgSmczFdrc97mWT4kVY72KA+WnnhJ5pghSvSg==",
      "license": "MIT",
      "dependencies": {
        "function-bind": "^1.1.2"
      },
      "engines": {
        "node": ">= 0.4"
      }
    },
    "node_modules/math-intrinsics": {
      "version": "1.1.0",
      "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
      "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==",
      "license": "MIT",
      "engines": {
        "node": ">= 0.4"
      }
    },
    "node_modules/mime-db": {
      "version": "1.52.0",
      "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz",
      "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==",
      "license": "MIT",
      "engines": {
        "node": ">= 0.6"
      }
    },
    "node_modules/mime-types": {
      "version": "2.1.35",
      "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz",
      "integrity": "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==",
      "license": "MIT",
      "dependencies": {
        "mime-db": "1.52.0"
      },
      "engines": {
        "node": ">= 0.6"
      }
    },
    "node_modules/prettier": {
      "version": "3.8.3",
      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.8.3.tgz",
      "integrity": "sha512-7igPTM53cGHMW8xWuVTydi2KO233VFiTNyF5hLJqpilHfmn8C8gPf+PS7dUT64YcXFbiMGZxS9pCSxL/Dxm/Jw==",
      "dev": true,
      "license": "MIT",
      "bin": {
        "prettier": "bin/prettier.cjs"
      },
      "engines": {
        "node": ">=14"
      },
      "funding": {
        "url": "https://github.com/prettier/prettier?sponsor=1"
      }
    },
    "node_modules/proxy-from-env": {
      "version": "2.1.0",
      "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-2.1.0.tgz",
      "integrity": "sha512-cJ+oHTW1VAEa8cJslgmUZrc+sjRKgAKl3Zyse6+PV38hZe/V6Z14TbCuXcan9F9ghlz4QrFr2c92TNF82UkYHA==",
      "license": "MIT",
      "engines": {
        "node": ">=10"
      }
    },
    "node_modules/typescript": {
      "version": "6.0.3",
      "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz",
      "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==",
      "dev": true,
      "license": "Apache-2.0",
      "bin": {
        "tsc": "bin/tsc",
        "tsserver": "bin/tsserver"
      },
      "engines": {
        "node": ">=14.17"
      }
    },
    "node_modules/undici-types": {
      "version": "7.19.2",
      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.19.2.tgz",
      "integrity": "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg==",
      "dev": true,
      "license": "MIT"
    }
  }
}

{
  "name": "neon-for-agent-platforms",
  "version": "1.0.0",
  "private": true,
  "description": "Neon Agent Program examples and companion Agent Skill",
  "license": "Apache-2.0",
  "repository": {
    "type": "git",
    "url": "https://github.com/neondatabase/neon-for-agent-platforms"
  },
  "keywords": ["neon", "postgres", "agent-skills", "ai-agents"],
  "type": "module",
  "scripts": {
    "fmt": "prettier --write \"**/*.ts\"",
    "fmt:check": "prettier --check \"**/*.ts\"",
    "typecheck": "tsc --noEmit",
    "build": "tsc",
    "neon:list-projects": "npm run build && node dist/scripts/list-projects.js",
    "create-project": "npm run build && node dist/scripts/create-project.js",
    "create-project-with-auth": "npm run build && node dist/scripts/create-project-with-auth.js",
    "delete-project": "npm run build && node dist/scripts/delete-project.js",
    "branch": "npm run build && node dist/scripts/branch.js",
    "snapshot": "npm run build && node dist/scripts/snapshot.js",
    "list-snapshots": "npm run build && node dist/scripts/list-snapshots.js",
    "delete-snapshot": "npm run build && node dist/scripts/delete-snapshot.js",
    "rename-snapshot": "npm run build && node dist/scripts/rename-snapshot.js",
    "delete-branch": "npm run build && node dist/scripts/delete-branch.js",
    "promote-safe": "npm run build && node dist/scripts/promote-safe-production.js",
    "versioning-flow": "npm run build && node dist/scripts/versioning-flow.js",
    "restore-snapshot": "npm run build && node dist/scripts/restore-snapshot.js",
    "transfer": "npm run build && node dist/scripts/transfer-project.js",
    "consumption": "npm run build && node dist/scripts/consumption-query.js",
    "auth-users": "npm run build && node dist/scripts/auth-users.js"
  },
  "dependencies": {
    "@neondatabase/api-client": "^2.7.1",
    "dotenv": "^16.5.0"
  },
  "devDependencies": {
    "@types/node": "^25.6.0",
    "prettier": "^3.4.2",
    "typescript": "^6.0.3"
  }
}

/**
 * Snapshot-based promotion workflow from:
 * https://neon.com/blog/promoting-postgres-changes-safely-production
 *
 * Usage (from `scripts/` after `npm run build`):
 *   npm run promote-safe -- <subcommand>
 *   node dist/scripts/promote-safe-production.js <subcommand>
 */
import "dotenv/config";
import { createApiClient } from "@neondatabase/api-client";

import {
  applySnapshotToBranch,
  createLogicalSnapshot,
  getProductionBranchId,
  restoreSnapshotAsNewBranch,
} from "./utils.js";

const apiKey = process.env.NEON_API_KEY?.trim();
const projectIdEnv = process.env.NEON_PROJECT_ID;
const [, , sub] = process.argv;

function usage(): void {
  console.error(`Usage: npm run promote-safe -- <bootstrap-dev|promote|refresh-dev|rollback-prod>

See https://neon.com/blog/promoting-postgres-changes-safely-production
`);
}

if (!apiKey || !projectIdEnv) {
  console.error("Set NEON_API_KEY and NEON_PROJECT_ID.");
  usage();
  process.exit(1);
}

const projectId: string = projectIdEnv;

if (!sub) {
  usage();
  process.exit(1);
}

const api = createApiClient({ apiKey });

async function prodBranchId(): Promise<string> {
  const id = process.env.NEON_PROD_BRANCH_ID?.trim();
  if (id) return id;
  const prod = await getProductionBranchId(api, projectId);
  if (!prod) {
    throw new Error(
      "No production branch (main/production) and NEON_PROD_BRANCH_ID unset",
    );
  }
  return prod;
}

const runId = Date.now();

if (sub === "bootstrap-dev") {
  const newName = process.env.NEON_BOOTSTRAP_DEV_BRANCH_NAME?.trim() || "dev";
  const pre = await prodBranchId();
  console.error(
    `[bootstrap-dev] Snapshot production branch, restore as new branch "${newName}"...`,
  );
  const snapId = await createLogicalSnapshot(api, projectId, {
    branchId: pre,
    name:
      process.env.NEON_SNAPSHOT_BOOTSTRAP_NAME?.trim() ??
      `bootstrap-from-prod-${runId}`,
  });
  const branchId = await restoreSnapshotAsNewBranch(
    api,
    projectId,
    snapId,
    newName,
    false,
  );
  console.log(
    JSON.stringify(
      {
        phase: "bootstrap-dev",
        prodBranchId: pre,
        snapshotFromProdId: snapId,
        newDevBranchId: branchId,
        newDevBranchName: newName,
        note: "Point dev workloads at newDevBranchId; cleanup orphaned branches in Console if needed.",
      },
      null,
      2,
    ),
  );
  process.exit(0);
}

if (sub === "promote") {
  const devBranchId = process.env.NEON_DEV_BRANCH_ID?.trim();
  if (!devBranchId) {
    console.error(
      "Set NEON_DEV_BRANCH_ID (branch whose state you promote to production).",
    );
    process.exit(1);
  }
  const prodId = await prodBranchId();
  const preName =
    process.env.NEON_SNAPSHOT_PRE_PROMOTION_NAME?.trim() ??
    `prod_snap_${runId}_pre_promotion`;
  const candName =
    process.env.NEON_SNAPSHOT_DEV_CANDIDATE_NAME?.trim() ??
    `dev_snap_${runId}_candidate`;

  console.error("[promote] 1/3 Snapshot prod (rollback point)...");
  const rollbackSnapId = await createLogicalSnapshot(api, projectId, {
    branchId: prodId,
    name: preName,
  });

  console.error("[promote] 2/3 Snapshot dev (candidate to publish)...");
  const candidateSnapId = await createLogicalSnapshot(api, projectId, {
    branchId: devBranchId,
    name: candName,
  });

  console.error(
    "[promote] 3/3 Restore dev snapshot onto prod (finalize); brief connection drop on prod...",
  );
  await applySnapshotToBranch(api, projectId, candidateSnapId, prodId, {
    finalizeRestore: true,
    restoreBranchName:
      process.env.NEON_RESTORE_BACKUP_BRANCH_NAME ?? `before_promote_${runId}`,
  });

  console.error(
    "[promote] Done. Re-fetch prod branch id after finalize if you store it (Neon may rotate branch id).",
  );
  console.log(
    JSON.stringify(
      {
        phase: "promote",
        prodBranchIdBeforeNote: prodId,
        rollbackSnapshotId: rollbackSnapId,
        promotedSnapshotId: candidateSnapId,
        warning:
          "Production writes after rollbackSnapId was taken are not included. Delete orphaned backup branches when ready.",
      },
      null,
      2,
    ),
  );
  process.exit(0);
}

if (sub === "refresh-dev") {
  const devBranchId = process.env.NEON_DEV_BRANCH_ID?.trim();
  if (!devBranchId) {
    console.error(
      "Set NEON_DEV_BRANCH_ID (branch to refresh from current prod).",
    );
    process.exit(1);
  }
  const prodId = await prodBranchId();
  const snapName =
    process.env.NEON_SNAPSHOT_REFRESH_NAME?.trim() ??
    `prod_snap_${runId}_refresh_dev`;

  console.error("[refresh-dev] 1/2 Snapshot prod...");
  const prodSnapId = await createLogicalSnapshot(api, projectId, {
    branchId: prodId,
    name: snapName,
  });

  console.error("[refresh-dev] 2/2 Restore prod snapshot onto dev...");
  await applySnapshotToBranch(api, projectId, prodSnapId, devBranchId, {
    finalizeRestore: true,
    restoreBranchName:
      process.env.NEON_RESTORE_BACKUP_BRANCH_NAME ??
      `before_refresh_dev_${runId}`,
  });

  console.log(
    JSON.stringify(
      {
        phase: "refresh-dev",
        prodBranchId: prodId,
        devBranchId,
        prodSnapshotId: prodSnapId,
      },
      null,
      2,
    ),
  );
  process.exit(0);
}

if (sub === "rollback-prod") {
  const snap = process.env.NEON_SNAPSHOT_ID?.trim();
  if (!snap) {
    console.error(
      "Set NEON_SNAPSHOT_ID (e.g. pre-promotion rollback snapshot id).",
    );
    process.exit(1);
  }
  const prodId = await prodBranchId();

  console.error("[rollback-prod] Restore snapshot onto prod...");
  await applySnapshotToBranch(api, projectId, snap, prodId, {
    finalizeRestore: true,
    restoreBranchName:
      process.env.NEON_RESTORE_BACKUP_BRANCH_NAME ?? `before_rollback_${runId}`,
  });

  console.log(
    JSON.stringify(
      {
        phase: "rollback-prod",
        prodBranchId: prodId,
        restoredFromSnapshotId: snap,
      },
      null,
      2,
    ),
  );
  process.exit(0);
}

console.error(`Unknown subcommand: ${sub}`);
usage();
process.exit(1);

/**
 * Rename a snapshot (PATCH metadata only).
 * @see https://neon.com/docs/ai/ai-database-versioning#update-snapshot-name
 */
import "dotenv/config";
import { createApiClient } from "@neondatabase/api-client";

const apiKey = process.env.NEON_API_KEY?.trim();
const projectId = process.env.NEON_PROJECT_ID;
const snapshotId = process.env.NEON_SNAPSHOT_ID;
const name = process.env.NEON_SNAPSHOT_NEW_NAME?.trim();

if (!apiKey || !projectId || !snapshotId || !name) {
  console.error(
    "Set NEON_API_KEY, NEON_PROJECT_ID, NEON_SNAPSHOT_ID, and NEON_SNAPSHOT_NEW_NAME.",
  );
  process.exit(1);
}

const api = createApiClient({ apiKey });
await api.updateSnapshot(projectId, snapshotId, {
  snapshot: { name },
});
console.log(JSON.stringify({ ok: true, projectId, snapshotId, name }, null, 2));

/**
 * Restore an existing snapshot onto a branch (single REST step after versioning-flow or Console).
 *
 * @see https://neon.com/docs/ai/ai-database-versioning
 */
import "dotenv/config";
import { createApiClient } from "@neondatabase/api-client";

import { applySnapshotToBranch } from "./utils.js";

const apiKey = process.env.NEON_API_KEY?.trim();
const projectId = process.env.NEON_PROJECT_ID;
const snapshotId = process.env.NEON_SNAPSHOT_ID;
const targetBranchId = process.env.NEON_TARGET_BRANCH_ID;

if (!apiKey || !projectId || !snapshotId || !targetBranchId) {
  console.error(
    "Set NEON_API_KEY, NEON_PROJECT_ID, NEON_SNAPSHOT_ID, NEON_TARGET_BRANCH_ID.",
  );
  process.exit(1);
}

const api = createApiClient({ apiKey });
await applySnapshotToBranch(api, projectId, snapshotId, targetBranchId);
console.log(
  JSON.stringify(
    {
      ok: true,
      projectId,
      snapshotId,
      targetBranchId,
    },
    null,
    2,
  ),
);

/**
 * Create a logical snapshot on the default branch (same pattern as many agent hosts).
 */
import "dotenv/config";
import { createApiClient } from "@neondatabase/api-client";

import { createLogicalSnapshot } from "./utils.js";

const apiKey = process.env.NEON_API_KEY?.trim();
const projectId = process.env.NEON_PROJECT_ID;
const snapshotName = process.env.NEON_SNAPSHOT_NAME;
const expiresAt = process.env.NEON_SNAPSHOT_EXPIRES_AT?.trim();
const lsn = process.env.NEON_SNAPSHOT_LSN?.trim();

if (!apiKey) {
  console.error("NEON_API_KEY is required.");
  process.exit(1);
}

if (!projectId) {
  console.error("Set NEON_PROJECT_ID.");
  process.exit(1);
}

const api = createApiClient({ apiKey });
const snapshotId = await createLogicalSnapshot(api, projectId, {
  name: snapshotName || undefined,
  ...(expiresAt ? { expiresAt } : {}),
  ...(lsn ? { lsn } : {}),
});
console.log(JSON.stringify({ snapshotId, projectId }, null, 2));

/**
 * Transfer one or more projects from a source org to a destination org (e.g. free / sponsored → paid).
 * Personal API key with access to both orgs; see Neon docs on org project transfer.
 *
 * Projects with GitHub or Vercel integrations cannot be transferred; the API returns **422** in that case.
 * @see https://neon.com/docs/manage/orgs-project-transfer
 */
import "dotenv/config";
import { createApiClient } from "@neondatabase/api-client";

const apiKey = process.env.NEON_API_KEY?.trim();
const sourceOrgId = process.env.NEON_SOURCE_ORG_ID;
const destinationOrgId = process.env.NEON_DESTINATION_ORG_ID;
const rawIds =
  process.env.NEON_PROJECT_IDS || process.env.NEON_PROJECT_ID || "";

if (!apiKey || !sourceOrgId || !destinationOrgId || !rawIds.trim()) {
  console.error(
    "Set NEON_API_KEY, NEON_SOURCE_ORG_ID, NEON_DESTINATION_ORG_ID, and NEON_PROJECT_IDS (comma-separated) or NEON_PROJECT_ID.",
  );
  process.exit(1);
}

const projectIds = rawIds
  .split(",")
  .map((s: string) => s.trim())
  .filter(Boolean);

const api = createApiClient({ apiKey });
await api.transferProjectsFromOrgToOrg(sourceOrgId, {
  destination_org_id: destinationOrgId,
  project_ids: projectIds,
});
console.log(
  JSON.stringify(
    {
      ok: true,
      transferred: projectIds,
      sourceOrgId,
      destinationOrgId,
    },
    null,
    2,
  ),
);

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022"],
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "skipLibCheck": true,
    "noEmit": false,
    "outDir": "dist/scripts",
    "rootDir": ".",
    "sourceMap": false,
    "types": ["node"]
  },
  "include": ["**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

/**
 * Shared Neon Management API utilities (operation polling + common SDK call patterns).
 * Uses {@link createApiClient} types only; no alternate Neon packages.
 */
import type { Api } from "@neondatabase/api-client";
import {
  OperationStatus,
  type GeneralError,
  type Operation,
} from "@neondatabase/api-client";

export function formatNeonManagementError(err: unknown): Error {
  if (err && typeof err === "object" && "response" in err) {
    const data = (err as { response?: { data?: GeneralError } }).response?.data;
    if (data?.message) {
      const text = data.code ? `${data.code}: ${data.message}` : data.message;
      return new Error(text);
    }
  }
  if (err instanceof Error) return err;
  return new Error(String(err));
}

export function operationIdsFrom(ops: Operation[] | undefined): string[] {
  return (ops ?? [])
    .map((o) => o.id)
    .filter((id): id is string => typeof id === "string" && id.length > 0);
}

function isTerminalSuccess(status: string): boolean {
  return (
    status === OperationStatus.Finished ||
    status === OperationStatus.Skipped ||
    status === OperationStatus.Cancelled
  );
}

function isTerminalFailure(status: string): boolean {
  return status === OperationStatus.Failed || status === OperationStatus.Error;
}

export async function waitForOperationsToSettle(
  api: Api<unknown>,
  projectId: string,
  operationIds: string[],
  options: { pollIntervalMs?: number; timeoutMs?: number } = {},
): Promise<void> {
  const pollIntervalMs = options.pollIntervalMs ?? 2000;
  const timeoutMs = options.timeoutMs ?? 5 * 60 * 1000;

  for (const opId of operationIds) {
    const startedAt = Date.now();
    for (;;) {
      const { data } = await api.getProjectOperation(projectId, opId);
      const status = data.operation?.status;
      if (!status) throw new Error(`Operation status missing for ${opId}`);
      if (isTerminalFailure(status)) {
        throw new Error(`Operation ${opId} ended with status ${status}`);
      }
      if (isTerminalSuccess(status)) break;
      if (Date.now() - startedAt > timeoutMs) {
        throw new Error(
          `Timed out waiting for operation ${opId} (last status: ${status})`,
        );
      }
      await new Promise((r) => setTimeout(r, pollIntervalMs));
    }
  }
}

export async function getProductionBranchId(
  api: Api<unknown>,
  projectId: string,
): Promise<string | undefined> {
  const { data } = await api.listProjectBranches({ projectId });
  const branches = data.branches ?? [];
  const main = branches.find((b) => b.name === "main");
  const prod = branches.find((b) => b.name === "production");
  const chosen = main ?? prod;
  return typeof chosen?.id === "string" ? chosen.id : undefined;
}

export async function createProjectWithOperations(
  api: Api<unknown>,
  params: {
    name: string;
    orgId?: string;
    endpointSettings?: {
      autoscaling_limit_min_cu?: number;
      autoscaling_limit_max_cu?: number;
      suspend_timeout_seconds?: number;
    };
  },
): Promise<{ projectId: string; databaseUrl: string }> {
  const { data } = await api.createProject({
    project: {
      name: params.name,
      ...(params.orgId ? { org_id: params.orgId } : {}),
      ...(params.endpointSettings
        ? { default_endpoint_settings: params.endpointSettings }
        : {}),
    },
  });
  const projectId = data.project?.id;
  if (!projectId)
    throw new Error("Create project: missing project id in response");
  const databaseUrl = data.connection_uris?.[0]?.connection_uri;
  if (!databaseUrl) {
    throw new Error("Create project: missing connection URI in response");
  }
  const opIds = operationIdsFrom(data.operations);
  if (opIds.length > 0) {
    await waitForOperationsToSettle(api, projectId, opIds);
  }
  return { projectId, databaseUrl };
}

export async function createLogicalSnapshot(
  api: Api<unknown>,
  projectId: string,
  options: {
    branchId?: string;
    name?: string;
    timestamp?: string;
    lsn?: string;
    expiresAt?: string;
  },
): Promise<string> {
  let branchId = options.branchId;
  if (!branchId) {
    const prodId = await getProductionBranchId(api, projectId);
    if (!prodId) {
      throw new Error(
        "No production branch (expected name main or production)",
      );
    }
    branchId = prodId;
  }
  const base = {
    projectId,
    branchId,
    ...(options.name ? { name: options.name } : {}),
    ...(options.expiresAt ? { expires_at: options.expiresAt } : {}),
  };
  const { data } = await api.createSnapshot(
    options.lsn
      ? { ...base, lsn: options.lsn }
      : {
          ...base,
          timestamp: options.timestamp ?? new Date().toISOString(),
        },
  );
  const snapshotId = data.snapshot?.id;
  if (!snapshotId)
    throw new Error("Create snapshot: missing snapshot id in response");
  const opIds = operationIdsFrom(data.operations);
  if (opIds.length > 0) {
    await waitForOperationsToSettle(api, projectId, opIds);
  }
  return snapshotId;
}

export async function applySnapshotToBranch(
  api: Api<unknown>,
  projectId: string,
  snapshotId: string,
  targetBranchId: string,
  options: {
    restoreBranchName?: string;
    finalizeRestore?: boolean;
  } = {},
): Promise<void> {
  try {
    const { data } = await api.restoreSnapshot(
      { projectId, snapshotId },
      {
        name: options.restoreBranchName ?? `before_restore_${Date.now()}`,
        finalize_restore: options.finalizeRestore !== false,
        target_branch_id: targetBranchId,
      },
    );
    const opIds = operationIdsFrom(data.operations);
    if (opIds.length > 0) {
      await waitForOperationsToSettle(api, projectId, opIds);
    }
  } catch (e) {
    throw formatNeonManagementError(e);
  }
}

export async function restoreSnapshotAsNewBranch(
  api: Api<unknown>,
  projectId: string,
  snapshotId: string,
  newBranchName: string,
  finalizeRestore = false,
): Promise<string> {
  try {
    const { data } = await api.restoreSnapshot(
      { projectId, snapshotId },
      {
        name: newBranchName,
        finalize_restore: finalizeRestore,
      },
    );
    const opIds = operationIdsFrom(data.operations);
    if (opIds.length > 0) {
      await waitForOperationsToSettle(api, projectId, opIds);
    }
    const branchId = data.branch?.id;
    if (!branchId) {
      throw new Error(
        "restoreSnapshotAsNewBranch: missing branch id in response",
      );
    }
    return branchId;
  } catch (e) {
    throw formatNeonManagementError(e);
  }
}

export async function createBranchWithOperations(
  api: Api<unknown>,
  projectId: string,
  params: { name: string; parentId?: string },
): Promise<{ id: string }> {
  const { data } = await api.createProjectBranch(projectId, {
    branch: {
      name: params.name,
      ...(params.parentId ? { parent_id: params.parentId } : {}),
    },
  });
  const id = data.branch?.id;
  if (!id) throw new Error("Create branch: missing id in response");
  const opIds = operationIdsFrom(data.operations);
  if (opIds.length > 0) {
    await waitForOperationsToSettle(api, projectId, opIds);
  }
  return { id };
}

export async function deleteSnapshotWithWait(
  api: Api<unknown>,
  projectId: string,
  snapshotId: string,
): Promise<void> {
  const { data } = await api.deleteSnapshot(projectId, snapshotId);
  const opIds = operationIdsFrom(data.operations);
  if (opIds.length > 0) {
    await waitForOperationsToSettle(api, projectId, opIds);
  }
}

export async function deleteBranchWithWait(
  api: Api<unknown>,
  projectId: string,
  branchId: string,
): Promise<void> {
  const { data } = await api.deleteProjectBranch(projectId, branchId);
  const opIds = operationIdsFrom(data.operations);
  if (opIds.length > 0) {
    await waitForOperationsToSettle(api, projectId, opIds);
  }
}