@productcraft/auth 0.5.1 → 0.6.0

package/README.md

@@ -90,8 +90,11 @@ await consumer.auth.signup({
 
 await consumer.auth.refresh({ refresh_token });
 await consumer.auth.logout({ refresh_token });
-await consumer.auth.requestReset({ email });
-await consumer.auth.resetPassword({ token, new_password: "..." });
+
+// Forgot password. `sendPasswordResetEmail` mints the code AND emails it
+// via Mail — this is what you want for a normal reset flow.
+await consumer.auth.sendPasswordResetEmail({ email });
+await consumer.auth.resetPassword({ code, new_password: "..." });
 
 // Sign in with Apple (native iOS flow). See "Federated sign-in" below.
 await consumer.auth.signinWithProvider({
@@ -116,6 +119,27 @@ await consumer.oauth.clientCredentials({ clientId, clientSecret, scope });
 
 > **Wire-shape note.** Auth's JSON wire is snake_case, and the SDK returns response objects as-is (e.g. `access_token`, `refresh_token`, `token_type`, `expires_in`). Request DTOs follow the same convention; some convenience fields (`identifier`, `password`, `nonce`) are unaffected, but anywhere the spec uses an underscore the SDK does too.
 
+### One-time codes: who sends the email?
+
+Verification and password-reset each come in two flavours. **Picking the wrong one is silent** — you get a `2xx` and no email is ever sent — so choose deliberately:
+
+| Method | Mints a code | Sends the email | Returns |
+| --- | --- | --- | --- |
+| `auth.requestVerification()` | ✅ | ❌ | `{ code, expires_at }` |
+| `auth.sendVerificationEmail()` | ✅ | ✅ via Mail | `{ expires_at }` |
+| `auth.requestReset()` | ✅ | ❌ | `{ code, expires_at }` |
+| `auth.sendPasswordResetEmail()` | ✅ | ✅ via Mail | `{ expires_at }` |
+
+**Use `send*` for a normal flow.** Mail delivers the code using your app's configured sender and template, and you never handle the plaintext code.
+
+**Use `request*` only when you are delivering the code yourself** — your own SMTP, an SMS provider, or consuming it in-process (e.g. provisioning a test account). If you call `request*` and drop the returned `code` on the floor, your users get nothing and nothing is logged anywhere, because no send was ever attempted.
+
+Each pair is gated by a *separate* PAK permission (`auth.user.verify.create` vs `auth.user.verify.send-email`, and likewise for `password-reset`), so a workspace can enable minting without enabling outbound mail.
+
+The `send*` methods fail loudly with a typed `412` when Mail isn't ready — `ENVOI_NOT_ENABLED`, `ENVOI_SENDER_NOT_CONFIGURED`, `ENVOI_TEMPLATE_NOT_CONFIGURED`, `ENVOI_APP_NOT_BOUND_TO_WORKSPACE` — or `503 ENVOI_DISPATCH_FAILED`. If your endpoint returns a uniform response to prevent account enumeration, catch and **log** these rather than discarding them; a swallowed 412 is indistinguishable from the silent failure above.
+
+Both `request*` and `send*` return `{}` when the contact doesn't match (or is already verified / unverified as appropriate). That's the anti-enumeration contract, not an error — there is nothing to branch on.
+
 ## Federated sign-in (Apple, Google)
 
 `consumer.auth.signinWithProvider` lets a BFF exchange a provider-issued identity token for an Auth `{ access_token, refresh_token }` pair. The endpoint creates the EndUser on first sign-in and returns the same account on subsequent ones — the SDK is a thin wrapper over Auth's `POST /{appSlug}/v1/auth/oauth/{provider}` which does the heavy lifting (Apple JWKS verification, issuer pinning, audience validation against the app's configured native client ids, server-side nonce replay protection, account creation / linking).

package/dist/index.cjs

@@ -1361,6 +1361,36 @@ async function consumerAuthControllerRequestPasswordReset({
   return res.data;
 }
 
+// src/_generated/clients/consumerAuth/consumerAuthControllerSendPasswordResetEmail.ts
+function getConsumerAuthControllerSendPasswordResetEmailUrl({
+  appSlug
+}) {
+  const app_slug = appSlug;
+  const res = {
+    method: "POST",
+    url: `/${app_slug}/v1/auth/send-password-reset-email`
+  };
+  return res;
+}
+async function consumerAuthControllerSendPasswordResetEmail({
+  appSlug,
+  data,
+  headers
+}, config = {}) {
+  const { client: request = client, ...requestConfig } = config;
+  const requestData = data;
+  const res = await request({
+    method: "POST",
+    url: getConsumerAuthControllerSendPasswordResetEmailUrl({
+      appSlug
+    }).url.toString(),
+    data: requestData,
+    ...requestConfig,
+    headers: { ...headers, ...requestConfig.headers }
+  });
+  return res.data;
+}
+
 // src/_generated/clients/consumerAuth/consumerAuthControllerResetPassword.ts
 function getConsumerAuthControllerResetPasswordUrl({
   appSlug
@@ -1887,7 +1917,17 @@ var ConsumerScope = class {
       { client: this.client }
     ),
     /**
-     * PAK-required: caller must instantiate `Auth` with
+     * Mint a 6-digit password-reset code. **Sends no email.** Returns
+     * `{ code, expires_at }` for delivery via your own channel — or
+     * `{}` when the contact doesn't match a verified account (uniform
+     * shape — no account enumeration).
+     *
+     * If you want Mail to deliver the code for you, call
+     * {@link sendPasswordResetEmail} instead. Calling this one and
+     * discarding the `code` means the user never hears anything.
+     *
+     * PAK-required with `auth.user.password-reset.create`: caller must
+     * instantiate `Auth` with
      * `auth: { type: "apiKey", key: "pcft_live_..." }`. The
      * kubb-generated `headers.authorization` slot is a stub — the
      * HTTP client's auth middleware overrides whatever's passed.
@@ -1896,6 +1936,31 @@ var ConsumerScope = class {
       { appSlug: this.appSlug, data, headers: { authorization: "" } },
       { client: this.client }
     ),
+    /**
+     * Mint + dispatch a password-reset email via Mail in one call.
+     * Returns `{ expires_at }` on success; the plaintext code is NOT
+     * returned. Returns `{}` when the contact is missing or unverified
+     * (same enumeration defence as {@link requestReset}).
+     *
+     * This is the counterpart to {@link sendVerificationEmail} for the
+     * reset slot, and the method you want for a plain "forgot
+     * password" flow — {@link requestReset} only mints, it does not
+     * email.
+     *
+     * PAK-required with `auth.user.password-reset.send-email` —
+     * distinct permission from the bare mint so customers can enable
+     * mint without enabling outbound Mail traffic. Surfaces typed 412
+     * precondition errors (e.g. `ENVOI_NOT_ENABLED`,
+     * `ENVOI_TEMPLATE_NOT_CONFIGURED`) rather than failing silently.
+     */
+    sendPasswordResetEmail: (data) => consumerAuthControllerSendPasswordResetEmail(
+      {
+        appSlug: this.appSlug,
+        data,
+        headers: { authorization: "" }
+      },
+      { client: this.client }
+    ),
     resetPassword: (data) => consumerAuthControllerResetPassword(
       { appSlug: this.appSlug, data },
       { client: this.client }