first commit

docs/communication/messaging/sms/src/schemas/schemas.md

@@ -0,0 +1,101 @@
+# `schemas`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`schemas` is the Zod boundary for every public input that
+`@suaveplan/sms` exposes. The schemas mirror the public type
+contracts (`SmsMessage`, `SmsTemplate`, `SmsDeliveryReport`,
+`SmsDeliveryStatus`) verbatim, and the `parseSmsMessage` /
+`parseSmsTemplate` / `parseSmsDeliveryReport` parsers throw a
+`SmsInvalidConfigError` (code `SMS.INVALID_CONFIG`) with the Zod
+issues attached as `context.issues` on rejection.
+
+The schemas use strict `.object()` shapes so unknown keys are
+rejected — callers cannot accidentally smuggle private fields
+through the public API.
+
+## Features
+
+- `SmsMessageSchema` — strict shape with E.164 `to`, non-empty
+  `body`, and optional `from`, `templateId`, `templateVars`,
+  `metadata`, `channel`.
+- `SmsTemplateSchema` — strict shape with non-empty `id`,
+  non-empty `body`, `variables` array, optional `defaults` map.
+- `SmsDeliveryStatusSchema` — union of the five status literals.
+- `SmsDeliveryReportSchema` — strict shape for receipts.
+- `parseSmsMessage`, `parseSmsTemplate`,
+  `parseSmsDeliveryReport` — throw `SmsInvalidConfigError` on
+  rejection with the Zod issues attached.
+- `stripUndefined` helper strips undefined keys before returning
+  so the result complies with the
+  `exactOptionalPropertyTypes` contract.
+
+## Usage: Basic
+
+```ts
+import { parseSmsMessage } from "@suaveplan/sms/schemas";
+
+const msg = parseSmsMessage({
+    to: "+15551234567",
+    body: "Hello",
+});
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    SmsMessageSchema,
+    parseSmsTemplate,
+} from "@suaveplan/sms/schemas";
+import { SmsInvalidConfigError } from "@suaveplan/sms/error-codes";
+
+try {
+    const template = parseSmsTemplate({
+        id: "welcome",
+        body: "Hi {{name}}",
+        variables: ["name"],
+    });
+    console.log(template.id);
+} catch (err) {
+    if (err instanceof SmsInvalidConfigError) {
+        for (const issue of (err.context?.issues ?? []) as ReadonlyArray<
+            Record<string, unknown>
+        >) {
+            console.error(issue);
+        }
+    }
+}
+
+// Or use the raw schema for partial validation pipelines:
+SmsMessageSchema.safeParse(input);
+```
+
+## API Reference
+
+- `SmsMessageSchema: ZodObject` — mirrors `SmsMessage`.
+- `SmsTemplateSchema: ZodObject` — mirrors `SmsTemplate`.
+- `SmsDeliveryStatusSchema: ZodUnion` — five string literals.
+- `SmsDeliveryReportSchema: ZodObject` — mirrors
+  `SmsDeliveryReport`.
+- `parseSmsMessage(input: unknown): SmsMessage` — throws
+  `SmsInvalidConfigError`.
+- `parseSmsTemplate(input: unknown): SmsTemplate` — throws
+  `SmsInvalidConfigError`.
+- `parseSmsDeliveryReport(input: unknown): SmsDeliveryReport` —
+  throws `SmsInvalidConfigError`.
+
+## Implementation Notes
+
+The default-export form `import z from "zod"` is the only
+Bun-safe form  (per the workspace's `feedback_zod_import`
+note); the named import variant breaks under Bun's module
+loader. Each parser returns the result of `stripUndefined` so
+the value matches the public type shape (which uses
+`exactOptionalPropertyTypes`). Zod's `.strict()` rejects unknown
+keys, so consumers cannot pass private fields through the public
+boundary.