@neondatabase/env 0.0.0 → 0.1.1

package/LICENSE.md

@@ -0,0 +1,178 @@
+# Apache License 2.0
+
+                                Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { runEnvRun } from "./lib/cli/commands.js";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+//#region src/cli.ts
+const pkgVersion = readPackageVersion();
+const argv = yargs(hideBin(process.argv)).scriptName("neon-env").usage("$0 run -- <command> [options]").parserConfiguration({ "populate--": true }).option("debug", {
+	type: "boolean",
+	default: false,
+	describe: "Print stack traces and structured error details when something fails"
+}).command("run", "Run a command with Neon env vars (from your neon.ts policy) injected into its environment. Use `--` to separate the command: `neon-env run -- npm run dev`.", (y) => y.option("config", {
+	type: "string",
+	describe: "Path to neon.ts (defaults to walking up from cwd)"
+}).option("project-id", {
+	type: "string",
+	describe: "Override the .neon/project.json projectId"
+}).option("branch", {
+	type: "string",
+	describe: "Override the .neon/project.json branchId / NEON_BRANCH_ID"
+}).option("api-key", {
+	type: "string",
+	describe: "Neon API key (defaults to NEON_API_KEY)"
+})).demandCommand(1, "Run `neon-env --help` to see the available commands.").strict().help().version(pkgVersion).parseSync();
+const command = String(argv._[0]);
+const cwd = process.cwd();
+let result;
+switch (command) {
+	case "run":
+		result = await runEnvRun({
+			command: Array.isArray(argv["--"]) ? argv["--"].map(String) : [],
+			...typeof argv.config === "string" ? { configPath: argv.config } : {},
+			...typeof argv["project-id"] === "string" ? { projectId: argv["project-id"] } : {},
+			...typeof argv.branch === "string" ? { branch: argv.branch } : {},
+			...typeof argv["api-key"] === "string" ? { apiKey: argv["api-key"] } : {}
+		}, { cwd });
+		break;
+	default: result = {
+		exitCode: 1,
+		stdout: "",
+		stderr: `Unknown command: ${command}\n`
+	};
+}
+if (result.stdout) process.stdout.write(result.stdout);
+if (result.stderr) process.stderr.write(result.stderr);
+if (argv.debug && result.exitCode !== 0 && result.debugInfo) process.stderr.write(`\n--- debug ---\n${result.debugInfo}\n`);
+process.exit(result.exitCode);
+function readPackageVersion() {
+	try {
+		const raw = readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf-8");
+		const parsed = JSON.parse(raw);
+		return typeof parsed.version === "string" ? parsed.version : "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
+}
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { readFileSync } from \"node:fs\";\nimport { fileURLToPath } from \"node:url\";\nimport yargs from \"yargs\";\nimport { hideBin } from \"yargs/helpers\";\nimport { type CommandResult, runEnvRun } from \"./lib/cli/commands.js\";\n\nconst pkgVersion = readPackageVersion();\n\nconst argv = yargs(hideBin(process.argv))\n\t.scriptName(\"neon-env\")\n\t.usage(\"$0 run -- <command> [options]\")\n\t.parserConfiguration({ \"populate--\": true })\n\t.option(\"debug\", {\n\t\ttype: \"boolean\",\n\t\tdefault: false,\n\t\tdescribe:\n\t\t\t\"Print stack traces and structured error details when something fails\",\n\t})\n\t.command(\n\t\t\"run\",\n\t\t\"Run a command with Neon env vars (from your neon.ts policy) injected into its environment. Use `--` to separate the command: `neon-env run -- npm run dev`.\",\n\t\t(y) =>\n\t\t\ty\n\t\t\t\t.option(\"config\", {\n\t\t\t\t\ttype: \"string\",\n\t\t\t\t\tdescribe:\n\t\t\t\t\t\t\"Path to neon.ts (defaults to walking up from cwd)\",\n\t\t\t\t})\n\t\t\t\t.option(\"project-id\", {\n\t\t\t\t\ttype: \"string\",\n\t\t\t\t\tdescribe: \"Override the .neon/project.json projectId\",\n\t\t\t\t})\n\t\t\t\t.option(\"branch\", {\n\t\t\t\t\ttype: \"string\",\n\t\t\t\t\tdescribe:\n\t\t\t\t\t\t\"Override the .neon/project.json branchId / NEON_BRANCH_ID\",\n\t\t\t\t})\n\t\t\t\t.option(\"api-key\", {\n\t\t\t\t\ttype: \"string\",\n\t\t\t\t\tdescribe: \"Neon API key (defaults to NEON_API_KEY)\",\n\t\t\t\t}),\n\t)\n\t.demandCommand(1, \"Run `neon-env --help` to see the available commands.\")\n\t.strict()\n\t.help()\n\t.version(pkgVersion)\n\t.parseSync();\n\nconst command = String(argv._[0]);\nconst cwd = process.cwd();\n\nlet result: CommandResult;\nswitch (command) {\n\tcase \"run\": {\n\t\tconst passthrough = Array.isArray(argv[\"--\"])\n\t\t\t? argv[\"--\"].map(String)\n\t\t\t: [];\n\t\tresult = await runEnvRun(\n\t\t\t{\n\t\t\t\tcommand: passthrough,\n\t\t\t\t...(typeof argv.config === \"string\"\n\t\t\t\t\t? { configPath: argv.config }\n\t\t\t\t\t: {}),\n\t\t\t\t...(typeof argv[\"project-id\"] === \"string\"\n\t\t\t\t\t? { projectId: argv[\"project-id\"] }\n\t\t\t\t\t: {}),\n\t\t\t\t...(typeof argv.branch === \"string\"\n\t\t\t\t\t? { branch: argv.branch }\n\t\t\t\t\t: {}),\n\t\t\t\t...(typeof argv[\"api-key\"] === \"string\"\n\t\t\t\t\t? { apiKey: argv[\"api-key\"] }\n\t\t\t\t\t: {}),\n\t\t\t},\n\t\t\t{ cwd },\n\t\t);\n\t\tbreak;\n\t}\n\tdefault:\n\t\tresult = {\n\t\t\texitCode: 1,\n\t\t\tstdout: \"\",\n\t\t\tstderr: `Unknown command: ${command}\\n`,\n\t\t};\n}\n\nif (result.stdout) process.stdout.write(result.stdout);\nif (result.stderr) process.stderr.write(result.stderr);\nif (argv.debug && result.exitCode !== 0 && result.debugInfo) {\n\tprocess.stderr.write(`\\n--- debug ---\\n${result.debugInfo}\\n`);\n}\nprocess.exit(result.exitCode);\n\nfunction readPackageVersion(): string {\n\t// The built CLI lives at `dist/cli.js`, so `package.json` is one directory up. When\n\t// running from source (tsx, vitest), the file lives at `src/cli.ts` and `package.json`\n\t// is again one directory up. Single resolution covers both layouts.\n\ttry {\n\t\tconst pkgUrl = new URL(\"../package.json\", import.meta.url);\n\t\tconst raw = readFileSync(fileURLToPath(pkgUrl), \"utf-8\");\n\t\tconst parsed = JSON.parse(raw) as { version?: unknown };\n\t\treturn typeof parsed.version === \"string\" ? parsed.version : \"0.0.0\";\n\t} catch {\n\t\treturn \"0.0.0\";\n\t}\n}\n"],"mappings":";;;;;;;AAQA,MAAM,aAAa,mBAAmB;AAEtC,MAAM,OAAO,MAAM,QAAQ,QAAQ,IAAI,CAAC,EACtC,WAAW,UAAU,EACrB,MAAM,+BAA+B,EACrC,oBAAoB,EAAE,cAAc,KAAK,CAAC,EAC1C,OAAO,SAAS;CAChB,MAAM;CACN,SAAS;CACT,UACC;AACF,CAAC,EACA,QACA,OACA,gKACC,MACA,EACE,OAAO,UAAU;CACjB,MAAM;CACN,UACC;AACF,CAAC,EACA,OAAO,cAAc;CACrB,MAAM;CACN,UAAU;AACX,CAAC,EACA,OAAO,UAAU;CACjB,MAAM;CACN,UACC;AACF,CAAC,EACA,OAAO,WAAW;CAClB,MAAM;CACN,UAAU;AACX,CAAC,CACJ,EACC,cAAc,GAAG,sDAAsD,EACvE,OAAO,EACP,KAAK,EACL,QAAQ,UAAU,EAClB,UAAU;AAEZ,MAAM,UAAU,OAAO,KAAK,EAAE,EAAE;AAChC,MAAM,MAAM,QAAQ,IAAI;AAExB,IAAI;AACJ,QAAQ,SAAR;CACC,KAAK;EAIJ,SAAS,MAAM,UACd;GACC,SALkB,MAAM,QAAQ,KAAK,KAAK,IACzC,KAAK,MAAM,IAAI,MAAM,IACrB,CAAC;GAIF,GAAI,OAAO,KAAK,WAAW,WACxB,EAAE,YAAY,KAAK,OAAO,IAC1B,CAAC;GACJ,GAAI,OAAO,KAAK,kBAAkB,WAC/B,EAAE,WAAW,KAAK,cAAc,IAChC,CAAC;GACJ,GAAI,OAAO,KAAK,WAAW,WACxB,EAAE,QAAQ,KAAK,OAAO,IACtB,CAAC;GACJ,GAAI,OAAO,KAAK,eAAe,WAC5B,EAAE,QAAQ,KAAK,WAAW,IAC1B,CAAC;EACL,GACA,EAAE,IAAI,CACP;EACA;CAED,SACC,SAAS;EACR,UAAU;EACV,QAAQ;EACR,QAAQ,oBAAoB,QAAQ;CACrC;AACF;AAEA,IAAI,OAAO,QAAQ,QAAQ,OAAO,MAAM,OAAO,MAAM;AACrD,IAAI,OAAO,QAAQ,QAAQ,OAAO,MAAM,OAAO,MAAM;AACrD,IAAI,KAAK,SAAS,OAAO,aAAa,KAAK,OAAO,WACjD,QAAQ,OAAO,MAAM,oBAAoB,OAAO,UAAU,GAAG;AAE9D,QAAQ,KAAK,OAAO,QAAQ;AAE5B,SAAS,qBAA6B;CAIrC,IAAI;EAEH,MAAM,MAAM,aAAa,cAAc,IADpB,IAAI,mBAAmB,OAAO,KAAK,GACV,CAAC,GAAG,OAAO;EACvD,MAAM,SAAS,KAAK,MAAM,GAAG;EAC7B,OAAO,OAAO,OAAO,YAAY,WAAW,OAAO,UAAU;CAC9D,QAAQ;EACP,OAAO;CACR;AACD"}

package/dist/config/dist/lib/neon-api.d.ts

@@ -0,0 +1,264 @@
+import { BucketAccessLevel, ComputeSettings, FunctionMemoryMib, FunctionRuntime } from "./types.js";
+
+//#region ../config/dist/lib/neon-api.d.ts
+
+//#region src/lib/neon-api.d.ts
+/**
+ * Snapshot of a Neon project field set we care about. Maps onto a subset of the upstream
+ * `@neondatabase/api-client` `Project` type. We do **not** widen this to the full upstream
+ * shape — keeping the surface narrow makes the in-memory fake practical to maintain.
+ */
+interface NeonProjectSnapshot {
+  id: string;
+  name: string;
+  regionId: string;
+  pgVersion: number;
+  orgId?: string;
+  defaultEndpointSettings?: ComputeSettings;
+}
+interface NeonBranchSnapshot {
+  id: string;
+  name: string;
+  parentId?: string;
+  isDefault: boolean;
+  /** Whether the branch is marked protected on Neon. */
+  protected: boolean;
+  expiresAt?: string;
+}
+interface NeonEndpointSnapshot {
+  id: string;
+  branchId: string;
+  type: "read_only" | "read_write";
+  autoscalingLimitMinCu: ComputeSettings["autoscalingLimitMinCu"];
+  autoscalingLimitMaxCu: ComputeSettings["autoscalingLimitMaxCu"];
+  suspendTimeout: ComputeSettings["suspendTimeout"];
+}
+interface CreateProjectInput {
+  name: string;
+  regionId: string;
+  pgVersion?: number;
+  orgId?: string;
+  defaultEndpointSettings?: ComputeSettings;
+  /**
+   * Optional name for the project's auto-created default branch. When omitted, Neon
+   * uses its own default (`main`).
+   */
+  defaultBranchName?: string;
+}
+interface CreateBranchInput {
+  name: string;
+  parentId?: string;
+  expiresAt?: string;
+  /** When `true`, the branch is created with the `protected` flag set on Neon. */
+  protected?: boolean;
+  computeSettings?: ComputeSettings;
+}
+interface UpdateBranchInput {
+  name?: string;
+  expiresAt?: string | null;
+  /** When set, toggles the branch's `protected` flag on Neon. */
+  protected?: boolean;
+}
+/**
+ * A role on a Neon branch (e.g. `neondb_owner`). Passwords are never returned by
+ * {@link NeonApi.listBranchRoles}; use {@link NeonApi.getConnectionUri} to fetch a URI
+ * with the role's password baked in.
+ */
+interface NeonRoleSnapshot {
+  name: string;
+  branchId: string;
+  /** Whether the role is system-protected (cannot be deleted). */
+  protected: boolean;
+}
+/**
+ * A database on a Neon branch (e.g. `neondb`).
+ */
+interface NeonDatabaseSnapshot {
+  name: string;
+  branchId: string;
+  /** The role that owns the database (one role can own multiple databases). */
+  ownerName: string;
+}
+/**
+ * Bits of a Neon Auth integration. The key fields are optional because the Neon API only
+ * includes them on create / rotate responses; `GET /auth` returns the public fields.
+ */
+interface NeonAuthSnapshot {
+  /** The Neon Auth project id (`auth_provider_project_id` on the Neon API). */
+  projectId: string;
+  /** Public client key (`pub_client_key`), only present on create / rotate responses. */
+  publishableClientKey?: string;
+  /** Secret server key (`secret_server_key`), only present on create / rotate responses. */
+  secretServerKey?: string;
+  /** JWKS URL for verifying tokens issued by Neon Auth. */
+  jwksUrl: string;
+  /** Optional base URL of the Neon Auth deployment. */
+  baseUrl?: string;
+}
+/**
+ * Public, fetchable bits of a Neon Data API integration on a specific branch.
+ */
+interface NeonDataApiSnapshot {
+  /** REST endpoint URL. */
+  url: string;
+}
+/**
+ * A branchable object-storage bucket (Preview). Backed by the Neon Platform
+ * branchable-storage service.
+ */
+interface NeonBucketSnapshot {
+  name: string;
+  accessLevel: BucketAccessLevel;
+}
+/**
+ * Input for creating a bucket on a branch.
+ */
+interface CreateBucketInput {
+  name: string;
+  accessLevel?: BucketAccessLevel;
+}
+/**
+ * A Neon Function on a branch (Preview). Mirrors the subset of the Functions API we model:
+ * the immutable `slug`, the display `name`, and the active deployment id when one exists.
+ */
+interface NeonFunctionSnapshot {
+  /** Opaque, stable function identifier. */
+  id: string;
+  /** Branch-unique slug (the invocation path segment). Immutable. */
+  slug: string;
+  /** Free-form display name. */
+  name: string;
+  /** URL at which the function is invoked. */
+  invocationUrl: string;
+  /** Id (platform version number) of the active deployment, when any code is deployed. */
+  activeDeploymentId?: number;
+}
+/**
+ * Input for deploying code to a function. `bundle` is the already-built ZIP archive of the
+ * function source — building it (esbuild + zip) is an imperative step performed by the
+ * caller, not by the {@link NeonApi} adapter.
+ */
+interface DeployFunctionInput {
+  bundle: Uint8Array;
+  runtime: FunctionRuntime;
+  memoryMib: FunctionMemoryMib;
+  environment: Record<string, string>;
+}
+/**
+ * A function deployment (Preview).
+ */
+interface NeonFunctionDeploymentSnapshot {
+  /** The deployment id (monotonic per function). */
+  id: number;
+  status: "pending" | "building" | "completed" | "failed";
+}
+/**
+ * Parameters accepted by {@link NeonApi.getConnectionUri}. `branchId` and `endpointId`
+ * are optional — when omitted, the API uses the project's default branch and that
+ * branch's read-write endpoint, respectively.
+ */
+interface GetConnectionUriInput {
+  branchId?: string;
+  endpointId?: string;
+  databaseName: string;
+  roleName: string;
+  /** When `true`, returns the pooled (PgBouncer) URI instead of the direct URI. */
+  pooled?: boolean;
+}
+/**
+ * Narrow façade over the Neon management API. `pullConfig`, `pushConfig`, and `fetchEnv`
+ * depend on this interface — *not* on `@neondatabase/api-client` directly — which lets us
+ * inject a real in-memory fake during tests without resorting to module mocks.
+ */
+interface NeonApi {
+  listProjects(filter: {
+    orgId?: string;
+  }): Promise<NeonProjectSnapshot[]>;
+  getProject(projectId: string): Promise<NeonProjectSnapshot>;
+  createProject(input: CreateProjectInput): Promise<NeonProjectSnapshot>;
+  updateProject(projectId: string, input: {
+    name?: string;
+    defaultEndpointSettings?: ComputeSettings;
+  }): Promise<NeonProjectSnapshot>;
+  listBranches(projectId: string): Promise<NeonBranchSnapshot[]>;
+  createBranch(projectId: string, input: CreateBranchInput): Promise<{
+    branch: NeonBranchSnapshot;
+    endpoints: NeonEndpointSnapshot[];
+  }>;
+  updateBranch(projectId: string, branchId: string, input: UpdateBranchInput): Promise<NeonBranchSnapshot>;
+  listEndpoints(projectId: string): Promise<NeonEndpointSnapshot[]>;
+  updateEndpoint(projectId: string, endpointId: string, settings: ComputeSettings): Promise<NeonEndpointSnapshot>;
+  /** List roles on a branch. Used by {@link fetchEnv} to auto-pick the role when only one exists. */
+  listBranchRoles(projectId: string, branchId: string): Promise<NeonRoleSnapshot[]>;
+  /** List databases on a branch. Used by {@link fetchEnv} to auto-pick the database when only one exists. */
+  listBranchDatabases(projectId: string, branchId: string): Promise<NeonDatabaseSnapshot[]>;
+  /**
+   * Fetch a Postgres connection URI for the given role + database on a branch.
+   * Returns the same string the Neon Console shows under "Connection Details".
+   */
+  getConnectionUri(projectId: string, input: GetConnectionUriInput): Promise<{
+    uri: string;
+  }>;
+  /**
+   * Fetch the Neon Auth integration attached to a specific branch. Returns `null` when
+   * no integration is enabled — used by `fetchEnv` to decide whether the `env.auth`
+   * namespace can be populated.
+   */
+  getNeonAuth(projectId: string, branchId: string): Promise<NeonAuthSnapshot | null>;
+  /**
+   * Enable the Neon Auth integration on a specific branch. Idempotent: if an integration
+   * is already enabled, the existing snapshot is returned unchanged. Used by
+   * `pushConfig` and `branch` to honour branch policy `auth: {}` / `auth.enabled: true`.
+   */
+  enableNeonAuth(projectId: string, branchId: string, input?: {
+    databaseName?: string;
+  }): Promise<NeonAuthSnapshot>;
+  /**
+   * Fetch the Neon Data API integration attached to a specific branch + database.
+   * Returns `null` when no integration is enabled — used by `fetchEnv` to decide
+   * whether the `env.dataApi` namespace can be populated.
+   */
+  getNeonDataApi(projectId: string, branchId: string, databaseName: string): Promise<NeonDataApiSnapshot | null>;
+  /**
+   * Enable the Neon Data API integration on a specific branch + database. Idempotent:
+   * if an integration is already enabled, the existing snapshot is returned unchanged.
+   * Used by `pushConfig` and `branch` to honour branch policy `dataApi: {}` / `dataApi.enabled: true`.
+   */
+  enableProjectBranchDataApi(projectId: string, branchId: string, databaseName: string): Promise<NeonDataApiSnapshot>;
+  /** List branchable object-storage buckets visible on a branch. */
+  listBranchBuckets(projectId: string, branchId: string): Promise<NeonBucketSnapshot[]>;
+  /** Create a bucket on a branch. Used by `pushConfig` to honour `preview.buckets`. */
+  createBranchBucket(projectId: string, branchId: string, input: CreateBucketInput): Promise<NeonBucketSnapshot>;
+  /** Delete a bucket from a branch. */
+  deleteBranchBucket(projectId: string, branchId: string, bucketName: string): Promise<void>;
+  /** List functions on a branch. */
+  listBranchFunctions(projectId: string, branchId: string): Promise<NeonFunctionSnapshot[]>;
+  /**
+   * Create a function on a branch. The function has no deployment until code is deployed
+   * to it with {@link deployBranchFunction}.
+   */
+  createBranchFunction(projectId: string, branchId: string, input: {
+    slug: string;
+    name: string;
+  }): Promise<NeonFunctionSnapshot>;
+  /** Delete a function (by slug) from a branch. */
+  deleteBranchFunction(projectId: string, branchId: string, slug: string): Promise<void>;
+  /**
+   * Deploy a built bundle to a function. The newest deployment becomes active. The
+   * `bundle` is built (esbuild + zip) by the caller and passed in as bytes.
+   */
+  deployBranchFunction(projectId: string, branchId: string, slug: string, input: DeployFunctionInput): Promise<NeonFunctionDeploymentSnapshot>;
+  /**
+   * Whether the AI Gateway is enabled on a branch. Toggle-style, like Neon Auth / Data
+   * API: used by both `fetchEnv` (to decide visibility) and `pushConfig` (to diff intent).
+   */
+  getAiGatewayEnabled(projectId: string, branchId: string): Promise<boolean>;
+  /** Enable the AI Gateway on a branch. Idempotent. */
+  enableAiGateway(projectId: string, branchId: string): Promise<void>;
+  /** Disable the AI Gateway on a branch. Idempotent. */
+  disableAiGateway(projectId: string, branchId: string): Promise<void>;
+}
+//#endregion
+//#endregion
+export { CreateBranchInput, CreateBucketInput, CreateProjectInput, DeployFunctionInput, GetConnectionUriInput, NeonApi, NeonAuthSnapshot, NeonBranchSnapshot, NeonBucketSnapshot, NeonDataApiSnapshot, NeonDatabaseSnapshot, NeonEndpointSnapshot, NeonFunctionDeploymentSnapshot, NeonFunctionSnapshot, NeonProjectSnapshot, NeonRoleSnapshot, UpdateBranchInput };
+//# sourceMappingURL=neon-api.d.ts.map

package/dist/config/dist/lib/neon-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"neon-api.d.ts","names":["BucketAccessLevel","ComputeSettings","FunctionMemoryMib","FunctionRuntime","NeonProjectSnapshot","NeonBranchSnapshot","NeonEndpointSnapshot","CreateProjectInput","CreateBranchInput","UpdateBranchInput","NeonRoleSnapshot","NeonDatabaseSnapshot","NeonAuthSnapshot","NeonDataApiSnapshot","NeonBucketSnapshot","CreateBucketInput","NeonFunctionSnapshot","DeployFunctionInput","Uint8Array","Record","NeonFunctionDeploymentSnapshot","GetConnectionUriInput","NeonApi","Promise"],"sources":["../../../../../config/dist/lib/neon-api.d.ts"],"sourcesContent":["import { BucketAccessLevel, ComputeSettings, FunctionMemoryMib, FunctionRuntime } from \"./types.js\";\n\n//#region src/lib/neon-api.d.ts\n\n/**\n * Snapshot of a Neon project field set we care about. Maps onto a subset of the upstream\n * `@neondatabase/api-client` `Project` type. We do **not** widen this to the full upstream\n * shape — keeping the surface narrow makes the in-memory fake practical to maintain.\n */\ninterface NeonProjectSnapshot {\n  id: string;\n  name: string;\n  regionId: string;\n  pgVersion: number;\n  orgId?: string;\n  defaultEndpointSettings?: ComputeSettings;\n}\ninterface NeonBranchSnapshot {\n  id: string;\n  name: string;\n  parentId?: string;\n  isDefault: boolean;\n  /** Whether the branch is marked protected on Neon. */\n  protected: boolean;\n  expiresAt?: string;\n}\ninterface NeonEndpointSnapshot {\n  id: string;\n  branchId: string;\n  type: \"read_only\" | \"read_write\";\n  autoscalingLimitMinCu: ComputeSettings[\"autoscalingLimitMinCu\"];\n  autoscalingLimitMaxCu: ComputeSettings[\"autoscalingLimitMaxCu\"];\n  suspendTimeout: ComputeSettings[\"suspendTimeout\"];\n}\ninterface CreateProjectInput {\n  name: string;\n  regionId: string;\n  pgVersion?: number;\n  orgId?: string;\n  defaultEndpointSettings?: ComputeSettings;\n  /**\n   * Optional name for the project's auto-created default branch. When omitted, Neon\n   * uses its own default (`main`).\n   */\n  defaultBranchName?: string;\n}\ninterface CreateBranchInput {\n  name: string;\n  parentId?: string;\n  expiresAt?: string;\n  /** When `true`, the branch is created with the `protected` flag set on Neon. */\n  protected?: boolean;\n  computeSettings?: ComputeSettings;\n}\ninterface UpdateBranchInput {\n  name?: string;\n  expiresAt?: string | null;\n  /** When set, toggles the branch's `protected` flag on Neon. */\n  protected?: boolean;\n}\n/**\n * A role on a Neon branch (e.g. `neondb_owner`). Passwords are never returned by\n * {@link NeonApi.listBranchRoles}; use {@link NeonApi.getConnectionUri} to fetch a URI\n * with the role's password baked in.\n */\ninterface NeonRoleSnapshot {\n  name: string;\n  branchId: string;\n  /** Whether the role is system-protected (cannot be deleted). */\n  protected: boolean;\n}\n/**\n * A database on a Neon branch (e.g. `neondb`).\n */\ninterface NeonDatabaseSnapshot {\n  name: string;\n  branchId: string;\n  /** The role that owns the database (one role can own multiple databases). */\n  ownerName: string;\n}\n/**\n * Bits of a Neon Auth integration. The key fields are optional because the Neon API only\n * includes them on create / rotate responses; `GET /auth` returns the public fields.\n */\ninterface NeonAuthSnapshot {\n  /** The Neon Auth project id (`auth_provider_project_id` on the Neon API). */\n  projectId: string;\n  /** Public client key (`pub_client_key`), only present on create / rotate responses. */\n  publishableClientKey?: string;\n  /** Secret server key (`secret_server_key`), only present on create / rotate responses. */\n  secretServerKey?: string;\n  /** JWKS URL for verifying tokens issued by Neon Auth. */\n  jwksUrl: string;\n  /** Optional base URL of the Neon Auth deployment. */\n  baseUrl?: string;\n}\n/**\n * Public, fetchable bits of a Neon Data API integration on a specific branch.\n */\ninterface NeonDataApiSnapshot {\n  /** REST endpoint URL. */\n  url: string;\n}\n/**\n * A branchable object-storage bucket (Preview). Backed by the Neon Platform\n * branchable-storage service.\n */\ninterface NeonBucketSnapshot {\n  name: string;\n  accessLevel: BucketAccessLevel;\n}\n/**\n * Input for creating a bucket on a branch.\n */\ninterface CreateBucketInput {\n  name: string;\n  accessLevel?: BucketAccessLevel;\n}\n/**\n * A Neon Function on a branch (Preview). Mirrors the subset of the Functions API we model:\n * the immutable `slug`, the display `name`, and the active deployment id when one exists.\n */\ninterface NeonFunctionSnapshot {\n  /** Opaque, stable function identifier. */\n  id: string;\n  /** Branch-unique slug (the invocation path segment). Immutable. */\n  slug: string;\n  /** Free-form display name. */\n  name: string;\n  /** URL at which the function is invoked. */\n  invocationUrl: string;\n  /** Id (platform version number) of the active deployment, when any code is deployed. */\n  activeDeploymentId?: number;\n}\n/**\n * Input for deploying code to a function. `bundle` is the already-built ZIP archive of the\n * function source — building it (esbuild + zip) is an imperative step performed by the\n * caller, not by the {@link NeonApi} adapter.\n */\ninterface DeployFunctionInput {\n  bundle: Uint8Array;\n  runtime: FunctionRuntime;\n  memoryMib: FunctionMemoryMib;\n  environment: Record<string, string>;\n}\n/**\n * A function deployment (Preview).\n */\ninterface NeonFunctionDeploymentSnapshot {\n  /** The deployment id (monotonic per function). */\n  id: number;\n  status: \"pending\" | \"building\" | \"completed\" | \"failed\";\n}\n/**\n * Parameters accepted by {@link NeonApi.getConnectionUri}. `branchId` and `endpointId`\n * are optional — when omitted, the API uses the project's default branch and that\n * branch's read-write endpoint, respectively.\n */\ninterface GetConnectionUriInput {\n  branchId?: string;\n  endpointId?: string;\n  databaseName: string;\n  roleName: string;\n  /** When `true`, returns the pooled (PgBouncer) URI instead of the direct URI. */\n  pooled?: boolean;\n}\n/**\n * Narrow façade over the Neon management API. `pullConfig`, `pushConfig`, and `fetchEnv`\n * depend on this interface — *not* on `@neondatabase/api-client` directly — which lets us\n * inject a real in-memory fake during tests without resorting to module mocks.\n */\ninterface NeonApi {\n  listProjects(filter: {\n    orgId?: string;\n  }): Promise<NeonProjectSnapshot[]>;\n  getProject(projectId: string): Promise<NeonProjectSnapshot>;\n  createProject(input: CreateProjectInput): Promise<NeonProjectSnapshot>;\n  updateProject(projectId: string, input: {\n    name?: string;\n    defaultEndpointSettings?: ComputeSettings;\n  }): Promise<NeonProjectSnapshot>;\n  listBranches(projectId: string): Promise<NeonBranchSnapshot[]>;\n  createBranch(projectId: string, input: CreateBranchInput): Promise<{\n    branch: NeonBranchSnapshot;\n    endpoints: NeonEndpointSnapshot[];\n  }>;\n  updateBranch(projectId: string, branchId: string, input: UpdateBranchInput): Promise<NeonBranchSnapshot>;\n  listEndpoints(projectId: string): Promise<NeonEndpointSnapshot[]>;\n  updateEndpoint(projectId: string, endpointId: string, settings: ComputeSettings): Promise<NeonEndpointSnapshot>;\n  /** List roles on a branch. Used by {@link fetchEnv} to auto-pick the role when only one exists. */\n  listBranchRoles(projectId: string, branchId: string): Promise<NeonRoleSnapshot[]>;\n  /** List databases on a branch. Used by {@link fetchEnv} to auto-pick the database when only one exists. */\n  listBranchDatabases(projectId: string, branchId: string): Promise<NeonDatabaseSnapshot[]>;\n  /**\n   * Fetch a Postgres connection URI for the given role + database on a branch.\n   * Returns the same string the Neon Console shows under \"Connection Details\".\n   */\n  getConnectionUri(projectId: string, input: GetConnectionUriInput): Promise<{\n    uri: string;\n  }>;\n  /**\n   * Fetch the Neon Auth integration attached to a specific branch. Returns `null` when\n   * no integration is enabled — used by `fetchEnv` to decide whether the `env.auth`\n   * namespace can be populated.\n   */\n  getNeonAuth(projectId: string, branchId: string): Promise<NeonAuthSnapshot | null>;\n  /**\n   * Enable the Neon Auth integration on a specific branch. Idempotent: if an integration\n   * is already enabled, the existing snapshot is returned unchanged. Used by\n   * `pushConfig` and `branch` to honour branch policy `auth: {}` / `auth.enabled: true`.\n   */\n  enableNeonAuth(projectId: string, branchId: string, input?: {\n    databaseName?: string;\n  }): Promise<NeonAuthSnapshot>;\n  /**\n   * Fetch the Neon Data API integration attached to a specific branch + database.\n   * Returns `null` when no integration is enabled — used by `fetchEnv` to decide\n   * whether the `env.dataApi` namespace can be populated.\n   */\n  getNeonDataApi(projectId: string, branchId: string, databaseName: string): Promise<NeonDataApiSnapshot | null>;\n  /**\n   * Enable the Neon Data API integration on a specific branch + database. Idempotent:\n   * if an integration is already enabled, the existing snapshot is returned unchanged.\n   * Used by `pushConfig` and `branch` to honour branch policy `dataApi: {}` / `dataApi.enabled: true`.\n   */\n  enableProjectBranchDataApi(projectId: string, branchId: string, databaseName: string): Promise<NeonDataApiSnapshot>;\n  /** List branchable object-storage buckets visible on a branch. */\n  listBranchBuckets(projectId: string, branchId: string): Promise<NeonBucketSnapshot[]>;\n  /** Create a bucket on a branch. Used by `pushConfig` to honour `preview.buckets`. */\n  createBranchBucket(projectId: string, branchId: string, input: CreateBucketInput): Promise<NeonBucketSnapshot>;\n  /** Delete a bucket from a branch. */\n  deleteBranchBucket(projectId: string, branchId: string, bucketName: string): Promise<void>;\n  /** List functions on a branch. */\n  listBranchFunctions(projectId: string, branchId: string): Promise<NeonFunctionSnapshot[]>;\n  /**\n   * Create a function on a branch. The function has no deployment until code is deployed\n   * to it with {@link deployBranchFunction}.\n   */\n  createBranchFunction(projectId: string, branchId: string, input: {\n    slug: string;\n    name: string;\n  }): Promise<NeonFunctionSnapshot>;\n  /** Delete a function (by slug) from a branch. */\n  deleteBranchFunction(projectId: string, branchId: string, slug: string): Promise<void>;\n  /**\n   * Deploy a built bundle to a function. The newest deployment becomes active. The\n   * `bundle` is built (esbuild + zip) by the caller and passed in as bytes.\n   */\n  deployBranchFunction(projectId: string, branchId: string, slug: string, input: DeployFunctionInput): Promise<NeonFunctionDeploymentSnapshot>;\n  /**\n   * Whether the AI Gateway is enabled on a branch. Toggle-style, like Neon Auth / Data\n   * API: used by both `fetchEnv` (to decide visibility) and `pushConfig` (to diff intent).\n   */\n  getAiGatewayEnabled(projectId: string, branchId: string): Promise<boolean>;\n  /** Enable the AI Gateway on a branch. Idempotent. */\n  enableAiGateway(projectId: string, branchId: string): Promise<void>;\n  /** Disable the AI Gateway on a branch. Idempotent. */\n  disableAiGateway(projectId: string, branchId: string): Promise<void>;\n}\n//#endregion\nexport { CreateBranchInput, CreateBucketInput, CreateProjectInput, DeployFunctionInput, GetConnectionUriInput, NeonApi, NeonAuthSnapshot, NeonBranchSnapshot, NeonBucketSnapshot, NeonDataApiSnapshot, NeonDatabaseSnapshot, NeonEndpointSnapshot, NeonFunctionDeploymentSnapshot, NeonFunctionSnapshot, NeonProjectSnapshot, NeonRoleSnapshot, UpdateBranchInput };\n//# sourceMappingURL=neon-api.d.ts.map"],"mappings":";;;;;AAe2C;AAEf;;;;UARlBI,mBAAAA,CAuBQH;EAAe,EAAA,EAAA,MAAA;EAAA,IAEvBM,EAAAA,MAAAA;EAKiC,QAOjCC,EAAAA,MAAAA;EAMyB,SAEzBC,EAAAA,MAAAA;EAAiB,KAWjBC,CAAAA,EAAAA,MAAAA;EAAgB,uBAShBC,CAAAA,EA3DkBV,eA2DE;AAAA;AAUJ,UAnEhBI,kBAAAA,CAkFmB;EAAA,EAQnBS,EAAAA,MAAAA;EAEsB,IAKtBC,EAAAA,MAAAA;EAEuB,QAMvBC,CAAAA,EAAAA,MAAAA;EAAoB,SAiBpBC,EAAAA,OAAAA;EAAmB;WACnBC,EAAAA,OAAAA;WACCf,CAAAA,EAAAA,MAAAA;;UAnHDG,oBAAAA,CAqHKa;EAAM,EAAA,EAAA,MAAA;EAAA,QAKXC,EAAAA,MAAAA;EAA8B,IAU9BC,EAAAA,WAAAA,GAAAA,YAAqB;EAAA,qBAad,EA7IQpB,eA6IR,CAAA,uBAAA,CAAA;EAAA,qBAAA,EA5IQA,eA4IR,CAAA,uBAAA,CAAA;gBAGHG,EA9IIH,eA8IJG,CAAAA,gBAAAA,CAAAA;;UA5IJG,kBAAAA,CA6I+BH;QAARmB,MAAAA;UACVhB,EAAAA,MAAAA;WAA6BH,CAAAA,EAAAA,MAAAA;OAARmB,CAAAA,EAAAA,MAAAA;yBAGdtB,CAAAA,EA5IFA,eA4IEA;;;;;mBAGWO,CAAAA,EAAAA,MAAAA;;UAxI/BA,iBAAAA,CA0IKF;QAF8CiB,MAAAA;UAIFd,CAAAA,EAAAA,MAAAA;WAA4BJ,CAAAA,EAAAA,MAAAA;;WAC3CC,CAAAA,EAAAA,OAAAA;iBAARiB,CAAAA,EAvIhBtB,eAuIgBsB;;UArI1Bd,iBAAAA,CAsIkFH;OAARiB,EAAAA,MAAAA;WAEpBb,CAAAA,EAAAA,MAAAA,GAAAA,IAAAA;;WAEIC,CAAAA,EAAAA,OAAAA;;;;;;;UA/H1DD,gBAAAA,CAoJJa;QAM+EV,MAAAA;UAARU,EAAAA,MAAAA;;WAMYA,EAAAA,OAAAA;;;;;UAvJ/EZ,oBAAAA,CA2J2EY;QAENA,MAAAA;UAEXP,EAAAA,MAAAA;;WAQtDA,EAAAA,MAAAA;;;;;;UA7JJJ,gBAAAA,CAyKkDW;;WAIHA,EAAAA,MAAAA;EAAO;;;;;;;;;;;;UA9JtDV,mBAAAA;;;;;;;;UAQAC,kBAAAA;;eAEKd;;;;;UAKLe,iBAAAA;;gBAEMf;;;;;;UAMNgB,oBAAAA;;;;;;;;;;;;;;;;;UAiBAC,mBAAAA;UACAC;WACCf;aACED;eACEiB;;;;;UAKLC,8BAAAA;;;;;;;;;;UAUAC,qBAAAA;;;;;;;;;;;;;UAaAC,OAAAA;;;MAGJC,QAAQnB;iCACmBmB,QAAQnB;uBAClBG,qBAAqBgB,QAAQnB;;;8BAGtBH;MACxBsB,QAAQnB;mCACqBmB,QAAQlB;yCACFG,oBAAoBe;YACjDlB;eACGC;;2DAE4CG,oBAAoBc,QAAQlB;oCACnDkB,QAAQjB;kEACsBL,kBAAkBsB,QAAQjB;;wDAEpCiB,QAAQb;;4DAEJa,QAAQZ;;;;;6CAKvBU,wBAAwBE;;;;;;;;oDAQjBA,QAAQX;;;;;;;;MAQtDW,QAAQX;;;;;;6EAM+DW,QAAQV;;;;;;yFAMIU,QAAQV;;0DAEvCU,QAAQT;;iEAEDC,oBAAoBQ,QAAQT;;+EAEdS;;4DAEnBA,QAAQP;;;;;;;;MAQ9DO,QAAQP;;2EAE6DO;;;;;iFAKMN,sBAAsBM,QAAQH;;;;;4DAKnDG;;wDAEJA;;yDAECA"}