diff --git a/commands/marketplace.md b/commands/marketplace.md index 304d696..8f5dd92 100644 --- a/commands/marketplace.md +++ b/commands/marketplace.md @@ -44,9 +44,9 @@ No destructive operations unless the user explicitly confirms. Package installs vercel integration discover # Filter by category -vercel integration discover --category databases +vercel integration discover --category storage vercel integration discover --category monitoring -vercel integration discover --category auth +vercel integration discover --category authentication # List integrations already installed on this project vercel integration list @@ -114,7 +114,7 @@ Check that each variable name listed in the guide appears in the output. **Never - If local env sync was disabled or `.env.local` is stale, run: ```bash -vercel env pull .env.local --yes +vercel env pull --yes ``` - **All present** → Proceed to code changes. @@ -138,81 +138,25 @@ Ask the user for confirmation before writing files. ### 7. Verify Drain (Observability Integrations) - -Marketplace observability integrations (Datadog, Sentry, Axiom, Honeycomb, etc.) connect to Vercel's **Drains** system to receive telemetry. Understanding the data-type split is critical for correct setup. +Observability vendors installed via the Marketplace auto-create drains for **logs and traces only**. Speed Insights and Web Analytics need manual drain setup via the Dashboard or REST API. -### Data-Type Split +| Data Type | Auto-configured by install? | How to set up | +| ------------------ | --------------------------- | -------------------------------------------------------------- | +| **Logs** | Yes | `vercel integration add ` | +| **Traces** | Yes | Same — auto-configured on install | +| **Speed Insights** | No | Manual drain via REST API or Dashboard (`/~/settings/log-drains`) | +| **Web Analytics** | No | Manual drain via REST API or Dashboard (`/~/settings/log-drains`) | -| Data Type | Delivery Mechanism | Integration Setup | -| ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| **Logs** | Native drain (auto-configured by Marketplace install) | `vercel integration add ` auto-creates drain | -| **Traces** | Native drain (OpenTelemetry-compatible) | Same — auto-configured on install | -| **Speed Insights** | Custom drain endpoint only | Requires manual drain creation via REST API or Dashboard (`https://vercel.com/dashboard/{team}/~/settings/log-drains`) | -| **Web Analytics** | Custom drain endpoint only | Requires manual drain creation via REST API or Dashboard (`https://vercel.com/dashboard/{team}/~/settings/log-drains`) | - -> **Key distinction:** When you install an observability vendor via the Marketplace, it auto-configures drains for **logs and traces** only. Speed Insights and Web Analytics data require a separate, manually configured drain pointing to a custom endpoint. See `⤳ skill: observability` for drain setup details. - -### Agentic Flow: Observability Vendor Setup - -Follow this sequence when setting up an observability integration: - -#### 1. Pick Vendor +Confirm the auto-created drain landed: ```bash -# Discover observability integrations -vercel integration discover --category monitoring - -# Get setup guide for chosen vendor -vercel integration guide datadog -``` - -#### 2. Install Integration - -```bash -# Install — auto-provisions env vars and creates log/trace drains -vercel integration add datadog -``` - -#### 3. Verify Drain Created - -```bash -# Confirm drain was auto-configured curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \ "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" | jq '.[] | {id, url, type, sources}' ``` -Check the response for a drain pointing to the vendor's ingestion endpoint. If no drain appears, the integration may need manual drain setup — see `⤳ skill: observability` for REST API drain creation. - -#### 4. Validate Endpoint - -```bash -# Send a test payload to the drain -curl -X POST -H "Authorization: Bearer $VERCEL_TOKEN" \ - "https://api.vercel.com/v1/drains//test?teamId=$TEAM_ID" -``` - -Confirm the vendor dashboard shows the test event arriving. - -#### 5. Smoke Log Check +For Speed Insights / Web Analytics, create a drain manually: ```bash -# Trigger a deployment and check logs flow through -vercel logs --follow --since 5m - -# Check integration balance to confirm data is flowing -vercel integration balance datadog -``` - -Verify that logs appear both in Vercel's runtime logs and in the vendor's dashboard. - -> **For drain payload formats and signature verification**, see `⤳ skill: observability` — the Drains section covers JSON/NDJSON schemas and `x-vercel-signature` HMAC-SHA1 verification. - -### Speed Insights + Web Analytics Drains - -For observability vendors that also want Speed Insights or Web Analytics data, configure a separate drain manually: - -```bash -# Create a drain for Speed Insights + Web Analytics curl -X POST -H "Authorization: Bearer $VERCEL_TOKEN" \ -H "Content-Type: application/json" \ "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" \ @@ -224,10 +168,8 @@ curl -X POST -H "Authorization: Bearer $VERCEL_TOKEN" \ }' ``` -> **Payload schema reference:** See `⤳ skill: observability` for Web Analytics drain payload formats (JSON array of `{type, url, referrer, timestamp, geo, device}` events). - - **Drain present** → Proceed to health check. -- **No drain found** → Integration may not auto-configure drains. Create one manually via Dashboard or REST API. +- **No drain found** → Integration may not auto-configure drains. Create one manually via Dashboard (`https://vercel.com/dashboard/{team}/~/settings/log-drains`) or REST API. - **Drain errored** → Check the drain status in the Vercel Dashboard. Common fixes: endpoint URL typo, auth header missing, endpoint not accepting POST. ### 8. Run Local Health Check @@ -255,7 +197,7 @@ After completing the apply-guide loop, confirm: - [ ] Integration guide was retrieved via `vercel integration guide --framework ` - [ ] Project was linked before provisioning started - [ ] All required environment variables are provisioned on Vercel -- [ ] Local env sync is up to date (auto-sync succeeded or `vercel env pull .env.local --yes` ran) +- [ ] Local env sync is up to date (auto-sync succeeded or `vercel env pull --yes` ran) - [ ] SDK package installed without errors - [ ] Code changes applied and match the guide's patterns - [ ] For observability integrations: drain verified and test payload received diff --git a/commands/marketplace.md.tmpl b/commands/marketplace.md.tmpl index 9ed1077..8f5dd92 100644 --- a/commands/marketplace.md.tmpl +++ b/commands/marketplace.md.tmpl @@ -44,9 +44,9 @@ No destructive operations unless the user explicitly confirms. Package installs vercel integration discover # Filter by category -vercel integration discover --category databases +vercel integration discover --category storage vercel integration discover --category monitoring -vercel integration discover --category auth +vercel integration discover --category authentication # List integrations already installed on this project vercel integration list @@ -114,7 +114,7 @@ Check that each variable name listed in the guide appears in the output. **Never - If local env sync was disabled or `.env.local` is stale, run: ```bash -vercel env pull .env.local --yes +vercel env pull --yes ``` - **All present** → Proceed to code changes. @@ -138,11 +138,38 @@ Ask the user for confirmation before writing files. ### 7. Verify Drain (Observability Integrations) - -{{include:skill:marketplace:Observability Integration Path}} +Observability vendors installed via the Marketplace auto-create drains for **logs and traces only**. Speed Insights and Web Analytics need manual drain setup via the Dashboard or REST API. + +| Data Type | Auto-configured by install? | How to set up | +| ------------------ | --------------------------- | -------------------------------------------------------------- | +| **Logs** | Yes | `vercel integration add ` | +| **Traces** | Yes | Same — auto-configured on install | +| **Speed Insights** | No | Manual drain via REST API or Dashboard (`/~/settings/log-drains`) | +| **Web Analytics** | No | Manual drain via REST API or Dashboard (`/~/settings/log-drains`) | + +Confirm the auto-created drain landed: + +```bash +curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \ + "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" | jq '.[] | {id, url, type, sources}' +``` + +For Speed Insights / Web Analytics, create a drain manually: + +```bash +curl -X POST -H "Authorization: Bearer $VERCEL_TOKEN" \ + -H "Content-Type: application/json" \ + "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" \ + -d '{ + "url": "https://your-vendor-endpoint.example.com/vercel-analytics", + "type": "json", + "sources": ["lambda"], + "environments": ["production"] + }' +``` - **Drain present** → Proceed to health check. -- **No drain found** → Integration may not auto-configure drains. Create one manually via Dashboard or REST API. +- **No drain found** → Integration may not auto-configure drains. Create one manually via Dashboard (`https://vercel.com/dashboard/{team}/~/settings/log-drains`) or REST API. - **Drain errored** → Check the drain status in the Vercel Dashboard. Common fixes: endpoint URL typo, auth header missing, endpoint not accepting POST. ### 8. Run Local Health Check @@ -170,7 +197,7 @@ After completing the apply-guide loop, confirm: - [ ] Integration guide was retrieved via `vercel integration guide --framework ` - [ ] Project was linked before provisioning started - [ ] All required environment variables are provisioned on Vercel -- [ ] Local env sync is up to date (auto-sync succeeded or `vercel env pull .env.local --yes` ran) +- [ ] Local env sync is up to date (auto-sync succeeded or `vercel env pull --yes` ran) - [ ] SDK package installed without errors - [ ] Code changes applied and match the guide's patterns - [ ] For observability integrations: drain verified and test payload received diff --git a/generated/build-from-skills.manifest.json b/generated/build-from-skills.manifest.json index 60108cb..a07dbfe 100644 --- a/generated/build-from-skills.manifest.json +++ b/generated/build-from-skills.manifest.json @@ -1,6 +1,6 @@ { "version": 1, - "generatedAt": "2026-05-19T03:50:38.812Z", + "generatedAt": "2026-06-11T01:55:09.119Z", "templates": [ { "template": "agents/ai-architect.md.tmpl", @@ -290,18 +290,8 @@ { "template": "commands/marketplace.md.tmpl", "output": "commands/marketplace.md", - "dependencies": [ - "marketplace" - ], - "includes": [ - { - "marker": "{{include:skill:marketplace:Observability Integration Path}}", - "skillName": "marketplace", - "target": "Observability Integration Path", - "type": "section", - "lineNumber": 142 - } - ] + "dependencies": [], + "includes": [] }, { "template": "commands/status.md.tmpl", diff --git a/generated/skill-manifest.json b/generated/skill-manifest.json index 7631eb4..ac9ec78 100644 --- a/generated/skill-manifest.json +++ b/generated/skill-manifest.json @@ -1,5 +1,5 @@ { - "generatedAt": "2026-06-09T19:39:41.807Z", + "generatedAt": "2026-06-11T01:55:09.087Z", "version": 2, "skills": { "vercel-agent": { @@ -1309,9 +1309,9 @@ ], "intents": [ "install integration", - "build integration", "manage marketplace", - "add third party service" + "add third party service", + "discover integrations" ], "entities": [ "Vercel Marketplace", diff --git a/skills/marketplace/SKILL.md b/skills/marketplace/SKILL.md index 58f4d02..69cd6b3 100644 --- a/skills/marketplace/SKILL.md +++ b/skills/marketplace/SKILL.md @@ -1,6 +1,6 @@ --- name: marketplace -description: Vercel Marketplace expert guidance — discovering, installing, and building integrations, auto-provisioned environment variables, unified billing, and the vercel integration CLI. Use when consuming third-party services, building custom integrations, or managing marketplace resources on Vercel. +description: Vercel Marketplace expert guidance — discovering, installing, and managing integrations via the `vercel integration` CLI, with auto-provisioned environment variables and unified billing. Use when consuming third-party services on Vercel. metadata: priority: 3 docs: @@ -20,9 +20,9 @@ retrieval: - add ons intents: - install integration - - build integration - manage marketplace - add third party service + - discover integrations entities: - Vercel Marketplace - integration @@ -42,450 +42,171 @@ chainTo: # Vercel Marketplace -You are an expert in the Vercel Marketplace — the integration platform that connects third-party services to Vercel projects with unified billing, auto-provisioned environment variables, and one-click setup. +You drive the Vercel Marketplace via the `vercel integration` CLI. It provisions third-party services (databases, auth, observability, AI, payments, etc.) into the linked project with auto-injected env vars and unified billing. -## Consuming Integrations - -### Linked Project Preflight - -Integration provisioning is project-scoped. Verify the repository is linked before running `integration add`. - -```bash -# Check whether this directory is linked to a Vercel project -test -f .vercel/project.json && echo "Linked" || echo "Not linked" - -# Link if needed -vercel link -``` - -If the project is not linked, do not continue with provisioning commands until linking completes. - -### Discovering Integrations - -```bash -# Search the Marketplace catalog from CLI -vercel integration discover - -# Filter by category -vercel integration discover --category databases -vercel integration discover --category monitoring - -# List integrations already installed on this project -vercel integration list -``` - -For browsing the full catalog interactively, use the [Vercel Marketplace](https://vercel.com/marketplace) dashboard. +## CRITICAL: Discover BEFORE you scaffold -### Getting Setup Guidance - -```bash -# Get agent-friendly setup guide for a specific integration -vercel integration guide +When the user asks you to build, create, scaffold, or describe an app — even casually ("build me X", "I want an app that does Z", "make me a dashboard") — your FIRST action is `vercel integration discover`, NOT writing application code. -# Include framework-specific steps when available -vercel integration guide --framework - -# Examples -vercel integration guide neon -vercel integration guide datadog --framework nextjs -``` +**Why this matters:** scaffolding code from memory hardcodes integrations from your training data, which are often outdated. The Marketplace is the live source of truth for what's available and provisions env vars for you automatically. -Use `--framework ` as the default discovery flow when framework-specific setup matters. The guide returns structured setup steps including required environment variables, SDK packages, and code snippets — ideal for agentic workflows. +**The workflow:** -### Installing an Integration +1. Read the user's prompt and identify what kinds of services they'll need (auth, storage, payments, AI, monitoring, etc.) — use your own judgment, the Marketplace organizes around standard categories. +2. Run `vercel integration categories` to get the canonical category slugs. +3. Run `vercel integration discover --category ` to filter. Use multiple `--category` flags in one call if the prompt has multiple needs. +4. Recommend specific integrations from the results. Only then write code. -```bash -# Install from CLI -vercel integration add - -# Examples -vercel integration add neon # Postgres database -vercel integration add upstash # Redis / Kafka -vercel integration add clerk # Authentication -vercel integration add sentry # Error monitoring -vercel integration add sanity # CMS -vercel integration add datadog # Observability (auto-configures drain) -``` +## Consuming Integrations -`vercel integration add` is the primary scripted/AI path. It installs to the currently linked project, auto-connects the integration, and auto-runs environment sync locally unless disabled. +### Linked project preflight -If the CLI hands off to the dashboard for provider-specific completion, treat that as fallback: +Integration provisioning is project-scoped. Verify the local directory is linked to a Vercel project before any `add`/`connect`: ```bash -vercel integration open +test -f .vercel/project.json && echo "Linked" || vercel link ``` -Complete the web step, then return to CLI verification (`vercel env ls` and local env sync check). - -### Auto-Provisioned Environment Variables - -When you install a Marketplace integration from a linked project, Vercel automatically provisions the required environment variables for that project. +If not linked, do not continue with provisioning until linking completes. -**IMPORTANT: Provisioning delay after install.** After installing a database integration (especially Neon), the resource may take **1–3 minutes** to fully provision. During this window, connection attempts return HTTP 500 errors. Do NOT debug the connection string or code — just wait and retry. If local env sync was disabled or skipped, run `vercel env pull .env.local --yes` after a brief wait to get the finalized credentials. +### Discovering Integrations ```bash -# View environment variables added by integrations -vercel env ls - -# Example: after installing Neon, these are auto-provisioned: -# POSTGRES_URL — connection string -# POSTGRES_URL_NON_POOLING — direct connection -# POSTGRES_USER — database user -# POSTGRES_PASSWORD — database password -# POSTGRES_DATABASE — database name -# POSTGRES_HOST — database host -``` +# List canonical category slugs (always run this first when filtering) +vercel integration categories +vercel integration categories --format=json -No manual `.env` file management is needed — the variables are injected into all environments (Development, Preview, Production) automatically. +# Filter discover by category +vercel integration discover --category storage +vercel integration discover -c ai # shorthand -### Using Provisioned Resources +# Multi-category in a single command (preferred when user has multiple needs) +vercel integration discover --category commerce --category payments --category authentication +vercel integration discover -c storage -c ai +# Server-side union: returns integrations matching ANY listed category. -```ts -// app/api/users/route.ts — using Neon auto-provisioned env vars -import { neon } from "@neondatabase/serverless"; +# Specific integration by query (substring search across slug/name/description) +vercel integration discover postgres +vercel integration discover sentry -// POSTGRES_URL is auto-injected by the Neon integration -const sql = neon(process.env.POSTGRES_URL!); - -export async function GET() { - const users = await sql`SELECT * FROM users LIMIT 10`; - return Response.json(users); -} +# Full catalog +vercel integration discover +vercel integration discover --format=json ``` -```ts -// app/api/cache/route.ts — using Upstash auto-provisioned env vars -import { Redis } from "@upstash/redis"; - -// KV_REST_API_URL and KV_REST_API_TOKEN are auto-injected -const redis = Redis.fromEnv(); +For browsing the full catalog interactively, use the [Vercel Marketplace](https://vercel.com/marketplace) dashboard. -export async function GET() { - const cached = await redis.get("featured-products"); - return Response.json(cached); -} -``` +### Getting Setup Guidance -### Managing Integrations +`` is the integration slug from `vercel integration discover` (e.g. `neon`, `sentry`, `clerk`). ```bash -# List installed integrations -vercel integration ls - -# Check usage and billing for an integration -vercel integration balance - -# Remove an integration -vercel integration remove -``` - -## Unified Billing - -Marketplace integrations use Vercel's unified billing system: - -- **Single invoice**: All integration charges appear on your Vercel bill -- **Usage-based**: Pay for what you use, scaled per integration's pricing model -- **Team-level billing**: Charges roll up to the Vercel team account -- **No separate accounts**: No need to manage billing with each provider individually +# Agent-friendly setup guide for a specific integration +vercel integration guide neon +vercel integration guide sentry -```bash -# Check current usage balance for an integration -vercel integration balance datadog -vercel integration balance neon +# Framework-specific steps when available +vercel integration guide neon --framework nextjs +vercel integration guide clerk --framework sveltekit ``` -## Building Integrations - -### Integration Architecture +Supported frameworks: `nextjs`, `remix`, `astro`, `nuxtjs`, `sveltekit`. The guide returns env vars, packages, and code snippets tailored to the framework. -Vercel integrations consist of: - -1. **Integration manifest** — declares capabilities, required scopes, and UI surfaces -2. **Webhook handlers** — respond to Vercel lifecycle events -3. **UI components** — optional dashboard panels rendered within Vercel -4. **Resource provisioning** — create and manage resources for users +### Installing an Integration -### Scaffold an Integration +One command provisions the resource, connects it to the linked project, and pulls env vars locally: ```bash -# Create a new integration project -npx create-vercel-integration my-integration - -# Or start from the template -npx create-next-app my-integration --example vercel-integration -``` - -### Integration Manifest - -```json -// vercel-integration.json -{ - "name": "my-integration", - "slug": "my-integration", - "description": "Provides X for Vercel projects", - "logo": "public/logo.svg", - "website": "https://my-service.com", - "categories": ["databases"], - "scopes": { - "project": ["env-vars:read-write"], - "team": ["integrations:read-write"] - }, - "installationType": "marketplace", - "resourceTypes": [ - { - "name": "database", - "displayName": "Database", - "description": "A managed database instance" - } - ] -} -``` - -### Handling Lifecycle Webhooks - -```ts -// app/api/webhook/route.ts -import { verifyVercelSignature } from "@vercel/integration-utils"; - -export async function POST(req: Request) { - const body = await req.json(); - - // Verify the webhook is from Vercel - const isValid = await verifyVercelSignature(req, body); - if (!isValid) { - return Response.json({ error: "Invalid signature" }, { status: 401 }); - } +vercel integration add - switch (body.type) { - case "integration.installed": - // Provision resources for the new installation - await provisionDatabase(body.payload); - break; +# Multi-product integrations use slash syntax +vercel integration add aws/aws-dynamodb - case "integration.uninstalled": - // Clean up resources - await deprovisionDatabase(body.payload); - break; +# Custom resource name +vercel integration add --name my-resource - case "integration.configuration-updated": - // Handle config changes - await updateConfiguration(body.payload); - break; - } +# Specific environments (defaults to all three) +vercel integration add --environment production --environment preview - return Response.json({ received: true }); -} -``` +# Namespace env vars to avoid collisions +vercel integration add --prefix NEON2_ -### Provisioning Environment Variables - -```ts -// lib/provision.ts -async function provisionEnvVars( - installationId: string, - projectId: string, - credentials: { url: string; token: string }, -) { - const response = await fetch( - `https://api.vercel.com/v1/integrations/installations/${installationId}/env`, - { - method: "POST", - headers: { - Authorization: `Bearer ${process.env.VERCEL_INTEGRATION_TOKEN}`, - "Content-Type": "application/json", - }, - body: JSON.stringify({ - projectId, - envVars: [ - { - key: "MY_SERVICE_URL", - value: credentials.url, - target: ["production", "preview", "development"], - type: "encrypted", - }, - { - key: "MY_SERVICE_TOKEN", - value: credentials.token, - target: ["production", "preview", "development"], - type: "secret", - }, - ], - }), - }, - ); - - return response.json(); -} +# Non-interactive (CI / scripted) +vercel integration add --no-claim --format=json ``` -### Integration CLI Commands +Aliases: `vercel install ` and `vercel i `. -The `vercel integration` CLI supports these subcommands: +If the CLI hands off to the dashboard for provider-specific completion, use the web fallback: ```bash -# Discover integrations in the Marketplace catalog -vercel integration discover -vercel integration discover --category - -# Get agent-friendly setup guide -vercel integration guide -vercel integration guide --framework - -# Add (install) an integration -vercel integration add - -# List installed integrations -vercel integration list # alias: vercel integration ls - -# Check usage / billing balance -vercel integration balance - -# Open integration dashboard in browser (fallback when add redirects) vercel integration open - -# Remove an integration -vercel integration remove ``` -> **Building integrations?** Use `npx create-vercel-integration` to scaffold, then deploy your -> integration app to Vercel normally with `vercel --prod`. Publish to the Marketplace via the -> [Vercel Partner Dashboard](https://vercel.com/docs/integrations). +Complete the web step, then verify with `vercel env ls` and `vercel env pull --yes`. -## Common Integration Categories - -| Category | Popular Integrations | Auto-Provisioned Env Vars | -| --------------------- | --------------------------------------------- | --------------------------------------- | -| Databases | Neon, Supabase, PlanetScale, MongoDB, Turso | `POSTGRES_URL`, `DATABASE_URL` | -| Cache/KV | Upstash Redis | `KV_REST_API_URL`, `KV_REST_API_TOKEN` | -| Auth | Clerk, Auth0, Descope | `CLERK_SECRET_KEY`, `AUTH0_SECRET` | -| CMS | Sanity, Contentful, Storyblok, DatoCMS | `SANITY_PROJECT_ID`, `CONTENTFUL_TOKEN` | -| Monitoring | Datadog, Sentry, Checkly, New Relic | `SENTRY_DSN`, `DD_API_KEY` | -| Payments | Stripe | `STRIPE_SECRET_KEY` | -| Feature Flags | LaunchDarkly, Statsig, Hypertune | `LAUNCHDARKLY_SDK_KEY` | -| AI Agents & Services | CodeRabbit, Braintrust, Sourcery, Chatbase | varies by integration | -| Video | Mux | `MUX_TOKEN_ID`, `MUX_TOKEN_SECRET` | -| Messaging | Resend, Knock, Novu | `RESEND_API_KEY` | -| Searching | Algolia, Meilisearch | `ALGOLIA_APP_ID`, `ALGOLIA_API_KEY` | -| Commerce | Shopify, Swell, BigCommerce | `SHOPIFY_ACCESS_TOKEN` | - -## Observability Integration Path - -Marketplace observability integrations (Datadog, Sentry, Axiom, Honeycomb, etc.) connect to Vercel's **Drains** system to receive telemetry. Understanding the data-type split is critical for correct setup. - -### Data-Type Split - -| Data Type | Delivery Mechanism | Integration Setup | -| ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| **Logs** | Native drain (auto-configured by Marketplace install) | `vercel integration add ` auto-creates drain | -| **Traces** | Native drain (OpenTelemetry-compatible) | Same — auto-configured on install | -| **Speed Insights** | Custom drain endpoint only | Requires manual drain creation via REST API or Dashboard (`https://vercel.com/dashboard/{team}/~/settings/log-drains`) | -| **Web Analytics** | Custom drain endpoint only | Requires manual drain creation via REST API or Dashboard (`https://vercel.com/dashboard/{team}/~/settings/log-drains`) | - -> **Key distinction:** When you install an observability vendor via the Marketplace, it auto-configures drains for **logs and traces** only. Speed Insights and Web Analytics data require a separate, manually configured drain pointing to a custom endpoint. See `⤳ skill: observability` for drain setup details. - -### Agentic Flow: Observability Vendor Setup - -Follow this sequence when setting up an observability integration: - -#### 1. Pick Vendor - -```bash -# Discover observability integrations -vercel integration discover --category monitoring - -# Get setup guide for chosen vendor -vercel integration guide datadog -``` +### Auto-Provisioned Environment Variables -#### 2. Install Integration +Installing via Marketplace injects env vars into Development, Preview, and Production automatically. No `.env` editing needed. ```bash -# Install — auto-provisions env vars and creates log/trace drains -vercel integration add datadog +vercel env ls # see what was injected (names only) +vercel env pull --yes # sync to local (defaults to .env.local) ``` -#### 3. Verify Drain Created +### Managing Integrations ```bash -# Confirm drain was auto-configured -curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \ - "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" | jq '.[] | {id, url, type, sources}' +vercel integration list # resources for current project +vercel integration list --all # all team resources +vercel integration installations # team-level installations +vercel integration balance # billing balance (prepayment integrations) +vercel integration update --plan pro +vercel integration update --projects all +vercel integration remove --yes # uninstall ``` -Check the response for a drain pointing to the vendor's ingestion endpoint. If no drain appears, the integration may need manual drain setup — see `⤳ skill: observability` for REST API drain creation. +### Resource Management -#### 4. Validate Endpoint +For per-resource operations after install: ```bash -# Send a test payload to the drain -curl -X POST -H "Authorization: Bearer $VERCEL_TOKEN" \ - "https://api.vercel.com/v1/drains//test?teamId=$TEAM_ID" +vercel integration resource connect [project] +vercel integration resource disconnect --all --yes +vercel integration resource remove --disconnect-all --yes +vercel integration resource create-threshold ``` -Confirm the vendor dashboard shows the test event arriving. - -#### 5. Smoke Log Check - -```bash -# Trigger a deployment and check logs flow through -vercel logs --follow --since 5m - -# Check integration balance to confirm data is flowing -vercel integration balance datadog -``` +Short alias: `vc ir `. -Verify that logs appear both in Vercel's runtime logs and in the vendor's dashboard. +## Operational Rules -> **For drain payload formats and signature verification**, see `⤳ skill: observability` — the Drains section covers JSON/NDJSON schemas and `x-vercel-signature` HMAC-SHA1 verification. +- **Prefer the Marketplace path over provider CLIs.** Marketplace auto-provisions env vars, manages billing through Vercel, and works without separate provider accounts. +- **Never echo secret values.** Use `vercel env ls` to verify names only. +- **For CI / non-interactive runs**, pass `--yes` for confirmations, `--format=json` for machine-readable output, and `--no-claim` for sandbox resources to avoid prompts. +- **Don't enumerate categories or integrations from memory.** Run `vercel integration categories` or `vercel integration discover` — those are the live source of truth. -### Speed Insights + Web Analytics Drains +## Unified Billing -For observability vendors that also want Speed Insights or Web Analytics data, configure a separate drain manually: +Marketplace integration charges roll up to the Vercel team's invoice. Per-integration billing: ```bash -# Create a drain for Speed Insights + Web Analytics -curl -X POST -H "Authorization: Bearer $VERCEL_TOKEN" \ - -H "Content-Type: application/json" \ - "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" \ - -d '{ - "url": "https://your-vendor-endpoint.example.com/vercel-analytics", - "type": "json", - "sources": ["lambda"], - "environments": ["production"] - }' +vercel integration balance ``` -> **Payload schema reference:** See `⤳ skill: observability` for Web Analytics drain payload formats (JSON array of `{type, url, referrer, timestamp, geo, device}` events). - -## Decision Matrix - -| Need | Use | Why | -| ----------------------------------------- | -------------------------------------------------- | ---------------------------------------------- | -| Add a database to your project | `vercel integration add neon` | Auto-provisioned, unified billing | -| Browse available services | `vercel integration discover` | CLI-native catalog search | -| Get setup steps for an integration | `vercel integration guide --framework ` | Framework-specific, agent-friendly setup guide | -| CLI redirects to dashboard during install | `vercel integration open ` | Fallback to complete provider web flow | -| Check integration usage/cost | `vercel integration balance ` | Billing visibility per integration | -| Build a SaaS integration | Integration SDK + manifest | Full lifecycle management | -| Centralize billing | Marketplace integrations | Single Vercel invoice | -| Auto-inject credentials | Marketplace auto-provisioning | No manual env var management | -| Add observability vendor | `vercel integration add ` | Auto-creates log/trace drains | -| Export Speed Insights / Web Analytics | Manual drain via REST API | Not auto-configured by vendor install | -| Manage integrations programmatically | Vercel REST API | `/v1/integrations` endpoints | -| Test integration locally | `vercel dev` | Local development server with Vercel features | +## Two Integration Types + +- **Native integrations** — full two-way integration installable directly via the `vercel integration` CLI. No provider account needed. Billing through Vercel. +- **Connectable accounts** — connect an existing third-party account. **Requires manual setup via the Vercel Dashboard in the browser** — the CLI doesn't drive the auth handshake. Once connected, env vars are still auto-provisioned to the linked project. ## Cross-References -- **Drain configuration, payload formats, signature verification** → `⤳ skill: observability` -- **Drains REST API endpoints** → `⤳ skill: vercel-api` -- **CLI log streaming (`--follow`, `--since`, `--level`)** → `⤳ skill: vercel-cli` -- **Safe project setup sequencing (link, env pull, then run db/dev)** → `⤳ skill:bootstrap` +- Storage (Neon, Upstash, Blob, Edge Config) → see `vercel-storage` skill +- Auth (Clerk, Auth0, Descope) → see `auth` skill +- AI providers (xAI, Fal, DeepInfra, AI Gateway) → see `ai-gateway` skill + ## Official Documentation -- [Vercel Marketplace](https://vercel.com/marketplace) -- [Building Integrations](https://vercel.com/docs/integrations) -- [Integration CLI](https://vercel.com/docs/cli/integration) -- [Integration Webhooks](https://vercel.com/docs/integrations#webhooks) -- [Environment Variables](https://vercel.com/docs/environment-variables) -- [Drains Overview](https://vercel.com/docs/drains) -- [Drains Security](https://vercel.com/docs/drains/security) +- [Vercel Marketplace docs](https://vercel.com/docs/integrations) +- [`vercel integration` CLI reference](https://vercel.com/docs/cli/integration) +- [Marketplace catalog](https://vercel.com/marketplace) diff --git a/tests/__snapshots__/build-from-skills-integration.test.ts.snap b/tests/__snapshots__/build-from-skills-integration.test.ts.snap index 7f24c06..3205a08 100644 --- a/tests/__snapshots__/build-from-skills-integration.test.ts.snap +++ b/tests/__snapshots__/build-from-skills-integration.test.ts.snap @@ -47,10 +47,8 @@ exports[`dependency manifest manifest dependency snapshot 1`] = ` "template": "commands/env.md.tmpl", }, { - "dependencies": [ - "marketplace", - ], - "includeCount": 1, + "dependencies": [], + "includeCount": 0, "template": "commands/marketplace.md.tmpl", }, { @@ -106,9 +104,9 @@ exports[`CLI --json output shape --json output shape snapshot 1`] = ` "template": "commands/env.md", }, { - "dependencyCount": 1, + "dependencyCount": 0, "diagnosticCount": 0, - "resolvedCount": 1, + "resolvedCount": 0, "status": "unchanged", "template": "commands/marketplace.md", },