@bffless/skills 1.7.0

package/plugins/bffless/skills/share-links/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: share-links
+description: Token-based sharing for private deployments
+---
+
+# Share Links
+
+**Docs**: https://docs.bffless.app/features/share-links/
+
+Share links allow sharing private deployments without requiring authentication. Each link contains a unique token that grants temporary access.
+
+## Creating Share Links
+
+1. Navigate to your deployment in the Repository
+2. Click the **Share** button in the toolbar
+3. Configure options:
+   - **Expiration**: Set duration or leave unlimited
+   - **Usage limit**: Max number of visits (optional)
+   - **Label**: Descriptive name for tracking
+4. Copy the generated URL
+
+## Link Management
+
+- **View usage**: See visit count and last accessed time
+- **Disable**: Temporarily suspend access without deleting
+- **Regenerate**: Create new token, invalidating the old URL
+- **Delete**: Permanently remove access
+
+## Use Cases
+
+- **Portfolio sharing**: Send private work to potential clients
+- **Client reviews**: Share staging sites for feedback
+- **Beta testing**: Distribute preview builds to testers
+- **Time-limited access**: Demos that expire after a meeting
+
+## Best Practices
+
+1. Use descriptive labels to track who has which link
+2. Set expiration dates for sensitive content
+3. Combine with traffic splitting to show different content per link
+4. Regenerate tokens if a link is compromised
+5. Monitor usage to detect unexpected access patterns
+
+## Troubleshooting
+
+**Link not working?**
+- Check if the link is disabled or expired
+- Verify usage limit hasn't been reached
+- Ensure the deployment still exists
+
+**Need to revoke access?**
+- Disable the link immediately, or delete it entirely
+- Regenerate creates a new URL while keeping tracking history

package/plugins/bffless/skills/traffic-splitting/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: traffic-splitting
+description: Distribute traffic across aliases with weights and rules
+---
+
+# Traffic Splitting
+
+**Docs**: https://docs.bffless.app/features/traffic-splitting/
+
+Traffic splitting distributes requests across multiple deployment aliases. Use it for A/B testing, canary deployments, and personalized experiences.
+
+## Configuration
+
+### Weights
+
+Assign percentage weights to aliases. Weights must sum to 100.
+
+```
+production: 90%
+canary: 10%
+```
+
+### Sticky Sessions
+
+When enabled, visitors consistently see the same variant. Controlled via cookie. Disable for true random distribution per request.
+
+### Traffic Rules
+
+Rules override weights based on conditions. Evaluated in order, first match wins.
+
+**Rule conditions:**
+- **Headers**: Match request headers (e.g., `X-Beta-User: true`)
+- **Query params**: Match URL parameters (e.g., `?variant=new`)
+- **Cookies**: Match cookie values
+- **Share link**: Route specific share links to specific aliases
+
+## Use Cases
+
+**A/B Testing**: Split traffic 50/50 between variants, measure conversion
+
+**Canary Deployment**: Send 5% to new version, monitor for errors, gradually increase
+
+**Beta Features**: Route users with beta header to feature branch
+
+**Personalized Demos**: Use share links to show customized content per client
+
+## Configuration Tips
+
+1. Start canary deployments at 5-10%, increase gradually
+2. Enable sticky sessions for consistent user experience
+3. Use rules for deterministic routing (internal testing, specific clients)
+4. Combine with share links for per-recipient personalization
+
+## Troubleshooting
+
+**Unexpected routing?**
+- Rules are evaluated before weights; check rule order
+- Clear cookies if sticky session is routing to old variant
+- Verify alias names match exactly (case-sensitive)
+
+**Traffic percentages seem off?**
+- Small sample sizes show high variance; need 100+ requests for accuracy
+- Sticky sessions can skew percentages if users have different visit frequencies

package/plugins/bffless/skills/upload-artifact/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: upload-artifact
+description: GitHub Action for uploading build artifacts to BFFless
+---
+
+# BFFless Upload Artifact Action
+
+The `bffless/upload-artifact` GitHub Action uploads build artifacts from your CI/CD pipeline to a BFFless instance. It's available on the [GitHub Marketplace](https://github.com/bffless/upload-artifact).
+
+For full documentation, see the [README on GitHub](https://github.com/bffless/upload-artifact).
+
+## Quick Start
+
+Only 3 inputs are required:
+
+```yaml
+- uses: bffless/upload-artifact@v1
+  with:
+    path: dist
+    api-url: ${{ vars.ASSET_HOST_URL }}
+    api-key: ${{ secrets.ASSET_HOST_KEY }}
+```
+
+## Common Workflows
+
+### PR Preview with Comment
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write # Required for PR comments
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Required for commit timestamp
+
+      - name: Build
+        run: npm run build
+
+      - uses: bffless/upload-artifact@v1
+        with:
+          path: dist
+          api-url: ${{ vars.ASSET_HOST_URL }}
+          api-key: ${{ secrets.ASSET_HOST_KEY }}
+          alias: preview
+          description: 'PR #${{ github.event.pull_request.number }} preview'
+          pr-comment: true
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### Production Deploy
+
+```yaml
+- uses: bffless/upload-artifact@v1
+  id: deploy
+  with:
+    path: dist
+    api-url: ${{ vars.ASSET_HOST_URL }}
+    api-key: ${{ secrets.ASSET_HOST_KEY }}
+    alias: production
+    tags: ${{ needs.release.outputs.version }}
+    description: 'Release ${{ needs.release.outputs.version }}'
+
+- run: echo "Deployed to ${{ steps.deploy.outputs.sha-url }}"
+```
+
+### Multiple Artifacts (Same Workflow)
+
+You can upload multiple artifacts in the same workflow:
+
+```yaml
+- name: Upload frontend
+  uses: bffless/upload-artifact@v1
+  with:
+    path: apps/frontend/dist
+    api-url: ${{ vars.ASSET_HOST_URL }}
+    api-key: ${{ secrets.ASSET_HOST_KEY }}
+    alias: production
+    base-path: /dist
+
+- name: Upload skills
+  uses: bffless/upload-artifact@v1
+  with:
+    path: .bffless
+    api-url: ${{ vars.ASSET_HOST_URL }}
+    api-key: ${{ secrets.ASSET_HOST_KEY }}
+    alias: production
+```
+
+## All Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `path` | **yes** | -- | Build directory to upload |
+| `api-url` | **yes** | -- | BFFless platform URL |
+| `api-key` | **yes** | -- | API key for authentication |
+| `repository` | no | `github.repository` | Repository in `owner/repo` format |
+| `commit-sha` | no | auto | Git commit SHA |
+| `branch` | no | auto | Branch name |
+| `is-public` | no | `'true'` | Public visibility |
+| `alias` | no | -- | Deployment alias (e.g., `production`) |
+| `base-path` | no | `/<path>` | Path prefix in zip |
+| `committed-at` | no | auto | ISO 8601 commit timestamp |
+| `description` | no | -- | Human-readable description |
+| `proxy-rule-set-name` | no | -- | Proxy rule set name |
+| `proxy-rule-set-id` | no | -- | Proxy rule set ID |
+| `tags` | no | -- | Comma-separated tags |
+| `summary` | no | `'true'` | Write GitHub Step Summary |
+| `summary-title` | no | `'Deployment Summary'` | Summary heading |
+| `working-directory` | no | `'.'` | Working directory |
+| `pr-comment` | no | `'false'` | Post comment on PR |
+| `comment-header` | no | `'🚀 BFFLESS Deployment'` | PR comment header |
+| `github-token` | no | `GITHUB_TOKEN` | Token for PR comments |
+
+## Outputs
+
+| Output | Description |
+|--------|-------------|
+| `deployment-url` | Primary URL (SHA-based) |
+| `sha-url` | Immutable SHA-based URL |
+| `alias-url` | Alias-based URL |
+| `preview-url` | Preview URL (if basePath provided) |
+| `branch-url` | Branch-based URL |
+| `deployment-id` | API deployment ID |
+| `file-count` | Number of files uploaded |
+| `total-size` | Total bytes |
+| `response` | Raw JSON response |
+
+## How It Works
+
+1. **Validates** the build directory exists
+2. **Zips** the directory preserving structure
+3. **Uploads** via multipart POST to `/api/deployments/zip`
+4. **Sets outputs** from API response
+5. **Writes Step Summary** with deployment table
+6. **Posts PR comment** (if enabled)
+7. **Cleans up** temporary files
+
+## Auto-Detection
+
+The action automatically detects:
+
+- **Repository**: from `github.repository`
+- **Commit SHA**: PR head SHA or push SHA
+- **Branch**: PR head ref or push ref
+- **Committed At**: via `git log` (requires `fetch-depth: 0`)
+- **Base Path**: derived from `path` input as `/<path>`
+
+## PR Comments
+
+When `pr-comment: true`, the action posts a formatted comment:
+
+> ## 🚀 BFFLESS Deployment
+>
+> **Alias:** `preview`
+>
+> | Property    | Value                              |
+> | ----------- | ---------------------------------- |
+> | **Preview** | [example.com](https://example.com) |
+> | **Commit**  | `abc1234`                          |
+> | **Files**   | 42                                 |
+> | **Size**    | 1.2 MB                             |
+
+Comments are automatically updated on subsequent pushes (no duplicates).
+
+## Troubleshooting
+
+### Missing commit timestamp
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0 # Full history needed for git log
+```
+
+### PR comment permission denied
+
+```yaml
+permissions:
+  pull-requests: write # Required for comments
+```
+
+### Custom base path
+
+If your app expects to be served from a subdirectory:
+
+```yaml
+- uses: bffless/upload-artifact@v1
+  with:
+    path: build
+    base-path: /docs/build # Served at /docs/build/*
+```

package/plugins/bffless/skills/use-bff-state/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: use-bff-state
+description: React hook for managing server-side state with BFFless Data Tables and Pipelines, with guest IDs, loading states, and stale refetching
+---
+
+# @bffless/use-bff-state
+
+React hook library for managing server-side state with BFFless Data Tables and Pipelines. Enables React apps to synchronize state with a BFFless backend, with automatic guest identification, loading states, error handling, and stale data refetching.
+
+- **NPM Package**: `@bffless/use-bff-state`
+- **Docs**: https://docs.bffless.app/recipes/state-management/
+- **Peer Dependency**: React 18 or 19
+
+## Installation
+
+```bash
+npm install @bffless/use-bff-state
+```
+
+## Setup
+
+Wrap your app with `BffStateProvider`:
+
+```tsx
+import { BffStateProvider } from '@bffless/use-bff-state';
+
+<BffStateProvider
+  options={{
+    baseUrl: '/api', // URL prefix for all requests
+    headers: {}, // Global headers for all requests
+    persistence: 'forever', // Guest ID cookie: 'session' | { days: N } | 'forever'
+    staleTime: 5000, // ms before refetch on window focus
+  }}
+>
+  <App />
+</BffStateProvider>;
+```
+
+All options are optional. The provider can be used with no options: `<BffStateProvider><App /></BffStateProvider>`.
+
+## Core Hook: `useBffState`
+
+```tsx
+import { useBffState } from '@bffless/use-bff-state';
+
+const {
+  data,             // T — current state (initialValue until first fetch)
+  guestId,          // string — UUID for this browser/session
+  loading,          // boolean — isFetching OR isUpdating
+  error,            // Error | null
+  update,           // (newState: T | (prev: T) => T) => Promise<void>
+  refetch,          // () => Promise<void>
+  isUninitialized,  // true before first fetch
+  isFetching,       // true during GET
+  isUpdating,       // true during POST
+} = useBffState<T>(path, initialValue, options?);
+```
+
+### Hook Options
+
+| Option                 | Type                     | Default | Description                              |
+| ---------------------- | ------------------------ | ------- | ---------------------------------------- |
+| `skip`                 | `boolean`                | `false` | Skip initial fetch (conditional loading) |
+| `headers`              | `Record<string, string>` | `{}`    | Per-hook headers (merged with provider)  |
+| `refetchOnWindowFocus` | `boolean`                | `true`  | Refetch when tab visible if data stale   |
+
+## Usage Patterns
+
+### Basic State
+
+```tsx
+const { data, update } = useBffState('/api/preferences', { theme: 'light' });
+
+// Direct update
+await update({ theme: 'dark' });
+
+// Functional update (uses current state)
+await update((prev) => ({ ...prev, theme: 'dark' }));
+```
+
+### Shopping Cart
+
+```tsx
+const {
+  data: cart,
+  update,
+  loading,
+} = useBffState('/api/cart', {
+  items: [],
+  total: 0,
+});
+
+const addItem = async (item) => {
+  await update((prev) => ({
+    items: [...prev.items, item],
+    total: prev.total + item.price,
+  }));
+};
+```
+
+### Conditional Fetching
+
+```tsx
+const { data } = useBffState(
+  `/api/users/${userId}/prefs`,
+  { theme: 'light' },
+  { skip: !userId }, // Don't fetch until userId exists
+);
+```
+
+### Feature Flags
+
+```tsx
+const { data: flags, update } = useBffState('/api/feature-flags', {
+  darkMode: false,
+  betaFeatures: false,
+});
+```
+
+## Other Exports
+
+```tsx
+import { useGuestId, useBffStateContext } from '@bffless/use-bff-state';
+
+const guestId = useGuestId(); // Get current guest ID
+const context = useBffStateContext(); // Access provider config
+```
+
+### Core Utilities (Advanced)
+
+```tsx
+import {
+  generateUuid,
+  readGuestId,
+  writeGuestId,
+  getOrCreateGuestId,
+  fetchState,
+  updateState,
+  appendGuestIdParam,
+  buildUrl,
+  mergeHeaders,
+} from '@bffless/use-bff-state';
+```
+
+## How It Works
+
+- **Guest ID**: UUID v4 stored in `bff-guest-id` cookie. Lazy-created on first use. Appended to all requests as `?_bffGuestId=<uuid>`.
+- **Fetching**: GET request on mount (unless `skip: true`). Response JSON becomes `data`.
+- **Updating**: POST request with new state as JSON body. Response becomes new `data`.
+- **Stale Refetch**: On window focus, refetches if `Date.now() - lastFetch > staleTime`.
+- **Abort**: Requests aborted on unmount or when new fetch starts. AbortError silently ignored.
+- **Credentials**: All requests use `credentials: 'include'` for cookie handling.
+
+## Backend API Contract
+
+The hook expects these endpoints:
+
+**GET `{path}?_bffGuestId=<uuid>`** — Returns JSON state object
+**POST `{path}?_bffGuestId=<uuid>`** — Body: JSON state. Returns confirmed/updated state.
+
+These map to BFFless Pipeline proxy rules with `state-get` and `state-set` handler types.
+
+## Type Safety
+
+Generic type inferred from initial value or explicit:
+
+```tsx
+interface CartState {
+  items: CartItem[];
+  total: number;
+}
+const { data, update } = useBffState<CartState>('/api/cart', { items: [], total: 0 });
+// data is CartState, update expects CartState | (prev: CartState) => CartState
+```