feat: add mintlify documentation site #485
Conversation
- Add mint.json configuration for Mintlify - Convert existing markdown docs to MDX format - Add introduction landing page with feature overview - Add Getting Started guides (architecture, database, development, production) - Add API Reference documentation (overview, usage guide) - Add Channel provider docs (email, SMS, WhatsApp, push, voice) - Add Guides (add provider, test mode, webhooks, delivery status) - Add Operations documentation (redis cleanup, AWS SNS) - Include OsmoX logos and diagram images - Place docs in apps/api/docs-site for monorepo setup
📝 WalkthroughWalkthroughThis pull request adds comprehensive documentation for the OsmoX notification platform, including API references, provider integration guides, getting-started materials, operational guides, and site configuration. All additions are new documentation files covering architecture, database schema, authentication, channel configurations, deployment, webhooks, and delivery status workflows. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~35 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Pre-merge checks✅ Passed checks (3 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
xixas
added
ready for review
documentation
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🧹 Nitpick comments (3)
apps/api/docs-site/getting-started/production.mdx (1)
56-57: Add security guidance for secrets.Based on learnings, security-related environment variables like
API_KEY_SECRETandJWT_SECRETshould include explicit warnings about production requirements such as minimum character lengths for secrets and recommended shorter expiration times for JWT tokens.Consider adding a warning callout after the table:
<Warning> For production environments: - `API_KEY_SECRET` should be at least 32 characters - `JWT_SECRET` should be at least 32 characters - Consider shorter JWT expiration times for enhanced security </Warning>apps/api/docs-site/getting-started/database.mdx (1)
108-117: Add security guidance for credential storage.The example shows sensitive credentials (SMTP_USERNAME, SMTP_PASSWORD) stored in the configuration JSON. Consider adding a note about encryption at rest, secure credential management practices, or referencing a security guide.
🔎 Suggested addition
```<Accordion title="Example provider configuration"> +<Warning> + In production environments, ensure sensitive configuration values are encrypted at rest and consider using a secrets management service. +</Warning> + ```json { "SMTP_HOST": "some.smtp.host", "SMTP_PORT": 123, "SMTP_USERNAME": "someusername", "SMTP_PASSWORD": "somepassword" }apps/api/docs-site/api-reference/overview.mdx (1)
54-65: Consider using a more realistic JWT token example.The example token
"eymysecuretoken"doesn't follow the typical JWT format (which starts witheyJand has three dot-separated parts). While it's clearly marked as an example, using a more realistic-looking token might better set user expectations.🔎 Suggested improvement
**Response:** ```json { "data": { "login": { - "token": "eymysecuretoken", + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", "__typename": "LoginResponse" } } }The response token is used for Bearer Token Authorization as
Bearer <token>.</details> </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between ac0481876edb5d5f939c20fe64b5822e8e933f84 and de4dcc3e944cbccff70162989fd25f0f37e0b0d3. </details> <details> <summary>⛔ Files ignored due to path filters (6)</summary> * `apps/api/docs-site/images/OsmoX-block-diagram.png` is excluded by `!**/*.png` * `apps/api/docs-site/images/OsmoX-notification-life-cycle.png` is excluded by `!**/*.png` * `apps/api/docs-site/images/OsmoX_database_schema.png` is excluded by `!**/*.png` * `apps/api/docs-site/images/dark-logo.svg` is excluded by `!**/*.svg` * `apps/api/docs-site/images/favicon.png` is excluded by `!**/*.png` * `apps/api/docs-site/images/light-logo.svg` is excluded by `!**/*.svg` </details> <details> <summary>📒 Files selected for processing (25)</summary> * `apps/api/docs-site/api-reference/overview.mdx` * `apps/api/docs-site/api-reference/usage.mdx` * `apps/api/docs-site/channels/email/aws-ses.mdx` * `apps/api/docs-site/channels/email/mailgun.mdx` * `apps/api/docs-site/channels/email/smtp.mdx` * `apps/api/docs-site/channels/push/aws-sns.mdx` * `apps/api/docs-site/channels/sms/aws-sns.mdx` * `apps/api/docs-site/channels/sms/plivo.mdx` * `apps/api/docs-site/channels/sms/twilio.mdx` * `apps/api/docs-site/channels/voice/twilio.mdx` * `apps/api/docs-site/channels/whatsapp/360dialog.mdx` * `apps/api/docs-site/channels/whatsapp/twilio-business.mdx` * `apps/api/docs-site/channels/whatsapp/twilio.mdx` * `apps/api/docs-site/getting-started/architecture.mdx` * `apps/api/docs-site/getting-started/database.mdx` * `apps/api/docs-site/getting-started/development.mdx` * `apps/api/docs-site/getting-started/production.mdx` * `apps/api/docs-site/guides/add-provider.mdx` * `apps/api/docs-site/guides/delivery-status.mdx` * `apps/api/docs-site/guides/test-mode.mdx` * `apps/api/docs-site/guides/webhooks.mdx` * `apps/api/docs-site/introduction.mdx` * `apps/api/docs-site/mint.json` * `apps/api/docs-site/operations/aws-sns.mdx` * `apps/api/docs-site/operations/redis-cleanup.mdx` </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🧠 Learnings (8)</summary> <details> <summary>📚 Learning: 2024-07-03T13:27:46.550Z</summary>Learnt from: ayushnvs
Repo: OsmosysSoftware/osmo-x PR: 262
File: apps/api/src/jobs/consumers/notifications/mailgun-notifications.job.consumer.ts:0-0
Timestamp: 2024-07-03T13:27:46.550Z
Learning: ThenotificationSendResponsevariable in theprocessMailgunNotificationConfirmationQueuemethod of theMailgunNotificationConsumerclass was changed fromlettoconstto reflect that it is never reassigned.**Applied to files:** - `apps/api/docs-site/channels/email/mailgun.mdx` </details> <details> <summary>📚 Learning: 2025-12-17T08:03:33.224Z</summary>Learnt from: CR
Repo: OsmosysSoftware/osmo-x PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T08:03:33.224Z
Learning: Use Bull queues (backed by Redis) for job processing with separate queues for each notification channel type**Applied to files:** - `apps/api/docs-site/operations/redis-cleanup.mdx` </details> <details> <summary>📚 Learning: 2024-07-02T10:51:07.210Z</summary>Learnt from: LakshayaT
Repo: OsmosysSoftware/osmo-x PR: 263
File: apps/api/src/modules/notifications/queues/queue.service.ts:96-103
Timestamp: 2024-07-02T10:51:07.210Z
Learning: TheprocessAwaitingConfirmationNotificationQueuemethod in theNotificationConsumerclass includes robust error handling, logging errors, updating the delivery status, incrementing the retry count, and saving the notification.**Applied to files:** - `apps/api/docs-site/guides/delivery-status.mdx` </details> <details> <summary>📚 Learning: 2025-04-02T04:39:38.272Z</summary>Learnt from: kshitij-k-osmosys
Repo: OsmosysSoftware/osmo-x PR: 408
File: apps/api/src/database/migrations/1743145236864-AddNotificationSentOnColumn.ts:0-0
Timestamp: 2025-04-02T04:39:38.272Z
Learning: In the Osmo-X project, thenotification_sent_oncolumn in bothnotify_archived_notificationsandnotify_notificationstables is designed to be nullable, as explicitly defined in the migration file withisNullable: true.**Applied to files:** - `apps/api/docs-site/getting-started/database.mdx` </details> <details> <summary>📚 Learning: 2024-06-10T19:12:20.809Z</summary>Learnt from: LakshayaT
Repo: OsmosysSoftware/osmo-x PR: 218
File: apps/api/src/database/migrations/1692870736645-migration.ts:0-0
Timestamp: 2024-06-10T19:12:20.809Z
Learning: The foreign key forchannel_typeinnotify_notificationsreferencesmaster_idfromnotify_master_providersby design, to keep naming consistent with the table name.**Applied to files:** - `apps/api/docs-site/getting-started/database.mdx` </details> <details> <summary>📚 Learning: 2024-11-08T05:23:26.338Z</summary>Learnt from: osm-vishnukyatannawar
Repo: OsmosysSoftware/osmo-x PR: 354
File: apps/api/src/database/migrations/1730724383210-ArchiveCompletedNotifications.ts:25-27
Timestamp: 2024-11-08T05:23:26.338Z
Learning: In the 'archived_notifications' table, we do not add a foreign key constraint on 'notification_id' to 'notify_notifications' because the original notifications may have been deleted, and we want to retain archived notifications even if the originals are removed.**Applied to files:** - `apps/api/docs-site/getting-started/database.mdx` </details> <details> <summary>📚 Learning: 2025-02-11T11:55:41.029Z</summary>Learnt from: kshitij-k-osmosys
Repo: OsmosysSoftware/osmo-x PR: 390
File: apps/api/.env.example:0-0
Timestamp: 2025-02-11T11:55:41.029Z
Learning: Security-related environment variables in OsmoX should include explicit warnings about production requirements, such as minimum character lengths for secrets and recommended shorter expiration times for tokens.**Applied to files:** - `apps/api/docs-site/getting-started/production.mdx` </details> <details> <summary>📚 Learning: 2025-12-17T08:03:33.224Z</summary>Learnt from: CR
Repo: OsmosysSoftware/osmo-x PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T08:03:33.224Z
Learning: Organize API code into modular NestJS architecture with Core Modules (auth, notifications, providers, applications, users, etc.), Job Processing (consumers, producers), and Configuration (database, typeorm, logger)**Applied to files:** - `apps/api/docs-site/getting-started/architecture.mdx` - `apps/api/docs-site/guides/add-provider.mdx` </details> </details><details> <summary>🪛 Gitleaks (8.30.0)</summary> <details> <summary>apps/api/docs-site/guides/webhooks.mdx</summary> [high] 42-44: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource. (curl-auth-header) </details> </details> </details> <details> <summary>🔇 Additional comments (20)</summary><blockquote> <details> <summary>apps/api/docs-site/guides/test-mode.mdx (1)</summary><blockquote> `7-173`: **Well-structured and comprehensive Test Mode documentation.** The guide is well-organized with clear sections, practical examples for both GraphQL and cURL, and helpful best practices. The use of Mintlify components (CardGroup, Tabs, Note, Warning, Steps) effectively communicates key information. The whitelist configuration guidance and edge cases (wildcard support, whitelist updates outside test mode) are particularly useful. </blockquote></details> <details> <summary>apps/api/docs-site/channels/email/smtp.mdx (1)</summary><blockquote> `1-129`: **LGTM!** The SMTP documentation is well-structured with clear configuration instructions, example payloads, and field descriptions. The note about text-only attachment support is a helpful limitation callout. </blockquote></details> <details> <summary>apps/api/docs-site/channels/whatsapp/360dialog.mdx (1)</summary><blockquote> `1-118`: **LGTM!** The 360Dialog WhatsApp documentation is comprehensive, with detailed template message examples and proper field definitions. The sandbox and template message references are helpful for developers getting started. </blockquote></details> <details> <summary>apps/api/docs-site/channels/email/aws-ses.mdx (1)</summary><blockquote> `1-139`: **LGTM!** The AWS SES documentation is thorough with clear configuration instructions. The file content encoding section (lines 110-127) differentiating text-based and binary file handling is particularly helpful for developers working with attachments. </blockquote></details> <details> <summary>apps/api/docs-site/channels/sms/twilio.mdx (1)</summary><blockquote> `1-78`: **LGTM!** The Twilio SMS documentation is concise and well-structured. Good use of Twilio's test number in the example configuration, and the E.164 format requirement is clearly documented. </blockquote></details> <details> <summary>apps/api/docs-site/channels/whatsapp/twilio-business.mdx (1)</summary><blockquote> `1-90`: **LGTM!** The Twilio WhatsApp Business documentation clearly explains the Content Template Builder integration. The note about `contentVariables` requiring string values (line 78-80) is an important detail that will help developers avoid type-related issues. </blockquote></details> <details> <summary>apps/api/docs-site/channels/sms/aws-sns.mdx (1)</summary><blockquote> `1-79`: **LGTM!** The AWS SNS SMS documentation follows a consistent structure with other AWS provider docs. Configuration fields and request format are clearly documented with the E.164 phone number format requirement. </blockquote></details> <details> <summary>apps/api/docs-site/mint.json (1)</summary><blockquote> `1-114`: **LGTM!** The Mintlify configuration is well-organized with a clear navigation structure covering all documentation sections. All referenced pages exist in the docs-site folder. The color scheme and branding elements are consistent. </blockquote></details> <details> <summary>apps/api/docs-site/guides/delivery-status.mdx (1)</summary><blockquote> `1-117`: **Well-structured delivery status documentation.** This guide provides comprehensive coverage of the notification lifecycle with clear status definitions, visual flow diagram, and provider-specific behavior. The mermaid diagram syntax is correct, and the archival and retry behavior sections are well-documented. </blockquote></details> <details> <summary>apps/api/docs-site/operations/redis-cleanup.mdx (1)</summary><blockquote> `1-235`: **Excellent operational documentation for Redis cleanup.** This guide provides comprehensive coverage of Redis memory management for BullMQ queues. The inclusion of recommended values by environment, manual cleanup options, monitoring commands, and troubleshooting scenarios makes this a valuable operational resource. </blockquote></details> <details> <summary>apps/api/docs-site/channels/sms/plivo.mdx (1)</summary><blockquote> `74-74`: No action needed. The documented Plivo version `^4.75.1` matches the actual dependency specified in `apps/api/package.json`. </blockquote></details> <details> <summary>apps/api/docs-site/api-reference/usage.mdx (1)</summary><blockquote> `167-172`: No action required. The whitelist JSON correctly uses string keys as shown in the documentation. The implementation parses JSON keys as strings (via `Object.entries`) and internally converts them to numbers for provider lookups (line 175: `const numericKey = Number(key)`). </blockquote></details> <details> <summary>apps/api/docs-site/channels/email/mailgun.mdx (1)</summary><blockquote> `143-146`: **Remove form-data from the dependencies table or add it to package.json.** The `form-data` package is listed as a dependency in the documentation but is missing from the project's `package.json`. Either remove it from the documentation (if it's not actually required) or add it as a dependency to the project. The `mailgun.js` version (^10.2.3) is correct and matches the package.json. > Likely an incorrect or invalid review comment. </blockquote></details> <details> <summary>apps/api/docs-site/channels/whatsapp/twilio.mdx (1)</summary><blockquote> `74-74`: **No changes needed.** The specified version `^5.8.0` matches the project's actual dependency in `package.json` and is accurate. The caret operator allows npm to install newer compatible versions (up to 5.11.1), so this version constraint is current and appropriate. </blockquote></details> <details> <summary>apps/api/docs-site/introduction.mdx (1)</summary><blockquote> `1-83`: **LGTM! Well-structured introduction.** The introduction provides a clear overview of OsmoX with appropriate cross-references to other documentation sections. The feature highlights and getting started guide effectively orient new users. </blockquote></details> <details> <summary>apps/api/docs-site/getting-started/architecture.mdx (1)</summary><blockquote> `1-82`: **LGTM! Clear architecture overview.** The architecture documentation effectively explains the system's component interactions and data flow. The visual diagram and step-by-step flow description provide excellent context for developers. </blockquote></details> <details> <summary>apps/api/docs-site/operations/aws-sns.mdx (1)</summary><blockquote> `1-219`: **LGTM! Comprehensive AWS SNS guide.** Excellent detailed guide covering platform-specific payload formats, field references, and usage examples. The warnings about correct formatting and the distinction between sandbox and production environments are particularly helpful. </blockquote></details> <details> <summary>apps/api/docs-site/channels/push/aws-sns.mdx (1)</summary><blockquote> `1-103`: **LGTM! Clear AWS SNS Push configuration guide.** The documentation clearly explains the configuration requirements and request format. The platform-specific examples and the warning about JSON string formatting (with escaped quotes) are particularly valuable for preventing common mistakes. </blockquote></details> <details> <summary>apps/api/docs-site/channels/voice/twilio.mdx (2)</summary><blockquote> `87-89`: No action required. The documentation is accurate per Twilio's official API behavior. When both `url` and `twiml` parameters are provided to the Twilio Calls API, the `twiml` parameter is indeed ignored in favor of `url`. The implementation correctly delegates this behavior to Twilio's native API without enforcing custom precedence logic. This precedence order (where `url` takes precedence over `twiml`) is standard Twilio API design. --- `119-124`: No action needed. The documentation accurately reflects the Twilio version in use (`^5.8.0`). Contrary to the review comment's claim, this version was released on July 24, 2025, making it current and recent rather than outdated from 2019. While newer patch versions exist (5.10.7 as of December 3, 2025), the caret specifier allows automatic updates within the same major version, so this is not a concern. > Likely an incorrect or invalid review comment. </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
| <Accordion title="Example master provider configuration"> | ||
| ```json | ||
| { | ||
| "apikey": { | ||
| "label": "API Key", | ||
| "id": "apikey", | ||
| "pattern": "^[0-19]10$", | ||
| "type": "number" | ||
| } | ||
| } | ||
| ``` | ||
| </Accordion> |
There was a problem hiding this comment.
Clarify or correct the example regex pattern.
The regex pattern "^[0-19]10$" appears incorrect. This would match strings like "010", "110", "210", etc., which seems unintended. If this is meant to be a placeholder example, consider using a more obvious placeholder or a realistic pattern.
🔎 Suggested fix
<Accordion title="Example master provider configuration">
```json
{
"apikey": {
"label": "API Key",
"id": "apikey",
- "pattern": "^[0-19]10$",
+ "pattern": "^[A-Za-z0-9]{20,}$",
"type": "number"
}
}Or if it's truly just a placeholder:
- "pattern": "^[0-19]10$",
+ "pattern": "<your-validation-pattern>",🤖 Prompt for AI Agents
In apps/api/docs-site/getting-started/database.mdx around lines 131 to 142, the
regex "^[0-19]10$" is incorrect and will match unintended short numeric strings;
replace it with a realistic API key pattern such as an alphanumeric length
requirement (for example "^[A-Za-z0-9]{20,}$") and update the field type from
"number" to "string" to reflect that API keys are strings; ensure the JSON
example remains valid and the pattern is clearly documented as an example.
|
|
||
| ## Docker Alternative | ||
|
|
||
| You can also run OsmoX using Docker while using a local database. See the Docker guide in `apps/api/docs/use-local-db-instead-of-dockerized-db/README.md` for details. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if the referenced Docker guide exists in old docs
echo "=== Checking old docs path ==="
find apps/api/docs -name "README.md" -path "*use-local-db*" 2>/dev/null
echo ""
echo "=== Listing apps/api/docs-site structure ==="
find apps/api/docs-site -type f -name "*.md*" | head -20
echo ""
echo "=== Checking if apps/api/docs exists and its structure ==="
if [ -d "apps/api/docs" ]; then
ls -la apps/api/docs/ | head -20
fiRepository: OsmosysSoftware/osmo-x
Length of output: 2501
🏁 Script executed:
#!/bin/bash
# Check for Docker/local-db references in docs-site
echo "=== Searching for Docker or local-db references in docs-site ==="
rg -i "docker|local-db|use-local" apps/api/docs-site/ --type mdx
echo ""
echo "=== Checking what the old docs reference looks like ==="
cat apps/api/docs/use-local-db-instead-of-dockerized-db/README.md | head -30
echo ""
echo "=== Checking all links in development.mdx ==="
cat apps/api/docs-site/getting-started/development.mdx | grep -E "(\[|http|/)" | head -20Repository: OsmosysSoftware/osmo-x
Length of output: 1815
🏁 Script executed:
#!/bin/bash
# Check the full development.mdx file to see context and other references
echo "=== Full development.mdx content ==="
cat -n apps/api/docs-site/getting-started/development.mdx
echo ""
echo "=== Check if docs-site has a guide that could replace this ==="
find apps/api/docs-site -type f \( -name "*.mdx" -o -name "*.md" \) | xargs grep -l -i "docker" 2>/dev/nullRepository: OsmosysSoftware/osmo-x
Length of output: 4286
Align Docker guide reference with new docs-site structure.
The referenced file exists at apps/api/docs/use-local-db-instead-of-dockerized-db/README.md, but the reference pattern is inconsistent with other links in this file, which use relative paths to the new docs-site (e.g., /api-reference/usage, /channels/email/smtp). Either migrate the Docker guide to the docs-site structure with a corresponding relative link, or clarify that this references the legacy docs directory.
🤖 Prompt for AI Agents
In apps/api/docs-site/getting-started/development.mdx around line 117, the
Docker guide link points to
apps/api/docs/use-local-db-instead-of-dockerized-db/README.md which is
inconsistent with this docs-site's relative link style; either (A) move or copy
the guide into the docs-site content and update the link to the new docs-site
path (use the same relative linking pattern used elsewhere, e.g., /api/.. or
/getting-started/..), or (B) explicitly mark the current link as referencing the
legacy docs directory by adding text like “(legacy docs)” and keep the existing
path; update the mdx link accordingly and verify the link resolves after the
change.
| <Step title="Stop containers"> | ||
| ```bash | ||
| docker compose stop | ||
| docker compose down -v | ||
| ``` |
There was a problem hiding this comment.
Add data loss warning for docker compose down -v.
The -v flag removes volumes, which will delete all persistent data including the database. This should have a prominent warning to prevent accidental data loss.
Suggested change
<Step title="Stop containers">
+ <Warning>
+ The `-v` flag removes volumes and will delete all persistent data. Only use this if you intend to reset the database.
+ </Warning>
```bash
docker compose stop
docker compose down -v
```
</Step>🤖 Prompt for AI Agents
In apps/api/docs-site/getting-started/production.mdx around lines 162 to 166,
the docs run "docker compose down -v" without warning that the -v flag removes
volumes and will delete persistent data (e.g., databases); update the section to
add a prominent, inline warning immediately before or after the command noting
that using -v will remove volumes and permanently delete data and recommend
running without -v for routine shutdowns or backing up volumes first, and
optionally show the safer alternative command (docker compose down) and a short
note about backup steps.
| <Step title="Add Documentation"> | ||
| Create `docs/channels/<channel_name>.md` describing: | ||
| - Environment variables | ||
| - Provider usage | ||
| - Sample request body | ||
| - Additional information | ||
|
|
||
| Update `usage-guide.md` to include the new channel. | ||
| </Step> | ||
| </Steps> |
There was a problem hiding this comment.
Update documentation paths to match the actual structure.
The referenced paths don't match the actual documentation structure introduced in this PR:
docs/channels/<channel_name>.mdshould beapps/api/docs-site/channels/<channel_type>/<channel_name>.mdxusage-guide.mdshould beapps/api/docs-site/api-reference/usage.mdx
🔎 Proposed fix
<Step title="Add Documentation">
- Create `docs/channels/<channel_name>.md` describing:
+ Create `apps/api/docs-site/channels/<channel_type>/<channel_name>.mdx` describing:
- Environment variables
- Provider usage
- Sample request body
- Additional information
- Update `usage-guide.md` to include the new channel.
+ Update the site navigation in `apps/api/docs-site/mint.json` to include the new channel.
</Step>📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <Step title="Add Documentation"> | |
| Create `docs/channels/<channel_name>.md` describing: | |
| - Environment variables | |
| - Provider usage | |
| - Sample request body | |
| - Additional information | |
| Update `usage-guide.md` to include the new channel. | |
| </Step> | |
| </Steps> | |
| <Step title="Add Documentation"> | |
| Create `apps/api/docs-site/channels/<channel_type>/<channel_name>.mdx` describing: | |
| - Environment variables | |
| - Provider usage | |
| - Sample request body | |
| - Additional information | |
| Update the site navigation in `apps/api/docs-site/mint.json` to include the new channel. | |
| </Step> | |
| </Steps> |
🤖 Prompt for AI Agents
In apps/api/docs-site/guides/add-provider.mdx around lines 180 to 189, update
the documentation paths to match the repo structure: replace
`docs/channels/<channel_name>.md` with
`apps/api/docs-site/channels/<channel_type>/<channel_name>.mdx` and replace
`usage-guide.md` with `apps/api/docs-site/api-reference/usage.mdx`; ensure the
step text and any example links reflect the new channel_type folder and .mdx
extension so generated docs point to the correct files.
| ```json | ||
| { | ||
| "6": ["abcrecipient@gmail.com"], | ||
| "18": ["+18900100002", "+18900100003", "+18900100004"], |
There was a problem hiding this comment.
Clarify phone number format variation.
Examples show different phone number formats: +18900100002 (US) on line 48 and +918900100002 (India country code +91) on line 132. Without explicit guidance, users may be unsure of the expected format. Either standardize the examples or add a note explaining that phone numbers should include the country code in E.164 format.
🔎 Suggested refinement
Add a clarification note after line 43 or in the Configuration Fields section:
**Phone Number Format:** Phone numbers should follow the E.164 format (e.g., +1 for US, +91 for India). Always include the country code with the + prefix.Also applies to: 132-132
🤖 Prompt for AI Agents
In apps/api/docs-site/guides/test-mode.mdx around lines 48 and 132, examples use
inconsistent phone-number formats which may confuse readers; add a short
clarification that phone numbers must be in E.164 format (include country code
and +) — place the note after line 43 or in the Configuration Fields section and
update examples to either all use the same country format or keep the existing
examples but annotate them as E.164-compliant (e.g., “+1... (US)”, “+91...
(India)”).
| curl --location 'localhost:3000/graphql' \ | ||
| --header 'Authorization: Bearer my-secure-token' \ | ||
| --header 'Content-Type: application/json' \ | ||
| --data '{"query":"mutation UpdateApplication($applicationId: Float!) { updateApplication(updateApplicationInput: { applicationId: $applicationId, testModeEnabled: 1 }) { applicationId name testModeEnabled } }","variables":{"applicationId":2}}' | ||
| ``` | ||
| </Tab> |
There was a problem hiding this comment.
Replace hardcoded localhost:3000 with environment placeholder.
The cURL examples reference localhost:3000, which is a local development URL. This could mislead users copying code for production or staging environments. Use a placeholder like {BASE_URL} and add a note indicating this is for local development, or provide guidance for updating the URL.
🔎 Suggested refinement
- curl --location 'localhost:3000/graphql' \
+ curl --location '{BASE_URL}/graphql' \Then add a note before the cURL tab:
Replace `{BASE_URL}` with your API server URL (e.g., `http://localhost:3000` for local development, or your production API endpoint).
Also applies to: 139-142
🤖 Prompt for AI Agents
In apps/api/docs-site/guides/test-mode.mdx around lines 81-86 (and similarly
139-142), replace the hardcoded 'localhost:3000' in the cURL examples with a
placeholder like '{BASE_URL}' and add a short preceding note telling users to
replace '{BASE_URL}' with their API server URL (e.g., 'http://localhost:3000'
for local dev or their production endpoint); update both cURL blocks to use the
placeholder and add the explanatory sentence immediately above each code block.
| ## Identifying Test Mode Notifications | ||
|
|
||
| Notifications processed in test mode have the following characteristics: | ||
|
|
||
| | Field | Value | | ||
| |-------|-------| | ||
| | `delivery_status` | `SUCCESS` (5) | | ||
| | `result` | `{"result": "This is a test mode notification. Notification was not delivered to recipient."}` | | ||
| | `retry_count` | `0` | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's examine the test-mode.mdx file to see the context
find . -name "test-mode.mdx" -type fRepository: OsmosysSoftware/osmo-x
Length of output: 107
🏁 Script executed:
# Also search for API response examples or documentation about result field
rg -l "result.*test mode notification" --type markdownRepository: OsmosysSoftware/osmo-x
Length of output: 133
🏁 Script executed:
# Look for any API schema or response definitions
find . -name "*.mdx" -o -name "*.md" -o -name "*.json" -o -name "*.ts" | head -20Repository: OsmosysSoftware/osmo-x
Length of output: 752
🏁 Script executed:
# Read the test-mode.mdx file to see the complete context
cat -n ./apps/api/docs-site/guides/test-mode.mdx | head -180Repository: OsmosysSoftware/osmo-x
Length of output: 6335
🏁 Script executed:
# Also check the related test-mode-guide.md
cat -n ./apps/api/docs/test-mode-guide.mdRepository: OsmosysSoftware/osmo-x
Length of output: 8672
🏁 Script executed:
# Search for API response examples or notification schemas
rg -i "delivery_status.*result" --type markdown --type json -A 3 -B 3Repository: OsmosysSoftware/osmo-x
Length of output: 535
🏁 Script executed:
# Look for notification model/schema definitions
find . -name "*.ts" -o -name "*.js" -o -name "*.json" | xargs grep -l "result.*test mode" 2>/dev/null | head -10Repository: OsmosysSoftware/osmo-x
Length of output: 114
🏁 Script executed:
# Search for notification response type definitions
rg -i "notification.*response\|result.*field" apps/api --type ts --type js -A 2 | head -50Repository: OsmosysSoftware/osmo-x
Length of output: 48
🏁 Script executed:
# Check the miscellaneous constants file
cat -n ./apps/api/src/common/constants/miscellaneous.tsRepository: OsmosysSoftware/osmo-x
Length of output: 387
🏁 Script executed:
# Search for notification entity/model definitions
find ./apps/api/src -name "*.ts" -type f | xargs grep -l "notification.*entity\|notification.*model\|result.*field" | head -10Repository: OsmosysSoftware/osmo-x
Length of output: 844
🏁 Script executed:
# Look for database migration files or schema definitions
find ./apps/api -name "*notification*" -type f | grep -E "\.(ts|sql|json)$" | head -20Repository: OsmosysSoftware/osmo-x
Length of output: 1674
🏁 Script executed:
# Search for how TEST_MODE_RESULT_JSON is used
rg "TEST_MODE_RESULT_JSON" ./apps/api/src -A 3 -B 3Repository: OsmosysSoftware/osmo-x
Length of output: 2381
🏁 Script executed:
# Check the notifications constants file
cat -n ./apps/api/src/common/constants/notifications.tsRepository: OsmosysSoftware/osmo-x
Length of output: 2681
🏁 Script executed:
# Search for notification entity/model to see result field type
find ./apps/api/src -name "*notification*entity\|*notification*model" -o -path "*/entities/*notification*" | head -10Repository: OsmosysSoftware/osmo-x
Length of output: 296
🏁 Script executed:
# Check the notification entity to see the result field type
cat -n ./apps/api/src/modules/notifications/entities/notification.entity.ts | head -100Repository: OsmosysSoftware/osmo-x
Length of output: 3226
🏁 Script executed:
# Also check archived notification entity
cat -n ./apps/api/src/modules/archived-notifications/entities/archived-notification.entity.ts | head -100Repository: OsmosysSoftware/osmo-x
Length of output: 3214
Clarify the result field format in the documentation.
The result field in line 158 is a JSON object, not a stringified JSON string. Update the documentation to explicitly state that result is a JSON object of type {"result": "..."} that developers will receive directly (not as a string). This prevents confusion when applications parse the API response.
🤖 Prompt for AI Agents
In apps/api/docs-site/guides/test-mode.mdx around lines 151 to 159, the docs
currently show the `result` field as a quoted string; update the wording to
clarify that `result` is a JSON object (not a stringified JSON) of shape
{"result": "This is a test mode notification. Notification was not delivered to
recipient."} and state that consumers will receive this object directly in the
API response so they should parse it as JSON rather than attempting to
JSON.parse a string.
| curl --location 'http://localhost:3000/graphql' \ | ||
| --header 'Content-Type: application/json' \ | ||
| --header 'x-api-key: OsmoX-test-key' \ | ||
| --header 'Authorization: Bearer OsmoX-test-key' \ | ||
| --data '{"query":"mutation RegisterWebhook { webhook(createWebhookInput: { providerId: 10, webhookUrl: \"http://localhost:4200/webhook\" }) { webhookUrl providerId createdOn updatedOn status } }","variables":{}}' |
There was a problem hiding this comment.
Clarify authentication header usage.
The cURL example uses both x-api-key and Authorization: Bearer headers with the same test key value. This appears inconsistent. Please clarify:
- Does the GraphQL endpoint require both headers?
- Or should only one authentication method be used?
Typically, an API would use either API key authentication OR Bearer token authentication, not both simultaneously.
Note on static analysis hint
The static analysis tool flagged this as containing an authorization token. This is a false positive since these are example placeholder values (OsmoX-test-key) for documentation purposes.
🧰 Tools
🪛 Gitleaks (8.30.0)
[high] 42-44: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
🤖 Prompt for AI Agents
In apps/api/docs-site/guides/webhooks.mdx around lines 42 to 46, the cURL
example sends both x-api-key and Authorization: Bearer headers which is
confusing; clarify which authentication method the GraphQL endpoint expects (API
key or Bearer token), then update the example to use only the correct header (or
provide two separate examples labeled "API key" and "Bearer token" if both
methods are supported), remove the redundant header, and add a short note that
the shown OsmoX-test-key value is a placeholder to avoid static-analysis false
positives.
API PR Checklist
Task Link
N/A
Pre-requisites
.env.examplefile with the required values as applicable.PR Details
PR details have been updated as per the given format (see below)
feat: add admin login endpoint)Additional Information
ready for reviewshould be added if the PR is ready to be reviewed)Note: Reviewer should ensure that the checklist and description have been populated and followed correctly, and the PR should be merged only after resolving all conversations and verifying that CI checks pass.
Description:
Related changes:
N/A
Screenshots:
N/A
Query request and response:
N/A
Documentation changes:
N/A
Test suite/unit testing output:
N/A
Pending actions:
N/A
Additional notes:
Site: https://osmosyssoftwaresolution-4707f81e.mintlify.app/introduction