Merge pull request #452 from kinde-oss/feat/pre-reg-workflow

Pre-registration workflow docs

Author: DaveOrDead

src/components/APICards.astro

@@ -23,21 +23,21 @@
   <li
     class="relative flex list-none flex-col gap-4 rounded-2xl bg-kinde-grey-50 p-12 dark:bg-kinde-grey-900"
   >
-    <h3>Kinde Frontend API</h3>
+    <h3>Account API</h3>
     <p>
-      For managing the currently signed-in user, includes getting their profile and revoking tokens
+      For managing the currently signed-in user, includes e.g their profile, roles, permissions, billing info and revoking tokens
     </p>
     <p
       aria-hidden="true"
       class="mt-12 text-inherit underline decoration-inherit underline-offset-[6px] transition-all hover:text-current"
     >
-      Explore the Frontend API reference
+      Explore the Account API reference
     </p>
     <a
       href="/kinde-apis/frontend/"
       class="absolute inset-0 rounded-2xl transition duration-200 hover:ring-2 hover:ring-black focus:border-0 focus:shadow-none focus:ring-2 focus:ring-black focus-visible:overflow-hidden focus-visible:border-none focus-visible:shadow-none focus-visible:outline-black focus-visible:ring-2 focus-visible:ring-black dark:hover:ring-white dark:focus:ring-white dark:focus-visible:outline-white dark:focus-visible:ring-white"
     >
-      <span class="sr-only">Go to the Kinde Frontend API reference docs</span>
+      <span class="sr-only">Go to the Kinde Account API reference docs</span>
     </a>
   </li>
 </ul>

src/content/docs/workflows/about-workflows/index.mdx

@@ -15,6 +15,7 @@ Develop code in your own repo, and push it to a Kinde workflow, where we execute
 
 Currently, you can use the following triggers:
 
+- [user:pre_registration](/workflows/example-workflows/pre-user-registration-workflow/) - when a user attempts to register an account.
 - [user:post_authentication](/workflows/example-workflows/workflow-user-post-auth/) fires after the user has completed single factor authentication (e.g. email + password or Google), and before authorization.
 - [m2m:token_generation](/workflows/example-workflows/m2m-token-generation-workflow/) - when a request to the token endpoint is made with an M2M application.
 - [user:new_password_provided](/workflows/example-workflows/new-password-provided-workflow/) - when a user requests to create or reset a password.
@@ -34,7 +35,7 @@ We will add more triggers (and allow you to create your own) as we develop the f
 ## Basic workflow rules
 
 - Workflow actions need to be written in TypeScript or plain JavaScript
-- Filenames must end in the word 'Workflow' for Kinde to recognize them as containing workflow code. For example, `MFAWorkflow.ts` or `PreauthorizationWorkflow.jsx` 
+- Filenames must end in the word 'Workflow' for Kinde to recognize them as containing workflow code. For example, `MFAWorkflow.ts` or `PreauthorizationWorkflow.jsx`
 - File extensions should be .ts, .js, .tsx or .jsx
 - Each trigger can only have one workflow
 - Only Kinde-defined triggers are available (for now)

src/content/docs/workflows/bindings/auth-binding.mdx

@@ -18,6 +18,7 @@ Prevent the user from accessing the application.
 
 ## Available in workflows
 
+- [user:pre_registration](/workflows/example-workflows/pre-user-registration-workflow/)
 - [user:post_authentication](/workflows/example-workflows/workflow-user-post-auth/)
 - [user:new_password_provided](/workflows/example-workflows/new-password-provided-workflow/)
 - [user:existing_password_provided](/workflows/example-workflows/existing-password-provided-workflow/)

src/content/docs/workflows/bindings/env-binding.mdx

@@ -21,12 +21,15 @@ Secret variables will be redacted in the logs.
 
 ## Available in workflows
 
+- [user:pre_registration](/workflows/example-workflows/pre-user-registration-workflow/)
 - [user:post_authentication](/workflows/example-workflows/workflow-user-post-auth/)
 - [m2m:token_generation](/workflows/example-workflows/m2m-token-generation-workflow/)
 - [user:new_password_provided](/workflows/example-workflows/new-password-provided-workflow/)
 - [user:existing_password_provided](/workflows/example-workflows/existing-password-provided-workflow/)
 - [user:tokens_generation](/workflows/example-workflows/user-token-generation/)
 - [user:pre_mfa](/workflows/example-workflows/pre-mfa-workflow/)
+- [user:plan_selection](/workflows/example-workflows/plan-selection-workflow/)
+- [user:plan_cancellation_request](/workflows/example-workflows/plan-cancellation-request-workflow/)
 
 ## Configuration
 

src/content/docs/workflows/bindings/fetch-binding.mdx

@@ -14,12 +14,15 @@ If you are passing sensitive data we recommend you instead use [kinde.secureFetc
 
 ## Available in workflows
 
+- [user:pre_registration](/workflows/example-workflows/pre-user-registration-workflow/)
 - [user:post_authentication](/workflows/example-workflows/workflow-user-post-auth/)
 - [m2m:token_generation](/workflows/example-workflows/m2m-token-generation-workflow/)
 - [user:new_password_provided](/workflows/example-workflows/new-password-provided-workflow/)
 - [user:existing_password_provided](/workflows/example-workflows/existing-password-provided-workflow/)
 - [user:tokens_generation](/workflows/example-workflows/user-token-generation/)
 - [user:pre_mfa](/workflows/example-workflows/pre-mfa-workflow/)
+- [user:plan_selection](/workflows/example-workflows/plan-selection-workflow/)
+- [user:plan_cancellation_request](/workflows/example-workflows/plan-cancellation-request-workflow/)
 
 ## Configuration
 

src/content/docs/workflows/bindings/secure-fetch-binding.mdx

@@ -13,12 +13,15 @@ The `kinde.secureFetch` binding allows you to make POST requests to external API
 
 ## Available in workflows
 
+- [user:pre_registration](/workflows/example-workflows/pre-user-registration-workflow/)
 - [user:post_authentication](/workflows/example-workflows/workflow-user-post-auth/)
 - [m2m:token_generation](/workflows/example-workflows/m2m-token-generation-workflow/)
 - [user:new_password_provided](/workflows/example-workflows/new-password-provided-workflow/)
 - [user:existing_password_provided](http://localhost:4321/workflows/example-workflows/existing-password-provided-workflow/)
 - [user:tokens_generation](/workflows/example-workflows/user-token-generation/)
 - [user:pre_mfa](http://localhost:4321/workflows/example-workflows/pre-mfa-workflow/)
+- [user:plan_selection](/workflows/example-workflows/plan-selection-workflow/)
+- [user:plan_cancellation_request](/workflows/example-workflows/plan-cancellation-request-workflow/)
 
 ## Configuration
 

src/content/docs/workflows/bindings/url-binding.mdx

@@ -12,12 +12,15 @@ The `url` binding allows you to access the native JavaScript `URLSearchParams` A
 
 ## Available in workflows
 
+- [user:pre_registration](/workflows/example-workflows/pre-user-registration-workflow/)
 - [user:post_authentication](/workflows/example-workflows/workflow-user-post-auth/)
 - [m2m:token_generation](/workflows/example-workflows/m2m-token-generation-workflow/)
 - [user:new_password_provided](/workflows/example-workflows/new-password-provided-workflow/)
 - [user:existing_password_provided](/workflows/example-workflows/existing-password-provided-workflow/)
 - [user:tokens_generation](/workflows/example-workflows/user-token-generation/)
 - [user:pre_mfa](/workflows/example-workflows/pre-mfa-workflow/)
+- [user:plan_selection](/workflows/example-workflows/plan-selection-workflow/)
+- [user:plan_cancellation_request](/workflows/example-workflows/plan-cancellation-request-workflow/)
 
 ## Configuration
 

src/content/docs/workflows/example-workflows/pre-user-registration-workflow.mdx

@@ -0,0 +1,70 @@
+---
+page_id: 69b42223-701c-4707-b961-e52c7cb05399
+title: User pre-registration workflow
+sidebar:
+  order: 7
+relatedArticles:
+  - 62fafade-5d33-4f85-9fd2-712c533db3d0
+  - f499ebb0-d7f5-4244-bf92-6bf0f6082b62
+---
+
+Trigger: `user:pre_registration`
+
+This trigger fires after the user has completed single factor authentication (e.g email + password or Google) but before a user record is created in Kinde.
+
+<Aside type="warning">
+
+At this stage the user is not authorized - we have not checked organization access or carried out MFA.
+
+</Aside>
+
+## Example use cases
+
+### IP address checks
+
+Block user registrations from suspicious IP addresses.
+
+### Block disposable email addresses
+
+Refuse disposable email addresses to prevent spam registrations.
+
+## Workflow code
+
+### Sample event object
+
+The main argument provided to your code is the Kinde workflow `event` object which has two keys `request` and `context`. This gives you access to the reason the workflow was triggered and additional relevant datapoints. Here's an example:
+
+```json
+{
+  "request": {
+    "ip": "***",
+    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:135.0) Gecko/20100101 Firefox/135.0",
+    "authUrlParams": {
+      "state": "b9ea1131f7796a10abe8eac1b48c715575a0ffd349fb9c602e13d824",
+      "orgCode": "org_12345667",
+      "clientId": "cad2d86b1ac645e1957889fcb1eff0f9",
+      "redirectUri": "http://localhost:3000"
+    }
+  },
+  "context": {
+    "auth": {
+      "connectionId": "conn_0194ee03c226d48c6858d5a412359ed2"
+    },
+    "domains": {
+      "kindeDomain": "https://newbus.localkinde.me"
+    },
+    "workflow": {
+      "trigger": "user:pre_registration"
+    },
+    "application": {
+      "clientId": "cad2d86b1ac645e1957889fcb1eff0f9"
+    }
+  }
+}
+```
+
+### Example workflows
+
+See examples on GitHub:
+
+[Prevent disposable email sign ups](https://github.com/kinde-starter-kits/workflow-examples/blob/main/preUserRegistration/blockDisposableEmails.ts) - Check the email address against a list of disposable email domains and block the registration if it matches.

src/content/docs/workflows/getting-started/workflow-examples.mdx

@@ -23,6 +23,7 @@ You can use this in conjunction with the example files below to create more comp
 
 These can be used as a starting point for your own workflows. You can find them in the [Kinde GitHub repo](https://github.com/kinde-starter-kits/workflow-examples). Either copy the files you need into your existing project or the base template above.
 
+- [Block disposable emails](https://github.com/kinde-starter-kits/workflow-examples/blob/main/preUserRegistration/blockDisposableEmails.ts) - Prevent users from creating accounts with disposable email addresses.
 - [Drip feed migration](https://github.com/kinde-starter-kits/workflow-examples/blob/main/existingPassword/dripFeedMigrationWorkflow.ts) - Shows how to check a password against an external database before creating the user in Kinde.
 - [Sync passwords to another system](https://github.com/kinde-starter-kits/workflow-examples/blob/main/newPassword/securelySyncPasswordWorkflow.ts) - Use encryption keys to securely keep passwords in sync between systems.
 - [Custom password validation](https://github.com/kinde-starter-kits/workflow-examples/blob/main/newPassword/customPasswordValidationWorkflow.ts) - Shows how to validate a password against your own rules.

src/pages/kinde-apis.astro

@@ -6,7 +6,7 @@ import APICards from "@components/APICards.astro";
 <StarlightPage
   frontmatter={{
     title: "Kinde APIs",
-    description: "Use the Management API for account admin tasks, or the Frontend API for user profile and token management.",
+    description: "Use the Management API for account admin tasks, or the Account API for current user and token management.",
     template: "splash",
     editUrl: false,
     page_id: "31b91e66-7f86-4fd9-b3c7-b4d0a2a86d6e"