chore(docs): improve docs with better explanations (#175)

* chore(docs): better organise doc files

* better explanation for fields

* better field explanations for other unified fields

fern/api/definition/common/types.yml

@@ -49,3 +49,7 @@ types:
             - zohocrm
             - sfdc
             - pipedrive
+    ResponseStatus:
+        enum:
+            - ok
+            - error

fern/api/definition/common/unified.yml

@@ -1,43 +1,89 @@
 types:
     CommonUnifiedFields:
         properties:
-            id: string
-            remoteId: string
-            createdTimestamp: unknown
-            updatedTimestamp: unknown
+            id:
+                type: string
+                docs: The unique `id` of this object in Revert.
+            remoteId:
+                type: string
+                docs: The unique `id` of this object in the downstream CRM.
+            createdTimestamp:
+                type: unknown
+                docs: Creation timestamp of the object.
+            updatedTimestamp:
+                type: unknown
+                docs: The last updated timestamp of the object.
             associations: unknown
-            additional: unknown
+            additional:
+                type: unknown
+                docs: Any fields that are not unified yet/non-unifiable come inside this `json` object.
     Lead:
         extends: CommonUnifiedFields
         properties:
-            firstName: string
-            lastName: string
-            phone: string
-            email: string
+            firstName:
+                type: string
+                docs: The first name of the lead in a CRM.
+            lastName:
+                type: string
+                docs: The last name of the lead in a CRM.
+            phone:
+                type: string
+                docs: The phone number of the lead in a CRM.
+            email:
+                type: string
+                docs: The email of the lead in a CRM.
     Deal:
         extends: CommonUnifiedFields
         properties:
-            amount: integer
-            priority: optional<string>
-            stage: string
-            name: string
-            expectedCloseDate: unknown
-            isWon: boolean
-            probability: integer
+            amount:
+                type: integer
+                docs: The deal amount mentioned in the CRM for this deal.
+            priority:
+                type: optional<string>
+                docs: The priority attached to this deal.
+            stage:
+                type: string
+                docs: Deal stage in the CRM.
+            name:
+                type: string
+                docs: The name of the deal in a CRM.
+            expectedCloseDate:
+                type: unknown
+                docs: Expected close date for this deal.
+            isWon:
+                type: boolean
+                docs: Is `true` if the deal is closed (won).
+            probability:
+                type: integer
+                docs: Probability of the deal getting closed, a decimal number between 0 to 1 (inclusive).
     Note:
         extends: CommonUnifiedFields
         properties:
-            content: string
+            content:
+                type: string
+                docs: The contents of the note in plain text or HTML.
     Company:
         extends: CommonUnifiedFields
         properties:
-            name: string
-            industry: string
-            description: string
+            name:
+                type: string
+                docs: Name of the company in a CRM.
+            industry:
+                type: string
+                docs: Industry associated with this company.
+            description:
+                type: string
+                docs: Description of the company.
             annualRevenue: integer
-            size: integer
-            phone: string
-            address: CompanyAddress
+            size:
+                type: integer
+                docs: Number of employees or size of the company.
+            phone:
+                type: string
+                docs: Phone number of the company.
+            address:
+                type: CompanyAddress
+                docs: Company address.
     CompanyAddress:
         properties:
             street: optional<string>
@@ -49,33 +95,72 @@ types:
     Contact:
         extends: CommonUnifiedFields
         properties:
-            firstName: string
-            lastName: string
-            phone: string
-            email: string
+            firstName:
+                type: string
+                docs: The first name of the contact in a CRM.
+            lastName:
+                type: string
+                docs: The last name of the contact in a CRM.
+            phone:
+                type: string
+                docs: The phone number of the contact in a CRM.
+            email:
+                type: string
+                docs: The email of the contact in a CRM.
     Event:
         extends: CommonUnifiedFields
         properties:
-            type: string
-            subject: string
-            startDateTime: string
-            endDateTime: string
-            isAllDayEvent: boolean
-            description: string
-            location: string
+            type:
+                type: string
+                docs: The type of the event in the CRM.
+            subject:
+                type: string
+                docs: The Subject of the event/meeting in the CRM.
+            startDateTime:
+                type: string
+                docs: Event start date time.
+            endDateTime:
+                type: string
+                docs: Event end date time.
+            isAllDayEvent:
+                type: boolean
+                docs: Is `true` if the event is an all day event.
+            description:
+                type: string
+                docs: Description of the event/meeting.
+            location:
+                type: string
+                docs: The location of the event/meeting.
     Task:
         extends: CommonUnifiedFields
         properties:
-            subject: string
-            body: string
-            priority: string
-            status: string
-            dueDate: unknown
+            subject:
+                type: string
+                docs: Subject of the task.
+            body:
+                type: string
+                docs: Body of the task description.
+            priority:
+                type: string
+                docs: The priority of the task in hand.
+            status:
+                type: string
+                docs: Completion status of the task.
+            dueDate:
+                type: unknown
+                docs: The date when this task is due.
     User:
         extends: CommonUnifiedFields
         properties:
-            firstName: string
-            lastName: string
-            phone: string
-            email: string
-
+            firstName:
+                type: string
+                docs: The first name of a user in a CRM.
+            lastName:
+                type: string
+                docs: The last name of a user in a CRM.
+            phone:
+                type: string
+                docs: The phone number of a user in a CRM.
+            email:
+                type: string
+                docs: The email of a user in a CRM.

fern/api/definition/connection.yml

@@ -12,19 +12,19 @@ types:
     GetAllConnectionResponse: list<types.Connection>
     DeleteConnectionResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             deleted: types.Connection
     CreateConnectionWebhookResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             webhookUrl: string
             createdAt: string
             secret: string
             error: optional<string>
             errorMessage: optional<unknown>
     GetConnectionWebhookResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             webhook: unknown
             error: optional<string>
             errorMessage: optional<unknown>
@@ -33,7 +33,7 @@ types:
             webhookUrl: string
     DeleteConnectionWebhookResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             error: optional<string>
             errorMessage: optional<unknown>
 

fern/api/definition/crm/company.yml

@@ -8,22 +8,22 @@ imports:
 types:
     GetCompanyResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             result: unified.Company
     GetCompaniesResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             next: optional<string>
             previous: optional<string>
             results: list<unified.Company>
     CreateOrUpdateCompanyResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             message: string
             result: unknown
     SearchCompaniesResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             results: list<unified.Company>
 
 service:

fern/api/definition/crm/contact.yml

@@ -8,22 +8,22 @@ imports:
 types:
     GetContactResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             result: unified.Contact
     GetContactsResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             next: optional<string>
             previous: optional<string>
             results: list<unified.Contact>
     CreateOrUpdateContactResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             message: string
             result: unknown
     SearchContactsResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             results: list<unified.Contact>
 
 service:

fern/api/definition/crm/deal.yml

@@ -8,22 +8,22 @@ imports:
 types:
     GetDealResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             result: unified.Deal
     GetDealsResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             next: optional<string>
             previous: optional<string>
             results: list<unified.Deal>
     CreateOrUpdateDealResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             message: string
             result: unknown
     SearchDealsResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             results: list<unified.Deal>
 
 service:

fern/api/definition/crm/event.yml

@@ -8,22 +8,22 @@ imports:
 types:
     GetEventResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             result: unified.Event
     GetEventsResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             next: optional<string>
             previous: optional<string>
             results: list<unified.Event>
     CreateOrUpdateEventResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             message: string
             result: unknown
     SearchEventsResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             results: list<unified.Event>
 
 service:

fern/api/definition/crm/lead.yml

@@ -8,22 +8,22 @@ imports:
 types:
     GetLeadResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             result: unified.Lead
     GetLeadsResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             next: optional<string>
             previous: optional<string>
             results: list<unified.Lead>
     CreateOrUpdateLeadResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             message: string
             result: unknown
     SearchLeadsResponse:
         properties:
-            status: string
+            status: types.ResponseStatus
             results: list<unified.Lead>
 
 service: