@liiift-studio/deploy-vercel-from-sanity 0.1.3 → 0.1.6

package/README.md

@@ -1,21 +1,21 @@
 # deploy-vercel-from-sanity
 
-Sanity Studio v5 plugin — trigger and monitor Vercel deployments directly from the Studio.
+A [Sanity Studio](https://www.sanity.io) plugin to trigger, monitor, and manage Vercel deployments — without leaving your studio.
 
-- Deploy button per target with live status polling
-- Build timer while the deployment is running
-- Branch, commit message, and creator shown inline
-- Cancel an in-progress build
-- Deployment history (last 10) with preview URLs and direct build log links
-- Vercel API token stored securely in your Sanity dataset
+![Deploy tool screenshot](./docs/screenshot.png)
 
----
-
-## Requirements
+## Features
 
-- Sanity Studio v5
-- A Vercel project with at least one [Deploy Hook](https://vercel.com/docs/git/deploy-hooks) configured
-- A Vercel API token (for reading deployment status, history, and logs)
+- **Trigger deployments** via Vercel deploy hooks
+- **Live status** with automatic polling — Queued → Building → Ready / Error
+- **Build timer** showing elapsed time while a deploy is running
+- **Cancel** in-progress deployments
+- **Copy deployment URL** with one click
+- **Inline error log viewer** — see build errors directly in the card without going to Vercel
+- **Deployment history** per target
+- **"Open in Vercel"** link to the project dashboard
+- **Responsive grid layout** — 2 columns on desktop, 1 on mobile
+- **Shared API token** — set it once, works for all studio users with editor access or above
 
 ---
 
@@ -29,7 +29,7 @@ npm install @liiift-studio/deploy-vercel-from-sanity
 
 ## Setup
 
-### 1. Add the plugin
+### 1. Add the plugin to your Sanity config
 
 ```ts
 // sanity.config.ts
@@ -40,97 +40,119 @@ export default defineConfig({
   // ...
   plugins: [
     vercelDeploy(),
-    // or with custom label/icon:
+    // or with a custom label / name:
     vercelDeploy({ title: 'Deploy', name: 'vercel-deploy' }),
   ],
 })
 ```
 
-### 2. Add a deploy hook document
+### 2. (Optional) Restrict the tool to editors and above
 
-Create a `vercel_deploy` document in your Sanity dataset with the deploy hook URL from
-**Vercel → Project Settings → Git → Deploy Hooks**:
+By default the tool is visible to all authenticated users. To hide it from viewers:
 
 ```ts
-// Via Sanity CLI (run once):
-// npx sanity exec scripts/seed.js --with-user-token
+// sanity.config.ts
+tools: (prev, { currentUser }) => {
+  const canDeploy = currentUser?.roles?.some(r =>
+    ['administrator', 'editor'].includes(r.name)
+  )
+  return canDeploy ? prev : prev.filter(t => t.name !== 'vercel-deploy')
+},
+```
 
-import { getCliClient } from 'sanity/cli'
-const client = getCliClient({ apiVersion: '2025-01-01' })
+### 3. Connect your Vercel API token
 
-await client.createOrReplace({
-  _id: 'vercel-deploy-production',
-  _type: 'vercel_deploy',
-  name: 'Production',
-  url: 'https://api.vercel.com/v1/integrations/deploy/prj_xxx/yyy',
-})
+Open the **Deploy** tool in Sanity Studio. Enter a Vercel API token when prompted.
+
+To create a token: **vercel.com → Settings → Tokens → Create → Full Account scope**.
+
+The token is stored in a `config.vercelDeploy` document in your dataset and is shared across all authenticated studio users (see [Security](#security)).
+
+### 4. Create deploy targets
+
+Create one or more `vercel_deploy` documents in your dataset. Each represents a deployment environment (e.g. Production, Staging).
+
+**Via Sanity CLI:**
+
+```bash
+sanity documents create << 'EOF'
+{
+  "_type": "vercel_deploy",
+  "_id": "vercel-deploy-production",
+  "name": "Production",
+  "url": "https://api.vercel.com/v1/integrations/deploy/YOUR_PROJECT_ID/YOUR_HOOK_ID"
+}
+EOF
 ```
 
-Or create it from the Studio — the plugin registers the `vercel_deploy` schema automatically.
+**To get your deploy hook URL:** Vercel Dashboard → Project → Settings → Git → Deploy Hooks → Create Hook.
 
-### 3. Add your Vercel API token
+**Fields on each `vercel_deploy` document:**
 
-On first launch, the plugin shows a token setup screen. Create a token at
-**vercel.com → Settings → Tokens** with **Full Account** scope, paste it in, and save.
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `name` | `string` | ✓ | Display label shown in the studio |
+| `url` | `url` | ✓ | Vercel deploy hook URL |
+| `teamId` | `string` | | Vercel team ID — required for team-owned projects |
+| `disableDeleteAction` | `boolean` | | Hides the delete button for this target in the studio UI |
+
+---
 
-The token is stored in a Sanity document at `_id: "secrets.vercelDeploy"`.
+## Plugin options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `name` | `string` | `'vercel-deploy'` | Tool slug in the Studio sidebar |
+| `title` | `string` | `'Deploy'` | Tool label in the Studio sidebar |
+| `icon` | `ComponentType` | `RocketIcon` | Custom sidebar icon |
+
+---
+
+## How it works
+
+1. Deploy targets are stored as `vercel_deploy` documents in your Sanity dataset.
+2. The plugin fetches the last 10 deployments for each target from the Vercel API, filtered to those triggered by that hook.
+3. While a deployment is active (Queued / Initializing / Building), it polls every 5 seconds.
+4. Clicking **Deploy** POSTs to the hook URL — Vercel queues a new build.
+5. If a deploy fails, clicking **Show error details** fetches the last 30 build log lines from the Vercel API inline.
 
 ---
 
 ## Security
 
-### Vercel API token storage
+### API token storage
 
-The token is stored in a Sanity document with `_id: "secrets.vercelDeploy"`. Sanity's
-platform excludes documents in the `secrets.*` namespace from public/unauthenticated
-API access — they are only readable by authenticated Studio sessions.
+The Vercel API token is stored in a `config.vercelDeploy` Sanity document, which is readable by **all authenticated studio users**. Anyone with a login to your Sanity project can read the token value via the Sanity API.
 
-**If your dataset is in public mode**, verify this protection is in place before storing
-sensitive credentials. You can confirm by attempting to fetch the document without an
-auth token:
+**Recommendations:**
+- Audit who has access to your Sanity project at sanity.io → Project → Members.
+- If your studio includes untrusted editors, consider a server-side proxy that holds the token outside Sanity and exposes only a scoped deploy endpoint.
 
-```bash
-curl "https://{projectId}.api.sanity.io/v2021-06-07/data/query/{dataset}?query=*[_id==\"secrets.vercelDeploy\"]"
-# Should return empty results
-```
+### Deploy hook URL validation
 
-### Link safety
+`triggerDeploy` validates that the hook URL matches `api.vercel.com/v1/integrations/deploy/` before making the request. This prevents SSRF if a `vercel_deploy` document is created or modified outside the Studio's schema validation.
 
-All external links (`inspectorUrl`, preview URLs) from the Vercel API are validated
-to allow only `http:` and `https:` protocols before being used as `href` values.
-This prevents `javascript:` injection from a malformed API response.
+### External links
 
-### Deploy hook URLs
+All external links use `target="_blank" rel="noreferrer"` and are validated through `safeHref()` before rendering, blocking `javascript:` injection from a compromised API response.
 
-Deploy hook URLs act as secrets — anyone with the URL can trigger a deployment.
-Do not log them, commit them to public repos, or expose them client-side outside
-the Studio. The plugin only sends a POST to the hook URL; the URL itself is never
-displayed in full.
+### GROQ queries
 
----
+All GROQ queries in this plugin are static strings — no user input is interpolated, so there is no GROQ injection risk.
 
-## `vercel_deploy` document schema
+---
 
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `name` | string | ✓ | Display label (e.g. "Production") |
-| `url` | url | ✓ | Vercel deploy hook URL |
-| `teamId` | string | | Vercel team ID — required for team-owned projects |
-| `disableDeleteAction` | boolean | | Prevent deletion from the Studio |
+## Requirements
 
-The `projectId` and hook ID are parsed automatically from the hook URL.
+- Sanity Studio v3, v4, or v5
+- React 18 or 19
+- A Vercel account with at least one project configured with a deploy hook
 
 ---
 
-## Options
+## Contributing
 
-```ts
-vercelDeploy({
-  name?: string   // Tool slug in the Studio sidebar (default: 'vercel-deploy')
-  title?: string  // Tool label (default: 'Deploy')
-  icon?: React.ComponentType  // Custom icon
-})
-```
+Issues and pull requests are welcome at [github.com/Liiift-Studio/Deploy-Vercel-from-Sanity](https://github.com/Liiift-Studio/Deploy-Vercel-from-Sanity).
 
 ---