# `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.