@netlify/agent-runner-cli 1.175.0-run-started.0 → 1.175.1-alpha.0

package/dist/skills/netlify-connections/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: netlify-connections
+description: Call a third-party service from deployed site code using a connection the project has already authorized, with no provider API key. Use when server-side code needs to reach Stripe or another connected service at runtime. Must be read before writing any code that would otherwise require a provider secret such as STRIPE_SECRET_KEY.
+---
+
+# Netlify Connections
+
+A connected service is authorized **for the project**, not just for this run. Deployed code can
+reuse that authorization, so that service needs no provider API key in the site.
+
+## When to use this
+
+You are writing server-side code — a Netlify Function, an edge function, a framework route
+handler — that needs to call a service listed under **Connected services** in your context.
+
+For those services **do not** write `process.env.<SERVICE>_SECRET_KEY` or ask the user for a
+provider key — the project already has an authorized connection, so use it.
+
+This applies only to services listed under **Connected services**. Anything else has no connection
+to reuse, and an API key in the environment is the normal way to reach it.
+
+The tools you have for these services are for **your own use during this run** (looking things up,
+creating records as part of the task). They are not available to the deployed site. Deployed code
+uses the HTTP endpoint below.
+
+## How it works
+
+When a service is authorized for the project, Netlify sets two environment variables on it,
+scoped to functions, for the production and deploy-preview contexts. Nothing to enable — if the
+service is listed under **Connected services**, these are already set:
+
+| Variable | What it is |
+|----------|------------|
+| `NETLIFY_CONNECTIONS_URL` | Base URL for this project's connections |
+| `NETLIFY_CONNECTIONS_TOKEN` | This project's credential. Identifies the site; grants nothing on its own |
+
+You call Netlify, Netlify calls the provider with the stored credential. The path after
+`/proxy/` is the **provider's own API path**, so write the request you would write against the
+provider directly and change only the host.
+
+```
+${NETLIFY_CONNECTIONS_URL}/<service>/proxy/<provider path>
+```
+
+`.../stripe/proxy/v1/products` reaches `https://api.stripe.com/v1/products`.
+
+## Example
+
+A checkout endpoint, with no Stripe key anywhere:
+
+```typescript
+// netlify/functions/create-checkout.mts
+export default async (req: Request) => {
+  const { priceId } = await req.json()
+
+  const response = await fetch(`${process.env.NETLIFY_CONNECTIONS_URL}/stripe/proxy/v1/checkout/sessions`, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${process.env.NETLIFY_CONNECTIONS_TOKEN}`,
+      'content-type': 'application/x-www-form-urlencoded',
+    },
+    body: new URLSearchParams({
+      mode: 'payment',
+      'line_items[0][price]': priceId,
+      'line_items[0][quantity]': '1',
+      success_url: `${process.env.URL}/success`,
+      cancel_url: `${process.env.URL}/`,
+    }),
+  })
+
+  if (!response.ok) {
+    return new Response('Could not start checkout', { status: 502 })
+  }
+
+  const session = await response.json()
+  return Response.json({ url: session.url })
+}
+```
+
+The response is the provider's own response, status and body unchanged, so parse it exactly as
+you would parse Stripe's.
+
+## What you can reach
+
+Any path on a service listed under **Connected services**. The path after `/proxy/` is the
+provider's own API path, so use the provider's documented endpoints directly.
+
+A service that is not listed is not reachable **through this proxy**, which is not a blocker on its
+own: a service with no connection is reached the ordinary way, with its own credential from the
+environment. Report it in your result only when the task needs a service you can reach no other way.
+
+## Other responses
+
+| Status | Meaning | What to do |
+|--------|---------|------------|
+| 404 | Service not connected for this project, or connections are off | Do not retry. |
+| 424 | The connection needs to be reauthorized by the user | Surface it in your result. Handle it in code as a user-facing "reconnect Stripe" state, not a crash. |
+| 502 | The provider could not be reached | Transient. Fail the request cleanly. |
+
+## Security
+
+- **This endpoint is as public as the function you put it in.** The token is the project's, not
+  the visitor's, so anyone who can reach your handler acts with the project's authority. Build the
+  request server-side from fixed values and validate anything that comes from the caller. Never
+  forward a caller-supplied body, path, or query straight through — that hands a visitor the whole
+  allowed surface, including writes.
+- Never return `NETLIFY_CONNECTIONS_TOKEN` to the browser, embed it in client-side code, or put
+  it in a framework's public env namespace (`VITE_`, `NEXT_PUBLIC_`, `PUBLIC_`). Server-side only.
+- Never log the token or the provider's raw responses.
+
+## Checklist
+
+1. Check the service is listed under **Connected services** in your context.
+2. Write the call server-side using both environment variables.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@netlify/agent-runner-cli",
   "type": "module",
-  "version": "1.175.0-run-started.0",
+  "version": "1.175.1-alpha.0",
   "description": "CLI tool for running Netlify agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",