npm - opencodekit - Versions diffs - 0.15.20 → 0.16.0 - Mend

opencodekit 0.15.20 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (606) hide show

package/dist/template/.opencode/skill/resend/references/react-email.md ADDED Viewed

@@ -0,0 +1,287 @@
+# React Email
+Build and send HTML emails using React components. A modern, component-based approach to email development that works across all major email clients by compiling to compatible HTML.
+## When to Use
+- Creating transactional emails (welcome, password reset, order confirmation)
+- Building notification or marketing email templates
+- Need consistent rendering across Gmail, Outlook, Apple Mail, Yahoo
+- Want component reusability and TypeScript support in emails
+- Integrating with email providers like Resend, SendGrid, Postmark
+**When NOT to use:**
+- Simple plain-text emails
+- Emails that don't need cross-client compatibility
+- Projects without React/Node.js
+## Installation
+### New Project
+```bash
+npx create-email@latest
+cd react-email-starter
+npm install
+npm run dev
+```
+The server runs at localhost:3000 with a preview interface for templates in the `emails` folder.
+### Existing Project
+```bash
+npm install react-email @react-email/preview-server -D -E
+npm install @react-email/components react react-dom -E
+```
+Add script to package.json:
+```json
+{
+  "scripts": {
+    "email:dev": "email dev --dir src/emails"
+  }
+}
+```
+## Basic Email Template
+```tsx
+import {
+  Html,
+  Head,
+  Preview,
+  Body,
+  Container,
+  Heading,
+  Text,
+  Button,
+  Tailwind,
+  pixelBasedPreset,
+} from "@react-email/components";
+interface WelcomeEmailProps {
+  name: string;
+  verificationUrl: string;
+}
+export default function WelcomeEmail({ name, verificationUrl }: WelcomeEmailProps) {
+  return (
+    <Html lang="en">
+      <Tailwind
+        config={{
+          presets: [pixelBasedPreset],
+          theme: {
+            extend: {
+              colors: {
+                brand: "#007bff",
+              },
+            },
+          },
+        }}
+      >
+        <Head />
+        <Body className="bg-gray-100 font-sans">
+          <Preview>Welcome - Verify your email</Preview>
+          <Container className="max-w-xl mx-auto p-5">
+            <Heading className="text-2xl text-gray-800">Welcome!</Heading>
+            <Text className="text-base text-gray-800">Hi {name}, thanks for signing up!</Text>
+            <Button
+              href={verificationUrl}
+              className="bg-brand text-white px-5 py-3 rounded block text-center no-underline box-border"
+            >
+              Verify Email
+            </Button>
+          </Container>
+        </Body>
+      </Tailwind>
+    </Html>
+  );
+}
+WelcomeEmail.PreviewProps = {
+  name: "John Doe",
+  verificationUrl: "https://example.com/verify/abc123",
+} satisfies WelcomeEmailProps;
+export { WelcomeEmail };
+```
+## Essential Components
+**Core Structure:**
+- `Html` - Root wrapper with `lang` attribute
+- `Head` - Meta elements, styles, fonts
+- `Body` - Main content wrapper
+- `Container` - Centers content (max-width layout)
+- `Section` - Layout sections
+- `Row` & `Column` - Multi-column layouts (table-based)
+- `Tailwind` - Enables Tailwind CSS utility classes
+**Content:**
+- `Preview` - Inbox preview text (place after `Body` opening tag)
+- `Heading` - h1-h6 headings
+- `Text` - Paragraphs
+- `Button` - Styled link buttons
+- `Link` - Hyperlinks
+- `Img` - Images (use absolute URLs)
+- `Hr` - Horizontal dividers
+**Specialized:**
+- `CodeBlock` - Syntax-highlighted code
+- `CodeInline` - Inline code
+- `Markdown` - Render markdown
+- `Font` - Custom web fonts
+## Styling Rules
+### Always Do
+| Rule                           | Why                                           |
+| ------------------------------ | --------------------------------------------- |
+| Use `pixelBasedPreset`         | Email clients don't support `rem` units       |
+| Use `Row`/`Column` for layouts | Table-based layouts work everywhere           |
+| Specify border type            | Always: `border-solid`, `border-dashed`, etc. |
+| Use `box-border` on buttons    | Consistent sizing                             |
+| Use PNG/JPEG images            | SVG/WEBP not supported                        |
+| Use absolute image URLs        | Relative paths won't work                     |
+### Never Do
+| Rule                             | Why                                      |
+| -------------------------------- | ---------------------------------------- |
+| Use flexbox/grid                 | Not supported in email clients           |
+| Use media queries (`sm:`, `md:`) | Most email clients ignore them           |
+| Use theme selectors (`dark:`)    | Inconsistent support                     |
+| Use SVG/WEBP images              | Not supported                            |
+| Write template vars in JSX       | Use props: `{props.name}` not `{{name}}` |
+## Rendering
+### Convert to HTML
+```tsx
+import { render } from "@react-email/components";
+import { WelcomeEmail } from "./emails/welcome";
+const html = await render(
+  <WelcomeEmail name="John" verificationUrl="https://example.com/verify" />,
+);
+```
+### Convert to Plain Text
+```tsx
+const text = await render(
+  <WelcomeEmail name="John" verificationUrl="https://example.com/verify" />,
+  { plainText: true },
+);
+```
+## Sending with Resend
+```tsx
+import { Resend } from "resend";
+import { WelcomeEmail } from "./emails/welcome";
+const resend = new Resend(process.env.RESEND_API_KEY);
+const { data, error } = await resend.emails.send({
+  from: "Acme <onboarding@resend.dev>",
+  to: ["user@example.com"],
+  subject: "Welcome to Acme",
+  react: <WelcomeEmail name="John" verificationUrl="https://example.com/verify" />,
+});
+if (error) {
+  console.error("Failed to send:", error);
+}
+```
+Resend accepts React components directly. It automatically generates a plain-text version if not provided.
+## Common Patterns
+### Responsive Container
+```tsx
+<Container className="max-w-xl mx-auto p-5">
+  {/* Content stays centered and readable on all devices */}
+</Container>
+```
+### Two-Column Layout
+```tsx
+<Row>
+  <Column className="w-1/2">
+    <Text>Left content</Text>
+  </Column>
+  <Column className="w-1/2">
+    <Text>Right content</Text>
+  </Column>
+</Row>
+```
+**Note:** Columns won't stack on mobile. Design with this in mind.
+### CTA Button
+```tsx
+<Button
+  href="https://example.com"
+  className="bg-blue-600 text-white px-6 py-3 rounded block text-center no-underline box-border"
+>
+  Click Here
+</Button>
+```
+### Footer with Links
+```tsx
+<Section className="text-center text-gray-500 text-sm">
+  <Text>
+    <Link href="https://example.com/unsubscribe" className="text-gray-500 underline">
+      Unsubscribe
+    </Link>
+    {" | "}
+    <Link href="https://example.com/preferences" className="text-gray-500 underline">
+      Preferences
+    </Link>
+  </Text>
+  <Text>123 Main St, City, State 12345</Text>
+</Section>
+```
+## Best Practices
+1. **Test across clients** - Gmail, Outlook, Apple Mail, Yahoo
+2. **Keep responsive** - Max-width ~600px
+3. **Use absolute image URLs** - Host on reliable CDN
+4. **Provide plain text version** - Required for accessibility
+5. **Add TypeScript types** - Define interfaces for all props
+6. **Include PreviewProps** - For development testing
+7. **Keep under 102KB** - Gmail clips larger emails
+## Common Mistakes
+| Mistake                           | Fix                                      |
+| --------------------------------- | ---------------------------------------- |
+| Using flexbox/grid                | Use `Row` and `Column` components        |
+| Using `rem` units                 | Use `pixelBasedPreset` with Tailwind     |
+| Using SVG images                  | Use PNG or JPG instead                   |
+| Using media queries               | Design mobile-first with stacked layouts |
+| Template vars in JSX (`{{name}}`) | Use props: `{props.name}`                |
+| Missing border type               | Always specify: `border-solid`, etc.     |
+| Emails over 102KB                 | Gmail clips - reduce size                |
+## Resources
+- [React Email Documentation](https://react.email/docs)
+- [React Email GitHub](https://github.com/resend/react-email)
+- [Email Client CSS Support](https://www.caniemail.com)

package/dist/template/.opencode/skill/resend/references/receive-email.md ADDED Viewed

@@ -0,0 +1,248 @@
+# Receive Emails with Resend
+## Overview
+Resend processes incoming emails for your domain and sends webhook events to your endpoint. **Webhooks contain metadata only** - you must call separate APIs to retrieve email body and attachments.
+## Quick Start
+1. **Configure receiving domain** - Use Resend's `.resend.app` domain or add MX record for custom domain
+2. **Set up webhook** - Subscribe to `email.received` event
+3. **Retrieve content** - Call Receiving API for body, Attachments API for files
+## Domain Setup
+### Option 1: Resend-Managed Domain (Fastest)
+Use your auto-generated address: `<anything>@<your-id>.resend.app`
+No DNS configuration needed. Find your address in Dashboard -> Emails -> Receiving -> "Receiving address".
+### Option 2: Custom Domain
+Add MX record to receive at `<anything>@yourdomain.com`.
+| Setting      | Value                        |
+| ------------ | ---------------------------- |
+| **Type**     | MX                           |
+| **Host**     | Your domain or subdomain     |
+| **Value**    | Provided in Resend dashboard |
+| **Priority** | 10 (lowest number wins)      |
+**Critical:** Your MX record must have the lowest priority value, or emails won't route to Resend.
+### Subdomain Recommendation
+If you already have MX records (e.g., Google Workspace, Microsoft 365):
+| Approach                        | Result                                                        |
+| ------------------------------- | ------------------------------------------------------------- |
+| **Use subdomain** (recommended) | `support.acme.com` -> Resend, `acme.com` -> existing provider |
+| **Use root domain**             | All email routes to Resend (breaks existing email)            |
+```dns
+# Receive at support.acme.com without affecting acme.com
+support.acme.com.  MX  10  <resend-mx-value>
+```
+## Webhook Setup
+### Subscribe to `email.received`
+Dashboard -> Webhooks -> Add Webhook -> Select `email.received`
+For local development, use tunneling:
+```bash
+ngrok http 3000
+# Use https://abc123.ngrok.io/api/webhook as endpoint
+```
+### Webhook Payload Structure
+**Important:** Payload contains metadata only, not email body or attachments.
+```json
+{
+  "type": "email.received",
+  "created_at": "2024-02-22T23:41:12.126Z",
+  "data": {
+    "email_id": "a1b2c3d4-...",
+    "from": "sender@example.com",
+    "to": ["support@acme.com"],
+    "cc": [],
+    "bcc": [],
+    "subject": "Question about my order",
+    "attachments": [
+      {
+        "id": "att_abc123",
+        "filename": "receipt.pdf",
+        "content_type": "application/pdf"
+      }
+    ]
+  }
+}
+```
+### Verify Webhook Signatures
+Always verify signatures to prevent spoofed events:
+```typescript
+import { Resend } from "resend";
+const resend = new Resend(process.env.RESEND_API_KEY);
+export async function POST(req: Request) {
+  const payload = await req.text();
+  const event = resend.webhooks.verify({
+    payload,
+    headers: {
+      "svix-id": req.headers.get("svix-id"),
+      "svix-timestamp": req.headers.get("svix-timestamp"),
+      "svix-signature": req.headers.get("svix-signature"),
+    },
+    secret: process.env.RESEND_WEBHOOK_SECRET,
+  });
+  if (event.type === "email.received") {
+    // Process the email
+  }
+  return new Response("OK", { status: 200 });
+}
+```
+## Retrieving Email Content
+Webhooks exclude email body. Call the Receiving API:
+```typescript
+if (event.type === "email.received") {
+  const { data: email } = await resend.emails.receiving.get(event.data.email_id);
+  console.log(email.html); // HTML body
+  console.log(email.text); // Plain text body
+  console.log(email.headers); // Email headers
+}
+```
+**Why this design?** Serverless environments have request body size limits. Separating content retrieval supports large emails and attachments.
+## Handling Attachments
+### Get Attachment Metadata and Download URLs
+```typescript
+const { data: attachments } = await resend.emails.receiving.attachments.list({
+  emailId: event.data.email_id,
+});
+for (const attachment of attachments) {
+  console.log(attachment.filename);
+  console.log(attachment.download_url); // Valid for 1 hour
+  console.log(attachment.expires_at);
+}
+```
+### Download Attachment Content
+```typescript
+const response = await fetch(attachment.download_url);
+const buffer = await response.arrayBuffer();
+// Save to storage, process, etc.
+await saveToStorage(attachment.filename, buffer);
+```
+**Important:** `download_url` expires after 1 hour. Call the API again for a fresh URL if needed.
+## Forwarding Emails
+Complete workflow to receive and forward an email with attachments:
+```typescript
+import { Resend } from "resend";
+const resend = new Resend(process.env.RESEND_API_KEY);
+export async function POST(req: Request) {
+  const payload = await req.text();
+  const event = resend.webhooks.verify({
+    /* ... */
+  });
+  if (event.type === "email.received") {
+    // 1. Get email content
+    const { data: email } = await resend.emails.receiving.get(event.data.email_id);
+    // 2. Get attachments (if any)
+    const { data: attachmentList } = await resend.emails.receiving.attachments.list({
+      emailId: event.data.email_id,
+    });
+    // 3. Download and encode attachments
+    const attachments = await Promise.all(
+      attachmentList.map(async (att) => {
+        const res = await fetch(att.download_url);
+        const buffer = Buffer.from(await res.arrayBuffer());
+        return {
+          filename: att.filename,
+          content: buffer.toString("base64"),
+        };
+      }),
+    );
+    // 4. Forward the email
+    await resend.emails.send({
+      from: "Support System <system@acme.com>",
+      to: ["team@acme.com"],
+      subject: `Fwd: ${email.subject}`,
+      html: email.html,
+      text: email.text,
+      attachments,
+    });
+  }
+  return new Response("OK", { status: 200 });
+}
+```
+## Routing by Recipient
+All emails to your domain arrive at the same webhook. Route based on the `to` field:
+```typescript
+if (event.type === "email.received") {
+  const recipient = event.data.to[0];
+  if (recipient.includes("support@")) {
+    await handleSupportEmail(event.data);
+  } else if (recipient.includes("billing@")) {
+    await handleBillingEmail(event.data);
+  } else {
+    await handleUnknownEmail(event.data);
+  }
+}
+```
+## Common Mistakes
+| Mistake                                      | Fix                                                              |
+| -------------------------------------------- | ---------------------------------------------------------------- |
+| Expecting body in webhook payload            | Webhook has metadata only - call `resend.emails.receiving.get()` |
+| MX record not lowest priority                | Ensure Resend's MX has lowest number (highest priority)          |
+| Adding MX to root domain with existing email | Use subdomain to avoid breaking existing email service           |
+| Using expired download_url                   | URLs expire after 1 hour - call attachments API again            |
+| Not verifying webhook signatures             | Always verify - attackers can send fake events                   |
+| Forgetting to return 200 OK                  | Resend retries on non-200 responses                              |
+## Storage Note
+Resend stores received emails even if:
+- Webhook isn't configured yet
+- Webhook endpoint is down
+View all received emails in Dashboard -> Emails -> Receiving tab.