@bffless/claude-skills 1.2.2 → 1.3.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "version": "1.3.0",
+  "description": "BFFless platform skills for Claude Code — deployments, pipelines, proxy rules, chat, traffic splitting, and more",
+  "skills": ["./skills/"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bffless/claude-skills",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Claude Code plugin with BFFless platform skills",
   "keywords": [
     "claude-code-plugin",
@@ -17,6 +17,7 @@
     "url": "https://github.com/bffless/claude-skills"
   },
   "files": [
+    ".claude-plugin/plugin.json",
     "skills/"
   ]
 }

package/skills/pipelines/SKILL.md

@@ -7,27 +7,88 @@ description: Backend automation without code using handler chains
 
 **Docs**: https://docs.bffless.app/features/pipelines/
 
-Pipelines provide backend functionality for static sites without writing server code. Chain handlers together to process forms, store data, send emails, and more.
+Pipelines provide backend functionality for static sites without writing server code. Chain handlers together to process forms, store data, send emails, call AI models, accept payments, and more.
 
 ## Handler Types
 
-| Handler | Purpose |
-|---------|---------|
-| **Form** | Parse form submissions (multipart, JSON, URL-encoded) |
-| **Data CRUD** | Create, read, update, delete DB Records |
-| **Email** | Send emails via configured provider |
-| **Response** | Return custom JSON or redirect |
-| **Function** | Custom JavaScript for complex logic |
-| **Aggregate** | Combine data from multiple sources |
+| Handler | Type | Purpose |
+|---------|------|---------|
+| **Form** | `form_handler` | Parse form submissions (multipart, JSON, URL-encoded) |
+| **Data Create** | `data_create` | Create DB records in a pipeline schema |
+| **Data Query** | `data_query` | Read/list DB records with filters, sorting, pagination |
+| **Data Update** | `data_update` | Update existing DB records |
+| **Data Delete** | `data_delete` | Delete DB records |
+| **Aggregate** | `db_aggregate` | Combine/aggregate data from multiple sources |
+| **Email** | `email_handler` | Send emails via configured provider |
+| **Response** | `response_handler` | Return custom JSON, status codes, or redirect |
+| **Function** | `function_handler` | Custom JavaScript for transformation/logic |
+| **AI** | `ai_handler` | Call OpenAI/Anthropic/Google AI models (chat or completion) |
+| **HTTP Request** | `http_request` | Make outbound HTTP requests to external APIs |
+| **File Upload** | `file_upload_handler` | Upload files from forms or URLs to storage |
+| **File Serve** | `file_serve_handler` | Serve files from storage with Range request support |
+| **Image Convert** | `image_convert_handler` | Convert images between PNG/JPEG/WebP using sharp |
+| **Signed URL** | `signed_url` | Generate time-limited presigned URLs for storage files |
+| **Replicate** | `replicate` | Call Replicate ML models (image gen, embeddings, etc.) |
+| **Embed Store** | `embed_store` | Store embedding vectors for semantic search |
+| **Vector Search** | `vector_search` | Query embeddings by cosine similarity |
+| **Stripe Checkout** | `stripe_checkout` | Create Stripe Checkout sessions for payments/subscriptions |
+| **Stripe Webhook** | `stripe_webhook` | Validate Stripe webhook signatures and parse events |
 
 ## DB Records
 
 Schema-based data storage built into BFFless:
 
 1. Define schema in project settings (fields, types, validation)
-2. Use Data CRUD handler to interact with records
+2. Use Data CRUD handlers to interact with records
 3. Query with filters, sorting, pagination
 
+## AI Handler
+
+Call AI models directly from pipelines. Supports chat (multi-turn) and completion (single-turn) modes.
+
+Key config:
+- `provider`: `openai`, `anthropic`, or `google`
+- `mode`: `chat` or `completion`
+- `messageField`: field name containing the user message (from input)
+- `systemPrompt`: system instructions for the AI
+- `persistMessages`: store conversation history in a pipeline schema
+- `persistMessagesSchemaId`: which schema to store messages in
+
+## HTTP Request Handler
+
+Make outbound API calls to external services from within a pipeline.
+
+Key config:
+- `url`: target URL (supports expressions like `${steps.prev.apiUrl}`)
+- `method`: GET, POST, PATCH, DELETE
+- `body`: request body (expressions supported)
+- `headers`: custom headers to add
+- `forwardAuth`: forward the original request's auth header
+
+## File Handlers
+
+**Upload** (`file_upload_handler`): Handles multipart file uploads or downloads from URLs. Supports allowed MIME type filtering, max file size, optional image conversion, and date-bucketed storage.
+
+**Serve** (`file_serve_handler`): Streams files from storage with HTTP Range support for video/audio playback. Config: `subDir`, `cacheMaxAge`.
+
+**Image Convert** (`image_convert_handler`): Converts between PNG, JPEG, WebP. Config: `inputPath`, `outputFormat`, `quality`.
+
+**Signed URL** (`signed_url`): Generates time-limited presigned URLs for private storage files. Config: `path`, `expiresIn` (seconds, default 3600).
+
+## Stripe Handlers
+
+**Checkout** (`stripe_checkout`): Creates Stripe Checkout sessions. Config: `priceId`, `mode` (payment/subscription), `successUrl`, `cancelUrl`, `customerEmail`, `environment` (live/test).
+
+**Webhook** (`stripe_webhook`): Validates webhook signatures and parses events. Config: `allowedEventTypes` (optional filter), `environment`.
+
+## Vector/Embedding Handlers
+
+**Embed Store** (`embed_store`): Stores embedding vectors in the database. Supports single embeddings or chunked documents. Config: `schemaId`, `recordId`, `embedding` or `chunks`.
+
+**Vector Search** (`vector_search`): Queries embeddings by cosine similarity. Config: `schemaId`, `queryVector`, `limit`, `threshold`.
+
+**Replicate** (`replicate`): Calls Replicate ML models for image generation, embeddings, etc. Auto-uploads large files to Replicate's Files API. Config: `model`, `version`, `input`.
+
 ## Expression Syntax
 
 Access data throughout the pipeline using expressions:
@@ -41,6 +102,15 @@ Access data throughout the pipeline using expressions:
 
 Example: `${input.email}` or `${steps.createUser.id}`
 
+## Validators
+
+Pipelines support validators that run before any steps execute:
+
+- `auth_required` - Require authenticated user
+- `rate_limit` - Rate limit requests (by IP or user)
+
+Both support conditions to selectively apply (e.g., only rate limit POST requests).
+
 ## Common Workflows
 
 **Contact form:**
@@ -49,17 +119,27 @@ Example: `${input.email}` or `${steps.createUser.id}`
 3. Email → notify admin
 4. Response → thank you message
 
-**Waitlist signup:**
-1. Form handler → parse email
-2. Data CRUD → check if exists, then create
-3. Email → send confirmation to user
-4. Response → success or "already registered"
+**AI chat:**
+1. Form handler → parse user message
+2. AI handler → call model with conversation context
+3. Response → return AI response
+
+**File upload with processing:**
+1. File Upload → store file
+2. Image Convert → resize/convert
+3. Data Create → store metadata
+4. Response → return file URL
+
+**Stripe payment:**
+1. Form handler → parse product selection
+2. Stripe Checkout → create session
+3. Response → redirect to Stripe
 
-**Webhook receiver:**
-1. Form handler → parse JSON payload
-2. Function → validate signature, transform data
-3. Data CRUD → store event
-4. Response → 200 OK
+**Semantic search:**
+1. Form handler → parse query
+2. AI/Replicate → generate query embedding
+3. Vector Search → find similar records
+4. Response → return results
 
 ## Configuration Tips
 
@@ -67,13 +147,14 @@ Example: `${input.email}` or `${steps.createUser.id}`
 2. Use Response handler last to control what client sees
 3. Test with simple inputs before adding validation
 4. Check pipeline logs for debugging failed executions
+5. Use `postSteps` for async work after the response is sent (e.g., sending emails)
 
 ## Troubleshooting
 
 **Pipeline not triggering?**
 - Verify endpoint path matches request URL
 - Check HTTP method (GET, POST, etc.) is correct
-- Ensure pipeline is enabled and deployed
+- Ensure pipeline is enabled and rule set is assigned to alias
 
 **Expression returning undefined?**
 - Check handler name matches exactly (case-sensitive)

package/skills/proxy-rules/SKILL.md

@@ -13,7 +13,34 @@ Proxy rules forward requests from your static site to backend APIs, eliminating
 
 **Project defaults**: Apply to all aliases unless overridden
 
-**Alias overrides**: Specific aliases can have different proxy configurations
+**Alias overrides**: Specific aliases can have their own proxy rule sets assigned
+
+## Rule Sets
+
+Proxy rules are organized into **rule sets** — named, reusable groups of rules.
+
+An alias can have **multiple rule sets** attached. When multiple rule sets are assigned, their rules are merged in priority order (first set wins if two sets define the same path+method).
+
+This allows logical grouping, e.g.:
+- `api-proxy` — routes to your backend API
+- `pipelines` — pipeline-based handlers for chat, forms, etc.
+- `auth-proxy` — cookie-to-bearer token transformation
+
+### Assigning Rule Sets to Aliases
+
+Use `update_alias` with `proxyRuleSetIds` (array) to attach one or more rule sets:
+
+```
+update_alias(
+  repository: "owner/repo",
+  alias: "production",
+  proxyRuleSetIds: ["rule-set-id-1", "rule-set-id-2"]
+)
+```
+
+The legacy `proxyRuleSetId` (singular) still works for backwards compatibility but only supports one rule set.
+
+**Important**: After creating proxy rules, you must assign the rule set(s) to an alias for rules to take effect. Rules won't be active until linked to an alias.
 
 ## Rule Structure
 
@@ -75,9 +102,9 @@ With strip prefix OFF:
 
 **Requests not proxying?**
 - Check path pattern matches request URL exactly
-- Verify alias isn't overriding project defaults
+- Verify rule set is assigned to the alias via `update_alias`
 - Confirm target URL is HTTPS and reachable
 
 **Getting CORS errors still?**
-- Ensure the proxy rule is active on the alias being accessed
+- Ensure the proxy rule set is assigned to the alias being accessed
 - Check browser DevTools for actual request URL (may not be hitting proxy)