@keystrokehq/resend 0.0.9 → 0.0.16-integration-id-canonicalization.0

package/README.md

@@ -1,183 +1,79 @@
 # @keystrokehq/resend
 
-Resend integration for Keystroke workflows — transactional email, broadcasts, contacts, segments, templates, domains, and Svix-signed webhook triggers.
+Resend integration for Keystroke workflows — transactional email, broadcasts, contacts, segments, templates, domains, and Svix-signed webhook event schemas.
 
-## Overview
+## Package layout (strict-end)
 
-This package wraps the [Resend](https://resend.com) v1 REST API and exposes:
+This package exports four subpaths:
 
-- **66 operations** across 12 resource domains.
-- **17 direct-binding webhook trigger helpers** (11 email, 3 domain, 3 contact) with Svix v1 signature verification.
-- An idempotent `ensureResendWebhook` helper that registers a webhook endpoint, reconciles its event subscription, and returns the per-endpoint signing secret.
+| Subpath | Contents |
+|---------|----------|
+| `@keystrokehq/resend` | Re-exports credential sets, operations, and schemas |
+| `@keystrokehq/resend/credential-sets` | `resendCredentialSet`, `ResendCredentials` |
+| `@keystrokehq/resend/operations` | 66 `Operation` primitives (one file per operation under `src/operations/`) |
+| `@keystrokehq/resend/schemas` | Shared Zod schemas, webhook event envelopes, domain response shapes |
 
-No runtime dependency on the official `resend` npm package — the client is a thin wrapper over the shared `createJsonRestClient` helper from `@keystrokehq/integration-authoring`, and the Svix verifier is hand-rolled on top of Node's `crypto` module. See [`IMPLEMENTATION_NOTES.md`](./IMPLEMENTATION_NOTES.md) § 3 for the SDK rejection rationale.
-
-## Installation
-
-```bash
-pnpm add @keystrokehq/resend
-```
+Internal helpers live under `src/utils/` (`createResendClient`, Svix webhook verification). They are not public package exports.
 
 ## Credentials
 
-The public connection is manual API-key auth.
+Single user credential set id: **`resend`**.
 
 Required:
 
-- `RESEND_API_KEY` — an API key from your Resend dashboard (`re_…`).
+- `RESEND_API_KEY` — API key from the Resend dashboard (`re_…` prefix).
 
 Optional:
 
-- `RESEND_WEBHOOK_SIGNING_SECRETS` — a map of `{ webhookId: whsec_… }`. Populate it automatically via `ensureResendWebhook` (see below) before binding webhook triggers.
+- `RESEND_WEBHOOK_SIGNING_SECRETS` — map of `{ endpointId: whsec_… }` per webhook endpoint. Populate when registering webhooks (`create-resend-webhook` returns a signing secret) so inbound Svix payloads can be verified at runtime.
 
-There is no OAuth flow and no Keystroke-owned shared client secret. API keys are team-scoped — one Keystroke connection = one Resend team.
+There is no OAuth flow. API keys are team-scoped.
 
 ## Quickstart
 
-Import the connection and two helpers you'll use most:
-
-```ts
-import { resend, type ResendCredentials } from '@keystrokehq/resend/connection';
-import { sendEmail } from '@keystrokehq/resend/emails';
-import { triggers } from '@keystrokehq/resend/triggers';
-```
-
-### Send a transactional email
-
-`sendEmail` is a Keystroke operation. Drop it into a workflow step that has the Resend connection attached; the workflow runtime hands it typed credentials.
-
 ```ts
-import { sendEmail } from '@keystrokehq/resend/emails';
-
-sendEmail({
-  id: 'welcome_email',
-  // Keystroke wires input at workflow-compile time; the shape below is
-  // the validated input of sendEmail.
-  input: {
-    from: 'Acme <onboarding@acme.example>',
-    to: ['delivered@resend.dev'],
-    subject: 'Welcome to Acme',
-    html: '<p>Glad you are here.</p>',
-    // Optional; forwarded as the Idempotency-Key header (24h TTL).
-    idempotency_key: 'welcome-2026-04-20',
-  },
-});
+import { resendCredentialSet } from '@keystrokehq/resend/credential-sets';
+import { sendEmailOperation } from '@keystrokehq/resend/operations';
+import { resendWebhookEventSchema } from '@keystrokehq/resend/schemas';
 ```
 
-### Subscribe to delivery events
-
-All Resend webhooks go through one signed HTTPS POST channel. Bind one helper per event type:
-
-```ts
-import { triggers } from '@keystrokehq/resend/triggers';
-
-const onBounce = triggers.emailBounced({
-  name: 'Resend bounce handler',
-});
-```
+Workflow steps reference operations by id (e.g. `resend.send-resend-email`). The runtime resolves `context.credentials.resend` from the bound credential set.
 
-`triggers.emailOpened` filters out Apple Mail Privacy Protection cache-opens (`data.is_machine_opened === true`) by default — if you want those too, pass a custom `filter` in the binding options.
+## Operations (66)
 
-### Wire the webhook endpoint
+| Domain | Count |
+|--------|------:|
+| emails (sent) | 8 |
+| emails (receiving) | 4 |
+| broadcasts | 6 |
+| contacts | 10 |
+| contact-properties | 5 |
+| segments | 5 |
+| templates | 7 |
+| topics | 5 |
+| domains | 6 |
+| api-keys | 3 |
+| webhooks (endpoint CRUD) | 5 |
+| logs | 2 |
 
-Before a trigger binding can verify payloads it needs the per-endpoint `whsec_…` signing secret on the credential set. Run this once per environment:
-
-```ts
-import { ensureResendWebhook } from '@keystrokehq/resend/triggers';
-
-const result = await ensureResendWebhook({
-  credentials,
-  endpointUrl: 'https://workflows.example.com/hooks/resend',
-  events: ['email.delivered', 'email.bounced', 'email.complained'],
-});
-// result.webhookId, result.signingSecret, result.created, result.updated
-```
-
-Then persist `result.signingSecret` under `credentials.RESEND_WEBHOOK_SIGNING_SECRETS[result.webhookId]`. The trigger verifier iterates every secret in that map, which also handles rotation: add a new webhook, store its secret alongside the old one, and remove the old webhook once you've cut over.
-
-## Resource domains
-
-Every endpoint on the public Resend v1 API is wrapped.
-
-| Subpath | Endpoints covered |
-|---------|-------------------|
-| `@keystrokehq/resend/emails` | `POST /emails`, `POST /emails/batch`, `GET /emails`, `GET /emails/{id}`, `PATCH /emails/{id}`, `POST /emails/{id}/cancel`, `GET /emails/{id}/attachments`, `GET /emails/{id}/attachments/{id}` |
-| `@keystrokehq/resend/emails-receiving` | `GET /emails/receiving`, `GET /emails/receiving/{id}`, `GET /emails/receiving/{id}/attachments`, `GET /emails/receiving/{id}/attachments/{id}` |
-| `@keystrokehq/resend/templates` | CRUD + duplicate + publish |
-| `@keystrokehq/resend/broadcasts` | CRUD + send |
-| `@keystrokehq/resend/contacts` | CRUD + segment-membership + topic-subscriptions |
-| `@keystrokehq/resend/contact-properties` | CRUD |
-| `@keystrokehq/resend/segments` | CRUD + list-contacts (no update — segments are filter-defined) |
-| `@keystrokehq/resend/topics` | CRUD |
-| `@keystrokehq/resend/domains` | CRUD + verify |
-| `@keystrokehq/resend/api-keys` | Create, list, delete (no get/update on the Resend API) |
-| `@keystrokehq/resend/webhooks` | CRUD (endpoint CRUD — for direct-binding triggers use `/triggers`) |
-| `@keystrokehq/resend/logs` | List, retrieve (plan-gated) |
-
-### Support-surface imports
-
-Use these when you need to wire secondary pieces (raw client, schema types, event constants, verification helpers):
-
-- `@keystrokehq/resend/connection` — `resend`, `ResendCredentials`, `resendAuthSchema`.
-- `@keystrokehq/resend/client` — `createResendClient`, `ResendClient`, `RESEND_BASE_URL`, `RESEND_USER_AGENT`.
-- `@keystrokehq/resend/schemas` — list envelope, pagination, region / TLS / permission enums.
-- `@keystrokehq/resend/events` — event name constants and payload schemas.
-- `@keystrokehq/resend/verification` — `verifyResendWebhookRequest`, `parseResendWebhookBody`, Svix header constants.
-
-### Hidden surfaces (do not import from application code)
-
-`@keystrokehq/resend/_official` and `@keystrokehq/resend/_runtime` exist for `@keystrokehq/official-integration-catalog`. End users should not import them.
+Webhook **endpoint CRUD** lives in `./operations`. Event payload schemas live in `./schemas` (`events.ts`). Svix verification helpers are internal (`src/utils/verification.ts`).
 
 ## Safety model
 
-Writes and deletes are marked `needsApproval: true`. Read-only list/retrieve operations are not. Callers can override either way per-operation, but the defaults reflect Resend's destructive-action surface.
-
-## Webhook verification (standalone)
-
-If you want to verify a Resend webhook outside the Keystroke trigger runtime:
-
-```ts
-import {
-  verifyResendWebhookRequest,
-  parseResendWebhookBody,
-} from '@keystrokehq/resend/verification';
-import { resendWebhookEventSchema } from '@keystrokehq/resend/events';
-
-function handle(request: {
-  rawBody: string;
-  headers: Record<string, string | string[] | undefined>;
-}) {
-  const verified = verifyResendWebhookRequest({
-    rawBody: request.rawBody,
-    headers: request.headers,
-    signingSecret: process.env.RESEND_WEBHOOK_SECRET ?? '',
-  });
-  if (!verified.ok) {
-    return { status: 401 as const, reason: verified.reason };
-  }
-
-  const body = parseResendWebhookBody(request.rawBody);
-  const event = resendWebhookEventSchema.parse(body);
-  return { status: 200 as const, event };
-}
-```
+Writes and deletes default to `needsApproval: true`. Read-only list/retrieve operations do not.
 
 ## Caveats
 
-- **User-Agent is mandatory.** The Resend API returns HTTP 403 with error code 1010 if no `User-Agent` is attached. The client sets one automatically.
-- **Rate limit.** Default is 5 requests/second per team. Retries are not automatic — callers should implement backoff, or forward an `Idempotency-Key` on `sendEmail`/`sendBatchEmails` so retries are safe.
-- **Apple Mail Privacy Protection.** `triggers.emailOpened` silently drops `is_machine_opened: true` events. Override the `filter` to opt in.
-- **React rendering is not server-side.** The official SDK's `react` body field is intentionally not accepted — render React Email components to HTML upstream and pass the string via `html`.
-- **CSV imports do not emit `contact.created`.** Documented limitation. If you need that signal, poll `listContacts` with cursor persistence.
-- **Signing-secret rotation.** Resend does not expose in-place rotation. Cut over by creating a second webhook, storing its new secret alongside the old one in `RESEND_WEBHOOK_SIGNING_SECRETS`, and deleting the old endpoint once traffic has flipped. The trigger verifier iterates every secret in the map.
+- **User-Agent is mandatory.** Missing `User-Agent` returns HTTP 403 (error code 1010). The internal client sets one automatically.
+- **Rate limit.** Default 5 req/s per team — implement backoff or use `Idempotency-Key` on send operations.
+- **React rendering is not server-side.** Pass rendered HTML via `html`; the SDK `react` field is not accepted.
+- **Signing-secret rotation.** Create a new webhook, store both secrets in `RESEND_WEBHOOK_SIGNING_SECRETS`, then delete the old endpoint.
 
 ## References
 
-- API docs index: <https://resend.com/docs/api-reference/introduction>
-- Webhook event types: <https://resend.com/docs/dashboard/webhooks/event-types>
+- API docs: <https://resend.com/docs/api-reference/introduction>
+- Webhook events: <https://resend.com/docs/dashboard/webhooks/event-types>
 - Webhook verification: <https://resend.com/docs/webhooks/verify-webhooks-requests>
-- Pagination: <https://resend.com/docs/api-reference/pagination>
-- OpenAPI spec: <https://github.com/resend/resend-openapi>
 
 ## License
 

package/dist/credential-sets/index.d.mts

@@ -0,0 +1,2 @@
+import { n as resendCredentialSet, t as ResendCredentials } from "../resend.credential-set-CO_XYnvV.mjs";
+export { type ResendCredentials, resendCredentialSet };

package/dist/credential-sets/index.mjs

@@ -0,0 +1,3 @@
+import { t as resendCredentialSet } from "../resend.credential-set-BVQIXE4k.mjs";
+
+export { resendCredentialSet };