vybekiit 0.7.4 → 0.7.8

package/dist/global-skills/email-best-practices/references/webhooks-events.md

@@ -0,0 +1,167 @@
+# Webhooks and Events
+
+Receiving and processing email delivery events in real-time.
+
+## Event Types
+
+| Event | When Fired | Use For |
+|-------|------------|---------|
+| `email.sent` | Email accepted by Resend | Confirming send initiated |
+| `email.delivered` | Email delivered to recipient server | Confirming delivery |
+| `email.bounced` | Email bounced (hard or soft) | List hygiene, alerting |
+| `email.complained` | Recipient marked as spam | Immediate unsubscribe |
+| `email.opened` | Recipient opened email | Engagement tracking |
+| `email.clicked` | Recipient clicked link | Engagement tracking |
+
+## Webhook Setup
+
+### 1. Create Endpoint
+
+Your endpoint must:
+- Accept POST requests
+- Return 2xx status quickly (within 5 seconds)
+- Handle duplicate events (idempotent processing)
+
+```typescript
+app.post('/webhooks/resend', async (req, res) => {
+  // Return 200 immediately to acknowledge receipt
+  res.status(200).send('OK');
+
+  // Process asynchronously
+  processWebhookAsync(req.body).catch(console.error);
+});
+```
+
+### 2. Verify Signatures
+
+Always verify webhook signatures to prevent spoofing.
+
+```typescript
+import { Webhook } from 'svix';
+
+const webhook = new Webhook(process.env.RESEND_WEBHOOK_SECRET);
+
+app.post('/webhooks/resend', (req, res) => {
+  try {
+    const payload = webhook.verify(
+      JSON.stringify(req.body),
+      {
+        'svix-id': req.headers['svix-id'],
+        'svix-timestamp': req.headers['svix-timestamp'],
+        'svix-signature': req.headers['svix-signature'],
+      }
+    );
+    // Process verified payload
+  } catch (err) {
+    return res.status(400).send('Invalid signature');
+  }
+});
+```
+
+### 3. Register Webhook URL
+
+Configure your webhook endpoint in the Resend dashboard or via API.
+
+## Processing Events
+
+### Bounce Handling
+
+```typescript
+async function handleBounce(event) {
+  const { email_id, email, bounce_type } = event.data;
+
+  if (bounce_type === 'hard') {
+    // Permanent failure - remove from all lists
+    await suppressEmail(email, 'hard_bounce');
+    await removeFromAllLists(email);
+  } else {
+    // Soft bounce - track and remove after threshold
+    await incrementSoftBounce(email);
+    const count = await getSoftBounceCount(email);
+    if (count >= 3) {
+      await suppressEmail(email, 'soft_bounce_limit');
+    }
+  }
+}
+```
+
+### Complaint Handling
+
+```typescript
+async function handleComplaint(event) {
+  const { email } = event.data;
+
+  // Immediate suppression - no exceptions
+  await suppressEmail(email, 'complaint');
+  await removeFromAllLists(email);
+  await logComplaint(event); // For analysis
+}
+```
+
+### Delivery Confirmation
+
+```typescript
+async function handleDelivered(event) {
+  const { email_id } = event.data;
+  await updateEmailStatus(email_id, 'delivered');
+}
+```
+
+## Idempotent Processing
+
+Webhooks may be sent multiple times. Use event IDs to prevent duplicate processing.
+
+```typescript
+async function processWebhook(event) {
+  const eventId = event.id;
+
+  // Check if already processed
+  if (await isEventProcessed(eventId)) {
+    return; // Skip duplicate
+  }
+
+  // Process event
+  await handleEvent(event);
+
+  // Mark as processed
+  await markEventProcessed(eventId);
+}
+```
+
+## Error Handling
+
+### Retry Behavior
+
+If your endpoint returns non-2xx, webhooks will retry with exponential backoff:
+- Retry 1: ~30 seconds
+- Retry 2: ~1 minute
+- Retry 3: ~5 minutes
+- (continues for ~24 hours)
+
+### Best Practices
+
+- **Return 200 quickly** - Process asynchronously to avoid timeouts
+- **Be idempotent** - Handle duplicate deliveries gracefully
+- **Log everything** - Store raw events for debugging
+- **Alert on failures** - Monitor webhook processing errors
+- **Queue for processing** - Use a job queue for complex handling
+
+## Testing Webhooks
+
+**Local development:** Use ngrok or similar to expose localhost.
+
+```bash
+ngrok http 3000
+# Use the ngrok URL as your webhook endpoint
+```
+
+**Verify handling:** Send test events through Resend dashboard or manually trigger each event type.
+
+## Ingest webhooks for data storage
+- [Open source repo](https://github.com/resend/resend-webhooks-ingester)
+- [Why store data](https://resend.com/docs/dashboard/webhooks/how-to-store-webhooks-data)
+
+## Related
+
+- [List Management](./list-management.md) - What to do with bounce/complaint data
+- [Sending Reliability](./sending-reliability.md) - Retry logic when sends fail

package/dist/global-skills/email-best-practices/tests/README.md

@@ -0,0 +1,35 @@
+# Skill Tests
+
+Tests for the `email-best-practices` skill using the RED-GREEN methodology from [writing-skills](https://github.com/yourorg/writing-skills).
+
+## Skill Type
+
+This is a **reference/technique** skill (not discipline-enforcing), so tests focus on:
+
+- **Retrieval** — Does the agent find the right resource for a given problem?
+- **Application** — Does the agent produce correct, specific guidance?
+- **Gap** — Are common email scenarios adequately covered?
+
+## Test Scenarios
+
+| # | Scenario | Tests | Key Resource(s) |
+|---|----------|-------|-----------------|
+| 1 | Emails going to spam | Retrieval + Application | deliverability.md |
+| 2 | Multi-region compliance | Retrieval + Application | compliance.md |
+| 3 | Retry logic + idempotency | Application | sending-reliability.md |
+| 4 | Webhook bounce/complaint handling | Application | webhooks-events.md, list-management.md |
+| 5 | New SaaS email infrastructure | Retrieval + Application + Gap | All resources |
+
+## Running Tests
+
+Each scenario in `scenarios/` is a self-contained prompt. Run with a subagent:
+
+**RED (baseline):** Run the prompt as-is — no skill loaded. The agent uses only general knowledge.
+
+**GREEN (with skill):** Prepend: `You have access to an email best practices skill with resources in <path>. Read SKILL.md first, then read the relevant resource file(s).`
+
+Compare outputs against `results.md` for expected correctness criteria.
+
+## Results
+
+See `results.md` for the full RED vs GREEN comparison and gap analysis from the initial test campaign.

package/dist/global-skills/email-best-practices/tests/scenarios/01-spam-deliverability.md

@@ -0,0 +1,46 @@
+# Scenario 1: Emails Going to Spam
+
+## Prompt
+
+```
+You are an AI coding assistant. A developer asks you:
+
+"My transactional emails (password resets, order confirmations) are going to spam in Gmail. What do I do to fix this?"
+
+Answer with specific, actionable steps. Include exact DNS records, commands to verify, and threshold numbers where relevant.
+
+Format your response as a numbered action plan.
+```
+
+## Expected Correctness Criteria
+
+The agent MUST include these skill-specific details:
+
+### Authentication (deliverability.md)
+- [ ] SPF record example: `v=spf1 include:amazonses.com ~all`
+- [ ] DKIM: provider supplies the record
+- [ ] DMARC: `v=DMARC1; p=none; rua=mailto:dmarc@example.com`
+- [ ] DMARC rollout: `p=none` → `p=quarantine; pct=25` → `p=reject`
+- [ ] Verification commands: `dig TXT example.com +short`, `dig TXT resend._domainkey.example.com +short`, `dig TXT _dmarc.example.com +short`
+
+### Thresholds (deliverability.md)
+- [ ] Bounce targets: <1% good, 1-3% acceptable, 3-4% concerning, >4% critical
+- [ ] Complaint targets: <0.01% excellent, 0.01-0.05% good, >0.05% critical
+
+### IP Warming (deliverability.md)
+- [ ] Week 1: 50-100/day
+- [ ] Week 2: 200-500/day
+- [ ] Week 3: 1,000-2,000/day
+- [ ] Week 4: 5,000-10,000/day
+
+### Infrastructure (deliverability.md)
+- [ ] Dedicated subdomains: `t.example.com` (transactional), `m.example.com` (marketing)
+- [ ] DNS TTL: 300s during setup, 3600s+ after stable
+
+### Troubleshooting order (deliverability.md)
+- [ ] Check in order: 1. Authentication, 2. List-Unsubscribe header, 3. Reputation, 4. Content, 5. Sending patterns
+
+### Diagnostic tools (deliverability.md)
+- [ ] Google Postmaster Tools
+- [ ] mail-tester.com
+- [ ] MXToolbox blacklist check

package/dist/global-skills/email-best-practices/tests/scenarios/02-multi-region-compliance.md

@@ -0,0 +1,48 @@
+# Scenario 2: Multi-Region Email Compliance
+
+## Prompt
+
+```
+You are an AI coding assistant. A developer asks you:
+
+"I'm building an email newsletter for my SaaS product. I have users in the US, EU, and Canada. What legal requirements do I need to follow? Give me a comparison table of requirements by region and the specific implementation steps."
+
+Be specific about penalty amounts, timing requirements for unsubscribe processing, and consent record requirements.
+```
+
+## Expected Correctness Criteria
+
+### Penalties (compliance.md)
+- [ ] CAN-SPAM: $53k/email
+- [ ] GDPR: EUR 20M or 4% revenue
+- [ ] CASL: $1M (individual) to $10M (organization) CAD
+
+### Consent types (compliance.md)
+- [ ] CAN-SPAM: opt-out model (can send without opt-in)
+- [ ] GDPR: explicit opt-in (no pre-checked boxes)
+- [ ] CASL express: explicit opt-in
+- [ ] CASL implied: existing relationship (2 years) or inquiry (6 months)
+
+### Unsubscribe timing (compliance.md)
+- [ ] CAN-SPAM: 10 business days, must work 30 days after send
+- [ ] GDPR: immediately, as easy as opting in
+- [ ] CASL: 10 business days, must work 60 days after send
+
+### CASL specifics (compliance.md)
+- [ ] Sender identification valid 60 days after send
+- [ ] Keep consent records 3 years after expiration
+
+### Consent records (compliance.md)
+- [ ] Record: email, date/time, method, what consented to, source
+
+### International sending (compliance.md)
+- [ ] Best practice: follow GDPR (most restrictive) for all regions
+
+### Managing preferences vs unsubscribe (compliance.md)
+- [ ] One-click unsubscribe required; preference management is nice-to-have, doesn't replace unsubscribe
+
+### List-Unsubscribe header (compliance.md)
+- [ ] Required by Gmail/Yahoo since Feb 2024
+- [ ] Headers: `List-Unsubscribe` URL + `List-Unsubscribe-Post: List-Unsubscribe=One-Click`
+- [ ] Endpoint: POST returns 200/202, GET shows unsubscribe page
+- [ ] Stop sending within 48 hours

package/dist/global-skills/email-best-practices/tests/scenarios/03-retry-idempotency.md

@@ -0,0 +1,36 @@
+# Scenario 3: Retry Logic + Idempotency
+
+## Prompt
+
+```
+You are an AI coding assistant. A developer asks you:
+
+"I'm using the Resend API to send transactional emails. I need to implement retry logic with idempotency to prevent duplicate sends. Show me a TypeScript implementation with idempotency keys, exponential backoff, and proper error code handling."
+
+Include specific HTTP error codes and which ones to retry vs not retry, idempotency key generation strategies, and backoff timing.
+```
+
+## Expected Correctness Criteria
+
+### Idempotency keys (sending-reliability.md)
+- [ ] Event-based key example: `order-confirm-${orderId}` (recommended)
+- [ ] Request-scoped example: `reset-${userId}-${resetRequestId}`
+- [ ] UUID fallback: `crypto.randomUUID()` — generate once, reuse on retry
+- [ ] Warns against `Date.now()` or random values generated fresh on each attempt
+- [ ] Key expiration: 24 hours — complete retry logic within this window
+
+### Error codes (sending-reliability.md)
+- [ ] Retry: 5xx (server error), 429 (rate limit), network timeout, DNS failure
+- [ ] Do NOT retry: 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 422 (validation)
+
+### Backoff (sending-reliability.md)
+- [ ] Exponential: 1s -> 2s -> 4s -> 8s
+- [ ] Cap at 30 seconds
+- [ ] Jitter to prevent thundering herd
+- [ ] Max retries: 3
+
+### Timeout (sending-reliability.md)
+- [ ] AbortController pattern with 10-30 second timeout
+
+### Queuing (sending-reliability.md)
+- [ ] Queue pattern for critical emails: write pending -> attempt send -> mark sent/schedule retry -> mark failed + alert

package/dist/global-skills/email-best-practices/tests/scenarios/04-webhook-bounce-handling.md

@@ -0,0 +1,52 @@
+# Scenario 4: Webhook Bounce/Complaint Handling
+
+## Prompt
+
+```
+You are an AI coding assistant. A developer asks you:
+
+"I need to set up Resend webhooks to handle bounces and complaints. Show me how to implement this with signature verification using svix, idempotent event processing, and proper bounce/complaint handling (when to suppress, when to retry). Include TypeScript code."
+
+Be specific about: svix verification headers, hard vs soft bounce handling thresholds, and complaint handling requirements.
+```
+
+## Expected Correctness Criteria
+
+### Webhook setup (webhooks-events.md)
+- [ ] Endpoint must return 2xx within 5 seconds
+- [ ] Return 200 immediately, process asynchronously
+
+### Svix verification (webhooks-events.md)
+- [ ] Import from 'svix'
+- [ ] Headers: `svix-id`, `svix-timestamp`, `svix-signature`
+- [ ] Verify before processing, return 400 on invalid signature
+
+### Idempotent processing (webhooks-events.md)
+- [ ] Use event ID to deduplicate
+- [ ] Check if already processed before handling
+- [ ] Mark as processed after handling
+
+### Event types (webhooks-events.md)
+- [ ] `email.sent`, `email.delivered`, `email.bounced`, `email.complained`, `email.opened`, `email.clicked`
+
+### Bounce handling (webhooks-events.md + list-management.md)
+- [ ] Hard bounce: suppress immediately, remove from all lists
+- [ ] Soft bounce: track count, suppress after 3 failures
+- [ ] Suppression entry schema includes: email, reason, created_at, source_email_id
+
+### Complaint handling (webhooks-events.md + list-management.md)
+- [ ] Immediate suppression — no exceptions
+- [ ] Remove from all lists
+- [ ] Log for analysis
+
+### Suppression unsuppress rules (list-management.md)
+- [ ] Hard bounce: cannot unsuppress (address invalid)
+- [ ] Complaint: cannot unsuppress (legal requirement)
+- [ ] Soft bounce (3x): can unsuppress after 30-90 days
+- [ ] Manual removal: only if user requests
+
+### Pre-send check (list-management.md)
+- [ ] Always check suppression before sending
+
+### Retry behavior (webhooks-events.md)
+- [ ] Non-2xx triggers retries: ~30s -> ~1min -> ~5min (continues ~24 hours)

package/dist/global-skills/email-best-practices/tests/scenarios/05-new-saas-email-plan.md

@@ -0,0 +1,51 @@
+# Scenario 5: New SaaS Email Infrastructure Plan
+
+## Prompt
+
+```
+You are an AI coding assistant. A developer asks you:
+
+"I'm building a new SaaS app and need to plan my entire email infrastructure. I need to know: (1) what types of transactional emails I should plan for, (2) how to set up DNS authentication, (3) how to warm up my sending domain, (4) how to handle bounces/complaints in production, and (5) what compliance requirements I need for international users. Give me a comprehensive implementation roadmap."
+
+Be specific about: IP warming schedules (daily volumes by week), bounce rate thresholds, complaint rate thresholds, DNS record formats, and legal requirements by region.
+```
+
+## Expected Correctness Criteria
+
+### Email planning (transactional-email-catalog.md)
+- [ ] References the transactional email catalog for SaaS planning
+- [ ] Covers at minimum: verification, password reset, OTP/2FA, security alerts, billing
+
+### DNS authentication (deliverability.md)
+- [ ] SPF, DKIM, DMARC records with examples
+- [ ] DMARC rollout strategy (none -> quarantine; pct=25 -> reject)
+- [ ] Dedicated subdomains for transactional vs marketing
+
+### Warming (deliverability.md)
+- [ ] Correct weekly schedule: 50-100 / 200-500 / 1k-2k / 5k-10k
+- [ ] Start with engaged users, send consistently
+
+### Bounce/complaint handling (deliverability.md + list-management.md + webhooks-events.md)
+- [ ] Bounce thresholds: <1% good, >4% critical
+- [ ] Complaint thresholds: <0.01% excellent, >0.05% critical
+- [ ] Hard bounce: immediate suppression
+- [ ] Soft bounce: suppress after 3 failures
+- [ ] Complaint: immediate suppression
+- [ ] Pre-send suppression check
+
+### Compliance (compliance.md)
+- [ ] Covers CAN-SPAM, GDPR, CASL
+- [ ] Correct penalty amounts
+- [ ] Correct unsubscribe timing by region
+- [ ] Recommends GDPR as global standard
+
+### Data retention (list-management.md)
+- [ ] Send attempts: 90 days
+- [ ] Bounce/complaint events: 3 years
+- [ ] Suppression list: indefinite
+- [ ] Email content: 30 days
+- [ ] Consent records: 3 years after expiry
+
+### Cross-resource synthesis
+- [ ] Agent references multiple resource files (not just one)
+- [ ] "Start Here" routing from SKILL.md is followed

package/dist/global-skills/expo-animation/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emil Kowalski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.