rsc-universal 0.1.1

package/skills/fal/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: fal
+
+should_trigger:
+  - prompt: "Generate an image with fal-ai/flux/dev from this prompt and save the output URL"
+    why: Core synchronous generation against a fal endpoint id — the central use case.
+  - prompt: "Should I use subscribe or submit for a 30-second Veo video on fal?"
+    why: Call-mode decision; non-obvious — the right answer is submit + webhook, not subscribe or run.
+  - prompt: "My fal webhook signature verification keeps failing"
+    why: ED25519 / JWKS verification path; non-obvious failure that lives entirely in this skill.
+  - prompt: "How much will 500 Seedream images cost on fal, and is batch cheaper?"
+    why: Per-unit pricing estimate plus the 50% batch path.
+  - prompt: "Genera un vídeo con fal y recíbelo por webhook verificando la firma"
+    why: Spanish; submit + webhook + signature verification end to end.
+  - prompt: "Migrate our code off @fal-ai/serverless-client to the current fal client"
+    why: Deprecated-client migration is an explicit in-scope task.
+
+should_not_trigger:
+  - prompt: "Which video model gives the best cinematic look for our ad?"
+    route_to: ai-media
+    why: Model choice and art direction, not the fal call mechanics.
+  - prompt: "Run this same FLUX model on Replicate instead"
+    route_to: replicate
+    why: Different platform with a different API (replicate.run / predictions).
+  - prompt: "Spin up an A100 pod I can SSH into and train on"
+    route_to: runpod
+    why: Raw GPU rental, not endpoint inference.
+  - prompt: "Deploy my own Python inference function as an autoscaling endpoint"
+    route_to: modal
+    why: Serving your own code, not calling fal's hosted endpoints.
+
+capability:
+  - scenario: >
+      Given a FAL_KEY, a prompt, and a requirement to generate a long video and
+      receive it via webhook, produce the end-to-end flow.
+    must_include:
+      - "@fal-ai/client (or fal-client) install + FAL_KEY auth"
+      - "submit with webhook_url for the long job — NOT run/subscribe — with the why (no held connection / drop risk)"
+      - "webhook payload shape: request_id, status (OK/ERROR), payload (and payload_error case)"
+      - "ED25519 signature verification using the four X-Fal-Webhook-* headers and JWKS at rest.fal.ai/.well-known/jwks.json"
+      - "idempotent handler tolerating the 10-retries-over-2h duplicate deliveries (dedupe on request_id)"
+      - "reading the output URL from the result payload"
+      - "a per-second cost estimate and mention of the 50% batch path"

package/skills/fal/references/models-and-cost.md

@@ -0,0 +1,53 @@
+# Models & cost
+
+How to find a fal endpoint, what its schema is, and what it costs. fal hosts hundreds of model endpoints across three modalities; you call them by id.
+
+## Finding an endpoint id and its schema
+
+1. Browse the fal model gallery; each model page shows its **endpoint id** (e.g. `fal-ai/flux/dev`), an input schema, an output schema, and a **pricing tab**.
+2. The endpoint id is what you pass to `subscribe` / `submit` / `run`.
+3. The input schema tells you required fields (`prompt`, `image_url`, `duration`, …) and the optional spend knobs.
+4. Sub-paths select a variant — e.g. `fal-ai/flux/dev` vs `fal-ai/flux/dev/image-to-image`.
+
+## Model-family map (2026)
+
+| Modality | Family | Example endpoints | Typical input |
+| --- | --- | --- | --- |
+| Image | FLUX | `fal-ai/flux/dev`, `fal-ai/flux-pro` | prompt, size, steps |
+| Image | Seedream | `fal-ai/bytedance/seedream/v4` | prompt, num_images |
+| Image | Stable Diffusion | `fal-ai/stable-diffusion-v35-large` | prompt, steps |
+| Video | Veo | `fal-ai/veo3` | prompt, duration |
+| Video | Wan | `fal-ai/wan-2.5` | prompt, duration, image_url |
+| Video | Kling / Hailuo | `fal-ai/kling-video/...`, `fal-ai/minimax/hailuo-...` | prompt, duration |
+| Audio | TTS | text-to-speech endpoints | text, voice |
+| Audio | Music | music-generation endpoints | prompt, duration |
+
+Endpoint ids shift as model versions ship — always confirm the id on the model page.
+
+## Pricing-unit cheatsheet
+
+Pricing is per-model and per-unit; the unit varies. Read the model page's pricing tab every time.
+
+| Unit | Modality | 2026 example (accessed 2026-06-02) |
+| --- | --- | --- |
+| Per image | image | Seedream V4 ~`$0.03`/image |
+| Per second of output | video | Wan 2.5 ~`$0.05`/s; Veo 3 ~`$0.4`/s |
+| Per megapixel | some image models | varies by model |
+| GPU-hour | fal-served compute | A100 40GB `$0.99`/h, H100 80GB `$1.89`/h (2026-05-13) |
+
+**Batch inference is 50% of the serverless price** — use it for offline bulk where latency does not matter.
+
+## Spend-control knobs by modality
+
+| Modality | Knobs that cut cost | Note |
+| --- | --- | --- |
+| Image | `num_inference_steps`, resolution / megapixels, `num_images` | fewer steps + smaller output = cheaper, usually fine |
+| Video | `duration`, fps, resolution | per-second pricing scales linearly with duration |
+| Audio | output length / duration | longer audio = more compute |
+
+## Worked estimates
+
+- 500 Seedream V4 images at ~$0.03 ≈ **$15** serverless; ≈ **$7.50** on the batch path.
+- A 10-second Veo 3 clip at ~$0.4/s ≈ **$4**; the same length on Wan 2.5 at ~$0.05/s ≈ **$0.50**.
+
+Cost moves with the unit and the model. Re-derive the estimate from the pricing tab before committing to a loop.

package/skills/fal/references/queue-and-webhooks.md

@@ -0,0 +1,153 @@
+# Queue & webhooks — full async lifecycle
+
+The complete async path for fal jobs you cannot block on: submit, deliver by webhook, verify, dedupe.
+
+## Lifecycle
+
+```text
+submit(endpoint, { input, webhook_url })
+        │  returns { request_id } instantly
+        ▼
+   fal queue:  IN_QUEUE ──▶ IN_PROGRESS ──▶ COMPLETED
+        │                                      │
+        │  (you poll)                          │  (fal pushes)
+        ▼                                      ▼
+ queue.status(endpoint, { requestId })   POST webhook_url  { request_id, status, payload }
+ queue.result(endpoint, { requestId })   ── verify signature, dedupe, act ──
+```
+
+Pick **one** delivery mechanism per job: poll the queue *or* receive a webhook. Webhooks win for long jobs — no held connection, no polling cost.
+
+## Webhook payload shapes
+
+```jsonc
+// Success — result is in payload
+{ "request_id": "764cabcf-...", "gateway_request_id": "764cabcf-...", "status": "OK", "payload": { "images": [{ "url": "https://..." }] } }
+
+// Job failed
+{ "request_id": "764cabcf-...", "status": "ERROR", "error": "..." }
+
+// Job succeeded but result couldn't be serialized into the webhook
+{ "request_id": "764cabcf-...", "status": "OK", "payload": null, "payload_error": "..." }
+```
+
+`gateway_request_id` equals `request_id` in normal cases. Always branch on `status` first, then check `payload` vs `payload_error`.
+
+## Delivery, retries, idempotency
+
+- Initial POST has a **15-second timeout**. Respond fast — enqueue the work, return 200, process async.
+- On timeout or any non-2xx, fal **retries up to 10 times over roughly 2 hours**.
+- Your handler **must be idempotent**: the same `request_id` can arrive multiple times. Dedupe before side effects.
+
+```ts
+// Idempotent guard — record the request_id first; skip if already seen.
+const seen = await db.webhookEvents.findUnique({ where: { requestId } });
+if (seen) return res.status(200).end();      // already processed, ack the retry
+await db.webhookEvents.create({ data: { requestId } });
+// ...now do the side effect exactly once
+```
+
+## ED25519 signature verification
+
+Four headers travel with every webhook:
+
+| Header | Meaning |
+| --- | --- |
+| `X-Fal-Webhook-Request-Id` | the job's request id |
+| `X-Fal-Webhook-User-Id` | your fal user id |
+| `X-Fal-Webhook-Timestamp` | unix seconds when fal signed |
+| `X-Fal-Webhook-Signature` | hex-encoded ED25519 signature |
+
+Verification algorithm:
+
+1. Reject if `|now - timestamp| > 300` seconds (±5 min) — blocks replay.
+2. Fetch the JWKS from `https://rest.fal.ai/.well-known/jwks.json`; **cache it ≤ 24h**. Each key's `x` field is a base64url-encoded ED25519 public key.
+3. Build the signed message as four newline-joined parts: `request_id`, `user_id`, `timestamp`, and the **hex SHA-256 of the raw request body**.
+4. Hex-decode the signature.
+5. ED25519-verify the message against each JWKS key until one passes. If none pass, reject.
+
+Use the **raw** request body for the SHA-256 — re-serialized JSON will not match.
+
+### Node
+
+```ts
+import { createHash, verify } from "node:crypto";
+
+let jwksCache: { keys: any[]; at: number } | null = null;
+async function getJwks() {
+  if (jwksCache && Date.now() - jwksCache.at < 24 * 3600_000) return jwksCache.keys;
+  const r = await fetch("https://rest.fal.ai/.well-known/jwks.json");
+  const { keys } = await r.json();
+  jwksCache = { keys, at: Date.now() };
+  return keys;
+}
+
+export async function verifyFalWebhook(headers: Record<string, string>, rawBody: Buffer) {
+  const reqId = headers["x-fal-webhook-request-id"];
+  const userId = headers["x-fal-webhook-user-id"];
+  const ts = headers["x-fal-webhook-timestamp"];
+  const sigHex = headers["x-fal-webhook-signature"];
+  if (!reqId || !userId || !ts || !sigHex) return false;
+  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
+
+  const bodyHash = createHash("sha256").update(rawBody).digest("hex");
+  const message = Buffer.from([reqId, userId, ts, bodyHash].join("\n"), "utf-8");
+  const sig = Buffer.from(sigHex, "hex");
+
+  for (const jwk of await getJwks()) {
+    const pub = Buffer.from(jwk.x, "base64url"); // 32-byte raw ed25519 key
+    const der = Buffer.concat([
+      Buffer.from("302a300506032b6570032100", "hex"), // SPKI prefix for ed25519
+      pub,
+    ]);
+    const keyObj = { key: der, format: "der" as const, type: "spki" as const };
+    if (verify(null, message, keyObj as any, sig)) return true;
+  }
+  return false;
+}
+```
+
+### Python
+
+```python
+import time, hashlib, httpx
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from cryptography.exceptions import InvalidSignature
+
+_jwks = {"keys": None, "at": 0.0}
+
+def _get_jwks():
+    if _jwks["keys"] and time.time() - _jwks["at"] < 24 * 3600:
+        return _jwks["keys"]
+    keys = httpx.get("https://rest.fal.ai/.well-known/jwks.json").json()["keys"]
+    _jwks.update(keys=keys, at=time.time())
+    return keys
+
+def verify_fal_webhook(headers: dict, raw_body: bytes) -> bool:
+    import base64
+    req_id = headers.get("x-fal-webhook-request-id")
+    user_id = headers.get("x-fal-webhook-user-id")
+    ts = headers.get("x-fal-webhook-timestamp")
+    sig_hex = headers.get("x-fal-webhook-signature")
+    if not all([req_id, user_id, ts, sig_hex]):
+        return False
+    if abs(time.time() - int(ts)) > 300:
+        return False
+
+    body_hash = hashlib.sha256(raw_body).hexdigest()
+    message = "\n".join([req_id, user_id, ts, body_hash]).encode()
+    sig = bytes.fromhex(sig_hex)
+
+    for jwk in _get_jwks():
+        pub = base64.urlsafe_b64decode(jwk["x"] + "==")  # 32-byte raw key
+        try:
+            Ed25519PublicKey.from_public_bytes(pub).verify(sig, message)
+            return True
+        except InvalidSignature:
+            continue
+    return False
+```
+
+## Optional: IP allowlisting
+
+For an extra layer, restrict your endpoint to fal's egress ranges. Fetch `webhook_ip_ranges` from `https://api.fal.ai/v1/meta`. Ranges rotate — refresh periodically; do not hardcode. Signature verification is the primary defense; IP allowlisting is belt-and-suspenders.

package/skills/fal/scripts/verify.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# verify.sh — static, offline checks for the fal skill's worked code.
+# Read-only. No network, no real FAL_KEY. Exit 0 on a clean/empty target.
+#
+# Usage: scripts/verify.sh [TARGET_DIR]
+#   TARGET_DIR defaults to the skill root (parent of this script's dir).
+# Checks the SKILL.md + references code fences for:
+#   1. no deprecated @fal-ai/serverless-client (must use @fal-ai/client)
+#   2. webhook section names all four X-Fal-Webhook-* headers + the JWKS URL
+#   3. long-job guidance uses submit/webhook_url and flags run as not-for-long-jobs
+#   4. FAL_KEY is referenced and no hardcoded key literal is present
+
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+target="${1:-$(cd "$here/.." && pwd)}"
+
+fail=0
+note() { printf '  - %s\n' "$1"; }
+err()  { printf 'FAIL: %s\n' "$1"; fail=1; }
+
+# Gather the skill's markdown files. Empty target => nothing to check => pass.
+# Portable to bash 3.2 (default macOS) — no mapfile.
+files="$(find "$target" -type f -name '*.md' 2>/dev/null | sort)"
+if [ -z "$files" ]; then
+  echo "verify(fal): no markdown files under $target — nothing to check."
+  exit 0
+fi
+file_count="$(printf '%s\n' "$files" | wc -l | tr -d ' ')"
+
+# Concatenated corpus for grep (read-only).
+corpus="$(printf '%s\n' "$files" | while IFS= read -r f; do cat "$f"; done 2>/dev/null || true)"
+
+# 1. deprecated client must not appear.
+if grep -q '@fal-ai/serverless-client' <<<"$corpus"; then
+  # Allowed only when explicitly flagged as deprecated/NOT/migrate on the same line.
+  if grep '@fal-ai/serverless-client' <<<"$corpus" \
+       | grep -qviE 'deprecat|NOT |migrate|anti-pattern'; then
+    err "deprecated @fal-ai/serverless-client referenced without a deprecation flag"
+  fi
+fi
+grep -q '@fal-ai/client' <<<"$corpus" || err "current @fal-ai/client never referenced"
+
+# 2. webhook headers + JWKS URL (only enforce if a webhook section exists).
+if grep -qi 'webhook' <<<"$corpus"; then
+  for h in X-Fal-Webhook-Request-Id X-Fal-Webhook-User-Id \
+           X-Fal-Webhook-Timestamp X-Fal-Webhook-Signature; do
+    grep -qi "$h" <<<"$corpus" || err "webhook header $h not documented"
+  done
+  grep -q 'rest.fal.ai/.well-known/jwks.json' <<<"$corpus" \
+    || err "JWKS URL rest.fal.ai/.well-known/jwks.json not referenced"
+fi
+
+# 3. long-job guidance: submit/webhook present, run flagged as not-for-long-jobs.
+grep -qiE 'webhook_url|webhookUrl' <<<"$corpus" || err "webhook_url not in guidance"
+grep -qi 'submit' <<<"$corpus" || err "submit call mode not documented"
+grep -qiE 'run.*(drop|long|no queue|few second)' <<<"$corpus" \
+  || err "'run' not flagged as unsuitable for long jobs"
+
+# 4. FAL_KEY referenced; no hardcoded key literal.
+grep -q 'FAL_KEY' <<<"$corpus" || err "FAL_KEY auth not referenced"
+# A real key looks like key_id:key_secret with long hex-ish parts; placeholders are fine.
+if grep -oE 'key_[0-9a-f]{16,}:[0-9a-f]{16,}' <<<"$corpus" >/dev/null; then
+  err "a hardcoded FAL_KEY literal appears in the docs"
+fi
+
+if [ "$fail" -ne 0 ]; then
+  echo "verify(fal): checks failed."
+  exit 1
+fi
+echo "verify(fal): all static checks passed ($file_count files)."
+exit 0