feat: add environment and workflows apis #881
Conversation
✅ Deploy Preview for docs-novu ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
WalkthroughThis update introduces comprehensive API documentation for the "Environments" and "Workflows" features, including new endpoint references and schema definitions. It also updates type definitions for subscribers and SDKs, enhancing type flexibility and customization. Dependency versions for several Novu packages are incremented, and the API documentation index is reorganized to include the new sections. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant API
participant Docs
Client->>Docs: View API Reference
Docs->>API: Reference endpoint schema (e.g., /v1/environments)
Client->>API: Call endpoint (create, update, delete, list environment/workflow)
API-->>Client: Return response (Environment/Workflow object)
Possibly related PRs
Suggested reviewers
Poem
✨ Finishing Touches
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (12)
content/docs/platform/sdks/javascript/index.mdx (1)
21-24: OptionalapplicationIdentifiertype update is correct.
Updating the type tostring | undefinedreflects the new optional behavior. Consider adding a minimal example that omits this field to illustrate its optionality in practice.content/docs/platform/sdks/react/index.mdx (2)
17-20: MarkapplicationIdentifieras optional.
The change tostring | undefinedis accurate. Consider updating theInboxusage example to demonstrate initializing without this prop.
99-104: Includeiconsoverride example.
Theiconsproperty inInboxAppearancePropsenables icon customization. Adding a small code sample demonstrating icon overrides will improve discoverability.content/docs/api-reference/events/broadcast-event-to-all.mdx (2)
14-21: Remove extra blank lines. This block contains unnecessary blank lines that can be trimmed to improve readability and maintain consistency with surrounding content.
28-35: Remove extra blank lines. These consecutive blank lines are redundant; removing them will tighten the layout.content/docs/api-reference/environments/list-all-environments.mdx (2)
11-14: Normalize indentation in structuredData.contents.
The multi-line block has inconsistent leading spaces which may render extra indentation. Consider unifying the indent:- - content: |- - This API returns a list of environments for the current organization. - Each environment contains its configuration, API keys (if user has access), and metadata. + - content: |- + This API returns a list of environments for the current organization. + Each environment contains its configuration, API keys (if user has access), and metadata.
18-19: Page description duplicates structuredData.
Optional: you may streamline the markdown by consolidating or differentiating the in-body description fromstructuredData.content/docs/api-reference/environments/delete-an-environment.mdx (1)
11-13: Align indentation in multi-line descriptionThe content block uses uneven indentation, which may introduce unintended whitespace in the rendered doc. Consider this adjustment:
- - content: |- - Delete an environment by its unique identifier **environmentId**. - This action is irreversible and will remove the environment and all its associated data. + - content: |- + Delete an environment by its unique identifier **environmentId**. + This action is irreversible and will remove the environment and all its associated data.content/docs/api-reference/environments/update-an-environment.mdx (1)
11-14: Align indentation in multi-line descriptionThe description block has inconsistent indentation. Harmonize it as follows:
- - content: |- - Update an environment by its unique identifier **environmentId**. - You can modify the environment name, identifier, color, and other configuration settings. + - content: |- + Update an environment by its unique identifier **environmentId**. + You can modify the environment name, identifier, color, and other configuration settings.content/docs/api-reference/workflows/workflow-schema.model.mdx (1)
7-7: Fix double punctuation
Remove the extra period after "debugging" to avoid a typographical error.
Suggested change:- ... debugging.. Read more about workflows ... + ... debugging. Read more about workflows ...content/docs/api-reference/workflows/workflow-schema.mdx (2)
7-7: Fix double punctuation
Remove the extra period after "debugging" to correct the typo.- ... debugging.. Read more about workflows ... + ... debugging. Read more about workflows ...
9-94: Populate or omit empty field descriptions
All properties in theTypeTablehave emptydescriptionfields, which undermines clarity. Please source descriptions from the API spec or remove the empty keys to streamline the documentation.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (23)
content/docs/api-reference/api-types.ts(2 hunks)content/docs/api-reference/environments/create-an-environment.mdx(1 hunks)content/docs/api-reference/environments/delete-an-environment.mdx(1 hunks)content/docs/api-reference/environments/environment-schema.mdx(1 hunks)content/docs/api-reference/environments/environment-schema.model.mdx(1 hunks)content/docs/api-reference/environments/list-all-environments.mdx(1 hunks)content/docs/api-reference/environments/update-an-environment.mdx(1 hunks)content/docs/api-reference/events/broadcast-event-to-all.mdx(1 hunks)content/docs/api-reference/meta.json(1 hunks)content/docs/api-reference/subscribers/subscriber-schema.mdx(3 hunks)content/docs/api-reference/topics/topic-schema.mdx(3 hunks)content/docs/api-reference/workflows/create-a-workflow.mdx(1 hunks)content/docs/api-reference/workflows/delete-a-workflow.mdx(1 hunks)content/docs/api-reference/workflows/list-all-workflows.mdx(1 hunks)content/docs/api-reference/workflows/retrieve-a-workflow.mdx(1 hunks)content/docs/api-reference/workflows/retrieve-workflow-step.mdx(1 hunks)content/docs/api-reference/workflows/sync-a-workflow.mdx(1 hunks)content/docs/api-reference/workflows/update-a-workflow.mdx(1 hunks)content/docs/api-reference/workflows/workflow-schema.mdx(1 hunks)content/docs/api-reference/workflows/workflow-schema.model.mdx(1 hunks)content/docs/platform/sdks/javascript/index.mdx(3 hunks)content/docs/platform/sdks/react/index.mdx(7 hunks)package.json(1 hunks)
🧰 Additional context used
🪛 LanguageTool
content/docs/api-reference/workflows/workflow-schema.model.mdx
[typographical] ~7-~7: Two consecutive dots
Context: ...tivity Feed for monitoring and debugging.. Read more about workflows on [workflows...
(DOUBLE_PUNCTUATION)
content/docs/api-reference/workflows/workflow-schema.mdx
[typographical] ~7-~7: Two consecutive dots
Context: ...tivity Feed for monitoring and debugging.. Read more about workflows on [workflows...
(DOUBLE_PUNCTUATION)
⏰ Context from checks skipped due to timeout of 90000ms (4)
- GitHub Check: Redirect rules - docs-novu
- GitHub Check: Header rules - docs-novu
- GitHub Check: Pages changed - docs-novu
- GitHub Check: Build and Lint
🔇 Additional comments (55)
package.json (1)
24-27: Dependency bumps look correct.
The versions for@novu/api,@novu/framework,@novu/js, and@novu/reactalign with the newly introduced environment and workflow APIs. Ensure the corresponding release notes have been reviewed for compatibility.content/docs/platform/sdks/javascript/index.mdx (1)
111-118: Newdatafilter property added correctly.
The addition ofdata: Record<string, unknown>toNotificationFilterallows arbitrary key-value filtering. Please double-check downstream type definitions and ensure examples handle this property as expected.content/docs/platform/sdks/react/index.mdx (3)
405-410: Approve new element style keylockIcon.
The addition oflockIcontoInboxAppearanceElementsprovides fine-grained UI control and aligns with the broader style API.
743-750: Approve new workflow label style keys.
TheworkflowLabelHeaderContainerandworkflowLabelIconkeys correctly extend the appearance API for workflows.
775-783: Approve preference group style keys.
The newly addedpreferencesGroup*keys offer granular styling for preference groups and integrate well with the updated API.content/docs/api-reference/topics/topic-schema.mdx (9)
63-66: AllowfirstNameto be nullable. Updating the type tostring | nullensures that the field can be explicitly null or omitted, aligning with the flexible subscriber model.
67-70: AllowlastNameto be nullable. Changing the type tostring | nullreflects that the field may be absent or intentionally null.
71-74: Allowstring | nullaccommodates cases where email may not be provided.
75-78: Allowphoneto be nullable. Thestring | nulltype handles scenarios without a phone number.
79-82: Allowavatarto be nullable. Usingstring | nullcovers subscribers without avatars.
83-86: Allowlocaleto be nullable. Changing tostring | nullsupports unspecified locale preferences.
95-98: AllowisOnlineto be nullable. Adjusting toboolean | nullcaptures unknown or unset online status.
99-102: AllowlastOnlineAtto be nullable. Switching tostring | nullhandles cases where last online timestamp is unavailable.
111-114: Allowtimezoneto be nullable. Usingstring | nullsupports subscribers without a defined timezone.content/docs/api-reference/subscribers/subscriber-schema.mdx (9)
13-16: AllowfirstNameto be nullable. Changing tostring | nullensures consistency with optional subscriber fields.
17-20: AllowlastNameto be nullable. The update tostring | nullreflects real-world usage where last name may be omitted.
21-24: Allowstring | nullaligns with flexible subscriber profiles.
25-28: Allowphoneto be nullable. Switching tostring | nullaccommodates subscribers without a phone.
29-32: Allowavatarto be nullable. Thestring | nulltype handles missing avatars.
33-36: Allowlocaleto be nullable. Changing tostring | nullsupports unspecified locale settings.
45-48: AllowisOnlineto be nullable. Adjusting toboolean | nullcaptures undetermined online status.
49-52: AllowlastOnlineAtto be nullable. Switching tostring | nullcovers cases where the timestamp is not set.
61-64: Allowtimezoneto be nullable. Usingstring | nullhandles subscribers without a timezone.content/docs/api-reference/environments/environment-schema.model.mdx (1)
1-11: Document new Environment schema. The new file correctly introduces the Environment type and includes a type table reference toEnvironmentinapi-types.ts.content/docs/api-reference/workflows/sync-a-workflow.mdx (1)
1-18: Add workflow synchronization endpoint documentation. The file accurately defines thePUT /v2/workflows/{workflowId}/syncoperation with the appropriate metadata, auto-generation notice, and APIPage component.content/docs/api-reference/workflows/create-a-workflow.mdx (4)
1-12: Frontmatter configuration is correct.
The YAML metadata correctly specifies the POST method and/v2/workflowsroute.
14-14: Auto-generated file notice is present.
The notice prevents manual edits and reminds maintainers to re-run the generation command.
16-17: Page title and description match the endpoint.
The human-readable title and summary clearly describe the “create workflow” operation.
18-18: Verify API specification link and operation details.
Ensure thedocumentURL is current and that the OpenAPI spec defines a POST/v2/workflowsoperation.#!/bin/bash # Verify the OpenAPI spec contains the POST /v2/workflows operation curl -s https://spec.speakeasy.com/novu/novu/json-development-with-code-samples | jq '.paths["/v2/workflows"].post'content/docs/api-reference/workflows/retrieve-a-workflow.mdx (3)
1-14: Frontmatter and descriptive block are accurate.
The GET method, route/v2/workflows/{workflowId}, and description align with the retrieve operation.
16-18: Auto-generated notice and summary are present.
The file correctly warns against manual edits and repeats the summary.
20-20: Verify APIPage configuration.
Confirm the spec URL and theoperationspath{workflowId}placeholder mapping are correct.#!/bin/bash # Verify the OpenAPI spec contains the GET /v2/workflows/{workflowId} operation curl -s https://spec.speakeasy.com/novu/novu/json-development-with-code-samples | jq '.paths["/v2/workflows/{workflowId}"].get'content/docs/api-reference/meta.json (2)
47-61: Workflows group added to navigation index.
The new"---Workflows---"section and its entries for schema, CRUD, list, sync, and steps are correctly positioned.
62-68: Environments group added to navigation index.
The"---Environments---"section with schema, create, update, delete, and list entries is correctly inserted.content/docs/api-reference/environments/list-all-environments.mdx (3)
1-10: Frontmatter configuration is correct.
The GET/v1/environmentsroute and metadata accurately reflect the “list all environments” endpoint.
16-16: Auto-generated file notice is present.
The generation comment correctly warns against manual edits.
21-21: ```shell
#!/bin/bashShow the GET operation under /v1/environments in the OpenAPI spec
curl -s https://spec.speakeasy.com/novu/novu/json-development-with-code-samples
| grep -n -A5 '/v1/environments:'</details> <details> <summary>content/docs/api-reference/workflows/delete-a-workflow.mdx (4)</summary> `1-11`: **Frontmatter configuration is correct.** The DELETE method, route `/v2/workflows/{workflowId}`, and description match the delete operation. --- `14-14`: **Auto-generated file notice is present.** The generation comment prevents manual edits. --- `16-17`: **Operation description matches metadata.** The inline summary clearly states the removal of a workflow by its `workflowId`. --- `18-18`: **Verify DELETE operation in spec.** Confirm the OpenAPI document defines the DELETE `/v2/workflows/{workflowId}` operation: ```shell #!/bin/bash # Check for DELETE /v2/workflows/{workflowId} in the spec curl -s https://spec.speakeasy.com/novu/novu/json-development-with-code-samples | jq '.paths["/v2/workflows/{workflowId}"].delete'content/docs/api-reference/workflows/retrieve-workflow-step.mdx (2)
1-12: Frontmatter validation: GET endpoint configuration looks correctThe
_openapimetadata correctly specifies the GET method and the route/v2/workflows/{workflowId}/steps/{stepId}, andtoc/structuredDataare properly initialized.
16-18: APIPage component configuration is accurateThe
<APIPage>invocation correctly references the intended operation path and spec URL.content/docs/api-reference/api-types.ts (2)
1-16: Import ofEnvironmentResponseDtois correctThe new import from
@novu/api/models/componentsaddsEnvironmentResponseDtoand is used below to define theEnvironmentalias.
40-45: Exports forEnvironmentandWorkflowtypes are correctly organizedThe file now cleanly groups the
EnvironmentandWorkflowtype aliases at the end, making the exports more domain-centric.content/docs/api-reference/environments/delete-an-environment.mdx (2)
1-14: Frontmatter metadata for DELETE/v1/environments/{environmentId}is correctThe
_openapiblock properly defines the DELETE method and route, and the structured data sections are initialized without unintended values.
17-21: Duplicate description outside frontmatter is expected for auto-generated docs. The generator handles synchronization.content/docs/api-reference/environments/update-an-environment.mdx (2)
1-14: Frontmatter metadata for PUT/v1/environments/{environmentId}is correctThe
_openapiblock is configured correctly for the update endpoint. All fields are properly set.
17-21: Duplicate description outside frontmatter is normal for the auto-generated pages.content/docs/api-reference/workflows/update-a-workflow.mdx (2)
1-14: Frontmatter metadata for PUT/v2/workflows/{workflowId}is correctThe
_openapiblock correctly defines the PUT method and route. The metadata aligns with other workflow endpoints.
17-20: The content duplication outside frontmatter is expected in auto-generated docs.content/docs/api-reference/environments/create-an-environment.mdx (1)
1-23: New endpoint documentation looks correct—approved
The frontmatter, descriptive copy, and<APIPage>component align with existing API references. The auto-generated notice guards against manual edits.content/docs/api-reference/workflows/workflow-schema.model.mdx (1)
1-11: Workflow schema model is well-structured—approved
Frontmatter, heading, and the---type-table---reference toWorkfloware correctly defined and consistent with other model files.content/docs/api-reference/workflows/list-all-workflows.mdx (1)
1-18: List-all-workflows endpoint doc is properly structured
Frontmatter metadata, auto-generated notice, and<APIPage>integration match project conventions.content/docs/api-reference/environments/environment-schema.mdx (1)
1-38: Environment schema type table is correctly defined—approved
All environment properties and descriptions align with the API spec and follow theTypeTableformat.
| "type": "PreferencesFilter" | ||
| }, | ||
| "preferenceGroups": { | ||
| "description": "", | ||
| "type": "PreferenceGroups" | ||
| }, |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Document the new preferenceGroups prop.
You’ve introduced a preferenceGroups prop in InboxProps. Please include a snippet in the usage section showing how to pass this prop and describe its purpose.
🤖 Prompt for AI Agents
In content/docs/platform/sdks/react/index.mdx around lines 47 to 52, the new
preferenceGroups prop in InboxProps is undocumented. Add a usage example snippet
demonstrating how to pass the preferenceGroups prop and include a clear
description of its purpose in the usage section to help users understand its
role and how to use it.
Summary by CodeRabbit
New Features
Improvements
Chores