From 72ae816818675aafb8b8f828232f35a5807e5f67 Mon Sep 17 00:00:00 2001 From: Ken'ichiro Oyama Date: Thu, 2 Apr 2026 18:13:16 +0900 Subject: [PATCH] docs: add emailConfig and per-request fromName/subject for Built-in IdP Add documentation for namespace-level email configuration (emailConfig) and per-request fromName/subject overrides for password reset emails. --- docs/guides/auth/integration/built-in-idp.md | 49 +++++++++++++++++++- docs/guides/function/builtin-interfaces.md | 2 + docs/guides/function/managing-idp-users.md | 13 +++++- docs/sdk/services/idp.md | 20 ++++++++ 4 files changed, 81 insertions(+), 3 deletions(-) diff --git a/docs/guides/auth/integration/built-in-idp.md b/docs/guides/auth/integration/built-in-idp.md index 05fcc4a..8b6286e 100644 --- a/docs/guides/auth/integration/built-in-idp.md +++ b/docs/guides/auth/integration/built-in-idp.md @@ -37,6 +37,10 @@ const idp = defineIdp("builtin-idp", { useNonEmailIdentifier: false, allowSelfPasswordReset: true, }, + emailConfig: { + fromName: "My App Support", + passwordResetSubject: "Reset your My App password", + }, }); // 2. Configure Auth service to use the Built-in IdP @@ -317,6 +321,38 @@ export const builtinIdp = defineIdp("builtin-idp", { When `disable_password_auth` is enabled, existing users who previously signed in with a password will need to use Google OAuth or Microsoft OAuth instead. Ensure that all users have accounts with the configured OAuth provider and email addresses in the allowed domains before enabling this setting. ::: +### Email Configuration + +The Built-in IdP allows you to customize the sender name and subject line for emails sent by the IdP (such as password reset emails). You can configure namespace-level defaults using the `emailConfig` option, and optionally override them per request. + +**Priority chain** (highest to lowest): + +1. **Per-request parameter** — `fromName` / `subject` passed in `_sendPasswordResetEmail` or `tailor.idp.sendPasswordResetEmail` +2. **Namespace default** — configured in `emailConfig` +3. **Hardcoded default** — `"Tailor Platform IdP"` for sender name, localized default for subject + +**Configuration:** + +- `fromName` (string, optional) — Default sender display name for emails. Max 200 characters. When omitted, falls back to `"Tailor Platform IdP"`. +- `passwordResetSubject` (string, optional) — Default subject line for password reset emails. Max 200 characters. When omitted, falls back to the localized default subject. + +**Example Configuration:** + +```typescript +import { defineIdp } from "@tailor-platform/sdk"; + +export const builtinIdp = defineIdp("builtin-idp", { + authorization: "user.role == 'admin'", + clients: ["main-client"], + emailConfig: { + fromName: "My App Support", + passwordResetSubject: "Reset your My App password", + }, +}); +``` + +With this configuration, password reset emails will be sent as `My App Support ` with the subject "Reset your My App password", unless overridden per request. + ### Why Use the Built-In IdP - **Unified API with Automatic Schema Generation**: When registered as subgraphs, both services automatically contribute their schemas to your application's GraphQL API, making all authentication and user management operations available through a single GraphQL endpoint and simplifying client integration. @@ -517,12 +553,21 @@ Variables: { "input": { "userId": "user-id-here", - "redirectUri": "https://your-app.com/reset-password-complete" + "redirectUri": "https://your-app.com/reset-password-complete", + "fromName": "My App Support", + "subject": "Password Reset for Your My App Account" } } ``` -Password reset emails are sent from `no-reply@idp.erp.dev`. The `redirectUri` must be a valid absolute URL with `http` or `https` scheme. This operation is only available when `use_non_email_identifier` is set to `false` (the default), as it requires users to have email addresses. +**Input fields:** + +- `userId` (ID!, required) — The ID of the user to send the password reset email to. +- `redirectUri` (String!, required) — The URL to redirect the user to after they reset their password. Must be a valid absolute URL with `http` or `https` scheme. +- `fromName` (String, optional) — Overrides the sender display name for this email. When omitted, falls back to the namespace-level `emailConfig.fromName`, then to `"Tailor Platform IdP"`. +- `subject` (String, optional) — Overrides the email subject line for this email. When omitted, falls back to the namespace-level `emailConfig.passwordResetSubject`, then to the localized default. + +Password reset emails are sent from `no-reply@idp.erp.dev`. This operation is only available when `use_non_email_identifier` is set to `false` (the default), as it requires users to have email addresses. User management operations are available only when the IdP service is registered as a subgraph in your application configuration. The GraphQL schema is automatically generated based on the IdP service specification. diff --git a/docs/guides/function/builtin-interfaces.md b/docs/guides/function/builtin-interfaces.md index 06ac6fb..faf09d1 100644 --- a/docs/guides/function/builtin-interfaces.md +++ b/docs/guides/function/builtin-interfaces.md @@ -51,6 +51,8 @@ await client.deleteUser(userId); await client.sendPasswordResetEmail({ userId: user.id, redirectUri: "https://app.example.com/reset", + fromName: "My App Support", // optional: overrides namespace default + subject: "Reset your password", // optional: overrides namespace default }); ``` diff --git a/docs/guides/function/managing-idp-users.md b/docs/guides/function/managing-idp-users.md index eec638b..325e1df 100644 --- a/docs/guides/function/managing-idp-users.md +++ b/docs/guides/function/managing-idp-users.md @@ -65,6 +65,8 @@ interface UpdateUserInput { interface SendPasswordResetEmailInput { userId: string; redirectUri: string; + fromName?: string; + subject?: string; } class Client { @@ -307,6 +309,8 @@ export default async (args) => { const success = await idpClient.sendPasswordResetEmail({ userId: args.userId, redirectUri: "https://your-app.com/reset-password-complete", + fromName: "My App Support", + subject: "Password Reset for Your My App Account", }); return { @@ -315,8 +319,15 @@ export default async (args) => { }; ``` +**Input fields:** + +- `userId` (string, required) — The ID of the user to send the password reset email to. +- `redirectUri` (string, required) — The URL to redirect the user to after password reset. Must be a valid absolute URL with `http` or `https` scheme. +- `fromName` (string, optional) — Overrides the sender display name for this email. When omitted, falls back to the namespace-level `emailConfig.fromName`, then to `"Tailor Platform IdP"`. +- `subject` (string, optional) — Overrides the email subject line for this email. When omitted, falls back to the namespace-level `emailConfig.passwordResetSubject`, then to the localized default. + :::tip -Password reset emails are sent from `no-reply@idp.erp.dev`. The `redirectUri` must be a valid absolute URL with `http` or `https` scheme. +Password reset emails are sent from `no-reply@idp.erp.dev`. ::: ## Related Documentation diff --git a/docs/sdk/services/idp.md b/docs/sdk/services/idp.md index 46046b5..f2afd76 100644 --- a/docs/sdk/services/idp.md +++ b/docs/sdk/services/idp.md @@ -77,6 +77,26 @@ defineIdp("my-idp", { }); ``` +### emailConfig + +Optional email configuration defaults for emails sent by the IdP (e.g., password reset emails). Per-request values take priority over namespace defaults. + +```typescript +defineIdp("my-idp", { + authorization: "loggedIn", + clients: ["default-client"], + emailConfig: { + fromName: "My App", + passwordResetSubject: "Reset your password", + }, +}); +``` + +**Fields:** + +- `fromName` (string, optional) — Default sender display name for emails (e.g., `My App `). Max 200 characters. When omitted, falls back to `"Tailor Platform IdP"`. +- `passwordResetSubject` (string, optional) — Default subject line for password reset emails. Max 200 characters. When omitted, falls back to the localized default subject. + ## Using idp.provider() The `idp.provider()` method creates a type-safe reference to the IdP for use in Auth configuration. The client name is validated at compile time against the clients defined in the IdP.