Merge pull request #456 from panoratech/feat/update-docs

📝 Docs update

apps/client-ts/src/components/Configuration/Catalog/CopySnippet.tsx

@@ -25,11 +25,12 @@ export const CopySnippet = () => {
 
     const handleCopyLeft = () => {
         navigator.clipboard.writeText(
-            `<DynamicCatalog>
-            projectId={'c9a1b1f8-466d-442d-a95e-11cdd00baf49'}
-            returnUrl={'https://acme.inc'}
-            linkedUserId={'b860d6c1-28f9-485c-86cd-fb09e60f10a2'}
-            </DynamicCatalog>`
+            `<PanoraDynamicCatalog
+                category={"crm"}
+                projectId={"c9a1b1f8-466d-442d-a95e-11cdd00baf49"}
+                returnUrl={"https://acme.inc"}
+                linkedUserId={"b860d6c1-28f9-485c-86cd-fb09e60f10a2"}
+            />`
         );
         toast.success("Code snippet copied", {
             action: {
@@ -45,13 +46,13 @@ export const CopySnippet = () => {
 
     const handleCopyRight = () => {
         navigator.clipboard.writeText(
-            `<PanoraProviderCard>
-            name={'hubspot'}
-            vertical={'crm'}
-            projectId={'c9a1b1f8-466d-442d-a95e-11cdd00baf49'}
-            returnUrl={'https://acme.inc'}
-            linkedUserId={'b860d6c1-28f9-485c-86cd-fb09e60f10a2'}
-            </PanoraProviderCard>`
+            `<PanoraProviderCard
+            name={"hubspot"}
+            category={"crm"}
+            projectId={"c9a1b1f8-466d-442d-a95e-11cdd00baf49"}
+            returnUrl={"https://acme.inc"}
+            linkedUserId={"b860d6c1-28f9-485c-86cd-fb09e60f10a2"} 
+          />`
         );
         toast.success("Code snippet copied", {
             action: {
@@ -120,9 +121,12 @@ export const CopySnippet = () => {
                     <span className="flex flex-col gap-2">
                         <span className="flex-1">
                         <span>
-                            {`<DynamicCatalog>`}
+                            {`<PanoraDynamicCatalog>`}
                         </span>
                         </span>
+                        <span className="pl-4">
+                            <span className="text-green-800">category</span>{`=crm`}
+                        </span>
                         <span className="pl-4">
                             <span className="text-cyan-600">projectId</span>{`={'c9a1b1f8-466d-442d-a95e-11cdd00baf49'}`}
                         </span>
@@ -134,7 +138,7 @@ export const CopySnippet = () => {
                         </span> 
                         <span className="flex-1">
                         <span>
-                            {`</DynamicCatalog>`}
+                            {`</PanoraDynamicCatalog>`}
                         </span>
                         </span>
                     </span>
@@ -181,7 +185,7 @@ export const CopySnippet = () => {
                       <span className="text-lime-500">name</span>{`={'hubspot'}`}
                     </span>
                     <span className="pl-4">
-                        <span className="text-fuchsia-200">vertical</span>{`={'crm'}`}
+                        <span className="text-fuchsia-200">category</span>{`={'crm'}`}
                     </span>
                     <span className="pl-4">
                         <span className="text-cyan-600">projectId</span>{`={'c9a1b1f8-466d-442d-a95e-11cdd00baf49'}`}

apps/magic-link/src/hooks/queries/useLinkedUser.tsx

@@ -10,7 +10,7 @@ const useLinkedUser = (id: string) => {
         if (!response.ok) {
           throw new Error('Network response was not ok');
         }
-        return response.json();
+        return response.json(); 
     }
   });
 };

docs/core-concepts/custom-fields.mdx

@@ -11,7 +11,17 @@ Creating a `Field Mapping` involves two majors actions:
 - Defining a custom field on Panora's side
 - Mapping it to a field from your customer's software.
 
-_insert video_
+In this video we define a field and then once a connection is available we fetch fields inside your user's software so you can map the custom field with Panora.
+
+<Frame type="glass">
+  <video
+    controls
+    className="w-full aspect-video"
+    src="/images/definefields.mp4"
+  ></video>
+</Frame>
+
+## Create a custom field mapping using our UI dashboard
 
 <Steps>
 
@@ -20,23 +30,74 @@ _insert video_
     </Step>
 
     <Step title="Define your custom field">
-    Click `Add Field Mapping`. Select a unified object you want to extend, and give your custom field a slug and a friendly name. You also need to select a data type.
+    Click `Define a custom field`. Select a unified object you want to extend, and give your custom field a slug and a friendly name. You also need to select a data type.
     </Step>
 
     <Step title="Map your custom field to a remote field">
 
-Now, move to the `Map Fields` section. To finish the mapping, select the custom field you just created, and fill the fields `Provider` and Linked User ID.
+Now, click on the `Map a custom field` button. To finish the mapping, select the custom field you just created, and fill the fields `Provider` and `Linked User Id`.
 
 </Step>
 
     <Step>
 
-You will now find all the fields your user has in its software. Pick the one that you want to map to.
+You will now find all the fields your user has in its software. Pick the one that you want to map to. Click `Map`.
 
 </Step>
 
 </Steps>
 
+## Create a custom field mapping using our API
+
+The following example creates a custom field mapping in two steps (**define and map**) where we map a remote field called `hair_color_hubspot_123_id` (existing in the `Husbpot` provider) and mapping it to the `crm.contact` unified model of Panora under the name of `hair_color`.
+
+ ```shell Create custom field
+        curl --request POST \
+             --url https://api.panora.dev/field-mappings \
+             --header 'Authorization: Bearer <MY_API_KEY>' \
+             --header 'Content-Type: application/json' \
+             --data '{
+                "object_type_owner": "crm.contact",
+                "name": "hair_color",
+                "description": "My hair_color field mapping",
+                "data_type": "text",
+                "source_custom_field_id": "hair_color_hubspot_123_id",  # id of the remote field inside the remote provider
+                "source_provider": "hubspot",
+                "linked_user_id": "acme_customer_a"
+             }'
+        ```
+<Info>You may want to define it in two steps if you miss some information to map in the 1st step.</Info>
+
+The following example creates a custom field mapping in two steps (**define and map**) where we map a remote field called `hair_color_hubspot_123_id` (existing in the `Husbpot` provider) and mapping it to the `crm.contact` unified model of Panora under the name of `hair_color`.
+
+        <CodeGroup>
+        ```shell Define custom field
+        curl --request POST \
+             --url https://api.panora.dev/field-mappings/define \
+             --header 'Authorization: Bearer <MY_API_KEY>' \
+             --header 'Content-Type: application/json' \
+             --data '{
+                "object_type_owner": "crm.contact",
+                "name": "hair_color",
+                "description": "My hair_color field mapping",
+                "data_type": "text"
+             }'
+        ```
+
+        ```shell Map custom field
+        curl --request POST \
+             --url https://api.panora.dev/field-mappings/map \
+             --header 'Authorization: Bearer <MY_API_KEY>' \
+             --header 'Content-Type: application/json' \
+             --data '{
+                "attributeId": "id_defined_field", # retrieve that from response of the /define request
+                "source_custom_field_id": "hair_color_hubspot_123_id", # id of the remote field inside the remote provider
+                "source_provider": "hubspot",
+                "linked_user_id": "acme_customer_a"
+             }'
+        ```
+        </CodeGroup>
+
 [✏️ Suggest an update](https://tally.so/r/mRD1QQ?feedback_source=custom_fields)
 
 [Need help? Come chat on Discord!](https://discord.gg/G7fr4HNyTb)

docs/core-concepts/magic-links.mdx

@@ -5,11 +5,11 @@ icon: "wand-magic-sparkles"
 ---
 
 <Frame type="glass">
-  <img
-    className="block"
-    src="/images/generate-magic-link.gif"
-    alt="Hero Light"
-  />
+  <video
+    controls
+    className="w-full aspect-video"
+    src="/images/magiclinks.mp4"
+  ></video>
 </Frame>
 
 ## Send your first Magic Link
@@ -18,14 +18,19 @@ icon: "wand-magic-sparkles"
 
 <Step>Login to your [account dashboard](https://dashboard.panora.dev)</Step>
 
-<Step>Go to the _Connections_ [section](https://dashboard.panora.dev/connections) and click button `Create a Magic Link`</Step>
+<Step>
+  Go to the _Connections_ [section](https://dashboard.panora.dev/connections)
+  and click button `Create a Magic Link`
+</Step>
 
 <Step>Click `Create a Unique Magic Link`</Step>
 
 <Step>
   You'll be asked for two informations: an `Origin User Email` and an `Origin
   User Identifier`. The `Origin User Identifier` is the id of the user you're
-  inviting, as represented in your systems.
+  inviting, as represented in your systems. If you already have created a
+  [Linked User](/recipes/import-existing-users) you have the option to select
+  it.
 </Step>
 
 <Step>Click `Generate`</Step>

docs/glossary/metadata/category.mdx

@@ -0,0 +1,21 @@
+---
+title: "Categories"
+description: "All categories across Panora"
+icon: layer-group
+---
+
+## Categories powering the Panora API
+
+All values are derived from `ConnectorCategory` found in the `@panora/shared` package which can be found [here](https://www.npmjs.com/package/@panora/shared).
+
+```ts 
+export declare enum ConnectorCategory {
+  Crm = "crm",
+  Hris = "hris",
+  Ats = "ats",
+  Accounting = "accounting",
+  Ticketing = "ticketing",
+  MarketingAutomation = "marketingautomation",
+  FileStorage = "filestorage"
+}
+```

docs/glossary/metadata/connectors.mdx

@@ -0,0 +1,15 @@
+---
+title: "Connectors"
+description: ""
+icon: circle-nodes
+---
+
+## Connectors powering the Panora API
+
+All connectors are within the `@panora/shared` (in the `metadata.ts` file) package which can be found [here](https://www.npmjs.com/package/@panora/shared).
+
+The **source of truth** is contained within this [**object**](https://github.com/panoratech/Panora/blob/main/packages/shared/src/connectors/metadata.ts#L6) :
+
+```ts 
+CONNECTORS_METADATA: ProvidersConfig
+```

docs/mint.json

@@ -405,7 +405,6 @@
     {
       "group": "Recipes",
       "pages": [
-        "recipes/share-magic-link", 
         "recipes/embed-catalog", 
         "recipes/import-existing-users", 
         "recipes/catch-connection-token",
@@ -414,7 +413,11 @@
     },
     {
       "group": "Glossary",
-      "pages": ["glossary/connection-object", "glossary/linked-account-object"]
+      "pages": ["glossary/connection-object", "glossary/linked-account-object",
+      {
+        "group": "Metadata",
+        "pages": ["glossary/metadata/category", "glossary/metadata/connectors"]
+      }]
     },
 
     {

docs/quick-start.mdx

@@ -14,7 +14,7 @@ Before you begin, make sure you have the following:
 
 ## **Step 1: Get access to your users data**
 
-You either have the option to use a **no-code magic link** or the **embedded frontend snippet** to get access to your user's data.
+You either have the option to use a [**no-code magic link**](/core-concepts/magic-links) or the [**embedded frontend snippet**](/recipes/embed-catalog) to get access to your user's data.
 Choose the one that fits your needs !
 
 <Steps titleSize="h3">
@@ -38,7 +38,8 @@ Choose the one that fits your needs !
         You'll be asked for two informations: an `Origin User Email` (of the user
         you're creating the link for) and an `Origin User Identifier`. The `Origin
         User Identifier` is the id of the user you're inviting, as represented in your
-        sofwtare.
+        sofwtare. If you already have created a [Linked User](/recipes/import-existing-users) you have the option to select
+        it.
       </Step>
       <Step>Click `Generate`</Step>
     </Steps>
@@ -65,22 +66,36 @@ Choose the one that fits your needs !
                 ```javascript React
                 import "@panora/embedded-card-react/dist/index.css";
                 import PanoraProviderCard from "@panora/embedded-card-react";
+                import PanoraDynamicCatalog from "@panora/embedded-card-react";
                 ```
             </CodeGroup>
         </Step>
 
-        <Step title="Use the catalog in your integrations page:">
+        <Step title="Use the catalog in your integrations page">
+            You can either import a single connector card or a catalog of all connectors that you select in the UI dashboard configuration (see [here](//recipes/embed-catalog) for more details).
+            <Info>In order to fill the `linkedUserId` prop, use your own remote id that exist in your system **OR** check this [recipe](/recipes/import-existing-users) ! </Info>
             <CodeGroup>
-                ```javascript React
+                ```javascript Single Connector Card
                 <PanoraProviderCard
                     name={"hubspot"} # name of the provider
-                    vertical={"crm"} # vertical where provider belongs to
+                    category={"crm"} # vertical where provider belongs to
+                    projectId={"c9a1b1f8-466d-442d-a95e-11cdd00baf49"} # the project id tied to your organization
+                    returnUrl={"https://acme.inc"} # the url you want to redirect users to after the connection flow is successful
+                    linkedUserId={"b860d6c1-28f9-485c-86cd-fb09e60f10a2"}  # the linked id of the user if already created in Panora system or user's info in your system
+                />
+                ```
+                ```javascript Whole Connector Catalog
+                <PanoraDynamicCatalog
+                    category={"crm"} # optional but if provided it returns only connectors of the category
                     projectId={"c9a1b1f8-466d-442d-a95e-11cdd00baf49"} # the project id tied to your organization
                     returnUrl={"https://acme.inc"} # the url you want to redirect users to after the connection flow is successful
                     linkedUserId={"b860d6c1-28f9-485c-86cd-fb09e60f10a2"}  # the linked id of the user if already created in Panora system or user's info in your system
                 />
                 ```
             </CodeGroup>
+            You should see a card or catalog being rendered client-side !
+
+            __insert photo__
         </Step>
     </Steps>
 

docs/recipes/add-custom-provider-creds.mdx

@@ -14,5 +14,9 @@ icon: "gear-code"
 Visit the _Manage Connectors_ [section](https://dashboard.panora.dev/configuration), choose the connector you wish to add credentials for and add your own credentials.
 
 <Frame type="glass">
-  <img src="/images/custom-oauth.png" />
+  <video
+    controls
+    className="w-full aspect-video"
+    src="/images/customcreds.mp4"
+  />
 </Frame>