feat: support phone templates (#1224)

* feat: add support for phone templates

- src/context/defaults.ts: add phoneTemplatesDefaults function to strip read-only fields
- src/context/directory/handlers/index.ts: import phoneTemplates handler
- src/context/yaml/handlers/index.ts: import phoneTemplates handler
- src/tools/auth0/handlers/index.ts: import phoneTemplates handler
- src/tools/constants.ts: add PHONE_TEMPLATES_DIRECTORY constant
- src/types.ts: add PhoneTemplate type and update Assets type
- src/context/directory/handlers/phoneTemplates.ts: implement phoneTemplatesHandler for directory context
- src/context/yaml/handlers/phoneTemplates.ts: implement phoneTemplatesHandler for YAML context
- src/tools/auth0/handlers/phoneTemplates.ts: implement PhoneTemplatesHandler class for managing phone templates
- .gitignore: ignore .github/agents directory

* feat: add support for phone templates

- docs/resource-specific-documentation.md: Added documentation for phone templates.
- examples/yaml/tenant.yaml: Included phone templates configuration example.
- src/context/directory/handlers/phoneTemplates.ts: Updated to return null for missing templates.
- src/context/yaml/handlers/phoneTemplates.ts: Updated to return null for missing templates.
- test/context/yaml/context.test.js: Added tests for phone templates processing.
- test/utils.js: Mocked phone templates management functions.
- examples/directory/phone-templates/otp_enroll.json: Created OTP enrollment template.
- examples/directory/phone-templates/otp_verify.json: Created OTP verification template.
- test/context/directory/phoneTemplates.test.ts: Added tests for directory context phone templates.
- test/context/yaml/phoneTemplates.test.ts: Added tests for YAML context phone templates.
- test/tools/auth0/handlers/phoneTemplates.test.ts: Added tests for phone templates handler.

* feat: update phone templates to use keyword markers

- src/context/directory/handlers/phoneTemplates.ts: remove comment on read-only fields
- test/context/directory/phoneTemplates.test.ts: update verification and enrollment code texts to use keyword markers
- test/context/yaml/phoneTemplates.test.ts: update verification and enrollment code texts to use keyword markers
- test/tools/auth0/handlers/phoneTemplates.test.ts: update verification and enrollment code texts to use keyword markers

---------

Author: kushalshit27

.gitignore

@@ -16,3 +16,4 @@ Makefile
 .github/copilot-instructions.md
 .github/chatmodes/*
 .github/prompts/*
+.github/agents/*

docs/resource-specific-documentation.md

@@ -575,3 +575,56 @@ phoneProviders:
   }
 ]
 ```
+
+## PhoneTemplates
+
+Phone templates allow you to customize the SMS and voice messages sent to users for phone-based authentication.
+Refer to the [Management API](https://auth0.com/docs/api/management/v2/branding/get-phone-templates) for more details.
+
+### YAML Example
+
+```yaml
+# Contents of ./tenant.yaml
+phoneTemplates:
+  - type: otp_verify
+    disabled: false
+    content:
+      from: '+12341234567'
+      body:
+        text: 'Your verification code is {{ code }}'
+        voice: 'Your verification code is {{ code }}'
+  - type: otp_enroll
+    disabled: false
+    content:
+      from: '+12341234567'
+      body:
+        text: 'Your enrollment code is {{ code }}'
+```
+
+### Directory Example
+
+Create individual JSON files for each template in the `phone-templates` directory:
+
+```text
+phone-templates/
+├── otp_verify.json
+├── otp_enroll.json
+├── change_password.json
+└── ...
+```
+
+Example `phone-templates/otp_verify.json`:
+
+```json
+{
+  "type": "otp_verify",
+  "disabled": false,
+  "content": {
+    "from": "+12341234567",
+    "body": {
+      "text": "Your verification code is {{ code }}",
+      "voice": "Your verification code is {{ code }}"
+    }
+  }
+}
+```

examples/directory/phone-templates/otp_enroll.json

@@ -0,0 +1,12 @@
+{
+  "type": "otp_enroll",
+  "disabled": false,
+  "content": {
+    "syntax": "liquid",
+    "from": "+12341234567",
+    "body": {
+      "text": "Your enrollment code is {{ code }}",
+      "voice": "Your enrollment code is {{ code }}"
+    }
+  }
+}

examples/directory/phone-templates/otp_verify.json

@@ -0,0 +1,12 @@
+{
+  "type": "otp_verify",
+  "disabled": false,
+  "content": {
+    "syntax": "liquid",
+    "from": "+12341234567",
+    "body": {
+      "text": "Your verification code is {{ code }}",
+      "voice": "Your verification code is {{ code }}"
+    }
+  }
+}

examples/yaml/tenant.yaml

@@ -111,6 +111,21 @@ phoneProviders:
     credentials:
       auth_token: "some_auth_token"
 
+phoneTemplates:
+  - type: otp_verify
+    disabled: false
+    content:
+      from: "+12341234567"
+      body:
+        text: "Your verification code is {{ code }}"
+        voice: "Your verification code is {{ code }}"
+  - type: otp_enroll
+    disabled: false
+    content:
+      from: "+12341234567"
+      body:
+        text: "Your enrollment code is {{ code }}"
+
 emailProvider:
   name: "smtp"
   enabled: true

src/context/defaults.ts

@@ -90,6 +90,27 @@ export function phoneProviderDefaults(phoneProvider) {
   return updated;
 }
 
+export function phoneTemplatesDefaults(phoneTemplate) {
+  const updated = { ...phoneTemplate };
+
+  // Strip read-only fields that are returned by the API but should not be included in exported config
+  const removeKeysFromOutput = [
+    'id',
+    'channel',
+    'customizable',
+    'tenant',
+    'created_at',
+    'updated_at',
+  ];
+  removeKeysFromOutput.forEach((key) => {
+    if (key in updated) {
+      delete updated[key];
+    }
+  });
+
+  return updated;
+}
+
 export function connectionDefaults(connection) {
   if (connection.options) {
     // Mask secret for key: connection.options.client_secret

src/context/directory/handlers/index.ts

@@ -20,6 +20,7 @@ import triggers from './triggers';
 import attackProtection from './attackProtection';
 import branding from './branding';
 import phoneProviders from './phoneProvider';
+import phoneTemplates from './phoneTemplates';
 import logStreams from './logStreams';
 import prompts from './prompts';
 import customDomains from './customDomains';
@@ -70,6 +71,7 @@ const directoryHandlers: {
   attackProtection,
   branding,
   phoneProviders,
+  phoneTemplates,
   logStreams,
   prompts,
   customDomains,

src/context/directory/handlers/phoneTemplates.ts

@@ -0,0 +1,52 @@
+import path from 'path';
+import fs from 'fs-extra';
+import { constants } from '../../../tools';
+
+import { existsMustBeDir, getFiles, dumpJSON, loadJSON } from '../../../utils';
+import { DirectoryHandler } from '.';
+import DirectoryContext from '..';
+import { ParsedAsset } from '../../../types';
+import { PhoneTemplate } from '../../../tools/auth0/handlers/phoneTemplates';
+import { phoneTemplatesDefaults } from '../../defaults';
+
+type ParsedPhoneTemplates = ParsedAsset<'phoneTemplates', PhoneTemplate[]>;
+
+function parse(context: DirectoryContext): ParsedPhoneTemplates {
+  const phoneTemplatesFolder = path.join(context.filePath, constants.PHONE_TEMPLATES_DIRECTORY);
+  if (!existsMustBeDir(phoneTemplatesFolder)) return { phoneTemplates: null }; // Skip
+
+  const files = getFiles(phoneTemplatesFolder, ['.json']);
+
+  const phoneTemplates = files.map((f) =>
+    loadJSON(f, {
+      mappings: context.mappings,
+      disableKeywordReplacement: context.disableKeywordReplacement,
+    })
+  );
+
+  return { phoneTemplates };
+}
+
+async function dump(context: DirectoryContext): Promise<void> {
+  const { phoneTemplates } = context.assets;
+
+  if (!phoneTemplates) {
+    return;
+  } // Skip, nothing to dump
+
+  const phoneTemplatesFolder = path.join(context.filePath, constants.PHONE_TEMPLATES_DIRECTORY);
+  fs.ensureDirSync(phoneTemplatesFolder);
+
+  phoneTemplates.forEach((template) => {
+    const templateWithDefaults = phoneTemplatesDefaults(template);
+    const templateFile = path.join(phoneTemplatesFolder, `${template.type}.json`);
+    dumpJSON(templateFile, templateWithDefaults);
+  });
+}
+
+const phoneTemplatesHandler: DirectoryHandler<ParsedPhoneTemplates> = {
+  parse,
+  dump,
+};
+
+export default phoneTemplatesHandler;

src/context/yaml/handlers/index.ts

@@ -20,6 +20,7 @@ import triggers from './triggers';
 import attackProtection from './attackProtection';
 import branding from './branding';
 import phoneProviders from './phoneProvider';
+import phoneTemplates from './phoneTemplates';
 import logStreams from './logStreams';
 import prompts from './prompts';
 import customDomains from './customDomains';
@@ -68,6 +69,7 @@ const yamlHandlers: { [key in AssetTypes]: YAMLHandler<{ [key: string]: unknown
   attackProtection,
   branding,
   phoneProviders,
+  phoneTemplates,
   logStreams,
   prompts,
   customDomains,

src/context/yaml/handlers/phoneTemplates.ts

@@ -0,0 +1,36 @@
+import { YAMLHandler } from '.';
+import YAMLContext from '..';
+import { PhoneTemplate } from '../../../tools/auth0/handlers/phoneTemplates';
+import { ParsedAsset } from '../../../types';
+import { phoneTemplatesDefaults } from '../../defaults';
+
+type ParsedPhoneTemplates = ParsedAsset<'phoneTemplates', PhoneTemplate[]>;
+
+async function parse(context: YAMLContext): Promise<ParsedPhoneTemplates> {
+  const { phoneTemplates } = context.assets;
+
+  if (!phoneTemplates) return { phoneTemplates: null };
+
+  return {
+    phoneTemplates,
+  };
+}
+
+async function dump(context: YAMLContext): Promise<ParsedPhoneTemplates> {
+  const { phoneTemplates } = context.assets;
+
+  if (!phoneTemplates) return { phoneTemplates: null };
+
+  const processedTemplates = phoneTemplates.map((template) => phoneTemplatesDefaults(template));
+
+  return {
+    phoneTemplates: processedTemplates,
+  };
+}
+
+const phoneTemplatesHandler: YAMLHandler<ParsedPhoneTemplates> = {
+  parse,
+  dump,
+};
+
+export default phoneTemplatesHandler;