@productcraft/mail 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProductCraft
+
+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.

package/README.md

@@ -0,0 +1,178 @@
+# @productcraft/mail
+
+Typed Node.js SDK for [ProductCraft Mail](https://productcraft.co) — receive-and-store mail platform: send template-rendered messages, manage mailboxes + domains + DKIM, lint templates, track deliveries, configure outbound webhooks, hold suppression lists.
+
+```bash
+npm install @productcraft/mail
+```
+
+Server-side only. The SDK ships a Platform API Key in the `Authorization` header — never embed it in a browser bundle.
+
+## Quick start
+
+```ts
+import { Mail } from "@productcraft/mail";
+
+const mail = new Mail({
+  auth: { type: "apiKey", key: process.env.PCFT_KEY! },
+});
+
+// Send a template-rendered message
+const { data, error } = await mail.client.POST(
+  "/v1/workspaces/{workspace_id}/templates/{name}/send",
+  {
+    params: {
+      path: { workspace_id: "ws_...", name: "welcome" },
+      // Make retries safe — replays return the original response
+      // with `Idempotent-Replay: true` for 24h.
+      header: { "Idempotency-Key": "welcome-2026-05-22-alice" },
+    },
+    body: {
+      from: "hello@yourbrand.com",
+      to: "alice@example.com",
+      subject: "Welcome",          // optional — falls back to template subject
+      data: { name: "Alice" },     // rendered into the template
+    },
+  },
+);
+```
+
+The `client` property is an [`openapi-fetch`](https://openapi-ts.dev/openapi-fetch/) instance bound to `https://api.mail.productcraft.co` and your auth credential. Every endpoint in the published OpenAPI spec is reachable through it — your editor's autocomplete lists paths + method shapes + body fields.
+
+## Configuration
+
+```ts
+new Mail({
+  // The auth credential the SDK presents to Mail
+  auth: { type: "apiKey", key: "pcft_live_..." }
+      | { type: "bearer", token: "eyJ..." }
+      | { type: "cookie", value: "auth_token=..." },
+  // Override the prod base URL — useful for staging / a local proxy
+  baseUrl: "https://api.mail.example.test",
+  // Custom fetch implementation (undici with retry, mock in tests, ...)
+  fetch: customFetch,
+});
+```
+
+## Common operations
+
+Every path is workspace-scoped — `{workspace_id}` is the UUID of the workspace that owns the resource, returned by `@productcraft/platform-auth`'s introspect endpoint.
+
+### Templates
+
+```ts
+// List templates
+await mail.client.GET(
+  "/v1/workspaces/{workspace_id}/templates",
+  { params: { path: { workspace_id: "ws_..." } } },
+);
+
+// Lint a template before saving — the body field is `body_html`
+// (wire) / `bodyHtml` (camelCase TS DTO), NOT `html`.
+await mail.client.POST(
+  "/v1/workspaces/{workspace_id}/templates/lint",
+  {
+    params: { path: { workspace_id: "<workspace-uuid>" } },
+    body: { body_html: "<p>Hello {{name}}</p>" },
+  },
+);
+// → { score, findings: [...] }
+
+// Preview / render with sample data
+await mail.client.POST(
+  "/v1/workspaces/{workspace_id}/templates/{name}/render",
+  {
+    params: { path: { workspace_id: "ws_...", name: "welcome" } },
+    body: { data: { name: "Alice" } },
+  },
+);
+
+// Send to one address (template-rendered)
+await mail.client.POST(
+  "/v1/workspaces/{workspace_id}/templates/{name}/send",
+  { params: { ... }, body: { from, to, data } },
+);
+
+// Send the same template to many addresses (batch)
+await mail.client.POST(
+  "/v1/workspaces/{workspace_id}/templates/{name}/send-batch",
+  { params: { ... }, body: { recipients: [{ to, data }, ...] } },
+);
+```
+
+### Domains + DKIM
+
+```ts
+// List domains
+await mail.client.GET("/v1/workspaces/{workspace_id}/domains", { ... });
+
+// Add a domain (then publish the DKIM TXT record Mail prints)
+await mail.client.POST(
+  "/v1/workspaces/{workspace_id}/domains",
+  { params: { ... }, body: { name: "mail.yourbrand.com" } },
+);
+
+// Verify after DNS propagation
+await mail.client.POST(
+  "/v1/workspaces/{workspace_id}/domains/{domain_id}/verify",
+  { params: { path: { workspace_id, domain_id } } },
+);
+```
+
+### Messages
+
+```ts
+// Workspace-wide message listing + filters
+await mail.client.GET(
+  "/v1/workspaces/{workspace_id}/messages",
+  { params: { path: { workspace_id }, query: { limit: 50 } } },
+);
+
+// Read body / attachments / raw RFC822
+await mail.client.GET("/v1/workspaces/{workspace_id}/messages/{id}/body", { ... });
+await mail.client.GET(
+  "/v1/workspaces/{workspace_id}/mailboxes/{id}/messages/{mid}/attachments/{position}",
+  { ... },
+);
+```
+
+### Suppression list
+
+```ts
+// Add an email to the workspace suppression list
+await mail.client.POST(
+  "/v1/workspaces/{workspace_id}/suppression",
+  { params: { ... }, body: { email: "bounced@example.com", reason: "hard_bounce" } },
+);
+```
+
+### Outbound webhooks
+
+```ts
+// Configure the workspace's default webhook (delivery / open / bounce events)
+await mail.client.PUT(
+  "/v1/workspaces/{workspace_id}/webhooks/default",
+  {
+    params: { ... },
+    body: { url: "https://yourapp.com/hooks/mail", events: ["message.delivered"] },
+  },
+);
+
+// Per-domain webhook overrides + secret rotation
+await mail.client.POST(
+  "/v1/workspaces/{workspace_id}/webhooks/domains/{domain_id}/rotate-secret",
+  { ... },
+);
+```
+
+## Idempotency
+
+Send endpoints accept an `Idempotency-Key` header (1–256 chars, `[A-Za-z0-9_\-:]`). Retries with the same key + same body replay the original response with `Idempotent-Replay: true` for 24h. Same key + different body returns `409 IDEMPOTENCY_KEY_REUSE`.
+
+## How this SDK is built
+
+Generated from the live OpenAPI spec at `https://api.mail.productcraft.co/docs-json` via [`openapi-typescript`](https://openapi-ts.dev/) (types) + [`openapi-fetch`](https://openapi-ts.dev/openapi-fetch/) (runtime). The nightly `spec-refresh` workflow opens a PR whenever the spec changes; merging publishes a patch bump so type-safe consumers stay current automatically.
+
+## License
+
+[MIT](https://github.com/clauderanelagh/productcraft-node/blob/main/LICENSE).

package/dist/index.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+var core = require('@productcraft/core');
+
+// src/index.ts
+var Mail = class {
+  /** The underlying typed client. v0 surface — every endpoint reachable. */
+  client;
+  constructor(config = {}) {
+    this.client = core.makeClient(core.PC_BASE_URL.mail, config);
+  }
+};
+
+exports.Mail = Mail;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["makeClient","PC_BASE_URL"],"mappings":";;;;;AASO,IAAM,OAAN,MAAW;AAAA;AAAA,EAEA,MAAA;AAAA,EAEhB,WAAA,CAAY,MAAA,GAAyB,EAAC,EAAG;AACvC,IAAA,IAAA,CAAK,MAAA,GAASA,eAAA,CAAkBC,gBAAA,CAAY,IAAA,EAAM,MAAM,CAAA;AAAA,EAC1D;AACF","file":"index.cjs","sourcesContent":["import type { paths } from \"./_generated.js\";\nimport { makeClient, PC_BASE_URL, type PCClientConfig } from \"@productcraft/core\";\n\n/**\n * Mail — typed `openapi-fetch` client for every endpoint in\n * `Specs/mail.json`. Reach for `client.GET(\"/v1/...\")` or\n * `client.POST(...)`; request / response types come from the\n * generated `paths` interface.\n */\nexport class Mail {\n  /** The underlying typed client. v0 surface — every endpoint reachable. */\n  public readonly client: ReturnType<typeof makeClient<paths>>;\n\n  constructor(config: PCClientConfig = {}) {\n    this.client = makeClient<paths>(PC_BASE_URL.mail, config);\n  }\n}\n\nexport type { paths } from \"./_generated.js\";\n"]}