vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/resend/references/broadcasts.md

@@ -0,0 +1,125 @@
+# Broadcasts
+
+Send emails to audience segments. Broadcasts follow a two-step lifecycle: **create** (draft) then **send**.
+
+## SDK Methods
+
+| Operation | Node.js | Python |
+|-----------|---------|--------|
+| Create | `resend.broadcasts.create(params)` | `resend.Broadcasts.create(params)` |
+| Get | `resend.broadcasts.get(id)` | `resend.Broadcasts.get(id)` |
+| List | `resend.broadcasts.list(params)` | `resend.Broadcasts.list(params)` |
+| Send | `resend.broadcasts.send(id, params?)` | `resend.Broadcasts.send(params)` |
+| Update | `resend.broadcasts.update(id, params)` | `resend.Broadcasts.update(params)` |
+| Delete | `resend.broadcasts.remove(id)` | `resend.Broadcasts.remove(id)` |
+
+## Create Parameters
+
+**Required:** `name`, `from`, `subject`, `segmentId`, and one of `html` / `text` / `react`
+
+**Optional:** `topicId`, `previewText`, `replyTo`, `send` (boolean), `scheduledAt`
+
+## Lifecycle: Create then Send
+
+```typescript
+import { Resend } from 'resend';
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+// Step 1: Create a draft broadcast
+const { data: broadcast, error: createError } = await resend.broadcasts.create({
+  name: 'March Newsletter',
+  from: 'Acme <news@acme.com>',
+  subject: 'Hi {{{FIRST_NAME|there}}}, here is your March update',
+  html: '<p>Hi {{{FIRST_NAME|there}}}</p><a href="{{{RESEND_UNSUBSCRIBE_URL}}}">Unsubscribe</a>',
+  segmentId: 'seg_abc123',
+  topicId: 'top_xyz789',     // optional: controls topic-level unsubscribes
+});
+
+if (createError) {
+  console.error(createError);
+  return;
+}
+
+// Step 2: Send it (or schedule)
+const { data: sent, error: sendError } = await resend.broadcasts.send(broadcast.id, {
+  scheduledAt: 'in 1 hour',  // optional: ISO 8601 or natural language
+});
+
+if (sendError) {
+  console.error(sendError);
+  return;
+}
+```
+
+### Shortcut: Create and Send in One Call
+
+Pass `send: true` on create to skip the separate send call:
+
+```typescript
+const { data, error } = await resend.broadcasts.create({
+  name: 'Flash Sale',
+  from: 'Acme <deals@acme.com>',
+  subject: 'Flash sale - 24 hours only',
+  html: '<p>Shop now!</p>',
+  segmentId: 'seg_abc123',
+  send: true,
+});
+```
+
+## Get, List, Update, Delete
+
+```typescript
+// Get
+const { data, error } = await resend.broadcasts.get('bc_abc123');
+
+// List with pagination
+const { data, error } = await resend.broadcasts.list({ limit: 10, offset: 0 });
+
+// Update a draft
+const { data, error } = await resend.broadcasts.update('bc_abc123', {
+  subject: 'Updated subject line',
+});
+
+// Delete a draft (only works on drafts)
+const { data, error } = await resend.broadcasts.remove('bc_abc123');
+```
+
+## Python Example
+
+```python
+import resend
+
+resend.api_key = "re_xxxxxxxxx"
+
+broadcast = resend.Broadcasts.create({
+    "name": "March Newsletter",
+    "from": "Acme <news@acme.com>",
+    "subject": "Your March update",
+    "html": "<p>Hello!</p>",
+    "segment_id": "seg_abc123",
+})
+
+resend.Broadcasts.send({"broadcast_id": broadcast["id"]})
+```
+
+## Contact Property Interpolation
+
+Use triple-mustache with a pipe for fallbacks: `{{{PROPERTY_KEY|fallback}}}`
+
+```html
+<p>Hi {{{FIRST_NAME|there}}}, your balance is {{{BALANCE|0}}}.</p>
+<a href="{{{RESEND_UNSUBSCRIBE_URL}}}">Unsubscribe</a>
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Expecting `create` to send the broadcast | `create` makes a draft. Call `send` separately, or pass `send: true` |
+| Calling `.delete()` instead of `.remove()` | Node.js SDK uses `.remove()` for all delete operations |
+| Deleting a sent/scheduled broadcast | Only drafts can be deleted |
+| Missing `segmentId` | Required — broadcasts target segments, not all contacts |
+| Missing unsubscribe link | Include `{{{RESEND_UNSUBSCRIBE_URL}}}` in HTML |
+| `{{VAR}}` instead of `{{{VAR}}}` | Triple braces required for variable interpolation |
+| Ignoring `error` return | Node.js SDK returns `{ data, error }` — always check `error` |
+| `scheduledAt` format confusion | Accepts both ISO 8601 (`2025-03-15T10:00:00Z`) and natural language (`in 1 hour`) |

package/dist/global-skills/resend/references/contact-properties.md

@@ -0,0 +1,111 @@
+# Contact Properties
+
+Define custom properties that can be set on contacts and interpolated in broadcast HTML. Properties are account-wide — they apply across all segments.
+
+## SDK Methods
+
+| Operation | Node.js | Python |
+|-----------|---------|--------|
+| Create | `resend.contactProperties.create(params)` | `resend.ContactProperties.create(params)` |
+| Get | `resend.contactProperties.get(id)` | `resend.ContactProperties.get(id)` |
+| List | `resend.contactProperties.list(params?)` | `resend.ContactProperties.list()` |
+| Update | `resend.contactProperties.update(params)` | `resend.ContactProperties.update(params)` |
+| Delete | `resend.contactProperties.remove(id)` | `resend.ContactProperties.remove(id)` |
+
+## Create Parameters
+
+**Required:** `key`, `type`
+
+**Optional:** `fallbackValue`
+
+- `type`: `"string"` or `"number"` — **immutable** after creation
+- `key`: alphanumeric + underscores, max 50 chars — **immutable** after creation
+- `fallbackValue`: used when a contact lacks a value for this property (must match `type`)
+
+## Node.js Example
+
+```typescript
+import { Resend } from 'resend';
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+// Create a property
+const { data, error } = await resend.contactProperties.create({
+  key: 'company_name',
+  type: 'string',
+  fallbackValue: 'your company',
+});
+
+if (error) {
+  console.error(error);
+  return;
+}
+
+// Get, list, update, delete
+const { data: prop } = await resend.contactProperties.get(data.id);
+
+const { data: props } = await resend.contactProperties.list();
+
+// Only fallbackValue can be updated
+const { data: updated } = await resend.contactProperties.update({
+  id: data.id,
+  fallbackValue: 'your organization',
+});
+
+const { data: deleted } = await resend.contactProperties.remove(data.id);
+```
+
+## Python Example
+
+```python
+import resend
+
+resend.api_key = "re_xxxxxxxxx"
+
+prop = resend.ContactProperties.create({
+    "key": "company_name",
+    "type": "string",
+    "fallback_value": "your company",
+})
+
+# Only fallback_value can be updated
+resend.ContactProperties.update({
+    "id": prop["id"],
+    "fallback_value": "your organization",
+})
+```
+
+## Setting Properties on Contacts
+
+Pass a `properties` object when creating or updating contacts:
+
+```typescript
+const { data, error } = await resend.contacts.create({
+  email: 'alice@example.com',
+  properties: {
+    company_name: 'Acme Corp',
+    plan_tier: 'enterprise',
+  },
+});
+```
+
+## Using in Broadcast HTML
+
+Use triple-mustache syntax with a pipe for fallbacks:
+
+```html
+<p>Hi {{{FIRST_NAME|there}}}, welcome from {{{company_name|your company}}}!</p>
+```
+
+The fallback after the pipe overrides the property-level `fallbackValue` for that specific broadcast.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Trying to change `key` or `type` after creation | Both are immutable — delete and recreate if wrong |
+| Updating fields other than `fallbackValue` | Only `fallbackValue` can be updated via the API |
+| `fallbackValue` type mismatch | Must match the property `type` (string value for string property, number for number) |
+| `{{VAR}}` instead of `{{{VAR}}}` in broadcast HTML | Triple braces required |
+| Special characters in key | Only alphanumeric characters and underscores allowed |
+| Calling `.delete()` instead of `.remove()` | Node.js SDK uses `.remove()` for all delete operations |
+| Ignoring `error` return | Node.js SDK returns `{ data, error }` — always check `error` |

package/dist/global-skills/resend/references/contacts.md

@@ -0,0 +1,174 @@
+# Contacts
+
+## Overview
+
+Contacts represent email recipients stored in Resend. They support custom properties, segment assignment, and topic subscriptions for managing audiences and preferences.
+
+## SDK Methods
+
+### Node.js
+
+| Operation | Method | Notes |
+|-----------|--------|-------|
+| Create | `resend.contacts.create(params)` | Add a contact with properties, segments, topics |
+| Get | `resend.contacts.get({ id })` or `resend.contacts.get({ email })` | Lookup by ID or email |
+| List | `resend.contacts.list({ limit?, offset?, segmentId? })` | Filter by segment |
+| Update | `resend.contacts.update(params)` | By `id` or `email` |
+| Delete | `resend.contacts.remove({ id })` or `resend.contacts.remove({ email })` | Not `.delete()` |
+
+### Python
+
+`resend.Contacts.create/get/list/update/remove` — same operations with snake_case params (e.g., `first_name`, `last_name`, `segment_id`).
+
+## Create Contact
+
+```typescript
+const { data, error } = await resend.contacts.create({
+  email: 'alice@example.com',
+  firstName: 'Alice',
+  lastName: 'Smith',
+  unsubscribed: false,
+  properties: {
+    plan: 'enterprise',
+    company: 'Acme Corp',
+    signupDate: '2026-01-15',
+  },
+  segments: [{ id: 'seg_abc123' }],
+  topics: [
+    { id: 'topic_product_updates', subscription: 'opt_in' },
+    { id: 'topic_marketing', subscription: 'opt_out' },
+  ],
+});
+if (error) {
+  console.error(error);
+  return;
+}
+console.log(data.id); // contact ID
+```
+
+```python
+contact = resend.Contacts.create({
+    "email": "alice@example.com",
+    "first_name": "Alice",
+    "last_name": "Smith",
+    "unsubscribed": False,
+    "properties": {
+        "plan": "enterprise",
+        "company": "Acme Corp",
+    },
+})
+
+# Add to segment separately (Python SDK doesn't support segments/topics on create)
+resend.Contacts.Segments.add({"contact_id": contact["id"], "segment_id": "seg_abc123"})
+```
+
+## Get and Update
+
+```typescript
+// Get by email (alternative: pass { id: 'contact_uuid' })
+const { data, error } = await resend.contacts.get({ email: 'alice@example.com' });
+
+// Update by email — change properties, set a property to null to delete it
+const { data: updated, error: updateErr } = await resend.contacts.update({
+  email: 'alice@example.com',
+  firstName: 'Alicia',
+  properties: {
+    plan: 'pro',       // update existing property
+    company: null,     // delete this property
+  },
+});
+```
+
+## Delete and List
+
+```typescript
+// Delete by ID or email — pick one
+const { data, error } = await resend.contacts.remove({ email: 'alice@example.com' });
+
+// List with segment filter
+const { data: contacts, error: listErr } = await resend.contacts.list({
+  segmentId: 'seg_abc123',
+  limit: 50,
+});
+```
+
+## Bulk Import from CSV
+
+Import many contacts at once from a CSV file (`POST /contacts/imports`, `multipart/form-data`). Imports run **asynchronously**: `create` returns an import id immediately, then poll `get` until `status` is `completed` (or `failed`).
+
+### SDK Methods (Node.js)
+
+| Operation | Method | Notes |
+|-----------|--------|-------|
+| Create | `resend.contacts.imports.create({ file, columnMap?, onConflict?, segments?, topics? })` | `file` is a `Blob`/`File` (CSV). Returns `{ id }` |
+| Get | `resend.contacts.imports.get(id)` | Status + counts. `id` is a positional string — not `{ id }` |
+| List | `resend.contacts.imports.list({ limit?, after?, before?, status? })` | `status` filters by `queued` / `in_progress` / `completed` / `failed` |
+
+```typescript
+import { readFile } from 'node:fs/promises';
+
+const file = new Blob([await readFile('contacts.csv')], { type: 'text/csv' });
+
+const { data, error } = await resend.contacts.imports.create({
+  file,
+  // 'upsert' (default) updates existing contacts; 'skip' leaves them unchanged
+  onConflict: 'upsert',
+  segments: [{ id: 'seg_abc123' }],
+});
+if (error) {
+  console.error(error);
+  return;
+}
+
+// Imports are async — poll until processing finishes
+const { data: imp } = await resend.contacts.imports.get(data.id);
+console.log(imp.status, imp.counts);
+// e.g. 'completed' { total: 1200, created: 800, updated: 300, skipped: 75, failed: 25 }
+
+// List past imports, newest first; filter by status and paginate with after/before
+const { data: imports } = await resend.contacts.imports.list({ status: 'completed', limit: 20 });
+```
+
+### CSV columns
+
+Without `columnMap`, columns are matched by the lowercase names `email` (required), `first_name`, `last_name`, `unsubscribed` — **matching is case-sensitive**, so a CSV with `Email` / `First Name` headers returns `422 validation_error` ("CSV missing required email column"). Map non-standard headers explicitly:
+
+```typescript
+await resend.contacts.imports.create({
+  file,
+  columnMap: {
+    email: 'Email',
+    firstName: 'First Name',
+    lastName: 'Last Name',
+    properties: { plan: { column: 'Plan', type: 'string' } },
+  },
+});
+```
+
+> The SDK accepts camelCase (`firstName`, `lastName`); the raw `multipart/form-data` field is `column_map` with snake_case keys (`first_name`, `last_name`). `column_map`, `segments`, and `topics` are sent as JSON-encoded strings. Maximum file size is 100 MB.
+
+Properties that aren't already defined on your contacts are created automatically when you map them in the import; no need to pre-register them.
+
+### Raw HTTP
+
+```bash
+curl -X POST 'https://api.resend.com/contacts/imports' \
+  -H 'Authorization: Bearer re_xxxxxxxxx' \
+  -F 'file=@contacts.csv;type=text/csv' \
+  -F 'column_map={"email":"Email","first_name":"First Name"}' \
+  -F 'on_conflict=upsert'
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Passing both `id` and `email` to get/update/remove | Use one or the other — not both |
+| Using `audienceId` (Node.js) | Segments replaced audiences — use `segmentId`. Python SDK still uses `audience_id` in create params |
+| Calling `.delete()` | SDK method is `.remove()` |
+| Expecting property deletion with empty string | Set property value to `null` to delete it |
+| Not checking `error` in Node.js | SDK returns `{ data, error }`, does not throw — always destructure and check |
+| Forgetting `email` is required on create | `email` is the only required field — all others are optional |
+| CSV import returns 422 "missing required email column" | Column matching is case-sensitive lowercase (`email`, `first_name`, `last_name`) — pass `columnMap` for headers like `Email` / `First Name` |
+| Calling `imports.get({ id })` | `imports.get(id)` takes a positional string, unlike `contacts.get({ id })` |
+| Treating an import as synchronous | `create` returns an id immediately — poll `imports.get(id)` until `status` is `completed` |

package/dist/global-skills/resend/references/domains.md

@@ -0,0 +1,179 @@
+# Domains
+
+## Overview
+
+Domains must be verified before sending. The workflow is: create domain, add DNS records to your provider, call verify, then poll until verified.
+
+```
+Create → Add DNS records → Verify → Poll status → Send
+```
+
+## SDK Methods
+
+### Node.js
+
+| Operation | Method | Notes |
+|-----------|--------|-------|
+| Create | `resend.domains.create(params)` | Returns DNS records to configure |
+| Get | `resend.domains.get(id)` | Returns domain with DNS records and status |
+| List | `resend.domains.list({ limit?, offset? })` | Paginated list |
+| Update | `resend.domains.update(params)` | Update tracking, TLS, capabilities |
+| Delete | `resend.domains.remove(id)` | Permanent — not `.delete()` |
+| Verify | `resend.domains.verify(id)` | Triggers async DNS verification |
+
+### Python
+
+`resend.Domains.create/get/list/update/remove/verify` — same operations with snake_case params (e.g., `custom_return_path`, `open_tracking`, `click_tracking`).
+
+> **Claiming a domain another Resend account already verified?** See [Claim a Domain](#claim-a-domain) — Node SDK (`resend >= 6.14.0`) and CLI (`resend domains claim`).
+
+## Use a Subdomain
+
+Prefer a subdomain (e.g., `send.example.com`) over the root domain:
+
+- **No MX conflicts** with existing email (Google Workspace, Microsoft 365)
+- **Isolated reputation** — if transactional reputation gets damaged, your root domain is unaffected
+- DNS records (DKIM CNAMEs, MX, TXT) go on the **subdomain**, not the root
+
+## Create Domain
+
+```typescript
+const { data, error } = await resend.domains.create({
+  name: 'send.acme.com',           // subdomain recommended
+  region: 'us-east-1',              // immutable after creation
+  customReturnPath: 'bounce',       // optional: bounce@send.acme.com — helps DMARC alignment
+  openTracking: false,
+  clickTracking: false,
+});
+if (error) {
+  console.error(error);
+  return;
+}
+
+// data.records contains DNS records to add:
+// [{ type: 'MX', name: '...', value: '...' }, { type: 'TXT', ... }, ...]
+console.log(data.id);      // domain ID for later calls
+console.log(data.records);  // add these to your DNS provider
+```
+
+```python
+domain = resend.Domains.create({
+    "name": "send.acme.com",
+    "region": "us-east-1",
+    "custom_return_path": "bounce",
+    "open_tracking": False,
+    "click_tracking": False,
+})
+# domain["records"] has the DNS entries to configure
+```
+
+## Verify Flow
+
+After adding DNS records to your provider, trigger verification and poll:
+
+```typescript
+// Trigger verification (returns immediately)
+await resend.domains.verify(data.id);
+
+// Poll until verified (DNS propagation can take minutes to hours)
+const { data: domain } = await resend.domains.get(data.id);
+console.log(domain.status); // 'pending', 'verified', 'failed'
+```
+
+### Verify DNS Propagation
+
+```bash
+dig TXT send.example.com +short
+dig MX send.example.com +short
+dig CNAME resend._domainkey.send.example.com +short
+```
+
+## Update Domain
+
+```typescript
+const { data, error } = await resend.domains.update({
+  id: 'domain_abc123',
+  clickTracking: true,
+  openTracking: true,
+  tls: 'enforced',
+  capabilities: { sending: 'enabled', receiving: 'enabled' },
+});
+```
+
+## Claim a Domain
+
+Claiming takes over a domain **another Resend account has already verified**. The domain transfers to your account as a **brand-new domain with fresh DKIM keys**, so the previous account's DNS records can't be reused — you must update DNS and verify before sending or receiving.
+
+```
+Claim → Add TXT proof to DNS → Verify claim → (completed) → Update DKIM in DNS → Verify domain → Send
+```
+
+Claim methods are available via the **Node SDK** (`resend >= 6.14.0`) and the **CLI** (`resend domains claim`) — no other-language SDK support yet.
+
+| Operation | Method | Notes |
+|-----------|--------|-------|
+| Start claim | `resend.domains.claims.create({ name })` | Accepts `name` (required) + optional `region`, `customReturnPath`, `openTracking`, `clickTracking`, `trackingSubdomain` (`domains.create` body minus `tls`/`capabilities`). Returns a `domain_claim` with `domain_id` + the TXT `record` to add |
+| Get claim | `resend.domains.claims.get(domainId)` | Latest claim for the placeholder domain — poll `status` |
+| Verify claim | `resend.domains.claims.verify(domainId)` | Triggers async DNS proof + transfer (not synchronous) |
+
+```typescript
+// 1. Start the claim — returns the placeholder domain id + TXT record to add
+const { data: claim, error } = await resend.domains.claims.create({
+  name: 'send.acme.com',
+});
+if (error) {
+  console.error(error);
+  return;
+}
+console.log(claim.domain_id); // placeholder domain id for later calls
+console.log(claim.record);    // { type: 'TXT', name, value, ttl } — add to DNS
+
+// 2. After adding the TXT record, trigger verification
+await resend.domains.claims.verify(claim.domain_id);
+
+// 3. Poll until the claim status is 'completed'
+const { data: latest } = await resend.domains.claims.get(claim.domain_id);
+console.log(latest.status); // 'pending' | 'verified' | 'completed' | 'blocked' | ...
+
+// 4. Once 'completed', the transferred domain has NEW DKIM records:
+//    fetch them, update your DNS, then verify the domain itself.
+const { data: domain } = await resend.domains.get(claim.domain_id);
+console.log(domain.records); // add these to DNS, then:
+await resend.domains.verify(claim.domain_id);
+```
+
+A `blocked` status means a safety check failed — inspect `blocked_reason` (`grace_period`, `recent_owner_activity`, `pending_scheduled_emails`).
+
+## Parameter Reference
+
+| Parameter | Values | Default | Notes |
+|-----------|--------|---------|-------|
+| `region` | `us-east-1`, `eu-west-1`, `sa-east-1`, `ap-northeast-1` | `us-east-1` | **Immutable** after creation |
+| `customReturnPath` | string (e.g., `"bounce"`) | none | Results in `bounce@example.com` — helps DMARC alignment |
+| `tls` | `opportunistic`, `enforced` | `opportunistic` | |
+| `openTracking` | `true`, `false` | Domain default | |
+| `clickTracking` | `true`, `false` | Domain default | |
+| `capabilities` | `{ sending: 'enabled'\|'disabled', receiving: 'enabled'\|'disabled' }` | sending enabled | |
+| `trackingSubdomain` / `tracking_subdomain` | string | none | Subdomain for click/open tracking URLs (e.g., `"track"` → `track.example.com`). Set on create or update |
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using root domain when a subdomain would be safer | Consider `send.example.com` — avoids MX conflicts with existing email and isolates reputation |
+| Sending before DNS records are added | Create returns DNS records — add them to your provider first, then verify |
+| Expecting `verify()` to be synchronous | Verify triggers async check — poll with `get()` to confirm status |
+| Trying to change `region` after creation | Region is **immutable** — delete and recreate the domain |
+| MX record value doesn't match region | MX must be region-specific (`feedback-smtp.{region}.amazonses.com`) — use the exact records from the create response |
+| Cloudflare proxy mode enabled | Disable proxy (orange → gray cloud) for all Resend DNS records — CNAME proxy breaks DKIM verification |
+| DNS provider auto-appends domain name | GoDaddy/Namecheap may turn `resend._domainkey.send.acme.com` into `resend._domainkey.send.acme.com.acme.com` — add a trailing dot or enter just the subdomain portion |
+| DNS records added to root instead of subdomain | DKIM CNAMEs go on `resend._domainkey.send.example.com`, not `resend._domainkey.example.com` |
+| Calling `.delete()` | SDK method is `.remove()` |
+| Deleting a domain accidentally | Delete is permanent with no undo — verify intent before calling |
+| Using `enforced` TLS with recipients that don't support it | Use `opportunistic` (default) unless you know all recipients support TLS |
+| Not checking `error` in Node.js | SDK returns `{ data, error }`, does not throw — always destructure and check |
+| Forgetting region on create | Defaults to `us-east-1` — set explicitly for EU/SA/AP data residency requirements |
+| Reusing the old account's DNS records after a claim | A claim issues **new DKIM keys** — fetch the transferred domain with `domains.get()`, update DNS, then `domains.verify()` |
+| Treating the claim as done at `completed` | `completed` only means the transfer finished — the domain still needs its new DKIM records in DNS and a `domains.verify()` to send |
+| Expecting `claims.verify()` to be synchronous | It triggers an async DNS proof + transfer — poll `claims.get()` for `status` |
+| Looking for a claim method in Python or another language | Claims are Node SDK + CLI only today — no other-language SDK support yet |