Merge pull request #19 from magicalapi/add-webhook-feature

fix return type for WebhookResponse in all services

Author: AmirAref

magicalapi/services/company_data_service.py

@@ -8,7 +8,7 @@
 
 from magicalapi.types.base import ErrorResponse
 from magicalapi.types.company_data import CompanyDataResponse
-from magicalapi.types.schemas import HttpResponse
+from magicalapi.types.schemas import HttpResponse, WebhookCreatedResponse
 
 from .base_service import BaseService
 
@@ -23,13 +23,18 @@ async def get_company_data(
         company_username: str | None = None,
         company_name: str | None = None,
         company_website: str | None = None,
-    ) -> CompanyDataResponse | ErrorResponse:
+    ) -> CompanyDataResponse | WebhookCreatedResponse | ErrorResponse:
         """this method sends request to company data service in magicalAPI.
         https://magicalapi.com/services/company-data
 
         company_name (``str``):
             the username of linkedin company that you want to get it's data.
 
+        Returns:
+            CompanyDataResponse: When request completes successfully (no webhook).
+            WebhookCreatedResponse: When using webhook_url (immediate acknowledgment).
+            ErrorResponse: When an error occurs (e.g., 403 if webhook domain not whitelisted).
+
         """
         # check which parameters passed
         if company_username is not None:
@@ -66,5 +71,5 @@ async def get_company_data(
 
     def validate_response(
         self, response: HttpResponse, validate_model: type[BaseModel]
-    ) -> CompanyDataResponse | ErrorResponse:
+    ) -> CompanyDataResponse | WebhookCreatedResponse | ErrorResponse:
         return super().validate_response(response, validate_model)

magicalapi/services/profile_data_service.py

@@ -8,7 +8,7 @@
 
 from magicalapi.types.base import ErrorResponse
 from magicalapi.types.profile_data import ProfileDataResponse
-from magicalapi.types.schemas import HttpResponse
+from magicalapi.types.schemas import HttpResponse, WebhookCreatedResponse
 
 from .base_service import BaseService
 
@@ -20,13 +20,18 @@ class ProfileDataService(BaseService):
 
     async def get_profile_data(
         self, profile_name: str
-    ) -> ProfileDataResponse | ErrorResponse:
+    ) -> ProfileDataResponse | WebhookCreatedResponse | ErrorResponse:
         """this method sends request to profile data service in magicalAPI.
         https://magicalapi.com/services/profile-data
 
         profile_name (``str``):
             the username of linkedin profile that you want to get it's data.
 
+        Returns:
+            ProfileDataResponse: When request completes successfully (no webhook).
+            WebhookCreatedResponse: When using webhook_url (immediate acknowledgment).
+            ErrorResponse: When an error occurs (e.g., 403 if webhook domain not whitelisted).
+
         """
         request_body = {
             "profile_name": profile_name,
@@ -43,5 +48,5 @@ async def get_profile_data(
 
     def validate_response(
         self, response: HttpResponse, validate_model: type[BaseModel]
-    ) -> ProfileDataResponse | ErrorResponse:
+    ) -> ProfileDataResponse | WebhookCreatedResponse | ErrorResponse:
         return super().validate_response(response, validate_model)  # type:ignore

magicalapi/services/resume_parser_service.py

@@ -8,7 +8,7 @@
 
 from magicalapi.types.base import ErrorResponse
 from magicalapi.types.resume_parser import ResumeParserResponse
-from magicalapi.types.schemas import HttpResponse
+from magicalapi.types.schemas import HttpResponse, WebhookCreatedResponse
 
 from .base_service import BaseService
 
@@ -18,13 +18,20 @@
 class ResumeParserService(BaseService):
     service_path = "resume-parser"
 
-    async def get_resume_parser(self, url: str) -> ResumeParserResponse | ErrorResponse:
+    async def get_resume_parser(
+        self, url: str
+    ) -> ResumeParserResponse | WebhookCreatedResponse | ErrorResponse:
         """this method sends request to resume parser service in magicalAPI.
         https://magicalapi.com/services/resume-parser
 
         url (``str``):
             the url of pdf resume file that you want parse it.
 
+        Returns:
+            ResumeParserResponse: When request completes successfully (no webhook).
+            WebhookCreatedResponse: When using webhook_url (immediate acknowledgment).
+            ErrorResponse: When an error occurs (e.g., 403 if webhook domain not whitelisted).
+
         """
         request_body = {
             "url": url,
@@ -41,5 +48,5 @@ async def get_resume_parser(self, url: str) -> ResumeParserResponse | ErrorRespo
 
     def validate_response(
         self, response: HttpResponse, validate_model: type[BaseModel]
-    ) -> ResumeParserResponse | ErrorResponse:
+    ) -> ResumeParserResponse | WebhookCreatedResponse | ErrorResponse:
         return super().validate_response(response, validate_model)

magicalapi/services/resume_review_service.py

@@ -8,21 +8,28 @@
 
 from magicalapi.types.base import ErrorResponse
 from magicalapi.types.resume_review import ResumeReviewResponse
-from magicalapi.types.schemas import HttpResponse
+from magicalapi.types.schemas import HttpResponse, WebhookCreatedResponse
 
 from .base_service import BaseService
 
 
 class ResumeReviewService(BaseService):
     service_path = "resume-review"
 
-    async def get_resume_review(self, url: str) -> ResumeReviewResponse | ErrorResponse:
+    async def get_resume_review(
+        self, url: str
+    ) -> ResumeReviewResponse | WebhookCreatedResponse | ErrorResponse:
         """this method sends request to resume review service in magicalAPI.
         https://magicalapi.com/services/resume-review
 
         url (``str``):
             the url of pdf resume file that you want review it.
 
+        Returns:
+            ResumeReviewResponse: When request completes successfully (no webhook).
+            WebhookCreatedResponse: When using webhook_url (immediate acknowledgment).
+            ErrorResponse: When an error occurs (e.g., 403 if webhook domain not whitelisted).
+
         """
         request_body = {
             "url": url,
@@ -34,5 +41,5 @@ async def get_resume_review(self, url: str) -> ResumeReviewResponse | ErrorRespo
 
     def validate_response(
         self, response: HttpResponse, validate_model: type[BaseModel]
-    ) -> ResumeReviewResponse | ErrorResponse:
+    ) -> ResumeReviewResponse | WebhookCreatedResponse | ErrorResponse:
         return super().validate_response(response, validate_model)

magicalapi/services/resume_score_service.py

@@ -8,7 +8,7 @@
 
 from magicalapi.types.base import ErrorResponse
 from magicalapi.types.resume_score import ResumeScoreResponse
-from magicalapi.types.schemas import HttpResponse
+from magicalapi.types.schemas import HttpResponse, WebhookCreatedResponse
 
 from .base_service import BaseService
 
@@ -18,7 +18,7 @@ class ResumeScoreService(BaseService):
 
     async def get_resume_score(
         self, url: str, job_description: str
-    ) -> ResumeScoreResponse | ErrorResponse:
+    ) -> ResumeScoreResponse | WebhookCreatedResponse | ErrorResponse:
         """this method sends request to resume score service in magicalAPI.
         https://magicalapi.com/services/resume-score
 
@@ -29,6 +29,11 @@ async def get_resume_score(
             give some description of the job,
             your resume score will calculate based on your job description.
 
+        Returns:
+            ResumeScoreResponse: When request completes successfully (no webhook).
+            WebhookCreatedResponse: When using webhook_url (immediate acknowledgment).
+            ErrorResponse: When an error occurs (e.g., 403 if webhook domain not whitelisted).
+
         """
         request_body = {
             "url": url,
@@ -41,5 +46,5 @@ async def get_resume_score(
 
     def validate_response(
         self, response: HttpResponse, validate_model: type[BaseModel]
-    ) -> ResumeScoreResponse | ErrorResponse:
+    ) -> ResumeScoreResponse | WebhookCreatedResponse | ErrorResponse:
         return super().validate_response(response, validate_model)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "magicalapi"
-version = "1.5.0"
+version = "1.5.1"
 description = "This is a Python client that provides easy access to the MagicalAPI.com services, fully type annotated, and asynchronous."
 authors = [
     { name = "MagicalAPI", email = "info@magicalapi.com" }