@neon/tools 2.14.4 → 2.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/README.md +195 -5
  2. package/dist/descriptions.gen.js +2 -2
  3. package/dist/effect.d.ts +22 -0
  4. package/dist/effect.d.ts.map +1 -0
  5. package/dist/effect.js +3 -0
  6. package/dist/generated/output.gen.d.ts +3418 -0
  7. package/dist/generated/output.gen.d.ts.map +1 -0
  8. package/dist/generated/output.gen.js +1498 -0
  9. package/dist/generated/zod.gen.d.ts +3 -3
  10. package/dist/index.d.ts +17 -5
  11. package/dist/index.d.ts.map +1 -1
  12. package/dist/index.js +30 -9
  13. package/dist/lib/custom/auth-config.d.ts +63 -2
  14. package/dist/lib/custom/auth-config.d.ts.map +1 -1
  15. package/dist/lib/custom/auth-config.js +34 -7
  16. package/dist/lib/custom/docs.d.ts +32 -2
  17. package/dist/lib/custom/docs.d.ts.map +1 -1
  18. package/dist/lib/custom/docs.js +18 -1
  19. package/dist/lib/custom/feedback.d.ts +7 -2
  20. package/dist/lib/custom/feedback.d.ts.map +1 -1
  21. package/dist/lib/custom/feedback.js +3 -0
  22. package/dist/lib/custom/fetch.d.ts +15 -1
  23. package/dist/lib/custom/fetch.d.ts.map +1 -1
  24. package/dist/lib/custom/fetch.js +10 -1
  25. package/dist/lib/custom/organizations.d.ts +23 -1
  26. package/dist/lib/custom/organizations.d.ts.map +1 -1
  27. package/dist/lib/custom/organizations.js +3 -0
  28. package/dist/lib/custom/resources.d.ts +15 -1
  29. package/dist/lib/custom/resources.d.ts.map +1 -1
  30. package/dist/lib/custom/resources.js +8 -1
  31. package/dist/lib/custom/sql/connection.d.ts +6 -7
  32. package/dist/lib/custom/sql/connection.d.ts.map +1 -1
  33. package/dist/lib/custom/sql/connection.js +10 -12
  34. package/dist/lib/custom/sql/describe-branch.d.ts +99 -1
  35. package/dist/lib/custom/sql/describe-branch.d.ts.map +1 -1
  36. package/dist/lib/custom/sql/describe-branch.js +11 -2
  37. package/dist/lib/custom/sql/inspect/inspect.d.ts +27 -1
  38. package/dist/lib/custom/sql/inspect/inspect.d.ts.map +1 -1
  39. package/dist/lib/custom/sql/inspect/inspect.js +17 -3
  40. package/dist/lib/custom/sql/migrations.d.ts +46 -2
  41. package/dist/lib/custom/sql/migrations.d.ts.map +1 -1
  42. package/dist/lib/custom/sql/migrations.js +29 -7
  43. package/dist/lib/custom/sql/query-tuning.d.ts +90 -2
  44. package/dist/lib/custom/sql/query-tuning.d.ts.map +1 -1
  45. package/dist/lib/custom/sql/query-tuning.js +31 -8
  46. package/dist/lib/custom/sql/run.d.ts +30 -3
  47. package/dist/lib/custom/sql/run.d.ts.map +1 -1
  48. package/dist/lib/custom/sql/run.js +15 -6
  49. package/dist/lib/custom/sql/schema.d.ts +76 -2
  50. package/dist/lib/custom/sql/schema.d.ts.map +1 -1
  51. package/dist/lib/custom/sql/schema.js +34 -5
  52. package/dist/lib/custom/sql/slow-queries.d.ts +15 -1
  53. package/dist/lib/custom/sql/slow-queries.d.ts.map +1 -1
  54. package/dist/lib/custom/sql/slow-queries.js +11 -3
  55. package/dist/lib/customize.d.ts +1 -1
  56. package/dist/lib/customize.d.ts.map +1 -1
  57. package/dist/lib/customize.js +8 -4
  58. package/dist/lib/effect/errors.d.ts +51 -0
  59. package/dist/lib/effect/errors.d.ts.map +1 -0
  60. package/dist/lib/effect/errors.js +37 -0
  61. package/dist/lib/effect/tools.d.ts +56 -0
  62. package/dist/lib/effect/tools.d.ts.map +1 -0
  63. package/dist/lib/effect/tools.js +67 -0
  64. package/dist/lib/ergonomic/bind.d.ts +25 -7
  65. package/dist/lib/ergonomic/bind.d.ts.map +1 -1
  66. package/dist/lib/ergonomic/bind.js +13 -3
  67. package/dist/lib/ergonomic/catalog.d.ts +5335 -180
  68. package/dist/lib/ergonomic/catalog.d.ts.map +1 -1
  69. package/dist/lib/ergonomic/catalog.js +286 -23
  70. package/dist/lib/ergonomic/composed.d.ts +866 -12
  71. package/dist/lib/ergonomic/composed.d.ts.map +1 -1
  72. package/dist/lib/ergonomic/composed.js +63 -0
  73. package/dist/lib/mcp-json-schema.d.ts +20 -0
  74. package/dist/lib/mcp-json-schema.d.ts.map +1 -1
  75. package/dist/lib/mcp-json-schema.js +89 -1
  76. package/dist/lib/mcp-register.d.ts +1 -1
  77. package/dist/lib/mcp-register.d.ts.map +1 -1
  78. package/dist/lib/mcp-register.js +2 -1
  79. package/dist/lib/operation.d.ts +56 -5
  80. package/dist/lib/operation.d.ts.map +1 -1
  81. package/dist/lib/operation.js +6 -1
  82. package/dist/lib/policy.d.ts +24 -0
  83. package/dist/lib/policy.d.ts.map +1 -0
  84. package/dist/lib/policy.js +49 -0
  85. package/dist/lib/redact.d.ts +8 -0
  86. package/dist/lib/redact.d.ts.map +1 -0
  87. package/dist/lib/redact.js +40 -0
  88. package/dist/mastra.d.ts +2 -1
  89. package/dist/mastra.d.ts.map +1 -1
  90. package/dist/mcp-v1.d.ts.map +1 -1
  91. package/dist/mcp-v1.js +3 -1
  92. package/dist/mcp.d.ts +3 -3
  93. package/dist/mcp.d.ts.map +1 -1
  94. package/dist/mcp.js +3 -3
  95. package/dist/operations.gen.d.ts +194 -194
  96. package/package.json +21 -2
package/README.md CHANGED
@@ -94,7 +94,7 @@ await tools["projects.list"].execute(
94
94
  );
95
95
  ```
96
96
 
97
- Each tool includes its Zod 4 `inputSchema`, published `id`, title, description, safety annotations, stability metadata, and `execute()`. Inputs are snake_case at the tool boundary. `execute()` strictly validates the input, rejects unknown fields, and returns typed, JSON-safe `{ data }`. Neon SDK errors remain typed and are thrown to the caller.
97
+ Each tool includes its Zod 4 `inputSchema` and `outputSchema`, published `id`, title, description, safety annotations, stability metadata, and `execute()`. Inputs are snake_case at the tool boundary. `execute()` strictly validates the input, rejects unknown fields, and returns typed, JSON-safe `{ data }`. Neon SDK errors remain typed and are thrown to the caller.
98
98
 
99
99
  Paginated lists call `.all()` and return the item array. Do not pass a cursor; those fields are omitted from the input schema.
100
100
 
@@ -144,7 +144,7 @@ const tools = createNeonTools({
144
144
  const { data: config } = await tools["auth.getConfig"].execute({
145
145
  project_id: "project-id",
146
146
  });
147
- config.oauth_providers; // [{ id: "google", type: "standard", client_id: "…", client_secret: "***redacted***" }]
147
+ config.oauth_providers; // [{ id: "google", type: "standard", client_id: "…", client_secret: "****abcd" }]
148
148
 
149
149
  const { data: found } = await tools["resources.search"].execute({
150
150
  query: "checkout",
@@ -194,7 +194,7 @@ const { data: result } = await tools["sql.run"].execute({
194
194
  result; // { rows: [{ id: 1, email: "a@example.com" }, { id: 2, email: "b@example.com" }], totalRowCount: 40, truncated: true, note: "Showing the first 2 of 40 rows. …" }
195
195
  ```
196
196
 
197
- `auth.getConfig` replaces OAuth client secrets and the SMTP password with `"***redacted***"`. Trusted origins, localhost access, email and password, and OAuth providers are required reads: an error on any of them fails the call, and a branch without Neon Auth throws `NeonNotFoundError`. The email provider, plugins, and webhook reads are reported under `_errors` when they fail; an email provider that was never configured is `null`.
197
+ `auth.getConfig` returns the OAuth client secrets and SMTP password the API returns to the caller; they are `stored` secrets, so `secrets: "setup"` or `"none"` hides them (see [Secrets](#secrets)). Trusted origins, localhost access, email and password, and OAuth providers are required reads: an error on any of them fails the call, and a branch without Neon Auth throws `NeonNotFoundError`. The email provider, plugins, and webhook reads are reported under `_errors` when they fail; an email provider that was never configured is `null`.
198
198
 
199
199
  `user.organizations` takes an optional `search` that filters by a case-insensitive part of the name or id. An organization API key gets its own organization.
200
200
 
@@ -227,7 +227,7 @@ await tools["sql.run"].execute(
227
227
 
228
228
  | Field | Effect |
229
229
  | --- | --- |
230
- | `readOnly` | `sql.run` and `sql.explain` run the statement in a `READ ONLY` transaction, so Postgres rejects writes. `sql.runTransaction`, `migrations.*`, and `queryTuning.*` throw `NeonClientError` without running anything, because a caller statement such as `COMMIT` or `SET TRANSACTION READ WRITE` can leave a read-only transaction. `schema.*` and `queries.listSlow` behave the same; `branches.describe` and `database.inspect` always use a `READ ONLY` transaction. |
230
+ | `readOnly` | A tool whose `metadata.readOnlySafe` is `false` throws `NeonClientError` without a request (see [Read-only](#read-only)). `sql.run` and `sql.explain` run the statement in a `READ ONLY` transaction, so Postgres rejects writes. `sql.runTransaction`, `migrations.*`, and `queryTuning.*` are not read-only safe, because a caller statement such as `COMMIT` or `SET TRANSACTION READ WRITE` can leave a read-only transaction. `schema.*` and `queries.listSlow` behave like `sql.run`; `branches.describe` and `database.inspect` always use a `READ ONLY` transaction. |
231
231
  | `postgresRole` | Every SQL connection logs in as this role, and `postgres.connectionString` returns a URI for it. A `role_name` that differs throws `NeonClientError`. |
232
232
  | `caller` | Sent with `docs.search` as `x-caller-source`, `x-caller-user-agent`, and `x-caller-client`. Without it, or when `source` cannot be a header value, `x-caller-source` is `neon_tools`. The search service records `website`, `cli`, `mcp`, and `monitor` by name and counts any other source as `rest`. |
233
233
 
@@ -250,6 +250,119 @@ const { data: page } = await tools["docs.get"].execute({ slug: data.hits[0].slug
250
250
 
251
251
  Neon's feedback reporting counts `manual_test`, `neon_agent`, `neon_cli`, `neon_mcp`, and `neon_website` by name and any other `feedbackSource`, including the default, as `other`.
252
252
 
253
+ ## Read-only
254
+
255
+ `metadata.readOnlySafe` is `true` when a tool changes no Neon resource and returns no connection string or role password: a `GET` that needs no approval, `logs.query`, the SQL tools that run one statement in a `READ ONLY` transaction, and the docs, feedback, search, and incidents tools. `postgres.connectionString` is a `GET` but not read-only safe, because its URI carries a role password that works against the read-write compute.
256
+
257
+ `readOnly: true` on `createNeonTools`, `createNeonTool`, or `execute` refuses every tool that is not read-only safe. The execution context wins over the factory:
258
+
259
+ ```ts
260
+ const tools = createNeonTools({
261
+ apiKey,
262
+ tools: ["projects.list", "projects.delete", "sql.run"],
263
+ readOnly: true,
264
+ });
265
+
266
+ await tools["projects.list"].execute({}); // runs
267
+ await tools["sql.run"].execute({ project_id: "project-id", sql: "SELECT 1" }); // READ ONLY transaction
268
+ await tools["projects.delete"].execute({ project_id: "project-id" });
269
+ // throws NeonClientError: delete_projects is unavailable in read-only mode ...
270
+ await tools["projects.delete"].execute(
271
+ { project_id: "project-id" },
272
+ { readOnly: false },
273
+ ); // runs
274
+ ```
275
+
276
+ The refusal happens inside `onExecute`, so a tracking hook sees it as a failed call, and before `inject` resolves a project or branch id.
277
+
278
+ ### Select tools by metadata
279
+
280
+ `tools` also takes a predicate. It sees every published tool without its `execute` (`operationId`, `id`, `title`, `description`, `annotations`, `requiresApproval`, `metadata`) and keeps the ones it returns `true` for, in `toolIds` order. A predicate that matches nothing throws.
281
+
282
+ ```ts
283
+ const readTools = createNeonTools({
284
+ apiKey,
285
+ readOnly: true,
286
+ tools: (tool) =>
287
+ tool.metadata.readOnlySafe && tool.metadata.tags.includes("Branch"),
288
+ });
289
+
290
+ await readTools["branches.list"]?.execute({ project_id: "project-id" });
291
+ ```
292
+
293
+ The result is typed as a partial record, since which tools the predicate keeps is known only at runtime. `toMastraTools` keeps that optionality, also when the record mixes in tools from a list. `CreateNeonToolsPredicateOptions` types predicate options declared ahead of the call. Pass a list of selectors when you need exact keys.
294
+
295
+ ## Secrets
296
+
297
+ Tools return secrets as the API returns them. `secrets` on `createNeonTools`, `createNeonTool`, or `execute` chooses which ones results keep, and the execution context wins over the factory:
298
+
299
+ | `secrets` | Results keep |
300
+ | --- | --- |
301
+ | `"all"` (default) | every secret |
302
+ | `"setup"` | `setup` secrets: credentials Neon issues for an app, CI job, or agent to use |
303
+ | `"none"` | no secret |
304
+
305
+ A hidden secret becomes `REDACTED_SECRET` (`"***redacted***"`). An absent, `null`, or empty value stays as it is.
306
+
307
+ ```ts
308
+ import { createNeonTools, REDACTED_SECRET } from "@neon/tools";
309
+
310
+ const tools = createNeonTools({
311
+ apiKey,
312
+ tools: ["credentials.create", "auth.emailProvider.get", "realtime.secret"],
313
+ secrets: "setup",
314
+ });
315
+
316
+ const { data: credential } = await tools["credentials.create"].execute({
317
+ project_id: "project-id",
318
+ branch_id: "br-main",
319
+ scopes: ["ai_gateway:invoke"],
320
+ principal_type: "user",
321
+ });
322
+ credential.api_token; // "nt_live_..."
323
+
324
+ const { data: smtp } = await tools["auth.emailProvider.get"].execute({
325
+ project_id: "project-id",
326
+ branch_id: "br-main",
327
+ });
328
+ smtp.password === REDACTED_SECRET; // true
329
+
330
+ await tools["realtime.secret"].execute(
331
+ { project_id: "project-id", branch_id: "br-main" },
332
+ { secrets: "none" },
333
+ );
334
+ // throws NeonClientError: secret_realtime is unavailable with secrets: "none" because its result is a secret.
335
+ ```
336
+
337
+ `metadata.secretOutputFields` lists where a tool's result carries a secret, as `{ path, kind }`. A path is `$` (the whole value), `.key`, or `[*]` (every array item). `kind` is `setup` for a credential Neon issues, or `stored` for a secret you gave Neon to call another service. `metadata.returnsOnlySecrets` is `true` when the result is the secret itself; such a tool refuses before it sends a request when `secrets` would hide its result.
338
+
339
+ | Tool | `secretOutputFields` | `kind` | `returnsOnlySecrets` |
340
+ | --- | --- | --- | --- |
341
+ | `postgres.connectionString` | `$` | `setup` | yes |
342
+ | `projects.createAndConnect`, `branches.createAndConnect` | `$.connectionString` | `setup` | no |
343
+ | `postgres.roles.list` | `$[*].password` | `setup` | no |
344
+ | `postgres.roles.get`, `postgres.roles.create` | `$.password` | `setup` | no |
345
+ | `postgres.roles.resetPassword` | `$.password` | `setup` | yes |
346
+ | `credentials.create` | `$.api_token`, `$.s3_secret_access_key` | `setup` | no |
347
+ | `credentials.rotate` | `$.api_token`, `$.s3_secret_access_key` | `setup` | yes |
348
+ | `realtime.secret` | `$.secret` | `setup` | yes |
349
+ | `storage.objects.presign` | `$.url` | `setup` | yes |
350
+ | `auth.create` | `$.secret_server_key` | `setup` | no |
351
+ | `auth.oauthClients.create` | `$.client_secret` | `setup` | no |
352
+ | `auth.oauthClients.rotateSecret` | `$.client_secret` | `setup` | yes |
353
+ | `apiKeys.create`, `organizations.apiKeys.create` | `$.key` | `setup` | no |
354
+ | `auth.oauthProviders.list` | `$[*].client_secret` | `stored` | no |
355
+ | `auth.oauthProviders.add`, `auth.oauthProviders.update` | `$.client_secret` | `stored` | no |
356
+ | `auth.emailProvider.get`, `auth.emailProvider.update` | `$.password` | `stored` | no |
357
+ | `auth.plugins.get` | `$.email_provider.password`, `$.oauth_providers[*].client_secret` | `stored` | no |
358
+ | `auth.getConfig` | `$.oauth_providers[*].client_secret`, `$.email_provider.password` | `stored` | no |
359
+
360
+ `withheldUnderSecrets(tool.metadata, mode)` tells whether a tool refuses under a mode, so a host can leave those tools out: `(tool) => !withheldUnderSecrets(tool.metadata, "none")`. `hiddenSecretFields(tool.metadata, mode)` returns the fields a mode hides.
361
+
362
+ A rotation that returns the replacement (`credentials.rotate`, `postgres.roles.resetPassword`, `auth.oauthClients.rotateSecret`) counts as only a secret, because hiding it would discard the new value after the old one stopped working. `realtime.rotateSecret` returns nothing and stays available. Creates still run when their secret is hidden, so a secret the API returns only once, such as `apiKeys.create`'s `key` or a confidential client's `client_secret`, is lost. `readOnly` does not change `secrets`.
363
+
364
+ Redaction runs inside `onExecute`, so a tracking hook sees the redacted result.
365
+
253
366
  ## Writes and waiting
254
367
 
255
368
  Tools run with `waitForReadiness: true`. When a mutation response includes an `operations` array, the call waits until those operations finish. The default deadline is five minutes (`wait.timeoutMs`). Pass `wait: { timeoutMs: 30_000 }` on `createNeonTools` or `createNeonTool` to bound that. Set it below the host's own tool-call timeout, otherwise the host gives up first.
@@ -423,6 +536,49 @@ registerNeonTools(server, tools);
423
536
 
424
537
  `registerNeonTools` publishes that catalog. MCP 2 `inputSchema` is JSON Schema without `$schema`. Generated fields have types, enums, `required`, and constraints, and no OpenAPI property docs. Fields this package described with `.describe()` (`pooled`, `finalize`, `zip`) keep that copy.
425
538
 
539
+ Every tool also publishes an `outputSchema` for its `structuredContent`, `{ data }`:
540
+
541
+ ```json
542
+ {
543
+ "type": "object",
544
+ "properties": {
545
+ "data": {
546
+ "type": "array",
547
+ "items": {
548
+ "type": "object",
549
+ "properties": {
550
+ "id": { "type": "string" },
551
+ "name": { "type": "string" },
552
+ "default": { "type": "boolean" },
553
+ "parent_id": { "type": ["string", "null"] },
554
+ "created_by": { "type": ["object", "null"] }
555
+ },
556
+ "required": ["id", "name", "default"]
557
+ }
558
+ }
559
+ },
560
+ "required": ["data"]
561
+ }
562
+ ```
563
+
564
+ That is an excerpt of `list_branches`. The schema types the fields of `data`, or of each list item, and stops there: a nested object is `{ "type": "object" }`. Enums are strings and extra fields are allowed, so a new API value or field still validates. Descriptions appear only where this package wrote them. The server checks every successful result against this schema, the same check a validating MCP client runs; a result that breaks it becomes an `isError` result reading `Output validation error`. Failures return `{ error }` and are not checked.
565
+
566
+ `tool.outputSchema` is the full Zod schema of `data`. Hosts that register tools themselves can publish the same compact form:
567
+
568
+ ```ts
569
+ import { toMcpOutputJsonSchema, toMcpOutputSchema } from "@neon/tools/mcp";
570
+
571
+ const json = toMcpOutputJsonSchema(tool.outputSchema); // JSON Schema of { data }
572
+ const standard = toMcpOutputSchema(tool.outputSchema); // Standard Schema for MCP 2 registerTool
573
+
574
+ // A host that removes fields from results before returning them
575
+ const stripped = toMcpOutputSchema(tool.outputSchema, {
576
+ omit: ["connectionString", "password"],
577
+ });
578
+ ```
579
+
580
+ `omit` drops those names from the schema at every level, including from `required`.
581
+
426
582
  Hosts that convert Zod themselves:
427
583
 
428
584
  ```ts
@@ -508,9 +664,43 @@ const createProject = createTool(configs.create_and_connect_projects);
508
664
 
509
665
  The adapter maps approval requirements to Mastra's `requireApproval` field and forwards its abort signal. Credentials are the constructor `apiKey` (a string or a callback invoked on every request).
510
666
 
667
+ ## Effect
668
+
669
+ `@neon/tools/effect` runs the same tools as [Effect](https://effect.website) v4 Effects. Install the optional peer dependencies `effect` and `@neon/effect`; the other entry points don't need them.
670
+
671
+ ```ts
672
+ import { createNeonTools } from "@neon/tools";
673
+ import { retryReadOnlyNetworkFailures, toEffectTools } from "@neon/tools/effect";
674
+ import { Effect } from "effect";
675
+
676
+ const tools = toEffectTools(
677
+ createNeonTools({ tools: ["projects.list", "projects.get"] as const }),
678
+ { retry: retryReadOnlyNetworkFailures },
679
+ );
680
+
681
+ const project = tools["projects.get"]
682
+ .execute({ project_id: "my-project-id" }, { apiKey })
683
+ .pipe(Effect.catchTag("NeonNotFoundError", () => Effect.succeed(undefined)));
684
+ ```
685
+
686
+ `toEffectTools` keeps every tool field and replaces `execute`, which returns `Effect<NeonToolResult, NeonToolError>` with a span named `NeonTools.<id>`. The execution context is the one above without `signal`: interrupting the fiber cancels the call.
687
+
688
+ The span records every failure's tag as `error.type` and fails only for the server's: invalid input, a statement Postgres rejected, and any 4xx from the Neon API keep it ok. `NeonClientError` fails it, since the SDK uses it for malformed responses as well as its own validation. A `NeonSqlError` whose SQLSTATE class is 08, 40, 53, 55, 57, 58, F0, or XX (connection, rollback, resources, operator, system, or internal errors) fails it. `neon.tool.attempts` counts the attempts, and `neon.tool.retried_error.type` names the failure a retry recovered from.
689
+
690
+ | Error / `_tag` | When |
691
+ | --- | --- |
692
+ | `NeonEffectError` members (`NeonAuthError`, `NeonNotFoundError`, `NeonNetworkError`, …) | The Neon API or SDK failed; see [`@neon/effect`](../effect/README.md#errors) |
693
+ | `NeonToolInputError` | The input failed the tool's schema; `issues` lists why |
694
+ | `NeonSqlError` | Postgres rejected the statement; `code` is the SQLSTATE, with `position`, `detail`, `hint`, `where` |
695
+ | `NeonSqlConnectionError` | The SQL endpoint failed before Postgres answered |
696
+
697
+ Anything else a tool throws becomes a defect. `toNeonToolError` is the mapping, for promise code you wrap yourself.
698
+
699
+ Retries are off unless you pass `retry`. The SDK already retries 423, 429, and 503 responses and honours `Retry-After`. `retryReadOnlyNetworkFailures` retries a read-only tool that got no response, twice with jittered exponential backoff from 200 ms; mutations are never retried, since one may have reached the API. A retry runs the whole tool again, including `onExecute` hooks and every page of a list. Pass your own `NeonToolRetryPolicy` (`schedule`, `times`, `shouldRetry`) for a different policy. Whatever it says, the adapter only retries read-only tools and never a 423, 429, or 503 response.
700
+
511
701
  ## Safety and binary data
512
702
 
513
- Every non-read operation requires approval. Generated non-read operations are conservatively marked as potentially destructive; `migrations.prepare` and `queryTuning.prepare` (which write only to a new temporary branch) and `feedback.send` are not. Reads that return connection credentials also require approval.
703
+ Every non-read operation requires approval. Generated non-read operations are conservatively marked as potentially destructive; `migrations.prepare` and `queryTuning.prepare` (which write only to a new temporary branch) and `feedback.send` are not. Reads that return connection credentials or Neon Auth secrets also require approval.
514
704
 
515
705
  Binary request fields accept base64 strings:
516
706
 
@@ -110,10 +110,10 @@ const toolDescriptions = {
110
110
  "auth.allowLocalhost.update": "Sets whether a branch's Neon Auth accepts localhost origins; turn it off for production. Current value: {{auth.getConfig}}.",
111
111
  "auth.emailAndPassword.get": "Gets a branch's Neon Auth email and password sign-in settings.",
112
112
  "auth.emailAndPassword.update": "Updates a branch's Neon Auth email and password sign-in; omitted fields keep their value. Current values: {{auth.getConfig}}.",
113
- "auth.emailProvider.get": "Gets a branch's Neon Auth email provider; the SMTP password comes back empty.",
113
+ "auth.emailProvider.get": "Gets a branch's Neon Auth email provider.",
114
114
  "auth.emailProvider.update": "Sets the email provider for Neon Auth's emails: body.type \"shared\" for Neon's sender, or \"standard\" with your SMTP details. Test it with {{auth.emailProvider.sendTest}}.",
115
115
  "auth.emailProvider.sendTest": "Sends a test email through the branch's saved standard SMTP provider to recipient_email. Only send to an address the user gave you. A failed send returns success false with error_message, not an error.",
116
- "auth.plugins.get": "Gets all Neon Auth plugin settings of a branch. OAuth and SMTP secrets come back empty.",
116
+ "auth.plugins.get": "Gets all Neon Auth plugin settings of a branch.",
117
117
  "auth.plugins.magicLink.update": "Updates the Neon Auth magic link plugin; omitted fields keep their value. Current values: {{auth.getConfig}}.",
118
118
  "auth.plugins.organization.update": "Updates the Neon Auth organization plugin, which lets your app's users form organizations (not Neon organizations). Omitted fields keep their value. Current values: {{auth.getConfig}}.",
119
119
  "auth.plugins.phoneNumber.get": "Gets a branch's Neon Auth SMS OTP plugin settings.",
@@ -0,0 +1,22 @@
1
+ /**
2
+ * `@neon/tools/effect` — run Neon tools as Effects: typed errors, interruption that
3
+ * cancels the call, a span per tool, and opt-in retries.
4
+ *
5
+ * Requires the optional peer dependencies `effect` and `@neon/effect`.
6
+ *
7
+ * @example
8
+ * ```ts
9
+ * import { createNeonTools } from "@neon/tools";
10
+ * import { toEffectTools } from "@neon/tools/effect";
11
+ * import { Effect } from "effect";
12
+ *
13
+ * const tools = toEffectTools(createNeonTools({ tools: ["projects.list"] }));
14
+ *
15
+ * const program = tools["projects.list"]
16
+ * .execute({}, { apiKey: process.env.NEON_API_KEY })
17
+ * .pipe(Effect.catchTag("NeonAuthError", () => Effect.succeed(undefined)));
18
+ * ```
19
+ */
20
+ export { NeonSqlConnectionError, NeonSqlError, type NeonToolError, NeonToolInputError, toNeonToolError, } from "./lib/effect/errors.js";
21
+ export { type EffectToolOptions, type ExecutableNeonTool, type NeonEffectTool, type NeonEffectToolContext, type NeonEffectTools, type NeonToolRetryPolicy, retryReadOnlyNetworkFailures, toEffectTool, toEffectTools, } from "./lib/effect/tools.js";
22
+ //# sourceMappingURL=effect.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"effect.d.ts","sourceRoot":"","sources":["../src/effect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACN,sBAAsB,EACtB,YAAY,EACZ,KAAK,aAAa,EAClB,kBAAkB,EAClB,eAAe,GACf,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACN,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,4BAA4B,EAC5B,YAAY,EACZ,aAAa,GACb,MAAM,uBAAuB,CAAC"}
package/dist/effect.js ADDED
@@ -0,0 +1,3 @@
1
+ import { NeonSqlConnectionError, NeonSqlError, NeonToolInputError, toNeonToolError } from "./lib/effect/errors.js";
2
+ import { retryReadOnlyNetworkFailures, toEffectTool, toEffectTools } from "./lib/effect/tools.js";
3
+ export { NeonSqlConnectionError, NeonSqlError, NeonToolInputError, retryReadOnlyNetworkFailures, toEffectTool, toEffectTools, toNeonToolError };