@neon/config 0.14.0 → 1.0.0

package/dist/lib/wrap-neon-error.js

@@ -33,7 +33,7 @@ function wrapNeonError(err, context) {
 		case 401: return new PlatformError(ErrorCode.Unauthorized, [
 			`${context.op} failed: the Bearer token sent to the Neon API was rejected.`,
 			apiSummaryWithRequestId,
-			"Either (a) generate or rotate an API key at https://console.neon.tech/app/settings/api-keys and set NEON_API_KEY / pass --api-key, or (b) re-run `npx neonctl auth` to refresh the OAuth token in `~/.config/neonctl/credentials.json` (OAuth tokens expire)."
+			"Either (a) generate or rotate an API key at https://console.neon.tech/app/settings/api-keys and set NEON_API_KEY / pass --api-key, or (b) re-run `npx neon auth` to refresh the OAuth token in `~/.config/neonctl/credentials.json` (OAuth tokens expire)."
 		].join(" "), {
 			cause: err,
 			details: httpDetails(context, httpInfo)

package/dist/lib/wrap-neon-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"wrap-neon-error.js","names":[],"sources":["../../src/lib/wrap-neon-error.ts"],"sourcesContent":["import { ErrorCode, PlatformError } from \"./errors.js\";\n\n/**\n * Context the wrapper attaches to every PlatformError so consumers can debug without\n * digging into the raw axios stack.\n */\nexport interface NeonErrorContext {\n\t/** Short label of the operation that failed, e.g. `getProject(proj-foo)` or `createBranch`. */\n\top: string;\n\t/** Optional project id when the operation is project-scoped. */\n\tprojectId?: string;\n}\n\n/**\n * Turn a raw error from `@neondatabase/api-client` (axios under the hood) into a typed\n * {@link PlatformError} whose message includes:\n *\n * 1. What operation was attempted (`op`, e.g. `getProject(proj-foo)`).\n * 2. Why it failed in human terms (e.g. \"API key is unauthorized\").\n * 3. The exact Neon API error message + request id (when present) for support tickets.\n * 4. A concrete next action (\"Generate a new key at …\", \"Pass `projectId`\", …).\n *\n * Non-axios errors are passed through unchanged (a regular `Error` already has a useful\n * stack trace; wrapping it would lose information without adding value).\n */\nexport function wrapNeonError(\n\terr: unknown,\n\tcontext: NeonErrorContext,\n): PlatformError | unknown {\n\tif (err instanceof PlatformError) return err;\n\tconst httpInfo = extractHttpInfo(err);\n\tif (!httpInfo) {\n\t\tconst networkInfo = extractNetworkInfo(err);\n\t\tif (networkInfo) {\n\t\t\treturn new PlatformError(\n\t\t\t\tErrorCode.NetworkError,\n\t\t\t\t`Could not reach the Neon API while running ${context.op}: ${networkInfo.message}. Check your network connection and that https://console.neon.tech is reachable.`,\n\t\t\t\t{ cause: err, details: { op: context.op, ...networkInfo } },\n\t\t\t);\n\t\t}\n\t\treturn err;\n\t}\n\n\tconst apiSummary = httpInfo.neonMessage\n\t\t? `Neon API said: \"${httpInfo.neonMessage}\"`\n\t\t: `HTTP ${httpInfo.status}`;\n\tconst requestIdSuffix = httpInfo.requestId\n\t\t? ` (request id ${httpInfo.requestId})`\n\t\t: \"\";\n\tconst apiSummaryWithRequestId = `${apiSummary}${requestIdSuffix}.`;\n\n\tswitch (httpInfo.status) {\n\t\tcase 401:\n\t\t\treturn new PlatformError(\n\t\t\t\tErrorCode.Unauthorized,\n\t\t\t\t[\n\t\t\t\t\t`${context.op} failed: the Bearer token sent to the Neon API was rejected.`,\n\t\t\t\t\tapiSummaryWithRequestId,\n\t\t\t\t\t\"Either (a) generate or rotate an API key at https://console.neon.tech/app/settings/api-keys and set NEON_API_KEY / pass --api-key, or (b) re-run `npx neonctl auth` to refresh the OAuth token in `~/.config/neonctl/credentials.json` (OAuth tokens expire).\",\n\t\t\t\t].join(\" \"),\n\t\t\t\t{ cause: err, details: httpDetails(context, httpInfo) },\n\t\t\t);\n\t\tcase 403:\n\t\t\treturn new PlatformError(\n\t\t\t\tErrorCode.Forbidden,\n\t\t\t\t[\n\t\t\t\t\t`${context.op} failed: this API key is not allowed to perform that operation.`,\n\t\t\t\t\tapiSummaryWithRequestId,\n\t\t\t\t\t\"Project-scoped keys can only operate on their own project; switch to an organisation/user-scoped key or pass `projectId` for an operation that doesn't need listing.\",\n\t\t\t\t].join(\" \"),\n\t\t\t\t{ cause: err, details: httpDetails(context, httpInfo) },\n\t\t\t);\n\t\tcase 404:\n\t\t\treturn new PlatformError(\n\t\t\t\tErrorCode.NotFound,\n\t\t\t\t[\n\t\t\t\t\t`${context.op} failed: resource not found on Neon.`,\n\t\t\t\t\tapiSummaryWithRequestId,\n\t\t\t\t\tcontext.projectId\n\t\t\t\t\t\t? `Verify that project '${context.projectId}' exists in this account and that the API key has access to it.`\n\t\t\t\t\t\t: \"Verify that the resource id is correct and that the API key has access to it.\",\n\t\t\t\t].join(\" \"),\n\t\t\t\t{ cause: err, details: httpDetails(context, httpInfo) },\n\t\t\t);\n\t\tcase 409:\n\t\t\treturn new PlatformError(\n\t\t\t\tErrorCode.Conflict,\n\t\t\t\t[\n\t\t\t\t\t`${context.op} failed: a conflicting resource already exists on Neon.`,\n\t\t\t\t\tapiSummaryWithRequestId,\n\t\t\t\t\t\"This is often a name collision (e.g. a branch with the same name already exists). Pull first to compare against the remote, or rename in your `neon.ts`.\",\n\t\t\t\t].join(\" \"),\n\t\t\t\t{ cause: err, details: httpDetails(context, httpInfo) },\n\t\t\t);\n\t\tcase 423:\n\t\t\treturn new PlatformError(\n\t\t\t\tErrorCode.Locked,\n\t\t\t\t[\n\t\t\t\t\t`${context.op} failed: the resource is still being modified by a previous operation, and our built-in retries did not drain it in time.`,\n\t\t\t\t\tapiSummaryWithRequestId,\n\t\t\t\t\t\"Wait a few seconds and re-run, or raise `retryOnLocked.maxAttempts` when constructing the real Neon adapter.\",\n\t\t\t\t].join(\" \"),\n\t\t\t\t{ cause: err, details: httpDetails(context, httpInfo) },\n\t\t\t);\n\t\tcase 429:\n\t\t\treturn new PlatformError(\n\t\t\t\tErrorCode.RateLimited,\n\t\t\t\t[\n\t\t\t\t\t`${context.op} failed: rate-limited by the Neon API.`,\n\t\t\t\t\tapiSummaryWithRequestId,\n\t\t\t\t\t\"Back off and retry; if this happens repeatedly, contact Neon support with the request id above.\",\n\t\t\t\t].join(\" \"),\n\t\t\t\t{ cause: err, details: httpDetails(context, httpInfo) },\n\t\t\t);\n\t}\n\n\tif (httpInfo.status >= 500) {\n\t\treturn new PlatformError(\n\t\t\tErrorCode.ServerError,\n\t\t\t[\n\t\t\t\t`${context.op} failed: the Neon API returned a server error (HTTP ${httpInfo.status}).`,\n\t\t\t\tapiSummaryWithRequestId,\n\t\t\t\t\"This is most likely transient. Retry shortly; if it persists, file an issue with the request id above and check https://neonstatus.com.\",\n\t\t\t].join(\" \"),\n\t\t\t{ cause: err, details: httpDetails(context, httpInfo) },\n\t\t);\n\t}\n\n\t// 4xx we don't have a dedicated code for. Surface what we know.\n\treturn new PlatformError(\n\t\tErrorCode.ServerError,\n\t\t`${context.op} failed: HTTP ${httpInfo.status}. ${apiSummary}${requestIdSuffix}.`,\n\t\t{ cause: err, details: httpDetails(context, httpInfo) },\n\t);\n}\n\ninterface HttpInfo {\n\tstatus: number;\n\tneonMessage?: string;\n\tneonCode?: string;\n\trequestId?: string;\n}\n\nfunction extractHttpInfo(err: unknown): HttpInfo | null {\n\tif (err === null || typeof err !== \"object\") return null;\n\tconst response = (err as { response?: unknown }).response;\n\tif (response === null || typeof response !== \"object\") return null;\n\tconst status = (response as { status?: unknown }).status;\n\tif (typeof status !== \"number\") return null;\n\tconst data = (response as { data?: unknown }).data;\n\tconst out: HttpInfo = { status };\n\tif (data !== null && typeof data === \"object\") {\n\t\tconst dataObj = data as Record<string, unknown>;\n\t\tif (typeof dataObj.message === \"string\" && dataObj.message !== \"\")\n\t\t\tout.neonMessage = dataObj.message;\n\t\tif (typeof dataObj.code === \"string\" && dataObj.code !== \"\")\n\t\t\tout.neonCode = dataObj.code;\n\t\tif (typeof dataObj.request_id === \"string\" && dataObj.request_id !== \"\")\n\t\t\tout.requestId = dataObj.request_id;\n\t}\n\treturn out;\n}\n\ninterface NetworkInfo {\n\tmessage: string;\n\tcode?: string;\n}\n\nfunction extractNetworkInfo(err: unknown): NetworkInfo | null {\n\tif (err === null || typeof err !== \"object\") return null;\n\tconst code = (err as { code?: unknown }).code;\n\tconst message = (err as { message?: unknown }).message;\n\tif (\n\t\ttypeof code === \"string\" &&\n\t\t/^(ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|EPIPE|EHOSTUNREACH|ENETUNREACH)$/.test(\n\t\t\tcode,\n\t\t)\n\t) {\n\t\treturn { message: typeof message === \"string\" ? message : code, code };\n\t}\n\t// axios timeout reports `code: \"ECONNABORTED\"`.\n\tif (code === \"ECONNABORTED\") {\n\t\treturn {\n\t\t\tmessage: typeof message === \"string\" ? message : \"timeout\",\n\t\t\tcode,\n\t\t};\n\t}\n\treturn null;\n}\n\nfunction httpDetails(\n\tcontext: NeonErrorContext,\n\tinfo: HttpInfo,\n): Record<string, unknown> {\n\tconst out: Record<string, unknown> = {\n\t\top: context.op,\n\t\tstatus: info.status,\n\t};\n\tif (context.projectId) out.projectId = context.projectId;\n\tif (info.neonMessage) out.neonMessage = info.neonMessage;\n\tif (info.neonCode) out.neonCode = info.neonCode;\n\tif (info.requestId) out.requestId = info.requestId;\n\treturn out;\n}\n"],"mappings":"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"}
+{"version":3,"file":"wrap-neon-error.js","names":[],"sources":["../../src/lib/wrap-neon-error.ts"],"sourcesContent":["import { ErrorCode, PlatformError } from \"./errors.js\";\n\n/**\n * Context the wrapper attaches to every PlatformError so consumers can debug without\n * digging into the raw axios stack.\n */\nexport interface NeonErrorContext {\n\t/** Short label of the operation that failed, e.g. `getProject(proj-foo)` or `createBranch`. */\n\top: string;\n\t/** Optional project id when the operation is project-scoped. */\n\tprojectId?: string;\n}\n\n/**\n * Turn a raw error from `@neondatabase/api-client` (axios under the hood) into a typed\n * {@link PlatformError} whose message includes:\n *\n * 1. What operation was attempted (`op`, e.g. `getProject(proj-foo)`).\n * 2. Why it failed in human terms (e.g. \"API key is unauthorized\").\n * 3. The exact Neon API error message + request id (when present) for support tickets.\n * 4. A concrete next action (\"Generate a new key at …\", \"Pass `projectId`\", …).\n *\n * Non-axios errors are passed through unchanged (a regular `Error` already has a useful\n * stack trace; wrapping it would lose information without adding value).\n */\nexport function wrapNeonError(\n\terr: unknown,\n\tcontext: NeonErrorContext,\n): PlatformError | unknown {\n\tif (err instanceof PlatformError) return err;\n\tconst httpInfo = extractHttpInfo(err);\n\tif (!httpInfo) {\n\t\tconst networkInfo = extractNetworkInfo(err);\n\t\tif (networkInfo) {\n\t\t\treturn new PlatformError(\n\t\t\t\tErrorCode.NetworkError,\n\t\t\t\t`Could not reach the Neon API while running ${context.op}: ${networkInfo.message}. Check your network connection and that https://console.neon.tech is reachable.`,\n\t\t\t\t{ cause: err, details: { op: context.op, ...networkInfo } },\n\t\t\t);\n\t\t}\n\t\treturn err;\n\t}\n\n\tconst apiSummary = httpInfo.neonMessage\n\t\t? `Neon API said: \"${httpInfo.neonMessage}\"`\n\t\t: `HTTP ${httpInfo.status}`;\n\tconst requestIdSuffix = httpInfo.requestId\n\t\t? ` (request id ${httpInfo.requestId})`\n\t\t: \"\";\n\tconst apiSummaryWithRequestId = `${apiSummary}${requestIdSuffix}.`;\n\n\tswitch (httpInfo.status) {\n\t\tcase 401:\n\t\t\treturn new PlatformError(\n\t\t\t\tErrorCode.Unauthorized,\n\t\t\t\t[\n\t\t\t\t\t`${context.op} failed: the Bearer token sent to the Neon API was rejected.`,\n\t\t\t\t\tapiSummaryWithRequestId,\n\t\t\t\t\t\"Either (a) generate or rotate an API key at https://console.neon.tech/app/settings/api-keys and set NEON_API_KEY / pass --api-key, or (b) re-run `npx neon auth` to refresh the OAuth token in `~/.config/neonctl/credentials.json` (OAuth tokens expire).\",\n\t\t\t\t].join(\" \"),\n\t\t\t\t{ cause: err, details: httpDetails(context, httpInfo) },\n\t\t\t);\n\t\tcase 403:\n\t\t\treturn new PlatformError(\n\t\t\t\tErrorCode.Forbidden,\n\t\t\t\t[\n\t\t\t\t\t`${context.op} failed: this API key is not allowed to perform that operation.`,\n\t\t\t\t\tapiSummaryWithRequestId,\n\t\t\t\t\t\"Project-scoped keys can only operate on their own project; switch to an organisation/user-scoped key or pass `projectId` for an operation that doesn't need listing.\",\n\t\t\t\t].join(\" \"),\n\t\t\t\t{ cause: err, details: httpDetails(context, httpInfo) },\n\t\t\t);\n\t\tcase 404:\n\t\t\treturn new PlatformError(\n\t\t\t\tErrorCode.NotFound,\n\t\t\t\t[\n\t\t\t\t\t`${context.op} failed: resource not found on Neon.`,\n\t\t\t\t\tapiSummaryWithRequestId,\n\t\t\t\t\tcontext.projectId\n\t\t\t\t\t\t? `Verify that project '${context.projectId}' exists in this account and that the API key has access to it.`\n\t\t\t\t\t\t: \"Verify that the resource id is correct and that the API key has access to it.\",\n\t\t\t\t].join(\" \"),\n\t\t\t\t{ cause: err, details: httpDetails(context, httpInfo) },\n\t\t\t);\n\t\tcase 409:\n\t\t\treturn new PlatformError(\n\t\t\t\tErrorCode.Conflict,\n\t\t\t\t[\n\t\t\t\t\t`${context.op} failed: a conflicting resource already exists on Neon.`,\n\t\t\t\t\tapiSummaryWithRequestId,\n\t\t\t\t\t\"This is often a name collision (e.g. a branch with the same name already exists). Pull first to compare against the remote, or rename in your `neon.ts`.\",\n\t\t\t\t].join(\" \"),\n\t\t\t\t{ cause: err, details: httpDetails(context, httpInfo) },\n\t\t\t);\n\t\tcase 423:\n\t\t\treturn new PlatformError(\n\t\t\t\tErrorCode.Locked,\n\t\t\t\t[\n\t\t\t\t\t`${context.op} failed: the resource is still being modified by a previous operation, and our built-in retries did not drain it in time.`,\n\t\t\t\t\tapiSummaryWithRequestId,\n\t\t\t\t\t\"Wait a few seconds and re-run, or raise `retryOnLocked.maxAttempts` when constructing the real Neon adapter.\",\n\t\t\t\t].join(\" \"),\n\t\t\t\t{ cause: err, details: httpDetails(context, httpInfo) },\n\t\t\t);\n\t\tcase 429:\n\t\t\treturn new PlatformError(\n\t\t\t\tErrorCode.RateLimited,\n\t\t\t\t[\n\t\t\t\t\t`${context.op} failed: rate-limited by the Neon API.`,\n\t\t\t\t\tapiSummaryWithRequestId,\n\t\t\t\t\t\"Back off and retry; if this happens repeatedly, contact Neon support with the request id above.\",\n\t\t\t\t].join(\" \"),\n\t\t\t\t{ cause: err, details: httpDetails(context, httpInfo) },\n\t\t\t);\n\t}\n\n\tif (httpInfo.status >= 500) {\n\t\treturn new PlatformError(\n\t\t\tErrorCode.ServerError,\n\t\t\t[\n\t\t\t\t`${context.op} failed: the Neon API returned a server error (HTTP ${httpInfo.status}).`,\n\t\t\t\tapiSummaryWithRequestId,\n\t\t\t\t\"This is most likely transient. Retry shortly; if it persists, file an issue with the request id above and check https://neonstatus.com.\",\n\t\t\t].join(\" \"),\n\t\t\t{ cause: err, details: httpDetails(context, httpInfo) },\n\t\t);\n\t}\n\n\t// 4xx we don't have a dedicated code for. Surface what we know.\n\treturn new PlatformError(\n\t\tErrorCode.ServerError,\n\t\t`${context.op} failed: HTTP ${httpInfo.status}. ${apiSummary}${requestIdSuffix}.`,\n\t\t{ cause: err, details: httpDetails(context, httpInfo) },\n\t);\n}\n\ninterface HttpInfo {\n\tstatus: number;\n\tneonMessage?: string;\n\tneonCode?: string;\n\trequestId?: string;\n}\n\nfunction extractHttpInfo(err: unknown): HttpInfo | null {\n\tif (err === null || typeof err !== \"object\") return null;\n\tconst response = (err as { response?: unknown }).response;\n\tif (response === null || typeof response !== \"object\") return null;\n\tconst status = (response as { status?: unknown }).status;\n\tif (typeof status !== \"number\") return null;\n\tconst data = (response as { data?: unknown }).data;\n\tconst out: HttpInfo = { status };\n\tif (data !== null && typeof data === \"object\") {\n\t\tconst dataObj = data as Record<string, unknown>;\n\t\tif (typeof dataObj.message === \"string\" && dataObj.message !== \"\")\n\t\t\tout.neonMessage = dataObj.message;\n\t\tif (typeof dataObj.code === \"string\" && dataObj.code !== \"\")\n\t\t\tout.neonCode = dataObj.code;\n\t\tif (typeof dataObj.request_id === \"string\" && dataObj.request_id !== \"\")\n\t\t\tout.requestId = dataObj.request_id;\n\t}\n\treturn out;\n}\n\ninterface NetworkInfo {\n\tmessage: string;\n\tcode?: string;\n}\n\nfunction extractNetworkInfo(err: unknown): NetworkInfo | null {\n\tif (err === null || typeof err !== \"object\") return null;\n\tconst code = (err as { code?: unknown }).code;\n\tconst message = (err as { message?: unknown }).message;\n\tif (\n\t\ttypeof code === \"string\" &&\n\t\t/^(ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|EPIPE|EHOSTUNREACH|ENETUNREACH)$/.test(\n\t\t\tcode,\n\t\t)\n\t) {\n\t\treturn { message: typeof message === \"string\" ? message : code, code };\n\t}\n\t// axios timeout reports `code: \"ECONNABORTED\"`.\n\tif (code === \"ECONNABORTED\") {\n\t\treturn {\n\t\t\tmessage: typeof message === \"string\" ? message : \"timeout\",\n\t\t\tcode,\n\t\t};\n\t}\n\treturn null;\n}\n\nfunction httpDetails(\n\tcontext: NeonErrorContext,\n\tinfo: HttpInfo,\n): Record<string, unknown> {\n\tconst out: Record<string, unknown> = {\n\t\top: context.op,\n\t\tstatus: info.status,\n\t};\n\tif (context.projectId) out.projectId = context.projectId;\n\tif (info.neonMessage) out.neonMessage = info.neonMessage;\n\tif (info.neonCode) out.neonCode = info.neonCode;\n\tif (info.requestId) out.requestId = info.requestId;\n\treturn out;\n}\n"],"mappings":"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"}

package/dist/v1.d.ts

@@ -1,10 +1,11 @@
-import { AppliedChange, BranchTarget, BranchTuning, BranchTuningFn, BucketAccessLevel, BucketDef, ComputeSettings, ComputeUnit, Config, ConflictReport, CredentialPrincipalType, CredentialScope, DATA_API_AUTH_PROVIDERS, DataApiAuthProvider, DataApiConfig, DataApiExternalAuthConfig, DataApiInput, DataApiNeonAuthConfig, DataApiSettings, DurationString, DurationUnit, FunctionDef, FunctionDevConfig, FunctionRuntime, FunctionTuning, PostgresConfig, PreviewInput, PreviewTuning, PushResult, ResolvedBranchConfig, ResolvedBucketConfig, ResolvedDataApiConfig, ResolvedFunctionConfig, ResolvedPreviewConfig, ServiceEnabled, ServiceToggle, ServiceToggleInput } from "./lib/types.js";
+import { AppliedChange, BranchTarget, BranchTuning, BranchTuningFn, BucketAccessLevel, BucketDef, ComputeSettings, ComputeUnit, Config, ConflictReport, CredentialPrincipalType, CredentialScope, DATA_API_AUTH_PROVIDERS, DataApiAuthProvider, DataApiConfig, DataApiExternalAuthConfig, DataApiInput, DataApiNeonAuthConfig, DataApiSettings, DurationString, DurationUnit, ExternalPackageDef, ExternalPackageEntry, FunctionDef, FunctionDevConfig, FunctionRuntime, FunctionTuning, PostgresConfig, PreviewInput, PreviewTuning, PushResult, ResolvedBranchConfig, ResolvedBucketConfig, ResolvedDataApiConfig, ResolvedExternalPackage, ResolvedFunctionConfig, ResolvedPreviewConfig, ServiceEnabled, ServiceToggle, ServiceToggleInput } from "./lib/types.js";
 import { ConfigLoadError, ConfigValidationError, ErrorCode, MissingContextError, PartialBranchCreateError, PlatformError, PushAbortedError, PushConflictError, isPartialBranchCreateError, isPlatformError } from "./lib/errors.js";
 import { CreateBranchInput, CreateBucketInput, CreateCredentialInput, CreateProjectInput, DeployFunctionInput, EnableDataApiInput, GetConnectionUriInput, NeonApi, NeonAuthSnapshot, NeonBranchSnapshot, NeonBranchStorageSnapshot, NeonBucketSnapshot, NeonCredentialMeta, NeonCredentialSecret, NeonDataApiSnapshot, NeonDatabaseSnapshot, NeonEndpointSnapshot, NeonFunctionDeploymentSnapshot, NeonFunctionSnapshot, NeonProjectSnapshot, NeonRoleSnapshot, UpdateBranchInput } from "./lib/neon-api.js";
 import { createNeonApiFromOptions } from "./lib/auth.js";
 import { CredentialFeatureFlags, credentialScopesSatisfied, deriveCredentialScopes } from "./lib/credentials.js";
 import { defineConfig, resolveConfig } from "./lib/define-config.js";
 import { DiffOptions, DiffResult, PlanStep, RemotePreviewState, RemoteServiceState, RemoteState, diffConfig } from "./lib/diff.js";
+import { externalPackageRoot, packagesToStage } from "./lib/external-packages.js";
 import { LoadConfigOptions, loadConfigFromFile } from "./lib/loader.js";
 import { createRealNeonApi } from "./lib/neon-api-real.js";
 import * as zod0 from "zod";
@@ -83,7 +84,10 @@ declare const schemas: {
         name: zod0.ZodString;
         source: zod0.ZodString;
         env: zod0.ZodOptional<zod0.ZodRecord<zod0.ZodString, zod0.ZodString>>;
-        externalPackages: zod0.ZodOptional<zod0.ZodArray<zod0.ZodString>>;
+        externalPackages: zod0.ZodOptional<zod0.ZodArray<zod0.ZodUnion<readonly [zod0.ZodString, zod0.ZodObject<{
+          name: zod0.ZodString;
+          includeFiles: zod0.ZodOptional<zod0.ZodBoolean>;
+        }, zod_v4_core0.$strict>]>>>;
         dev: zod0.ZodOptional<zod0.ZodObject<{
           port: zod0.ZodOptional<zod0.ZodNumber>;
         }, zod_v4_core0.$strict>>;
@@ -173,7 +177,10 @@ declare const schemas: {
     name: zod0.ZodString;
     source: zod0.ZodString;
     env: zod0.ZodOptional<zod0.ZodRecord<zod0.ZodString, zod0.ZodString>>;
-    externalPackages: zod0.ZodOptional<zod0.ZodArray<zod0.ZodString>>;
+    externalPackages: zod0.ZodOptional<zod0.ZodArray<zod0.ZodUnion<readonly [zod0.ZodString, zod0.ZodObject<{
+      name: zod0.ZodString;
+      includeFiles: zod0.ZodOptional<zod0.ZodBoolean>;
+    }, zod_v4_core0.$strict>]>>>;
     dev: zod0.ZodOptional<zod0.ZodObject<{
       port: zod0.ZodOptional<zod0.ZodNumber>;
     }, zod_v4_core0.$strict>>;
@@ -196,7 +203,10 @@ declare const schemas: {
       name: zod0.ZodString;
       source: zod0.ZodString;
       env: zod0.ZodOptional<zod0.ZodRecord<zod0.ZodString, zod0.ZodString>>;
-      externalPackages: zod0.ZodOptional<zod0.ZodArray<zod0.ZodString>>;
+      externalPackages: zod0.ZodOptional<zod0.ZodArray<zod0.ZodUnion<readonly [zod0.ZodString, zod0.ZodObject<{
+        name: zod0.ZodString;
+        includeFiles: zod0.ZodOptional<zod0.ZodBoolean>;
+      }, zod_v4_core0.$strict>]>>>;
       dev: zod0.ZodOptional<zod0.ZodObject<{
         port: zod0.ZodOptional<zod0.ZodNumber>;
       }, zod_v4_core0.$strict>>;
@@ -213,5 +223,5 @@ declare const schemas: {
   }, zod_v4_core0.$strict>]>;
 };
 //#endregion
-export { type AppliedChange, type BranchTarget, type BranchTuning, type BranchTuningFn, type BucketAccessLevel, type BucketDef, type ComputeSettings, type ComputeUnit, type Config, ConfigLoadError, ConfigValidationError, type ConflictReport, type CreateBranchInput, type CreateBucketInput, type CreateCredentialInput, type CreateProjectInput, type CredentialFeatureFlags, type CredentialPrincipalType, type CredentialScope, DATA_API_AUTH_PROVIDERS, type DataApiAuthProvider, type DataApiConfig, type DataApiExternalAuthConfig, type DataApiInput, type DataApiNeonAuthConfig, type DataApiSettings, type DeployFunctionInput, type DiffOptions, type DiffResult, type DurationString, type DurationUnit, type EnableDataApiInput, ErrorCode, type FunctionDef, type FunctionDevConfig, type FunctionRuntime, type FunctionTuning, type GetConnectionUriInput, type LoadConfigOptions, MissingContextError, type NeonApi, type NeonAuthSnapshot, type NeonBranchSnapshot, type NeonBranchStorageSnapshot, type NeonBucketSnapshot, type NeonCredentialMeta, type NeonCredentialSecret, type NeonDataApiSnapshot, type NeonDatabaseSnapshot, type NeonEndpointSnapshot, type NeonFunctionDeploymentSnapshot, type NeonFunctionSnapshot, type NeonProjectSnapshot, type NeonRoleSnapshot, PartialBranchCreateError, type PlanStep, PlatformError, type PostgresConfig, type PreviewInput, type PreviewTuning, PushAbortedError, PushConflictError, type PushResult, type RemotePreviewState, type RemoteServiceState, type RemoteState, type ResolvedBranchConfig, type ResolvedBucketConfig, type ResolvedDataApiConfig, type ResolvedFunctionConfig, type ResolvedPreviewConfig, type ServiceEnabled, type ServiceToggle, type ServiceToggleInput, type UpdateBranchInput, createNeonApiFromOptions, createRealNeonApi, credentialScopesSatisfied, defineConfig, deriveCredentialScopes, diffConfig, errors, isPartialBranchCreateError, isPlatformError, loadConfigFromFile, resolveConfig, schemas };
+export { type AppliedChange, type BranchTarget, type BranchTuning, type BranchTuningFn, type BucketAccessLevel, type BucketDef, type ComputeSettings, type ComputeUnit, type Config, ConfigLoadError, ConfigValidationError, type ConflictReport, type CreateBranchInput, type CreateBucketInput, type CreateCredentialInput, type CreateProjectInput, type CredentialFeatureFlags, type CredentialPrincipalType, type CredentialScope, DATA_API_AUTH_PROVIDERS, type DataApiAuthProvider, type DataApiConfig, type DataApiExternalAuthConfig, type DataApiInput, type DataApiNeonAuthConfig, type DataApiSettings, type DeployFunctionInput, type DiffOptions, type DiffResult, type DurationString, type DurationUnit, type EnableDataApiInput, ErrorCode, type ExternalPackageDef, type ExternalPackageEntry, type FunctionDef, type FunctionDevConfig, type FunctionRuntime, type FunctionTuning, type GetConnectionUriInput, type LoadConfigOptions, MissingContextError, type NeonApi, type NeonAuthSnapshot, type NeonBranchSnapshot, type NeonBranchStorageSnapshot, type NeonBucketSnapshot, type NeonCredentialMeta, type NeonCredentialSecret, type NeonDataApiSnapshot, type NeonDatabaseSnapshot, type NeonEndpointSnapshot, type NeonFunctionDeploymentSnapshot, type NeonFunctionSnapshot, type NeonProjectSnapshot, type NeonRoleSnapshot, PartialBranchCreateError, type PlanStep, PlatformError, type PostgresConfig, type PreviewInput, type PreviewTuning, PushAbortedError, PushConflictError, type PushResult, type RemotePreviewState, type RemoteServiceState, type RemoteState, type ResolvedBranchConfig, type ResolvedBucketConfig, type ResolvedDataApiConfig, type ResolvedExternalPackage, type ResolvedFunctionConfig, type ResolvedPreviewConfig, type ServiceEnabled, type ServiceToggle, type ServiceToggleInput, type UpdateBranchInput, createNeonApiFromOptions, createRealNeonApi, credentialScopesSatisfied, defineConfig, deriveCredentialScopes, diffConfig, errors, externalPackageRoot, isPartialBranchCreateError, isPlatformError, loadConfigFromFile, packagesToStage, resolveConfig, schemas };
 //# sourceMappingURL=v1.d.ts.map

package/dist/v1.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v1.d.ts","names":[],"sources":["../src/v1.ts"],"mappings":";;;;;;;;;;;;;;;;;;cAuEa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAcA;;mDAcH,IAAA,CAAA,UAAA"}
+{"version":3,"file":"v1.d.ts","names":[],"sources":["../src/v1.ts"],"mappings":";;;;;;;;;;;;;;;;;;;cAuEa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAcA;;mDAcH,IAAA,CAAA,UAAA"}

package/dist/v1.js

@@ -1,4 +1,5 @@
 import { ConfigLoadError, ConfigValidationError, ErrorCode, MissingContextError, PartialBranchCreateError, PlatformError, PushAbortedError, PushConflictError, isPartialBranchCreateError, isPlatformError } from "./lib/errors.js";
+import { externalPackageRoot, packagesToStage } from "./lib/external-packages.js";
 import { branchTuningSchema, bucketDefSchema, computeSettingsSchema, configInputSchema, dataApiConfigSchema, dataApiInputSchema, dataApiSettingsSchema, functionDefSchema, functionTuningSchema, postgresConfigSchema, previewInputSchema, serviceToggleInputSchema, serviceToggleSchema } from "./lib/schema.js";
 import { createRealNeonApi } from "./lib/neon-api-real.js";
 import { createNeonApiFromOptions } from "./lib/auth.js";
@@ -79,6 +80,6 @@ const schemas = {
 	serviceInput: serviceToggleInputSchema
 };
 //#endregion
-export { ConfigLoadError, ConfigValidationError, DATA_API_AUTH_PROVIDERS, ErrorCode, MissingContextError, PartialBranchCreateError, PlatformError, PushAbortedError, PushConflictError, createNeonApiFromOptions, createRealNeonApi, credentialScopesSatisfied, defineConfig, deriveCredentialScopes, diffConfig, errors, isPartialBranchCreateError, isPlatformError, loadConfigFromFile, resolveConfig, schemas };
+export { ConfigLoadError, ConfigValidationError, DATA_API_AUTH_PROVIDERS, ErrorCode, MissingContextError, PartialBranchCreateError, PlatformError, PushAbortedError, PushConflictError, createNeonApiFromOptions, createRealNeonApi, credentialScopesSatisfied, defineConfig, deriveCredentialScopes, diffConfig, errors, externalPackageRoot, isPartialBranchCreateError, isPlatformError, loadConfigFromFile, packagesToStage, resolveConfig, schemas };
 
 //# sourceMappingURL=v1.js.map

package/dist/v1.js.map

@@ -1 +1 @@
-{"version":3,"file":"v1.js","names":[],"sources":["../src/v1.ts"],"sourcesContent":["/**\n * `@neon/config/v1` — the v1 public API for Config-as-Code on Neon.\n *\n * Usage in `neon.ts`:\n * ```ts\n * import { defineConfig } from \"@neon/config/v1\";\n *\n * export default defineConfig({\n *   // Static: what *exists* on every branch (drives the typed env).\n *   auth: true,\n *   // Dynamic: per-branch tuning only — cannot add/remove services.\n *   branch: (branch) => ({\n *     protected: branch.name === \"main\",\n *     ...(branch.name === \"main\" ? {} : { parent: \"main\", ttl: \"7d\" }),\n *   }),\n * });\n * ```\n *\n * This is the **authoring** surface — `defineConfig`, types, schemas, the pure diff engine,\n * and the Neon API adapter. It is intentionally free of heavy/native dependencies so that\n * importing it from `neon.ts` stays cheap and bundler-safe.\n *\n * The imperative operations (`inspect` / `plan` / `apply`, `pushConfig` / `pullConfig`) and\n * function bundling/deploy live in **`@neon/config-runtime`**, which depends on this\n * package and pulls in `esbuild`. Import that from your CLI / CI, not from `neon.ts`:\n * ```ts\n * import config from \"../neon\";\n * import { inspect, plan, apply } from \"@neon/config-runtime/v1\";\n * ```\n *\n * Surface guidelines:\n * - Top-level: `defineConfig` / `resolveConfig`, the pure `diffConfig` engine, the\n *   `createRealNeonApi` adapter + `NeonApi` types, the config loader, the `PlatformError`\n *   base class + `ErrorCode` enum, and the config types used in `neon.ts`.\n * - `errors` namespace: specific `PlatformError` subclasses (`ConfigLoadError`,\n *   `PushConflictError`, …).\n * - `schemas` namespace: the zod schemas underlying `defineConfig`.\n */\n\nimport {\n\tConfigLoadError,\n\tConfigValidationError,\n\tErrorCode,\n\tisPartialBranchCreateError,\n\tisPlatformError,\n\tMissingContextError,\n\tPartialBranchCreateError,\n\tPlatformError,\n\tPushAbortedError,\n\tPushConflictError,\n} from \"./lib/errors.js\";\nimport {\n\tbranchTuningSchema,\n\tbucketDefSchema,\n\tcomputeSettingsSchema,\n\tconfigInputSchema,\n\tdataApiConfigSchema,\n\tdataApiInputSchema,\n\tdataApiSettingsSchema,\n\tfunctionDefSchema,\n\tfunctionTuningSchema,\n\tpostgresConfigSchema,\n\tpreviewInputSchema,\n\tserviceToggleInputSchema,\n\tserviceToggleSchema,\n} from \"./lib/schema.js\";\n\n/**\n * Specific `PlatformError` subclasses, grouped for `instanceof` / structured access.\n * Also available as top-level exports.\n */\nexport const errors = {\n\tConfigLoadError,\n\tConfigValidationError,\n\tErrorCode,\n\tisPartialBranchCreateError,\n\tisPlatformError,\n\tMissingContextError,\n\tPartialBranchCreateError,\n\tPlatformError,\n\tPushAbortedError,\n\tPushConflictError,\n} as const;\n\n/** The zod schemas underlying `defineConfig`, grouped under product-friendly names. */\nexport const schemas = {\n\tconfig: configInputSchema,\n\tbranchTuning: branchTuningSchema,\n\tbucket: bucketDefSchema,\n\tcomputeSettings: computeSettingsSchema,\n\tdataApi: dataApiConfigSchema,\n\tdataApiInput: dataApiInputSchema,\n\tdataApiSettings: dataApiSettingsSchema,\n\tfunction: functionDefSchema,\n\tfunctionTuning: functionTuningSchema,\n\tpostgres: postgresConfigSchema,\n\tpreview: previewInputSchema,\n\tservice: serviceToggleSchema,\n\tserviceInput: serviceToggleInputSchema,\n} as const;\n\n// ─── Lower-level adapters ──────────────────────────────────────────────────────\nexport { createNeonApiFromOptions } from \"./lib/auth.js\";\n// ─── Credentials (pure scope derivation; Preview) ─────────────────────────────\nexport type { CredentialFeatureFlags } from \"./lib/credentials.js\";\nexport {\n\tcredentialScopesSatisfied,\n\tderiveCredentialScopes,\n} from \"./lib/credentials.js\";\nexport { defineConfig, resolveConfig } from \"./lib/define-config.js\";\n// ─── Diff engine (pure; consumed by @neon/config-runtime) ─────────────\nexport type {\n\tDiffOptions,\n\tDiffResult,\n\tPlanStep,\n\tRemotePreviewState,\n\tRemoteServiceState,\n\tRemoteState,\n} from \"./lib/diff.js\";\nexport { diffConfig } from \"./lib/diff.js\";\n// ─── Errors ────────────────────────────────────────────────────────────────────\nexport {\n\tConfigLoadError,\n\tConfigValidationError,\n\tErrorCode,\n\tisPartialBranchCreateError,\n\tisPlatformError,\n\tMissingContextError,\n\tPartialBranchCreateError,\n\tPlatformError,\n\tPushAbortedError,\n\tPushConflictError,\n} from \"./lib/errors.js\";\nexport type { LoadConfigOptions } from \"./lib/loader.js\";\nexport { loadConfigFromFile } from \"./lib/loader.js\";\n// ─── NeonApi types (needed by callers implementing their own adapters) ────────\nexport type {\n\tCreateBranchInput,\n\tCreateBucketInput,\n\tCreateCredentialInput,\n\tCreateProjectInput,\n\tDeployFunctionInput,\n\tEnableDataApiInput,\n\tGetConnectionUriInput,\n\tNeonApi,\n\tNeonAuthSnapshot,\n\tNeonBranchSnapshot,\n\tNeonBranchStorageSnapshot,\n\tNeonBucketSnapshot,\n\tNeonCredentialMeta,\n\tNeonCredentialSecret,\n\tNeonDataApiSnapshot,\n\tNeonDatabaseSnapshot,\n\tNeonEndpointSnapshot,\n\tNeonFunctionDeploymentSnapshot,\n\tNeonFunctionSnapshot,\n\tNeonProjectSnapshot,\n\tNeonRoleSnapshot,\n\tUpdateBranchInput,\n} from \"./lib/neon-api.js\";\nexport { createRealNeonApi } from \"./lib/neon-api-real.js\";\nexport type {\n\tAppliedChange,\n\tBranchTarget,\n\tBranchTuning,\n\tBranchTuningFn,\n\tBucketAccessLevel,\n\tBucketDef,\n\tComputeSettings,\n\tComputeUnit,\n\tConfig,\n\tConflictReport,\n\tCredentialPrincipalType,\n\tCredentialScope,\n\tDataApiAuthProvider,\n\tDataApiConfig,\n\tDataApiExternalAuthConfig,\n\tDataApiInput,\n\tDataApiNeonAuthConfig,\n\tDataApiSettings,\n\tDurationString,\n\tDurationUnit,\n\tFunctionDef,\n\tFunctionDevConfig,\n\tFunctionRuntime,\n\tFunctionTuning,\n\tPostgresConfig,\n\tPreviewInput,\n\tPreviewTuning,\n\tPushResult,\n\tResolvedBranchConfig,\n\tResolvedBucketConfig,\n\tResolvedDataApiConfig,\n\tResolvedFunctionConfig,\n\tResolvedPreviewConfig,\n\tServiceEnabled,\n\tServiceToggle,\n\tServiceToggleInput,\n} from \"./lib/types.js\";\n// ─── Config types (used in neon.ts and in operation return values) ────────────\nexport { DATA_API_AUTH_PROVIDERS } from \"./lib/types.js\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuEA,MAAa,SAAS;CACrB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACD;;AAGA,MAAa,UAAU;CACtB,QAAQ;CACR,cAAc;CACd,QAAQ;CACR,iBAAiB;CACjB,SAAS;CACT,cAAc;CACd,iBAAiB;CACjB,UAAU;CACV,gBAAgB;CAChB,UAAU;CACV,SAAS;CACT,SAAS;CACT,cAAc;AACf"}
+{"version":3,"file":"v1.js","names":[],"sources":["../src/v1.ts"],"sourcesContent":["/**\n * `@neon/config/v1` — the v1 public API for Config-as-Code on Neon.\n *\n * Usage in `neon.ts`:\n * ```ts\n * import { defineConfig } from \"@neon/config/v1\";\n *\n * export default defineConfig({\n *   // Static: what *exists* on every branch (drives the typed env).\n *   auth: true,\n *   // Dynamic: per-branch tuning only — cannot add/remove services.\n *   branch: (branch) => ({\n *     protected: branch.name === \"main\",\n *     ...(branch.name === \"main\" ? {} : { parent: \"main\", ttl: \"7d\" }),\n *   }),\n * });\n * ```\n *\n * This is the **authoring** surface — `defineConfig`, types, schemas, the pure diff engine,\n * and the Neon API adapter. It is intentionally free of heavy/native dependencies so that\n * importing it from `neon.ts` stays cheap and bundler-safe.\n *\n * The imperative operations (`inspect` / `plan` / `apply`, `pushConfig` / `pullConfig`) and\n * function bundling/deploy live in **`@neon/config-runtime`**, which depends on this\n * package and pulls in `esbuild`. Import that from your CLI / CI, not from `neon.ts`:\n * ```ts\n * import config from \"../neon\";\n * import { inspect, plan, apply } from \"@neon/config-runtime/v1\";\n * ```\n *\n * Surface guidelines:\n * - Top-level: `defineConfig` / `resolveConfig`, the pure `diffConfig` engine, the\n *   `createRealNeonApi` adapter + `NeonApi` types, the config loader, the `PlatformError`\n *   base class + `ErrorCode` enum, and the config types used in `neon.ts`.\n * - `errors` namespace: specific `PlatformError` subclasses (`ConfigLoadError`,\n *   `PushConflictError`, …).\n * - `schemas` namespace: the zod schemas underlying `defineConfig`.\n */\n\nimport {\n\tConfigLoadError,\n\tConfigValidationError,\n\tErrorCode,\n\tisPartialBranchCreateError,\n\tisPlatformError,\n\tMissingContextError,\n\tPartialBranchCreateError,\n\tPlatformError,\n\tPushAbortedError,\n\tPushConflictError,\n} from \"./lib/errors.js\";\nimport {\n\tbranchTuningSchema,\n\tbucketDefSchema,\n\tcomputeSettingsSchema,\n\tconfigInputSchema,\n\tdataApiConfigSchema,\n\tdataApiInputSchema,\n\tdataApiSettingsSchema,\n\tfunctionDefSchema,\n\tfunctionTuningSchema,\n\tpostgresConfigSchema,\n\tpreviewInputSchema,\n\tserviceToggleInputSchema,\n\tserviceToggleSchema,\n} from \"./lib/schema.js\";\n\n/**\n * Specific `PlatformError` subclasses, grouped for `instanceof` / structured access.\n * Also available as top-level exports.\n */\nexport const errors = {\n\tConfigLoadError,\n\tConfigValidationError,\n\tErrorCode,\n\tisPartialBranchCreateError,\n\tisPlatformError,\n\tMissingContextError,\n\tPartialBranchCreateError,\n\tPlatformError,\n\tPushAbortedError,\n\tPushConflictError,\n} as const;\n\n/** The zod schemas underlying `defineConfig`, grouped under product-friendly names. */\nexport const schemas = {\n\tconfig: configInputSchema,\n\tbranchTuning: branchTuningSchema,\n\tbucket: bucketDefSchema,\n\tcomputeSettings: computeSettingsSchema,\n\tdataApi: dataApiConfigSchema,\n\tdataApiInput: dataApiInputSchema,\n\tdataApiSettings: dataApiSettingsSchema,\n\tfunction: functionDefSchema,\n\tfunctionTuning: functionTuningSchema,\n\tpostgres: postgresConfigSchema,\n\tpreview: previewInputSchema,\n\tservice: serviceToggleSchema,\n\tserviceInput: serviceToggleInputSchema,\n} as const;\n\n// ─── Lower-level adapters ──────────────────────────────────────────────────────\nexport { createNeonApiFromOptions } from \"./lib/auth.js\";\n// ─── Credentials (pure scope derivation; Preview) ─────────────────────────────\nexport type { CredentialFeatureFlags } from \"./lib/credentials.js\";\nexport {\n\tcredentialScopesSatisfied,\n\tderiveCredentialScopes,\n} from \"./lib/credentials.js\";\nexport { defineConfig, resolveConfig } from \"./lib/define-config.js\";\n// ─── Diff engine (pure; consumed by @neon/config-runtime) ─────────────\nexport type {\n\tDiffOptions,\n\tDiffResult,\n\tPlanStep,\n\tRemotePreviewState,\n\tRemoteServiceState,\n\tRemoteState,\n} from \"./lib/diff.js\";\nexport { diffConfig } from \"./lib/diff.js\";\n// ─── Errors ────────────────────────────────────────────────────────────────────\nexport {\n\tConfigLoadError,\n\tConfigValidationError,\n\tErrorCode,\n\tisPartialBranchCreateError,\n\tisPlatformError,\n\tMissingContextError,\n\tPartialBranchCreateError,\n\tPlatformError,\n\tPushAbortedError,\n\tPushConflictError,\n} from \"./lib/errors.js\";\n// ─── External packages (pure; also for a custom FunctionBundler) ──────────────\nexport {\n\texternalPackageRoot,\n\tpackagesToStage,\n} from \"./lib/external-packages.js\";\nexport type { LoadConfigOptions } from \"./lib/loader.js\";\nexport { loadConfigFromFile } from \"./lib/loader.js\";\n// ─── NeonApi types (needed by callers implementing their own adapters) ────────\nexport type {\n\tCreateBranchInput,\n\tCreateBucketInput,\n\tCreateCredentialInput,\n\tCreateProjectInput,\n\tDeployFunctionInput,\n\tEnableDataApiInput,\n\tGetConnectionUriInput,\n\tNeonApi,\n\tNeonAuthSnapshot,\n\tNeonBranchSnapshot,\n\tNeonBranchStorageSnapshot,\n\tNeonBucketSnapshot,\n\tNeonCredentialMeta,\n\tNeonCredentialSecret,\n\tNeonDataApiSnapshot,\n\tNeonDatabaseSnapshot,\n\tNeonEndpointSnapshot,\n\tNeonFunctionDeploymentSnapshot,\n\tNeonFunctionSnapshot,\n\tNeonProjectSnapshot,\n\tNeonRoleSnapshot,\n\tUpdateBranchInput,\n} from \"./lib/neon-api.js\";\nexport { createRealNeonApi } from \"./lib/neon-api-real.js\";\nexport type {\n\tAppliedChange,\n\tBranchTarget,\n\tBranchTuning,\n\tBranchTuningFn,\n\tBucketAccessLevel,\n\tBucketDef,\n\tComputeSettings,\n\tComputeUnit,\n\tConfig,\n\tConflictReport,\n\tCredentialPrincipalType,\n\tCredentialScope,\n\tDataApiAuthProvider,\n\tDataApiConfig,\n\tDataApiExternalAuthConfig,\n\tDataApiInput,\n\tDataApiNeonAuthConfig,\n\tDataApiSettings,\n\tDurationString,\n\tDurationUnit,\n\tExternalPackageDef,\n\tExternalPackageEntry,\n\tFunctionDef,\n\tFunctionDevConfig,\n\tFunctionRuntime,\n\tFunctionTuning,\n\tPostgresConfig,\n\tPreviewInput,\n\tPreviewTuning,\n\tPushResult,\n\tResolvedBranchConfig,\n\tResolvedBucketConfig,\n\tResolvedDataApiConfig,\n\tResolvedExternalPackage,\n\tResolvedFunctionConfig,\n\tResolvedPreviewConfig,\n\tServiceEnabled,\n\tServiceToggle,\n\tServiceToggleInput,\n} from \"./lib/types.js\";\n// ─── Config types (used in neon.ts and in operation return values) ────────────\nexport { DATA_API_AUTH_PROVIDERS } from \"./lib/types.js\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuEA,MAAa,SAAS;CACrB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACD;;AAGA,MAAa,UAAU;CACtB,QAAQ;CACR,cAAc;CACd,QAAQ;CACR,iBAAiB;CACjB,SAAS;CACT,cAAc;CACd,iBAAiB;CACjB,UAAU;CACV,gBAAgB;CAChB,UAAU;CACV,SAAS;CACT,SAAS;CACT,cAAc;AACf"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neon/config",
-  "version": "0.14.0",
+  "version": "1.0.0",
   "description": "Config-as-Code for Neon. Define a `neon.ts` policy and inspect/diff/deploy it against the Neon API as plain TypeScript functions.",
   "keywords": [
     "neon",
@@ -51,7 +51,7 @@
   "dependencies": {
     "jiti": "^2.7.0",
     "zod": "^4.4.3",
-    "@neon/sdk": "1.5.0"
+    "@neon/sdk": "2.0.0"
   },
   "engines": {
     "node": ">=20.19.0"